Skip to content
1 change: 1 addition & 0 deletions quest/m0/ci/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,4 +67,5 @@ The historical samples locate candidates; they are not controlled benchmarks.
- [Require platform gates](/quest/m0/ci/platform-queue.md) - activate the consolidated platform checks in the main and release rulesets after the workflow lands
- [mbx on R2](/quest/m0/ci/mbx-r2.md) - Rust builds on every OS read an R2 cache that only `main` writes, escaping the 10 GB Actions cache
- [Nix cache](/quest/m0/ci/nix-cache.md) - `nix.moq.dev` on R2 replaces Cachix for CI and releases
- [TS path filter](/quest/m0/ci/ts-path-filter.md) - TS validation runs whenever a crate it builds changes, checked against `cargo metadata`
- [First shared FFI release](/quest/m0/ci/nightly-ffi-reuse.md) - condition: the first `moq-ffi-v*` tag that runs `Release FFI`, and a `Shipping sizes` run; verify the wrappers and size keys
25 changes: 25 additions & 0 deletions quest/m0/ci/ts-path-filter.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# [XS] TS validation runs whenever a crate it builds changes

## Goal

`.github/workflows/ts.yml` triggers on every workspace crate the TS harness
builds, and a lint fails Check when its path filter drifts from that set.

## Plan

`test/ts/run.sh` builds `moq-relay`, `moq-cli` and `moq-shaper` with their
default features. That build compiles workspace crates the filter misses,
found 2026-10-17 with `cargo tree` over those roots: `moq-clock`,
`moq-auth`, `moq-stats`, `moq-archive`, `moq-hls`, `moq-rtc`, `moq-rtmp` and
`moq-srt`. Optional crates such as `moq-transcode`, `moq-video` and
`moq-nvenc` are not compiled and must not trigger the workflow.
crates.io dependencies such as `web-transport-*` are already covered by the
`Cargo.lock` filter.

Decided 2026-10-17 (maintainer): derive the set from Cargo in a lint that
runs in Check, rather than hand-listing paths that drift with the next
dependency. Resolve it for the harness's exact packages and features (the
activated closure), not the whole workspace graph, or unrelated changes will
trigger this expensive workflow.

