@norskvideo/moq-net 0.1.8 → 0.2.0

package/track.js

@@ -5,43 +5,70 @@
  * @module
  */
 import { Once, Signal } from "@norskvideo/moq-signals";
-import { Producer as GroupProducer, Lagged } from "./group.js";
-import { hooks } from "./internal.js";
-import { Timescale } from "./time.js";
-/** Default {@link Info.latencyMax} window (milliseconds) when the publisher does not set one. */
-export const DEFAULT_LATENCY_MAX_MS = 5000;
-/**
- * How long (milliseconds) a datagram stays in the per-subscriber buffer before it is dropped.
- *
- * Datagrams are a best-effort send buffer, not a replay cache (unlike groups): only the last few
- * tens of milliseconds are kept, so a consumer that stalls loses stale datagrams instead of
- * replaying them. Mirrors the Rust `MAX_DATAGRAM_AGE`.
- */
-const MAX_DATAGRAM_AGE_MS = 50;
+import { GroupTooLarge, TooFarBehind } from "./error.js";
+import { Producer as GroupProducer } from "./group.js";
+import { groupBounds, hooks, } from "./internal.js";
+import { Milli, Timescale } from "./time.js";
+import { registerTrackConsumer } from "./wire.js";
+// The largest delay setTimeout keeps: anything more truncates to a signed 32-bit int
+// and fires right away.
+const MAX_TIMEOUT_MS = 2 ** 31 - 1;
+// The cache scans at most this many times per retention window.
+const PRUNE_SLICES = 8;
+/** Default {@link Info.maxAge} window (milliseconds) when the publisher does not set one. */
+export const DEFAULT_MAX_AGE_MS = Milli(5000);
+// The higher-first midpoint. IETF flips priority (lower first), so this goes out as 128, the
+// draft's usual publisher priority, while moq-lite carries 127 as written: one urgency on both.
+const DEFAULT_PRIORITY = 127;
+/** Maximum buffered datagrams per subscriber; mirrors Rust's bounded send buffer. */
+const MAX_DATAGRAMS = 64;
 /**
  * Sanity cap on a datagram payload: the QUIC DATAGRAM frame ceiling. The real limit is
  * per-hop (the negotiated transport datagram size minus a small header) and oversize
  * datagrams are dropped there; a payload above this cap could never fit anywhere.
  */
 const MAX_DATAGRAM_BYTES = 65535;
+// Normalize a latency budget for the wire, which carries it as an unsigned varint.
+//
+// Callers derive it from measurements (a jitter estimate scaled off RTT), so a fractional
+// millisecond is expected; ceil rather than round, because a budget shortened by rounding
+// skips a group the subscriber still wants. Anything that is not a duration is refused
+// here, where the field is named, rather than deep in the encoder.
+function maxAgeMillis(value) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new RangeError(`maxAge must be a non-negative number of milliseconds: ${value}`);
+    }
+    const millis = Math.ceil(value);
+    if (!Number.isSafeInteger(millis)) {
+        throw new RangeError(`maxAge exceeds the safe integer millisecond range: ${value}`);
+    }
+    return Milli(millis);
+}
+function priorityByte(value) {
+    if (!Number.isInteger(value) || value < 0 || value > 255) {
+        throw new RangeError(`priority must be an integer in 0..=255: ${value}`);
+    }
+    return value;
+}
 /** Fill in any unset {@link Info} fields with their defaults. */
 export function infoDefaults(info = {}) {
     return {
-        timescale: info.timescale ?? Timescale.MILLI,
-        latencyMax: info.latencyMax ?? DEFAULT_LATENCY_MAX_MS,
-        priority: info.priority ?? 0,
-        ordered: info.ordered ?? false,
+        timescale: Timescale(info.timescale ?? Timescale.MILLI),
+        maxAge: maxAgeMillis(info.maxAge ?? DEFAULT_MAX_AGE_MS),
+        priority: priorityByte(info.priority ?? DEFAULT_PRIORITY),
     };
 }
 // Materialize the defaults at the model boundary so every layer observes a complete
 // subscription rather than interpreting an omitted field differently.
 function subscriptionDefaults(subscription = {}) {
+    const bounds = groupBounds(subscription.groups ?? {});
     return {
-        priority: subscription.priority ?? 0,
-        ordered: subscription.ordered ?? false,
-        latencyMax: subscription.latencyMax ?? 0,
-        startGroup: subscription.startGroup,
-        endGroup: subscription.endGroup,
+        priority: priorityByte(subscription.priority ?? 0),
+        maxAge: maxAgeMillis(subscription.maxAge ?? Milli.zero),
+        groups: {
+            start: subscription.groups?.start === undefined ? undefined : { included: bounds.start },
+            end: bounds.end === undefined ? undefined : { excluded: bounds.end },
+        },
     };
 }
 // Aggregate the preferences of every live subscriber, matching Rust's Subscription::poll_combined.
@@ -56,25 +83,22 @@ function combineSubscriptions(states) {
             continue;
         }
         combined.priority = Math.max(combined.priority ?? 0, subscription.priority ?? 0);
-        combined.ordered = (combined.ordered ?? false) && (subscription.ordered ?? false);
-        combined.latencyMax = Math.max(combined.latencyMax ?? 0, subscription.latencyMax ?? 0);
-        if (subscription.startGroup !== undefined) {
-            combined.startGroup =
-                combined.startGroup === undefined
-                    ? subscription.startGroup
-                    : Math.min(combined.startGroup, subscription.startGroup);
-        }
-        if (combined.endGroup === undefined || subscription.endGroup === undefined) {
-            combined.endGroup = undefined;
-        }
-        else {
-            combined.endGroup = Math.max(combined.endGroup, subscription.endGroup);
-        }
+        combined.maxAge = Milli(Math.max(combined.maxAge ?? Milli.zero, subscription.maxAge ?? Milli.zero));
+        // A floor only restricts, so a subscriber without one clears the aggregate:
+        // its budget may reach below any floor the others set.
+        const a = groupBounds(combined.groups ?? {});
+        const b = groupBounds(subscription.groups ?? {});
+        combined.groups = {
+            start: combined.groups?.start === undefined || subscription.groups?.start === undefined
+                ? undefined
+                : { included: Math.min(a.start, b.start) },
+            end: a.end === undefined || b.end === undefined ? undefined : { excluded: Math.max(a.end, b.end) },
+        };
     }
     return combined;
 }
 /**
- * A request for a track the peer wants, yielded by `Broadcast.Producer.requested`.
+ * A request for a track the peer wants, delivered to the publishing wire layer.
  *
  * Created internally by the broadcast when a subscription (or info lookup) needs a track
  * served; answer it with {@link accept} or {@link reject}.
@@ -86,13 +110,17 @@ export class Request {
     name;
     #producer;
     #sequences;
+    #pending;
     constructor(options) {
         this.name = options.name;
         this.#producer = options.producer;
         this.#sequences = options.sequences;
+        this.#pending = options.pending;
+        this.#pending.add(this);
     }
     static {
         hooks.makeRequest = (options) => new Request(options);
+        hooks.pendingTrackProducer = (request) => request.#producer;
     }
     /** The aggregate subscription requested for this track. */
     get subscription() {
@@ -104,11 +132,13 @@ export class Request {
     }
     /** Accept the request, committing the track's immutable {@link Info}. */
     accept(info = {}) {
+        this.#pending.delete(this);
         bindProducer(this.name, this.#producer, this.#sequences);
         return this.#producer.accept(info);
     }
     /** Reject the request, closing the track optionally with an error. */
     reject(err) {
+        this.#pending.delete(this);
         this.#producer.close(err);
     }
 }
@@ -125,7 +155,17 @@ export class Consumer {
         this.name = name;
         this.#broadcast = broadcast;
     }
-    /** Open a live subscription to the track. */
+    static {
+        registerTrackConsumer((name, broadcast) => new Consumer(name, broadcast));
+    }
+    /**
+     * Open a live subscription to the track.
+     *
+     * The cursor starts at the group the subscription named (its floor), or 0.
+     * {@link Subscription.maxAge} is what asks for data: delivery skips everything above
+     * the floor that the budget convicts, so the default budget of zero delivers only the
+     * latest group and a larger one reaches back over what it can still use.
+     */
     subscribe(options) {
         return this.#broadcast.subscribe(this.name, options);
     }
@@ -138,15 +178,57 @@ export class Consumer {
         return this.#broadcast.fetchGroup(this.name, sequence, options);
     }
 }
