Skip to content

quest: plan the cache, no-overlap, and route-switch gaps before lite-07 - #9234

Merged
kixelated merged 3 commits into
mainfrom
t3/audit-lite07-cache-switching
Nov 20, 2026
Merged

kixelated merged 3 commits into
mainfrom
t3/audit-lite07-cache-switching

Conversation

@kixelated

@kixelated kixelated commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Problem

The maintainer set three rules for moq-net subscriptions and asked whether they hold before the lite-07 cut:

  1. The cache only makes things faster. A partial hit still asks upstream for the miss, and only an open subscription's SUBSCRIBE_OK says where live is.
  2. Groups never overlap in time, though frames within a group may reorder (B-frames). Skipping bounds a whole group by its highest timestamp, and an incomplete one by the lowest timestamp of a higher group.
  3. A route switch caps the old subscription and starts the new one at one group/frame boundary, and the reader sees one subscription.

None of the three is fully implemented on main. The lite-07 wire parts are now owned by quests on main: group times and no relative anchors, both from moq-dev/moq#9249 and both Required by the cut. This PR plans the rest.

Summary

  • rs/moq-net/AGENTS.md states rules 2 and 3, plus the moq-net parts of rule 1 (the live position and partial hits). The root AGENTS.md already states the general cache rule, so its duplicate here goes. The "never blocks an answer" line stays as it was. Rule 2 bounds a whole group by its End, which group times keeps on GROUP_END at or above the highest frame.
  • Quests for every gap that no other quest owns:
Quest Size Milestone Why there
Groups never overlap (moved from m3) L m2, Required by lite07-finalize The cut publishes group times' no-overlap MUST, and moq-mux breaks it today
Missing head asks upstream M m1 Rule 1 fix; the draft's DROP rule relaxes for relays, which breaks nothing
Switch caps the old subscription L m1 Rule 3 fix; no wire change
A replaced copy's short group continues M m1 Rule 3 loss bug, reproduced in JS
Switch caps at a frame M m1, not Required Wire, but the cut doesn't wait for it; m1 ranks it ahead of m2 so it can make the cut
Expire by a higher group's lowest timestamp M m3 Rule 2 fix; needs the no-overlap rule first and breaks nothing

What the audit found

Each claim was checked in the code on main at 9828a20, in Rust and JS.

  • Rule 1.
    • Holds: an idle copy waits for a fresh SUBSCRIBE_OK.
    • Gaps:
      • A time start is placed into a hole between held groups when any higher group is held, with no Previous Start link (containing_received; JS track.ts).
      • A Min Age live join reaches back only over held groups (reach_back).
      • A missing group head is dropped rather than fetched (position_group, a_missing_head_is_dropped_early).
      • Relative starts and ends count over the cache.
  • Rule 2.
    • Only frame 0 is ordered: the draft and check_start compare frame 0s.
    • moq-mux publishes overlap by design (a_keyframe_overlapping_the_previous_group_publishes).
    • Expiry uses GROUP_END's end or the successor's frame 0.
    • Main also ages the latest whole group by wall clock (ended_at).
    • A correction to the first audit pass: a successor's frame 0 is a looser bound than its minimum, not an unsafe one. Only overlap makes it unsafe.
  • Rule 3.
    • Rust resumes at a Position in the newest group handed out, not the largest held.
    • JS re-asks the whole group (js-route-resume, m4).
    • The old copy's bound is chosen when the replacement first delivers, and reaches the wire only if demand narrows.
    • A bare FIN that lands before the stall ends the group after frame 0, though the replacement holds more.

Decisions

