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
1 change: 1 addition & 0 deletions quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,7 @@ surface and zero-copy texture import, land before the cut.

- [Resume checked against a model](/quest/m1/resume-model-test.md) - a randomized test checks every resumed reader against a one-track reference model in Rust and JS, and passes before the cut
- [Address groups by timestamp](/quest/m1/time-addressing/README.md) - group start timestamps replace sequence numbers in the moq-net API and lite-07 wire, while old subscribers, old publishers, and published JS clients keep working
- [A group ends at its highest PTS](/quest/m1/group-end-pts.md) - a B-frame tail no longer understates a group's end, in Rust and JS
- [Release audit findings](/quest/m1/release-audit/README.md) - resolve newly identified resource, parser, playback, and interoperability risks before the cut
- [Pre-cut audit findings](/quest/m1/cut-audit/README.md) - fix the crashes, hostile-input costs, and correctness bugs the 2026-10-24 audit of main found
- [Cancelled moq-transport requests stop](/quest/m1/ietf-request-cancel.md) - a cancelled request releases its state even when the peer withholds credit
Expand Down
21 changes: 21 additions & 0 deletions quest/m1/group-end-pts.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# [XS] A group ends at its highest PTS

## Goal

A group's end in presentation time is the highest PTS among its frames, not
its newest frame's, in Rust and `@moq/net`, so a group whose decode-order tail
holds B-frames is not judged stale early.

## Plan

Rust overwrites the group's `latest` with each new frame's timestamp
(`rs/moq-net/src/model/group.rs`, `Timeline::Timed` in `stamp` and on
adoption), and so does JS (`js/net/src/group.ts`, `state.latest`). Keep the
maximum instead, and test a group written in decode order with a B-frame
last against a drift budget.

Public API: none. Wire: none.

## Related

