@blockcast/mmt-container 2.1.0 → 2.2.0-main.079cd7664c0b

package/src/mmtp-router.ts

@@ -23,7 +23,8 @@ import {
   type MMTPHeader,
   type MoqRepairFrame,
 } from "@blockcast/mmt-base";
-import type { FECManager, IsoHeldSource, WasmFecDecoder } from "./fec-manager.js";
+import { USER_AGENT_VERIFIED } from "@blockcast/mmt-transport";
+import type { FECManager, IsoHeldSource, RebuiltSourceFeed, WasmFecDecoder } from "./fec-manager.js";
 import type { IsoPlacedSource, IsoRepairPlacement } from "./iso-block-locator.js";
 import { isMfuReassemblyError } from "./mfu-reassembler.js";
 import type {
@@ -47,10 +48,12 @@ import {
 } from "./cmaf-block-assembler.js";
 import {
   MmtpContainerParser,
+  authoredAdjacent,
   isMfuKeyframeMetadata,
   type FecReleaseGate,
   type FrameMeta as ParserFrameMeta,
   type ParsedMmtpPacket,
+  type MmtpRecoveredHeadTimingStats,
 } from "./mmtp-container-parser.js";
 import { type TrackRole } from "./carp-catalog.js";
 import {
@@ -211,6 +214,61 @@ export interface KeyframeOverlayStats {
   restarts: number;
   unsequencedDropped: number;
   protectedDropped: number;
+  /** Rebuilt packets fed to their base block's decoder (joint decoding). */
+  baseFed: number;
+  /** Rebuilt packets the base never took: no base SS_ID could be determined. */
+  baseUndetermined: number;
+}
+
+/**
+ * The newest received overlay member of one MPU. `psnOffset` (overlay SS_ID
+ * minus wire packet_sequence_number) restores a rebuilt packet's wire
+ * sequence; the member's own SS_IDs anchor a rebuilt packet's base SS_ID
+ * (overlayBaseSsId).
+ */
+interface OverlayMemberAnchor {
+  readonly psnOffset: number;
+  readonly overlaySsId: number;
+  /** The member's base SS_ID, from its Source FEC Payload ID. */
+  readonly baseSsId?: number;
+}
+
+/**
+ * The base SS_ID of a packet the overlay rebuilt at `overlaySsId`, which an
+ * overlay coordinate alone never yields (draft-ramadan-moq-mmt-02 7.1). Both
+ * SS_IDs advance by one per packet along a run of consecutive overlay
+ * members, so base minus overlay SS_ID is the anchor's along a run the wire
+ * proves to be all members: one over which the rebuilt packet's protected
+ * packet_sequence_number (`headerPsn`) advanced from the anchor's exactly as
+ * the overlay SS_ID did (`restoredPsn`), so no other packet lies inside it.
+ * A hop that re-stamped packet_sequence_number after protection fails the
+ * test. Undefined when it fails.
+ */
+function overlayBaseSsId(
+  anchor: OverlayMemberAnchor,
+  overlaySsId: number,
+  restoredPsn: number,
+  headerPsn: number,
+): number | undefined {
+  if (anchor.baseSsId === undefined || headerPsn !== restoredPsn) return undefined;
+  return serial32Add(anchor.baseSsId, (overlaySsId - anchor.overlaySsId) | 0);
+}
+
+/** 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 {
@@ -222,8 +280,8 @@ interface OverlayInstance {
   readonly k: number;
   /** The newest overlay symbol seen: its overlay SS_ID and wire sequence. */
   last?: { ssId: number; psn: number };
-  /** MPU sequence number → overlay SS_ID − wire packet_sequence_number. */
-  readonly offsets: Map<number, number>;
+  /** MPU sequence number → its newest received member. */
+  readonly offsets: Map<number, OverlayMemberAnchor>;
   /** Overlay blocks a MoQ symbol fed (multicast-02 7.2.7). */
   readonly moqBlocks: Set<number>;
 }
@@ -245,6 +303,14 @@ export interface MmtpIngressContext {
    * the same ingress and `feedPacket` splits them off.
    */
   flow?: string;
+  /**
+   * `USER_AGENT_VERIFIED` when the datagram came from the browser's own
+   * MulticastReceiver, which verified the flow's records itself and delivers
+   * only admitted data (`userAgentVerifiedIngress` in
+   * `@blockcast/mmt-transport`). A protected multicast datagram carrying it
+   * is admitted without a record. Any other value means nothing.
+   */
+  admittedBy?: symbol;
 }
 
 /** One physical stream: an MMTP packet ID and the catalog track it carries. */
@@ -502,6 +568,9 @@ export type RoutedPacketMeta = {
   mmtpTimestamp: bigint;
   /**
    * The MMTP header RAP flag: the packet starts a random access point. On a
+   * track under a keyframe overlay it is also set on the FT=0 and FT=1 data
+   * units that govern a covered keyframe (draft-ramadan-moq-mmt-02 7.4.2), so
+   * it can precede the keyframe's first MFU fragment. On a
    * `recovered` packet it is read from the FEC-reconstructed header, which is
    * byte-exact outside packet_sequence_number, so it is the flag the
    * publisher sent. The router's own gap decisions deliberately ignore it for
@@ -565,6 +634,7 @@ interface StreamLedgers {
    *   the pair.
    */
   readonly duplicates: StreamDuplicateLedgers;
+  readonly overlayToBase: OverlayToBase;
 }
 
 const NO_FEC_MANAGER_HORIZON: DuplicateHorizon = Object.freeze({
@@ -652,6 +722,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;
 
@@ -946,6 +1027,15 @@ function sourceSymbolEvidence(
   };
 }
 
+/** One protected flow: its 7.2.7 receiver, and the ingress its datagrams arrive with. */
+interface ProvenanceEntry {
+  receiver: BcProvenanceV2Receiver;
+  ingress: MmtpIngressContext;
+  protected?: boolean;
+  /** A datagram the user agent verified admitted the flow (`admittedBy`). */
+  userAgent?: boolean;
+}
+
 export class MmtpRouter {
   readonly #parser: MmtpContainerParser;
   // Source AND FEC-recovered MFU fragments share ONE reassembler — the parser's
@@ -955,10 +1045,7 @@ export class MmtpRouter {
   #defaultFecMapper: FecBlockMapper | null;
   #fecMappersByPacketId = new Map<number, FecBlockMapper>();
   /** Protected flows: one 7.2.7 receiver each, and the ingress its datagrams arrive with. */
-  readonly #provenance = new Map<
-    string,
-    { receiver: BcProvenanceV2Receiver; ingress: MmtpIngressContext; protected?: boolean }
-  >();
+  readonly #provenance = new Map<string, ProvenanceEntry>();
   #onFlowProtected: ((flow: string) => void) | null = null;
   #unadmittedListedDrops = 0;
   #unlistedRepairSetAside = 0;
@@ -1106,7 +1193,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:
@@ -1385,7 +1472,7 @@ export class MmtpRouter {
     const cb = this.#getFrameCallback(packetId);
     if (isVideo && !assembler) {
       if (frameMeta.recovered) {
-        this.#routeDirectRecoveredVideo(packetId, data, frameMeta, cb);
+        this.#routeDirectRecoveredVideo(packetId, data, frameMeta, cb, meta.fecSbn);
       } else {
         this.#routeDirectSourceVideo(packetId, data, frameMeta, cb);
       }
@@ -1900,6 +1987,11 @@ export class MmtpRouter {
     return { ...this.#overlayStats };
   }
 
+  /** Recovered FT=2 heads held for their FT=1, and how each left the wait (BLO-53369). */
+  get recoveredHeadsAwaitingTiming(): Readonly<MmtpRecoveredHeadTimingStats> {
+    return this.#parser.recoveredHeadsAwaitingTiming;
+  }
+
   #isOverlayRepair(repairPacketId: number, repairTrackName?: string): boolean {
     return this.#overlayLegs.has(repairPacketId) ||
       (repairTrackName !== undefined && this.#overlayRepairNames.has(repairTrackName));
@@ -1951,6 +2043,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 {
@@ -2028,7 +2127,8 @@ export class MmtpRouter {
    * A source packet that carries a 0x8B01 overlay SS_ID is also a symbol of
    * every overlay installed for its source, at that SS_ID, with the bytes the
    * base protects: the packet minus its 4-byte SS_ID trailer, extension
-   * included (7.1, 7.4.3).
+   * included (7.1, 7.4.3). `baseSsId` is that trailer's SS_ID, when the base
+   * FEC reads it.
    */
   #feedOverlaySource(
     packetId: number,
@@ -2038,6 +2138,7 @@ export class MmtpRouter {
     sequenceNumber: number,
     rapFlag: boolean,
     source: MmtpSourcePath,
+    baseSsId: number | undefined,
   ): void {
     if (this.#overlays.size === 0) return;
     const ssId = keyframeOverlaySsId(header);
@@ -2047,7 +2148,11 @@ export class MmtpRouter {
       const identity = MmtpContainerParser.sourcePacketIdentity(packet, header);
       if (identity !== null) {
         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;
@@ -2134,12 +2239,17 @@ export class MmtpRouter {
     const streamKey = this.#mediaStreamKey(sourcePacketId, sourceName);
     const restamped = this.#restampedStreams.has(streamKey);
     const restored = new Set<number>();
+    const baseSsIds = new Map<ProcessFecBlockResult["symbols"][number], number>();
     const symbols = result.symbols.flatMap((sym) => {
-      const offset = inst.offsets.get(sym.fragment.mpuSequenceNumber);
-      if (offset !== undefined) {
-        const packetSequenceNumber = (serial32Add(blockStart, sym.index) - offset) >>> 0;
+      const anchor = inst.offsets.get(sym.fragment.mpuSequenceNumber);
+      if (anchor !== undefined) {
+        const overlaySsId = serial32Add(blockStart, sym.index);
+        const packetSequenceNumber = (overlaySsId - anchor.psnOffset) >>> 0;
         restored.add(packetSequenceNumber);
-        return [{ ...sym, packetSequenceNumber }];
+        const out = { ...sym, packetSequenceNumber };
+        const baseSsId = overlayBaseSsId(anchor, overlaySsId, packetSequenceNumber, sym.packetSequenceNumber);
+        if (baseSsId !== undefined) baseSsIds.set(out, baseSsId);
+        return [out];
       }
       // A stream re-stamped by a bridge that no base recovery has shown yet
       // keeps the header's sequence too: from received packets alone the
@@ -2155,6 +2265,91 @@ export class MmtpRouter {
     });
     this.#noteOverlayRecoveredRaps(sourcePacketId, sourceName, streamKey, symbols.filter((sym) =>
       restored.has(sym.packetSequenceNumber)));
+    this.#feedOverlayRecoveredToBase(inst, blockStart, symbols, baseSsIds);
+  }
+
+  /**
+   * Joint decoding (BLO-52085). A packet the overlay rebuilt is a source of
+   * its base block too, once its base SS_ID is determined (overlayBaseSsId),
+   * so it is fed to the base decoder as a rebuilt source
+   * (FECManager.feedRebuiltSourceSymbol): the base block has one erasure
+   * fewer to solve, and its repair can recover the block's other packets.
+   * A base block no repair has stated yet takes it when one does
+   * (#feedPendingRebuilt).
+   *
+   * The overlay route already handled each packet fed (delivered it, or
+   * held an untimed head for its FT=1), so a base recovery routes none of
+   * them again (#routeVerifiedFecSymbols): a second recovered copy of a
+   * held head would wait in the parser for timing its first copy consumed.
+   * Only an overlay block decoded from multicast symbols alone is fed: with
+   * a MoQ symbol in it, the base block's recovery would depend on bytes
+   * that crossed no multicast socket, which the provenance counted from the
+   * block's own arrivals cannot show.
+   */
+  #feedOverlayRecoveredToBase(
+    inst: OverlayInstance,
+    blockStart: number,
+    symbols: ProcessFecBlockResult["symbols"],
+    baseSsIds: ReadonlyMap<ProcessFecBlockResult["symbols"][number], number>,
+  ): void {
+    const fec = this.#fecManager;
+    const owner = inst.leg.sourcePacketId;
+    const name = inst.leg.sourceCatalogTrackName;
+    if (!fec?.feedRebuiltSourceSymbol || inst.moqBlocks.has(blockStart)) return;
+    if (this.#classifyPacketId(owner) === null || fec.isTrackConfigured?.(owner) === false) return;
+    const { duplicates, overlayToBase: { routed } } = this.#stream(owner, name);
+    const feeds: Array<readonly [number, Uint8Array]> = [];
+    for (const sym of symbols) {
+      // A packet the base received already sits in its block.
+      if (duplicates.sourceSeqs.has(sym.packetSequenceNumber)) continue;
+      const ssId = baseSsIds.get(sym);
+      if (ssId === undefined) {
+        this.#overlayStats.baseUndetermined++;
+        continue;
+      }
+      routed.delete(ssId);
+      routed.add(ssId);
+      if (routed.size > OVERLAY_ROUTED_LIMIT) routed.delete(routed.values().next().value!);
+      feeds.push([ssId, sym.rawSymbol]);
+    }
+    // Any feed can recover the base block, whose routing must already skip
+    // every packet this recovery routed: all are registered before the first.
+    for (const [ssId, symbolData] of feeds) 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);
+      pending.set(ssId, symbolData);
+      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 (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
@@ -2329,12 +2524,13 @@ export class MmtpRouter {
     if (!entry) return;
     entry.receiver.release();
     entry.protected = false;
+    entry.userAgent = false;
     // ponytail: drops every governed block's record, not only this flow's; per-flow if joins multiply.
     this.#assistBlocks.clear();
     this.#assistFailures.clear();
   }
 
-  /** MoQ packets of a track a protected flow lists, dropped on its unicast path: duplicate, overflow, or listed by more than one flow. */
+  /** Packets of a track a protected flow lists, dropped unread: a MoQ copy (duplicate, overflow, or listed by more than one flow) or a multicast source datagram that names no flow, of a track a user-agent-admitted flow lists. */
   get unadmittedListedDropCount(): number {
     return this.#unadmittedListedDrops;
   }
@@ -2384,6 +2580,14 @@ export class MmtpRouter {
     return false;
   }
 
+  /** Whether a protected flow the user agent admitted lists `packetId`. */
+  #userAgentGoverns(packetId: number): boolean {
+    for (const entry of this.#provenance.values()) {
+      if (entry.protected && entry.userAgent && ingressHasPacketId(entry.ingress, packetId)) return true;
+    }
+    return false;
+  }
+
   /**
    * A MoQ repair symbol no protected flow lists, owned by a source track one
    * does: its FEC instance is governed (7.2.7 step 2) and takes only admitted
@@ -2503,7 +2707,7 @@ export class MmtpRouter {
       fec.cancelBlockTimeout(blockStart, ownerPacketId, catalogTrackName);
       fec.countRecovery(ownerPacketId, blockStart, catalogTrackName);
       fec.markBlockCompleted(blockStart, ownerPacketId, catalogTrackName);
-    })) {
+    }, true)) {
       this.#unlistedAssistedRecoveries++;
       this.#assistBlocks.delete(key);
       return;
@@ -2955,6 +3159,8 @@ export class MmtpRouter {
     }
     this.#replayIsoSources(ownerPacketId, catalogTrackName, blockStart, placement.placed);
     if (this.#classifyPacketId(ownerPacketId) === null) return;
+    this.#feedPendingRebuilt(ownerPacketId, catalogTrackName, placement.block);
+    if (this.#classifyPacketId(ownerPacketId) === null) return;
     if (!this.#feedFecTransportSymbol(
       ownerPacketId,
       blockStart,
@@ -3959,6 +4165,15 @@ export class MmtpRouter {
         debugRouter(`[MmtpRouter] Dropping multicast packet pid=${info.packetId}: flow ${ingress.flow} has no receiver`);
         return;
       }
+      // The user agent verified this datagram against the flow's records
+      // itself, and the records never reach the page: admitted as is. The
+      // flow stays registered, so its MoQ copies are still checked.
+      if (ingress.admittedBy === USER_AGENT_VERIFIED) {
+        this.#noteFlowAdmitted(ingress.flow);
+        protectedFlow.userAgent = true;
+        this.#processMMTP(packet, source, true, ingress, overlapCopy);
+        return;
+      }
       // Held: released by a record (feedProvenanceRecord) or expired. Duplicate / overflow: dropped.
       const { verdict } = protectedFlow.receiver.onDatagram(packet, "multicast");
       if (verdict === "admitted") {
@@ -3983,6 +4198,18 @@ export class MmtpRouter {
       }
     }
 
+    // A multicast datagram that names no flow is unverified. Of a track a
+    // user-agent-admitted flow lists it would feed that flow's live decoder,
+    // whose recoveries are kept without a record (#routeVerifiedFecSymbols):
+    // its source is dropped here and its repair set aside below, as for
+    // unlisted MoQ. Under a record-only flow it is read as before: those
+    // recoveries still need a record.
+    const flowless = source === "multicast" && !manifestAdmitted && ingress?.flow === undefined;
+    if (flowless && !info.isRepair && this.#userAgentGoverns(info.packetId)) {
+      this.#unadmittedListedDrops++;
+      return;
+    }
+
     if (info.isRepair) {
       // Repair packet — per ISO 23008-1 §C.5.3, carries (SS_Start, SSB_length, RS_ID).
       // Read from the header parsed above rather than parsing it again
@@ -4003,9 +4230,10 @@ export class MmtpRouter {
         );
         if (!repair) return;
         if (ownerPacketId != null && this.#fecManager) {
-          // An unadmitted MoQ symbol reaching here is unlisted (#admitUnicast).
+          // An unadmitted MoQ symbol reaching here is unlisted (#admitUnicast);
+          // a flow-less multicast one is unverified.
           if (
-            source === "moq" && !manifestAdmitted &&
+            ((flowless && this.#userAgentGoverns(ownerPacketId)) || (source === "moq" && !manifestAdmitted)) &&
             this.#setAsideUnlistedRepair(ownerPacketId, catalogTrackNameForPacket(ingress, ownerPacketId), repair)
           ) return;
         this.#repairPidCounts[info.packetId] = (this.#repairPidCounts[info.packetId] || 0) + 1;
@@ -4345,6 +4573,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,
         );
       }
     }
@@ -4573,6 +4802,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);
     }
@@ -4771,8 +5001,28 @@ export class MmtpRouter {
     data: Uint8Array,
     meta: RoutedFrameMeta,
     cb: FrameCallback | null,
+    /** The base SS_ID the FEC release gate ordered the frame by, if any. */
+    fecSbn: number | undefined,
   ): void {
     const streamKey = this.#mediaStreamKey(packetId, meta.catalogTrackName);
+    // The FEC release gate let this frame out in order: only once every
+    // block between it and the frame before it resolved, or because it
+    // starts where that frame ended. Nothing still in flight can precede it
+    // then, so it plays now, as a source frame does; holding it for the next
+    // intact frame cost every repaired burst its length in decoder input
+    // (BLO-52085). An overlay recovery names no base block for the gate to
+    // wait on, so past a gap it may be ahead of frames still in flight (an
+    // overlay that outran the wire, BLO-53342): it keeps waiting for the
+    // source cursor below, unless it starts where the last emitted frame
+    // ended (on this direct path, the delivered high water).
+    if (this.#isFecTrack(packetId)) {
+      const high = this.#deliveredVideoHighWaterByStream.get(streamKey);
+      if (fecSbn !== undefined || (high !== undefined && authoredAdjacent(high, meta))) {
+        this.#drainDirectRecoveredVideo(streamKey, packetId, frame => frame.timestamp <= meta.timestamp, cb);
+        this.#emitDirectVideo(packetId, data, meta, cb);
+        return;
+      }
+    }
     this.#enqueueDirectRecoveredVideo(packetId, data, meta);
     const lastSourceTs = this.#lastDirectSourceVideoTsByStream.get(streamKey);
     this.#drainDirectRecoveredVideo(
@@ -4950,6 +5200,7 @@ export class MmtpRouter {
     ownerPacketId?: number,
     catalogTrackName?: string,
     complete?: () => void,
+    assisted = false,
   ): boolean {
     // MMTP path: use processFecBlock for MMTP-wrapped recovery.
     // Recovered symbols are individual MMTP packets that may be fragments
@@ -4974,7 +5225,7 @@ export class MmtpRouter {
       ownerPacketId,
       blockProfile,
     });
-    return this.#routeVerifiedFecSymbols(blockId, result, ownerPacketId, catalogTrackName, complete);
+    return this.#routeVerifiedFecSymbols(blockId, result, ownerPacketId, catalogTrackName, complete, assisted);
   }
 
   /**
@@ -4987,6 +5238,19 @@ export class MmtpRouter {
    * recovered packets is refused is unrecovered (7.2.7): its caller leaves it
    * open, so it reaches its FEC deadline and fails by class. Always true
    * outside a protected flow.
+   *
+   * On a flow the user agent admitted, the live decoder's recoveries are kept
+   * without a record: while the flow is protected that decoder takes only
+   * symbols the user agent or a record verified (a flow-less multicast
+   * datagram of a listed track is dropped or set aside in #processMMTP), so
+   * what it recovers is as verified as they are. An `assisted` (scratch-decoder) recovery mixes in
+   * unlisted MoQ repair and still needs a record.
+   * ponytail: per-flow flag; per-block provenance only if a protected flow
+   * ever mixes verified and unverified live inputs.
+   * ponytail: a worker frame computed before the protection reset can still
+   * arrive after it (frames carry no epoch); its inputs are MoQ copies read
+   * and played before protection, so it admits nothing new. Drop pre-reset
+   * frames by epoch only if pre-protection input ever matters.
    */
   #routeVerifiedFecSymbols(
     blockId: number,
@@ -4994,8 +5258,22 @@ export class MmtpRouter {
     ownerPacketId?: number,
     catalogTrackName?: string,
     complete?: () => void,
+    assisted = false,
   ): boolean {
-    const receiver = ownerPacketId == null ? undefined : this.#provenanceFor(ownerPacketId, catalogTrackName);
+    // 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;
     let recovered = true;
     if (receiver) {
       const parsed = this.#stream(ownerPacketId!, catalogTrackName).duplicates.parsedSymbols;
@@ -5008,6 +5286,8 @@ export class MmtpRouter {
           let admitted = false;
           if (receiver === "ambiguous") {
             this.#ambiguousRecoveredDrops++;
+          } else if (userAgent) {
+            admitted = true;
           } else {
             const wire = new Uint8Array(sym.rawSymbol.byteLength + 4);
             wire.set(sym.rawSymbol);
@@ -5033,7 +5313,7 @@ export class MmtpRouter {
   #provenanceFor(
     packetId: number,
     catalogTrackName: string | undefined,
-  ): BcProvenanceV2Receiver | "ambiguous" | undefined {
+  ): ProvenanceEntry | "ambiguous" | undefined {
     // A caller that names no track matches every name the packet id was admitted under.
     const byName = this.#provenanceStreamFlow.get(packetId);
     const flows = new Set(
@@ -5042,12 +5322,12 @@ export class MmtpRouter {
         : byName.has(catalogTrackName) ? [byName.get(catalogTrackName)!] : [],
     );
     if (flows.size > 1) return "ambiguous";
-    for (const bound of flows) return this.#provenance.get(bound)?.receiver ?? "ambiguous";
-    let match: BcProvenanceV2Receiver | undefined;
-    for (const { receiver, ingress } of this.#provenance.values()) {
-      if (ingress.tracks.some((t) => t.packetId === packetId && (catalogTrackName === undefined || t.name === catalogTrackName))) {
+    for (const bound of flows) return this.#provenance.get(bound) ?? "ambiguous";
+    let match: ProvenanceEntry | undefined;
+    for (const entry of this.#provenance.values()) {
+      if (entry.ingress.tracks.some((t) => t.packetId === packetId && (catalogTrackName === undefined || t.name === catalogTrackName))) {
         if (match) return "ambiguous";
-        match = receiver;
+        match = entry;
       }
     }
     return match;
@@ -5141,6 +5421,43 @@ export class MmtpRouter {
       );
     }
 
+    // A recovered head whose sample FT=1 has not named yet (an overlay that
+    // outran the source path) would complete its data unit untimed: the unit
+    // is dropped, marked completed, and the timed source copy is then refused
+    // (BLO-53342). Hand it to the parser instead, which holds it in its
+    // awaiting-timing queue and feeds it again when FT=1 lands; its recovered
+    // continuations park in the reassembler meanwhile. If the source path
+    // lost the head, this held copy is the keyframe (BLO-53369).
+    const untimedHead = (sym: (typeof result.symbols)[number]): boolean =>
+      sym.fragmentType === 2 &&
+      sym.fragment.fragmentationIndicator === 1 &&
+      sym.fragment.movieFragmentSequenceNumber !== undefined &&
+      sym.fragment.sampleNumber !== undefined &&
+      !this.#parser.hasAuthoredTimingFor(
+        ownerPacketId,
+        sym.fragment.mpuSequenceNumber,
+        sym.fragment.movieFragmentSequenceNumber,
+        sym.fragment.sampleNumber,
+        catalogTrackName,
+      );
+    for (const sym of result.symbols) {
+      if (!untimedHead(sym) ||
+        this.#sourceSeqReceived(ownerPacketId, sym.packetSequenceNumber, catalogTrackName)) continue;
+      this.#feedViaParser(
+        sym.rawSymbol,
+        { packetId: ownerPacketId, sequenceNumber: sym.packetSequenceNumber },
+        undefined,
+        {
+          skipFecPayloadId: true,
+          recovered: true,
+          deliveryProvenance,
+          ...fecSbnOf(sym.index),
+          ...(catalogTrackName === undefined ? {} : { catalogTrackName }),
+        },
+      );
+    }
+    result = { ...result, symbols: result.symbols.filter((sym) => !untimedHead(sym)) };
+
     // MSE assembler path: route recovered block as pre-assembled frames (skip FT=0)
     // BLO-3035 layer 3: recovered symbols are RAW MFU fragments, not complete
     // frames. A keyframe can span multiple packets (FI=1/2/3); pushing each