From e215edf77353dbfa132600fa3e8a34c836b0fd3f Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 9 Nov 2026 23:46:14 -0800 Subject: [PATCH] quest: plan the 2026-11-09 deletion audit and prune m5 Plans the cuts the maintainer picked from a repository-wide deletion and simplification audit, and deletes 80 m5 quests with no consumer, checked against moq.pro's plans. Co-Authored-By: Claude Opus 5.5 --- quest/m0/ci/trim.md | 40 ++++ quest/m1/README.md | 6 + quest/m1/audit-merge.md | 40 ++++ quest/m1/carla-workspace.md | 23 ++ quest/m1/drafts-publish-trim.md | 19 ++ quest/m1/ffi-doc-trim.md | 20 ++ quest/m1/receive-windows-evicted.md | 2 +- quest/m1/test-time-rule.md | 21 ++ quest/m1/unused-code.md | 45 ++++ quest/m2/README.md | 2 + quest/m2/api-shape/README.md | 16 ++ quest/m2/boy-unpublish.md | 28 +++ quest/m2/cluster-routing/README.md | 8 +- quest/m2/cluster-routing/federation.md | 1 - quest/m2/cluster-routing/routes/README.md | 2 - quest/m2/ietf-scope/README.md | 44 ++++ quest/m2/ietf-scope/extensions.md | 36 +++ quest/m2/ietf-scope/serving.md | 34 +++ quest/m2/probe/README.md | 1 - quest/m2/subscribe-ranges/README.md | 6 +- quest/m3/audio-decode-audiotoolbox.md | 5 - quest/m3/audit-deps.md | 5 +- quest/m3/audit-perf.md | 16 +- quest/m3/audit-size.md | 7 +- quest/m3/cache-routing/README.md | 1 - quest/m3/follow-refused-retry.md | 4 +- quest/m3/js-announced-coalesce.md | 4 - quest/m3/json-snapshot-resync.md | 4 - quest/m3/obs-moq-video/README.md | 8 +- quest/m3/obs-moq-video/linux-bundle.md | 4 - quest/m3/obs-moq-video/vpx-obs.md | 4 - quest/m3/qos/README.md | 2 - quest/m3/qos/lag-histogram.md | 4 +- quest/m3/quic-ack-hook.md | 4 +- quest/m3/quic-realtime/README.md | 3 - quest/m3/quic-realtime/moqsink-feedback.md | 1 - quest/m3/stats/README.md | 8 +- quest/m3/stats/rust.md | 5 +- quest/m3/vaapi-vulkan-import.md | 1 - quest/m3/video-quality/README.md | 3 +- quest/m3/video-quality/on-demand.md | 4 - quest/m3/webcodecs-priming.md | 1 - ...ipewire-dma-bufs-safely-into-the-vulkan.md | 4 - quest/m4/README.md | 1 - quest/m4/announce-interest-memory.md | 1 - quest/m4/audio-visqol.md | 2 - quest/m4/cache-fairness.md | 1 - quest/m4/mutants.md | 31 --- quest/m4/p2p/README.md | 6 +- quest/m4/p2p/cost-scopes.md | 4 - quest/m4/p2p/harness.md | 3 +- quest/m4/perf/quic-lock-contention.md | 1 - quest/m4/perf/shard-default.md | 1 - quest/m4/quic-sim.md | 4 - quest/m4/resume-redesign.md | 4 - quest/m4/route-wakes.md | 1 - ...evc-and-av1-support-in-the-nvidia-codec.md | 38 --- ...te-35-ad-cue-signaling-carried-opaquely.md | 50 ---- ...bandwidth-grant-in-moq-audio-instead-of.md | 82 ------- quest/m5/README.md | 79 +------ quest/m5/ac3-low-rate.md | 21 -- quest/m5/announce-credit.md | 71 ------ quest/m5/announce-fanout-allocs.md | 21 -- quest/m5/archive-lookup-withdrawal.md | 22 -- quest/m5/archive-paced-replay.md | 38 --- quest/m5/archive-time-followups.md | 1 - quest/m5/audio-decode-mediacodec.md | 35 --- quest/m5/audio-decode-mediafoundation.md | 29 --- quest/m5/audio-encode-audiotoolbox.md | 44 ---- quest/m5/audio-encode-mediacodec.md | 33 --- quest/m5/audio-encode-mediafoundation.md | 29 --- quest/m5/audio-filters.md | 31 --- quest/m5/audio-opus-backend.md | 48 ---- quest/m5/auth-http-request-kind.md | 36 --- quest/m5/auth-sign-caps.md | 13 -- quest/m5/auth-token-fetch.md | 26 --- quest/m5/c-origin-relay.md | 30 --- quest/m5/captions-cea.md | 30 --- quest/m5/catalog-republish-cost.md | 29 --- quest/m5/cpp-conan.md | 32 --- quest/m5/cpp-vcpkg.md | 35 --- quest/m5/cut-through/README.md | 79 ------- quest/m5/cut-through/bench.md | 52 ----- quest/m5/cut-through/loss-delay.md | 44 ---- quest/m5/delivery-delay.md | 37 --- quest/m5/emsg.md | 64 ----- quest/m5/ffi-size-profile.md | 26 --- quest/m5/flv-script.md | 32 --- quest/m5/id3.md | 44 ---- quest/m5/ietf-cluster-peers.md | 45 ---- quest/m5/ietf-hole-marker.md | 87 ------- quest/m5/json-value-diff.md | 62 ----- quest/m5/ladder/README.md | 84 ------- quest/m5/ladder/controller.md | 70 ------ quest/m5/ladder/fetch.md | 41 ---- quest/m5/latency-ledger.md | 58 ----- quest/m5/link-quality.md | 4 +- quest/m5/lite05-subscribe-end.md | 32 --- quest/m5/mkv-input-coalesce.md | 32 --- quest/m5/msf-publish-tracks.md | 21 -- quest/m5/msfts-convergence.md | 43 ---- quest/m5/nvenc-av1.md | 1 - quest/m5/obs-decode-linux.md | 16 -- quest/m5/obs-decode-windows.md | 15 -- quest/m5/obs-linux-gpu.md | 26 --- quest/m5/obs-macos.md | 16 -- quest/m5/obs-windows.md | 23 -- quest/m5/origin-front-parks.md | 58 ----- quest/m5/performance-survey/README.md | 221 ------------------ .../performance-survey/announced-snapshots.md | 32 --- .../browser-media-copies.md | 34 --- quest/m5/performance-survey/cache-metadata.md | 38 --- quest/m5/performance-survey/gst-buffers.md | 31 --- quest/m5/performance-survey/hls-serving.md | 32 --- quest/m5/performance-survey/send-groups.md | 31 --- .../performance-survey/session-selection.md | 30 --- quest/m5/performance-survey/task-capacity.md | 57 ----- quest/m5/pipewire-camera-planes.md | 15 -- quest/m5/qos-lag-dashboard.md | 39 ---- quest/m5/quic-bbr-study.md | 106 --------- quest/m5/quic-careful-resume.md | 37 --- quest/m5/quic-deadline.md | 94 -------- quest/m5/quic-ecn-measure.md | 47 ---- quest/m5/quic-ecn.md | 41 ---- quest/m5/quic-egress-profile.md | 134 ----------- quest/m5/quic-io-boundary.md | 4 - quest/m5/quic-lb-forward-extras.md | 31 --- quest/m5/receive-pool.md | 81 ------- quest/m5/recover-budget.md | 31 --- quest/m5/request-token-surfaces.md | 29 --- quest/m5/room-bench.md | 22 -- quest/m5/route-health/README.md | 125 ---------- quest/m5/route-health/idle-timeout.md | 12 - quest/m5/route-health/meta.md | 68 ------ quest/m5/route-health/recovery.md | 88 ------- quest/m5/route-health/selection.md | 45 ---- quest/m5/route-interest-prefixes.md | 36 --- quest/m5/routing-cost-domains.md | 85 ------- quest/m5/stats-encoder-feedback.md | 101 -------- quest/m5/unreal.md | 31 --- quest/m5/video-codec-coverage.md | 35 --- quest/m5/video-hardware.md | 4 +- quest/m5/watch-webxr.md | 30 --- quest/m5/webgpu-hdr.md | 42 ---- 144 files changed, 418 insertions(+), 4072 deletions(-) create mode 100644 quest/m0/ci/trim.md create mode 100644 quest/m1/audit-merge.md create mode 100644 quest/m1/carla-workspace.md create mode 100644 quest/m1/drafts-publish-trim.md create mode 100644 quest/m1/ffi-doc-trim.md create mode 100644 quest/m1/test-time-rule.md create mode 100644 quest/m1/unused-code.md create mode 100644 quest/m2/boy-unpublish.md create mode 100644 quest/m2/ietf-scope/README.md create mode 100644 quest/m2/ietf-scope/extensions.md create mode 100644 quest/m2/ietf-scope/serving.md delete mode 100644 quest/m4/mutants.md delete mode 100644 quest/m5/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md delete mode 100644 quest/m5/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md delete mode 100644 quest/m5/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md delete mode 100644 quest/m5/ac3-low-rate.md delete mode 100644 quest/m5/announce-credit.md delete mode 100644 quest/m5/announce-fanout-allocs.md delete mode 100644 quest/m5/archive-lookup-withdrawal.md delete mode 100644 quest/m5/archive-paced-replay.md delete mode 100644 quest/m5/audio-decode-mediacodec.md delete mode 100644 quest/m5/audio-decode-mediafoundation.md delete mode 100644 quest/m5/audio-encode-audiotoolbox.md delete mode 100644 quest/m5/audio-encode-mediacodec.md delete mode 100644 quest/m5/audio-encode-mediafoundation.md delete mode 100644 quest/m5/audio-filters.md delete mode 100644 quest/m5/audio-opus-backend.md delete mode 100644 quest/m5/auth-http-request-kind.md delete mode 100644 quest/m5/auth-sign-caps.md delete mode 100644 quest/m5/auth-token-fetch.md delete mode 100644 quest/m5/c-origin-relay.md delete mode 100644 quest/m5/captions-cea.md delete mode 100644 quest/m5/catalog-republish-cost.md delete mode 100644 quest/m5/cpp-conan.md delete mode 100644 quest/m5/cpp-vcpkg.md delete mode 100644 quest/m5/cut-through/README.md delete mode 100644 quest/m5/cut-through/bench.md delete mode 100644 quest/m5/cut-through/loss-delay.md delete mode 100644 quest/m5/delivery-delay.md delete mode 100644 quest/m5/emsg.md delete mode 100644 quest/m5/ffi-size-profile.md delete mode 100644 quest/m5/flv-script.md delete mode 100644 quest/m5/id3.md delete mode 100644 quest/m5/ietf-cluster-peers.md delete mode 100644 quest/m5/ietf-hole-marker.md delete mode 100644 quest/m5/json-value-diff.md delete mode 100644 quest/m5/ladder/README.md delete mode 100644 quest/m5/ladder/controller.md delete mode 100644 quest/m5/ladder/fetch.md delete mode 100644 quest/m5/latency-ledger.md delete mode 100644 quest/m5/lite05-subscribe-end.md delete mode 100644 quest/m5/mkv-input-coalesce.md delete mode 100644 quest/m5/msf-publish-tracks.md delete mode 100644 quest/m5/msfts-convergence.md delete mode 100644 quest/m5/obs-decode-linux.md delete mode 100644 quest/m5/obs-decode-windows.md delete mode 100644 quest/m5/obs-linux-gpu.md delete mode 100644 quest/m5/obs-macos.md delete mode 100644 quest/m5/obs-windows.md delete mode 100644 quest/m5/origin-front-parks.md delete mode 100644 quest/m5/performance-survey/README.md delete mode 100644 quest/m5/performance-survey/announced-snapshots.md delete mode 100644 quest/m5/performance-survey/browser-media-copies.md delete mode 100644 quest/m5/performance-survey/cache-metadata.md delete mode 100644 quest/m5/performance-survey/gst-buffers.md delete mode 100644 quest/m5/performance-survey/hls-serving.md delete mode 100644 quest/m5/performance-survey/send-groups.md delete mode 100644 quest/m5/performance-survey/session-selection.md delete mode 100644 quest/m5/performance-survey/task-capacity.md delete mode 100644 quest/m5/pipewire-camera-planes.md delete mode 100644 quest/m5/qos-lag-dashboard.md delete mode 100644 quest/m5/quic-bbr-study.md delete mode 100644 quest/m5/quic-careful-resume.md delete mode 100644 quest/m5/quic-deadline.md delete mode 100644 quest/m5/quic-ecn-measure.md delete mode 100644 quest/m5/quic-ecn.md delete mode 100644 quest/m5/quic-egress-profile.md delete mode 100644 quest/m5/quic-lb-forward-extras.md delete mode 100644 quest/m5/receive-pool.md delete mode 100644 quest/m5/recover-budget.md delete mode 100644 quest/m5/request-token-surfaces.md delete mode 100644 quest/m5/room-bench.md delete mode 100644 quest/m5/route-health/README.md delete mode 100644 quest/m5/route-health/idle-timeout.md delete mode 100644 quest/m5/route-health/meta.md delete mode 100644 quest/m5/route-health/recovery.md delete mode 100644 quest/m5/route-health/selection.md delete mode 100644 quest/m5/route-interest-prefixes.md delete mode 100644 quest/m5/routing-cost-domains.md delete mode 100644 quest/m5/stats-encoder-feedback.md delete mode 100644 quest/m5/unreal.md delete mode 100644 quest/m5/video-codec-coverage.md delete mode 100644 quest/m5/watch-webxr.md delete mode 100644 quest/m5/webgpu-hdr.md diff --git a/quest/m0/ci/trim.md b/quest/m0/ci/trim.md new file mode 100644 index 00000000000..be7975ac770 --- /dev/null +++ b/quest/m0/ci/trim.md @@ -0,0 +1,40 @@ +# [M] CI lanes that fail or repeat the queue are cut + +## Goal + +Every workflow either produces a signal someone reads or is gone. Today +`cache.yml` fails every run, `cache-refresh.yml` has never passed, +`mutants.yml` has never produced a result, and three workflows re-run on +`main` what the merge queue already ran. + +## Plan + +Planned 2026-11-09 (maintainer, /quest-plan from the deletion audit). +Decided: ✅ CI trims (rejected: leave CI as the 2026-11-01 workflow audit +kept it). Joins m0 because `cache.yml` is broken now (rule: broken CI is m0). + +- `cache.yml`: every push to `main` fails in the warm jobs with + `does not contain a 'flake.nix'` (the `roots` recipe runs outside the + checkout), including the macOS job. Fix it and add it to `alert.yml`, or + delete it if the R2 and nix.moq.dev caches already cover what it warms; + reproduce first and say which in the PR. Check + [Cachix retire](/quest/m0/ci/cachix-retire.md), which also edits it. +- Delete `cache-refresh.yml`. It guards against weeks without a merge, and + `main` lands more than ten PRs a day. +- Delete `mutants.yml`. Its one run failed all 24 shards creating + `target/mutants`, and `test/drill/sensitivity.sh` already runs hand-written + mutations nightly. This PR deleted its quest. +- `codspeed.yml` moves from every Rust push on `main` to the nightly + schedule. It gates nothing, and 62 of its last 100 runs were cancelled by + the next push. The 2026-10-28 decision to keep CodSpeed stands; only its + trigger changes. +- `check.yml` stops running for PRs into `main` and keeps `release` + admission; the queue runs the same `just ci`. +- `quest.yml` drops its `main` push trigger and keeps `release` and + `quest/**`; `main` lands only through the queue, which runs the quest + checks. + +Update the rows these change in [CI workflow audit](/quest/m3/audit-ci.md) +and any doc naming the removed workflows. + +Public API: none. Wire: none. diff --git a/quest/m1/README.md b/quest/m1/README.md index ce4af68e701..f578c647594 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -44,6 +44,12 @@ moves what remains of them once their claims merge. - [A padded TS export sheds when its sink falls behind](/quest/m1/ts-padded-shed.md) - a `--mux-rate` export skips stale slots with a flagged PCR jump instead of back-filling them or blaming the source - [A resumed QUIC client gives up on its own idle timer](/quest/m1/quic-resume-idle.md) - a client stopped past its idle timeout closes within about one timeout of resuming, without waiting on a stateless reset - [A reused moq-transport alias delivers a group that beats its SUBSCRIBE_OK](/quest/m1/ietf-alias-reuse.md) - a new SUBSCRIBE clears its track's alias tombstone, so moqxr's alias-0 catalog refetch no longer hangs +- [Unused crates, scripts, and files are deleted](/quest/m1/unused-code.md) - moq-room, the moq-native tombstone, demo/throttle, sh/dart/publish.sh, demo/web's Solid deps, and unpublished packages' release notes go +- [The recurring audits are fewer and carry plans, not results](/quest/m1/audit-merge.md) - m3's 13 audits become about five, each a Goal plus a short check-first list +- [The CARLA bridge builds outside the root workspace](/quest/m1/carla-workspace.md) - workspace builds stop compiling the demo bridge +- [.github/ffi.md holds rules, not evidence](/quest/m1/ffi-doc-trim.md) - the FFI release doc drops one-off measurements for links to their PRs +- [Draft publishing keeps the upload and drops changelog rewriting](/quest/m1/drafts-publish-trim.md) - `sh/drafts/publish.sh` and its test shrink to the datatracker upload +- [rs/AGENTS.md's time-test rule matches the tree](/quest/m1/test-time-rule.md) - the rule names `#[kio::test]`, which about 4,900 tests use, and is stated once ## Related diff --git a/quest/m1/audit-merge.md b/quest/m1/audit-merge.md new file mode 100644 index 00000000000..52f59f85989 --- /dev/null +++ b/quest/m1/audit-merge.md @@ -0,0 +1,40 @@ +# [M] The recurring audits are fewer and carry plans, not results + +## Goal + +m3's 13 recurring `audit-*.md` quests become about five, each a Goal plus a +short "check first" list. Results and baselines live in the PR that measured +them, not in the plan. + +## Plan + +Planned 2026-11-09 (maintainer, /quest-plan from the deletion audit). +Decided: ✅ merge the audits (rejected: keep 13 separate recurring audits). + +The 13 files total about 23.6k words, mostly result tables from past runs +(`audit-ci.md` alone is about 7,400 words describing one Nightly). +Several overlap: dead code against simplify, CI against test cost, and deps, +size, and compile time all trace back to dependencies. The same ~150-word +recurrence paragraph is copied into each. + +Recommended grouping, the implementer's call: + +- Cost: CI, test cost, compile time, artifact size, dependencies. +- Code: dead code, simplification, lints. +- Tests: coverage. +- Docs. +- Interop. +- Performance. + +Delete [quest tree audit](/quest/m3/audit-quests.md); `/quest-audit` does +that job. Keep each merged audit's "decided" carve-outs and the still-useful +"check first" items. Drop result tables, measured baselines, and history, +linking the PR that recorded them instead. Each merged audit keeps the +recurrence rule (successor added by the PR that finishes a run, behind the +[release cut](/quest/m3/release/cut.md)), stated once per file in a line or +two. Update m3's README links and anything else that links a merged file. + +[CI lane trims](/quest/m0/ci/trim.md) edits `audit-ci.md` rows; whichever +lands second adapts. + +Public API: none. Wire: none. diff --git a/quest/m1/carla-workspace.md b/quest/m1/carla-workspace.md new file mode 100644 index 00000000000..c1269ee2f73 --- /dev/null +++ b/quest/m1/carla-workspace.md @@ -0,0 +1,23 @@ +# [S] The CARLA bridge builds outside the root workspace + +## Goal + +`demo/carla/bridge` is no longer a root Cargo workspace member, so workspace +builds, checks, and `cargo` metadata stop compiling a demo bridge, while the +bridge still builds and is checked when its own files change. + +## Plan + +Planned 2026-11-09 (maintainer, /quest-plan from the deletion audit). +Decided: ✅ exclude it from the workspace (rejected: keep it a member; +move it to its own repository). + +The bridge is the root `Cargo.toml`'s first `members` entry. Give it its own +workspace and lock file, keep its check in the dispatch for `demo/carla/**` +changes, and keep the files where they are: moq.pro reads +`demo/carla/sim/trucks.json` from its pin. Check the GPU end-to-end test in +[vendor-free CARLA bridge](/quest/m5/carla-bridge.md) and +[macOS check](/quest/m0/macos-check.md), which touch the bridge, still find +it. + +Public API: none. Wire: none. diff --git a/quest/m1/drafts-publish-trim.md b/quest/m1/drafts-publish-trim.md new file mode 100644 index 00000000000..091da73c938 --- /dev/null +++ b/quest/m1/drafts-publish-trim.md @@ -0,0 +1,19 @@ +# [S] Draft publishing keeps the upload and drops changelog rewriting + +## Goal + +`sh/drafts/publish.sh` uploads a draft to the datatracker and nothing else +automated: the changelog heading rewriting, about half of its 298 lines, and +most of the 653-line `publish.test.sh` that every `just drafts check` runs +are gone. The 17 drafts publish a few times a year, so the author edits the +changelog by hand. + +## Plan + +Planned 2026-11-09 (maintainer, /quest-plan from the deletion audit). +Decided: ✅ trim (rejected: keep the automation). + +Keep whatever test still guards the upload path. Update `drafts/` docs or +CONTRIBUTING text that describes the removed step. + +Public API: none. Wire: none. diff --git a/quest/m1/ffi-doc-trim.md b/quest/m1/ffi-doc-trim.md new file mode 100644 index 00000000000..f878de7ea0f --- /dev/null +++ b/quest/m1/ffi-doc-trim.md @@ -0,0 +1,20 @@ +# [S] .github/ffi.md holds rules, not evidence + +## Goal + +`.github/ffi.md` states the FFI release layout and its rules in about a +sixth of its 264 lines. The one-off evidence moves out: SHA comparisons, +runner image versions, OpenH264 assembly differences, and runner-minute +tables belong to the PRs that measured them. + +## Plan + +Planned 2026-11-09 (maintainer, /quest-plan from the deletion audit). +Decided: ✅ trim (rejected: leave as is). + +Link the PR for any evidence a rule still rests on. Drop the temporary rule +that accepts legacy per-language workflow names for a tag cut from a +`release` older than the coordinator once `release` carries the +coordinator; if it does not yet, keep that rule and say when it goes. + +Public API: none. Wire: none. diff --git a/quest/m1/receive-windows-evicted.md b/quest/m1/receive-windows-evicted.md index 366ead9ee98..2e2b292cbe1 100644 --- a/quest/m1/receive-windows-evicted.md +++ b/quest/m1/receive-windows-evicted.md @@ -84,7 +84,7 @@ What remains: `Cell::fits` partition in `benchmark_receive_windows`), and run the full sweep through `quest gate`. - Retain the stream/frame/window axes and the actual offered workload - for [Receive pool](/quest/m5/receive-pool.md). + for a shared receive budget, if one is planned again. - Repro: `just rs test -p moq-tokio --test integration --release -E 'test(benchmark_receive_windows)' --run-ignored only --success-output immediate`. diff --git a/quest/m1/test-time-rule.md b/quest/m1/test-time-rule.md new file mode 100644 index 00000000000..fa07bdcceb0 --- /dev/null +++ b/quest/m1/test-time-rule.md @@ -0,0 +1,21 @@ +# [S] rs/AGENTS.md's time-test rule matches the tree + +## Goal + +`rs/AGENTS.md` tells an agent writing a time-dependent Rust test what the +tree actually does. Its rule says such tests call `tokio::time::pause()` and +that only moq-net and moq-relay's in-memory tests use `#[kio::test]`; the +tree has about 4,900 `kio::test` uses (moq-mux, moq-tokio, moq-ffi, and +more) against about 200 `pause()` calls. + +## Plan + +Planned 2026-11-09 (maintainer, /quest-plan from the deletion audit, which +the maintainer prompted). Decided: ✅ fix the stale rule (rejected: leave it). + +Follow `quest guide prompting`. State the rule once: the time-mocking rule +also appears in `quest context`, `REVIEW.md`, `rs/moq-net/AGENTS.md`, and +`clippy.toml`, so drop any copy that only repeats it. Say when `pause()` is +still the right tool, if ever. + +Public API: none. Wire: none. diff --git a/quest/m1/unused-code.md b/quest/m1/unused-code.md new file mode 100644 index 00000000000..b47616cd23f --- /dev/null +++ b/quest/m1/unused-code.md @@ -0,0 +1,45 @@ +# [S] Unused crates, scripts, and files are deleted + +## Goal + +Code and files with no consumer, whose removal breaks no published API, are +gone: the `moq-room` crate, the `moq-native` tombstone, `demo/throttle`, +`sh/dart/publish.sh`, `demo/web`'s Solid dependencies, and release notes for +packages that never publish. + +## Plan + +Planned 2026-11-09 (maintainer, /quest-plan from the deletion audit). +Decided: ✅ delete, in one PR with one commit each (rejected: keep them for +possible future use). + +- `rs/moq-room`: `publish = false` since + [moq-dev/moq#6454](https://github.com/moq-dev/moq/pull/6454), no + workspace or binding consumer, and `doc/lib/rs/moq-room.md` already points + users to `@moq/room`. Delete the crate, its workspace entry, and its doc + page, and rewrite [room alias withdraw](/quest/m3/room-alias-withdraw.md) + to JS only. `@moq/room` stays. +- `rs/moq-native`: the 0.20.0 tombstone has been on crates.io since + 2026-09-23 and stays there. Remove the crate and its workspace entry so the + shared-minor cut cannot publish another tombstone. The redirects in + `doc/worker.js` stay. +- `demo/throttle`: a macOS-only pf/dummynet script behind `just throttle` in + `demo/justfile`; moq-shaper does seeded, cross-platform impairment. +- `sh/dart/publish.sh`: no caller; the release workflows run + `dart pub publish` inline. +- `demo/web`: `solid-js`, `vite-plugin-solid`, and `solidPlugin()` with no + `.tsx` in the demo. +- Release notes for packages that never publish: `demo/boy/CHANGELOG.md`, + `js/p2p/MIGRATE.md`, `js/crypto/MIGRATE.md`, `rs/moq-quic/MIGRATE.md` + (157 lines), and the "unpublished API" paragraph in `rs/moq-congestion`'s + README. A package gets them when it first publishes. +- `rs/moq-rtmp/src/flv.rs` matches `moq_mux::Error::TimestampRewind` to + decide which demux failures end the session, against the rule never to + match on errors. Make the importer report that outcome as its own result + instead; how is the implementer's call. + +Kept on purpose (2026-11-09): `Hang.Health` and `hang::health` have no +caller in this repository, but moq.pro's QoS line plans to use the client +health sample and classification. + +Public API: none (moq-room and moq-native no longer publish). Wire: none. diff --git a/quest/m2/README.md b/quest/m2/README.md index 716148b6409..116dddd854e 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -204,3 +204,5 @@ quests that require them. - [Finishing a media producer returns a Finished handle](/quest/m2/finished-handle.md) - `finish(self)` consumes the media crates' producers, as it does moq-net's, so appending after finish doesn't compile - [Probe](/quest/m2/probe/README.md) - a session probes up to the bitrate it wants to send or receive, so a stopped simulcast rendition resumes and a viewer up-switches; browser padding is parked in m3 (held in m2 by open claims; moves to m3) - [Finish the milestone re-cut](/quest/m2/recut-held.md) - claim-held epics move to the milestone their kind and priority give them once their claims merge +- [moq-transport is a compatibility layer again](/quest/m2/ietf-scope/README.md) - our extensions, JS FETCH serving, and track listing leave moq-transport; live media and joining FETCH stay +- [MoQ Boy is a demo, not a published package](/quest/m2/boy-unpublish.md) - `moq-boy` and `@moq/boy` stop publishing, and `@moq/signals/solid` goes with them diff --git a/quest/m2/api-shape/README.md b/quest/m2/api-shape/README.md index 1b8dd7965db..b754f23006d 100644 --- a/quest/m2/api-shape/README.md +++ b/quest/m2/api-shape/README.md @@ -57,6 +57,22 @@ Rejected in planning: - Folding these items into the larger quests: those wait on decisions or prototypes, and these do not. +Added 2026-11-09 (maintainer, /quest-plan from the deletion audit): the +pre-cut sweep also deletes these, which a "used only by its definition" +search misses or which are not items: + +- `@moq/watch`'s `Arrival`/`Arrivals` export and `decoder.arrivals()`: + only `test/audio-quality` uses them, and it can import from source. Not on + `release`, so removing them breaks nobody. +- `@moq/qmux`'s `install()`: no caller, and it cannot help Safari, which + ships a broken WebTransport rather than none. +- `moq-nvenc`'s `src/sys/windows_sys` (680 KB generated): moq-video depends + on moq-nvenc only under `cfg(target_os = "linux")`. +- `moq-sock`'s `fast-apple-datapath` feature (`udp/apple_fast.rs`), which only + `just rs macos-test` enables, and its WASI arm (`udp/wasi.rs`), which no + target builds. Update [cmsg length on send](/quest/m3/cmsg-len-send.md), + which names the feature. + ## Required - [A peer's closed session reads as Closed in the bindings](/quest/m2/api-shape/session-closed.md) - a remote SESSION_CLOSED maps to `MoqError::Closed`, as a local close does diff --git a/quest/m2/boy-unpublish.md b/quest/m2/boy-unpublish.md new file mode 100644 index 00000000000..f5fc421ff30 --- /dev/null +++ b/quest/m2/boy-unpublish.md @@ -0,0 +1,28 @@ +# [S] MoQ Boy is a demo, not a published package + +## Goal + +The `moq-boy` crate and `@moq/boy` npm package stop publishing, and MoQ Boy +lives as a demo: no semver, CHANGELOG, MIGRATE, API report, or release tag. +The Solid UI it alone carries leaves the published surface with it. The +hosted demo keeps working. + +## Plan + +Planned 2026-11-09 (maintainer, /quest-plan from the deletion audit). +Decided: ✅ unpublish (rejected: keep publishing; delete MoQ Boy). +Joins m2 because ending a published package is breaking. + +- `rs/moq-boy`: `publish = false`, drop its CHANGELOG and MIGRATE, and drop + the `moq-boy-v*` tags from `release-nix.yml`. Keep the flake package + `moq-boy`: moq.pro's demo hosts build it from their pin. +- `js/moq-boy`: move into `demo/boy` as a private package with no API + report, MIGRATE, or trusted-publisher entry. +- `@moq/signals/solid` has no other consumer: delete it. Either rewrite the + Boy UI on `@moq/signals/dom`, as watch and publish do, or keep Solid + private to `demo/boy`; the implementer picks the smaller change. +- The release cut deprecates the last published versions on crates.io and + npm with a pointer to the demo. + +Public API: breaking. `moq-boy` and `@moq/boy` stop publishing, and +`@moq/signals/solid` is removed. Wire: none. diff --git a/quest/m2/cluster-routing/README.md b/quest/m2/cluster-routing/README.md index b1df1c94fd2..bcccbbd027f 100644 --- a/quest/m2/cluster-routing/README.md +++ b/quest/m2/cluster-routing/README.md @@ -9,9 +9,8 @@ Known advertisements remain distinct from current reachability, and stale copies cannot revive a claim after its withdrawal is known. Reliability, federation, and P2P are independently shippable milestones of -this architecture. Active/passive delivery health is a separate -[route-health line](/quest/m5/route-health/README.md), shared by endpoints -and relays, and applies only to broadcasts with epochs. +this architecture. Active/passive delivery health is out of scope; its +plan was deleted 2026-11-09 for want of a consumer. ## Plan @@ -122,7 +121,7 @@ reduces origin count when every application publishes one broadcast. Non-goals: measured RTT/loss pricing by default, TURN, browser transit, full link-state topology, or cross-operator economic exchange rates. Basic federation does not wait for -[routing cost domains](/quest/m5/routing-cost-domains.md). Node routes here +administrative routing cost domains, which nobody plans. Node routes here are the cold cost that [cache-aware routing](/quest/m3/cache-routing/README.md)'s per-broadcast warm routes rank against (decided 2026-11-08, maintainer). @@ -137,7 +136,6 @@ setup after the capabilities land. ## Related -- [Route health](/quest/m5/route-health/README.md) - epoch-only active/passive delivery monitoring and automatic recovery - [P2P](/quest/m4/p2p/README.md) - application-selected peer sessions feed the shared routing model - [Routing guide](/quest/m1/routing-guide.md) - concept page and federation setup; P2P extends it in m4 - [Route wakes](/quest/m4/route-wakes.md) - local work follows affected fronts rather than the whole covered table diff --git a/quest/m2/cluster-routing/federation.md b/quest/m2/cluster-routing/federation.md index bb44c6ef8a3..0b869dc6a94 100644 --- a/quest/m2/cluster-routing/federation.md +++ b/quest/m2/cluster-routing/federation.md @@ -79,5 +79,4 @@ Rust/JS parity. Run `just check`, `just test interop --all`, and `just drafts ch ## Related -- [Route health](/quest/m5/route-health/README.md) - epoch-only detection of stalled delivery on still-open links - [Routing guide](/quest/m1/routing-guide.md) - runnable operator setup after integration diff --git a/quest/m2/cluster-routing/routes/README.md b/quest/m2/cluster-routing/routes/README.md index ac0b1214c4d..896cffeae82 100644 --- a/quest/m2/cluster-routing/routes/README.md +++ b/quest/m2/cluster-routing/routes/README.md @@ -548,5 +548,3 @@ benchmarks. ## Related - [Route wakes](/quest/m4/route-wakes.md) - index work follows the settled source-selection model -- [Route health](/quest/m5/route-health/README.md) - epoch-only progress observation and local delivery failover -- [A route stream's interest is a set of prefixes](/quest/m5/route-interest-prefixes.md) - m5: one stream's interest covers several prefixes diff --git a/quest/m2/ietf-scope/README.md b/quest/m2/ietf-scope/README.md new file mode 100644 index 00000000000..0fe228c3de0 --- /dev/null +++ b/quest/m2/ietf-scope/README.md @@ -0,0 +1,44 @@ +# moq-transport is a compatibility layer again + +## Goal + +Our moq-transport support covers what a third-party implementation needs to +exchange live media with ours, and stops there: SETUP, the standard +AUTHORIZATION TOKEN, live PUBLISH_NAMESPACE / SUBSCRIBE / PUBLISH, joining +FETCH, and relay forwarding between moq-transport and moq-lite sessions, +including across our relays. Our own extensions and the IETF-only features +nobody third-party uses are deleted from Rust, JS, and the drafts. + +## Plan + +Planned 2026-11-09 (maintainer, /quest-plan from the deletion audit). +Decided: ✅ freeze the IETF scope (rejected: keep growing IETF features to +parity with lite). + +AGENTS.md calls moq-transport "a low-effort compatibility layer", but Rust +`ietf/` is 62.3k lines (28.3k logic) against `lite/`'s 40.4k (21.0k logic), +and both `ietf/publisher.rs` and `ietf/subscriber.rs` grew by thousands of +lines since 2026-10-23. Since August, the Rust IETF code took 465 commits +against lite's 429. + +Settled with this epic: + +- Deleted from m5 by this PR, as work the freeze rules out: + moq-transport hole markers and moq-transport cluster peers. +- Kept: moq-transport drafts 18, 20, and 22 (draft 20 restored on purpose in + [moq-dev/moq#7190](https://github.com/moq-dev/moq/pull/7190)), and the + relay paths moq.pro's fleet smoke runs: cross-relay moq-transport + subscribes and a draft-18 session to a third-party relay. +- Kept, as rejected in the same interview: lite-07's `ietf` object extension + and moq-lite 01 to 04. +- Not here: `ietf/flate.rs`; compression removal has its own work. + +This epic's own work, after its children: the docs that describe +moq-transport support (`doc/concept/`, `drafts/draft-lcurley-moq-ietf.md` if +it lists the extensions, and the interop matrix in +[interop audit](/quest/m3/audit-interop.md)) state the frozen scope, and +AGENTS.md's IETF rule is reworded only if the maintainer asks. + +## Related + +- [Simplification audit](/quest/m3/audit-simplify.md) - owns duplication inside the IETF code that remains diff --git a/quest/m2/ietf-scope/extensions.md b/quest/m2/ietf-scope/extensions.md new file mode 100644 index 00000000000..a35decf28f0 --- /dev/null +++ b/quest/m2/ietf-scope/extensions.md @@ -0,0 +1,36 @@ +# [L] Our extensions stop riding moq-transport + +## Goal + +moq-transport sessions no longer negotiate or carry our own extensions: +cluster, hidden, solicit, active count, and the moq-auth extension. Rust +(`rs/moq-net/src/ietf/{cluster,hidden,solicit,active_count,auth}.rs`), JS +(`js/net/src/ietf/{cluster,hidden,solicit,active_count,auth,auth_setup}.ts`), +their handshake wiring, tests, and the moq-transport sections of the +matching `drafts/draft-lcurley-moq-*` documents are deleted. They stay on +moq-lite, where our own peers use them. + +## Plan + +Part of the [IETF scope freeze](/quest/m2/ietf-scope/README.md), decided +2026-11-09. None of the third-party implementations our interop runs +(Cloudflare, moxygen, imquic, MOQtail, aiomoqt) speaks these extensions, and +our own peers connect over moq-lite. + +- Keep the standard AUTHORIZATION TOKEN (`ietf/token.rs`, `token.ts`): it is + how a third party authenticates. +- Wire: an extension removed here is one a peer must have negotiated, so a + published client or relay that offers it gets a session without it rather + than a failure. Verify that against the published `@moq/net` and the + release relay before deleting each one; if one would break a published + peer's session, stop and report it. +- A relay forwarding a hidden or soliciting lite broadcast to a + moq-transport subscriber now treats it as moq-transport does (hidden + broadcasts are never forwarded there). Test that boundary in both + languages. +- JS exports such as `Ietf.Cluster` go; the PR's Impact section carries the + migration note. + +Public API: breaking (JS `Ietf` extension types; Rust items under `ietf` +that are public). Wire: moq-transport sessions stop negotiating our +extensions; moq-lite is unchanged. diff --git a/quest/m2/ietf-scope/serving.md b/quest/m2/ietf-scope/serving.md new file mode 100644 index 00000000000..07691ef2cc9 --- /dev/null +++ b/quest/m2/ietf-scope/serving.md @@ -0,0 +1,34 @@ +# [M] moq-transport FETCH serving in JS and track listing are gone + +## Goal + +js/net no longer answers moq-transport FETCH as a publisher, and moq-net no +longer lists a moq-transport peer's tracks with SUBSCRIBE_TRACKS +(`ietf/subscribe_tracks.rs`, `ietf/subscriber/tracks.rs`, and the JS +`subscribe_tracks.ts`). A received SUBSCRIBE_TRACKS is refused, as it is +today. + +## Plan + +Part of the [IETF scope freeze](/quest/m2/ietf-scope/README.md), decided +2026-11-09. JS FETCH serving and its pacing landed in +[moq-dev/moq#6945](https://github.com/moq-dev/moq/pull/6945), +[moq-dev/moq#7793](https://github.com/moq-dev/moq/pull/7793), +[moq-dev/moq#7794](https://github.com/moq-dev/moq/pull/7794), +[moq-dev/moq#8117](https://github.com/moq-dev/moq/pull/8117), and +[moq-dev/moq#8231](https://github.com/moq-dev/moq/pull/8231); a browser +publisher serving a third-party FETCH has no user. Relays keep answering +FETCH from their cache, and a subscriber keeps its joining FETCH. + +Before deleting track listing, confirm no relay or moq.pro path needs it to +bridge a moq-transport publisher into moq-lite announcements; if one does, +keep that part, record why here, and delete the rest. A JS publisher that +receives a moq-transport FETCH answers it with the error moq-transport +defines for an unsupported request. + +[Subscribe ranges](/quest/m2/subscribe-ranges/README.md) fills relay misses +over moq-transport; this quest leaves relay FETCH alone. + +Public API: breaking only if js/net exposes a FETCH-serving option or Rust a +track-listing call publicly; name each in the PR's Impact section. Wire: +none; both are optional moq-transport behaviors. diff --git a/quest/m2/probe/README.md b/quest/m2/probe/README.md index 981ecbc7d71..535612b10f0 100644 --- a/quest/m2/probe/README.md +++ b/quest/m2/probe/README.md @@ -103,5 +103,4 @@ This README's own work, once the children land: ## Related -- [BBR media study](/quest/m5/quic-bbr-study.md) - preserving an estimate and discovering spare capacity are separate problems - [Realtime uplink congestion control](/quest/m3/quic-realtime/README.md) - a delay-based alternative to BBR3 on native uplinks; it must implement native probing to ship (decided 2026-10-25) diff --git a/quest/m2/subscribe-ranges/README.md b/quest/m2/subscribe-ranges/README.md index 2b7d9e6cf75..337688b3b8c 100644 --- a/quest/m2/subscribe-ranges/README.md +++ b/quest/m2/subscribe-ranges/README.md @@ -48,9 +48,9 @@ relay bounds a sparse FETCH only if the model can request ranges: group's existing prefix but never wait for its future objects. Downstream, our publishers answer only a one-group FETCH or fill and refuse wider ones (maintainer, 2026-10-28, - [moq-dev/moq#7204](https://github.com/moq-dev/moq/pull/7204)), until - [hole markers](/quest/m5/ietf-hole-marker.md) let a cache that knows every - group answer a range. A FETCH of the track's newest live group is refused + [moq-dev/moq#7204](https://github.com/moq-dev/moq/pull/7204)), and the + [IETF scope freeze](/quest/m2/ietf-scope/README.md) adds no hole-marker + extension that would let a cache answer a range. A FETCH of the track's newest live group is refused unless its range ends below that group's live edge ([moq-dev/moq#7944](https://github.com/moq-dev/moq/pull/7944), `poll_settle` in `rs/moq-net/src/ietf/publisher.rs`), replacing the diff --git a/quest/m3/audio-decode-audiotoolbox.md b/quest/m3/audio-decode-audiotoolbox.md index d359e586bee..a6fdec784a0 100644 --- a/quest/m3/audio-decode-audiotoolbox.md +++ b/quest/m3/audio-decode-audiotoolbox.md @@ -34,8 +34,3 @@ alongside the `objc2-core-audio-types` the crate already carries. on a device like the rest of the mobile line. - Docs: the `decode` row in `doc/lib/rs/moq-audio.md` ("AAC-LC (mono or stereo)") names what macOS and iOS also decode. - -## Related - -- [Media Foundation decode](/quest/m5/audio-decode-mediafoundation.md) - the same shape on Windows -- [MediaCodec decode](/quest/m5/audio-decode-mediacodec.md) - the same shape on Android diff --git a/quest/m3/audit-deps.md b/quest/m3/audit-deps.md index df4c0371c81..3650393be70 100644 --- a/quest/m3/audit-deps.md +++ b/quest/m3/audit-deps.md @@ -212,9 +212,8 @@ standalone build, not incremental workspace savings. allocator would recreate stats_alloc's instrumentation. Their own units cost 0.05/0.03 s; cpu-time also needs libc/platform bindings. - `unsafe-libopus`: a nontrivial codec with active moq-audio consumers, - not a helper. The [Opus backend](/quest/m5/audio-opus-backend.md) comparison - still owns whether a different backend is better; deleting Opus is a - user-facing feature decision. + not a helper. No quest compares Opus backends (that plan was deleted + 2026-11-09); deleting Opus is a user-facing feature decision. - `moq-gst` keeps its Rust 1.92 floor for GStreamer 0.25, above the workspace's 1.91 library floor. Do not normalize that manifest to 1.91. - The QUIC/UDP, RTMP, V4L2, NVIDIA, VA-API, UniFFI and LibAV forks all have diff --git a/quest/m3/audit-perf.md b/quest/m3/audit-perf.md index f97f1464b0b..0ffce2dfa78 100644 --- a/quest/m3/audit-perf.md +++ b/quest/m3/audit-perf.md @@ -159,18 +159,18 @@ wall-clock bisect blames the wrong commit. Count instructions instead: Each needs a bench, swept over both axes where it fans out, or its own follow-up quest. The m1 run added none of these: -1. [HLS request fan-out](/quest/m5/performance-survey/hls-serving.md) owns +1. HLS request fan-out: repeated segment fetch/remux and playlist rendering, swept over viewers, renditions and window segments. 2. LOC and CMAF wire containers in moq-mux: `containers` and `export` only use `Container::Legacy`; sweep container x frame size x frames. -3. [Browser media copies](/quest/m5/performance-survey/browser-media-copies.md) - owns CMAF sample copies and LOC encode allocation. Generic `js/msf` and +3. Browser media copies: + CMAF sample copies and LOC encode allocation. Generic `js/msf` and `js/flate` benchmark coverage remains here. 4. moq-quic loss recovery and real congestion controllers: every bench pins `Unlimited`; sweep controller x flight x loss x streams. -5. [Announcement snapshots](/quest/m5/performance-survey/announced-snapshots.md) - owns HTTP snapshot/rendering costs across routes and pollers. +5. Announcement snapshots: + HTTP snapshot/rendering costs across routes and pollers. 6. JWT verification is covered: `moq-auth`'s `verify` bench runs nightly in `rust-extra` (see [bench/README.md](/bench/README.md#auth-verification)). Signature verification dominated every asymmetric algorithm; nothing @@ -183,9 +183,9 @@ follow-up quest. The m1 run added none of these: do not count that transfer as another mandatory copy. Sweep publishers x renditions, channels and frame duration in a browser. -The [2026-10-22 source survey](/quest/m5/performance-survey/README.md) owns -the extracted items above and additional algorithmic hypotheses, with paired -benchmarks required before optimization. This audit still owns nightly +The 2026-10-22 source survey's quests were deleted on 2026-11-09 for want of +a consumer; a measured regression or a consumer brings an item back, with +paired benchmarks required before optimization. This audit still owns nightly regression attribution and the remaining coverage. Its fragmented-MKV child specializes item 7's MKV work. diff --git a/quest/m3/audit-size.md b/quest/m3/audit-size.md index a79bdd9a38c..380ca1d9803 100644 --- a/quest/m3/audit-size.md +++ b/quest/m3/audit-size.md @@ -133,9 +133,9 @@ largest text-symbol increases to `moq_net` (+335,565 bytes), `moq_mux` attribution, not a compressed-byte decomposition. Cross-crate inlining, compiler-generated code, and metadata account for other bytes. [moq-dev/moq#7400](https://github.com/moq-dev/moq/pull/7400), merged after -these measurements, addresses the catalog serialization duplication lead. The [bindings size profile -quest](/quest/m5/ffi-size-profile.md) requires codec/crypto and FFI throughput -measurements before adopting opt-level s; no compiler profile was changed. +these measurements, addresses the catalog serialization duplication lead. Adopting opt-level s for the bindings would need codec/crypto and FFI +throughput measurements first; no quest plans it, and no compiler profile was +changed. The Swift source tarball grows in `Generated.swift`, from 684,643 to 704,105 bytes. Its new request/publication, token, media-read and decoder-start @@ -153,6 +153,5 @@ moq's WASM build was removed on 2026-10-31, so there is no WASM row to repeat. ## Related -- [FFI size profile](/quest/m5/ffi-size-profile.md) - [Native synchronous codecs](/quest/m5/native-compression-sync.md) - [Native browser codecs](/quest/m5/native-compression-adopt.md) diff --git a/quest/m3/cache-routing/README.md b/quest/m3/cache-routing/README.md index e54ff8d0c75..c64008dc77b 100644 --- a/quest/m3/cache-routing/README.md +++ b/quest/m3/cache-routing/README.md @@ -101,4 +101,3 @@ This README's own work, once its children land: - [Cluster routing](/quest/m2/cluster-routing/README.md) - the node routes and feasibility distances this ranks on - [Relays split horizon per session](/quest/m3/route-split-horizon.md) - per-session suppression of node routes, beside warm routes' per-neighbor rule -- [Route health](/quest/m5/route-health/README.md) - stalled-delivery failover, separate from choosing where a copy is pulled diff --git a/quest/m3/follow-refused-retry.md b/quest/m3/follow-refused-retry.md index ca2a23ab2fb..fc12b8c410a 100644 --- a/quest/m3/follow-refused-retry.md +++ b/quest/m3/follow-refused-retry.md @@ -44,8 +44,7 @@ decision 2 (maintainer, 2026-11-04) ruled out. Build on `Following` as [moq-dev/moq#7678](https://github.com/moq-dev/moq/pull/7678) left it, which reports the path going offline beside its `refused` flag. If the -path watch changes under -[front parking](/quest/m5/origin-front-parks.md), use its replacement. +path watch has changed since, use its replacement. Tests: a refused follower asks the replacement after an overlapping identical-route handler swap; an announcement listener sees no event for @@ -57,5 +56,4 @@ Public API: none. Wire: none. ## Related -- [Front parking](/quest/m5/origin-front-parks.md) - the same refusal wait for `request` - [The HLS server follows each path once](/quest/m4/hls-follow-once.md) - another `Following` addition diff --git a/quest/m3/js-announced-coalesce.md b/quest/m3/js-announced-coalesce.md index 723bdd04f25..bca61294af1 100644 --- a/quest/m3/js-announced-coalesce.md +++ b/quest/m3/js-announced-coalesce.md @@ -19,7 +19,3 @@ saw cancels it. The JS lite publisher already coalesces this way Tests: churn on one path while the reader is idle leaves one pending event; a start then end before a read leaves nothing; a restart after a read is still delivered. - -## Related - -- [Announce credit](/quest/m5/announce-credit.md) - bounds how many paths there can be diff --git a/quest/m3/json-snapshot-resync.md b/quest/m3/json-snapshot-resync.md index 4ab5364bc23..2e91d66e9cf 100644 --- a/quest/m3/json-snapshot-resync.md +++ b/quest/m3/json-snapshot-resync.md @@ -43,7 +43,3 @@ state. The maintainer approved planning the fix from #7693's iterate. delta fails instead of applying to stale state. Public API: at most a `skipped()` counter in `@moq/json` and `moq-json`. Wire: none. - -## Related - -- [Benchmark a Value merge-patch diff for moq-json](/quest/m5/json-value-diff.md) - may replace the Rust diff this consumer applies diff --git a/quest/m3/obs-moq-video/README.md b/quest/m3/obs-moq-video/README.md index 88c28e60b47..8c4de7db7ed 100644 --- a/quest/m3/obs-moq-video/README.md +++ b/quest/m3/obs-moq-video/README.md @@ -12,7 +12,7 @@ Attempt GPU delivery immediately on macOS decode; other platforms keep the CPU p Initial video decoding covers H.264, HEVC, and AV1 where moq-video has an available backend. Unsupported codecs produce an actionable error; do not retain an FFmpeg fallback. VP8/VP9 return through their own follow-up quest. Audio playback covers Opus, AAC-LC, and PCM. -Publishing remains opt-in, with one **Use MoQ encoders** choice for video and audio. Keep the existing OBS encoder mode. Internal OBS encoder adapters call moq-video/moq-audio, preserving OBS's A/V handling and the existing encoded MoQ output. The combined choice is enabled only when both adapters are present. Start with H.264, supported HEVC, and Opus; defer AV1/AAC encoding and PCM publishing UI. Keep bitrate separate from **Low latency**, **Balanced** (default), and **Quality** presets. Presets describe supported buffering/compression controls, not an end-to-end delay promise. The line PR must call out the video default changes #4099 made: NVENC P4 to P1, and openh264 medium to low complexity. Known gap: VAAPI reports Low latency whatever was asked, and V4L2 and MediaCodec report unconfirmed; no quest owns measuring and mapping presets for them. Media Foundation is owned by [Windows GPU input](/quest/m5/obs-windows.md). +Publishing remains opt-in, with one **Use MoQ encoders** choice for video and audio. Keep the existing OBS encoder mode. Internal OBS encoder adapters call moq-video/moq-audio, preserving OBS's A/V handling and the existing encoded MoQ output. The combined choice is enabled only when both adapters are present. Start with H.264, supported HEVC, and Opus; defer AV1/AAC encoding and PCM publishing UI. Keep bitrate separate from **Low latency**, **Balanced** (default), and **Quality** presets. Presets describe supported buffering/compression controls, not an end-to-end delay promise. The line PR must call out the video default changes #4099 made: NVENC P4 to P1, and openh264 medium to low complexity. Known gap: VAAPI reports Low latency whatever was asked, and V4L2 and MediaCodec report unconfirmed; no quest owns measuring and mapping presets for them. Media Foundation has no owner either. The quests separate portable decoding, audio, and publishing so each can land and be validated independently. moq-ffi's decoded frames own their surface and convert to CPU pixels only on request (#4094); a surface decode exposes the platform surface as a borrowed view, which each platform GPU quest extends to its own surface type. @@ -27,11 +27,5 @@ Decided in the 2026-09-30 audit: the Windows and Linux GPU decode paths and the ## Related -- [Linux GPU decode](/quest/m5/obs-decode-linux.md) - present hardware-decoded frames without CPU readback; needs physical-hardware proof -- [Windows GPU decode](/quest/m5/obs-decode-windows.md) - present D3D11 decoded textures without CPU readback; needs physical-hardware proof -- [macOS GPU input](/quest/m5/obs-macos.md) - feed compositor frames to VideoToolbox without a CPU round trip; needs physical-hardware proof -- [Windows GPU input](/quest/m5/obs-windows.md) - feed D3D11 compositor frames to the encoder without CPU staging; needs physical-hardware proof - [Video hardware validation](/quest/m5/video-hardware.md) - physical hardware evidence is required for each claimed GPU path - [AudioToolbox decode](/quest/m3/audio-decode-audiotoolbox.md) - HE-AAC and multichannel AAC reach the OBS source on macOS through moq-ffi -- [AudioToolbox encode](/quest/m5/audio-encode-audiotoolbox.md) - native AAC encode reaches the OBS encoder adapter on macOS through moq-ffi -- [Linux GPU input](/quest/m5/obs-linux-gpu.md) - allocation-export feasibility and its dependent implementation are deferred diff --git a/quest/m3/obs-moq-video/linux-bundle.md b/quest/m3/obs-moq-video/linux-bundle.md index a8865433178..1043425d55a 100644 --- a/quest/m3/obs-moq-video/linux-bundle.md +++ b/quest/m3/obs-moq-video/linux-bundle.md @@ -15,7 +15,3 @@ Every `obs-moq-v*` release attaches a Linux x86_64 tarball that loads into a sto ## Required - [Video source replacement](/quest/m3/obs-moq-video/source.md) - removes the FFmpeg video linkage that makes a Linux binary non-portable - -## Related - -- [Linux decoded frames](/quest/m5/obs-decode-linux.md) - native surface delivery lands on top of the portable CPU path this bundle ships diff --git a/quest/m3/obs-moq-video/vpx-obs.md b/quest/m3/obs-moq-video/vpx-obs.md index c241306b890..b17000d7fab 100644 --- a/quest/m3/obs-moq-video/vpx-obs.md +++ b/quest/m3/obs-moq-video/vpx-obs.md @@ -13,7 +13,3 @@ The OBS MoQ source plays VP8 and VP9 (8-bit 4:2:0) on every platform it ships fo ## Required - [Video source replacement](/quest/m3/obs-moq-video/source.md) - the source decodes through moq-video first - -## Related - -- [Codec coverage](/quest/m5/video-codec-coverage.md) - hardware VP8/VP9 decode belongs to that review diff --git a/quest/m3/qos/README.md b/quest/m3/qos/README.md index eb5c00243dc..950e89feae1 100644 --- a/quest/m3/qos/README.md +++ b/quest/m3/qos/README.md @@ -65,5 +65,3 @@ on `main`. - [Media stats](/quest/m3/stats/README.md) - publishers and viewers report their own media, transport, and playback health, the media half of a verdict -- [Loss delay](/quest/m5/cut-through/loss-delay.md) - an ingress counter of - bytes a loss held back by at least one RTT, on the same rows diff --git a/quest/m3/qos/lag-histogram.md b/quest/m3/qos/lag-histogram.md index 497e22ab29f..287f23da277 100644 --- a/quest/m3/qos/lag-histogram.md +++ b/quest/m3/qos/lag-histogram.md @@ -35,8 +35,8 @@ Decided 2026-10-26 (maintainer, on #6791), each with its reason: acknowledged frame end through [poll_acked](/quest/m3/quic-ack-hook.md), so the sampler reads a frontier at most one frame stale. `dropped` counts only the frames written after the newest acknowledged one. This folds in the - frontier half of the former starvation-frames quest; the delivery-delay - histogram stays in [its own quest](/quest/m5/delivery-delay.md). Its sketch, + frontier half of the former starvation-frames quest; a delivery-delay + histogram is not planned. Its sketch, to adjust as the code dictates: the group stream's writer counts the bytes it writes, each frame end records its offset and timestamp, and one waiter per stream polls the oldest pending offset, interleaved with later writes so diff --git a/quest/m3/quic-ack-hook.md b/quest/m3/quic-ack-hook.md index 5fa7953582e..fcd916b2315 100644 --- a/quest/m3/quic-ack-hook.md +++ b/quest/m3/quic-ack-hook.md @@ -109,5 +109,5 @@ offset order, reset by sender, STOP_SENDING by the receiver, and session close. Decided in the 2026-09-30 audit: moved to m2 with its consumers, the -[viewer lag histogram](/quest/m3/qos/lag-histogram.md) and the -[delivery-delay histogram](/quest/m5/delivery-delay.md). +[viewer lag histogram](/quest/m3/qos/lag-histogram.md) and a +delivery-delay histogram, whose plan was deleted on 2026-11-09. diff --git a/quest/m3/quic-realtime/README.md b/quest/m3/quic-realtime/README.md index a73e0b53a84..4ff3836d349 100644 --- a/quest/m3/quic-realtime/README.md +++ b/quest/m3/quic-realtime/README.md @@ -182,7 +182,4 @@ owns that feedback. ## Related -- [Per-stream and per-datagram deadlines](/quest/m5/quic-deadline.md) - also consumes the forward-delay estimate -- [BBR media study](/quest/m5/quic-bbr-study.md) - BBR3 behavior under media, the baseline here -- [Measure ECN on the backbone](/quest/m5/quic-ecn-measure.md) - decides whether SCReAMv2's L4S path is worth porting - [QUIC on the sim](/quest/m4/quic-sim.md) - deterministic successor to the moq-shaper harness once it lands diff --git a/quest/m3/quic-realtime/moqsink-feedback.md b/quest/m3/quic-realtime/moqsink-feedback.md index eaeb41579c0..5c22962ff38 100644 --- a/quest/m3/quic-realtime/moqsink-feedback.md +++ b/quest/m3/quic-realtime/moqsink-feedback.md @@ -30,4 +30,3 @@ Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and r ## Related - [Realtime uplink congestion control](/quest/m3/quic-realtime/README.md) - the controller whose rate this follows -- [Opus follows its grant](/quest/m5/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - the same feedback for moq-audio diff --git a/quest/m3/stats/README.md b/quest/m3/stats/README.md index 7bd6cbe9bf4..fc5d2f14893 100644 --- a/quest/m3/stats/README.md +++ b/quest/m3/stats/README.md @@ -108,8 +108,8 @@ kind. `drafts/draft-lcurley-moq-hang.md` specs the wire. Decided in the 2026-09-30 audit: a Rust encoder adapting its bitrate to viewer -feedback moved to [encoder feedback](/quest/m5/stats-encoder-feedback.md) (m5), -along with its open questions. This line publishes, reads, and classifies the +feedback moved to m5 and was deleted there on 2026-11-09 for want of a +consumer. This line publishes, reads, and classifies the reports; no encoder acts on them here. Decided 2026-10-05 (moq.pro audit): the client health model and preflight @@ -131,7 +131,3 @@ connection view and the dashboard flow. - [QoS](/quest/m3/qos/README.md) - the relay's delivery counters; the combined per-broadcast verdict reading both lives downstream -- [Encoder feedback](/quest/m5/stats-encoder-feedback.md) - a Rust encoder - adapts its bitrate to what its viewers report -- [Latency ledger](/quest/m5/latency-ledger.md) - adds the viewer's latency - stages to the same feedback snapshot diff --git a/quest/m3/stats/rust.md b/quest/m3/stats/rust.md index c57054f68b5..a891af47084 100644 --- a/quest/m3/stats/rust.md +++ b/quest/m3/stats/rust.md @@ -56,8 +56,8 @@ `--echo` when it adds one: they would publish rendition IDs and per-track counters in plaintext beside it. - Decided 2026-10-22 (maintainer): the publisher's solicit option moved here - from [encoder feedback](/quest/m5/stats-encoder-feedback.md), which keeps - only the adaptation loop and reuses `--echo-path`. + from the encoder feedback quest, since deleted, which kept only the + adaptation loop. - `export --echo` counts no drops in `late`: `Received::report` (`rs/moq-mux/src/stats.rs`) fills only frames, bytes, and arrival while the TS release section holds the drops (from @@ -68,4 +68,3 @@ Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and r ## Related - [Encrypted native CLI](/quest/m5/e2ee/cli.md) - refuses stats and feedback on an encrypted broadcast -- [Encoder feedback](/quest/m5/stats-encoder-feedback.md) - the adaptation loop that reads what `--echo-path` solicits diff --git a/quest/m3/vaapi-vulkan-import.md b/quest/m3/vaapi-vulkan-import.md index 848d8529dd8..f8a49539447 100644 --- a/quest/m3/vaapi-vulkan-import.md +++ b/quest/m3/vaapi-vulkan-import.md @@ -71,5 +71,4 @@ Public API: none; the surface landed in #4975. Wire: none. - [Vulkan Video encode on AMD](/quest/m3/vulkan-encode.md) - the AMD half of the same proof - [GPU capacity and health](/quest/m3/gpu-health.md) - reports per device keyed by the same render node `dev_t` -- [Linux OBS GPU input](/quest/m5/obs-linux-gpu.md) - a DMA-BUF producer that needs the same explicit sync - [Video hardware validation](/quest/m5/video-hardware.md) - VA-API so far ran only on Meteor Lake diff --git a/quest/m3/video-quality/README.md b/quest/m3/video-quality/README.md index 98498eedc9a..ff4f00bad74 100644 --- a/quest/m3/video-quality/README.md +++ b/quest/m3/video-quality/README.md @@ -12,8 +12,7 @@ Today nothing measures encoded quality: the only check is a manual PSNR/SSIM recipe in `rs/moq-video/examples/encode-presets.rs`. moq-boy's encoding looks bad, and nobody knows how each backend or GPU compares on the same input. -Non-goals: per-viewer adaptation and live bitrate control, which belong to the -[ladder](/quest/m5/ladder/README.md); browser playback quality, which belongs to +Non-goals: per-viewer adaptation and live bitrate control, which nothing plans; browser playback quality, which belongs to `just test media`. ## Plan diff --git a/quest/m3/video-quality/on-demand.md b/quest/m3/video-quality/on-demand.md index d26951fa2fd..6e8c9aeb4c0 100644 --- a/quest/m3/video-quality/on-demand.md +++ b/quest/m3/video-quality/on-demand.md @@ -46,7 +46,3 @@ Public API: none expected. Wire: none. ## Required - [Harness](/quest/m3/video-quality/harness.md) - the scorer and pop metric - -## Related - -- [Ladder fetch](/quest/m5/ladder/fetch.md) - later makes fetch encode at the controller's target; keep the same fetch encoder ownership diff --git a/quest/m3/webcodecs-priming.md b/quest/m3/webcodecs-priming.md index 3c74ec04175..14984f4ab93 100644 --- a/quest/m3/webcodecs-priming.md +++ b/quest/m3/webcodecs-priming.md @@ -68,5 +68,4 @@ Decided 2026-11-04 (maintainer, /quest-plan): ## Related - [moq-audio in the browser](/quest/m5/audio-web.md) - its WebCodecs backend's `delay()` reuses this measurement -- [AudioToolbox encode](/quest/m5/audio-encode-audiotoolbox.md) - the native AAC encoder's delay, folded the same way - [Chromium's Opus encoder stamps chunks from their input](/quest/m4/chromium-opus-timestamps.md) - another WebCodecs `AudioEncoder` timestamp bug diff --git a/quest/m4/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md b/quest/m4/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md index e880bbd4ebd..dced1559fbc 100644 --- a/quest/m4/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md +++ b/quest/m4/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md @@ -33,7 +33,3 @@ both of which need a CPU conversion or decode anyway, so exporting the buffer saves no copy. Revisit only if NV12 camera capture lands. Refs #2481, #1837. - -## Related - -- [Capture multi-plane PipeWire cameras](/quest/m5/pipewire-camera-planes.md) - separate memory blocks from a camera, the capture offer rather than this import diff --git a/quest/m4/README.md b/quest/m4/README.md index f0244443fff..652ee69fec6 100644 --- a/quest/m4/README.md +++ b/quest/m4/README.md @@ -20,7 +20,6 @@ deleted. - [Wire fuzz coverage](/quest/m4/wire-fuzz-coverage.md) - the cmsg walks in moq-sock and moq-uring have invariant fuzz targets, and the unsafe peer input reaches runs under Miri - [VA-API renderer tests](/quest/m4/vaapi-render-tests.md) - the VA-API renderer, decode, and transcode tests run in `just rs gpu` on AMD and Intel and fail instead of skipping, and hosted CI reports them ignored - [One Ruff pin and Swift formatting on aarch64-linux](/quest/m4/format-gate-followups.md) - only the dev shell pins Ruff, and aarch64-linux checks Swift formatting once nixpkgs builds `swiftc` there -- [Weekly mutation testing on critical modules](/quest/m4/mutants.md) - cargo-mutants runs weekly on moq-auth and moq-net's permission, resume, and expiry code - [P2P](/quest/m4/p2p/README.md) - application-selected peer sessions use shared priorities, routing, and same-epoch handover - [Challenge proof for certificate credentials](/quest/m4/cert-challenge.md) - a relay can require a signed nonce, so a certificate credential replayed within its time window admits nothing - [Benchmark sources](/quest/m4/bench-sources.md) - every measuring nightly benchmark feeds the regression table, and none is a smoke run diff --git a/quest/m4/announce-interest-memory.md b/quest/m4/announce-interest-memory.md index c4830f52ba6..c361b848092 100644 --- a/quest/m4/announce-interest-memory.md +++ b/quest/m4/announce-interest-memory.md @@ -35,5 +35,4 @@ Public API: none. Wire: none. ## Related -- [Announced snapshots](/quest/m5/performance-survey/announced-snapshots.md) - the HTTP listing's copy of the same table - [Cluster routing](/quest/m2/cluster-routing/README.md) - reshapes the route table this walks diff --git a/quest/m4/audio-visqol.md b/quest/m4/audio-visqol.md index 92a734fb869..141fad45f5b 100644 --- a/quest/m4/audio-visqol.md +++ b/quest/m4/audio-visqol.md @@ -44,5 +44,3 @@ Public API: none. Wire: none. ## Related - [Audio outlives video](/quest/m4/audio-bufferbloat-av.md) - the other extension of the same harness -- [Opus backends](/quest/m5/audio-opus-backend.md) - a quality score is the evidence an implementation comparison needs -- [Opus bandwidth grant](/quest/m5/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - bitrate changes this score should track diff --git a/quest/m4/cache-fairness.md b/quest/m4/cache-fairness.md index a3879079e64..ada1561601a 100644 --- a/quest/m4/cache-fairness.md +++ b/quest/m4/cache-fairness.md @@ -55,4 +55,3 @@ Wire: none. ## Related - [Broadcast fairness](/quest/m5/broadcast-fairness.md) - the same tenant fair share on cluster links -- [Receive pool](/quest/m5/receive-pool.md) - one per-worker budget covering receive credit and the cache diff --git a/quest/m4/mutants.md b/quest/m4/mutants.md deleted file mode 100644 index e63200f9267..00000000000 --- a/quest/m4/mutants.md +++ /dev/null @@ -1,31 +0,0 @@ -# [S] Weekly mutation testing on critical modules - -## Goal - -A weekly scheduled job runs cargo-mutants on `moq-auth` and on `moq-net`'s -path permission, resume, and expiry code, and reports surviving mutants, -so assertions that never notice a behavior change get found. - -## Plan - -From the 2026-10-27 coverage audit. The failure drills already use -mutation-style negative controls; nothing does it systematically. - -Decided 2026-10-27 (maintainer): - -- Weekly, not nightly: the scoped code changes slowly and each mutant - rebuilds and reruns its crate's tests. -- Scope to the modules above with cargo-mutants' file filters, and bound each - mutant with its timeout so one hung mutant cannot eat the job. -- Survivors go to the job summary, and a run with survivors alerts through - `alert.yml`. -- No mutation-score gate. The PR that adds the job fixes or annotates the - first run's survivors: add a test where one is worth killing, or exclude the - mutant in cargo-mutants' config with the reason (an equivalent mutant, or - logging only). - -`mutants.yml` runs the job: `just rs mutants` over `.cargo/mutants.toml`'s -scope, in 24 shards. What remains is fixing or annotating the first full run's -survivors, about 1,800 mutants; a short local sample of 14 saw none. - -Public API: none. Wire: none. diff --git a/quest/m4/p2p/README.md b/quest/m4/p2p/README.md index 0f701d5c625..367f179bc19 100644 --- a/quest/m4/p2p/README.md +++ b/quest/m4/p2p/README.md @@ -60,9 +60,8 @@ The CDN session and discovery remain connected. Release unused CDN media demand after a same-epoch handoff, except bounded overlap while validating a replacement. If a peer dies, drains, or was never reachable, the shared origin selects the best remaining eligible route. This is ordinary transport -fallback; nothing TURN-shaped is built. Still-open delivery stalls -are handled by [Route health](/quest/m5/route-health/README.md), only with a -matching explicit epoch. Epochless source changes restart instead of resume. +fallback; nothing TURN-shaped is built. Detecting a delivery stall on a +still-open route is out of scope. Epochless source changes restart instead of resume. The relay is the nearest STUN server a client can name, but this line takes ICE servers from the application and works with any. Decided 2026-10-08: the @@ -175,5 +174,4 @@ Extractor declaration checks, which analyze only published packages since ## Related -- [Route health](/quest/m5/route-health/README.md) - epoch-only active/passive delivery recovery on selected connections - [E2EE](/quest/m5/e2ee/README.md) - what a peer would need if the token scope stopped being the trust boundary diff --git a/quest/m4/p2p/cost-scopes.md b/quest/m4/p2p/cost-scopes.md index e1a99ae2e45..24355985502 100644 --- a/quest/m4/p2p/cost-scopes.md +++ b/quest/m4/p2p/cost-scopes.md @@ -51,7 +51,3 @@ in Peers and native configuration. Wire: none beyond shared routing and existing - [Routes and announces](/quest/m2/cluster-routing/routes/README.md) - route identities and route ordering - [Signaling and policy](/quest/m4/p2p/signal.md) - explicit application peer selection - [moq-cli joins](/quest/m4/p2p/cli.md) - matching native controls - -## Related - -- [Route health](/quest/m5/route-health/README.md) - automatic epoch-only stalled-delivery recovery diff --git a/quest/m4/p2p/harness.md b/quest/m4/p2p/harness.md index 9bcd341faff..008d8d6e661 100644 --- a/quest/m4/p2p/harness.md +++ b/quest/m4/p2p/harness.md @@ -33,8 +33,7 @@ full-mesh selection, roster churn, pending negotiations and cancellation. Report connection counts, signaling bytes, wakes, CPU and retained state; per-peer `iceServers` alone do not bound pairing. Verify the CDN control session survives peer handover while unused CDN payload demand stops. -Real CDN/P2P route-health cases extend this harness from the m5 -[Route health](/quest/m5/route-health/README.md) line, not here. +Route-health cases are out of scope. Metrics: sustained throughput ceiling, per-frame latency p50 and p99 from the timestamp `moq-bench` stamps into each keyframe (same host, so one clock), diff --git a/quest/m4/perf/quic-lock-contention.md b/quest/m4/perf/quic-lock-contention.md index 140b6f1b39b..1f8ee755610 100644 --- a/quest/m4/perf/quic-lock-contention.md +++ b/quest/m4/perf/quic-lock-contention.md @@ -64,5 +64,4 @@ staging queue and batch dispatch should need none. ## Related -- [Relay egress profile](/quest/m5/quic-egress-profile.md) - the transmit side of the same path - [Relay allocations](/quest/m4/perf/relay-allocs.md) - the allocation profile of the same workload diff --git a/quest/m4/perf/shard-default.md b/quest/m4/perf/shard-default.md index b2bcc71edd0..51e0ef0d6f5 100644 --- a/quest/m4/perf/shard-default.md +++ b/quest/m4/perf/shard-default.md @@ -64,4 +64,3 @@ Update `doc/bin/relay/` for the default change. ## Related - [kio channel contention](/quest/m4/kio-channel-contention/README.md) - its per-thread spikes run on the workers -- [Performance survey](/quest/m5/performance-survey/README.md) - paired benchmark evidence and memory/settings controls diff --git a/quest/m4/quic-sim.md b/quest/m4/quic-sim.md index ca3f468c9a7..8e82b7c46bb 100644 --- a/quest/m4/quic-sim.md +++ b/quest/m4/quic-sim.md @@ -38,7 +38,3 @@ Keep random loss for recovery correctness. Any acceptance or performance consumer uses a rate below its media bitrate behind a deep but finite queue, and checks that the queue overflowed. A stalled sender that never filled the queue is not evidence about congestion loss. - -## Related - -- [Per-stream and per-datagram deadlines](/quest/m5/quic-deadline.md) - a consumer diff --git a/quest/m4/resume-redesign.md b/quest/m4/resume-redesign.md index aca9318536d..da8e089f847 100644 --- a/quest/m4/resume-redesign.md +++ b/quest/m4/resume-redesign.md @@ -91,7 +91,3 @@ serving copy's upstream closed, followed by a read. ## Required - [Release cut](/quest/m3/release/cut.md) - wait for the release in flight to ship - -## Related - -- [Recover reads its budget without a sync](/quest/m5/recover-budget.md) - a per-frame cost this deletes diff --git a/quest/m4/route-wakes.md b/quest/m4/route-wakes.md index 98e8a571462..24799436f68 100644 --- a/quest/m4/route-wakes.md +++ b/quest/m4/route-wakes.md @@ -83,4 +83,3 @@ Public API: none. Wire: none. ## Related - [Routes and announces](/quest/m2/cluster-routing/routes/README.md) - the identity and selection views the index serves -- [Front parking](/quest/m5/origin-front-parks.md) - replaces the `routed_broadcast` watch loop this wakes diff --git a/quest/m5/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md b/quest/m5/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md deleted file mode 100644 index ddc97dd085a..00000000000 --- a/quest/m5/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md +++ /dev/null @@ -1,38 +0,0 @@ -# [M] Complete NVIDIA Main10 encoding support - -## Goal - -Implement and verify the remaining 10-bit HEVC encoding work described in -[#2147](https://github.com/moq-dev/moq/issues/2147). NVDEC AV1 decoding and -catalog AV1 types already exist; do not reimplement them. - -## Plan - -Decided in the 2026-09-30 audit: AV1 encoding split out to -[NVENC AV1](/quest/m5/nvenc-av1.md), because it needs an Ada GPU and the only -GPU CI host is an RTX 3070 Ti. Main10 stays here since that host can verify it. - -Decided 2026-10-08: moved to m3. No 10-bit encode pipeline or consumer -exists yet. - -Extend the settled frame and NVENC contracts with Main10 surfaces, profile -selection, and accurate codec metadata. Audit byte pitch, plane layout, CPU -download, and P016 input/output together; a codec enum alone does not establish -10-bit support. Preserve color metadata and refuse unsupported conversions. -Do not imply that OpenH264 can decode HEVC or tonemap HDR. - -Use existing extensible codec enums; no replacement of the 0.1 core API is -planned. Keep the NVIDIA backend optional and loaded at runtime. - -Validate decoded pixels, bit depth, profile, resource lifetime, drain, and -refusal on unsupported devices. Wire fixtures and contract tests into CI, and -run the hardware tests on the [GPU CI](/quest/m3/gpu-ci.md) host. - -Public API: additive capabilities on the extension points settled on main. Wire: existing -codec signaling, with cross-language fixtures for any metadata change. - -## Related - -- [GPU CI](/quest/m3/gpu-ci.md) - nightly NVIDIA hardware tests that would verify Main10 -- [NVENC AV1](/quest/m5/nvenc-av1.md) - the AV1 half of #2147, hardware-gated -- [Codec coverage study](/quest/m5/video-codec-coverage.md) - measure optional software and other native backends separately diff --git a/quest/m5/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md b/quest/m5/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md deleted file mode 100644 index 3abe5a055ec..00000000000 --- a/quest/m5/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md +++ /dev/null @@ -1,50 +0,0 @@ -# [L] hang: SCTE-35 cues a player can act on - -## Goal - -An ad cue carried through MoQ is readable by a browser without knowing MPEG-TS -exists, and a player can raise an event on it. Today `splice_info_section` -bytes ride byte-faithfully on a TS-specific verbatim track that only the TS -exporter understands. Server-side ad insertion is a separate future quest. - -## Plan - -Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no named consumer for timed metadata. - -Use the shared event contract [emsg](/quest/m5/emsg.md) settles. Deliver cues immediately, including when splice_time is in the -future; consumers need advance notification. Metadata group sequences are -independent of media GOPs. - -- A SCTE-35 scheme entry in the shared catalog `events` section names cue - tracks with an optional `rendition` association (the program's rendition, - as [ID3](/quest/m5/id3.md) does), not a top-level - `scte35` section (decided 2026-11-07, maintainer, /quest-plan from the API sweep of open PRs and remaining quests). Video is not required for audio-only programs. -- Preserve complete raw splice_info_section bytes. Carry the event's - presentation time on the broadcast clock; commands without splice_time - use the media clock observed at arrival. Do not delay publication until the - target media group opens or use its sequence as the event identity. -- Preserve source timing and placement needed by TS export separately from - the event's presentation time. The shared contract settles the outer - timestamp and retention behavior for a future cue followed by a current event. -- **Typed decode is a helper, not the wire.** A parser for `splice_insert`, - `time_signal`, and segmentation descriptors (a maintained crate if one is - adequate) lives beside the scheme in Rust and JS, and `js/watch` raises a - cue event from it. Applications that want the rest parse the bytes. -- **The TS lanes stay.** The importer keeps the verbatim `mpegts` track for - contribution fidelity and additionally emits the sidecar; the exporter must - not double-emit: an import-to-export test with the sidecar present asserts - each source section is emitted exactly once, including audio-only programs. - -Wire and catalog schema: a new scheme in the optional `events` section, additive, so it lands on -`main`, with `drafts/draft-lcurley-moq-hang.md` updated in the same PR as the -schema: the draft is the normative spec, and a section Rust and JS emit must -be in it the day it ships. Cross-package sync: `rs/hang`, `js/hang`, -`rs/moq-mux`, `doc/concept`. - -## Required - -- [fMP4 emsg](/quest/m5/emsg.md) - settles the shared timed-metadata contract this builds on, which needs maintainer agreement first - -## Related - -- [ID3 in the events section](/quest/m5/id3.md) - the other typed timed-metadata scheme, same rule diff --git a/quest/m5/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md b/quest/m5/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md deleted file mode 100644 index ebaf4acbbba..00000000000 --- a/quest/m5/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md +++ /dev/null @@ -1,82 +0,0 @@ -# [M] moq-audio's Opus encoder follows its bandwidth grant - -## Goal - -An Opus track published through `moq_audio::encode::Producer` retunes to its -share of the connection's estimate: a grant below the configured bitrate -lowers the encoder at once, room coming back raises it gradually, and a link -too small for the configured audio rate sheds audio bits instead of stalling. -The reservation's ceiling stays the configured bitrate. A grant below the -codec floor holds the encoder at the floor, and the transport sheds what the -link cannot carry; the rendition stays enabled. PCM keeps reserve-only -usage: it claims its fixed rate and never reads the grant. - -The rate policy has one home shared by every sender, so audio and video back -off the same way. - -## Plan - -Today audio reserves but never follows. The capture driver takes the -reservation once the layout reveals the encoded rate -(`rs/moq-audio/src/encode/capture.rs`) and nothing reads its -grant; `Options::bandwidth` documents that -(`rs/moq-audio/src/encode/producer.rs`). Video already follows through -`moq_mux::rate::Control` (`rs/moq-video/src/encode/producer.rs`). - -- Consume `moq_mux::rate`, keeping one shared policy; this quest adds audio - adaptation without growing a second implementation. -- The follow loop lives in `moq_audio::encode::Producer`, not the capture - driver: `Producer::new` already takes `Options` with the - allocator, so it reserves the configured bitrate against - `self.demand()`, holds a `Reservation::consumer()` plus a - `rate::Control`, and feeds each grant to `Encoder::set_bitrate` - (`rs/moq-audio/src/encode/encoder.rs`). Capture and moq-ffi - (`rs/moq-ffi/src/audio.rs`) build the Producer, so both adapt without - their own loop; the capture driver's `_reservation` goes away. Public entry - points for a manual ceiling stay `Producer::set_bitrate` - and `Encoder::set_bitrate`. -- The Opus encoder sits behind the encode backend seam: the rate setter and - its floor live in `rs/moq-audio/src/encode/backend/libopus.rs`, and - `Encoder::set_bitrate` dispatches through the backend. -- Floor: the libopus backend's `set_bitrate` refuses anything outside - `opus::bitrate_floor(codec_rate, frame_size).max(500)` to - `300_000 * channels` (`backend/libopus.rs`, `rs/moq-audio/src/opus.rs`). `Policy::min` defaults to a tenth of - the ceiling (`rs/moq-mux/src/rate.rs`); for Opus it is the codec floor. A - grant below it holds the encoder at the floor; the encoder never errors and - the rendition is never disabled, so `moq_mux::rate::Control`'s rung disable - rule does not apply to audio. The reservation's ceiling is the configured - bitrate; only the policy target moves. -- PCM: `pcm::bitrate(sample_rate, channels)` is `pub(crate)` - (`rs/moq-audio/src/pcm.rs`), `Settings::bitrate` is refused for it - and so is `set_bitrate` (`encoder.rs`, `backend/pcm.rs`). A PCM - Producer reserves its fixed rate and runs no policy. That is the same - reserve-only usage passthrough imports use, so nothing new is added for it. -- Priority is unchanged: `PRIORITY` puts audio at 80 and video at 60 - (`rs/hang/src/catalog/priority.rs`), so the allocator fills audio's - reservation before video sees a bit and audio is squeezed only once the link - cannot carry audio alone. Worth doing for that tail, not worth blocking on. - -Decided 2026-10-08: moved to m2, since that tail is the only gain. - -Decided 2026-11-07 (maintainer, /quest-plan of the follow-ups from the -/quest-complete run, after [moq-dev/moq#8123](https://github.com/moq-dev/moq/pull/8123)): -a grant below the Opus floor holds the encoder at the floor and never -disables the rendition. This replaces the 2026-10-04 disable-and-re-enable -rule. Recovery alone would work: an unwatched reservation still reads the slice -it would get back (`an_idle_track_claims_nothing` in -`rs/moq-net/src/model/bandwidth.rs`). The cost is the catalog flip. Players -now deselect a disabled rendition, so each flip makes every listener drop the -track and subscribe again, losing what it was playing. That is the -`enabled`-toggle cost [moq-dev/moq#7942](https://github.com/moq-dev/moq/pull/7942) -removed from push-to-talk. - -- ✅ Hold the floor, no disable -- Keep the disable; the Producer keeps reserving at the floor while disabled -- Keep the disable; players keep a passive subscription to a grant-disabled rendition -- Drop the follow-up - -Tests: retain the shared `Control` tests; an Opus Producer whose -grant drops below its configured bitrate reports the lower `bitrate()` after -one policy step, holds it on a `None` grant, and ramps back when the grant -returns; a grant below the Opus floor holds the encoder at the floor with the rendition -still enabled; a PCM Producer ignores every grant. diff --git a/quest/m5/README.md b/quest/m5/README.md index 4fbdb4b505c..a2a5f6056d5 100644 --- a/quest/m5/README.md +++ b/quest/m5/README.md @@ -26,6 +26,14 @@ bucket when milestones shift after a cut. Rate-grant work targets the next unpublished lite version after finalized lite-07; bitrate enforcement is not part of the next release. +Pruned 2026-11-09 (maintainer, /quest-plan from the deletion audit): 80 +quests with no named consumer, no outside gate, and no m0 to m4 quest +requiring them were deleted; git history keeps them. Consumers were checked +in this repository and in moq.pro's plans, which kept the io_uring tuning +quests (fleet relays on io_uring workers), broadcast fairness, and the +transcode and NVENC quests (production transcoding). Re-plan one when a +consumer asks. + ## Required - [Mesh over ICE](/quest/m5/mesh-ice.md) - mesh nodes on different networks connect directly through the P2P line's ICE pairs, once a mesh user needs it @@ -34,29 +42,15 @@ lite-07; bitrate enforcement is not part of the next release. - [Video hardware validation](/quest/m5/video-hardware.md) - run the encode, capture, and zero-copy paths that were never run on real machines, including PipeWire on KDE, the camera portal, and a Pi - [An Ada NVIDIA GPU is available](/quest/m5/ada-gpu.md) - the hardware AV1 NVENC is verified on - [NVENC AV1](/quest/m5/nvenc-av1.md) - AV1 encode through NVENC, once an Ada-generation GPU is available -- [#2147](/quest/m5/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md) - NVIDIA Main10 encode, once a 10-bit source exists in the pipeline - [NVDEC and NVENC share CUDA arrays](/quest/m5/nvenc-cuda-arrays.md) - SDK 13.1 application-owned CUDA arrays drop the per-frame device copy, on driver 610+ - [Embedded video](/quest/m5/video-embedded.md) - verify a Pi 4/5 presents through the existing Vulkan and CPU paths, adding EGL import only if that fails -- [Multi-plane PipeWire cameras](/quest/m5/pipewire-camera-planes.md) - I420 and NV12 cameras that deliver one memory block per plane capture -- [Video codec coverage](/quest/m5/video-codec-coverage.md) - prioritize remaining native AV1 and portable decoder gaps once a consumer asks - [A physical-NIC peer for the zero-copy sweep](/quest/m5/zero-copy-peer.md) - the rig the zero-copy sweep runs on - [#3201: moq-uring: use SENDMSG_ZC for large UDP GSO trains](/quest/m5/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md) - complete the prerequisite issue first - [#3204](/quest/m5/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md) - moq-uring: register TX-pool buffers for zero-copy sends - [Cluster dials on the ring](/quest/m5/uring-cluster-dial.md) - measure whether an io_uring relay's outbound cluster links belong on its workers - [#3202](/quest/m5/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md) - moq-uring: fixed-file slots for worker UDP sockets, if its own benchmark measures a win -- [L4S on the backbone](/quest/m5/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/m5/quic-careful-resume.md) - a Rust redial starts at the previous connection's rate -- [Cut-through](/quest/m5/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 - [Byte streams in moq-ffi](/quest/m5/ffi-stream.md) - Swift and Kotlin dial and accept byte streams, for moq.pro's T3 Code mobile client - [E2EE in moq-ffi](/quest/m5/ffi-e2ee.md) - Swift and Kotlin publish and consume protected broadcasts, for the same client -- [Unreal prototype](/quest/m5/unreal.md) - a UE5 module on the C++ package with exceptions disabled, rendering a subscribed broadcast to a texture -- [vcpkg registry](/quest/m5/cpp-vcpkg.md) - a registry we own serves the prebuilt package to `vcpkg` manifests, once a consumer asks -- [Conan remote](/quest/m5/cpp-conan.md) - a remote we own serves the same tarball to `conan install` -- [Linux OBS GPU input](/quest/m5/obs-linux-gpu.md) - publish OBS compositor frames without CPU readback on a validated Linux graphics/encoder combination -- [Routing cost domains](/quest/m5/routing-cost-domains.md) - design operator boundaries and policy without adding incomparable costs -- [Request tokens beyond Rust](/quest/m5/request-token-surfaces.md) - a JS, moq-ffi, or moq-cli request-token API, built only for the surface a consumer names -- [Token on FETCH](/quest/m5/auth-token-fetch.md) - our TRACK_STATUS and FETCH carry the request token, once a consumer asks -- [moq-transport cluster peers](/quest/m5/ietf-cluster-peers.md) - the cluster draft carries the route layer, so moq-transport relays peer again, once a moq-transport relay operator asks - [The moq.pro mesh runs lite-07](/quest/m5/lite07-mesh.md) - the deployment that makes the exemption dead code - [Drop the hidden cluster exemption](/quest/m5/hidden-exemption.md) - relays stop forcing hidden broadcasts on cluster peers once every peer opts in on the wire - [Robot teleoperation conventions](/quest/m5/teleop-robot.md) - documented track shapes for video down and control up, implemented by the MAVLink gateway, once a robotics consumer appears @@ -67,88 +61,31 @@ lite-07; bitrate enforcement is not part of the next release. - [SITL proof and browser ground station](/quest/m5/teleop-proof.md) - ArduPilot SITL and a synthetic camera flown from a browser ground station, reproducible in five minutes -- [Ladder](/quest/m5/ladder/README.md) - a transcode ladder adapts to the uplink it publishes over, instead of encoding every live rung at its ceiling -- [fMP4 emsg](/quest/m5/emsg.md) - settles the shared framing and missing-data semantics before this section adopts them -- [ID3 in the events section](/quest/m5/id3.md) - timed ID3 as a container-neutral scheme in the catalog's `events` section -- [FLV script tags](/quest/m5/flv-script.md) - onMetaData and AMF data messages survive RTMP and FLV import -- [Half and quarter rate AC-3](/quest/m5/ac3-low-rate.md) - bsid 9 and 10 AC-3 parse through TS and FLV instead of being refused -- [MSF feedback tracks](/quest/m5/msf-publish-tracks.md) - `--report` and `--echo` work under `--catalog-format msf` through `publishTracks`, once a consumer asks -- [MSFTS convergence](/quest/m5/msfts-convergence.md) - the demultiplexed TS lane converges on MSFTS where they differ, once an MSFTS implementer engages -- [#2279](/quest/m5/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md) - hang: SCTE-35 cues arrive immediately on an independent metadata track, optionally associated with a rendition -- [CEA-608/708](/quest/m5/captions-cea.md) - captions carried inside video SEI become a real text rendition at import -- [WebXR playback](/quest/m5/watch-webxr.md) - `` renders equirectangular and stereo renditions through WebXR layers on a headset -- [Paced replay](/quest/m5/archive-paced-replay.md) - an archive consumer pushes stored groups to live subscribers on one shared clock, so any live player plays it -- [Encoder feedback](/quest/m5/stats-encoder-feedback.md) - a Rust encoder - reads its viewers' feedback and adapts its bitrate - [Interop runner withdraws before disconnecting](/quest/m5/interop-runner-approval.md) - condition: a released moq-tokio and @moq/net carry close() withdrawals; then the runner's moq.dev clients switch to close() - [Safari ships the WebKit 319818 fix](/quest/m5/webkit-319818.md) - the Safari release the gate admits - [Safari WebTransport](/quest/m5/safari-webtransport.md) - WebKit browsers return to WebTransport once WebKit 319818 ships fixed - [moq-video in the browser](/quest/m5/video-web.md) - getUserMedia, getDisplayMedia, WebCodecs, and VideoFrame import into wgpu, for moq-dev/studio's web studio - [moq-audio in the browser](/quest/m5/audio-web.md) - AudioWorklet capture and playback and WebCodecs Opus and AAC, for the web studio's audio -- [moq-audio filter chain](/quest/m5/audio-filters.md) - per-source suppression, gate, compressor, limiter, ducking, and plugins, which moq-dev/studio configures - [Mesh keys](/quest/m5/mesh-keys.md) - parked: encrypted and HMAC-authenticated mesh broadcasts through a wrapped `.keys` track - [rust2-ts reaches moq-net's model](/quest/m5/rs2ts-model-ready.md) - rust2's translator is ready to translate the model - [Keep moq-net's model in rust2-ts's subset](/quest/m5/rs2ts-model-subset.md) - safe twins for the model's internal `unsafe`, `dyn Expiry` as an enum, once rust2-ts reaches the model - [Wait for a stable bun lint](/quest/m5/bun-lint-release.md) - condition: `bun lint` ships in a stable Bun that nixpkgs carries -- [Rust and JS end a lite-05 track the same way after an inclusive SUBSCRIBE_END](/quest/m5/lite05-subscribe-end.md) - after a legacy inclusive SUBSCRIBE_END, Rust and JS both end the track instead of Rust sending a FIN and JS only releasing -- [Byte-at-a-time MKV input imports as fast as chunked input](/quest/m5/mkv-input-coalesce.md) - the MKV importer fed one byte at a time is no slower than before moq-dev/moq#7234 - [A transcode ladder probes an unseen source shape without stalling its other rungs](/quest/m5/transcode-parallel-open.md) - a source changing to an unseen size opens the new encoders without stalling the ladder's other rungs - [Relay ACME on instant-acme](/quest/m5/relay-acme.md) - moq-relay's ACME returns on instant-acme and rind, once a user needs it -- [Announce credit](/quest/m5/announce-credit.md) - a subscriber bounds an Announce Stream's routes with credit at the wire, so a path flood never closes a session -- [A C origin can discover eagerly, like a relay](/quest/m5/c-origin-relay.md) - the C API puts an origin in relay mode, so forwarding a client session's routes needs no local announce watcher - [Native compression flush](/quest/m5/native-compression-flush.md) - report the per-frame nonfinal flush requirement in existing browser discussions - [Native synchronous codecs](/quest/m5/native-compression-sync.md) - report the stateful small-frame synchronous API requirement - [Native browser codecs](/quest/m5/native-compression-adopt.md) - adopt native operations when timing, frame and resource contracts hold -- [AudioToolbox encode](/quest/m5/audio-encode-audiotoolbox.md) - macOS and iOS encode AAC-LC - [Vendor-free CARLA bridge](/quest/m5/carla-bridge.md) - the CARLA demo's GPU bridge lets moq-video pick the encoder, and its stand-in test runs on AMD as well as NVIDIA -- [Performance survey follow-ups](/quest/m5/performance-survey/README.md) - benchmark the source audit's transport, browser, media and serving risks before optimizing -- [Receive pool](/quest/m5/receive-pool.md) - one byte budget per worker covers every connection's receive credit and the cache, billing each frame once -- [Front parking](/quest/m5/origin-front-parks.md) - an unroutable request waits on a front instead of re-asking on every route-table move -- [A route stream's interest is a set of prefixes](/quest/m5/route-interest-prefixes.md) - one Announce Stream covers several subtrees, with floors and certification proved over the set -- [Fewer allocations in announce fan-out](/quest/m5/announce-fanout-allocs.md) - a deep path costs no more allocations per subscriber than a shallow one -- [moq-room scales to large rooms](/quest/m5/room-bench.md) - a benchmark measures `Room` with large participant counts, and polling narrows only if it shows a slope -- [Route health](/quest/m5/route-health/README.md) - epoch-only active/passive track recovery over metadata-only subscriptions - [Wrapper traits over moq-net](/quest/m5/net-wrap/README.md) - moq-net exports producer and consumer traits, and every writer and reader above it takes them, so a wrapper such as e2ee passes through unchanged - [E2EE](/quest/m5/e2ee/README.md) - TypeScript and Rust peers interoperate over encrypted broadcasts no relay can decrypt -- [Bindings size profile](/quest/m5/ffi-size-profile.md) - a benchmark decides whether the moq-ffi builds ship at opt-level "s", which halves the dylib -- [Value merge-patch diff](/quest/m5/json-value-diff.md) - benchmarks decide between moq-json's generic serializer diff, a ported `Value` diff, and compression alone -- [Measure what a catalog republish costs per rendition edit](/quest/m5/catalog-republish-cost.md) - bench whole-catalog re-serialization across track counts, then decide deltas or a bound -- [WebGPU HDR](/quest/m5/webgpu-hdr.md) - HDR renditions play as HDR where the browser and display can show it, and tone-map to SDR elsewhere -- [moq-transport hole markers](/quest/m5/ietf-hole-marker.md) - a negotiated extension names a SUBSCRIBE's holes, so our publishers answer multi-group FETCH from caches that know every group; built when an IETF client wants it -- [A parked read of a resumed group reads its budget without re-syncing](/quest/m5/recover-budget.md) - measure, then drop the per-frame reader sync - [Publishers learn their cap](/quest/m5/rate-grant.md) - the AUTH grant carries the caps and publishers clamp their encoder to them -- [Linux decoded frames](/quest/m5/obs-decode-linux.md) - present supported native decoded surfaces with visible CPU fallback -- [Windows decoded frames](/quest/m5/obs-decode-windows.md) - present decoded D3D11 surfaces in OBS without CPU readback -- [macOS GPU input](/quest/m5/obs-macos.md) - feed the encoder from the OBS compositor without CPU readback -- [Windows GPU input](/quest/m5/obs-windows.md) - import or blit OBS D3D11 textures with explicit synchronization - [WASM-to-JS evaluation](/quest/m5/rs2ts-wasm2js.md) - try the Rust implementation as JS-only browser output and compare source-translator alternatives if needed - [JS-only @moq/net](/quest/m5/rs2ts-js.md) - adopt the selected Rust-to-JS route after browser parity and measured tradeoffs are accepted -- [Per-stream and per-datagram deadlines](/quest/m5/quic-deadline.md) - hopeless retransmits - become resets, a tail loss probe fires early while there is still time, and - datagrams past their subscription's max delay are dropped instead of sent late -- [Measure ECN on the backbone](/quest/m5/quic-ecn-measure.md) - a written - verdict on marking versus dropping, and whether Linode and OVH keep marks -- [Delivery delay](/quest/m5/delivery-delay.md) - a per-frame - delivery-delay histogram from `poll_acked`, so viewer jitter is visible - [#3199](/quest/m5/3199-moq-uring-remove-sq-indirection-and-per-enter-ring-fd.md) - moq-uring: remove SQ indirection and per-enter ring fd lookup, if a profile shows the win - [#3200](/quest/m5/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md) - moq-uring: batch completion wakeups with MIN_TIMEOUT - [Browser media report](/quest/m5/rs2ts-browser-report.md) - compare Rust-backed and handwritten @moq/net through full media workloads, supplementing the pre-adoption comparisons - [Link quality](/quest/m5/link-quality.md) - a radio link's cost follows its measured quality without flapping routes - [io_uring thread check](/quest/m5/uring-transport-machines.md) - the relay fanout bench measures `moq_uring::transport::Local`'s per-call thread check after the transport is boxed, removing it only if it shows -- [Opus implementation](/quest/m5/audio-opus-backend.md) - compare Opus codec quality, CPU, build cost, and the loss recovery each backend offers -- [Latency ledger](/quest/m5/latency-ledger.md) - a viewer reports its share of playback delay stage by stage: jitter buffer and device -- [Media Foundation decode](/quest/m5/audio-decode-mediafoundation.md) - Windows decodes HE-AAC, multichannel AAC, and what else the MFTs offer -- [Media Foundation encode](/quest/m5/audio-encode-mediafoundation.md) - Windows encodes AAC-LC -- [MediaCodec decode](/quest/m5/audio-decode-mediacodec.md) - Android decodes HE-AAC, multichannel AAC, and what else the device offers -- [MediaCodec encode](/quest/m5/audio-encode-mediacodec.md) - Android encodes AAC-LC -- [#2848](/quest/m5/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - the Opus producer follows its bandwidth grant through the settled `moq_mux::rate::Control` - [NVENC buffer pool](/quest/m5/nvenc-pool.md) - NVENC reuses input and output buffers instead of allocating per frame, if a benchmark shows it wins - [QUIC I/O boundary](/quest/m5/quic-io-boundary.md) - moq-uring receives from the buffer ring and transmits into caller-owned buffers with no copy, once a profile says where -- [BBR media study](/quest/m5/quic-bbr-study.md) - whether Google's growth recognition and precautionary probe stop help media, measured on a shaped media harness -- [Egress profile](/quest/m5/quic-egress-profile.md) - measure relay send-path syscalls, pacing bursts, and allocations before optimizing any of them -- [Archive lookups cancel when abandoned](/quest/m5/archive-lookup-withdrawal.md) - a public withdrawal signal on `Fill` stops a time lookup's store read once its readers leave -- [Demo dashboard shows viewer lag](/quest/m5/qos-lag-dashboard.md) - follow-on capability after the release contract is stable - [A failed archive time lookup fails the subscription](/quest/m5/archive-time-followups.md) - when an `archive::Consumer` cannot answer a `Time(pts)` lookup because a store GET fails or an object does not decode, the subscription fails with a typed error naming the lookup failure instead of silently falling back to the cache -- [HTTP auth servers see which request named a token](/quest/m5/auth-http-request-kind.md) - the HTTP auth contract forwards `auth::Request`'s `kind()` and `path()` -- [moq auth sign mints capped tokens](/quest/m5/auth-sign-caps.md) - CLI flags for the bitrate caps -- [QUIC-LB forwarding reads the cluster's peers and reports its counts](/quest/m5/quic-lb-forward-extras.md) - a cluster-API peer map and forward counters diff --git a/quest/m5/ac3-low-rate.md b/quest/m5/ac3-low-rate.md deleted file mode 100644 index 2a0ce14b73c..00000000000 --- a/quest/m5/ac3-low-rate.md +++ /dev/null @@ -1,21 +0,0 @@ -# [XS] Half and quarter rate AC-3 - -## Goal - -`moq-mux` parses AC-3 with bsid 9 and 10, the half and quarter sample-rate -variants, through TS and FLV import and TS export, instead of refusing them. - -## Plan - -Decided 2026-10-22 (maintainer, from the release audit): support them rather -than only documenting the refusal. It is cheap and removes an inconsistency -noted in [moq-dev/moq#5758](https://github.com/moq-dev/moq/pull/5758): -`ac3_core` in `rs/moq-mux/src/container/ts/export.rs` counts bsid up to 10 as an AC-3 -core, then hands it to `ac3::parse_header`, which refuses anything above 8. - -In `rs/moq-mux/src/codec/ac3.rs`, keep the frame-size tables and shift the -sample rate right by `bsid - 8`. Add a bsid 9 or 10 fixture through TS import -and TS export. Broadcast specs require 48 kHz, so these streams are rare, and -this stays low priority. - -Public API: none. Wire: none. diff --git a/quest/m5/announce-credit.md b/quest/m5/announce-credit.md deleted file mode 100644 index 15ee60d2919..00000000000 --- a/quest/m5/announce-credit.md +++ /dev/null @@ -1,71 +0,0 @@ -# [M] Announce credit - -## Goal - -A subscriber bounds how many routes an Announce Stream advertises to it, at -the wire: ANNOUNCE_REQUEST carries an initial route credit, the subscriber -raises it later on its side of the stream, and the publisher never holds more -live advertisements on the stream than the credit. A peer that floods distinct -paths is held to the credit instead of closing the session at the 100k -announce cap, so a flood of distinct paths cannot drop a cluster link or the -other announcements it carries. Rust and JS implement it on the next -unpublished lite version after lite-07. - -## Plan - -Decided 2026-11-01 with the maintainer (the follow-up to the -sockets interview): - -- Backpressure is fixed at the wire, not by a local cap. The draft already - tells implementations to limit matching broadcasts but gives the subscriber - no way to state a limit; its only tools are closing the stream or the - session. -- Credit, not fastest-consumer pacing. Rust already coalesces each - consumer's pending announcements to the latest state per path - (`rs/moq-net/src/model/origin.rs`) and paces the outgoing stream by write - credit, so a slow reader costs no growing buffer. Count is the unbounded - dimension. Pausing a merged upstream stream for one slow consumer would stall - every overlapping prefix. Credit avoids that: each Announce Stream is - credited on its own, and a relay sets its upstream credit from its own - budget. -- Declined: per-route refusal (frees the subscriber but not the publisher, - and the flood still crosses the wire once), and aggregating to a covering - prefix at the limit (loses the per-path inventory a reader watching many - broadcasts needs). -- The publisher withholds routes beyond the credit, coalesced to the latest - state per path as it already does, and sends them as an ANNOUNCE_END or a - credit raise frees room. Which withheld route goes first is the - publisher's choice; the draft says so and Rust documents its order. A - withheld route that is retracted is never sent. Exceeding the credit is a - PROTOCOL_VIOLATION. -- On the new lite version, `session::Limits::announces` becomes the credit - the session advertises, and the session never closes for count. - moq-transport and older lite versions have no credit and keep today's - close at the cap. -- Decided 2026-11-03 (maintainer, follow-up planning after the 2026-11-03 /quest-afk and /quest-complete runs): weigh per-socket stream credit here, - like QUIC's MAX_STREAMS. With - [moq-dev/moq#7677](https://github.com/moq-dev/moq/pull/7677)'s sockets, a peer can keep - as many live socket streams listed as the session's announce cap allows, - with no per-socket bound. Decide whether the route credit covers it or a - socket needs its own, for byte streams and the mesh. Options shown: m0; - m1; ✅ m2, in this quest. -- Settle and record here how SYNCED behaves when the initial set exceeds the - credit. For example, SYNCED could follow the credited part, and the rest - arrives as live updates. - -Update the Announce Stream, ANNOUNCE_REQUEST, and a new credit message in -`drafts/draft-lcurley-moq-lite.md`, and run `just drafts check`. Implement -both sides in `rs/moq-net` and `js/net`, gated on the version. Leave -moq-transport unchanged. - -Tests on controlled time: a publisher with more routes than the credit -withholds the excess and sends it as ENDs or raises free room; a retracted -withheld route is never sent; a peer over the credit is a PROTOCOL_VIOLATION; -a relay's flooded upstream holds the credit while its other announcements keep -flowing and the session stays open; an older version still closes at the cap. - -## Related - -- [Announce interest memory](/quest/m4/announce-interest-memory.md) - per-stream memory proportional to what is in flight, which credit bounds -- [JS announced coalescing](/quest/m3/js-announced-coalesce.md) - the JS consumer-side queue that is still unbounded -- [Publishers learn their bitrate cap](/quest/m5/rate-grant.md) - the other wire change targeting the next lite version diff --git a/quest/m5/announce-fanout-allocs.md b/quest/m5/announce-fanout-allocs.md deleted file mode 100644 index 9e3f7e5602d..00000000000 --- a/quest/m5/announce-fanout-allocs.md +++ /dev/null @@ -1,21 +0,0 @@ -# [S] Fewer allocations in announce fan-out - -## Goal - -Announcing a broadcast to its subscribers costs about as many allocations per -subscriber with a deep path as with a shallow one. An allocation-count test announces -a broadcast to many subscribers at two path depths and records the per-subscriber -counts before and after. - -## Plan - -Decided with the maintainer on 2026-10-25, as a follow-up of the Path spike. Its -counting allocator measured 16.5 allocations per subscriber at one depth and 26.7 at a -deeper one, the same with every `Path` representation, so the extra 10 come from -fan-out itself. No checked-in test measures this yet; `announce_allocs.rs` covers -route churn and could host the new case. Find where depth adds allocations per -subscriber (per-segment joins, `strip_prefix` copies, or per-subscriber -presentation), and cut them. Allocation counts are the signal; timing on a loaded -host was within noise. - -Public API: none. diff --git a/quest/m5/archive-lookup-withdrawal.md b/quest/m5/archive-lookup-withdrawal.md deleted file mode 100644 index 7125533fd30..00000000000 --- a/quest/m5/archive-lookup-withdrawal.md +++ /dev/null @@ -1,22 +0,0 @@ -# [XS] moq-archive cancels an abandoned lookup's store read - -## Goal - -A `track::Fill` exposes a public signal for "no reader waits on this fill any more", and moq-archive's handler uses it to stop the store read of a time lookup whose readers left, so time-range readers that churn don't leave slow stores serving reads nobody takes. - -## Plan - -Follow-up of [moq-dev/moq#7310](https://github.com/moq-dev/moq/pull/7310), which resolves archive time ranges through a fill lookup: a fill over `0..reach` carrying the unresolved time in `Fill::time()` and owing no group. moq-archive used `fill.unused()` to stop a slow store read once nobody waited, but [moq-dev/moq#7036](https://github.com/moq-dev/moq/pull/7036) removed it, and a lookup owes no group, so `unwanted(sequence)` can't stand in. #7310 dropped lookup cancellation by maintainer decision (2026-11-01, "no new moq-net API" in that PR), so an abandoned lookup now finishes its read and answers nobody. Group fills still stop on `unwanted(sequence)`. - -Decided 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-afk run): m2, adding the public withdrawal signal #7310 deferred, since wasted store reads under churn are a real cost for slow stores. - -- `Fill::poll_withdrawn` exists but is crate-private (`rs/moq-net/src/model/track/fill.rs`, about line 759, and async-only). Make it, or a `withdrawn()` future over it, public, rather than #7310's other alternative of `time()` turning `None` once withdrawn, which would overload a value with a lifecycle. -- moq-archive races its lookup's store read against it and drops the read on withdrawal. -- Test: a lookup whose only reader leaves mid-read stops its store GET (a slow mock store counts completed reads). -- Mirror it in `@moq/net` only if a JS handler needs it; none does today. - -Public API: a public withdrawal signal on `moq_net::track::Fill`. Wire: none. - -## Related - -- [A failed archive time lookup fails the subscription](/quest/m5/archive-time-followups.md) - a lookup refusal on `Fill`, the other half of a lookup's lifecycle; whichever lands second shares its `Fill` surface diff --git a/quest/m5/archive-paced-replay.md b/quest/m5/archive-paced-replay.md deleted file mode 100644 index d43f86e636b..00000000000 --- a/quest/m5/archive-paced-replay.md +++ /dev/null @@ -1,38 +0,0 @@ -# [M] Paced replay - -## Goal - -A live player plays a stored broadcast unchanged: `archive::Consumer` can push -each track's groups when a shared clock reaches their media time, like -`ffmpeg -re`, instead of answering only requests. `export ts` and web watch -play a paced `moq import archive` the way they play a live broadcast, and a -viewer who joins late joins mid-replay. - -## Plan - -Retargeted 2026-10-17 onto the archive consumer, -whose broadcast already includes the archived catalog as an ordinary track. - -- Decided 2026-10-08: the catalog paces on the same clock as the media, each - stored catalog group emitted at its recorded time, so a viewer sees the - state that applied then. Test a stored broadcast that ends muted or with a - rendition removed. At equal timestamps the catalog goes first, so a media - group never arrives before the catalog update that lists it. -- One clock per import, not per subscriber. It starts at the earliest stored - timestamp across tracks and every track paces against it, so tracks stay in - sync and every viewer sees the same moment. -- Decided 2026-10-17: untimed tracks are not paced. They stay readable by - request and range, since they have no media time to pace by; only timed - tracks pace. Rejected: pacing an untimed track by its neighbours. -- A gap is skipped at pace (the clock keeps running). A growing archive is - followed as new keys land. A finite archive ends each track after its last - group. -- Requests for past groups keep answering, so DVR and HLS are unaffected. -- The API shape (a consumer option vs a separate paced publisher) and the CLI - default follow the root API rules; report both in the PR. Update - `doc/bin/cli.md`. -- Test with paused time: store, replay paced, and assert a plain subscriber - gets every group in order at media pace, that a late subscriber starts at the - current group, and that two tracks stay aligned. -- Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no - named consumer. diff --git a/quest/m5/archive-time-followups.md b/quest/m5/archive-time-followups.md index 9a3c9e764e6..3b7fb8dc68c 100644 --- a/quest/m5/archive-time-followups.md +++ b/quest/m5/archive-time-followups.md @@ -48,5 +48,4 @@ Public API: `track::Fill` gains a lookup refusal; moq-ffi `MoqFill` gains ## Related -- [Archive lookup withdrawal](/quest/m5/archive-lookup-withdrawal.md) - the other [moq-dev/moq#7310](https://github.com/moq-dev/moq/pull/7310) follow-up, a public withdrawal signal on `Fill` - [DVR rewind](/quest/m3/archive-dvr.md) - the consumer of time seeks diff --git a/quest/m5/audio-decode-mediacodec.md b/quest/m5/audio-decode-mediacodec.md deleted file mode 100644 index 544a2034087..00000000000 --- a/quest/m5/audio-decode-mediacodec.md +++ /dev/null @@ -1,35 +0,0 @@ -# [M] MediaCodec decode on Android - -## Goal - -On Android, `moq-audio` decodes AAC-LC, HE-AAC v1 and v2, and multichannel -AAC through `AMediaCodec`, and whichever of MP3, FLAC, AC-3, and E-AC-3 the -device's codec list opens. - -## Plan - -Rust owns capture and codecs on mobile, settled in the 2026-09-30 audit, so this backend is -the Android audio codec path. - -The audio counterpart of `rs/moq-video/src/decode/backend/mediacodec.rs`, -behind a new optional audio `mediacodec` feature and the decode seam, on `target_os -= "android"`. - -- `audio/mp4a-latm` with the catalog description as `csd-0`; the output format - reports the channel count and, on API 23 and later, the channel mask that - maps to `Layout`. -- Optional codecs are probed through `AMediaCodecList` at open and advertised - only where present. -- Fixtures and layout-order tests as in the AudioToolbox quest; runtime proof - on a device or emulator through `just rs android-test`, which android.yml's - `emulator` job runs. Extend `sh/rs/android-test.sh` to run moq-audio's - ignored MediaCodec tests beside moq-video's, and add the audio feature to the - `just rs android` compile lane. -- The binding ships in the moq-ffi Android slice, which is how Kotlin and Dart - reach it. - -Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): moq-audio's codecs return zero or more outputs with `flush` before the cut, so this backend adds no break. `decode::Consumer` still places each packet by the one output it returns and refuses any other count, so if this backend holds or splits output, it also teaches the consumer to place that output. - -## Related - -- [Android capture](/quest/m3/mobile-capture-android.md) - the video MediaCodec family this sits beside diff --git a/quest/m5/audio-decode-mediafoundation.md b/quest/m5/audio-decode-mediafoundation.md deleted file mode 100644 index cb53debe31d..00000000000 --- a/quest/m5/audio-decode-mediafoundation.md +++ /dev/null @@ -1,29 +0,0 @@ -# [M] Media Foundation decode on Windows - -## Goal - -On Windows, `moq-audio` decodes AAC-LC, HE-AAC v1 and v2, and multichannel -AAC through the Media Foundation AAC decoder MFT, and whichever of MP3, FLAC, -AC-3, and E-AC-3 the installed MFTs open. - -## Plan - -The audio counterpart of `rs/moq-video/src/decode/backend/mediafoundation.rs`, -using the `windows` crate features moq-video already enables plus the audio -ones. Behind the decode seam as the first candidate on `target_os = -"windows"`. - -- The AAC decoder MFT takes an `MF_MT_USER_DATA` blob built from the catalog - AudioSpecificConfig and reports the output `WAVEFORMATEXTENSIBLE`, whose - channel mask maps to `Layout`. -- Optional MFTs (Dolby, FLAC) are probed at open: absent means the codec is - not advertised on that host, not an error at decode time. -- Fixtures and layout-order tests as in the AudioToolbox quest. -- Verification runs on a Windows host; the per-PR CI only compiles the - platform code (`just rs windows`). - -Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): moq-audio's codecs return zero or more outputs with `flush` before the cut, so this backend adds no break. `decode::Consumer` still places each packet by the one output it returns and refuses any other count, so if this backend holds or splits output, it also teaches the consumer to place that output. - -## Related - -- [Windows decoded frames](/quest/m5/obs-decode-windows.md) - the OBS Windows line this feeds diff --git a/quest/m5/audio-encode-audiotoolbox.md b/quest/m5/audio-encode-audiotoolbox.md deleted file mode 100644 index b1218f6b2af..00000000000 --- a/quest/m5/audio-encode-audiotoolbox.md +++ /dev/null @@ -1,44 +0,0 @@ -# [M] AudioToolbox AAC encode on macOS and iOS - -## Goal - -On macOS and iOS, `Codec::Aac` encodes through AudioToolbox at the input's -layout, mono through 5.1 and 7.1, and the result plays in the browser, -`moq play`, and OBS. 6.1 is refused: since #4973 a synthesized ASC names no -program config element. Carrying the converter's magic cookie verbatim would -lift that once a caller needs it. - -## Plan - -An `AudioConverter` from interleaved `f32` to `kAudioFormatMPEG4AAC`, behind -the encode seam as the platform candidate on macOS and iOS. - -- The catalog ASC is synthesized at construction per the encode seam; read - `kAudioConverterCompressionMagicCookie` at open and assert it matches. - `kAudioConverterPrimeInfo` gives the delay the timestamps fold in. -- Bitrate through `kAudioConverterEncodeBitRate`, updated live where the - converter allows. -- Gate the seam's "AAC refused without a platform encoder" test to hosts - without one. -- Regression: a stereo and a 5.1 encode round-trip through the AudioToolbox - decoder and through symphonia (stereo only), with timestamps continuous - across the priming. -- That continuity fails today for an epoch below the delay: `Producer::timestamp` - (`rs/moq-audio/src/encode/producer.rs`) clamps each priming packet to zero, - so a zero epoch stamps `[0, 0, 0, 20_000]`, and `decode::Consumer` reads the - duplicates as holes and resets AAC between them. Shift the whole timeline by - the deficit instead, including the terminal end (found in #4081 review). - -This backend implements the zero-or-more packet return and `flush` that -moq-audio's encoder took in m2 before the cut -(decided 2026-11-07, maintainer, /quest-plan from the API sweep of open PRs -and remaining quests), so it adds no break and waits on no other encoder backend; its round-trip test still needs its platform decoder. - -## Required - -- [AudioToolbox decode](/quest/m3/audio-decode-audiotoolbox.md) - the round-trip regression decodes through it - -## Related - -- [MediaCodec AAC encode](/quest/m5/audio-encode-mediacodec.md) - the same encode seam on Android -- [Media Foundation AAC encode](/quest/m5/audio-encode-mediafoundation.md) - the same encode seam on Windows diff --git a/quest/m5/audio-encode-mediacodec.md b/quest/m5/audio-encode-mediacodec.md deleted file mode 100644 index c04e8d50b6e..00000000000 --- a/quest/m5/audio-encode-mediacodec.md +++ /dev/null @@ -1,33 +0,0 @@ -# [M] MediaCodec AAC encode on Android - -## Goal - -On Android, `Codec::Aac` encodes through `AMediaCodec` at the input's layout -where the device's encoder supports it. - -## Plan - -Rust owns capture and codecs on mobile, settled in the 2026-09-30 audit, so this backend is -the Android audio codec path. - -The audio counterpart of `rs/moq-video/src/encode/backend/mediacodec.rs`, -behind the `mediacodec` feature and the encode seam. - -- `audio/mp4a-latm` with `KEY_AAC_PROFILE` = LC. The catalog ASC is - synthesized at construction per the encode seam, since `csd-0` only arrives - with the first output buffer; assert the two match. -- MediaCodec pipelines output. Reuse the flush and zero-or-more packet - return from the m2 seam; do not design another encoder seam. -- Multichannel is device-dependent; probe the encoder's capabilities at open - and refuse a layout it does not list. -- Round-trip regression through the MediaCodec decoder; runtime proof on a - device or emulator through `just rs android-test`, as in the decode quest. - -This backend implements the zero-or-more packet return and `flush` that -moq-audio's encoder took in m2 before the cut -(decided 2026-11-07, maintainer, /quest-plan from the API sweep of open PRs -and remaining quests), so it adds no break and waits on no other encoder backend; its round-trip test still needs its platform decoder. - -## Required - -- [MediaCodec decode](/quest/m5/audio-decode-mediacodec.md) - the round-trip regression decodes through it diff --git a/quest/m5/audio-encode-mediafoundation.md b/quest/m5/audio-encode-mediafoundation.md deleted file mode 100644 index 2ca85484b43..00000000000 --- a/quest/m5/audio-encode-mediafoundation.md +++ /dev/null @@ -1,29 +0,0 @@ -# [M] Media Foundation AAC encode on Windows - -## Goal - -On Windows, `Codec::Aac` encodes through the Media Foundation AAC encoder -MFT, mono, stereo, and up to 5.1. - -## Plan - -The audio counterpart of `rs/moq-video/src/encode/backend/mediafoundation.rs`, -behind the encode seam on Windows. - -- The encoder MFT fixes its output rates and bitrates per channel count; - refuse configurations outside that table at construction rather than - letting the MFT pick silently. -- The catalog ASC is synthesized at construction per the encode seam; the - output type's `MF_MT_USER_DATA` must match it, asserted in tests. -- Round-trip regression through the Media Foundation decoder; verification on - a Windows host, since the per-PR CI compiles only. - -This backend implements the zero-or-more packet return and `flush` that -moq-audio's encoder took in m2 before the cut -(decided 2026-11-07, maintainer, /quest-plan from the API sweep of open PRs -and remaining quests), so it adds no break and waits on no other encoder backend; its round-trip test still needs its platform decoder. - -## Required - -- [Media Foundation decode](/quest/m5/audio-decode-mediafoundation.md) - the round-trip regression decodes through it - diff --git a/quest/m5/audio-filters.md b/quest/m5/audio-filters.md deleted file mode 100644 index 01c2dfc1aa1..00000000000 --- a/quest/m5/audio-filters.md +++ /dev/null @@ -1,31 +0,0 @@ -# [L] moq-audio filter chain - -## Goal - -Each audio source can run an ordered processing chain in moq-audio before the -program bus: noise suppression, noise gate, compressor, and limiter, plus -ducking, which lowers one source (music) when another (the microphone) is -active. Third-party VST3 and CLAP plugins load into the chain. The -[studio's audio filters](https://github.com/moq-dev/studio/blob/main/quest/m0/audio-filters.md) in moq-dev/studio -configure it per source. - -## Plan - -Changed 2026-11-02 (maintainer): the studio moved to moq-dev/studio. The -chain lands here with its own tests and benchmark; the studio's panel and -scene-file shape follow a pin bump there. - -Decided 2026-11-02 (maintainer): the chain runs on the capture producer -before `capture::Producer` fans out to its consumers, so -the bus and a source's own track both carry filtered audio; gain and mute -stay after the split, in the bus `Strip`, so the chain has no gain stage of -its own; a compressor's makeup gain covers level fixes. - -Prefer maintained crates, such as `nnnoiseless` for RNNoise suppression, over -hand-rolled DSP. Benchmark the chain per source so its cost per added source -shows up as a slope. Host plugins out of process, so a crashing or hung plugin -drops that filter rather than the audio bus: the audio thread never blocks on -the plugin process, a block the plugin misses its deadline for passes through -unfiltered, and a plugin that keeps missing is bypassed and reported as failed. -Use a maintained host crate (such as `clack` for CLAP) rather than -hand-rolling the plugin ABIs. diff --git a/quest/m5/audio-opus-backend.md b/quest/m5/audio-opus-backend.md deleted file mode 100644 index f064f1a089b..00000000000 --- a/quest/m5/audio-opus-backend.md +++ /dev/null @@ -1,48 +0,0 @@ -# [M] Compare Opus implementations and loss recovery - -## Goal - -Determine whether an optional newer Opus backend improves quality, CPU, or -loss recovery enough to justify its build and maintenance cost while retaining -the simple Rust path, and settle a tested loss-recovery policy. - -## Plan - -The manifest describes unsafe-libopus as a Rust port of 1.3.1. Compare it with -a currently maintained upstream implementation, including -[Opus 1.6](https://opus-codec.org/demo/opus-1.6/), rather than treating old -unmeasured percentage claims as a decision. Verify the actual versions at -implementation time. - -Candidates seen in the 2026-10-19 dependency audit: unsafe-libopus itself has -been idle upstream since 2024-11. `opus` 0.4 now binds libopus through the -maintained `opusic-sys` rather than `audiopus_sys`, and `opus-rs` (restsend) -and `mousiki` are pure-Rust ports with recent releases. Check each one's -libopus baseline before measuring. - -Measure relevant voice/music rates, frame sizes, DTX, loss behavior, startup, -CPU, and package/toolchain cost. Keep native compilation optional and use the -existing private backend seam; do not add another public configuration surface -just to expose one implementation's controls. A no-go is a valid outcome. - -### Loss recovery - -Decided in the 2026-09-30 audit: the loss-recovery policy study folds in here, -because the options depend on the backend. DRED and deep PLC need libopus 1.5+, -while the current 1.3.1 port only offers in-band LBRR FEC and classic -concealment. - -Decide whether a concrete MoQ audio consumer benefits from FEC, DRED, or deep -PLC over concealment. The old FEC boolean supplied no expected-loss percentage -and our decoder never requested FEC recovery. Treat source loss, late-group -abandonment, and DTX as different cases. Define sequencing, expected loss, -playout lookahead, recovery versus concealment, and behavior when the next -packet is unavailable. Use deterministic dropped-packet fixtures to prove -redundancy is emitted and used, compare audible quality and delay, and name -the transport scenario where it helps. Any resulting policy is small and -additive on the extensible audio settings; do not reintroduce an enable flag -tested only by reading the codec's control value. - -Retain fixtures and repeatable measurements in the existing CI/nightly audio -harness. Public API and wire: no change for the study; validate compatibility -before a separately scoped backend implementation. diff --git a/quest/m5/auth-http-request-kind.md b/quest/m5/auth-http-request-kind.md deleted file mode 100644 index b4505d81022..00000000000 --- a/quest/m5/auth-http-request-kind.md +++ /dev/null @@ -1,36 +0,0 @@ -# [M] HTTP auth servers see which request named a token - -## Goal - -An external auth server authorizes per request: the HTTP auth contract -forwards `auth::Request`'s `kind()` and `path()` from -[moq-dev/moq#7211](https://github.com/moq-dev/moq/pull/7211), so the server can -decide a token's grant knowing which request (and path) first named it. - -## Plan - -Decided 2026-11-03 (maintainer, follow-up planning after the 2026-11-03 /quest-afk and /quest-complete runs), milestone: - -- m0 -- m1 -- ✅ m2 - -#7211 made `moq_net::auth::RequestKind` public and gave `auth::Request` -`kind()` and `path()`, naming the request that first named the token -(`None` for an AUTH-stream token). moq-auth's HTTP client doesn't send them -yet. - -- Add both to the HTTP auth request body as optional fields, absent for an - AUTH-stream token, so existing servers keep working. -- Document the fields in the HTTP auth contract docs and `moq auth serve`, - and have the reference server read them. -- Test that a server can refuse a token for one request kind and accept it - for another. - -Public API: additive (HTTP auth contract fields). Wire: none. - -Re-planned 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [moq-dev/moq#8088](https://github.com/moq-dev/moq/pull/8088) removed `auth::Request::{kind, path}`, so this quest starts by re-adding them, additively, only once an auth server asks for per-request decisions. Needs a fresh `/quest-plan` then. - -## Related - -- [Token auth follow-ups](/quest/m3/token-auth-followups.md) - the rest of #7211's follow-ups diff --git a/quest/m5/auth-sign-caps.md b/quest/m5/auth-sign-caps.md deleted file mode 100644 index 285aee8ab50..00000000000 --- a/quest/m5/auth-sign-caps.md +++ /dev/null @@ -1,13 +0,0 @@ -# [XS] moq auth sign mints capped tokens - -## Goal - -`moq auth sign` takes flags for the bitrate caps from -[moq-dev/moq#7535](https://github.com/moq-dev/moq/pull/7535), its publish and -subscribe rates and the object role's `rate`, so a capped token doesn't need -the library. - -## Plan - -Planned 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-complete run). Mirror the grant fields #7535 added, and document them in -`doc/bin/cli.md` and the relay auth guide. diff --git a/quest/m5/auth-token-fetch.md b/quest/m5/auth-token-fetch.md deleted file mode 100644 index 140b4b221ad..00000000000 --- a/quest/m5/auth-token-fetch.md +++ /dev/null @@ -1,26 +0,0 @@ -# [M] Our TRACK_STATUS and FETCH carry the request token - -## Goal - -Our own TRACK_STATUS, standalone FETCH, and a relay's cache-miss group FETCH -carry the connection's request token when one is set, as our SUBSCRIBE and -PUBLISH_NAMESPACE do, so a peer that grants authority per request admits -them. - -## Plan - -A [moq-dev/moq#5148](https://github.com/moq-dev/moq/pull/5148) follow-up. -The incoming half, a token admitting TRACK_STATUS and FETCH, landed with -[moq-dev/moq#7211](https://github.com/moq-dev/moq/pull/7211), which honors a -token on any request type. This quest keeps only the outgoing half. - -Decided 2026-10-20 (maintainer): stays in m5 with the other request-token -surfaces until a consumer asks. Outgoing tokens wait for `add()` with -automatic naming, so this lands with or after that. A joining FETCH keeps -following its subscription's authorization and carries no token of its own. - -Tests: outgoing TRACK_STATUS and FETCH carry the token. Run cross-language -interop for the wire change. - -Public API: none. Wire: the existing AUTHORIZATION TOKEN parameter (0x03), -now sent on TRACK_STATUS and FETCH. diff --git a/quest/m5/c-origin-relay.md b/quest/m5/c-origin-relay.md deleted file mode 100644 index 62fda7a9c9d..00000000000 --- a/quest/m5/c-origin-relay.md +++ /dev/null @@ -1,30 +0,0 @@ -# [S] A C origin can discover eagerly, like a relay - -## Goal - -The C API (`rs/moq-c`, `moq.h`) can put an origin in relay mode, with the -eager discovery moq-net gives an origin handle on a relay link, so a C -application that forwards a client session's routes needs no local -announce watcher of its own to make discovery run. - -## Plan - -Decided 2026-10-31 (maintainer, the /quest-complete requeue session), a -follow-up of [moq-dev/moq#7246](https://github.com/moq-dev/moq/pull/7246) -(moq-c API gaps), whose follow-ups note that C has no way to make an origin -relay-mode for a client-ingest relay. - -In moq-net, a handle's link decides it: `origin::Producer::with_link` -(`rs/moq-net/src/model/origin.rs`) takes `Link::Local`, `Link::Peer`, or -`Link::Upstream`, and a non-local link's sessions discover everything they -may (`relays()`). `moq_origin_create` (`rs/moq-c/src/api.rs`) always makes a -local one. Expose the choice in C, by a create option or a setter mirroring -`with_link`, following whatever moq-ffi exposes if it has gained the same -by then, and document it in `moq.h` and `doc/lib/c`. If the -[generated C line](/quest/m3/c/README.md) has replaced the hand-written crate -before this starts, add it to moq-ffi instead so every binding gets it. -Test a C origin forwarding a client session's routes with no announce -watcher. - -Public API: additive in moq-c, or in moq-ffi if the generated C line has -replaced it. Wire: none. diff --git a/quest/m5/captions-cea.md b/quest/m5/captions-cea.md deleted file mode 100644 index 7a4df8ed096..00000000000 --- a/quest/m5/captions-cea.md +++ /dev/null @@ -1,30 +0,0 @@ -# [L] CEA-608/708 extraction - -## Goal - -Captions carried inside video SEI become a real text rendition at import. A -large share of existing broadcast content carries captions only this way, so -without extraction those broadcasts have no captions in MoQ at all. - -## Plan - -Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no named consumer for timed metadata. - -Parse the `user_data_registered_itu_t_t35` SEI payloads that carry CEA-708 -(with 608 compatibility bytes inside) out of H.264 and H.265 access units at -import, and publish the decoded cues as a `text` rendition beside the video. - -The fiddly part is that 608/708 is a stateful terminal protocol, not a cue -list. Pop-on, roll-up, and paint-on modes each build the visible caption -differently, and the decoder has to track the display buffer to know when a -cue starts and ends. 708 adds a service layer, so a stream can carry several -services (commonly a primary language and a secondary one), each of which -should become its own rendition with its own `lang`. - -Emit cues on the shared media clock, taken from the access unit the SEI rode -in, so the text rendition needs no timeline of its own to stay in sync. - -Parse at import from the inline SEI. The separation study kept H.264 and HEVC -SEI in the video access unit, so this parser walks that access unit. There is -no sidecar and no strip step. Leave the SEI in place after the cues are -published, so a decoder that reads captions from the bitstream still can. diff --git a/quest/m5/catalog-republish-cost.md b/quest/m5/catalog-republish-cost.md deleted file mode 100644 index 2eebbd6e53d..00000000000 --- a/quest/m5/catalog-republish-cost.md +++ /dev/null @@ -1,29 +0,0 @@ -# [S] Measure what a catalog republish costs per rendition edit - -## Goal - -A benchmark measures whole-catalog re-serialization per rendition edit -across track counts, and its numbers decide between catalog deltas, a bound -on catalog size, or leaving it as is, recorded in the PR. - -## Plan - -Decided 2026-11-03 (maintainer, follow-up planning after the 2026-11-03 /quest-afk and /quest-complete runs), milestone: - -- m0 -- m1 -- ✅ m2 - -Every rendition edit re-serializes and republishes the whole catalog, so -the cost grows with the track count. - -- Bench serialize plus publish per edit at, for example, 1, 16, 256, and - 4,096 tracks, in Rust and JS. -- Then bring the choice back: deltas (see the JSON diff quest), a documented - bound on tracks per catalog, or no change. - -Public API: none for the measurement. Wire: none. - -## Related - -- [Benchmark a Value merge-patch diff for moq-json](/quest/m5/json-value-diff.md) - the delta machinery a catalog diff would reuse diff --git a/quest/m5/cpp-conan.md b/quest/m5/cpp-conan.md deleted file mode 100644 index cb0a232b480..00000000000 --- a/quest/m5/cpp-conan.md +++ /dev/null @@ -1,32 +0,0 @@ -# [S] Conan remote for the prebuilt C++ package - -## Goal - -A consumer adds the moq Conan remote, requires `moq-cpp/`, and gets the -prebuilt package for their `os`, `arch`, and `compiler` without a Rust -toolchain or the bindgen fork. A fresh consumer project installs it in CI on -Windows, macOS, and Linux. - -## Plan - -In m5 until a Conan consumer asks; the release tarball covers C++ consumers -first. The vcpkg registry, which this reuses, is parked in m5 too (decided -2026-10-08), so it lands before this does. - -- A `moq-cpp` recipe, named after the package, on a moq-dev remote - (Artifactory or a GitHub-hosted `conan` index) that packages the prebuilt - release tarball per setting and exports the `moq::cpp` CMake target from - `package_info`. -- The recipe reads the release manifest the vcpkg quest introduced, so one - release bumps both recipes; `release-cpp.yml` publishes to the remote after - the tarballs land. -- CI: a consumer smoke project (`conan install` then CMake) built nightly on - all three platforms. -- conan-center is out of scope; it wants source builds. -- Decided 2026-10-08: like the vcpkg port, this needs the first C++ package - release, which #4079 adds as its own quest. - -## Required - -- [First C++ package release](/quest/m3/release/cpp-release.md) - the tarballs the recipe packages -- [vcpkg registry](/quest/m5/cpp-vcpkg.md) - the release manifest and bump automation this reuses diff --git a/quest/m5/cpp-vcpkg.md b/quest/m5/cpp-vcpkg.md deleted file mode 100644 index ba905c8cd69..00000000000 --- a/quest/m5/cpp-vcpkg.md +++ /dev/null @@ -1,35 +0,0 @@ -# [S] vcpkg registry for the prebuilt C++ package - -## Goal - -A consumer adds `moq-dev/vcpkg-registry` to `vcpkg-configuration.json`, -depends on `moq-cpp`, and gets the prebuilt package for their triple without a -Rust toolchain or the bindgen fork. A fresh consumer project installs it in -CI on Windows, macOS, and Linux. - -## Plan - -- `moq-dev/vcpkg-registry`: a git registry with a `moq-cpp` port, named after - the package (`find_package(moq-cpp)`, target `moq::cpp`), whose portfile - downloads the per-target release tarball from `release-cpp.yml` by version - and hash, installs headers, the static library, and the CMake config, and - declares `supports` for exactly the release matrix. Versioning follows the - tarball tags. -- The port's version and hashes come from a release manifest checked into - this repository, which `release-cpp.yml` updates and which opens the - registry bump (like `release-brew.yml` does for Homebrew) once the tarballs - are published. The Conan quest reads the same manifest. -- CI: a consumer smoke project (`vcpkg install` in manifest mode, then CMake) - built nightly on all three platforms; a mismatch between the port and the - tarball fails the nightly, not the user. -- Curated `microsoft/vcpkg` is out of scope; it wants source builds. -- Decided 2026-10-08: the tarballs this needs are the first C++ package - release, which #4079 adds as its own quest. - -## Required - -- [First C++ package release](/quest/m3/release/cpp-release.md) - the tarballs the port fetches - -## Related - -- [Conan remote](/quest/m5/cpp-conan.md) - the same tarball through Conan diff --git a/quest/m5/cut-through/README.md b/quest/m5/cut-through/README.md deleted file mode 100644 index 2dd9f446c08..00000000000 --- a/quest/m5/cut-through/README.md +++ /dev/null @@ -1,79 +0,0 @@ -# Cut-through group streams - -## Goal - -A relay forwards group stream bytes that arrive past a QUIC stream hole -instead of holding them until the retransmission fills it. Payload after a -lost packet reaches the next hop at its own output offset while the hole is -still being recovered, so a loss on one hop no longer delays everything behind -it on the next. - -The line measures whether this is worth it. Only the loss-delay metric and -the bench are quests today; on a go, the build quests (offset writes in -`moq-quic`, frame ranges, the transport trait, relay cut-through) are -re-planned from git history against the bench's numbers. - -Non-goals: end consumers (players, `moq-cli`) keep ordered reads, since a -decoder needs whole frames. No MoQ wire change; QUIC already allows a sender to -send stream offsets in any order. - -## Plan - -Decided 2026-10-02: the line moved from m2 to m3. It is a speculative -optimization with no consumer asking for it, so it parks until one does and -is deleted if it goes stale. The QUIC primitives land in `moq-quic`. - -Decided 2026-10-08: the four build quests were deleted. They churned with -every frame-model and transport change while waiting on a verdict nobody had -measured, so they are re-planned from git history if the bench says go. The -design decisions below stay as the starting point for that re-plan. - -Decided 2026-09-30: - -- Measure first; the [bench](/quest/m5/cut-through/bench.md) gates any build. -- The gain is roughly the time the relay would spend bursting the held bytes - downstream after the hole fills: small when the egress hop has headroom, - larger for a big I-frame on a tight hop. The bench sweeps exactly that. -- A hole that covers a frame header blocks every later frame on that stream: - the next header's input position and every output header's length depend on - earlier header values (lite's timestamp delta, IETF's object id delta). A hole - inside a payload blocks nothing, since the frame sizes locate both the input - and the output bytes. Passing a hole into later frames needs several - in-flight frames per group; the build prototypes both scopes and keeps - the one the bench justifies. -- The opportunity is measured on the real two-hop path, not against a direct - connection: the gain exists only with a relay in the middle. -- The frame model gains an offset write and a range read, crate-private in - `moq-net`, since the lite and IETF publishers and subscribers that use them - live in the same crate. Cut-through frames keep the received chunks by - offset instead of copying into a pre-allocated buffer, so memory tracks bytes - received and the per-session pre-allocation `Budget` (`model/frame.rs`) - does not apply. The group cache already charges each frame by bytes written - (#4609), so several in-flight frames charge only what has arrived. -- moq-net's `transport::poll` traits gain an unordered chunk read and an - offset write whose defaults report unsupported, and moq-net falls back to - ordered I/O. Only the - `moq-quic` backends implement them; browsers and qmux keep the defaults. - Additive, so it lands on `main`. -- Always on wherever both of the relay's streams support it. No config knob. -- The relay's own egress is `moq-quic` for every native and browser viewer, so browser - viewers benefit too; only the relay's side needs the feature. - -Public API: additive `transport::poll` methods in moq-net; the loss-delay counter on -`moq-stats` ingress rows. Wire: none for MoQ; the counter is a `moq-stats` -field. - -End to end: once a relay build lands, re-run the -bench on the same sweep and record before and after in this README before -closing the line. No new doc page: nothing user-facing changes beyond the -stats field, which its quest documents inline. - -## Required - -- [Loss delay](/quest/m5/cut-through/loss-delay.md) - relays report, per broadcast, the ingress bytes a loss held back by at least one RTT -- [Bench](/quest/m5/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 - -- [QoS](/quest/m3/qos/README.md) - the loss-delay counter follows its per-broadcast ingress row conventions -- [Frame slot accounting](https://github.com/moq-dev/moq/pull/5239) - landed: the cache charges frame slot growth, which covers the in-flight frames a cut-through build would hold diff --git a/quest/m5/cut-through/bench.md b/quest/m5/cut-through/bench.md deleted file mode 100644 index 1460de3464a..00000000000 --- a/quest/m5/cut-through/bench.md +++ /dev/null @@ -1,52 +0,0 @@ -# [M] Benchmark head-of-line blocking at a relay hop - -## Goal - -A nightly bench measures how long a frame takes to complete at the viewer when -the publisher's hop to the relay loses packets, and how much of that a -cut-through relay could win back. It ends with a written go or no-go for the -rest of the [cut-through line](/quest/m5/cut-through/README.md). - -## Plan - -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 `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 - viewer, minus the same for frames with no hole. That excess is the burst - cut-through removes. No direct publisher-to-viewer control: the gain exists - only with a relay in the middle, and one QUIC hop already reassembles out of - order, so a direct run measures a different topology (review of #4616). -- Split the held bytes three ways: bytes in the frame that has the hole, bytes - in later frames whose headers were known while the hole was open, and bytes - behind a lost header. Only the first two are forwardable; the last blocks with - or without cut-through and is reported but excluded from the opportunity. The - first split shows what multiple in-flight frames per group would add beyond - the current frame. Report the drain estimate as an upper bound, and - include both a payload-loss and a header-loss case to validate the split. -- Take publisher and subscriber counts as parameters, so a relay build - reuses the rig for its fan-out sweep. -- Record the loss-delay counter from the same runs, if - [Loss delay](/quest/m5/cut-through/loss-delay.md) has landed, so production - numbers can be read against the lab. -- It runs on wall-clock time, so it is a nightly bench, not a unit test. Wire it - into the nightly workflow. - -Write the numbers and the verdict into this line's README. The maintainer makes -the go or no-go call from them; no threshold is set in advance. On a go, -re-plan the build quests from git history (decided 2026-10-08); either way -the bench stays. diff --git a/quest/m5/cut-through/loss-delay.md b/quest/m5/cut-through/loss-delay.md deleted file mode 100644 index ab4377e4ffc..00000000000 --- a/quest/m5/cut-through/loss-delay.md +++ /dev/null @@ -1,44 +0,0 @@ -# [M] Report bytes delayed by loss at relay ingest - -## Goal - -The relay's `moq-stats` ingress rows carry, per broadcast, a cumulative -`loss_delay_bytes` counter: stream bytes that arrived behind a hole and stayed -unreadable for at least one smoothed RTT. Compared with bytes received, it -shows how much of a publisher's media a lossy uplink held back, and it is the -production number that sizes the cut-through opportunity. - -## Plan - -Decided 2026-09-30: one monotonic byte counter, no hold-time histogram, on the -ingress (`Role::Subscriber`) rows next to -[publisher timeliness](/quest/m3/qos-publisher-timeliness.md)'s fields. -Independent of the bench. - -- `moq-quic` counts per receive stream. The assembler stamps each chunk buffered past - the contiguous frontier with its arrival time; when the frontier passes it, - bytes held at least one smoothed RTT are counted. Plain reordering fills - within an RTT and is not counted. The count is by arrival and gap fill, not by - when the application reads, so it stays meaningful once reads go unordered. - When a stream ends with a hole still open (reset, stop, or session close), - buffered bytes that have already waited one smoothed RTT are counted then. -- `moq-quic` exposes the per-stream count, and moq-net's - `transport::poll::RecvStream` gains an accessor returning `Option` (`None` - when the backend cannot see it), following the module's `Stats` - convention. The moq-tokio and moq-uring adapters implement it, as - [poll_acked](/quest/m3/quic-ack-hook.md) does. -- The lite and IETF subscribers read the count at each frame boundary and when - the group stream ends, adding the delta to the broadcast's ingress row, so a - long group does not leave the row stale. Nothing on the per-byte path. -- Update the stats section of `doc/bin/relay/config.md`. - -Test: a seeded loss on a `moq-quic` pair counts the held bytes; a reorder shorter than -an RTT counts nothing. - -Public API: an additive trait accessor. Wire: a new `moq-stats` field, -additive on `main` since `Traffic` is `#[non_exhaustive]` and readers default -missing fields. - -## Related - -- [QoS](/quest/m3/qos/README.md) - the per-broadcast ingress conventions this follows diff --git a/quest/m5/delivery-delay.md b/quest/m5/delivery-delay.md deleted file mode 100644 index d069025357b..00000000000 --- a/quest/m5/delivery-delay.md +++ /dev/null @@ -1,37 +0,0 @@ -# [S] Per-frame delivery delay histogram - -## Goal - -The relay's `moq-stats` egress side reports, per broadcast, a byte-weighted -cumulative histogram of per-frame delivery delay (from when a frame is -written to when the peer acknowledges it), so viewer jitter is visible beside -the `lag` histogram. Subscriptions on a backend that cannot see -acknowledgements leave it absent, never zero. - -## Plan - -Decided 2026-10-26 (maintainer, on -[moq-dev/moq#6791](https://github.com/moq-dev/moq/pull/6791)): this quest's -frontier half, moving the acknowledged frontier at every frame end and -counting `dropped` per frame, moved into the -[viewer lag histogram](/quest/m3/qos/lag-histogram.md), which no longer -lands at group granularity. That quest already awaits each frame's -acknowledgement through `poll_acked`; this one adds the delay it observes. - -Record `acked_at - written_at` per frame, where `acked_at` is when the serve -task is woken by `poll_acked`. Its low edge approaches the path RTT and its -spread is the jitter. Use the `lag` histogram's type and bucket contract. -Document that the value still includes the return one-way delay and the -peer's delayed-ACK timer, since the hook reports no corrected instant -(decided 2026-10-17 on #5817). - -Tests: delivery delay staying inside one bucket of the true RTT plus the -peer's `max_ack_delay`, and the histogram absent over a backend without the -hook. - -Public API: an additive `Traffic` field. Wire: an additive stats JSON field. - -## Required - -- [Viewer lag histogram](/quest/m3/qos/lag-histogram.md) - the per-frame - acknowledgement tracking and histogram type this reuses diff --git a/quest/m5/emsg.md b/quest/m5/emsg.md deleted file mode 100644 index 84d50d91f5e..00000000000 --- a/quest/m5/emsg.md +++ /dev/null @@ -1,64 +0,0 @@ -# [L] fMP4 emsg carriage, and the timed-metadata contract it sets - -## Goal - -`emsg` boxes survive fMP4 import instead of being discarded with a warning, and export -reproduces them. In-band ID3, SCTE-35 splice information, and DASH event -messages reach a MoQ consumer. This is the first of the four timed-metadata -carriers, so it also settles the contract they share: how an event's -presentation time and its delivery time are framed, how a metadata group -sequences independently of media, how source placement is kept for exact -export, and what missing data means; ID3, SCTE-35, and FLV script tags adopt -it rather than restating it. Deferred SEI extraction is not a prerequisite. - -## Plan - -Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no named consumer for timed metadata. - -The shared contract, recorded here and mirrored in the Hang draft: - -- Publish an event as soon as it is received, on its own group sequence; never - wait for a media GOP or require a media rendition to exist, so advance ad - cues, sparse metadata, audio-only, and metadata-only sources all work. -- Carry the event's presentation time on the broadcast clock, distinct from - the outer frame timestamp; a future cue precedes a current event, so test - retention and expiry for that order, since relay expiry reads group - timestamps. -- Keep source placement (before the first media, container position, order - among equal timestamps) separate from event time, and state what export - reconstructs exactly and what is only equivalent. -- Missing data is reported, not inferred: an export deadline shares the mux - budget and says metadata was unavailable rather than claiming the source - had none, and a sparse track never waits indefinitely. - -A new exported envelope shape needs maintainer agreement before the -dependents implement against it; land the shared CI fixtures with it. - -`rs/moq-mux/src/container/fmp4/import.rs` counts discarded `emsg` boxes -and warns on the first drop. Carriage and export remain unimplemented; -logging the loss does not preserve the metadata. - -Carry the boxes byte-faithfully: scheme id URI, value, timescale, presentation -time, duration, id, and the opaque message payload, for both version 0 and -version 1 timing. Do not parse the payload into a vocabulary; an application -decodes it with its own library, and a new scheme stays forward-compatible. - -Publish each box when received on independently sequenced metadata groups -under the contract above. Keep event -presentation time separate from the containing fragment or pre-media -placement. A future event is delivered before its presentation time, and a -box before the first moof does not wait for a media group to exist. Preserve -source placement for exact export rather than selecting a fragment solely -from the event's presentation timestamp. - -Test version 0 and version 1 boxes, an emsg before the first moof, several on -one fragment, an unknown scheme, a zero duration, and a round trip that is -byte-identical. - -Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): one catalog `events` section, `[{track, scheme, rendition?}]` keyed by scheme URI, shared with SCTE-35, ID3, and FLV script data as schemes with their own parsing helpers, instead of one top-level section per format. - -## Related - -- [ID3 in the events section](/quest/m5/id3.md) - gives one payload type carried here a - typed contract -- [FLV script tags](/quest/m5/flv-script.md) - likewise diff --git a/quest/m5/ffi-size-profile.md b/quest/m5/ffi-size-profile.md deleted file mode 100644 index 553c611eafa..00000000000 --- a/quest/m5/ffi-size-profile.md +++ /dev/null @@ -1,26 +0,0 @@ -# [M] Bindings size profile - -## Goal - -Decide, with a benchmark, whether the moq-ffi builds for Swift, Android, -Dart, Go, and Python ship at `opt-level = "s"`. On aarch64-apple-darwin it -halved the stripped dylib from 20.0 MiB to 10.1 MiB (fat LTO, 1 CGU) and -shrank `__text` from 18.2 MB to 8.5 MB. The throughput cost is unmeasured. - -## Plan - -Decided in planning: adopt it only if the benchmark shows the cost is -negligible. The relay and CLI stay at opt-level 3 regardless. - -Guidance: - -- The `cc` crate builds the C dependencies at the profile's opt-level too: - aws-lc, openh264, and libopus. Hold the codec and crypto crates at - opt-level 3 with per-package overrides, and compare against building - everything at "s". -- Measure what the bindings actually do: publish and subscribe throughput - through moq-ffi on rust2's [binding benchmark](https://github.com/moq-dev/rust2/blob/main/bench/ffi/README.md), plus - audio and video encode and decode. -- If it's adopted, use a named profile (for example `[profile.ffi]`, - inheriting release) that every binding build path selects, so the relay - and self-builders keep opt-level 3. diff --git a/quest/m5/flv-script.md b/quest/m5/flv-script.md deleted file mode 100644 index f9d46d3e423..00000000000 --- a/quest/m5/flv-script.md +++ /dev/null @@ -1,32 +0,0 @@ -# [S] FLV script tag carriage - -## Goal - -FLV script tags survive RTMP and FLV import instead of being discarded, so -`onMetaData` and application AMF data messages reach a MoQ consumer. - -## Plan - -Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no named consumer for timed metadata. - -`rs/moq-mux/src/container/flv/import.rs` counts discarded `TAG_SCRIPT` -payloads and warns on the first drop. `onMetaData` and application cues still -need carriage; logging their loss does not implement this quest. - -Carry raw tag payloads without decoding AMF into a fixed vocabulary. Publish -when received on independently sequenced metadata groups, with event time on -the broadcast clock and source placement per the contract -[emsg](/quest/m5/emsg.md) settles. Tags before media -are delivered immediately and retain explicit pre-media placement; audio-only -and script-only input do not require a dummy video rendition. -Where `onMetaData` duplicates something the catalog already models (dimensions, -framerate, bitrate), prefer the value the bitstream actually carries and treat -the script tag as opaque data, not a second source of truth for configuration. - -Export reproduces the tags on the FLV path. Test `onMetaData`, an application -message with a custom name, AMF0 and AMF3 payloads, a tag before the first -media tag, and a byte-identical round trip. - -## Required - -- [fMP4 emsg](/quest/m5/emsg.md) - settles the shared timed-metadata contract this builds on, which needs maintainer agreement first diff --git a/quest/m5/id3.md b/quest/m5/id3.md deleted file mode 100644 index 562fb620819..00000000000 --- a/quest/m5/id3.md +++ /dev/null @@ -1,44 +0,0 @@ -# [M] ID3 in the catalog's events section - -## Goal - -A Hang catalog exposes ID3 metadata as an ID3 scheme entry in the shared -`events` section [emsg](/quest/m5/emsg.md) defines, with named tracks and -media correlation, independent of the MPEG-TS PID that supplied it. -Consumers can discover and read timed ID3 without understanding the `mpegts` -extension, while MPEG-TS export still reconstructs a valid ID3 elementary -stream. - -## Plan - -Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no named consumer for timed metadata. - -Define the ID3 scheme's entry and frame contract for complete ID3 tags on the -shared event contract [emsg](/quest/m5/emsg.md) settles: one catalog `events` -section keyed by scheme URI, not a top-level `id3` section (decided 2026-11-07, maintainer, /quest-plan from the API sweep of open PRs and remaining quests). Publish tags when -received on independently sequenced groups, with their presentation time on -the broadcast clock and an optional association to the program's rendition. -ID3-only programs need no artificial media owner. Carry original tag bytes, -and in the scheme's entry the raw stream-level PMT descriptor loop plus any -application or program registration metadata the exporter needs to reproduce -the input. Do not parse the tag into a fixed -metadata vocabulary; applications can decode frames with their ID3 library and -new tag types remain forward-compatible. - -Teach MPEG-TS import to use this entry only when the PMT descriptors or -application metadata identify ID3 and complete payloads validate as ID3 tags. -Stream type `0x15` alone is generic metadata PES and does not qualify. -Ambiguous, non-ID3, or inconsistent streams stay byte-faithful in the generic -`mpegts` representation. Export typed ID3 to recreate the elementary stream, -descriptors, and timestamps, without publishing a second generic copy of a -stream positively identified as ID3. - -Land matching Rust and web catalog bindings plus byte-faithful round-trip tests -with default and non-default PMT descriptors, multiple tags, unknown frames, -large tags spanning PES packets, timestamp wrap, discontinuity, and an ID3-only -program. Include non-ID3 and malformed stream type `0x15` fixtures that remain -generic. - -## Required - -- [fMP4 emsg](/quest/m5/emsg.md) - settles the shared timed-metadata contract this builds on, which needs maintainer agreement first diff --git a/quest/m5/ietf-cluster-peers.md b/quest/m5/ietf-cluster-peers.md deleted file mode 100644 index 7381dbbbf3b..00000000000 --- a/quest/m5/ietf-cluster-peers.md +++ /dev/null @@ -1,45 +0,0 @@ -# [L] moq-transport cluster peers - -## Goal - -A moq-transport relay joins a cluster as a peer through an extended -`draft-lcurley-moq-cluster`, with the loop safety a lite cluster link has. - -## Plan - -The extension must carry what a lite cluster link carries by then: the route -layer of the [cluster routing line](/quest/m2/cluster-routing/README.md) -(per-node ROUTEs with seqno and metric, path-less announces, the down-only -bit) and its selection. - -Test: a moq-transport relay peering through the extension discards a route -that loops back to it, and resumes a subscription on another route when the -serving one dies, only with matching explicit epochs. Test cluster-only, -epoch-only, both and neither negotiated: cluster metadata alone never makes -namespace equality sufficient for continuity. Without verified epochs, -route replacement signals a new instance instead of stitching. - -Noted 2026-10-31 from [moq-dev/moq#7259](https://github.com/moq-dev/moq/pull/7259) -(landed as 44e85d8efb): the draft's "Track Delivery" section -(`drafts/draft-lcurley-moq-cluster.md:262` on be39188000) runs ahead of the -implementation. -It gives PUBLISH and SUBSCRIBE_TRACKS the namespace advertisements' Hop ID -loop rules: a PUBLISH carries HOP_PATH and ROUTE_COST, is sourced only from a -path that excludes the subscriber's Hop ID, and is discarded when its path -holds the receiver's own Hop ID; an edge relay forwarding an unsolicited -PUBLISH keeps its HOP_PATH (or the bridging 0 entry), appends its Hop ID, and -accumulates ROUTE_COST; and SUBSCRIBE_TRACKS resolves per namespace and -resumes a track's preferred source only while the track has demand. The -same PR put EPOCH on PUBLISH (`drafts/draft-lcurley-moq-epoch.md:112`). -Neither `rs/moq-net` nor `js/net` carries HOP_PATH, ROUTE_COST, or EPOCH on -PUBLISH yet. Implement them here, and reconcile with -[moq-dev/moq#7236](https://github.com/moq-dev/moq/pull/7236) (merged), -whose publishers refuse inbound SUBSCRIBE_TRACKS -(`rs/moq-net/src/ietf/publisher.rs:1198`): once this lands, a cluster peer -serves it instead. - -Wire: extends `draft-lcurley-moq-cluster`, updated in the same PR. - -## Required - -- [Cluster routing](/quest/m2/cluster-routing/README.md) - settles what a cluster link carries diff --git a/quest/m5/ietf-hole-marker.md b/quest/m5/ietf-hole-marker.md deleted file mode 100644 index 022d76b3921..00000000000 --- a/quest/m5/ietf-hole-marker.md +++ /dev/null @@ -1,87 +0,0 @@ -# [L] moq-transport hole markers - -## Goal - -A negotiated moq-transport extension (a new `drafts/draft-lcurley-moq-*` -document) lets a publisher name each group it won't deliver on a SUBSCRIBE, -like moq-lite's SUBSCRIBE_SKIP and SUBSCRIBE_DROP: never produced, or dropped -with its reason. -A relay's copy ingested over moq-transport then knows its holes ("null") -instead of leaving them unknown ("undefined"). Our moq-transport publishers -then answer a multi-group FETCH, and a multi-group draft-22 fill, whenever -the cache knows every group in the range: a local, moq-lite, or -extension-carrying copy. Groups go out in order. End of Non-Existent Range -(`0x8C`) marks only a proven hole: a group never produced, or a -budget-independent drop (a cut, an origin's eviction or expiry). A stale -drop judged under a narrower budget or range, as lite-07's `Update` and the -subscriber's record of that update's terms qualify it, proves nothing for a -wider FETCH. That -group is unknown, so the publisher fills it or the range is refused. Any -other range stays refused, as -[moq-dev/moq#7204](https://github.com/moq-dev/moq/pull/7204) -leaves it. - -A live ordered reader on an extension-carrying SUBSCRIBE stops waiting at a -signalled hole, as it already does on moq-lite with SUBSCRIBE_DROP. Peers -without the extension behave as today. - -## Plan - -Decided with the maintainer on 2026-10-28 (`/quest-plan`, "what's not worth -supporting in IETF"). - -Decision prompts: - -- Define a hole-marker extension: no, since drafts 18 and 22 already have - `0x8C` and `0x10C`; ✅ yes. The marker belongs on the SUBSCRIBE, so that - the cache can be used for FETCH. FETCH's own markers only describe the - answer, not the copy that answers it. -- Scope: ✅ extension plus range FETCH from caches that know every hole, in - m2; extension only; both in m1. - -Decided 2026-10-30 (maintainer, from -[moq-dev/moq#7403](https://github.com/moq-dev/moq/pull/7403)), on detecting -unsignalled holes on a live moq-transport SUBSCRIBE: - -- Unsignalled holes are a moq-transport protocol bug. Until a peer signals - them, an ordered reader with an unlimited budget blocks at an owed hole on - a moq-transport SUBSCRIBE. That's accepted, and documented on - `Ordered`/`max_delay`. -- No FETCH to learn whether a hole will fill: it races the live - subscription. No inference from later groups, and no grace periods. -- Build this extension when an IETF client wants it (see Waiting). - -Only peers that implement the extension benefit, which today means our own -Rust and JS moq-transport stacks. Our own peers talk moq-lite to each other, -so the payoff is third-party adoption. Write the draft so it can be proposed -to the working group. - -Open, for this quest's interview: - -- The carrier: a message on the SUBSCRIBE's request stream (drafts 18, 20, - and 22 give each request its own stream), or a status on a group stream. -- Whether the drop names the terms it was judged under, as lite-07's - SUBSCRIBE_DROP `Update` does in [Drop set](/quest/m1/drop-set.md), so a - stale drop doesn't settle a wider reader. -- How a publisher answering a range walks the drop set's runs in group - order, and where FETCH_OK's End Location falls. - -Test across Rust and JS on drafts 18, 20, and 22, with and without the extension. Draft 20 added 2026-11-03 (maintainer, /quest-plan of the follow-ups from [moq-dev/moq#7704](https://github.com/moq-dev/moq/pull/7704)), since draft 20 joined the covered drafts in [interop coverage](https://github.com/moq-dev/moq/blob/acef90cf0425d9f0e4e699759cede07adfb2ecfb/quest/m1/interop-coverage/README.md). -A range over a copy whose holes are all proven is answered with `0x8C` runs. -A range with an unknown hole is still refused. Regression: an upstream -reports G stale for a narrow subscriber while still holding G; a wider -downstream FETCH covering G gets G, or a refusal, never `0x8C`. Interop with a peer that lacks -the extension is unchanged. - -Public API: none. Wire: a new negotiated SETUP option and its drop message. -Our publishers answer multi-group FETCH and fills over known caches. - -## Waiting - -- IETF clients: a third-party moq-transport implementation asks for hole - markers or would adopt the extension. Check moq-dev/moq issues and the - interop runner's participants for such a request. - -## Related - -- [Ordered reads wait only on owed groups](https://github.com/moq-dev/moq/pull/7403) - the ordered-reader wait a signalled hole ends diff --git a/quest/m5/json-value-diff.md b/quest/m5/json-value-diff.md deleted file mode 100644 index 099b78e56d8..00000000000 --- a/quest/m5/json-value-diff.md +++ /dev/null @@ -1,62 +0,0 @@ -# [M] Benchmark a Value merge-patch diff for moq-json - -## Goal - -Numbers decide whether `moq-json`'s generic serializer diff stays. -`rs/moq-json/src/diff.rs` is about 1,100 code lines (`Differ`, `lockstep`, -`MapDiff`, `Memo`) that diff a `Serialize` value against the last frame. -The candidate replacement is one non-generic `serde_json::Value`-vs-`Value` -RFC 7396 merge-patch diff, ported from `js/json/src/diff.ts` (about 120 -lines). It keeps the same semantics, where a `null` in the new value forces a -snapshot, and passes the shared `rs/moq-json/tests/vectors.json`. - -The quest ends with the chosen variant landed, or with the current diff kept -and the measurements recorded here or in the PR. - -## Plan - -Compare three variants: - -1. The current diff (main). -2. The `Value` diff: serialize `T` to a `Value` once, then diff it against the - previous `Value`. -3. Compression only: deltas off, a full snapshot per frame in the same group, - and group DEFLATE through the track's `with_compression(Compression::Deflate)`. - -Measure each on producer CPU, consumer CPU, wire bytes after DEFLATE, -allocations, and code size (`cargo llvm-lines` on a consumer crate such as -`moq-hls`, plus the `moq-json` line count). Use -`cargo bench -p moq-json --bench codec`, `--bench table` (100 to 20,000 rows, -1%, 10% and 100% changed) and `--bench allocations`, plus -`cargo bench -p moq-stats --bench aggregate`. Run on a quiet host, with a -main-vs-main run first to establish the noise floor. - -Context: - -- The maintainer asked, reviewing - [moq-dev/moq#7400](https://github.com/moq-dev/moq/pull/7400): "why is it so - complicated, are we chasing a dragon?" #7400 already moved the diff to - serialized bytes so it compiles once, at +2–5% on table deltas up to 1,000 - rows and +6–12% at 10,000–20,000 rows. -- Maintainer: "In the past we tried relying on compression only (moq-flate) - and the ratio was about the same, but the performance was different." -- History: [moq-dev/moq#1912](https://github.com/moq-dev/moq/pull/1912) - compared merge plus DEFLATE against DEFLATE only. - [moq-dev/moq#3955](https://github.com/moq-dev/moq/pull/3955) found full - snapshots plus DEFLATE lose up to 15x in bytes once frames exceed DEFLATE's - 32 KiB window, and browsers lack zstd. -- Readers keep `delta()` regardless of the outcome. Deployed producers emit - patches: `moq-stats`, `moq-boy`, `moq-cli report`, JS room metadata, and the - bindings, which default deltas on. -- `drafts/draft-lcurley-moq-hang.md` contradicts itself on deltas: line ~149 - forbids multiple frames per group, while lines ~611 and ~803 allow RFC 7396 - patches after the snapshot. Align it with whatever this decides. -- `moq_json::diff` has no in-repo callers since #7400. With a `Value` diff - it could take `&Value`, or be removed. - -Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): `moq_json::{diff, Diff}` become private before the cut ([moq-dev/moq#8298](https://github.com/moq-dev/moq/pull/8298)), so this work is internal. - -## Related - -- [Compile time audit](/quest/m3/audit-compile-time.md) -- [Artifact size audit](/quest/m3/audit-size.md) diff --git a/quest/m5/ladder/README.md b/quest/m5/ladder/README.md deleted file mode 100644 index ff470703c15..00000000000 --- a/quest/m5/ladder/README.md +++ /dev/null @@ -1,84 +0,0 @@ -# Congestion-aware transcode ladders - -## Goal - -A transcode ladder respects the uplink it publishes over. `moq-transcode` -opens one encoder per demanded rung at its configured maximum and publishes -every rung across one first-mile connection, with no bandwidth input and no -live rate control, so congestion leaves every active rung producing at its -ceiling. - -This is first-mile adaptation, not per-viewer adaptation. Sharing one output -broadcast across several independently constrained output sessions stays out -of the model: one encoder and one catalog bit cannot represent per-session -state. - -## Plan - -Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no named consumer for the -publisher-side ladder. - -The catalog and player half is the rendition `enabled` flag, which replaced the `stalled` -state shipped in [moq#2865](https://github.com/moq-dev/moq/pull/2865): -`enabled: false` means no frames are coming and a viewer must not select the -rendition. Routing, decoder, and presentation identities are split so a -metadata-only change cannot rebuild WebCodecs. - -Decided (2026-10-04): a rung's `enabled` follows its last applied target. It -is disabled, with encoding stopped, when its share falls below its boundary, -and enabled once a target at or above the boundary is applied. Demand loss -alone never changes the flag. - -What remains is the publisher side. The allocator -([moq#2854](https://github.com/moq-dev/moq/pull/2854)) divides a connection's -estimate by `track::Info::priority`, filling a tier before the next sees a -bit and splitting max-min fair within one. A controller that assigns -descending priorities down the ladder gets correct allocation from that -alone. Send order ranks by the subscriber's priority from SUBSCRIBE first -and the publisher's `Info::priority` after it (`Priority::cmp` in -`rs/moq-net/src/priority.rs`, [moq-dev/moq#6142](https://github.com/moq-dev/moq/pull/6142)), so the same number decides what to -produce and, among equal subscriber priorities, what to send first; the -controller only consumes that tiebreak. - - -### Adaptive bands - -`moq_transcode::Rung::bitrate` (`rs/moq-transcode/src/ladder.rs`) stays -the configured maximum and never follows the instantaneous target. For a -rendition with configured maximum `max` and the next lower rendition's -`lower`: - -```text -disable = (max + 2 * lower) / 3 -``` - -The lowest rendition takes `lower = 0`, so its boundary is `max / 3`. An -encoder may adapt within `[disable, max]`; below the boundary the rung is -disabled (`enabled: false`) and stops encoding, and it is enabled again only -once a target at or above the same boundary is successfully applied. Catalog state follows the last target the encoder -*accepted*, not the one the controller requested, so a transient rate-control -failure retains the last applied target rather than lying. - -Start with the shared rate policy's five percent hysteresis, immediate -decreases, and gradual upward ramp (`moq_mux::rate::Control`). -No second re-entry threshold and no dwell timer until measurements show the -catalog state flaps. - -### Non-goals - -Per-viewer or per-session rendition state; rewriting the advertised maximum -bitrate; removing a disabled rung from the catalog; an application-level -`unselectable` state; stall counters in the catalog (those are telemetry, -[#2734](https://github.com/moq-dev/moq/issues/2734)); rebuilding unsupported -encoders on every target change. - -## Required - -- [Controller](/quest/m5/ladder/controller.md) - one controller owns every - rung's share, target, enabled state, and send order -- [Fetch and catalog](/quest/m5/ladder/fetch.md) - uncached FETCH encodes at - the shared applied target, and rung state survives a source catalog refresh - -## Related - -- [#2848](/quest/m5/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - the other sender that reserves but never follows its grant diff --git a/quest/m5/ladder/controller.md b/quest/m5/ladder/controller.md deleted file mode 100644 index a0db6b03ab5..00000000000 --- a/quest/m5/ladder/controller.md +++ /dev/null @@ -1,70 +0,0 @@ -# [L] Ladder controller - -## Goal - -One controller owns every generated rung's share, encoder target, enabled -state, and send order for one output bandwidth domain, so a ladder adapts to -its uplink instead of encoding every live rung at its ceiling, and transport -shedding drops the top of the ladder first. - -## Plan - -Add an optional bandwidth input to the transcode configuration and wire the -CLI's publisher session into it. `transcode` is not stageable -(`rs/moq-cli/src/args.rs`), so it dials its own session -(`rs/moq-cli/src/main.rs`, `rs/moq-cli/src/transcode.rs`) and -that session is the whole bandwidth domain. Supplying no input preserves -today's fixed-rate behavior exactly and never publishes congestion-induced -`enabled` state, which is what keeps this additive. - -The controller subdivides that estimate across the ladder and applies the -band boundary from the [questline](/quest/m5/ladder/README.md), including the -lowest rung's `max / 3` case. `moq_transcode::Ladder` is ascending: `new` -sorts by configured maximum (`rs/moq-transcode/src/ladder.rs`) and -`rungs()` is lowest first, so the next lower rendition the -formula reads is the preceding entry and the lowest rung is the one with -none. - -### One priority for allocation and send order - -Assign descending `track::Info::priority` down the ladder. Every rung is -stamped `PRIORITY.video` today (`rs/moq-transcode/src/rung.rs`, -`rs/moq-transcode/src/lib.rs`). The allocator fills a tier -before the next sees a bit, so that alone protects lower rungs' allocation. - -For send order, consume the publisher-priority tiebreak in `Priority::cmp` -([moq-dev/moq#6142](https://github.com/moq-dev/moq/pull/6142)). The `BitrateUnsupported` fallback leans on it: without it, an -encoder that cannot retune degrades the whole ladder equally instead of -protecting the bottom. A subscriber asking for a higher rendition ahead of a -lower one still gets what it asked for. - -### Keep honest - -- **Requested and applied targets are different numbers.** Catalog state - follows what the encoder accepted. A transient rate-control failure keeps - the last applied target and retries on a later material movement. -- **`BitrateUnsupported` is an explicit fallback, not a silent one.** Mirror - moq-video's handling (`rs/moq-video/src/encode/producer.rs`): such - an encoder keeps its configured maximum, is disabled (`enabled: false`) - whenever the allocation is below it, and is enabled only when the full - maximum fits again. It reclaims no encoder work by design, and it must be visible in - logs and tests rather than pretending the target was applied. -- **An idle rung must be able to recover.** Only demanded rungs consume - allocation, but a rung that loses all demand while disabled cannot be left - permanently disabled. Evaluate its hypothetical share against the current - estimate and active lower-priority reservations, without giving it a real - share or encoding probe traffic. - -Acceptance: one demanded rung reaching its configured maximum on a permissive -uplink; several rungs sharing one uplink with lower ones protected; a -supported rung adapting down, clamping, disabling, and re-enabling without its -advertised maximum moving; the 5 Mbps over 2.5 Mbps boundary landing near -3.33 Mbps; the default 350 kbps lowest rung disabled near 117 kbps; an -unsupported encoder holding its maximum and not recovering early; no -bandwidth input preserving existing behavior exactly; and for send order, -equal subscriber priority where the lower rung wins, conflicting subscriber -priority where the subscriber's order wins, and a custom ladder order. - -## Related - -- [Encoder feedback](/quest/m5/stats-encoder-feedback.md) - viewer stalls for `moq import`; its `moq transcode --echo` leg, split out if revived, feeds this controller diff --git a/quest/m5/ladder/fetch.md b/quest/m5/ladder/fetch.md deleted file mode 100644 index 3fdc63ae06f..00000000000 --- a/quest/m5/ladder/fetch.md +++ /dev/null @@ -1,41 +0,0 @@ -# [M] Fetch and catalog - -## Goal - -An uncached FETCH encodes at the ladder's shared applied target instead of -opening a fresh encoder at the configured maximum, and a source catalog -refresh cannot erase current rung state. - -## Plan - -Two independent leaks of controller state, both cheap to close once the -controller owns it. - -The FETCH path opens a new encoder per requested group at -`Rung::bitrate`: `fetches` and `fetch` -(`rs/moq-transcode/src/rung.rs`) call `encode`, which sets -`config.bitrate = Some(self.info.bitrate)`, so a constrained ladder -still burns full-rate encodes on demand. Make it read the controller's -applied target and participate in the same allocation. A disabled rung stays -manually fetchable, and cache hits are untouched. - -Catalog mutations publish full snapshots -(`rs/moq-mux/src/catalog/producer.rs`). The -[compression migration](https://github.com/moq-dev/moq/pull/7046) removed the HANGZ -sibling; coalesce every rung state change from one -controller iteration into a single publication of each supported catalog, and make a -later source catalog snapshot compose with current generated-rung state -rather than overwrite it. - -Acceptance: a fresh FETCH using the shared applied target while a cache hit -encodes nothing, and one source catalog refresh leaving disabled rung state -intact. - -## Required - -- [Controller](/quest/m5/ladder/controller.md) - there is no shared applied - target to read until the controller owns one - -## Related - -- [On-demand pops](/quest/m3/video-quality/on-demand.md) - grades and fixes cold-start pops in the same fetch encoder this quest retargets diff --git a/quest/m5/latency-ledger.md b/quest/m5/latency-ledger.md deleted file mode 100644 index dd2106cc59b..00000000000 --- a/quest/m5/latency-ledger.md +++ /dev/null @@ -1,58 +0,0 @@ -# [M] A viewer's share of playback latency is reportable, not just measurable in a test - -## Goal - -A running viewer reports where its share of the audio delay went (the jitter -buffer and the output device) through its `.echo` feedback snapshot, in both -languages. The numbers a user reads when debugging their own latency are the -numbers the harness grades, because they come from the same place. Decode and -render stay internal; publisher and network stages, and an end-to-end total, -wait for a clock that spans the whole path, and none exists today. - -## Plan - -The audio quality harness (`test/audio-quality/`) landed on ad-hoc debug -probes, which was the right trade to get it running. This quest promotes them. - -- Decided 2026-10-08: scope to the viewer's stages. No clock spans - publisher to viewer, so the harness reports end-to-end as null. -- Decided 2026-10-30: wait for both feedback reporters (see Required), then - fill the fields from each reporter's tally rather than adding a second - per-player readout the reporters would have to fold in later. -- Decided 2026-10-30: replace the producer-less scalar `latency` on - `hang::echo::Rendition` (`rs/hang/src/echo.rs`), `Echo.RenditionSchema` - (`js/hang/src/echo.ts`), and `ViewerRendition` in - `drafts/draft-lcurley-moq-hang.md` with an object of stages: - `latency: { jitterBuffer?, decode?, render?, device? }`, each integer - milliseconds and absent when unmeasured. The schema is unreleased, so this - breaks no one. -- Decided 2026-10-30: export only `jitterBuffer` and `device`. The decoder - runs inside the jitter-buffer span, so `decode` is zero while the ring holds - anything, and `render` is a fixed ring-to-graph handoff (one 128-frame - quantum in the browser); neither is something a viewer can act on. They stay - unmeasured in the harness schema. -- Decided 2026-10-30: leave the publisher snapshot (`rs/hang/src/stats.rs`) - alone. Every viewer stage belongs in feedback, and publisher stages wait for - a spanning clock. -- Both languages, matching names, per the repo's cross-language rule. -- Switch the harness over, deleting the probes it replaces. Today - `test/audio-quality/clients/js/src/probe.ts` reads `sync.out.delay` and - `AudioContext.outputLatency + baseLatency`, and natively `moq play --metrics` - writes the presentation target. A ledger with no consumer is how this drifts - from reality. -- Keep the harness's terms: one duration unit, every timestamp on a named - clock, and stages as exclusive spans that cannot both claim the same - milliseconds. Inherit those from the schema rather than restating them, - so the sum-to-end-to-end identity (with its named `unaccounted` - remainder) can be added once a spanning clock exists. - -Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): hang echo's producer-less `latency` is deleted before the cut ([moq-dev/moq#8298](https://github.com/moq-dev/moq/pull/8298)), so this adds its measurement additively. - -## Required - -- [Rust reporters](/quest/m3/stats/rust.md) - `moq play --echo` publishes the feedback snapshot these stages join - -## Related - -- [QoS](/quest/m3/qos/README.md) - relay-side health, the same idea from the other end -- [Media stats](/quest/m3/stats/README.md) - the hang stats and `.echo` snapshots these stages join diff --git a/quest/m5/link-quality.md b/quest/m5/link-quality.md index 984f9967105..d1acd3d8c94 100644 --- a/quest/m5/link-quality.md +++ b/quest/m5/link-quality.md @@ -28,9 +28,7 @@ the default and measured cost is opt-in, so the line ships without it. opt-in on links the operator chooses. - A lossy-link fixture over the mock transport with mocked time. -[Route health](/quest/m5/route-health/README.md) is separate: it detects -stalled epoch-bound track delivery using metadata-only standby observations, -without repricing the whole network from local health evidence. +Detecting stalled epoch-bound track delivery is out of scope. Public API: a per-link way to ask for measured cost in the peer entry. Wire: none. diff --git a/quest/m5/lite05-subscribe-end.md b/quest/m5/lite05-subscribe-end.md deleted file mode 100644 index e1bd9cc7225..00000000000 --- a/quest/m5/lite05-subscribe-end.md +++ /dev/null @@ -1,32 +0,0 @@ -# [S] Rust and JS end a lite-05 track the same way after an inclusive SUBSCRIBE_END - -## Goal - -On lite-05, when a publisher from older `@moq/net` (0.1.3 to 0.1.9) sends -the inclusive SUBSCRIBE_END that `finish_at` refuses and the tail then -settles, Rust and JS subscribers both end the track cleanly, as a current -lite-05 publisher's SUBSCRIBE_END does. A test in each language asserts that -clean end for the settled case. - -## Plan - -Decided 2026-10-31 (user, /quest-plan of the follow-ups from the 2026-10-31 /quest-complete run), from [moq-dev/moq#7295](https://github.com/moq-dev/moq/pull/7295) (merged). -Milestone m3: a narrow legacy case, `@moq/net` 0.1.3 to 0.1.9 only. - -[moq-dev/moq#7295](https://github.com/moq-dev/moq/pull/7295) aligned the end signal (SUBSCRIBE_END on lite-05+, the FIN on -lite-01..04) and made a mid-tail session death abort in both languages. One -mismatch is left: with that inclusive SUBSCRIBE_END, Rust still ends the -track through the FIN (`ServeEnd::Finished` in -`rs/moq-net/src/lite/subscriber.rs`) once the tail settles, while JS only -releases it. Match what a current lite-05 publisher's SUBSCRIBE_END -produces, a clean end, so JS changes and Rust keeps its behavior. Rust's -`a_subscribe_end_below_a_received_group` -(`rs/moq-net/src/lite/subscriber.rs:3885` at be39188000) already asserts -Rust's clean end; its JS twin (`js/net/src/lite/tail.test.ts:392`) -checks only that `reader.closed` is `null`, which a release also gives, so -make it assert the finish. Extend [moq-dev/moq#7295](https://github.com/moq-dev/moq/pull/7295)'s -`bare-fin` interop exchange (`test/interop/bare-fin.ts`, `just test -bare-fin`) with the inclusive encoding rather than the real-QUIC matrix, -for the reason [moq-dev/moq#7295](https://github.com/moq-dev/moq/pull/7295) gives. - -Public API: none. Wire: none; behavior only. diff --git a/quest/m5/mkv-input-coalesce.md b/quest/m5/mkv-input-coalesce.md deleted file mode 100644 index 4211865046f..00000000000 --- a/quest/m5/mkv-input-coalesce.md +++ /dev/null @@ -1,32 +0,0 @@ -# [S] Byte-at-a-time MKV input imports as fast as chunked input - -## Goal - -The MKV importer fed one byte at a time is no slower than before -[moq-dev/moq#7234](https://github.com/moq-dev/moq/pull/7234) (about 81 µs -on its `mkv-chunks/1` bench, 155 µs after it), with the same memory bound: -readers lag the input by at most a small fixed buffer, so a block larger -than it stays readable before the block completes, and the importer retains -no more than that buffer, a split element header, and the fields it reads. - -## Plan - -Decided 2026-10-31 (user, /quest-plan of the follow-ups from the 2026-10-31 /quest-complete run), from [moq-dev/moq#7234](https://github.com/moq-dev/moq/pull/7234). -Milestone m3: real inputs arrive in 1500-byte or larger chunks, where [moq-dev/moq#7234](https://github.com/moq-dev/moq/pull/7234) -is as fast or about 2x faster. - -[moq-dev/moq#7234](https://github.com/moq-dev/moq/pull/7234) streams each frame through `container::Producer::open`/`commit`, -so each input call's slice of a block payload becomes its own readable -write on the moq-net frame; fed byte by byte, that is one write per byte. -Already-larger chunks write their whole span at once, so only tiny calls -need help. Hold payload bytes in a small fixed buffer and write them when -it fills, when the payload ends, or on `finish()`/abort. Settle the bound -(a few KiB, well under one moq-net segment): it caps both the importer's -extra retention and how far readers lag the input. A payload shorter than -the buffer is therefore readable only once it ends; that delay is bounded by -the buffer and is the point of coalescing, so no flush per input call. - -Measure with [moq-dev/moq#7234](https://github.com/moq-dev/moq/pull/7234)'s `mkv-payloads` and `mkv-chunks` benches in -`rs/moq-mux/benches/containers.rs`, and keep its retention tests passing. - -Public API: none. Wire: none. diff --git a/quest/m5/msf-publish-tracks.md b/quest/m5/msf-publish-tracks.md deleted file mode 100644 index 22624c59df0..00000000000 --- a/quest/m5/msf-publish-tracks.md +++ /dev/null @@ -1,21 +0,0 @@ -# [M] MSF feedback tracks - -## Goal - -`--report` and `--echo` work under `--catalog-format msf`: a soliciting -catalog's `echo` maps onto an MSF `publishTracks` entry (draft-ietf-moq-msf -§5.1.5), and a viewer publishes the hang `.echo` snapshot there. Start once a -consumer asks. - -## Plan - -Raised in [#5360](https://github.com/moq-dev/moq/issues/5360). Until then the -[media stats schema](/doc/concept/stats.md#media-reports) leaves both sections out of -the MSF catalog. `moq export --echo` refuses `--catalog-format msf`, and the -[Rust reporters](/quest/m3/stats/rust.md) quest's `moq play --echo` will -(decided 2026-10-12). - -Open: how the entry names the hang payload, since MSF fixes its packaging -values in the draft; and whether to add a CMCD v2 Event Mode encoding -(draft-wilaw-moq-cmcd-event-timeline) of the overlapping fields (stalls, -dropped frames, latency, throughput, errors) for consumers that ingest CMCD. diff --git a/quest/m5/msfts-convergence.md b/quest/m5/msfts-convergence.md deleted file mode 100644 index a8b70c7d83d..00000000000 --- a/quest/m5/msfts-convergence.md +++ /dev/null @@ -1,43 +0,0 @@ -# [M] MPEG-TS lane converges with MSFTS ES-level carriage - -## Goal - -A subscriber author can map this repository's demultiplexed TS lane -(access units, Hang catalog `mpegts` section) onto MSFTS ES-level carriage -without guessing. Transporting TS verbatim is out of scope here: -`moq import ts --passthrough` carries it in an `m2ts` catalog section that -[the TS draft](/drafts/draft-lcurley-moq-mpegts.md) maps onto MSFTS's track -fields. - -## Plan - -Decided in the 2026-09-30 audit: moved from m4 and the msfts#33 gate removed. -msfts#33 closed on 2026-09-28, answered by msfts#36 (merged 2026-09-24), and -egress moved to msfts#37 (closed). Two differences remain: - -- **Program tables.** PAT/PMT information lives in the Hang catalog's - `mpegts` section; supported SI already uses tracks. Map these mechanisms - separately to MSFTS's table tracks instead of saying all tables live in - the catalog. -- **ES units.** MSFTS `es-packets` (draft-gregoire-moq-msfts-02) carry the - TS packets of one PID. Here decoded media carries access units, and - undecoded PES carries the whole PES packet at its source placement - ([`pesPacket`](/drafts/draft-lcurley-moq-mpegts.md)). Document the - mapping between them. - -Decided in the 2026-10-11 audit: keep the semantic lane and raw fallback -distinct. Whole SPTS maps to `unmodified-program`, whole MPTS to -`unmodified-multiplex`. MSFTS `per-program` extraction and `es-packets` -(which omit null packets) are not byte-identical whole-input carriage. -The fallback will not split PIDs or add source-position reconstruction -metadata. Use [the current draft](https://datatracker.ietf.org/doc/html/draft-gregoire-moq-msfts) -to document both semantic and scheduling differences; shared terminology -does not establish wire interoperability. - -Update `drafts/draft-lcurley-moq-mpegts.md` and `doc/concept` with whatever -lands. [#4577](https://github.com/moq-dev/moq/pull/4577) (per-ES access -units at export) has merged, and [#4579](https://github.com/moq-dev/moq/pull/4579) -(export on the mux rate) closed in favour of the T-STD export -([#4645](https://github.com/moq-dev/moq/pull/4645)). -[#4580](https://github.com/moq-dev/moq/pull/4580) (per-program SI) merged on -2026-10-01 and touches the same area. diff --git a/quest/m5/nvenc-av1.md b/quest/m5/nvenc-av1.md index af42494840e..ddd9e649d23 100644 --- a/quest/m5/nvenc-av1.md +++ b/quest/m5/nvenc-av1.md @@ -27,5 +27,4 @@ Public API: additive. Wire: existing AV1 codec signaling. ## Related -- [Main10](/quest/m5/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md) - the other half of #2147 - [GPU CI](/quest/m3/gpu-ci.md) - the current runner lacks AV1 NVENC diff --git a/quest/m5/obs-decode-linux.md b/quest/m5/obs-decode-linux.md deleted file mode 100644 index b610c865d28..00000000000 --- a/quest/m5/obs-decode-linux.md +++ /dev/null @@ -1,16 +0,0 @@ -# [XL] Present native moq-video decoded frames in OBS on Linux - -## Goal - -At least one supported Linux hardware decoder delivers frames to OBS without CPU readback. Other machines keep working through the explicit CPU delivery fallback. - -## Plan - -- Probe decoder output and OBS EGL/GL import compatibility before promising broad support. This checkout has NVDEC and a VAAPI decode backend; audit their current codec and surface support before extending either. Choose an available native path based on actual hardware evidence and report which drivers/devices were tested. Add its `MoqVideoSurface` variant and lift the Linux refusal of `MoqVideoDecoderOutput.surface` in moq-ffi's `MoqVideoConsumer::subscribe` together, with that proof. -- For DMA-BUF, validate device, modifiers, planes, stride, color conversion, fd ownership, and implicit/explicit synchronization. For CUDA output, establish a real graphics interop path or GPU copy into importable storage. A DMA-BUF type or OBS import function alone does not prove the decoder allocation can be presented. -- Bound imported allocations and retain them through GPU completion. Handle device loss, resize, stale frames, and failed imports with automatic CPU fallback shown in Stats. Never use an FFmpeg fallback. -- Verify pixels, timestamps, latency, no CPU readback, cancellation, resource growth, and fallback on real Linux graphics stacks. Keep VAAPI and NVIDIA validation results separate; one driver passing is not platform-wide proof. - -## Required - -- [Video source replacement](/quest/m3/obs-moq-video/source.md) - native frame contract and fallback lifecycle diff --git a/quest/m5/obs-decode-windows.md b/quest/m5/obs-decode-windows.md deleted file mode 100644 index 5b41fdba334..00000000000 --- a/quest/m5/obs-decode-windows.md +++ /dev/null @@ -1,15 +0,0 @@ -# [L] Present moq-video decoded textures in OBS on Windows - -## Goal - -Supported Windows hardware decoders deliver GPU frames to the OBS source without CPU readback, with automatic CPU fallback and an accurate Stats indicator. - -## Plan - -- Extend the native frame contract from the source replacement using moq-video's D3D11 texture representation. Add the `MoqVideoSurface` variant and lift the Windows refusal of `MoqVideoDecoderOutput.surface` in moq-ffi's `MoqVideoConsumer::subscribe` together, with hardware proof. Verify the decoder adapter/device, OBS graphics device, texture format, and sharing capabilities. Start with Media Foundation's actual native texture path; do not infer CUDA/D3D interop from handle types. -- Import compatible allocations or GPU-convert/blit into an OBS-compatible bounded pool. Model fences/keyed mutexes, render-thread ownership, device removal, resize, and release after GPU completion. An AddRef prevents object destruction but not decoder pool reuse. -- Test decoded color/timestamps and no-readback traces on real Windows hardware. Include incompatible adapters, hybrid GPU, unsupported formats, import failure, and stream restart. Fallback must preserve timing and expose its reason without silently reintroducing FFmpeg. - -## Required - -- [Video source replacement](/quest/m3/obs-moq-video/source.md) - shared native frame ownership, source rendering, and CPU fallback diff --git a/quest/m5/obs-linux-gpu.md b/quest/m5/obs-linux-gpu.md deleted file mode 100644 index 547cd2402ec..00000000000 --- a/quest/m5/obs-linux-gpu.md +++ /dev/null @@ -1,26 +0,0 @@ -# [XL] Export OBS GPU frames for moq-video on Linux - -## Goal - -A supported Linux OBS graphics/encoder combination publishes composited video without CPU readback and reports unsupported combinations explicitly. - -## Plan - -In m5 until the OBS encoder ships and a Linux user reports CPU readback as -the bottleneck. - -- Start with an API feasibility probe. OBS exposes DMA-BUF import in `graphics.h`; that is not proof its compositor textures can be exported. Determine whether EGL/GL allocation export is available, or whether an upstream OBS hook or an encoder-owned exportable render target is required. -- moq-video encodes a `Surface::DmaBuf` on VAAPI without a download, and scales one through VPP (moq-vaapi 0.1.1). This quest still has to turn an OBS compositor texture into a DMA-BUF that import accepts. -- Negotiate DRM device, fourcc, plane offsets/strides, modifiers, and synchronization. Reuse `Surface::DmaBuf` and the hardware encoder's real import path, retaining allocation ownership until completion. A borrowed fd or an importable packed RGB texture does not prove the encoder accepts NV12 on the same device. -- Prefer direct import; otherwise GPU-convert into exportable NV12 surfaces. Document and measure each GPU copy. Keep CPU staging as a visible fallback, not as the successful accelerated result. -- Validate at least one Intel/AMD VAAPI path on hardware before promising broad support. Scope NVIDIA/CUDA interoperability separately if it needs another allocation or synchronization strategy. Test unsupported modifiers, multi-plane buffers, fd closure, cancellation, device loss, resize, and repeated pool reuse. -- Capture API traces/copy counts and decoded pixel/timestamp checks with a real subscriber. Compare latency percentiles, utilization, and resource growth against the CPU adapter and existing OBS encoder at matched settings. - -## Required - -- [Encoder adapter](/quest/m3/obs-moq-video/adapter.md) - frame ownership, queue policy, packet output, and comparison baseline - -## Related - -- [Video hardware validation](/quest/m5/video-hardware.md) - native input and encoder acceptance need hardware evidence -- [VA-API encodes an external Vulkan image](/quest/m3/vaapi-vulkan-import.md) - explicit sync for an external DMA-BUF, and the public `DmaBuf` constructor from #4975 diff --git a/quest/m5/obs-macos.md b/quest/m5/obs-macos.md deleted file mode 100644 index b9ff0483bfe..00000000000 --- a/quest/m5/obs-macos.md +++ /dev/null @@ -1,16 +0,0 @@ -# [L] Feed OBS GPU frames into moq-video on macOS - -## Goal - -An OBS compositor frame reaches moq-video's VideoToolbox encoder without a GPU-to-CPU-to-GPU round trip, with bounded retained resources and correct color and timing. - -## Plan - -- Inspect OBS's OpenGL compositor, `encode_texture2`, and mac-videotoolbox input path. Determine whether the output allocation is IOSurface-backed and exportable. OBS's encoder currently copies CPU planes into its own pixel buffer; a CVPixelBuffer in moq-video alone does not remove that upstream readback. -- Prefer retained IOSurface/CVPixelBuffer storage in the format VideoToolbox accepts. Otherwise prototype GPU color conversion/blit into an IOSurface-backed NV12 pool. Specify GL/Metal/CoreVideo interop, graphics-context thread affinity, completion fences, and when OBS may recycle the source. -- Reuse the native PixelBuffer surface and the moq-video VideoToolbox backend. Retain the destination until encoding completes, including dropped submissions and cancellation. Bound the pool and handle resolution/HDR changes and device failure. -- Verify no CPU readback using GPU/API traces and copy counters. Compare direct import or GPU blit against the CPU baseline at 1080p60 and 4K where supported. Check decoded color bars and moving timestamps, latency percentiles, audio sync, stop/restart, and long-running pool reuse on Apple hardware. - -## Required - -- [Encoder adapter](/quest/m3/obs-moq-video/adapter.md) - frame ownership, queue policy, packet output, and comparison baseline diff --git a/quest/m5/obs-windows.md b/quest/m5/obs-windows.md deleted file mode 100644 index ac09644bf4c..00000000000 --- a/quest/m5/obs-windows.md +++ /dev/null @@ -1,23 +0,0 @@ -# [L] Feed OBS D3D11 frames into moq-video - -## Goal - -The moq-video OBS encoder consumes compositor output through D3D11 without CPU staging, and releases every shared texture and synchronization primitive correctly. - -## Plan - -- Inspect OBS `encoder_texture` shared handles and `encode_texture2` lock_key/next_key semantics. Record whether the source is packed RGB or split NV12 planes, its adapter LUID, and the lifetime OBS guarantees after the callback returns. -- Reuse the native D3D11 surface where the encoder accepts the same device and format. Otherwise GPU-convert/blit into a bounded encoder-owned NV12 pool before returning the OBS synchronization key. An AddRef alone does not prevent OBS from overwriting pooled pixels. -- Audit keyed mutex/fence sequencing, asynchronous completion, incompatible adapters, software fallback, resolution changes, and device removal. Start with Media Foundation, which accepts D3D11 surfaces. The current NVENC backend is Linux-only and directly imports CUDA surfaces there; Windows NVENC/D3D11 support is separate backend work. Do not infer interoperability from both APIs accepting a texture handle. -- Measure and map the encoder presets on Media Foundation while on the - hardware. Today `applied()` reports "AVLowLatencyMode requested, - unconfirmed" for every preset, because a refused knob is only logged and - the MFT is configured on the first frame. Make low-latency mode - confirmable (read it back, or fail when it is refused) so `Applied::preset` - can name a preset, and give Balanced and Quality distinct controls where - the MFT has them. -- Trace readback and GPU copy counts on real Windows hardware. Verify pixels and A/V timestamps with a subscriber, compare latency and utilization to the CPU baseline, and exercise cancellation while textures remain in flight. Include hybrid-GPU and device-mismatch rejection where available. - -## Required - -- [Encoder adapter](/quest/m3/obs-moq-video/adapter.md) - frame ownership, queue policy, packet output, and comparison baseline diff --git a/quest/m5/origin-front-parks.md b/quest/m5/origin-front-parks.md deleted file mode 100644 index 0095f7524db..00000000000 --- a/quest/m5/origin-front-parks.md +++ /dev/null @@ -1,58 +0,0 @@ -# [S] An unroutable request waits on the front, not in a retry loop - -## Goal - -`origin::Consumer::routed_broadcast` retries: it registers a watch on the -path, asks, and on `Unroutable` waits for the covering routes to move. The -wait lives beside the fronts the driver runs rather than in them. The watch -is path-scoped: unrelated table changes do not re-ask the path, and a path -without coverage fails before minting a front. A covering handler that -refuses with `Unroutable`, however, ends its front; each subsequent covering -change re-asks the path and mints another front. A request for an unroutable path should be -able to mint a front that waits for coverage, and the loop should go away. - -## Plan - -The obstacle, and the reason #3901 rejected this as an alternative, is that -fronts are shared per path. A front that parks would park every requester at -that path, including `request_broadcast`, whose whole contract is a verdict -now. So the disposition has to travel with the requester rather than the -front: `request_broadcast` resolves the current verdict at once without -parking, while `routed_broadcast` stays registered until its route completes. -The front ends only once every parked requester has been handled, so one -requester's disposition never ends another's wait. - -Decided 2026-10-08: benchmark first. Build the parked front only if the -re-mint shows as a real slope; the same benchmark then shows the replacement -is cheaper. A measured no-win deletes this quest. - -Pending: whether to park is undecided until the benchmark has been timed. No -timed results exist yet; the next step is the quiet-host measurement below, -then either the parked front or deleting this quest. - -The `origin/viewer_*` benches do not cover the retry loop. -`origin/unroutable_churn` sweeps 0, 1, 32, and 256 -requesters against 1 and 32 repricings after a covering handler refuses. -Shared and distinct paths separate requester fan-out from front count; -unrelated repricings and zero requesters provide controls. Each change is -driven through refusal and back to waiting, without sleeps or spawned tasks, -polling only the requests a change woke so harness polling does not scale with -requesters; unrelated repricings assert they wake none. -It runs under the existing Rust benchmark nightly. - -Measure repeated A/A runs on a quiet host before choosing whether to park. -The benchmark asserts each distinct path still reaches its handler after a -covering change, so it can also measure parking without removing those -legitimate attempts. Record host load, CPU affinity, compiler/profile, and -per-change cost alongside the control cases. - -A parked front must not retire: a front nobody holds and nobody reads ends, -but only once it serves from a source with no route request pending -(`Front::idle` in `rs/moq-net/src/model/front.rs`). - -Public API: no signature change expected. `routed_broadcast` and -`request_broadcast` keep their contracts; only where the waiting happens -changes. - -Fronts are keyed by effective exclusion (`Horizon::effective`), so viewers -share them. diff --git a/quest/m5/performance-survey/README.md b/quest/m5/performance-survey/README.md deleted file mode 100644 index 38f8b29c70a..00000000000 --- a/quest/m5/performance-survey/README.md +++ /dev/null @@ -1,221 +0,0 @@ -# Performance survey follow-ups - -## Goal - -Validate the performance risks found in the 2026-10-22 source audit with -benchmarks, then remove costs that matter to real consumers. A measured -no-win closes a quest with evidence; a suspicious loop alone does not justify -an optimization. Each child is independently landable. - -This epic's remaining work is to reconcile the children's measurements into -the recurring performance audit: what mattered, what did not, and which -nightly series now protect the relevant workload. - -## Plan - -Requested on 2026-10-22: an extensive performance audit and quests requiring -benchmarks to validate findings. Audited main -[`1d43c096e044`](https://github.com/moq-dev/moq/commit/1d43c096e04431bfc87d807ce47a546df8017475). -These are source-supported hypotheses, not new measured regressions or -promised speedups. General optimization stays in m4 under the existing -milestone policy. Do not change API, wire, scheduling policy, or retention -contracts just to improve a number; bring a necessary contract change to the -maintainer with the measurement first. No new user guide is needed for this -planning change; implementations update documentation they make stale. - -The follow-up audit on main -[`d44813cb703b`](https://github.com/moq-dev/moq/commit/d44813cb703bf0d5366266ae8206f794856c69f8) -adds memory lifetime, idle/churn scaling, kernel mechanisms and settings. -These additional findings are source-supported; no new memory or kernel -benchmark result is claimed. - -### Benchmark contract for every child - -- Reproduce the suspected cost in the production path before changing it. - Sweep the dimensions named in the child independently, including both - publisher and subscriber axes for fan-out. Keep useful delivered work - comparable and verify payloads, ordering, lifecycle, and timing semantics. -- Retain baseline and candidate revisions, exact commands, raw samples, - toolchain, machine, load, and build configuration. Use paired alternating - runs and an A/A control to distinguish a gain from measurement noise. - Report absolute cost and normalized cost, not only percentage changes. -- Attribute CPU work with profiles or instruction/operation counts; measure - allocations, copied bytes, retained memory, and tail latency where relevant. - Instruction counts do not measure blocking or prove end-to-end throughput. - Setup and teardown boundaries must match between variants. -- For memory, include cold start, burst, quiet, repeat burst and teardown. - Separate logical cache/flow-control charges, live allocations, allocator - active/resident pages, virtual retained mappings and kernel socket memory. - RSS alone cannot establish a leak or identify its owner. Record allocator, - profiling mode and cgroup memory pressure. Only investigate allocator decay, - arenas or background purging after application-owned retention is attributed; - compare reclaim latency and CPU/fault cost on reuse. Reuse the phases in - [heap profiling](/bench/profile.py). The - [jemalloc statistics definitions](https://jemalloc.net/jemalloc.3.html) - distinguish allocated, active, resident and retained memory. -- Measure JS changes in a real browser with the existing browser harness. - Bun operation counts can demonstrate an algorithmic slope but cannot stand - in for browser latency, GC, native copies, or hardware behavior. -- Network performance uses a rate below offered media bitrate behind a deep, - finite queue whose overflow also drops packets. Random loss is useful for - correctness only. Report delivery and latency beside CPU so doing less work - cannot look like an improvement. -- Extend the existing benchmark harnesses and schedule each new benchmark - at least nightly. Keep timing out of the merge gate. Fast deterministic - correctness/complexity checks may gate; no arbitrary speedup threshold. - Link the nightly command and retained report in the implementation PR. -- Land an optimization only when the measured consumer benefit justifies its - complexity and memory tradeoffs. Otherwise retain the useful benchmark and - record why the implementation was left alone. - -For settings sweeps, record effective values, not only requested ones. -[Resolved client defaults](/rs/moq-tokio/src/quic.rs) currently allow 10,000 -streams per direction, 128 MiB connection receive credit, 4 MiB per-stream -credit and 16 MiB send credit. [Relay peer overrides](/rs/moq-relay/src/limits.rs) -allow 100,000 streams and 640 MiB each of connection receive and send credit. -Standalone backend defaults differ again; benchmark the effective settings -of the actual consumer. These are limits, not per-connection allocations. -Include idle connections and stalled -readers as well as high-bandwidth, high-RTT relay links before recommending -smaller windows. Receive leases ([moq-dev/moq#5878](https://github.com/moq-dev/moq/pull/5878)) own budget -correctness; settings must preserve useful bandwidth-delay product and -failover behavior. The keep-alive already derives from the negotiated idle -timeout, so leave timer policy alone. Do not add a generic tuning surface without a measured consumer. - -Reuse [the benchmark harness](/bench/README.md). Criterion's -[timing-loop guidance](https://bheisler.github.io/criterion.rs/book/user_guide/timing_loops.html) -explains setup/drop boundaries; the -[WebCodecs resource model](https://www.w3.org/TR/webcodecs/#resources) -means removing a JS copy still requires measuring native resource lifetime. -Neither source establishes a bottleneck in this repository. - -### Evidence and coverage - -The audit inspected Rust model/runtime/QUIC paths, JS transport/playback/ -publish paths, media import/export, auth, storage, bindings and benchmark -orchestration. It did not run the full release comparison, real-browser -performance suite, GPU/platform codecs, or every generated wrapper. Those -remain with their existing owners. The recurring audit is not completed by -this source survey. - -UDP socket queues closed as a measured no-win: the 8 MiB request stays, -with no new setting. `benchmark_socket_queues` (moq-uring, nightly) showed -loss follows the kernel queue against worker stalls, while pool depth, flows -and the receive path did not change it. A bigger queue costs delay only -while a worker is overloaded and the queue sits full. Relay shard sweeps at -up to 256 connections saw no socket drops, with the sampled peak queue under -1% of the granted 16 MiB. The relay sampler now records per-socket drops, -granted buffers and queued bytes (`udp_*`). - -An operation-count probe imported the actual JS `bandwidth.allocate`, counted -`Want.priority` getter reads, and called it for every reservation, as -`Allocator.#publish` does. With one tier, 16/64/256 reservations caused -512/8,192/131,072 reads, exactly 2N². With distinct tiers, 16/64 caused -6,952/438,944 reads. Nix Bun 1.4.2 was used; no browser speedup is claimed. -[moq-dev/moq#7521](https://github.com/moq-dev/moq/pull/7521) divides once per -change in both languages. At 64 reservations in one tier, an estimate change across -every observer fell from 4.5M to 98K instructions and from 901 to 4 allocations in -Rust, and from 146 to 46 µs in Chromium. The `bandwidth/grants/*` Criterion groups -and the `bandwidth` JS and browser micro benchmarks run nightly. - -[Resume identity history](https://github.com/moq-dev/moq/pull/7514) found, in -Chromium after cache age-out, that a JS front's first-seen track record kept -every route that first answered a name reachable: 32 routes of churned names -left 31 sessions, transports and broadcast handles per front (7.7 MB of JS heap -for 8 fronts reading 8 names by lookup). Recording the answering source by id -releases them; the `resume-history` browser fixture now fails on any retired -route still reachable. - -`python3 sh/gh/nightly.test.py NightlyTest.test_every_cargo_bench_target_runs_nightly` -reproduced the missing `moq-archive/producer` selection. The existing -[CI audit PR](https://github.com/moq-dev/moq/pull/6266) already fixes it. -No duplicate quest or workflow edit belongs here. - -Cached JS group joins mattered. In Chromium 156, a subscriber joining 2,048 -retained groups ran about 2.1M sort comparator visits and took 12-18 ms; an -arrival into 8 subscribers' 2,048-group unread backlogs took about 100-113 µs. -Ordered insertion removed every sort: the same join took 0.5-2 ms and the -arrival 9-11 µs. Those original timings used a whole-run frozen clock; the -fixture now expires each shape outside timing so completed tracks cannot -accumulate through prune timers. The original whole-run GC totals are withdrawn. -The `js/replay` nightly series and the browser smoke's `replay.json` protect it. - -### Kernel and placement assessment - -- Already implemented in [moq-uring](/rs/moq-uring/README.md): multishot - receive, provided buffers, GRO/GSO, deferred/cooperative task running, - coalesced futex wakes and per-worker CID-steered sockets. Measure these - with existing ablations before adding another mechanism. -- [Ring submission setup](/quest/m5/3199-moq-uring-remove-sq-indirection-and-per-enter-ring-fd.md) - and [completion batching](/quest/m5/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md) - already own the small ring experiments. Batching must preserve deadlines - and latency tails, not merely reduce syscalls. -- [Zero-copy sends](/quest/m5/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md) - need physical-NIC evidence: the previous loopback prototype lost 6-9% - while exercising copy fallback. Deferred completion ownership, pinned - memory and CQ pressure are costs to measure, not free benefits. - [QUIC I/O ownership](/quest/m5/quic-io-boundary.md) owns the buffer seam. -- Extend [worker defaults](/quest/m4/perf/shard-default.md) with NUMA, SMT, - NIC queues and CPU quotas. Application CID steering does not establish - matching NIC/softirq locality; see the Linux - [network scaling guide](https://docs.kernel.org/networking/scaling.html). -- Linux [io_uring zero-copy receive](https://docs.kernel.org/networking/iou-zcrx.html) - describes a TCP receive path with hardware header/data split and dedicated - queues. It is not evidence of a drop-in optimization for this UDP path. - Confirm transport, hardware and minimum-kernel support before a future trial. -- NAPI busy polling and registered wait arguments were explicitly dropped in - [Perf](/quest/m4/perf/README.md). Do not reopen them without new profiling - evidence. SQPOLL, huge pages and blanket page locking likewise have no - demonstrated need here; they can exchange CPU or reclaimable memory for - lower latency. Incremental provided-buffer consumption is deliberately - unsuitable for the current multishot `recvmsg` tail behavior. - -### Existing ownership and deliberately deferred work - -- [Release performance](/.github/release-perf.md) records the completed main - against release comparison for this cut, including the sparse read slope, - resume duplicates, idle GC, stats drain, FETCH fan-out, JS frame regressions, - and paired comparison correctness. The - [performance audit](/quest/m3/audit-perf.md) repeats it before later cuts. -- [Perf](/quest/m4/perf/README.md) owns measured channel contention, relay - allocations, ingest batching, worker quiescence and runtime selection. -- The 2026-10-22 release audit bounded the media - reorder queues in [moq-dev/moq#6453](https://github.com/moq-dev/moq/pull/6453) - and fixed QMux copying in - [moq-dev/moq#6381](https://github.com/moq-dev/moq/pull/6381). The MKV - importer's replay of accumulated input before those queues was removed by - [moq-dev/moq#6908](https://github.com/moq-dev/moq/pull/6908) and - [moq-dev/moq#7234](https://github.com/moq-dev/moq/pull/7234); the - measured no-win is in [moq-dev/moq#7515](https://github.com/moq-dev/moq/pull/7515), - and the nightly `mkv-chunks` and `mkv-payloads` series cover the slope. -- [Binding bytes](https://github.com/moq-dev/rust2/blob/main/quest/m1/ffi-bytes.md), - [foreign polling](https://github.com/moq-dev/rust2/blob/main/quest/m1/ffi-poll-protocol.md), - [Kotlin calls](https://github.com/moq-dev/rust2/blob/main/quest/m1/kt-ffi-calls.md), - [NVENC pooling](/quest/m5/nvenc-pool.md), and - [watch worker planning](/quest/m3/plan-watch-worker.md) retain their scopes. -- [Route wakes](/quest/m4/route-wakes.md) and - [front parking](/quest/m5/origin-front-parks.md) own discovery scans/wakes. -- The [recurring audit](/quest/m3/audit-perf.md) retains real congestion- - controller/loss-recovery coverage, broader importer/container coverage, - and publish Fanout/audio-ring profiling. QUIC protocol microbenchmarks use - `Unlimited`; their numbers cannot establish controller performance. Expand - reassembly flight/reordering coverage there before proposing another index. - [BBR study](/quest/m5/quic-bbr-study.md) owns controller behavior. -- The archive consumer replaced the timeline reader; benchmark it when - revisiting archive reads. - -## Required - -- [Task capacity after bursts](/quest/m5/performance-survey/task-capacity.md) - memory a task set keeps after peak occupancy subsides -- [QUIC send-group capacity](/quest/m5/performance-survey/send-groups.md) - memory the scheduler's send-group slab keeps after subscription churn -- [Cache metadata](/quest/m5/performance-survey/cache-metadata.md) - bookkeeping capacity after cached groups expire -- [HLS request fan-out](/quest/m5/performance-survey/hls-serving.md) - repeated fetch, remux and playlist construction per viewer -- [Announcement snapshots](/quest/m5/performance-survey/announced-snapshots.md) - HTTP polling cost versus result size and unrelated routes -- [Selective session operations](/quest/m5/performance-survey/session-selection.md) - exact-ID lookups and registry lock hold time -- [Browser media copies](/quest/m5/performance-survey/browser-media-copies.md) - CMAF sample and LOC framing copies versus retention -- [GStreamer ingest buffers](/quest/m5/performance-survey/gst-buffers.md) - copy avoidance versus upstream pool retention - -## Related - -- [Performance audit](/quest/m3/audit-perf.md) - nightly regression attribution and remaining coverage -- [Benchmark sources](/quest/m4/bench-sources.md) - publishing existing measurements to the trend table diff --git a/quest/m5/performance-survey/announced-snapshots.md b/quest/m5/performance-survey/announced-snapshots.md deleted file mode 100644 index 0f66435d203..00000000000 --- a/quest/m5/performance-survey/announced-snapshots.md +++ /dev/null @@ -1,32 +0,0 @@ -# [M] Measure HTTP announcement snapshot fan-out - -## Goal - -Repeated announcement-list polling has measured cost proportional to useful -results, with avoidable copying or unrelated-route work removed if worthwhile. - -## Plan - -[serve_announced](/rs/moq-relay/src/web.rs) creates an announcement consumer, -collects prefixes, creates another Vec of strings and joins them per request. -Some output-size cost is necessary; repeated snapshot and -formatting work is the hypothesis, not proof of a bottleneck. - -Sweep registered routes × HTTP pollers, independently varying matched prefix -size, route churn and path length. Compare an empty selective prefix, a small -result among many unrelated routes and the full listing. Measure CPU/request, -allocations/copied bytes, response latency and route-update latency while -polling. Exercise the real authorization/view path, and attribute its cost -separately from rendering. - -Preserve admission, tenant isolation, hidden-prefix rules, response contents -and visibility during changes. Any shared snapshot must follow authorization -and content identity; avoid a global credential-blind cache. Prefer removing -intermediate allocations over a second route index unless measurements earn it. -This takes the recurring audit's HTTP announcement item; discovery wake/index -quests retain ownership of the underlying routing machinery. - -Follow the [survey's benchmark contract](/quest/m5/performance-survey/README.md): -measure the baseline before optimizing, retain paired evidence, verify equivalent -work, schedule coverage nightly, and accept a measured no-win. Expected public -API and wire impact: none; report the actual impact in the implementation PR. diff --git a/quest/m5/performance-survey/browser-media-copies.md b/quest/m5/performance-survey/browser-media-copies.md deleted file mode 100644 index 01cc76a2c53..00000000000 --- a/quest/m5/performance-survey/browser-media-copies.md +++ /dev/null @@ -1,34 +0,0 @@ -# [M] Measure browser media framing copies and retention - -## Goal - -CMAF decode and legacy frame encode retain only copies that earn their lifetime or -API benefits under representative browser media workloads. - -## Plan - -[CMAF decode](/js/hang/src/cmaf/decode.ts) slices each sample from mdat. -[Legacy `encodeFrame`](/js/hang/src/container/legacy.ts), the publish path's -framing since the JS LOC encoder was removed in -[moq-dev/moq#6517](https://github.com/moq-dev/moq/pull/6517), allocates -contiguous framed output and copies the payload. These are concrete copy sites, -not proof that views are cheaper: a small sample view may pin a large fragment, -and a WebCodecs copyTo may be necessary to obtain bytes at all. - -Extend the existing browser CMAF case and add legacy framing measurements. -Sweep tracks × consumers, sample size × samples per fragment, and held-sample -lifetime. Report JS-visible allocation/copy volume, CPU, GC and retained heap -for immediate consumption and a slow reader. Separate format cost from codec -and transport work; do not infer native copy counts from typed-array hooks. -Check bytes, codec configuration, timestamps and ownership through close. - -A view/owned-buffer change must preserve mutation isolation and release large -backing allocations promptly. Keep current copies if that tradeoff wins. -This extracts the recurring audit's sample-copy item; missing generic -`js/msf`/`js/flate` coverage remains with that audit. CMAF parsing is already -bounded by [moq-dev/moq#6378](https://github.com/moq-dev/moq/pull/6378). - -Follow the [survey's benchmark contract](/quest/m5/performance-survey/README.md): -measure the baseline before optimizing, retain paired evidence, verify equivalent -work, schedule coverage nightly, and accept a measured no-win. Expected public -API and wire impact: none; report the actual impact in the implementation PR. diff --git a/quest/m5/performance-survey/cache-metadata.md b/quest/m5/performance-survey/cache-metadata.md deleted file mode 100644 index 86fb92666a9..00000000000 --- a/quest/m5/performance-survey/cache-metadata.md +++ /dev/null @@ -1,38 +0,0 @@ -# [M] Cache metadata follows live occupancy - -## Goal - -Tracks that expire a large cache do not retain unjustified bookkeeping -capacity after their payload charges fall. - -## Plan - -[Track expiry](/rs/moq-net/src/model/track.rs) pops or retains entries in -`arrival` and `evict` without shrinking backing storage. The `CACHE_OVERHEAD` -rationale assumes a deque holds at most twice its current entries; draining -does not preserve that assumption. Long-lived relay tracks can therefore -retain historical queue capacity after `Pool::used()` falls. - -Sweep tracks × peak cached groups, expire to the protected live group, then -refill. Record queue capacities, logical charges, live allocation bytes and -RSS separately. Use simulated time for expiry correctness and repeated -grow/drain cycles to expose reclamation CPU, copies and allocation churn. -Preserve arrival cursors, live-edge protection and useful cache retention. -Correct the accounting explanation with the chosen implementation. - -Front eviction ([moq-dev/moq#6993](https://github.com/moq-dev/moq/pull/6993)) -kept the group's `kio::log` representation and sheds by advancing its base. Land the benchmark now, but any shrink of the -`arrival`/`evict` deques waits on -[log adoption](/quest/m4/kio-channel-contention/log-adoption.md)'s verdict, -since that quest may move `TrackState` arrival order onto the kio log. -Idle GC clock and lock work was settled by -[moq-dev/moq#6291](https://github.com/moq-dev/moq/pull/6291); this owns -retained queue backing. - -Follow the [survey benchmark contract](/quest/m5/performance-survey/README.md): -baseline first, paired evidence, equivalent work and nightly coverage. A -measured no-win is valid. No API or wire change is expected; report actual impact. - -## Related - -- [Log adoption](/quest/m4/kio-channel-contention/log-adoption.md) - may replace the `arrival` deque this quest would shrink diff --git a/quest/m5/performance-survey/gst-buffers.md b/quest/m5/performance-survey/gst-buffers.md deleted file mode 100644 index d9078a118c1..00000000000 --- a/quest/m5/performance-survey/gst-buffers.md +++ /dev/null @@ -1,31 +0,0 @@ -# [M] Measure GStreamer ingest copies against pool retention - -## Goal - -GStreamer ingest uses the least costly safe buffer ownership strategy, -proven with both fast and slow consumers. - -## Plan - -[Sink::forward_buffer](/rs/moq-gst/src/sink/imp.rs) receives an owned -GStreamer buffer but maps and copies its full encoded payload into Bytes. -Egress already wraps Bytes in a GStreamer buffer. The ingest -copy could be avoidable, but retaining a mapped upstream buffer can exhaust a -finite producer pool or pin more memory than copying. - -Add ingest benchmarks beyond the existing catalog target. Sweep streams × -subscribers, payload size/cadence, and independently the number of upstream -pool buffers and reader retention. Measure copy bandwidth, allocations, -CPU/frame, delivery tail latency, peak memory and upstream stalls. Include -multi-memory/noncontiguous buffers, map failures, flush, cancellation and -teardown; compare identical delivered payloads and timestamps. - -Evaluate owned mapped backing only if end-to-end results justify it and its -Send/lifetime properties hold. Do not claim a win from removing memcpy alone, -or introduce an unbounded pool to make the experiment pass. Retaining the -current copy with a benchmark explaining why is a complete outcome. - -Follow the [survey's benchmark contract](/quest/m5/performance-survey/README.md): -measure the baseline before optimizing, retain paired evidence, verify equivalent -work, schedule coverage nightly, and accept a measured no-win. Expected public -API and wire impact: none; report the actual impact in the implementation PR. diff --git a/quest/m5/performance-survey/hls-serving.md b/quest/m5/performance-survey/hls-serving.md deleted file mode 100644 index 73e46af4528..00000000000 --- a/quest/m5/performance-survey/hls-serving.md +++ /dev/null @@ -1,32 +0,0 @@ -# [L] Measure and reduce repeated HLS serving work - -## Goal - -HLS/DASH viewer fan-out avoids redundant fetch/remux/render work where -measurements justify sharing, without retaining stale or unauthorized output. - -## Plan - -[Rendition::fetch](/rs/moq-hls/src/export/rendition.rs) creates a muxer, -fetches group ranges, gathers frames and constructs a fragment on each segment -request. Init construction already has caching; do not count -it as missing. Media playlists snapshot/render on each call, and DASH builds -representations from the same rendition state. - -Sweep viewers × renditions with independent window length, frame size and -concurrent same-segment requests. Measure CPU/request, upstream fetch count, -allocations, retained bytes and response tail latency, both cold and warm. -Separate unavoidable response serialization from duplicate content work. -Validate all bytes/durations and include gaps, eviction, restarts, reference -handover, concurrent first requests and authorization differences. - -Shared in-flight work or bounded immutable output caching are candidates only -after profiling. Keys and ownership must include the actual content instance; -never let a reused row number cross epochs or cache one viewer's credentials -in another's playlist. The archive/HLS contract quests retain policy decisions. -This takes ownership of the recurring audit's HLS serving coverage item. - -Follow the [survey's benchmark contract](/quest/m5/performance-survey/README.md): -measure the baseline before optimizing, retain paired evidence, verify equivalent -work, schedule coverage nightly, and accept a measured no-win. Expected public -API and wire impact: none; report the actual impact in the implementation PR. diff --git a/quest/m5/performance-survey/send-groups.md b/quest/m5/performance-survey/send-groups.md deleted file mode 100644 index b5c7b9075d4..00000000000 --- a/quest/m5/performance-survey/send-groups.md +++ /dev/null @@ -1,31 +0,0 @@ -# [S] QUIC send-group capacity after subscription churn - -## Goal - -A measured verdict on the memory that moq-quic's scheduler keeps in its -send-group `Slab` after a connection's concurrent subscriptions peak and -fall. Either the slab gives the memory back, or the quest records why the -retained bytes per peak subscription are acceptable. - -## Plan - -Decided 2026-11-03 (maintainer, /quest-plan of the follow-ups from -[moq-dev/moq#7740](https://github.com/moq-dev/moq/pull/7740)): milestone m2, -in the performance survey, with the same "measure before reclaiming" policy -as [task capacity](/quest/m5/performance-survey/task-capacity.md). - -- `rs/moq-quic/src/connection/streams/schedule.rs`: `groups: - Slab>` (around line 177) grows in `open_group`, and - `free_group` only removes the entry. Each `Group` holds a `Queue` of - BTreeMaps, priority, deficit, ring, and members. Explicit send groups are - opened per subscription (`rs/moq-net/src/lite/publisher.rs` - `session.send_group(...)`, and the same in `ietf/publisher.rs`), so a - relay connection keeps slots for its peak concurrent subscriptions. -- Measure with #7740's heap-delta approach (its `receive_bursts` - benchmark): open N subscriptions on one connection, close them, and record - retained bytes per peak subscription and how long they are held. -- If it matters at relay scale, shrink on a low-water mark, or reuse freed - slots across groups so idle entries hold no queue allocation. Otherwise - record the numbers and close. - -Public API: none. Wire: none. diff --git a/quest/m5/performance-survey/session-selection.md b/quest/m5/performance-survey/session-selection.md deleted file mode 100644 index c01aca15059..00000000000 --- a/quest/m5/performance-survey/session-selection.md +++ /dev/null @@ -1,30 +0,0 @@ -# [S] Selective session operations avoid full registry scans - -## Goal - -Exact-session listing and revalidation avoid unnecessary work across other -sessions while maintaining the existing filter semantics. - -## Plan - -[Registry::list and revalidate](/rs/moq-relay/src/session.rs) iterate every -entry while holding the registry mutex (lines 114-132), even though -`Filter::id` is exact and the table is keyed by that ID. Views/IDs are cloned -and matching leases woken while the lock is held. Operators and concurrent -connection registration/drop are the consumers. - -Sweep sessions × concurrent queries/revalidations, comparing exact-ID hits -and misses, selective multi-field filters and all-session requests. Measure -CPU/query, allocation volume, lock hold/wait, response latency, and concurrent -registration/drop latency. Verify an ID plus other filters still means all -fields must match, and only matching sessions are nudged. - -A direct keyed lookup is the minimal candidate. Broad listing necessarily -scales with output; do not add secondary indexes for it without independent -measurement. Existing relay auth-refresh benches do not measure this -administrative selection path. - -Follow the [survey's benchmark contract](/quest/m5/performance-survey/README.md): -measure the baseline before optimizing, retain paired evidence, verify equivalent -work, schedule coverage nightly, and accept a measured no-win. Expected public -API and wire impact: none; report the actual impact in the implementation PR. diff --git a/quest/m5/performance-survey/task-capacity.md b/quest/m5/performance-survey/task-capacity.md deleted file mode 100644 index 4663498fc1b..00000000000 --- a/quest/m5/performance-survey/task-capacity.md +++ /dev/null @@ -1,57 +0,0 @@ -# [M] Task sets release memory after a burst - -## Goal - -A long-lived task set does not keep an unjustified amount of memory for a -burst that has already drained, or the measurement shows that the retained -capacity is worth what it saves. - -## Plan - -[kio::Tasks](/rs/kio/src/task.rs) keeps every slot it ever grew: the slab -entry (`Option>`, whose `Park` holds an inline `Waiter` of about -164 B), the per-slot waker allocation, and the wake bitset. The CPU half of -this quest landed in [moq-dev/moq#7513](https://github.com/moq-dev/moq/pull/7513). -A three-level wake index means an owner poll visits only woken words, so poll -cost no longer depends on the historical peak. The memory half remains. - -Decided 2026-11-01 by the maintainer on -[moq-dev/moq#7513](https://github.com/moq-dev/moq/pull/7513): - -- ✅ (a) Land the CPU half as is, and keep this quest for the memory half: - reclaimable slot chunks, measured against repeat-burst cost and the real - consumers' task sizes. -- (b) Treat retained capacity as justified and delete this quest. -- (c) Implement chunk reclaim in the same PR. - -The [`task_capacity` bench](/rs/kio/benches/task_capacity.rs) reports -retained bytes after a burst. With an 8-byte task, the set keeps about -248 B per peak slot whatever is still live: 254,448 B after a 1,024-task -burst and 16,279,608 B after 65,536. A real task adds `size_of::()` -per slot, so measure the actual consumers (`GroupServe`, the io_uring worker's -`Task`, the session sets) before judging the cost. Dropping the set returns -the heap to baseline, so this is retained capacity, not a leak. - -The candidate is reclaimable slot chunks. Store slots, wakers and wake bits per -1,024-slot chunk, and free a chunk once it empties. That needs allocation to -prefer low free slots, so chunks can drain while one survivor stays behind, -plus some hysteresis so a set oscillating across a chunk boundary does not -reallocate 1,024 wakers each time. Today's LIFO free list and full reuse make -a repeated burst cheap. In the harness from -[moq-dev/moq#7513](https://github.com/moq-dev/moq/pull/7513), a repeated -1,024-task burst through a drained set costs about 840 instructions per task, -the task's own allocations included, and the set allocates nothing for it. Do -not trade that for reclaimed memory without measuring both, with an A/A control. - -Any reclamation must preserve stale-waker safety. A waker that outlives its -chunk must keep its chunk alive or point at nothing. It must also keep -concurrent wakeups, coalescing, snapshot fairness and the rotation order -(`concurrent_wakes_are_never_lost`, `wakes_past_64_chunks_run_in_slot_order`). - -The io_uring worker now uses `Tasks::poll_passes`, so its bounded wake chains -repeat that indexed snapshot within one turn. - -Follow the [survey's benchmark contract](/quest/m5/performance-survey/README.md): -measure the baseline before optimizing, retain paired evidence, verify -equivalent work, schedule coverage nightly, and accept a measured no-win. -Expected public API and wire impact: none. diff --git a/quest/m5/pipewire-camera-planes.md b/quest/m5/pipewire-camera-planes.md deleted file mode 100644 index 805babdbe18..00000000000 --- a/quest/m5/pipewire-camera-planes.md +++ /dev/null @@ -1,15 +0,0 @@ -# [M] Capture multi-plane PipeWire cameras - -## Goal - -A PipeWire camera that delivers I420 or NV12 in separate memory blocks produces frames. Single-block cameras keep working. Other pixel formats stay unsupported. The renderer already imports multi-plane NV12 DMA-BUFs (#3331); this is the shared-memory capture offer. - -## Plan - -The buffer offer sets `SPA_PARAM_BUFFERS_blocks` to 1, so a producer that puts each plane in its own block never links. NV12 is already negotiated. Offer up to two blocks for NV12 and map them into the NV12 conversion that exists. I420 is not. `camera::RAW_FORMATS` drops it before selection, and `convert` has no I420 arm, so negotiate it, offer up to three blocks, and pack its planes into the I420 frame the rest of the pipeline already takes. A one-block buffer of a format already supported keeps the current mapping. - -Unit-test the offer, a multi-block NV12 buffer, and a multi-block I420 buffer, with no camera attached. `doc/lib/rs/moq-video.md` already says a Pi CSI camera and a sandboxed camera are reachable. This quest is what makes the separate-plane case of that sentence true. No new page. - -## Related - -- [PipeWire DMA-BUFs into Vulkan](/quest/m4/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md) - the hardware validation of the DMA-BUF path diff --git a/quest/m5/qos-lag-dashboard.md b/quest/m5/qos-lag-dashboard.md deleted file mode 100644 index ac25e12eb04..00000000000 --- a/quest/m5/qos-lag-dashboard.md +++ /dev/null @@ -1,39 +0,0 @@ -# [S] Demo dashboard shows viewer lag - -## Goal - -The demo stats dashboard (`demo/web/src/stats.ts`) shows the relay's viewer -lag and dropped media: percentiles of the egress `lag` histogram over the -chart window, and `dropped` bytes, frames, and groups as rates, cluster-wide -and per node like the existing counters. - -## Plan - -- Read both from the stats totals and prefix tracks - (`/prefix.json`) rather than the bucket tracks' per-path rows they sit on today (decided in the - 2026-10-06 audit; the rows stay for existing readers, 2026-10-12); [viewer lag histogram](/quest/m3/qos/lag-histogram.md) - lands them on the egress side of its per-bucket totals and prefix tracks - (decided 2026-10-08). `lag` is a cumulative byte count per bucket keyed - by its upper edge (`"50ms"` to `"5s"`, then `"inf"`, empty buckets - omitted); `dropped` has the same four fields as `stale` (`bytes`, `frames`, - `groups`, `datagrams`), written only when non-empty. `lag` is absent where - no viewer's backend reports acknowledgements (qmux, the browser - transport), so show no data there rather than zero lag. - `doc/concept/stats.md` documents them. Diff two - samples within one subscription for an interval's distribution, as the - dashboard already does to turn cumulative bytes into rates, and sum nodes - bucket by bucket. -- A percentile read from buckets is a bucket edge, not a point value, and - `inf` has no upper edge. Show it as "under X" or interpolate inside the - bucket, and say which. -- Skip `.`-prefixed system broadcasts, as the existing aggregate does. Lag is - per broadcast, so a per-broadcast view reads that broadcast's prefix track - if it stays cheap. -- Extend the dashboard's existing relay-stats interfaces; no `@moq/stats` - package is planned. - -Public API: none. Wire: none. - -## Required - -- [Viewer lag histogram](/quest/m3/qos/lag-histogram.md) - the `lag` histogram and `dropped` counters the dashboard reads diff --git a/quest/m5/quic-bbr-study.md b/quest/m5/quic-bbr-study.md deleted file mode 100644 index 5eb3f3d157d..00000000000 --- a/quest/m5/quic-bbr-study.md +++ /dev/null @@ -1,106 +0,0 @@ -# [M] BBR media study - -## Goal - -Measured adopt, retain, or investigate-further decisions on two BBR -behaviors under media traffic: recognizing bandwidth growth within a round, -and precautionary bandwidth probing. Reduce demonstrated frame deadline -interference without persistent queues or unfairness. Google parity is not -assumed to be an improvement. Acceptance and performance use a rate below -the media bitrate behind a deep but finite queue with verified overflow -drops. Random loss may prove recovery 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. -ProbeRTT natural-drain credit is settled: BBR3 skips a due ProbeRTT after an -interval that was app-limited at least once and saw no loss or CE (QUICHE -BBRv1's kBBR8, which subsumes its near-floor kBBR7). The maintainer chose -kBBR8 on 2026-10-25 on the advice of BBR's designer, replacing the -2026-10-24 kBBR7-only decision. The rejected risk, `min_rtt` ratcheting up -under a standing queue the flow builds itself, is the known cost; a skip keeps -the `min_rtt` value rather than taking the queued samples, so it shows up as -the mirror image: while media stays app-limited and congestion-free, `min_rtt` -does not follow a base-RTT rise until a lost or CE-marked packet, or an -interval with no starved poll, brings ProbeRTT back. - -### Harness - -Use `moq-congestion`'s BBR3, which carries the released fork's corrections, -as baseline, with 30-fps frames and keyframes. Include both learned capacity -above the media rate and a sender that has never measured more than its -source rate. - -Use identical media traces and seeds. Start with short and long RTT paths, -then test capacity changes, base-RTT changes, competing bulk traffic, queue -depths, and compressed or delayed ACKs. Use loss-based cross traffic when -BBR alone does not fill the deep queue; verify actual overflow drops. Keep -scripted loss bursts as recovery correctness checks only. Record deadlines and -frame completion, sender backlog separately from network queueing, sample -labels, and mode residence. -Set latency and fairness acceptance limits before tuning. Persist the -harness in CI, with broader network cases at least nightly, and a verdict -with pinned sources/configurations. Any adopted production policy gets a -separate implementation quest; this study does not silently change defaults. - -Check which side sends keep-alives in moq-tokio's native QUIC config. If -both sides ping, the sender's controller may see no samples during an idle, -which masks bugs like #4219. BBR also idles in its 1.25x probe-bandwidth -phase while the app has nothing to send; this is harmless today because -restart from idle resets the gain to 1.0. - -### Google differences - -The 2026-09-21 audit compared noq-proto 1.3.0 / upstream `1a26a8b` with -Google Linux BBRv3 `90210de4` and Google QUICHE `535a2730`. Recheck current -upstream sources before testing. The audit describes noq; `moq-quic`'s BBR3 -was ported from it (#4921), so recheck each difference against `moq-congestion`. -Use QUICHE's actual `bbr3_sender.cc` with -its shared `bbr2_*` model; the older BBR2 sender is not a substitute for its -BBR3 state machine. - -- [Google Linux](https://github.com/google/bbr/blob/90210de4b779d40496dee0b89081780eeddf2a60/net/ipv4/tcp_bbr.c#L1924) - recognizes growth on any ACK and increments the plateau counter only at a - round boundary. Noq follows - [draft-06](https://www.ietf.org/archive/id/draft-ietf-ccwg-bbr-06.html#section-5.3.1.2)'s - earlier round-start gate. QUICHE instead checks its bandwidth maximum at - round boundaries. Test bursty and aggregated ACKs and changing bottleneck - capacity for premature plateau exits. -- [Google Linux](https://github.com/google/bbr/blob/90210de4b779d40496dee0b89081780eeddf2a60/net/ipv4/tcp_bbr.c#L1803) - and [Google QUICHE](https://github.com/google/quiche/blob/535a2730e77d47e0dc03746555cc9c34b17bc9e9/quiche/quic/core/congestion_control/bbr3_sender.cc#L1079) - stop precautionarily when probing reaches a previously lossy inflight - bound, then accelerate a later probe if feedback is clean. Noq lacks this - state and transition. Compare queue depths, capacity increases, and - competing flows on shaped paths with verified overflow drops. -- Found in [moq-dev/moq#7017](https://github.com/moq-dev/moq/pull/7017): - `moq-congestion`'s extra-acked filter is a 10-round Nichols `MaxFilter` - (`EXTRA_ACKED_FILTER_LEN` in `rs/moq-congestion/src/bbr3/mod.rs`), while - Google Linux keeps two slots of 5 rounds each, the shape #7017 gave the - bandwidth filter. Compare aggregation headroom and queue delay under - bursty ACKs before changing it. - -Report throughput, queue delay, loss, convergence time, and fairness with -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. - -### Congestion evidence - -Use the overflowing and deep-queue lanes in `test/ts/README.md` as the -end-to-end baseline. A BBR-only run that sheds groups at the relay but never -overflows the network queue cannot judge the loss response. A CUBIC run -that overflows establishes that the harness exercises recovery; it cannot -establish whether changing BBR improves it. - -Keep the current 2% `LOSS_THRESH` and baseline controller policy unless a -candidate improves the shaped-path comparison, including queues and -fairness. Surviving an independent random-loss percentage is not a reason -to weaken the congestion response or precautionary probe stop. This study -still decides growth recognition and probe behavior separately; it does not -adopt either in advance. - -## Related - -- [TS validation](/test/ts/README.md) - shaped paths, whole-group shedding, and measured baselines diff --git a/quest/m5/quic-careful-resume.md b/quest/m5/quic-careful-resume.md deleted file mode 100644 index 1bb32862ea4..00000000000 --- a/quest/m5/quic-careful-resume.md +++ /dev/null @@ -1,37 +0,0 @@ -# [M] Careful resume on reconnect - -## Goal - -A QUIC connection to a host the process recently talked to starts at the -previous QUIC connection's delivered rate instead of the initial window. -A relay reconnect after a peer restart and a redial after a GOAWAY reach their -steady rate in one RTT, not a slow start. A stale or wrong estimate falls back -to slow start without hurting the path. - -## Plan - -Decided in the 2026-10-10 audit: scope this to remembered QUIC connections. - -Follow the shape of draft-ietf-ccwg-careful-resume: the sender keeps a -per-destination record of the last validated bandwidth estimate and minimum -RTT with its age, jumps the congestion window toward that estimate once the -new path's RTT matches the recorded one, and drops back to ordinary slow -start on the first loss or a mismatched RTT. - -- Implement in `moq-congestion` as a controller wrapper: any controller can be - resumed. BBR3 seeds its bandwidth model and pacing rate directly; Cubic - seeds `ssthresh`. -- The store is a bounded, in-process map keyed by remote address plus SNI, - owned by the endpoint, with an age limit. No persistence across processes. -- moq-tokio's `Connection` (its reconnect loop and GOAWAY handover in - `rs/moq-tokio/src/connection.rs`, dialing through the race in - `failover.rs`) seeds a redial from the session it replaces, and - the relay's cluster peers seed from the previous session to the same peer. - -Measure time to the encoder's target rate after a reconnect on bufferbloat: -a rate below the media bitrate behind a deep but finite queue, with actual -overflow drops, plus loss and latency during the jump. Include competing -loss-based traffic when BBR alone does not fill the queue. Random loss may -prove fallback correctness, but never grades the jump's performance. -Ship it on by default -only when the jump never makes the first second worse than slow start. diff --git a/quest/m5/quic-deadline.md b/quest/m5/quic-deadline.md deleted file mode 100644 index af050e879c7..00000000000 --- a/quest/m5/quic-deadline.md +++ /dev/null @@ -1,94 +0,0 @@ -# [L] Per-stream and per-datagram deadlines - -## Goal - -A send stream can carry a deadline. Bytes that cannot reach the peer before it -are not retransmitted: the stream is reset instead, so a late group never -competes with a live one for the congestion window. Below the deadline, -recovery gets faster rather than slower: when the last packet of a burst is -still unacknowledged and there is time for an acknowledgment and one -retransmission to land, the sender asks for an immediate ACK and probes early -instead of waiting a full PTO. moq-net sets the deadline per group stream from -the subscription's `max_delay` and the group's expiry, so no MoQ wire -change is needed. Datagrams get the same: a queued datagram past its -deadline is dropped from the send buffer instead of sent late, so a -congested viewer receives fresh datagrams rather than seconds-old ones. - -## Plan - -Implement in `moq-quic`. - -- Add `set_deadline(Instant)` on `SendStream`. A stream without one behaves - exactly as today. -- On loss detection, before queueing a retransmission for a stream with a - deadline, estimate the arrival instant as now plus the forward one-way - delay. Start with `min_rtt / 2`, corrected by the peer's reported ACK delay. - Measure whether receive-time differences (`moq_congestion::Acked::received`, - from the [realtime epic](/quest/m3/quic-realtime/README.md)) improve that - estimate, accounting for clock offset, drift, and uncertainty. They do not - alone measure absolute one-way delay. If the estimate is past the deadline, - reset the stream with a dedicated error code and drop its retransmit ranges, - including bytes already lost, so flow control is returned in one step. -- Proactive tail-loss probe: when the newest in-flight packet carries deadline - data and `now + pto() > deadline - rtt`, send an `IMMEDIATE_ACK` (the - ACK-frequency extension `moq-quic` already implements) on the next packet and arm - a shortened probe at `max(deadline - rtt - now, min_pto)`. Never probe past - the congestion window; the probe is a scheduling choice, not extra credit. -- moq-net cannot call `moq-quic` directly, so the deadline crosses its own - `transport::poll::SendStream` trait, the way - [the ACK hook](/quest/m3/quic-ack-hook.md) does: a method whose default - reports unsupported, implemented by the moq-tokio and moq-uring adapters - over `moq-quic`. A backend without it sends as today. -- moq-net: the per-group `GroupServe` machine in the lite and IETF - publishers (`lite/publisher.rs`, `ietf/publisher.rs`) sets the deadline - when it opens the stream, from the subscription's `max_delay` and the - group's expiry, whichever is sooner; a subscription with neither sets none. The reset error code maps to the - existing group-expired code on the MoQ wire, so a viewer sees the same - signal it sees for a relay-side expiry today. - -Datagrams. Decided 2026-11-01 (maintainer, follow-up planning after the -2026-11-01 /quest-afk run), from -[moq-dev/moq#7517](https://github.com/moq-dev/moq/pull/7517)'s datagram -delivery bench: behind a 2 Mbit/s bottleneck fed 4 Mbit/s, about 25% of -datagrams were lost and the survivors' p99 was about 8.2 s (p50 about 50 ms) -on lite-06, lite-07-wip, and moq-transport-22 alike. Congestion control kept -the shaper's queue from overflowing; the sender's 1 MiB QUIC datagram buffer -absorbed the overload and dropped only on overflow, and nothing expired a -datagram by age. Of #7517's options (a send deadline, a smaller send buffer, -or oldest-first within a subscription), the deadline was picked, because it -uses the delay budget the subscriber already stated instead of a buffer size -or ordering that suits only some rates. - -- moq-quic: a datagram carries an optional deadline, and the send path - drops a queued datagram whose deadline has passed (counted, and reported - in the connection's stats) before building a packet with it. A datagram - without one behaves as today. The same estimate of forward delay applies: - drop one that can't arrive before its deadline. -- moq-net: the datagram writer sets the deadline from the subscription's - max delay (`Delay::max`), through the same `transport::poll` seam as the stream - deadline; a backend without it sends as today. -- Keep newest-first within a subscription; with stale datagrams expiring, - it no longer starves the fresh ones. -- Re-run #7517's `datagram_delivery` bench: p99 behind the bottleneck stays - within the subscription's max delay, and the loopback viewer is unchanged. - Percentiles are over delivered datagrams, so also report offered, - delivered, and expired counts separately, and check that datagrams - delivered within the max delay don't fall below today's: the deadline may - drop only what would have arrived too late anyway. - -Measure on bufferbloat: a rate below the media bitrate behind a deep but -finite queue whose overflow demonstrably drops packets, with competing -loss-based traffic if needed to fill it. Random loss may prove recovery -correctness, but never grades latency or throughput. Report delivery latency -p95 and p99, bytes -retransmitted past their deadline (must be zero), spurious resets under -reordering, and probe overhead versus the default PTO. A proactive probe that -raises loss or latency under any profile stays off by default. - -Decided in the 2026-09-30 audit: moved to m2. No m1 quest needs it: -native probing ([moq-dev/moq#6635](https://github.com/moq-dev/moq/pull/6635)) learns of expiry from the stream -reset moq-net already sends. - -## Related - -- [ACK hook](/quest/m3/quic-ack-hook.md) - the same pattern for a moq-net method backed by `moq-quic` diff --git a/quest/m5/quic-ecn-measure.md b/quest/m5/quic-ecn-measure.md deleted file mode 100644 index 02c83a529b8..00000000000 --- a/quest/m5/quic-ecn-measure.md +++ /dev/null @@ -1,47 +0,0 @@ -# [S] Measure ECN on the backbone - -## Goal - -A written verdict on classic ECN between relays: whether a marking -bottleneck reduces the rate before its queue overflows instead of after, -with the numbers, and whether Linode's and OVH's networks preserve ECT(0) -and CE between relays. No code lands; the verdict is recorded in -[L4S on the backbone](/quest/m5/quic-ecn.md), which acts on it. - -## Plan - -A manual procedure on Linux, run as root, with the commands and what to -record written here so the dualpi2 run and any later provider re-check -repeat it. - -Use `moq-quic`, whose BBR3 carries the classic CE response ported from -[moq-dev/noq#12](https://github.com/moq-dev/noq/pull/12) (see -`rs/moq-quic/README.md`), for the controller-response verdict and record the -exact commit. Provider mark-survival captures alone do not establish a -controller response; a result from a stack without that response, such as -moq-noq 1.3.1, is a defective baseline, not evidence that classic ECN cannot -help. - -- Bottleneck: two relays on the io_uring runtime across a netem link with a - rate limit and delay, once with `fq_codel` marking (`ecn` on) and once - with the same qdisc dropping (`noecn`). Measure queueing delay at the - bottleneck, goodput, and loss under a moq-bench media profile. The - question is whether the marking run holds a shorter queue at the same - goodput. -- Providers: between a Linode relay and an OVH relay, `tcpdump -v` on each - end shows the TOS byte of arriving packets. Record whether ECT(0) arrives - intact in each data direction and whether any CE appears. Check that - the reverse ACKs report the received ECN counts; the ACK packets need not - themselves retain an ECN IP marking to carry those counts. Repeat the - capture for cross-provider and same-provider pairs. -- Record the qdisc parameters, the moq-bench profile, the kernel version, - and the tcpdump summaries beside the numbers in the L4S quest's Plan. - If neither provider preserves the marks, say so there: L4S stays off and - the marking response is only a lab result. - -Decided in the 2026-09-30 audit: moved to m2 with its only consumer, -[L4S on the backbone](/quest/m5/quic-ecn.md). - -Decided in the 2026-10-06 audit: no code lands here, and `moq-quic` already -carries the classic CE response, so the study runs today. L4S on the -backbone lands its code in `moq-quic`. diff --git a/quest/m5/quic-ecn.md b/quest/m5/quic-ecn.md deleted file mode 100644 index 1ccd99d2fee..00000000000 --- a/quest/m5/quic-ecn.md +++ /dev/null @@ -1,41 +0,0 @@ -# [M] L4S on the backbone - -## Goal - -Relay-to-relay sessions can mark ECT(1) with a scalable response, measured -behind an option that is off by default, and a deployment whose network -mangles marks can turn ECN off explicitly. Paths that strip or mangle the -marks fall back to no ECN, and a viewer's session is unaffected. - -## Plan - -ECT(0) marking and ACK ECN counts are carried end to end, and BBR3's classic -CE response, ported to `moq-quic` from -[moq-dev/noq#12](https://github.com/moq-dev/noq/pull/12) (see -`rs/moq-quic/README.md`), is the baseline. `main` no longer depends on -moq-noq or upstream noq-proto. This quest adds the -scalable policy separately. `moq-quic` has no ECN knob: `sending_ecn` starts -on per path and validation failure or an ACK without counts turns it off, so -both `off` and `ect1` need a `moq-quic` change. - -- In `moq-quic`: an `Ect1` marking option and the accounting to keep the two - codepoints apart, so an L4S response (proportional to the CE fraction per - RTT, per RFC 9330 to 9332) can be tried as a `moq-congestion` controller - without a transport change; the controller chooses the codepoint. Off by default. -- `moq-tokio`'s `[quic]` section gains `ecn = off | ect0 | ect1`, ect0 by - default (today's behavior on tokio), and `doc/bin/relay/config.md` - documents it in the same PR. -- Measure on the netem bottleneck from the - [ECN study](/quest/m5/quic-ecn-measure.md) with `dualpi2` marking against - the same bottleneck dropping: queueing delay, goodput, loss. The study's - provider verdict decides whether the result matters outside the lab; - if neither Linode nor OVH preserves the marks, L4S stays off and the - result is written down here. -- ECN visibility stays on the wire: the study observes marks with tcpdump, - and exposing per-path ECN state in stats is a later quest if operators - need it. - -## Required - -- [Measure ECN on the backbone](/quest/m5/quic-ecn-measure.md) - the - provider verdict this quest acts on diff --git a/quest/m5/quic-egress-profile.md b/quest/m5/quic-egress-profile.md deleted file mode 100644 index 710bb85a5ab..00000000000 --- a/quest/m5/quic-egress-profile.md +++ /dev/null @@ -1,134 +0,0 @@ -# [M] Relay egress syscall and allocation profile - -## Goal - -A measured verdict on the relay's egress costs below moq-net: syscalls per -train, allocations and copies per frame, and whether a released GSO train -bursts at the bottleneck. Each lever below is built only if the profile -shows its cost; a lever measured within noise is recorded and closed. - -## Plan - -Decided in the 2026-09-30 audit: send batching, kernel pacing, and send -buffer pools merged into this one measure-first quest, since all three are -questions about the same egress path and share one profile. - -Decided 2026-10-30 (maintainer): the profile also covers moq-quic's -ingress and egress (`just bench-profile cpu` on `io-uring-workers`), since -[quic-io-boundary](/quest/m5/quic-io-boundary.md) waits on it to rank its -candidates. - -Measure first, on the chat and fanout shapes with many connections, tokio -workers versus io_uring workers, with the existing profiling captures: - -- Syscalls: the tokio path sends one `sendmsg` per GSO train per connection; - the io_uring path queues one SQE per train and submits them together. Count - syscalls per second and CPU per Gbps, and confirm from the io_uring - worker's `enters` counter that the ring already amortizes. -- Allocations: `moq-quic`'s `SendBuffer` keeps each write as the caller's - `Bytes`, with no coalescing copy. Count allocations and bytes copied per - frame above it, split by frame size, so any copy left is located. -- Bursts: the QUIC connection paces inside `poll_transmit` on both runtimes - (#4400; `moq-congestion`'s pacer), so the only open question - is whether a released GSO train leaves the NIC as a burst the bottleneck - cannot absorb. On a netem bottleneck, compare inter-packet gaps and queue - occupancy for a 64-segment train against the same bytes paced at the - controller's rate. - -Then, only where the profile shows a cost: - -- `sendmmsg` in `moq_sock::udp` behind the existing GSO path, submitting every - train ready across connections in one call, falling back to per-train - `sendmsg` on partial failure the way the GSO fallback does. A contributor's - prototype on the tokio driver gives the profile a starting point; none of - its code is in-tree, and its numbers below are the prototype's, not the - profile's. It was measured before being - [ported onto main in a fork](https://github.com/zshenker/moq/commit/040df9948bd110a83463f35cd4bd86245db03373) - (opt-in through `Endpoint::batch_sends`), and comes with its - [raw samples](https://github.com/zshenker/moq/blob/eae2ca6941ce67b8e14ba6afdb76c1c2240c45a0/bench/driver-batch-sends/samples.jsonl), - so the profile should re-measure the port. - - Revision: measured on e072cf604 with #7458, #7418, #7394, #7543, and a - GSO byte cap equivalent to #7649 applied. The prototype revisions measured - predate the handshake bypass, and the last round ran after the drop and - rebind fixes. The steady-state send path matches the port, which differs - in its opt-in (`Endpoint::batch_sends`), its flush task's spawner, the - handshake bypass, and its base. Those revisions and the harness are not - public. - - Invocation: one run per sample of the harness's - `bench --sessions 1000 --rate 30 --object-size 1024-4096 --objects-per-stream 1 --client-threads 6 --client-endpoints 12 --pin --batch-sends {false|true}`, - with audio at `--rate 50 --object-size 100-200`, 1 Mbit/s video at - `--object-size 3125-5208 --objects-per-stream 30`, and 3 Mbit/s video at - `--sessions 500 --object-size 9375-15625 --objects-per-stream 30`. Its - defaults are a 1,280-byte payload, GSO on, one tokio worker, a 5 s warmup, - a 15 s measure, 128 handshakes in flight, and a 15 s keep-alive, all under - `taskset` on physical cores. - - Setup: server and client on one host over loopback, the server on one - tokio worker pinned to one physical core, and the client on 6 pinned workers - over 12 sockets. 1,280-byte payloads, MTU discovery off, GSO and GRO on, - BBR3. Only the server batches. Each sample is one 15 s run after a 5 s - warmup, on a dual-socket Broadwell Xeon with Linux 6.12. On and off ran back - to back on the same binary, in alternating order across runs. - - Server CPU (`getrusage`, % of one core): - - small objects (1,024 to 4,096 B at 30/s, 1,000 sessions): 61.7% off - against 54.9% on, n=3 each, so 8 to 15% lower; - - audio-rate (100 to 200 B at 50/s, 1,000 sessions): 66.9% against 53.9%, - n=3 each, so 16 to 22% lower; - - 1 and 3 Mbit/s video: 10% and 8% lower, n=1 each. - - The system share fell from 31 to 38% to 22 to 34%. A single run varies by - about ±3%. - - Calls: in separate 5 s `strace` windows of the small-object point, the - unbatched server made 135,497 `sendmsg` and the batched one 7,214 - `sendmmsg` plus 506 `sendmsg`, so about 18 to 19 trains per `sendmmsg`. - That is an estimate across runs with no direct counter, and `strace` slows - each arm differently. - - Latency (per object, from the server's write to the client's read of the - last byte): p50 rose from 36 to 72 µs to 258 to 352 µs. On the small-object - and audio points, p99 rose from 104 to 705 µs to 606 to 770 µs. - - Its shape: - - `UdpSocketState::try_send_many` on Linux sends up to 64 transmits, one - `mmsghdr` each, in one `sendmmsg`, each with its own GSO segment size, - ECN, and source-address cmsgs. It returns how many the kernel took, and - retries an `EIO` or `EINVAL` on the first transmit alone through - `try_send`, so GSO halting still applies. - - The driver copies each train into a per-socket queue, bounded in bytes, - and one task per socket yields once and then flushes the queue. - - Handshake packets try the socket directly, since `handle_unreachable` - acts only during a handshake and a queued send's error never reaches it; - without that, a dial to an unreachable address would wait out the - handshake timeout instead of failing with `NO_VIABLE_PATH`. The bypass is - not unconditional: on `WouldBlock` the port queues the handshake packet, - and that packet's send error is lost the same way. A shipped version - should keep backpressure on handshake sends instead of queueing them. - - A rebind wraps the new socket the same way. Dropping the queue sends what - the socket has room for and closes it synchronously, freeing the port. The - flush is best-effort: it stops at `WouldBlock`, and a batch the flush task - already took is dropped once the socket closes, so a CONNECTION_CLOSE can - be lost. A shipped version should drain that batch too. - - Open: whether batching is opt-in in the driver's config or on by default, - given the added p50 and p99 latency, and whether moq-uring, which already - submits every train in one ring enter, needs any of it. -- A `BufFactory`-style seam on `SendBuffer` in `moq-quic` that takes buffers - from a pool sized from the send window and returns them on ACK. Design it - with [the I/O boundary redesign](/quest/m5/quic-io-boundary.md), which - reworks the same transmit buffers. -- `SCM_TXTIME` stamps, one per train, at the time the pacer would have - released it (the next-send time `moq-congestion`'s trait exposes), tested under both `etf` and `fq`. The socket is shared across - connections per worker, so `SO_MAX_PACING_RATE` cannot express - per-connection pacing. Measure on a real NIC as well as loopback, since - `etf` needs hardware offload to be exact. - -Report CPU per Gbps, RSS, loss, and p99 latency on Linux: `just bench BASE` -for tokio, and `just bench-runtime` at both revisions for the ring, since -`just bench BASE` runs only tokio. The verdict names which levers ship and which qdisc, if any, relay -hosts need. - -## Related - -- [QUIC I/O boundary](/quest/m5/quic-io-boundary.md) - redesigns the transmit buffers the pool lever would feed -- [#3201](/quest/m5/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md) - - zero-copy on the same trains -- [#3204](/quest/m5/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md) - - the UDP-side pool the same buffers could feed diff --git a/quest/m5/quic-io-boundary.md b/quest/m5/quic-io-boundary.md index 39b57980b6f..da4863e6152 100644 --- a/quest/m5/quic-io-boundary.md +++ b/quest/m5/quic-io-boundary.md @@ -56,7 +56,3 @@ Require this quest and build on its transmit contract, so the contract is settled once; registering buffers stays with #3204, which measures whether it pays. Report relay CPU per Gbps before and after on the same workloads. - -## Required - -- [Relay egress profile](/quest/m5/quic-egress-profile.md) - its moq-quic profile ranks this quest's candidates, and its send-buffer pool shares the `SendBuffer` seam diff --git a/quest/m5/quic-lb-forward-extras.md b/quest/m5/quic-lb-forward-extras.md deleted file mode 100644 index 72f091432b5..00000000000 --- a/quest/m5/quic-lb-forward-extras.md +++ /dev/null @@ -1,31 +0,0 @@ -# [S] QUIC-LB forwarding reads the cluster's peers and reports its counts - -## Goal - -The QUIC-LB forward peer map can come from the `cluster.api.url` peer entries, -not only the watched TOML file. Relay stats count packets forwarded, dropped for -an unknown server ID, and refused. - -## Plan - -Planned 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-complete run). Follow-ups from [moq-dev/moq#7539](https://github.com/moq-dev/moq/pull/7539), -which landed the forwarding on 2026-11-02. -The maintainer kept the TOML file as the source there (decision 4), with the -cluster API as this follow-up. Use the cluster API only if the deployment's API -already serves the mesh peer list. - -Peer map: each map entry is a QUIC-LB server ID and that relay's forward -socket address (`[listen.lb.forward] bind`), the same pair the TOML file -holds. A `cluster.api.url` peer object carries only `url`, `cost`, `egress`, -`token`, and `upstream` today, so it gains optional fields for the two, with -names to settle in the PR. A peer without both stays out of the forward map, -so a packet naming its server ID is still refused as unknown. Decide whether -the API replaces the TOML file or merges with it when both are set. - -Counters: the forwarding module from #7539 (`moq_tokio::quic::driver::forward`) -owns them and the relay exposes them in its stats and `/metrics`: - -- forwarded: a short-header packet sent to another server's forward socket; -- unknown server ID: a short header naming a server ID the map lacks, dropped; -- refused: a received forward dropped for an unlisted source, a bad tag, or - naming a server other than this one. diff --git a/quest/m5/receive-pool.md b/quest/m5/receive-pool.md deleted file mode 100644 index ba4f651f8a7..00000000000 --- a/quest/m5/receive-pool.md +++ /dev/null @@ -1,81 +0,0 @@ -# [L] One receive budget per worker, shared with the cache - -## Goal - -Each worker has one byte budget that covers both the receive credit every -connection holds and the groups its cache keeps. A frame's bytes are billed once, -from the first leased byte until the cache drops them. An operator sets that one -number instead of sizing `quic.receive_window` against the cache capacity and the -expected peer count. - -Today each connection's window bounds only its own incomplete messages, and the -cache `Pool` is billed again for the same bytes once a frame is taken. So the worst -case is connections × 128 MiB plus the cache. A relay with many peers either -reserves memory it never uses or sizes the window below what one peer's largest -unit needs. - -Non-goals: revoking credit already granted, cross-peer eviction, and zero-copy -send buffers (see [registered TX buffers](/quest/m5/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md)). - -## Plan - -Decided 2026-10-21 in the [moq-dev/moq#5878](https://github.com/moq-dev/moq/pull/5878) -iteration: - -- **Per worker.** One budget per io_uring worker thread, with no cross-thread - atomics; the tokio runtime gets one budget. The cache `Pool` splits the same way, - so each worker's cache and receive credit draw on one number. This reverses the - relay's single process-wide cache pool, which this quest must migrate (config, - a migration note, `doc/bin/relay/`). -- **Under pressure, stop granting.** Credit already advertised is never revoked. - New `MAX_DATA` comes from the budget by fair share, so a peer over its share - stalls rather than evicting anyone else. Eviction stays within one connection, as - in #5878. A peer still cannot cost another peer its streams. -- **Accounting first.** Received bytes stay `Bytes` slices, compacted when a reader - waits on them (#5878). The budget counts leased plus cached bytes once. Move to - QUICHE-style fixed blocks (8 KiB, allocated lazily and freed as consumed) only if a - benchmark shows allocator or fragmentation cost the accounting cannot see. - -Open, for the implementer to bring to the maintainer: - -- **The 64 MiB floor.** Each connection must be able to assemble its largest unit, a - legacy `AnnounceInit` (`MIN_RECEIVE_WINDOW`). Should a connection get its floor - only on a `want` that needs it, or should the announcement cap shrink first? -- **The handoff from lease to cache.** A frame taken from a lease keeps its credit - until complete. Once complete, the credit becomes a cache charge. The charge has - to move to the cache without a window where the bytes are billed twice or not at - all. - -Idea for later (maintainer, 2026-10-30, from the -[fastest-reader pacing](https://github.com/moq-dev/moq/pull/7664) iteration -in [moq-dev/moq#7388](https://github.com/moq-dev/moq/pull/7388)): instead of -moq-quic granting `MAX_STREAM_DATA` automatically as a stream is read, the -application could pause a stream, or grant it an explicit -`allow(fastest + window)`, so flow control never grants credit past the pacing -window (the stream receive window, capped at 16 MB). Paused streams would then hold no credit beyond that window, replacing -moq-net's per-session cap on paused credit. - -Until then, the pool must keep that cap honest (noted 2026-10-31 from -[moq-dev/moq#7388](https://github.com/moq-dev/moq/pull/7388), moved here when -[moq-dev/moq#7624](https://github.com/moq-dev/moq/pull/7624) finished the qmux -receive lease): each paused stream reserves its window from a budget of about -half the connection window when it pauses (`Shared::reserve` in -`rs/moq-net/src/transport/boxed.rs`), and nothing re-checks it. No caller -shrinks a live receive window today; if the pool's fair share can shrink -one, re-balance the paused reservations when it does. - -Lessons from other stacks: QUICHE frees 8 KiB blocks as they are consumed, msquic -never advertises credit it could not back, and quinn and lsquic both let a slice -pin its packet buffer. #5878 already handles the last with compaction. - -Benchmark: sweep peers × window over a fixed budget on the `benchmark_receive_windows` -harness. Report peak resident bytes against the budget, evictions, and throughput. - -## Related - -- [Unbounded groups](/quest/m2/unbounded-groups/README.md) - drops the frame cap that - sets half of `MIN_RECEIVE_WINDOW` -- [Perf](/quest/m4/perf/README.md) - the per-worker hot paths this budget must not add - contention to -- [Broadcast fairness](/quest/m5/broadcast-fairness.md) - the receive rank's - fairness domains diff --git a/quest/m5/recover-budget.md b/quest/m5/recover-budget.md deleted file mode 100644 index 53a2b8102ae..00000000000 --- a/quest/m5/recover-budget.md +++ /dev/null @@ -1,31 +0,0 @@ -# [S] A parked read of a resumed group reads its budget without re-syncing - -## Goal - -A pending read of an open group handed out by a resumed reader checks its -expiry budget without locking the reader and re-running its route sync, so -relay fanout through fronts pays no per-frame, per-viewer sync. A benchmark -of resumed readers shows the per-read cost flat in the number of copies. - -## Plan - -From the 2026-10-24 pre-cut audit at 151a529670. Source-inferred, not -benchmarked; new on main. Measure first, and delete this quest if the cost -does not show. - -Every Pending read of an open group goes -`poll_expired_if_blocked` -> `poll_expiry` (`rs/moq-net/src/model/group.rs:2692`) --> `Recover::poll_budget` (`model/resume.rs:1868`), which locks the -`Reader` and runs `sync`: `learn_end` over every copy (each taking its track -lock), `subscription.poll_ref`, and a route state read, only to read a -`Duration`. On a relay every downstream subscription to a front track goes -through this path. - -Publish the reader's budget through the existing preferences channel (or an -atomic) for `Recover` to read, and keep `sync` on the reader's own poll path. - -Public API: none. Wire: none. - -## Related - -- [Resume as producer replacement](/quest/m4/resume-redesign.md) - deletes this path entirely diff --git a/quest/m5/request-token-surfaces.md b/quest/m5/request-token-surfaces.md deleted file mode 100644 index 7cc4cbd5932..00000000000 --- a/quest/m5/request-token-surfaces.md +++ /dev/null @@ -1,29 +0,0 @@ -# [M] Request tokens beyond Rust - -## Goal - -When a consumer needs it, a JS, binding, or CLI application can present a -request token on its outgoing requests and, where the consumer verifies -tokens, accept them. Each surface mirrors the Rust names. Only the surfaces a -named consumer uses ship. - -## Plan - -✅ Decided 2026-10-15 (maintainer, #5148): a request token is one kind of -auth. Incoming ones already arrive on the session's `requests()` queue, and -outgoing ones come later through `add()` with automatic naming, sent as -`USE_VALUE` on plain moq-transport. There is no separate request-token setter -or acceptor to mirror. - -So each surface here exposes that unified shape once Rust has it, and only -for the surface a named consumer uses. Start by asking that consumer which -surface it needs. Do not build all three. Through moq-ffi, follow the session -AUTH shape: `MoqSession.tokens()` and `MoqSession.grants()`. Update every -wrapper, as the cross-package table requires. - -Public API: whatever the chosen surface needs to present and accept auths -per request. Wire: none. - -## Related - -- [#5148](https://github.com/moq-dev/moq/pull/5148) - incoming request tokens in Rust diff --git a/quest/m5/room-bench.md b/quest/m5/room-bench.md deleted file mode 100644 index a962f228c94..00000000000 --- a/quest/m5/room-bench.md +++ /dev/null @@ -1,22 +0,0 @@ -# [S] moq-room scales to large rooms - -## Goal - -A benchmark measures `moq-room`'s `Room` with large participant counts -(for example 10, 100 and 1,000 followed paths), covering the cost of one -participant's change and of steady-state wakes. If the cost grows with room -size per wake, the room polls only the followers a wake concerns, and the -benchmark shows the change. - -## Plan - -Planned 2026-10-31 (`/quest-plan`, maintainer), a follow-up to -[Listing and follow](https://github.com/moq-dev/moq/pull/7678), after which -`Room` holds a follower per listed path and polls every follower on each wake. That should be fine at room sizes seen -today. Benchmark first, as -[moq-dev/moq#7340](https://github.com/moq-dev/moq/pull/7340) did for the -lite subscriber's prefixes, and fix -only if it shows a slope. Wire the benchmark into the existing bench lanes -([Benchmark sources](/quest/m4/bench-sources.md)). - -Public API: none. Wire: none. diff --git a/quest/m5/route-health/README.md b/quest/m5/route-health/README.md deleted file mode 100644 index 32294f7c871..00000000000 --- a/quest/m5/route-health/README.md +++ /dev/null @@ -1,125 +0,0 @@ -# Active/passive route health - -## Goal - -Endpoints and relays detect stalled delivery on an actively demanded track by -comparing it with a next-best route observing group/frame progress without -payload. The shared routing model automatically resumes through a working -alternate and keeps the track there until that route fails. This applies only to -broadcasts with an explicit matching epoch: epochless broadcasts cannot resume -and keep their existing Restart behavior. - -## Plan - -Decided with the maintainer, 2026-10-13: - -- Ranked in m2 (m5 since the 2026-11-05 re-cut), after clustering stability, federation, and P2P. Health - design had to reproduce a stall that transport failure and ordinary - reconnect do not recover, or the line would be abandoned. It did - ([moq-dev/moq#7096](https://github.com/moq-dev/moq/pull/7096)): - `rs/moq-net/tests/integration/route_health.rs` pins a silent kill that loses - about `detection - max_delay` of media, and a payload stall on live sessions - that is never recovered while `largest()` keeps pace. -- A route that dies without a close counts as such a stall until the QUIC - idle timeout fires (decided 2026-10-20, from - [#6062](https://github.com/moq-dev/moq/issues/6062)): a killed relay - starves a same-epoch subscription until the QUIC idle timeout fires; since - [#6183](https://github.com/moq-dev/moq/pull/6183) resume recovers only what - max age still holds, so a max age below the timeout still loses media. - -- Application-assigned connection priority remains ahead of additive cost. - Deterministic hashing still chooses distinct equal routes; a new connection - wins only when routes otherwise match. Stalled delivery is addressed by - evidence, not a general newest-connection preference. -- Observe at most one eligible same-epoch standby at a time per demanded - track, the next-best route, aggregating downstream readers. If - active and standby provide insufficient evidence, bounded exploration must - reach other eligible candidates; a shared failure must not hide a working - third route. Silence alone still does not establish failure. Metadata watchers - must not recursively - create their own backups at every relay or multiply into a network-wide - monitoring tree. Monitor at endpoints and relays from the first implementation. -- A new mode in whichever lite wip is current when it lands; it does not - gate lite-07. The preferred API is `Subscription.meta: true`: a live stream of - group/frame headers with payload omitted, so a standby notices a live - failure such as a dead old connection whose keep-alives stopped. `largest()` - alone cannot: on a payload-less standby it is only the SUBSCRIBE_OK - snapshot. A one-shot TRACK_STATUS on a new route's announcement is racy, - since a switch needs the candidate to stay meaningfully ahead. It is not - PROBE or a full media subscription hidden locally. -- Prefer per-track failover. The existing track resume layer can support it, - but shared broadcast source selection must be separated from per-track - active/standby selection. The maintainer permits broadcast-level fallback - if this proves disproportionately complex; explain the evidence if used. - One stalled track never establishes whole-session failure. -- Automatically let a stalled preferred route yield to a healthy lower-ranked - eligible route. Relative metadata progress is evidence to test a replacement, - not proof it can deliver the needed media. Brief payload overlap is allowed - while verifying a promotion; steady standby carries no payload. -- Never automatically return to a demoted preferred route (decided - 2026-11-02, reversing the 2026-10-13 decision to return after useful media - demonstrated recovery). The track stays on the working route until that - route fails, by transport failure or by the same stall evidence. Payload - trials that let a recovered route win the track back, with uncapped or - capped doubling backoff, were rejected: the track is already being - delivered, and a return would trade a working route for one that just - failed, at the cost of overlap, possible oscillation, and a backoff - schedule. Preserve ordinary transport failures. -- No health standby, automatic resume, or recovery promotion for epochless - broadcasts, even when the path, node, or connection looks unchanged. - -Decided with the maintainer, 2026-11-02, from the measured stalls: - -- Evidence: the standby is a `Subscription.meta: true` subscription on the - existing SUBSCRIBE; "SUBSCRIBE_META" was shorthand, not a new message. - Switch when the active's delivered media timestamp lags the standby's - reported timestamp by more than the reader's max delay, while the reader - demands. That budget is what the reader already accepts losing, so a - standby that is normally a little faster never overrides application - priority, and no per-route baseline or fraction constant is needed. A - reader without a max delay uses a fixed 2s. Until the active delivers its - first frame, its delivered timestamp is that of the first frame the reader - still needs, as the standby reported it, so a route that never delivers is - caught on the same budget. Never compare `largest()` values, and never - count source silence or a reader that stopped reading. -- Exploration: when neither active nor standby shows progress for the - reader's max delay (or the same 2s), the standby slot moves to the next - eligible candidate, doubling the wait per move. That bounds exploration: - one standby at a time, and moves that slow down geometrically. With every - candidate quiet, the slot keeps cycling through the eligible candidates at - the doubling wait and fails nothing, since silence is not failure; the - track stays on the active until real progress resets the wait or demand - ends. One constant drives both the switch and exploration; it replaces - falling back to the publisher's max age. -- Standby choice: the next-best route. Exploration already bounds the cost of - an upstream it shares with the active, so preferring the candidate with - the fewest shared hops was rejected as extra machinery. - -The epic's remaining work is end-to-end validation across a multi-hop relay -network and alternate sessions representing CDN/direct paths: stalled video moves while healthy audio remains, -control advances while payload stalls, a recovered preferred route does not -take the track back while the working route delivers, and both quiet routes -stay unknown rather than falsely failing. -Test epochless exclusion, an active/standby shared bottleneck with a healthy -third route, simultaneous relay decisions, -loss/reordering, cancelled demand, and stale/replayed progress. Wire these into -CI. Report actual media overlap, control traffic, wakes, switches, and memory -across tracks, candidate connections, and downstream readers. Extend the -[P2P harness](/quest/m4/p2p/harness.md) with real browser/native cases: -metadata-only standby, stalled payload with advancing control, same-epoch -promotion with bounded overlap, no failback while the working route -delivers, and epochless exclusion. -Add a route-health section to the routing concept page. - -## Required - -- [Metadata subscriptions](/quest/m5/route-health/meta.md) - the current lite wip and the shared model observe frames without payload in Rust and JS -- [Track route selection](/quest/m5/route-health/selection.md) - share broadcast identity/candidates while tracks choose sources independently -- [Automatic recovery](/quest/m5/route-health/recovery.md) - epoch-only promotion in endpoints and relays, staying on the working route -- [Revisit the relay's default QUIC idle timeout](/quest/m5/route-health/idle-timeout.md) - keep or change the 10 s default, with the reason recorded - -## Related - -- [Cluster routing](/quest/m2/cluster-routing/README.md) - reachability and advertisement freshness, distinct from delivery health -- [Link quality](/quest/m5/link-quality.md) - optional metric repricing, not this local delivery-health decision -- [Routing guide](/quest/m1/routing-guide.md) - priorities, health, and epoch-only continuity explained together diff --git a/quest/m5/route-health/idle-timeout.md b/quest/m5/route-health/idle-timeout.md deleted file mode 100644 index e7956641a8a..00000000000 --- a/quest/m5/route-health/idle-timeout.md +++ /dev/null @@ -1,12 +0,0 @@ -# [XS] Revisit the relay's default QUIC idle timeout - -## Goal - -moq-relay's default `quic.idle_timeout` (10 s) is either kept or changed, with -the reason recorded in the relay config doc, now that route recovery moves a -track before the idle timeout declares a dead route. - -## Plan - -Planned 2026-11-02 (maintainer, follow-up planning after the 2026-11-02 /quest-complete run), from [moq-dev/moq#7096](https://github.com/moq-dev/moq/pull/7096)'s -route-health measurements. diff --git a/quest/m5/route-health/meta.md b/quest/m5/route-health/meta.md deleted file mode 100644 index 0fc2879ded8..00000000000 --- a/quest/m5/route-health/meta.md +++ /dev/null @@ -1,68 +0,0 @@ -# [L] Metadata-only subscriptions - -## Goal - -Rust and JS can subscribe to group/frame progression without receiving media -payload, through the shared subscription model and whichever lite wip is current when it lands. Relay -chains forward and aggregate that demand without secretly pulling full media. - -## Plan - -Decided 2026-10-13: a `meta: true` field on `Subscription`, defaulting to -normal payload delivery, carried by the existing SUBSCRIBE (confirmed -2026-11-02: "SUBSCRIBE_META" was shorthand, not a new message). It must be a -live stream: `largest()` on a payload-less standby is only the SUBSCRIBE_OK -snapshot, and a one-shot TRACK_STATUS on announcement races the active route. -It does not gate lite-07. Preserve normal group/frame progression with -payload omitted. Mirror the public field and semantics across Rust, JS, and -any bindings exposing Subscription. - -Framing, decided 2026-11-02: each group stream marks its metadata mode in -its own header, so a stream opened before a mode update is read under the -mode it was opened in. Keeping the mode only on the subscription was -rejected: the receiver would race updates against already-open streams. -Metadata FRAMEs keep the timestamp and declared size and carry no bytes, so -a real empty frame stays distinguishable from omitted payload. Promotion to -payload is a SUBSCRIBE update on the same subscription, re-requesting bytes -from the reader's first missing frame, including positions it observed as -metadata. Metadata-only state never satisfies a media reader, fills a cache -as a complete frame, or advances a resume cursor. - -Aggregation, settled 2026-11-02: a relay pulls payload upstream only for -payload demand. Metadata-only demand still travels upstream as a live -`meta: true` subscription, so group and frame headers keep arriving after -any payload copy the relay holds is exhausted; while such a copy is live, -the relay serves metadata from it. Only payload demand creates a health -standby, so metadata observers never branch further. Each downstream -metadata subscriber still receives no payload. When only metadata demand -remains, demote the upstream subscription to metadata with an update: drop -the payload demand and keep the metadata demand. -Remove all observation demand when the last reader leaves. Preserve ranges, -priority, drop/end semantics, and retention without one global scan per -update. - -Reuse the live-largest model where its semantics fit, keeping remote reports -separate from useful received media. Standby health uses this feature only -for matching explicit epochs; the field itself does not authorize resume. -Older negotiated protocols must not silently emulate metadata-only mode by -fetching and discarding media. Explicitly report unsupported mode; ordinary -media and epochless Restart continue unchanged. An IETF counterpart is not -required for this lite feature. - -Tests: metadata-only multi-hop traffic has no media payload; a relay whose -last payload reader leaves keeps forwarding live headers to its metadata -readers; mixed demand; -promotion/demotion during an open group; empty frames; late old-mode frames; -resume at a metadata-observed position; cancellation; refusal on unsupported -versions. Sweep tracks, readers, and relay depth for bytes, wakes and memory. -Update `draft-lcurley-moq-lite.md`, Rust/JS codecs, and stale API docs together. -Run `just check`, `just drafts check`, and `just test interop --all`; add the -new mode to cross-language interop and existing CI. - -Public API: `Subscription.meta` and any corresponding binding surface. -Wire: a metadata delivery mode in the current lite wip: the SUBSCRIBE field, -a mode marker in each group stream header, and payload-less metadata FRAMEs. - -## Required - -- [Subscribe ranges](/quest/m2/subscribe-ranges/README.md) - final subscription range shape this extends diff --git a/quest/m5/route-health/recovery.md b/quest/m5/route-health/recovery.md deleted file mode 100644 index e6621a76c25..00000000000 --- a/quest/m5/route-health/recovery.md +++ /dev/null @@ -1,88 +0,0 @@ -# [L] Automatically recover stalled epoch tracks - -## Goal - -Endpoints and relays automatically move a stalled track to a verified working -same-epoch alternate, and keep it there until that route fails, while -preserving logical readers and bounded control/media overhead. -This includes a route that dies without a close: the track moves before the -QUIC idle timeout declares it dead. -Epochless broadcasts never enter this active/passive mechanism. - -## Plan - -Decided with the maintainer 2026-11-02; the line README records why. -Observe the next-best eligible same-epoch candidate with a `meta: true` -subscription, shared across downstream readers. While the reader demands the -track, switch when the active's delivered media timestamp lags the standby's -reported timestamp by more than the reader's max delay, or a fixed 2s for a -reader without one. Until the active delivers its first frame, measure it -from the standby-reported timestamp of the first frame the reader still -needs. Compare payload the active actually delivered against -timestamps the standby reported, never `largest()` values. Neither source -silence nor a reader that stopped reading or applies backpressure establishes -a route failure. At a relay the reader is the aggregated subscription, so -its budget is the largest downstream max delay the aggregate already -carries. Open question for this quest: when one aggregated reader has no -max delay, the aggregate has none either and falls to 2s, which may be -shorter than another reader's budget; decide whether such a reader should -instead leave the others' budget in force. - -Exploration: while demand is outstanding and neither active nor standby -shows progress for that same budget, move the standby slot to the next -eligible candidate, doubling the wait per move until real progress resets -it. With every candidate quiet, the slot keeps cycling at that doubling wait -and nothing fails: the track stays on the active. A healthy third candidate stays discoverable behind an upstream the -active and standby share, while only one steady standby is observed at a -time. Without demand nothing explores. - -Health may exclude an otherwise preferred route from a track, allowing a -lower-priority or more expensive eligible route to serve it. Keep that evidence -local to the affected delivery choice, not a global route-price change or -publisher END. Do not close a shared connection because one track stalled. - -Metadata progress justifies trying a candidate. Promote it to payload with -an update on the same subscription, from the reader's first missing frame, -and demonstrate useful delivery before retiring a still-usable active copy. -Brief overlap during promotion is approved; no steady duplicate payload -pull. Reuse resume's retained in-flight copies and deduplication. - -Never automatically return the track to a demoted preferred route (decided -2026-11-02, reversing the 2026-10-13 line decision to return after useful -media demonstrated recovery). The track stays on the working route until -that route fails, by transport failure or by the same stall evidence; no -payload trials, requalification backoff, or permanent polling of idle -connections. Cancel checks with reader demand, terminal track state, epoch -replacement, and session closure. A newer same-epoch connection is not -automatically a healthier route. - -`rs/moq-net/tests/integration/route_health.rs` pins today's stalls: a silent -kill loses about `detection - max_delay` of media, and a payload stall with live -sessions is never recovered, even while `largest()` keeps pace. Flip both into -resumes through the standby; detection under the reader's max delay loses no -group. - -Mock-time tests cover a preferred route whose metadata advances but media -remains blocked, an active route that never delivers its first frame, -failed promotion, a standby that is normally faster by less -than the budget and so never takes the track, a recovered preferred route -that does not win the track back until the working route fails, a reader -without a max delay using the 2s default, a shared active/standby failure -with a healthy third route, every candidate quiet (one standby at a time, -doubling waits, no route or track failed), -a quiet publisher, receiver backpressure, stale or replayed reports, an epoch -change, multi-hop simultaneous failover, and no -standby for epochless broadcasts. Run through Rust/JS interop and existing CI. -Measure tracks, routes, and readers on both axes; retain the idle-session -poll-count regressions and report overlap, switch counts, and memory. - -Public API: expose only health policy/evidence consumers need, mirrored across -languages if public; settle consequential shape through quest-plan. Wire: uses -Metadata subscriptions, with no separate health-specific route protocol. - -Planned 2026-11-02 (maintainer, follow-up planning after the 2026-11-02 /quest-complete run), from [moq-dev/moq#7096](https://github.com/moq-dev/moq/pull/7096): whether the in-progress group survives a resume depends on whether the upstream cache is warm or cold. Make it one defined behavior and test both cache states. - -## Required - -- [Metadata subscriptions](/quest/m5/route-health/meta.md) - progress-only standby and safe promotion -- [Track route selection](/quest/m5/route-health/selection.md) - independent copies and shared resume diff --git a/quest/m5/route-health/selection.md b/quest/m5/route-health/selection.md deleted file mode 100644 index 56191f0cd0f..00000000000 --- a/quest/m5/route-health/selection.md +++ /dev/null @@ -1,45 +0,0 @@ -# [L] Select route copies per logical track - -## Goal - -A broadcast shares its identity and eligible route handles while each demanded -track can select active and standby copies independently. Existing logical -readers and same-epoch resume remain the single handoff implementation in -Rust and JS, without a route table or full broadcast front per track. - -## Plan - -Decided 2026-10-13: prefer per-track failover so stalled video need not move -healthy audio. Rust TrackIo already owns independent resume producers, but -Front's broadcast-wide serving/upstream source and redispatch need refactoring. -Coordinate JS with its existing logical-track handover, not another P2P or -health-specific reader. The maintainer permits broadcast-level fallback only -if the design work demonstrates disproportionate complexity and records it. - -Keep candidate resolution, epoch/authorization checks and requester exclusions -shared. Select per-track copies from those candidates. A standby is the -next-best eligible candidate (decided 2026-11-02), pinned to that -candidate's session rather than routed through the front, so its -observations measure the candidate itself. Only payload demand creates a -standby. Selection also lets Automatic recovery move the standby slot to the -next eligible candidate, and keeps a promoted copy active until it fails: -nothing here returns a track to a higher-ranked route on its own. Preserve -subscription aggregation and bounded ownership when tracks, candidates, or -downstream readers leave. - -Normal selection still uses application priority, cost, deterministic hashing, -and newest only on otherwise identical routes. This quest provides selection -and lifetime machinery; Automatic recovery owns the detector and exploration. -Never create resumable multi-route state for an epochless broadcast. - -Test independent track switches, changed/missing epoch, a disappearing candidate, -late old-copy frames, cancelled pending resolution, and candidate reuse across -many tracks. Measure tracks times routes/readers, including untouched-track -polls and retained handles. Update affected API docs and bindings if exposed. - -Public API/wire: prefer private selection machinery and existing resume; -report any required surface change. No independent wire extension planned. - -## Required - -- [Routes and announces](/quest/m2/cluster-routing/routes/README.md) - shared candidate and identity model diff --git a/quest/m5/route-interest-prefixes.md b/quest/m5/route-interest-prefixes.md deleted file mode 100644 index f2442f270f9..00000000000 --- a/quest/m5/route-interest-prefixes.md +++ /dev/null @@ -1,36 +0,0 @@ -# [M] A route stream's interest is a set of prefixes - -## Goal - -A route-layer Announce Stream's interest is a set of prefixes instead of -one, so a subscriber that wants several disjoint subtrees opens one stream -rather than one per prefix. An ANNOUNCE_FLOOR certifies the whole set at -one revision or nothing, and the proof's floor and certification sweeps pass -over multi-prefix interests. - -## Plan - -Decided 2026-11-03 (maintainer, follow-up planning after the 2026-11-03 /quest-afk and /quest-complete runs), milestone: - -- m0 -- m1 -- ✅ m2 - -Split out of [Routes and announces](/quest/m2/cluster-routing/routes/README.md) by -[moq-dev/moq#7676](https://github.com/moq-dev/moq/pull/7676), which lands -the route layer's core with a single interest prefix per stream (its -regions are suffixes of that prefix) and leaves this as a separate m2 quest. - -- Define what a whole-set floor certifies (lite-07's floor is a marker over - its one prefix, decided 2026-11-05), and how a sender that knows only some - of the set's prefixes answers. -- Redo the proof's floor and certification sweeps with multi-prefix - interests, including overlapping prefixes and a set that changes. -- Update the lite draft and both implementations together. - -Public API: the route layer's interest type. Wire: an Announce Stream's -interest and what ANNOUNCE_FLOOR certifies on the next unpublished lite version. - -## Related - -- [Routes and announces](/quest/m2/cluster-routing/routes/README.md) - the single-prefix route layer this extends diff --git a/quest/m5/routing-cost-domains.md b/quest/m5/routing-cost-domains.md deleted file mode 100644 index 822f772906a..00000000000 --- a/quest/m5/routing-cost-domains.md +++ /dev/null @@ -1,85 +0,0 @@ -# [M] Design administrative routing cost domains - -## Goal - -Settle how independently operated MoQ networks exchange reachability without -adding incomparable costs, at the boundaries between operators on the one node id space -[Cluster routing](/quest/m2/cluster-routing/README.md) routes over. Cost inside -one operator's network is cluster-routing's. This includes whether a boundary -may fold a large customer cluster's nodes into one advertised node, and how -that keeps loop safety. Produce a -reviewed design and scoped implementation quests, not a protocol -implementation. Each operator, such as moq.pro or a self-hosted relay, -retains its own business policy; no RTT/loss-driven repricing or automatic -performance failover is authorized by this work. - -## Plan - -Decided 2026-10-13: basic outbound local-cluster federation is required and -belongs to [Outbound federation](/quest/m2/cluster-routing/federation.md), -not this quest. Identity, namespace admission, local connection priorities, -and export policy are settled with cluster routing. This quest stays parked -for economic cost translation and origin aggregation until those have a -consumer; do not make them prerequisites of connecting a self-hosted relay. - -Costs reflect SKU, directional egress economics, provider affinity, and marginal -transfer savings. A hosting provider is not necessarily a policy domain: -moq.pro can coordinate one model across its OVH and Linode nodes. Domain -membership must come from an operator-controlled trust boundary, not a peer's -unverified assertion. Whatever identifies a boundary must hold to these -operator-safety constraints: - -- A boundary is an explicitly configured link with an expected remote - identity. A URL, an observed address, or the `peer` grant alone does not - make a link a boundary. -- The identity is bound to the authenticated link, whichever side dialed, - never taken from a route or announcement. -- A missing, malformed, or mismatched boundary identity is fatal: refuse it - at startup or drop the link. -- `cluster.id` is never reused as a domain identity. It is one node's id, and - sharing it across nodes merges distinct origins. - -Investigate a shared cost model within a coordinating domain and explicit -import/export policy at its boundaries. A remote number is not comparable to -ours merely because both are integers. Prefer local policy and existing -mechanisms where sufficient; do not prescribe a new domain identifier, cost -vector, or exchange-rate scheme before demonstrating its necessity. Separate -reachability and loop prevention from optional economic hints. Business logic -stays outside the base media protocol; justify any minimal cluster extension -against a configuration-only alternative. - -Use these references to evaluate the design: - -- [BGP, RFC 4271](https://www.rfc-editor.org/rfc/rfc4271.html): LOCAL_PREF, - import/export policy, AS_PATH, and MED's same-neighbor comparison scope. -- [MED considerations, RFC 4451](https://www.rfc-editor.org/rfc/rfc4451.html): - scoped comparisons and oscillation risks. -- [Large Communities, RFC 8092](https://www.rfc-editor.org/rfc/rfc8092.html): - namespaced policy signals rather than universally comparable prices. -- [Inter-domain TE, RFC 7926](https://www.rfc-editor.org/rfc/rfc7926.html): - abstract reachability across domains without exposing complete internals. -- [Gao and Rexford](https://www.cs.princeton.edu/~jrex/papers/ton01-stable.pdf): - conditions for policy convergence; loop prevention alone does not prove it. - -The design must work through examples of two operators using different scales, -multiple entrances to one domain, asymmetric charges, mixed-provider nodes in -one domain, unknown or untrusted peers, and a route leaving and re-entering a -domain. Preserve loop safety across any metric rewrite. -State tradeoffs, migration and -mixed-version behavior, and the limits of any convergence claim. - -Reconcile with cluster-routing's configured link costs rather than creating -a second peer-policy mechanism. Completion is a documented decision, -worked counterexamples or model checks, and independently completable follow-up -quests. Open wire/API choices belong to this design exercise. - -## Required - -- [Cluster routing](/quest/m2/cluster-routing/README.md) - the route layer this designs policy on - -## Related - -- [#3769](https://github.com/moq-dev/moq/pull/3769) - measurement-based pricing - prompted the separation of measurement, operator policy, and protocol -- [#4718](https://github.com/moq-dev/moq/pull/4718) - the dropped - cluster-domain hop plan the boundary constraints come from diff --git a/quest/m5/stats-encoder-feedback.md b/quest/m5/stats-encoder-feedback.md deleted file mode 100644 index 821d42c5345..00000000000 --- a/quest/m5/stats-encoder-feedback.md +++ /dev/null @@ -1,101 +0,0 @@ -# [M] A Rust encoder adapts its bitrate to what its viewers report - -## Goal - -A `moq-video` or `moq-audio` encode producer given a feedback handle solicits -feedback in its catalog. It reads the feedback track from every `.echo` -broadcast announced under the catalog's echo path, and lowers its bitrate -while viewers report stalls and late frames, beside the congestion estimate -it already follows. Keyframe requests stay out. - -## Plan - -Deferred in the 2026-09-30 audit and moved to the deferred milestone (now m5) in the 2026-10-05 audit: no named consumer; the media stats it -reads land first in m3. - -Decided 2026-10-08: parked, and the transcode leg is out. The -[ladder controller](/quest/m5/ladder/controller.md) owns every -`moq-transcode` rung's target, so `moq transcode --echo` feeds the folded -stall signal to that controller rather than to `rate::Control`; split it -into its own quest requiring the controller if this is revived. This quest -covers the encode producers and `moq import --echo-path`, which need no ladder. - -- `encode::Capture` in `rs/moq-video` and `encode::Options` in - `rs/moq-audio` (the producer options, beside `bandwidth`) gain - `echo: Option`. - - The handle is built from an `origin::Consumer` and the echo path, - resolved against the publisher's broadcast. - - It consumes `.echo` announcements under that path, subscribes to the - feedback track on each, and reads its own renditions by ID. - - It folds the reports into one signal: the share of viewers stalled over - the last interval and their late frame rate, weighted equally per viewer. - - The counters are cumulative, so the handle keeps the previous snapshot - per viewer, keyed by (path, epoch) like `moq_stats::aggregate`, and diffs - it. A restarted viewer announces a new epoch and gets a fresh baseline. - Only on a route without an epoch does a counter that goes backwards mean - a restart and reset that baseline. - - A viewer counts toward a rendition while its latest snapshot has a row - for that ID, so viewers of other rungs, or ones that switched away, - never dilute the share. The announcement, not the age of its last - report, keeps that snapshot current: an unchanged snapshot sends no frame, so a quiet healthy - viewer must not age out. Diffing already makes one stall long - ago contribute nothing to later intervals. -- Trust (2026-09-29): the token prefix is the boundary. Any viewer the - application's tokens let publish under the echo path counts. How far - viewers may move the target is application-specific (a simulcast ladder - suffers less from one viewer than a single rendition), so the step-down - policy is built in but takes a tunable config struct: a minimum viewer - count or quorum, a bitrate floor, and the stalled-share threshold, with a - way to disable it. Reason: a safe default without hard-coding one - application's policy. -- `moq_mux::rate::Control` takes that signal beside the bandwidth estimate. - A stalled share above the threshold steps the target down like a bandwidth - drop, never below the floor; recovery follows the existing decay ramp, - and the estimate stays the ceiling. Audio does not follow its grant today - (`Options::bandwidth` in `rs/moq-audio/src/encode/producer.rs` reserves - only). It follows this signal only once the grant quest lands; until then - the loop drives video. -- `moq import --echo-path `, which already sets the catalog's `echo` - section ([Rust stats](/quest/m3/stats/rust.md)), also wires the handle. -- Test: the CLI publishes to a relay, and two `moq play --echo` viewers - report under the echo path, one of them throttled through the impairment - profile. The target bitrate drops within two intervals of the throttled - viewer reporting stalls, and recovers after it stops. A unit test on mocked - time checks that the quorum and floor bound one viewer's influence. -- A benchmark sweeps viewers and renditions per snapshot, runs at least - nightly, and shows one interval's fold growing with the rows it reads, not - a full-table scan per rendition. -- Document the flag in `doc/bin/cli.md` and the loop and its config in the - moq-video README. - -Open, to settle before starting (moved from the -[media stats](/quest/m3/stats/README.md) line): - -- **Referenced-rendition feedback.** A derivative catalog (a `moq-transcode` - passthrough) collects feedback for a source rendition it lists, but owns - no encoder for it, and the source encoder reads only its own catalog's - prefix. Candidates: the derivative forwards those rows to the source's - echo path, or the source encoder also reads catalogs that reference it, - or referenced renditions stay report-only. -- **Shared echo prefixes.** Two catalogs can resolve their echo paths to one - prefix (`../viewers` from `room/a/live` and `room/b/live`). Then a viewer - using one name for both closes one `.echo` with the other, and each - publisher reads the other's reports under a shared ID. Candidates: - require each catalog's echo prefix to be its own, as application policy - like the token rights, or carry the catalog's broadcast in the snapshot - and ignore reports for another. - -Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): encoders take pressure, not echo. `moq_mux::rate::Control` accepts a generic pressure input beside the bandwidth estimate; a hang or moq-stats aggregator turns announced echoes into it, moq-cli wires the two, and the encode producers drop their `echo` option. - -## Required - -- [Rust reporters](/quest/m3/stats/rust.md) - the viewers that report and - the CLI it wires - -## Related - -- [Ladder controller](/quest/m5/ladder/controller.md) - owns the rung targets a split-out transcode leg would feed -- [Audio follows the grant](/quest/m5/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - - the audio rate follow this signal would feed -- [Ladder](/quest/m5/ladder/README.md) - the transcode ladder, which today - encodes every rung at a fixed rate with no bandwidth input diff --git a/quest/m5/unreal.md b/quest/m5/unreal.md deleted file mode 100644 index 35df677bfc1..00000000000 --- a/quest/m5/unreal.md +++ /dev/null @@ -1,31 +0,0 @@ -# [M] Unreal prototype: a UE5 module on the C++ package - -## Goal - -A written go/no-go verdict on shipping an Unreal Engine plugin. The evidence -is `cpp/unreal`: a UE5 module that links the prebuilt C++ package with -exceptions disabled, subscribes to a broadcast from a Blueprint node, and -renders decoded video into a `UTexture2D`, measured for frame latency and -editor stability across a play-stop-play cycle. - -## Plan - -In m5 until an Unreal consumer asks; the C++ package it links already exists. - -- Consume the release tarball through the module's `Build.cs` - (`PublicAdditionalLibraries`, include paths); Unreal's build does not use - vcpkg or CMake, which is why the tarball exists alongside the registries. - Keep `bEnableExceptions` off to prove the `expected` error style holds. -- Marshal futures onto the game thread with `AsyncTask(ENamedThreads::GameThread, ...)` - as the `moq::Executor`; never touch `UObject`s from a continuation. -- Decode: the moq-ffi video consumer feeds the texture; the CPU frame path - is enough for the verdict, GPU import is not measured here. -- Record: editor hot-reload behavior with a static Rust library loaded, the - dispatcher shutdown on module unload, and package size. -- A positive verdict proposes a plugin quest in the then-current feature - horizon for maintainer prioritization; it does not automatically gate a - release. Otherwise abandon this with the reasons. - -## Required - -- [First C++ package release](/quest/m3/release/cpp-release.md) - the tarball the module links diff --git a/quest/m5/video-codec-coverage.md b/quest/m5/video-codec-coverage.md deleted file mode 100644 index 04d47db3ccf..00000000000 --- a/quest/m5/video-codec-coverage.md +++ /dev/null @@ -1,35 +0,0 @@ -# [M] Prioritize remaining native and portable video codec coverage - -## Goal - -Identify which missing decoder/backend coverage serves actual consumers after -the existing platform and NVIDIA work, without adding mandatory build costs. - -## Plan - -Review AV1 decode through Apple VideoToolbox and Windows Media Foundation, -and a portable software AV1 fallback such as -[dav1d](https://code.videolan.org/videolan/dav1d). Establish actual framework, -OS, extension, hardware, format, and fixture requirements; a browser playing -a codec is not proof that our native backend can open it. - -NVIDIA AV1 encode/10-bit already has quests; keep those owners. VA-API gaps, -such as HEVC Main 10 decode, have no owner and are in scope here. Software VP8/VP9 decode is libvpx behind moq-video's `vpx` feature; -hardware VP8/VP9 decode is in scope here. Windows NVIDIA support needs a demonstrated advantage over -the existing native path. If revisiting software AV1 encoding, measure the -target real-time workload and build cost rather than assuming all presets or -all hardware are equivalent. Optional codec dependencies stay optional. - -Produce a supported/refused matrix and separately completable implementation -quests only for justified gaps. Each selected backend needs decode fixtures, -drain/color/timestamp proof, and a CI or explicit hardware validation lane. -Use the settled Frame/output/codec extension points; no parallel surface API. - -Public API and wire: no changes during this study. - -Decided 2026-10-08: moved to m3. No consumer has asked for a missing codec. - -## Related - -- [NVIDIA formats](/quest/m5/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md) - 10-bit HEVC scope; AV1 encode moved to [NVENC AV1](/quest/m5/nvenc-av1.md) -- [VP8/VP9 in OBS](/quest/m3/obs-moq-video/vpx-obs.md) - the software decoder reaching the OBS source diff --git a/quest/m5/video-hardware.md b/quest/m5/video-hardware.md index 658b74634fe..e19a36d5d48 100644 --- a/quest/m5/video-hardware.md +++ b/quest/m5/video-hardware.md @@ -65,8 +65,7 @@ PipeWire node (spa-libcamera). Record the mode that opened, whether frames arrived, and whether the producer used one memory block or one per plane. No new capture API, and no libcamera source. -A separate-plane producer belongs to -[multi-plane cameras](/quest/m5/pipewire-camera-planes.md); if that is why a +A separate-plane producer is not planned; if that is why a Pi produces nothing, write it down and stop. `doc/lib/rs/moq-video.md` says both paths are reachable; correct that sentence if one cannot capture. @@ -100,5 +99,4 @@ is not a bug any amount of review finds. ## Related - [#2819](/quest/m4/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md) - the DMA-BUF import validation this capture feeds -- [Capture multi-plane PipeWire cameras](/quest/m5/pipewire-camera-planes.md) - separate-plane I420 and NV12, when the Pi pass finds them - [Embedded video path](/quest/m5/video-embedded.md) - presenting on a Pi, which is a different gap diff --git a/quest/m5/watch-webxr.md b/quest/m5/watch-webxr.md deleted file mode 100644 index 8d9a1e885ce..00000000000 --- a/quest/m5/watch-webxr.md +++ /dev/null @@ -1,30 +0,0 @@ -# [M] The watch element renders spatial video through WebXR layers - -## Goal - -On a headset browser with WebXR layers, `` presents a rendition -whose catalog says `projection: equirectangular` in an immersive session -through an `XREquirectLayer`: the horizontal span comes from `fov`, and the -layer layout from `stereo`, mapping `left-right` to `stereo-left-right`, -`top-bottom` to `stereo-top-bottom`, and `mono` or absent to `mono`. A flat -rendition, and a browser without WebXR layers, play as today. - -## Plan - -Decided with the maintainer on 2026-10-20, from the follow-ups of -[#5543](https://github.com/moq-dev/moq/pull/5543), which landed the fields. - -- `XRMediaBinding` layers take an `HTMLVideoElement`, which `` - does not use (it decodes with WebCodecs), so an `XRWebGLBinding` layer fed - each decoded frame is the likely path. Check whether a WebGPU XR binding is - usable yet. -- Entering an immersive session needs a user gesture, so the UI offers it - only when the browser supports layers and the rendition is spatial. -- Ambisonic audio playback is out of scope; propose it as a follow-up. - -Tests: a mocked XR session checks the layer each catalog produces, all three -layouts included, and is wired -into CI; a manual run on a headset browser proves playback. - -Public API: possibly a `` attribute to enter or disable immersive -playback. Wire: none. diff --git a/quest/m5/webgpu-hdr.md b/quest/m5/webgpu-hdr.md deleted file mode 100644 index bea853dc759..00000000000 --- a/quest/m5/webgpu-hdr.md +++ /dev/null @@ -1,42 +0,0 @@ -# [M] HDR video renders as HDR - -## Goal - -An HDR rendition (PQ or HLG) plays as HDR in the browser where the display -and browser can show it: the `@moq/video` WebGPU renderer converts the frame -itself and presents through an `rgba16float` canvas with extended tone -mapping. Elsewhere it is tone-mapped to SDR deliberately, instead of being -drawn as if it were SDR as today. - -## Plan - -Decided 2026-10-08 in the WebGPU renderer `/quest-plan` interview: SDR and -wide gamut first in the `@moq/video` WebGPU renderer (`js/video`). HDR -follows here; the catalog colour fields it reads landed in #5846. - -Facts (2026-10): - -- HDR canvas output: - `configure({ format: "rgba16float", toneMapping: { mode: "extended" } })` - ships on Chromium desktop since Chrome 129. Safari 26's release notes list - HDR for WebGPU canvases without a device or display matrix, and an earlier - WebKit build accepted `extended` while displaying SDR (WebKit bug 272702), - so Safari is unverified. Firefox has none. Canvas2D has no HDR output. -- `importExternalTexture` and `copyExternalImageToTexture` carry no HDR - headroom (gpuweb#5236 is open), so imported video is SDR. HDR needs the - renderer to convert the frame itself: read the planes, apply the matrix, - range, transfer (PQ or HLG), and primaries, and tone-map when the display - has less headroom. -- `VideoFrame.colorSpace` gives primaries, transfer, matrix, and range - (Chrome 94, Firefox 130, Safari 16.4). Mastering display and content light - levels come from the rendition's catalog `color`. - -Settle while building: whether the HDR path gives up zero copy (planes via -`copyTo` and a custom conversion shader), and how the renderer detects -display headroom. - -Tests: an HDR10 rendition renders extended on Chromium desktop and on Safari -26 with an HDR display if it does show extended output, tone-maps to SDR -where extended output is unavailable, and an SDR rendition is unchanged. - -Public API: none beyond the renderer. Wire: none.