diff --git a/quest/README.md b/quest/README.md index 97c5ad7b97a..677705a8c92 100644 --- a/quest/README.md +++ b/quest/README.md @@ -7,20 +7,22 @@ grouped into milestones ordered by priority. ## Plan -Milestones sort by kind, which tracks urgency here: m0 fixes what is broken, +Milestones sort by kind, which tracks urgency here: m0 blocks the release, m1 is the dev branch line, m2 grows the surface, m3 explores. The 2026-08 grooming turned every surviving GitHub issue into a quest and migrated the upstream-facing questlines from the downstream moq.pro tree; issues opened since are imported in periodic grooming passes (the last one on 2026-09-05), -and an issue already fixed on `dev` stays open until `dev` merges. New work joins the milestone matching its -kind, at its priority rank. +and an issue already fixed on `dev` stays open until `dev` merges. The +2026-09-12 pass narrowed m0 to the release blockers and moved every additive +dev quest to m2. New work joins the milestone matching its kind, at its +priority rank. ## Quests -- [m0: bug fixes](/quest/m0/README.md) - defects in what main ships today, - security first +- [m0: release blockers](/quest/m0/README.md) - what must land before dev + merges and the release is cut - [m1: the dev line](/quest/m1/README.md) - the breaking API and wire - changes, the archive line that gates the dev merge, and the merge itself + changes, the merge gates, and the merge itself - [m2: features](/quest/m2/README.md) - new capabilities on stable surfaces, from wire extensions to E2EE to developer packages - [m3: prototypes](/quest/m3/README.md) - experiments, spikes, hardware diff --git a/quest/m0/3492-ietf-track-status-refusal.md b/quest/m0/3492-ietf-track-status-refusal.md deleted file mode 100644 index d8668ccf402..00000000000 --- a/quest/m0/3492-ietf-track-status-refusal.md +++ /dev/null @@ -1,37 +0,0 @@ -# [XS] TRACK_STATUS is refused, not dropped - -## Goal - -A moq-transport peer that sends TRACK_STATUS gets an immediate refusal with the -registered NOT_SUPPORTED code on every negotiated draft, instead of a warning in -our log and a request that hangs until the peer's timeout. TRACK_STATUS itself -stays unimplemented: all it adds over TRACK_INFO is a snapshot of the latest -object, and answering it honestly needs either a new API or a throwaway -SUBSCRIBE. PR #3519 built the latter and was closed for it. - -## Plan - -`rs/moq-net/src/ietf/publisher.rs` matches `ietf::TrackStatus::ID` with a -warning and an empty future; `session.rs` already routes the stream there, so -nothing is session-fatal. Mirror `run_publish_stream` in `subscriber.rs`, which -answers PUBLISH with NOT_SUPPORTED and closes the writer explicitly (#3348): - -- Decode the request so the stream is consumed, reply with the per-draft - refusal (TRACK_STATUS_ERROR on draft-14, REQUEST_ERROR from draft-15 on) using - the code type [IETF error codes](https://github.com/moq-dev/moq/pull/3531) introduces, - and close the writer. On draft-14 and 15 the request rides a virtual stream - over the control stream whose reset is a no-op, so the explicit reply is the - only way bytes reach the peer. -- `js/net/src/ietf/publisher.ts` already replies; make it send the same code. -- Tests: a byte-exact transport-log test per version that a TRACK_STATUS request - yields the refusal and nothing else. - -Branch from dev, where the error registry lands. - -## Required - -- [IETF error codes](https://github.com/moq-dev/moq/pull/3531) - the registered NOT_SUPPORTED value per draft comes from its code type - -## Closes - -- [#3492](https://github.com/moq-dev/moq/issues/3492) - close this issue when the quest finishes diff --git a/quest/m0/3532-connect-auth-race.md b/quest/m0/3532-connect-auth-race.md index 5453084a672..6a78e926d96 100644 --- a/quest/m0/3532-connect-auth-race.md +++ b/quest/m0/3532-connect-auth-race.md @@ -2,14 +2,12 @@ ## Goal -`moq_native::Client::connect` against a WebTransport-only endpoint succeeds +`moq_tokio::Client::connect` against a WebTransport-only endpoint succeeds whenever the QUIC dial succeeds, even when the WebSocket fallback is refused first. Cloudflare's relays answer every non-WebTransport request with 403, and today that 403 landing inside the 200 ms fallback delay fails the whole connect as Forbidden while the QUIC arm is still in flight, indistinguishable from a bad -token. An auth error ends the race only when the other arm has also failed, and -a moq-ffi caller can disable the WebSocket fallback the way libmoq and the CLI -already can. +token. An auth error ends the race only when the other arm has also failed. Boundaries: blind subscription, consuming a broadcast the peer never announced, stays refused. A client here may hold several connections and cannot pick one @@ -19,27 +17,48 @@ non-conformant, not a gap in this repo. ## Plan -- `race_transport_connect` in `rs/moq-native/src/client.rs` returns on - `err.is_auth()` from either arm. Record an auth error like any other failure - and keep polling the other arm. When both are done, the result is an auth - error only if both arms rejected authentication; otherwise report the - non-auth failure, which stays retryable, because `Reconnect::run` exits on - `is_auth()` and a fallback endpoint that answers every non-WebTransport - request with 403 must not stop the client from retrying a QUIC dial that - merely failed transiently. Flip - `race_transport_connect_stops_on_quic_auth_error` and add: WebSocket 403 then - QUIC success connects; both arms refusing reports Forbidden; a transient QUIC - failure after a WebSocket 403 reports the QUIC error and the reconnect loop - retries. -- `MoqClient` in `rs/moq-ffi/src/session.rs` gains `set_websocket_enabled` and - `set_websocket_delay` beside `set_tls_disable_verify`, mapping onto - `websocket::Client::{enabled, delay}`. libmoq already exports - `moq_client_set_websocket_enabled` and `_delay`; mirror the two setters in - `py/moq-rs`, `swift`, `kt`, `go/wrapper/moq`, `dart/moq`, and - `doc/lib/{py,swift,kt,go,dart}`. - -On main, additive. +Branch from dev: `rs/moq-tokio` exists only there, and main still ships the +deprecated `rs/moq-native`. + +`race_transport_connect` (`rs/moq-tokio/src/client.rs:642`) polls both arms +in a `select!` loop. Each arm has an early return on `err.is_auth()`: the QUIC +arm at line 660 and the WebSocket arm at line 671. Every other failure is +recorded and the loop keeps polling the other arm, then line 690 folds the +pair: both failed is `Error::TransportRace`, one failed is that error, neither +ran is `ConnectFailed`. `connect_inner` calls it at line 564 with the +WebSocket arm from `websocket::race_handle` (`rs/moq-tokio/src/websocket.rs:228`), +which yields `None` when the fallback is disabled and otherwise dials after the +configured head start, so a fast 403 is what lands first. + +- Delete both `is_auth()` early returns. An auth error is recorded like any + other failure and the loop continues until both arms are done. +- Fold the pair with auth awareness: the result is an auth error only when + both arms rejected authentication. When one arm is auth and the other is a + non-auth failure, report the non-auth failure, which stays retryable. This + matters because the reconnect loop treats `is_auth()` as terminal at + `rs/moq-tokio/src/connection.rs:759` and `:810`; a fallback endpoint that + refuses every non-WebTransport request must not stop the client from + redialing a QUIC arm that merely failed transiently. +- Keep `TransportRace` for the both-non-auth case so the log still names + both failures. + +Tests, all in the `client.rs` test module beside the existing three: + +- Flip `race_transport_connect_stops_on_quic_auth_error` (line 1228): a QUIC + `Unauthorized` followed by a WebSocket success now connects over WebSocket. +- WebSocket 403 (`ConnectError::Forbidden` or the status mapping in + `rs/moq-tokio/src/connect.rs:366`) then QUIC success connects over QUIC. +- Both arms refusing reports an auth error. +- WebSocket 403 then a transient QUIC failure reports the QUIC error, and + `err.is_auth()` is false so `Reconnect` retries. +- `race_transport_connect_keeps_websocket_after_quic_non_auth_error` (1242) + and `race_transport_connect_returns_when_quic_transport_connects` (1252) + pass unchanged. ## Closes - [#3532](https://github.com/moq-dev/moq/issues/3532) - close this issue when the quest finishes + +## Related + +- [FFI WebSocket fallback](/quest/m2/ffi-websocket-fallback.md) - moq-ffi and its wrappers gain the disable and delay setters the CLI and libmoq already have diff --git a/quest/m0/3533-ts-export-restart-stall.md b/quest/m0/3533-ts-export-restart-stall.md deleted file mode 100644 index 0eb7c071930..00000000000 --- a/quest/m0/3533-ts-export-restart-stall.md +++ /dev/null @@ -1,61 +0,0 @@ -# [S] TS export survives a content restart on a continuous timeline - -## Goal - -`moq export ts` keeps emitting every elementary stream across a content join -on a source whose transport timeline is continuous: PCR, PTS and DTS monotone -on the wire, continuity counters unbroken, no `discontinuity_indicator`. That is -what a real encoder produces at a hard cut. The only backwards step in that -scenario is the importer's: the legacy audio importer extrapolates timestamps -from the last PES header, so after a resync at the join it re-locks a frame a -few milliseconds below its own extrapolated high-water mark. A rewind detected -on one track may cost the program one clock and PSI reset, but it never fences -another track for good, and the true rewind recovery #3375 added, a looping -file where every track steps backwards, keeps withholding stale frames. - -Boundaries: the consumer's rewind detection and the legacy audio importer's -resync are untouched here. Retiring inferred rewinds altogether is -[Monotonic timeline](/quest/m1/monotonic-timeline.md). - -## Plan - -Since #3375, `rewind(backwards)` in `rs/moq-mux/src/container/ts/export.rs` -bumps the program epoch and, on a backwards boundary, leaves every track that -already has a timeline in the old epoch. `Track::admit` then discards that -track's frames until it both changes its discontinuity counter and steps below -its own high-water mark. A continuous source supplies neither. The consumer's -rewind check in `rs/moq-mux/src/container/consumer.rs` has no tolerance, so the -sub-frame backwards step the legacy importer produces on an MPEG-1 audio resync -at the join is read as a rewind, and video plus primary audio are fenced -permanently while the passthrough PSI, AC-3 and teletext continue. #3533 -measured 0.31 Mb/s against a 9.5 Mb/s source with no recovery over 40 minutes, -bisected to #3375, and showed a single-track source is immune because the fence -needs a bystander. - -- Give the fence an exit. A fenced track joins the new generation when its own - timeline steps back, as today, or when the program clock driven by the joined - tracks passes its pending frame's timestamp. On a true rewind the video - track's own boundary arrives long before the reset clock climbs back to its - stale frames, so they are still discarded, which is what - `rewind_flags_the_break_once_across_tracks` asserts. On the #3533 join the - reset clock sits a few milliseconds below video's next frame, so video - re-joins within one frame. Implement it in `Track::admit` against the - exporter's watermark rather than as a timer: the exit is a clock comparison, - never a deadline. A frame at or below the watermark is admitted, a frame - above it stays fenced, and `rewind()` clears the watermark, so nothing - re-joins until a joined track has emitted; `fill` passes the current - watermark into admission so the rule has one definition. -- Regression test in `export_test.rs`: two tracks on a continuous transport - timeline whose content restarts, the audio track alone stepping back by less - than one frame at the join; video and audio keep emitting across it, and the - join costs at most one PCR discontinuity and one PSI re-emission. The existing - `rewind_re_emits_tables_and_resumes_the_clock` and - `rewind_flags_the_break_once_across_tracks` keep passing unchanged. - -## Closes - -- [#3533](https://github.com/moq-dev/moq/issues/3533) - close this issue when the quest finishes - -## Related - -- [Monotonic timeline](/quest/m1/monotonic-timeline.md) - deletes the inferred rewind that triggers the false boundary, and is the declared-break model the exporter will read instead diff --git a/quest/m0/3534-ietf-publisher-priority.md b/quest/m0/3534-ietf-publisher-priority.md deleted file mode 100644 index 92166b68e3b..00000000000 --- a/quest/m0/3534-ietf-publisher-priority.md +++ /dev/null @@ -1,70 +0,0 @@ -# [M] Publisher priority survives a moq-transport hop - -## Goal - -A track's publisher priority reaches a moq-transport subscriber the way it -already reaches a moq-lite one. A relay that ingests over either protocol and -serves over moq-transport stamps every group header with the track's priority -instead of 0, a peer that declares DEFAULT_PUBLISHER_PRIORITY (0x21) has it -recorded on the track, and a subgroup header that omits its priority resolves -to that declared default. The audio-ahead-of-video intent of a linear SSAI -publisher is what the next relay sees, and the moqtest conformance requirement -that a relay preserve publisher priority is met. - -Boundaries: priority is track-scoped, as `track::Info::priority` and -draft-lcurley-moq-lite define it, fixed for the lifetime of the track. A -subgroup priority that differs from its track's collapses to the track value. -The local send queue keeps ranking by each subscription's own priority. - -## Plan - -The model has the field: `track::Info::priority` (higher first) rides TRACK_INFO -on moq-lite, and `rs/moq-net/src/ietf/priority.rs` converts to the wire's -lower-first byte. The IETF side ignores it in both directions: - -- `rs/moq-net/src/ietf/publisher.rs` builds the group header with - `publisher_priority: 0`. -- `rs/moq-net/src/ietf/properties.rs` names TIMESCALE (0x08) and - DEFAULT_PUBLISHER_GROUP_ORDER (0x22); 0x21 falls through the unknown path. -- `rs/moq-net/src/ietf/group.rs` decodes an absent priority flag as a literal - 128. -- `rs/moq-net/src/ietf/subscriber.rs` builds `track::Info::default()` from - SUBSCRIBE_OK with only timescale and latency. - -Steps: - -- Properties: add DEFAULT_PUBLISHER_PRIORITY (0x21) beside 0x22. Encode it on - SUBSCRIBE_OK and PUBLISH from `info.priority` through `priority::to_wire`; - decode it into `track::Info::priority` on the subscriber through - `priority::from_wire`. The property block is written from draft-17 on and - read from draft-16 on, as `Properties::encode` already gates; draft-14 and 15 - have no block at all, so on those drafts the priority travels only in the - group header and an absent flag resolves straight to the draft's fallback. -- Group header: the publisher stamps `priority::to_wire(track.info().priority)` - where it reads the timescale today. The decoder resolves an absent flag to the - track's declared default first and only then to the draft's fallback; confirm - that fallback against each negotiated draft's text instead of keeping 128 by - assumption, and cite the section in the type's docs. On the subscriber the - header value is decoded and then dropped: the model has no per-group - priority, so an explicit subgroup value that disagrees with the track's - declared priority never overrides `track::Info::priority`, and a test pins - that a conflicting header leaves the track's priority unchanged. -- Mirror in `js/net/src/ietf/publisher.ts`, `object.ts`, and `properties.ts`. -- Tests: 0x21 round-trips on SUBSCRIBE_OK on every draft that carries the - block and is absent from the bytes on the ones that do not; a lite-ingested track - with priority N serves over moq-transport with header priority `to_wire(N)`; - a subgroup without the flag decodes to the declared default; a relay - integration test where hang audio (priority 80) and video (60) arrive at a - moq-transport subscriber with distinct header priorities. Run the interop - runner's priority case if it has one. - -Additive, on main. No draft change: 0x21 is IETF-registered and moq-lite already -specifies the field. - -## Closes - -- [#3534](https://github.com/moq-dev/moq/issues/3534) - close this issue when the quest finishes - -## Related - -- [IETF error codes](https://github.com/moq-dev/moq/pull/3531) - the sibling sweep of the moq-transport registries diff --git a/quest/m0/3588-anonymous-handoff.md b/quest/m0/3588-anonymous-handoff.md new file mode 100644 index 00000000000..6e33891ebca --- /dev/null +++ b/quest/m0/3588-anonymous-handoff.md @@ -0,0 +1,63 @@ +# [S] moq-net: anonymous handoff is proven on the source model + +## Goal + +An anonymous publisher session that dies without unannouncing is replaced by +the next anonymous session announcing the same path, and a subscriber on a +third anonymous session gets the newcomer's media with no parking and no 404. +On main the relay lingered the dead front, advertised it to the newcomer +before it announced, registered an `ExclusionGuard` for the id it had just +minted, and then read the newcomer's own announce as a reflection: parked +until the linger expired, 404 `dropped` meanwhile, failing interop cells +nightly. dev removed that mechanism; the fix is the model. This quest is the +proof, so the regression cannot come back through a merge. Branch from dev. + +## Plan + +What the tree does today, all in `rs/moq-net/src/model/origin.rs`: + +- `FrontState` (line 1914) holds `next_source`, `sources`, `track_info`, + `active`, `closed`. No `excluded`, no guard, no linger, no `taints_a_reader`. +- `attach_source` (2078) joins the live front under one lock and the newest + source becomes active; a front whose sources have all closed is replaced by + a fresh broadcast rather than spliced into. +- `detach_source` (1990) closes the broadcast synchronously with its last + source, however the source ended. +- Loop detection is hop-based route filtering: `Consumer::excluding` (3501) + hides every route whose hop chain contains the peer, enforced in + `best_route` (3033). The lite publisher applies it at + `rs/moq-net/src/lite/publisher.rs:119`; the server mints `Hop::random()` + per accepted session at `rs/moq-net/src/server.rs:217`. +- The relay's `cluster.linger` is a hidden deprecated no-op + (`rs/moq-relay/src/cluster.rs:485`). + +Work: two regression tests in the `origin.rs` test module, beside +`exclude_hides_routes_through_the_peer` (4331) and +`anonymous_routes_never_resume` (4991), using the same rig style. + +- Handoff: session A (anonymous hop) attaches a source at a path; a consumer + from a third anonymous session resolves it. A's source is dropped without + an unannounce. Session B attaches a source at the same path. The consumer + resolves again and reads B's media; assert the front closed with A's last + source and B's front is served immediately, with no stale front at the leaf. +- Reflection, in the lite session harness rather than the origin rig: the + origin asserts a looping chain never reaches it (`origin.rs:1506`), and the + drop happens one layer up, where `rs/moq-net/src/lite/subscriber.rs` + (lines 267 to 305) discards an announce whose chain already names this + session or its origin. Beside the `SinkSession` tests at `subscriber.rs:1333`, + a peer that was advertised the path announces it back with the relay's own + hop in the chain; assert the announce is dropped, the local front keeps + serving, and the peer's own subscription is still served from it. + +Then `just test smoke-full`: the nightly matrix +(`.github/workflows/smoke.yml:11`, `test/smoke/README.md:71`) runs +wire-anonymous clients that hit this path; confirm every cell passes on the +branch. Note the run in the PR. + +## Closes + +- [#3588](https://github.com/moq-dev/moq/issues/3588) - close this issue when the quest finishes + +## Related + +- [Anonymous rank](/quest/m1/anonymous-route-rank.md) - anonymous routes rank below identified ones diff --git a/quest/m0/3588-anonymous-publisher-parked.md b/quest/m0/3588-anonymous-publisher-parked.md deleted file mode 100644 index 28582fdc87b..00000000000 --- a/quest/m0/3588-anonymous-publisher-parked.md +++ /dev/null @@ -1,58 +0,0 @@ -# [M] moq-net: an anonymous publisher is parked behind its own minted id - -## Goal - -On main, when an anonymous publisher's session ends without a graceful -unannounce and another anonymous session announces the same path while the -front lingers, the newcomer takes the path over and a subscriber on any other -session gets its media. Today the newcomer is parked until the linger expires -and every subscriber gets 404 `dropped` meanwhile, which costs eight cells of -the nightly interop matrix and every reconnect on a released relay. Boundary: -a newcomer arriving while the old session is still open keeps waiting for it -to end, because a relay cannot tell an anonymous handoff from an anonymous -reflection, and evicting a live incumbent on a reflected announce is a loop. -Established ids keep taking over immediately, as today. Fix on main; dev -deleted the gate. - -## Plan - -#3042 mints `Origin::random()` for every accepted session that declares no -identity, so routes learned on it are not advertised back to it. That is all -`drafts/draft-lcurley-moq-cluster.md` asks of an assigned id, and the -reflection gate must keep counting it: a peer we advertised a live path to, -which then announces that path under the id we minted for it, is reflecting -our content. The defect is one step earlier. A new session is advertised the -lingering front before it announces anything, `AnnounceConsumerNotify::announce` -registers an `ExclusionGuard` for the freshly minted id in -`FrontState::excluded`, the peer's own announce is stamped `hops = [id]`, and -`attach_source` in `rs/moq-net/src/model/origin.rs` parks it as a reflection. -A front with no live route has nothing to reflect. - -- A lingering front, one whose `routes` are empty and whose linger is what - keeps it open, is not advertised to announce consumers that attach after - its last route left, and registers no exclusion for them. It is advertised - again the moment a route joins. Consumers that were advertised it while it - was live keep their guards, so a reflection from any of them stays parked - and the linger closes the front as today. The resolve path keeps - registering guards: a subscriber is a real reader. -- With no guard for the newcomer, its announce is untainted and the existing - takeover branch closes the lingering incumbent and announces the new front, - which is the "newest publisher wins" rule main already applies to - established ids. -- Regression tests: two anonymous sessions on one relay where the publisher - session dies without unannouncing and a new one announces the same path - during the linger; a third anonymous session subscribes and gets media with - zero parking events. A reflection test in the same shape: the peer that was - advertised the path while it was live announces it back after the - publisher dies, stays parked, and the front closes when the linger expires. - `test_reflection_through_an_exposed_peer_cannot_take_over` and its rival - test in `origin.rs` keep passing unchanged. Run `just test smoke-full`; its - draft-18 clients hit this. -- dev is unaffected: #2704 removed the linger and #3225 deleted - `FrontState::excluded`, `taints_a_reader`, and parking, so a front closes - with its last source and reflection is the chain test against the relay's - own hop. Nothing to port at [merge dev](/quest/m1/merge-dev.md). - -## Closes - -- [#3588](https://github.com/moq-dev/moq/issues/3588) - close this issue when the quest finishes diff --git a/quest/m0/README.md b/quest/m0/README.md index e3ce36ec055..8cb92b33c44 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -1,33 +1,21 @@ -# m0: bug fixes +# m0: release blockers ## Goal -Defects in what main or dev ships today: crashes, races, protocol violations, -wrong output, security gaps, regressions an unreleased change introduced, and -the missing tests that let them through. +What must land before dev merges into main and the release that follows is +cut: user-visible breakage on a released surface, and the proof that a +regression the merge fixes cannot return. Everything else that is a defect +sits in [m2](/quest/m2/README.md) beside the feature it shares code with. ## Plan -Fix where the defect is, which is usually main; a quest says so when it is dev. -Security and credential exposure lead; user-visible breakage -next; hardening, tooling, and test debt close the list. Each fix lands with a -regression test per Root Cause First. +Fix where the defect is; each quest says which branch. Every fix lands with a +regression test per Root Cause First. [Merge dev](/quest/m1/merge-dev.md) +requires this questline, so a quest that stops being a blocker moves to m2 +rather than holding the merge. ## Quests -- [Play tune-in backpressure](/quest/m0/play-tunein-backpressure.md) - moq play: a tune-in burst larger than the video queue parks the decoder, so the clock never reaches live at a wide `--delay` -- [Play audio rendition gap](/quest/m0/play-audio-rendition-gap.md) - moq play: a retired audio rendition drains its sink before the replacement fills one, so the switch costs a `--delay` of silence -- [Audio jitter target](/quest/m0/audio-jitter-target/README.md) - the audio playout target is a measured, ported estimate of arrival timing in both languages, not a round-trip guess - [WebKit gate](/quest/m0/webkit-webtransport-gate.md) - js/net: every WebKit engine takes the WebSocket path, not just the Safari brand, so iOS Chrome and Firefox stop freezing after two minutes -- [Anonymous handoff](/quest/m0/3588-anonymous-publisher-parked.md) - moq-net: a lingering front is not advertised to sessions that arrive after its publisher left, so the next anonymous publisher takes the path over instead of being parked as a reflection -- [Publisher priority](/quest/m0/3534-ietf-publisher-priority.md) - moq-net: a track's publisher priority survives a moq-transport hop instead of being flattened to 0 -- [TRACK_STATUS refusal](/quest/m0/3492-ietf-track-status-refusal.md) - moq-net: TRACK_STATUS gets a NOT_SUPPORTED refusal instead of a silent drop -- [Connect auth race](/quest/m0/3532-connect-auth-race.md) - moq-native: a 403 on the WebSocket arm no longer fails a connect whose QUIC arm is still in flight; moq-ffi can disable the fallback -- [Jitter clock](/quest/m0/jitter-flush-clock.md) - moq-mux: catalog jitter measures how far behind the media clock an encoder flushes, fed by encoders only -- [TS restart stall](/quest/m0/3533-ts-export-restart-stall.md) - moq export ts: a content restart on a continuous timeline no longer fences video and primary audio for good -- [Failure artifacts](/quest/m0/qa-failure-artifacts.md) - a failing harness run keeps its run directory and a Playwright trace, and CI uploads them -- [Harness drive-bys](/quest/m0/harness-drive-bys.md) - decide whether the relay listening kind field that came with #3509 stays -- [Capture denial](/quest/m0/browser-permission-qa.md) - moq-publish swallows a refused camera or microphone and retries forever; it surfaces the denial and recovers on grant -- [Publisher audio unlock](/quest/m0/publish-audio-unlock.md) - the publisher's capture AudioContext stays suspended when the page had no gesture, so no audio is ever encoded -- [Impaired path](/quest/m0/transport-impairment-profile.md) - the transport drills run over a seeded, impaired UDP path on any host -- [Tooling](/quest/m0/tooling/README.md) - justfiles become a one-line menu over `sh/`, one impact map scopes CI, and every workflow step runs a recipe +- [Connect auth race](/quest/m0/3532-connect-auth-race.md) - moq-tokio: a 403 on the WebSocket arm no longer fails a connect whose QUIC arm is still in flight +- [Anonymous handoff](/quest/m0/3588-anonymous-handoff.md) - moq-net: the source model's takeover by the next anonymous publisher is pinned by regression tests, so the parking regression the merge removes cannot return diff --git a/quest/m0/audio-jitter-target/README.md b/quest/m0/audio-jitter-target/README.md deleted file mode 100644 index bea5de57695..00000000000 --- a/quest/m0/audio-jitter-target/README.md +++ /dev/null @@ -1,58 +0,0 @@ -# Audio jitter target - -## Goal - -The audio playout target is a measured estimate of arrival timing, ported from -a known-good implementation, in the browser and natively alike. The round-trip -formula is gone. `max(20ms, 1.25 x minRtt)` sized the buffer for a single -retransmit, which describes how long the network takes to recover a loss and -not how unevenly a publisher emits frames, so a sender flushing 100 ms of media -at once got a target far too shallow to play through the next flush. One -written algorithm, cited by both implementations, produces the same target from -the same arrival trace. - -Boundaries: convergence still uses skip-ahead and silence, so playing slightly -faster or slower to converge stays [Time -stretch](/quest/m2/watch-audio-time-stretch.md). No packet loss concealment. -Video keeps its own target; making the audio playhead the clock is [Plan: A/V -clock](/quest/m1/plan-av-clock.md). - -## Plan - -Three quests: the survey and the written algorithm first, then one -implementation per language against it. The two implementations are -independent once the spec lands and may run in parallel. - -PR #3517 stays open and is fixed in place by the watch quest rather than -restarted. It already deleted the RTT term and plumbed a per-track arrival -`spread` through `Container.Consumer`, measured at container frame arrival and -before the age budget can skip a group, which is the right observation point. -What it got wrong is the estimator on top. A viewer on that branch reads a -14.56 s jitter buffer in auto, and the cause is reproduced in -[Spec](/quest/m0/audio-jitter-target/spec.md): the "plus one frame" term is -learned from the first gap between observed timestamps, so a tune-in across a -stale group sets it to seconds, and nothing clamps the target or bounds how -fast it rises. - -Native has no jitter buffer at all. `rs/moq-audio`'s decode `Config` carries -only `latency_max`, an upper bound before skipping a stalled group, and its own -doc comment promises "a companion `latency_min` for jitter-buffer padding will -land in a follow-up". This questline is that follow-up. - -## Quests - -- [Spec](/quest/m0/audio-jitter-target/spec.md) - survey what already exists, then write the algorithm down once -- [Watch](/quest/m0/audio-jitter-target/watch.md) - js/watch and js/hang implement it, fixing #3517 in place -- [Native](/quest/m0/audio-jitter-target/native.md) - rs/moq-audio grows `latency_min` from the same algorithm - -## Closes - -- [#3477](https://github.com/moq-dev/moq/issues/3477) - close this issue when the questline finishes -- [#2812](https://github.com/moq-dev/moq/issues/2812) - the iOS stutter report the same estimator fixes - -## Related - -- [Jitter clock](/quest/m0/jitter-flush-clock.md) - the advertised jitter (#3513 landed the flush span), whose relationship to the measured target the spec settles -- [Audio quality harness](/quest/m2/audio-quality-harness/README.md) - the automated proof, built on its own schedule -- [Time stretch](/quest/m2/watch-audio-time-stretch.md) - inaudible convergence, on top of this -- [Plan: A/V clock](/quest/m1/plan-av-clock.md) - the clock this target eventually feeds diff --git a/quest/m0/audio-jitter-target/watch.md b/quest/m0/audio-jitter-target/watch.md deleted file mode 100644 index 77441ca232f..00000000000 --- a/quest/m0/audio-jitter-target/watch.md +++ /dev/null @@ -1,62 +0,0 @@ -# [M] js/watch: the playout target follows the spec, proven in a real browser - -## Goal - -`js/watch` computes its auto target with the algorithm from -[Spec](/quest/m0/audio-jitter-target/spec.md) and passes the conformance -vector. The "Real-time" preset plays clean audio on a LAN and against the -public relay: zero underruns after convergence and no skip-aheads in steady -state, on both the isolated and the postMessage ring paths, confirmed by a -manual run on Chrome and Safari with a real microphone and 40 ms or more of -added RTT. - -Boundaries: the ring's slack, re-stall and underrun counter are mechanical and -already correct in #3517; this quest changes the estimator above them. - -## Plan - -Fix PR #3517 in place on `dev` rather than reopening it. It is a published -`@moq/watch` break (the `Sync` input `probe` is removed) and `dev` already -carries the `delay`/`buffer` split it is expressed in. Resolve its conflicts -with `dev` first, since it currently does not merge. - -- Replace the estimator in `js/hang/src/container/jitter.ts` with the spec's, - and run the conformance corpus in `jitter.test.ts`. Keep the arrival - plumbing, the `spread` getter, and the measurement point: those were right. -- The reproduced 14.56 s runaway is the regression test to write first, before - any replacement: two frames whose media timestamps are far apart, then paced - audio with zero real jitter, asserting the target stays near the frame - duration. On today's branch it reads 14.5 s and needs about fifteen minutes - of clean audio to unwind. Take the frame duration from the source the spec - settles on rather than from observed timestamps, clamp the target, and bound - how fast it rises; [Spec](/quest/m0/audio-jitter-target/spec.md) has the - detail and the candidates. -- Check what the viewer's saved preset does on load. The element defaults - `delay` to `"auto"` and nothing in `demo/` overrides it, yet a fresh session - came up on the 100 ms chip, so something is restoring or overriding it. Pin - that down: a stored preference silently winning over the default is its own - bug, and it also means auto gets far less real exposure than it looks like. -- Keep the ring work as it stands: one chunk of slack above the target, landing - back on the target when skipping, re-stalling on empty, and the underrun - counter reaching the stats panel and the buffering indicator. -- Replay the recorded traces from #3477 rather than synthetic ones of the same - shape. They are on the reporter's fork - (`fperex/moq`, branch `debug/rt-audio`) with the raw ndjson attached to - release `rt-audio-traces-2026-09-06`. Trim a copy into the repository and - replay it through both rings in `replay.test.ts`. -- Manual run against the public relay on Chrome and Safari, the two rows the - issue measured. Measure the publisher's audio encoder input-to-output lag in - the same run using the reporter's instrumented harness; #3518 fixed the known - cause, so the 7.35 s lag and the 88 to 275 ms/s drift the issue reported - stand unconfirmed. If drift survives, the suspects are `writeFrame` opening a - group per audio frame under WebTransport stream credit and the main-thread - task queue delivering encoder output. Turn that into its own quest rather - than fixing it here. - -Two sibling quests on `main` touch the same audio path -(`3479-watch-audio-identity`, `publish-audio-encoder-lag`), for conflict triage -when `main` next merges into `dev`. - -## Required - -- [Spec](/quest/m0/audio-jitter-target/spec.md) - the algorithm this implements diff --git a/quest/m0/harness-drive-bys.md b/quest/m0/harness-drive-bys.md deleted file mode 100644 index 17ed492138a..00000000000 --- a/quest/m0/harness-drive-bys.md +++ /dev/null @@ -1,23 +0,0 @@ -# [XS] Decide the relay listening kind field - -## Goal - -The test harness isolation from #3509 keeps its point (private run -directories, reserved ports, process-group teardown) and sheds the one thing -that came along without a reason to live here if nobody reads it: the `kind` -field on the relay's `listening` log line. - -## Plan - -- Decide whether the relay's `kind = "quic" | "http" | "https"` on the - `listening` line and the two new web-listener lines stay. They are - operator-visible and documented in `doc/bin/relay/config.md`; keep them - only if the harness actually reads the bound address from them, otherwise - revert to the single line and drop the doc. -- The `just worktree` recipe that rode in with the same PR is deleted by - [Thin justfiles](/quest/m0/tooling/justfiles.md), not here. - -## Related - -- [Failure artifacts](/quest/m0/qa-failure-artifacts.md) - the harness run directory this trims around -- [Thin justfiles](/quest/m0/tooling/justfiles.md) - removes the `worktree` recipe diff --git a/quest/m1/3190-align-origin-broadcast-creation-naming-across-language.md b/quest/m1/3190-align-origin-broadcast-creation-naming-across-language.md index 2b801677d6a..56b74497363 100644 --- a/quest/m1/3190-align-origin-broadcast-creation-naming-across-language.md +++ b/quest/m1/3190-align-origin-broadcast-creation-naming-across-language.md @@ -33,7 +33,7 @@ queue that one of them owns; that is what the rename must not paper over. The Rust model's `origin::Producer::dynamic(prefix: impl Into, route)` (`rs/moq-net/src/model/origin.rs:1366`) changes to take a `moq_net::path::Pattern` (`rs/moq-net/src/path/pattern.rs:172`), so the -announce API breaks once. Until [Advertise](/quest/m1/wildcard/advertise.md) +announce API breaks once. Until [Advertise](/quest/m1/wildcard-advertise.md) lands, anything but a prefix-shaped pattern (literal segments then `**`) is refused; the bindings take the pattern as a string and inherit that refusal. @@ -86,6 +86,6 @@ Branch from `dev`: every rename is breaking. ## Related -- [#2152](/quest/m1/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md) - the rest of the C ABI catch-up +- [#2152](/quest/m2/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md) - the rest of the C ABI catch-up - [JS announce](/quest/m1/js-announce.md) - the same alignment for js/net -- [Advertise](/quest/m1/wildcard/advertise.md) - lifts the prefix-only refusal so `dynamic()` accepts any pattern +- [Advertise](/quest/m1/wildcard-advertise.md) - lifts the prefix-only refusal so `dynamic()` accepts any pattern diff --git a/quest/m1/README.md b/quest/m1/README.md index e32e06808f3..58a77faff03 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -4,31 +4,28 @@ Everything that must land on `dev` before it merges to `main`: the breaking API and wire changes (the announce and wildcard surface, error codes, the -allocator mirrors, the bindings), the merge gates (the archive line, because -moq.pro needs archive-backed recording on the release that `dev` produces), -and the merge itself. +allocator mirrors, the bindings), the merge gates (the archive catalog and +store, the monotonic timeline, wildcard advertisements), and the merge +itself. ## Plan -Branch a quest from `dev` when it breaks a published API or wire. A merge -gate that lands on `main` (the additive Resolve and Demand halves of the -wildcard line) branches from `main` and ranks here only because the merge -waits on it. A quest stays here only if it breaks a -published API or wire, or gates the merge. Work that is identical on -`main`, additive, or targets a `0.0.x` crate lives in +Branch a quest from `dev` when it breaks a published API or wire. A quest +stays here only if it breaks a published API or wire, or gates the merge; +[Merge dev](/quest/m1/merge-dev.md) names the gates. Work that is identical +on `main`, additive, or targets a `0.0.x` crate lives in [m2](/quest/m2/README.md) even when it builds on dev-only code; it starts on -`main` after the merge. The 2026-09-09 grooming reconciled every quest here -with the dev tree. +`main` after the merge. The 2026-09-12 grooming applied that rule to every +quest here and merged main into dev. ## Quests -- [Archive](/quest/m1/archive/README.md) - record selected tracks to any object_store and replay them over FETCH or derived HLS; the whole line gates the dev merge +- [Archive catalog](/quest/m1/archive-catalog.md) - one root `archive` entry subsumes `timeline` and names the timeline track, replay path, store URL, and format version +- [Archive store](/quest/m1/archive-store.md) - `moq-archive` puts, gets, lists, and deletes the versioned objects over `object_store` - [Monotonic timeline](/quest/m1/monotonic-timeline.md) - a marker group of one empty frame declares a break and moves the live edge; producers refuse a rewind; consumers jump the playhead on an unproven hole and drop rewind detection -- [js/publish discontinuity](/quest/m1/js-publish-discontinuity.md) - the JS container producer and js/publish emit the same marker group on encoder restart - [#3190](/quest/m1/3190-align-origin-broadcast-creation-naming-across-language.md) - every native binding, Dart included, creates unadvertised, announces from the broadcast, and takes a path Pattern in `dynamic(pattern, route)` - [JS announce](/quest/m1/js-announce.md) - js/net drops `publish()` and `RouteProvider` for `createBroadcast`, `announce(route)`, and a `dynamic(pattern, route)` handle -- [Wildcard](/quest/m1/wildcard/README.md) - a service advertises a path pattern priced at its start-up cost; Advertise gates the merge, Resolve and Demand are additive -- [Route cold cost](/quest/m1/route-cold-cost.md) - MoqRoute carries warm and cold, so an observed route re-announces intact +- [Advertise](/quest/m1/wildcard-advertise.md) - moq-net encodes, forwards, and authorizes wildcard advertisements, so `dynamic(pattern, route)` takes a pattern before the announce API is published - [Anonymous rank](/quest/m1/anonymous-route-rank.md) - moq-net: a route through an anonymous hop ranks below every identified route at any cost, and hop 0 travels the chain to say so - [Group overflow](/quest/m1/group-overflow-abort.md) - an open group past its budget aborts for every reader with GROUP_TOO_LARGE, and head eviction is deleted - [#2774](/quest/m1/2774-collapse-reload-and-shared-into-one-connection-class.md) - one cloneable refcounted `Connection` mirroring `moq_tokio::Connection`; close releases a handle @@ -47,6 +44,5 @@ with the dev tree. - [LAN discovery app id](/quest/m1/lan-app.md) - every advertisement names an application as a DNS-SD subtype bound into the proofs, so unrelated apps on one network never meet - [One LAN mesh](/quest/m1/lan-mesh.md) - moq-cli drives the relay's Cluster, LAN peers authenticate by mDNS credential, and the two binaries mesh with each other - [Native Go context](/quest/m1/go-native-context.md) - the Go generator emits context.Context itself, retiring the hand-rolled cancellation token -- [#2152](/quest/m1/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md) - libmoq serves tracks on demand and accepts sessions, the two moq-ffi calls C still lacks - [Transport feature](/quest/m1/tokio-transport-feature.md) - moq-tokio has one `_transport` gate and its backend-less build passes `-D warnings` - [Merge dev](/quest/m1/merge-dev.md) - dev lands on main with a closing keyword for every issue it fixed diff --git a/quest/m1/anonymous-route-rank.md b/quest/m1/anonymous-route-rank.md index f972773babf..f02d6b821c6 100644 --- a/quest/m1/anonymous-route-rank.md +++ b/quest/m1/anonymous-route-rank.md @@ -65,7 +65,7 @@ Hop 0 in a chain is the mark, and it travels: - [Rank](/quest/m2/pop-skipping/rank.md) - warm-copy adoption, which also refuses to treat two anonymous relays as one -- [Route cold cost](/quest/m1/route-cold-cost.md) - the cost pair the bindings +- [Route cold cost](/quest/m2/route-cold-cost.md) - the cost pair the bindings carry, which `is_anonymous()` joins - [#3060](https://github.com/moq-dev/moq/issues/3060) - the ban on hop 0 in chains this quest decides against diff --git a/quest/m1/archive/catalog.md b/quest/m1/archive-catalog.md similarity index 100% rename from quest/m1/archive/catalog.md rename to quest/m1/archive-catalog.md diff --git a/quest/m1/archive/store.md b/quest/m1/archive-store.md similarity index 100% rename from quest/m1/archive/store.md rename to quest/m1/archive-store.md diff --git a/quest/m1/js-announce.md b/quest/m1/js-announce.md index 101d8e2f375..3cc50cfa8d4 100644 --- a/quest/m1/js-announce.md +++ b/quest/m1/js-announce.md @@ -31,7 +31,7 @@ decisions and the second is callback-shaped. requests with `accept(broadcast)` and `reject(error)`. The pattern is parsed by `Path.Pattern` (`js/net/src/path.ts:526`), the same dialect the Rust model takes, so the API breaks once; until - [Advertise](/quest/m1/wildcard/advertise.md) lands, anything but a + [Advertise](/quest/m1/wildcard-advertise.md) lands, anything but a prefix-shaped pattern is refused. `RouteProvider` is removed; `connection/forward.ts` and the session code drive the handle instead. - `StreamCode` (`js/net/src/error.ts:71-95`) gains `NoCapacity: 0x30`, the @@ -59,5 +59,5 @@ Branch from `dev`, where the origin table lives; the rename is breaking. - [#3190](/quest/m1/3190-align-origin-broadcast-creation-naming-across-language.md) - the native bindings half, and the Rust `dynamic(pattern, route)` signature - [#2774](/quest/m1/2774-collapse-reload-and-shared-into-one-connection-class.md) - rewrites `connection/reload.ts` and `pool.ts`, which this touches; land one before the other -- [Advertise](/quest/m1/wildcard/advertise.md) - lifts the prefix-only refusal so `dynamic()` accepts any pattern +- [Advertise](/quest/m1/wildcard-advertise.md) - lifts the prefix-only refusal so `dynamic()` accepts any pattern - [#2318](/quest/m2/2318-js-net-remaining-capability-gaps-vs-rs-moq-net-setup-role.md) - other js/net gaps vs rs/moq-net diff --git a/quest/m1/js-close-classification.md b/quest/m1/js-close-classification.md index c68e339f74f..380be168322 100644 --- a/quest/m1/js-close-classification.md +++ b/quest/m1/js-close-classification.md @@ -52,4 +52,4 @@ abort the case asked for. The blanket drain is `WaitProps.tolerateErrors` in - [#2318](/quest/m2/2318-js-net-remaining-capability-gaps-vs-rs-moq-net-setup-role.md) - the other js/net gaps against the Rust model - [Media QA on other engines](/quest/m2/browser-media-qa-engines.md) - the same harness, another axis -- [Failure artifacts](/quest/m0/qa-failure-artifacts.md) - shared trace and sample output +- [Failure artifacts](/quest/m2/qa-failure-artifacts.md) - shared trace and sample output diff --git a/quest/m1/lan-app.md b/quest/m1/lan-app.md index d9824e1f395..afc0af553fa 100644 --- a/quest/m1/lan-app.md +++ b/quest/m1/lan-app.md @@ -26,8 +26,9 @@ record. so the boundary test refuses a 63-character app rather than letting registration fail later. `impl Default` returns `default`, the name both binaries advertise under. - `Config::new(app, port)` replaces `Config::new(port)`; moq-tokio is - unpublished, so no shim. + `Config::new(app, port)` replaces `Config::new(port)`: moq-tokio is + published (`rs/moq-tokio/Cargo.toml:8`, 0.19.x), so that is a breaking + change and belongs on `dev` for that reason, with no shim. - Partition: register the service under the DNS-SD subtype `_._sub._moq._udp.local.` (RFC 6763 section 7.1) and browse that subtype, so the daemon only ever resolves this application's records. diff --git a/quest/m1/merge-dev.md b/quest/m1/merge-dev.md index 8fa80bb0da7..3d319351426 100644 --- a/quest/m1/merge-dev.md +++ b/quest/m1/merge-dev.md @@ -3,18 +3,36 @@ ## Goal `main` carries everything on `dev`: the thread-per-core runtime, the net model -and allocator work, the announce handle and its bindings, the archive line, and -every fix that only dev has. The merge PR closes each issue dev fixed with a -closing keyword, and the release that follows is the one moq.pro adopts. +and allocator work, the announce handle and its bindings, the archive catalog +and store, and every fix that only dev has. The merge PR closes each issue dev +fixed with a closing keyword, and the release that follows is the one moq.pro +adopts. ## Plan -As of 2026-09-09 dev is 285 commits ahead of main and main 6 ahead of dev. The -six are a docs pass (#3557), a quest plan (#3560), and CI repairs (#3553, -#3554, #3555, #3556), so the main-into-dev merge is trivial. Merge main into -dev first and resolve there, then open the merge PR from dev with the list -below as closing keywords. Run `just check-all`, `just test all`, -`just test smoke-full`, and `just bench origin/main` on the merged tree. +main is merged into dev as of 2026-09-12, so the merge PR opens from dev with +the list below as closing keywords once the gates clear. Run `just check-all`, +`just test all`, `just test smoke-full`, and `just bench origin/main` on the +merged tree, and record the revision the proof ran on. + +Resolve by behavior, never by side. The traps the last main-into-dev merge +hit, so the merge PR re-checks each on the combined tree: + +- main's joining FETCH keeps its saved object prefix (#3562) and answers with + FETCH_OK; dev's registry maps its two refusal codes to DOES_NOT_EXIST until + [IETF leftovers](/quest/m2/ietf-leftovers.md) adds them. +- main's refusal of an incompatible copy during failover (#3521) lives on + dev's source table (`FrontState::track_info`, `accept_track_info`) and is + checked on `Step::Splice`; a successor with a different timescale never + rescales samples a subscriber already holds. +- dev's structural flush-span jitter (#3513), registered request codes + (#3531), bounded `moq_json::window` timeline (#3240), and duration marker + (#3575) keep their regressions; main's draft-21 (#3574) is in every + per-version list, including the stream and request registries. +- The hop-0 ban is abandoned (#3623); anonymous routes rank last instead + ([Anonymous rank](/quest/m1/anonymous-route-rank.md)). +- Auto-merged files hide breakage: `just check` and `just test` run before + the merge commit, not after. Also soak HLS on the merged tree: a fresh viewer joining a `moq import ts` broadcast that has been up for days must get a playlist promptly. The bounded @@ -23,15 +41,19 @@ run proves it. The breaking-change targeting rules in CONTRIBUTING.md govern the release that follows. Dart lands on that surface with #3190, so nothing waits on this -merge for it. +merge for it. The rest of the archive line, wildcard resolution, and every +additive quest that builds on dev-only code start on main afterwards from +[m2](/quest/m2/README.md). ## Required -- [Archive](/quest/m1/archive/README.md) - moq.pro needs archive-backed recording on the release dev produces -- [#3190](/quest/m1/3190-align-origin-broadcast-creation-naming-across-language.md) - every native binding on that surface +- [m0](/quest/m0/README.md) - every release blocker lands or is punted before the merge +- [Archive catalog](/quest/m1/archive-catalog.md) - the breaking catalog shape the release ships +- [Archive store](/quest/m1/archive-store.md) - the object layout the catalog names +- [#3190](/quest/m1/3190-align-origin-broadcast-creation-naming-across-language.md) - every native binding on the announce surface - [JS announce](/quest/m1/js-announce.md) - js/net on that surface - [Monotonic timeline](/quest/m1/monotonic-timeline.md) - so a shed marker still jumps the playhead on a timestamp hole (#3291) -- [Advertise](/quest/m1/wildcard/advertise.md) - so `dynamic(prefix, route)` takes a path pattern before the announce API is published +- [Advertise](/quest/m1/wildcard-advertise.md) - so `dynamic(prefix, route)` takes a path pattern before the announce API is published ## Closes @@ -63,4 +85,8 @@ merge for it. - [#679](https://github.com/moq-dev/moq/issues/679) - QUIC receive is spread across thread-per-core workers, each on its own socket (#2921) - [#1073](https://github.com/moq-dev/moq/issues/1073) - the origin lifecycle is caller-driven: `origin::Driver` plus `moq_tokio::origin::spawn` (#2897, #2901) - [#2155](https://github.com/moq-dev/moq/issues/2155) - js/net: subscriptions take a `Subscription` options object with `startGroup`, `endGroup`, and `update()` (#2716); ordering became a handle (#3099) -- [#3493](https://github.com/moq-dev/moq/issues/3493) - the timeline is a `moq_json::window` with a bounded checkpoint, so a 24/7 importer no longer retains every record (#3240) + +## Related + +- [Archive](/quest/m2/archive/README.md) - the writer, reader, HLS, DVR, browser, and proof follow the release +- [Wildcard](/quest/m2/wildcard/README.md) - Resolve and Demand are additive and follow the release diff --git a/quest/m1/monotonic-timeline.md b/quest/m1/monotonic-timeline.md index 5aa229967fa..d9574eb12e6 100644 --- a/quest/m1/monotonic-timeline.md +++ b/quest/m1/monotonic-timeline.md @@ -27,6 +27,13 @@ generation. Consumers stop detecting and re-anchoring on undeclared rewinds. A group that breaks the forward-only rule is a malformed track, not a timeline event. +This also retires the inferred rewind behind #3533: `moq export ts` stalls +video and primary audio for good at the first content join of a source whose +transport timeline is continuous, because the legacy audio importer's +sub-frame backwards step at a PES resync is read as a rewind and the +exporter's backward fence never opens for the bystander tracks. With no +inferred rewinds there is no fence. + js/publish does not emit the marker yet. ## Plan @@ -47,7 +54,7 @@ object in the hole. Callers stay: h264/h265/opus/aac/legacy importers, TS import, moq-video idle capture, moq-audio, moq-boy. js/publish is -[its own quest](/quest/m1/js-publish-discontinuity.md). +[its own quest](/quest/m2/js-publish-discontinuity.md). If the marker arrives, walk now and bump the playhead generation. If it is shed, N→N+2 is a sequence hole: wait until `max_age` trips or the track @@ -77,6 +84,22 @@ on a flush and rejects a rewinding base; check the CLI importers, the capture publishers, and `js/publish` do the same on a source restart, and re-anchor rather than refuse where the source is trusted. +The legacy MPEG audio importer in `rs/moq-mux/src/container/ts/import.rs` is +one such trusted source and must re-anchor forward. `LegacyStream::write` +takes the PES PTS for the first frame that begins in a PES and then +extrapolates every following frame by its own duration +(`advance_pts`, `:2436`), carrying the extrapolated value across a PES +boundary as `tail_pts` (`:2447`). When frame sync is lost it abandons the +tail and re-anchors on the PES PTS (`pts = pes_base`, `:2377` and `:2395`). +At a content join on a continuous transport timeline that PES PTS sits a few +milliseconds below the extrapolated high-water mark, which is the backwards +step #3533 measured (one MPEG-1 audio resync at the join, `audio frame sync +lost pid=121 resyncs=2`). Once the producer refuses rewinds that sub-frame +step becomes a refused frame and an aborted import rather than a stall, so +the resync must clamp its re-anchor to the track's live edge (or skip the +frame that would land below it) and only then continue from the PES PTS. +A stale tail after a loop wrap, wrong by hours, still re-anchors on the PES. + ### Consumer abort rewind Delete the rewind boundary and its classification in both languages (`Rewind` @@ -102,9 +125,12 @@ restarts the program clock on a source discontinuity, clearing `last_pcr`, generation (`:696`). The `backwards` flag (decided at `:581` and `:1145`, and what fences peers across a backward boundary at `:948`) disappears with backward rewinds, so the reset takes no argument and its docs lose the -backward case; keep `pcr_discontinuity`, the `discontinuity_indicator` on -the PCR packet, since a PCR jump over 100 ms without it is a TR 101 290 -error whichever direction the jump goes. +backward case. `Track::admit` (`:178`) then admits any frame in the current +generation and no track is ever left behind in an old one, which is the #3533 +fix: the fence that discarded video and primary audio for 40 minutes no +longer exists. Keep `pcr_discontinuity`, the `discontinuity_indicator` on the +PCR packet, since a PCR jump over 100 ms without it is a TR 101 290 error +whichever direction the jump goes. ### Tests @@ -122,16 +148,31 @@ Rewrite `empty_group_declares_a_discontinuity`, `discontinuity_moves_the_live_edge_off_stale_content` for the marker group (one empty frame, not zero objects). +TS import: a legacy audio resync whose PES PTS sits below the extrapolated +high-water mark publishes forward from the live edge and does not abort. + +TS export, the #3533 regression in `export_test.rs`: two tracks on a +continuous transport timeline whose content restarts, the audio track alone +stepping back by less than one frame at the join; video and audio keep +emitting across it, and the join costs at most one PCR discontinuity and one +PSI re-emission. `rewind_re_emits_tables_and_resumes_the_clock` +(`export_test.rs:2129`) and `rewind_flags_the_break_once_across_tracks` +(`:2307`) are rewritten for the no-backwards world: the break is a declared +marker group, the clock and tables reset once per program break, and no +track is fenced. + Branch from `dev`, where the container consumers carry the current `Rewind` state and `is_stale` sheds empty groups. ## Closes - [#3291](https://github.com/moq-dev/moq/issues/3291) - close this issue when the quest finishes +- [#3533](https://github.com/moq-dev/moq/issues/3533) - close this issue when the quest finishes ## Related -- [js/publish discontinuity](/quest/m1/js-publish-discontinuity.md) - the JS container producer and js/publish emit the same marker +- [js/publish discontinuity](/quest/m2/js-publish-discontinuity.md) - the JS container producer and js/publish emit the same marker - [#3056](/quest/m2/3056-watch-video-decoder-captures-the-rewind-generation-at.md) - whether watch still resets VideoDecoder to drop in-flight chunks when playhead generation bumps - [#3115](/quest/m2/3115-moqsink-the-publication-has-no-generation-so-a-flush.md) - moqsink's generation model after EOS, the same publisher - [Open-GOP leading pictures](/quest/m2/open-gop-leading-pictures.md) - latency skip now bumps playhead generation but does not flush the decoder, so leading pictures still decode +- [TS import stream liveness](/quest/m2/3489-ts-import-stream-liveness.md) - the per-stream access-unit reporting that would have shown the #3533 stall at the importer diff --git a/quest/m1/plan-av-clock.md b/quest/m1/plan-av-clock.md index 6b94e2ee649..1dfe011afaf 100644 --- a/quest/m1/plan-av-clock.md +++ b/quest/m1/plan-av-clock.md @@ -11,11 +11,16 @@ the next re-anchor. ## Plan -Settled: per-track handles. `sync.track("audio")` and `sync.track("video")` -each report their advertised delay and measured spread, and one is nominated -as the clock source. #3517 adopts that shape before it merges, so `SyncInput` +Settled: per-track handles, and this quest lands them. `sync.track("audio")` +and `sync.track("video")` each report their advertised delay and measured +spread, and one is nominated as the clock source. `SyncInput` (`js/watch/src/sync.ts:21-46`, today `delay`, `buffer`, `probe`, `audio`, `video`) breaks once, and a third track joins without another pair of inputs. +The measured spread per track comes from +[Watch](/quest/m2/audio-jitter-target/watch.md); its branch carries flat +`audioSpread` and `videoSpread` inputs in place of `probe`, which this quest +folds into the handles. This is a published `@moq/watch` break, so it targets +`dev`. Recommendations for the implementation: @@ -32,13 +37,14 @@ Recommendations for the implementation: - Reset coupling stays: `` already flushes the ring alongside `sync.reset()` (`js/watch/src/element.ts:301`, `:620-621`). - The text renderer is the third track: it reads `sync.now()` - (`js/watch/src/text/renderer.ts:261`) for the cues it drains at `:273-278`. + (`js/watch/src/text/renderer.ts:261`) to drive the cue clock and prune cues + at `:263-265`. ## Required -- #3517 merges carrying the per-track shape +- [Watch](/quest/m2/audio-jitter-target/watch.md) - lands the per-track spread inputs this shape carries; it merges to `dev` before this starts ## Related -- [Audio jitter target](/quest/m0/audio-jitter-target/README.md) - the estimator this sits on +- [Audio jitter target](/quest/m2/audio-jitter-target/README.md) - the estimator this sits on - [Time stretch](/quest/m2/watch-audio-time-stretch.md) - stretching needs a clock to converge toward diff --git a/quest/m1/wildcard/advertise.md b/quest/m1/wildcard-advertise.md similarity index 100% rename from quest/m1/wildcard/advertise.md rename to quest/m1/wildcard-advertise.md diff --git a/quest/m1/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md b/quest/m2/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md similarity index 100% rename from quest/m1/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md rename to quest/m2/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md diff --git a/quest/m2/README.md b/quest/m2/README.md index d5a2d3de664..276f228a753 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -23,6 +23,23 @@ targeting a `0.0.x` crate. ## Quests +- [Audio jitter target](/quest/m2/audio-jitter-target/README.md) - the audio playout target is a measured estimate of arrival timing in both languages, not a round-trip guess +- [Jitter clock](/quest/m2/jitter-flush-clock.md) - moq-mux: catalog jitter measures how far behind the media clock an encoder flushes, fed by encoders only, and never decreases +- [Capture denial](/quest/m2/browser-permission-qa.md) - moq-publish surfaces a refused camera or microphone instead of retrying forever, and recovers on grant +- [Publisher audio unlock](/quest/m2/publish-audio-unlock.md) - the publisher's capture AudioContext is resumed on a gesture or the source is refused, so no silent audio track is announced +- [IETF leftovers](/quest/m2/ietf-leftovers.md) - moq-net: the 0x21 priority property, a NOT_SUPPORTED reply to TRACK_STATUS, and the two FETCH refusal codes come from the registry +- [FFI WebSocket fallback](/quest/m2/ffi-websocket-fallback.md) - moq-ffi and every wrapper can disable or delay the WebSocket fallback +- [Play tune-in backpressure](/quest/m2/play-tunein-backpressure.md) - moq play: a tune-in burst larger than the video queue parks the decoder, so the clock never reaches live at a wide `--delay` +- [Play audio rendition gap](/quest/m2/play-audio-rendition-gap.md) - moq play: a retired audio rendition drains its sink before the replacement fills one, so the switch costs a `--delay` of silence +- [Archive](/quest/m2/archive/README.md) - record selected tracks to any object_store and replay them over FETCH or derived HLS, on the catalog and store the release ships +- [Wildcard](/quest/m2/wildcard/README.md) - a relay resolves subscriptions against advertised patterns and the browser player treats a covering pattern as availability +- [#2152](/quest/m2/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md) - libmoq serves tracks on demand and accepts sessions, the two moq-ffi calls C still lacks +- [Route cold cost](/quest/m2/route-cold-cost.md) - MoqRoute carries warm and cold, so an observed route re-announces intact +- [js/publish discontinuity](/quest/m2/js-publish-discontinuity.md) - the JS container producer and js/publish emit the same marker group on encoder restart +- [Failure artifacts](/quest/m2/qa-failure-artifacts.md) - a failing harness run keeps its run directory and a Playwright trace, and CI uploads them +- [Listening kind field](/quest/m2/harness-drive-bys.md) - revert the relay's `kind` field on the listening log lines; nothing reads it +- [Impaired path](/quest/m2/transport-impairment-profile.md) - the transport drills run over a seeded, impaired UDP path on any host +- [Tooling](/quest/m2/tooling/README.md) - justfiles become a one-line menu over `sh/`, one impact map scopes CI, and every workflow step runs a recipe - [Generation](/quest/m2/hls-generation.md) - init URLs follow the rendition config and segment URLs carry an embedder-supplied generation, so caching can be re-enabled - [Catalog track identity](/quest/m2/catalog-tracks.md) - explore immutable track definitions versus explicit catalog-to-group version binding for live and recorded playback - [Path patterns](/quest/m2/path-patterns/README.md) - one versioned matcher for every predicate over broadcast paths: tokens, origins, interest diff --git a/quest/m1/archive/README.md b/quest/m2/archive/README.md similarity index 84% rename from quest/m1/archive/README.md rename to quest/m2/archive/README.md index 41679d4b4f1..a09d0c3c247 100644 --- a/quest/m1/archive/README.md +++ b/quest/m2/archive/README.md @@ -12,8 +12,11 @@ The same archive supports MoQ FETCH, DVR, and ordinary HLS derived on demand. After normal catalog discovery, an HLS media playlist is generated by downloading only the timeline, never media objects. -The whole line gates the dev merge: moq.pro needs archive-backed recording on -the release dev produces ([merge dev](/quest/m1/merge-dev.md)). +The catalog shape and the store layout ship with the dev merge as +[Archive catalog](/quest/m1/archive-catalog.md) and +[Archive store](/quest/m1/archive-store.md), the two pieces that break a +published surface or define what later versions must read. The rest of the +line is additive on top of them and starts on `main` after the merge. ## Plan @@ -100,18 +103,18 @@ protected broadcasts are out of scope. ## Quests -- [Archive catalog](/quest/m1/archive/catalog.md) - one root `archive` entry subsumes `timeline` and names the timeline track, replay path, store URL, and format version -- [Archive store](/quest/m1/archive/store.md) - `moq-archive` puts, gets, lists, and deletes the versioned objects over `object_store` -- [Recording writer](/quest/m1/archive/writer.md) - feed the segmenter from a `broadcast::Consumer`, store each segment, then commit its record -- [Recording reader](/quest/m1/archive/reader.md) - serve archived FETCH through a supplied `broadcast::Producer` -- [Browser archive](/quest/m1/archive/browser.md) - the same contract for browser-published broadcasts -- [Offline archive HLS](/quest/m1/archive/hls.md) - render playlists from the archive timeline and fetch segment media lazily -- [DVR rewind](/quest/m1/archive/dvr.md) - seek through a bounded archive and return to live playback -- [Archive proof](/quest/m1/archive/proof.md) - prove persistence ordering, selective reads, exact FETCH replay, and timeline-only HLS generation +- [Recording writer](/quest/m2/archive/writer.md) - feed the segmenter from a `broadcast::Consumer`, store each segment, then commit its record +- [Recording reader](/quest/m2/archive/reader.md) - serve archived FETCH through a supplied `broadcast::Producer` +- [Browser archive](/quest/m2/archive/browser.md) - the same contract for browser-published broadcasts +- [Offline archive HLS](/quest/m2/archive/hls.md) - render playlists from the archive timeline and fetch segment media lazily +- [DVR rewind](/quest/m2/archive/dvr.md) - seek through a bounded archive and return to live playback +- [Archive proof](/quest/m2/archive/proof.md) - prove persistence ordering, selective reads, exact FETCH replay, and timeline-only HLS generation ## Related +- [Archive catalog](/quest/m1/archive-catalog.md) - the catalog entry every quest here reads, on dev +- [Archive store](/quest/m1/archive-store.md) - the object layout every quest here reads and writes, on dev - [Catalog track identity](/quest/m2/catalog-tracks.md) - explore immutable definitions or explicit version binding independently of archives -- [wildcard](/quest/m1/wildcard/README.md) - catch-all routing exposes an archive at its stable replay path +- [wildcard](/quest/m2/wildcard/README.md) - catch-all routing exposes an archive at its stable replay path - [e2ee](/quest/m2/e2ee/README.md) - protected broadcasts are excluded initially diff --git a/quest/m1/archive/browser.md b/quest/m2/archive/browser.md similarity index 93% rename from quest/m1/archive/browser.md rename to quest/m2/archive/browser.md index cf34c6eed29..f91f11ce741 100644 --- a/quest/m1/archive/browser.md +++ b/quest/m2/archive/browser.md @@ -38,6 +38,6 @@ remains downstream (moq.pro) work. ## Required -- [Archive catalog](/quest/m1/archive/catalog.md) -- [Archive store](/quest/m1/archive/store.md) -- [Recording writer](/quest/m1/archive/writer.md) +- [Archive catalog](/quest/m1/archive-catalog.md) +- [Archive store](/quest/m1/archive-store.md) +- [Recording writer](/quest/m2/archive/writer.md) diff --git a/quest/m1/archive/dvr.md b/quest/m2/archive/dvr.md similarity index 94% rename from quest/m1/archive/dvr.md rename to quest/m2/archive/dvr.md index 625b878fbd0..26506e05d1c 100644 --- a/quest/m1/archive/dvr.md +++ b/quest/m2/archive/dvr.md @@ -34,8 +34,8 @@ objects retained from an earlier DVR window. ## Required -- [Recording writer](/quest/m1/archive/writer.md) -- [Recording reader](/quest/m1/archive/reader.md) +- [Recording writer](/quest/m2/archive/writer.md) +- [Recording reader](/quest/m2/archive/reader.md) ## Closes diff --git a/quest/m1/archive/hls.md b/quest/m2/archive/hls.md similarity index 97% rename from quest/m1/archive/hls.md rename to quest/m2/archive/hls.md index a967808de43..3c746cebb87 100644 --- a/quest/m1/archive/hls.md +++ b/quest/m2/archive/hls.md @@ -39,4 +39,4 @@ caller-supplied finality, and bounded LRU reads. ## Required -- [Recording reader](/quest/m1/archive/reader.md) +- [Recording reader](/quest/m2/archive/reader.md) diff --git a/quest/m1/archive/proof.md b/quest/m2/archive/proof.md similarity index 96% rename from quest/m1/archive/proof.md rename to quest/m2/archive/proof.md index 04a38443f63..1d6d6a6bb3b 100644 --- a/quest/m1/archive/proof.md +++ b/quest/m2/archive/proof.md @@ -54,5 +54,5 @@ object directly without any listing or separate index object. ## Required -- [Recording writer](/quest/m1/archive/writer.md) -- [Offline archive HLS](/quest/m1/archive/hls.md) +- [Recording writer](/quest/m2/archive/writer.md) +- [Offline archive HLS](/quest/m2/archive/hls.md) diff --git a/quest/m1/archive/reader.md b/quest/m2/archive/reader.md similarity index 96% rename from quest/m1/archive/reader.md rename to quest/m2/archive/reader.md index 1b441c02e5c..1d9b158ede3 100644 --- a/quest/m1/archive/reader.md +++ b/quest/m2/archive/reader.md @@ -50,5 +50,5 @@ missing its tail, and remains readable. ## Required -- [Archive catalog](/quest/m1/archive/catalog.md) -- [Archive store](/quest/m1/archive/store.md) +- [Archive catalog](/quest/m1/archive-catalog.md) +- [Archive store](/quest/m1/archive-store.md) diff --git a/quest/m1/archive/writer.md b/quest/m2/archive/writer.md similarity index 97% rename from quest/m1/archive/writer.md rename to quest/m2/archive/writer.md index 7403d4b9cd3..e5562cdf6ab 100644 --- a/quest/m1/archive/writer.md +++ b/quest/m2/archive/writer.md @@ -77,8 +77,8 @@ import path and enrolls the resulting `broadcast::Consumer` tracks. Downstream ## Required -- [Archive catalog](/quest/m1/archive/catalog.md) -- [Archive store](/quest/m1/archive/store.md) +- [Archive catalog](/quest/m1/archive-catalog.md) +- [Archive store](/quest/m1/archive-store.md) ## Closes diff --git a/quest/m2/audio-jitter-target/README.md b/quest/m2/audio-jitter-target/README.md new file mode 100644 index 00000000000..f08fa75df00 --- /dev/null +++ b/quest/m2/audio-jitter-target/README.md @@ -0,0 +1,72 @@ +# Audio jitter target + +## Goal + +The audio playout target is a measured estimate of arrival timing, ported from +a known-good implementation, in the browser and natively alike. The round-trip +formula is gone. `max(20ms, 1.25 x minRtt)` sized the buffer for a single +retransmit, which describes how long the network takes to recover a loss and +not how unevenly a publisher emits frames, so a sender flushing 100 ms of media +at once got a target far too shallow to play through the next flush. One +written algorithm, cited by both implementations, produces the same target from +the same arrival trace. + +Boundaries: convergence still uses skip-ahead and silence, so playing slightly +faster or slower to converge stays [Time +stretch](/quest/m2/watch-audio-time-stretch.md). No packet loss concealment. +Video keeps its own target; making the audio playhead the clock is [Plan: A/V +clock](/quest/m1/plan-av-clock.md). + +## Plan + +Three quests: the survey and the written algorithm first, then one +implementation per language against it. The two implementations are +independent once the spec lands and may run in parallel. All three are +additive and target `main`: the spec is a document, the native knob is a new +field on a `#[non_exhaustive]` struct, and the browser estimator is a new +module plus a new `spread` observation. + +Neither `main` nor `dev` has a measured estimator. `js/watch/src/sync.ts:150` +still computes `max(MIN_JITTER, minRtt * 1.25)` from the connection's PROBE +(`sync.ts:36-39`, `:144-150`), and `js/watch/src/audio/latency.ts` still +exists. + +The prior art is the branch of PR #3517, `origin/quest/m0/3477-watch-auto-latency`, +two commits ahead of `dev`. The PR is closed and never merged; the watch quest +starts from the branch rather than from `dev`. It already deletes the RTT term +(`latency.ts`, `MIN_JITTER`, `FALLBACK_JITTER`, `#minRtt`, and the `probe` +input are gone from `sync.ts`) and plumbs a per-track arrival `spread` through +`Container.Consumer`, measured at container frame arrival and before the age +budget can skip a group, which is the right observation point. Its estimator, +`js/hang/src/container/jitter.ts`, is a decaying histogram of 5 ms buckets, 200 +of them so the percentile saturates at one second, read at the 95th percentile +plus one frame, with the arrival minimum expiring over two 30 s windows, +`reanchor()` on a discontinuity, and the step down bounded to one frame per +second. `jitter.test.ts` and `js/watch/src/audio/replay.test.ts` cover it. What +the branch still gets wrong is recorded in +[Spec](/quest/m2/audio-jitter-target/spec.md): the extra frame is learned from +the first gap between observed timestamps and the rise is immediate and +unclamped, so a tune-in across a stale group sets the target to seconds. + +Native has no jitter buffer at all. `rs/moq-audio`'s decode `Config` +(`rs/moq-audio/src/decode/decoder.rs:60-80`) carries `max_age`, how far +playback may drift from the live edge before skipping a stalled group, and +`start`, where to begin on a track that already holds groups. Nothing pads the +buffer against uneven arrivals. + +## Quests + +- [Spec](/quest/m2/audio-jitter-target/spec.md) - survey what already exists, then write the algorithm down once +- [Watch](/quest/m2/audio-jitter-target/watch.md) - js/watch and js/hang bring the #3517 branch's estimator into conformance +- [Native](/quest/m2/audio-jitter-target/native.md) - rs/moq-audio grows a measured jitter buffer from the same algorithm + +## Closes + +- [#2812](https://github.com/moq-dev/moq/issues/2812) - the iOS stutter report the same estimator fixes + +## Related + +- [Jitter clock](/quest/m2/jitter-flush-clock.md) - the advertised jitter (#3513 landed the flush span), whose relationship to the measured target the spec settles +- [Audio quality harness](/quest/m2/audio-quality-harness/README.md) - the automated proof, built on its own schedule +- [Time stretch](/quest/m2/watch-audio-time-stretch.md) - inaudible convergence, on top of this +- [Plan: A/V clock](/quest/m1/plan-av-clock.md) - the clock this target eventually feeds diff --git a/quest/m0/audio-jitter-target/native.md b/quest/m2/audio-jitter-target/native.md similarity index 56% rename from quest/m0/audio-jitter-target/native.md rename to quest/m2/audio-jitter-target/native.md index 1c05512a2b3..b356e10c73f 100644 --- a/quest/m0/audio-jitter-target/native.md +++ b/quest/m2/audio-jitter-target/native.md @@ -3,7 +3,7 @@ ## Goal Native playback holds a jitter buffer sized by the algorithm from -[Spec](/quest/m0/audio-jitter-target/spec.md), and passes the same conformance +[Spec](/quest/m2/audio-jitter-target/spec.md), and passes the same conformance vector as the browser on the same trace. `moq play` on a path with uneven arrivals plays through a flush without underrunning, where today it has nothing to absorb one. @@ -13,21 +13,27 @@ Video keeps its own path. ## Plan -`rs/moq-audio` has no jitter buffer at all. `decode::Config` carries only -`latency_max`, an upper bound before skipping a stalled group, and its doc -comment already promises the companion: - -> The `_max` suffix is a reminder that we never *add* latency here: the consumer -> skips only when newer data is already this far ahead. A companion -> `latency_min` for jitter-buffer padding will land in a follow-up. +`rs/moq-audio` has no jitter buffer at all. `decode::Config` +(`rs/moq-audio/src/decode/decoder.rs:60-80`) carries `max_age`, how far +playback may drift from the live edge before skipping a stalled group, applied +to the subscription and clamped to the track's retention in +`decode/consumer.rs:113`, and `start`, where to begin on a track that already +holds groups. Neither adds latency: the consumer skips only when newer data is +already that far ahead. - Measure arrivals at the same point the browser does, on the container consumer before the age budget can skip a group, so both languages estimate from the same observation. -- Add `latency_min` to `decode::Config`, additive on a `#[non_exhaustive]` - struct, so it targets `main`. Its exact contract is a decision this quest - makes and records, not something to leave to the reader, because "floor" and - "fixed target" behave differently under an adaptive estimator: +- Add the knob to `decode::Config`, additive on the `#[non_exhaustive]` struct, + so it targets `main`. Its name is a decision this quest makes. Recommended: + `delay`, mirroring the browser's `delay`/`buffer` split, where `delay` is how + far playback trails the live edge and `max_age` stays the budget above it. + Alternatives: `min_age`, symmetric with `max_age` but "age" describes the + skip budget rather than a cushion; `jitter`, which collides with the + catalog's publisher-declared field and invites the confusion the spec warns + about. +- Its contract is also a decision to record, because "floor" and "fixed + target" behave differently under an adaptive estimator: 1. **Floor.** `Some(d)` is a lower bound and the estimator may still raise the target above it. Recommended: it matches how the browser treats a @@ -38,9 +44,9 @@ comment already promises the companion: fixed-latency preset byte for byte matters more than the parallel above. Either way, state the precedence against the estimator and against - `latency_max`, and what happens when the requested floor exceeds the - effective `latency_max` that `Consumer` already clamps to publisher - retention. Refusing that combination loudly beats silently clamping it. + `max_age`, and what happens when the requested floor exceeds the effective + `max_age` that `Consumer` already clamps to publisher retention. Refusing + that combination loudly beats silently clamping it. - The estimator itself is internal. Only the config field and whatever the playback path needs to report its current target become public, and each one is argued for rather than exposed by default. @@ -53,10 +59,6 @@ comment already promises the companion: replays the same trimmed arrival trace the browser replays and asserts the same target series. -`latency_min` is the natural name only because `latency_max` already exists. If -it reads wrong next to a `Duration` that is a floor rather than a budget, -propose alternatives with a recommendation rather than shipping it. - ## Required -- [Spec](/quest/m0/audio-jitter-target/spec.md) - the algorithm this implements +- [Spec](/quest/m2/audio-jitter-target/spec.md) - the algorithm this implements diff --git a/quest/m0/audio-jitter-target/spec.md b/quest/m2/audio-jitter-target/spec.md similarity index 94% rename from quest/m0/audio-jitter-target/spec.md rename to quest/m2/audio-jitter-target/spec.md index ab2f700f9e6..42b021ae30c 100644 --- a/quest/m0/audio-jitter-target/spec.md +++ b/quest/m2/audio-jitter-target/spec.md @@ -72,7 +72,7 @@ The widely repeated "0.97" is a transitional value, not head. Say explicitly that the forget factor decays once per *resampled observation*, not once per arrival, and give the resulting wall-clock memory (`500ms / (1 - 0.983)`, about 29 s). Applying a per-observation factor per -arrival is the mistake #3517 made, and a number that reads plausible either way +arrival is the mistake the #3517 branch makes, and a number that reads plausible either way is the kind that survives review. Then settle what an interval with no arrival does. An empty interval produces no @@ -87,7 +87,9 @@ what a timestamp discontinuity does to the reference. Two implementations that disagree on any of these produce different targets from the same trace while both look correct. -**What actually breaks #3517, reproduced.** A viewer on that branch reads a +**What the #3517 branch still gets wrong, reproduced.** PR #3517 is closed, +but its branch (`origin/quest/m0/3477-watch-auto-latency`) is where the watch +quest starts, and a viewer on it reads a 14.56 s jitter buffer in auto. The estimator cannot produce that from its histogram: the percentile is clamped to `BUCKETS * BUCKET`, one second. The unbounded term is the "plus one frame" on top of it. @@ -146,7 +148,8 @@ Two lessons for the document, both structural rather than a constant to retune: - **The target needs a clamp and a bounded rise.** WebRTC clamps in `DelayConstraints` (`delay_constraints.{h,cc}`), applied by `DecisionLogic` rather than by the delay manager, with a hard ceiling at 75% of buffer - capacity. #3517 ported neither the clamp nor a rise limit, so any single bad + capacity. The #3517 branch clamps the percentile but not the frame term on + top of it, and has no rise limit, so any single bad observation is permanent on the timescale a viewer will wait. The forget factor is a separate and smaller divergence: `0.9993` is NetEq's @@ -184,16 +187,16 @@ Write `doc/concept/`, covering the observation point, the estimator, rise and fall, startup and re-anchoring, and the clamp. Specifically: - Measure at container frame arrival and before the age budget can skip a - group. #3517 has this right, and it matters: a target derived from what + group. The #3517 branch has this right, and it matters: a target derived from what survives the budget only ever confirms the budget it was cut to. - Rise and fall asymmetry is the "too aggressive or not aggressive enough" dial, so it gets a justification rather than a number. - The clamp reads the rendition's advertised flush span from [Jitter - clock](/quest/m0/jitter-flush-clock.md), which #3513 landed as the + clock](/quest/m2/jitter-flush-clock.md), which #3513 landed as the structural flush span on `dev`. That field is a publisher-declared floor and the estimate is a measurement of the network: say plainly which is which, because the shared word "jitter" invites - confusion. #3517 combines them with a max on the grounds they describe the + confusion. The #3517 branch combines them with a max on the grounds they describe the same quantity; that reasoning does not survive the distinction, so revisit it. - The document is normative, not either implementation. Parity is held by the conformance corpus, one JSON fixture set run by both test suites, the way @@ -205,4 +208,4 @@ chooses differently is still conformant. ## Related -- [Jitter clock](/quest/m0/jitter-flush-clock.md) - the advertised jitter the clamp reads; #3513 landed the flush span, this is its clock-based follow-on +- [Jitter clock](/quest/m2/jitter-flush-clock.md) - the advertised jitter the clamp reads; #3513 landed the flush span, this is its clock-based follow-on diff --git a/quest/m2/audio-jitter-target/watch.md b/quest/m2/audio-jitter-target/watch.md new file mode 100644 index 00000000000..ef0175f4780 --- /dev/null +++ b/quest/m2/audio-jitter-target/watch.md @@ -0,0 +1,92 @@ +# [M] js/watch: the playout target follows the spec, proven in a real browser + +## Goal + +`js/watch` computes its auto target with the algorithm from +[Spec](/quest/m2/audio-jitter-target/spec.md) and passes the conformance +vector. The "Real-time" preset plays clean audio on a LAN and against the +public relay: zero underruns after convergence and no skip-aheads in steady +state, on both the isolated and the postMessage ring paths, confirmed by a +manual run on Chrome and Safari with a real microphone and 40 ms or more of +added RTT. + +Boundaries: the ring's slack, re-stall and underrun counter are mechanical and +already correct on the #3517 branch; this quest changes the estimator above +them. + +## Plan + +Start from `origin/quest/m0/3477-watch-auto-latency`, the branch of the closed +PR #3517, two commits ahead of `dev`. Rebase it onto the base branch first. +Nothing on `main` or `dev` has any of it: `js/watch/src/sync.ts:150` still +sizes auto from `minRtt * 1.25`. + +What the branch already has, and this quest keeps: + +- The RTT term is gone. `js/watch/src/audio/latency.ts` is deleted, and + `MIN_JITTER`, `FALLBACK_JITTER` and `#minRtt` are gone from `sync.ts`; auto + is the larger of the per-track spreads. +- The measurement point: `Container.Consumer` observes each frame at arrival, + before the age budget can skip a group, and exposes it as a `spread` getter. +- The estimator in `js/hang/src/container/jitter.ts`: a histogram of 5 ms + buckets, 200 of them, decayed per arrival by `0.9993`, read at the 95th + percentile and clamped to `BUCKETS * BUCKET` (one second) and to the largest + spread seen; the arrival minimum expires over two 30 s windows; `reanchor()` + drops the baseline on a discontinuity; the step down is bounded to one frame + per second. `jitter.test.ts` covers it. +- The ring work: one chunk of slack above the target, landing back on the + target when skipping, re-stalling on empty, and the underrun counter reaching + the stats panel and the buffering indicator. `replay.test.ts` drives both + rings from a recorded arrival trace. + +What remains is conformance to the spec: + +- The "plus one frame" term. `jitter.ts` learns it as the running minimum of + positive gaps between consecutive observed timestamps, so the first gap sets + it with nothing to validate against, `#publish` raises the target to + `percentile + step` immediately, and `reanchor()` clears `#latest` but not the + learned spacing. That is the 14.56 s reading reproduced in the spec, and it + still reproduces on the branch head. Write the regression first: two frames + whose media timestamps are far apart, then paced audio with zero real jitter, + asserting the target stays near the frame duration. Then take the frame + duration from the source the spec settles on rather than from observed + timestamps, and bound the rise. +- The forget factor: the spec's resampled 500 ms maximum with the underrun + factor, decayed per observation rather than per arrival, replacing the + per-arrival `0.9993`. +- Reordered arrivals excluded from the reference and the histogram, per the + spec. +- Run the conformance corpus in `jitter.test.ts` alongside the existing cases. +- Check what the viewer's saved preset does on load. The element defaults + `delay` to `"auto"` and nothing in `demo/` overrides it, yet a fresh session + came up on the 100 ms chip, so something is restoring or overriding it. Pin + that down: a stored preference silently winning over the default is its own + bug, and it also means auto gets far less real exposure than it looks like. +- Replay the recorded traces from #3477 rather than synthetic ones of the same + shape. They are on the reporter's fork (`fperex/moq`, branch + `debug/rt-audio`) with the raw ndjson attached to release + `rt-audio-traces-2026-09-06`. Trim a copy into the repository and replay it + through both rings in `replay.test.ts`. +- Manual run against the public relay on Chrome and Safari, the two rows the + issue measured. Measure the publisher's audio encoder input-to-output lag in + the same run using the reporter's instrumented harness; #3518 fixed the known + cause, so the 7.35 s lag and the 88 to 275 ms/s drift the issue reported + stand unconfirmed. If drift survives, the suspects are `writeFrame` opening a + group per audio frame under WebTransport stream credit and the main-thread + task queue delivering encoder output. Turn that into its own quest rather + than fixing it here. + +The branch also replaces `probe` in `SyncInput` with per-track `audioSpread` +and `videoSpread` inputs, which breaks the published `@moq/watch` type. This +quest lands on `main`, so it adds the spread inputs beside `probe` and stops +reading `probe`; removing it is part of the `SyncInput` reshape in +[Plan: A/V clock](/quest/m1/plan-av-clock.md) on `dev`. Land the estimator so +that quest can adopt it without a second estimator change. + +## Required + +- [Spec](/quest/m2/audio-jitter-target/spec.md) - the algorithm this implements + +## Related + +- [Plan: A/V clock](/quest/m1/plan-av-clock.md) - reshapes `SyncInput` around the per-track spread this quest produces diff --git a/quest/m2/audio-quality-harness/README.md b/quest/m2/audio-quality-harness/README.md index bad61704479..aec0748db2e 100644 --- a/quest/m2/audio-quality-harness/README.md +++ b/quest/m2/audio-quality-harness/README.md @@ -28,7 +28,7 @@ raw ndjson traces attached to release `rt-audio-traces-2026-09-06`. Upstream that rather than reinventing it. Jitter comes from the seeded userspace UDP shaper in [Impaired -path](/quest/m0/transport-impairment-profile.md), not from a fake arrival clock, +path](/quest/m2/transport-impairment-profile.md), not from a fake arrival clock, so the transport's own contribution is measured rather than assumed. That quest builds the shaper inside the relay drills' support code; it has to come out into something a JS harness process can also put in front of a relay. Extracting it @@ -50,7 +50,7 @@ each of those dimensions moves the expected floor. ## Related -- [Audio jitter target](/quest/m0/audio-jitter-target/README.md) - the estimator this exists to keep honest +- [Audio jitter target](/quest/m2/audio-jitter-target/README.md) - the estimator this exists to keep honest - [Latency ledger](/quest/m2/latency-ledger.md) - promotes this harness's probes into a public API -- [Failure artifacts](/quest/m0/qa-failure-artifacts.md) - keeps the run directory and trace of a failing run +- [Failure artifacts](/quest/m2/qa-failure-artifacts.md) - keeps the run directory and trace of a failing run - [Time stretch](/quest/m2/watch-audio-time-stretch.md) - graded by this harness once it lands diff --git a/quest/m2/audio-quality-harness/browser.md b/quest/m2/audio-quality-harness/browser.md index ef6d63928c9..6537c9997a1 100644 --- a/quest/m2/audio-quality-harness/browser.md +++ b/quest/m2/audio-quality-harness/browser.md @@ -48,7 +48,7 @@ budget, or a schedule. identity is unimplementable if two stages can claim the same milliseconds, and an unaccounted remainder is the finding, so give it a name too. - Extract the seeded shaper from [Impaired - path](/quest/m0/transport-impairment-profile.md) into something that runs as + path](/quest/m2/transport-impairment-profile.md) into something that runs as its own process in front of a relay, so this harness and the drills share one impairment implementation. Assert the shaper actually treated traffic: a profile that silently did nothing turns an impaired run into an unimpaired @@ -73,4 +73,4 @@ budget, or a schedule. ## Required -- [Impaired path](/quest/m0/transport-impairment-profile.md) - the seeded shaper this puts in front of the relay +- [Impaired path](/quest/m2/transport-impairment-profile.md) - the seeded shaper this puts in front of the relay diff --git a/quest/m2/audio-quality-harness/native.md b/quest/m2/audio-quality-harness/native.md index 8f16e0a8284..c9231326078 100644 --- a/quest/m2/audio-quality-harness/native.md +++ b/quest/m2/audio-quality-harness/native.md @@ -35,7 +35,7 @@ Nothing here is a second estimator. Compare the two runtimes at the estimator first: the target series each produces from the same arrival trace, which is the conformance corpus's own comparison and carries no device timing in it. A disagreement there is a finding against [Audio jitter -target](/quest/m0/audio-jitter-target/README.md) and never a reason to widen a +target](/quest/m2/audio-jitter-target/README.md) and never a reason to widen a budget. Only then compare end-to-end totals, with the backend-dependent stages isolated: this lane deliberately accepts real device callback noise, so a difference in totals alone proves nothing about the estimator. @@ -43,4 +43,4 @@ difference in totals alone proves nothing about the estimator. ## Required - [Browser](/quest/m2/audio-quality-harness/browser.md) - defines the metric schema, the budget file, and the extracted shaper -- [Native jitter target](/quest/m0/audio-jitter-target/native.md) - the estimator this lane grades and compares against the browser; without it there is no target series and the budgets would be set against a playout path that holds nothing +- [Native jitter target](/quest/m2/audio-jitter-target/native.md) - the estimator this lane grades and compares against the browser; without it there is no target series and the budgets would be set against a playout path that holds nothing diff --git a/quest/m2/browser-media-qa-engines.md b/quest/m2/browser-media-qa-engines.md index 08dc1c487c0..c5d1dc31755 100644 --- a/quest/m2/browser-media-qa-engines.md +++ b/quest/m2/browser-media-qa-engines.md @@ -35,5 +35,5 @@ which is the path a real Firefox viewer takes today. ## Related - [Runtime QA hosts](/quest/m2/runtime-qa-hosts.md) - where an engine that will not run on the CI image runs -- [Failure artifacts](/quest/m0/qa-failure-artifacts.md) - shared trace and sample output +- [Failure artifacts](/quest/m2/qa-failure-artifacts.md) - shared trace and sample output - [Close classification](/quest/m1/js-close-classification.md) - the same harness, another axis diff --git a/quest/m0/browser-permission-qa.md b/quest/m2/browser-permission-qa.md similarity index 94% rename from quest/m0/browser-permission-qa.md rename to quest/m2/browser-permission-qa.md index 2db1d652275..daa2b9df3b9 100644 --- a/quest/m0/browser-permission-qa.md +++ b/quest/m2/browser-permission-qa.md @@ -38,5 +38,5 @@ external symptom is a `source` that never becomes defined. ## Related -- [Publisher audio unlock](/quest/m0/publish-audio-unlock.md) - the other publisher path that fails silently without a gesture -- [Failure artifacts](/quest/m0/qa-failure-artifacts.md) - shared trace and sample output +- [Publisher audio unlock](/quest/m2/publish-audio-unlock.md) - the other publisher path that fails silently without a gesture +- [Failure artifacts](/quest/m2/qa-failure-artifacts.md) - shared trace and sample output diff --git a/quest/m2/catalog-tracks.md b/quest/m2/catalog-tracks.md index 4726ec7c408..65a3b7018d5 100644 --- a/quest/m2/catalog-tracks.md +++ b/quest/m2/catalog-tracks.md @@ -40,4 +40,4 @@ as a substitute for deciding track identity. ## Related -- [Archive](/quest/m1/archive/README.md) - storage and replay consume the eventual identity contract +- [Archive](/quest/m2/archive/README.md) - storage and replay consume the eventual identity contract diff --git a/quest/m2/e2ee/README.md b/quest/m2/e2ee/README.md index f93cd331ddb..2208e426b08 100644 --- a/quest/m2/e2ee/README.md +++ b/quest/m2/e2ee/README.md @@ -65,5 +65,5 @@ The profile starts from IETF Secure Objects where its object model maps exactly, ## Related -- [archive](/quest/m1/archive/README.md) - protected broadcasts are deliberately outside recording and replay formats +- [archive](/quest/m2/archive/README.md) - protected broadcasts are deliberately outside recording and replay formats - [Merge dev](/quest/m1/merge-dev.md) - its HLS soak (a fresh viewer joining a days-old broadcast, playable since #3240) covers plaintext broadcasts only; stock HLS and DASH exclude `.e2ee` broadcasts diff --git a/quest/m2/ffi-websocket-fallback.md b/quest/m2/ffi-websocket-fallback.md new file mode 100644 index 00000000000..ec163f71a77 --- /dev/null +++ b/quest/m2/ffi-websocket-fallback.md @@ -0,0 +1,56 @@ +# [S] moq-ffi can disable or delay the WebSocket fallback + +## Goal + +A moq-ffi caller, and every wrapper over it (py, swift, kt, go, dart), can +disable the WebSocket fallback or change the head start QUIC gets before it, +the way the CLI (`--connect-websocket-enabled`, `--connect-websocket-delay`) +and libmoq's `moq_client_config` already can. Today a wrapper user on a +WebTransport-only relay has no way to stop the fallback from racing at all. +Additive, on main after the dev merge lands `rs/moq-tokio` there. + +## Plan + +`MoqClient` (`rs/moq-ffi/src/session.rs:310`) holds a +`moq_tokio::connect::Config` (line 381) and exposes it through setters that +each lock the task state and write one field: `set_tls_disable_verify` at +line 389 writes `config.tls.insecure`, `set_reconnect` at 469 writes +`config.once`, `set_backoff` at 476 unpacks a `MoqBackoff` record of `_ms` +fields into `config.backoff`. The fallback knobs live at +`config.websocket`: `websocket::Config` (`rs/moq-tokio/src/websocket.rs:114`) +with `enabled: Option` (131, `None` means on) and `delay: CliDuration` +(141, default 200 ms). libmoq already maps both: `moq_client_config` +(`rs/libmoq/src/api.rs:843`) carries `websocket_enabled` and +`websocket_delay_ms` with `has_` flags (874 to 879), applied in +`rs/libmoq/src/client.rs:64` to `:69`, and defaults exported at +`api.rs:977`. + +Shape, two options: + +- Two setters beside the tls ones, `set_websocket_enabled(bool)` and + `set_websocket_delay(delay_ms: u64)`, mirroring the libmoq fields and the + `_ms` convention `MoqBackoff` uses. Recommended: smallest surface, and + every wrapper already has a one-line pattern for a boolean setter. +- One `set_websocket(MoqWebsocket { enabled, delay_ms })` record like + `set_backoff`. Only worth it if a third knob appears. + +Cross-package sync from the root CLAUDE.md table, with the lines that mirror +`set_tls_disable_verify` today: + +- `rs/libmoq`: already has both fields; nothing to add. +- `py/moq-rs/moq/client.py:80` (constructor kwargs, applied in `__aenter__`). +- `swift/Sources/Moq/Client.swift:15`. +- `kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt:109`. +- `go/wrapper/client.go:194` (the table names `go/wrapper/moq/*.go`; the + wrapper lives at `go/wrapper/` in this tree). `go/ffi` regenerates. +- `dart/moq/lib/moq.dart:32`. `dart/moq_ffi` regenerates. +- `doc/lib/{py,swift,kt,go,dart}/index.md`: add the two options to each + client example. + +Tests: a moq-ffi unit test that each setter lands in `config.websocket`, and a +wrapper test where the tls setter is covered today +(`py/moq-rs/tests/test_server.py`). `just test smoke-full` for the bindings. + +## Related + +- [Connect auth race](/quest/m0/3532-connect-auth-race.md) - the race that a disabled fallback sidesteps entirely diff --git a/quest/m2/flate/README.md b/quest/m2/flate/README.md index bd753224828..24d1dc02c22 100644 --- a/quest/m2/flate/README.md +++ b/quest/m2/flate/README.md @@ -32,4 +32,4 @@ a compressed track is announced, routed, and cached like any other. ## Related -- [#2152](/quest/m1/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md) - the libmoq catch-up this line adds one more symbol family to +- [#2152](/quest/m2/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md) - the libmoq catch-up this line adds one more symbol family to diff --git a/quest/m2/harness-drive-bys.md b/quest/m2/harness-drive-bys.md new file mode 100644 index 00000000000..bc872d9c8cc --- /dev/null +++ b/quest/m2/harness-drive-bys.md @@ -0,0 +1,25 @@ +# [XS] Revert the relay listening kind field + +## Goal + +The test harness isolation from #3509 keeps its point (private run +directories, reserved ports, process-group teardown) and sheds the one thing +that came along without a reason to live here: the `kind` field on the +relay's `listening` log line. Nothing under `test/` reads it, so it goes. + +## Plan + +- `rs/moq-relay/src/relay.rs:266` logs + `tracing::info!(%addr, kind = "quic", "listening")`; revert it to the + single `tracing::info!(%addr, "listening")` line #3509 replaced. +- `rs/moq-relay/src/web.rs:328-337` adds a helper that logs each web + listener's bound address with `kind`; drop the field there too. +- `doc/bin/relay/config.md:234-249` documents the three `kind=` records; + drop the block. +- The `just worktree` recipe that rode in with the same PR is deleted by + [Thin justfiles](/quest/m2/tooling/justfiles.md), not here. + +## Related + +- [Failure artifacts](/quest/m2/qa-failure-artifacts.md) - the harness run directory this trims around +- [Thin justfiles](/quest/m2/tooling/justfiles.md) - removes the `worktree` recipe diff --git a/quest/m2/ietf-leftovers.md b/quest/m2/ietf-leftovers.md new file mode 100644 index 00000000000..b03773d09d3 --- /dev/null +++ b/quest/m2/ietf-leftovers.md @@ -0,0 +1,111 @@ +# [S] moq-transport registry leftovers + +## Goal + +Three registered moq-transport values the tree still gets wrong after the +error-code sweep (#3531) and the joining FETCH fix (#3562): the +DEFAULT_PUBLISHER_PRIORITY property is neither written nor read, TRACK_STATUS +is dropped in Rust and answered with a success in JS instead of refused, and +two FETCH refusals lost their registered codes in the dev merge. Each is fixed +on every negotiated draft, with a byte-level test per version. TRACK_STATUS +itself stays unimplemented: answering it honestly needs a throwaway +SUBSCRIBE, which PR #3519 built and was closed for. + +## Plan + +### DEFAULT_PUBLISHER_PRIORITY (0x21) + +The group header is done: dev stamps +`priority::to_wire(self.track.info().priority)` +(`rs/moq-net/src/ietf/publisher.rs:1873`) and js/net +`toWire(info.priority)` (`js/net/src/ietf/publisher.ts:239`). What remains +is the property. `rs/moq-net/src/ietf/properties.rs` knows only TIMESCALE +0x08 (`:27`) and DEFAULT_PUBLISHER_GROUP_ORDER 0x22 (`:34`), and +`js/net/src/ietf/properties.ts` the same two (`:8`, `:14`); 0x21 falls +through the unknown path. The subscriber builds `track::Info::default()` +with only timescale and max age (`rs/moq-net/src/ietf/subscriber.rs:1419`), +and an absent header priority flag resolves to a literal 128 +(`rs/moq-net/src/ietf/group.rs:333`, `js/net/src/ietf/object.ts:254`). + +- Add 0x21 beside 0x22 in both property modules. Encode it on SUBSCRIBE_OK + and PUBLISH from `info.priority` through `priority::to_wire`; decode it + through `priority::from_wire` into `track::Info::priority` where the + subscriber builds its `Info`. The block is written from draft-17 on and + read from draft-16 on, as `Properties::encode` already gates; draft-14 and + 15 carry the priority only in the group header. +- An absent header flag resolves to the track's declared default first and + only then to the draft's fallback; confirm that fallback against each + draft's text rather than keeping 128 by assumption, and cite the section + in the type's docs. The model has no per-group priority, so a subgroup + value that disagrees with the track's is decoded and dropped. +- Tests: 0x21 round-trips on SUBSCRIBE_OK on every draft that carries the + block and is absent from the bytes on those that do not; a subgroup + without the flag decodes to the declared default; a conflicting header + leaves `track::Info::priority` unchanged. + +### TRACK_STATUS refusal + +`rs/moq-net/src/ietf/publisher.rs:439` matches `ietf::TrackStatus::ID` with +a warning and an empty future, so the request is never decoded and nothing +is written back; on draft-14 and 15 it rides a virtual stream over the +control stream whose reset is a no-op, so the peer waits out its timeout. +`request::Kind` (`rs/moq-net/src/ietf/error.rs:149`) has Subscribe, Fetch, +Publish, PublishNamespace, and SubscribeNamespace and no TrackStatus. +`runTrackStatusRequest` (`js/net/src/ietf/publisher.ts:1022`) answers +draft-15+ with a bare `RequestOk`, a success, and draft-14 with a +`TrackStatus` 0x0e body carrying the draft-13 status enum. + +- Add `Kind::TrackStatus`. Decode the request so the stream is consumed, + reply with the per-draft refusal (TRACK_STATUS_ERROR 0x0f on draft-14, + REQUEST_ERROR from draft-15 on) carrying NOT_SUPPORTED through + `request::to_code(&Error::Unsupported, Kind::TrackStatus, version)`, and + close the writer explicitly, mirroring `run_publish_stream` in + `subscriber.rs` (#3348). +- `runTrackStatusRequest` sends the same refusal on every draft instead of a + success. +- `js/net/src/ietf/adapter.ts:638` routes message 0x0e to a + SubscribeNamespace stream on every version, so a draft-14 TRACK_STATUS_OK + would be handed to whatever SubscribeNamespace stream exists and read as + a namespace. 0x0e is TRACK_STATUS_OK only on draft-14, absent on draft-15, + and NAMESPACE_DONE from draft-16 on. Guard the case on the version (three + lines) and add the adapter test from PR #3519: an unsolicited 0x0e on + draft-14 refuses the session, matching Rust's `classify`. +- Tests: a byte-exact transport-log test per version, in both languages, + that a TRACK_STATUS request yields the refusal and nothing else. + +### FETCH refusal codes + +#3562 on main sent INVALID_JOINING_REQUEST_ID (0x7 on draft-14, 0x32 after) +for a joining FETCH naming no subscription and INVALID_RANGE (0x5 on +draft-14, 0x11 after) for an empty snapshot. The dev merge lost both: +`reject_fetch` keys the code on an `Error` through `request::to_code` +(`rs/moq-net/src/ietf/error.rs:248`), which has no variant for either, so +the `None` arm (`publisher.rs:1057`, "no such subscription") and the +`Joined::Empty` arm (`:1080`, "no objects at subscription start") both pass +`Error::NotFound` and land on DOES_NOT_EXIST. + +- Add the two registry entries to `request` with their per-draft values, + and the `Error` variants they need (`Error` is `#[non_exhaustive]`, + `rs/moq-net/src/error.rs:251`, so adding is not a break); `from_code` + reads them back symmetrically, and `EVERY_ERROR` in the registry tests + grows by two. +- Switch the publisher tests that assert `does_not_exist(version)` + (`publisher.rs:2756`, used at `:2993`, `:2999`, `:3049`, `:3070`, `:3076`, + `:3133`, `:3139`) to the registered code each case actually means, per + version. js/net does not send joining FETCH, so it only needs the decode + side if it reads FETCH_ERROR codes. + +Additive, on main after the dev merge lands. No draft change: all three are +IETF-registered values and moq-lite already specifies the priority field. + +## Closes + +- [#3534](https://github.com/moq-dev/moq/issues/3534) - close this issue when the quest finishes +- [#3492](https://github.com/moq-dev/moq/issues/3492) - close this issue when the quest finishes + +## Related + +- [IETF error codes](https://github.com/moq-dev/moq/pull/3531) - the sweep that introduced `request::to_code` and `Kind` +- [Joining FETCH prefix](https://github.com/moq-dev/moq/pull/3562) - where the two FETCH codes were first sent +- [TRACK_STATUS answered](https://github.com/moq-dev/moq/pull/3519) - the closed PR whose adapter guard and test this reuses +- [IETF uni stream types](/quest/m2/ietf-uni-stream-types.md) - the neighbouring stream-type registry check diff --git a/quest/m0/jitter-flush-clock.md b/quest/m2/jitter-flush-clock.md similarity index 72% rename from quest/m0/jitter-flush-clock.md rename to quest/m2/jitter-flush-clock.md index 98669ba0b61..486c42b9979 100644 --- a/quest/m0/jitter-flush-clock.md +++ b/quest/m2/jitter-flush-clock.md @@ -37,10 +37,21 @@ clock-free estimates from the media span of each emitted batch. `0, 120, 40, 80` ms does not permanently advertise its first 120 ms gap when the reorder delay is only 80 ms. Preserve the never-lower rule for measurements already advertised. +- Enforce the never-lower rule at the publisher, not only by convention. + `js/publish/src/catalog.ts:25-29` already refuses a decrease and a zero for + audio and video renditions; Rust does not. Add `moq_mux::Error::JitterDecreased` + and return it from `Rendition::set`, `Rendition::update`, and + `Rendition::estimate` (`rs/moq-mux/src/catalog/tracks.rs:444`, `:497`, `:486`) + when the resolved jitter would drop below what the catalog already carries. + Extend the `MillisCeil` ceiling serialization (`rs/hang/src/catalog/millis.rs`) + to `TextConfig` (`rs/hang/src/catalog/text/mod.rs:124`), which audio and video + already use, and mirror the zero-as-absent normalization in + `js/hang/src/catalog/text.ts` and the text section of `js/publish/src/catalog.ts`. - Tests inject the clock. Cover: a batch flushed at its end reports the batch, a constant offset reports zero on one track and the offset on the - other track sharing the baseline, and a slow drift stays bounded. + other track sharing the baseline, a slow drift stays bounded, and an + estimate lower than the advertised value is refused on every site. ## Related -- [Audio jitter target](/quest/m0/audio-jitter-target/README.md) - reads this field as its floor +- [Audio jitter target](/quest/m2/audio-jitter-target/README.md) - reads this field as its floor diff --git a/quest/m1/js-publish-discontinuity.md b/quest/m2/js-publish-discontinuity.md similarity index 100% rename from quest/m1/js-publish-discontinuity.md rename to quest/m2/js-publish-discontinuity.md diff --git a/quest/m2/libmoq-fetch.md b/quest/m2/libmoq-fetch.md index 6af744712e5..5ae1b3b27b1 100644 --- a/quest/m2/libmoq-fetch.md +++ b/quest/m2/libmoq-fetch.md @@ -29,4 +29,4 @@ claims group fetch for C; the fetch symbol makes it true. ## Related -- [#2152](/quest/m1/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md) - the dev half: dynamic track serving and server-side accept +- [#2152](/quest/m2/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md) - the dev half: dynamic track serving and server-side accept diff --git a/quest/m2/path-patterns/README.md b/quest/m2/path-patterns/README.md index b1320afde48..5d24596b954 100644 --- a/quest/m2/path-patterns/README.md +++ b/quest/m2/path-patterns/README.md @@ -91,7 +91,7 @@ CAT cannot represent `pid/*/chat`. ## Related -- [Wildcard advertisements](/quest/m1/wildcard/README.md) - routing adopts the +- [Wildcard advertisements](/quest/m2/wildcard/README.md) - routing adopts the matcher while retaining its own cost, pool, refusal, and resolution work - [mTLS explicit scope](/quest/m2/auth-api/mtls-scope.md) - an mTLS grant uses the same versioned publish and subscribe pattern sets diff --git a/quest/m0/play-audio-rendition-gap.md b/quest/m2/play-audio-rendition-gap.md similarity index 96% rename from quest/m0/play-audio-rendition-gap.md rename to quest/m2/play-audio-rendition-gap.md index 9a6a58b4209..c4f10fbf3d1 100644 --- a/quest/m0/play-audio-rendition-gap.md +++ b/quest/m2/play-audio-rendition-gap.md @@ -38,4 +38,4 @@ practice. ## Related -- [Play tune-in backpressure](/quest/m0/play-tunein-backpressure.md) - the other place a wide `--delay` costs more latency than it asked for +- [Play tune-in backpressure](/quest/m2/play-tunein-backpressure.md) - the other place a wide `--delay` costs more latency than it asked for diff --git a/quest/m0/play-tunein-backpressure.md b/quest/m2/play-tunein-backpressure.md similarity index 100% rename from quest/m0/play-tunein-backpressure.md rename to quest/m2/play-tunein-backpressure.md diff --git a/quest/m2/pop-skipping/README.md b/quest/m2/pop-skipping/README.md index cd141a2b60a..4ec79010012 100644 --- a/quest/m2/pop-skipping/README.md +++ b/quest/m2/pop-skipping/README.md @@ -154,5 +154,5 @@ costs of one bidirectional session, which one `?cost=` cannot split. ## Related - [drain](/quest/m2/drain/README.md) - a second relay per PoP makes the same-PoP link price and its connection cardinality operationally important -- [wildcard](/quest/m1/wildcard/README.md) - it reuses this questline's route cost, and needs a cluster on Lite06 +- [wildcard](/quest/m2/wildcard/README.md) - it reuses this questline's route cost, and needs a cluster on Lite06 - [relay-memory](/quest/m2/relay-memory.md) - a denser mesh multiplies whatever a non-selected route costs diff --git a/quest/m2/processor/README.md b/quest/m2/processor/README.md index ae56023f371..8fc438fa12b 100644 --- a/quest/m2/processor/README.md +++ b/quest/m2/processor/README.md @@ -30,5 +30,5 @@ and custom transforms use the same worker lifecycle. - [Reference vision worker](/quest/m3/processor-vision.md) - a runnable worker publishes frame-correlated detections and proves demand, reconnect, failover, and teardown end to end -- [Wildcard advertisements](/quest/m1/wildcard/README.md) - lets a dormant +- [Wildcard advertisements](/quest/m2/wildcard/README.md) - lets a dormant processor advertise what it could serve without enumerating live sources diff --git a/quest/m2/processor/advertise-auth.md b/quest/m2/processor/advertise-auth.md index 2c3a26dd811..89f347f3861 100644 --- a/quest/m2/processor/advertise-auth.md +++ b/quest/m2/processor/advertise-auth.md @@ -28,7 +28,7 @@ publish grant. ## Required -- [Advertise](/quest/m1/wildcard/advertise.md) - supplies the wildcard message +- [Advertise](/quest/m1/wildcard-advertise.md) - supplies the wildcard message and authorization point this capability separates - [Token SDKs](/quest/m2/path-patterns/token-sdk.md) - supplies the published v1 claim writers this extension changes diff --git a/quest/m0/publish-audio-unlock.md b/quest/m2/publish-audio-unlock.md similarity index 60% rename from quest/m0/publish-audio-unlock.md rename to quest/m2/publish-audio-unlock.md index bc23d1ac6a2..dada04344eb 100644 --- a/quest/m0/publish-audio-unlock.md +++ b/quest/m2/publish-audio-unlock.md @@ -7,26 +7,28 @@ why it cannot. `` never announces an audio track that silently carr ## Plan -`@moq/publish`'s `Audio.Encoder` builds its own `AudioContext` the moment a source appears -(`#runSource`) and never resumes it. `@moq/watch`'s decoder handles the same problem with -`unlockOnGesture`; the publisher has no equivalent. +`@moq/publish`'s `Audio.Capture` builds its own `AudioContext` the moment a track source appears +(`#runTrack`, `js/publish/src/audio/capture.ts:130`, the context at `:143`) and never resumes it. +`@moq/watch`'s decoder handles the same problem with `unlockOnGesture`; the publisher has no +equivalent. Observed in `test/smoke/clients/js`, which drives Chromium with no autoplay override: handing the -encoder its source at page load left the audio rendition without a catalog config indefinitely, and +capture its source at page load left the audio rendition without a catalog config indefinitely, and the fixture only became ready once the source was withheld until after a real click. The fixture -carries that workaround today, with a comment pointing here. +carries that workaround today (`test/smoke/clients/js/src/fixture.ts:109`), with a comment pointing +here. - Confirm the mechanism before fixing it. The suspended capture context is the likely cause (a suspended context renders nothing, so the capture worklet never posts the first frame that sets - the captured format), but the observation above is a symptom, not a proof: reproduce it in a - `js/publish` test first. + the captured format), but the observation above is a symptom, not a proof: reproduce it in + `capture.test.ts` first. - Then either apply what `unlockOnGesture` gives the decoder, or refuse the source with a clear error rather than announcing a track that will never carry samples. -- The permission-granted path can reach `#runSource` with no gesture at all (a pre-granted camera on - page load), so a gesture is not something the encoder can assume already happened. +- The permission-granted path can reach `#runTrack` with no gesture at all (a pre-granted camera on + page load), so a gesture is not something the capture can assume already happened. - Drop the workaround in `test/smoke/clients/js/src/fixture.ts` and let the harness assert the behavior instead. ## Related -- [Browser permission QA](/quest/m0/browser-permission-qa.md) - the other publisher path that runs without a gesture +- [Browser permission QA](/quest/m2/browser-permission-qa.md) - the other publisher path that runs without a gesture diff --git a/quest/m0/qa-failure-artifacts.md b/quest/m2/qa-failure-artifacts.md similarity index 89% rename from quest/m0/qa-failure-artifacts.md rename to quest/m2/qa-failure-artifacts.md index 5f1cf6057eb..8285595aa65 100644 --- a/quest/m0/qa-failure-artifacts.md +++ b/quest/m2/qa-failure-artifacts.md @@ -26,8 +26,10 @@ browser drivers record nothing. `smoke.yml` and `wasm.yml` upload nothing. That is the whole quest. Stack dumps of hung processes, relay qlog, HAR capture, retained debug sessions, and fetching CI artifacts by run id were the earlier plan, abandoned with #3506 as far more machinery than a failed -run needs; if one of them earns its place later it is its own quest. +run needs; if one of them earns its place later it is its own quest. The +branch that carried that debug-bundle scope was deleted and is not a +starting point; begin from `main`. ## Related -- [Impaired path](/quest/m0/transport-impairment-profile.md) - records the profile and seed in the same directory +- [Impaired path](/quest/m2/transport-impairment-profile.md) - records the profile and seed in the same directory diff --git a/quest/m1/route-cold-cost.md b/quest/m2/route-cold-cost.md similarity index 100% rename from quest/m1/route-cold-cost.md rename to quest/m2/route-cold-cost.md diff --git a/quest/m0/tooling/README.md b/quest/m2/tooling/README.md similarity index 78% rename from quest/m0/tooling/README.md rename to quest/m2/tooling/README.md index 989db020a37..79753181a5c 100644 --- a/quest/m0/tooling/README.md +++ b/quest/m2/tooling/README.md @@ -2,7 +2,7 @@ ## Goal -A month of merges left the command surface bloated: 865 lines of root +A month of merges left the command surface bloated: 873 lines of root `justfile`, seven self-tests of the tooling itself on every pull request, three metadata guards, recipes nothing calls, and release workflows that are the same file with a binary name swapped. The result is a `just` tree that is @@ -19,7 +19,7 @@ requires the one before it, so they land as one line of pull requests. ## Quests -- [Thin justfiles](/quest/m0/tooling/justfiles.md) - recipe bodies move to `sh/`, one impact map scopes check/fix/test, self-tests and guards are deleted -- [Workflows call just](/quest/m0/tooling/workflows-call-just.md) - no workflow `run:` step names a `.sh`; every script a workflow needs has a recipe -- [Binary release workflow](/quest/m0/tooling/release-binary.md) - moq-cli, moq-relay, and moq-token-cli share one reusable workflow behind three thin callers -- [FFI release workflow](/quest/m0/tooling/release-ffi.md) - the five `release-*-ffi.yml` share the moq-ffi target matrix and artifact staging +- [Thin justfiles](/quest/m2/tooling/justfiles.md) - recipe bodies move to `sh/`, one impact map scopes check/fix/test, self-tests and guards are deleted +- [Workflows call just](/quest/m2/tooling/workflows-call-just.md) - no workflow `run:` step names a `.sh`; every script a workflow needs has a recipe +- [Binary release workflow](/quest/m2/tooling/release-binary.md) - moq-cli, moq-relay, and moq-token-cli share one reusable workflow behind three thin callers +- [FFI release workflow](/quest/m2/tooling/release-ffi.md) - the five `release-*-ffi.yml` share the moq-ffi target matrix and artifact staging diff --git a/quest/m0/tooling/justfiles.md b/quest/m2/tooling/justfiles.md similarity index 80% rename from quest/m0/tooling/justfiles.md rename to quest/m2/tooling/justfiles.md index c5b0cd4692d..a9683705063 100644 --- a/quest/m0/tooling/justfiles.md +++ b/quest/m2/tooling/justfiles.md @@ -55,20 +55,19 @@ Delete: - Self-tests: `_changed-test`, `_markdown-test`, `_select-test`, `_doc-names-test`, `_publish-test`, `sh/rs/package-nfpm.test.sh`, `sh/gh/package-binary.test.sh`. -- Guards: `_doc-names` and `doc-names.jq`, `_fuzz-lock`, and the publish - lower-bound check. This is a deliberate trade: the guards were three - incidents' worth of bash plus their self-tests on every pull request. Where - each surfaces instead: a doc-directory collision shows up as an intermittent - `failed to remove directory` in the `cargo doc` step of whichever pull - request selects both crates, not deterministically (resolve with `doc = - false` as before); a stale internal lower bound fails release-plz's publish. - `_fuzz-lock` is already deleted by #3543, which folds the fuzz harness into - the workspace so the root lockfile and `--locked` cover it; if that lands - first there is nothing left to remove here. `alert.sh check-coverage` - stays: it is a lint of alert.yml, not of a recipe. +- Guards: `_doc-names` and `doc-names.jq`, and the publish lower-bound + check. This is a deliberate trade: the guards were incidents' worth of + bash plus their self-tests on every pull request. Where each surfaces + instead: a doc-directory collision shows up as an intermittent `failed to + remove directory` in the `cargo doc` step of whichever pull request selects + both crates, not deterministically (resolve with `doc = false` as before); + a stale internal lower bound fails release-plz's publish. `_fuzz-lock` is + already gone: #3543 folded the fuzz harness into the workspace so the root + lockfile and `--locked` cover it. `alert.sh check-coverage` stays: it is a + lint of alert.yml, not of a recipe. - The `worktree` recipe and its 170 lines, plus the Worktrees section of `test/README.md`. This absorbs the justfile half of - [Harness drive-bys](/quest/m0/harness-drive-bys.md); keep `_base` folded + [Harness drive-bys](/quest/m2/harness-drive-bys.md); keep `_base` folded into `sh/dispatch.sh`. - `rs bump` and `rs semver`. `rs release` stays for release-rs.yml. - The `mod` lines in `demo/justfile`: `just pub`, `just relay`, `just boy`, @@ -97,4 +96,4 @@ and release-*.yml invoke still resolves. ## Related -- [Harness drive-bys](/quest/m0/harness-drive-bys.md) - the relay `kind` field decision that stays behind once the `worktree` recipe is deleted here +- [Harness drive-bys](/quest/m2/harness-drive-bys.md) - the relay `kind` field revert that stays behind once the `worktree` recipe is deleted here diff --git a/quest/m0/tooling/release-binary.md b/quest/m2/tooling/release-binary.md similarity index 75% rename from quest/m0/tooling/release-binary.md rename to quest/m2/tooling/release-binary.md index 5362e01c743..e7d4678e754 100644 --- a/quest/m0/tooling/release-binary.md +++ b/quest/m2/tooling/release-binary.md @@ -3,11 +3,11 @@ ## Goal `moq-cli.yml`, `moq-relay.yml`, and `moq-token-cli.yml` are three copies of -the same 224-line workflow with the binary name swapped. They become one -reusable `release-binary.yml` taking `crate` and `bin` inputs, and three -callers of a dozen lines each that keep their tag trigger and workflow name, -so `alert.yml`, `release-brew.yml`, and `release-winget.yml` keep matching on -the names they match today. +the same workflow (226, 225, and 226 lines) with the binary name swapped. +They become one reusable `release-binary.yml` taking `crate` and `bin` +inputs, and three callers of a dozen lines each that keep their tag trigger +and workflow name, so `alert.yml`, `release-brew.yml`, and +`release-winget.yml` keep matching on the names they match today. ## Plan @@ -29,4 +29,4 @@ the names they match today. ## Required -- [Workflows call just](/quest/m0/tooling/workflows-call-just.md) - the reusable workflow is written in the recipe style from the start +- [Workflows call just](/quest/m2/tooling/workflows-call-just.md) - the reusable workflow is written in the recipe style from the start diff --git a/quest/m0/tooling/release-ffi.md b/quest/m2/tooling/release-ffi.md similarity index 96% rename from quest/m0/tooling/release-ffi.md rename to quest/m2/tooling/release-ffi.md index c6beb3d113b..5ce157b3ed6 100644 --- a/quest/m0/tooling/release-ffi.md +++ b/quest/m2/tooling/release-ffi.md @@ -32,4 +32,4 @@ only its packaging and publish steps. ## Required -- [Binary release workflow](/quest/m0/tooling/release-binary.md) - proves the reusable-plus-callers pattern before it is applied to five files +- [Binary release workflow](/quest/m2/tooling/release-binary.md) - proves the reusable-plus-callers pattern before it is applied to five files diff --git a/quest/m0/tooling/workflows-call-just.md b/quest/m2/tooling/workflows-call-just.md similarity index 97% rename from quest/m0/tooling/workflows-call-just.md rename to quest/m2/tooling/workflows-call-just.md index e03f3eafa5f..b57cc37bcb2 100644 --- a/quest/m0/tooling/workflows-call-just.md +++ b/quest/m2/tooling/workflows-call-just.md @@ -42,4 +42,4 @@ the swift `package`, `package-ffi`, `publish`, `publish-ffi`, `verify`, ## Required -- [Thin justfiles](/quest/m0/tooling/justfiles.md) - establishes `sh/` and the module recipes the workflows will call +- [Thin justfiles](/quest/m2/tooling/justfiles.md) - establishes `sh/` and the module recipes the workflows will call diff --git a/quest/m0/transport-impairment-profile.md b/quest/m2/transport-impairment-profile.md similarity index 88% rename from quest/m0/transport-impairment-profile.md rename to quest/m2/transport-impairment-profile.md index 499e71ddedd..a7307553261 100644 --- a/quest/m0/transport-impairment-profile.md +++ b/quest/m2/transport-impairment-profile.md @@ -18,6 +18,10 @@ which forwards each datagram to the relay after the profile's treatment, and back. That is not an HTTP interceptor or a TCP proxy, which cannot impair QUIC; it is a datagram relay, and QUIC is indifferent to the extra hop. +`test/drill/README.md:108-110` already forward-references this quest under +"Not covered here"; that README is where the shaper is documented once it +exists, so replace the forward reference with the profile and seed usage. + - A `Shaper` in the drill support code: per-direction delay and jitter, loss, reorder, and a token-bucket rate limit, all driven by one seeded RNG so a failing run's seed reproduces the same treatment. Kernel scheduling @@ -40,4 +44,4 @@ protocol's reaction to loss and delay, not the kernel's rendering of them. ## Related -- [Failure artifacts](/quest/m0/qa-failure-artifacts.md) - stores profiles, seeds, and traces +- [Failure artifacts](/quest/m2/qa-failure-artifacts.md) - stores profiles, seeds, and traces diff --git a/quest/m2/watch-audio-time-stretch.md b/quest/m2/watch-audio-time-stretch.md index 19897aaa3e4..b531e775bc8 100644 --- a/quest/m2/watch-audio-time-stretch.md +++ b/quest/m2/watch-audio-time-stretch.md @@ -31,4 +31,4 @@ Branch from dev. - [Plan: A/V clock](/quest/m1/plan-av-clock.md) - stretching against a free-running ring only moves the drift -- [Watch](/quest/m0/audio-jitter-target/watch.md) - the recorded traces this replays, and the JS target it converges toward +- [Watch](/quest/m2/audio-jitter-target/watch.md) - the recorded traces this replays, and the JS target it converges toward diff --git a/quest/m1/wildcard/README.md b/quest/m2/wildcard/README.md similarity index 95% rename from quest/m1/wildcard/README.md rename to quest/m2/wildcard/README.md index bd0b71686b0..fee086c63e2 100644 --- a/quest/m1/wildcard/README.md +++ b/quest/m2/wildcard/README.md @@ -27,12 +27,12 @@ across the fleet in resident memory. ## Plan -The line sits in m1 so the announce API breaks once: `dynamic(pattern, route)` -takes a path Pattern from day one in +[Advertise](/quest/m1/wildcard-advertise.md) sits in m1 so the announce API +breaks once: `dynamic(pattern, route)` takes a path Pattern from day one in [#3190](/quest/m1/3190-align-origin-broadcast-creation-naming-across-language.md) and [js-announce](/quest/m1/js-announce.md), with a prefix spelled `foo/**` and anything else refused until Advertise lands. Advertise alone gates the -merge; Resolve and Demand are additive and may land on main. +merge; Resolve and Demand here are additive and land on main after it. ### What already exists, and what does not @@ -59,14 +59,14 @@ the requester's excluded hop, ordered by `route_order` (`rs/moq-net/src/model/origin.rs:633`), served on demand by the session that announced it and cached per prefix in `ServeState.served` (`:764`). That is the split-horizon-safe lookup the old `origin::Dynamic` could not provide, and it is what -[Resolve](/quest/m1/wildcard/resolve.md) now extends rather than replaces. +[Resolve](/quest/m2/wildcard/resolve.md) now extends rather than replaces. Route matching, by contrast, is prefix-only (`origin::Prefix`, `rs/moq-net/src/model/origin.rs:498`). The pattern matcher itself exists: `moq_net::path::{Pattern, Patterns, Segment}` (`rs/moq-net/src/path/pattern.rs:172`, `patterns.rs:14`, `pattern.rs:39`) and `Path.Pattern` / `Path.Patterns` in `js/net/src/path.ts` (`:526`, `:846`) own the shared matching, containment, -specificity, and rebasing that [Advertise](/quest/m1/wildcard/advertise.md) +specificity, and rebasing that [Advertise](/quest/m1/wildcard-advertise.md) builds on. What is genuinely missing, beyond patterns themselves, is content identity. @@ -152,7 +152,7 @@ field. composer waiting for an announcement that only demand would produce. The browser player currently enforces the opposite (`js/watch`'s `#isPathAnnounced` hides a catalog rendition with no exact-path - announcement); [Demand](/quest/m1/wildcard/demand.md) makes a covering wildcard count as + announcement); [Demand](/quest/m2/wildcard/demand.md) makes a covering wildcard count as availability there. - **Refusal is a typed stream reset, with no negative cache.** An advertiser resets a subscribe it will not serve, and the reset carries which KIND of @@ -258,25 +258,24 @@ prevent exactly this and goes with it. The archive is the same shape at the source path itself: a recording IS the broadcast, served from storage through the catch-all pattern. A wildcard names no generation, so a client that must distinguish recording generations reads -the catalog's archive entry ([archive](/quest/m1/archive/README.md)) rather +the catalog's archive entry ([archive](/quest/m2/archive/README.md)) rather than announce state. ## Quests -- [Advertise](/quest/m1/wildcard/advertise.md) - moq-net encodes, forwards, and - authorizes wildcard advertisements, without yet resolving one into a - subscription -- [Resolve](/quest/m1/wildcard/resolve.md) - a relay resolves a subscribe or +- [Resolve](/quest/m2/wildcard/resolve.md) - a relay resolves a subscribe or FETCH for an unannounced path against the best matching wildcard -- [Demand](/quest/m1/wildcard/demand.md) - the browser player subscribes to a +- [Demand](/quest/m2/wildcard/demand.md) - the browser player subscribes to a catalog-referenced broadcast a wildcard covers, breaking the lazy-rendition deadlock ## Related +- [Advertise](/quest/m1/wildcard-advertise.md) - the wire and model half + that gates the merge; Resolve requires it - [path-patterns](/quest/m2/path-patterns/README.md) - owns the pattern dialect and the shared matcher advertisements reuse -- [archive](/quest/m1/archive/README.md) - an archive advertises the catch-all +- [archive](/quest/m2/archive/README.md) - an archive advertises the catch-all pattern, and its catalog names the generations a wildcard cannot - [pop-skipping](/quest/m2/pop-skipping/README.md) - it owns the route cost and the rank hash this reuses diff --git a/quest/m1/wildcard/demand.md b/quest/m2/wildcard/demand.md similarity index 92% rename from quest/m1/wildcard/demand.md rename to quest/m2/wildcard/demand.md index e3baaa824d8..2fd57f23ec1 100644 --- a/quest/m1/wildcard/demand.md +++ b/quest/m2/wildcard/demand.md @@ -18,7 +18,7 @@ a pattern, since it tests with `Path.hasPrefix` (`:223`). So the remaining work is narrow: teach the JS client the wildcard advertisement (`js/net/src/announced.ts` and `js/net/src/lite/announce.ts`, -mirroring what [advertise](/quest/m1/wildcard/advertise.md) does in moq-net) +mirroring what [advertise](/quest/m1/wildcard-advertise.md) does in moq-net) and make the covering test use `Path.Pattern` (`js/net/src/path.ts:526`) rather than prefix containment. Withdrawal of the last covering wildcard hides the rendition again, the same @@ -28,7 +28,7 @@ Do not simply delete the gate. It exists so the player does not subscribe to absent broadcasts and so renditions appear and disappear reactively with announcements. The Rust side needs nothing here: `moq-mux::Source` resolves references through `request_broadcast`, which -[resolve](/quest/m1/wildcard/resolve.md) teaches to consult patterns. +[resolve](/quest/m2/wildcard/resolve.md) teaches to consult patterns. Two existing soft spots to not reintroduce: the first evaluation runs before the announcement stream has populated, briefly hiding cross-broadcast @@ -45,5 +45,5 @@ nothing visibly. ## Required -- [Resolve](/quest/m1/wildcard/resolve.md) - recognizing the wildcard is useless +- [Resolve](/quest/m2/wildcard/resolve.md) - recognizing the wildcard is useless until the relay routes the resulting subscribe through it diff --git a/quest/m1/wildcard/resolve.md b/quest/m2/wildcard/resolve.md similarity index 99% rename from quest/m1/wildcard/resolve.md rename to quest/m2/wildcard/resolve.md index 17f390345e5..c3bd496b6be 100644 --- a/quest/m1/wildcard/resolve.md +++ b/quest/m2/wildcard/resolve.md @@ -97,4 +97,4 @@ Tests, at the process level with real sessions rather than an in-process stand-i ## Required -- [Advertise](/quest/m1/wildcard/advertise.md) +- [Advertise](/quest/m1/wildcard-advertise.md) diff --git a/test/drill/README.md b/test/drill/README.md index f2fb5a0975f..b9b441ea402 100644 --- a/test/drill/README.md +++ b/test/drill/README.md @@ -106,8 +106,8 @@ corpus nobody replays. ## Not covered here - An impaired path (delay, loss, rate limits). Loopback is the only path these - drills see; `quest/m0/transport-impairment-profile.md` adds the seeded UDP + drills see; `quest/m2/transport-impairment-profile.md` adds the seeded UDP shaper they run under. - CI lane scheduling. - Failure bundles beyond what the test harness prints, which belongs to - `quest/m0/qa-failure-artifacts.md`. + `quest/m2/qa-failure-artifacts.md`. diff --git a/test/smoke/clients/js/src/fixture.ts b/test/smoke/clients/js/src/fixture.ts index 05cbc3e52a7..0e699c78c39 100644 --- a/test/smoke/clients/js/src/fixture.ts +++ b/test/smoke/clients/js/src/fixture.ts @@ -106,7 +106,7 @@ export class Fixture { // Handed to the capture only once this page has user activation. The capture builds its own // AudioContext the moment a source appears and never resumes it, so one built before the // first gesture stays suspended and no audio is ever captured. See - // /quest/m0/publish-audio-unlock.md; until that lands, giving it the source late is what keeps + // /quest/m2/publish-audio-unlock.md; until that lands, giving it the source late is what keeps // this fixture measuring the player rather than that gap. const audioSource = new Signal(undefined);