From 50ab339aa1a2c3421bf67444ba2eed7c72a97549 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 11:57:22 -0700 Subject: [PATCH 01/18] chore(quest): claim quest tree audit From 682ad52316599e40fa58b445d7f87e7ca86eedbc Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 11:59:22 -0700 Subject: [PATCH 02/18] docs(quest): point plans at current source paths Co-Authored-By: GPT-6.1-Sol --- quest/m1/auth/bindings.md | 2 +- quest/m1/subscribe-ranges/lite.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/quest/m1/auth/bindings.md b/quest/m1/auth/bindings.md index 8395c24771b..abe97b515c2 100644 --- a/quest/m1/auth/bindings.md +++ b/quest/m1/auth/bindings.md @@ -31,7 +31,7 @@ export the experimental Rust request hook through the bindings here. `auth granted publish=[...] subscribe=[...]` line and join `prints_grant` and `enforces_grant` in `test/interop/interop.sh`, beside Rust and JS. - Wrappers: `py/moq-rs/moq/session.py`, `swift/Sources/Moq`, - `kt/.../Flows.kt` (a `Flow` over `grant_changed`), `go/wrapper/moq/session.go` + `kt/.../Flows.kt` (a `Flow` over `grant_changed`), `go/wrapper/session.go` (context-cancellable like the rest), and `dart/moq/lib/moq.dart`. Kotlin typealiases pick up the raw methods for free; the flow is the idiomatic add. - Docs: `doc/lib/{py,swift,kt,go,dart}` each gain a short auth section, and diff --git a/quest/m1/subscribe-ranges/lite.md b/quest/m1/subscribe-ranges/lite.md index a6a073eee9b..6aa5ae0c793 100644 --- a/quest/m1/subscribe-ranges/lite.md +++ b/quest/m1/subscribe-ranges/lite.md @@ -36,12 +36,12 @@ not counted until its first object arrives; the relay reports what it has rather than waiting for the peer. Test the lite-05 relay case #5000 left out, on mock time beside -`rs/moq-net/tests/late_lower_group.rs`: a live subscriber already reading +`rs/moq-net/tests/integration/late_lower_group.rs`: a live subscriber already reading group 1, then one from `Absolute(0)`, and a fresh group 0 reaches only the second. Today the merged request goes upstream as its covering span, which on lite-05 has no floor and joins at the latest group, so group 0 never arrives; it needs the explicit group 0 above. The merged-range relay test, -`rs/moq-net/tests/subscribe_ranges.rs`, extends to lite-07 once it carries the +`rs/moq-net/tests/integration/subscribe_ranges.rs`, extends to lite-07 once it carries the list. Update `drafts/draft-lcurley-moq-lite.md` in the same PR: the SUBSCRIBE and From 1835f8a5074471c3882d6c98ce663d746648a5e4 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 12:00:56 -0700 Subject: [PATCH 03/18] docs(quest): judge cut-through on congested paths Co-Authored-By: GPT-6.1-Sol --- quest/m3/README.md | 2 +- quest/m3/cut-through/README.md | 2 +- quest/m3/cut-through/bench.md | 16 +++++++++++----- 3 files changed, 13 insertions(+), 7 deletions(-) diff --git a/quest/m3/README.md b/quest/m3/README.md index 7cc82dc2da2..8e545ba22b1 100644 --- a/quest/m3/README.md +++ b/quest/m3/README.md @@ -35,7 +35,7 @@ m4's upstream waits in here and moved m2 work with no consumer. - [#3129](/quest/m3/3129-moq-uring-write-the-webtransport-stream-header-at-open.md) - moq-uring writes the WebTransport stream header at open and settles the open contract, once a caller hits it - [L4S on the backbone](/quest/m3/quic-ecn.md) - an ECT(1) option in `moq-quic`, an `ecn` config knob, and a dualpi2 measurement, if the ECN measurement says marks survive - [Careful resume on reconnect](/quest/m3/quic-careful-resume.md) - a Rust redial starts at the previous connection's rate -- [Cut-through](/quest/m3/cut-through/README.md) - a lossy-hop bench decides whether a relay should forward bytes behind a QUIC stream hole; the build is re-planned if it says go +- [Cut-through](/quest/m3/cut-through/README.md) - a bufferbloat bench decides whether a relay should forward bytes behind a QUIC stream hole; the build is re-planned if it says go - [Unreal prototype](/quest/m3/unreal.md) - a UE5 module on the C++ package with exceptions disabled, rendering a subscribed broadcast to a texture - [vcpkg registry](/quest/m3/cpp-vcpkg.md) - a registry we own serves the prebuilt package to `vcpkg` manifests, once a consumer asks - [Conan remote](/quest/m3/cpp-conan.md) - a remote we own serves the same tarball to `conan install` diff --git a/quest/m3/cut-through/README.md b/quest/m3/cut-through/README.md index c10ef675a5a..65fd23af677 100644 --- a/quest/m3/cut-through/README.md +++ b/quest/m3/cut-through/README.md @@ -71,7 +71,7 @@ stats field, which its quest documents inline. ## Required - [Loss delay](/quest/m3/cut-through/loss-delay.md) - relays report, per broadcast, the ingress bytes a loss held back by at least one RTT -- [Bench](/quest/m3/cut-through/bench.md) - a lossy relay hop swept over loss, frame size, and egress headroom, measuring the post-hole drain time, with a go or no-go verdict +- [Bench](/quest/m3/cut-through/bench.md) - a congested relay hop swept over ingress rate, queue depth, frame size, and egress headroom, measuring the post-hole drain time, with a go or no-go verdict ## Related diff --git a/quest/m3/cut-through/bench.md b/quest/m3/cut-through/bench.md index 196d8e25557..2fbc05e5ad7 100644 --- a/quest/m3/cut-through/bench.md +++ b/quest/m3/cut-through/bench.md @@ -13,11 +13,17 @@ Decided 2026-09-30: real stacks, not a mock. The loss recovery being measured belongs to the QUIC stack, so a mock transport with a made-up retransmit model would partly measure its own assumptions. -- Publisher, then a seeded `moq-shaper` (loss and delay), then `moq-relay` over - QUIC, then a clean or rate-limited hop to the viewer. Reuse the shaper wiring - from `rs/moq-relay/tests/drills.rs`. -- Sweep loss rate, frame size (audio-sized through a large I-frame), and egress - headroom (egress rate relative to the media rate). +- Publisher, then `moq-shaper` with an ingress rate below the media bitrate + and a deep but finite queue whose overflow drops packets, then `moq-relay` + over QUIC, then a clean or rate-limited hop to the viewer. Reuse the shaper + wiring from `rs/moq-relay/tests/drills.rs` and the overflowing bufferbloat + profiles described in `test/ts/README.md`. Verify that the measured path + actually overflows its queue. +- Sweep ingress rate, queue depth, frame size (audio-sized through a large + I-frame), and egress headroom (egress rate relative to the media rate). + The go or no-go verdict uses these bufferbloat runs. Seeded random loss + may check correctness, such as the payload-loss and header-loss cases + below, but never gates acceptance or performance. - Report per-frame completion at the viewer, from publish to last byte, p50 and p99. The opportunity is the drain time on this same two-hop path: per frame, the time from the relay's ingress hole filling to the frame completing at the From 81a27d1bcc60e1c8aab33f16802cad5cfe986328 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 12:01:22 -0700 Subject: [PATCH 04/18] docs(quest): remove stale milestone and migration wording Co-Authored-By: GPT-6.1-Sol --- quest/m1/auth/README.md | 1 - quest/m1/time/README.md | 4 ++-- quest/m3/stats-encoder-feedback.md | 2 +- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/quest/m1/auth/README.md b/quest/m1/auth/README.md index 270bef2c170..56a2f0375c1 100644 --- a/quest/m1/auth/README.md +++ b/quest/m1/auth/README.md @@ -138,7 +138,6 @@ because `main` assigned 0x3A to NOT_FETCHABLE first. - [Token in band](/quest/m1/auth/token-in-band.md) - the credential can leave the URL: a session starts on what the URL carried and its AUTH streams add the rest, with the URL kept for peers without the AUTH stream - subscription even while its joining FETCH waits for request-ID credit ## Related diff --git a/quest/m1/time/README.md b/quest/m1/time/README.md index d8e3c53157a..ba2d1b4f3d7 100644 --- a/quest/m1/time/README.md +++ b/quest/m1/time/README.md @@ -62,8 +62,8 @@ reasons, so later sessions don't reopen them: - **The simulator folds into `moq-clock`** behind a `sim` feature (a dev-dependency only, so production builds never compile it). It is one backend of the ambient clock, starts at zero, keeps deadlock detection, and - seeds the later runtime trait. `#[moq_clock::test]` replaces - `#[moq_clock::test]`. + seeds the later runtime trait. `#[moq_clock::test]` runs tests on this + backend. - **Tests for migrated contracts use the sim wherever possible.** A test with no real I/O that cannot run on the sim yet uses paused tokio, whose clock `moq-clock` reads. A real-I/O test never uses paused tokio, which auto-advances to the diff --git a/quest/m3/stats-encoder-feedback.md b/quest/m3/stats-encoder-feedback.md index 943af7ff149..660d438b5c3 100644 --- a/quest/m3/stats-encoder-feedback.md +++ b/quest/m3/stats-encoder-feedback.md @@ -11,7 +11,7 @@ it already follows. Keyframe requests stay out. ## Plan Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no named consumer; the media stats it -reads land first in m1. +reads land first in m2. Decided 2026-10-08: parked, and the transcode leg is out. The [ladder controller](/quest/m3/ladder/controller.md) owns every From c3550b9f2228beab7f765cea6a14b85aac8f251a Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 12:07:18 -0700 Subject: [PATCH 05/18] docs(quest): retire the completed datagram scheduler quest Implemented in #5770 and refined in #5872, with publisher integration, saturation and eviction regressions, fanout benchmarks, and draft coverage on main. Co-Authored-By: GPT-6.1-Sol --- quest/m1/quic/README.md | 2 - quest/m1/quic/datagram-priority.md | 112 ----------------------------- 2 files changed, 114 deletions(-) delete mode 100644 quest/m1/quic/datagram-priority.md diff --git a/quest/m1/quic/README.md b/quest/m1/quic/README.md index 82a301e8718..82bd4a6b9e5 100644 --- a/quest/m1/quic/README.md +++ b/quest/m1/quic/README.md @@ -68,8 +68,6 @@ cache limits remain separate; bitrate pacing composes with this memory cap. - [A reset group keeps its header](/quest/m1/quic/group-reset.md) - a lite publisher resets a group with `RESET_STREAM_AT`, so its subscriber drops the tail grace -- [Schedule datagrams by subscription priority](/quest/m1/quic/datagram-priority.md) - - datagrams join their subscription's send group instead of preempting every stream - [0-RTT streams adopt a raised stream window](/quest/m1/quic/zero-rtt-window-raise.md) - a server's larger stream window reaches the client's 0-RTT streams, so they no longer stall ## Related diff --git a/quest/m1/quic/datagram-priority.md b/quest/m1/quic/datagram-priority.md deleted file mode 100644 index 55b2d76ed59..00000000000 --- a/quest/m1/quic/datagram-priority.md +++ /dev/null @@ -1,112 +0,0 @@ -# [M] Schedule datagrams by subscription priority - -## Goal - -In `moq-quic`, a queued QUIC datagram is scheduled by its subscription's -priority in the same hierarchy as streams. A low-priority datagram track no -longer preempts higher-priority streams, and a high-priority one still goes -ahead of lower-priority streams. Both the lite and IETF publishers in -`rs/moq-net` hand each datagram to its subscription's send group. - -Today every quinn-derived stack (moq-noq, noq, `moq-quic`) packs every -queued DATAGRAM frame before any STREAM frame in `populate_packet` -(`rs/moq-quic/src/connection/mod.rs`, the `// DATAGRAM` loop ahead of -`// STREAM`), so datagrams beat every stream, control streams included, and -are FIFO among themselves. Nothing in moq-net orders them either. - -Out of scope: browsers. Chrome's QUICHE also sends datagrams first, and its -datagram `sendOrder` (`createWritable`) only orders datagrams among -themselves behind an experimental flag. Firefox's neqo starves datagrams -behind normal streams ([neqo#3813](https://github.com/mozilla/neqo/issues/3813)). -Neither can express a unified order, so js/net is unchanged. - -## Plan - -Decided 2026-10-10 with the maintainer: - -- **Unified priority, not "datagrams always first".** It matches MoQT - draft-21 section 5.1.2, where datagrams and subgroups share one priority - order and a datagram wins a tie within one group. Strict datagrams-first lets a busy - datagram track starve streams up to the congestion window, which is what - every stack does today. -- **A datagram queue per send group.** Each send group (one per - subscription, from `moq-quic`'s `SendGroups`) owns a - datagram queue. Datagram bytes spend - the group's fair-share credit, so a datagram-heavy subscription buys no - extra bandwidth over its equal-priority peers. The datagram send API takes - the same send-group handle as a stream; a datagram without one joins the - default group. -- **A datagram carries its order within the group**, the same value a stream - gets (its group sequence), so it merges into the subscription's - newest-first order: a queued datagram for group 10 waits behind a stream - for group 11. Only on a tie, a datagram and a stream of the same group, - does the datagram go first, which is MoQT draft-21's rule (group order - before forwarding preference). Decided 2026-10-10 after review: draining - every datagram ahead of the group's streams broke newest-first. Control - streams stay above datagrams because of their priority, not because of - frame order. Rejected: a separate datagram group - per subscription (two groups each, and it breaks the tie rule) and a - global datagram queue compared by scalar (it bypasses the fair tier). -- **Eviction is domain-aware: the lowest-priority oldest datagram goes - first.** Keep one connection-wide byte budget - (`datagram_send_buffer_size`). When a new datagram doesn't fit, pick the - scheduling domain holding the most queued datagram bytes (on a tie, the - domain whose oldest queued datagram is oldest), then evict the oldest - datagram of that domain's lowest-priority group, oldest first among equal - priorities. Counting bytes, not datagrams, keeps eviction byte-fair, the - same as the send tier. Drop the new datagram instead if it would itself be that - victim. Priorities are compared only inside a domain, because - [Scope track priority](/quest/m1/track-priority-scope.md) confines them to - the broadcast when cluster fairness is on; with fairness off there is one - domain. Decided 2026-10-10 after review: a connection-wide comparison let - one busy high-priority broadcast evict every datagram of another. Sending - never blocks, so the poll-shaped `poll_send_datagram` becomes a - synchronous `send_datagram` that can't represent Pending, and moq-tokio - (drop oldest today) and moq-uring (drop newest today) behave the same. Each runtime keeps its current budget size. Rejected: RTT-based - expiry (a timer path and a tuning constant) and per-group budgets (memory - grows with subscriptions). -- **Draft:** add a sentence to the Prioritization section of - `drafts/draft-lcurley-moq-lite.md`: a publisher SHOULD apply a - subscription's priority and group order to its datagrams as to its - streams, and SHOULD send the datagram first when both carry the same - group. No wire change. Run `just drafts check`. -- **No browser quest**, and no comment on neqo#3813. - -Tests in `moq-quic`, reusing the scheduler's saturation fixtures: a -low-priority datagram group waits behind a higher-priority stream, a -high-priority datagram preempts a lower-priority stream, a datagram for an -older group waits behind a stream for a newer one, a datagram goes ahead of -a stream of its own group, datagram and stream bytes share one group's -fair-share credit, eviction removes the lowest-priority oldest datagram -first, and with fairness on two saturated broadcasts both keep sending -datagrams, including when one sends many small datagrams and the other few -large ones. In moq-net, a lite and an IETF publisher pass the subscription's -send group and group sequence with each datagram. - -Eviction fans out over domains, send groups, and queued datagrams, so add a -benchmark sweeping each axis independently (many broadcasts with one group -each included). Picking a victim must not scan every domain or group on each -enqueue: keep a byte counter per domain in a heap keyed by queued bytes, and -a per-domain heap of groups keyed by priority. - -Public API: the datagram send path in `moq-quic` and moq-net's transport -trait (`poll_send_datagram` in `rs/moq-net/src/transport.rs`) becomes a -synchronous `send_datagram` taking a send-group handle and a group -sequence. -Every implementation follows: moq-tokio (`transport.rs`, -`transport/owned.rs`), moq-uring (`transport/adapter.rs`, -`quic/driver/connection.rs`, `quic/web.rs`), moq-ffi and moq-wasm -(`transport/adapter.rs`), moq-net's `ietf/adapter.rs`, and the test mocks. -moq-uring's `quic/web.rs` serves WebTransport over the worker's own QUIC -connection, so it honors the handle and order like raw QUIC. moq-wasm sits -on the browser's WebTransport, which cannot rank a datagram against -a stream, so it ignores the handle and order and keeps its current -best-effort send. Wire: none. - -Docs: the Priority row in `doc/concept/moq-lite.md` says datagrams are not -part of the equal-priority byte split yet; drop that once they are. - -## Related - -- [Scope track priority](/quest/m1/track-priority-scope.md) - owns what a - subscription's priority means; datagrams follow it From a64c49312673e57df71f313b7eca5a26feb00098 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 12:07:27 -0700 Subject: [PATCH 06/18] docs(quest): require data values before exact binding timestamps Co-Authored-By: GPT-6.1-Sol --- quest/m1/binding-timestamps.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/quest/m1/binding-timestamps.md b/quest/m1/binding-timestamps.md index 20403c6446c..fd8058c6a24 100644 --- a/quest/m1/binding-timestamps.md +++ b/quest/m1/binding-timestamps.md @@ -55,7 +55,10 @@ Verification: round-trip a 90 kHz tick, a present zero, and untimed through moq-ffi, moq-c, C++ and every wrapper's tests; refuse scale 0, an out-of-range scale, and an out-of-range value; `just test interop --all`. -## Related +## Required - [Data consumer timestamps](/quest/m1/data-consumer-timestamps.md) - lands first with the interim microsecond fields this replaces + +## Related + - [Controlled time](/quest/m1/time/README.md) - wall and monotonic time, not media timestamps; keep the types distinct From a93b9bc7bb684bd854af5002e331673ef22fe771 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 12:07:41 -0700 Subject: [PATCH 07/18] docs(quest): trace loss audit leads to their current owners Co-Authored-By: GPT-6.1-Sol --- quest/m1/random-loss-audit.md | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/quest/m1/random-loss-audit.md b/quest/m1/random-loss-audit.md index caf37c02ffc..2a0316df99d 100644 --- a/quest/m1/random-loss-audit.md +++ b/quest/m1/random-loss-audit.md @@ -40,15 +40,23 @@ changed for random loss; `LOSS_THRESH` is still 2%): `--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. + [the BBR study](/quest/m2/quic-bbr-natural-drain.md) and the former + `m3/quic-gcc.md` survive, since their premise rests on random loss. + The latter was replaced by the approved + [realtime uplink line](/quest/m2/quic-realtime/README.md) in #5889. + Audit the historical premise and any decisions it carried forward; + replacing that quest does not authorize abandoning the later line's + approved goals without a maintainer decision. - 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. + the former `quic-probe.md` (with noq#811 and noq#476), now + [the probe line](/quest/m2/probe/README.md) after #5863, + [QUIC on the sim](/quest/m2/quic-sim.md), + [deadlines](/quest/m2/quic-deadline.md), + [careful resume](/quest/m3/quic-careful-resume.md) ("the impaired path + profile"), [cut-through](/quest/m3/cut-through/bench.md), and + [TS recovery](/quest/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. From eb8cf2e7a4e873cbd04db5bef3470dfd3089c20b Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 12:09:40 -0700 Subject: [PATCH 08/18] docs(quest): align encrypted publishers with the approved identity contract Co-Authored-By: GPT-6.1-Sol --- quest/m2/e2ee/browser.md | 8 +++++++- quest/m2/e2ee/cli.md | 9 ++++++++- quest/m2/e2ee/rust-publish.md | 9 ++++++++- 3 files changed, 23 insertions(+), 3 deletions(-) diff --git a/quest/m2/e2ee/browser.md b/quest/m2/e2ee/browser.md index d8b299abfd2..501974184d8 100644 --- a/quest/m2/e2ee/browser.md +++ b/quest/m2/e2ee/browser.md @@ -10,7 +10,13 @@ Existing plaintext operation remains the default; an explicit application creden - Integrate the TypeScript E2EE layer before the existing Hang publish and after the existing Hang subscribe boundaries, keeping codec selection, synchronization, and rendering in the post-decryption pipelines. - Accept keys through a programmatic property/API only, never an HTML attribute, URL, persistent browser storage, analytics event, or log. Clear owned secret bytes when the component is replaced or disconnected; do not make extractability a hidden requirement. -- Derive the opaque broadcast name from the semantic one, discover the newest epoch under that prefix, derive the encrypted catalog name from that generation, decrypt it before existing Hang selection, then subscribe to its opaque media and timeline tracks. Publish every catalog representation and semantic track name through the same protected naming contract. +- Derive the invariant opaque broadcast path from the semantic name and + resolve that path, taking the selected epoch from its route. On a wire + without route epochs, the application supplies the epoch. Derive the + encrypted catalog name from that generation, decrypt it before existing + Hang selection, then subscribe to its opaque media and timeline tracks. + Publish every catalog representation and semantic track name through the + same protected naming contract. - Refuse the stats track and the `echo` attribute while a credential is set: they would publish rendition IDs and per-track counters in plaintext beside the protected broadcast. This quest owns the refusal (decided 2026-10-08), since the stats quests have no encrypted mode to refuse until this credential exists. - Cover camera/microphone publication, the stats and `echo` refusal, audio/video playback, late subscription, WebCrypto backpressure through awaited writes, a restarted publisher under a new epoch, bad-group termination, and bad-datagram events in browser tests. diff --git a/quest/m2/e2ee/cli.md b/quest/m2/e2ee/cli.md index b0a07472d5e..cebced5002d 100644 --- a/quest/m2/e2ee/cli.md +++ b/quest/m2/e2ee/cli.md @@ -10,7 +10,14 @@ Existing plaintext commands remain the default; an explicit application credenti - Integrate the Rust E2EE layer into `moq-cli` publication and playback before semantic mux output and after protected track input. Keep codec, capture, playback, and synchronization logic outside the crypto layer. - Accept the credential through a dedicated file descriptor, otherwise-unused stdin, or a permission-checked file (`0600` on Unix), never a command argument or environment variable. Redact errors and tracing, zeroize owned secret bytes, and document shell-safe invocation. -- Inject opaque physical names into mux, video, audio, timeline, and catalog construction. Take the semantic broadcast name from the user and publish under its opaque derivation; mint a UUIDv7 epoch per publisher run and discover the newest one under the opaque prefix when playing; derive and decrypt the protected catalog before existing selection, and suppress every plaintext Hang or MSF catalog representation. +- Follow the approved protected naming contract for mux, video, audio, + timeline, and catalog construction. Take the semantic broadcast name from + the user and publish at its invariant opaque path with a fresh UUIDv7 + route epoch per publisher run. Playback resolves that path and takes the + selected epoch from its route; the application supplies it on a wire + without route epochs. Derive and decrypt the protected catalog before + existing selection, and suppress every plaintext Hang or MSF catalog + representation. - Refuse any path that hands an encrypting publisher an epoch it did not mint, before connecting (maintainer, 2026-10-08): a shared epoch repeats AES-GCM nonces. `moq --epoch` is removed by [distinct importer epochs](/quest/m0/broadcast-epoch/distinct-importer-epochs.md). - Refuse `--stats` and `--echo` together with a credential: they would publish rendition IDs and per-track counters in plaintext beside the protected broadcast. This quest owns the refusal (decided 2026-10-08), since the stats quests have no encrypted mode to refuse until this credential exists. - Cover native audio/video publication and playback, late subscription, a restarted publisher under a new epoch, `--stats` or `--echo` with a credential refused, clean authentication errors, and both lite and IETF transports. diff --git a/quest/m2/e2ee/rust-publish.md b/quest/m2/e2ee/rust-publish.md index ea310fc0dd7..f53958a9a70 100644 --- a/quest/m2/e2ee/rust-publish.md +++ b/quest/m2/e2ee/rust-publish.md @@ -11,7 +11,14 @@ The reusable crypto crate remains independent of Hang and codec-specific publish Publishers use `Credential::produce()` and its `generation::Producer`; the producing/consuming split landed separately in #5313. -- Provide injectable opaque-name allocation or explicit-name constructors for mux, video, audio, timeline, and catalog publishers that currently derive semantic names. +- After the dynamic-name design is approved, adapt mux, video, audio, + timeline, and catalog publishers to its chosen naming contract. + Applications keep semantic track names; the e2ee broadcast wrappers own + their translation to physical names, as the epic specifies. - Derive the protected catalog name from its well-known logical role, then put media roles, codecs, quality, timelines, and custom-track mappings only inside the encrypted catalog. - Encrypt both Hang catalog representations and encrypt or suppress the MSF catalog. Compress protected catalog bodies before encryption and retain ordinary plaintext publication unchanged outside E2EE mode. - Cover every current Rust importer and capture path so a convenience API cannot silently recreate `.avc3`, `.opus`, timeline, or other semantic suffixes. + +## Required + +- [Dynamic names](/quest/m2/e2ee/dynamic-names.md) - the maintainer approves the naming design before implementation starts From 4301b40d1c5de12db07d8e9e901007465a1a0bac Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 12:09:53 -0700 Subject: [PATCH 09/18] docs(quest): gate the BBR study on its loss audit Co-Authored-By: GPT-6.1-Sol --- quest/m2/quic-bbr-natural-drain.md | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/quest/m2/quic-bbr-natural-drain.md b/quest/m2/quic-bbr-natural-drain.md index df4d0e5a176..2eacbe4a182 100644 --- a/quest/m2/quic-bbr-natural-drain.md +++ b/quest/m2/quic-bbr-natural-drain.md @@ -8,14 +8,20 @@ ProbeRTT, recognizing bandwidth growth within a round, and precautionary bandwidth probing. Reduce demonstrated frame deadline interference without stale minimum RTT, persistent queues, or unfairness. Application limitation alone is not evidence that the path drained, and Google parity is not -assumed to be an improvement. Grade them, and BBR's response to random -loss, on a 10 % random-loss media profile as well. +assumed to be an improvement. Acceptance and performance verdicts use +bufferbloat: a rate below the media bitrate behind a deep but finite queue +whose overflow drops packets. Random loss may check correctness, but never +grades media quality or performance. ## Plan Decided in the 2026-09-30 audit: the Google BBR comparison merged here as one study, since both reuse the same media profiles, harness, and baseline. +The random-loss audit decides whether this study survives before it starts, +as the maintainer decided on 2026-10-17. The measurements below preserve +its historical motivation; they are not acceptance criteria. + ### Natural drains Use `moq-quic`'s BBR3, which carries the released fork's corrections, as @@ -86,10 +92,9 @@ pinned code and configurations. Keep transport differences and QUICHE flags explicit and compare each algorithm change separately. A simulation result is not an end-to-end network measurement. -### Random loss +### Historical random-loss observations -Moved from the finished T-STD export epic (2026-10-16), whose nightly -stays at 1 %. +Moved from the finished T-STD export epic (2026-10-16). `just test ts --hrd --loss ` drops that share of the relay's datagrams to the subscriber at random through `moq-shaper`, 25 ms each way, and grades the export with T-STD, PCR accuracy and `holes.py`. Measured on a @@ -105,9 +110,13 @@ loaded host (rerun before deciding): BBRv3 takes a round with more than 2 % loss (`LOSS_THRESH`) as congestion and cuts its inflight bound, so random loss above it holds the leg below the -media rate. Decide whether and how BBR should tell random loss from -congestion without giving up fairness against loss-based flows, and how that -interacts with the precautionary probe stop under Google differences. +media rate. Re-judge those observations on bufferbloat before proposing +any change to the congestion response or precautionary probe stop. A +random-loss quality result alone cannot justify weakening either. + +## Required + +- [Random-loss audit](/quest/m1/random-loss-audit.md) - decides whether this study survives and records its bufferbloat verdict ## Related From 993a625b9c5ac7695eaf356f66883a41dcd81526 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 12:10:07 -0700 Subject: [PATCH 10/18] docs(quest): narrow error cleanup to its unfinished removal Co-Authored-By: GPT-6.1-Sol --- quest/m2/README.md | 2 +- quest/m2/error-cleanups.md | 17 +++++------------ 2 files changed, 6 insertions(+), 13 deletions(-) diff --git a/quest/m2/README.md b/quest/m2/README.md index 978ae902389..c94b789fb26 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -167,4 +167,4 @@ ranked just below deterministic TS legs, which it requires. - [RTMP client reports a publish or play error](/quest/m2/rtmp-client-error.md) - a refused publish or play surfaces its reason - [Adopt usage-rs 7](/quest/m2/usage-rs-7.md) - the workspace builds on usage-rs 7 - [Dead routes on IETF name their cause](/quest/m2/js-ietf-dead-route-error.md) - a JS subscription on a dead moq-transport session ends with the session error, not `unauthorized` -- [Error cleanups](/quest/m2/error-cleanups.md) - delete the unused `Error::SessionClosed`, and Rust and JS both reset a served stream over a raw transport failure with `Unroutable` +- [Error cleanups](/quest/m2/error-cleanups.md) - delete the unused `Error::SessionClosed`; raw transport failures already map to `Unroutable` diff --git a/quest/m2/error-cleanups.md b/quest/m2/error-cleanups.md index 7cd83c9809f..98b2e5d2ad1 100644 --- a/quest/m2/error-cleanups.md +++ b/quest/m2/error-cleanups.md @@ -3,12 +3,7 @@ ## Goal `moq_net::Error::SessionClosed`, which nothing outside tests constructs, is -deleted. A raw transport failure or idle timeout (a session that failed -without a close code) resets a served stream with `Unroutable` in both Rust -and JS, so one condition sends one code. Today both send `Internal`: Rust's -`StreamError::from(&Error)` in `rs/moq-net/src/error.rs` reaches its -catch-all arm for `Transport` and `IdleTimeout`, and `localStreamCode` in -`js/net/src/error.ts` falls through. +deleted. ## Plan @@ -16,12 +11,10 @@ Decided with the maintainer on 2026-10-17: the goal as drafted, from the follow-ups of [#5729](https://github.com/moq-dev/moq/pull/5729), widened the same day to Rust after review found Rust sends `Internal` too. -#5729 was still open at planning, and its head already maps `Transport`, -`IdleTimeout` and a codeless session failure to `Unroutable` in both -languages, with unit tests in `rs/moq-net/src/error.rs` and -`js/net/src/error.test.ts`. If it lands that way, confirm those tests and -finish only the `SessionClosed` removal; otherwise add the mapping and a -test on each side here. +#5729 landed as `50da59e67`. It maps `Transport`, `IdleTimeout` and a +codeless session failure to `Unroutable` in both languages, with unit tests +in `rs/moq-net/src/error.rs` and `js/net/src/error.test.ts`. Keep that +behavior and its tests; only the `SessionClosed` removal remains here. `SessionClosed` has match arms in `rs/moq-net` (`error.rs`, `model/resume.rs`), `rs/moq-ffi/src/error.rs` and `rs/moq-relay`, and From 4f8e2e97c57b2a9a5b0237bf294132a62950b6b2 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 12:10:09 -0700 Subject: [PATCH 11/18] docs(quest): state the approved intra-refresh recovery promise Co-Authored-By: GPT-6.1-Sol --- quest/m2/intra-refresh/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/quest/m2/intra-refresh/README.md b/quest/m2/intra-refresh/README.md index 6d4e42f062b..ac72c0af628 100644 --- a/quest/m2/intra-refresh/README.md +++ b/quest/m2/intra-refresh/README.md @@ -6,8 +6,9 @@ Video encoded with periodic intra refresh has no keyframes. Each frame refreshes a stripe of the picture, so a decoder that starts at the beginning of a sweep is clean once the sweep completes, and the bitrate never spikes. This questline makes such video a first-class hang broadcast on import and playback: streams -contributed that way import cleanly, and every viewer tunes in without a -visible glitch. +contributed that way import cleanly, and viewers stay live while recovering +to a clean picture. A cold join or skip may show refresh stripes until the +second decoder catches up, as the playback decision below permits. Measured on 2026-10-06: at fixed quality, a 60s keyframe interval saves 10-16% against 2s on the 240p-720p rungs and about 10% at 1080p (x264 From 1929161f1c62bb4c9b02c6150cbd00861902751b Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 12:10:21 -0700 Subject: [PATCH 12/18] docs(quest): distinguish existing shard steering from shared demux Co-Authored-By: GPT-6.1-Sol --- quest/m2/one-port/README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/quest/m2/one-port/README.md b/quest/m2/one-port/README.md index 3d78a5fe488..f2baef71539 100644 --- a/quest/m2/one-port/README.md +++ b/quest/m2/one-port/README.md @@ -43,8 +43,11 @@ reuse its filter rather than recreating that completed work. RFC 7983 already partitions the first byte: STUN is 0 to 3, DTLS 20 to 63, RTP and RTCP 128 to 191. QUIC fills the gaps: a long header is 192 to 255 and a short header 64 to 127, as long as the fixed bit is set, so the QUIC -config disables QUIC-bit greasing (RFC 9287) explicitly; `moq-quic` turns it on by -default and nothing here disables it today. SRT does not fit: +config disables QUIC-bit greasing (RFC 9287) explicitly. `moq-quic` turns it +on by default, but the existing shard-steering path already disables it in +`rs/moq-tokio/src/quic/backend.rs`. The shared demux must apply the same +requirement to every QUIC endpoint it serves, including an unsharded one. +SRT does not fit: its data packets start with a 0 bit and its control packets with a 1, so both overlap. SRT is demuxed by flow instead. A 4-tuple ICE has succeeded on is pinned to WebRTC in the outer table before any SRT test, because an RTP v2 packet From b1d4010eed1c98a7d09fa04e3a3089be10ffe0b0 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 12:10:23 -0700 Subject: [PATCH 13/18] docs(quest): record the landed benchmark site pipeline Co-Authored-By: GPT-6.1-Sol --- quest/m2/bench-site.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/quest/m2/bench-site.md b/quest/m2/bench-site.md index 3dc29a290f6..c2eefba2e6f 100644 --- a/quest/m2/bench-site.md +++ b/quest/m2/bench-site.md @@ -10,9 +10,10 @@ site. ## Plan -The pipeline is in review. Remaining: the maintainer enables repository Pages -with **Source: GitHub Actions** (until then the Nightly's Benchmark site job -fails at deployment), then verifies the first Nightly deployment at +The pipeline landed in #5759 (`9fcb3f327`), including the shared history +publisher and explicit Pages deployment. Pages activation and the first +successful deployment remain unverified: confirm the repository uses +**Source: GitHub Actions** and verify the first Nightly deployment at . The "Rust benchmark tests" job is not charted yet: its nextest benchmarks print no structured measurements. @@ -42,4 +43,7 @@ Decided with the maintainer on 2026-10-15: - Document the site URL, what each series means, and local reproduction in `bench/README.md`. +The implementation and documentation above are on `main`; verify their +first deployed reports rather than rebuilding the pipeline. + Public API: none. Wire: none. From dfe2e92cbbe11953f0c79777b07e50b3b798a3a5 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 12:10:51 -0700 Subject: [PATCH 14/18] docs(quest): record the later mobile completion deferral Co-Authored-By: GPT-6.1-Sol --- quest/m2/mobile-completion.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/quest/m2/mobile-completion.md b/quest/m2/mobile-completion.md index c52463d29b0..4991d2370b5 100644 --- a/quest/m2/mobile-completion.md +++ b/quest/m2/mobile-completion.md @@ -21,7 +21,8 @@ native/mobile getting-started docs with the working path. Do not close #700 merely because its next subset or a design decision finished. Promoted from m2 on 2026-10-09 by maintainer priority, with both capture -quests. +quests. Deferred back to m2 in #5427 (`8f0dfa760`) with those capture +quests; mobile completion does not gate the next breaking cut. ## Required From fca02fecca5388a7e208735a7ad2be2bb34e62cd Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 12:10:51 -0700 Subject: [PATCH 15/18] docs(quest): separate landed wire accounting from adapter work Co-Authored-By: GPT-6.1-Sol --- quest/m2/wire-stats/README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/quest/m2/wire-stats/README.md b/quest/m2/wire-stats/README.md index 50490a99137..f79e706149c 100644 --- a/quest/m2/wire-stats/README.md +++ b/quest/m2/wire-stats/README.md @@ -44,6 +44,18 @@ depends on the workload. Measured wire/payload in moq.pro's bench: A provider bills the wire, so a relay operator needs per-root wire bytes to see cost per tenant. +The shared core landed in #5773 (`778263c50`): `Presence` carries both +counters, `moq_net::stats::Handle::wire` registers embedder sources, and +the stats producer samples and preserves their final values. Native tokio +and io_uring QUIC sources and their relay integration tests are already on +`main`. Reuse that registry and accounting; do not create another one. + +Remaining here: finish the qmux and SRT adapter children, then verify their +wire counters appear in the existing per-root presence and per-tier totals +alongside native sessions, with final counts retained when a source closes. +Confirm the stats documentation describes the supported adapters and their +receive-side limitations. + - **`Presence`, not `Traffic`.** `Presence` is already per (tier, root) and per session. `Traffic.bytes` stays payload, and its docs say so. - **Named `wire_tx` / `wire_rx`.** Rejected: `bytes_sent`, which reads like From 19df183eaec1e6d993fb96c27877fca683b3ea82 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 12:10:51 -0700 Subject: [PATCH 16/18] docs(quest): preserve unverified benchmark report gaps Co-Authored-By: GPT-6.1-Sol --- quest/m2/bench-site.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/quest/m2/bench-site.md b/quest/m2/bench-site.md index c2eefba2e6f..d9329fcf77d 100644 --- a/quest/m2/bench-site.md +++ b/quest/m2/bench-site.md @@ -43,7 +43,7 @@ Decided with the maintainer on 2026-10-15: - Document the site URL, what each series means, and local reproduction in `bench/README.md`. -The implementation and documentation above are on `main`; verify their -first deployed reports rather than rebuilding the pipeline. +Keep the landed publisher and documented local reproduction; verify the +deployed reports before filling any remaining measurement gaps. Public API: none. Wire: none. From 01eba8ee1078ebd948b2aeee5e04d9beef80db38 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 12:11:33 -0700 Subject: [PATCH 17/18] docs(quest): checkpoint whole-tree audit and unresolved conflicts Co-Authored-By: GPT-6.1-Sol --- quest/m0/audit-quests.md | 42 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/quest/m0/audit-quests.md b/quest/m0/audit-quests.md index 35143c45abc..0a7ebf169e9 100644 --- a/quest/m0/audit-quests.md +++ b/quest/m0/audit-quests.md @@ -22,3 +22,45 @@ follow-up through `/quest-plan`. Run `/quest-audit`. After a release cut shifts the milestones, also check that the move left no broken links or misplaced quests. Until now, audits ran ad hoc (2026-09-30, 10-05, 10-08, 10-10). + +Checkpoint, 2026-10-19, against `main` at `2e1ec2ebf`: + +- Read all 438 documents: m0, m3, and global structure in the coordinating + audit, with parallel reviewers for all 133 m1 and 222 m2 documents. + Structural validation found no broken links, cycles, or prerequisites in + a later milestone. +- Retired datagram priority: #5770 (`79005b06d`) and #5872 (`8e3966cd3`) + already contain the scheduler, publisher integration, saturation and + eviction tests, fan-out benchmarks, and draft updates. Broadcast-domain + exposure remains owned by track-priority-scope. +- Encoded the already-decided timestamp, E2EE naming-design, and BBR audit + prerequisites. Corrected stale paths, epoch discovery, accepted refresh + recovery behavior, mobile priority, and the landed error, shard, benchmark + site, and wire-accounting work. Cut-through and BBR performance judgments + now follow the existing bufferbloat policy; historical loss data remains. +- Four closed linked issues still have explicitly planned or in-flight + work. Their closure alone was not treated as evidence to retire a quest. + Open implementation PRs were not treated as merged work. +- `quest check` passes for the remaining 437 documents, as does + `git diff --check`. The full `just check` exit was not captured; its + attempted capture run was rejected because another suite was running. + +This run remains open, with no successor, until the unresolved conflicts are +settled. The unattended instruction was to skip uncertain choices: + +- [Auth issuer](/quest/m1/auth/issuer.md) specifies a shared handle and one + live session's grant, but not how independent concurrent sessions select + grants and refusals. Existing reconnect code only designates one active + generation alongside draining predecessors. +- [Binding linger](/quest/m1/linger-ffi.md) extends the hand-written C ABI, + while [generated C](/quest/m1/c/README.md) freezes it except claim safety. +- [Catalog HLS](/quest/m1/archive/catalog-hls.md) names `.hls.z` tracks, + while [compression migration](/quest/m1/compress/migrate.md) removes `.z` + names. Their shared timeline edits need a consistent final name and order. +- [Priority scope](/quest/m1/track-priority-scope.md) still preserves old + archive priority encoding, while [archive](/quest/m1/archive/README.md) + replaces the old layout without migration. The ladder also assumes a + publisher-priority tiebreak that priority scope still asks to decide. +- Per-request auth planning is separately owned by + [#5972](https://github.com/moq-dev/moq/pull/5972), following the rejection + of #5927. Preserve that owner's decisions and reconcile after it lands. From 83e5288bf65cea9d75ea129f25a784557e9047ab Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 12:12:06 -0700 Subject: [PATCH 18/18] docs(quest): record final validation against current main Co-Authored-By: GPT-6.1-Sol --- quest/m0/audit-quests.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/quest/m0/audit-quests.md b/quest/m0/audit-quests.md index 0a7ebf169e9..845db826906 100644 --- a/quest/m0/audit-quests.md +++ b/quest/m0/audit-quests.md @@ -41,7 +41,9 @@ Checkpoint, 2026-10-19, against `main` at `2e1ec2ebf`: - Four closed linked issues still have explicitly planned or in-flight work. Their closure alone was not treated as evidence to retire a quest. Open implementation PRs were not treated as merged work. -- `quest check` passes for the remaining 437 documents, as does +- Final validation includes `main` at `f37d19b73` (#5920), whose completed + auth-refresh quest and updated clock-migration plan were rechecked. + `quest check` passes for the remaining 436 documents, as does `git diff --check`. The full `just check` exit was not captured; its attempted capture run was rejected because another suite was running.