@norskvideo/moq-net 0.1.7 → 0.2.0

package/lite/publisher.js

@@ -1,18 +1,20 @@
 /* @ts-self-types="./publisher.d.ts" */
-import { Signal } from "@norskvideo/moq-signals";
-import { error, reason } from "../error.js";
-import * as Path from "../path.js";
+import { race, Signal } from "@norskvideo/moq-signals";
+import { error, NotFound, reason, StreamCode, StreamError } from "../error.js";
+import { Cost, routesEqual } from "../hop.js";
+import { hiddenBelow, hooks, presented } from "../internal.js";
 import { Writer } from "../stream.js";
-import { Timescale } from "../time.js";
+import { Milli, Timescale } from "../time.js";
+import { wireOf } from "../wire.js";
 import { AnnounceInit, AnnounceOk, encodeAnnounceBroadcast } from "./announce.js";
 import { Datagram as DatagramMessage } from "./datagram.js";
 import * as DatagramStream from "./datagram_stream.js";
 import { Group as GroupMessage } from "./group.js";
 import { Priority, sendOrder } from "./priority.js";
 import { Probe } from "./probe.js";
-import { encodeSubscribeResponse, SubscribeEnd, SubscribeOk, SubscribeStart, SubscribeUpdate, } from "./subscribe.js";
+import { encodeSubscribeResponse, exclusiveGroupEnd, SubscribeEnd, SubscribeOk, SubscribeStart, SubscribeUpdate, } from "./subscribe.js";
 import { TrackInfo as TrackInfoMessage } from "./track.js";
-import { hasAnnounceId, hasAnnounceOk, hasDatagrams, hasProbeRtt, Version } from "./version.js";
+import { hasAnnounceId, hasAnnounceOk, hasDatagrams, hasProbeRtt, hasRouteCost, hasStreamCount, resolvesStart, Version, } from "./version.js";
 const PROBE_INTERVAL = 100; // ms
 const PROBE_MAX_AGE = 10_000; // ms
 const PROBE_MAX_DELTA = 0.25;
@@ -34,6 +36,175 @@ function supportsTrackStream(version) {
             return true;
     }
 }
