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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockcast/mmt-container",
-  "version": "2.2.0-main.75b39a2cdddf",
+  "version": "2.2.0-main.7e8a9d13c01c",
   "description": "MMTP/LOC container parsing for MMT over MoQ and SSM",
   "type": "module",
   "main": "dist/index.js",
@@ -169,10 +169,10 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@blockcast/fec-worker": "2.2.0-main.75b39a2cdddf",
-    "@blockcast/mmt-base": "2.2.0-main.75b39a2cdddf",
-    "@blockcast/mmt-fec": "2.2.0-main.75b39a2cdddf",
-    "@blockcast/mmt-manifest-verify": "2.2.0-main.75b39a2cdddf",
+    "@blockcast/fec-worker": "2.2.0-main.7e8a9d13c01c",
+    "@blockcast/mmt-base": "2.2.0-main.7e8a9d13c01c",
+    "@blockcast/mmt-fec": "2.2.0-main.7e8a9d13c01c",
+    "@blockcast/mmt-manifest-verify": "2.2.0-main.7e8a9d13c01c",
     "@noble/curves": "^1.9.7",
     "@noble/hashes": "^1.8.0",
     "ajv": "^8.17.1",

package/src/fec-manager.ts

@@ -213,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.
  *
@@ -522,7 +541,14 @@ 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>>()
@@ -538,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
@@ -745,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
   /**
@@ -835,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)
@@ -1489,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)
   }
 
@@ -1683,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,
@@ -1691,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
@@ -1747,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))
       )) {
@@ -2101,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
@@ -2139,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
@@ -2558,6 +2612,7 @@ export class FECManager {
     resetMap(this.#blockSourceEsis)
     resetMap(this.#blockRebuiltEsis)
     resetMap(this.#blockAuthoredLengths)
+    resetSet(this.#isoSpanKeys)
     resetMap(this.#blockRepairRsIds)
     resetMap(this.#blockRsbLengths)
     resetMap(this.#heldLayerStates)
@@ -2691,6 +2746,7 @@ export class FECManager {
     dropMap(this.#blockSourceEsis)
     dropMap(this.#blockRebuiltEsis)
     dropMap(this.#blockAuthoredLengths)
+    dropSet(this.#isoSpanKeys)
     dropMap(this.#blockRepairRsIds)
     dropMap(this.#blockRsbLengths)
     dropMap(this.#blockPathCounts)
@@ -3122,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)
@@ -3285,6 +3342,7 @@ 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) {
@@ -3313,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 = {
@@ -3345,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,
@@ -3385,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)
   }
 
@@ -3864,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) => {
@@ -3952,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)
@@ -4726,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.
@@ -4737,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) {
@@ -4758,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;
@@ -4837,6 +4946,7 @@ export class FECManager {
     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
@@ -4878,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
@@ -4969,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)
@@ -4988,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)
   }
 
@@ -5020,6 +5148,7 @@ export class FECManager {
     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)
@@ -5129,6 +5258,7 @@ export class FECManager {
     this.#blockSourceEsis.clear()
     this.#blockRebuiltEsis.clear()
     this.#blockAuthoredLengths.clear()
+    this.#isoSpanKeys.clear()
     this.#blockRepairRsIds.clear()
     this.#blockRsbLengths.clear()
     this.#heldLayerStates.clear()

package/src/index.ts

@@ -260,6 +260,8 @@ export {
   type FecStats,
   type MulticastSymbolDelivery,
   type UndelimitedIsoLoss,
+  type ExpiredIsoHole,
+  type IsoSpanFailure,
   type FecBlockResolution,
   type RepairVia,
   type FecRepairLayer,