Public API: none. Wire: none.
8 changes: 8 additions & 0 deletions quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,9 @@ lands before the cut.
- [IETF fill timeout](/quest/m1/ietf-fill-timeout.md) - native FILL_TIMEOUT bounds upstream waiting on drafts 18-22, alongside local content-age enforcement
- [Browser follows a renamed track](/quest/m1/browser-rename-check.md) - a real browser keeps playing when `@moq/publish` renames a track after a codec change, while size-only changes keep their identity
- [Rust identity enforcement](/quest/m1/catalog-identity-rs.md) - `moq-mux` refuses a redefined rendition, and every Rust publisher mints a new rendition name for a decoder identity change and updates everything else in place
- [JSON duplicate keys](/quest/m1/json-duplicate-keys.md) - Rust and JS JSON decoders refuse duplicate keys in every frame kind
- [Catalog too new](/quest/m1/catalog-unsupported.md) - `@moq/watch` reports a distinct status when its player cannot read the catalog version
- [One hang catalog consumer](/quest/m1/catalog-consumer-fold.md) - `moq-mux` reads hang catalogs through `hang`'s consumer
- [Broadcast archives](/quest/m1/archive/README.md) - SUBSCRIBE_ALL records every track under a prefix to any object_store, a host serves a stored broadcast back, and the catalog drops its archive pointer for an opt-in `hls` field
- [In-band auth](/quest/m1/auth/README.md) - a session tells its peer what it may publish and subscribe to, unions tokens presented in band, and fails loud on an out-of-scope publish
- [IETF epochs](/quest/m1/ietf-epochs.md) - negotiate explicit broadcast identity on drafts 17-22, retaining unchanged paths and epochless clients on updated relays
Expand All @@ -98,9 +101,14 @@ lands before the cut.
- [Publish channel count](/quest/m1/publish-audio-channel-count.md) - forcing a channel count on an Audio.Capture stops costing the subscriber gaps of silence, and the media fixture's cold-start audio-tone flake is fixed at its cause
- [Handshake deadline covers admission](/quest/m1/handshake-admission-deadline.md) - `listen.timeout` bounds a connection through auth admission on both listeners, replacing the hardcoded admission timeout
- [Drain cleanup](/quest/m1/drain-cleanup.md) - sessions force-closed at the drain deadline record their lease end and bytes before the relay or CLI exits, while unfinished handshakes stay bounded
- [GOAWAY coverage](/quest/m1/goaway-coverage.md) - every IETF request stream handles GOAWAY, a closed control stream is a violation, and the draft-18 cutoff is honored
- [Container reads drop backfill](/quest/m1/read-backfill.md) - the JS container consumer drops groups below its read cursor like Rust
- [Decode errors end the reader](/quest/m1/decode-errors.md) - a container decode error fails the reader in Rust and JS instead of reading as loss
- [Transcode finishes its group](/quest/m1/transcode-open-group.md) - `moq-transcode` never aborts a group a fetch's live loop opened
- [Rust request credit](/quest/m1/rs-request-credit.md) - a moq-net request fails at once without stream credit instead of waiting
- [qmux no-wait opens](/quest/m1/qmux-no-wait.md) - @moq/qmux rejects an over-limit create when waitUntilAvailable is false, like Chrome
- [Bufferbloat harness](/quest/m1/bufferbloat.md) - acceptance and performance checks impair paths with a rate limit and a deep queue, not random loss
- [Random-loss audit](/quest/m1/random-loss-audit.md) - every decision random-loss gates drove is kept, reworked, or reverted on shaped paths
- [Timed-out requests clean up](/quest/m1/legacy-request-timeout-cleanup.md) - on drafts 14-16, Rust and JS send PUBLISH_NAMESPACE_DONE or UNSUBSCRIBE_NAMESPACE for a timed-out request before its local reset
- [TS fidelity and recovery](/quest/m1/ts-reliability/README.md) - both modes have explicit profiles, automated validation, loss tests, and a dedicated guide
- [Resume reorder](/quest/m1/resume-reorder.md) - a group whose stream header arrives after its successor's still resumes on failover; only a dropped or long-gone group fails
Expand Down
53 changes: 53 additions & 0 deletions quest/m1/bufferbloat.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# [M] Acceptance and performance run on bufferbloat, not random loss

## Goal

Every acceptance or performance (QoS) check that impairs a network does it
with a rate limit below the media bitrate behind a deep but finite queue, so
it congests and tail-drops like a real path. Random loss remains only where
a test proves correctness, such as retransmits happening.

## Plan

Decided 2026-10-17 (maintainer), and recorded in the root `AGENTS.md`:
bufferbloat does double duty, since its overflow drops packets too, so it is
the impairment for anything judged on quality, latency, or throughput.
Random loss judged that way pushed decisions toward surviving a failure mode
real paths do not show (see the [audit](/quest/m1/random-loss-audit.md)).

Classify each random-loss user, move the acceptance and performance ones to
shaping, and leave correctness checks alone:

- TS harness: `just test ts` gains `--rate` and `--queue` beside `--loss`
(decided 2026-10-17), passed to `moq-shaper`'s existing token bucket; its
100 ms default queue is shallow for bufferbloat. The nightly
`--hrd --loss 1` and `--passthrough --loss 1` steps in `ts.yml`,
`passthrough.py --loss-ok`, and the `test/ts/README.md` lossy-path section
grade output quality, so they move to `--rate`/`--queue`; `--loss` stays
for correctness runs.
- Relay drills: the 5% profile every `::impaired` lane and the cluster
drills use (`drills.rs`, `test/drill/README.md`). Decide per drill
whether it proves correctness or judges behavior under impairment.
- `moq-quic`'s sim (`Link.loss`, the lossy proptests) and BBR3's
deterministic periodic-drop unit tests prove recovery is correct; they
stay unless they assert throughput or latency.

`moq-shaper --loss` stays for correctness use. Earlier in the same day the
plan was to delete it; the maintainer then scoped the rule to acceptance and
performance.

The TS run's oracle under a path narrower than the muxrate, decided
2026-10-17: the export stays T-STD conformant and continuous (PCR,
continuity counters, no partial PES), sheds whole groups rather than
stalling, and end-to-end latency stays bounded instead of growing with the
queue. No loss-percentage or hole-count thresholds. Pick the shaped rate and
queue depth from what the run must exercise (the queue must overflow), and
say why in the harness.

