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
36 changes: 23 additions & 13 deletions quest/m1/read-backfill.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,12 @@
# [S] Rust and JS container reads drop groups below the cursor
# [M] Rust and JS container reads drop groups below the cursor

## Goal

The Rust and JS container consumers agree on groups that arrive below the read
cursor: neither delivers them. The read stays `Frame | Gap | End` in delivery
order past the cursor, and what lies below is already covered by the `Gap`
that moved the cursor.
that moved the cursor. This is the ordered read only: APIs that yield in
arrival order keep every group.

## Plan

Expand All @@ -22,16 +23,25 @@ delivers a group that arrives below the cursor as a late backfill; Rust
for an explicit start floor under the max-delay budget
(`startup_keeps_late_arriving_head_group_within_max_delay`); give JS the same
startup so the window head is never below the cursor.
- Open: a subscription with only a max delay and no start (as in
`consumer.outoforder.test.ts`) has no floor to wait for, so the window head
can still land below the cursor, in Rust too. Options include requiring a
start floor for retained windows or settling the floor before the first
delivery. Ask the maintainer before dropping groups in that case; do not
ship a drop that loses startup media.
- Then change the JS consumer to discard groups below the cursor, and add a
test mirroring Rust's: a reordered group older than the cursor is never
yielded and no extra `Gap` appears.
- ✅ Decided 2026-10-13: a settlement window, for ordered APIs only. An
ordered read (the container consumer's in-order `Read` stream, Rust and JS)
with no declared start holds its first delivery until the newest content is
a full max-delay budget ahead (the test Rust already uses to give up on a
missing group), takes the lowest group seen as its floor, then drops
Comment on lines +28 to +30

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.

P2: Bound startup settlement when a live track stops advancing.

This condition requires newer media. With no declared start and a nonzero max delay, a track that supplies one group and stays live but quiet never settles, holding its available frame indefinitely. Rust explicitly covers this in startup_mid_stream_live_track_starts_at_the_served_group (consumer.rs:2596–2617): a 500 ms budget and one group at 3 s must still yield. Specify bounded completion for quiet/paused live tracks and retain the terminal-track escape, rather than requiring media-time advancement for every first delivery. Add those cases alongside the reordered-window regression.

anything below. Unordered, arrival-order APIs (raw `recv_group`, the
arrivals handle from #5311, anything that yields in arrival order) get no
window and no drop. Not chosen: knowingly drop, with the floor at the first
arrival; require a declared start floor for retained windows.
- Give both consumers the window where they lack it (Rust's no-start startup
adopts its cursor from the first arrival today), then make JS discard groups
below the cursor. `consumer.outoforder.test.ts`'s case must keep passing
under the window: the head arriving after the live edge is still delivered.
Add a test mirroring Rust's: a reordered group below the settled floor is
never yielded and no extra `Gap` appears.
- Check JS readers that relied on backfill (watch's audio/video decoders,
`Sync`, the arrivals handle from #5311 if it has landed) and adjust them.
`Sync`) and adjust them; one that wants every group reads an arrival-order
API instead.

Public API: no type change; JS read behavior changes. Wire: none.
Public API: no type change; the ordered read changes in Rust and JS (the first
delivery waits for the window when no start is declared, and JS drops
backfill). Wire: none.
6 changes: 3 additions & 3 deletions quest/m2/play-resume.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,9 @@ declared end has to reach the decode loop so it flushes the pictures it still
holds before decoding the resumed group, which today happens only when the
track ends.

Open: whether audio follows the same queue or snaps to the new timeline. Audio
owns the presentation anchor, so this sets the latency and sync policy; ask
the maintainer before implementing.
✅ Decided 2026-10-13: audio queues with video. One sequential timeline: audio
and video both play out the old segment, then rebase together, which keeps
A/V sync. Not chosen: audio snaps to the new timeline; leave it open.

Test with a declared end followed immediately by a new group, using a decoder
that holds pictures (depth above zero): every pre-end picture is shown before
Expand Down
Loading