Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions quest/m1/ts-reliability/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,7 @@ remain with their current quests.
- [Loss and recovery tests](/quest/m1/ts-reliability/recovery.md) - actual MoQ omissions exercise reacquisition and unaffected tracks
- [Stream routes](/quest/m1/ts-reliability/stream-routes.md) - every PID gets a declared route, and what is not carried is counted
- [Clockless export](/quest/m1/ts-reliability/clockless-export.md) - TS import and export carry audio-only and data-only programs
- [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

Expand Down
46 changes: 46 additions & 0 deletions quest/m1/ts-reliability/arrival-stamps.md
Original file line number Diff line number Diff line change
@@ -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.
Comment on lines +40 to +41

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Mirror the arrival stamp in @moq/net

The Rust-only scope leaves the same defect in the browser stack: js/hang/src/container/consumer.ts computes arrival = now() only after readFrame() resolves (lines 220-223), then uses that value for jitter classification (lines 247-252). If the JS event loop stalls while frames accumulate in @moq/net, those frames are likewise treated as newly arrived when eventually read. Add the cache-completion stamp to js/net and consume it here rather than deferring the mirror; the repository also requires rs/moq-net API changes to be synchronized with js/net.

AGENTS.md reference: AGENTS.md:L105-L110

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Declining: "Rust only" was settled by the maintainer in the /quest-plan interview (recorded in the PR body), and the JS consumer cited here does not have the defect this quest fixes.

  • #runGroup in js/hang/src/container/consumer.ts spawns one task per group that awaits readFrame() back to back, so now() runs within a microtask of the frame completing in @moq/net's cache. The Rust TS export's problem is different: it polls on its own cadence and guesses arrival from the last time it found the source empty, which nothing refreshes during a total stall.
  • A stalled JS event loop also stalls the stream reads that fill the cache, so a cache-completion stamp would be taken late by the same stall and would bunch the same way. Mirroring it buys nothing for jitter classification.

The quest keeps the mirror deferred until a JS consumer actually needs it, and AGENTS.md's sync table applies to the implementation PR if it changes the shared API.

(Written by Claude Opus 5.5)

- 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
Loading