From the maintainer's /quest-plan interview, 2026-11-20:

  • No-overlap rule: ✅ strong form, where every frame of a lower group presents before every frame of a higher one (rejected: the weak form, before the next group's frame 0). Group times puts it in the lite-07 draft, and the cut also waits for first-party producers to keep it.
  • Wall clock: ✅ arrival age stays, since it is also the backstop against a publisher that never advances its timestamps, so expiry uses both clocks. The latest group never ages by the wall clock (rejected: main's ended_at, and closed moq-dev/moq#9221's mean-interval estimate; timestamps only).
  • Relative anchors: removed by no relative anchors, which also has a relay ask upstream for a Min Age join. This PR's Min Age quest was dropped as a duplicate when merging main.
  • Old cap at a switch: ✅ by group at the switch, now, with a frame cap as its own quest (rejected: keep today's late bound). The frame cap gets a Position end. Its publisher leaves the boundary group's stream open without a FIN, so a later update can widen the range. The maintainer expects it to make the cut but did not make the cut wait for it.
  • Settled by the rules themselves, without a question:
    • A relay fetches a missing head, reversing the draft's DROP for relays.
    • The switch boundary is the largest group any copy holds.

Owned elsewhere

  • moq-dev/moq#9172 adds quest/m1/time-start-asks-upstream.md, which owns the time-start hole placement. A comment there names containing_received as one more unproven inference to remove, and notes that rule 1 answers that quest's waiting cost question: accept the extra range.
  • Group times recommends bounding an incomplete group by its successor's start. The expiry quest here tightens that to a higher group's lowest timestamp once producers keep the rule.

Impact

Agent guidance and quests only. Public API and wire: none.

Validation

  • quest check (511 documents) and sh/markdown.sh check pass after merging main.
  • just check passed on d9c3bef, including all 10,889 Rust tests. The first run had four trivial moq-net track tests time out together at 60 s. Rerun alone, they pass in 9 ms, and the branch changes no Rust code.
  • A sub-agent traced each claim to file:line on main, in both languages. The first audit pass ran three JS probes; this pass reran none of them.

Models

Size: M

Implementer: Codex, gpt-6.2-astra, high effort
Implementer: Claude Code, claude-opus-5-5, unknown effort

🤖 Generated with Claude Code

(Written by Claude Opus 5.5)

Review

Rewritten by quest review after each round.

  • Head: 852ed66

  • Base: origin/main at cedb53b

  • Risk: medium, The quest plans and revised moq-net agent instructions could steer contributors toward incorrect cache, expiry, or route-switch behavior, but change no shipped code or agent permissions and are fully undone by a revert.

  • Classified: medium by Codex, gpt-6.1-sol, low effort, session 01a1fa8f-7029-7ad1-bbd9-57ca082a546f

  • Reviewer: Codex, gpt-6.1-sol, high effort

  • Session: 01a1fa8b-c6f4-7e01-9370-07e2256d8884, round 2

  • Score: 9/10, The incremental changes consistently align the guidance and plans with group End semantics and the merged base, with no actionable defects found.

  • Rounds: 2; first round 0; findings 0: fixed 0, refuted 0, open 0

  • Findings: none

kixelated and others added 2 commits November 20, 2026 10:06
Records the three subscription rules in moq-net's AGENTS.md and plans each
gap the audit found: groups never overlap (strong form) gates the lite-07 cut;
a relay asks upstream for a Min Age join and a missing group head; a route
switch caps the old subscription at one boundary, by group now and by frame
when the Position end lands; a replaced copy's short group continues; and
expiry bounds an incomplete group by a higher group's lowest timestamp.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated kixelated changed the title docs(moq-net): record subscription cache, timestamp, and handoff rules quest: plan the cache, no-overlap, and route-switch gaps before lite-07 Nov 20, 2026
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated
kixelated marked this pull request as ready for review November 20, 2026 20:05
@coderabbitai

coderabbitai Bot commented Nov 20, 2026

Copy link
Copy Markdown
Contributor

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 1 minute.

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

  • 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: 6f0afec5-107c-4421-98f5-688a13a66c36
Commits

Reviewing files that changed from the base of the PR and between cedb53b and 852ed66.

Files selected for processing: 11

  • quest/m1/missing-head-asks-upstream.md
  • quest/m1/switch-caps-old.md
  • quest/m1/switch-frame-cap.md
  • quest/m1/switch-partial-close.md
  • quest/m2/groups-never-overlap.md
  • quest/m2/lite07-finalize.md
  • quest/m2/time-addressing/group-times.md
  • quest/m3/expire-by-higher-min.md
  • quest/m3/fmp4-group-start-tfdt.md
  • quest/m3/groups-never-overlap.md
  • rs/moq-net/AGENTS.md
  • 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

@kixelated
kixelated enabled auto-merge November 20, 2026 20:05

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

✅ No new issues found.

Approach: sound. It records the three subscription rules in rs/moq-net/AGENTS.md and plans each remaining gap as a quest, so nothing ships ahead of the lite-07 cut unowned.

Reviewed changes

Docs and quest files only, with no code or wire change. I read the quest/m2/lite07-finalize.md, group-times.md, expire-by-higher-min.md, fmp4-group-start-tfdt.md, and rs/moq-net/AGENTS.md hunks closely. I did not read the new m1 quests or the moved groups-never-overlap.md.

  • rs/moq-net/AGENTS.md: the live position now comes only from an open upstream subscription's answer, groups never overlap, expiry uses both timestamps and wall clock, and a route switch splits one subscription at one boundary. The duplicate cache rule is dropped, since the root AGENTS.md already states it.
  • lite07-finalize: it records the decisions and adds groups-never-overlap to Required. The frame cap is explicitly not Required.
  • groups-never-overlap: the quest moves from m3 to m2, and the links in group-times.md and fmp4-group-start-tfdt.md are updated to match.
  • expire-by-higher-min: a new m3 quest that bounds a group by a higher group's lowest timestamp, gated on the no-overlap rule.
  • Switch and missing-head quests: missing-head-asks-upstream, switch-caps-old, switch-frame-cap, and switch-partial-close are new m1 quests.

Pullfrog  | View workflow run | Using claude-sonnet-5-5 | 𝕏

@kixelated
kixelated added this pull request to the merge queue Nov 20, 2026
Merged via the queue into main with commit 847fe82 Nov 20, 2026
9 checks passed
@kixelated
kixelated deleted the t3/audit-lite07-cache-switching branch November 20, 2026 20:22
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