@blockcast/mmt-container 2.2.0-main.75b39a2cdddf → 2.2.0-main.7e8a9d13c01c

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, RebuiltSourceFeed, 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 {
@@ -216,7 +216,9 @@ export interface KeyframeOverlayStats {
   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. */
+  /** 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;
 }
 
@@ -260,12 +262,12 @@ function overlayBaseSsId(
  * 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.
+ * 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
@@ -313,10 +315,18 @@ interface OverlayInstance {
   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
@@ -833,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. */
@@ -1009,6 +1020,7 @@ export interface FECManagerLike {
         packetId: number,
         catalogTrackName: string | undefined,
         blockClass: BlockClass,
+        span?: IsoSpanFailure,
       ) => void)
     | null;
 
@@ -1155,6 +1167,17 @@ export class MmtpRouter {
    * 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
@@ -1203,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. */
@@ -1300,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;
@@ -1533,6 +1558,7 @@ export class MmtpRouter {
           packetId: number,
           catalogTrackName: string | undefined,
           blockClass: BlockClass,
+          span?: IsoSpanFailure,
         ) => void)
       | undefined,
   ): void {
@@ -1585,6 +1611,7 @@ export class MmtpRouter {
         packetId: number,
         catalogTrackName: string | undefined,
         blockClass: BlockClass,
+        span?: IsoSpanFailure,
       ) => {
         this.#mseAssemblerFor(packetId, catalogTrackName)?.failBlock(sbn);
         if (
@@ -1593,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);
+        }
       };
     }
   }
@@ -1647,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;
@@ -1872,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();
@@ -1943,6 +1981,7 @@ export class MmtpRouter {
       packetId: number,
       catalogTrackName: string | undefined,
       blockClass: BlockClass,
+      span?: IsoSpanFailure,
     ) => void,
   ): void {
     this.#onBlockFailed = cb;
@@ -2047,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 () => {
@@ -2096,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[] {
@@ -2168,6 +2208,13 @@ export class MmtpRouter {
    * base protects: the packet minus its 4-byte SS_ID trailer, extension
    * 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,
@@ -2182,8 +2229,12 @@ export class MmtpRouter {
     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
@@ -2221,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 {
@@ -2261,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;
@@ -2288,51 +2356,96 @@ 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>();
+    // 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 overlaySsId = serial32Add(blockStart, sym.index);
       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);
         const out = { ...sym, packetSequenceNumber };
         const baseSsId = overlayBaseSsId(anchor, overlaySsId, packetSequenceNumber, sym.packetSequenceNumber);
-        if (baseSsId !== undefined) baseSsIds.set(out, baseSsId);
+        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.
+      // 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. 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);
+        // 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, baseSsIds);
+    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),
+   * 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.
@@ -2352,7 +2465,7 @@ export class MmtpRouter {
     inst: OverlayInstance,
     blockStart: number,
     symbols: ProcessFecBlockResult["symbols"],
-    baseSsIds: ReadonlyMap<ProcessFecBlockResult["symbols"][number], number>,
+    baseSsIds: ReadonlyMap<number, number>,
   ): void {
     const fec = this.#fecManager;
     const owner = inst.leg.sourcePacketId;
@@ -2364,7 +2477,7 @@ export class MmtpRouter {
     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);
+      const ssId = baseSsIds.get(sym.index);
       if (ssId === undefined) {
         this.#overlayStats.baseUndetermined++;
         continue;
@@ -3312,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;
@@ -3431,6 +3544,7 @@ export class MmtpRouter {
     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);
@@ -3562,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
@@ -3614,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;
@@ -3708,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);
   }
 
@@ -3901,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);
       }
     }
   }
@@ -3995,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;
@@ -4680,6 +4840,7 @@ export class MmtpRouter {
       deliveryProvenance?: MmtpDeliveryProvenance;
       catalogTrackName?: string;
       fecSbn?: number;
+      fecSbnFirst?: number;
     },
     parsed?: ParsedMmtpPacket,
   ): void {
@@ -4703,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);
@@ -5088,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))) {
@@ -5422,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