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

package/src/fec-worker-setup.ts

@@ -64,7 +64,7 @@ export interface FecWorkerSetupOptions {
   /**
    * Repair symbols per block this receiver actually joined: the sum of
    * `repairSymbols` over the joined BASE layers (draft-ramadan-moq-fec 6.3).
-   * Reported as P by the worker snapshot and CMCD `x-bc-fec-p`, because the
+   * Reported as P by the worker snapshot and CMCD `com.blockcast-fp`, because the
    * catalog total is not what this receiver joined. Falls back to
    * `fecRepairCount`, which is the same value on a single-layer track.
    */
@@ -252,7 +252,7 @@ export async function setupFecWorkerForTrack(
     blockProfile,
     k: opts.fecK,
     // P as this receiver joined it, not the catalog total: the worker snapshot
-    // and CMCD `x-bc-fec-p` are read from this. Identity on a single layer.
+    // and CMCD `com.blockcast-fp` are read from this. Identity on a single layer.
     repairCount: opts.joinedRepairCount ?? opts.fecRepairCount,
     symbolSize: opts.fecSymbolSize,
     interleaveDepth: interleaveDepthBlocks,

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,
@@ -299,6 +301,7 @@ export {
   type MmtpFeedOutcomeKey,
   type TrackInfo,
   type MmtpReorderStats,
+  type MmtpRecoveredHeadTimingStats,
   type MmtpReorderFrameDiagnostics,
   type MmtpReorderStreamDiagnostics,
   type FrameMeta as ParserFrameMeta,
@@ -526,10 +529,13 @@ export {
   type FecStarvationDetectorConfig,
 } from './fec-starvation-detector.js'
 
-// CMCD Producer (x-bc-* vendor key telemetry, BLO-1044)
+// CMCD v2 Event-mode producer (CTA-5004-B, com.blockcast-* custom keys)
 export {
   CmcdProducer,
-  type CmcdParams,
+  encodeCmcdRecord,
+  type CmcdRecord,
+  type CmcdToken,
+  type CmcdValue,
   type CmcdProducerOptions,
   type SnapshotData,
   type TransportSnapshot,
@@ -546,6 +552,7 @@ export {
 	type TrackFecParams,
 	type TrackFecUnavailable,
 	catalogTrackFecUnavailable,
+	catalogTrackDeliveryMode,
 	catalogGroupDurationMs,
 	catalogKeyframeCadenceMs,
 	catalogFecMediaUnitsPerSecond,
@@ -602,11 +609,22 @@ export {
 	type MmtpFecSessionConfig,
 	type MmtpFecSessionDecoder,
 	type MmtpFecSessionDecoderConstructor,
+	type MmtpFecSessionMessageConfig,
+	type MmtpFecSessionMessageUpdate,
 	type MmtpFecSessionMixedPathStats,
 	type MmtpFecSessionPath,
 	type MmtpFecSessionPathCounts,
 	type MmtpFecSessionStats,
 } from "./mmtp-fec-session.js";
+// MoQ repair-layer subscriptions by measured loss (BLO-35456)
+export {
+	RepairLayerSubscriptions,
+	type MoqRepairDelivery,
+	type RepairLayerSource,
+	type RepairLayerSubscriptionsOptions,
+	type RepairLayerSubscriptionsSnapshot,
+	type RepairTrackSubscription,
+} from "./repair-layer-subscriptions.js";
 
 export {
 	catalogAmtNetworkSource,

package/src/iso-block-locator.ts

@@ -14,9 +14,10 @@
  * between are one or more blocks whose every repair symbol was lost: they are
  * kept as one repair-less span, which completes clean once all of its SS_IDs
  * arrived (C.5.2 makes a gap in consecutive SS_IDs directly visible) and
- * otherwise resolves through its catalog-derived deadline. That is the only
- * way a block without repair completes: on the next block's SS_Start, never on
- * a count of K source symbols.
+ * otherwise resolves through its catalog-derived deadline. A block without
+ * repair completes that way, on the next block's SS_Start, never on a count of
+ * K source symbols, unless a repair that arrives later (a FETCH of the span's
+ * first group) states exactly the span's range: the span was that one block.
  */
 import {
   isoBlockContains,
@@ -58,14 +59,29 @@ export type IsoRepairPlacement<T> =
        */
       readonly hole?: { readonly block: IsoBlockRange; readonly lostSsId: number }
     }
-  /** Not a block this stream can use; the repair symbol is dropped. */
-  | { readonly status: 'conflict' | 'overlap' | 'stale' | 'ahead'; readonly reason: string }
+  /**
+   * Not a block this stream can use; the repair symbol is dropped. `ofSpan` is
+   * set when the repair stated only the first block of that repair-less span:
+   * the span holds more than one block, so no single repair group completes it.
+   */
+  | {
+      readonly status: 'conflict' | 'overlap' | 'stale' | 'ahead'
+      readonly reason: string
+      readonly ofSpan?: IsoBlockRange
+    }
 
 /**
  * Retention: the locator is never without one. Every call that can grow it
  * (`hold`, `placeRepair`) retires, behind the position it just saw, every
  * block, span and held source more than `retentionBlocks` blocks back, by the
- * one ISO horizon metric (`isoBlocksBehindLowerBound`). A block is measured
+ * one ISO horizon metric (`isoBlocksBehindLowerBound`). A held source stays
+ * while a pending hole holding it does: the hole's repair FETCH may still
+ * state its block, and closing the hole places it, so the span it leaves
+ * counts every source it received (BLO-52085). A pending hole the horizon
+ * passes stops being pending (its blocks can no longer be stated, and the
+ * release gate no longer waits for it), but keeps its sources until its
+ * owner closes it (`takeExpiredHoles`), so it still fails as the span it
+ * is. A block is measured
  * from its last SS_ID, so it stays while any SS_ID of it is inside the
  * horizon: a repair-less span has no length bound, and one measured from its
  * start could be retired the moment it is created, before the sources it
@@ -85,8 +101,18 @@ export class IsoBlockLocator<T> {
   #retentionBlocks: number
   #heldEvicted = 0
   #newest: number | undefined
+  #newestSource: number | undefined
   /** Pending holes (see `deferIncompleteGaps`): unstated, sources still held. */
   readonly #holes: IsoBlockRange[] = []
+  /** Holes the horizon passed while pending: sources held until closed. */
+  readonly #expired: IsoBlockRange[] = []
+  /** Of `#expired`, those `takeExpiredHoles` has not handed out yet. */
+  readonly #newlyExpired: IsoBlockRange[] = []
+  /**
+   * Spans closed from expired holes: behind the horizon, so kept only for
+   * `locate` while their sources are fed, until the next retirement.
+   */
+  readonly #closedBehind: IsoBlockRange[] = []
   /**
    * Keep a gap that is missing a source as a pending hole rather than a span,
    * so a repair FETCHed for it (draft-ramadan-moq-fec §7.5) can still state
@@ -152,6 +178,23 @@ export class IsoBlockLocator<T> {
     if (this.#newest === undefined || serial32Precedes(this.#newest, position)) this.#newest = position
   }
 
+  /**
+   * The newest source SS_ID noted with `noteSource` (RFC 1982 order). Unlike
+   * `newest`, a repair never moves it: a repair can run ahead of its sources,
+   * a source cannot run ahead of the sources sent before it except by
+   * reordering.
+   */
+  get newestSource(): number | undefined {
+    return this.#newestSource
+  }
+
+  /** Note a received source's SS_ID; true when it is the newest one yet. */
+  noteSource(ssId: number): boolean {
+    if (this.#newestSource !== undefined && !serial32Precedes(this.#newestSource, ssId)) return false
+    this.#newestSource = ssId
+    return true
+  }
+
   /** Held sources evicted by `heldCapacity` (never by the horizon itself). */
   get heldEvicted(): number {
     return this.#heldEvicted
@@ -174,18 +217,31 @@ export class IsoBlockLocator<T> {
 
   /** The known block or span containing `ssId`, with its ESI. */
   locate(ssId: number): { block: IsoBlockRange; esi: number } | null {
-    for (let i = this.#blocks.length - 1; i >= 0; i--) {
-      const block = this.#blocks[i]!
-      if (isoBlockContains(block.start, block.length, ssId)) {
-        return { block, esi: serial32Distance(block.start, ssId) }
+    for (const blocks of [this.#blocks, this.#closedBehind]) {
+      for (let i = blocks.length - 1; i >= 0; i--) {
+        const block = blocks[i]!
+        if (isoBlockContains(block.start, block.length, ssId)) {
+          return { block, esi: serial32Distance(block.start, ssId) }
+        }
       }
     }
     return null
   }
 
-  /** Number of pending holes. */
+  /** Number of holes not closed yet, pending or past the horizon. */
   get holeCount(): number {
-    return this.#holes.length
+    return this.#holes.length + this.#expired.length
+  }
+
+  /**
+   * The pending holes the horizon has passed since the last call, in the
+   * order it passed them. Each is no longer pending: no repair states a block
+   * in it (that repair is `stale`, as for a span the horizon retired) and the
+   * release gate does not wait for it. Its owner must close it
+   * (`closeHolesWithin`), which turns it into a span that is not kept here.
+   */
+  takeExpiredHoles(): IsoBlockRange[] {
+    return this.#newlyExpired.splice(0)
   }
 
   /** The stated block (never a span) ending exactly at `end`. */
@@ -250,9 +306,11 @@ export class IsoBlockLocator<T> {
   /**
    * Apply one repair symbol's `(SS_Start, SSB_length)`. The first repair of a
    * block states its range and places every held source in it; later repair
-   * symbols of the same block change nothing. A range that contradicts a
-   * known block (a different length, or an overlap with another block or a
-   * span) fails closed: the repair symbol is dropped and no block changes.
+   * symbols of the same block change nothing. A repair whose range is exactly
+   * a repair-less span states that span's one block. A range that contradicts
+   * a known block (a different length, or an overlap with another block or
+   * with part of a span) fails closed: the repair symbol is dropped and no
+   * block changes.
    * A newly stated block retires behind its SS_Start (see the class note).
    * A block so far past `newest` that stating it would retire the position
    * `newest` is refused as `ahead`. When `newest` is a placed block's SS_Start
@@ -271,7 +329,25 @@ export class IsoBlockLocator<T> {
     const known = this.blockAt(start)
     if (known !== undefined) {
       if (known.span) {
-        return { status: 'overlap', reason: `repair block ${start}+${length} falls inside a repair-less span` }
+        // A span is no accepted block: it is the whole blocks between two
+        // stated ones whose repair never came (blocks are consecutive), so a
+        // repair whose range is exactly the span states its one block and
+        // contradicts nothing (draft-ramadan-moq-fec-core-00 5.4). Its sources
+        // were placed at these same ESIs when the span closed. A FETCH of the
+        // span's Group ext(SS_Start) returns just this when one block lost
+        // every multicast repair (a join).
+        if (known.length === length) {
+          const block: IsoBlockRange = { start, length, span: false }
+          this.#blocks[this.#blocks.indexOf(known)] = block
+          return { status: 'placed', block, placed: [] }
+        }
+        return length < known.length
+          ? {
+              status: 'overlap',
+              reason: `repair block ${start}+${length} is only the first block of repair-less span ${known.start}+${known.length}`,
+              ofSpan: known,
+            }
+          : { status: 'overlap', reason: `repair block ${start}+${length} runs past repair-less span ${known.start}+${known.length}` }
       }
       if (known.length !== length) {
         return {
@@ -349,18 +425,28 @@ export class IsoBlockLocator<T> {
   }
 
   /**
-   * Turn every pending hole inside `[start, start + length)` into a
-   * repair-less span, claiming its held sources: its range FETCH ended, so
-   * nothing more will state its blocks. Returns the spans, in SS_ID order.
+   * Turn every hole inside `[start, start + length)` into a repair-less span,
+   * claiming its held sources: its range FETCH ended, so nothing more will
+   * state its blocks. A hole the horizon passed (`takeExpiredHoles`) leaves a
+   * span that is not kept among the blocks, as the horizon would retire it at
+   * once; only `locate` finds it, until the next retirement, so its sources
+   * can be fed. Returns the spans, in SS_ID order.
    */
   closeHolesWithin(start: number, length: number): { block: IsoBlockRange; placed: IsoPlacedSource<T>[] }[] {
     const closed: { block: IsoBlockRange; placed: IsoPlacedSource<T>[] }[] = []
-    for (const hole of [...this.#holes]) {
-      if (!isoBlockContains(start, length, hole.start)) continue
-      this.#holes.splice(this.#holes.indexOf(hole), 1)
-      const spanBlock: IsoBlockRange = { start: hole.start, length: hole.length, span: true }
-      closed.push({ block: spanBlock, placed: this.#claim(spanBlock) })
-      this.#blocks.push(spanBlock)
+    for (const holes of [this.#holes, this.#expired]) {
+      for (const hole of [...holes]) {
+        if (!isoBlockContains(start, length, hole.start)) continue
+        holes.splice(holes.indexOf(hole), 1)
+        const spanBlock: IsoBlockRange = { start: hole.start, length: hole.length, span: true }
+        closed.push({ block: spanBlock, placed: this.#claim(spanBlock) })
+        if (holes === this.#holes) {
+          this.#blocks.push(spanBlock)
+        } else {
+          this.#closedBehind.push(spanBlock)
+          if (this.#newlyExpired.includes(hole)) this.#newlyExpired.splice(this.#newlyExpired.indexOf(hole), 1)
+        }
+      }
     }
     return closed.sort((x, y) => serial32Distance(start, x.block.start) - serial32Distance(start, y.block.start))
   }
@@ -377,15 +463,17 @@ export class IsoBlockLocator<T> {
   }
 
   /**
-   * Retire every block and span whose last SS_ID, and every held source,
-   * lies more than `retentionBlocks` blocks behind `position`, with the shared
-   * lower-bound metric (`isoBlocksBehindLowerBound`) every ISO interleave
-   * horizon uses. Returns the retired block starts.
+   * Retire every block and span whose last SS_ID, and every held source
+   * outside a hole, lies more than `retentionBlocks` blocks behind
+   * `position`, with the shared lower-bound metric (`isoBlocksBehindLowerBound`)
+   * every ISO interleave horizon uses; a pending hole so far behind expires
+   * (`takeExpiredHoles`). Returns the retired block starts.
    */
   retireBehind(position: number): number[] {
     this.observe(position)
     const horizon = this.#retentionBlocks
     const retired: number[] = []
+    this.#closedBehind.length = 0
     for (let i = this.#blocks.length - 1; i >= 0; i--) {
       const block = this.#blocks[i]!
       const last = serial32Add(block.start, block.length - 1)
@@ -397,10 +485,20 @@ export class IsoBlockLocator<T> {
     for (let i = this.#holes.length - 1; i >= 0; i--) {
       const hole = this.#holes[i]!
       const last = serial32Add(hole.start, hole.length - 1)
-      if (isoBlocksBehindLowerBound(last, position, this.#kMax) > horizon) this.#holes.splice(i, 1)
+      if (isoBlocksBehindLowerBound(last, position, this.#kMax) <= horizon) continue
+      this.#holes.splice(i, 1)
+      this.#expired.push(hole)
+      this.#newlyExpired.push(hole)
     }
+    // A held source stays while a hole holding it does (class note).
     for (const ssId of [...this.#held.keys()]) {
-      if (isoBlocksBehindLowerBound(ssId, position, this.#kMax) > horizon) this.#held.delete(ssId)
+      if (
+        isoBlocksBehindLowerBound(ssId, position, this.#kMax) > horizon &&
+        !this.#holes.some((hole) => isoBlockContains(hole.start, hole.length, ssId)) &&
+        !this.#expired.some((hole) => isoBlockContains(hole.start, hole.length, ssId))
+      ) {
+        this.#held.delete(ssId)
+      }
     }
     return retired
   }
@@ -409,9 +507,13 @@ export class IsoBlockLocator<T> {
   reset(): void {
     this.#blocks.length = 0
     this.#holes.length = 0
+    this.#expired.length = 0
+    this.#newlyExpired.length = 0
+    this.#closedBehind.length = 0
     this.#held.clear()
     this.#coverageEnd = undefined
     this.#newest = undefined
+    this.#newestSource = undefined
   }
 
   #claim(block: IsoBlockRange): IsoPlacedSource<T>[] {

package/src/iso-bmff-timing.ts

@@ -581,6 +581,14 @@ type PendingMovieFragment = Array<IsoBmffSampleTiming | null>
 export class IsoBmffTimingResolver {
   #track: IsoBmffTrackTiming | null = null
   #fragments = new Map<string, PendingMovieFragment>()
+  /** First sample of each pending fragment, kept in `#delivered` with its sample count. */
+  #firstSamples = new Map<string, IsoBmffSampleTiming>()
+  /**
+   * First sample and sample count of the newest fragments whose every slot was
+   * cleared. Abandonment counts: `releaseSample` clears a slot too, which
+   * matches the combiner, since it retires an abandoned sample as well.
+   */
+  #delivered = new Map<string, { first: IsoBmffSampleTiming, sampleCount: number }>()
   #pendingSamples = 0
   #evictedSamples = 0
   #lastMovieFragmentRejection: IsoBmffMovieFragmentRejection | null = null
@@ -591,6 +599,11 @@ export class IsoBmffTimingResolver {
     }
   }
 
+  /** True once an FT=0 has bound the track that FT=1 timing is read against. */
+  get initialized(): boolean {
+    return this.#track !== null
+  }
+
   get pendingSampleCount(): number {
     return this.#pendingSamples
   }
@@ -618,10 +631,18 @@ export class IsoBmffTimingResolver {
     return true
   }
 
+  /**
+   * `recovered` marks an FEC-recovered copy. A recovered block hands back
+   * every FT=1 it holds, the received ones included, so a recovered copy of a
+   * fragment whose samples are all done is a duplicate: admitting it again
+   * would charge stale timing and could displace the live MPU's. A source
+   * copy is still admitted again (a rendition switch re-arms timing that way).
+   */
   addMovieFragment(
     mpuSequenceNumber: number,
     data: Uint8Array,
     additionalSampleLimit = this.maxPendingSamples,
+    recovered = false,
   ): boolean {
     this.#lastMovieFragmentRejection = null
     if (!Number.isInteger(additionalSampleLimit) || additionalSampleLimit < 0) {
@@ -648,6 +669,9 @@ export class IsoBmffTimingResolver {
         (sample, index) => sample !== null && sameSample(sample, parsed.samples[index]!),
       )
     }
+    const delivered = recovered ? this.#delivered.get(key) : undefined
+    if (delivered && delivered.sampleCount === parsed.samples.length &&
+        sameSample(delivered.first, parsed.samples[0]!)) return true
     // Sliding window, not a one-way ratchet. `consumeSample` and
     // `releaseSample` between them cover every sample some component observed
     // -- but a sample whose data units never arrive at all is observed by
@@ -683,6 +707,7 @@ export class IsoBmffTimingResolver {
       return false
     }
     this.#fragments.set(key, [...parsed.samples])
+    this.#firstSamples.set(key, parsed.samples[0]!)
     this.#pendingSamples += parsed.samples.length
     return true
   }
@@ -758,6 +783,7 @@ export class IsoBmffTimingResolver {
     let live = 0
     for (const sample of samples) if (sample !== null) live++
     this.#fragments.delete(oldest)
+    this.#firstSamples.delete(oldest)
     this.#pendingSamples -= live
     this.#evictedSamples += live
     return live
@@ -779,13 +805,26 @@ export class IsoBmffTimingResolver {
     if (!samples || !samples[index]) return false
     samples[index] = null
     this.#pendingSamples--
-    if (samples.every(value => value === null)) this.#fragments.delete(key)
+    if (samples.every(value => value === null)) {
+      this.#fragments.delete(key)
+      const first = this.#firstSamples.get(key)!
+      this.#firstSamples.delete(key)
+      this.#delivered.delete(key)
+      this.#delivered.set(key, { first, sampleCount: samples.length })
+      // ponytail: the dedupe memory is as wide as the timing budget, in fragments;
+      // a recovered copy older than that is admitted again, as before.
+      if (this.#delivered.size > this.maxPendingSamples) {
+        this.#delivered.delete(this.#delivered.keys().next().value!)
+      }
+    }
     return true
   }
 
   reset(): void {
     this.#track = null
     this.#fragments.clear()
+    this.#firstSamples.clear()
+    this.#delivered.clear()
     this.#pendingSamples = 0
   }
 }