@blockcast/mmt-container 0.1.0-main.0399efef1f07

package/src/sample-combiner.ts

@@ -0,0 +1,938 @@
+/**
+ * @mmt/container - Sample-level combining of subsample data units (moqcast #37)
+ *
+ * {@link MFUReassembler} reassembles exactly one data unit -- a whole-sample
+ * DU, or one subsample DU of a partitioned sample. When a timed sample
+ * exceeds one data unit's 256-payload capacity, the origin packetizer
+ * partitions it into multiple subsample data units (each its own FI chain,
+ * its own authored base offset). This module combines those
+ * already-reassembled data units back into one contiguous sample.
+ *
+ * Container-blind, matching {@link MFUReassembler}'s own doctrine: it never
+ * parses ISOBMFF itself. The authored sample size a subsample-partitioned
+ * sample must total to comes from the host's own FT=1 (movie-fragment-
+ * metadata) parse, supplied via {@link SampleCombiner.registerAuthoredSize}.
+ * Completion is a protocol event -- every constituent data unit reassembled,
+ * byte-adjacent from zero, totaling the registered size -- never a
+ * timer-based guess; on lossy paths the existing per-data-unit deadline in
+ * {@link MFUReassembler} already bounds each constituent, so this module adds
+ * no second timer tier, matching moqcast #37 section 5.2.1.
+ *
+ * A whole-sample data unit whose length already equals the registered
+ * authored size passes through immediately, with no buffering. When
+ * `requireAuthoredSize` is false, an offset-zero data unit with no registered
+ * size at all also passes through immediately -- the pre-amendment shape, for
+ * a host that does not drive FT=1. When true, that same data unit instead
+ * buffers and waits for a size to be registered: FT=1 always publishes before
+ * any FT=2 sample referencing it (moqcast #37), but on a lossy path FT=1 can
+ * still *arrive* after an offset-zero data unit (reordering, or FT=1's own DU
+ * FEC-recovered late) -- treating "no size yet" as "whole sample" in that
+ * window would silently truncate a subsample-partitioned sample.
+ *
+ * Both `#pending` (incomplete samples) and `#authoredSizes` (registered but
+ * not yet consumed) are bounded. `#pending` is bounded by `maxBuffered`
+ * samples and `maxSegmentsPerSample` data units per sample; a full table
+ * evicts its oldest sample by insertion order rather than throwing, so one
+ * FEC-lost subsample DU cannot wedge every future sample. `#authoredSizes` is
+ * bounded by retiring each key the moment its sample completes, keeping only a
+ * bounded recent-retirement set so a late duplicate or FEC-recovered
+ * retransmission for that same sample is dropped rather than silently
+ * re-emitted or misread as a fresh whole sample.
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  MmtpSourcePath,
+  ReassembledMFU,
+  MmtpDeliveryProvenance,
+} from './mfu-reassembler.js'
+
+/** Identifies one authored sample: `(catalogTrackName, mpu, movieFragmentSequenceNumber, sampleNumber)`. */
+type SampleKey = string
+
+function sampleKey(
+  catalogTrackName: string | undefined,
+  mpuSequenceNumber: number,
+  movieFragmentSequenceNumber: number,
+  sampleNumber: number,
+): SampleKey {
+  return JSON.stringify([catalogTrackName ?? null, mpuSequenceNumber, movieFragmentSequenceNumber, sampleNumber])
+}
+
+/** The `catalogTrackName` a key was built from, or undefined when it had none. */
+function trackNameOfKey(key: SampleKey): string | undefined {
+  const name = (JSON.parse(key) as [string | null, number, number, number])[0]
+  return name ?? undefined
+}
+
+/** The full authored-sample identity a key was built from. */
+function identityOfKey(key: SampleKey): AbandonedSample {
+  const [name, mpuSequenceNumber, movieFragmentSequenceNumber, sampleNumber] =
+    JSON.parse(key) as [string | null, number, number, number]
+  return {
+    catalogTrackName: name ?? undefined,
+    mpuSequenceNumber,
+    movieFragmentSequenceNumber,
+    sampleNumber,
+  }
+}
+
+/**
+ * An authored sample that provably will not be delivered, reported to the
+ * owner of any per-sample state keyed on this identity so that state can be
+ * released. See {@link SampleCombinerOptions.onAbandon}.
+ */
+export interface AbandonedSample {
+  catalogTrackName: string | undefined
+  mpuSequenceNumber: number
+  movieFragmentSequenceNumber: number
+  sampleNumber: number
+}
+
+/** One authored sample combined from its constituent data unit(s). */
+export interface CombinedSample {
+  mpuSequenceNumber: number
+  movieFragmentSequenceNumber: number
+  sampleNumber: number
+  /** The full sample's media bytes, in ascending-offset order. */
+  data: Uint8Array
+  /** Raw MMTP short-NTP header timestamp for the offset-zero data unit. */
+  mmtpTimestamp?: bigint
+  timestamp: bigint
+  /**
+   * The sample's RAP flag is the RAP flag of the FI=0 or FI=1 object of its
+   * offset-0 data unit (moqcast #37).
+   */
+  rapFlag: boolean
+  priority?: number
+  /** Every authoritative source-packet sequence across all constituent data units, in offset order. */
+  packetSequenceNumbers?: number[]
+  /** Subset of packetSequenceNumbers reconstructed by FEC. */
+  repairedPacketSequenceNumbers?: number[]
+  catalogTrackName?: string
+  /** Number of subsample data units combined (1 for a whole-sample DU or a non-timed passthrough). */
+  subsampleCount: number
+  /** MMTP fragments that formed the sample, summed across constituent data units. */
+  fragmentCount: number
+  /**
+   * Transport that supplied the offset-zero data unit's head fragment. Taken
+   * from that data unit alone -- like {@link CombinedSample.rapFlag} -- rather
+   * than from whichever sibling happened to complete last.
+   */
+  source?: MmtpSourcePath
+  /**
+   * Strict provenance folded across EVERY constituent data unit, and within
+   * each of them across every MMTP fragment. Unlike {@link CombinedSample.source},
+   * which is the offset-zero DU's routing tag, this is whole-sample evidence:
+   * only 'multicast' proves that no byte of this sample arrived another way.
+   */
+  deliveryProvenance: MmtpDeliveryProvenance
+}
+
+export const SAMPLE_COMBINE_ERROR_CODES = [
+  'duplicate-subsample-offset',
+  'overlapping-subsample',
+  'exceeds-authored-size',
+  'too-many-subsample-segments',
+] as const
+
+export type SampleCombineErrorCode = typeof SAMPLE_COMBINE_ERROR_CODES[number]
+
+/**
+ * Fail-closed rejection reasons for subsample combining. Distinct from
+ * {@link MfuReassemblyError}, which governs one data unit's own fragment
+ * chain; these govern combining already-reassembled data units into a
+ * sample.
+ */
+export class SampleCombineError extends Error {
+  readonly name = 'SampleCombineError'
+
+  constructor(readonly code: SampleCombineErrorCode, message: string) {
+    super(message)
+  }
+}
+
+export interface SampleCombinerStats {
+  combinedSamples: number
+  passthroughSamples: number
+  timedOutSamples: number
+  /** Incomplete samples discarded to enforce `maxBuffered`. */
+  evictedSamples: number
+}
+
+export interface SampleCombinerOptions {
+  /**
+   * Max concurrent incomplete samples. Enforced by evicting the oldest by
+   * insertion order, never by throwing, so a host that never calls
+   * {@link SampleCombiner.cleanupTimeouts} still recovers from a permanently
+   * lost subsample data unit instead of wedging.
+   */
+  maxBuffered: number
+  /**
+   * When true, an offset-zero data unit with no registered authored size
+   * buffers and waits for one rather than passing through immediately. See
+   * the module doc.
+   */
+  requireAuthoredSize: boolean
+  /**
+   * Max subsample data units held for one sample at once. Bounds both memory
+   * and the per-insert overlap scan; a legitimate subsample-partitioned
+   * sample needs at most `ceil(sampleSize / (256 * maxPayload))` data units.
+   */
+  maxSegmentsPerSample: number
+  /**
+   * Called once per sample discarded by eviction or timeout -- the two paths
+   * where a sample is abandoned while its stream keeps running.
+   *
+   * Completion and passthrough are deliberately excluded: those samples were
+   * delivered, and their consumer releases whatever per-sample state it held.
+   * Wholesale resets (`flush`, `resetStream`) are excluded too, because they
+   * already discard that state in bulk.
+   *
+   * Exists because per-sample state elsewhere -- notably the ISO-BMFF
+   * timing-sample budget -- is otherwise only released on delivery, making it
+   * a one-way ratchet that wedges the stream once it saturates. The combiner
+   * is where abandonment is actually detected, so it is where the signal has
+   * to come from; inferring it downstream would require a timer or an age
+   * bound, neither of which is derivable from the catalog.
+   */
+  onAbandon?: (sample: AbandonedSample) => void
+}
+
+interface PendingSample {
+  /** Held data units keyed by their authored base offset. */
+  segments: Map<number, ReassembledMFU>
+  startedAt: number
+}
+
+/** Combines subsample data units of one sample into a contiguous whole. */
+export class SampleCombiner {
+  #maxBuffered: number
+  #requireAuthoredSize: boolean
+  #maxSegmentsPerSample: number
+  #onAbandon: ((sample: AbandonedSample) => void) | undefined
+  #authoredSizes: Map<SampleKey, number> = new Map()
+  /** Map iteration is insertion-ordered, so the first key is the oldest. */
+  #pending: Map<SampleKey, PendingSample> = new Map()
+  /**
+   * Bounded, insertion-ordered set of recently-completed sample keys, so a
+   * late duplicate or FEC-recovered retransmission is dropped rather than
+   * re-emitted or misread as a fresh whole sample.
+   */
+  #retired: Set<SampleKey> = new Set()
+  #stats: SampleCombinerStats = {
+    combinedSamples: 0,
+    passthroughSamples: 0,
+    timedOutSamples: 0,
+    evictedSamples: 0,
+  }
+
+  constructor(options: SampleCombinerOptions) {
+    const { maxBuffered, requireAuthoredSize, maxSegmentsPerSample, onAbandon } = options
+    if (!Number.isInteger(maxBuffered) || maxBuffered <= 0) {
+      throw new Error('[SampleCombiner] maxBuffered must be a positive integer')
+    }
+    if (!Number.isInteger(maxSegmentsPerSample) || maxSegmentsPerSample <= 0) {
+      throw new Error('[SampleCombiner] maxSegmentsPerSample must be a positive integer')
+    }
+    this.#maxBuffered = maxBuffered
+    this.#requireAuthoredSize = requireAuthoredSize
+    this.#maxSegmentsPerSample = maxSegmentsPerSample
+    this.#onAbandon = onAbandon
+  }
+
+  /** Report one abandoned sample to the owner of any state keyed on it. */
+  #abandon(key: SampleKey): void {
+    this.#onAbandon?.(identityOfKey(key))
+  }
+
+  /**
+   * Register the authored sample size from the host's own FT=1 parse. Per
+   * moqcast #37, FT=1 for a movie fragment publishes before any FT=2 sample
+   * referencing it, so a host driving FT=1 as it arrives registers each
+   * sample's size before that sample's own data unit(s) arrive.
+   *
+   * On a lossy path FT=1 can still *arrive* late, after data units this
+   * combiner has already buffered. Registering a size therefore re-drives the
+   * completion check and returns the combined sample when the buffered data
+   * units already satisfy the newly-known size. Callers MUST consume the
+   * return value: for a sample carried by a single data unit there is no
+   * later {@link SampleCombiner.addMfu} to re-enter, so discarding it
+   * silently drops the sample.
+   *
+   * Registering also clears the key from the retired set. Retirement exists
+   * to drop data units that arrive *passively* after a sample completed — a
+   * late duplicate, an FEC-recovered retransmission. A host calling this
+   * method is instead asserting that a sample with this identity is authored
+   * now, which is what happens when a publisher restarts and its MPU
+   * sequence numbers begin again, or when MPU sequence wraps. Without this,
+   * such a stream would silently drop every sample whose identity collided
+   * with a retired one until the bounded set aged the key out.
+   */
+  registerAuthoredSize(
+    catalogTrackName: string | undefined,
+    mpuSequenceNumber: number,
+    movieFragmentSequenceNumber: number,
+    sampleNumber: number,
+    size: number,
+  ): CombinedSample | null {
+    const key = sampleKey(catalogTrackName, mpuSequenceNumber, movieFragmentSequenceNumber, sampleNumber)
+    this.#retired.delete(key)
+    this.#authoredSizes.set(key, size)
+    return this.#tryComplete(key, size)
+  }
+
+  /**
+   * Add one reassembled data unit. Returns the combined sample once every
+   * constituent data unit has arrived and totals the authored size.
+   */
+  addMfu(mfu: ReassembledMFU): CombinedSample | null {
+    if (mfu.movieFragmentSequenceNumber === undefined || mfu.sampleNumber === undefined) {
+      // Non-timed (Item) MFU: sample combining does not apply.
+      this.#stats.passthroughSamples++
+      return fromPassthrough(mfu)
+    }
+    const offset = mfu.sampleOffset ?? 0
+    const key = sampleKey(
+      mfu.catalogTrackName,
+      mfu.mpuSequenceNumber,
+      mfu.movieFragmentSequenceNumber,
+      mfu.sampleNumber,
+    )
+
+    if (this.#retired.has(key)) {
+      // Duplicate or late data unit for an already-retired sample (a
+      // FEC-recovered retransmission, reordering after completion, or a
+      // sample discarded by eviction/timeout). Drop it rather than
+      // re-emitting a duplicate downstream or misreading a stray fragment as
+      // a fresh whole sample.
+      return null
+    }
+
+    const dataLen = mfu.data.byteLength
+    const authoredSize = this.#authoredSizes.get(key)
+
+    if (offset === 0 && !this.#pending.has(key)) {
+      const passesThrough = authoredSize === undefined
+        ? !this.#requireAuthoredSize
+        : dataLen === authoredSize
+      if (passesThrough) {
+        this.#stats.passthroughSamples++
+        this.#retire(key)
+        return fromPassthrough(mfu)
+      }
+      // Either shorter than the authored total (a subsample), or awaiting a
+      // size under requireAuthoredSize -- buffer below.
+    }
+
+    // Reject BEFORE mutating any state. An earlier revision allocated the
+    // pending entry (evicting the oldest sample to make room) and only then
+    // validated, so a data unit the combiner went on to reject could destroy
+    // an unrelated in-flight sample and leave an empty entry in its slot.
+    const thisEnd = offset + dataLen
+    if (authoredSize !== undefined && thisEnd > authoredSize) {
+      throw new SampleCombineError(
+        'exceeds-authored-size',
+        'combined subsample data would exceed the registered authored sample size',
+      )
+    }
+    const existing = this.#pending.get(key)
+    if (existing !== undefined) {
+      if (existing.segments.has(offset)) {
+        throw new SampleCombineError(
+          'duplicate-subsample-offset',
+          'subsample data unit duplicates an offset already held for this sample',
+        )
+      }
+      if (existing.segments.size >= this.#maxSegmentsPerSample) {
+        throw new SampleCombineError(
+          'too-many-subsample-segments',
+          'a sample already holds the maximum number of subsample data units',
+        )
+      }
+      for (const [segOffset, seg] of existing.segments) {
+        const segEnd = segOffset + seg.data.byteLength
+        if (offset < segEnd && segOffset < thisEnd) {
+          throw new SampleCombineError(
+            'overlapping-subsample',
+            "subsample data unit overlaps a preceding data unit's byte range",
+          )
+        }
+      }
+    }
+
+    let pending = existing
+    if (pending === undefined) {
+      if (this.#pending.size >= this.#maxBuffered) this.#evictOldestPending()
+      pending = { segments: new Map(), startedAt: Date.now() }
+      this.#pending.set(key, pending)
+    }
+    pending.segments.set(offset, mfu)
+
+    if (authoredSize === undefined) return null
+    return this.#tryComplete(key, authoredSize)
+  }
+
+  /**
+   * Emit the sample when its held data units are byte-adjacent from zero and
+   * total `size`. Completion is a protocol event, never a timer.
+   */
+  #tryComplete(key: SampleKey, size: number): CombinedSample | null {
+    const pending = this.#pending.get(key)
+    if (pending === undefined) return null
+    let expected = 0
+    const sortedOffsets = [...pending.segments.keys()].sort((a, b) => a - b)
+    for (const segOffset of sortedOffsets) {
+      if (segOffset !== expected) return null // gap: not yet contiguous from zero.
+      expected += pending.segments.get(segOffset)!.data.byteLength
+    }
+    if (expected !== size) return null // contiguous so far, short of the authored total.
+
+    this.#pending.delete(key)
+    this.#stats.combinedSamples++
+    this.#retire(key)
+    return fromSegments(pending.segments, sortedOffsets)
+  }
+
+  /**
+   * Retire a sample's key: free its registered authored size and remember the
+   * key in a bounded recency set. Called on every path that removes a sample
+   * -- completion, passthrough, eviction, and timeout -- so `#authoredSizes`
+   * cannot accumulate entries for samples that never complete, and so a later
+   * data unit for a discarded sample is dropped rather than starting a fresh
+   * buffer or being misread as a whole sample.
+   *
+   * The recency set holds `maxBuffered` keys. A duplicate delayed by more
+   * than that many retirements escapes it; on a reliable path there is no
+   * such duplicate, and on a lossy path the per-data-unit deadline in
+   * {@link MFUReassembler} bounds the delay well inside this window.
+   */
+  #retire(key: SampleKey): void {
+    this.#authoredSizes.delete(key)
+    this.#retired.add(key)
+    while (this.#retired.size > this.#maxBuffered) {
+      const oldest = this.#retired.values().next().value
+      if (oldest === undefined) break
+      this.#retired.delete(oldest)
+    }
+  }
+
+  /**
+   * Discard the oldest pending sample by insertion order. This is the only
+   * backstop against one FEC-lost subsample data unit wedging
+   * {@link SampleCombiner.addMfu} for every future sample once `maxBuffered`
+   * is reached, for a host that never drives
+   * {@link SampleCombiner.cleanupTimeouts}.
+   */
+  #evictOldestPending(): void {
+    const oldest = this.#pending.keys().next().value
+    if (oldest === undefined) return
+    this.#pending.delete(oldest)
+    this.#stats.evictedSamples++
+    this.#retire(oldest)
+    this.#abandon(oldest)
+  }
+
+  /**
+   * Discard samples whose oldest held segment has waited past `timeoutMs`.
+   * Mirrors {@link MFUReassembler}'s clock-driven shape; the per-data-unit
+   * deadline inside {@link MFUReassembler} already bounds each constituent,
+   * so this is a backstop against a host that registers an authored size but
+   * never supplies every subsample DU.
+   */
+  cleanupTimeouts(timeoutMs: number): void {
+    const now = Date.now()
+    for (const [key, pending] of [...this.#pending]) {
+      if (now - pending.startedAt > timeoutMs) {
+        this.#pending.delete(key)
+        this.#stats.timedOutSamples++
+        this.#retire(key)
+        this.#abandon(key)
+      }
+    }
+  }
+
+  flush(): void {
+    this.#pending.clear()
+    this.#authoredSizes.clear()
+    this.#retired.clear()
+  }
+
+  /**
+   * Drop one stream's in-flight, registered-size, and retired state while
+   * preserving every other stream (mirrors
+   * {@link MFUReassembler.resetStream}).
+   */
+  resetStream(catalogTrackName: string): void {
+    for (const key of this.#pending.keys()) {
+      if (trackNameOfKey(key) === catalogTrackName) this.#pending.delete(key)
+    }
+    for (const key of this.#authoredSizes.keys()) {
+      if (trackNameOfKey(key) === catalogTrackName) this.#authoredSizes.delete(key)
+    }
+    for (const key of this.#retired) {
+      if (trackNameOfKey(key) === catalogTrackName) this.#retired.delete(key)
+    }
+  }
+
+  get stats(): SampleCombinerStats {
+    return { ...this.#stats }
+  }
+
+  get pendingCount(): number {
+    return this.#pending.size
+  }
+
+  /**
+   * Registered authored sizes still held. Diagnostic only: it exists so tests
+   * and health reporting can assert this table stays bounded, since an
+   * unbounded one is invisible from `pendingCount` alone.
+   */
+  get debugAuthoredSizeCount(): number {
+    return this.#authoredSizes.size
+  }
+
+  /** Retired keys still remembered. Diagnostic only, bounded by `maxBuffered`. */
+  get debugRetiredCount(): number {
+    return this.#retired.size
+  }
+}
+
+function fromPassthrough(mfu: ReassembledMFU): CombinedSample {
+  return {
+    mpuSequenceNumber: mfu.mpuSequenceNumber,
+    movieFragmentSequenceNumber: mfu.movieFragmentSequenceNumber ?? 0,
+    sampleNumber: mfu.sampleNumber ?? 0,
+    data: mfu.data,
+    mmtpTimestamp: mfu.timestamp,
+    timestamp: mfu.timestamp,
+    rapFlag: mfu.rapFlag,
+    priority: mfu.priority,
+    packetSequenceNumbers: mfu.packetSequenceNumbers,
+    repairedPacketSequenceNumbers: mfu.repairedPacketSequenceNumbers,
+    catalogTrackName: mfu.catalogTrackName,
+    subsampleCount: 1,
+    fragmentCount: mfu.fragmentCount,
+    source: mfu.source,
+    // One data unit in, one sample out: its provenance IS the sample's.
+    deliveryProvenance: mfu.deliveryProvenance
+  }
+}
+
+function fromSegments(
+  segments: Map<number, ReassembledMFU>,
+  sortedOffsets: number[],
+): CombinedSample {
+  const totalSize = sortedOffsets.reduce((sum, offset) => sum + segments.get(offset)!.data.byteLength, 0)
+  const data = new Uint8Array(totalSize)
+  let packetSequenceNumbers: number[] | undefined
+  let repairedPacketSequenceNumbers: number[] | undefined
+  let writeOffset = 0
+  let first: ReassembledMFU | undefined
+  let fragmentCount = 0
+  // Fold across data units the same way the reassembler folds across the
+  // fragments inside one: a sample is multicast-exclusive only if every
+  // subsample that formed it was.
+  let combinedProvenance: MmtpDeliveryProvenance =
+    sortedOffsets.length === 0 ? 'unknown' : 'multicast'
+  for (const offset of sortedOffsets) {
+    const seg = segments.get(offset)!
+    combinedProvenance =
+      combinedProvenance === 'mixed' || seg.deliveryProvenance === 'mixed'
+        ? 'mixed'
+        : combinedProvenance === 'unknown' || seg.deliveryProvenance === 'unknown'
+          ? 'unknown'
+          : 'multicast'
+    data.set(seg.data, writeOffset)
+    writeOffset += seg.data.byteLength
+    fragmentCount += seg.fragmentCount
+    if (seg.packetSequenceNumbers !== undefined) {
+      (packetSequenceNumbers ??= []).push(...seg.packetSequenceNumbers)
+    }
+    if (seg.repairedPacketSequenceNumbers !== undefined) {
+      (repairedPacketSequenceNumbers ??= []).push(...seg.repairedPacketSequenceNumbers)
+    }
+    if (first === undefined) first = seg
+  }
+  return {
+    mpuSequenceNumber: first!.mpuSequenceNumber,
+    movieFragmentSequenceNumber: first!.movieFragmentSequenceNumber!,
+    sampleNumber: first!.sampleNumber!,
+    data,
+    mmtpTimestamp: first!.timestamp,
+    timestamp: first!.timestamp,
+    rapFlag: first!.rapFlag,
+    priority: first!.priority,
+    packetSequenceNumbers,
+    repairedPacketSequenceNumbers,
+    catalogTrackName: first!.catalogTrackName,
+    subsampleCount: segments.size,
+    fragmentCount,
+    source: first!.source,
+    deliveryProvenance: combinedProvenance,
+  }
+}
+
+// =============================================================================
+// Inline Tests (vitest)
+// =============================================================================
+
+if (import.meta.vitest) {
+  const { describe, test, expect } = import.meta.vitest
+
+  const combiner = (overrides: Partial<SampleCombinerOptions> = {}) =>
+    new SampleCombiner({
+      maxBuffered: 10,
+      requireAuthoredSize: false,
+      maxSegmentsPerSample: 8,
+      ...overrides,
+    })
+
+  const mfu = (
+    mpu: number,
+    movie: number,
+    sample: number,
+    offset: number,
+    data: number[],
+    timestamp: bigint,
+    rapFlag: boolean,
+    deliveryProvenance: MmtpDeliveryProvenance = 'multicast',
+  ): ReassembledMFU => ({
+    mpuSequenceNumber: mpu,
+    data: new Uint8Array(data),
+    timestamp,
+    fragmentCount: 1,
+    rapFlag,
+    sampleNumber: sample,
+    movieFragmentSequenceNumber: movie,
+    sampleOffset: offset,
+    packetSequenceNumbers: [offset],
+    deliveryProvenance,
+  })
+
+  describe('SampleCombiner', () => {
+    test('whole-sample DU passes through immediately with no registered size', () => {
+      const c = combiner()
+      const out = c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3, 4, 5], 1000n, true))
+      expect(out).not.toBeNull()
+      expect(out!.data).toEqual(new Uint8Array([1, 2, 3, 4, 5]))
+      expect(out!.subsampleCount).toBe(1)
+      expect(c.pendingCount).toBe(0)
+    })
+
+    test('whole-sample DU passes through when it matches the registered size', () => {
+      const c = combiner()
+      c.registerAuthoredSize(undefined, 1, 9, 17, 5)
+      const out = c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3, 4, 5], 1000n, true))
+      expect(out?.data).toEqual(new Uint8Array([1, 2, 3, 4, 5]))
+    })
+
+    test('subsample data units combine once the authored size is met', () => {
+      const c = combiner()
+      c.registerAuthoredSize(undefined, 1, 9, 17, 10)
+
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3, 4, 5], 1000n, true))).toBeNull()
+      expect(c.pendingCount).toBe(1)
+
+      const out = c.addMfu(mfu(1, 9, 17, 5, [6, 7, 8, 9, 10], 1001n, false))
+      expect(out?.data).toEqual(new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]))
+      expect(out?.subsampleCount).toBe(2)
+      expect(out?.rapFlag).toBe(true) // offset-0 DU's RAP flag, per moqcast #37.
+      expect(out?.timestamp).toBe(1000n)
+      expect(c.pendingCount).toBe(0)
+      expect(c.stats.combinedSamples).toBe(1)
+    })
+
+    test('subsample data units combine out of order', () => {
+      const c = combiner()
+      c.registerAuthoredSize(undefined, 1, 9, 17, 10)
+
+      expect(c.addMfu(mfu(1, 9, 17, 5, [6, 7, 8, 9, 10], 1001n, false))).toBeNull()
+      const out = c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3, 4, 5], 1000n, true))
+      expect(out?.data).toEqual(new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]))
+    })
+
+    test('subsample without a registered size never completes', () => {
+      // A non-zero-offset DU always buffers (it can never be a whole
+      // sample). Without a registered authored size there is nothing to
+      // combine against, so it -- and a sibling that arrives after it --
+      // stay pending rather than being guessed complete.
+      const c = combiner()
+      expect(c.addMfu(mfu(1, 9, 17, 3, [1, 2, 3], 1001n, false))).toBeNull()
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3], 1000n, true))).toBeNull()
+      expect(c.pendingCount).toBe(1)
+    })
+
+    test('requireAuthoredSize buffers an offset-zero DU instead of guessing complete', () => {
+      // A moqcast-#37-aware host opts into fail-closed buffering: on a lossy
+      // path FT=1 can arrive after an offset-zero data unit (reordering, or
+      // FT=1's own DU recovered late by FEC). Treating "no size yet" as
+      // "whole sample" would silently truncate a partitioned sample.
+      const c = combiner({ requireAuthoredSize: true })
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3, 4, 5], 1000n, true))).toBeNull()
+      expect(c.pendingCount).toBe(1)
+
+      c.registerAuthoredSize(undefined, 1, 9, 17, 10)
+      const out = c.addMfu(mfu(1, 9, 17, 5, [6, 7, 8, 9, 10], 1001n, false))
+      expect(out?.data).toEqual(new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]))
+    })
+
+    test('duplicate offset is rejected', () => {
+      const c = combiner()
+      c.registerAuthoredSize(undefined, 1, 9, 17, 10)
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3, 4, 5], 1000n, true))).toBeNull()
+      expect(() => c.addMfu(mfu(1, 9, 17, 0, [9, 9, 9, 9, 9], 2000n, true)))
+        .toThrow(SampleCombineError)
+    })
+
+    test('overlapping subsample is rejected', () => {
+      const c = combiner()
+      c.registerAuthoredSize(undefined, 1, 9, 17, 10)
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3, 4, 5], 1000n, true))).toBeNull()
+      expect(() => c.addMfu(mfu(1, 9, 17, 3, [9, 9, 9, 9, 9], 2000n, true)))
+        .toThrow(SampleCombineError)
+    })
+
+    test('exceeding the authored size is rejected', () => {
+      const c = combiner()
+      c.registerAuthoredSize(undefined, 1, 9, 17, 8)
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3, 4, 5], 1000n, true))).toBeNull()
+      expect(() => c.addMfu(mfu(1, 9, 17, 5, [6, 7, 8, 9, 10], 2000n, false)))
+        .toThrow(SampleCombineError)
+    })
+
+    test('exceeding maxSegmentsPerSample is rejected', () => {
+      const c = combiner({ maxSegmentsPerSample: 2 })
+      c.registerAuthoredSize(undefined, 1, 9, 17, 100)
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 2], 1000n, true))).toBeNull()
+      expect(c.addMfu(mfu(1, 9, 17, 2, [3, 4], 1001n, false))).toBeNull()
+      expect(() => c.addMfu(mfu(1, 9, 17, 4, [5, 6], 1002n, false)))
+        .toThrow(SampleCombineError)
+    })
+
+    test('reports every abandoned sample so its per-sample state can be freed', () => {
+      // Regression (BLO-31103): eviction and timeout are the two paths where
+      // a sample is abandoned while its stream keeps running. State keyed on
+      // that sample elsewhere -- notably the ISO-BMFF timing-sample budget --
+      // is otherwise released only on delivery, so an abandoned sample holds
+      // its slot forever and the budget becomes a one-way ratchet that wedges
+      // the stream at saturation.
+      const abandoned: AbandonedSample[] = []
+      const c = combiner({ maxBuffered: 2, onAbandon: s => abandoned.push(s) })
+      c.registerAuthoredSize(undefined, 1, 9, 17, 10)
+      c.registerAuthoredSize(undefined, 1, 9, 18, 10)
+      c.registerAuthoredSize(undefined, 1, 9, 19, 10)
+
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 1, 1, 1, 1], 1000n, true))).toBeNull()
+      expect(c.addMfu(mfu(1, 9, 18, 0, [2, 2, 2, 2, 2], 1001n, true))).toBeNull()
+      expect(abandoned).toEqual([])
+
+      // Eviction reports the evicted identity, not the incoming one.
+      expect(c.addMfu(mfu(1, 9, 19, 0, [3, 3, 3, 3, 3], 1002n, true))).toBeNull()
+      expect(abandoned).toEqual([{
+        catalogTrackName: undefined,
+        mpuSequenceNumber: 1,
+        movieFragmentSequenceNumber: 9,
+        sampleNumber: 17,
+      }])
+
+      // Timeout reports too; both survivors are still incomplete here.
+      c.cleanupTimeouts(-1)
+      expect(abandoned.map(s => s.sampleNumber)).toEqual([17, 18, 19])
+
+      // A delivered sample is NOT reported: its consumer releases that state.
+      const d = combiner({ maxBuffered: 2, onAbandon: s => abandoned.push(s) })
+      d.registerAuthoredSize(undefined, 1, 9, 20, 10)
+      expect(d.addMfu(mfu(1, 9, 20, 0, [4, 4, 4, 4, 4], 1003n, true))).toBeNull()
+      expect(d.addMfu(mfu(1, 9, 20, 5, [5, 5, 5, 5, 5], 1004n, false))).not.toBeNull()
+      expect(abandoned.map(s => s.sampleNumber)).toEqual([17, 18, 19])
+    })
+
+    test('a full combiner evicts the oldest pending sample instead of throwing', () => {
+      // Eviction is by insertion order, which is also the only backstop
+      // against one permanently-lost subsample DU wedging every future
+      // sample once maxBuffered incomplete samples accumulate.
+      const c = combiner({ maxBuffered: 2 })
+      c.registerAuthoredSize(undefined, 1, 9, 17, 10)
+      c.registerAuthoredSize(undefined, 1, 9, 18, 10)
+      c.registerAuthoredSize(undefined, 1, 9, 19, 10)
+
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 1, 1, 1, 1], 1000n, true))).toBeNull()
+      expect(c.addMfu(mfu(1, 9, 18, 0, [2, 2, 2, 2, 2], 1001n, true))).toBeNull()
+      expect(c.pendingCount).toBe(2)
+
+      // A third distinct incomplete sample evicts sample 17, the oldest.
+      expect(c.addMfu(mfu(1, 9, 19, 0, [3, 3, 3, 3, 3], 1002n, true))).toBeNull()
+      expect(c.pendingCount).toBe(2)
+      expect(c.stats.evictedSamples).toBe(1)
+
+      // The surviving samples are undisturbed and still complete normally.
+      expect(c.addMfu(mfu(1, 9, 18, 5, [8, 8, 8, 8, 8], 2001n, false))?.data)
+        .toEqual(new Uint8Array([2, 2, 2, 2, 2, 8, 8, 8, 8, 8]))
+      expect(c.addMfu(mfu(1, 9, 19, 5, [9, 9, 9, 9, 9], 2002n, false))?.data)
+        .toEqual(new Uint8Array([3, 3, 3, 3, 3, 9, 9, 9, 9, 9]))
+
+      // The combiner still accepts new work rather than being wedged.
+      c.registerAuthoredSize(undefined, 1, 9, 20, 10)
+      expect(c.addMfu(mfu(1, 9, 20, 0, [4, 4, 4, 4, 4], 3000n, true))).toBeNull()
+      expect(c.addMfu(mfu(1, 9, 20, 5, [7, 7, 7, 7, 7], 3001n, false))?.data)
+        .toEqual(new Uint8Array([4, 4, 4, 4, 4, 7, 7, 7, 7, 7]))
+    })
+
+    test('a completed sample frees its authored size and drops a late duplicate', () => {
+      const c = combiner()
+      c.registerAuthoredSize(undefined, 1, 9, 17, 10)
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3, 4, 5], 1000n, true))).toBeNull()
+      expect(c.addMfu(mfu(1, 9, 17, 5, [6, 7, 8, 9, 10], 1001n, false))).not.toBeNull()
+
+      // A FEC-recovered retransmission of the completed sample's offset-0
+      // data unit must not be re-emitted as a second complete sample.
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3, 4, 5], 2000n, true))).toBeNull()
+    })
+
+    test('resetStream drops one track and preserves the others', () => {
+      const c = combiner()
+      c.registerAuthoredSize('video/720p', 1, 9, 17, 10)
+      c.registerAuthoredSize('audio', 1, 9, 17, 10)
+      const video = { ...mfu(1, 9, 17, 0, [1, 1, 1, 1, 1], 1000n, true), catalogTrackName: 'video/720p' }
+      const audio = { ...mfu(1, 9, 17, 0, [2, 2, 2, 2, 2], 1000n, true), catalogTrackName: 'audio' }
+      expect(c.addMfu(video)).toBeNull()
+      expect(c.addMfu(audio)).toBeNull()
+
+      c.resetStream('video/720p')
+      expect(c.pendingCount).toBe(1)
+
+      const audioTail = { ...mfu(1, 9, 17, 5, [3, 3, 3, 3, 3], 1001n, false), catalogTrackName: 'audio' }
+      expect(c.addMfu(audioTail)?.data).toEqual(new Uint8Array([2, 2, 2, 2, 2, 3, 3, 3, 3, 3]))
+    })
+
+    test('flush clears registered authored sizes', () => {
+      const c = combiner()
+      c.registerAuthoredSize(undefined, 1, 9, 17, 5)
+      c.flush()
+      // A now-unregistered size means an offset-zero DU passes through
+      // immediately again (requireAuthoredSize is false here) rather than
+      // waiting on a size flush() already discarded.
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3, 4, 5], 1000n, true))?.data)
+        .toEqual(new Uint8Array([1, 2, 3, 4, 5]))
+    })
+
+    test('a healthy stream accumulates no bookkeeping', () => {
+      // Regression: retirement ran only on completion paths, so an
+      // abandoned sample's registered size stayed resident forever.
+      const c = combiner({ maxBuffered: 4, requireAuthoredSize: true })
+      for (let i = 0; i < 1000; i++) {
+        expect(c.registerAuthoredSize(undefined, 1, 9, i, 10)).toBeNull()
+        expect(c.addMfu(mfu(1, 9, i, 0, [1, 1, 1, 1, 1], 1000n, true))).toBeNull()
+        expect(c.addMfu(mfu(1, 9, i, 5, [2, 2, 2, 2, 2], 1001n, false))).not.toBeNull()
+      }
+      expect(c.stats.combinedSamples).toBe(1000)
+      expect(c.pendingCount).toBe(0)
+      expect(c.debugAuthoredSizeCount).toBe(0)
+      expect(c.debugRetiredCount).toBeLessThanOrEqual(4)
+    })
+
+    test('samples that never complete release their authored size', () => {
+      const c = combiner({ maxBuffered: 4, requireAuthoredSize: true })
+      for (let i = 0; i < 1000; i++) {
+        expect(c.registerAuthoredSize(undefined, 1, 9, i, 10)).toBeNull()
+        expect(c.addMfu(mfu(1, 9, i, 0, [1, 1, 1, 1, 1], 1000n, true))).toBeNull()
+        // Deliberately never supply the tail.
+      }
+      c.cleanupTimeouts(-1) // expire everything still held
+      expect(c.pendingCount).toBe(0)
+      expect(c.debugAuthoredSizeCount).toBe(0)
+    })
+
+    test('a late authored size completes an already-buffered sample', () => {
+      // Regression: with requireAuthoredSize the completion check ran only
+      // inside addMfu, so a sample carried by a SINGLE data unit whose FT=1
+      // arrived afterwards had no later data unit to re-enter on and was
+      // silently lost.
+      const c = combiner({ requireAuthoredSize: true })
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3, 4, 5], 1000n, true))).toBeNull()
+      expect(c.pendingCount).toBe(1)
+
+      const out = c.registerAuthoredSize(undefined, 1, 9, 17, 5)
+      expect(out?.data).toEqual(new Uint8Array([1, 2, 3, 4, 5]))
+      expect(out?.subsampleCount).toBe(1)
+      expect(c.pendingCount).toBe(0)
+    })
+
+    test('a rejected data unit does not evict a live sample', () => {
+      // Regression: the pending slot was allocated (evicting the oldest
+      // sample to make room) BEFORE validation, so a data unit the combiner
+      // went on to reject destroyed an unrelated in-flight sample.
+      const c = combiner({ maxBuffered: 2 })
+      for (const s of [17, 18, 19]) c.registerAuthoredSize(undefined, 1, 9, s, 10)
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 1, 1, 1, 1], 1000n, true))).toBeNull()
+      expect(c.addMfu(mfu(1, 9, 18, 0, [2, 2, 2, 2, 2], 1001n, true))).toBeNull()
+      expect(c.pendingCount).toBe(2)
+
+      // 8 + 5 = 13 exceeds sample 19's authored size of 10.
+      expect(() => c.addMfu(mfu(1, 9, 19, 8, [9, 9, 9, 9, 9], 2000n, false)))
+        .toThrow(SampleCombineError)
+      expect(c.stats.evictedSamples).toBe(0)
+      expect(c.pendingCount).toBe(2)
+
+      // Sample 17 is untouched and still completes.
+      expect(c.addMfu(mfu(1, 9, 17, 5, [3, 3, 3, 3, 3], 2001n, false))?.data)
+        .toEqual(new Uint8Array([1, 1, 1, 1, 1, 3, 3, 3, 3, 3]))
+    })
+
+    test('an evicted sample is retired rather than reopened', () => {
+      const c = combiner({ maxBuffered: 1 })
+      for (const s of [17, 18]) c.registerAuthoredSize(undefined, 1, 9, s, 10)
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 1, 1, 1, 1], 1000n, true))).toBeNull()
+      expect(c.addMfu(mfu(1, 9, 18, 0, [2, 2, 2, 2, 2], 1001n, true))).toBeNull()
+      expect(c.stats.evictedSamples).toBe(1)
+
+      // Sample 17's tail arrives after its eviction; it must not reopen.
+      expect(c.addMfu(mfu(1, 9, 17, 5, [3, 3, 3, 3, 3], 2000n, false))).toBeNull()
+      expect(c.pendingCount).toBe(1)
+    })
+  })
+
+  describe('sample-level delivery provenance', () => {
+    test('one non-multicast subsample makes the whole sample non-exclusive', () => {
+      // A 4K/8K sample is split across subsample DUs. If any one of them
+      // arrived over QUIC, the assembled sample contains bytes that never
+      // crossed a multicast socket, so the sample is not physical evidence
+      // even though every other DU was multicast.
+      const c = combiner()
+      c.registerAuthoredSize(undefined, 1, 1, 1, 4)
+      expect(c.addMfu(mfu(1, 1, 1, 0, [1, 2], 100n, true, 'multicast'))).toBeNull()
+      const done = c.addMfu(mfu(1, 1, 1, 2, [3, 4], 100n, false, 'mixed'))
+      expect(done).not.toBeNull()
+      expect(done!.subsampleCount).toBe(2)
+      expect(done!.deliveryProvenance).toBe('mixed')
+    })
+
+    test('an unattributed subsample degrades the sample to unknown', () => {
+      const c = combiner()
+      c.registerAuthoredSize(undefined, 2, 1, 1, 4)
+      expect(c.addMfu(mfu(2, 1, 1, 0, [1, 2], 100n, true, 'multicast'))).toBeNull()
+      const done = c.addMfu(mfu(2, 1, 1, 2, [3, 4], 100n, false, 'unknown'))
+      expect(done).not.toBeNull()
+      expect(done!.deliveryProvenance).toBe('unknown')
+    })
+
+    test('an all-multicast sample stays multicast-exclusive', () => {
+      const c = combiner()
+      c.registerAuthoredSize(undefined, 3, 1, 1, 4)
+      expect(c.addMfu(mfu(3, 1, 1, 0, [1, 2], 100n, true, 'multicast'))).toBeNull()
+      const done = c.addMfu(mfu(3, 1, 1, 2, [3, 4], 100n, false, 'multicast'))
+      expect(done).not.toBeNull()
+      expect(done!.deliveryProvenance).toBe('multicast')
+    })
+
+    test('a passthrough sample inherits its data unit provenance verbatim', () => {
+      const c = combiner()
+      const done = c.addMfu(mfu(4, 1, 1, 0, [1, 2], 100n, true, 'mixed'))
+      expect(done).not.toBeNull()
+      expect(done!.subsampleCount).toBe(1)
+      expect(done!.deliveryProvenance).toBe('mixed')
+    })
+  })
+}