From 6916a2dbf918907b70fa839a197a70a171daf787 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 20 Nov 2026 10:05:08 -0800 Subject: [PATCH 1/2] docs(moq-net): record subscription cache, timestamp, and handoff rules --- rs/moq-net/AGENTS.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/rs/moq-net/AGENTS.md b/rs/moq-net/AGENTS.md index 43982d64ba..af30d8aa35 100644 --- a/rs/moq-net/AGENTS.md +++ b/rs/moq-net/AGENTS.md @@ -7,8 +7,10 @@ The wire layer: generic over the transport and media-agnostic. - Closes never cascade: aborting a group leaves its track, broadcast, and siblings alone. - Never finish a stream or producer and forget it: something, such as expiry, a cancel, or the session's close, must abort it eventually, or a stale stream holds connection credit and stalls the streams behind it. - A subscription stays on the instance it started on while that instance has a route, even after a newer route wins the path. When none is left, it ends with an error, never a clean end, and never stitches onto another instance. A clean end means only a deliberate publisher finish. Apps restart on announcements, never on request errors. See "Stream instances" in `doc/concept/moq-lite.md`. -- The cache is only an optimization: a relay behaves the same warm or cold, reporting upstream state (such as the largest group) rather than what it holds. -- A relay never blocks an answer on other nodes finishing something; it reports what it knows now. One exception: a track listing's synced mark waits for the upstream's, while its tracks still flow live. +- Serve the part of a subscription the cache can prove and ask upstream for every miss, including missing frames. When the live subscription has ended, wait for the new `SUBSCRIBE_OK` before reporting a live position. Group 10 in an idle cache says only that group 10 existed. +- Forward known results as they arrive. A track listing streams tracks immediately and reports synced once upstream does. +- Frame timestamps may reorder within a group (B-frames). Every timestamp in a lower group must be at or before every timestamp in a higher group. For timestamp-based skipping, use a whole group's maximum timestamp. For an incomplete group, use the minimum known timestamp of a higher group as an upper bound. Without such a bound, its frames may still be in range. +- When switching routes for the same instance, cap the old subscription and start the new one at the same position, just past the frames held contiguously in the largest known group. Drain the old range while possible, accounting for every requested group or asking the new route for what is missing. Use in-flight frames from either copy when available and deliver each frame once on the same logical subscription. - New capabilities are additive SETUP extensions; receivers ignore unknown parameters. - A moq-transport feature with no moq-lite counterpart (e.g. FORWARD=0) gets the least code inside the IETF layer. It may keep crate-private state in the model so a moq-transport-to-moq-transport relay forwards it faithfully, but never adds public API. - Outside the crate, branch on `is_lite()` and `alpn()`. Inside, match draft enums with old drafts listed explicitly and the newest behavior as the fallthrough. From d9c3bef1daf4eab15b5bdf2f3b9a98bbcd20e917 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 20 Nov 2026 11:43:51 -0800 Subject: [PATCH 2/2] quest: plan the cache, no-overlap, and route-switch gaps before lite-07 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 --- quest/m1/min-age-asks-upstream.md | 47 ++++++++++++++ quest/m1/missing-head-asks-upstream.md | 39 +++++++++++ quest/m1/switch-caps-old.md | 52 +++++++++++++++ quest/m1/switch-frame-cap.md | 41 ++++++++++++ quest/m1/switch-partial-close.md | 38 +++++++++++ quest/m2/groups-never-overlap.md | 90 ++++++++++++++++++++++++++ quest/m2/lite07-finalize.md | 16 +++++ quest/m3/expire-by-higher-min.md | 47 ++++++++++++++ quest/m3/fmp4-group-start-tfdt.md | 2 +- quest/m3/groups-never-overlap.md | 64 ------------------ rs/moq-net/AGENTS.md | 8 +-- 11 files changed, 375 insertions(+), 69 deletions(-) create mode 100644 quest/m1/min-age-asks-upstream.md create mode 100644 quest/m1/missing-head-asks-upstream.md create mode 100644 quest/m1/switch-caps-old.md create mode 100644 quest/m1/switch-frame-cap.md create mode 100644 quest/m1/switch-partial-close.md create mode 100644 quest/m2/groups-never-overlap.md create mode 100644 quest/m3/expire-by-higher-min.md delete mode 100644 quest/m3/groups-never-overlap.md diff --git a/quest/m1/min-age-asks-upstream.md b/quest/m1/min-age-asks-upstream.md new file mode 100644 index 0000000000..afec7867cb --- /dev/null +++ b/quest/m1/min-age-asks-upstream.md @@ -0,0 +1,47 @@ +# [M] A relay places a Min Age live join from its upstream's answer + +## Goal + +A reader that joins at the live edge with a nonzero `Subscriber Min Age` +through a relay starts at the group it would start at reading the publisher +directly, however much of the track the relay's copy holds. In Rust and +`@moq/net`, a copy places that start from its own groups only where they prove +upstream's answer, and otherwise asks upstream and waits for the answer. + +## Plan + +Found by the 2026-11-20 audit of the subscription rules before the lite-07 +cut. A cache only makes things faster (root `AGENTS.md`), but a live join +reaches back only over the groups this hop holds: + +- Rust: `joins` (`rs/moq-net/src/model/subscription/window.rs`) through + `TrackState::reach_back` (`model/track.rs`), whose comment says it is always + a group this hop holds, so a copy never asks its upstream for the prefix it + lacks. +- JS: `#reachBack` (`js/net/src/track.ts`). +- The relay already forwards the largest Min Age upstream on SUBSCRIBE and + SUBSCRIBE_UPDATE, but no reader's start waits on what upstream resolves. + +A copy that went live seconds ago serves a 5 s Min Age join from the 1 s it +holds, where the publisher would hand over 5 s. + +- Recommended: the copy places the start itself only when it holds every group + from the live edge back to a group starting at or before the edge minus the + reader's Min Age, received contiguously since it went live. Otherwise it adds + the reader's join to its upstream subscription as a range of its own, under + the reader's Min Age, and starts where that range's SUBSCRIBE_STARTED + resolves. Groups at or past the live edge keep flowing meanwhile. +- The draft's "The publisher starts from what it holds and never fetches to + reach further back" stays true of an origin. Add that a relay's start comes + from its upstream's answer whenever its own holdings can't prove it. +- Share the mechanism with [time-start-asks-upstream](https://github.com/moq-dev/moq/pull/9172) + (`quest/m1/time-start-asks-upstream.md` on #9172's branch), which asks + upstream for a time start the same way. Whichever lands first builds it. +- Relative anchors are being removed in another session, which changes how a + live join is spelled on the wire. Build on whatever spelling has landed. + +Reproduce first: a relay whose copy went live 1 s ago, and a reader joining +with a 5 s Min Age against a publisher holding 10 s, in +`rs/moq-net/tests/integration` and `js/net/src/integration.test.ts`. + +Public API: none expected. Wire: none; the draft clarifies a relay's start. diff --git a/quest/m1/missing-head-asks-upstream.md b/quest/m1/missing-head-asks-upstream.md new file mode 100644 index 0000000000..89d2090622 --- /dev/null +++ b/quest/m1/missing-head-asks-upstream.md @@ -0,0 +1,39 @@ +# [M] A relay fetches a group's missing head instead of dropping it + +## Goal + +When a relay's copy holds only the later frames of a group a subscription +covers, as when its upstream subscription started at a Position, the relay +fetches the earlier frames from upstream and delivers the group whole. It +names the group in SUBSCRIBE_DROP only when upstream can't supply them. A +subscriber gets the same group through the relay, warm or cold, as it would +from the publisher. Rust and `@moq/net` match, and the moq-lite draft says so. + +## Plan + +Found by the 2026-11-20 audit of the subscription rules before the lite-07 +cut. A cache only makes things faster (root `AGENTS.md`), so a partial hit +asks upstream for the miss. The draft's Positions section says the opposite: +"A publisher that holds only the later frames of a Group a subscription +covers names it in a SUBSCRIBE_DROP rather than deliver the part it holds". +The Rust publisher does that. `position_group` (`rs/moq-net/src/lite/publisher.rs`) +finds no head, and its caller logs "skipping group with a missing head" and +drops the group with `NotFound` (test `a_missing_head_is_dropped_early`). +Check what `@moq/net`'s publisher does. + +- Recommended: the copy FETCHes the missing frames (`Frame Start` 0 through + the first frame it holds) through the group-fill path a miss already uses, + and the publisher serves the group once the head lands, within the + subscriber's budget. A failed or refused fetch falls back to the DROP. +- The draft's sentence becomes: a relay fetches the missing earlier frames + from upstream, and a publisher that can't obtain them names the group in a + SUBSCRIBE_DROP. A subscriber already handles both. +- A copy holding the earlier frames of a group its upstream closed short keeps + delivering them and closing without GROUP_END. Upstream has no more, so + that matches a direct read. + +Reproduce first: a relay whose first reader resumes at a Position partway +through a group, then a second reader whose range covers that group whole. + +Public API: none expected. Wire: none; the draft's Positions rule changes for +relays. diff --git a/quest/m1/switch-caps-old.md b/quest/m1/switch-caps-old.md new file mode 100644 index 0000000000..800fc1d700 --- /dev/null +++ b/quest/m1/switch-caps-old.md @@ -0,0 +1,52 @@ +# [L] A route switch caps the old subscription at one boundary + +## Goal + +When a front moves a track to another route of the same instance, the reader +sees one subscription split at one boundary, chosen at the switch. The +boundary is the largest group any copy holds, past the frames held +contiguously in it. The new subscription starts there. The old one is capped +at that group on the wire at once and drains what lies below it within the +budget. Each frame is delivered once, from whichever copy brings it first. +Rust and `@moq/net` match. + +## Plan + +Found by the 2026-11-20 audit of the subscription rules before the lite-07 +cut. Today: + +- Rust `Reader::sync` (`rs/moq-net/src/model/resume.rs`) resumes from the + newest group handed to the reader (`held_at`, `resume_at`), not the largest + any copy holds. JS `sync` (`js/net/src/resume.ts`) asks that group from + frame 0, which [js-route-resume](/quest/m4/js-route-resume.md) owns. +- A switch only marks the old copy replaced. Its bound is chosen later, by + `observe` when the replacement hands out its first group, or by + `bound_at_end` (JS `#observe`, `#boundAtEnd`). It reaches the wire as + SUBSCRIBE_UPDATE only if the copy's aggregate demand narrows, so until then + both routes send every new group. + +Decided 2026-11-20 (maintainer, /quest-plan): ✅ cap the old at the switch, by +group (rejected: keep today's late bound; cap by frame now, which +[switch-frame-cap](/quest/m1/switch-frame-cap.md) adds on top of this). + +- At the switch, pick the boundary group G and frame N. The replacement starts + at Position (G, N). The old copy's ranges end at G, so it finishes G and + sends nothing newer. That goes out as SUBSCRIBE_UPDATE right away. +- The old copy keeps draining every group below G within the budget, as + `let_go` already allows. A group it can't deliver is asked of the new route + (`backfill_gaps`). +- Once the replacement delivers past the old copy's position in G, stop only + G's stream on the old copy, which also ends a group that never finishes. +- Run the resume and failover models (`/verify-resume`, `/verify-failover`) + after updating them, since they encode today's bound. Teach the resume + oracles (`resume_model.rs`, `resume.model.test.ts`) the fixed boundary. + +Test: a switch while the old route still delivers sends no group above G from +the old route, loses no group below G, and delivers G's frames once, in both +languages. + +Public API: none expected. Wire: none. + +## Related + +- [A replaced copy's short group continues from the replacement](/quest/m1/switch-partial-close.md) - the other gap the audit found at a switch diff --git a/quest/m1/switch-frame-cap.md b/quest/m1/switch-frame-cap.md new file mode 100644 index 0000000000..6c3b610e3c --- /dev/null +++ b/quest/m1/switch-frame-cap.md @@ -0,0 +1,41 @@ +# [M] A route switch caps the old subscription at a frame + +## Goal + +A lite-07 Range can end at a Position (a group's start and a frame), so a +route switch caps the old subscription at the exact frame where the +replacement starts. The old publisher sends nothing of the boundary group +past that frame, beyond what was already in flight. Rust, `@moq/net`, and the +moq-lite draft change together. + +## Plan + +Decided 2026-11-20 (maintainer, /quest-plan auditing the subscription rules +before the lite-07 cut): a switch caps the old subscription by group first +([switch-caps-old](/quest/m1/switch-caps-old.md)), and this quest adds the +frame cap on top. It isn't Required by +[the lite-07 cut](/quest/m2/lite07-finalize.md). It rides lite-07 if it has +landed when the cut is made, and otherwise moves to the next wip version. + +- Today a Position is a `Start` only (draft, SUBSCRIBE's Anchor Type), and the + Positions section says a subscription "never stops partway through" a + Group. Allow Position as an `End` too, ending before that frame. Check how + it reads beside "both ends include the Group they name". +- A publisher reaching a Position end stops the group's stream without a FIN + (maintainer: a later SUBSCRIBE_UPDATE may widen the range to include the + rest). The stream stays open until the range widens, the group expires, or + the subscription ends. Account for the credit it holds, per moq-net's rule + that no stream is finished and forgotten. +- The switch then ends the old copy's ranges at Position (G, N) instead of + group G, and drops the step that stops G's stream once the replacement + passes it. +- moq-transport has no frame end; its publisher serves the whole group, as + today. +- Run `just test interop --all`. + +Public API: the range end type gains a Position in Rust, JS, and the +bindings. Wire: lite-07-wip if before the cut, else the next wip version. + +## Required + +- [A route switch caps the old subscription at one boundary](/quest/m1/switch-caps-old.md) - the switch-time cap this narrows to a frame diff --git a/quest/m1/switch-partial-close.md b/quest/m1/switch-partial-close.md new file mode 100644 index 0000000000..26ea15614d --- /dev/null +++ b/quest/m1/switch-partial-close.md @@ -0,0 +1,38 @@ +# [M] A replaced copy's short group continues from the replacement + +## Goal + +A group that a replaced copy closes short (FIN without GROUP_END) continues +from the replacement at the next frame, so the reader gets every frame the +group holds, as if read from one route. The group ends early only when no +route can supply more. Rust and `@moq/net` match. + +## Plan + +Found by the 2026-11-20 audit of the subscription rules before the lite-07 +cut, and reproduced in JS. In the resume test "a stalled group continues from +the replacement at the next frame", have the old copy close its one-frame +group with `finish()` before `swap()`, under a five-minute budget. The other +copy holds three matching frames, yet the reader ends the group after frame 0. + +- Rust: a bare FIN finishes the received group (`recv::Group::end(None)`, + `rs/moq-net/src/recv.rs`), and `poll_resumed` (`model/group.rs`) treats a + finished read as needing no route ("Read to its end"). +- JS: `#readFrame` (`js/net/src/group.ts`) returns the end: "The copy finished + the group: a replacement asked for meanwhile is moot". +- Only when the reader parks on the next frame before the FIN lands does + `Recover::wants` move it to the replacement. Which happens depends on + arrival order. + +Recommended: a read that reaches a closed group's end on a copy the front has +replaced, or while another route may hold more, recovers the next frame from +the replacement as a stall does. It ends the group only once a copy holds it +whole, or the replacement also has nothing past that frame. A group read to a +GROUP_END is whole and ends as today. +[moq-dev/moq#9221](https://github.com/moq-dev/moq/pull/9221) turns the whole +marker into a flag (`is_whole`), so build on whichever has landed. + +Add the reproduction in both languages, and the case to the resume models +(`/verify-resume`), whose oracles should require every frame some route held. + +Public API: none expected. Wire: none. diff --git a/quest/m2/groups-never-overlap.md b/quest/m2/groups-never-overlap.md new file mode 100644 index 0000000000..5431c8af30 --- /dev/null +++ b/quest/m2/groups-never-overlap.md @@ -0,0 +1,90 @@ +# [L] Every frame of a group presents before every frame of a higher group + +## Goal + +Groups never go back in time: every frame of a group presents strictly before +every frame of any higher group, so a reader bounds a group that isn't whole +by the lowest timestamp it knows in a higher group. Frames within a group may +still reorder (B-frames, open-GOP leading pictures). Sources that overlap +today, such as a TS content join, publish without ending the broadcast and +without rewriting a timestamp. The moq-lite and hang drafts state the rule, +and the producers and every importer keep it, in Rust and JS. + +## Plan + +[moq-dev/moq#4543](https://github.com/moq-dev/moq/pull/4543) replaced the +importers' live-edge floor and TS `Reanchor` shift with monotonic group starts. +With nothing shifted, a TS content join +([#3798](https://github.com/moq-dev/moq/issues/3798)) publishes an IDR below +the old content's last frame, so the draft now lets frames present below the +previous group's content (`drafts/draft-lcurley-moq-hang.md`, the malformed-group +rules), and even lets a group start at the previous group's start. +`container::Producer::prepare` opens a group for a keyframe above the open +group's start, even one below its newest frame +(`a_keyframe_overlapping_the_previous_group_publishes`). The moq-lite draft +only orders frame 0s ("a publisher MUST NOT start a Group's frame 0 at or +before that of any Group with a lower start", in its Frame section), and +`@moq/net` accepted a frame at 250 in group 100 after group 200 opened. + +That overlap is why +[moq-dev/moq#8874](https://github.com/moq-dev/moq/pull/8874) cannot place an +HLS group early with certainty: when the overlap straddles a grid line, an +edge that saw the earlier group and one that joined at the overlapping group +list one segment differently. #8874 documents that case in +`rs/moq-hls/src/export/grid.rs` and `doc/bin/hls.md`; delete both notes here. + +Start by finding every source that overlaps and why: the TS content join, +other importers (fMP4, FLV, MKV, RTMP, SRT, HLS), encoders, and the JS +publisher. + +Decided 2026-11-15 (maintainer, /quest-plan): + +- ✅ Enforce the rule end to end: draft, producer, importers (rejected: + investigate only and plan the fix later; end the import at an overlapping + keyframe, which would stop a TS feed at every content join). +- ✅ A keyframe that doesn't start after the open group's newest frame continues + that group, as one at or below its start already does (rejected: shift the + broadcast forward at each join, which brings back the rewriting #4543 + removed and drifts the catalog clock; leave it to the implementer). The + group at a join then runs about two GOPs: a viewer can't join exactly there, + and HLS lists one over-long segment through its overrun path. +- ✅ Readers assume the rule and don't detect it, per AGENTS.md (rejected: + `container::Consumer` refusing an overlapping group). A publisher that + breaks it hurts only its own broadcast. Delete any reader-side overlap + handling the rule makes dead. moq-net's frame 0 check (`check_start`) stays + as it is. + +Decided 2026-11-20 (maintainer, /quest-plan auditing the subscription rules +before the lite-07 cut): + +- ✅ The strong form: every frame of a lower group presents before every frame + of a higher one (rejected: the weak form, every frame before the next + group's frame 0, which bounds an incomplete group only by a higher group's + frame 0). Conforming HEVC and H.264 already keep it, since a leading picture + follows every picture of the previous GOP in output order. Only a splice can + break it. +- ✅ The moq-lite draft states it as a publisher MUST in lite-07, and the cut + waits on this quest (moved from m3): the cut publishes the rule, and + first-party producers break it today. + +Recommended for a splice: a frame after the keyframe that would present at or +before the previous group's newest frame, such as a RASL picture, is dropped. +It references pictures from before the splice, so it can't decode there +anyway. Check RADL pictures, which do decode, before settling on dropping +them too. + +The hang draft's "a group MAY start at the same timestamp as the previous +group" goes too. + +Tests: the producer test above becomes one where the overlapping keyframe +continues the group, and a TS import across a content join, including leading +pictures, publishes groups whose frames all precede every frame of the next +group. + +Public API: none expected. Wire: none; the moq-lite and hang drafts' group rule +tightens. + +## Related + +- [An incomplete group expires by the lowest timestamp of a higher group](/quest/m3/expire-by-higher-min.md) - the expiry bound this rule makes safe +- [An fMP4 group start never rewinds the decode timeline](/quest/m3/fmp4-group-start-tfdt.md) - a keyframe repeating its predecessor's timestamp would now continue the group; check which of its cases remain diff --git a/quest/m2/lite07-finalize.md b/quest/m2/lite07-finalize.md index 430e9bc508..e8f8fa9fec 100644 --- a/quest/m2/lite07-finalize.md +++ b/quest/m2/lite07-finalize.md @@ -211,9 +211,25 @@ The padding paragraph above is superseded: lite-07 freezes with no Padding type, and [the padding probes](/quest/m5/probe-padding.md) bring one back in the version that ships them. +Decided 2026-11-20 (maintainer, /quest-plan auditing the cache, timestamp, +and switching rules in `rs/moq-net/AGENTS.md` before the cut): + +- ✅ The cut waits for [groups never overlap](/quest/m2/groups-never-overlap.md) + (rejected: after the cut). The draft gains a publisher MUST that every frame + of a lower group presents before every frame of a higher one, which expiry + relies on, and first-party producers break it today. +- ✅ [The frame cap](/quest/m1/switch-frame-cap.md) is not Required, like the + warmth port: if it has landed when the cut is made, its Position end is in + lite-07, and otherwise it moves to the next wip version. +- The audit's other gaps change no wire and don't gate the cut: a relay + asking upstream for a Min Age join and a missing group head, the switch's + group cap, a replaced copy's short group, and expiry by a higher group's + lowest timestamp. + ## Required - [Cache-aware multicast](/quest/m2/multicast/README.md) - lite-07 carries the redesigned route layer: routes to forwarding nodes, no holds or doubt, claims crossing trust boundaries by a chain, and no Route Key +- [Groups never overlap](/quest/m2/groups-never-overlap.md) - the draft's publisher MUST that every frame of a lower group presents before every frame of a higher one, kept by first-party producers ## Related diff --git a/quest/m3/expire-by-higher-min.md b/quest/m3/expire-by-higher-min.md new file mode 100644 index 0000000000..5b9eb45c4a --- /dev/null +++ b/quest/m3/expire-by-higher-min.md @@ -0,0 +1,47 @@ +# [M] A group expires by its own highest timestamp, or a higher group's lowest + +## Goal + +Timestamp expiry bounds a whole group by its own highest frame timestamp +(inclusive), and any other group, or a hole, by the lowest frame timestamp +this hop knows in any higher group (exclusive). That bound applies whether or +not the higher group is the immediate successor. The latest group never ages. +Arrival age, the wall time since a group's successor arrived, still expires a +superseded group on its own. Rust, `@moq/net`, and the moq-lite draft's +Expiration section change together. + +## Plan + +Decided 2026-11-20 (maintainer, /quest-plan auditing the subscription rules +before the lite-07 cut): skipping is by timestamp, from a group's maximum, or +from a higher group's minimum while the group isn't whole. Arrival age stays +beside it as the backstop for a publisher whose timestamps stall, or an +abusive one that never advances them, whose stale streams would otherwise +hold connection credit other broadcasts need. ✅ Both clocks (rejected: +timestamps only). ✅ The latest group never ages by the wall clock (rejected: +[moq-dev/moq#9221](https://github.com/moq-dev/moq/pull/9221)'s aging of a +whole group with no successor from an estimated mean frame interval, and +main's `ended_at`, which ages it from GROUP_END's end). + +Today `reach` (`rs/moq-net/src/model/track.rs`) and `#reach` +(`js/net/src/track.ts`) use GROUP_END's end, else the immediate successor's +frame 0. The draft says the same ("A group's reach is its own end once it +finished ... otherwise the first frame timestamp of the next group by start"). +#9221 was asked to adopt the whole-group half (its own highest timestamp +whenever something newer measures it) and to drop the latest group's +wall-clock aging. Whatever it leaves undone is this quest's. + +- A higher group's lowest timestamp bounds a lower group only under the + strong no-overlap rule, so this waits on it. Until then moq-mux's + overlapping groups would expire early. +- Use any known frame of any higher group, a tail copy's included: under the + rule every one of them is above the lower group's frames. +- Find every other place that bounds a group or a hole by a successor's start, + such as a reader giving up a hole by the max delay, and apply the same bound. + +Public API: none expected. Wire: none; the draft's Expiration text changes, +which only lets a publisher expire sooner. + +## Required + +- [Every frame of a group presents before every frame of a higher group](/quest/m2/groups-never-overlap.md) - the rule that makes a higher group's lowest timestamp an upper bound diff --git a/quest/m3/fmp4-group-start-tfdt.md b/quest/m3/fmp4-group-start-tfdt.md index 0391772bcc..1906a2d18e 100644 --- a/quest/m3/fmp4-group-start-tfdt.md +++ b/quest/m3/fmp4-group-start-tfdt.md @@ -70,4 +70,4 @@ Public API: none. Wire: none. ## Related - [fMP4 decode times from the declared depth](/quest/m3/fmp4-declared-clock.md) - replaces how reordered video's decode times are authored; this quest's rule must hold under it too -- [A group's frames present before the next group starts](/quest/m3/groups-never-overlap.md) - an overlapping or repeating keyframe continues its group there, which may remove some cases here +- [A group's frames present before the next group starts](/quest/m2/groups-never-overlap.md) - an overlapping or repeating keyframe continues its group there, which may remove some cases here diff --git a/quest/m3/groups-never-overlap.md b/quest/m3/groups-never-overlap.md deleted file mode 100644 index f3b0312c18..0000000000 --- a/quest/m3/groups-never-overlap.md +++ /dev/null @@ -1,64 +0,0 @@ -# [M] A group's frames present before the next group starts - -## Goal - -Groups never go back in time: every frame of a group presents before the next -group's start, so a reader can bound a group's end from its own frames. -B-frames and open-GOP leading pictures stay allowed within their own group. -Sources that overlap today, such as a TS content join, publish without ending -the broadcast and without rewriting a timestamp. The hang draft, the producer, -and every importer state and keep the rule. - -## Plan - -[moq-dev/moq#4543](https://github.com/moq-dev/moq/pull/4543) replaced the -importers' live-edge floor and TS `Reanchor` shift with monotonic group starts. -With nothing shifted, a TS content join -([#3798](https://github.com/moq-dev/moq/issues/3798)) publishes an IDR below -the old content's last frame, so the draft now lets frames present below the -previous group's content (`drafts/draft-lcurley-moq-hang.md`, the malformed-group -rules), and even lets a group start at the previous group's start. -`container::Producer::prepare` opens a group for a keyframe above the open -group's start, even one below its newest frame -(`a_keyframe_overlapping_the_previous_group_publishes`). - -That overlap is why -[moq-dev/moq#8874](https://github.com/moq-dev/moq/pull/8874) cannot place an -HLS group early with certainty: when the overlap straddles a grid line, an -edge that saw the earlier group and one that joined at the overlapping group -list one segment differently. #8874 documents that case in -`rs/moq-hls/src/export/grid.rs` and `doc/bin/hls.md`; delete both notes here. - -Start by finding every source that overlaps and why: the TS content join, -other importers (fMP4, FLV, MKV, RTMP, SRT, HLS), encoders, and the JS -publisher. - -Decided 2026-11-15 (maintainer, /quest-plan): - -- ✅ Enforce the rule end to end: draft, producer, importers (rejected: - investigate only and plan the fix later; end the import at an overlapping - keyframe, which would stop a TS feed at every content join). -- ✅ A keyframe that doesn't start after the open group's newest frame continues - that group, as one at or below its start already does (rejected: shift the - broadcast forward at each join, which brings back the rewriting #4543 - removed and drifts the catalog clock; leave it to the implementer). The - group at a join then runs about two GOPs: a viewer can't join exactly there, - and HLS lists one over-long segment through its overrun path. -- ✅ Readers assume the rule and don't detect it, per AGENTS.md (rejected: - `container::Consumer` refusing an overlapping group). A publisher that - breaks it hurts only its own broadcast. Delete any reader-side overlap - handling the rule makes dead. - -The draft's "a group MAY start at the same timestamp as the previous group" -goes too: a group's start is after every frame of the group before it. - -Tests: the producer test above becomes one where the overlapping keyframe -continues the group, and a TS import across a content join publishes groups -whose frames all precede the next group's start. - -Public API: none expected. Wire: none; the draft's group rule tightens. - -## Related - -- [GROUP_END is a bare whole marker](/quest/m2/time-addressing/group-end-whole.md) - a finished group with no successor ages from its highest frame timestamp, which this rule keeps below the next start -- [An fMP4 group start never rewinds the decode timeline](/quest/m3/fmp4-group-start-tfdt.md) - a keyframe repeating its predecessor's timestamp would now continue the group; check which of its cases remain diff --git a/rs/moq-net/AGENTS.md b/rs/moq-net/AGENTS.md index af30d8aa35..1bc75940dd 100644 --- a/rs/moq-net/AGENTS.md +++ b/rs/moq-net/AGENTS.md @@ -7,10 +7,10 @@ The wire layer: generic over the transport and media-agnostic. - Closes never cascade: aborting a group leaves its track, broadcast, and siblings alone. - Never finish a stream or producer and forget it: something, such as expiry, a cancel, or the session's close, must abort it eventually, or a stale stream holds connection credit and stalls the streams behind it. - A subscription stays on the instance it started on while that instance has a route, even after a newer route wins the path. When none is left, it ends with an error, never a clean end, and never stitches onto another instance. A clean end means only a deliberate publisher finish. Apps restart on announcements, never on request errors. See "Stream instances" in `doc/concept/moq-lite.md`. -- Serve the part of a subscription the cache can prove and ask upstream for every miss, including missing frames. When the live subscription has ended, wait for the new `SUBSCRIBE_OK` before reporting a live position. Group 10 in an idle cache says only that group 10 existed. -- Forward known results as they arrive. A track listing streams tracks immediately and reports synced once upstream does. -- Frame timestamps may reorder within a group (B-frames). Every timestamp in a lower group must be at or before every timestamp in a higher group. For timestamp-based skipping, use a whole group's maximum timestamp. For an incomplete group, use the minimum known timestamp of a higher group as an upper bound. Without such a bound, its frames may still be in range. -- When switching routes for the same instance, cap the old subscription and start the new one at the same position, just past the frames held contiguously in the largest known group. Drain the old range while possible, accounting for every requested group or asking the new route for what is missing. Use in-flight frames from either copy when available and deliver each frame once on the same logical subscription. +- The live position (largest group, live edge) comes only from an open upstream subscription's answer: a copy with none open waits for the next `SUBSCRIBE_OK`, since a cached group 10 says only that group 10 existed. A partial hit, such as a group missing its first frames, still asks upstream for the rest. +- A relay never blocks an answer on other nodes finishing something; it reports what it knows now. One exception: a track listing's synced mark waits for the upstream's, while its tracks still flow live. +- Groups never overlap in time: every frame of a lower group presents before every frame of a higher one, though frames within a group may reorder (B-frames). Expire a group by timestamp, from its own highest timestamp once whole and otherwise from the lowest timestamp known in any higher group, and by wall clock, once its successor arrived longer ago than the budget, which stops a publisher whose timestamps stall. The latest group never expires. +- A route switch for the same instance looks like one subscription split at one boundary, picked at the switch: the largest group any copy holds, past the frames held contiguously in it. The new subscription starts there; the old one is capped at that group and drains what lies below within the budget. Deliver each frame once, from whichever copy brings it first. - New capabilities are additive SETUP extensions; receivers ignore unknown parameters. - A moq-transport feature with no moq-lite counterpart (e.g. FORWARD=0) gets the least code inside the IETF layer. It may keep crate-private state in the model so a moq-transport-to-moq-transport relay forwards it faithfully, but never adds public API. - Outside the crate, branch on `is_lite()` and `alpn()`. Inside, match draft enums with old drafts listed explicitly and the newest behavior as the fallthrough.