[kixelated]

Quest: quest/m1/subscribe-ranges/fetch-range.md

Summary

The overnight attempt stopped before replacing fetch_group. Probing the model turned up three behavior gaps that would break today's fetch callers. This PR lands only the requested benchmark and rewrites the quest to what remains, with the maintainer's decisions below recorded in its Plan.

• track_range_filling (rs/moq-net/benches/track.rs): one reader fills R disjoint ranges of S groups each, all below the feed's start. It is the filling counterpart of track_range_serving.
• The quest is resized to [L]. Its Plan records the decisions and choices below, and waits on the linear fill path quest (quest/m1/subscribe-ranges/fill-linear.md, planned in moq-dev/moq#6790).

Findings

Both gaps were reproduced with throwaway unit tests, which are not committed:

1. No feed frontier means no fill. On a track with no live feed (the moq-archive reader, or a relay copy no subscription feeds), a reader with Range::groups(5..6) parks forever and never asks a fill. A miss only counts below the newest group the feed produced (decision 2 on moq-dev/moq#6123). fetch_group queues a one-group fill instead.

2. Cached backfill is invisible to range readers. One reader's fill caches group 0. A second 0..1 reader then parks with no fill asked: the arrival walk skips backfill, and the miss judge counts it as already held. fetch_group reads it straight from the cache.

3. Relay demand changes on the wire. A one-range read's ranges join the track's aggregate. A relay would then put a bounded SUBSCRIBE upstream where it puts a FETCH today. fetch_only.rs asserts that a moq-transport fetch never subscribes, and a lite SUBSCRIBE before lite-05 cannot name a missing group.

4. The fill path is superlinear. Groups/s over range count (columns) and span (rows):

   span \ ranges	1	16	256
   1	234K	239K	10.2K
   8	569K	216K	7.2K
   64	215K	69K	1.9K

   Two things drive it. Each poll's drift edge (live_edge) and each candidate's successor search (arrival/successor) walk lookup across the reader's runs, and a filled group is never "shown", so every scan passes all of it. Misses::retain also rescans every filled group on each poll. Making retain incremental alone helped only at 16 ranges, so it is left out.

Decisions (maintainer, 2026-10-25)

1. What counts as a miss with no feed frontier (finding 1):
   • ✅ (a) While the track has no live feed, holes in a bounded range are misses up to its end. Recommended: it serves the archive and fetch-only relay copies, and asks nothing of a live feed.
   • (b) Every bounded range's holes are misses up to its end, live feed or not. This asks fills for groups a live feed has yet to produce.
   • (c) Keep a by-sequence read beside subscriptions.
2. Cached backfill (finding 2):
   • ✅ (a) A cached backfill group inside a reader's window is owed to it, like its own fill's answer. Recommended: "a relay behaves the same warm or cold" asks for it. This retires fetched_backfill_not_subscribed and refilled_sequence_stays_out_of_subscriptions.
   • (b) Range readers re-fill a cached group. This costs an upstream FETCH for a group already in the cache.
3. Relay demand before lite-07 (finding 3):
   • ✅ (a) A range wholly below the live edge stays out of the upstream SUBSCRIBE on any wire without range SUBSCRIBE, and per-group FETCH fills it. Recommended: it keeps today's wire behavior until lite-07 ranges land.
   • (b) It goes upstream as a bounded SUBSCRIBE, and SUBSCRIBE_START and SUBSCRIBE_DROP account for it. This works on lite-05 and later only.
4. Order: make the fill path linear (finding 4) in its own quest before this one, since one-range reads put every past read on it.
   • ✅ Yes, in fill-linear.md, planned in moq-dev/moq#6790. That file is not on main yet, so the quest's Plan names the dependency in text; list it under Required once it lands. Recommended

Choices made (recorded in the quest)

• Wire publishers keep parking. The lite and IETF publishers keep parking on a bounded downstream SUBSCRIBE once recv_group ends a bounded read. Today the lite subscriber treats an upstream FIN as the track's end, relying on "bounded downstream demand alone never FINs". If the publishers FIN instead, a peer on a published version reads the range's end as the track's end.
• Route recovery keeps a frame start. resume::Recover fetches the rest of a group from frame N, which a whole-group range cannot express, so a crate-private fetch stays for it.

Public API and wire impact

None. The PR adds a benchmark and edits a quest.

Checks

• just check: passed (moq-net, 3201 tests).
• cargo clippy -p moq-net --benches: clean. cargo bench -p moq-net --bench track -- --test track_range_filling: passed. The numbers above come from a short measured run.
• quest check: ok.
• After merging main: cargo clippy -p moq-net --benches -- -D warnings clean, and track_range_filling passes in test mode.

(Written by Claude Opus 5.5)

🤖 Generated with Claude Code

[chatgpt-codex-connector]

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-25T15:46:59.899376Z	3df5d0d	Draft marked ready

ℹ️ 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.

[kixelated]

Automated review by review (OpenAI)

Reviewed commit: 3df5d0d

No actionable bugs found. The benchmark separates range count from span, excludes fixture setup from timing, and verifies expected delivered-group count. Limiting this PR to measurement and documenting fetch migration prerequisites is sensible; it avoids prematurely changing API or wire behavior.

Verification: static inspection of changes and relevant fill/benchmark code. No tests or benchmarks run; reported performance numbers were not independently reproduced.

[coderabbitai]

No actionable comments were generated in the recent review.

Recent review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 4c4f9b20-585d-4410-9387-aae43b5ef032

Commits

Reviewing files that changed from the base of the PR and between 0bac05e and 3df5d0d.

Files selected for processing: 2

• quest/m1/subscribe-ranges/fetch-range.md
• rs/moq-net/benches/track.rs

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 quest document updates its scope and records decisions about bounded reads, fills, publisher behavior, route recovery, cached backfill, and relay demand. The benchmark adds a fixture that fills disjoint ranges below the feed start, verifies the received groups, and measures performance across range counts and spans.

Priority: Low

Merge Risk: Minimal · up to 3df5d

The benchmark and quest updates appear mergeable after normal checks.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 1 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Title check		The title clearly identifies the main benchmark addition and the related fetch-range scoping work.
Description check		The description directly explains the benchmark, quest updates, findings, maintainer decisions, and validation results.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 1 files. (1 skipped: 1 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[kixelated]

Landing 3df5d0d. Changes since the draft:

• Merged main. cargo clippy -p moq-net --benches -- -D warnings is clean and track_range_filling passes in test mode.
• The quest's Plan records the maintainer's 2026-10-25 decisions, all the recommended options: (1a) while a track has no live feed, holes in a bounded range are misses up to its end; (2a) cached backfill inside a reader's window is owed to it, retiring fetched_backfill_not_subscribed and refilled_sequence_stays_out_of_subscriptions; (3a) a range wholly below the live edge stays out of the upstream SUBSCRIBE on any wire without range SUBSCRIBE and is filled by per-group FETCH until lite-07 ranges land; (4) the fill path goes linear first.
• The fill-linear quest is still only in moq-dev/moq#6790, so the Plan names the dependency in text. Once it is on main, list it under this quest's Required.

The OpenAI and CodeRabbit reviews of this head found nothing actionable. quest check against origin/main passes.

(Written by Claude Opus 5.5)