Public API: none. Wire: none.

## Related

- [Random-loss audit](/quest/m1/random-loss-audit.md) - re-judges what random-loss tests drove, on this harness
- [Relay burst drill](/quest/m1/test-flakes-2/relay-burst-impaired.md) - owns the impaired burst drill's flake
- [TS recovery](/quest/m1/ts-reliability/recovery.md) - MoQ content-loss schedules, separate from network impairment
25 changes: 25 additions & 0 deletions quest/m1/catalog-consumer-fold.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# [S] One hang catalog consumer

## Goal

`moq-mux` reads hang catalogs through `hang`'s catalog consumer instead of
its own near-copy, so rendition and resolvability checks live in one place.

## Plan

`rs/moq-mux/src/catalog/hang/consumer.rs` and
`rs/hang/src/catalog/consumer.rs` both wrap
`moq_json::snapshot::Consumer<Catalog<E>>` with the same `new`,
`compressed`, `poll_next` (rendition and resolvability checks) and `next`.
The `moq-mux` copy adds only a `CatalogFormat` (hang or hangz) and the
`CatalogExt` bound. Fold that into `hang`'s consumer, or keep a thin
`moq-mux` adapter over it; pick whichever keeps `hang`'s public surface
smaller. Found by #5806.

Public API: `moq-mux`'s hang catalog consumer may become a re-export or
adapter. Wire: none.

## Related

- [Rust identity enforcement](/quest/m1/catalog-identity-rs.md) - `moq-mux` catalog checks
- [Compressed tracks](/quest/m1/compress/README.md) - drops `catalog.json.z`, so the folded consumer need not keep the hangz format
17 changes: 17 additions & 0 deletions quest/m1/catalog-unsupported.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# [S] A viewer sees that its player is too old for the catalog

## Goal

When `@moq/watch` reads a catalog whose version it does not support, the
broadcast reports a distinct status that says the player needs an update,
instead of going "offline" (fetched catalog) or staying "loading" (inline).

## Plan

After #5806, an unsupported catalog version is only logged. Decided
2026-10-17 (maintainer): add a distinct broadcast status rather than reusing
the error path, so the UI can tell a viewer to update instead of implying
the broadcast is down. Mirror the shape in Rust consumers' error so native
players can say the same.

Public API: a new broadcast status value in `@moq/watch`. Wire: none.
35 changes: 35 additions & 0 deletions quest/m1/decode-errors.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# [S] A container decode error ends the reader in Rust and JS

## Goal

A container payload that fails to decode ends the media reader with that
error, the same way in Rust and JS. Only a transport abort or eviction of a
group is skipped as a gap. Nothing logs a decode error and keeps reading.

## Plan

Rust already does this in the main read path (`moq-mux` container consumer
ends the reader on a payload decode error), with two holes:

- JS `@moq/hang`'s container consumer marks the group truncated on any
error, keeps the frames it decoded, and lets the rest reach `spawn`, which
only logs. The reader never fails, so malformed media reads as loss.
- Rust's `poll_min_timestamp` lookahead returns the error, but its callers
(startup, the max-end scan, the rewind check) discard it. The bad frame is
already consumed, so a malformed object at the head of a group then reads
as a clean or short end.

Decided 2026-10-17 (maintainer): a quest of its own in m1, since both are
silent data loss. Found while reviewing #5815; the JS behavior was declined
there as out of scope.

Each fix lands with a regression test that feeds a malformed object (head of
group and mid-group) and asserts the reader's error, in both languages.

Public API: JS readers can now reject with a decode error where they used to
truncate. Wire: none.

## Related

- [Container reads drop backfill](/quest/m1/read-backfill.md) - the other Rust/JS container-consumer parity gap
- [Dropped sources](/quest/m1/dropped-sources.md) - consumers see the producer's real error on every end
36 changes: 36 additions & 0 deletions quest/m1/goaway-coverage.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# [M] GOAWAY reaches every IETF request stream

## Goal

