From 372506e06f103b5922c6e5e08312ead11ba6e96a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 20:54:22 -0700 Subject: [PATCH] quest(m1): plan frame arrival stamps for TS export lateness Found by the TS recovery arms: a whole-path stall lets held frames out late because the export guesses arrival from its own polls. The maintainer settled the shape: per frame, stamped on completion, a private field behind Frame::arrived(), Rust only. Co-Authored-By: Claude Opus 5.5 --- quest/m1/ts-reliability/README.md | 1 + quest/m1/ts-reliability/arrival-stamps.md | 46 +++++++++++++++++++++++ 2 files changed, 47 insertions(+) create mode 100644 quest/m1/ts-reliability/arrival-stamps.md diff --git a/quest/m1/ts-reliability/README.md b/quest/m1/ts-reliability/README.md index f543017f979..a06edaf68fb 100644 --- a/quest/m1/ts-reliability/README.md +++ b/quest/m1/ts-reliability/README.md @@ -101,6 +101,7 @@ remain with their current quests. - [Plan: semantic fidelity](/quest/m1/ts-reliability/fidelity.md) - explicit profiles and PMT lifecycle contracts produce implementation quests - [Loss and recovery tests](/quest/m1/ts-reliability/recovery.md) - actual MoQ omissions exercise reacquisition and unaffected tracks +- [Arrival stamps](/quest/m1/ts-reliability/arrival-stamps.md) - frames carry their local arrival time, so a stalled path never lets late frames out ## Related diff --git a/quest/m1/ts-reliability/arrival-stamps.md b/quest/m1/ts-reliability/arrival-stamps.md new file mode 100644 index 00000000000..aca55f9235b --- /dev/null +++ b/quest/m1/ts-reliability/arrival-stamps.md @@ -0,0 +1,46 @@ +# [M] Frames carry their local arrival time + +## Goal + +Each frame a moq-net reader receives carries the local instant it landed in +this node's cache, so a consumer judges lateness from that stamp instead of +the moment it happened to poll. TS export uses it, so a stall of the whole +path no longer lets held frames out past their deadline: the ignored arm +`a_path_stall_drops_what_it_made_late` in `rs/moq-mux` passes and loses its +`#[ignore]`. + +Non-goals: wall-clock or cross-hop provenance +([received timestamps are media time](/quest/m1/lite-time-provenance.md)), +and any wire change. + +## Plan + +Found by the TS recovery arms +([moq-dev/moq#6139](https://github.com/moq-dev/moq/pull/6139)): the export +assumes a frame arrived when it last found the source empty, and during a +total stall nothing wakes it, so that guess can lag the real arrival by a +delay or more. Treating a poll after `Pending` as "arrived now" was tried and +reverted: it breaks the `two_legs_*` tests, because a caller polling on its own +cadence judges arrivals differently from one polling after every frame. + +Decided by the maintainer on 2026-10-20 (`/quest-plan`): + +- **Per frame**, not per group: frames in a group arrive over time, so + lateness is per frame. The cost is one `moq_clock::Instant` per cached + frame. +- **Stamped on completion**: when the frame's last byte lands in this node's + cache, the earliest an exporter can emit it. A locally published frame and + a backfilled (fetched) frame are stamped the same way, when they enter the + cache. +- **Accessor only**: `frame::Frame` keeps the stamp in a private field read + through `Frame::arrived() -> moq_clock::Instant`, with a constructor, rather + than a public settable field or a separate reader method. Adding a private + field breaks struct literals of `Frame`, so `rs/moq-net/MIGRATE.md` gets an + entry. +- **Rust only**: the only consumer is the Rust TS export. `@moq/net` mirrors + it when a JS consumer needs it. +- The stamp reads the ambient `moq_clock`, so simulated tests control it. + +## Related + +- [Loss and recovery tests](/quest/m1/ts-reliability/recovery.md) - the arms that found this, and the ignored arm it un-ignores