+/**
+ * The frames of `sequence` a subscription asked for, as a start index and an inclusive end.
+ *
+ * The frame bounds qualify the start and end group only; every other group is served whole.
+ * Which groups are served at all is the subscriber's read cursor (`replaceGroups`),
+ * applied when a group is popped rather than re-checked here.
+ *
+ * The serving loop calls this synchronously after the pop, before any SUBSCRIBE_UPDATE can
+ * change `bounds`. Nothing downstream trims the frame range: it is a wire request,
+ * deliberately decoupled from the receiver's local read cursor.
+ */
+function frameRange(bounds, sequence) {
+    return {
+        start: bounds.startGroup === sequence ? bounds.startFrame : 0,
+        end: bounds.endGroup === sequence ? bounds.endFrame : undefined,
+    };
+}
+/**
+ * The subscribe stream's control half, decoded ahead of the serving loop.
+ *
+ * Decoding runs on its own and publishes each full subscription update immediately, so a
+ * blocked response write cannot delay re-ranking streams already in flight. It separately
+ * stores only the latest range state for the serving loop, which owns the local track cursor
+ * and frame bounds. That keeps a group pop and its frame-range snapshot one indivisible step.
+ *
+ * Reading ahead makes control-first ordering hold for a burst. Coalescing bounds memory while
+ * preserving the newest state decoded before the next group pop. The Rust publisher gets the
+ * same ordering from `poll_decode_maybe`, which decodes straight out of the reader's buffer;
+ * nothing here can decode synchronously, so it reads ahead instead.
+ */
+class SubscriptionControls {
+    #writer;
+    #update;
+    // Sticky, first one wins: null once the stream is over, an Error once it failed.
+    #end;
+    #ended;
+    #resolveEnd;
+    #changed = new Signal(0);
+    /** Settles once decoding stops, so teardown can wait for it rather than leaving it running. */
+    decoding;
+    constructor({ reader, writer, version, apply }) {
+        this.#writer = writer;
+        this.#ended = new Promise((resolve) => {
+            this.#resolveEnd = resolve;
+        });
+        this.decoding = this.#decode(reader, version, apply);
+        // Our own half going away ends the loop too, and has to reach it the same way: the
+        // loop looks at nothing else.
+        void writer.closed.then(() => this.#finish(null), (err) => this.#finish(error(err)));
+    }
+    /** The next control to apply, or undefined while the peer is quiet. */
+    take() {
+        const update = this.#update;
+        this.#update = undefined;
+        // An update decoded before the stream ended still applies before the sticky end.
+        if (update)
+            return { kind: "update", update };
+        if (this.#end === undefined)
+            return undefined;
+        return this.#end === null ? { kind: "done" } : { kind: "error", error: this.#end };
+    }
+    /** Calls `fn` once {@link take} may answer differently. */
+    changed(fn) {
+        return this.#changed.changed(fn);
+    }
+    /** Returns false when peer departure supersedes a blocked response write. */
+    async response(pending) {
+        // `#ended` lives as long as the stream, so it is raced as-is rather than mapped per call.
+        const result = await race([
+            pending.then(() => ({ kind: "sent" }), (err) => ({ kind: "error", error: error(err) })),
+            this.#ended,
+        ]);
+        if (result !== null && !(result instanceof Error)) {
+            if (result.kind === "sent")
+                return true;
+            throw result.error;
+        }
+        // The race leaves the blocked encode running, so reset the writable half too.
+        this.#writer.reset(result ?? new StreamError(StreamCode.Cancel, { message: "cancel" }));
+        if (result)
+            throw result;
+        return false;
+    }
+    /** Settles once the stream is over: `null` when it ended cleanly, or the failure. */
+    get ended() {
+        return this.#ended;
+    }
+    #finish(end) {
+        if (this.#end !== undefined)
+            return;
+        this.#end = end;
+        this.#resolveEnd(end);
+        this.#changed.update((value) => value + 1);
+    }
+    async #decode(reader, version, apply) {
+        try {
+            while (this.#end === undefined) {
+                const update = await SubscribeUpdate.decodeMaybe(reader, version);
+                if (!update)
+                    break;
+                apply(update);
+                this.#update = update;
+                this.#changed.update((value) => value + 1);
+            }
+        }
+        catch (err) {
+            this.#finish(error(err));
+            return;
+        }
+        this.#finish(null);
+    }
+}
+// A microtask is too short: decoding one framed update crosses several awaits, each of which
+// can requeue behind the serving continuation. A task boundary lets the decoder finish whatever
+// the transport already delivered before the next group pop. Updates are rare, so groups do not
+// pay this scheduling cost on the normal path.
+const yieldToControls = () => new Promise((resolve) => setTimeout(resolve, 0));
+// Register both readiness sources in the same turn after the caller observed neither ready.
+// The winner disposes both registrations, so an idle subscription accumulates nothing no
+// matter how many times it wakes.
+function waitForSubscription(controls, subscriber) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const dispose = [];
+        const wake = () => {
+            if (settled)
+                return;
+            settled = true;
+            for (const close of dispose)
+                close();
+            resolve();
+        };
+        dispose.push(controls.changed(wake), hooks.groupChanged(subscriber, wake));
+    });
+}
+/**
+ * The budget to serve a peer with, given what its wire could tell us.
+ *
+ * A version without the field decodes as `0`, which is indistinguishable from a peer
+ * genuinely asking for the live edge. Serving that as real time would discard backlog
+ * a legacy subscriber never declined, so fall back to a window wide enough not to drop
+ * and leave enforcement to the receiver, as the IETF path does for the same reason.
+ */
+function servingMaxAge(version, requested) {
+    return carriesMaxAge(version) ? (requested ?? 0) : Number.MAX_SAFE_INTEGER;
+}
+/** Whether this version's SUBSCRIBE carries Subscriber Max Age at all. */
+function carriesMaxAge(version) {
+    return version !== Version.DRAFT_01 && version !== Version.DRAFT_02;
+}
+/**
+ * Position a subscription's read cursor for the wire serving it.
+ *
+ * On lite-06 there is nothing to do: the cursor is floored at the group the subscription
+ * named (or 0), and its Max Age decides what above the floor is worth delivering.
+ *
+ * Pre-06 wires are the exception: their drafts define an absent `Group Start` as the
+ * latest group, so say so explicitly rather than letting the budget reach back. Lite-03/04/05
+ * carry a Max Age, but there it is a staleness tolerance only; lite-01/02 additionally get
+ * an unbounded budget so nothing is dropped under them (see {@link servingMaxAge}), which
+ * must not read as a request to replay the whole cache on join.
+ */
+function positionCursor(track, version, startGroup) {
+    if (resolvesStart(version) || startGroup !== undefined)
+        return;
+    const latest = track.latest();
+    if (latest !== undefined)
+        hooks.replaceGroups(track, { start: { included: latest } });
+}
 /**
  * Handles publishing broadcasts and managing their lifecycle.
  *
@@ -46,58 +217,45 @@ export class Publisher {
     // can detect loops and prefer shorter paths. Created by Connection and
     // shared with Subscriber, which can optionally use it to filter out its
     // own announcements.
-    origin;
+    hop;
     #quic;
     // The one writer for the outbound datagram stream (getWriter locks it), acquired once at
     // construction when this version + transport carry datagrams, released in close(). Its
     // presence is the gate: undefined means datagrams aren't served on this connection. All
     // subscriptions share it, since a second getWriter on the same stream would throw.
     #datagramWriter;
-    // Our published broadcasts.
-    // It's a signal so we can live update any announce streams.
-    #broadcasts = new Signal(new Map());
+    // Originated advertisements this session forwards.
+    #advertised;
+    #publish;
     // TRACK_INFO is immutable per track, so resolve it from the application once
     // (via a throwaway subscribe whose info() resolves when the app calls accept)
-    // and reuse it for every later TRACK request of the same track. Keyed by
-    // `broadcast\0track`. A rejected lookup is evicted so a retry can re-probe.
-    #trackInfo = new Map();
+    // and reuse it for every later TRACK request of the same track. Keyed by the
+    // routing front rather than the path: immutability holds for one broadcast, and a
+    // republish puts a different one on the path, so its entries must not be reused.
+    // A rejected lookup is evicted so a retry can re-probe.
+    #trackInfo = new WeakMap();
     /**
      * Creates a new Publisher instance.
      * @param quic - The WebTransport session to use
      * @param version - Negotiated protocol version
-     * @param origin - Origin id shared with the Subscriber
+     * @param origin - Hop id shared with the Subscriber
+     * @param publish - The origin whose broadcasts this session serves; omit to publish nothing
      *
      * @internal
      */
-    constructor(quic, version, origin) {
+    constructor(quic, version, hop, publish) {
         this.#quic = quic;
         this.version = version;
-        this.origin = origin;
+        this.hop = hop;
+        const origin = publish && wireOf(publish);
+        this.#advertised = origin?.advertised ?? new Signal(new Map());
+        this.#publish = publish;
         // Grab the datagram writer up front when the transport carries datagrams (no group
         // fallback, so it stays undefined otherwise). One writer for all subscriptions.
         if (hasDatagrams(version)) {
             this.#datagramWriter = DatagramStream.datagramWriter(quic);
         }
     }
-    /**
-     * Publishes a broadcast with any associated tracks.
-     * @param name - The broadcast to publish
-     */
-    publish(path, broadcast) {
-        this.#broadcasts.mutate((broadcasts) => {
-            if (!broadcasts)
-                throw new Error("closed");
-            broadcasts.set(path, broadcast);
-        });
-        // Remove the broadcast from the lookup when it's closed, unless the path was republished.
-        void broadcast.closed.then(() => {
-            this.#broadcasts.mutate((broadcasts) => {
-                if (broadcasts?.get(path) === broadcast) {
-                    broadcasts.delete(path);
-                }
-            });
-        });
-    }
     /**
      * Handles an announce interest message.
      * @param msg - The announce interest message
@@ -107,99 +265,133 @@ export class Publisher {
      */
     async runAnnounce(msg, stream) {
         console.debug(`announce: prefix=${msg.prefix}`);
-        // Send initial announcements
-        let active = new Set();
-        const broadcasts = this.#broadcasts.peek();
-        if (!broadcasts)
-            return; // closed
-        for (const name of broadcasts.keys()) {
-            const suffix = Path.stripPrefix(msg.prefix, name);
-            if (suffix === null)
-                continue;
-            console.debug(`announce: broadcast=${name} active=true`);
-            active.add(suffix);
-        }
+        // Keyed by suffix, valued by identity plus route, so a republish diffs as
+        // ended-then-active and a re-price as a restart.
+        let active = new Map();
         // Lite06+: announce ids. Every active we send implicitly assigns the next
-        // per-stream ordinal; ended references the id instead of repeating the path.
+        // per-stream ordinal; ended/restart reference the id instead of repeating the path.
         let nextAnnounceId = 0n;
         const announceIds = new Map();
-        switch (this.version) {
-            case Version.DRAFT_01:
-            case Version.DRAFT_02: {
-                const init = new AnnounceInit([...active]);
-                await init.encode(stream.writer, this.version);
-                break;
+        const wireHops = (route) => {
+            if (hasAnnounceOk(this.version))
+                return route.hops;
+            return [...route.hops, this.hop];
+        };
+        // What the peer decodes for a route: pre-lite-06 wires carry no cost, so a re-price
+        // there must not restart.
+        const onWire = (route) => (hasRouteCost(this.version) ? route : { ...route, cost: Cost.zero });
+        const announce = async (suffix, route) => {
+            console.debug(`announce: broadcast=${suffix} active=true`);
+            if (hasAnnounceId(this.version))
+                announceIds.set(suffix, nextAnnounceId++);
+            await encodeAnnounceBroadcast(stream.writer, { status: "active", suffix, hops: wireHops(route), cost: route.cost }, this.version);
+        };
+        const restart = async (suffix, route) => {
+            if (!hasAnnounceId(this.version)) {
+                await retract(suffix);
+                await announce(suffix, route);
+                return;
+            }
+            const id = announceIds.get(suffix);
+            if (id === undefined) {
+                await announce(suffix, route);
+                return;
             }
-            default: {
-                if (!hasAnnounceOk(this.version)) {
-                    // Draft03/04: send individual Announce messages, stamping our origin as a hop.
-                    for (const suffix of active) {
-                        await encodeAnnounceBroadcast(stream.writer, { status: "active", suffix, hops: [this.origin] }, this.version);
+            console.debug(`announce: broadcast=${suffix} restart=true`);
+            await encodeAnnounceBroadcast(stream.writer, { status: "restart", id, hops: wireHops(route), cost: route.cost }, this.version);
+        };
+        // Lite06+ retracts by announce id; older versions repeat the path (ended announces
+        // don't need hops).
+        const retract = async (suffix) => {
+            console.debug(`announce: broadcast=${suffix} active=false`);
+            if (!hasAnnounceId(this.version)) {
+                await encodeAnnounceBroadcast(stream.writer, { status: "ended", suffix }, this.version);
+                return;
+            }
+            const id = announceIds.get(suffix);
+            announceIds.delete(suffix);
+            if (id === undefined)
+                return; // never announced
+            await encodeAnnounceBroadcast(stream.writer, { status: "endedId", id }, this.version);
+        };
+        // Subscribe BEFORE writing anything: every encode below awaits the wire, and a publish
+        // landing in that window only notifies the listeners already registered. One created
+        // afterwards would sleep through it, leaving the change unannounced until something
+        // unrelated moved.
+        // TODO Make a better helper within Signals.
+        let dispose;
+        let changed = new Promise((resolve) => {
+            dispose = this.#advertised.changed(resolve);
+        });
+        // A hidden route stays off the wire unless the request opted in.
+        const carries = (covered) => msg.hidden || !hiddenBelow(msg.prefix, covered);
+        try {
+            const initial = this.#advertised.peek();
+            if (!initial)
+                return; // closed
+            for (const [name, snap] of presented(msg.prefix, initial, carries)) {
+                active.set(name, snap);
+            }
+            switch (this.version) {
+                case Version.DRAFT_01:
+                case Version.DRAFT_02: {
+                    for (const suffix of active.keys()) {
+                        console.debug(`announce: broadcast=${suffix} active=true`);
                     }
+                    const init = new AnnounceInit([...active.keys()]);
+                    await init.encode(stream.writer, this.version);
                     break;
                 }
-                // Report our origin id once via AnnounceOk and the count of initial announces
-                // that follow; the subscriber stamps our origin onto each hop chain, so we omit it.
-                const ok = new AnnounceOk(this.origin, active.size);
-                await ok.encode(stream.writer, this.version);
-                for (const suffix of active) {
-                    if (hasAnnounceId(this.version)) {
-                        announceIds.set(suffix, nextAnnounceId++);
+                default: {
+                    if (!hasAnnounceOk(this.version)) {
+                        for (const [suffix, snap] of active) {
+                            await announce(suffix, snap.route);
+                        }
+                        break;
+                    }
+                    const ok = new AnnounceOk(this.hop, active.size);
+                    await ok.encode(stream.writer, this.version);
+                    for (const [suffix, snap] of active) {
+                        await announce(suffix, snap.route);
                     }
-                    await encodeAnnounceBroadcast(stream.writer, { status: "active", suffix, hops: [] }, this.version);
+                    break;
                 }
-                break;
             }
-        }
-        // Wait for updates to the broadcasts.
-        for (;;) {
-            // TODO Make a better helper within Signals.
-            let dispose;
-            const changed = new Promise((resolve) => {
-                dispose = this.#broadcasts.changed(resolve);
-            });
-            // Wait until the map of broadcasts changes.
-            const broadcasts = await Promise.race([changed, stream.reader.closed]);
-            dispose();
-            if (!broadcasts)
-                break;
-            // Create a new set of active broadcasts.
-            // This is SLOW, but it's not worth optimizing because we often have just 1 broadcast anyway.
-            const newActive = new Set();
-            for (const name of broadcasts.keys()) {
-                const suffix = Path.stripPrefix(msg.prefix, name);
-                if (suffix === null)
-                    continue; // Not our prefix.
-                newActive.add(suffix);
-            }
-            // Announce any new broadcasts. Lite05+ reports our origin once via AnnounceOk, so
-            // the subscriber stamps it onto each hop chain; older versions stamp it here.
-            for (const added of newActive.difference(active)) {
-                console.debug(`announce: broadcast=${added} active=true`);
-                const hops = hasAnnounceOk(this.version) ? [] : [this.origin];
-                if (hasAnnounceId(this.version)) {
-                    announceIds.set(added, nextAnnounceId++);
+            for (;;) {
+                const advertised = await race([changed, stream.reader.closed]);
+                dispose();
+                if (!advertised)
+                    break;
+                // Re-arm before reading, so an advertise that lands while we write is not lost.
+                changed = new Promise((resolve) => {
+                    dispose = this.#advertised.changed(resolve);
+                });
+                const latest = this.#advertised.peek();
+                if (!latest)
+                    break;
+                const updated = new Map();
+                for (const [name, snap] of presented(msg.prefix, latest, carries)) {
+                    updated.set(name, snap);
                 }
-                await encodeAnnounceBroadcast(stream.writer, { status: "active", suffix: added, hops }, this.version);
-            }
-            // Announce any removed broadcasts. Lite06+ retracts by announce id;
-            // older versions repeat the path (ended announces don't need hops).
-            for (const removed of active.difference(newActive)) {
-                console.debug(`announce: broadcast=${removed} active=false`);
-                if (hasAnnounceId(this.version)) {
-                    const id = announceIds.get(removed);
-                    announceIds.delete(removed);
-                    if (id === undefined)
-                        continue; // never announced
-                    await encodeAnnounceBroadcast(stream.writer, { status: "endedId", id }, this.version);
+                for (const [suffix, snap] of active) {
+                    const cur = updated.get(suffix);
+                    if (!cur || cur.identity !== snap.identity)
+                        await retract(suffix);
                 }
-                else {
-                    await encodeAnnounceBroadcast(stream.writer, { status: "ended", suffix: removed }, this.version);
+                for (const [suffix, snap] of updated) {
+                    const prev = active.get(suffix);
+                    if (!prev || prev.identity !== snap.identity) {
+                        await announce(suffix, snap.route);
+                    }
+                    else if (!routesEqual(onWire(prev.route), onWire(snap.route))) {
+                        await restart(suffix, snap.route);
+                    }
                 }
+                active = updated;
             }
-            // NOTE: This is kind of a hack that won't work with a rapid UNANNOUNCE/ANNOUNCE cycle.
-            // However, our client doesn't do that anyway.
-            active = newActive;
+        }
+        finally {
+            dispose();
         }
     }
     /**
@@ -210,27 +402,37 @@ export class Publisher {
      * @internal
      */
     async runSubscribe(msg, stream) {
-        const broadcast = this.#broadcasts.peek()?.get(msg.broadcast);
-        if (!broadcast) {
+        let front;
+        try {
+            front =
+                this.#publish &&
+                    (wireOf(this.#publish).local(msg.broadcast) ?? (await wireOf(this.#publish).demand(msg.broadcast)));
+        }
+        catch (err) {
+            stream.writer.reset(error(err));
+            return;
+        }
+        if (!front) {
             console.debug(`publish unknown: broadcast=${msg.broadcast}`);
-            stream.writer.reset(new Error("not found"));
+            stream.writer.reset(new NotFound(`broadcast ${msg.broadcast}`));
             return;
         }
-        const track = broadcast.subscribe(msg.track, {
+        const endGroup = exclusiveGroupEnd(msg.endGroup);
+        const track = wireOf(front).subscribe(msg.track, {
             priority: msg.priority,
-            ordered: msg.ordered,
-            latencyMax: msg.maxLatency,
-            startGroup: msg.startGroup,
-            endGroup: msg.endGroup,
+            maxAge: Milli(servingMaxAge(this.version, msg.maxAge)),
+            groups: {
+                start: msg.startGroup === undefined ? undefined : { included: msg.startGroup },
+                end: endGroup === undefined ? undefined : { excluded: endGroup },
+            },
         });
-        const startGroup = msg.startGroup ?? track.latest();
-        if (startGroup !== undefined)
-            track.startAt(startGroup);
-        track.endAt(msg.endGroup);
+        positionCursor(track, this.version, msg.startGroup);
+        hooks.replaceGroups(track, { end: endGroup === undefined ? undefined : { excluded: endGroup } });
         // The best-effort datagram loop, started once serving begins. It parks when the
         // track finishes (recvDatagram returns undefined), so #runTrack alone ends the
         // subscription; awaited during teardown so it doesn't outlive the subscription.
         let datagrams = Promise.resolve();
+        let controls;
         try {
             let timescale = Timescale.MILLI;
             if (supportsTrackStream(this.version)) {
@@ -250,51 +452,57 @@ export class Publisher {
                 // Older drafts acknowledge with SUBSCRIBE_OK and stream frames verbatim.
                 const ok = new SubscribeOk({
                     priority: msg.priority,
-                    ordered: msg.ordered,
-                    maxLatency: msg.maxLatency,
+                    maxAge: msg.maxAge,
                     startGroup: msg.startGroup,
                     endGroup: msg.endGroup,
                 });
                 await encodeSubscribeResponse(stream.writer, { ok }, this.version);
             }
             console.debug(`publish ok: broadcast=${msg.broadcast} track=${track.name}`);
-            const serving = this.#runTrack(msg.id, msg.broadcast, track, stream.writer, timescale);
             // Serve datagrams concurrently with groups whenever the transport carries them
             // (the writer exists iff so). No group fallback: otherwise they simply aren't sent.
             if (this.#datagramWriter) {
                 datagrams = this.#runDatagrams(msg.id, track, timescale);
             }
-            for (;;) {
-                const decode = SubscribeUpdate.decodeMaybe(stream.reader, this.version);
-                const result = await Promise.any([serving, decode]);
-                if (!result)
-                    break;
-                if (result instanceof SubscribeUpdate) {
-                    console.debug(`subscribe update: broadcast=${msg.broadcast} track=${track.name}`);
+            controls = new SubscriptionControls({
+                reader: stream.reader,
+                writer: stream.writer,
+                version: this.version,
+                apply: (update) => {
+                    const end = exclusiveGroupEnd(update.endGroup);
                     track.update({
-                        priority: result.priority,
-                        ordered: result.ordered,
-                        latencyMax: result.maxLatency,
-                        startGroup: result.startGroup,
-                        endGroup: result.endGroup,
+                        priority: update.priority,
+                        maxAge: Milli(servingMaxAge(this.version, update.maxAge)),
+                        groups: {
+                            start: update.startGroup === undefined ? undefined : { included: update.startGroup },
+                            end: end === undefined ? undefined : { excluded: end },
+                        },
                     });
-                    if (result.startGroup !== undefined)
-                        track.startAt(result.startGroup);
-                    track.endAt(result.endGroup);
-                }
-            }
+                },
+            });
+            await this.#runTrack(track, stream.writer, controls, {
+                sub: msg.id,
+                broadcast: msg.broadcast,
+                timescale,
+                bounds: {
+                    startGroup: msg.startGroup,
+                    startFrame: msg.startFrame,
+                    endGroup: msg.endGroup,
+                    endFrame: msg.endFrame,
+                },
+            });
             console.debug(`publish done: broadcast=${msg.broadcast} track=${track.name}`);
             stream.close();
             track.close();
-            // track.close ends the datagram loop; wait so it doesn't leak past teardown.
-            await datagrams;
+            // Closing the stream ends the decoder and track.close ends the datagram loop.
+            await Promise.all([datagrams, controls.decoding]);
         }
         catch (err) {
             const e = error(err);
             console.warn(`publish error: broadcast=${msg.broadcast} track=${track.name} error=${reason(e)}`);
             track.close(e);
             stream.abort(e);
-            await datagrams;
+            await Promise.all([datagrams, controls?.decoding]);
         }
     }
     /**
@@ -307,10 +515,19 @@ export class Publisher {
             stream.writer.reset(new Error("fetch requires moq-lite-05 or newer"));
             return;
         }
-        const broadcast = this.#broadcasts.peek()?.get(msg.broadcast);
-        if (!broadcast) {
+        let front;
+        try {
+            front =
+                this.#publish &&
+                    (wireOf(this.#publish).local(msg.broadcast) ?? (await wireOf(this.#publish).demand(msg.broadcast)));
+        }
+        catch (err) {
+            stream.writer.reset(error(err));
+            return;
+        }
+        if (!front) {
             console.debug(`fetch unknown: broadcast=${msg.broadcast}`);
-            stream.writer.reset(new Error("not found"));
+            stream.writer.reset(new NotFound(`broadcast ${msg.broadcast}`));
             return;
         }
         // The subscriber opened this stream, so its send order only ranked the request. Rank the
@@ -318,10 +535,15 @@ export class Publisher {
         stream.writer.setPriority(sendOrder({ priority: msg.priority }));
         let group;
         try {
-            // The timescale is immutable, so serve exactly what TRACK_INFO advertised.
-            const info = await this.#resolveTrackInfo(msg.broadcast, msg.track);
-            group = await broadcast.track(msg.track).fetchGroup(msg.group, { priority: msg.priority });
-            await this.#runFetchGroup(group, stream.writer, Timescale(info.timescale));
+            // The timescale is immutable, so serve exactly what TRACK_INFO advertised. Both
+            // come off the same front, so the metadata and the frames are one generation.
+            const info = await this.#resolveTrackInfo(front, msg.track);
+            group = await wireOf(front).fetchGroup(msg.track, msg.group, { priority: msg.priority });
+            await this.#runFetchGroup(group, stream.writer, {
+                timescale: Timescale(info.timescale),
+                start: msg.startFrame,
+                end: msg.endFrame,
+            });
             console.debug(`fetch done: broadcast=${msg.broadcast} track=${msg.track} group=${msg.group}`);
             stream.close();
             group.close();
@@ -342,70 +564,172 @@ export class Publisher {
      *
      * @internal
      */
-    async #runTrack(sub, broadcast, track, stream, timescale) {
+    async #runTrack(track, stream, controls, serving) {
+        const { sub, broadcast, timescale, bounds } = serving;
         // Lite-05+ resolves the range on the subscribe stream: SUBSCRIBE_START once the
         // first group is known, SUBSCRIBE_END when the track finishes.
         const emitRange = supportsTrackStream(this.version);
         let startSent = false;
-        // The exclusive end of the delivered range. recvGroup is arrival-ordered rather than
-        // sequence-ordered, so this tracks the max and not the last group seen. 0 is already
-        // the encoding for a track that produced no groups.
-        let end = 0;
+        let endSent = false;
+        // Lite-07+ counts the group streams in SUBSCRIBE_END, so it goes out only once every
+        // served group has opened its stream or given up, and a cap holding groups back
+        // delays it until they are released.
+        const countStreams = hasStreamCount(this.version);
+        let streams = 0;
+        const opening = new Set();
+        // The track's exclusive final boundary. A Rust subscriber feeds SUBSCRIBE_END
+        // straight into finish_at, so it must name the track's boundary (which counts
+        // datagram sequences too), not the delivered range: a subscription cap can hold
+        // produced groups back. The latest() fallback covers a subscription torn down
+        // before the producer declared it.
+        const boundary = () => track.final() ?? (track.latest() ?? -1) + 1;
+        // Before lite-07, SUBSCRIBE_END names that boundary, which a cap can hold groups back
+        // from, so it goes out as soon as the producer finishes and the subscription keeps
+        // serving whatever a later cap raise releases (see the Rust publisher's Recv::Boundary).
+        const sendEnd = async () => {
+            endSent = true;
+            if (!emitRange)
+                return true;
+            return controls.response((async () => {
+                // A group that gives up before its stream opens is never counted.
+                if (countStreams)
+                    while (opening.size > 0)
+                        await Promise.all(opening);
+                const end = new SubscribeEnd(boundary(), streams);
+                await encodeSubscribeResponse(stream, { end }, this.version);
+            })());
+        };
         // One ranking for the whole subscription, shared by every group it serves.
         const priority = new Priority(track);
+        // Every group this subscription started serving, until its stream finishes or resets.
+        const groups = new Set();
         // Cancels groups still queued for a stream slot. Only the subscriber leaving counts:
-        // a track that ran out of groups still has to flush the ones already queued, and we
-        // FIN the subscribe stream ourselves below to say so.
+        // a track that ran out of groups still has to flush the ones already queued, and the
+        // caller FINs the subscribe stream to say so.
         let finished = false;
         let unsubscribe;
         const unsubscribed = new Promise((resolve) => {
             unsubscribe = resolve;
         });
-        void stream.closed.then(() => {
-            if (!finished)
-                unsubscribe();
-        }, 
-        // A reset is always the peer.
-        () => unsubscribe());
         try {
             for (;;) {
-                // Exactly-once serving, not the sequence cursor: on a relay, a burst can be
-                // ingested micro-reordered by the upstream leg, and a sequence cursor would
-                // permanently skip the older group even though it is cached and in demand.
-                // Staleness is the latency window's job (cache expiry), not arrival order's.
-                const next = track.recvGroup();
-                const group = await Promise.race([next, stream.closed]);
-                if (!group) {
-                    next.then((group) => group?.close()).catch(() => { });
-                    break;
+                // Control before data, matching the Rust publisher: every control decoded while
+                // the loop was parked applies to the next pop, never to one already made. This
+                // drain is synchronous, so nothing the decoder holds can land between the pop
+                // below and its frame range.
+                const control = controls.take();
+                if (control) {
+                    switch (control.kind) {
+                        case "done":
+                            // The subscriber left. Its queued groups are pointless now, which
+                            // the finally below acts on since `finished` stays false.
+                            return;
+                        case "error":
+                            throw control.error;
+                        case "update": {
+                            const update = control.update;
+                            console.debug(`subscribe update: broadcast=${broadcast} track=${track.name}`);
+                            hooks.replaceGroups(track, {
+                                start: update.startGroup === undefined ? undefined : { included: update.startGroup },
+                                end: update.endGroup === undefined ? undefined : { included: update.endGroup },
+                            });
+                            bounds.startGroup = update.startGroup;
+                            bounds.startFrame = update.startFrame;
+                            bounds.endGroup = update.endGroup;
+                            bounds.endFrame = update.endFrame;
+                            await yieldToControls();
+                            continue;
+                        }
+                    }
+                }
+                // Exactly-once arrival-order serving. This synchronous package-internal pop
+                // and frameRange call are the operation's linearization point.
+                const recv = hooks.tryRecvGroup(track);
+                switch (recv.kind) {
+                    case "error":
+                        throw recv.error;
+                    case "idle":
+                        // Before lite-07, an end declared ahead of the live edge goes out as
+                        // soon as it is known, while the remaining groups are still being
+                        // produced. The lite-07 count is not final until those groups open.
+                        if (!endSent && !countStreams && track.final() !== undefined) {
+                            if (!(await sendEnd()))
+                                return;
+                            continue;
+                        }
+                        await waitForSubscription(controls, track);
+                        continue;
+                    case "boundary":
+                        // The producer finished but is still holding groups above the cap.
+                        // Declare the boundary, then wait for an update to release them.
+                        if (!endSent && !countStreams) {
+                            if (!(await sendEnd()))
+                                return;
+                            continue;
+                        }
+                        await waitForSubscription(controls, track);
+                        continue;
+                    case "done": {
+                        if (!endSent) {
+                            if (!(await sendEnd()))
+                                return;
+                            continue;
+                        }
+                        // The FIN tells the subscriber every group is accounted for, so it waits
+                        // until each group stream finished or reset. The subscriber leaving
+                        // instead cancels whatever is still queued.
+                        const drained = Symbol("drained");
+                        const end = await Promise.race([Promise.all(groups).then(() => drained), controls.ended]);
+                        if (end instanceof Error)
+                            throw end;
+                        if (end !== drained)
+                            return;
+                        finished = true;
+                        return;
+                    }
                 }
+                const group = recv.group;
+                const range = frameRange(bounds, group.sequence);
                 if (emitRange && !startSent) {
                     startSent = true;
                     // SUBSCRIBE_START promises nothing below this sequence will be delivered.
                     // Arrival-order serving could later surface a straggler below the first
                     // group, so pin the floor to what was announced.
-                    track.startAt(group.sequence);
-                    await encodeSubscribeResponse(stream, { start: new SubscribeStart(group.sequence) }, this.version);
+                    hooks.replaceGroups(track, {
+                        start: { included: group.sequence },
+                        end: bounds.endGroup === undefined ? undefined : { included: bounds.endGroup },
+                    });
+                    if (!(await controls.response(encodeSubscribeResponse(stream, { start: new SubscribeStart(group.sequence) }, this.version))))
+                        return;
                 }
-                end = Math.max(end, group.sequence + 1);
-                void this.#runGroup({ sub, group, timescale, priority, unsubscribed });
-            }
-            if (emitRange) {
-                await encodeSubscribeResponse(stream, { end: new SubscribeEnd(end) }, this.version);
+                const options = {
+                    sub,
+                    group,
+                    timescale,
+                    priority,
+                    unsubscribed,
+                    start: range.start,
+                    end: range.end,
+                };
+                // `opening` settles when the stream opens so the lite-07 count can be sent.
+                // `groups` covers the serve too, so the FIN still waits for every stream to
+                // finish or reset, including one that has not opened yet.
+                const opened = this.#openGroup(options);
+                const task = opened.then(async (writer) => {
+                    if (!writer)
+                        return;
+                    streams += 1;
+                    await this.#serveGroup(writer, options);
+                });
+                groups.add(task);
+                void task.finally(() => groups.delete(task));
+                opening.add(opened);
+                void opened.finally(() => opening.delete(opened));
             }
-            console.debug(`publish close: broadcast=${broadcast} track=${track.name}`);
-            finished = true;
-            track.close();
-            stream.close();
-        }
-        catch (err) {
-            const e = error(err);
-            console.warn(`publish error: broadcast=${broadcast} track=${track.name} error=${reason(e)}`);
-            unsubscribe();
-            track.close(e);
-            stream.reset(e);
         }
         finally {
+            if (!finished)
+                unsubscribe();
             priority.close();
         }
     }
@@ -416,7 +740,11 @@ export class Publisher {
      */
     async runTrackInfo(msg, stream) {
         try {
-            const info = await this.#resolveTrackInfo(msg.broadcast, msg.track);
+            const front = this.#publish &&
+                (wireOf(this.#publish).local(msg.broadcast) ?? (await wireOf(this.#publish).demand(msg.broadcast)));
+            if (!front)
+                throw new NotFound(`broadcast ${msg.broadcast}`);
+            const info = await this.#resolveTrackInfo(front, msg.track);
             await info.encode(stream.writer, this.version);
             console.debug(`track info: broadcast=${msg.broadcast} track=${msg.track}`);
             stream.close();
@@ -427,34 +755,33 @@ export class Publisher {
         }
     }
     // Resolve (and cache) a track's immutable TRACK_INFO by asking the application.
-    // `broadcast.track(name).info()` triggers a TrackRequest the app answers with
-    // accept(TrackInfo); only the immutable properties are needed (not the groups).
-    // Cached because they're fixed for the track's lifetime. Rejects if the broadcast
-    // or track is unavailable.
-    #resolveTrackInfo(broadcast, track) {
-        const key = `${broadcast}\0${track}`;
-        const cached = this.#trackInfo.get(key);
-        if (cached)
+    // `resolveTrackInfo` triggers a TrackRequest the app answers with accept(TrackInfo);
+    // only the immutable properties are needed (not the groups). Cached because they're
+    // fixed for the track's lifetime. Rejects if the track is unavailable.
+    #resolveTrackInfo(front, track) {
+        let tracks = this.#trackInfo.get(front);
+        if (!tracks) {
+            tracks = new Map();
+            this.#trackInfo.set(front, tracks);
+        }
+        const cached = tracks.get(track);
+        if (cached !== undefined)
             return cached;
         const pending = (async () => {
-            const published = this.#broadcasts.peek()?.get(broadcast);
-            if (!published)
-                throw new Error("not found");
-            const info = await published.track(track).info();
+            const info = await wireOf(front).resolveTrackInfo(track);
             return new TrackInfoMessage({
                 priority: info.priority,
-                ordered: info.ordered,
-                // Publisher Max Latency: the publisher's retention bound, advertised so
+                // Publisher Max Age: the publisher's retention bound, advertised so
                 // relays re-serve with the same window.
-                latencyMax: info.latencyMax,
+                maxAge: info.maxAge,
                 // Lite05 mandates per-frame timestamps. Advertise the track's timescale;
-                // `#runGroup` emits each frame converted to it.
+                // `#serveGroup` emits each frame converted to it.
                 timescale: info.timescale,
             });
         })();
         // Don't poison the cache on failure: a later request may succeed.
-        pending.catch(() => this.#trackInfo.delete(key));
-        this.#trackInfo.set(key, pending);
+        pending.catch(() => tracks.delete(track));
+        tracks.set(track, pending);
         return pending;
     }
     /**
@@ -475,9 +802,9 @@ export class Publisher {
                 const datagram = await track.recvDatagram();
                 if (!datagram)
                     return; // Track finished; #runTrack tears the subscription down.
-                // Convert the timestamp to the track's advertised timescale, matching #runGroup.
+                // Convert the timestamp to the track's advertised timescale, matching #serveGroup.
                 const ts = Math.round(datagram.timestamp.as(timescale));
-                const body = new DatagramMessage(sub, datagram.sequence, ts, datagram.payload).encode();
+                const body = new DatagramMessage(sub, datagram.sequence, ts, datagram.payload).encode(this.version);
                 // No group fallback: drop anything that doesn't fit a single datagram.
                 if (body.byteLength > maxSize) {
                     console.debug(`dropping oversize datagram: sub=${sub} size=${body.byteLength} max=${maxSize}`);
@@ -494,10 +821,18 @@ export class Publisher {
     }
     // Serialize a fetched group's frames onto the FETCH stream as bare records: each a
     // zigzag-delta timestamp (at the track's advertised timescale) followed by size + bytes.
-    async #runFetchGroup(group, stream, timescale) {
+    async #runFetchGroup(group, stream, { timescale, start: startFrame, end: endFrame }) {
+        // The response carries no header, so the receiver numbers the first frame it gets
+        // as `startFrame`. Skipping the head here is the only thing keeping those numbers
+        // honest; a group that ends before we reach it can't be served at all.
+        for (let i = 0; i < startFrame; i++) {
+            if (!(await race([group.readFrame(), stream.closed]))) {
+                throw new Error(`fetch group ended at frame ${i}, before the requested start ${startFrame}`);
+            }
+        }
         let prevTs = 0n;
-        for (;;) {
-            const frame = await Promise.race([group.readFrame(), stream.closed]);
+        for (let index = startFrame; endFrame === undefined || index <= endFrame; index++) {
+            const frame = await race([group.readFrame(), stream.closed]);
             if (!frame)
                 break;
             const ts = BigInt(Math.round(frame.timestamp.as(timescale)));
@@ -508,13 +843,13 @@ export class Publisher {
         }
     }
     /**
-     * Serves one group on its own unidirectional stream.
+     * Opens the unidirectional stream for one group, or closes the group and resolves
+     * `undefined` when it cannot get one.
      *
      * @internal
      */
-    async #runGroup(options) {
-        const { sub, group, timescale, priority, unsubscribed } = options;
-        const msg = new GroupMessage(sub, group.sequence);
+    async #openGroup(options) {
+        const { group, priority, unsubscribed } = options;
         try {
             // The transport drains streams by send order, so this is what makes a high-priority
             // track (and a newer group within it) win the link when there isn't room for both.
@@ -524,55 +859,92 @@ export class Publisher {
             // in the order we asked, which is oldest-first, exactly backwards for live media.
             // Failing here drops the group and lets the next one compete for the next slot.
             const stream = await Writer.tryOpen(this.#quic, {
+                version: this.version,
                 sendOrder: priority.rank(group.sequence),
                 cancel: unsubscribed,
                 waitUntilAvailable: false,
             });
-            if (!stream) {
+            if (!stream)
                 group.close(new Error("no stream slot"));
-                return;
-            }
-            // Everything past this point runs inside the cleanup scope, so a failure never leaves
-            // a finished group's stream being ranked.
-            try {
-                // A SUBSCRIBE_UPDATE re-ranks the subscription, so a group already on the wire
-                // follows it too rather than keeping a stale rank until it finishes.
-                priority.add(stream, group.sequence);
+            return stream;
+        }
+        catch (err) {
+            group.close(error(err));
+            return undefined;
+        }
+    }
+    /**
+     * Serves one group on the stream {@link #openGroup} opened for it.
+     *
+     * @internal
+     */
+    async #serveGroup(stream, options) {
+        const { sub, group, timescale, priority, start: startFrame, end: endFrame } = options;
+        // This model holds whole groups, so frame `startFrame` is always reachable unless
+        // the group ends first. Declaring it up front keeps the stream self-describing.
+        const msg = new GroupMessage({ subscribe: sub, sequence: group.sequence, frameStart: startFrame });
+        // Everything past this point runs inside the cleanup scope, so a failure never leaves
+        // a finished group's stream being ranked.
+        try {
+            // A SUBSCRIBE_UPDATE re-ranks the subscription, so a group already on the wire
+            // follows it too rather than keeping a stale rank until it finishes.
+            priority.add(stream, group.sequence);
+            await hooks.guardGroup(group, async () => {
                 await stream.u53(0); // stream type
-                await msg.encode(stream);
-                // Lite05+ prefixes every frame with a zigzag-delta timestamp at the track's
-                // advertised timescale; older drafts omit it.
-                const timestamps = supportsTrackStream(this.version);
-                let prevTs = 0n;
-                for (;;) {
-                    const frame = await Promise.race([group.readFrame(), stream.closed]);
-                    if (!frame)
+                await msg.encode(stream, this.version);
+            });
+            // Lite05+ prefixes every frame with a zigzag-delta timestamp at the track's
+            // advertised timescale; older drafts omit it.
+            const timestamps = supportsTrackStream(this.version);
+            let prevTs = 0n;
+            // Whether the cursor ever reached the requested start, which decides how the
+            // end of the group is read below.
+            let reached = startFrame === 0;
+            for (;;) {
+                const read = await race([hooks.readGroupFrame(group), stream.closed]);
+                if (!read) {
+                    // The group ended before the frame the subscriber asked to start
+                    // at, so this publisher can't serve the range at all. FINning here
+                    // would claim an empty group under that index; reset so it reads
+                    // as the gap it is.
+                    if (!reached)
+                        throw new Error(`group ended before frame ${startFrame}`);
+                    break;
+                }
+                try {
+                    // A group that ends exactly at the start is a valid, empty range.
+                    if (read.sequence + 1 >= startFrame)
+                        reached = true;
+                    // Frames below the requested start were excluded, and the receiver
+                    // numbers what it gets from `startFrame`.
+                    if (read.sequence < startFrame)
+                        continue;
+                    if (endFrame !== undefined && read.sequence > endFrame)
                         break;
                     if (timestamps) {
                         // Convert each frame to the track's advertised timescale.
-                        const ts = BigInt(Math.round(frame.timestamp.as(timescale)));
-                        await stream.u62(zigzag(ts - prevTs));
+                        const ts = BigInt(Math.round(read.frame.timestamp.as(timescale)));
+                        await hooks.guardGroup(group, () => stream.u62(zigzag(ts - prevTs)));
                         prevTs = ts;
                     }
-                    await stream.u53(frame.payload.byteLength);
-                    await stream.write(frame.payload);
+                    await hooks.guardGroup(group, () => stream.u53(read.frame.payload.byteLength));
+                    await hooks.guardGroup(group, () => stream.write(read.frame.payload));
+                }
+                finally {
+                    read.complete();
                 }
-                stream.close();
-                group.close();
-            }
-            catch (err) {
-                const e = error(err);
-                stream.reset(e);
-                group.close(e);
-            }
-            finally {
-                priority.remove(stream);
             }
+            stream.close();
+            group.close();
         }
         catch (err) {
             const e = error(err);
+            stream.reset(e);
             group.close(e);
         }
+        finally {
+            priority.remove(stream);
+        }
     }
     /**
      * Handles a probe stream by periodically reporting estimated bitrate.
@@ -605,7 +977,7 @@ export class Publisher {
         try {
             for (;;) {
                 const timeout = new Promise((resolve) => setTimeout(() => resolve("timeout"), PROBE_INTERVAL));
-                const result = await Promise.race([timeout, stream.reader.closed]);
+                const result = await race([timeout, stream.reader.closed]);
                 if (result !== "timeout")
                     break;
                 // The two fields are independent on the wire, each using 0 for
@@ -658,12 +1030,8 @@ export class Publisher {
         }
     }
     close() {
-        this.#broadcasts.update((broadcasts) => {
-            for (const broadcast of broadcasts?.values() ?? []) {
-                broadcast.close();
-            }
-            return undefined;
-        });
+        // The broadcasts belong to the origin, which outlives this session; closing here
+        // only drops the borrow. The peer sees the unannounce when the streams die.
         // Release the datagram writer's lock so the stream can be torn down.
         this.#datagramWriter?.releaseLock();
         this.#datagramWriter = undefined;