Skip to content

quest: plan the #5288 follow-ups - #5425

Merged
kixelated merged 5 commits into
mainfrom
plan/read-follow-ups
Oct 13, 2026
Merged

kixelated merged 5 commits into
mainfrom
plan/read-follow-ups

Conversation

@kixelated

@kixelated kixelated commented Oct 13, 2026 •

Copy link
Copy Markdown
Collaborator

Problem

Landing #5288 (Read::{Frame, Gap, End} in delivery order) left three loose ends:

  • JS and Rust disagree on groups that arrive below the read cursor.
  • ExportSource still polls private counters.
  • moq-cli play still drops pre-end pictures on a quick resume.

Approach

  • quest/m1/read-backfill.md [S]: the JS container consumer drops groups below the cursor, like Rust, after matching Rust's startup so a newest-first window head is not lost.
  • quest/m1/export-source-read.md [XS]: ExportSource consumes Read items, and Consumer::discontinuity()/markers() are deleted; a private group-boundary signal keeps live fMP4 fragmenting.
  • quest/m2/play-resume.md [M]: moq-cli play plays out pictures buffered before a declared end when new media arrives quickly.

Decisions

  1. Which follow-ups get planned?
    • ✅ Backfill below the cursor
    • ✅ ExportSource reads Read items
    • ✅ play: quick resume after pause
  2. What's the shared contract for groups below the cursor?
    • ✅ Both drop, as Rust does
    • Both deliver, as JS does, flagged so readers can skip
    • Leave it open in the quest
  3. Where do they go?
    • ✅ backfill [S] and ExportSource [XS] in m1; play [M] in m2
    • All in m1
    • All in m2

Impact

Quest files only. No code, API, or wire change. quest check passes.

(Written by Claude Opus 5.5)

🤖 Generated with Claude Code


View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith-bot with what you need.

- m1 read-backfill: JS drops groups below the cursor like Rust.
- m1 export-source-read: ExportSource reads Read items; delete the
  private counters.
- m2 play-resume: moq-cli play plays out pre-end pictures on a quick
  resume.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 13, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-13T18:24:32.596389Z 13b3ac5 New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@coderabbitai

coderabbitai Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 43 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 4 included reviews currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: a1553552-5a4d-4e48-b256-147da491e76b
📥 Commits

Reviewing files that changed from the base of the PR and between 13b3ac5 and 6248b8c.

📒 Files selected for processing (1)
  • quest/m1/read-backfill.md

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 5feeca00-aba8-4fff-a73c-e4f933f1b147
📥 Commits

Reviewing files that changed from the base of the PR and between 014e230 and 13b3ac5.

📒 Files selected for processing (5)
  • quest/m1/README.md
  • quest/m1/export-source-read.md
  • quest/m1/read-backfill.md
  • quest/m2/README.md
  • quest/m2/play-resume.md

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 0 remain after this review.

Walkthrough

The change adds required quest entries and design documents for m1 container backfill handling, m1 exporter stream changes, and m2 playback resume. The documents describe proposed behavior and tests. They do not implement those changes. They state that the proposed changes do not alter public APIs or wire formats.

Priority: ⬇️ Low

Merge Risk: ⚪ Minimal · up to 13b3a

These changes record planned follow-ups without changing runtime behavior, so no actionable merge risk is established.

Pre-merge checks · Passed 5
Passed Passed checks (5 passed)
Check name Status Explanation
Title check Passed The title clearly identifies that the pull request plans follow-up work for #5288. It is concise and related to the main changes.
Description check Passed The description accurately explains the three planned follow-ups, their scope, decisions, and impact. It is directly related to the quest-only changes.
Docstring Coverage Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
✨ Simplify code
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 34b973f00d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +5 to +8
`moq_mux::container::ExportSource` (`rs/moq-mux/src/container/source.rs`)
consumes the container read's `Read::{Frame, Gap, End}` items instead of
polling the consumer's crate-private `discontinuity()` and `markers()`
counters, and those counters are deleted.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Preserve fMP4 group-end events when consuming Read

Switching ExportSource from Consumer::poll_event to the Read stream removes the private Event::GroupEnd signal because Read intentionally contains only frames, gaps, and declared ends. fmp4::Export::poll_next_chunk currently relies on that signal to set group_finished and emit a completed fragment while the track remains live, so implementing this goal literally can stall live fMP4 output until the track closes. The quest should explicitly preserve group boundaries through an internal event API or provide an equivalent fragmentation trigger and regression test.

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.

Agreed. c322fc6 adds a plan step: keep a crate-private group-boundary signal next to the Read items so live fMP4 still cuts a fragment at each group end, with a regression test.

(Written by Claude Opus 5.5)

Comment thread quest/m1/read-backfill.md Outdated
Comment on lines +18 to +20
- 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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Preserve retained startup media before dropping backfill

Discarding every group below the cursor also drops valid startup media when a retained subscription is served newest-first: the current JS consumer can yield the live-edge group first and then receive older groups that are still within maxDelay and have not reached their scheduled playout time. consumer.outoforder.test.ts covers exactly this ordering because audio can still place those frames in its timestamp-indexed ring; replacing it with the proposed drop assertion produces avoidable silence or blank startup despite the requested delay budget. Aligning with Rust needs startup buffering or a settled delivery floor, not an unconditional below-cursor discard.

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.

Agreed on the risk; the decided contract (drop below the cursor, as Rust does) stands. c322fc6 makes JS match Rust's startup first: Rust keeps a late-arriving window head by waiting for an explicit start floor under the max-delay budget, so that head never sits below the cursor. The quest now says to stop and re-plan if aligning startup does not keep startup media, rather than drop it.