+// The index of the first timeline group at or after `sequence`.
+function timelineIndex(timeline, sequence) {
+    let lo = 0;
+    let hi = timeline.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (timeline[mid].sequence < sequence)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+// Add a group to a sorted timeline, replacing any group with the same sequence. Groups
+// usually arrive in order, so the append is checked first.
+function timelineInsert(timeline, group) {
+    const last = timeline.at(-1);
+    if (!last || last.sequence < group.sequence) {
+        timeline.push(group);
+        return;
+    }
+    const index = timelineIndex(timeline, group.sequence);
+    if (timeline[index]?.sequence === group.sequence)
+        timeline[index] = group;
+    else
+        timeline.splice(index, 0, group);
+}
 // The shared state behind a Producer / Subscriber pair. Package-internal
 // wiring, unexported so it never appears in the published type declarations.
 class TrackState {
     /** The producer fanning into this sink, so a subscriber can mint a sibling of itself. */
     producer;
     groups = new Signal([]);
-    /** Best-effort datagram channel, parallel to {@link groups}; an age-evicted send buffer per subscriber. */
+    // Every group still in the producer's replay cache, including groups this
+    // subscriber already consumed, sorted by sequence. Drift anchors have the same
+    // lifetime as content. Sorted so the latency guard, evaluated per group and per
+    // arrival, searches it instead of scanning the whole retained window.
+    timeline = [];
+    // First timestamps mutate group state rather than track state, so held groups
+    // watch this revision as well as arrivals when enforcing latency after handoff.
+    timelineChanged = new Signal(0);
+    /** Best-effort datagram channel, parallel to {@link groups}; a bounded send buffer per subscriber. */
     datagrams = new Signal([]);
     latest;
+    /**
+     * The exclusive final boundary, declared by {@link Producer.finishAt} or stamped by a
+     * clean close as one past the highest sequence produced. Groups and datagrams share the
+     * namespace, so this can exceed `latest + 1` (which only tracks groups). Mirrors the
+     * Rust `final_sequence`.
+     */
+    final = new Signal(undefined);
     closed = new Once();
     update;
     /** Resolved once the producer commits the immutable properties. */
@@ -190,6 +272,11 @@ function bindProducer(name, producer, sequences) {
     bindProducerSequence(producer, shared);
 }
 let bindProducerSequence;
+// The sequence-order cursor lives inside `Subscriber` (it shares the group buffer and the
+// drift anchor with the arrival cursor), so `Ordered` reaches it through this bridge,
+// assigned in the class's static block.
+let makeOrdered;
+let ordered_;
 // Constructs a Subscriber from within this module without exposing a public
 // constructor that would leak the unexported TrackState. Assigned in the class's
 // static block.
@@ -201,7 +288,7 @@ let makeSubscriber;
  * subscription the publisher serves from it) gets an independent
  * {@link Subscriber} that receives a full copy of the groups, each with its own
  * read cursor. Groups are mirrored into every live subscriber and retained for the
- * track's `latencyMax` window so a late subscriber replays the recent groups.
+ * track's `maxAge` window so a late subscriber replays the recent groups.
  *
  * Obtained from {@link Request.accept} (the wire asks the application for a track to
  * serve) or constructed directly for an in-process track.
@@ -213,11 +300,24 @@ export class Producer {
     // read mirrored sinks, never this state directly.
     #state = new TrackState();
     #sequence = { next: 0 };
+    // One past the highest group or datagram this producer received, like the Rust
+    // `max_sequence`. The shared counter above can run ahead of it: sibling producers of
+    // the same track advance it too.
+    #received = 0;
     // Recently written source groups, retained for replay to late subscribers and
-    // pruned once closed and older than the cache window. Each entry tracks the mirror
+    // pruned once idle for longer than the cache window. Each entry tracks the mirror
     // it handed to every sink so eviction can drop them too: otherwise a slow consumer
     // that never reads would pin old groups (and their frame bytes) forever.
     #cache = [];
+    // The same entries by sequence, so a write finds a duplicate without a scan.
+    #cached = new Map();
+    // When the cache was last scanned. See #prune.
+    #pruned = Number.NEGATIVE_INFINITY;
+    // Wakeup for the next entry due to age out. Writes settle retention inline, but a
+    // publisher that stalls stops writing, so without this an abandoned group (and any
+    // reader parked in it) would wait for a write that never comes.
+    #pruneTimer;
+    #pruneTimerAt = 0;
     // One independent downstream state per live subscriber.
     #sinks = new Set();
     // Whether any subscriber is currently attached. Exposed as {@link used}; the consumer wire
@@ -238,6 +338,15 @@ export class Producer {
     info() {
         return resolveInfo(this.#state);
     }
+    /**
+     * Publisher priority from the committed {@link Info}, or the default before {@link accept}.
+     *
+     * Higher is served first. Hang publishers set this from `Catalog.PRIORITY` so
+     * audio outranks video on the wire and in the bandwidth allocator.
+     */
+    get priority() {
+        return this.#state.info.peek()?.priority ?? DEFAULT_PRIORITY;
+    }
     /**
      * Settles once the track closes: `null` on a clean close, or the abort {@link Error}.
      * Peek it synchronously (`undefined` while open), observe it reactively, or `await` it.
@@ -254,14 +363,24 @@ export class Producer {
     }
     /** Commit the immutable publisher properties, resolving {@link info}. Returns `this`. */
     accept(info = {}) {
+        if (this.#state.closed.peek() !== undefined)
+            return this;
         const resolved = infoDefaults(info);
         this.#state.info.set(resolved);
         // Propagate to any sink handed out before accept (the on-demand path).
         for (const sink of this.#sinks)
             sink.info.set(resolved);
+        this.#updateSubscription();
         return this;
     }
-    /** An independent {@link Subscriber} receiving a full copy of this track's groups. */
+    /**
+     * An independent {@link Subscriber} reading this track's groups.
+     *
+     * Its cursor starts at the group the subscription named (its floor), or 0.
+     * {@link Subscription.maxAge} is what asks for data: delivery skips everything above
+     * the floor that the budget convicts, so the default budget of zero delivers only the
+     * latest group and a larger one reaches back over what it can still use.
+     */
     subscribe(options = {}) {
         const sink = new TrackState(options);
         this.#addSink(sink);
@@ -310,6 +429,15 @@ export class Producer {
                 forward();
                 this.#sinks.delete(sink);
                 this.#updateSubscription();
+                // Update demand: once the last subscriber leaves, the consumer wire (watching
+                // {@link unused}) tears the upstream down instead of downloading to nobody.
+                this.#used.set(this.#sinks.size > 0);
+                // The producer closing every sink keeps its mirrors tracked, so what the sink
+                // still buffers ages out with the cache instead of staying pinned.
+                if (this.#state.closed.peek() !== undefined) {
+                    dispose();
+                    return;
+                }
                 for (const entry of this.#cache) {
                     const mirror = entry.mirrors.get(sink);
                     if (mirror) {
@@ -320,21 +448,23 @@ export class Producer {
                 for (const group of sink.groups.peek())
                     group.close(abort);
                 dispose();
-                // Update demand: once the last subscriber leaves, the consumer wire (watching
-                // {@link unused}) tears the upstream down instead of downloading to nobody.
-                this.#used.set(this.#sinks.size > 0);
             });
         }
         this.#prune();
         for (const entry of this.#cache)
             this.#mirror(entry, sink);
+        sink.final.set(this.#state.final.peek());
         if (closed !== undefined)
             closeTrackState(sink, closed instanceof Error ? closed : undefined);
     }
     // Recompute from every live sink because an update or close can narrow as well as widen
     // the aggregate. The wire layer observes this signal and emits SUBSCRIBE_UPDATE.
     #updateSubscription() {
-        this.#state.update.set(combineSubscriptions(this.#sinks));
+        const combined = combineSubscriptions(this.#sinks);
+        const retained = this.#state.info.peek()?.maxAge;
+        if (combined && retained !== undefined)
+            combined.maxAge = Milli.min(combined.maxAge ?? Milli.zero, retained);
+        this.#state.update.set(combined);
     }
     // Mirror a cached source group into a sink. The mirror fills synchronously as the
     // source is written and keeps its own read cursor; frame bytes are shared by
@@ -342,6 +472,8 @@ export class Producer {
     #mirror(entry, sink) {
         const dst = entry.group.mirror();
         entry.mirrors.set(sink, dst);
+        timelineInsert(sink.timeline, dst);
+        void dst.readable().then(() => sink.timelineChanged.update((revision) => revision + 1));
         sink.latest = Math.max(sink.latest ?? 0, dst.sequence);
         sink.groups.mutate((groups) => {
             groups.push(dst);
@@ -350,43 +482,135 @@ export class Producer {
     }
     // Drop a cached group's mirror from every sink so no consumer can pin it.
     #evict(entry) {
+        // Reclaiming a group the publisher never closed ends it as the gap it is, before
+        // the mirrors below would otherwise report a clean finish to a reader that had
+        // drained it. The usual case, an already-closed group aging out, keeps its own
+        // terminal state.
+        if (!entry.group.isClosed)
+            entry.group.close(new TooFarBehind());
+        const mirrors = [...entry.mirrors.values()];
+        for (const mirror of mirrors)
+            hooks.evictGroup(mirror);
+        this.#unlink(entry);
+        for (const mirror of mirrors)
+            mirror.close();
+    }
+    // Take a cached group's mirrors out of every sink, so a subscriber can no longer
+    // receive them. A reader already holding one keeps it as is.
+    #unlink(entry) {
         for (const [sink, mirror] of entry.mirrors) {
             sink.groups.mutate((groups) => {
                 const i = groups.indexOf(mirror);
                 if (i >= 0)
                     groups.splice(i, 1);
             });
-            mirror.close();
+            const index = timelineIndex(sink.timeline, mirror.sequence);
+            if (sink.timeline[index] === mirror)
+                sink.timeline.splice(index, 1);
         }
         entry.mirrors.clear();
     }
-    // Evict cached groups that are closed and older than the cache window.
+    // Take a cached group out of the cache lookups.
+    #uncache(entry) {
+        this.#cache.splice(this.#cache.indexOf(entry), 1);
+        this.#cached.delete(entry.group.sequence);
+    }
+    // The one group retention never takes: the newest, while it is still open. That is
+    // the live edge a publisher is appending to, and a track may legitimately keep it
+    // open across a long quiet stretch (a catalog snapshot, a JSON stream). Every other
+    // open group is an abandoned one, and ages out like a closed one.
+    #liveEdge() {
+        const latest = this.#cache.at(-1)?.group;
+        return latest?.closed.peek() === undefined ? latest : undefined;
+    }
+    // Evict cached groups idle for longer than the cache window. Idle means nothing
+    // written, so an abandoned open group ages out instead of pinning its buffer (and
+    // any reader parked in it) forever.
+    //
+    // Scans at most once per slice of the window, so a track publishing faster than that
+    // evicts a run of groups per scan instead of scanning everything to evict one per
+    // write. A group can outlive the window by up to one slice.
     #prune() {
-        const latencyMaxMs = this.#state.info.peek()?.latencyMax ?? DEFAULT_LATENCY_MAX_MS;
-        const cutoff = Date.now() - latencyMaxMs;
+        const maxAgeMs = this.#state.info.peek()?.maxAge ?? DEFAULT_MAX_AGE_MS;
+        const now = performance.now();
+        const slice = maxAgeMs / PRUNE_SLICES;
+        if (now < this.#pruned + slice) {
+            // Something may have come due since the last scan, so make sure another follows.
+            this.#wake(this.#pruned + slice);
+            return;
+        }
+        this.#pruned = now;
+        const cutoff = now - maxAgeMs;
+        const live = this.#liveEdge();
+        let oldest;
         const retained = [];
         for (const entry of this.#cache) {
-            if (entry.time > cutoff || entry.group.closed.peek() === undefined) {
+            if (entry.group === live) {
                 retained.push(entry);
-                continue;
             }
-            this.#evict(entry);
+            else if (entry.group.activity >= cutoff) {
+                retained.push(entry);
+                if (oldest === undefined || entry.group.activity < oldest)
+                    oldest = entry.group.activity;
+            }
+            else {
+                this.#cached.delete(entry.group.sequence);
+                this.#evict(entry);
+            }
         }
         this.#cache = retained;
+        // Replace the wakeup with one for the next entry due to age out. Writes settle
+        // retention inline, so this only has to cover the case no write follows. Cheap to
+        // over-arm: an entry written since is retained and re-armed.
+        clearTimeout(this.#pruneTimer);
+        this.#pruneTimer = undefined;
+        if (oldest !== undefined)
+            this.#wake(Math.max(oldest + maxAgeMs, now + slice));
+    }
+    // Arm the prune wakeup for `at`, unless one is already armed sooner. Kept after a close,
+    // until the cache empties, so what the track left behind still ages out.
+    #wake(at) {
+        if (this.#pruneTimer !== undefined && this.#pruneTimerAt <= at)
+            return;
+        clearTimeout(this.#pruneTimer);
+        // setTimeout truncates its delay to a signed 32-bit int, so a longer window
+        // would fire immediately and spin. Wake at the cap instead and re-arm: #prune
+        // retains anything still fresh, so the extra wakeups are the only cost.
+        const delay = Math.min(MAX_TIMEOUT_MS, Math.max(0, at - performance.now()));
+        const timer = setTimeout(() => {
+            this.#pruneTimer = undefined;
+            this.#prune();
+        }, delay);
+        // A cache prune is never a reason to hold a Node/Bun process open.
+        timer.unref?.();
+        this.#pruneTimer = timer;
+        this.#pruneTimerAt = at;
     }
     // Retain a source group and fan it out to every live sink.
     #publish(group) {
-        const entry = { group, time: Date.now(), mirrors: new Map() };
+        const entry = { group, mirrors: new Map() };
         this.#cache.push(entry);
-        this.#prune();
+        this.#cached.set(group.sequence, entry);
+        this.#received = Math.max(this.#received, group.sequence + 1);
         for (const sink of this.#sinks)
             this.#mirror(entry, sink);
+        // Give held mirrors the new live edge before pruning their timeline entry,
+        // so their latency guard can preserve a terminal expiry verdict.
+        this.#prune();
     }
-    /** Append a new group with the next sequence number. */
-    appendGroup() {
+    // Refuse a write once the track is closed, or at or past its declared end.
+    #writable(sequence) {
         if (this.#state.closed.peek() !== undefined)
             throw new Error("track is closed");
+        const final = this.#state.final.peek();
+        if (final !== undefined && sequence >= final) {
+            throw new Error(`sequence ${sequence} is at or past the track's end ${final}`);
+        }
+    }
+    /** Append a new group with the next sequence number. */
+    appendGroup() {
         const sequence = this.#sequence;
+        this.#writable(sequence.next);
         const group = new GroupProducer(sequence.next);
         sequence.next = group.sequence + 1;
         this.#publish(group);
@@ -401,16 +625,14 @@ export class Producer {
      * entry is already gone, so a long-evicted sequence is accepted as new.
      */
     writeGroup(group) {
-        if (this.#state.closed.peek() !== undefined)
-            throw new Error("track is closed");
-        const existing = this.#cache.findIndex((entry) => entry.group.sequence === group.sequence);
-        if (existing >= 0) {
-            const entry = this.#cache[existing];
-            if (!(entry.group.closed.peek() instanceof Error)) {
+        this.#writable(group.sequence);
+        const existing = this.#cached.get(group.sequence);
+        if (existing) {
+            if (!(existing.group.closed.peek() instanceof Error)) {
                 throw new Error(`duplicate group: sequence=${group.sequence}`);
             }
-            this.#evict(entry);
-            this.#cache.splice(existing, 1);
+            this.#evict(existing);
+            this.#uncache(existing);
         }
         // Only advance the shared counter upward (for appendGroup auto-increment).
         const sequence = this.#sequence;
@@ -422,13 +644,12 @@ export class Producer {
     // Fan a datagram out to every live subscriber, dropping the oldest once the ring is full.
     // Late subscribers do NOT replay old datagrams (best-effort, unlike the group cache).
     #publishDatagram(datagram) {
-        const now = performance.now();
+        this.#received = Math.max(this.#received, datagram.sequence + 1);
         for (const sink of this.#sinks) {
             sink.datagrams.mutate((list) => {
-                list.push({ datagram, time: now });
-                // Drop anything older than the send-buffer window.
-                while (list.length > 0 && now - list[0].time > MAX_DATAGRAM_AGE_MS)
+                if (list.length === MAX_DATAGRAMS)
                     list.shift();
+                list.push(datagram);
             });
         }
     }
@@ -442,48 +663,106 @@ export class Producer {
      * keep datagram payloads small (e.g. a single audio frame). Datagrams are never delivered
      * over IETF moq-transport or stream-only transports (the WebSocket fallback). A payload over
      * 65535 bytes (the QUIC datagram frame ceiling) throws. An origin publisher uses this; a
-     * relay preserving upstream numbering uses {@link writeDatagram}.
+     * relay preserving upstream numbering uses {@link insertDatagram}.
      */
     appendDatagram(timestamp, payload) {
-        if (this.#state.closed.peek() !== undefined)
-            throw new Error("track is closed");
-        if (payload.byteLength > MAX_DATAGRAM_BYTES)
-            throw new Error("datagram payload too large");
         const counter = this.#sequence;
         const sequence = counter.next;
+        this.#writable(sequence);
+        if (payload.byteLength > MAX_DATAGRAM_BYTES)
+            throw new Error("datagram payload too large");
         counter.next = sequence + 1;
         this.#publishDatagram({ sequence, timestamp, payload });
         return sequence;
     }
     /**
-     * Write a datagram with an explicit sequence number.
+     * Insert a datagram with an explicit sequence number.
      *
      * Preserves the supplied sequence (advancing the shared counter if needed) so a relay can
      * forward a datagram without renumbering it. The size limits of {@link appendDatagram}
      * apply. Most origin publishers want {@link appendDatagram} instead.
      */
-    writeDatagram(datagram) {
+    insertDatagram(sequence, timestamp, payload) {
+        this.#writable(sequence);
+        if (payload.byteLength > MAX_DATAGRAM_BYTES)
+            throw new Error("datagram payload too large");
+        const counter = this.#sequence;
+        if (sequence >= counter.next) {
+            counter.next = sequence + 1;
+        }
+        this.#publishDatagram({ sequence, timestamp, payload });
+    }
+    /**
+     * Declare the track's exclusive end, possibly ahead of the live edge, mirroring the Rust
+     * `finish_at`.
+     *
+     * `final` is the first sequence that will never be produced, so a track whose last group
+     * is 89 finishes at 90. Groups and datagrams below it are still accepted; anything at or
+     * above it is refused. Unlike {@link close} it is not terminal: call `close()` once the
+     * remaining groups are written. Throws if the track is closed, already has an end, or
+     * `final` is at or below a sequence already produced.
+     */
+    finishAt(final) {
         if (this.#state.closed.peek() !== undefined)
             throw new Error("track is closed");
-        if (datagram.payload.byteLength > MAX_DATAGRAM_BYTES)
-            throw new Error("datagram payload too large");
-        const sequence = this.#sequence;
-        if (datagram.sequence >= sequence.next) {
-            sequence.next = datagram.sequence + 1;
+        if (!Number.isSafeInteger(final) || final < 0)
+            throw new RangeError(`invalid track end: ${final}`);
+        const declared = this.#state.final.peek();
+        if (declared !== undefined)
+            throw new Error(`track already ends at ${declared}`);
+        if (final < this.#received) {
+            throw new Error(`track end ${final} is below the next sequence ${this.#received}`);
         }
-        this.#publishDatagram(datagram);
+        this.#declareFinal(final);
+    }
+    #declareFinal(final) {
+        this.#state.final.set(final);
+        for (const sink of this.#sinks)
+            sink.final.set(final);
     }
-    /** Close the track and every subscriber, mirroring the abort to their groups. Idempotent. */
+    /**
+     * Close the track and every subscriber, mirroring the abort to their groups. Idempotent.
+     *
+     * A clean close keeps the end {@link finishAt} declared, or declares one past the highest
+     * sequence produced; an abort ends without one. Subscribers still draining get the
+     * finished groups first, then the end or the abort. An abort after the declared end
+     * settled (reached, with every group below it finished) is a clean close. The groups
+     * left behind still age out after the track's `maxAge`, so a stale subscriber can't pin
+     * them.
+     */
     close(abort) {
+        if (this.#state.closed.peek() !== undefined)
+            return;
+        if (abort && this.#settled())
+            abort = undefined;
+        if (abort === undefined && this.#state.final.peek() === undefined) {
+            this.#declareFinal(this.#received);
+        }
+        // Nobody will finish these, so a subscriber that has not taken one yet never sees it.
+        // Not evicted: a reader already holding one keeps its frames and sees the abort.
+        const open = abort ? this.#cache.filter((entry) => entry.group.closed.peek() === undefined) : [];
         closeTrackState(this.#state, abort);
         for (const { group } of this.#cache)
             group.close(abort);
+        for (const entry of open) {
+            this.#unlink(entry);
+            this.#uncache(entry);
+        }
         for (const sink of this.#sinks) {
             for (const group of sink.groups.peek())
                 group.close(abort);
             closeTrackState(sink, abort);
         }
         this.#sinks.clear();
+        this.#prune();
+    }
+    // Whether the declared end was reached and every cached group below it finished, so
+    // the track already holds everything it promised. Mirrors the Rust `is_settled`.
+    #settled() {
+        const final = this.#state.final.peek();
+        if (final === undefined || this.#received < final)
+            return false;
+        return this.#cache.every(({ group }) => group.sequence >= final || group.closed.peek() === null);
     }
     /** Append a frame as its own single-frame group. */
     writeFrame(frame) {
@@ -523,12 +802,136 @@ export class Subscriber {
     #state;
     #nextSequence = 0;
     #cursor = new Signal({ start: 0 });
+    #enforceLatency = true;
+    // Which cursor owns this subscription. Both cursors draw from one buffer, so the
+    // first group read commits the track to arrival order and {@link ordered} commits
+    // it to sequence order; whichever wins is the only one allowed from here on.
+    // Datagrams are a separate cursor and never commit.
+    #mode;
+    // The group the frame-level helpers are currently draining, acquired through the
+    // sequence cursor so frame reads and {@link Ordered.nextGroup} share one floor.
+    #frameGroup;
+    #drift() {
+        const { end } = this.#cursor.peek();
+        const timeline = this.#state.timeline;
+        let presentation;
+        // The edge wants the newest content that exists, so it takes the newest
+        // stamped group's latest frame: walk back from the cap to the first one.
+        for (let i = (end === undefined ? timeline.length : timelineIndex(timeline, end)) - 1; i >= 0; i--) {
+            const group = timeline[i];
+            if (group.closed.peek() instanceof Error)
+                continue;
+            const timestamp = hooks.groupTimestamp(group);
+            if (timestamp === undefined)
+                continue;
+            presentation = { sequence: group.sequence, timestamp: hooks.groupLatest(group) ?? timestamp };
+            break;
+        }
+        const requested = this.#state.update.peek()?.maxAge ?? 0;
+        const retained = this.#state.info.peek()?.maxAge;
+        return {
+            budget: this.#enforceLatency
+                ? retained === undefined
+                    ? requested
+                    : Math.min(requested, retained)
+                : Number.POSITIVE_INFINITY,
+            presentation,
+            end,
+        };
+    }
+    // The furthest presentation time the group at `sequence` could still reach: where its
+    // immediate servable successor begins, or undefined when nothing proves where it
+    // stops. An upper bound, deliberately: a frame's duration is not on the wire, so a
+    // group's own last timestamp says where it starts presenting, not where it ends.
+    // Only the *immediate* successor counts: timestamps need not rise with sequence (a
+    // rewind reorders them), so a later stamped group proves nothing about where an
+    // unstamped successor will begin, and shrinking the bound is the unsafe direction.
+    // An unstamped successor leaves the reach unbounded until it presents a frame.
+    #reach(sequence, end) {
+        const timeline = this.#state.timeline;
+        for (let i = timelineIndex(timeline, sequence + 1); i < timeline.length; i++) {
+            const successor = timeline[i];
+            if (end !== undefined && successor.sequence >= end)
+                break;
+            if (successor.closed.peek() instanceof Error)
+                continue;
+            return hooks.groupTimestamp(successor)?.asMillis();
+        }
+        return undefined;
+    }
+    // Whether the drift budget says to give up on `group`.
+    //
+    // Presentation time measures a group by how far it could still reach, not by how far
+    // behind it started. Being behind is survivable: priority transmits newer groups first,
+    // so a backlog bursts at whatever rate is left over and closes the gap faster than the
+    // live edge advances. A group is abandoned only once everything it could still present
+    // falls outside the budget.
+    //
+    // A group's reach is bounded by its nearest successor: it cannot present past where the
+    // next group begins. Its own frames say nothing, since a frame's duration is not on the
+    // wire, and the candidate needs no timestamp of its own: an empty group is bounded by
+    // its stamped successor the same way. The bound is exclusive, so the comparison is `>=`:
+    // the freshest frame a group could still hold sits just below its reach, so an age equal
+    // to the budget already puts every frame in it strictly past the budget. A zero budget
+    // falls out for free. Only timestamps drive expiry; wall-clock reclamation of idle
+    // content is the cache's own policy, not the budget's.
+    #isStale(group, drift) {
+        if (this.#state.timeline[timelineIndex(this.#state.timeline, group.sequence)] !== group)
+            return false;
+        const reach = this.#reach(group.sequence, drift.end);
+        return (drift.presentation !== undefined &&
+            drift.presentation.sequence > group.sequence &&
+            reach !== undefined &&
+            drift.presentation.timestamp.asMillis() - reach >= drift.budget);
+    }
+    #guard(group) {
+        if (!this.#enforceLatency)
+            return group;
+        hooks.expireGroup(group, {
+            expired: () => this.#isStale(group, this.#drift()),
+            changed: [
+                this.#state.groups,
+                this.#state.timelineChanged,
+                this.#state.update,
+                this.#state.info,
+                this.#cursor,
+                this.#state.closed,
+            ],
+        });
+        return group;
+    }
     constructor(name, state) {
         this.name = name;
         this.#state = state;
+        // The cursor's floor is the group the subscription named, or 0. A floor is the
+        // only thing a start contributes; {@link Subscription.maxAge} is what asks for
+        // data, and delivery skips everything above the floor that the budget convicts.
+        this.#cursor.set({ start: groupBounds(state.update.peek()?.groups ?? {}).start });
     }
     static {
         makeSubscriber = (name, state) => new Subscriber(name, state);
+        hooks.tryRecvGroup = (subscriber) => subscriber.#tryRecvGroup();
+        hooks.groupChanged = (subscriber, fn) => subscriber.#groupChanged(fn);
+        hooks.exemptFetch = (subscriber) => {
+            subscriber.#enforceLatency = false;
+        };
+        hooks.replaceGroups = (subscriber, groups) => subscriber.#replaceGroups(groups);
+        // The sequence cursor lives here (it shares the buffer and the drift anchor with
+        // the arrival cursor); `Ordered` is the handle that reaches it.
+        ordered_ = {
+            nextGroup: (subscriber) => subscriber.#nextGroup(),
+            readFrame: (subscriber) => subscriber.#readFrame(),
+            readString: (subscriber) => subscriber.#readString(),
+            readJson: (subscriber) => subscriber.#readJson(),
+            readBool: (subscriber) => subscriber.#readBool(),
+            // Unordered either way, so both handles reach the same cursor.
+            recvDatagram: (subscriber) => subscriber.#recvDatagram(),
+        };
+    }
+    // Refuse a read on this handle once `ordered()` has taken the subscription.
+    #live() {
+        if (this.#mode === "ordered")
+            throw new Error("track is read in sequence order; use the Ordered handle");
     }
     /**
      * Resolve this track's immutable publisher properties.
@@ -552,6 +955,37 @@ export class Subscriber {
     latest() {
         return this.#state.latest;
     }
+    /**
+     * The track's exclusive final boundary: the end {@link Producer.finishAt} declared, which
+     * can be ahead of the live edge, or one past the highest sequence produced once the
+     * producer closes cleanly (0 for a track that produced none). Groups and datagrams share
+     * the sequence namespace, so this can exceed `latest() + 1`. Undefined until declared,
+     * and after an abort that declared none.
+     */
+    final() {
+        return this.#state.final.peek();
+    }
+    /**
+     * Resolve with the track's exclusive final boundary once it is known, mirroring the Rust
+     * `finished`.
+     *
+     * Resolves as soon as the end is declared, which may be ahead of the live edge, so it
+     * says nothing about every group having arrived: read until the cursor returns
+     * `undefined` for that. Rejects with the abort, or if the track closes without an end.
+     */
+    async finished() {
+        for (;;) {
+            const final = this.#state.final.peek();
+            if (final !== undefined)
+                return final;
+            const closed = this.#state.closed.peek();
+            if (closed instanceof Error)
+                throw closed;
+            if (closed !== undefined)
+                throw new Error("track closed before its end was known");
+            await Signal.race(this.#state.final, this.#state.closed);
+        }
+    }
     /**
      * The newest frame this track has produced, or `undefined` while it has none.
      *
@@ -592,22 +1026,33 @@ export class Subscriber {
             throw new Error("track has no producer to fork from");
         return producer.subscribe(options);
     }
-    /** Start this subscriber's local read cursor at `sequence`, without changing its wire request. */
-    startAt(sequence) {
-        this.#cursor.update((cursor) => ({ ...cursor, start: sequence }));
+    /** Limit subsequent reads to these groups and return this reader for chaining. */
+    withGroups(groups) {
+        this.setGroups(groups);
+        return this;
     }
     /**
-     * Cap {@link nextGroup} and {@link recvGroup} at `sequence` inclusively, or omit it to
-     * remove the cap. Groups above the cap remain buffered and become readable if the cap
-     * is raised. This local cursor does not change the subscription's wire request.
+     * Limit subsequent reads without rewinding read progress or changing the wire request.
+     * An omitted start preserves the current floor; an omitted end removes the cap.
+     * Raising the end makes unread buffered groups available again.
      */
-    endAt(sequence) {
-        this.#cursor.update((cursor) => ({ ...cursor, end: sequence }));
+    setGroups(groups) {
+        const { start, end } = groupBounds(groups);
+        this.#cursor.update((cursor) => ({ start: Math.max(cursor.start, start), end }));
+    }
+    // Serving counterpart of setGroups: a named start replaces the floor, matching
+    // Rust `start_at`. Local readers stay monotonic; only the wire publisher lowers.
+    #replaceGroups(groups) {
+        const { start, end } = groupBounds(groups);
+        this.#cursor.update((cursor) => ({
+            start: groups.start === undefined ? cursor.start : start,
+            end,
+        }));
     }
     /** Close the track (optionally with an error), closing any pending groups. Idempotent. */
     close(abort) {
         // Settle if we're first (the producer may already have); either way drop anything
-        // still buffered. Groups parked at the endAt cap deliberately outlive a clean
+        // still buffered. Groups parked at the setGroups cap deliberately outlive a clean
         // producer close, so the subscriber leaving is what must release them: closing
         // and clearing wakes a pending read to observe the end instead of hanging.
         closeTrackState(this.#state, abort);
@@ -616,55 +1061,108 @@ export class Subscriber {
                 group.close(abort);
             groups.length = 0;
         });
+        this.#frameGroup?.close(abort);
+        this.#frameGroup = undefined;
+        this.#state.timeline.length = 0;
     }
     /**
      * Receive every group on this track exactly once, as it becomes available.
      *
      * Groups may arrive out of order or with gaps due to network conditions; unlike
-     * {@link nextGroup}, one that arrives after a newer group was already returned is
-     * still delivered. When several groups are buffered, the lowest sequence is
+     * {@link Ordered.nextGroup}, one that arrives after a newer group was already returned
+     * is still delivered. When several groups are buffered, the lowest sequence is
      * returned first.
      *
-     * Honors the floor set by {@link startAt} and the cap set by {@link endAt}: a group
+     * Honors the range set by {@link setGroups}: a group
      * beyond the cap stays buffered (not dropped) and is offered once the cap rises, even
      * after a clean close, without blocking in-range groups that arrive behind it.
+     * A group whose presentation time is further behind the live edge than this
+     * subscriber's `maxAge` is skipped. The default of zero takes the live edge.
+     * The budget remains attached after return, so a pending frame read rejects if a stalled
+     * group becomes stale while newer data advances.
+     *
+     * The first call commits this track to arrival order: {@link ordered} throws afterwards.
      */
     async recvGroup() {
+        this.#live();
+        this.#mode = "arrival";
         for (;;) {
-            const group = this.tryRecvGroup();
-            if (group)
-                return group;
-            const closed = this.#state.closed.peek();
-            if (closed instanceof Error)
-                throw closed;
-            // A group beyond the cap outlives a clean close: it becomes deliverable if
-            // the cap rises, so the track isn't over while any are held.
-            if (closed !== undefined && !this.#state.groups.peek()[0])
-                return undefined;
+            const recv = this.#tryRecvGroup();
+            switch (recv.kind) {
+                case "group":
+                    return recv.group;
+                case "done":
+                    return undefined;
+                case "error":
+                    throw recv.error;
+            }
+            // Idle, or parked at the boundary waiting for the cap to rise.
             await Signal.race(this.#state.groups, this.#cursor, this.#state.closed);
         }
     }
+    // Package-internal synchronous half of recvGroup. The lite publisher uses this so applying
+    // control state, popping the group, and positioning its frames are one JavaScript turn.
+    #tryRecvGroup() {
+        const groups = this.#state.groups.peek();
+        const { start, end } = this.#cursor.peek();
+        while (groups.length > 0 && groups[0].sequence < start)
+            groups.shift()?.close();
+        const drift = this.#drift();
+        for (;;) {
+            // The buffer is sequence-sorted, so an in-range group that arrives behind a
+            // beyond-cap one sorts in front of it and is never blocked by it.
+            const group = groups[0];
+            if (!group || (end !== undefined && group.sequence >= end))
+                break;
+            groups.shift();
+            if (this.#isStale(group, drift)) {
+                group.close();
+                continue;
+            }
+            return { kind: "group", group: this.#guard(group) };
+        }
+        const group = groups[0];
+        const closed = this.#state.closed.peek();
+        if (closed instanceof Error)
+            return { kind: "error", error: closed };
+        if (closed === undefined)
+            return { kind: "idle" };
+        // A group beyond the cap outlives a clean close: it becomes deliverable if
+        // the cap rises, so the track isn't over while any are held.
+        return group ? { kind: "boundary" } : { kind: "done" };
+    }
+    // Package-internal readiness half of recvGroup. Each registration fires at most once, and
+    // the caller disposes the losers after whichever source wakes it. A declared end wakes it
+    // too, so a publisher can forward the end before the live edge reaches it.
+    #groupChanged(fn) {
+        const dispose = [
+            this.#state.groups.changed(fn),
+            this.#cursor.changed(fn),
+            this.#state.closed.changed(fn),
+            this.#state.final.changed(fn),
+        ];
+        return () => {
+            for (const close of dispose)
+                close();
+        };
+    }
     /**
      * Take the next buffered group without blocking, honoring the same cursor bounds as
      * {@link recvGroup}.
      *
      * Returns `undefined` when nothing is deliverable right now, which is not by itself the
      * end of the track: a group may still arrive, or one may be parked beyond the
-     * {@link endAt} cap. Use it to drain what the retained window already holds, where
+     * {@link setGroups} cap. Use it to drain what the retained window already holds, where
      * waiting for a sequence nothing will republish would park forever.
      */
     tryRecvGroup() {
-        const groups = this.#state.groups.peek();
-        const { start, end } = this.#cursor.peek();
-        while (groups.length > 0 && groups[0].sequence < start)
-            groups.shift()?.close();
-        // The buffer is sequence-sorted, so an in-range group that arrives behind a
-        // beyond-cap one sorts in front of it and is never blocked by it.
-        const group = groups[0];
-        if (group && (end === undefined || group.sequence <= end)) {
-            groups.shift();
-            return group;
-        }
+        this.#live();
+        this.#mode = "arrival";
+        const recv = this.#tryRecvGroup();
+        if (recv.kind === "group")
+            return recv.group;
+        if (recv.kind === "error")
+            throw recv.error;
         return undefined;
     }
     /**
@@ -673,23 +1171,20 @@ export class Subscriber {
      * Datagrams are a separate best-effort channel from groups (see
      * {@link Producer.appendDatagram}); they share only the sequence namespace. A consumer
      * that falls too far behind silently loses the oldest datagrams. Read this alongside
-     * {@link recvGroup} (e.g. in a separate loop) to receive both channels concurrently. Returning
-     * a datagram advances {@link nextGroup} past that sequence.
+     * {@link recvGroup} (e.g. in a separate loop) to receive both channels concurrently.
+     * The two cursors are independent: a datagram never moves the group cursor.
      */
     async recvDatagram() {
+        this.#live();
+        return this.#recvDatagram();
+    }
+    // The datagram cursor, reachable from either handle: unordered by construction, so the
+    // choice of group order says nothing about it.
+    async #recvDatagram() {
         for (;;) {
             const datagrams = this.#state.datagrams.peek();
-            // Evict datagrams older than the send-buffer window (also enforced on write), so a
-            // reader that stalled skips stale datagrams instead of replaying them.
-            const cutoff = performance.now() - MAX_DATAGRAM_AGE_MS;
-            while (datagrams.length > 0 && datagrams[0].time < cutoff)
-                datagrams.shift();
             if (datagrams.length > 0) {
-                const datagram = datagrams.shift()?.datagram;
-                if (datagram) {
-                    this.#nextSequence = Math.max(this.#nextSequence, datagram.sequence + 1);
-                }
-                return datagram;
+                return datagrams.shift();
             }
             const closed = this.#state.closed.peek();
             if (closed instanceof Error)
@@ -699,128 +1194,111 @@ export class Subscriber {
             await Signal.race(this.#state.datagrams, this.#state.closed);
         }
     }
-    /**
-     * Return the next group with a strictly-greater sequence number than the last returned.
-     *
-     * Late arrivals (sequence at or below the last returned) are silently skipped.
-     * Use {@link recvGroup} to see every group in arrival order instead.
-     */
-    async nextGroup() {
+    // The sequence cursor behind {@link Ordered}, which owns the only public door to it.
+    async #nextGroup() {
         for (;;) {
             const groups = this.#state.groups.peek();
             const cursor = this.#cursor.peek();
             const start = Math.max(cursor.start, this.#nextSequence);
             while (groups.length > 0 && groups[0].sequence < start)
                 groups.shift()?.close();
-            const group = groups[0];
-            if (group && (cursor.end === undefined || group.sequence <= cursor.end)) {
+            // One anchor for the whole pass, so walking a backlog off stays linear.
+            const drift = this.#drift();
+            for (;;) {
+                const group = groups[0];
+                if (!group || (cursor.end !== undefined && group.sequence >= cursor.end))
+                    break;
                 groups.shift();
                 this.#nextSequence = group.sequence + 1;
-                return group;
+                // Every frame this group could still hold is past the budget, so keep
+                // scanning: one pass walks a whole backlog off rather than replaying it.
+                if (this.#isStale(group, drift)) {
+                    group.close();
+                    continue;
+                }
+                // One cursor: the frame helpers must not keep draining a group this
+                // read just moved past, or interleaved reads would run backwards.
+                if (this.#frameGroup && this.#frameGroup.sequence < group.sequence) {
+                    this.#frameGroup.close();
+                    this.#frameGroup = undefined;
+                }
+                return this.#guard(group);
             }
             const closed = this.#state.closed.peek();
             if (closed instanceof Error)
                 throw closed;
-            if (closed !== undefined && !group)
+            // A group parked above the cap stays deliverable even after a clean close
+            // (its frames remain buffered), so keep waiting for a cap raise. Only a
+            // drained track reports finished.
+            if (closed !== undefined && !groups[0])
                 return undefined;
             await Signal.race(this.#state.groups, this.#cursor, this.#state.closed);
         }
     }
     /**
-     * Reads the next frame across all groups, discarding older groups.
-     * Treat the returned frame bytes as read-only; they are shared with other consumers.
-     */
-    async readFrame() {
-        const next = await this.readFrameSequence();
-        return next ? { payload: next.payload, timestamp: next.timestamp } : undefined;
-    }
-    /**
-     * Reads the next frame along with its group and frame sequence numbers.
+     * Reads the next frame across groups, in sequence order, with its group and frame numbers.
      * Treat the returned frame bytes as read-only; they are shared with other consumers.
+     *
+     * Groups are acquired through the same sequence cursor as {@link Ordered.nextGroup},
+     * so frames never run backwards: a late lower-sequence group is skipped, and so is
+     * one every frame of which `maxAge` proves is too old. A group the budget abandons
+     * mid-stall ends cleanly and the cursor resyncs from the next group; a gap inside a
+     * group still surfaces as {@link TooFarBehind} or {@link GroupTooLarge}.
      */
-    async readFrameSequence() {
+    async #readFrame() {
         for (;;) {
-            const groups = this.#state.groups.peek();
-            const { start } = this.#cursor.peek();
-            while (groups.length > 0 && groups[0].sequence < start)
-                groups.shift()?.close();
-            // Drain older groups first, dropping each once empty.
-            while (groups.length > 1) {
-                if (groups[0].skipped) {
-                    // The reader fell behind this group's eviction window. Drop it and
-                    // signal the gap; the next read resyncs from the following group.
-                    groups.shift()?.close();
-                    throw new Lagged();
-                }
-                const next = groups[0].tryReadFrameSequence();
-                if (next) {
-                    return {
-                        group: groups[0].sequence,
-                        frame: next.sequence,
-                        payload: next.payload,
-                        timestamp: next.timestamp,
-                    };
-                }
-                groups.shift()?.close();
+            if (!this.#frameGroup) {
+                this.#frameGroup = await this.#nextGroup();
+                if (!this.#frameGroup)
+                    return undefined;
+            }
+            const group = this.#frameGroup;
+            let next;
+            try {
+                next = await group.readFrameSequence();
             }
-            if (groups.length === 0) {
+            catch (err) {
+                // The group failed underneath us: resync from the next one, surfacing
+                // only what the caller can act on (a gap, or the track's own abort).
+                this.#frameGroup = undefined;
+                group.close();
+                if (err instanceof TooFarBehind || err instanceof GroupTooLarge)
+                    throw err;
                 const closed = this.#state.closed.peek();
                 if (closed instanceof Error)
                     throw closed;
-                if (closed !== undefined)
-                    return undefined;
-                await Signal.race(this.#state.groups, this.#cursor, this.#state.closed);
                 continue;
             }
-            const group = groups[0];
-            if (group.skipped) {
-                // Fell behind this group's eviction window. Drop it and signal the gap;
-                // the next read resyncs from the following group.
-                groups.shift()?.close();
-                throw new Lagged();
-            }
-            const next = group.tryReadFrameSequence();
-            if (next)
+            if (next) {
                 return {
                     group: group.sequence,
                     frame: next.sequence,
                     payload: next.payload,
                     timestamp: next.timestamp,
                 };
-            const closed = this.#state.closed.peek();
-            if (closed instanceof Error)
-                throw closed;
-            if (closed !== undefined)
-                return undefined;
-            // A finished (drained + closed) group has nothing left: drop it and loop, rather than
-            // busy-waiting on its already-resolved readable() (which would livelock and starve the
-            // macrotask that delivers the next group).
-            if (group.done) {
-                groups.shift()?.close();
-                continue;
             }
-            // Lone open group with nothing buffered yet: wait for a frame on it, a new group, or
-            // the track closing.
-            await Promise.race([Signal.race(this.#state.groups, this.#cursor, this.#state.closed), group.readable()]);
+            // The group is exhausted (or the budget abandoned its stall); move on.
+            this.#frameGroup = undefined;
+            group.close();
         }
     }
     /** Reads the next frame and decodes it as a UTF-8 string. */
-    async readString() {
-        const next = await this.readFrame();
+    async #readString() {
+        const next = await this.#readFrame();
         if (!next)
             return undefined;
         return new TextDecoder().decode(next.payload);
     }
     /** Reads the next frame and parses it as JSON. */
-    async readJson() {
-        const next = await this.readString();
+    async #readJson() {
+        const next = await this.#readString();
         if (!next)
             return undefined;
         return JSON.parse(next);
     }
     /** Reads the next frame and decodes it as a one-byte boolean, throwing on a malformed frame. */
-    async readBool() {
-        const next = await this.readFrame();
+    async #readBool() {
+        const next = await this.#readFrame();
         if (!next)
             return undefined;
         const payload = next.payload;
@@ -828,6 +1306,25 @@ export class Subscriber {
             throw new Error("invalid bool frame");
         return payload[0] === 1;
     }
+    /**
+     * Read this track's groups in sequence order instead of arrival order.
+     *
+     * Both cursors draw from the same buffer, so a track is read one way or the other: this
+     * hands the subscription to the returned {@link Ordered} and leaves this handle inert.
+     * {@link recvGroup} and {@link recvDatagram} throw afterwards. Throws once a
+     * {@link recvGroup} call has already committed the track to arrival order.
+     *
+     * Datagrams come along: they are a separate cursor either way, so the choice of group
+     * order says nothing about them, and reading them commits nothing.
+     */
+    ordered() {
+        if (this.#mode === "ordered")
+            throw new Error("track is already read in sequence order");
+        if (this.#mode === "arrival")
+            throw new Error("track is already read in arrival order");
+        this.#mode = "ordered";
+        return makeOrdered(this);
+    }
     /**
      * Update this subscription's options (e.g. priority), triggering a SUBSCRIBE_UPDATE to the
      * publisher. Mirrors the Rust `Subscriber::update`.
@@ -836,4 +1333,118 @@ export class Subscriber {
         this.#state.update.set(subscriptionDefaults(options));
     }
 }
+/**
+ * A {@link Subscriber} that reads groups in sequence order.
+ *
+ * Created by {@link Subscriber.ordered}, which takes the subscription over: the two
+ * cursors draw from one buffer, so a track is read one way or the other and never both.
+ * Every group this returns has a higher sequence than the last, so a late arrival is
+ * skipped rather than delivered out of turn.
+ *
+ * `maxAge` applies as this cursor reads, exactly as it does on the arrival cursor: a
+ * group is skipped once its reach, where its immediate successor begins, is that far
+ * behind the newest frame on the track. Nothing weaker convicts it, since the reach is
+ * the only proof that every frame it could still hold is past the budget, so a backlog
+ * inside the budget is still delivered whole, as a burst in order. The budget follows a
+ * group already handed out too: a stalled group's pending frame read rejects once newer
+ * content has pulled that far ahead.
+ */
+export class Ordered {
+    /** The track name. */
+    name;
+    #subscriber;
+    constructor(subscriber) {
+        this.name = subscriber.name;
+        this.#subscriber = subscriber;
+    }
+    static {
+        makeOrdered = (subscriber) => new Ordered(subscriber);
+    }
+    /** Resolve this track's immutable publisher properties; see {@link Subscriber.info}. */
+    info() {
+        return this.#subscriber.info();
+    }
+    /** Settles once the track closes; see {@link Producer.closed}. */
+    get closed() {
+        return this.#subscriber.closed;
+    }
+    /** This subscriber's current options, including defaults and the last {@link update}. */
+    get subscription() {
+        return this.#subscriber.subscription;
+    }
+    /** The latest group sequence observed on this track, if any. */
+    latest() {
+        return this.#subscriber.latest();
+    }
+    /** The track's exclusive final boundary; see {@link Subscriber.final}. */
+    final() {
+        return this.#subscriber.final();
+    }
+    /** Resolve with the track's exclusive final boundary once known; see {@link Subscriber.finished}. */
+    finished() {
+        return this.#subscriber.finished();
+    }
+    /** Limit subsequent reads to these groups and return this reader for chaining. */
+    withGroups(groups) {
+        this.setGroups(groups);
+        return this;
+    }
+    /** Limit subsequent reads to these groups; see {@link Subscriber.setGroups}. */
+    setGroups(groups) {
+        this.#subscriber.setGroups(groups);
+    }
+    /** Update this subscription's options; see {@link Subscriber.update}. */
+    update(options) {
+        this.#subscriber.update(options);
+    }
+    /** Close the track (optionally with an error), closing any pending groups. Idempotent. */
+    close(abort) {
+        this.#subscriber.close(abort);
+    }
+    /**
+     * Return the next group with a strictly-greater sequence number than the last returned.
+     *
+     * Late arrivals (sequence at or below the last returned) are silently skipped, as is a
+     * group whose every frame is further behind the live edge than `maxAge` (the default of
+     * zero keeps only what nothing newer has superseded). Honors the bounds set by
+     * {@link setGroups}.
+     */
+    nextGroup() {
+        return ordered_.nextGroup(this.#subscriber);
+    }
+    /**
+     * Read the next frame across groups, in sequence order, with its group and frame numbers.
+     *
+     * Rides the same cursor as {@link nextGroup} and shares this handle's contract: a
+     * buffered backlog is drained in full up to the point `maxAge` proves it useless.
+     * Treat the returned frame bytes as read-only; they are shared with other consumers.
+     */
+    readFrame() {
+        return ordered_.readFrame(this.#subscriber);
+    }
+    /** Read the next frame and decode it as a UTF-8 string. */
+    readString() {
+        return ordered_.readString(this.#subscriber);
+    }
+    /** Read the next frame and parse it as JSON. */
+    readJson() {
+        return ordered_.readJson(this.#subscriber);
+    }
+    /** Read the next frame and decode it as a one-byte boolean, throwing on a malformed frame. */
+    readBool() {
+        return ordered_.readBool(this.#subscriber);
+    }
+    /**
+     * Receive the next datagram in arrival order.
+     *
+     * Datagrams are a separate best-effort channel from groups (see
+     * {@link Producer.appendDatagram}); they share only the sequence namespace, and
+     * neither cursor moves the other. Unordered by construction, so this behaves
+     * identically on either handle; it is here so a track carrying both channels needs
+     * one subscription rather than two.
+     */
+    recvDatagram() {
+        return ordered_.recvDatagram(this.#subscriber);
+    }
+}
 //# sourceMappingURL=track.js.map