@blockcast/mmt-container 2.0.1 → 2.1.0-main.5b10b5454faf

package/dist/multicast-manager.js

@@ -16314,6 +16314,14 @@ function isRouterDebugEnabled() {
 function debugRouter(message) {
   if (isRouterDebugEnabled()) console.debug(message);
 }
+var KEYFRAME_OVERLAY_EXTENSION_TYPE = 35585;
+function keyframeOverlaySsId(header) {
+  const ext = header.extension;
+  if (ext?.type !== KEYFRAME_OVERLAY_EXTENSION_TYPE || ext.data.length !== 4) return void 0;
+  return new DataView(ext.data.buffer, ext.data.byteOffset, 4).getUint32(0);
+}
+var OVERLAY_OFFSET_MPUS = 16;
+var OVERLAY_MOQ_HORIZON_BLOCKS = 64;
 function assertStreamIdentity(role, stream) {
   if (stream === void 0 || !Number.isInteger(stream.packetId) || stream.packetId <= MMTP_SIGNALING_PACKET_ID || typeof stream.catalogTrackName !== "string" || stream.catalogTrackName.length === 0) {
     throw new Error(
@@ -16530,6 +16538,26 @@ var MmtpRouter = class {
   #packetIdRoles = /* @__PURE__ */ new Map();
   /** Explicit catalog ownership for dedicated repair-track packet IDs. */
   #repairOwnersByPacketId = /* @__PURE__ */ new Map();
+  /** Keyframe-overlay repair PID → the source its FEC instance protects
+   *  (draft-ramadan-mmt-fec-02 7.4.1). Never an owner in
+   *  #repairOwnersByPacketId: the overlay is decoded as its own instance. */
+  #overlayLegs = /* @__PURE__ */ new Map();
+  /** Keyframe-overlay repair track names, which name a leg too: a catalog
+   *  may state no PID for it (learned at subscribe time). */
+  #overlayRepairNames = /* @__PURE__ */ new Map();
+  /** Installed overlay instances, by overlay repair PID (opt-in only). */
+  #overlays = /* @__PURE__ */ new Map();
+  #overlayRecoveredObservers = /* @__PURE__ */ new Set();
+  /** Streams whose recovered sequence the base path ever re-stamped. */
+  #restampedStreams = /* @__PURE__ */ new Set();
+  #overlayStats = {
+    repairDropped: 0,
+    ownerRefused: 0,
+    recovered: 0,
+    restarts: 0,
+    unsequencedDropped: 0,
+    protectedDropped: 0
+  };
   /** Callback fired when a delta-track FEC block completes or fails. */
   #onDeltaBlockCompleteCb = null;
   // Debug counters
@@ -16726,6 +16754,7 @@ var MmtpRouter = class {
       this.#fecManager.onSourceDiscontinuity = (packetId, catalogTrackName) => {
         this.#parser.markFecDiscontinuity(packetId, catalogTrackName);
         this.#requestFecPoke(packetId, catalogTrackName);
+        this.resetKeyframeOverlays(packetId, catalogTrackName);
       };
       this.#fecManager.onBlockComplete = (sbn, packetId, catalogTrackName) => {
         this.#mseAssemblerFor(packetId, catalogTrackName)?.completeBlock(sbn);
@@ -17048,13 +17077,287 @@ var MmtpRouter = class {
   /** Replace catalog-derived repair ownership before a catalog reconfiguration. */
   clearRepairPacketIdOwners() {
     this.#repairOwnersByPacketId.clear();
+    this.#overlayLegs.clear();
+    this.#overlayRepairNames.clear();
   }
-  /** Bind one dedicated repair-track PID to its authoritative media PID. */
+  /** Bind one dedicated repair-track PID to its authoritative media PID. A
+   *  known keyframe-overlay PID is refused, and counted: its symbols belong to
+   *  the overlay instance, never to the source's base decoder (mmt-02 7.4.4). */
   setRepairPacketIdOwner(repairPacketId, ownerPacketId) {
+    if (this.#overlayLegs.has(repairPacketId)) {
+      this.#overlayStats.ownerRefused++;
+      return;
+    }
     const owners = this.#repairOwnersByPacketId.get(repairPacketId) ?? /* @__PURE__ */ new Set();
     owners.add(ownerPacketId);
     this.#repairOwnersByPacketId.set(repairPacketId, owners);
   }
+  /**
+   * Record a keyframe-overlay repair leg (draft-ramadan-mmt-fec-02 7.4): its
+   * PID, the source it protects, and its repair track name. Either one names
+   * the leg, so a catalog that states no PID (learned at subscribe time) is
+   * covered by the name. Overlay repair is then never resolved to a base
+   * owner, on multicast or MoQ. Cleared with the catalog owners
+   * (`clearRepairPacketIdOwners`).
+   */
+  setKeyframeOverlayLeg(repairPacketId, leg) {
+    if (leg.repairTrackName !== void 0) this.#overlayRepairNames.set(leg.repairTrackName, { ...leg });
+    if (repairPacketId === void 0) return;
+    this.#repairOwnersByPacketId.delete(repairPacketId);
+    this.#overlayLegs.set(repairPacketId, { ...leg });
+  }
+  /** The keyframe-overlay leg registered on `repairPacketId`, if any. */
+  keyframeOverlayLeg(repairPacketId) {
+    return this.#overlayLegs.get(repairPacketId);
+  }
+  /**
+   * Overlay counters: repair dropped for want of an installed instance, base
+   * owners refused on an overlay PID, overlay blocks recovered, overlay
+   * restarts, and recovered packets dropped for want of a wire sequence or
+   * for a MoQ symbol on a protected flow (multicast-02 7.2.7).
+   */
+  get keyframeOverlayStats() {
+    return { ...this.#overlayStats };
+  }
+  #isOverlayRepair(repairPacketId, repairTrackName) {
+    return this.#overlayLegs.has(repairPacketId) || repairTrackName !== void 0 && this.#overlayRepairNames.has(repairTrackName);
+  }
+  /**
+   * Install the keyframe overlay decoded on `fec` for a known overlay leg
+   * (draft-ramadan-mmt-fec-02 7.4.4: decoded independently of the base). `fec`
+   * holds the overlay stream under `repairPacketId` and `streamName`. Replaces
+   * an earlier install on the same leg; the returned disposer removes only
+   * this one.
+   */
+  installKeyframeOverlay(repairPacketId, fec, k, streamName) {
+    const leg = this.#overlayLegs.get(repairPacketId);
+    if (!leg) throw new Error(`[MmtpRouter] packetId=${repairPacketId} is no known keyframe-overlay leg`);
+    const inst = {
+      repairPacketId,
+      streamName,
+      leg: { ...leg },
+      fec,
+      k,
+      offsets: /* @__PURE__ */ new Map(),
+      moqBlocks: /* @__PURE__ */ new Set()
+    };
+    this.#overlays.set(repairPacketId, inst);
+    return () => {
+      if (this.#overlays.get(repairPacketId) === inst) this.#overlays.delete(repairPacketId);
+    };
+  }
+  /**
+   * Observe each base block whose RAP MFU fragments a keyframe-overlay
+   * recovery supplied, with the keyframe's FT=0 and FT=1 held
+   * (fec-multicast-00 §6.6). The block is named by the recovered packets'
+   * restored wire sequence through the base SS_ID offset, never by an overlay
+   * coordinate. Called synchronously from the recovered-block route.
+   */
+  addKeyframeOverlayRecoveredObserver(observer) {
+    this.#overlayRecoveredObservers.add(observer);
+    return () => {
+      this.#overlayRecoveredObservers.delete(observer);
+    };
+  }
+  /** Whether an overlay is installed on `repairPacketId`. */
+  hasKeyframeOverlay(repairPacketId) {
+    return this.#overlays.has(repairPacketId);
+  }
+  /**
+   * Start a new epoch of every overlay protecting `sourcePacketId` (its
+   * source restarted): empty overlay stream, no coverage, no offsets.
+   */
+  resetKeyframeOverlays(sourcePacketId, catalogTrackName) {
+    for (const inst of this.#overlaysForSource(sourcePacketId, catalogTrackName)) this.#resetOverlay(inst);
+  }
+  #resetOverlay(inst) {
+    inst.fec.resetTrack(inst.repairPacketId, inst.streamName);
+    inst.last = void 0;
+    inst.offsets.clear();
+    inst.moqBlocks.clear();
+  }
+  #overlaysForSource(sourcePacketId, catalogTrackName) {
+    return [...this.#overlays.values()].filter(({ leg }) => leg.sourcePacketId === sourcePacketId && (catalogTrackName === void 0 || leg.sourceCatalogTrackName === void 0 || leg.sourceCatalogTrackName === catalogTrackName));
+  }
+  /**
+   * The overlay instance a repair packet belongs to, by the track it arrived
+   * on (7.4.2: its PID or its repair track name); null for overlay repair
+   * with no instance installed; undefined for repair of no overlay.
+   */
+  #overlayRepairTarget(repairPacketId, repairTrackName) {
+    const inst = this.#overlays.get(repairPacketId) ?? (repairTrackName === void 0 ? void 0 : [...this.#overlays.values()].find(({ leg }) => leg.repairTrackName === repairTrackName));
+    if (inst) return inst;
+    return this.#isOverlayRepair(repairPacketId, repairTrackName) ? null : void 0;
+  }
+  /** Overlay repair goes to its own instance, never to a base owner, locator
+   *  or decoder; with none installed it is dropped and counted. */
+  #routeOverlayRepair(inst, repairPacketId, packet, header, source) {
+    const repair = inst ? parseMoqRepairFrameWithHeader(packet, header) : null;
+    if (!inst || !repair) {
+      this.#overlayStats.repairDropped++;
+      debugRouter(`[MmtpRouter] Dropping keyframe-overlay repair pid=${repairPacketId}: no overlay instance`);
+      return;
+    }
+    const { fec, repairPacketId: pid, streamName: name } = inst;
+    if (!fec.admitRepairBlockLength(pid, repair.ssbLength, repair.rsbLength, repair.rsId)) return;
+    if (!fec.admitRepairSymbolSize(pid, repair.ssStart, repair.ssbLength, repair.rsId, repair.symbolData.byteLength)) return;
+    const placement = fec.placeIsoRepair(pid, name, repair.ssStart, repair.ssbLength);
+    if (placement.status !== "placed") return;
+    const blockStart = placement.block.start;
+    if (placement.span !== void 0) this.#replayOverlaySources(inst, placement.span.block.start, placement.span.placed);
+    this.#replayOverlaySources(inst, blockStart, placement.placed);
+    if (source === "moq") this.#noteOverlayMoqBlock(inst, blockStart);
+    const alreadyCompleted = fec.isBlockCompleted(blockStart, pid, name);
+    const recovered = fec.feedRepairSymbol(pid, repair.ssStart, repair.ssbLength, repair.rsId, repair.symbolData, name);
+    if (recovered && !alreadyCompleted) this.#routeOverlayRecovered(inst, blockStart, recovered);
+  }
+  #replayOverlaySources(inst, blockStart, placed) {
+    const { fec, repairPacketId: pid, streamName: name } = inst;
+    for (const { ssId, payload } of placed) {
+      if (payload.source === "moq") this.#noteOverlayMoqBlock(inst, blockStart);
+      if (payload.oversized) continue;
+      const alreadyCompleted = fec.isBlockCompleted(blockStart, pid, name);
+      const recovered = fec.feedSourceSymbol(pid, ssId, payload.symbolData, name);
+      if (recovered && !alreadyCompleted) this.#routeOverlayRecovered(inst, blockStart, recovered);
+    }
+  }
+  /**
+   * 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).
+   */
+  #feedOverlaySource(packetId, catalogTrackName, packet, header, sequenceNumber, rapFlag, source) {
+    if (this.#overlays.size === 0) return;
+    const ssId = keyframeOverlaySsId(header);
+    if (ssId === void 0) return;
+    for (const inst of this.#overlaysForSource(packetId, catalogTrackName)) {
+      this.#noteOverlaySsId(inst, ssId, sequenceNumber);
+      const identity = MmtpContainerParser.sourcePacketIdentity(packet, header);
+      if (identity !== null) {
+        inst.offsets.delete(identity.mpuSequenceNumber);
+        inst.offsets.set(identity.mpuSequenceNumber, ssId - sequenceNumber >>> 0);
+        if (inst.offsets.size > OVERLAY_OFFSET_MPUS) inst.offsets.delete(inst.offsets.keys().next().value);
+      }
+      const { fec, repairPacketId: pid, streamName: name } = inst;
+      const symbolData = packet.subarray(0, packet.length - 4);
+      const oversized = !fec.isoSourceFits(pid, symbolData.length);
+      const coords = fec.locateIsoSource(pid, name, ssId);
+      if (coords === null) {
+        fec.holdIsoSource(pid, name, ssId, {
+          symbolData,
+          source,
+          oversized,
+          evidence: sourceSymbolEvidence(packet, header, rapFlag, sequenceNumber)
+        });
+        continue;
+      }
+      if (source === "moq") this.#noteOverlayMoqBlock(inst, coords.sbn);
+      if (oversized) continue;
+      const alreadyCompleted = fec.isBlockCompleted(coords.sbn, pid, name);
+      const recovered = fec.feedSourceSymbol(pid, ssId, symbolData, name);
+      if (recovered && !alreadyCompleted) this.#routeOverlayRecovered(inst, coords.sbn, recovered);
+    }
+  }
+  #noteOverlayMoqBlock(inst, blockStart) {
+    inst.moqBlocks.add(blockStart);
+    const newest = inst.last?.ssId;
+    if (newest === void 0) return;
+    for (const start of inst.moqBlocks) {
+      if ((newest - start | 0) > OVERLAY_MOQ_HORIZON_BLOCKS * inst.k) inst.moqBlocks.delete(start);
+    }
+  }
+  /**
+   * An overlay SS_ID inconsistent with the source's packet_sequence_number
+   * advance since the last one is an overlay restart (an FFmpeg muxer start,
+   * a bridge swap that keeps psn continuous): it moved the other way, or
+   * further than the psn advance plus K_overlay. Reordering keeps the two
+   * consistent and is no restart.
+   */
+  #noteOverlaySsId(inst, ssId, psn) {
+    const last = inst.last;
+    if (last !== void 0) {
+      const dSs = ssId - last.ssId | 0;
+      const dPsn = psn - last.psn | 0;
+      const consistent = dSs === 0 ? dPsn === 0 : Math.sign(dSs) === Math.sign(dPsn) && Math.abs(dSs) <= Math.abs(dPsn) + inst.k;
+      if (!consistent) {
+        this.#overlayStats.restarts++;
+        this.#resetOverlay(inst);
+      } else if (dPsn < 0) {
+        return;
+      }
+    }
+    inst.last = { ssId, psn };
+  }
+  /**
+   * 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.
+   */
+  #routeOverlayRecovered(inst, blockStart, recovered) {
+    const { fec, repairPacketId: pid, streamName: name } = inst;
+    fec.markBlockCompleted(blockStart, pid, name);
+    const sourcePacketId = inst.leg.sourcePacketId;
+    const sourceName = inst.leg.sourceCatalogTrackName;
+    if (this.#classifyPacketId(sourcePacketId) === null) return;
+    const receiver = this.#provenanceFor(sourcePacketId, sourceName);
+    if (receiver !== void 0 && inst.moqBlocks.has(blockStart)) {
+      this.#overlayStats.protectedDropped++;
+      return;
+    }
+    const blockProfile = fec.blockProfileForPacket(pid);
+    const symbolSize = fec.symbolSizeForPacket(pid);
+    if (blockProfile === void 0 || symbolSize === void 0 || !(symbolSize > 0)) return;
+    const result = processFecBlock(recovered, { symbolSize, ownerPacketId: sourcePacketId, blockProfile });
+    const streamKey = this.#mediaStreamKey(sourcePacketId, sourceName);
+    const restamped = this.#restampedStreams.has(streamKey);
+    const restored = /* @__PURE__ */ new Set();
+    const symbols = result.symbols.flatMap((sym) => {
+      const offset = inst.offsets.get(sym.fragment.mpuSequenceNumber);
+      if (offset !== void 0) {
+        const packetSequenceNumber = serial32Add(blockStart, sym.index) - offset >>> 0;
+        restored.add(packetSequenceNumber);
+        return [{ ...sym, packetSequenceNumber }];
+      }
+      if (!restamped) return [sym];
+      this.#overlayStats.unsequencedDropped++;
+      return [];
+    });
+    this.#overlayStats.recovered++;
+    this.#routeProcessedFecSymbols(blockStart, { ...result, symbols }, sourcePacketId, sourceName, {
+      deliveryProvenance: inst.moqBlocks.has(blockStart) ? "mixed" : "multicast"
+    });
+    this.#noteOverlayRecoveredRaps(sourcePacketId, sourceName, streamKey, symbols.filter((sym) => restored.has(sym.packetSequenceNumber)));
+  }
+  /** fec-multicast-00 §6.6: report each base block whose RAP MFU fragments
+   *  the overlay restored, when the keyframe's FT=0 and FT=1 are held too. A
+   *  packet whose wire sequence was not restored names no base block. */
+  #noteOverlayRecoveredRaps(packetId, catalogTrackName, streamKey, symbols) {
+    const ssIdSeqOffset = this.#ssIdSeqOffsetByStream.get(streamKey);
+    if (ssIdSeqOffset === void 0 || this.#overlayRecoveredObservers.size === 0) return;
+    const withMeta = (type) => new Set(symbols.filter((sym) => sym.fragmentType === type).map((sym) => sym.fragment.mpuSequenceNumber));
+    const ft0 = withMeta(0);
+    const ft1 = withMeta(1);
+    const rapMfu = (fi) => new Set(symbols.filter((sym) => sym.fragmentType === 2 && sym.fragment.rapFlag && sym.fragment.fragmentationIndicator === fi).map((sym) => sym.fragment.mpuSequenceNumber));
+    const single = rapMfu(0);
+    const first = rapMfu(1);
+    const last = rapMfu(3);
+    const blocks = /* @__PURE__ */ new Set();
+    for (const sym of symbols) {
+      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;
+      const ssId = sym.packetSequenceNumber + ssIdSeqOffset >>> 0;
+      const sbn = this.#fecManager?.locateIsoSource?.(packetId, catalogTrackName, ssId)?.sbn;
+      if (sbn !== void 0) blocks.add(sbn);
+    }
+    for (const sbn of blocks) {
+      for (const observer of this.#overlayRecoveredObservers) observer(packetId, catalogTrackName, sbn);
+    }
+  }
   /**
    * Register callback fired when a delta-track FEC block completes or fails.
    *
@@ -17478,6 +17781,11 @@ var MmtpRouter = class {
       return;
     }
     const repairPacketId = header.packetId;
+    const overlay = this.#overlayRepairTarget(repairPacketId, repairTrackName);
+    if (overlay !== void 0) {
+      this.#routeOverlayRepair(overlay, repairPacketId, packet, header, "moq");
+      return;
+    }
     const hintedOwner = ownerPacketIdHint != null && this.#classifyPacketId(ownerPacketIdHint) !== null ? ownerPacketIdHint : null;
     const ownerPacketId = hintedOwner ?? (this.#classifyPacketId(repairPacketId) !== null ? repairPacketId : null);
     if (ownerPacketId === null) {
@@ -17767,6 +18075,8 @@ var MmtpRouter = class {
       }
     }
     this.#parser.resetTrack(packetId, catalogTrackName);
+    this.resetKeyframeOverlays(packetId, catalogTrackName);
+    this.#restampedStreams.delete(this.#mediaStreamKey(packetId, catalogTrackName));
     const assistPrefix = assistKey(packetId, catalogTrackName, 0).slice(0, -1);
     for (const key of this.#assistBlocks.keys()) if (key.startsWith(assistPrefix)) this.#assistBlocks.delete(key);
     for (const key of this.#assistFailures.keys()) if (key.startsWith(assistPrefix)) this.#assistFailures.delete(key);
@@ -17853,6 +18163,17 @@ var MmtpRouter = class {
     this.#packetIdRoles.delete(packetId);
     this.#catalogTrackNamesByPacketId.delete(packetId);
     this.#repairOwnersByPacketId.delete(packetId);
+    this.#overlayLegs.delete(packetId);
+    for (const [repairPacketId, leg] of [...this.#overlayLegs]) {
+      if (leg.sourcePacketId === packetId) this.#overlayLegs.delete(repairPacketId);
+    }
+    for (const [name, leg] of [...this.#overlayRepairNames]) {
+      if (leg.sourcePacketId === packetId) this.#overlayRepairNames.delete(name);
+    }
+    this.#overlays.delete(packetId);
+    for (const [repairPacketId, inst] of [...this.#overlays]) {
+      if (inst.leg.sourcePacketId === packetId) this.#overlays.delete(repairPacketId);
+    }
     delete this.#pidCounts[packetId];
     delete this.#repairPidCounts[packetId];
     delete this.#moqRepairPidCounts[packetId];
@@ -18091,6 +18412,9 @@ var MmtpRouter = class {
     this.#parserDiagnostics.clear();
     this.#catalogTrackNamesByPacketId.clear();
     this.#repairOwnersByPacketId.clear();
+    this.#overlayLegs.clear();
+    this.#overlayRepairNames.clear();
+    this.#overlays.clear();
     for (const { receiver } of this.#provenance.values()) receiver.release();
     this.#provenance.clear();
     this.#provenanceStreamFlow.clear();
@@ -18446,6 +18770,11 @@ var MmtpRouter = class {
       }
     }
     if (info.isRepair) {
+      const overlay = this.#overlayRepairTarget(info.packetId, catalogTrackNameForPacket(ingress, info.packetId));
+      if (overlay !== void 0) {
+        this.#routeOverlayRepair(overlay, info.packetId, packet, parsed.header, source);
+        return;
+      }
       const ownerPacketId = this.#resolveRepairOwnerPacketId(info.packetId, ingress);
       if (ownerPacketId != null && this.#fecManager && hasAmbiguousCatalogTrackName(ingress, ownerPacketId)) return;
       const repair = this.#readRepairObject(
@@ -18652,6 +18981,17 @@ var MmtpRouter = class {
           });
         }
       }
+      if (!overlapCopy && this.#classifyPacketId(info.packetId) !== null) {
+        this.#feedOverlaySource(
+          info.packetId,
+          catalogTrackName,
+          packet,
+          parsed.header,
+          info.sequenceNumber,
+          info.rapFlag,
+          source
+        );
+      }
     }
   }
   /**
@@ -19105,12 +19445,12 @@ var MmtpRouter = class {
     }
     return match;
   }
-  #routeProcessedFecSymbols(blockId, result, ownerPacketId, catalogTrackName) {
+  #routeProcessedFecSymbols(blockId, result, ownerPacketId, catalogTrackName, overlay) {
     if (ownerPacketId == null) return;
     if (this.#classifyPacketId(ownerPacketId) === null) return;
-    const ssIdSeqOffset = this.#ssIdSeqOffsetByStream.get(
-      this.#mediaStreamKey(ownerPacketId, catalogTrackName)
-    );
+    const fecSbnOf = (index) => overlay ? {} : { fecSbn: this.#fecAnchorForRecovered(blockId, index) };
+    const streamKey = this.#mediaStreamKey(ownerPacketId, catalogTrackName);
+    const ssIdSeqOffset = overlay ? void 0 : this.#ssIdSeqOffsetByStream.get(streamKey);
     if (ssIdSeqOffset !== void 0) {
       result = {
         ...result,
@@ -19118,12 +19458,13 @@ var MmtpRouter = class {
           const wire = this.#fecAnchorForRecovered(blockId, sym.index) - ssIdSeqOffset >>> 0;
           if (wire === sym.packetSequenceNumber) return sym;
           this.#restampedRecoveredSeqs++;
+          this.#restampedStreams.add(streamKey);
           return { ...sym, packetSequenceNumber: wire };
         })
       };
     }
-    this.#stream(ownerPacketId, catalogTrackName).duplicates.advance(blockId);
-    const deliveryProvenance = this.#fecManager?.blockDeliveryProvenance?.(
+    if (!overlay) this.#stream(ownerPacketId, catalogTrackName).duplicates.advance(blockId);
+    const deliveryProvenance = overlay?.deliveryProvenance ?? this.#fecManager?.blockDeliveryProvenance?.(
       blockId,
       ownerPacketId,
       catalogTrackName
@@ -19201,7 +19542,7 @@ var MmtpRouter = class {
               rapFlag: sym.fragment.rapFlag,
               recovered: true,
               deliveryProvenance,
-              fecSbn: this.#fecAnchorForRecovered(blockId, sym.index),
+              ...fecSbnOf(sym.index),
               ...catalogTrackName === void 0 ? {} : { catalogTrackName }
             });
             continue;
@@ -19313,7 +19654,7 @@ var MmtpRouter = class {
                 rapFlag: assembled.rapFlag,
                 recovered: true,
                 ...assembled.deliveryProvenance === void 0 ? {} : { deliveryProvenance: assembled.deliveryProvenance },
-                fecSbn: this.#fecAnchorForRecovered(blockId, sym.index),
+                ...fecSbnOf(sym.index),
                 ...recoveredCatalogTrackName === void 0 ? {} : { catalogTrackName: recoveredCatalogTrackName }
               });
               continue;
@@ -19450,7 +19791,7 @@ var MmtpRouter = class {
             rapFlag: sym.fragment.rapFlag,
             recovered: true,
             deliveryProvenance,
-            fecSbn: this.#fecAnchorForRecovered(blockId, sym.index),
+            ...fecSbnOf(sym.index),
             ...catalogTrackName === void 0 ? {} : { catalogTrackName }
           });
         } else {
@@ -19529,7 +19870,7 @@ var MmtpRouter = class {
               rapFlag: assembled.rapFlag,
               recovered: true,
               deliveryProvenance,
-              fecSbn: this.#fecAnchorForRecovered(blockId, sym.index),
+              ...fecSbnOf(sym.index),
               ...assembled.catalogTrackName === void 0 ? {} : { catalogTrackName: assembled.catalogTrackName }
             });
           }
@@ -19564,7 +19905,7 @@ var MmtpRouter = class {
             ...sym.fragment.sampleNumber === void 0 ? {} : { sampleNumber: sym.fragment.sampleNumber },
             recovered: true,
             deliveryProvenance,
-            fecSbn: this.#fecAnchorForRecovered(blockId, sym.index),
+            ...fecSbnOf(sym.index),
             ...catalogTrackName === void 0 ? {} : { catalogTrackName }
           });
           continue;
@@ -21896,7 +22237,7 @@ function newBlockPolicyStats(packetId, catalogTrackName, epoch) {
     repairsSkippedRangeNoAnchor: 0,
     repairsSkippedGroupCannotComplete: 0,
     repairsSkippedMootRap: 0,
-    repairStops: { preempted: 0, reprioritized: 0, expired: 0, resolved: 0, reset: 0, disposed: 0, moot: 0 },
+    repairStops: { preempted: 0, reprioritized: 0, expired: 0, resolved: 0, reset: 0, disposed: 0, moot: 0, "overlay-recovered": 0 },
     lastRepairSkip: null,
     keyframeRepairFetchesSent: 0,
     rangeRepairFetchesSent: 0,
@@ -22229,9 +22570,7 @@ function repairTrackNamesBySource(tracks) {
 }
 function boundRepairNames(binding) {
   if (binding?.status !== "ok") return [];
-  const names = binding.layers.map((layer) => layer.repairTrackName);
-  if (binding.overlay) names.push(binding.overlay.repairTrackName);
-  return names;
+  return binding.layers.map((layer) => layer.repairTrackName);
 }
 var MulticastManager = class {
   #fec;
@@ -22245,6 +22584,10 @@ var MulticastManager = class {
   /** Live joinRepairEndpoints() releases → the repair owners they registered,
    *  re-applied after configureMultiTrack() clears catalog-derived owners. */
   #repairReleases = /* @__PURE__ */ new Map();
+  /** Each source's catalog keyframe overlay, from its `ok` binding. */
+  #overlayBindings = /* @__PURE__ */ new Map();
+  /** Installed overlay decoders (`setKeyframeOverlayDecoder`), by source. */
+  #overlayInstalls = /* @__PURE__ */ new Map();
   #reportedFecDiagnosticsFailure = false;
   // ── Stream-global FEC timing reduction ──
   //
@@ -22485,6 +22828,63 @@ var MulticastManager = class {
     this.#configureTrackMapper(packetId, fecConfig);
     this.#router.setPacketIdType(packetId, trackType);
   }
+  /**
+   * Decode the keyframe overlay of `sourcePacketId` (draft-ramadan-mmt-fec-02
+   * 7.4) with `decoder`, a decoder of the same kind `setFecDecoder` takes.
+   * Opt-in: nothing else installs one, so a receiver that never calls this
+   * holds no overlay state and drops overlay repair. K_overlay, T, scheme
+   * and block profile come from the source's `ok` catalog binding, which
+   * must declare an overlay (`configureMultiTrack` first). The overlay is
+   * decoded on its own FEC state, apart from the base: no repair FETCH, no
+   * repair lifecycle event and no base statistic for its blocks. A second
+   * install on the same source replaces the first; the returned disposer
+   * removes only the install it created. Call it on releasing the overlay
+   * join.
+   */
+  setKeyframeOverlayDecoder(sourcePacketId, decoder, catalogTrackName) {
+    const binding = this.#overlayBindings.get(sourcePacketId);
+    if (!binding || catalogTrackName !== void 0 && binding.sourceCatalogTrackName !== catalogTrackName) {
+      throw new Error(
+        `[MulticastManager] packetId=${sourcePacketId} has no catalog keyframe overlay to decode`
+      );
+    }
+    this.#overlayInstalls.get(sourcePacketId)?.dispose();
+    let fec;
+    let uninstall;
+    const attach = () => {
+      fec = new FECManager();
+      fec.setFecDecoder(binding.repairPacketId, decoder, binding.k, {
+        blockProfile: binding.blockProfile,
+        k: binding.k,
+        symbolSize: binding.symbolSize,
+        trackKind: "video"
+      }, binding.repairTrackName);
+      uninstall = this.#router.installKeyframeOverlay(
+        binding.repairPacketId,
+        fec,
+        binding.k,
+        binding.repairTrackName
+      );
+    };
+    const detach = () => {
+      uninstall();
+      fec.releasePacket(binding.repairPacketId);
+    };
+    attach();
+    const install = {
+      reattach: () => {
+        detach();
+        attach();
+      },
+      dispose: () => {
+        if (this.#overlayInstalls.get(sourcePacketId) !== install) return;
+        this.#overlayInstalls.delete(sourcePacketId);
+        detach();
+      }
+    };
+    this.#overlayInstalls.set(sourcePacketId, install);
+    return install.dispose;
+  }
   /**
    * Register a Worker-backed FEC decoder for a specific packetId (track).
    * Worker-backed tracks decode asynchronously — recovered frames arrive via
@@ -22997,7 +23397,11 @@ var MulticastManager = class {
         console.warn("[MulticastManager] repair group release failed", error);
       }
     };
-    const repairOwners = endpoints.flatMap((endpoint) => endpoint.repairOwners);
+    const repairOwners = endpoints.flatMap((endpoint) => endpoint.repairOwners.map((owner) => owner.instance !== "keyframe" ? owner : {
+      ...owner,
+      ownerTrackName: endpoint.tracks.find((t) => t.packetId === owner.ownerPacketId)?.name,
+      repairTrackName: endpoint.tracks.find((t) => t.packetId === owner.packetId)?.name
+    }));
     this.#applyRepairOwners(repairOwners);
     for (const endpoint of endpoints) {
       const ingress = {
@@ -23045,9 +23449,17 @@ var MulticastManager = class {
     return release;
   }
   #applyRepairOwners(owners) {
-    for (const { packetId, ownerPacketId } of owners) {
+    for (const { packetId, ownerPacketId, instance, ownerTrackName, repairTrackName } of owners) {
       this.#router.setPacketIdRole(packetId, "repair");
-      this.#router.setRepairPacketIdOwner(packetId, ownerPacketId);
+      if (instance === "keyframe") {
+        this.#router.setKeyframeOverlayLeg(packetId, {
+          sourcePacketId: ownerPacketId,
+          ...ownerTrackName === void 0 ? {} : { sourceCatalogTrackName: ownerTrackName },
+          ...repairTrackName === void 0 ? {} : { repairTrackName }
+        });
+      } else {
+        this.#router.setRepairPacketIdOwner(packetId, ownerPacketId);
+      }
     }
   }
   // ---------------------------------------------------------------------------
@@ -23311,8 +23723,8 @@ var MulticastManager = class {
     this.#fec.setMulticastSymbolDelivery(delivery);
   }
   /** Process a repair packet from MoQ (reliable QUIC). */
-  processRepairFromMoQ(packet, ownerPacketId, catalogTrackName) {
-    this.#router.feedRepairPacket(packet, ownerPacketId, catalogTrackName);
+  processRepairFromMoQ(packet, ownerPacketId, catalogTrackName, repairTrackName) {
+    this.#router.feedRepairPacket(packet, ownerPacketId, catalogTrackName, repairTrackName);
   }
   /** Route a Worker-recovered FEC block through the MMTP parser + dedup pipeline. */
   routeRecoveredBlock(blockId, data, packetId, catalogTrackName) {
@@ -23364,7 +23776,10 @@ var MulticastManager = class {
     const ownedRepairNames = /* @__PURE__ */ new Set();
     const claimed = /* @__PURE__ */ new Map();
     for (const binding of bindings.values()) {
-      for (const name of boundRepairNames(binding)) claimed.set(name, (claimed.get(name) ?? 0) + 1);
+      const overlay = binding.status === "ok" ? binding.overlay?.repairTrackName : void 0;
+      for (const name of [...boundRepairNames(binding), ...overlay === void 0 ? [] : [overlay]]) {
+        claimed.set(name, (claimed.get(name) ?? 0) + 1);
+      }
     }
     for (const [name, count] of claimed) if (count === 1) ownedRepairNames.add(name);
     const repairOwnerGroup = /* @__PURE__ */ new Map();
@@ -23467,6 +23882,7 @@ var MulticastManager = class {
     const catalogTracksByName = new Map(
       catalog.tracks.map((track) => [track.name, track])
     );
+    const overlayBindings = /* @__PURE__ */ new Map();
     for (let i = 0; i < catalog.tracks.length; i++) {
       const track = catalog.tracks[i];
       const role = resolvedRoles[i];
@@ -23495,6 +23911,29 @@ var MulticastManager = class {
               this.#router.setRepairPacketIdOwner(repairTrack.packetId, track.packetId);
             }
           }
+          const overlayName = binding.overlay?.repairTrackName;
+          const overlayPacketId = overlayName === void 0 ? void 0 : catalogTracksByName.get(overlayName)?.packetId;
+          if (overlayName !== void 0 && ownedRepairNames.has(overlayName)) {
+            this.#router.setKeyframeOverlayLeg(overlayPacketId, {
+              sourcePacketId: track.packetId,
+              sourceCatalogTrackName: track.name,
+              repairTrackName: overlayName
+            });
+          }
+          if (overlayName !== void 0 && overlayPacketId !== void 0 && ownedRepairNames.has(overlayName)) {
+            const geometry2 = binding.overlay.geometry;
+            overlayBindings.set(track.packetId, {
+              repairPacketId: overlayPacketId,
+              repairTrackName: overlayName,
+              sourceCatalogTrackName: track.name,
+              k: binding.overlay.sourceSymbols,
+              symbolSize: fecCfg.symbolSize,
+              blockProfile: parseFecBlockProfile(
+                geometry2.blockProfile,
+                `tracks[${JSON.stringify(track.name)}].fec keyframe overlay blockProfile`
+              )
+            });
+          }
         }
         const wasmDecoder = fecDecoders.get(i);
         if (track.packetId !== void 0 && wasmDecoder !== void 0) {
@@ -23528,6 +23967,16 @@ var MulticastManager = class {
         }
       }
     }
+    for (const [sourcePacketId, install] of [...this.#overlayInstalls]) {
+      const before = this.#overlayBindings.get(sourcePacketId);
+      const after = overlayBindings.get(sourcePacketId);
+      const same = before !== void 0 && after !== void 0 && Object.keys(after).every((key) => after[key] === before[key]);
+      if (!same) install.dispose();
+      else if (this.#router.hasKeyframeOverlay(after.repairPacketId)) this.#router.resetKeyframeOverlays(sourcePacketId);
+      else install.reattach();
+    }
+    this.#overlayBindings.clear();
+    for (const [sourcePacketId, binding] of overlayBindings) this.#overlayBindings.set(sourcePacketId, binding);
   }
   /**
    * Why `configureMultiTrack` consumes the named catalog track without FEC
@@ -23699,6 +24148,10 @@ var MulticastManager = class {
   addRapCompleteObserver(observer) {
     return this.#router.addFecRapObserver(observer);
   }
+  /** Observe each base block whose RAP the keyframe overlay recovered (fec-multicast-00 §6.6). */
+  addKeyframeOverlayRecoveredObserver(observer) {
+    return this.#router.addKeyframeOverlayRecoveredObserver(observer);
+  }
   /** Catalog/reset epoch of a packet's streams; gap decisions carry it. */
   epochFor(packetId) {
     return this.#fec.epochFor(packetId);