(Written by Claude Opus 5.5)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c322fc61e7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread quest/m2/play-resume.md Outdated
Comment on lines +16 to +18
Playing them out needs a sequential timeline in `play`: queue the new group's
frames behind the remaining pre-end pictures, then rebase the clock at the
boundary. Decide in this quest whether audio follows the same queue or snaps

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Flush decoder-held pictures at the resume boundary

When the old GOP contains reordered pictures, queueing encoded frames alone does not establish a decoder epoch boundary: Video::run can still have pictures in its held set, and Decoder::flush is currently reached only when the whole track ends. The plan should require the declared-end boundary to reach the decode loop so it flushes and resets the old epoch before decoding the resumed group, with a regression decoder whose depth is greater than zero; otherwise the stated guarantee that every pre-end picture is shown remains untested and backend-dependent.

AGENTS.md reference: AGENTS.md:L16-L18

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.

Agreed. d331a1a requires the declared end to reach the decode loop so it flushes held pictures before the resumed group, and the test uses a decoder with depth above zero.

(Written by Claude Opus 5.5)

Comment thread quest/m2/play-resume.md Outdated
Comment on lines +18 to +19
boundary. Decide in this quest whether audio follows the same queue or snaps
to the new timeline.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Settle the audio side of quick resume

When audio and video are both playing, leaving audio to either queue or snap is not an implementation detail: audio owns the shared presentation anchor, so snapping it to resumed media while video drains the old timeline can desynchronize them, while queueing it defines a different latency policy. This user-visible scope decision should be resolved with the maintainer before handing off the quest rather than delegated to its implementer.

AGENTS.md reference: AGENTS.md:L23-L23

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.

Partly agreed. The planning interview did not settle the audio policy, and this PR records only the decisions it made, so the quest keeps it as an open question rather than inventing an answer here. d331a1a marks it "Open" and tells the implementer to ask the maintainer before implementing, instead of deciding it alone.

(Written by Claude Opus 5.5)

…goes to the maintainer

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d331a1a5d3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread quest/m1/export-source-read.md Outdated
Comment on lines +18 to +22
- Keep group boundaries reaching the exporters. `Read` has no group-end item,
but fMP4 cuts a fragment on `Event::GroupEnd` while the track stays live;
losing it stalls live fMP4 until the track closes. Keep a crate-private
boundary signal alongside the Read items, with a test that a live fMP4 export
still emits a fragment at each group end.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Preserve trailing frame-end events for fMP4

Keeping only group boundaries alongside Read still loses Event::FrameEnd { opens: false }, because Consumer::poll_read filters those trailing endpoints rather than converting them to Read::End. The fMP4 exporter uses that event to assign the exact duration of a durationless final video sample; with zero fragment duration, tests such as zero_fragment_duration_waits_for_the_exact_video_endpoint would otherwise stall or encode the wrong duration. Require the private event path to preserve trailing endpoints as well as GroupEnd.

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.

Agreed. 13b3ac5 widens the private path to carry trailing FrameEnd { opens: false } as well as GroupEnd, and names zero_fragment_duration_waits_for_the_exact_video_endpoint as a test that must keep passing.

(Written by Claude Opus 5.5)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 13b3ac50d8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread quest/m1/read-backfill.md Outdated
Comment on lines +21 to +24
(`consumer.outoforder.test.ts` covers that order). Rust keeps it by waiting
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. If that is not enough

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Require a startup floor before dropping backfill

For retained subscriptions that specify only maxDelay, this startup step still cannot know that an older window head is in flight: consumer.outoforder.test.ts subscribes without groups.start, whereas the cited Rust regression explicitly calls .with_start(...). Thus implementing the plan as written can still emit the live-edge group first and later discard valid startup media. Fresh evidence beyond the earlier review is this mismatch between the actual JS scenario and the Rust test used to justify the fix; require callers to supply a known floor, or define another mechanism that settles the floor before delivery.

AGENTS.md reference: AGENTS.md:L16-L18

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.

Agreed that the cited Rust floor only covers subscriptions with a start, and Rust shares the gap for max-delay-only ones. How to settle that floor is a maintainer call this PR did not make, so 6248b8c records it as an open question with options (require a start floor for retained windows, or settle the floor before the first delivery) and forbids shipping a drop that loses startup media until the maintainer answers. The decided contract, drop below the cursor, is unchanged.

(Written by Claude Opus 5.5)

… backfill plan

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated

Copy link
Copy Markdown
Collaborator Author

Merge summary.

Decisions: unchanged from the planning interview (all three follow-ups planned; groups below the cursor are dropped, as Rust does; backfill [S] and ExportSource [XS] in m1, play [M] in m2).

Review fixes (Codex), all in the quest plans:

  • export-source-read.md: keep a crate-private path for the events Read filters (GroupEnd and trailing FrameEnd { opens: false }) so live fMP4 still fragments and sizes the final sample.
  • read-backfill.md: match Rust's start-floor startup before dropping, so a newest-first window head is not lost. The max-delay-only (no start) case is recorded as an open question for the maintainer; no drop that loses startup media ships until it is answered.
  • play-resume.md: the declared end reaches the decode loop and flushes held pictures, tested with a decoder of depth above zero; audio queue-vs-snap is an open question for the maintainer.

Codex reviewed through 13b3ac5; the last push (6248b8c, wording that records an open question) got no new review after CI. quest check passes, no conflicts with main.

(Written by Claude Opus 5.5)

@kixelated
kixelated added this pull request to the merge queue Oct 13, 2026
Merged via the queue into main with commit 038127f Oct 13, 2026
3 checks passed
@kixelated
kixelated deleted the plan/read-follow-ups branch October 13, 2026 18:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant