@blockcast/mmt-container 2.2.0-main.c4fa878f4ff4 → 2.2.0-main.e75bbd7576a6

package/src/mmtp-router.ts

@@ -24,7 +24,7 @@ import {
   type MoqRepairFrame,
 } from "@blockcast/mmt-base";
 import { USER_AGENT_VERIFIED } from "@blockcast/mmt-transport";
-import type { FECManager, IsoHeldSource, WasmFecDecoder } from "./fec-manager.js";
+import type { FECManager, IsoHeldSource, RebuiltSourceFeed, WasmFecDecoder } from "./fec-manager.js";
 import type { IsoPlacedSource, IsoRepairPlacement } from "./iso-block-locator.js";
 import { isMfuReassemblyError } from "./mfu-reassembler.js";
 import type {
@@ -48,10 +48,12 @@ import {
 } from "./cmaf-block-assembler.js";
 import {
   MmtpContainerParser,
+  authoredAdjacent,
   isMfuKeyframeMetadata,
   type FecReleaseGate,
   type FrameMeta as ParserFrameMeta,
   type ParsedMmtpPacket,
+  type MmtpRecoveredHeadTimingStats,
 } from "./mmtp-container-parser.js";
 import { type TrackRole } from "./carp-catalog.js";
 import {
@@ -212,6 +214,90 @@ export interface KeyframeOverlayStats {
   restarts: number;
   unsequencedDropped: number;
   protectedDropped: number;
+  /** Rebuilt packets fed to their base block's decoder (joint decoding). */
+  baseFed: number;
+  /** Rebuilt packets the base never took: no base SS_ID could be determined. */
+  baseUndetermined: number;
+}
+
+/**
+ * The newest received overlay member of one MPU. `psnOffset` (overlay SS_ID
+ * minus wire packet_sequence_number) restores a rebuilt packet's wire
+ * sequence; the member's own SS_IDs anchor a rebuilt packet's base SS_ID
+ * (overlayBaseSsId).
+ */
+interface OverlayMemberAnchor {
+  readonly psnOffset: number;
+  readonly overlaySsId: number;
+  /** The member's base SS_ID, from its Source FEC Payload ID. */
+  readonly baseSsId?: number;
+}
+
+/**
+ * The base SS_ID of a packet the overlay rebuilt at `overlaySsId`, which an
+ * overlay coordinate alone never yields (draft-ramadan-moq-mmt-02 7.1). Both
+ * SS_IDs advance by one per packet along a run of consecutive overlay
+ * members, so base minus overlay SS_ID is the anchor's along a run the wire
+ * proves to be all members: one over which the rebuilt packet's protected
+ * packet_sequence_number (`headerPsn`) advanced from the anchor's exactly as
+ * the overlay SS_ID did (`restoredPsn`), so no other packet lies inside it.
+ * A hop that re-stamped packet_sequence_number after protection fails the
+ * test. Undefined when it fails.
+ */
+function overlayBaseSsId(
+  anchor: OverlayMemberAnchor,
+  overlaySsId: number,
+  restoredPsn: number,
+  headerPsn: number,
+): number | undefined {
+  if (anchor.baseSsId === undefined || headerPsn !== restoredPsn) return undefined;
+  return serial32Add(anchor.baseSsId, (overlaySsId - anchor.overlaySsId) | 0);
+}
+
+/**
+ * The base SS_ID of a rebuilt packet no received member of its MPU anchors,
+ * from its protected packet_sequence_number (`headerPsn`). SS_ID advances by
+ * one per FEC source packet (mmt-02 7.1) and psn by one per packet, so on a
+ * track whose every packet is an FEC source packet the sender keeps
+ * SS_ID - psn fixed. `offset` (SS_ID - psn of the stream's latest received
+ * source) is that sender value while a base recovery showed it
+ * (`unstampedOffset`): a recovered packet's header psn equal to its SS_ID
+ * minus the same offset. A hop that re-stamps psn moves the offset away from
+ * the one shown, which voids it, as does a packet with no SS_ID between the
+ * recovered packet that showed it and the latest received source (the shown
+ * span). Undefined without both.
+ * ponytail: exact only if every packet from the rebuilt one to the latest
+ * received source is an FEC source packet, as FFmpeg's muxer sends a track
+ * it protects. fec-core 8.3 lets a publisher leave one unprotected
+ * (FEC Type 0): outside the shown span it goes unseen, and each one puts the
+ * rebuilt packet a base slot off. If such a publisher appears, have mmt-02
+ * require FEC Type 1 across a protected track, or refuse a headerPsn outside
+ * the shown span.
+ */
+function unstampedBaseSsId(
+  offset: number | undefined,
+  unstampedOffset: number | undefined,
+  headerPsn: number,
+): number | undefined {
+  if (offset === undefined || offset !== unstampedOffset) return undefined;
+  return (headerPsn + offset) >>> 0;
+}
+
+/** Base SS_IDs of overlay-routed packets kept per stream (see OverlayToBase). */
+const OVERLAY_ROUTED_LIMIT = 1024;
+/** Rebuilt sources kept per stream for a base block no repair stated yet. */
+const OVERLAY_PENDING_LIMIT = 256;
+
+/**
+ * One stream's keyframe-overlay recoveries on their way into its base
+ * decoder (joint decoding, BLO-52085).
+ */
+interface OverlayToBase {
+  /** Base SS_IDs of the packets an overlay recovery routed (as media, or held
+   *  for their FT=1): a base recovery does not route them a second time. */
+  readonly routed: Set<number>;
+  /** Rebuilt sources, by base SS_ID, whose base block no repair stated yet. */
+  readonly pending: Map<number, Uint8Array>;
 }
 
 interface OverlayInstance {
@@ -223,8 +309,8 @@ interface OverlayInstance {
   readonly k: number;
   /** The newest overlay symbol seen: its overlay SS_ID and wire sequence. */
   last?: { ssId: number; psn: number };
-  /** MPU sequence number → overlay SS_ID − wire packet_sequence_number. */
-  readonly offsets: Map<number, number>;
+  /** MPU sequence number → its newest received member. */
+  readonly offsets: Map<number, OverlayMemberAnchor>;
   /** Overlay blocks a MoQ symbol fed (multicast-02 7.2.7). */
   readonly moqBlocks: Set<number>;
 }
@@ -511,6 +597,9 @@ export type RoutedPacketMeta = {
   mmtpTimestamp: bigint;
   /**
    * The MMTP header RAP flag: the packet starts a random access point. On a
+   * track under a keyframe overlay it is also set on the FT=0 and FT=1 data
+   * units that govern a covered keyframe (draft-ramadan-moq-mmt-02 7.4.2), so
+   * it can precede the keyframe's first MFU fragment. On a
    * `recovered` packet it is read from the FEC-reconstructed header, which is
    * byte-exact outside packet_sequence_number, so it is the flag the
    * publisher sent. The router's own gap decisions deliberately ignore it for
@@ -574,6 +663,7 @@ interface StreamLedgers {
    *   the pair.
    */
   readonly duplicates: StreamDuplicateLedgers;
+  readonly overlayToBase: OverlayToBase;
 }
 
 const NO_FEC_MANAGER_HORIZON: DuplicateHorizon = Object.freeze({
@@ -661,6 +751,17 @@ export interface FECManagerLike {
     catalogTrackName?: string,
   ): Uint8Array | null;
 
+  /** Feed a source another FEC instance over the same packets rebuilt (a
+   *  keyframe overlay) to its base block, which a repair must already have
+   *  stated; not a network arrival (FECManager.feedRebuiltSourceSymbol).
+   *  Optional: without it the overlay and the base decode apart. */
+  feedRebuiltSourceSymbol?(
+    packetId: number,
+    ssId: number,
+    symbolData: Uint8Array,
+    catalogTrackName?: string,
+  ): RebuiltSourceFeed;
+
   /** How long ago the stream's oldest open block with an FEC deadline took its first symbol (optional). */
   oldestOpenBlockAgeMs?(packetId: number, catalogTrackName: string): number | undefined;
 
@@ -976,6 +1077,7 @@ export class MmtpRouter {
   readonly #provenance = new Map<string, ProvenanceEntry>();
   #onFlowProtected: ((flow: string) => void) | null = null;
   #unadmittedListedDrops = 0;
+  #admittedSourceDatagrams = 0;
   #unlistedRepairSetAside = 0;
   readonly #assistBlocks = new Map<string, AssistBlock>();
   readonly #assistFailures = new Map<string, number>();
@@ -1044,6 +1146,15 @@ export class MmtpRouter {
    * sequence is its SS_ID minus this; see #routeProcessedFecSymbols.
    */
   #ssIdSeqOffsetByStream = new Map<string, number>();
+  /**
+   * Per stream, the SS_ID offset at which a base recovery last showed the
+   * sender's own packet_sequence_number: a recovered packet's header psn
+   * equal to its SS_ID minus that offset. While it equals the stream's
+   * current offset, no hop re-stamps the stream, and a packet's protected psn
+   * names its base SS_ID within unstampedBaseSsId's limits (joint decoding of
+   * an MPU no member of which arrived).
+   */
+  #unstampedSsIdSeqOffsetByStream = new Map<string, number>();
   /**
    * Streams whose multicast leg delivered a RAP-flagged source packet that was
    * not parsed, typically because its overlap copy was parsed first
@@ -1121,7 +1232,7 @@ export class MmtpRouter {
   #restampedStreams = new Set<string>();
   #overlayStats: KeyframeOverlayStats = {
     repairDropped: 0, ownerRefused: 0, recovered: 0, restarts: 0,
-    unsequencedDropped: 0, protectedDropped: 0,
+    unsequencedDropped: 0, protectedDropped: 0, baseFed: 0, baseUndetermined: 0,
   };
   /** Callback fired when a delta-track FEC block completes or fails. */
   #onDeltaBlockCompleteCb:
@@ -1400,7 +1511,7 @@ export class MmtpRouter {
     const cb = this.#getFrameCallback(packetId);
     if (isVideo && !assembler) {
       if (frameMeta.recovered) {
-        this.#routeDirectRecoveredVideo(packetId, data, frameMeta, cb);
+        this.#routeDirectRecoveredVideo(packetId, data, frameMeta, cb, meta.fecSbn);
       } else {
         this.#routeDirectSourceVideo(packetId, data, frameMeta, cb);
       }
@@ -1915,6 +2026,11 @@ export class MmtpRouter {
     return { ...this.#overlayStats };
   }
 
+  /** Recovered FT=2 heads held for their FT=1, and how each left the wait (BLO-53369). */
+  get recoveredHeadsAwaitingTiming(): Readonly<MmtpRecoveredHeadTimingStats> {
+    return this.#parser.recoveredHeadsAwaitingTiming;
+  }
+
   #isOverlayRepair(repairPacketId: number, repairTrackName?: string): boolean {
     return this.#overlayLegs.has(repairPacketId) ||
       (repairTrackName !== undefined && this.#overlayRepairNames.has(repairTrackName));
@@ -1966,6 +2082,13 @@ export class MmtpRouter {
    */
   resetKeyframeOverlays(sourcePacketId: number, catalogTrackName?: string): void {
     for (const inst of this.#overlaysForSource(sourcePacketId, catalogTrackName)) this.#resetOverlay(inst);
+    // The base restarted with it: base SS_IDs kept for joint decoding name
+    // the old epoch's packets.
+    for (const [name, stream] of this.#streams.get(sourcePacketId) ?? []) {
+      if (catalogTrackName !== undefined && name !== catalogTrackName) continue;
+      stream.overlayToBase.routed.clear();
+      stream.overlayToBase.pending.clear();
+    }
   }
 
   #resetOverlay(inst: OverlayInstance): void {
@@ -2043,7 +2166,8 @@ export class MmtpRouter {
    * A source packet that carries a 0x8B01 overlay SS_ID is also a symbol of
    * every overlay installed for its source, at that SS_ID, with the bytes the
    * base protects: the packet minus its 4-byte SS_ID trailer, extension
-   * included (7.1, 7.4.3).
+   * included (7.1, 7.4.3). `baseSsId` is that trailer's SS_ID, when the base
+   * FEC reads it.
    */
   #feedOverlaySource(
     packetId: number,
@@ -2053,6 +2177,7 @@ export class MmtpRouter {
     sequenceNumber: number,
     rapFlag: boolean,
     source: MmtpSourcePath,
+    baseSsId: number | undefined,
   ): void {
     if (this.#overlays.size === 0) return;
     const ssId = keyframeOverlaySsId(header);
@@ -2061,8 +2186,22 @@ export class MmtpRouter {
       this.#noteOverlaySsId(inst, ssId, sequenceNumber);
       const identity = MmtpContainerParser.sourcePacketIdentity(packet, header);
       if (identity !== null) {
+        // The newest member anchors its MPU; one with no base SS_ID leaves the
+        // MPU no base anchor rather than keep an older member's. A member that
+        // is no FEC source packet of the base takes an overlay SS_ID and a psn
+        // but no base SS_ID, so past it an older anchor would put each rebuilt
+        // packet one base slot high, and overlayBaseSsId's psn test would pass
+        // it. That costs a conforming stream nothing: every member carries the
+        // base trailer (7.4.3), unread only while the base track is
+        // unconfigured (fecUnreadable), which joint decoding skips, and a base
+        // release (MulticastManager) resets or removes the overlay, so no
+        // readable member precedes an unread one in its MPU.
         inst.offsets.delete(identity.mpuSequenceNumber);
-        inst.offsets.set(identity.mpuSequenceNumber, (ssId - sequenceNumber) >>> 0);
+        inst.offsets.set(identity.mpuSequenceNumber, {
+          psnOffset: (ssId - sequenceNumber) >>> 0,
+          overlaySsId: ssId,
+          ...(baseSsId === undefined ? {} : { baseSsId }),
+        });
         if (inst.offsets.size > OVERLAY_OFFSET_MPUS) inst.offsets.delete(inst.offsets.keys().next().value!);
       }
       const { fec, repairPacketId: pid, streamName: name } = inst;
@@ -2149,18 +2288,35 @@ export class MmtpRouter {
     const streamKey = this.#mediaStreamKey(sourcePacketId, sourceName);
     const restamped = this.#restampedStreams.has(streamKey);
     const restored = new Set<number>();
+    const baseSsIds = new Map<ProcessFecBlockResult["symbols"][number], number>();
     const symbols = result.symbols.flatMap((sym) => {
-      const offset = inst.offsets.get(sym.fragment.mpuSequenceNumber);
-      if (offset !== undefined) {
-        const packetSequenceNumber = (serial32Add(blockStart, sym.index) - offset) >>> 0;
+      const anchor = inst.offsets.get(sym.fragment.mpuSequenceNumber);
+      if (anchor !== undefined) {
+        const overlaySsId = serial32Add(blockStart, sym.index);
+        const packetSequenceNumber = (overlaySsId - anchor.psnOffset) >>> 0;
         restored.add(packetSequenceNumber);
-        return [{ ...sym, packetSequenceNumber }];
+        const out = { ...sym, packetSequenceNumber };
+        const baseSsId = overlayBaseSsId(anchor, overlaySsId, packetSequenceNumber, sym.packetSequenceNumber);
+        if (baseSsId !== undefined) baseSsIds.set(out, baseSsId);
+        return [out];
       }
       // A stream re-stamped by a bridge that no base recovery has shown yet
       // keeps the header's sequence too: from received packets alone the
       // router cannot tell (their psn is the wire one). Base recovery or a
       // FETCH still covers such a keyframe.
-      if (!restamped) return [sym];
+      if (!restamped) {
+        // No member of this MPU arrived to anchor a base SS_ID. A base
+        // recovery that showed the stream unstamped at its current offset
+        // determines one from the packet's protected psn instead
+        // (unstampedBaseSsId).
+        const baseSsId = unstampedBaseSsId(
+          this.#ssIdSeqOffsetByStream.get(streamKey),
+          this.#unstampedSsIdSeqOffsetByStream.get(streamKey),
+          sym.packetSequenceNumber,
+        );
+        if (baseSsId !== undefined) baseSsIds.set(sym, baseSsId);
+        return [sym];
+      }
       this.#overlayStats.unsequencedDropped++;
       return [];
     });
@@ -2170,6 +2326,98 @@ export class MmtpRouter {
     });
     this.#noteOverlayRecoveredRaps(sourcePacketId, sourceName, streamKey, symbols.filter((sym) =>
       restored.has(sym.packetSequenceNumber)));
+    this.#feedOverlayRecoveredToBase(inst, blockStart, symbols, baseSsIds);
+  }
+
+  /**
+   * Joint decoding (BLO-52085). A packet the overlay rebuilt is a source of
+   * its base block too, once its base SS_ID is determined (overlayBaseSsId,
+   * from a received member of its MPU, else unstampedBaseSsId),
+   * so it is fed to the base decoder as a rebuilt source
+   * (FECManager.feedRebuiltSourceSymbol): the base block has one erasure
+   * fewer to solve, and its repair can recover the block's other packets.
+   * A base block no repair has stated yet takes it when one does
+   * (#feedPendingRebuilt).
+   *
+   * The overlay route already handled each packet fed (delivered it, or
+   * held an untimed head for its FT=1), so a base recovery routes none of
+   * them again (#routeVerifiedFecSymbols): a second recovered copy of a
+   * held head would wait in the parser for timing its first copy consumed.
+   * Only an overlay block decoded from multicast symbols alone is fed: with
+   * a MoQ symbol in it, the base block's recovery would depend on bytes
+   * that crossed no multicast socket, which the provenance counted from the
+   * block's own arrivals cannot show.
+   */
+  #feedOverlayRecoveredToBase(
+    inst: OverlayInstance,
+    blockStart: number,
+    symbols: ProcessFecBlockResult["symbols"],
+    baseSsIds: ReadonlyMap<ProcessFecBlockResult["symbols"][number], number>,
+  ): void {
+    const fec = this.#fecManager;
+    const owner = inst.leg.sourcePacketId;
+    const name = inst.leg.sourceCatalogTrackName;
+    if (!fec?.feedRebuiltSourceSymbol || inst.moqBlocks.has(blockStart)) return;
+    if (this.#classifyPacketId(owner) === null || fec.isTrackConfigured?.(owner) === false) return;
+    const { duplicates, overlayToBase: { routed } } = this.#stream(owner, name);
+    const feeds: Array<readonly [number, Uint8Array]> = [];
+    for (const sym of symbols) {
+      // A packet the base received already sits in its block.
+      if (duplicates.sourceSeqs.has(sym.packetSequenceNumber)) continue;
+      const ssId = baseSsIds.get(sym);
+      if (ssId === undefined) {
+        this.#overlayStats.baseUndetermined++;
+        continue;
+      }
+      routed.delete(ssId);
+      routed.add(ssId);
+      if (routed.size > OVERLAY_ROUTED_LIMIT) routed.delete(routed.values().next().value!);
+      feeds.push([ssId, sym.rawSymbol]);
+    }
+    // Any feed can recover the base block, whose routing must already skip
+    // every packet this recovery routed: all are registered before the first.
+    for (const [ssId, symbolData] of feeds) {
+      // A recovery routed above can retire the owner (an in-place switch).
+      if (this.#classifyPacketId(owner) === null) return;
+      this.#feedRebuiltToBase(owner, name, ssId, symbolData);
+    }
+  }
+
+  /** Feed one rebuilt source to its base block, or keep it until a repair states that block. */
+  #feedRebuiltToBase(owner: number, name: string | undefined, ssId: number, symbolData: Uint8Array): void {
+    const fec = this.#fecManager;
+    if (!fec?.feedRebuiltSourceSymbol) return;
+    const coords = fec.locateIsoSource?.(owner, name, ssId);
+    if (coords == null) {
+      const pending = this.#stream(owner, name).overlayToBase.pending;
+      pending.delete(ssId);
+      // Its own copy: the symbol is a view of the whole recovered block.
+      pending.set(ssId, symbolData.slice());
+      if (pending.size > OVERLAY_PENDING_LIMIT) pending.delete(pending.keys().next().value!);
+      return;
+    }
+    const fed = fec.feedRebuiltSourceSymbol(owner, ssId, symbolData, name);
+    if (!fed.taken) return;
+    this.#overlayStats.baseFed++;
+    if (fed.recovered === null) return;
+    const sbn = coords.sbn;
+    this.#routeRecoveredBlock(sbn, fed.recovered, owner, name, () => {
+      fec.cancelBlockTimeout(sbn, owner, name);
+      fec.countRecovery(owner, sbn, name);
+      fec.markBlockCompleted(sbn, owner, name);
+    });
+  }
+
+  /** A repair stated `block`: the rebuilt sources that waited for it join it now. */
+  #feedPendingRebuilt(owner: number, name: string | undefined, block: { start: number; length: number }): void {
+    const pending = this.#streams.get(owner)?.get(name)?.overlayToBase.pending;
+    if (pending === undefined || pending.size === 0) return;
+    for (const [ssId, symbolData] of [...pending]) {
+      if (this.#classifyPacketId(owner) === null) return;
+      if (serial32Distance(block.start, ssId) >= block.length) continue;
+      pending.delete(ssId);
+      this.#feedRebuiltToBase(owner, name, ssId, symbolData);
+    }
   }
 
   /** fec-multicast-00 §6.6: report each base block whose RAP MFU fragments
@@ -2205,6 +2453,9 @@ export class MmtpRouter {
       const mpu = sym.fragment.mpuSequenceNumber;
       if (sym.fragmentType !== 2 || !sym.fragment.rapFlag || !ft0.has(mpu) || !ft1.has(mpu)) continue;
       if (!single.has(mpu) && !(first.has(mpu) && last.has(mpu))) continue;
+      // Not overlayBaseSsId: a wrong sbn only keeps or wrongly stops a keyframe
+      // FETCH (§6.6, a SHOULD; no symbol moves), and wire psn plus offset holds
+      // under a constant re-stamp shift, which overlayBaseSsId's psn test refuses.
       const ssId = (sym.packetSequenceNumber + ssIdSeqOffset) >>> 0;
       // ponytail: a base block no repair has stated yet (an undelimited hole) is not reported.
       const sbn = this.#fecManager?.locateIsoSource?.(packetId, catalogTrackName, ssId)?.sbn;
@@ -2355,6 +2606,11 @@ export class MmtpRouter {
     return this.#unadmittedListedDrops;
   }
 
+  /** Source datagrams (multicast or MoQ) a protected flow's bc-provenance v2 receiver released: admitted at once or held, then admitted by a record. Repair symbols and user-agent-admitted datagrams are not counted. Counted at release, before this router's own track checks: a released datagram those drop, which only a track change between hold and release can cause, still counts, so this is not a count of routed media. */
+  get admittedSourceDatagramCount(): number {
+    return this.#admittedSourceDatagrams;
+  }
+
   /** MoQ repair symbols of an unlisted track kept out of a governed FEC instance (7.2.7 step 2). */
   get unlistedRepairSetAsideCount(): number {
     return this.#unlistedRepairSetAside;
@@ -2989,6 +3245,11 @@ export class MmtpRouter {
     )) return;
     fec.noteBlockActivity?.(blockStart, ownerPacketId, catalogTrackName);
     fec.noteRepairGroupLength?.(blockStart, ownerPacketId, repair.rsbLength, catalogTrackName);
+    // Rebuilt sources that waited for this block join it once the block took
+    // a repair, so it has a deadline; still ahead of the repair, as the held
+    // sources above are.
+    this.#feedPendingRebuilt(ownerPacketId, catalogTrackName, placement.block);
+    if (this.#classifyPacketId(ownerPacketId) === null) return;
     const alreadyCompleted = fec.isBlockCompleted(blockStart, ownerPacketId, catalogTrackName);
     const recovered = fec.feedRepairSymbol(
       ownerPacketId,
@@ -3169,6 +3430,7 @@ export class MmtpRouter {
     this.#droppedPreSyncVideo.delete(streamKey);
     this.#latestVideoSeqByStream.delete(streamKey);
     this.#ssIdSeqOffsetByStream.delete(streamKey);
+    this.#unstampedSsIdSeqOffsetByStream.delete(streamKey);
     this.#multicastRapTwinByStream.delete(streamKey);
     this.#lastDirectSourceVideoTsByStream.delete(streamKey);
     this.#lastDirectEmittedVideoTsByStream.delete(streamKey);
@@ -3928,6 +4190,8 @@ export class MmtpRouter {
     const parsed = this.#parser.parsePacket(packet);
     if (!parsed) return;
     const info = parsed.info;
+    // manifestAdmitted is set only by a receiver release or the user agent's own verification.
+    if (manifestAdmitted && !info.isRepair && ingress?.admittedBy !== USER_AGENT_VERIFIED) this.#admittedSourceDatagrams++;
     // Every multicast packet is a delivery-gap sample, including one dropped
     // below: the gap is a property of the link the FEC deadlines run on, not
     // of which packets this router routes. The re-entry after a manifest
@@ -4391,6 +4655,7 @@ export class MmtpRouter {
       if (!overlapCopy && this.#classifyPacketId(info.packetId) !== null) {
         this.#feedOverlaySource(
           info.packetId, catalogTrackName, packet, parsed.header, info.sequenceNumber, info.rapFlag, source,
+          fecPayloadId?.ssId,
         );
       }
     }
@@ -4619,6 +4884,7 @@ export class MmtpRouter {
       stream = {
         key: JSON.stringify([packetId, catalogTrackName ?? null]),
         duplicates: new StreamDuplicateLedgers(() => this.duplicateHorizonFor(packetId)),
+        overlayToBase: { routed: new Set(), pending: new Map() },
       };
       byName.set(catalogTrackName, stream);
     }
@@ -4817,8 +5083,28 @@ export class MmtpRouter {
     data: Uint8Array,
     meta: RoutedFrameMeta,
     cb: FrameCallback | null,
+    /** The base SS_ID the FEC release gate ordered the frame by, if any. */
+    fecSbn: number | undefined,
   ): void {
     const streamKey = this.#mediaStreamKey(packetId, meta.catalogTrackName);
+    // The FEC release gate let this frame out in order: only once every
+    // block between it and the frame before it resolved, or because it
+    // starts where that frame ended. Nothing still in flight can precede it
+    // then, so it plays now, as a source frame does; holding it for the next
+    // intact frame cost every repaired burst its length in decoder input
+    // (BLO-52085). An overlay recovery names no base block for the gate to
+    // wait on, so past a gap it may be ahead of frames still in flight (an
+    // overlay that outran the wire, BLO-53342): it keeps waiting for the
+    // source cursor below, unless it starts where the last emitted frame
+    // ended (on this direct path, the delivered high water).
+    if (this.#isFecTrack(packetId)) {
+      const high = this.#deliveredVideoHighWaterByStream.get(streamKey);
+      if (fecSbn !== undefined || (high !== undefined && authoredAdjacent(high, meta))) {
+        this.#drainDirectRecoveredVideo(streamKey, packetId, frame => frame.timestamp <= meta.timestamp, cb);
+        this.#emitDirectVideo(packetId, data, meta, cb);
+        return;
+      }
+    }
     this.#enqueueDirectRecoveredVideo(packetId, data, meta);
     const lastSourceTs = this.#lastDirectSourceVideoTsByStream.get(streamKey);
     this.#drainDirectRecoveredVideo(
@@ -5056,6 +5342,17 @@ export class MmtpRouter {
     complete?: () => void,
     assisted = false,
   ): boolean {
+    // A packet a keyframe overlay recovery routed before it fed the packet to
+    // this block (#feedOverlayRecoveredToBase) is not routed again.
+    const overlayRouted = ownerPacketId == null
+      ? undefined
+      : this.#streams.get(ownerPacketId)?.get(catalogTrackName)?.overlayToBase.routed;
+    if (overlayRouted !== undefined && overlayRouted.size > 0) {
+      result = {
+        ...result,
+        symbols: result.symbols.filter((sym) => !overlayRouted.has(this.#fecAnchorForRecovered(blockId, sym.index))),
+      };
+    }
     const entry = ownerPacketId == null ? undefined : this.#provenanceFor(ownerPacketId, catalogTrackName);
     const receiver = entry === undefined || entry === "ambiguous" ? entry : entry.receiver;
     const userAgent = !assisted && entry !== undefined && entry !== "ambiguous" && entry.protected === true && entry.userAgent === true;
@@ -5149,7 +5446,10 @@ export class MmtpRouter {
         ...result,
         symbols: result.symbols.map((sym) => {
           const wire = (this.#fecAnchorForRecovered(blockId, sym.index) - ssIdSeqOffset) >>> 0;
-          if (wire === sym.packetSequenceNumber) return sym;
+          if (wire === sym.packetSequenceNumber) {
+            this.#unstampedSsIdSeqOffsetByStream.set(streamKey, ssIdSeqOffset);
+            return sym;
+          }
           this.#restampedRecoveredSeqs++;
           this.#restampedStreams.add(streamKey);
           return { ...sym, packetSequenceNumber: wire };
@@ -5206,6 +5506,43 @@ export class MmtpRouter {
       );
     }
 
+    // A recovered head whose sample FT=1 has not named yet (an overlay that
+    // outran the source path) would complete its data unit untimed: the unit
+    // is dropped, marked completed, and the timed source copy is then refused
+    // (BLO-53342). Hand it to the parser instead, which holds it in its
+    // awaiting-timing queue and feeds it again when FT=1 lands; its recovered
+    // continuations park in the reassembler meanwhile. If the source path
+    // lost the head, this held copy is the keyframe (BLO-53369).
+    const untimedHead = (sym: (typeof result.symbols)[number]): boolean =>
+      sym.fragmentType === 2 &&
+      sym.fragment.fragmentationIndicator === 1 &&
+      sym.fragment.movieFragmentSequenceNumber !== undefined &&
+      sym.fragment.sampleNumber !== undefined &&
+      !this.#parser.hasAuthoredTimingFor(
+        ownerPacketId,
+        sym.fragment.mpuSequenceNumber,
+        sym.fragment.movieFragmentSequenceNumber,
+        sym.fragment.sampleNumber,
+        catalogTrackName,
+      );
+    for (const sym of result.symbols) {
+      if (!untimedHead(sym) ||
+        this.#sourceSeqReceived(ownerPacketId, sym.packetSequenceNumber, catalogTrackName)) continue;
+      this.#feedViaParser(
+        sym.rawSymbol,
+        { packetId: ownerPacketId, sequenceNumber: sym.packetSequenceNumber },
+        undefined,
+        {
+          skipFecPayloadId: true,
+          recovered: true,
+          deliveryProvenance,
+          ...fecSbnOf(sym.index),
+          ...(catalogTrackName === undefined ? {} : { catalogTrackName }),
+        },
+      );
+    }
+    result = { ...result, symbols: result.symbols.filter((sym) => !untimedHead(sym)) };
+
     // MSE assembler path: route recovered block as pre-assembled frames (skip FT=0)
     // BLO-3035 layer 3: recovered symbols are RAW MFU fragments, not complete
     // frames. A keyframe can span multiple packets (FI=1/2/3); pushing each

package/src/repair-layer-subscriptions.ts

@@ -15,7 +15,10 @@
  * base (`MmtpRouter.feedRepairPacket(..., repairTrackName)`).
  *
  * `stream` delivery means QUIC retransmits: no repair track is ever
- * subscribed (FEC only for unreliable transports).
+ * subscribed (FEC only for unreliable transports). The mode is the source's
+ * `deliveryMode` (`catalogTrackDeliveryMode`); absent is `datagram`. It is
+ * read from the current source, so on a catalog refresh re-feed the updated
+ * source through `switchSource` for a changed `deliveryMode` to take effect.
  *
  * ABR switch R -> R' (`switchSource`): R's subscriptions are closed, the layer
  * count carries to R', and any packet R's subscriptions deliver after the
@@ -35,6 +38,8 @@ export interface RepairLayerSource {
   repairLayers?: readonly RepairLayerParams[]
   /** Keyframe overlays (`TrackFecParams.repairOverlays`); at most one is used. */
   repairOverlays?: readonly RepairOverlayParams[]
+  /** The publisher's MoQ delivery mode; absent is `datagram`. */
+  deliveryMode?: MoqRepairDelivery
 }
 
 export interface RepairTrackSubscription {
@@ -43,7 +48,6 @@ export interface RepairTrackSubscription {
 
 export interface RepairLayerSubscriptionsOptions {
   source: RepairLayerSource
-  delivery: MoqRepairDelivery
   /** Subscribe one repair track; every object payload goes to `onPacket`. */
   subscribe(
     repairTrackName: string,
@@ -110,7 +114,7 @@ export class RepairLayerSubscriptions {
    * or interleaved sequences read as loss.
    */
   noteSourceSequence(seq: number): void {
-    if (this.#disposed || this.#opts.delivery === 'stream') return
+    if (this.#disposed || this.#delivery() === 'stream') return
     seq >>>= 0
     if (this.#lastSeq === undefined) {
       this.#lastSeq = seq
@@ -152,13 +156,13 @@ export class RepairLayerSubscriptions {
     this.#expected = 0
     this.#lost = 0
     this.#wantFewer = 0
-    this.#layerCount = Math.min(this.#layerCount, this.#layers().length)
+    this.#layerCount = this.#delivery() === 'stream' ? 0 : Math.min(this.#layerCount, this.#layers().length)
     this.#reconcile()
   }
 
   snapshot(): RepairLayerSubscriptionsSnapshot {
     return {
-      delivery: this.#opts.delivery,
+      delivery: this.#delivery(),
       layerCount: this.#layerCount,
       subscribedTracks: [...this.#subs.keys()],
       repairPackets: this.#repairPackets,
@@ -174,6 +178,10 @@ export class RepairLayerSubscriptions {
     this.#disposed = true
   }
 
+  #delivery(): MoqRepairDelivery {
+    return this.#source.deliveryMode === 'stream' ? 'stream' : 'datagram'
+  }
+
   #layers(): readonly RepairLayerParams[] {
     return this.#source.repairLayers ?? []
   }

package/src/track-session.ts

@@ -58,7 +58,7 @@ export interface TrackSessionConfig {
    * This is runtime join state, not catalog geometry: a receiver on a clean
    * path joins layer 0 only while a lossy one adds layers, so the catalog's
    * total P is not what this receiver is receiving. Diagnostics that report P
-   * (the worker snapshot, CMCD `x-bc-fec-p`) must read this.
+   * (the worker snapshot, CMCD `com.blockcast-fp`) must read this.
    *
    * Absent when the caller joins no layers explicitly, in which case P_0 is
    * what was joined. That is an identity on a single-layer track, not a