From 263775aca851bcba52e3d21717627a4466a1f08a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 27 Oct 2026 22:06:03 -0700 Subject: [PATCH 1/2] quest: plan the 2026-10-27 refactor audit's new findings Co-Authored-By: Claude Opus 5.5 --- quest/m2/README.md | 5 +++++ quest/m2/dispatch-modules.md | 31 +++++++++++++++++++++++++++++ quest/m2/track-publication-state.md | 28 ++++++++++++++++++++++++++ quest/m2/ui-shared-controls.md | 27 +++++++++++++++++++++++++ quest/m2/usage-settings-once.md | 28 ++++++++++++++++++++++++++ quest/m2/watch-support-probe.md | 26 ++++++++++++++++++++++++ 6 files changed, 145 insertions(+) create mode 100644 quest/m2/dispatch-modules.md create mode 100644 quest/m2/track-publication-state.md create mode 100644 quest/m2/ui-shared-controls.md create mode 100644 quest/m2/usage-settings-once.md create mode 100644 quest/m2/watch-support-probe.md diff --git a/quest/m2/README.md b/quest/m2/README.md index 67de43cc562..aedae9b768d 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -118,6 +118,7 @@ lite-07; bitrate enforcement is not part of this release. - [Resume as producer replacement](/quest/m2/resume-redesign.md) - route changes replace the writer of one track state, deleting the per-reader resume path in Rust and JS - [moq-transport requests end through one lease](/quest/m2/ietf-request-lease.md) - every IETF request ends through one polled lease, and the two 18k-line files split by mechanism - [A moq-transport group head fills its hole in place](/quest/m2/ietf-fill-refill.md) - fills and joining FETCHes write into the tail's group, deleting the `Fill` handoff +- [Track publication is one state](/quest/m2/track-publication-state.md) - one enum replaces the published, staged, and claimed flags on `TrackState` - [Announce interest streams share one route table](/quest/m2/announce-interest-memory.md) - per-stream announce cost follows what is in flight, not every route - [One relay serve path for every runtime](/quest/m2/relay-serve-path.md) - io_uring serves through the shared `Connection::serve` and config mapping - [A parked read of a resumed group reads its budget without re-syncing](/quest/m2/recover-budget.md) - measure, then drop the per-frame reader sync @@ -136,6 +137,8 @@ lite-07; bitrate enforcement is not part of this release. - [Hang contribution references](/quest/m2/contribution-ref.md) - a catalog names a whole contribution broadcast that a player opens only when selected, backing moq.pro's composed rooms - [Synced data playback](/quest/m2/watch-data-sync.md) - js/watch releases JSON and binary payloads on the media playhead, and a slow data track holds media back - [Watch decode gate](/quest/m2/watch-decode-gate.md) - video lookahead stays encoded until it is near presentation, like audio +- [One support probe for watch audio and video](/quest/m2/watch-support-probe.md) - one probe helper with video's cache, and audio reports unsupported renditions +- [Shared fullscreen, formatters, and stats cards in @moq/ui](/quest/m2/ui-shared-controls.md) - watch and publish stop keeping copies of their shared controls - [moqsrc A/V sync](/quest/m2/moqsrc-av-sync.md) - a nightly test measures A/V skew from `moqsrc` through clock-synced sinks - [MP4 export](/quest/m2/mp4-export.md) - `moq export mp4 --output` records crash-safe fragments, then finishes a regular MP4 with moov at the end - [Importers fill the VR fields](/quest/m2/mux-vr-fields.md) - MP4, Matroska, and Opus imports set the catalog's projection, stereo, and ambisonic layout @@ -225,6 +228,7 @@ lite-07; bitrate enforcement is not part of this release. - [Dependency and alternatives audit](/quest/m2/audit-deps.md) - dependencies are current, deduplicated, needed, and the best maintained option - [Dead code and API surface audit](/quest/m2/audit-dead-code.md) - repeat the removal audit before the next major release - [Typecheck with bun check](/quest/m2/bun-check.md) - workspace packages typecheck through bun once nixpkgs ships bun 1.4.4 +- [Declare each check module once in the dispatcher](/quest/m2/dispatch-modules.md) - one registration call per module replaces its parallel tables - [Test coverage audit](/quest/m2/audit-test-coverage.md) - repeat the coverage audit against the m1 baselines after the next release ships - [Documentation audit](/quest/m2/audit-docs.md) - repeat the docs audit after the release ships, against the m1 baselines - [Test cost audit](/quest/m2/audit-test-cost.md) - the slowest, flakiest, and least valuable tests are fixed, deleted, or planned once the release ships @@ -234,6 +238,7 @@ lite-07; bitrate enforcement is not part of this release. - [Performance audit](/quest/m2/audit-perf.md) - benchmarks that regressed since the m1 run are explained, fixed, or planned, and unbenched hot paths get coverage - [Simplification audit](/quest/m2/audit-simplify.md) - repeat the simplification audit, starting with the m1 leftovers, after the release ships - [Upstream unknown-env option in usage-rs](/quest/m2/usage-unknown-env.md) - jdx/usage refuses unknown prefixed env vars, replacing the moq-tokio helper +- [Upstream single-declaration settings in usage-rs](/quest/m2/usage-settings-once.md) - waiting on approval to post, then jdx/usage builds the registry from Cli fields - [Artifact size audit](/quest/m2/audit-size.md) - repeat the shipping, native, WASM and browser attribution after the release ships - [Compile time audit](/quest/m2/audit-compile-time.md) - build-time hotspots are measured against the m1 baselines, starting with the transport share now that moq-net compiles once, and the worst are fixed or planned - [Lint override and deprecation audit](/quest/m2/audit-lints.md) - repeat the suppression and deprecation audit after the release ships, starting with clippy on the macOS and Windows targets diff --git a/quest/m2/dispatch-modules.md b/quest/m2/dispatch-modules.md new file mode 100644 index 00000000000..893fd0fa3d9 --- /dev/null +++ b/quest/m2/dispatch-modules.md @@ -0,0 +1,31 @@ +# [M] Declare each check module once in the dispatcher + +## Goal + +`sh/dispatch.sh` declares each module in one `module` registration call +(scope pattern, tools, whether it compiles Rust, lane, runs alone) that fills +the tables it reads today, instead of listing the module separately in +`scope`, `tools`, `compiles`, `lane`, `alone`, and the lane order. Selection +and scheduling are unchanged. No public API or wire impact. + +## Plan + +Decided 2026-10-27 (maintainer interview, from the 2026-10-27 refactor audit): +stay in bash with a registration function; porting the dispatcher to Python +was declined. + +- Keep each table's comment with the module it explains. +- Preserve the Bun lane (concurrent `bun install` breaks), the shared C++ + build lane, and Dart running alone. +- Prove equivalence with the existing `sh/dispatch-query.test.py` and + `sh/changed.test.py`, plus a before/after diff of `just ci-select` output for + a few representative diffs. +- Waits for the select audit, which is editing the same script. + +## Required + +- [Replay full-run failures against CI's selected gate](/quest/m0/ci/select-audit.md) - lands its `dispatch.sh` changes first + +## Related + +- [The relay's NixOS module is tested](/quest/m2/nix-relay-module.md) - also edits the dispatcher's module map diff --git a/quest/m2/track-publication-state.md b/quest/m2/track-publication-state.md new file mode 100644 index 00000000000..d2d991afaeb --- /dev/null +++ b/quest/m2/track-publication-state.md @@ -0,0 +1,28 @@ +# [S] Track publication is one state + +## Goal + +`TrackState`'s `published`, `staged`, and `claimed` booleans +(`rs/moq-net/src/model/track.rs`) become one private enum, so a combination +the lifecycle never reaches, such as staged but unpublished, cannot be +represented. Each transition is one method that sets the whole state. No API +or wire impact. + +## Plan + +Decided 2026-10-27 (maintainer interview, from the 2026-10-27 refactor audit): +narrow to publication only. A broader split of `TrackState` by invariant was +declined; `info` stays separate because a reverse fetch installs it before +acceptance, and the `arrival` and `evict` indexes stay distinct. + +- Today's transitions: `Request::claim` sets `claimed`; `Request::stage` sets + `published` (through `accept`) and `staged`; `Staged::commit` clears + `staged`. So the states are pending, claimed, staged, and published, and a + claimed request can still be staged and published. +- Readers: `poll_info` hides `info` while staged, and the reject check treats + anything but pending as answered. +- Waits for front eviction, which is rewriting the same file. + +## Required + +- [Front eviction](/quest/m1/unbounded-groups/front-eviction.md) - lands its `track.rs` rewrite first diff --git a/quest/m2/ui-shared-controls.md b/quest/m2/ui-shared-controls.md new file mode 100644 index 00000000000..3817a1c99a7 --- /dev/null +++ b/quest/m2/ui-shared-controls.md @@ -0,0 +1,27 @@ +# [M] Shared fullscreen, formatters, and stats cards in @moq/ui + +## Goal + +`@moq/watch` and `@moq/publish` import their fullscreen controller, +fullscreen button, human-readable formatters, and stats card and row builders +from `@moq/ui` instead of each keeping a copy. Each panel keeps its own +metrics and subscriptions. Additive exports only; no wire impact. + +## Plan + +Decided 2026-10-27 (maintainer interview, from the 2026-10-27 refactor audit): +include the stats primitives, not just fullscreen and formatters. + +- The two `ui/fullscreen.ts` copies differ only in comments and where + `enterPseudo`/`exitPseudo` are declared. The two `components/fullscreen-button.ts` + and `ui/format.ts` copies are near-identical; watch's `format.ts` adds + `formatMillis`. +- `card` and `line` in `js/watch/src/ui/stats.ts` and + `js/publish/src/ui/components/stats-tab.ts` are byte-identical. Move those + and the matching stats styles; leave `rate`, `track`, `trackActive`, and the + metric wiring in each package. +- The shared controller exposes its state as a signal instead of today's + `subscribe` listener set, per the repo's no-callback rule. +- Verify in a browser: real fullscreen, the iPhone pseudo-fullscreen class, + a rejected request (not a user gesture), and teardown removing the document + listeners. diff --git a/quest/m2/usage-settings-once.md b/quest/m2/usage-settings-once.md new file mode 100644 index 00000000000..97fd021a541 --- /dev/null +++ b/quest/m2/usage-settings-once.md @@ -0,0 +1,28 @@ +# [S] Upstream single-declaration settings in usage-rs + +## Goal + +usage-rs ([jdx/usage](https://github.com/jdx/usage)) builds the settings +registry from `#[derive(Cli)]` fields that carry `setting = "key"`, so +`rs/moq-tokio/src/settings.rs` and `rs/moq-relay/src/settings.rs` (626 lines +declaring every merged flag a second time) are deleted after a bump. Source +presence, precedence, deprecated-name rejection, and provenance keep working. +CLI behavior and wire are unchanged. + +## Plan + +Waits on two outside conditions, in order: + +1. The maintainer approves posting the proposal on jdx/usage. Decided + 2026-10-27 (maintainer interview): ask before posting; no approval yet. +2. Upstream ships it. Check the issue and usage-rs releases. + +Today `usage::Cli` and `usage::Config` reject each other's attributes, and +`Registry::drift` tests the two declarations agree. The Cli side already names +`env` and `setting` per field; the registry side adds the type and `parse`. +Propose inferring those from the field so one declaration serves both. If +upstream declines, delete this quest and keep the drift test. + +## Related + +- [Upstream unknown-env option in usage-rs](/quest/m2/usage-unknown-env.md) - another jdx/usage ask; file both together if both are approved diff --git a/quest/m2/watch-support-probe.md b/quest/m2/watch-support-probe.md new file mode 100644 index 00000000000..d41718ea7b5 --- /dev/null +++ b/quest/m2/watch-support-probe.md @@ -0,0 +1,26 @@ +# [S] One support probe for watch audio and video + +## Goal + +The watch audio and video `Source`s probe rendition support through one +private helper that owns the race against an unsettled probe, the config-keyed +cache, `pending`, and abort. Audio gains video's cache and an `out.error` that +is `NotSupportedError` when no audio rendition is supported, and the bundled +UI's unsupported indicator reports an audio-only broadcast it cannot play. +Rendition selection stays separate per kind. Additive `@moq/watch` API; no +wire impact. + +## Plan + +Decided 2026-10-27 (maintainer interview, from the 2026-10-27 refactor audit): + +- Audio exposes `out.error` like video, and the unsupported indicator is its + consumer: it fires when video is unsupported, or when the catalog has no + video and audio is unsupported. +- Video's `#runSupported` (`js/watch/src/video/source.ts`) caches per + rendition by `supportCacheKey` or the JSON config and sets the error; audio's + (`js/watch/src/audio/source.ts`) re-probes every run and only logs. The + helper takes video's behavior for both. +- Test a catalog replaced while a probe is pending, a probe that never + settles, a rejecting probe, and a catalog change that leaves configs + unchanged (served from cache). From 1e1aac4c2267782528eab168cc6be7a610da0c6c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 29 Oct 2026 08:24:03 -0700 Subject: [PATCH 2/2] quest: unblock dispatch-modules, the select audit landed in #6991 Co-Authored-By: Claude Opus 5.5 --- quest/m2/dispatch-modules.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/quest/m2/dispatch-modules.md b/quest/m2/dispatch-modules.md index 893fd0fa3d9..4cfff2b12f5 100644 --- a/quest/m2/dispatch-modules.md +++ b/quest/m2/dispatch-modules.md @@ -20,11 +20,6 @@ was declined. - Prove equivalence with the existing `sh/dispatch-query.test.py` and `sh/changed.test.py`, plus a before/after diff of `just ci-select` output for a few representative diffs. -- Waits for the select audit, which is editing the same script. - -## Required - -- [Replay full-run failures against CI's selected gate](/quest/m0/ci/select-audit.md) - lands its `dispatch.sh` changes first ## Related