@blockcast/mmt-container 2.2.0-main.f480a7ede8b1 → 2.2.0-main.fb5c7dfbe2de

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, IsoSpanFailure, RebuiltSourceFeed, WasmFecDecoder } from "./fec-manager.js";
 import type { IsoPlacedSource, IsoRepairPlacement } from "./iso-block-locator.js";
 import { isMfuReassemblyError } from "./mfu-reassembler.js";
 import type {
@@ -214,6 +214,92 @@ 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,
+   *  or only the overlay's own evidence did, which anchors the release gate
+   *  alone (BLO-52085). */
+  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 evidence showed it (`unstampedOffset`):
+ * a base recovery's (#unstampedSsIdSeqOffsetByStream), or the overlay's
+ * alone (#overlayUnstampedSsIdSeqOffsetByStream). 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 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 {
@@ -225,14 +311,22 @@ 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>;
+  /** Overlay SS_ID → protected packet_sequence_number of each packet rebuilt
+   *  with no base SS_ID, until its base copy lands (#feedOverlaySource). */
+  readonly rebuilt: Map<number, number>;
 }
 
 /** Offsets kept per overlay, one per MPU: a keyframe's fragments share one. */
 const OVERLAY_OFFSET_MPUS = 16;
+/** Rebuilt packets kept per overlay whose base copy has not landed (OverlayInstance.rebuilt).
+ *  ponytail: this cap is the only eviction for a base copy that never lands
+ *  (oldest first; an overlay epoch reset clears all). Bound records by SS_ID
+ *  age instead if stale ones ever crowd out live ones. */
+const OVERLAY_REBUILT_LIMIT = 256;
 /** A MoQ-fed overlay block is forgotten once it starts this many K_overlay
  *  behind the newest overlay SS_ID: the overlay locator, which keeps a fixed
  *  few blocks (no catalog timing), has retired it long before, so it can no
@@ -579,6 +673,7 @@ interface StreamLedgers {
    *   the pair.
    */
   readonly duplicates: StreamDuplicateLedgers;
+  readonly overlayToBase: OverlayToBase;
 }
 
 const NO_FEC_MANAGER_HORIZON: DuplicateHorizon = Object.freeze({
@@ -666,6 +761,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;
 
@@ -737,13 +843,14 @@ export interface FECManagerLike {
 
   /** Track a first-arrival network source symbol for block completion and
    *  classification. Refreshes the inactivity deadline and marks clean when
-   *  K arrive. */
+   *  K arrive. `held`: a source held unplaced since it arrived, placed now. */
   trackBlock(
     sbn: number,
     packetId: number,
     catalogTrackName: string | undefined,
     esi: number,
     evidence: SourceSymbolEvidence,
+    held?: boolean,
   ): void;
 
   /** True once the packetId has a per-track FEC configuration. */
@@ -913,6 +1020,7 @@ export interface FECManagerLike {
         packetId: number,
         catalogTrackName: string | undefined,
         blockClass: BlockClass,
+        span?: IsoSpanFailure,
       ) => void)
     | null;
 
@@ -981,6 +1089,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>();
@@ -1049,6 +1158,26 @@ 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>();
+  /**
+   * The same, shown by the overlay alone, before any base recovery did: a
+   * packet it rebuilt whose base copy carries its protected psn
+   * (#feedOverlaySource), or whose protected psn passes overlayBaseSsId's
+   * test at that offset (#routeOverlayRecovered). A base SS_ID placed by it
+   * anchors the release gate only (BLO-52085 D3): fed to the base, it would
+   * make the base drop a late base copy of a keyframe the overlay never
+   * finished, and lift a block's late-source cut, which nothing before
+   * this offset did.
+   */
+  #overlayUnstampedSsIdSeqOffsetByStream = 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
@@ -1097,6 +1226,7 @@ export class MmtpRouter {
         packetId: number,
         catalogTrackName: string | undefined,
         blockClass: BlockClass,
+        span?: IsoSpanFailure,
       ) => void)
     | null = null;
   /** Typed observer of every gap decision the release gate makes. */
@@ -1126,7 +1256,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:
@@ -1194,6 +1324,7 @@ export class MmtpRouter {
       packetId: number,
       catalogTrackName: string | undefined,
       blockClass: BlockClass,
+      span?: IsoSpanFailure,
     ) => void;
     /** Internal gap-decision sink owned by the composing transport. */
     onFrameGap?: (decision: FrameGapDecision) => void;
@@ -1427,6 +1558,7 @@ export class MmtpRouter {
           packetId: number,
           catalogTrackName: string | undefined,
           blockClass: BlockClass,
+          span?: IsoSpanFailure,
         ) => void)
       | undefined,
   ): void {
@@ -1479,6 +1611,7 @@ export class MmtpRouter {
         packetId: number,
         catalogTrackName: string | undefined,
         blockClass: BlockClass,
+        span?: IsoSpanFailure,
       ) => {
         this.#mseAssemblerFor(packetId, catalogTrackName)?.failBlock(sbn);
         if (
@@ -1487,8 +1620,13 @@ export class MmtpRouter {
         ) {
           this.#onDeltaBlockCompleteCb?.(packetId, true); // failed=true
         }
-        onBlockFailed?.(sbn, packetId, catalogTrackName, blockClass);
-        this.#onBlockFailed?.(sbn, packetId, catalogTrackName, blockClass);
+        if (span === undefined) {
+          onBlockFailed?.(sbn, packetId, catalogTrackName, blockClass);
+          this.#onBlockFailed?.(sbn, packetId, catalogTrackName, blockClass);
+        } else {
+          onBlockFailed?.(sbn, packetId, catalogTrackName, blockClass, span);
+          this.#onBlockFailed?.(sbn, packetId, catalogTrackName, blockClass, span);
+        }
       };
     }
   }