On moq-transport, every request stream in Rust and JS (publisher and
subscriber side, including FETCH, TRACK_STATUS and SUBSCRIBE_TRACKS) handles
a GOAWAY the way SUBSCRIBE does, a control stream that ends or resets is a
PROTOCOL_VIOLATION, and draft-18's Request ID cutoff answers requests past it
with GOING_AWAY.

## Plan

Found by #5800 (2026-10-17 state of main):

- Only SUBSCRIBE and SUBSCRIBE_NAMESPACE on the publisher side read GOAWAY
on their request streams (Rust `request_stream`, JS `nextMessage` and
`namespaceUpdate`). FETCH, TRACK_STATUS, SUBSCRIBE_TRACKS, and every
subscriber-side request stream end the request on a GOAWAY instead.
- A control stream FIN is treated as a clean end: Rust's draft-17+ GOAWAY
reader returns Ok, the draft 14-16 adapter tears the session down with no
code, and JS closes with no code. Draft 21 section 6.3 makes it a
PROTOCOL_VIOLATION; check the SETUP STOP_SENDING ordering too.
- Draft 18's GOAWAY Request ID is only parity-checked. Requests at or past
the cutoff never get GOING_AWAY, and our own GOAWAY sends a fixed 0 or 1.
- Check JS for a duplicate-GOAWAY race.

Decided 2026-10-17 (maintainer): m1, beside drain cleanup. Draft 17 stays
low priority; fix it where the shared code makes it free.

Public API: none expected. Wire: closer conformance on drafts 14-22; no new
fields.

## Related

- [Drain cleanup](/quest/m1/drain-cleanup.md) - what a drain does to sessions at its deadline
- #5798 - the legacy drafts' request handling
28 changes: 28 additions & 0 deletions quest/m1/json-duplicate-keys.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# [S] JSON decoders refuse duplicate keys in Rust and JS

## Goal

Every `moq-json` and `@moq/json` decoder (snapshot, delta, stream, and
window) refuses an object with a duplicate key, so a catalog or data frame
can never mean two things to two readers.

## Plan

Today Rust refuses duplicates in deltas only; snapshots go through
`serde_json` into `Value`, which keeps the last key. JS uses `JSON.parse`
everywhere, which also keeps the last key. #5806 adds a typed refusal for a
duplicate catalog `version` only.

Decided 2026-10-17 (maintainer): refuse everywhere, in both languages. For
JS, prefer a maintained parser over hand-rolling: `@humanwhocodes/momoa`
(maintained, widely used) keeps duplicate members in its AST, so walk it;
`json-dup-key-validator` is unmaintained since 2021. Measure the parse cost
against `JSON.parse` on catalog-sized and stats-sized frames, since every
reader pays it.

Public API: decoders return a new error on duplicate keys. Wire: frames
with duplicate keys, previously accepted, are refused.

## Related

- #5806 - adds the duplicate `version` refusal
52 changes: 52 additions & 0 deletions quest/m1/random-loss-audit.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# [M] Audit decisions made to pass random-loss tests

## Goal

Every acceptance or performance decision a random-loss test drove (code,
defaults, harness choices, CI steps, and quests) is re-judged on the
bufferbloat harness and kept, reworked, or reverted, each with a recorded
verdict and its evidence.

## Plan

Decided 2026-10-17 (maintainer): random loss may prove correctness, but it
is not how real paths fail, so anything tuned to survive it as a quality or
performance target may be wrong. Scope is every random-loss-driven
decision, not only the 10% TS work. Small reverts land in the audit's PR;
anything bigger becomes its own quest. Verdicts are measured on the
[bufferbloat harness](/quest/m1/bufferbloat.md), not argued.

Leads found 2026-10-17 (no production default or congestion threshold was
changed for random loss; `LOSS_THRESH` is still 2%):