- [Rust groups by start](/quest/m1/time-addressing/model.md) - group ends become explicit, but a group without GROUP_END still ends at its highest PTS
3 changes: 2 additions & 1 deletion quest/m1/lite07-finalize.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,8 @@ timestamp bound in [#6168](https://github.com/moq-dev/moq/pull/6168).
- [Routes and announces](/quest/m1/cluster-routing/routes.md) - lite-07 carries the route layer: ROUTE per origin node and path-less ANNOUNCE, with the hop list gone
- [Drop set](/quest/m1/drop-set.md) - lite-07's SUBSCRIBE_DROP carries `Max Age`, so a widening re-offers groups reported dropped
- [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - SUBSCRIBE carries ranges and an order and lite FETCH is gone, in Rust and JS
- [Spike: timestamps replace group sequence numbers](/quest/m1/time-addressing/spike.md) - decides the lite-07 wire without group sequence numbers and adds the implementation quests here
- [Lite-07 by start](/quest/m1/time-addressing/lite07.md) - lite-07 carries group starts, previous-start links, GROUP_END, and time bounds instead of sequence numbers
- [@moq/net by start](/quest/m1/time-addressing/js.md) - JS speaks the same lite-07 wire
- [Announcement takeover](/quest/m1/announce-takeover.md) - ANNOUNCE_TAKEOVER preserves a proven instance under a new independent route

## Related
Expand Down
2 changes: 1 addition & 1 deletion quest/m1/subscribe-ranges/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,4 +131,4 @@ generations of "start". When ranges land:
## Related

- [IETF fill timeout](/quest/m1/ietf-fill-timeout.md) - bounds upstream waiting independently of content age
- [Timestamp spike](/quest/m1/time-addressing/spike.md) - the cut reworks `Absolute(group)` ends and sequence-range drops onto times
- [Rust groups by start](/quest/m1/time-addressing/model.md) - the cut reworks `Absolute(group)` ends and sequence-range drops onto times
8 changes: 7 additions & 1 deletion quest/m1/time-addressing/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,5 +11,11 @@ compatibility.

## Required

- [Spike](/quest/m1/time-addressing/spike.md) - a Rust and JS prototype measures what breaks, and the spike writes the design and the implementation quests for the cut
- [Rust groups by start](/quest/m1/time-addressing/model.md) - the moq-net model and API address groups by start, and legacy wires carry the start ticks as the group ID
- [Lite-07 by start](/quest/m1/time-addressing/lite07.md) - lite-07 carries starts, previous-start links, GROUP_END, and time bounds instead of sequence numbers
- [moq-transport starts and ends](/quest/m1/time-addressing/ietf.md) - Prior Group ID Gap and TIMESTAMP carry links and PTS, END_OF_GROUP marks a whole group, and the end time needs an extension
- [@moq/net by start](/quest/m1/time-addressing/js.md) - JS matches Rust's model, wire, and legacy mapping
- [Consumers by start](/quest/m1/time-addressing/consumers.md) - hang drops duration and discontinuity markers, and every consumer that numbered groups uses starts
- [Bindings by start](/quest/m1/time-addressing/bindings.md) - moq-ffi, moq-c, and every binding expose starts, with migration docs
- [E2EE nonce](/quest/m1/time-addressing/e2ee.md) - the nonce binds the start instead of the sequence
- [Guide](/quest/m1/time-addressing/guide.md) - a page explaining seek by time, group ends, restarts, strictly increasing starts, and how legacy peers see group IDs
21 changes: 21 additions & 0 deletions quest/m1/time-addressing/bindings.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# [M] Bindings address groups by start

## Goal

moq-ffi, `moq-c`, and every language binding expose groups by start
timestamp instead of sequence number, including `seek` for GOP-aligned
failover, with each `doc/lib` page and `MIGRATE.md` saying how to migrate.

## Plan

Follow the cross-package sync table from `rs/moq-ffi` outward. Timestamps
already cross the bindings as `{value, scale}`
([exact timestamps](/quest/m1/binding-timestamps.md)), so a start reuses that
type.

Public API: breaking in every binding. Wire: none.

## Required

- [Rust groups by start](/quest/m1/time-addressing/model.md) - the API these wrap
- [Exact timestamps in every binding](/quest/m1/binding-timestamps.md) - the timestamp type a start uses
36 changes: 36 additions & 0 deletions quest/m1/time-addressing/consumers.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# [L] Media consumers address groups by start

## Goal

Every first-party consumer that numbered groups works by start timestamp,
in Rust and JS, and hang stops writing duration and discontinuity markers
that group ends and gaps now carry.

## Plan

Decided 2026-10-25 (maintainer), from the spike:

- GROUP_END replaces hang's empty-frame duration marker
(`rs/moq-mux/src/container/producer.rs:523`), so moq-mux stops writing
empty frames.
- Discontinuity marker groups go away (`producer.rs:650`): a gap is a
previous end below the next start, and a missing group is a
previous-start link that doesn't match.
- Legacy egress synthesizes neither: old players lose end durations and
pause markers, which they already tolerate being absent.

Convert each consumer that numbers groups: hang and moq-mux timelines,
HLS/DASH export, `seek` for GOP-aligned failover in moq-mux, HLS import's
discontinuity packing, transcode's 1:1 numbering, archive keys and resume,
relay and CLI `fetch --group`, and player continuity checks in the Rust and
JS container consumers and `js/watch`. Update the hang draft and the docs
each one makes stale; rename CLI flags per the repo's CLI rule.

Public API: breaking where a consumer exposes group numbers (CLI
`--group`, archive keys). Wire: hang drops empty duration frames and
discontinuity marker groups.

## Required

- [Rust groups by start](/quest/m1/time-addressing/model.md) - the Rust API these consume
- [@moq/net by start](/quest/m1/time-addressing/js.md) - the JS API these consume
19 changes: 19 additions & 0 deletions quest/m1/time-addressing/e2ee.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# [S] The E2EE nonce binds the group start

## Goal

The E2EE nonce binds a group's start timestamp instead of its sequence
number, in the draft and every implementation, so encrypted groups survive
the cut.

## Plan

Update `drafts/draft-lcurley-moq-e2ee.md` and `rs/moq-e2ee`, plus the JS
side if it has landed. The start is unique per track because starts strictly
increase. Run `just drafts check`.

Public API: none. Wire: the E2EE nonce input changes.

## Required

- [Rust groups by start](/quest/m1/time-addressing/model.md) - the start the nonce binds
7 changes: 5 additions & 2 deletions quest/m1/time-addressing/guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,14 @@ authors can follow it without reading the drafts.
## Plan

Decided 2026-10-25 (maintainer): a separate page, not only inline doc
updates. Write it against the design the spike records. Link it from
updates. Write it against the design [the model](/quest/m1/time-addressing/model.md)
and [lite-07](/quest/m1/time-addressing/lite07.md) quests record, including
that a released relay fills a hole with one FETCH per ID, so a mixed-version
deployment upgrades its relays together. Link it from
`doc/concept/moq-lite.md` and from the
[Identity and recovery guide](/quest/m1/identity-guide.md), which covers
epochs and restarts.

## Required

- [Spike](/quest/m1/time-addressing/spike.md) - the design this page describes
- [Lite-07 by start](/quest/m1/time-addressing/lite07.md) - the wire this page describes
40 changes: 40 additions & 0 deletions quest/m1/time-addressing/ietf.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# [M] moq-transport carries group starts and ends

## Goal

A moq-transport peer that understands the MOQ Properties sees each group's
predecessor link, each object's PTS, and each group's end, and moq-net reads
them back on ingest. A peer without them still plays live; only end
precision and gap detection degrade.

## Plan

Decided 2026-10-25 (maintainer), from the spike:

- The Group ID is the start ticks ([the model](/quest/m1/time-addressing/model.md)
owns that mapping). The previous-start link rides in the Prior Group ID Gap
property.
- Object IDs stay +1 per frame, so no Prior Object ID Gap is sent. Each
object's PTS rides in TIMESTAMP (0x10), with TIMESCALE (0x08) on the track,
the MOQ Properties shared with draft-ietf-moq-loc, so it stays LOC
compatible.
- GROUP_END maps to END_OF_GROUP. Only draft-14 lets a status object carry
properties, so only there does it carry the end in its TIMESTAMP; later
drafts refuse them (`check_status` in `rs/moq-net/src/ietf/object.rs`), so
their END_OF_GROUP stays bare and the end needs a negotiated extension or
is lost, as the extension rule below allows.
- Rejected: Object ID as a PTS delta, because B-frames run backwards in
decode order and open-GOP leading frames present before the group's start.
- The properties are optional on both sides: moq-transport may carry them as
properties or a negotiated extension, and a peer sending none still works
for live playback.

Test both directions over drafts 18 and 22, with and without the properties.

Public API: none. Wire: moq-transport Prior Group ID Gap and TIMESTAMP are
sent and read, END_OF_GROUP marks a whole group, and the end time rides a
negotiated extension if one is defined.

## Required

- [Rust groups by start](/quest/m1/time-addressing/model.md) - the model whose links and ends these carry
26 changes: 26 additions & 0 deletions quest/m1/time-addressing/js.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# [L] @moq/net addresses groups by start

## Goal

`@moq/net` matches Rust: groups are addressed by start timestamp in its API,
model, lite-07 wire, and legacy mapping, with the same names.

## Plan

Mirror [the model](/quest/m1/time-addressing/model.md) and
[the lite-07 wire](/quest/m1/time-addressing/lite07.md), including strictly
increasing starts, the three group ends, reach from a group's own end, and
`Relative(n)` counting groups. The gap machinery that assumes `sequence + 1`
(`delivered.ts`, `ledger.ts`, `track.ts`, `resume.ts`) follows
previous-start links instead. Starts stay JavaScript numbers, so a decoded
start past 2^53 is refused as today's group IDs are.

The spike found no sparse-ID breakage in direct `@moq/net` sessions over
lite-06 and lite-07; its relay fills follow Rust's once
[JS ranges](/quest/m1/subscribe-ranges/js.md) land.

Public API: breaking, mirroring Rust's. Wire: as the lite-07 quest.

## Required

- [Lite-07 by start](/quest/m1/time-addressing/lite07.md) - the wire this speaks
39 changes: 39 additions & 0 deletions quest/m1/time-addressing/lite07.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# [M] The lite-07 wire addresses groups by start

## Goal

moq-lite-07 carries no group sequence numbers: a GROUP names its start and
its predecessor's start, GROUP_END says where a whole group ends, and every
subscription bound, drop, and datagram is a time. Rust speaks it, the lite
draft specifies it, and lite-01..06 are unchanged.

## Plan

Decided 2026-10-25 (maintainer), from the spike:

- **GROUP** carries the start and the previous group's start, absent for the
first group of an epoch, so a cache or reader sees a hole without a round
trip.
- **GROUP_END** carries the group's exclusive end timestamp, meaning the
group is whole. A bare FIN means an incomplete group whose frames all
arrived, and a reset aborts. A relay closes an expired or partial group
instead of resetting it, which changes the draft's reset rule for those
groups (around line 760).
- SUBSCRIBE and SUBSCRIBE_UPDATE bounds, SUBSCRIBE_START and its largest,
SUBSCRIBE_END, SUBSCRIBE_DROP, and datagrams address by start. Drops name
time spans with no group to deliver, not sequence ranges. `Relative(n)`
stays a group count.
- Positions stay (start, frame index), so
[frame offsets](/quest/m1/transport-frame-offsets.md) carry over.

Update `drafts/draft-lcurley-moq-lite.md` (fields, the group-end rules, and the
lite-07 changelog) and `doc/concept/moq-lite.md`, and run `just drafts check`
and `just test interop --all`.

Public API: none beyond [the model](/quest/m1/time-addressing/model.md).
Wire: lite-07-wip GROUP, GROUP_END, SUBSCRIBE, SUBSCRIBE_UPDATE,
SUBSCRIBE_START, SUBSCRIBE_END, SUBSCRIBE_DROP, and datagrams change.

## Required

- [Rust groups by start](/quest/m1/time-addressing/model.md) - the model this wire carries
116 changes: 116 additions & 0 deletions quest/m1/time-addressing/model.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,116 @@
# [XL] Rust groups are addressed by their start

## Goal

In `rs/moq-net`, a group's identity is its start timestamp: the API and the
model carry no group sequence numbers, a reader seeks or starts from a time,
and no producer remembers group numbers. Lite-01..06 and moq-transport peers
keep working through a group ID equal to the start in the track's timescale,
and lite-07-wip carries that same value until
[the lite-07 wire](/quest/m1/time-addressing/lite07.md) replaces it.

## Plan

Decided 2026-10-25 (maintainer). Why: group numbers need timelines just to
map to and from time, and reusing a group number poisons caches, so resuming
a producer would need per-track memory of its last number.

- **A group's address is its first frame's PTS**, known when the group opens.
Frames inside a group stay in decode order and their PTS may go backwards
(B-frames).
- **Starts strictly increase.** An equal start is refused loudly like a
rewind; `Neighbors::admit` (`model/track.rs:491`) allows ties today.
- **Three ways a group ends**: `finish(end)` with an exclusive end timestamp
(the group is whole), `close()` (incomplete, but every frame written
arrives), and `abort(err)` (reset). A relay closes an expired or partial
group instead of resetting it.
- **Reach** (decided 2026-10-26, maintainer): a finished group's own end
bounds it, else its successor's start, so the last group of a paused or
finished track ages out without a successor (`TrackState::reach`).
- **Every track is timed.** Untimed goes away: the producer stamps an untimed
write with wall-clock time in microseconds, which stays under 2^53 (the
published JS decode limit, below) until the year 2255.
- **Gaps.** The model keeps each group's previous start, so a cache or reader
sees a hole without a round trip. The first group of an epoch has none, and
the gap before it is unknown. Restarts keep minting a new epoch with fresh
PTS; replicas in one epoch agree by PTS without coordinating numbers.
- **Legacy egress.** The group ID on lite-01..06 and moq-transport is the
start in the track's timescale, so every relay agrees without a table.
Published `@moq/net` decodes a group ID with `u53` and refuses one past
2^53 (`js/net/src/lite/group.ts`), so a track whose starts pass that, such
as nanosecond epoch time, fails those readers.
- **Legacy ingest.** A timed source keeps its timestamps. An untimed source
(moq-transport without TIMESCALE, lite-01..04) uses the group ID as the
timestamp on a synthetic scale, so relays agree and legacy egress
round-trips the exact ID; max age means nothing on those tracks. A timed
moq-transport group that starts at or before its predecessor ends the
track with an error.
- **Ranges.** `Absolute(group)` ends and sequence-range drops become times.
`Relative(n)` stays but counts groups instead of subtracting from an ID.
- **Name reuse** landed in
[moq-dev/moq#6780](https://github.com/moq-dev/moq/pull/6780); the cut
removes its sequence half, leaving a re-created track to keep its PTS
moving forward.
- **Old relays** (decided 2026-10-26, maintainer): a released relay fills a
hole over lite-05/06 with one FETCH per integer ID, so sparse IDs cost it
one FETCH per tick in the hole. Accepted: "This was a lingering problem.
The entire point of (multiple) ranges is to avoid this issue."

Every current role of the sequence needs a replacement or a reason to drop
it:

- The cache key, the duplicate check, the hand-out-once record
(`delivered.rs`), and slot stamps.
- Successor, reach, expiry, the arrival ledger, tail accounting, fills and
misses, and SUBSCRIBE_DROP accounting. Successor and reach already scan the
cache by range, so they tolerate sparse keys; `delivered.rs` runs, fills,
misses, and `subscription/window.rs` treat `sequence + 1` as the next group
and must follow previous-start links instead.
- Resume across route flips (`resume.rs`), mid-group `Position` and
`frame_start`, priority order within a subscription, `Demand::wanted`, and
refresh.
- The datagram namespace, which shares the group space.
- The legacy codecs: lite GROUP, SUBSCRIBE and SUBSCRIBE_UPDATE bounds,
SUBSCRIBE_START and its largest, SUBSCRIBE_END, SUBSCRIBE_DROP, FETCH, and
every IETF Location, Filter, FETCH, Largest, and NEW_GROUP_REQUEST.

### Spike evidence

The spike published groups at their start ticks (2 s GOPs at 1 kHz and at
90 kHz) over lite-03, lite-06, lite-07-wip, moq-transport-14, and
moq-transport-18, direct and through a relay, against a contiguous baseline
(prototype tests in
[moq-dev/moq@ebdfd55](https://github.com/moq-dev/moq/commit/ebdfd55fc606db8f2c990b937392b81291ab4715)).

- Unaffected on `main`: live delivery through `recv_group` and `ordered()`,
history with `Range::oldest` and absolute ranges, max-age expiry, a fetch
of a missing ID (prompt `NotFound`), and hole fills, which take a constant
handful of FETCHes at any spacing since
[moq-dev/moq#6724](https://github.com/moq-dev/moq/pull/6724) and
[moq-dev/moq#6715](https://github.com/moq-dev/moq/pull/6715). Before them
a relay opened one FETCH per ID (540,000 for one 90 kHz hole), which is
what released relays still do. `@moq/net` matched on lite-06 and lite-07.
- Broken: `Relative(1)..` on lite-07, direct or relayed, resolves by ID
arithmetic, delivering `[6000]` and then parking instead of
`[4000, 6000]`.

Update `doc/concept`, the lite draft's legacy mapping, `MIGRATE.md`, and the
Rust half of every consumer the API change breaks to compile;
[consumers](/quest/m1/time-addressing/consumers.md) and
[bindings](/quest/m1/time-addressing/bindings.md) own the behavior changes.
Test the legacy mapping both ways on every wire, with the
[resume model](/quest/m1/resume-model-test.md) as the oracle for resume.

Public API: breaking. `group::Info`, `create_group`, `append_group`,
`Position`, `Range` ends, `fetch_group`, `Subscriber::floor`, datagrams, and
group consumers address by start timestamp, and untimed tracks go away.
Wire: no format change; legacy and lite-07-wip group IDs become start ticks.

## Required

- [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - the range ends and drops this rework moves onto times
- [Lite-05/06 timestamps pass through](/quest/m1/lite-timestamps-through.md) - lite-05/06 tracks stay timed, so their ingest keeps real starts

## Related

- [Resume checked against a model](/quest/m1/resume-model-test.md) - its reference model is the oracle for resume after the cut
Loading
Loading