@@ -1541,8 +1679,9 @@ export class MmtpRouter {
 
   /**
    * FEC-recovered source symbols whose reconstructed header named a
-   * packet_sequence_number other than the wire sequence their SS_ID maps to:
-   * a hop re-stamped the sequence after the sender protected the packet.
+   * packet_sequence_number other than the wire sequence their SS_ID maps to,
+   * or, rebuilt by the overlay, than their base copy carries: a hop
+   * re-stamped the sequence after the sender protected the packet.
    */
   get restampedRecoveredSequenceCount(): number {
     return this.#restampedRecoveredSeqs;
@@ -1766,6 +1905,11 @@ export class MmtpRouter {
   ): CmafBlockAssembler {
     const assemblerKey = this.#mseAssemblerKey(packetId, catalogTrackName);
     const previous = this.#mseAssemblers.get(assemblerKey);
+    // The new assembler has no source cursor: the release gate must not hold
+    // an overlay keyframe for one either (FecReleaseSequencer.#cursorPassed).
+    // What the gate holds that unanchored had already released to the
+    // assembler being replaced goes to it first, and plays with its flush.
+    this.#parser.unsourceFecRelease(packetId, catalogTrackName);
     if (previous) {
       previous.flush();
       previous.dispose();
@@ -1837,6 +1981,7 @@ export class MmtpRouter {
       packetId: number,
       catalogTrackName: string | undefined,
       blockClass: BlockClass,
+      span?: IsoSpanFailure,
     ) => void,
   ): void {
     this.#onBlockFailed = cb;
@@ -1941,7 +2086,7 @@ export class MmtpRouter {
     const leg = this.#overlayLegs.get(repairPacketId);
     if (!leg) throw new Error(`[MmtpRouter] packetId=${repairPacketId} is no known keyframe-overlay leg`);
     const inst: OverlayInstance = {
-      repairPacketId, streamName, leg: { ...leg }, fec, k, offsets: new Map(), moqBlocks: new Set(),
+      repairPacketId, streamName, leg: { ...leg }, fec, k, offsets: new Map(), moqBlocks: new Set(), rebuilt: new Map(),
     };
     this.#overlays.set(repairPacketId, inst);
     return () => {
@@ -1976,6 +2121,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 {
@@ -1983,6 +2135,7 @@ export class MmtpRouter {
     inst.last = undefined;
     inst.offsets.clear();
     inst.moqBlocks.clear();
+    inst.rebuilt.clear();
   }
 
   #overlaysForSource(sourcePacketId: number, catalogTrackName: string | undefined): OverlayInstance[] {
@@ -2053,7 +2206,15 @@ 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.
+   *
+   * The base copy of a packet an overlay rebuilt with no base SS_ID shows
+   * what a base recovery of it would (#routeProcessedFecSymbols, BLO-52085):
+   * its wire packet_sequence_number equal to the protected one rebuilt shows
+   * the stream unstamped at the SS_ID offset it states, for the release gate
+   * (#overlayUnstampedSsIdSeqOffsetByStream); any other shows a hop that
+   * re-stamps it, which is counted (restampedRecoveredSequenceCount).
    */
   #feedOverlaySource(
     packetId: number,
@@ -2063,16 +2224,35 @@ export class MmtpRouter {
     sequenceNumber: number,
     rapFlag: boolean,
     source: MmtpSourcePath,
+    baseSsId: number | undefined,
   ): void {
     if (this.#overlays.size === 0) return;
     const ssId = keyframeOverlaySsId(header);
     if (ssId === undefined) return;
+    let rebuiltPsn: number | undefined;
     for (const inst of this.#overlaysForSource(packetId, catalogTrackName)) {
       this.#noteOverlaySsId(inst, ssId, sequenceNumber);
+      // After the restart check: a new epoch forgets the old one's packets.
+      rebuiltPsn ??= inst.rebuilt.get(ssId);
+      inst.rebuilt.delete(ssId);
       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;
@@ -2092,6 +2272,18 @@ export class MmtpRouter {
       const recovered = fec.feedSourceSymbol(pid, ssId, symbolData, name);
       if (recovered && !alreadyCompleted) this.#routeOverlayRecovered(inst, coords.sbn, recovered);
     }
+    if (rebuiltPsn === undefined || this.#classifyPacketId(packetId) === null) return;
+    const streamKey = this.#mediaStreamKey(packetId, catalogTrackName);
+    if (rebuiltPsn !== sequenceNumber) {
+      // Counted only. Marked re-stamped (#restampedStreams), the stream would
+      // drop every later rebuilt packet no member anchors, which the overlay
+      // route delivers unanchored until a base recovery shows the re-stamp:
+      // a keyframe whose base copy is lost too would never play.
+      this.#restampedRecoveredSeqs++;
+    } else if (baseSsId !== undefined) {
+      const offset = this.#ssIdSeqOffsetByStream.get(streamKey);
+      if (offset === ((baseSsId - sequenceNumber) >>> 0)) this.#overlayUnstampedSsIdSeqOffsetByStream.set(streamKey, offset);
+    }
   }
 
   #noteOverlayMoqBlock(inst: OverlayInstance, blockStart: number): void {
@@ -2132,11 +2324,16 @@ export class MmtpRouter {
 
   /**
    * Route an overlay-recovered block's packets as source media of the
-   * overlay's source (7.2: an overlay coordinate yields no base SS_ID). No
-   * base-SS_ID derivation runs: no release-gate anchor, no parse ledger, no
-   * base re-stamp, no block advance. Each packet's wire sequence is restored
-   * from its keyframe's own offset; without one, a stream the base never
-   * re-stamped keeps the header's sequence and any other drops the packet.
+   * overlay's source (7.2: an overlay coordinate yields no base SS_ID). A
+   * packet whose base SS_ID is determined independently (overlayBaseSsId,
+   * unstampedBaseSsId) enters the release gate at that SS_ID, as a packet
+   * base FEC recovered does, so it waits behind base frames still in flight,
+   * though not for its own MPU's packets (FrameMeta.fecSbnFirst) and no
+   * longer than unanchored; one whose base SS_ID is undetermined has no
+   * release-gate anchor. No parse ledger, no base re-stamp, no block
+   * advance. Each packet's wire sequence is restored from its keyframe's own
+   * offset; without one, a stream the base never re-stamped keeps the
+   * header's sequence and any other drops the packet.
    */
   #routeOverlayRecovered(inst: OverlayInstance, blockStart: number, recovered: Uint8Array): void {
     const { fec, repairPacketId: pid, streamName: name } = inst;
@@ -2159,27 +2356,181 @@ export class MmtpRouter {
     const streamKey = this.#mediaStreamKey(sourcePacketId, sourceName);
     const restamped = this.#restampedStreams.has(streamKey);
     const restored = new Set<number>();
+    // The base SS_IDs determined independently, by overlay ESI; those the
+    // overlay alone showed anchor the release gate, not the base decoder.
+    const baseSsIds = new Map<number, number>();
+    const gateOnly = new Set<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 overlaySsId = serial32Add(blockStart, sym.index);
+      const anchor = inst.offsets.get(sym.fragment.mpuSequenceNumber);
+      if (anchor !== undefined) {
+        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(sym.index, baseSsId);
+          // Its protected psn is the wire sequence its member gives it, at
+          // the base SS_ID that member gives it: at the stream's current
+          // SS_ID offset, the stream unstamped, as a base recovery shows it
+          // (#routeProcessedFecSymbols). A re-stamping hop fails the psn test.
+          // Only for a packet the base did not receive: a received member's
+          // slot holds the bytes it arrived with (the decoder keeps a
+          // received source as given), whose psn is the wire one whatever a
+          // hop did, so it passes the test against itself.
+          const offset = this.#ssIdSeqOffsetByStream.get(streamKey);
+          if (!this.#sourceSeqReceived(sourcePacketId, packetSequenceNumber, sourceName) &&
+              offset === ((baseSsId - packetSequenceNumber) >>> 0)) {
+            this.#overlayUnstampedSsIdSeqOffsetByStream.set(streamKey, offset);
+          }
+        }
+        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];
+      // router cannot tell (their psn is the wire one), and the base copy of
+      // a packet the overlay rebuilt only counts a re-stamp. Base recovery or
+      // a FETCH still covers such a keyframe.
+      if (!restamped) {
+        // No member of this MPU arrived to anchor a base SS_ID. Evidence that
+        // the stream is unstamped at its current offset determines one from
+        // the packet's protected psn instead (unstampedBaseSsId): a base
+        // recovery's, or else the overlay's own, which anchors the release
+        // gate only (#overlayUnstampedSsIdSeqOffsetByStream). Without it, the
+        // packet's base copy, if it lands, shows whether it is
+        // (#feedOverlaySource).
+        const offset = this.#ssIdSeqOffsetByStream.get(streamKey);
+        const fedSsId = unstampedBaseSsId(offset, this.#unstampedSsIdSeqOffsetByStream.get(streamKey), sym.packetSequenceNumber);
+        const baseSsId = fedSsId ??
+          unstampedBaseSsId(offset, this.#overlayUnstampedSsIdSeqOffsetByStream.get(streamKey), sym.packetSequenceNumber);
+        if (baseSsId !== undefined) {
+          baseSsIds.set(sym.index, baseSsId);
+          if (fedSsId === undefined) gateOnly.add(sym.index);
+        } else {
+          inst.rebuilt.set(overlaySsId, sym.packetSequenceNumber);
+          if (inst.rebuilt.size > OVERLAY_REBUILT_LIMIT) inst.rebuilt.delete(inst.rebuilt.keys().next().value!);
+        }
+        return [sym];
+      }
       this.#overlayStats.unsequencedDropped++;
       return [];
     });
     this.#overlayStats.recovered++;
+    // Each packet's MPU starts, in this decode, at the lowest base SS_ID
+    // determined for it: the release gate's span ends there.
+    const mpuFirst = new Map<number, number>();
+    for (const sym of symbols) {
+      const ssId = baseSsIds.get(sym.index);
+      const mpu = sym.fragment.mpuSequenceNumber;
+      const first = mpuFirst.get(mpu);
+      if (ssId !== undefined && (first === undefined || serial32Precedes(ssId, first))) mpuFirst.set(mpu, ssId);
+    }
+    const firstSsIds = new Map<number, number>();
+    for (const sym of symbols) {
+      if (baseSsIds.has(sym.index)) firstSsIds.set(sym.index, mpuFirst.get(sym.fragment.mpuSequenceNumber)!);
+    }
     this.#routeProcessedFecSymbols(blockStart, { ...result, symbols }, sourcePacketId, sourceName, {
       deliveryProvenance: inst.moqBlocks.has(blockStart) ? "mixed" : "multicast",
+      baseSsIds,
+      firstSsIds,
     });
     this.#noteOverlayRecoveredRaps(sourcePacketId, sourceName, streamKey, symbols.filter((sym) =>
       restored.has(sym.packetSequenceNumber)));
+    this.#feedOverlayRecoveredToBase(inst, blockStart, symbols, gateOnly.size === 0
+      ? baseSsIds
+      : new Map([...baseSsIds].filter(([index]) => !gateOnly.has(index))));
+  }
+
+  /**
+   * 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 at an offset a
+   * base recovery showed; `baseSsIds` holds no other),
+   * 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<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.index);
+      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
@@ -2215,6 +2566,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;
@@ -2365,6 +2719,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;
@@ -2999,6 +3358,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,
@@ -3061,7 +3425,7 @@ export class MmtpRouter {
         catalogTrackName,
       )) continue;
       if (fec.isTrackConfigured?.(ownerPacketId) !== false) {
-        fec.trackBlock(blockStart, ownerPacketId, catalogTrackName, esi, payload.evidence);
+        fec.trackBlock(blockStart, ownerPacketId, catalogTrackName, esi, payload.evidence, true);
         this.#requestFecPoke(ownerPacketId, catalogTrackName);
       }
       if (payload.oversized) continue;
@@ -3179,6 +3543,8 @@ export class MmtpRouter {
     this.#droppedPreSyncVideo.delete(streamKey);
     this.#latestVideoSeqByStream.delete(streamKey);
     this.#ssIdSeqOffsetByStream.delete(streamKey);
+    this.#unstampedSsIdSeqOffsetByStream.delete(streamKey);
+    this.#overlayUnstampedSsIdSeqOffsetByStream.delete(streamKey);
     this.#multicastRapTwinByStream.delete(streamKey);
     this.#lastDirectSourceVideoTsByStream.delete(streamKey);
     this.#lastDirectEmittedVideoTsByStream.delete(streamKey);
@@ -3310,6 +3676,12 @@ export class MmtpRouter {
    *   the outgoing stream stops. The hold is bounded by the incoming stream's
    *   own RAP cadence, so no timer is involved.
    *
+   * While the switch is staged, the FEC release gate lets a keyframe the
+   * overlay rebuilt reach it, on either side, when the keyframe did before
+   * the gate anchored it (FecReleaseGate.releaseUnanchored): the switch
+   * decides on what each side delivered, and the commit discards the gate's
+   * frames of the outgoing stream.
+   *
    * The commit is one synchronous transition inside the frame path: the
    * outgoing stream's already-admitted frames are released (its queued FEC
    * gap fills only up to the RAP, since recovery can queue a frame ahead of
@@ -3362,6 +3734,16 @@ export class MmtpRouter {
       droppedIncomingFrames: 0,
     };
     this.#staged = state;
+    // Release what the outgoing stream's gate held only because it was
+    // anchored (FecReleaseGate.releaseUnanchored): unanchored, it had already
+    // reached the switch. Only a gate that holds a frame the overlay rebuilt
+    // is poked: any other holds nothing for that reason, and a poke would
+    // still force out a frame held past the hold limit, which before the
+    // anchor waited for the next push. The incoming stream's gate is not
+    // drained here: a RAP it released would commit before this call returns.
+    if (this.#parser.fecReleaseHoldsRebuilt(from.packetId, from.catalogTrackName)) {
+      this.#requestFecPoke(from.packetId, from.catalogTrackName);
+    }
     return {
       cancel: () => {
         if (this.#staged !== state) return false;
@@ -3456,7 +3838,24 @@ export class MmtpRouter {
     // same call. Nothing registers a packet ID mid-frame, so this drops
     // only frames that lost their registration.
     if (this.#classifyPacketId(meta.packetId) === null) return;
-    if (this.#staged !== null && this.#interceptSwitchFrame(data, meta)) return;
+    if (this.#staged !== null) {
+      // A switch staged from this frame's commit (onCommit: the ladder walk)
+      // pokes its outgoing stream's gate, the stream just committed to, whose
+      // drain may be what released this frame. The poke waits until the
+      // commit has delivered that stream's init, held GOP and RAP. Run now,
+      // it would release the frames behind them ahead of them: a delta is
+      // dropped there (its stream is not synced yet), and a keyframe plays
+      // ahead of the init and leaves the commit's frames behind it.
+      let consumed = false;
+      this.#fecPokeDepth++;
+      try {
+        consumed = this.#interceptSwitchFrame(data, meta);
+      } finally {
+        this.#fecPokeDepth--;
+        this.#flushPendingFecPokes();
+      }
+      if (consumed) return;
+    }
     this.#deliverParsedFrame(data, meta);
   }
 
@@ -3649,12 +4048,17 @@ export class MmtpRouter {
       this.#parser.deferFecRelease(work);
     } finally {
       this.#fecPokeDepth--;
-      if (this.#fecPokeDepth === 0 && this.#pendingFecPokes.size > 0 && !this.#disposed) {
-        const pokes = [...this.#pendingFecPokes.values()];
-        this.#pendingFecPokes.clear();
-        for (const poke of pokes) {
-          this.#parser.pokeFecRelease(poke.packetId, poke.catalogTrackName);
-        }
+      this.#flushPendingFecPokes();
+    }
+  }
+
+  /** Run the pokes requested while #fecPokeDepth was raised, once it is 0. */
+  #flushPendingFecPokes(): void {
+    if (this.#fecPokeDepth === 0 && this.#pendingFecPokes.size > 0 && !this.#disposed) {
+      const pokes = [...this.#pendingFecPokes.values()];
+      this.#pendingFecPokes.clear();
+      for (const poke of pokes) {
+        this.#parser.pokeFecRelease(poke.packetId, poke.catalogTrackName);
       }
     }
   }
@@ -3743,6 +4147,14 @@ export class MmtpRouter {
       onRap: (packetId, catalogTrackName, ssId) => {
         for (const observer of this.#fecRapObservers) observer(packetId, catalogTrackName, ssId);
       },
+      // A staged switch commits on when each side's frames reach it
+      // (#interceptSwitchFrame): both sides' overlay keyframes reach it when
+      // they did unanchored.
+      releaseUnanchored: (packetId, catalogTrackName) => {
+        const staged = this.#staged;
+        const stream = { packetId, ...(catalogTrackName === undefined ? {} : { catalogTrackName }) };
+        return staged !== null && (isStream(stream, staged.from) || isStream(stream, staged.to));
+      },
       onReleased: (data, meta) => {
         if (meta.trackType !== "video" || meta.mpuSequenceNumber === undefined) return;
         const timing = meta.authoredTiming;
@@ -3938,6 +4350,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
@@ -4401,6 +4815,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,
         );
       }
     }
@@ -4425,6 +4840,7 @@ export class MmtpRouter {
       deliveryProvenance?: MmtpDeliveryProvenance;
       catalogTrackName?: string;
       fecSbn?: number;
+      fecSbnFirst?: number;
     },
     parsed?: ParsedMmtpPacket,
   ): void {
@@ -4448,6 +4864,7 @@ export class MmtpRouter {
         deliveryProvenance: parserOptions?.deliveryProvenance,
         catalogTrackName: parserOptions?.catalogTrackName,
         ...(parserOptions?.fecSbn === undefined ? {} : { fecSbn: parserOptions.fecSbn }),
+        ...(parserOptions?.fecSbnFirst === undefined ? {} : { fecSbnFirst: parserOptions.fecSbnFirst }),
       };
       if (parsed) this.#parser.feedParsed(packet, parsed, feedOptions);
       else this.#parser.feed(packet, feedOptions);
@@ -4629,6 +5046,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);
     }
@@ -4832,15 +5250,16 @@ export class MmtpRouter {
   ): 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
+    // block between it and the frame before it resolved, because it starts
+    // where that frame ended, or (one the overlay rebuilt) once the base
+    // path passed it. 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).
+    // (BLO-52085). An overlay recovery whose base SS_ID is undetermined 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))) {
@@ -5086,6 +5505,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;
@@ -5155,15 +5585,25 @@ export class MmtpRouter {
     catalogTrackName?: string,
     /** Set for a keyframe-overlay recovery: `blockId` is an overlay
      *  coordinate, which yields no base SS_ID (mmt-02 7.2), and the packets'
-     *  wire sequences are already restored. */
-    overlay?: { deliveryProvenance: MmtpDeliveryProvenance },
+     *  wire sequences are already restored. `baseSsIds` holds, by ESI, the
+     *  base SS_IDs determined independently: a packet's release-gate anchor;
+     *  `firstSsIds` the lowest of them in its MPU (FrameMeta.fecSbnFirst). */
+    overlay?: {
+      deliveryProvenance: MmtpDeliveryProvenance;
+      baseSsIds: ReadonlyMap<number, number>;
+      firstSsIds: ReadonlyMap<number, number>;
+    },
   ): void {
     // Route recovered symbols to the track's callback. The ownerPacketId tells us
     // which track this block belongs to — resolves per-track, then legacy fallback.
     if (ownerPacketId == null) return; // no track association
     if (this.#classifyPacketId(ownerPacketId) === null) return; // unknown track
-    const fecSbnOf = (index: number): { fecSbn?: number } =>
-      overlay ? {} : { fecSbn: this.#fecAnchorForRecovered(blockId, index) };
+    const fecSbnOf = (index: number): { fecSbn?: number; fecSbnFirst?: number } => {
+      if (!overlay) return { fecSbn: this.#fecAnchorForRecovered(blockId, index) };
+      const fecSbn = overlay.baseSsIds.get(index);
+      const fecSbnFirst = overlay.firstSsIds.get(index);
+      return fecSbn === undefined || fecSbnFirst === undefined ? {} : { fecSbn, fecSbnFirst };
+    };
     // A recovered symbol's header names the sequence the sender protected. A
     // hop that re-stamps packet_sequence_number after protection (cast's
     // publisher-rotation bridge) leaves the decode mixing every received
@@ -5179,7 +5619,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 };