- `quest/m2/quic-bbr-natural-drain.md` targets "BBR's response to random
loss" on a 10% profile and asks whether BBR should tell random loss from
congestion. The main live risk: it would weaken BBR's loss response. Its
premise came from #5805 moving 10% loss out of the T-STD epic.
- #4645's fixed-delay jitter buffer and skip design was partly justified by
the 10% netem rig (#4613); re-check the skip budget and acquire wait.
- The BBR fork fixes (#4193, noq 1.3.1) were accepted on a 2% random-loss
netem check; the fixes are correctness fixes, but re-check the evidence.
- Harness choices from #5805 and #5856: nightly `--hrd` because
`--headroom` loses audio at 1% loss, WebSocket fallback disabled under
`--loss`, a run that fails if the shaper dropped nothing, and
`passthrough.py --loss-ok`.
- Decided 2026-10-17 (maintainer): the audit decides whether
`quic-bbr-natural-drain.md` and `m3/quic-gcc.md` survive, since their
premise rests on random loss.
- Other quests only list random loss among their measurement inputs:
`quic-probe.md` (with noq#811 and noq#476), `quic-sim.md`,
`quic-deadline.md` and `quic-careful-resume.md` ("the impaired path
profile"), `m3/cut-through/bench.md`, and
`m1/ts-reliability/recovery.md`'s network impairment arm. Their goals
stand; the audit only moves any acceptance or performance input among
them to bufferbloat.

Record each verdict (decision, origin PR, keep/rework/revert, evidence) in
the PR description.

Public API: depends on the verdicts. Wire: none expected.

## Required

- [Bufferbloat harness](/quest/m1/bufferbloat.md) - verdicts are measured on shaped paths
4 changes: 4 additions & 0 deletions quest/m1/test-flakes-2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,10 @@ Public API: none. Wire: none.
- [uring teardown close](/quest/m1/test-flakes-2/uring-teardown-close.md) - moq-uring's published-close teardown test holds under load, fixed at its cause
- [Relay burst drill](/quest/m1/test-flakes-2/relay-burst-impaired.md) - the impaired transport-peer burst drill never aborts its subscription while the link is up
- [BBR marking seed](/quest/m1/test-flakes-2/bbr-marking-seed.md) - the BBR marking test seeds its probe schedule, replays a failing seed, and its rare drop is fixed at the cause
- [gst redial port](/quest/m1/test-flakes-2/gst-redial-port.md) - the moq-gst redial tests never lose their relay's port to `AddrInUse`
- [js/net local close](/quest/m1/test-flakes-2/js-local-close.md) - the draft-17 locally closed track test holds under load
- [WASM refused track](/quest/m1/test-flakes-2/wasm-refused-track.md) - the refused-track case passes and fails on its refusal, not a timeout
- [Drill shaper failure](/quest/m1/test-flakes-2/drill-shaper-failure.md) - a drill whose shaper stopped says so directly

## Related

Expand Down
18 changes: 18 additions & 0 deletions quest/m1/test-flakes-2/drill-shaper-failure.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# [XS] A drill names a shaper that stopped

## Goal

When a relay drill's shaper stops forwarding, the failure says so directly
instead of surfacing later as a status timeout.

## Plan

`Drop for Path` in `rs/moq-relay/tests/drills.rs` prints only the shaper's
counters; only `verify()` reports the shaper's error. Surface that error
when a drill fails. Found while chasing #5796.

Public API: none. Wire: none.

## Related

- [Relay burst drill](/quest/m1/test-flakes-2/relay-burst-impaired.md) - another impaired drill failure
18 changes: 18 additions & 0 deletions quest/m1/test-flakes-2/gst-redial-port.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# [XS] moq-gst redial tests keep their relay's port

## Goal

The moq-gst redial tests (`a_refused_redial_posts_a_bus_error_after_playback`,
`relay_loss_reconnects_after_the_default_budget`) never fail with
`AddrInUse` under load, fixed at its cause.

## Plan

Seen at least three times on #5798, #5803, #5815 and #5820 runs. The tests
stop their test relay (`Relay::bind`/`stop` in
`rs/moq-gst/src/source/imp.rs`) and rebind the freed ephemeral port to bring
it back; on a loaded host a parallel test can take that port in between.
The cause is unconfirmed: reproduce it first. Never add a retry around the
bind.

Public API: none. Wire: none.
15 changes: 15 additions & 0 deletions quest/m1/test-flakes-2/js-local-close.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# [XS] js/net's locally closed track test holds under load

## Goal

`js/net`'s "ends a locally closed track cleanly" integration test
(`runSessionDeath(..., true)`, draft 17) passes reliably, fixed at its
cause.

## Plan

Failed once in a full `bun test` run under load on #5803 and passed 6/6
alone. No root cause yet: reproduce it under load first, then decide whether
the product or the test races.

Public API: none. Wire: none.
Loading