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

package/src/fec-manager.ts

@@ -22,6 +22,7 @@ import {
   isoBlockContains,
   isoBlocksBehindLowerBound,
   parseFecBlockProfile,
+  serial32Add,
   serial32Distance,
   serial32Precedes,
   ssbg1FitsSymbol,
@@ -169,6 +170,17 @@ export interface FecPacketStats {
 
 export type FecSymbolSource = 'multicast' | 'moq'
 
+/**
+ * What feedRebuiltSourceSymbol did with a rebuilt source: whether its block
+ * took it, and the block the synchronous decoder recovered with it, if any.
+ */
+export interface RebuiltSourceFeed {
+  readonly taken: boolean
+  readonly recovered: Uint8Array | null
+}
+
+const NOT_TAKEN: RebuiltSourceFeed = Object.freeze({ taken: false, recovered: null })
+
 /**
  * One iso-ssbg1-v1 first-arrival source symbol MmtpRouter holds until a repair
  * symbol states its block: the exact protected packet (no SS_ID, unpadded),
@@ -201,6 +213,25 @@ export interface UndelimitedIsoLoss {
   readonly previousBlockStart?: number
 }
 
+/**
+ * A pending hole the stream ran more than the locator's horizon past before
+ * its range repair ended (BLO-52085): no repair can state its blocks any
+ * more, and the release gate no longer waits for it.
+ */
+export type ExpiredIsoHole = Pick<UndelimitedIsoLoss, 'packetId' | 'catalogTrackName' | 'holeStart' | 'holeLength'>
+
+/**
+ * What a failed iso-ssbg1-v1 repair-less span was: the `length` SS_IDs from
+ * its start, between two stated blocks, of which `sources` arrived. No repair
+ * stated the blocks inside it, so the receiver cannot tell its complete
+ * blocks from the ones that lost a source: the span failed, not the block
+ * that starts it.
+ */
+export interface IsoSpanFailure {
+  readonly length: number
+  readonly sources: number
+}
+
 /**
  * How the multicast leg hands its symbols to this manager.
  *
@@ -510,10 +541,21 @@ export class FECManager {
   // 'pending' forever, which would park every later frame of its stream in
   // the in-order release gate. Each entry owns its handle; the callback
   // checks it still owns the key, so a settled or reset key is never touched.
-  #pendingWorkerCleanupBounds = new Map<string, { handle: ReturnType<typeof setTimeout> }>()
+  /**
+   * Per owed Worker cleanup: the bound on its acknowledgement, when its block
+   * was due, and when its cleanup was asked for (see `onCleanupComplete`).
+   */
+  #pendingWorkerCleanupBounds = new Map<
+    string,
+    { handle: ReturnType<typeof setTimeout>; dueAtMs: number; askedAtMs: number }
+  >()
   // Source symbol count per track-scoped block — marks complete when K symbols arrive.
   #blockSourceCounts = new Map<string, number>()
   #blockSourceEsis = new Map<string, Set<number>>()
+  // Source ESIs per block that another FEC instance rebuilt and fed in
+  // (feedRebuiltSourceSymbol). Kept apart from #blockSourceEsis: they are
+  // not network arrivals and never make a block clean.
+  #blockRebuiltEsis = new Map<string, Set<number>>()
   // Authored SSB_length per block (ISO/IEC 23008-1 §C.5.3), learned from the
   // first repair symbol. The FFmpeg moq_mmt publisher closes a block every D
   // media units, usually before it holds K symbols; under iso-ssbg1-v1
@@ -522,6 +564,9 @@ export class FECManager {
   // SSB_length source arrivals and recoverable from SSB_length received
   // symbols; waiting for K fails every one of them.
   #blockAuthoredLengths = new Map<string, number>()
+  // Keys whose authored length is a repair-less span's (#openIsoSpan), until
+  // a repair states the block there or the span resolves.
+  #isoSpanKeys = new Set<string>()
   #ssbLengthConflictCount = 0
   #blockRepairRsIds = new Map<string, Set<number>>()
   // RSB_length per block (C.5.3 Repair FEC Payload ID): how many repair
@@ -644,6 +689,10 @@ export class FECManager {
   // ── Keyframe-protected repair policy (block-policy.ts) ──
   // One classifier per physical stream, built from that stream's geometry.
   #classifiers = new Map<string, BlockClassifier>()
+  // A stream without catalog timing has no classifier, so the last RAP it
+  // released stands in for one: "an MPU boundary bounds its RAPs" holds until
+  // a second RAP is released inside one MPU (BLO-52085).
+  #noSpanRaps = new Map<string, { mpu: number; presentationTime: bigint; inside: boolean }>()
   // Geometry a stream-scoped configuration gave one stream (streamKey). ABR
   // rungs can share a packetId with a different framerate or GOP, so the
   // packet-level geometry is only the geometry of a packet whose streams
@@ -725,13 +774,17 @@ export class FECManager {
   onBlockComplete:
     | ((sbn: number, packetId: number, catalogTrackName?: string) => void)
     | null = null
-  /** A block reached its fail bound. `blockClass` is its class at failure. */
+  /**
+   * A block reached its fail bound. `blockClass` is its class at failure.
+   * `span` is set when what failed is a repair-less span starting at `sbn`.
+   */
   onBlockFailed:
     | ((
         sbn: number,
         packetId: number,
         catalogTrackName: string | undefined,
         blockClass: BlockClass,
+        span?: IsoSpanFailure,
       ) => void)
     | null = null
   /**
@@ -815,6 +868,8 @@ export class FECManager {
    * for it, which it must be.
    */
   #onUndelimitedLoss: ((loss: UndelimitedIsoLoss) => void) | null = null
+  /** Set with the loss handler: true takes an expired hole to close (`closeIsoHoles`). */
+  #onIsoHoleExpired: ((hole: ExpiredIsoHole) => boolean) | null = null
   /** A block every symbol of which vanished was created by SBN evidence. */
   onBlockVanished:
     | ((sbn: number, packetId: number, catalogTrackName: string | undefined) => void)
@@ -1469,7 +1524,12 @@ export class FECManager {
       timer.handle = null
       this.#requestRepair(sbn, packetId, catalogTrackName)
     }
-    timer.handle = setTimeout(onFire, Math.max(0, deadlineMs - performance.now()))
+    timer.handle = setTimeout(
+      onFire,
+      this.#receiptAtMs === undefined
+        ? Math.max(0, deadlineMs - performance.now())
+        : this.#receiptTimerDelayMs(deadlineMs, 0),
+    )
     this.#repairDeadlines.set(key, timer)
   }
 
@@ -1663,6 +1723,12 @@ export class FECManager {
    * Vanished blocks are not enumerated here: their starts are unknown until a
    * repair states them. The SS_IDs between two stated blocks become one
    * repair-less span when the later block's repair arrives (placeIsoRepair).
+   *
+   * A `held` source arrived before its block was known and is fed only now
+   * that a repair, a span or a closed hole placed it: how far its block start
+   * then lies behind the frontier measures how long the receiver held it, not
+   * where the stream was, so only its SS_ID and packet_sequence_number judge
+   * it (BLO-52085).
    */
   #noteSbnSeen(
     sbn: number,
@@ -1671,6 +1737,7 @@ export class FECManager {
     symbol: 'source' | 'repair',
     packetSequenceNumber?: number,
     ssId = sbn,
+    held = false,
   ): void {
     const streamKey = this.#streamKey(packetId, catalogTrackName)
     // Arrival at FEC, not receipt (withReceiptTime): this bounds how far SS_ID
@@ -1706,6 +1773,7 @@ export class FECManager {
       // The classifier compares authored order with SBN order only within
       // one continuous SBN sequence.
       this.#classifiers.get(streamKey)?.noteSourceDiscontinuity()
+      this.#noSpanRaps.delete(streamKey)
       this.#highestSbn.set(streamKey, { sbn, atMs: now })
       this.#sourceFrontiers.set(streamKey, { sbn, atMs: now })
       if (psn === undefined) this.#sourceAnchors.delete(streamKey)
@@ -1726,7 +1794,7 @@ export class FECManager {
     }
     if (!this.#blockPrecedes(previous.sbn, sbn)) {
       if (symbol === 'source' && window !== null && this.#blockPrecedes(sbn, previous.sbn) && (
-        this.#blocksBehind(sbn, previous.sbn, packetId) > this.#isoRetentionBlocks(packetId) ||
+        (!held && this.#blocksBehind(sbn, previous.sbn, packetId) > this.#isoRetentionBlocks(packetId)) ||
         (psn !== undefined && anchor !== undefined && serial32Precedes(ssId, anchor.ssId) &&
           psn !== anchor.psn && !sentInOrder({ ssId, psn }, anchor))
       )) {
@@ -2080,21 +2148,28 @@ export class FECManager {
       this.#blockWaitDeadlinesMs.delete(key)
       this.#repairHoldUntilMs.delete(key)
       this.#traceLifecycle('timeout-queued', sbn, packetId, catalogTrackName)
-      this.#finalizeExpiredBlock(sbn, packetId, catalogTrackName)
+      this.#finalizeExpiredBlock(sbn, packetId, catalogTrackName, currentDeadlineMs ?? firedAtMs)
     }
-    timer.handle = setTimeout(onFire, Math.max(1, Math.ceil(deadlineMs - nowMs)))
+    timer.handle = setTimeout(
+      onFire,
+      this.#receiptAtMs === undefined
+        ? Math.max(1, Math.ceil(deadlineMs - nowMs))
+        : this.#receiptTimerDelayMs(deadlineMs, 1),
+    )
     this.#activeBlocks.set(key, timer)
     this.#indexBlockKey(key, sbn, packetId)
   }
 
   /**
    * Hand a block whose delivery is over to its decoder for finalization: the
-   * datagram deadline fired, or the ordered relay moved past it.
+   * datagram deadline fired, or the ordered relay moved past it. `dueAtMs`
+   * is when it was due: its deadline, or now.
    */
   #finalizeExpiredBlock(
     sbn: number,
     packetId: number,
     catalogTrackName: string | undefined,
+    dueAtMs = performance.now(),
   ): void {
     const key = this.#blockKey(sbn, packetId, catalogTrackName)
     // A vanished block that never received a symbol holds no decoder state
@@ -2118,7 +2193,7 @@ export class FECManager {
     if (workerClient) {
       this.#pendingWorkerCleanups.add(key)
       this.#pendingWorkerCleanupClients.set(key, workerClient)
-      this.#boundOwedCleanup(key, packetId, workerClient)
+      this.#boundOwedCleanup(key, packetId, workerClient, dueAtMs)
       workerClient.cleanup(sbn)
     } else {
       const decoder = this.#decoderForPacket(packetId, catalogTrackName)?.client
@@ -2289,6 +2364,9 @@ export class FECManager {
       // sibling's change, but the first stream-scoped geometry on a packet
       // does change the siblings that have none (stream-geometry-absent).
       this.#bumpEpoch(packetId)
+      for (const key of [...this.#noSpanRaps.keys()]) {
+        if (this.#belongsToPacket(key, packetId)) this.#noSpanRaps.delete(key)
+      }
       for (const [key, classifier] of [...this.#classifiers]) {
         if (!this.#belongsToPacket(key, packetId)) continue
         const stream = this.#parseStreamKey(key)
@@ -2532,7 +2610,9 @@ export class FECManager {
     }
     resetMap(this.#blockSourceCounts)
     resetMap(this.#blockSourceEsis)
+    resetMap(this.#blockRebuiltEsis)
     resetMap(this.#blockAuthoredLengths)
+    resetSet(this.#isoSpanKeys)
     resetMap(this.#blockRepairRsIds)
     resetMap(this.#blockRsbLengths)
     resetMap(this.#heldLayerStates)
@@ -2565,6 +2645,7 @@ export class FECManager {
     resetMap(this.#isoLocators)
     resetMap(this.#sourceAnchors)
     this.#classifiers.delete(this.#streamKey(packetId, catalogTrackName))
+    this.#noSpanRaps.delete(this.#streamKey(packetId, catalogTrackName))
     this.#bumpEpoch(packetId)
     for (const [sbn, keys] of this.#blockKeysBySbn) {
       for (const key of keys.keys()) {
@@ -2663,7 +2744,9 @@ export class FECManager {
     dropMap(this.#pendingWorkerCleanupClients)
     dropMap(this.#blockSourceCounts)
     dropMap(this.#blockSourceEsis)
+    dropMap(this.#blockRebuiltEsis)
     dropMap(this.#blockAuthoredLengths)
+    dropSet(this.#isoSpanKeys)
     dropMap(this.#blockRepairRsIds)
     dropMap(this.#blockRsbLengths)
     dropMap(this.#blockPathCounts)
@@ -2679,6 +2762,7 @@ export class FECManager {
     dropMap(this.#isoLocators)
     dropMap(this.#sourceAnchors)
     dropMap(this.#classifiers)
+    dropMap(this.#noSpanRaps)
     dropMap(this.#streamGeometries)
     dropSet(this.#pendingWorkerCleanups)
     dropSet(this.#completedBlocks)
@@ -2881,6 +2965,10 @@ export class FECManager {
       }
     }
 
+    if (isSourceSymbol && source === 'multicast') {
+      this.#noteMulticastSource(this.#isoLocatorFor(packetId, catalogTrackName), (sbn + esi) >>> 0, packetId, catalogTrackName)
+    }
+
     return true
   }
 
@@ -3090,8 +3178,9 @@ export class FECManager {
     return true
   }
   /**
-   * Drop a block's repair hold: its FETCH ended without delivering. The block
-   * falls back to its multicast wait, which may already have passed.
+   * Drop a block's repair hold: its FETCH ended without delivering, or brought
+   * back only a repair that cannot complete it. The block falls back to its
+   * multicast wait, which may already have passed.
    */
   releaseRepairHold(sbn: number, packetId: number, catalogTrackName?: string): void {
     const key = this.#blockKey(sbn, packetId, catalogTrackName)
@@ -3253,6 +3342,8 @@ export class FECManager {
     const locator = this.#growingIsoLocatorFor(packetId, catalogTrackName)
     const evictedBefore = locator.heldEvicted
     const held = locator.hold(ssId, source)
+    this.#settleExpiredIsoHoles(locator, packetId, catalogTrackName)
+    if (held && source.source === 'multicast') this.#noteMulticastSource(locator, ssId, packetId, catalogTrackName)
     const evicted = locator.heldEvicted - evictedBefore
     if (evicted > 0) {
       const before = this.#isoHeldEvictedCount
@@ -3280,17 +3371,26 @@ export class FECManager {
     ssStart: number,
     ssbLength: number,
   ): IsoRepairPlacement<IsoHeldSource> {
-    const placement = this.#growingIsoLocatorFor(packetId, catalogTrackName).placeRepair(ssStart, ssbLength)
+    const locator = this.#growingIsoLocatorFor(packetId, catalogTrackName)
+    const placement = locator.placeRepair(ssStart, ssbLength)
+    this.#settleExpiredIsoHoles(locator, packetId, catalogTrackName)
     if (placement.status !== 'placed') {
       this.#isoRepairRefusedCount++
       if (this.#isoRepairRefusedCount <= 5 || this.#isoRepairRefusedCount % 100 === 0) {
         console.warn(`[FECManager] packetId=${packetId} iso-ssbg1-v1 repair refused (${placement.status}): ${placement.reason}`)
       }
+      // The repair FETCH of a span's first group brought back a shorter block:
+      // the span holds more than one, so that group cannot complete it, and
+      // holding the span (and every frame behind it) for the FETCH buys
+      // nothing. It falls back to its multicast wait.
+      if (placement.ofSpan !== undefined) this.releaseRepairHold(placement.ofSpan.start, packetId, catalogTrackName)
       return placement
     }
+    // A repair states the block at its SS_Start: a span the locator kept
+    // there is now that one block (IsoBlockLocator.placeRepair).
+    this.#isoSpanKeys.delete(this.#blockKey(placement.block.start, packetId, catalogTrackName))
     if (placement.span !== undefined) this.#openIsoSpan(placement.span, packetId, catalogTrackName)
     if (placement.hole !== undefined) {
-      const locator = this.#isoLocatorFor(packetId, catalogTrackName)
       const hole = placement.hole.block
       const previous = locator.blockEndingAt(hole.start)
       const loss: UndelimitedIsoLoss = {
@@ -3312,18 +3412,38 @@ export class FECManager {
    * `handler`, instead of a repair-less span; null restores spans. Set by the
    * range repair scheduler; applies to every stream from its next gap. The
    * handler and the deferral are one setting, so no hole is ever created with
-   * nobody to close it.
+   * nobody to close it. `onExpired` is told of each pending hole the stream
+   * runs past the locator's horizon (BLO-52085): returning true, it closes
+   * the hole (`closeIsoHoles`), so the span it leaves still fails and is
+   * reported; otherwise the hole is discarded with its sources.
    */
-  setUndelimitedLossHandler(handler: ((loss: UndelimitedIsoLoss) => void) | null): void {
+  setUndelimitedLossHandler(
+    handler: ((loss: UndelimitedIsoLoss) => void) | null,
+    onExpired: ((hole: ExpiredIsoHole) => boolean) | null = null,
+  ): void {
     this.#onUndelimitedLoss = handler
+    this.#onIsoHoleExpired = handler === null ? null : onExpired
     this.#deferIsoGaps = handler !== null
     for (const locator of this.#isoLocators.values()) locator.deferIncompleteGaps = this.#deferIsoGaps
   }
 
+  /** Hand each hole the locator's horizon passed to its owner, or discard it (setUndelimitedLossHandler). */
+  #settleExpiredIsoHoles(
+    locator: IsoBlockLocator<IsoHeldSource>,
+    packetId: number,
+    catalogTrackName: string | undefined,
+  ): void {
+    for (const hole of locator.takeExpiredHoles()) {
+      const expired: ExpiredIsoHole = { packetId, catalogTrackName, holeStart: hole.start, holeLength: hole.length }
+      if (this.#onIsoHoleExpired?.(expired) !== true) locator.closeHolesWithin(hole.start, hole.length)
+    }
+  }
+
   /**
-   * The range repair for a hole ended: every hole still pending inside
-   * `[start, start + length)` becomes a repair-less span. Returns those spans
-   * with the held sources they placed, for the caller to feed (MmtpRouter).
+   * The range repair for a hole ended: every hole inside `[start, start +
+   * length)`, pending or expired, becomes a repair-less span. Returns those
+   * spans with the held sources they placed, for the caller to feed
+   * (MmtpRouter).
    */
   closeIsoHoles(
     packetId: number,
@@ -3352,7 +3472,10 @@ export class FECManager {
     catalogTrackName: string | undefined,
   ): void {
     const key = this.#blockKey(span.block.start, packetId, catalogTrackName)
-    if (!this.#blockAuthoredLengths.has(key)) this.#blockAuthoredLengths.set(key, span.block.length)
+    if (!this.#blockAuthoredLengths.has(key)) {
+      this.#blockAuthoredLengths.set(key, span.block.length)
+      this.#isoSpanKeys.add(key)
+    }
     if (span.placed.length === 0) this.#materializeBlock(span.block.start, packetId, catalogTrackName, true)
   }
 
@@ -3470,11 +3593,14 @@ export class FECManager {
   /**
    * Whether an MPU boundary still bounds this stream's RAPs (see
    * `BlockClassifier.mpuBoundsRaps`). Gap decisions drop MPU evidence once
-   * it does not. A stream with no classifier yet has shown nothing against it.
+   * it does not. A stream with no classifier yet has shown nothing against it,
+   * and neither has a stream without catalog timing until it releases two
+   * RAPs inside one MPU.
    */
   mpuBoundsRapsFor(packetId: number, catalogTrackName?: string): boolean {
-    if (!this.#hasCatalogTimingForPacket(packetId)) return false
-    return this.#classifiers.get(this.#streamKey(packetId, catalogTrackName))?.mpuBoundsRaps ?? true
+    const streamKey = this.#streamKey(packetId, catalogTrackName)
+    if (!this.#hasCatalogTimingForPacket(packetId)) return this.#noSpanRaps.get(streamKey)?.inside !== true
+    return this.#classifiers.get(streamKey)?.mpuBoundsRaps ?? true
   }
 
   /** A block's class now, or frozen at its resolution. */
@@ -3510,7 +3636,15 @@ export class FECManager {
     presentationTime: bigint,
     mediaTimescale: number,
   ): void {
-    if (!this.#trackConfigs.has(packetId) || !this.#hasCatalogTimingForPacket(packetId)) return
+    if (!this.#trackConfigs.has(packetId)) return
+    if (!this.#hasCatalogTimingForPacket(packetId)) {
+      const streamKey = this.#streamKey(packetId, catalogTrackName)
+      const last = this.#noSpanRaps.get(streamKey)
+      const inside = last?.inside === true ||
+        (last?.mpu === mpu && last.presentationTime !== presentationTime)
+      this.#noSpanRaps.set(streamKey, { mpu, presentationTime, inside })
+      return
+    }
     this.#applyClassifierChanges(
       packetId,
       catalogTrackName,
@@ -3820,13 +3954,27 @@ export class FECManager {
 
     client.onCleanupComplete((sbn: number) => {
       if (this.#releasedWorkerClients.has(client)) return
-      const cleanupKeys = [...this.#pendingWorkerCleanups].filter((key) => {
+      const owed = [...this.#pendingWorkerCleanups].filter((key) => this.#pendingWorkerCleanupClients.get(key) === client)
+      const cleanupKeys = owed.filter((key) => {
         const block = this.#parseBlockKey(key)
-        return block.packetId === packetId &&
-          block.sbn === sbn &&
-          this.#pendingWorkerCleanupClients.get(key) === client
+        return block.packetId === packetId && block.sbn === sbn
       })
-      for (const key of cleanupKeys) this.#settleOwedCleanup(key, 'cleanup-ack')
+      // A cleanup is a queue-drain barrier: the Worker took every symbol fed
+      // before it was asked for first, so every block already due by then
+      // is settled by this acknowledgement too, not one barrier later. The
+      // client sends one barrier at a time, and the blocks a repair walk
+      // stated in one span are due together (BLO-52085). That holds only
+      // while no block is fed a symbol after its dueAtMs, which is its
+      // receipt-scoped deadline, not when feeding stopped: a symbol fed
+      // between that deadline and the block's timer, after another block's
+      // barrier was asked for, would find the block settled (failed) one
+      // barrier early. Walks end before D-28 (walkDeadlineAt), so that window
+      // is the timer's lateness alone; whatever feeds a block past its dueAtMs
+      // must leave it to its own barrier.
+      const askedAtMs = Math.max(...cleanupKeys.map((key) => this.#pendingWorkerCleanupBounds.get(key)?.askedAtMs ?? -Infinity))
+      const due = owed.filter((key) =>
+        !cleanupKeys.includes(key) && (this.#pendingWorkerCleanupBounds.get(key)?.dueAtMs ?? Infinity) <= askedAtMs)
+      for (const key of [...cleanupKeys, ...due]) this.#settleOwedCleanup(key, 'cleanup-ack')
     })
 
     client.onError((msg: string, code?: FecWorkerErrorCode) => {
@@ -3908,9 +4056,11 @@ export class FECManager {
    * fail deadline already passed, so failing it is the decision that deadline
    * made. A late ack then finds nothing owed and is a no-op.
    */
-  #boundOwedCleanup(key: string, packetId: number, client: FecWorkerClient): void {
+  #boundOwedCleanup(key: string, packetId: number, client: FecWorkerClient, dueAtMs: number): void {
     this.#clearOwedCleanupBound(key)
     const bound = {
+      dueAtMs,
+      askedAtMs: performance.now(),
       handle: setTimeout(() => {
         if (this.#pendingWorkerCleanupBounds.get(key) !== bound) return
         this.#pendingWorkerCleanupBounds.delete(key)
@@ -4041,7 +4191,22 @@ export class FECManager {
       this.#isoSourceOversizeCount++
       return null
     }
-    const sbn = located.block.start
+    return this.#feedDecoderSource(packetId, ssId, symbolData, catalogTrackName, located.block.start)
+  }
+
+  /**
+   * Hand one placed source symbol to the stream's decoder: its Worker, which
+   * answers through onFrame (null here), or its synchronous decoder, whose
+   * recovered block is returned. `sbn` is the SS_Start of the block a repair
+   * stated for `ssId`.
+   */
+  #feedDecoderSource(
+    packetId: number,
+    ssId: number,
+    symbolData: Uint8Array,
+    catalogTrackName: string | undefined,
+    sbn: number,
+  ): Uint8Array | null {
     const blockKey = this.#blockKey(sbn, packetId, catalogTrackName)
     const syncBlockOwner = this.#syncDecoderBlockOwners.get(blockKey)
 
@@ -4086,6 +4251,97 @@ export class FECManager {
     return recovered
   }
 
+  /**
+   * Feed a source symbol of this stream that another FEC instance over the
+   * same packets rebuilt: a keyframe overlay recovery whose base SS_ID the
+   * caller determined (draft-ramadan-moq-mmt-02 7.1, 7.4.4; joint decoding,
+   * BLO-52085). It joins its block's decoder as a received source would, so
+   * it reduces the erasures the block still has to solve, but it is not a
+   * network arrival: no transport accounting, no classification evidence,
+   * no deadline refresh, and it never makes a block clean.
+   *
+   * Only a block a repair stated takes one (a repair-less span has no
+   * decoder block). A block that is terminal, or already holds that source,
+   * does not. The symbol is the exact protected packet, unpadded, as
+   * feedSourceSymbol takes it.
+   *
+   * `recovered` is the block the synchronous decoder completed with it; the
+   * caller routes it and completes the block, as for any recovery. When
+   * every source of the block is then present, received or rebuilt, and no
+   * decoder returned it (a Worker answers asynchronously, and reports such a
+   * block as clean on its own side), the block is completed here as
+   * recovered, with nothing left to route.
+   */
+  feedRebuiltSourceSymbol(
+    packetId: number,
+    ssId: number,
+    symbolData: Uint8Array,
+    catalogTrackName?: string,
+  ): RebuiltSourceFeed {
+    if (!this.#hasBlockProfile(packetId)) return NOT_TAKEN
+    const located = this.#isoLocatorFor(packetId, catalogTrackName).locate(ssId)
+    if (located === null || located.block.span) return NOT_TAKEN
+    if (!ssbg1FitsSymbol(symbolData.byteLength, this.#trackConfig(packetId).symbolSize)) return NOT_TAKEN
+    const sbn = located.block.start
+    const key = this.#blockKey(sbn, packetId, catalogTrackName)
+    if (this.#completedBlocks.has(key) || this.#blockSourceEsis.get(key)?.has(located.esi)) return NOT_TAKEN
+    let rebuilt = this.#blockRebuiltEsis.get(key)
+    if (rebuilt?.has(located.esi)) return NOT_TAKEN
+    if (rebuilt === undefined) {
+      rebuilt = new Set()
+      this.#blockRebuiltEsis.set(key, rebuilt)
+    }
+    const config = this.#trackConfigs.get(packetId)
+    const wasShort = config !== undefined &&
+      this.#lateSourceWaitMs(key, sbn, packetId, catalogTrackName, config) !== undefined
+    rebuilt.add(located.esi)
+    const recovered = this.#feedDecoderSource(packetId, ssId, symbolData, catalogTrackName, sbn)
+    if (recovered === null && !this.#completeWhenSourcesPresent(key, sbn, located.block.length, packetId, catalogTrackName)) {
+      // The late-source cut assumed only a late source could complete this
+      // block; with this source its group can, so it gets a full multicast
+      // wait again, counted from now.
+      // ponytail: from now, not from its sources, so it can close up to one
+      // multicast wait after its uncut deadline; at most once per block, since
+      // a rebuilt source only adds to what the block holds and the cut cannot
+      // apply to it again. Keep the uncut deadline and re-arm to it if a lab
+      // run shows that wait.
+      if (wasShort && this.#activeBlocks.has(key) &&
+        this.#lateSourceWaitMs(key, sbn, packetId, catalogTrackName, config!) === undefined) {
+        this.#armBlockTimeout(sbn, packetId, catalogTrackName, this.#multicastWaitMs(config!))
+      }
+    }
+    return { taken: true, recovered }
+  }
+
+  /**
+   * A block that holds every one of its `length` sources, received or
+   * rebuilt by another instance, with at least one rebuilt, is recovered:
+   * every packet of it was delivered, by its own arrival or by the instance
+   * that rebuilt it, so nothing is routed. Returns whether it completed it.
+   */
+  #completeWhenSourcesPresent(
+    key: string,
+    sbn: number,
+    length: number,
+    packetId: number,
+    catalogTrackName: string | undefined,
+  ): boolean {
+    const rebuilt = this.#blockRebuiltEsis.get(key)
+    if (rebuilt === undefined || this.#completedBlocks.has(key)) return false
+    let present = rebuilt.size
+    for (const esi of this.#blockSourceEsis.get(key) ?? []) if (!rebuilt.has(esi)) present++
+    if (present < length) return false
+    this.#traceLifecycle('recovered', sbn, packetId, catalogTrackName)
+    this.countRecovery(packetId, sbn, catalogTrackName)
+    this.cancelBlockTimeout(sbn, packetId, catalogTrackName)
+    if (catalogTrackName === undefined) {
+      this.onBlockComplete?.(sbn, packetId)
+    } else {
+      this.onBlockComplete?.(sbn, packetId, catalogTrackName)
+    }
+    return true
+  }
+
   /**
    * fec-01 4.5: a reed-solomon repair packet whose SSB_length + RSB_length
    * exceeds 255, or whose RS_ID is not below RSB_length, is discarded with the
@@ -4343,9 +4599,100 @@ export class FECManager {
       this.#completeCleanBlock(blockKey, sbn, packetId, catalogTrackName)
       return null
     }
+    // Its K' is known now: a block this repair shows short of it waits less.
+    if (recovered === null) this.#shortenUnrecoverableWait(blockKey, sbn, packetId, catalogTrackName)
     return recovered
   }
 
+  /**
+   * A first-arrival multicast source, held or placed. A datagram flow keeps
+   * its sources in send order, so one that moves the stream's newest source
+   * position past a block leaves the sources that block still misses
+   * reordered behind it at best: it shortens the wait of every block it
+   * passed that only a late source can complete. MoQ is left out: its streams
+   * can overtake one another, so a MoQ source shows nothing about the sources
+   * sent before it.
+   */
+  #noteMulticastSource(
+    locator: IsoBlockLocator<IsoHeldSource>,
+    ssId: number,
+    packetId: number,
+    catalogTrackName: string | undefined,
+  ): void {
+    const previous = locator.newestSource
+    if (!locator.noteSource(ssId) || previous === undefined) return
+    // The blocks whose last SS_ID lies in [previous, ssId): this source
+    // passed them and the previous newest one had not.
+    for (const block of locator.blocksBetween((previous - 1) >>> 0, ssId)) {
+      if (block.span || !serial32Precedes(serial32Add(block.start, block.length - 1), ssId)) continue
+      this.#shortenUnrecoverableWait(
+        this.#blockKey(block.start, packetId, catalogTrackName),
+        block.start,
+        packetId,
+        catalogTrackName,
+      )
+    }
+  }
+
+  /**
+   * The wait of a block that only a late source can complete (BLO-52085): a
+   * repair stated it, its received sources plus every symbol its repair group
+   * carries (RSB_length) are short of K' (the repair scheduler's
+   * group-cannot-complete), and a later source of the stream has arrived, so
+   * a source it misses is lost or reordered behind that one. The span, which
+   * covers repair symbols paced after its sources, buys it nothing: it waits
+   * the late-symbol allowance alone, the multicast wait less the span (the
+   * catalog tolerance or the measured delivery gap). Undefined for any other
+   * block.
+   */
+  #lateSourceWaitMs(
+    key: string,
+    sbn: number,
+    packetId: number,
+    catalogTrackName: string | undefined,
+    config: ResolvedFECTrackConfig,
+  ): number | undefined {
+    const authoredLength = this.#blockAuthoredLengths.get(key)
+    const rsbLength = this.#blockRsbLengths.get(key)
+    if (authoredLength === undefined || rsbLength === undefined) return undefined
+    // A source another instance rebuilt (feedRebuiltSourceSymbol) is one the
+    // decoder holds: the group need only cover what neither delivered.
+    let present = this.#blockSourceCounts.get(key) ?? 0
+    const received = this.#blockSourceEsis.get(key)
+    for (const esi of this.#blockRebuiltEsis.get(key) ?? []) if (!received?.has(esi)) present++
+    if (present + rsbLength >= authoredLength) return undefined
+    const newestSource = this.#isoLocators.get(this.#streamKey(packetId, catalogTrackName))?.newestSource
+    if (newestSource === undefined || !serial32Precedes(serial32Add(sbn, authoredLength - 1), newestSource)) {
+      return undefined
+    }
+    return this.#multicastWaitMs(config) - config.interleaveDepthMs
+  }
+
+  /**
+   * Bring an open block's wait in to its late-source wait, when it has one.
+   * Never later than it is armed: only a source can complete such a block,
+   * so a repair of its group (paced across the span) must not keep it open.
+   */
+  #shortenUnrecoverableWait(
+    key: string,
+    sbn: number,
+    packetId: number,
+    catalogTrackName: string | undefined,
+  ): void {
+    if (!this.#activeBlocks.has(key)) return
+    const config = this.#trackConfigs.get(packetId)
+    if (config === undefined) return
+    const waitMs = this.#lateSourceWaitMs(key, sbn, packetId, catalogTrackName, config)
+    if (waitMs === undefined) return
+    const armedAtMs = this.#blockWaitDeadlinesMs.get(key)
+    this.#armBlockTimeout(
+      sbn,
+      packetId,
+      catalogTrackName,
+      armedAtMs === undefined ? waitMs : Math.min(waitMs, armedAtMs - this.#receiptNow()),
+    )
+  }
+
   /**
    * Record a block's authored SSB_length from a repair symbol. Returns false,
    * leaving the block unchanged, when the symbol contradicts the block: a
@@ -4485,7 +4832,8 @@ export class FECManager {
    * the inactivity deadline on each symbol, records the symbol's in-band
    * classification evidence, and marks the block clean when all of its
    * authored source symbols arrived: the SSB_length a repair symbol declared,
-   * otherwise K.
+   * otherwise K. `held` marks a source held unplaced since it arrived and
+   * placed only now (see #noteSbnSeen).
    *
    * Throws for a packetId that was never configured, so a classified block
    * never reads the manager-global K or timeout.
@@ -4496,6 +4844,7 @@ export class FECManager {
     catalogTrackName: string | undefined,
     esi: number,
     evidence: SourceSymbolEvidence,
+    held = false,
   ): void {
     const trackConfig = this.#trackConfigs.get(packetId)
     if (trackConfig === undefined) {
@@ -4517,6 +4866,7 @@ export class FECManager {
       'source',
       evidence.packetSequenceNumber,
       Number.isInteger(esi) ? (sbn + esi) >>> 0 : sbn,
+      held,
     )
 
     // A source ESI at or past the block's authored SSB_length contradicts it;
@@ -4561,6 +4911,20 @@ export class FECManager {
       this.#completeCleanBlock(key, sbn, packetId, catalogTrackName)
       return
     }
+    // A late arrival can be the last source a block lacked besides those
+    // another instance rebuilt (feedRebuiltSourceSymbol).
+    if (
+      this.#blockRebuiltEsis.has(key) &&
+      this.#completeWhenSourcesPresent(
+        key,
+        sbn,
+        this.#isoLocatorFor(packetId, catalogTrackName).blockAt(sbn)?.length ?? authoredLength,
+        packetId,
+        catalogTrackName,
+      )
+    ) {
+      return
+    }
 
     this.noteBlockActivity(sbn, packetId, catalogTrackName, true)
 
@@ -4580,7 +4944,9 @@ export class FECManager {
     this.cancelBlockTimeout(sbn, packetId, catalogTrackName)
     this.#blockSourceCounts.delete(key)
     this.#blockSourceEsis.delete(key)
+    this.#blockRebuiltEsis.delete(key)
     this.#blockAuthoredLengths.delete(key)
+    this.#isoSpanKeys.delete(key)
     this.#blockRepairRsIds.delete(key)
     this.#blockRsbLengths.delete(key)
     // BLO-3323 L15: track which SBNs reached K source-symbol arrivals so the
@@ -4622,6 +4988,20 @@ export class FECManager {
     return this.#receiptAtMs ?? performance.now()
   }
 
+  /**
+   * The whole-ms delay of a timer for `deadlineMs` armed inside a receipt
+   * scope: counted from the receipt time, as the timer of a symbol fed when
+   * it was received was, less the whole ms since. So it fires on the tick
+   * that timer would have, never later than a delay counted from now, and
+   * its handler still re-arms a timer that fires before its deadline.
+   * Counted from now, a deadline set from the receipt time is rounded up
+   * from another fraction of a ms (BLO-52085).
+   */
+  #receiptTimerDelayMs(deadlineMs: number, minMs: number): number {
+    const receivedAtMs = this.#receiptAtMs!
+    return Math.max(minMs, Math.ceil(deadlineMs - receivedAtMs) - Math.ceil(performance.now() - receivedAtMs))
+  }
+
   /**
    * A held packet admitted late arms from its (earlier) receipt time; that
    * never pulls in a deadline later activity already armed. Outside a
@@ -4693,7 +5073,18 @@ export class FECManager {
       )
     }
 
-    this.#armBlockTimeout(sbn, packetId, catalogTrackName, timeoutMs)
+    // A block only a late source can complete waits the late-symbol
+    // allowance from its own sources' activity; nothing else moves it later.
+    if (!sourceProgress && this.#lateSourceWaitMs(key, sbn, packetId, catalogTrackName, trackConfig) !== undefined) {
+      this.#shortenUnrecoverableWait(key, sbn, packetId, catalogTrackName)
+      return
+    }
+    this.#armBlockTimeout(
+      sbn,
+      packetId,
+      catalogTrackName,
+      this.#lateSourceWaitMs(key, sbn, packetId, catalogTrackName, trackConfig) ?? timeoutMs,
+    )
   }
 
   #failBlock(
@@ -4702,6 +5093,9 @@ export class FECManager {
     catalogTrackName?: string,
   ): void {
     const key = this.#blockKey(sbn, packetId, catalogTrackName)
+    const span: IsoSpanFailure | undefined = this.#isoSpanKeys.delete(key)
+      ? { length: this.#blockAuthoredLengths.get(key) ?? 0, sources: this.#blockSourceCounts.get(key) ?? 0 }
+      : undefined
     this.#traceLifecycle('failed', sbn, packetId, catalogTrackName)
     this.#clearRepairDeadline(key)
     this.#clearBlockTimer(key)
@@ -4711,6 +5105,7 @@ export class FECManager {
     }
     this.#blockSourceCounts.delete(key)
     this.#blockSourceEsis.delete(key)
+    this.#blockRebuiltEsis.delete(key)
     this.#blockAuthoredLengths.delete(key)
     this.#blockRepairRsIds.delete(key)
     this.#blockRsbLengths.delete(key)
@@ -4720,7 +5115,8 @@ export class FECManager {
     this.#markPathBlockComplete(sbn, packetId, catalogTrackName)
     this.#fecStats.blocksFailed++
     this.#statsForPacket(packetId).blocksFailed++
-    this.onBlockFailed?.(sbn, packetId, catalogTrackName, blockClass)
+    if (span === undefined) this.onBlockFailed?.(sbn, packetId, catalogTrackName, blockClass)
+    else this.onBlockFailed?.(sbn, packetId, catalogTrackName, blockClass, span)
     this.onBlockResolved?.(sbn, packetId, catalogTrackName)
   }
 
@@ -4750,7 +5146,9 @@ export class FECManager {
     this.#retireBlockClass(key, block.sbn, block.packetId, block.catalogTrackName)
     this.#blockSourceCounts.delete(key)
     this.#blockSourceEsis.delete(key)
+    this.#blockRebuiltEsis.delete(key)
     this.#blockAuthoredLengths.delete(key)
+    this.#isoSpanKeys.delete(key)
     this.#blockRepairRsIds.delete(key)
     this.#blockRsbLengths.delete(key)
     this.#clearBlockTimer(key)
@@ -4858,7 +5256,9 @@ export class FECManager {
     this.#blockKeysBySbn.clear()
     this.#blockSourceCounts.clear()
     this.#blockSourceEsis.clear()
+    this.#blockRebuiltEsis.clear()
     this.#blockAuthoredLengths.clear()
+    this.#isoSpanKeys.clear()
     this.#blockRepairRsIds.clear()
     this.#blockRsbLengths.clear()
     this.#heldLayerStates.clear()
@@ -4883,6 +5283,7 @@ export class FECManager {
     this.#blockAnchorsMs.clear()
     this.#blockCatalogTrackNames.clear()
     this.#classifiers.clear()
+    this.#noSpanRaps.clear()
     this.#streamGeometries.clear()
     this.#failedBlocks.clear()
     this.#resolvedBlockClasses.clear()