@blockcast/mmt-container 2.1.0 → 2.2.0-main.050b52fb9b00

package/src/mmtp-container-parser.ts

@@ -173,6 +173,15 @@ export interface FrameMeta {
    * on FEC-gated streams.
    */
   fecSbn?: number
+  /**
+   * Set on a frame the keyframe overlay rebuilt (draft-ramadan-moq-mmt-02
+   * 7.4) whose base SS_IDs are determined: the lowest base SS_ID of its
+   * MPU's packets in that decode, its FT=0 when the decode holds it. The
+   * release gate waits only for the blocks before it, and stops waiting once
+   * a base frame after this one arrived. `fecSbn` stays the SS_ID the frame
+   * completed in.
+   */
+  fecSbnFirst?: number
   /**
    * Set on the first frame released after a gap: the blocks between it and
    * the previous release resolved with lost media, or authored decode time
@@ -242,13 +251,22 @@ export interface FecReleaseGate {
   isRap?(data: Uint8Array, meta: FrameMeta): boolean
   /** A complete RAP entered the gate at SS_ID `ssId` (see `isRap`). */
   onRap?(packetId: number, catalogTrackName: string | undefined, ssId: number): void
+  /**
+   * Whether what reads this stream decides on when its frames arrive (a
+   * staged stream switch): the gate then releases a held overlay-rebuilt
+   * frame when it did unanchored (#cursorPassed).
+   */
+  releaseUnanchored?(packetId: number, catalogTrackName: string | undefined): boolean
 }
 
 /** Typed ISO-BMFF timing-sample budget counters. See `timingBudgetStats`. */
 export interface MmtpTimingBudgetStats {
   /** Slots currently charged to declared-but-undelivered samples. */
   pending: number
-  /** Total slots available; `pending === capacity` rejects every new moof. */
+  /**
+   * Slots each stream's window holds (`maxBufferedMfus`). A stream at
+   * capacity displaces its own oldest timing; `pending` sums every stream.
+   */
   capacity: number
   /** Slots returned by samples the combiner abandoned (evicted or timed out). */
   reclaimed: number
@@ -259,7 +277,13 @@ export interface MmtpTimingBudgetStats {
    * up, `evicted` is loss that was never observable at all.
    */
   evicted: number
-  /** Movie fragments refused because the budget had no room for their samples. */
+  /**
+   * Movie fragments refused because the budget had no room for their samples.
+   * Stays 0 with a window per stream (BLO-52085): a stream at capacity
+   * displaces its own oldest timing to make room, and a moof declaring more
+   * samples than a whole window holds is refused as invalid before any budget
+   * is consulted. Kept as a guard, and because it is public.
+   */
   rejectedMovieFragments: number
 }
 
@@ -365,10 +389,22 @@ export type MmtpFeedDropReason =
   /** No timing resolver, or it refused the initialization segment. */
   | 'init-timing-refused'
   | 'fragment-unexpected-fragmentation'
+  /** FT=1 before an FT=0 has bound the stream's timing track. */
   | 'fragment-no-resolver'
-  /** addMovieFragment refused — includes the pending-timing-sample budget. */
+  /** addMovieFragment refused: the moof does not parse against the stream's
+   *  track, conflicts with a pending copy of itself, or repeats a pending
+   *  copy whose samples are partly consumed. Never the timing budget: a full
+   *  window displaces the stream's own oldest timing. */
   | 'fragment-timing-refused'
   | 'unknown-fragment-type'
+  /** Stable code, no longer produced: an FT=2 with no timing (before the
+   *  stream's first FT=0, or after setTrack dropped it) now waits for its
+   *  timing like one whose FT=1 has not arrived. A head counts as
+   *  `drop:mfu-sample-timing-missing` (parked) and a FI=2/FI=3 continuation
+   *  as the `pending` record. A continuation that completes a head the
+   *  reassembler buffered before the timing was dropped counts as
+   *  `drop:assembled-timing-missing`. A panel keyed on this code reads zero:
+   *  a re-attribution, not lost coverage. Re-key on both drop codes. */
   | 'mfu-no-resolver'
   | 'mfu-empty-payload'
   | 'mfu-du-header-missing'
@@ -499,6 +535,8 @@ export interface ParseHeaderOptions {
   deliveryProvenance?: MmtpDeliveryProvenance
   /** FEC source block this packet belongs to (FEC-protected packets only). */
   fecSbn?: number
+  /** See FrameMeta.fecSbnFirst. */
+  fecSbnFirst?: number
 }
 
 // ── FrameSequencer ──────────────────────────────────────────────────
@@ -679,7 +717,10 @@ class FrameSequencer {
 // ── FecReleaseSequencer ─────────────────────────────────────────────
 
 /** Authored decode-time adjacency: the next frame starts where this one ends. */
-function authoredAdjacent(before: FrameMeta, after: FrameMeta): boolean {
+export function authoredAdjacent(
+  before: Pick<FrameMeta, 'authoredTiming'>,
+  after: Pick<FrameMeta, 'authoredTiming'>,
+): boolean {
   const a = before.authoredTiming
   const b = after.authoredTiming
   if (!a || !b || a.mediaTimescale !== b.mediaTimescale) return false
@@ -709,9 +750,19 @@ function ssIdAfter(a: number, b: number): boolean {
   return ((a - b) | 0) > 0
 }
 
+/** The stream holds a frame the keyframe overlay rebuilt (FrameMeta.fecSbnFirst). */
+function holdsRebuilt(stream: GatedStream): boolean {
+  return stream.buf.some(({ meta }) => meta.fecSbnFirst !== undefined)
+}
+
 interface GatedFrame extends PendingFrame {
   /** performance.now() at push; measures the hold against the gate's limit. */
   arrivedAtMs: number
+  /**
+   * The unanchored path's gate is done with this frame (see #cursorPassed):
+   * it released it, or dropped it as stale.
+   */
+  passed?: boolean
 }
 
 interface GatedStream {
@@ -723,6 +774,10 @@ interface GatedStream {
   discontinuity: boolean
   /** Latest (serial order) SS_ID of a complete RAP that entered the gate since the last reset. */
   rapSsId: number | undefined
+  /** A frame that was not FEC-recovered was released since the last reset. */
+  sourced: boolean
+  /** Drains of this stream in progress: a release calls out, and back in (a stream switch's onCommit). */
+  draining: number
 }
 
 /**
@@ -731,9 +786,11 @@ interface GatedStream {
  * to the last released frame is released immediately. A frame after a gap
  * waits until every block between the last released frame's block and its
  * own has resolved; a D-28 repair or a late in-band recovery can therefore
- * still fill the gap. When the resolved blocks lost media, or authored decode
- * time shows a missing sample, the release carries the gate's stall/conceal
- * decision as `gapBefore`.
+ * still fill the gap. A frame the keyframe overlay rebuilt waits only for the
+ * blocks before its MPU (FrameMeta.fecSbnFirst), and no longer than the
+ * source cursor would hold it unanchored (#cursorPassed). When the resolved
+ * blocks lost media, or authored decode time shows a missing sample, the
+ * release carries the gate's stall/conceal decision as `gapBefore`.
  *
  * The wait is bounded here, not by the blocks: a frame held longer than the
  * gate's `holdLimitMs` since it arrived is released with the gate's
@@ -817,6 +874,7 @@ class FecReleaseSequencer {
       stream.lastSbn = undefined
       stream.discontinuity = false
       stream.rapSsId = undefined
+      stream.sourced = false
     }
     if (stream.last !== null && compareFrameOrder(frame, stream.last) <= 0) {
       this.#recordStat('droppedStale')
@@ -845,6 +903,8 @@ class FecReleaseSequencer {
       if (compareFrameOrder(stream.buf[mid]!, frame) < 0) lo = mid + 1
       else hi = mid
     }
+    // In front of a frame the unanchored path released, it was stale there.
+    if (stream.buf[lo]?.passed === true) frame.passed = true
     stream.buf.splice(lo, 0, frame)
     this.#drainUnlessDeferred(stream)
   }
@@ -883,6 +943,54 @@ class FecReleaseSequencer {
     return false
   }
 
+  /**
+   * These streams' sink is being replaced by one that has seen no source
+   * frame yet. First, from a stream that holds a frame the overlay rebuilt,
+   * release to the sink being replaced the frames the unanchored path had
+   * already released to it (#cursorPassed): there they waited in its queue,
+   * which its replacement flushes. A stream that holds none is not drained:
+   * it holds nothing the anchor kept back, and a drain would still force out
+   * a frame held past the hold limit, which before the anchor waited for the
+   * next push. Then treat the streams as unsourced until a source frame is
+   * released.
+   */
+  unsource(packetId: number, catalogTrackName: string | undefined): void {
+    for (const stream of this.#streams.values()) {
+      if (stream.packetId === packetId && (catalogTrackName === undefined || stream.catalogTrackName === catalogTrackName)) {
+        // From inside this stream's own drain (a sink replaced from a frame
+        // callback, as a stream switch's onCommit can), the drain under way
+        // releases the rest, in order, once the frame it is delivering is
+        // done (a commit delivers its held GOP and RAP after onCommit):
+        // released here, they would go ahead of them. Inside a deferral
+        // scope (a protected flow's record admits frames of several streams
+        // in one), the scope's drain does, for the same reason, into the
+        // replacement. With the stream unsourced, that drain lets a rebuilt
+        // frame go as unanchored did until it releases a source frame; a
+        // rebuilt frame behind that one waits for the blocks before it, as an
+        // anchored frame does (the record may hold the base frames it needs).
+        if (stream.draining === 0 && holdsRebuilt(stream)) {
+          if (this.#deferDepth > 0) this.#deferredStreams.add(stream)
+          else this.#drain(stream, true)
+        }
+        stream.sourced = false
+      }
+    }
+  }
+
+  /**
+   * Whether a stream of `packetId` holds a frame the keyframe overlay rebuilt
+   * (FrameMeta.fecSbnFirst). Without `catalogTrackName`, every stream of the
+   * packetId.
+   */
+  holdsRebuilt(packetId: number, catalogTrackName: string | undefined): boolean {
+    for (const stream of this.#streams.values()) {
+      if (stream.packetId !== packetId) continue
+      if (catalogTrackName !== undefined && stream.catalogTrackName !== catalogTrackName) continue
+      if (holdsRebuilt(stream)) return true
+    }
+    return false
+  }
+
   /** Re-evaluate held gaps after FEC state changed. */
   poke(streamKey?: string): void {
     if (streamKey !== undefined) {
@@ -989,16 +1097,34 @@ class FecReleaseSequencer {
         lastSbn: undefined,
         discontinuity: false,
         rapSsId: undefined,
+        sourced: false,
+        draining: 0,
       }
       this.#streams.set(streamKey, stream)
     }
     return stream
   }
 
-  #drain(stream: GatedStream): void {
+  /** `asUnanchored`: release overlay-rebuilt frames when unanchored did (#cursorPassed). */
+  #drain(stream: GatedStream, asUnanchored = false): void {
+    stream.draining++
+    try {
+      this.#drainLoop(stream, asUnanchored)
+    } finally {
+      stream.draining--
+    }
+  }
+
+  #drainLoop(stream: GatedStream, asUnanchored: boolean): void {
     while (stream.buf.length > 0 && stream.last !== null) {
       const head = stream.buf[0]!
       const last = stream.last
+      // A second held copy of the frame just released waits on nothing.
+      if (compareFrameOrder(head, last) <= 0) {
+        stream.buf.shift()
+        this.#release(stream, head, undefined)
+        continue
+      }
       if (stream.discontinuity) {
         stream.discontinuity = false
         stream.buf.shift()
@@ -1012,13 +1138,19 @@ class FecReleaseSequencer {
       }
       const headSbn = head.meta.fecSbn
       const from = stream.lastSbn ?? headSbn
-      const to = headSbn ?? stream.lastSbn
+      // An overlay-rebuilt frame waits only for the blocks before its MPU's
+      // first packet in that decode (fecSbnFirst): the overlay delivered the
+      // packets from there on.
+      const to = head.meta.fecSbnFirst ?? headSbn ?? stream.lastSbn
       let lost: readonly number[] = []
       // Neither side carries a Source FEC Payload ID: on a catalog-declared
       // FEC track that is the trailer-stripped profile violation, and there
       // are no blocks to wait on. The gap is still a gap: never release across
       // it undecided (fail closed), let the gate decide with no known blocks.
       const unanchored = from === undefined && to === undefined
+      // The source cursor released it (#cursorPassed) across blocks that have
+      // not resolved: nothing sized that gap either, so it is decided too.
+      let unresolved = false
       if (from !== undefined && to !== undefined) {
         const resolved = this.#gate.resolvedLoss(
           stream.packetId,
@@ -1027,7 +1159,8 @@ class FecReleaseSequencer {
           Math.max(from, to),
           from,
         )
-        if (resolved === null) {
+        unresolved = resolved === null
+        if (unresolved && !this.#cursorPassed(stream, asUnanchored)) {
           const heldMs = performance.now() - head.arrivedAtMs
           if (heldMs <= this.#gate.holdLimitMs(stream.packetId, stream.catalogTrackName)) return
           // Past the point where these blocks must have resolved: nothing
@@ -1037,7 +1170,7 @@ class FecReleaseSequencer {
           this.#release(stream, head, this.#gate.decide(last, head, [], true))
           continue
         }
-        lost = resolved
+        lost = resolved ?? []
       }
       stream.buf.shift()
       // Every gap in the frame sequence gets a decision, not only one whose
@@ -1048,19 +1181,67 @@ class FecReleaseSequencer {
       this.#release(
         stream,
         head,
-        lost.length > 0 || unanchored || authoredGap(last.meta, head.meta)
+        lost.length > 0 || unanchored || unresolved || authoredGap(last.meta, head.meta)
           ? this.#gate.decide(last, head, lost, false)
           : undefined,
       )
     }
   }
 
+  /**
+   * An overlay-rebuilt frame (fecSbnFirst) waits no longer than the BLO-53342
+   * source cursor holds it unanchored, and neither does a later frame behind
+   * it. Unanchored, a frame that waits on no block (fecSbnFirst set, or no
+   * fecSbn) left the gate once every frame ahead of it had: mark it `passed`,
+   * like each frame that arrived in front of it since (stale there). The head
+   * then goes, decided as it would be unanchored, once a frame the base path
+   * delivered (a source frame, or one base FEC recovered) is buffered after a
+   * marked one: the base path has passed that one, so a frame still missing
+   * before it can only come from a repair. It also goes while no source frame
+   * has been released, when the direct path shows a recovered frame at once.
+   * And it goes at once while a staged switch decides on when frames arrive
+   * (FecReleaseGate.releaseUnanchored), and when unsource releases into a
+   * sink being replaced: unanchored, it had already reached the sink.
+   * The scan also writes: the `passed` marks it sets stay on the frames,
+   * and push marks a frame it inserts in front of a marked one from them.
+   */
+  #cursorPassed(stream: GatedStream, asUnanchored: boolean): boolean {
+    let at = -1
+    for (let i = 0; i < stream.buf.length; i++) {
+      const frame = stream.buf[i]!
+      if (frame.meta.fecSbnFirst !== undefined || frame.meta.fecSbn === undefined) {
+        frame.passed = true
+        if (at < 0) at = i
+      } else if (frame.passed !== true) break
+    }
+    if (at < 0) return false
+    return asUnanchored || !stream.sourced ||
+      this.#gate.releaseUnanchored?.(stream.packetId, stream.catalogTrackName) === true ||
+      stream.buf.some(({ meta }, i) =>
+        i > at && meta.fecSbnFirst === undefined && (meta.recovered !== true || meta.fecSbn !== undefined))
+  }
+
   #release(stream: GatedStream, frame: PendingFrame, decision: FrameGapDecision | undefined): void {
+    // Two copies of one frame were held (its base copy and the overlay's
+    // rebuild) and the other went out: this one is stale, as a copy pushed
+    // after its frame was released is. It still moves the state as a release
+    // does: only the second emission is dropped.
+    const stale = stream.last !== null && compareFrameOrder(frame, stream.last) <= 0
+    if (stale) this.#recordStat('droppedStale')
     if (decision) frame.meta.gapBefore = decision
     stream.last = frame
-    if (frame.meta.fecSbn !== undefined) stream.lastSbn = frame.meta.fecSbn
+    // An overlay-rebuilt frame (fecSbnFirst) released before any base frame
+    // since the last reset leaves lastSbn unset, as it did unanchored: the
+    // base frame after it then waits for nothing, not for the frames between.
+    if (frame.meta.fecSbn !== undefined && (frame.meta.fecSbnFirst === undefined || stream.lastSbn !== undefined)) {
+      stream.lastSbn = frame.meta.fecSbn
+    }
+    if (frame.meta.recovered !== true) stream.sourced = true
+    // A stale copy of the frame just released (equal order) repeats an
+    // onReleased call already made: noteReleasedRap ignores a second RAP of
+    // an MPU it has anchored (the same MPU and presentation time).
     this.#gate.onReleased?.(frame.data, frame.meta)
-    this.#emit(frame.data, frame.meta)
+    if (!stale) this.#emit(frame.data, frame.meta)
   }
 }
 
@@ -1089,9 +1270,30 @@ interface AwaitingTimingHead {
   mpuSequenceNumber: number
   movieFragmentSequenceNumber: number
   sampleNumber: number
+  /** MMTP packet sequence number; a recovered copy carries its source's. */
+  sequenceNumber: number
   arrivedAt: number
 }
 
+/** FEC-recovered heads that went through the awaiting-timing queue. Every
+ * count but `pending` is cumulative. A held head is pending or has left the
+ * queue exactly once, so `held - expired - discarded - superseded - pending`
+ * is the number fed again once their FT=1 landed. That feed can still refuse
+ * one (size, offset, dispose from a frame callback); the refusal is counted in
+ * `feedStats.deferredOutcomes`, not here. */
+export interface MmtpRecoveredHeadTimingStats {
+  /** Held because their sample's FT=1 had not arrived yet. */
+  held: number
+  /** Left without timing: the reassembler-timeout deadline, or pushed out by the queue's capacity. */
+  expired: number
+  /** Dropped with their stream (track reconfigure, reset or retire) or by dispose(). */
+  discarded: number
+  /** Gave way to their arriving source copy, which takes their place in the queue. */
+  superseded: number
+  /** In the queue now; current occupancy, not cumulative. */
+  pending: number
+}
+
 const MAX_AWAITING_TIMING_HEADS = 8
 
 // ── MmtpContainerParser ─────────────────────────────────────────────
@@ -1129,6 +1331,9 @@ export class MmtpContainerParser {
   #reclaimedTimingSamples = 0
   #evictedTimingSamples = 0
   #rejectedMovieFragments = 0
+  #recoveredHeadsAwaitingTiming: Omit<MmtpRecoveredHeadTimingStats, 'pending'> = {
+    held: 0, expired: 0, discarded: 0, superseded: 0,
+  }
   #sequencers = new Map<string, { packetId: number; sequencer: FrameSequencer }>()
   #fecGate: FecReleaseGate | null = null
   #fecSequencer: FecReleaseSequencer | null = null
@@ -1330,11 +1535,12 @@ export class MmtpContainerParser {
   /**
    * Typed view of the ISO-BMFF timing-sample budget.
    *
-   * This is the acceptance signal for the budget ratchet: `pending` walking
-   * to `capacity` while `rejectedMovieFragments` climbs is the stream wedging,
-   * and it is observable here rather than only as media silently stopping.
-   * Per repo policy this is a producer-owned counter -- never infer budget
-   * state by parsing logs.
+   * Each stream admits timing against its own window of `capacity` slots
+   * (BLO-52085). A stream at capacity displaces its own oldest timing to
+   * admit the moof in hand, and `evicted` counts the slots so displaced:
+   * timing a stream declared and never delivered shows up there. `pending`
+   * sums every stream, so it can exceed `capacity`. Per repo policy this is
+   * a producer-owned counter -- never infer budget state by parsing logs.
    */
   get timingBudgetStats(): Readonly<MmtpTimingBudgetStats> {
     return {
@@ -1346,6 +1552,15 @@ export class MmtpContainerParser {
     }
   }
 
+  /** Recovered heads parked for FT=1 timing (BLO-53369). Survives dispose(). */
+  get recoveredHeadsAwaitingTiming(): Readonly<MmtpRecoveredHeadTimingStats> {
+    let pending = 0
+    for (const { awaitingTiming } of this.#timingStreams.values()) {
+      for (const head of awaitingTiming) if (head.options?.recovered) pending++
+    }
+    return { ...this.#recoveredHeadsAwaitingTiming, pending }
+  }
+
   get reorderStats(): Readonly<MmtpReorderStats> {
     let bufferedFrames = this.#fecSequencer?.buffered ?? 0
     for (const { sequencer } of this.#sequencers.values()) bufferedFrames += sequencer.buffered
@@ -1394,6 +1609,16 @@ export class MmtpContainerParser {
     return this.#fecSequencer?.rapAbove(packetId, catalogTrackName, ssId) ?? false
   }
 
+  /** See FecReleaseSequencer.unsource. */
+  unsourceFecRelease(packetId: number, catalogTrackName?: string): void {
+    this.#fecSequencer?.unsource(packetId, catalogTrackName)
+  }
+
+  /** See FecReleaseSequencer.holdsRebuilt. */
+  fecReleaseHoldsRebuilt(packetId: number, catalogTrackName?: string): boolean {
+    return this.#fecSequencer?.holdsRebuilt(packetId, catalogTrackName) ?? false
+  }
+
   /** Re-evaluate held gaps after FEC block state changed. */
   pokeFecRelease(packetId?: number, catalogTrackName?: string): void {
     if (!this.#fecSequencer) return
@@ -1541,7 +1766,7 @@ export class MmtpContainerParser {
     const now = Date.now()
     for (const { awaitingTiming } of this.#timingStreams.values()) {
       while (awaitingTiming.length > 0 && now - awaitingTiming[0]!.arrivedAt > timeoutMs) {
-        awaitingTiming.shift()
+        this.#leaveAwaitingTiming(awaitingTiming.shift()!, 'expired')
       }
     }
   }
@@ -1711,17 +1936,27 @@ export class MmtpContainerParser {
       if (mpu.fragmentationIndicator !== 0 || mpu.fragmentCounter !== 0)
         return this.#drop('fragment-unexpected-fragmentation')
       const resolver = this.#timingResolver(streamKey, info.packetId, false)
-      if (!resolver) return this.#drop('fragment-no-resolver')
+      if (!resolver?.initialized) return this.#drop('fragment-no-resolver')
       const pendingBefore = resolver.pendingSampleCount
       const evictedBefore = resolver.evictedSampleCount
-      const remaining = this.#maxPendingTimingSamples - this.#pendingTimingSamples
-      const admitted = resolver.addMovieFragment(mpu.mpuSequenceNumber, data, remaining)
+      // Each stream's window is the whole budget. A resolver can displace only
+      // its own timing, so a pool shared across streams let one stream's
+      // unconsumed slots refuse another stream's moofs with nothing to
+      // displace: BLO-52085 G7b, overlay-rebuilt video keyframes refusing audio.
+      const remaining = this.#maxPendingTimingSamples - resolver.pendingSampleCount
+      const admitted = resolver.addMovieFragment(
+        mpu.mpuSequenceNumber,
+        data,
+        remaining,
+        options?.recovered === true,
+      )
       // Sync on BOTH paths: the resolver can displace stale timing and still
-      // refuse the fragment in hand, and a global count that missed those
-      // freed slots would keep refusing on a budget that is no longer full.
+      // refuse the fragment in hand, and the total must count those freed slots.
       this.#pendingTimingSamples += resolver.pendingSampleCount - pendingBefore
       this.#evictedTimingSamples += resolver.evictedSampleCount - evictedBefore
       if (!admitted) {
+        // Never 'budget' with a window per stream (see
+        // `rejectedMovieFragments`); kept as a guard.
         if (resolver.lastMovieFragmentRejection === 'budget') {
           this.#rejectedMovieFragments++
         }
@@ -1739,7 +1974,11 @@ export class MmtpContainerParser {
     }
     if (fragmentType !== 2) return this.#drop('unknown-fragment-type')
 
-    const resolver = this.#timingResolver(streamKey, info.packetId, false)
+    // An FT=2 before the stream's first FT=0 (a join, a track reset) is taken
+    // like one whose FT=1 has not arrived: a head waits for its timing, a
+    // continuation parks in the reassembler, and a later or FEC-recovered
+    // FT=0/FT=1 can still time them.
+    const resolver = this.#timingResolver(streamKey, info.packetId, true)
     if (!resolver) return this.#drop('mfu-no-resolver')
     if (!Number.isSafeInteger(data.byteLength) || data.byteLength <= 0)
       return this.#drop('mfu-empty-payload')
@@ -1761,6 +2000,7 @@ export class MmtpContainerParser {
           mpuSequenceNumber: mpu.mpuSequenceNumber,
           movieFragmentSequenceNumber: mfuDuHeader.movieFragmentSequenceNumber,
           sampleNumber: mfuDuHeader.sampleNumber,
+          sequenceNumber: info.sequenceNumber,
           arrivedAt: Date.now(),
         })
         return this.#drop('mfu-sample-timing-missing')
@@ -1803,6 +2043,7 @@ export class MmtpContainerParser {
           resolver,
           options?.recovered === true,
           options?.fecSbn,
+          options?.fecSbnFirst,
         )
         if (deferred.record === undefined) this.#countDeferredOutcome(deferred.reason)
       }
@@ -1914,6 +2155,7 @@ export class MmtpContainerParser {
       resolver,
       options?.recovered === true,
       options?.fecSbn,
+      options?.fecSbnFirst,
     )
     if (outcome.record !== undefined) return outcome.record
     return this.#drop(outcome.reason)
@@ -1940,6 +2182,7 @@ export class MmtpContainerParser {
     resolver: IsoBmffTimingResolver,
     recovered: boolean,
     fecSbn: number | undefined,
+    fecSbnFirst: number | undefined,
   ): CombinedSampleOutcome {
     const timing = resolver.sampleTiming(
       combined.mpuSequenceNumber,
@@ -1961,6 +2204,7 @@ export class MmtpContainerParser {
     )
     if (!meta) return { reason: 'combined-meta-build-failed' }
     if (fecSbn !== undefined) meta.fecSbn = fecSbn
+    if (fecSbnFirst !== undefined) meta.fecSbnFirst = fecSbnFirst
     if (!resolver.consumeSample(
       combined.mpuSequenceNumber,
       combined.movieFragmentSequenceNumber,
@@ -2146,6 +2390,18 @@ export class MmtpContainerParser {
     this.#emitFrame(data, meta)
   }
 
+  /** Whether FT=1 metadata already names this sample, without claiming it. */
+  hasAuthoredTimingFor(
+    packetId: number,
+    mpuSequenceNumber: number,
+    movieFragmentSequenceNumber: number,
+    sampleNumber: number,
+    catalogTrackName?: string,
+  ): boolean {
+    return this.#timingResolver(this.#streamKey(packetId, catalogTrackName), packetId, false)
+      ?.sampleTiming(mpuSequenceNumber, movieFragmentSequenceNumber, sampleNumber) != null
+  }
+
   /**
    * Claim and return the authored timing for a recovered sample. Recovery does
    * not pass through the ordinary `feed()` completion path, so it must retire
@@ -2216,6 +2472,9 @@ export class MmtpContainerParser {
     for (const { sequencer } of this.#sequencers.values()) sequencer.discard()
     this.#sequencers.clear()
     this.#fecSequencer?.discard()
+    for (const { awaitingTiming } of this.#timingStreams.values()) {
+      for (const head of awaitingTiming) this.#leaveAwaitingTiming(head, 'discarded')
+    }
     this.#timingStreams.clear()
     this.#pendingTimingSamples = 0
     this.#reliableMoqStartupGate.clear()
@@ -2241,10 +2500,27 @@ export class MmtpContainerParser {
   }
 
   #awaitTiming(streamKey: string, head: AwaitingTimingHead): void {
-    const awaitingTiming = this.#timingStreams.get(streamKey)?.awaitingTiming
-    if (!awaitingTiming) return
+    const state = this.#timingStreams.get(streamKey)
+    if (!state) return
+    // The source copy of a held recovered head takes its place, so the frame
+    // is delivered with source provenance once FT=1 lands.
+    if (!head.options?.recovered) {
+      const kept = state.awaitingTiming.filter(queued =>
+        !queued.options?.recovered || queued.sequenceNumber !== head.sequenceNumber)
+      this.#recoveredHeadsAwaitingTiming.superseded += state.awaitingTiming.length - kept.length
+      state.awaitingTiming = kept
+    }
+    const awaitingTiming = state.awaitingTiming
     awaitingTiming.push(head)
-    if (awaitingTiming.length > MAX_AWAITING_TIMING_HEADS) awaitingTiming.shift()
+    if (head.options?.recovered) this.#recoveredHeadsAwaitingTiming.held++
+    if (awaitingTiming.length > MAX_AWAITING_TIMING_HEADS) {
+      this.#leaveAwaitingTiming(awaitingTiming.shift()!, 'expired')
+    }
+  }
+
+  /** Count a recovered head leaving the queue other than by replay or its source copy. */
+  #leaveAwaitingTiming(head: AwaitingTimingHead, outcome: 'expired' | 'discarded'): void {
+    if (head.options?.recovered) this.#recoveredHeadsAwaitingTiming[outcome]++
   }
 
   /**
@@ -2274,6 +2550,7 @@ export class MmtpContainerParser {
     const state = this.#timingStreams.get(streamKey)
     if (!state) return
     this.#timingStreams.delete(streamKey)
+    for (const head of state.awaitingTiming) this.#leaveAwaitingTiming(head, 'discarded')
     this.#pendingTimingSamples -= state.resolver.pendingSampleCount
     if (this.#pendingTimingSamples < 0) {
       throw new Error('[MmtpContainerParser] pending timing sample accounting underflow')