diff --git a/quest/m1/README.md b/quest/m1/README.md index a34ccc7d22b..e8d9f8467c8 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -67,6 +67,8 @@ session outcomes, and embedder refusals inside session outcomes. - [Untimed lite-07](/quest/m1/lite-untimed.md) - lite-07 carries an untimed track in both languages; lite-05/06 write send time - [A watch and publish release ships assets()](/quest/m1/assets-release.md) - the release that lets the sites host the worklets - [Dogfood hosted worklets](/quest/m1/dogfood-assets.md) - the moq.pro dashboard hosts the worklets and calls `assets()` after the release +- [TS pair acquisition](/quest/m1/ts-pair-acquisition.md) - fix the clean baseline and prove the grader's controls before #5328 enables its scheduled hard gate +- [Initial catalog routing](/quest/m1/initial-catalog-routing.md) - a usable fallback does not strand initial catalog acquisition with a spurious Unroutable - [More tests under load](/quest/m1/test-flakes-2/README.md) - the second round of load-only failures, one quest per flake, fixed at the cause - [END_OF_TRACK placement](/quest/m1/ietf-end-of-track-placement.md) - END_OF_TRACK rides the upstream's Location, and Rust's header stops claiming END_OF_GROUP - [Plan: a public model](/quest/m1/model-public-surface.md) - every crate-private model item is made public or unnecessary, so a custom publisher or subscriber builds from the public model alone diff --git a/quest/m1/initial-catalog-routing.md b/quest/m1/initial-catalog-routing.md new file mode 100644 index 00000000000..a747ec0997e --- /dev/null +++ b/quest/m1/initial-catalog-routing.md @@ -0,0 +1,62 @@ +# [M] Initial catalog acquisition survives a usable transport fallback + +## Goal + +Fix the initial `catalog.json` routing failure observed by TS validation, +with a deterministic regression and an automated round trip. A publisher +remaining available on a usable path must not leave the subscriber with a +spurious `Unroutable`; genuine refusal or disappearance still fails explicitly. + +## Plan + +Decided with the maintainer on 2026-10-11: reproduce and fix the cause, not +stop at diagnosis. This is independent of the pair grader's acquisition +contract. It is not a general transport redesign or a TS-specific retry path. + +Local live, EIT and HRD runs during #5328 failed their initial `catalog.json` +track-info request shortly after selecting WebSocket fallback. The exporter +exited one with `moq: unroutable`; the publisher continued to normal EOF and +exited zero. The live grader received zero packets. Live and EIT ran +concurrently; HRD reproduced later. Do not count these as three independent +sequential reproductions. The full PR TS job passed, including EIT and HRD; +its event skipped the live and pair arms. No transport root cause is established. + +Trace the failing initial request across publication discovery, catalog +availability, route selection and any session replacement. Preserve enough +session/broadcast/request identity to distinguish a real unavailable route +from a stale handle or handover race. First check current main and #5284: +that PR preserves a pending QUIC dial after an early WebSocket close, but +similar timing is not proof that it fixes this failure. If it owns the same +cause, add the missing regression there and verify the landed fix instead of +creating competing implementations. Otherwise keep the fix focused on the +layer that loses the usable route. + +Turn the observed ordering into a controlled regression before changing +behavior. Hold or order the relevant events and mock time where needed; +do not rely on load, sleeps, repeated reruns or larger timeouts to reproduce +or hide the failure. Cover the successful fallback/acquisition path and the +adjacent terminal path so a fix cannot silently retry genuine refusal or +keep a disappeared publication alive. Preserve existing broadcast/track +identity and epoch semantics. + +Verify the affected path with the TS round-trip harness and its existing +process-status, nonempty-content and decoder assertions. A successful rerun +alone does not finish the quest. Wire every regression and any new controls +into CI, with long live coverage at least nightly; retain diagnostic logs +and failing fixtures. Keep the publisher and exporter statuses in the verdict. + +Keep the older short-duration capture regression and midstream `--stitch` +catalog-linger work separate unless reproduction establishes the same cause. +Update comments and affected feature docs with the fix. No new guide, public +API or wire change is expected; a newly required contract needs a maintainer +decision rather than an invented retry or compatibility layer. + +## Related + +- [Validation PR #5328](https://github.com/moq-dev/moq/pull/5328) - records the process failures and successful PR CI baseline +- [Closed fallback](/quest/m1/transport-upgrade/closed-fallback.md) - #5284 owns the pending QUIC dial after an early WebSocket close +- [Fallback PR #5284](https://github.com/moq-dev/moq/pull/5284) - check its actual effect on this reproduction before duplicating work +- [Transport upgrade](/quest/m1/transport-upgrade/README.md) - existing handover and epoch contracts +- [TS duration fidelity](/quest/m0/ts-duration-fidelity.md) - previously captured only a short suffix, not zero-packet initial acquisition +- [Replacement catalog linger](/quest/m1/ts-follow-catalog-bound.md) - bounds a midstream stitch, not initial discovery +- [Pair acquisition](/quest/m1/ts-pair-acquisition.md) - independent grader/mux finding diff --git a/quest/m1/ts-pair-acquisition.md b/quest/m1/ts-pair-acquisition.md new file mode 100644 index 00000000000..c630b83afdc --- /dev/null +++ b/quest/m1/ts-pair-acquisition.md @@ -0,0 +1,60 @@ +# [M] TS pair validation distinguishes acquisition from persistent misalignment + +## Goal + +The late-joining pair test accepts supported clean acquisition and detects +persistent table misalignment without mistaking interleave for emission time. +Its positive baseline and negative controls run in CI before the scheduled +hard gate in #5328 is merged. + +## Plan + +Decided with the maintainer on 2026-10-11: fix the finding, not just diagnose +it. Keep this separate from initial catalog routing and the broader redundant +TS coordinate/API planning in #5327. Fix the baseline before #5328 merges; +do not temporarily make the pair test non-gating. + +The validation run in #5328 used `just test ts --pair`: two exports of one +45-second generated broadcast, the second joining five seconds late. Both +exporters and the publisher exited successfully. PAT/PMT agreement was 100%; +SDT had 20 common placements out of 23 in the union, or 86.96%, below the +existing 90% gate over 41 seconds of shared media. The mismatches were near +acquisition; 20 consecutive later SDT placements matched. These observations +do not establish permanent phase drift. + +`test/ts/table-anchor.py` tags a table with the next PES PTS and infers a +timer-driven phase difference from median cadence. Check those assumptions +against the current slot scheduler and the capture's actual table placement. +Correct the grader, the mux, or both as the evidence requires; do not assume +the exporter is defective because that diagnostic says so. + +Define and document the acquisition behavior being graded for the generated +profile. Any distinction between acquisition tables and recurring tables must +follow an observable stream condition with automated evidence. Do not ignore +an arbitrary number of seconds, reduce the agreement or coverage thresholds, +or shrink the shared window to the surviving table emissions. Keep missing +expected tables and inadequate evidence distinguishable from a passing check. + +Add deterministic controls for supported late acquisition and changed PES +interleave, plus persistent phase offset, drift and table loss within shared +media. The controls must fail for their intended reasons and must prevent a +grader that accepts everything from passing. Keep table carriage, cadence and +packet identity separate: this quest does not promise byte-identical TS legs, +introduce `--sync`, or claim ST 2022-7 compatibility. + +Run the short controls on relevant PRs and the real pair arm at least nightly, +using shared `just test` recipes. Preserve captures and reports on failure. +Require a passing clean pair baseline and failing negative controls before +unblocking #5328; a green PR run that skips the pair arm is not that evidence. +Update `test/ts/README.md` and misleading grader comments/diagnoses inline. + +Public API and wire: none expected. New shared-coordinate or synchronization +contracts remain with the broader alignment planning. + +## Related + +- [Validation PR #5328](https://github.com/moq-dev/moq/pull/5328) - its scheduled pair gate must wait for this fix +- [Pair gate review](https://github.com/moq-dev/moq/pull/5328#discussion_r4243103700) - a known-failing baseline would generate daily alerts +- [TS roadmap #5327](https://github.com/moq-dev/moq/pull/5327) - owns the broader redundant alignment planning +- [Deterministic TS legs](/quest/m2/ts-hitless.md) - packet identity requires a separate contract and proof +- [Initial catalog routing](/quest/m1/initial-catalog-routing.md) - distinct acquisition failure found by the same validation work