@blockcast/mmt-container 0.1.0-main.149f78a4adae

package/src/mfu-reassembler.ts

@@ -0,0 +1,2842 @@
+/**
+ * @mmt/container - MFU Fragment Reassembler
+ *
+ * Handles authored fragmented MFUs (Media Fragment Units) according to
+ * ISO/IEC 23008-1:2023 Section 9.2.3.3. Fragmented runs are admitted in the
+ * exact FI/fragment_counter countdown carried on the wire. Transport-run
+ * association additionally requires the repository's contiguous-source
+ * producer profile; ISO-permitted interleaving remains incomplete and fails
+ * closed.
+ *
+ * Fragmentation Indicator (FI) values:
+ * - 0: Complete MFU (single packet, no fragmentation)
+ * - 1: First fragment
+ * - 2: Middle fragment
+ * - 3: Last fragment
+ *
+ * @packageDocumentation
+ */
+
+import {
+  extractMFUPayload,
+  isFecRepairPacket,
+} from '@blockcast/mmt-base'
+
+/** Source transport admitted by the MMTP router. */
+export type MmtpSourcePath = 'multicast' | 'moq'
+
+/**
+ * Strict whole-frame delivery provenance, folded over EVERY contributing
+ * fragment rather than the head fragment alone.
+ *
+ * This is deliberately NOT `source`. `source` answers a routing question —
+ * "is this the reliable-MoQ copy that must not confirm multicast takeover?" —
+ * and head-fragment-wins is the documented, deterministic answer to it.
+ * Provenance answers an evidence question: "did every byte of this frame
+ * physically arrive over multicast?" A frame with a multicast head and a
+ * QUIC-delivered tail is a legitimate routing win for `source: 'multicast'`
+ * and is emphatically NOT multicast-exclusive delivery.
+ *
+ *   - 'multicast' — every contributing fragment was explicitly multicast.
+ *     The ONLY value that may be counted as physical-delivery evidence.
+ *   - 'mixed'     — at least one contributing fragment arrived over MoQ.
+ *   - 'unknown'   — no fragment arrived over MoQ, but at least one carried no
+ *     attribution at all. Absence is preserved as its own state rather than
+ *     defaulted, so a consumer cannot mistake "never recorded" for "proven".
+ */
+export type MmtpDeliveryProvenance = 'multicast' | 'mixed' | 'unknown'
+
+/**
+ * Fold one fragment's `source` into a running provenance verdict.
+ *
+ * Fail-closed, order-independent and associative: 'mixed' absorbs everything,
+ * a missing attribution degrades 'multicast' to 'unknown', and nothing ever
+ * upgrades a verdict. Fold over an empty set is 'unknown' — no fragment ever
+ * proved anything.
+ */
+export function foldDeliveryProvenance(
+  verdict: MmtpDeliveryProvenance,
+  source: MmtpSourcePath | undefined,
+): MmtpDeliveryProvenance {
+  if (verdict === 'mixed') return 'mixed'
+  if (source === 'moq') return 'mixed'
+  if (source === undefined) return 'unknown'
+  return verdict
+}
+
+/**
+ * One fragment's own provenance.
+ *
+ * An explicit `deliveryProvenance` wins: FEC-recovered fragments carry no
+ * `source` (they were never delivered as themselves) but their block's symbol
+ * provenance IS known, and the router supplies it. Falling back to `source`
+ * keeps directly-delivered fragments working unchanged.
+ */
+function fragmentProvenance(fragment: {
+  source?: MmtpSourcePath
+  deliveryProvenance?: MmtpDeliveryProvenance
+}): MmtpDeliveryProvenance {
+  if (fragment.deliveryProvenance !== undefined) return fragment.deliveryProvenance
+  if (fragment.source === 'moq') return 'mixed'
+  if (fragment.source === 'multicast') return 'multicast'
+  return 'unknown'
+}
+
+/** Strict provenance for a complete fragment set. */
+export function deliveryProvenanceOf(
+  fragments: readonly {
+    source?: MmtpSourcePath
+    deliveryProvenance?: MmtpDeliveryProvenance
+  }[],
+): MmtpDeliveryProvenance {
+  if (fragments.length === 0) return 'unknown'
+  let verdict: MmtpDeliveryProvenance = 'multicast'
+  for (const fragment of fragments) {
+    const own = fragmentProvenance(fragment)
+    verdict =
+      verdict === 'mixed' || own === 'mixed'
+        ? 'mixed'
+        : verdict === 'unknown' || own === 'unknown'
+          ? 'unknown'
+          : 'multicast'
+  }
+  return verdict
+}
+
+/**
+ * MFU Fragment for reassembly
+ */
+export interface MFUFragment {
+  fragmentationIndicator: number
+  mpuSequenceNumber: number
+  fragmentCounter: number
+  data: Uint8Array
+  timestamp: bigint
+  /** Random Access Point flag from MMTP header - indicates keyframe */
+  rapFlag: boolean
+  /** MFU DU priority. FFmpeg marks random-access samples with high priority. */
+  priority?: number
+  sampleNumber?: number
+  movieFragmentSequenceNumber?: number
+  sampleOffset?: number
+  /** Non-timed MFU Item_ID from the 4-byte DU header. */
+  itemId?: number
+  /** Authored u32 MMTP packet_sequence_number, including on recovered packets. */
+  packetSequenceNumber?: number
+  /** True when this accepted source packet was reconstructed by FEC. */
+  recovered?: boolean
+  /** Transport that supplied this accepted fragment. Absent for recovered data. */
+  source?: MmtpSourcePath
+  /**
+   * Explicit provenance for this fragment, overriding what `source` implies.
+   * Set by the router for FEC-recovered fragments, which have no `source` of
+   * their own but whose FEC block's symbol provenance is known.
+   */
+  deliveryProvenance?: MmtpDeliveryProvenance
+  /** Immutable catalog identity supplied by the owning ingress subscription. */
+  catalogTrackName?: string
+  /** Physical MMTP stream identity when no catalog identity is available. */
+  packetId?: number
+}
+
+/**
+ * Reassembled MFU result
+ */
+export interface ReassembledMFU {
+  mpuSequenceNumber: number
+  /** MMTP packet_sequence_number of the first fragment in delivery order. */
+  packetSequenceNumber?: number
+  /** Every authoritative MMTP source-packet sequence that formed this MFU. */
+  packetSequenceNumbers?: number[]
+  /** Subset of packetSequenceNumbers reconstructed by FEC. */
+  repairedPacketSequenceNumbers?: number[]
+  data: Uint8Array
+  timestamp: bigint
+  fragmentCount: number
+  /** Random Access Point flag - indicates keyframe (from first fragment) */
+  rapFlag: boolean
+  /** MFU DU priority from the first fragment that carried it. */
+  priority?: number
+  sampleNumber?: number
+  movieFragmentSequenceNumber?: number
+  /**
+   * This DU's authored base byte offset within its sample (moqcast #37). 0
+   * for a whole-sample DU; nonzero identifies one subsample DU among
+   * siblings partitioning an oversized sample. Constant across the DU's own
+   * fragments — feed into a sample combiner to reassemble the full sample.
+   */
+  sampleOffset?: number
+  /**
+   * Transport that supplied the accepted FI=1 head fragment (or the complete
+   * FI=0 frame). This is the deterministic winner for mixed-path assembly.
+   *
+   * ROUTING ONLY. It describes one fragment, so it is not evidence about the
+   * whole frame — read {@link ReassembledMFU.deliveryProvenance} for that.
+   */
+  source?: MmtpSourcePath
+  /**
+   * Strict provenance folded over every contributing fragment. Only
+   * 'multicast' proves multicast-exclusive delivery of this frame.
+   */
+  deliveryProvenance: MmtpDeliveryProvenance
+  /** Catalog identity from the accepted FI=1 head fragment, or FI=0 frame. */
+  catalogTrackName?: string
+}
+
+/**
+ * Reassembler statistics
+ */
+export interface ReassemblerStats {
+  totalFragments: number
+  reassembledMFUs: number
+  /** Fragments rejected by strict authored DU-state validation. */
+  rejectedFragments: number
+  /** Incomplete MFUs discarded after their configured deadline. */
+  timedOutMFUs: number
+  /** Incomplete MFUs discarded to enforce the configured memory bound. */
+  evictedMemoryLimit: number
+  outOfOrderFragments: number
+}
+
+export const MFU_REASSEMBLY_ERROR_CODES = [
+  'invalid-fragment-state',
+  'missing-data-unit-identity',
+  'missing-packet-sequence',
+  'conflicting-data-unit-identity',
+  'overlapping-data-unit',
+  'fragment-counter-mismatch',
+  'data-unit-identity-mismatch',
+  'offset-overflow',
+  'active-data-unit-limit',
+  'incomplete-terminal-fragment',
+] as const
+
+export type MfuReassemblyErrorCode = typeof MFU_REASSEMBLY_ERROR_CODES[number]
+
+const mfuReassemblyErrorCodes = new Set<string>(MFU_REASSEMBLY_ERROR_CODES)
+
+export function isMfuReassemblyErrorCode(value: unknown): value is MfuReassemblyErrorCode {
+  return typeof value === 'string' && mfuReassemblyErrorCodes.has(value)
+}
+
+export class MfuReassemblyError extends Error {
+  readonly name = 'MfuReassemblyError'
+
+  constructor(readonly code: MfuReassemblyErrorCode, message: string) {
+    super(message)
+  }
+}
+
+function assembledPacketSequences(fragments: readonly MFUFragment[]): {
+  packetSequenceNumbers?: number[]
+  repairedPacketSequenceNumbers?: number[]
+} {
+  const packetSequenceNumbers: number[] = []
+  const repairedPacketSequenceNumbers: number[] = []
+  const seen = new Set<number>()
+  const repaired = new Set<number>()
+  for (const fragment of fragments) {
+    const sequence = fragment.packetSequenceNumber
+    if (typeof sequence !== 'number' || !Number.isSafeInteger(sequence) ||
+        sequence < 0 || sequence > 0xffffffff) {
+      return {}
+    }
+    if (!seen.has(sequence)) {
+      seen.add(sequence)
+      packetSequenceNumbers.push(sequence)
+    }
+    if (fragment.recovered === true && !repaired.has(sequence)) {
+      repaired.add(sequence)
+      repairedPacketSequenceNumbers.push(sequence)
+    }
+  }
+  return {packetSequenceNumbers, repairedPacketSequenceNumbers}
+}
+
+export interface PendingMfuDebug {
+  key: string
+  fragments: number
+  fi0: number
+  fi1: number
+  fi2: number
+  fi3: number
+  firstFi: number
+  lastFi: number
+  firstOrder: number
+  lastOrder: number
+  minCounter: number
+  maxCounter: number
+  minOffset?: number
+  maxOffset?: number
+  movieFragmentSequenceNumber?: number
+  sampleNumber?: number
+  mpuSequenceNumber?: number
+  sortedHead: Array<{ fi: number; counter: number; order: number; seq?: number; offset?: number }>
+  sortedTail: Array<{ fi: number; counter: number; order: number; seq?: number; offset?: number }>
+}
+
+export interface MFUReassemblerOptions {
+  /** Timeout (ms) for incomplete MFUs. Derive from frame duration or FEC interleaveDepthMs.
+   *  Pass null for live clock-free operation; memory remains bounded by maxBuffered. */
+  timeoutMs: number | null
+  /** Max concurrent incomplete MFUs, including continuations awaiting FI=1. */
+  maxBuffered?: number
+}
+
+/** Reassembly surface consumed by MmtpContainerParser and MmtpRouter.
+ * Implemented by both the TypeScript engine and the shared
+ * Rust/WASM IFC adapter. */
+export interface MfuReassemblerBackend {
+  timeoutMs: number | null
+  readonly stats: ReassemblerStats
+  onDeferredAssembly?: (result: ReassembledMFU) => void
+  /** Returns null only for a valid incomplete DU; strict rejection throws
+   * `MfuReassemblyError`. */
+  addFragment(fragment: MFUFragment): ReassembledMFU | null
+  flush(): void
+  resetStream(catalogTrackName: string): void
+  reset(): void
+  readonly pendingCount: number
+  getStatus(): {
+    bufferedMFUs: number
+    pendingFragments: number
+    pendingSamples: PendingMfuDebug[]
+    stats: ReassemblerStats
+  }
+}
+
+function streamScope(fragment: MFUFragment): readonly [kind: string, identity: string | number | null] {
+  if (fragment.catalogTrackName !== undefined) return ['catalog', fragment.catalogTrackName]
+  if (fragment.packetId !== undefined) return ['packet', fragment.packetId]
+  return ['unspecified', null]
+}
+
+function isU32(value: unknown): value is number {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= 0xffffffff
+}
+
+/**
+ * Producer-profile transport coordinate shared by every contiguous source
+ * fragment in one data-unit run. This is association state only; objectKey
+ * remains the intrinsic DU identity. ISO-permitted interleaving creates a
+ * different key and therefore cannot cross-associate samples.
+ */
+function fragmentRunKey(fragment: MFUFragment): string {
+  if (!isU32(fragment.packetSequenceNumber)) {
+    throw new Error('[MFUReassembler] fragmented value has no validated packet sequence')
+  }
+  const terminalPacketSequence =
+    (fragment.packetSequenceNumber + fragment.fragmentCounter) % 0x1_0000_0000
+  return JSON.stringify([
+    ...streamScope(fragment),
+    fragment.mpuSequenceNumber,
+    terminalPacketSequence,
+  ])
+}
+
+function hasAnySampleIdentityField(fragment: MFUFragment): boolean {
+  return fragment.movieFragmentSequenceNumber !== undefined ||
+    fragment.sampleNumber !== undefined || fragment.sampleOffset !== undefined
+}
+
+type IdentifiedSampleFragment = MFUFragment & Required<Pick<
+  MFUFragment,
+  'movieFragmentSequenceNumber' | 'sampleNumber' | 'sampleOffset'
+>>
+
+function hasSampleIdentity(fragment: MFUFragment): fragment is IdentifiedSampleFragment {
+  return isU32(fragment.movieFragmentSequenceNumber) && fragment.movieFragmentSequenceNumber > 0 &&
+    isU32(fragment.sampleNumber) && fragment.sampleNumber > 0 && isU32(fragment.sampleOffset)
+}
+
+function hasValidFragmentHeader(fragment: MFUFragment): boolean {
+  const { fragmentationIndicator: fi, fragmentCounter: counter } = fragment
+  if (!Number.isInteger(fi) || fi < 0 || fi > 3) return false
+  if (!Number.isInteger(counter) || counter < 0 || counter > 0xff) return false
+  return fi === 0 || fi === 3 ? counter === 0 : counter > 0
+}
+
+function fragmentCounterOrder(fragment: MFUFragment): number {
+  return 0xff - fragment.fragmentCounter
+}
+
+function objectKey(fragment: MFUFragment): string {
+  const scope = streamScope(fragment)
+  if (fragment.itemId !== undefined) {
+    return JSON.stringify([
+      ...scope,
+      fragment.mpuSequenceNumber,
+      'item',
+      fragment.itemId,
+    ])
+  }
+  if (hasSampleIdentity(fragment)) {
+    return JSON.stringify([
+      ...scope,
+      fragment.mpuSequenceNumber,
+      'sample',
+      fragment.movieFragmentSequenceNumber,
+      fragment.sampleNumber,
+      // The DU's authored base offset (moqcast #37): sibling subsample DUs
+      // of one sample get distinct keys instead of colliding. Only ever
+      // called with the unmutated FI=1 (or FI=0) fragment, whose
+      // sampleOffset is that authored base -- never the accumulating
+      // per-continuation value written by #associateDataUnit.
+      fragment.sampleOffset,
+    ])
+  }
+  return JSON.stringify([
+    ...scope,
+    fragment.mpuSequenceNumber,
+    'unidentified',
+  ])
+}
+
+function ordersByOffset(fragments: MFUFragment[]): boolean {
+  return fragments.every((fragment) => hasSampleIdentity(fragment))
+}
+
+type ActiveDataUnit = {
+  bufferKey: string
+  nextFragmentCounter: number
+  catalogTrackName?: string
+} & (
+  | {
+      kind: 'sample'
+      movieFragmentSequenceNumber: number
+      sampleNumber: number
+      nextOffset: number
+    }
+  | {
+      kind: 'item'
+      itemId: number
+    }
+)
+
+interface DataUnitAssociation {
+  bufferKey: string
+  first: boolean
+  terminal: boolean
+}
+
+interface PendingContinuationRun {
+  fragments: Map<number, MFUFragment>
+  startedAt: number
+  timeoutId?: ReturnType<typeof setTimeout>
+}
+
+interface BufferTimeoutState {
+  startedAt: number
+  timeoutId?: ReturnType<typeof setTimeout>
+}
+
+function checkedSampleEnd(offset: number, byteLength: number): number | null {
+  const end = offset + byteLength
+  return Number.isSafeInteger(end) && end <= 0xffffffff ? end : null
+}
+
+/**
+ * MFU Reassembler with bounded reordered-fragment association
+ * Based on ISO/IEC 23008-1:2023 Section 9.2.3.3
+ */
+export class MFUReassembler {
+  // Fragment buffers use only the authored MFU DU identity. Continuations are
+  // admitted through bounded producer-profile runs keyed by physical stream,
+  // MPU, and the wrapping terminal packet sequence. This requires contiguous
+  // source-packet sequences within a fragmented DU; interleaving stays
+  // separated and incomplete. Continuations may wait in a counter-indexed queue
+  // until FI=1 supplies intrinsic identity; MMTP packet send time is never an
+  // association key.
+  #buffers: Map<string, MFUFragment[]> = new Map()
+  #timeouts: Map<string, BufferTimeoutState> = new Map()
+  #activeDataUnits: Map<string, ActiveDataUnit> = new Map()
+  #pendingContinuations: Map<string, PendingContinuationRun> = new Map()
+  #emitted: Set<string> = new Set() // same sample keys — reject FEC-recovered duplicates
+  #emittedOrder: string[] = []
+  #timeoutMs: number | null
+  #maxBuffered: number
+
+  /** Statistics for debugging */
+  readonly stats: ReassemblerStats = {
+    totalFragments: 0,
+    reassembledMFUs: 0,
+    rejectedFragments: 0,
+    timedOutMFUs: 0,
+    evictedMemoryLimit: 0,
+    outOfOrderFragments: 0,
+  }
+
+  constructor(options: MFUReassemblerOptions) {
+    if (options.timeoutMs !== null && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0)) {
+      throw new Error('[MFUReassembler] timeoutMs must be > 0 (derive from frame duration or FEC config)')
+    }
+    const maxBuffered = options.maxBuffered ?? 100
+    if (!Number.isInteger(maxBuffered) || maxBuffered <= 0) {
+      throw new Error('[MFUReassembler] maxBuffered must be a positive integer')
+    }
+    this.#timeoutMs = options.timeoutMs
+    this.#maxBuffered = maxBuffered
+  }
+
+  /** Update the expiry policy for all retained and future incomplete MFUs. */
+  set timeoutMs(ms: number | null) {
+    if (ms !== null && (!Number.isFinite(ms) || ms <= 0)) {
+      throw new Error('[MFUReassembler] timeoutMs must be > 0 (derive from frame duration or FEC config)')
+    }
+    this.#timeoutMs = ms
+    const now = Date.now()
+    for (const [bufferKey, state] of this.#timeouts) {
+      if (state.timeoutId !== undefined) clearTimeout(state.timeoutId)
+      delete state.timeoutId
+      if (ms !== null) {
+        state.timeoutId = setTimeout(
+          () => this.#onTimeout(bufferKey),
+          Math.max(0, state.startedAt + ms - now),
+        )
+      }
+    }
+    for (const [runKey, pending] of this.#pendingContinuations) {
+      if (pending.timeoutId !== undefined) clearTimeout(pending.timeoutId)
+      delete pending.timeoutId
+      if (ms !== null && !this.#activeDataUnits.has(runKey)) {
+        pending.timeoutId = setTimeout(
+          () => this.#onPendingTimeout(runKey),
+          Math.max(0, pending.startedAt + ms - now),
+        )
+      }
+    }
+  }
+  get timeoutMs(): number | null { return this.#timeoutMs }
+
+  /**
+   * Add a fragment and return reassembled MFU if complete
+   */
+  addFragment(fragment: MFUFragment): ReassembledMFU | null {
+    this.stats.totalFragments++
+
+    if (!hasValidFragmentHeader(fragment)) {
+      this.#reject('invalid-fragment-state', 'invalid MFU fragmentation indicator or counter')
+    }
+    if (fragment.itemId !== undefined && hasAnySampleIdentityField(fragment)) {
+      this.#reject(
+        'conflicting-data-unit-identity',
+        'MFU carries timed and non-timed DU identities',
+      )
+    }
+
+    const { mpuSequenceNumber, fragmentationIndicator } = fragment
+
+    // A complete FT=2 data unit still requires its intrinsic DU identity.
+    // The transport parser strips the deterministic timed/non-timed DU header
+    // before calling this layer; direct callers must provide the same identity.
+    // Don't check or update #emitted: in MMTP over MoQ, multiple complete MFUs
+    // share the same mpuSequenceNumber (all frames in a GOP have the same mpuSeq).
+    // Blocking FI=0 would prevent keyframe fragment assembly at the same mpuSeq.
+    if (fragmentationIndicator === 0) {
+      const sampleIdentity = hasSampleIdentity(fragment)
+      const hasSampleFields = hasAnySampleIdentityField(fragment)
+      const hasItemIdentity = fragment.itemId !== undefined
+      if (!sampleIdentity && !hasItemIdentity) {
+        this.#reject('missing-data-unit-identity', 'complete MFU has no intrinsic DU identity')
+      }
+      if (hasSampleFields && !sampleIdentity) {
+        this.#reject('missing-data-unit-identity', 'complete MFU has an incomplete sample identity')
+      }
+      if (hasItemIdentity && !isU32(fragment.itemId)) {
+        this.#reject('missing-data-unit-identity', 'complete MFU has an invalid Item_ID')
+      }
+      this.stats.reassembledMFUs++
+      return {
+        mpuSequenceNumber,
+        packetSequenceNumber: fragment.packetSequenceNumber,
+        ...assembledPacketSequences([fragment]),
+        data: fragment.data,
+        timestamp: fragment.timestamp,
+        fragmentCount: 1,
+        rapFlag: fragment.rapFlag,
+        priority: fragment.priority,
+        sampleNumber: fragment.sampleNumber,
+        movieFragmentSequenceNumber: fragment.movieFragmentSequenceNumber,
+        sampleOffset: fragment.sampleOffset,
+        source: fragment.source,
+        deliveryProvenance: deliveryProvenanceOf([fragment]),
+        catalogTrackName: fragment.catalogTrackName,
+      }
+    }
+
+    if (!isU32(fragment.packetSequenceNumber)) {
+      this.#reject(
+        'missing-packet-sequence',
+        'fragmented MFU has no MMTP packet sequence number',
+      )
+    }
+    const runKey = fragmentRunKey(fragment)
+    if (
+      fragmentationIndicator === 1 &&
+      (hasSampleIdentity(fragment) || isU32(fragment.itemId)) &&
+      this.#emitted.has(objectKey(fragment))
+    ) {
+      this.#deletePendingRun(runKey)
+      return null
+    }
+
+    if (fragmentationIndicator !== 1) {
+      const active = this.#activeDataUnits.get(runKey)
+      if (active !== undefined && fragment.fragmentCounter > active.nextFragmentCounter) {
+        this.#reject(
+          'fragment-counter-mismatch',
+          'MFU continuation is behind the authored fragment-counter countdown',
+        )
+      }
+      if (active === undefined || fragment.fragmentCounter < active.nextFragmentCounter) {
+        this.#parkContinuation(runKey, fragment)
+        return null
+      }
+    } else if (this.#activeDataUnits.has(runKey)) {
+      this.#reject('overlapping-data-unit', 'fragmented MFU overlaps an active data unit')
+    } else {
+      const pending = this.#pendingContinuations.get(runKey)
+      if (pending !== undefined && [...pending.fragments.keys()].some(
+        counter => counter >= fragment.fragmentCounter,
+      )) {
+        this.#reject(
+          'fragment-counter-mismatch',
+          'queued continuation counter is not below the authored first-fragment counter',
+        )
+      }
+    }
+
+    const pendingStartedAt = fragmentationIndicator === 1
+      ? this.#pendingContinuations.get(runKey)?.startedAt
+      : undefined
+    const result = this.#addAssociatedFragment(fragment, runKey, pendingStartedAt)
+    if (fragmentationIndicator === 1) this.#clearPendingTimeout(runKey)
+    if (result !== null) return result
+    return this.#drainPendingContinuations(runKey)
+  }
+
+  #addAssociatedFragment(
+    fragment: MFUFragment,
+    runKey: string,
+    startedAt?: number,
+  ): ReassembledMFU | null {
+    const association = this.#associateDataUnit(fragment, runKey)
+    const { bufferKey, first, terminal } = association
+
+    let fragments = this.#buffers.get(bufferKey)
+    if (first) {
+      if (fragments !== undefined) {
+        this.#reject('overlapping-data-unit', 'intrinsic data-unit buffer already exists')
+      }
+      fragments = []
+      this.#buffers.set(bufferKey, fragments)
+    } else if (fragments === undefined) {
+      throw new Error('[MFUReassembler] active data unit has no fragment buffer')
+    }
+
+    // A lossy-path deadline is measured from the first received fragment,
+    // including a continuation that arrived before FI=1. Reliable paths are
+    // clock-free and never install this timer.
+    if (first) this.#setTimeout(bufferKey, startedAt)
+    fragments.push(fragment)
+
+    if (!terminal) return null
+    const result = this.#tryReassemble(bufferKey)
+    this.#activeDataUnits.delete(runKey)
+    if (result === null) {
+      this.#clearTimeout(bufferKey)
+      this.#buffers.delete(bufferKey)
+      this.#reject(
+        'incomplete-terminal-fragment',
+        'validated terminal fragment did not complete its data unit',
+      )
+    }
+    return result
+  }
+
+  #parkContinuation(runKey: string, fragment: MFUFragment): void {
+    let pending = this.#pendingContinuations.get(runKey)
+    if (pending === undefined) {
+      const awaitingFirst = !this.#activeDataUnits.has(runKey)
+      if (awaitingFirst && this.#incompleteRunCount() >= this.#maxBuffered) {
+        this.#reject('active-data-unit-limit', 'active MFU data-unit limit reached')
+      }
+      const startedAt = Date.now()
+      pending = { fragments: new Map(), startedAt }
+      if (awaitingFirst && this.#timeoutMs !== null) {
+        pending.timeoutId = setTimeout(() => this.#onPendingTimeout(runKey), this.#timeoutMs)
+      }
+      this.#pendingContinuations.set(runKey, pending)
+    }
+    if (pending.fragments.has(fragment.fragmentCounter)) {
+      this.#reject(
+        'fragment-counter-mismatch',
+        'duplicate queued continuation counter would replace retained media',
+      )
+    }
+    pending.fragments.set(fragment.fragmentCounter, fragment)
+  }
+
+  #drainPendingContinuations(runKey: string): ReassembledMFU | null {
+    while (true) {
+      const active = this.#activeDataUnits.get(runKey)
+      if (active === undefined) {
+        this.#deletePendingRun(runKey)
+        return null
+      }
+      const pending = this.#pendingContinuations.get(runKey)
+      const fragment = pending?.fragments.get(active.nextFragmentCounter)
+      if (fragment === undefined) return null
+      pending!.fragments.delete(active.nextFragmentCounter)
+      if (pending!.fragments.size === 0) this.#deletePendingRun(runKey)
+      const result = this.#addAssociatedFragment(fragment, runKey)
+      if (result !== null) {
+        this.#deletePendingRun(runKey)
+        return result
+      }
+    }
+  }
+
+  #incompleteRunCount(): number {
+    let count = this.#activeDataUnits.size
+    for (const runKey of this.#pendingContinuations.keys()) {
+      if (!this.#activeDataUnits.has(runKey)) count++
+    }
+    return count
+  }
+
+  #reject(code: MfuReassemblyErrorCode, message: string): never {
+    this.stats.rejectedFragments++
+    throw new MfuReassemblyError(code, message)
+  }
+
+  #associateDataUnit(fragment: MFUFragment, runKey: string): DataUnitAssociation {
+    const fi = fragment.fragmentationIndicator
+    if (fi === 1) {
+      if (this.#activeDataUnits.has(runKey)) {
+        this.#reject('overlapping-data-unit', 'fragmented MFU overlaps an active data unit')
+      }
+      if (!this.#pendingContinuations.has(runKey) &&
+          this.#incompleteRunCount() >= this.#maxBuffered) {
+        this.#reject('active-data-unit-limit', 'active MFU data-unit limit reached')
+      }
+
+      const sampleIdentity = hasSampleIdentity(fragment)
+      const hasSampleFields = hasAnySampleIdentityField(fragment)
+      const hasItemIdentity = fragment.itemId !== undefined
+      if (sampleIdentity && hasItemIdentity) {
+        this.#reject(
+          'conflicting-data-unit-identity',
+          'fragmented MFU carries timed and non-timed DU identities',
+        )
+      }
+      if (!sampleIdentity && !hasItemIdentity) {
+        this.#reject('missing-data-unit-identity', 'first fragment has no intrinsic DU identity')
+      }
+      if (hasSampleFields && !sampleIdentity) {
+        this.#reject('missing-data-unit-identity', 'first fragment has an incomplete sample identity')
+      }
+      if (hasItemIdentity && !isU32(fragment.itemId)) {
+        this.#reject('missing-data-unit-identity', 'first fragment has an invalid Item_ID')
+      }
+
+      const bufferKey = objectKey(fragment)
+      if (this.#buffers.has(bufferKey)) {
+        this.#reject('overlapping-data-unit', 'intrinsic data-unit buffer already exists')
+      }
+
+      let active: ActiveDataUnit
+      if (sampleIdentity) {
+        const nextOffset = checkedSampleEnd(fragment.sampleOffset, fragment.data.byteLength)
+        if (nextOffset === null) this.#reject('offset-overflow', 'sample byte offset overflow')
+        active = {
+          kind: 'sample',
+          bufferKey,
+          nextFragmentCounter: fragment.fragmentCounter - 1,
+          movieFragmentSequenceNumber: fragment.movieFragmentSequenceNumber,
+          sampleNumber: fragment.sampleNumber,
+          nextOffset,
+          ...(fragment.catalogTrackName === undefined
+            ? {}
+            : { catalogTrackName: fragment.catalogTrackName }),
+        }
+      } else {
+        active = {
+          kind: 'item',
+          bufferKey,
+          nextFragmentCounter: fragment.fragmentCounter - 1,
+          itemId: fragment.itemId!,
+          ...(fragment.catalogTrackName === undefined
+            ? {}
+            : { catalogTrackName: fragment.catalogTrackName }),
+        }
+      }
+      this.#activeDataUnits.set(runKey, active)
+      return { bufferKey, first: true, terminal: false }
+    }
+
+    const active = this.#activeDataUnits.get(runKey)
+    if (active === undefined) {
+      throw new Error('[MFUReassembler] continuation was not parked before association')
+    }
+    if (fragment.fragmentCounter !== active.nextFragmentCounter) {
+      this.#reject(
+        'fragment-counter-mismatch',
+        'MFU continuation does not follow the authored fragment-counter countdown',
+      )
+    }
+
+    if (active.kind === 'sample') {
+      if (fragment.itemId !== undefined) {
+        this.#reject('data-unit-identity-mismatch', 'sample continuation carries an Item_ID')
+      }
+      if (hasAnySampleIdentityField(fragment) && (
+        !hasSampleIdentity(fragment) ||
+        fragment.movieFragmentSequenceNumber !== active.movieFragmentSequenceNumber ||
+        fragment.sampleNumber !== active.sampleNumber || fragment.sampleOffset !== active.nextOffset
+      )) {
+        this.#reject('data-unit-identity-mismatch', 'sample continuation identity does not match')
+      }
+      const nextOffset = checkedSampleEnd(active.nextOffset, fragment.data.byteLength)
+      if (nextOffset === null) this.#reject('offset-overflow', 'sample byte offset overflow')
+      fragment.movieFragmentSequenceNumber = active.movieFragmentSequenceNumber
+      fragment.sampleNumber = active.sampleNumber
+      fragment.sampleOffset = active.nextOffset
+      if (fi === 2) {
+        active.nextOffset = nextOffset
+        active.nextFragmentCounter = fragment.fragmentCounter - 1
+      }
+    } else {
+      if (hasAnySampleIdentityField(fragment) ||
+          (fragment.itemId !== undefined && fragment.itemId !== active.itemId)) {
+        this.#reject('data-unit-identity-mismatch', 'Item_ID continuation identity does not match')
+      }
+      fragment.itemId = active.itemId
+      if (fi === 2) active.nextFragmentCounter = fragment.fragmentCounter - 1
+    }
+
+    return {
+      bufferKey: active.bufferKey,
+      first: false,
+      terminal: fi === 3,
+    }
+  }
+
+  #tryReassemble(bufferKey: string): ReassembledMFU | null {
+    const fragments = this.#buffers.get(bufferKey)
+    if (!fragments || fragments.length === 0) {
+      return null
+    }
+
+    const sorted = [...fragments].sort((a, b) => this.#orderValue(a) - this.#orderValue(b))
+
+    if (
+      sorted[0]!.fragmentationIndicator !== 1 ||
+      sorted[sorted.length - 1]!.fragmentationIndicator !== 3
+    ) {
+      return null
+    }
+    if (sorted.slice(1, -1).some((fragment) => fragment.fragmentationIndicator !== 2)) {
+      return null
+    }
+
+    // ISO fragment_counter is the number of succeeding payloads. After
+    // normalization (`255 - counter`), a complete non-wrapping chain is strictly
+    // consecutive. This also caps a data unit at 256 payloads.
+    for (let i = 1; i < sorted.length; i++) {
+      if (this.#orderValue(sorted[i]!) !== this.#orderValue(sorted[i - 1]!) + 1) {
+        return null
+      }
+    }
+
+    // When every fragment carries a timed-MFU byte offset, independently prove
+    // byte adjacency within this data unit. Counter order remains authoritative;
+    // conflicting offsets fail closed instead of changing the fragment order.
+    // sorted[0]'s offset is this DU's authored base (moqcast #37: zero for a
+    // whole-sample DU, nonzero for one subsample DU of a partitioned sample) --
+    // never asserted against a literal zero.
+    if (ordersByOffset(sorted)) {
+      for (let i = 1; i < sorted.length; i++) {
+        const previous = sorted[i - 1]!
+        if (
+          sorted[i]!.sampleOffset !==
+          previous.sampleOffset! + previous.data.byteLength
+        ) {
+          return null
+        }
+      }
+    }
+
+    fragments.splice(0, fragments.length, ...sorted)
+    return this.#assemble(bufferKey, fragments)
+  }
+
+  #assemble(bufferKey: string, fragments: MFUFragment[]): ReassembledMFU {
+    // Reassemble: concatenate all fragment data
+    const totalSize = fragments.reduce((sum, f) => sum + f.data.length, 0)
+    const data = new Uint8Array(totalSize)
+
+    let offset = 0
+    for (const fragment of fragments) {
+      data.set(fragment.data, offset)
+      offset += fragment.data.length
+    }
+
+    // Cleanup + mark the intrinsic identity as emitted to prevent a recovered
+    // duplicate from starting another fragmented run.
+    this.#clearTimeout(bufferKey)
+    this.#buffers.delete(bufferKey)
+    this.#markEmitted(bufferKey)
+    this.stats.reassembledMFUs++
+
+    return {
+      mpuSequenceNumber: fragments[0]!.mpuSequenceNumber,
+      packetSequenceNumber: fragments[0]!.packetSequenceNumber,
+      ...assembledPacketSequences(fragments),
+      data,
+      timestamp: fragments[0]!.timestamp,
+      fragmentCount: fragments.length,
+      rapFlag: fragments[0]!.rapFlag,
+      priority: fragments.find((f) => f.priority !== undefined)?.priority,
+      sampleNumber: fragments[0]!.sampleNumber,
+      movieFragmentSequenceNumber: fragments[0]!.movieFragmentSequenceNumber,
+      sampleOffset: fragments[0]!.sampleOffset,
+      source: fragments[0]!.source,
+      deliveryProvenance: deliveryProvenanceOf(fragments),
+      catalogTrackName: fragments[0]!.catalogTrackName,
+    }
+  }
+
+  #setTimeout(bufferKey: string, startedAt = Date.now()): void {
+    const state: BufferTimeoutState = { startedAt }
+    if (this.#timeoutMs !== null) {
+      state.timeoutId = setTimeout(
+        () => this.#onTimeout(bufferKey),
+        Math.max(0, startedAt + this.#timeoutMs - Date.now()),
+      )
+    }
+    this.#timeouts.set(bufferKey, state)
+  }
+
+  #clearPendingTimeout(runKey: string): void {
+    const pending = this.#pendingContinuations.get(runKey)
+    if (pending?.timeoutId !== undefined) clearTimeout(pending.timeoutId)
+    if (pending !== undefined) {
+      delete pending.timeoutId
+    }
+  }
+
+  #deletePendingRun(runKey: string): void {
+    this.#clearPendingTimeout(runKey)
+    this.#pendingContinuations.delete(runKey)
+  }
+
+  #onPendingTimeout(runKey: string): void {
+    const pending = this.#pendingContinuations.get(runKey)
+    if (pending === undefined) return
+    this.stats.timedOutMFUs++
+    console.warn(
+      `[MfuReassembler] timeout: run=${runKey} fragments=${pending.fragments.size} ` +
+      '(continuations awaiting first fragment, discarded)',
+    )
+    this.#pendingContinuations.delete(runKey)
+  }
+
+  #clearTimeout(bufferKey: string): void {
+    const state = this.#timeouts.get(bufferKey)
+    if (state !== undefined) {
+      if (state.timeoutId !== undefined) clearTimeout(state.timeoutId)
+      this.#timeouts.delete(bufferKey)
+    }
+  }
+
+  /** Callback for deferred assembly results (set by caller for async frame delivery) */
+  onDeferredAssembly?: (result: ReassembledMFU) => void
+
+  #markEmitted(bufferKey: string): void {
+    if (this.#emitted.has(bufferKey)) return
+    this.#emitted.add(bufferKey)
+    this.#emittedOrder.push(bufferKey)
+    while (this.#emittedOrder.length > this.#maxBuffered) {
+      const oldest = this.#emittedOrder.shift()
+      if (oldest !== undefined) this.#emitted.delete(oldest)
+    }
+  }
+
+  #orderValue(fragment: MFUFragment): number {
+    return fragmentCounterOrder(fragment)
+  }
+
+  #removeActiveDataUnitForBuffer(bufferKey: string): void {
+    for (const [runKey, active] of this.#activeDataUnits) {
+      if (active.bufferKey === bufferKey) {
+        this.#activeDataUnits.delete(runKey)
+        this.#deletePendingRun(runKey)
+      }
+    }
+  }
+
+  #onTimeout(bufferKey: string): void {
+    const fragments = this.#buffers.get(bufferKey)
+    if (!fragments || fragments.length === 0) {
+      this.#buffers.delete(bufferKey)
+      this.#timeouts.delete(bufferKey)
+      this.#removeActiveDataUnitForBuffer(bufferKey)
+      this.stats.timedOutMFUs++
+      console.warn(`[MfuReassembler] timeout: key=${bufferKey} fragments=0 (no data buffered)`)
+      return
+    }
+
+    // Discard partial MFUs — incomplete AVCC data crashes WebCodecs with
+    // "Unable to determine size of bitstream buffer".  FEC recovery handles
+    // loss; partial assembly only produces garbage frames.
+    this.stats.timedOutMFUs++
+    console.warn(
+      `[MfuReassembler] timeout: key=${bufferKey} fragments=${fragments.length} (partial, discarded)`,
+    )
+
+    this.#buffers.delete(bufferKey)
+    this.#timeouts.delete(bufferKey)
+    this.#removeActiveDataUnitForBuffer(bufferKey)
+  }
+
+  /**
+   * Flush all buffered fragments
+   */
+  flush(): void {
+    for (const key of this.#buffers.keys()) {
+      this.#clearTimeout(key)
+    }
+    this.#buffers.clear()
+    this.#timeouts.clear()
+    this.#activeDataUnits.clear()
+    for (const runKey of this.#pendingContinuations.keys()) {
+      this.#clearPendingTimeout(runKey)
+    }
+    this.#pendingContinuations.clear()
+    this.#emitted.clear()
+    this.#emittedOrder.length = 0
+  }
+
+  /** Drop one catalog stream's incomplete and dedup state. */
+  resetStream(catalogTrackName: string): void {
+    const belongsToStream = (key: string): boolean => {
+      try {
+        const decoded = JSON.parse(key)
+        return Array.isArray(decoded) && decoded[0] === 'catalog' && decoded[1] === catalogTrackName
+      } catch {
+        return false
+      }
+    }
+    const discarded = new Set<string>()
+    for (const [key, fragments] of this.#buffers) {
+      if (fragments.some((fragment) => fragment.catalogTrackName === catalogTrackName)) {
+        discarded.add(key)
+      }
+    }
+    for (const [runKey, active] of this.#activeDataUnits) {
+      if (active.catalogTrackName === catalogTrackName) {
+        discarded.add(active.bufferKey)
+        this.#activeDataUnits.delete(runKey)
+      }
+    }
+    for (const [runKey, pending] of this.#pendingContinuations) {
+      if ([...pending.fragments.values()].some(
+        fragment => fragment.catalogTrackName === catalogTrackName,
+      )) {
+        this.#deletePendingRun(runKey)
+      }
+    }
+    for (const key of this.#emitted) {
+      if (belongsToStream(key)) discarded.add(key)
+    }
+    for (const key of discarded) {
+      this.#clearTimeout(key)
+      this.#buffers.delete(key)
+      this.#emitted.delete(key)
+    }
+    this.#emittedOrder = this.#emittedOrder.filter((key) => !discarded.has(key))
+  }
+
+  /** Reset all state — flush buffers and zero stats */
+  reset(): void {
+    this.flush()
+    this.stats.totalFragments = 0
+    this.stats.reassembledMFUs = 0
+    this.stats.rejectedFragments = 0
+    this.stats.timedOutMFUs = 0
+    this.stats.evictedMemoryLimit = 0
+    this.stats.outOfOrderFragments = 0
+  }
+
+  /**
+   * Get number of pending MFUs
+   */
+  get pendingCount(): number {
+    let count = this.#buffers.size
+    for (const runKey of this.#pendingContinuations.keys()) {
+      if (!this.#activeDataUnits.has(runKey)) count++
+    }
+    return count
+  }
+
+  /**
+   * Get current buffer status
+   */
+  getStatus(): {
+    bufferedMFUs: number
+    pendingFragments: number
+    pendingSamples: PendingMfuDebug[]
+    stats: ReassemblerStats
+  } {
+    let pendingFragments = 0
+    for (const fragments of this.#buffers.values()) {
+      pendingFragments += fragments.length
+    }
+    for (const pending of this.#pendingContinuations.values()) {
+      pendingFragments += pending.fragments.size
+    }
+
+    return {
+      bufferedMFUs: this.pendingCount,
+      pendingFragments,
+      pendingSamples: this.#pendingDebugSamples(),
+      stats: { ...this.stats },
+    }
+  }
+
+  #pendingDebugSamples(): PendingMfuDebug[] {
+    const out: PendingMfuDebug[] = []
+    for (const [key, fragments] of this.#buffers) {
+      if (fragments.length === 0) continue
+      const sorted = [...fragments].sort((a, b) => this.#orderValue(a) - this.#orderValue(b))
+      const fiCounts = [0, 0, 0, 0]
+      let minCounter = Infinity
+      let maxCounter = -Infinity
+      let minOffset = Infinity
+      let maxOffset = -Infinity
+      for (const fragment of sorted) {
+        fiCounts[fragment.fragmentationIndicator] =
+          (fiCounts[fragment.fragmentationIndicator] ?? 0) + 1
+        minCounter = Math.min(minCounter, fragment.fragmentCounter)
+        maxCounter = Math.max(maxCounter, fragment.fragmentCounter)
+        if (typeof fragment.sampleOffset === 'number') {
+          minOffset = Math.min(minOffset, fragment.sampleOffset)
+          maxOffset = Math.max(maxOffset, fragment.sampleOffset)
+        }
+      }
+      const point = (fragment: MFUFragment) => ({
+        fi: fragment.fragmentationIndicator,
+        counter: fragment.fragmentCounter,
+        order: this.#orderValue(fragment),
+        ...(typeof fragment.packetSequenceNumber === 'number' ? { seq: fragment.packetSequenceNumber } : {}),
+        ...(typeof fragment.sampleOffset === 'number' ? { offset: fragment.sampleOffset } : {}),
+      })
+      const summary: PendingMfuDebug = {
+        key,
+        fragments: sorted.length,
+        fi0: fiCounts[0] ?? 0,
+        fi1: fiCounts[1] ?? 0,
+        fi2: fiCounts[2] ?? 0,
+        fi3: fiCounts[3] ?? 0,
+        firstFi: sorted[0]!.fragmentationIndicator,
+        lastFi: sorted[sorted.length - 1]!.fragmentationIndicator,
+        firstOrder: this.#orderValue(sorted[0]!),
+        lastOrder: this.#orderValue(sorted[sorted.length - 1]!),
+        minCounter,
+        maxCounter,
+        movieFragmentSequenceNumber: sorted.find((f) => f.movieFragmentSequenceNumber !== undefined)
+          ?.movieFragmentSequenceNumber,
+        sampleNumber: sorted.find((f) => f.sampleNumber !== undefined)?.sampleNumber,
+        mpuSequenceNumber: sorted[0]!.mpuSequenceNumber,
+        sortedHead: sorted.slice(0, 6).map(point),
+        sortedTail: sorted.slice(-6).map(point),
+      }
+      if (minOffset !== Infinity) summary.minOffset = minOffset
+      if (maxOffset !== -Infinity) summary.maxOffset = maxOffset
+      out.push(summary)
+      if (out.length >= 12) break
+    }
+    return out
+  }
+}
+
+/**
+ * Create MFU fragment from MMTP packet for reassembly
+ */
+export function createFragment(mmtpPacket: Uint8Array): MFUFragment {
+  const extraction = extractMFUPayload(mmtpPacket)
+  if (!extraction) throw new Error('Unable to extract MFU payload from MMTP packet')
+  const { header, mpu, data, mfuDuHeader, itemId } = extraction
+
+  return {
+    fragmentationIndicator: mpu.fragmentationIndicator,
+    mpuSequenceNumber: mpu.mpuSequenceNumber,
+    fragmentCounter: mpu.fragmentCounter,
+    data,
+    timestamp: header.timestamp,
+    rapFlag: header.rapFlag,
+    sampleNumber: mfuDuHeader?.sampleNumber,
+    movieFragmentSequenceNumber: mfuDuHeader?.movieFragmentSequenceNumber,
+    sampleOffset: mfuDuHeader?.offset,
+    priority: mfuDuHeader?.priority,
+    itemId: itemId ?? undefined,
+    packetSequenceNumber: header.sequenceNumber,
+    packetId: header.packetId,
+  }
+}
+
+/**
+ * Process MMTP packet with fragment reassembly
+ */
+export function processMMTPWithReassembly(
+  mmtpPacket: Uint8Array,
+  reassembler: MFUReassembler,
+): ReassembledMFU | null {
+  // Skip FEC repair packets
+  if (isFecRepairPacket(mmtpPacket)) {
+    return null
+  }
+
+  const fragment = createFragment(mmtpPacket)
+  return reassembler.addFragment(fragment)
+}
+
+// =============================================================================
+// Inline Tests (vitest)
+// =============================================================================
+
+if (import.meta.vitest) {
+  const { describe, test, expect, vi } = import.meta.vitest
+
+  const expectRejection = (call: () => unknown, code: MfuReassemblyErrorCode): void => {
+    let rejection: unknown
+    try {
+      call()
+    } catch (error) {
+      rejection = error
+    }
+    expect(rejection).toBeInstanceOf(MfuReassemblyError)
+    expect((rejection as MfuReassemblyError).code).toBe(code)
+  }
+
+  const testPacketSequence = (mpu: number, counter: number, run = 0): number =>
+    (mpu * 1000 + run - counter + 0x1_0000_0000) % 0x1_0000_0000
+
+  describe('MFUReassembler', () => {
+    test('should return complete MFU for FI=0', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      const result = reassembler.addFragment({
+        fragmentationIndicator: 0,
+        mpuSequenceNumber: 1,
+        fragmentCounter: 0,
+        itemId: 1,
+        data: new Uint8Array([1, 2, 3, 4]),
+        timestamp: 1000n,
+
+        rapFlag: true,
+      })
+      expect(result).not.toBeNull()
+      expect(result?.data).toEqual(new Uint8Array([1, 2, 3, 4]))
+      expect(result?.fragmentCount).toBe(1)
+      expect(result?.rapFlag).toBe(true)
+    })
+
+    test('rejects a complete MFU without a valid sample identity', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      const complete = (identity: Partial<MFUFragment>): MFUFragment => ({
+        fragmentationIndicator: 0,
+        mpuSequenceNumber: 1,
+        fragmentCounter: 0,
+        data: new Uint8Array([1]),
+        timestamp: 1000n,
+        rapFlag: true,
+        ...identity,
+      })
+      expectRejection(
+        () => reassembler.addFragment(complete({})),
+        'missing-data-unit-identity',
+      )
+      expectRejection(
+        () => reassembler.addFragment(complete({
+          movieFragmentSequenceNumber: 2,
+          sampleNumber: 1,
+        })),
+        'missing-data-unit-identity',
+      )
+    })
+
+    test('accepts a complete subsample MFU with a nonzero authored offset', () => {
+      // moqcast #37: a subsample DU's offset is its authored base byte
+      // position within the sample -- nonzero identifies one subsample DU
+      // among siblings partitioning an oversized sample.
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      const result = reassembler.addFragment({
+        fragmentationIndicator: 0,
+        mpuSequenceNumber: 1,
+        fragmentCounter: 0,
+        movieFragmentSequenceNumber: 2,
+        sampleNumber: 1,
+        sampleOffset: 4,
+        data: new Uint8Array([1]),
+        timestamp: 1000n,
+        rapFlag: true,
+      })
+      expect(result).not.toBeNull()
+      expect(result?.sampleOffset).toBe(4)
+    })
+
+    test('accepts a fragmented subsample DU whose first fragment has a nonzero authored offset', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 1,
+        mpuSequenceNumber: 2,
+        fragmentCounter: 1,
+        movieFragmentSequenceNumber: 2,
+        sampleNumber: 1,
+        sampleOffset: 4,
+        packetSequenceNumber: testPacketSequence(2, 1),
+        data: new Uint8Array([0xa1]),
+        timestamp: 1000n,
+        rapFlag: true,
+      })).toBeNull()
+      expect(reassembler.pendingCount).toBe(1)
+      expect(reassembler.getStatus().pendingFragments).toBe(1)
+
+      const out = reassembler.addFragment({
+        fragmentationIndicator: 3,
+        mpuSequenceNumber: 2,
+        fragmentCounter: 0,
+        data: new Uint8Array([0xa2]),
+        timestamp: 1001n,
+        rapFlag: false,
+        packetSequenceNumber: testPacketSequence(2, 0),
+      })
+      expect(out?.data).toEqual(new Uint8Array([0xa1, 0xa2]))
+      expect(out?.sampleOffset).toBe(4)
+    })
+
+    test('sibling subsample DUs of one sample reassemble independently by offset', () => {
+      // moqcast #37: each subsample DU of a partitioned sample runs its own
+      // FI chain and gets its own buffer, keyed in part by its authored base
+      // offset -- distinct from a sibling DU sharing (movie, sample).
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+
+      expect(reassembler.addFragment({
+        mpuSequenceNumber: 3,
+        movieFragmentSequenceNumber: 5,
+        sampleNumber: 9,
+        fragmentationIndicator: 1,
+        fragmentCounter: 1,
+        sampleOffset: 0,
+        data: new Uint8Array([0xa1]),
+        timestamp: 2000n,
+        rapFlag: true,
+        packetSequenceNumber: testPacketSequence(3, 1, 0),
+      })).toBeNull()
+      expect(reassembler.addFragment({
+        mpuSequenceNumber: 3,
+        movieFragmentSequenceNumber: 5,
+        sampleNumber: 9,
+        fragmentationIndicator: 1,
+        fragmentCounter: 1,
+        sampleOffset: 3,
+        data: new Uint8Array([0xb1]),
+        timestamp: 2001n,
+        rapFlag: false,
+        packetSequenceNumber: testPacketSequence(3, 1, 1),
+      })).toBeNull()
+      expect(reassembler.pendingCount).toBe(2)
+
+      const first = reassembler.addFragment({
+        mpuSequenceNumber: 3,
+        fragmentationIndicator: 3,
+        fragmentCounter: 0,
+        data: new Uint8Array([0xa2]),
+        timestamp: 2000n,
+        rapFlag: false,
+        packetSequenceNumber: testPacketSequence(3, 0, 0),
+      })
+      expect(first?.data).toEqual(new Uint8Array([0xa1, 0xa2]))
+      expect(first?.sampleOffset).toBe(0)
+
+      const second = reassembler.addFragment({
+        mpuSequenceNumber: 3,
+        fragmentationIndicator: 3,
+        fragmentCounter: 0,
+        data: new Uint8Array([0xb2]),
+        timestamp: 2001n,
+        rapFlag: false,
+        packetSequenceNumber: testPacketSequence(3, 0, 1),
+      })
+      expect(second?.data).toEqual(new Uint8Array([0xb1, 0xb2]))
+      expect(second?.sampleOffset).toBe(3)
+      expect(reassembler.pendingCount).toBe(0)
+    })
+
+    test('isolates colliding fragment coordinates by catalog track identity', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      const fragment = (
+        catalogTrackName: string,
+        fragmentationIndicator: number,
+        fragmentCounter: number,
+        byte: number,
+      ): MFUFragment => ({
+        itemId: 1,
+        fragmentationIndicator,
+        fragmentCounter,
+        mpuSequenceNumber: 1,
+        data: new Uint8Array([byte]),
+        timestamp: 1000n,
+        rapFlag: fragmentationIndicator === 1,
+        catalogTrackName,
+        packetSequenceNumber: testPacketSequence(1, fragmentCounter),
+      })
+
+      expect(reassembler.addFragment(fragment('video/720p', 1, 1, 0x71))).toBeNull()
+      expect(reassembler.addFragment(fragment('video/540p', 1, 1, 0x51))).toBeNull()
+      const high = reassembler.addFragment(fragment('video/720p', 3, 0, 0x72))
+      const low = reassembler.addFragment(fragment('video/540p', 3, 0, 0x52))
+
+      expect(high?.data).toEqual(new Uint8Array([0x71, 0x72]))
+      expect(high?.catalogTrackName).toBe('video/720p')
+      expect(low?.data).toEqual(new Uint8Array([0x51, 0x52]))
+      expect(low?.catalogTrackName).toBe('video/540p')
+    })
+
+    test('rejects an overlapping non-timed item without replacing the active run', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      const fragment = (
+        itemId: number,
+        fragmentationIndicator: number,
+        fragmentCounter: number,
+        byte: number,
+      ): MFUFragment => ({
+        itemId,
+        fragmentationIndicator,
+        fragmentCounter,
+        mpuSequenceNumber: 1,
+        data: new Uint8Array([byte]),
+        timestamp: 1000n,
+        rapFlag: false,
+        packetSequenceNumber: testPacketSequence(1, fragmentCounter),
+      })
+
+      expect(reassembler.addFragment(fragment(10, 1, 1, 0x10))).toBeNull()
+      expectRejection(
+        () => reassembler.addFragment(fragment(20, 1, 1, 0x20)),
+        'overlapping-data-unit',
+      )
+      expect(reassembler.pendingCount).toBe(1)
+      expect(reassembler.addFragment(fragment(10, 3, 0, 0x11))?.data)
+        .toEqual(new Uint8Array([0x10, 0x11]))
+      expect(reassembler.pendingCount).toBe(0)
+    })
+
+    test('associates continuations by authored state when packet timestamps change', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      const fragment = (
+        itemId: number | undefined,
+        fragmentationIndicator: number,
+        fragmentCounter: number,
+        byte: number,
+        timestamp: bigint,
+      ): MFUFragment => ({
+        ...(itemId === undefined ? {} : { itemId }),
+        fragmentationIndicator,
+        fragmentCounter,
+        mpuSequenceNumber: 1,
+        data: new Uint8Array([byte]),
+        timestamp,
+        rapFlag: false,
+        packetSequenceNumber: testPacketSequence(1, fragmentCounter),
+      })
+
+      expect(reassembler.addFragment(fragment(10, 1, 2, 0x10, 1000n))).toBeNull()
+      expect(reassembler.addFragment(fragment(undefined, 2, 1, 0x11, 1001n))).toBeNull()
+      const out = reassembler.addFragment(fragment(undefined, 3, 0, 0x12, 1002n))
+      expect(out?.data).toEqual(new Uint8Array([0x10, 0x11, 0x12]))
+      expect(out?.timestamp).toBe(1000n)
+    })
+
+    test('should buffer and reassemble 2 fragments', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+
+      // First fragment (FI=1)
+      const result1 = reassembler.addFragment({
+        fragmentationIndicator: 1,
+        mpuSequenceNumber: 1,
+        fragmentCounter: 1,
+        itemId: 1,
+        data: new Uint8Array([1, 2]),
+        timestamp: 1000n,
+        rapFlag: true,
+        packetSequenceNumber: testPacketSequence(1, 1),
+      })
+      expect(result1).toBeNull()
+
+      // Last fragment (FI=3)
+      const result2 = reassembler.addFragment({
+        fragmentationIndicator: 3,
+        mpuSequenceNumber: 1,
+        fragmentCounter: 0,
+        data: new Uint8Array([3, 4]),
+        timestamp: 1000n,
+        rapFlag: false,
+        packetSequenceNumber: testPacketSequence(1, 0),
+      })
+      expect(result2).not.toBeNull()
+      expect(result2?.data).toEqual(new Uint8Array([1, 2, 3, 4]))
+      expect(result2?.fragmentCount).toBe(2)
+      expect(result2?.rapFlag).toBe(true) // Should use first fragment's rapFlag
+    })
+
+    test('buffers a terminal continuation until its authored first fragment arrives', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+
+      // Last fragment first (FI=3)
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 3,
+        mpuSequenceNumber: 1,
+        fragmentCounter: 0,
+        data: new Uint8Array([3, 4]),
+        timestamp: 1000n,
+        rapFlag: false,
+        packetSequenceNumber: testPacketSequence(1, 0),
+      })).toBeNull()
+      expect(reassembler.pendingCount).toBe(1)
+
+      // Then first fragment (FI=1)
+      const completed = reassembler.addFragment({
+        fragmentationIndicator: 1,
+        mpuSequenceNumber: 1,
+        fragmentCounter: 1,
+        itemId: 1,
+        data: new Uint8Array([1, 2]),
+        timestamp: 1000n,
+        rapFlag: true,
+        packetSequenceNumber: testPacketSequence(1, 1),
+      })
+
+      expect(completed?.data).toEqual(new Uint8Array([1, 2, 3, 4]))
+      expect(completed?.rapFlag).toBe(true)
+      expect(reassembler.pendingCount).toBe(0)
+    })
+
+    test('clock-free mode keeps an admitted MFU until completion', async () => {
+      const reassembler = new MFUReassembler({ timeoutMs: null })
+
+      reassembler.addFragment({
+        fragmentationIndicator: 1,
+        mpuSequenceNumber: 1,
+        fragmentCounter: 1,
+        itemId: 1,
+        data: new Uint8Array([1, 2]),
+        timestamp: 1000n,
+        rapFlag: true,
+        packetSequenceNumber: testPacketSequence(1, 1),
+      })
+
+      await new Promise(resolve => setTimeout(resolve, 5))
+
+      const result = reassembler.addFragment({
+        fragmentationIndicator: 3,
+        mpuSequenceNumber: 1,
+        fragmentCounter: 0,
+        data: new Uint8Array([3, 4]),
+        timestamp: 1000n,
+        rapFlag: false,
+        packetSequenceNumber: testPacketSequence(1, 0),
+      })
+
+      expect(result).not.toBeNull()
+      expect(result?.data).toEqual(new Uint8Array([1, 2, 3, 4]))
+      expect(reassembler.stats.timedOutMFUs).toBe(0)
+    })
+
+    test('should track pending count', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      expect(reassembler.pendingCount).toBe(0)
+
+      reassembler.addFragment({
+        fragmentationIndicator: 1,
+        mpuSequenceNumber: 1,
+        fragmentCounter: 1,
+        itemId: 1,
+        data: new Uint8Array([1]),
+        timestamp: 1000n,
+        rapFlag: false,
+        packetSequenceNumber: testPacketSequence(1, 1),
+      })
+      expect(reassembler.pendingCount).toBe(1)
+
+      reassembler.flush()
+      expect(reassembler.pendingCount).toBe(0)
+    })
+
+    test('should reassemble 3 fragments (FI=1, FI=2, FI=3)', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+
+      // First fragment
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 1, mpuSequenceNumber: 10,
+        fragmentCounter: 2, itemId: 1, data: new Uint8Array([0xAA, 0xBB]),
+        timestamp: 5000n, rapFlag: true,
+        packetSequenceNumber: testPacketSequence(10, 2),
+      })).toBeNull()
+
+      // Middle fragment
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 2, mpuSequenceNumber: 10,
+        fragmentCounter: 1, data: new Uint8Array([0xCC, 0xDD]),
+        timestamp: 5000n, rapFlag: false,
+        packetSequenceNumber: testPacketSequence(10, 1),
+      })).toBeNull()
+
+      // Last fragment — triggers reassembly
+      const result = reassembler.addFragment({
+        fragmentationIndicator: 3, mpuSequenceNumber: 10,
+        fragmentCounter: 0, data: new Uint8Array([0xEE, 0xFF]),
+        timestamp: 5000n, rapFlag: false,
+        packetSequenceNumber: testPacketSequence(10, 0),
+      })
+
+      expect(result).not.toBeNull()
+      expect(result!.data).toEqual(new Uint8Array([0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF]))
+      expect(result!.fragmentCount).toBe(3)
+      expect(result!.rapFlag).toBe(true) // from first fragment
+      expect(result!.mpuSequenceNumber).toBe(10)
+    })
+
+    test('should handle interleaved MPU sequences', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+
+      // MPU 1: first fragment
+      reassembler.addFragment({
+        fragmentationIndicator: 1, mpuSequenceNumber: 1,
+        fragmentCounter: 1, itemId: 1, data: new Uint8Array([0x01]),
+        timestamp: 100n, rapFlag: false,
+        packetSequenceNumber: testPacketSequence(1, 1),
+      })
+      // MPU 2: complete (FI=0)
+      const r2 = reassembler.addFragment({
+        fragmentationIndicator: 0, mpuSequenceNumber: 2,
+        fragmentCounter: 0, itemId: 2, data: new Uint8Array([0x02]),
+        timestamp: 200n, rapFlag: false,
+      })
+      expect(r2).not.toBeNull()
+      expect(r2!.mpuSequenceNumber).toBe(2)
+
+      // MPU 1: last fragment
+      const r1 = reassembler.addFragment({
+        fragmentationIndicator: 3, mpuSequenceNumber: 1,
+        fragmentCounter: 0, data: new Uint8Array([0x03]),
+        timestamp: 100n, rapFlag: false,
+        packetSequenceNumber: testPacketSequence(1, 0),
+      })
+      expect(r1).not.toBeNull()
+      expect(r1!.data).toEqual(new Uint8Array([0x01, 0x03]))
+    })
+
+    test('rejects overlapping fragmented MFUs sharing one stream and MPU', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      const mpuSeq = 5
+
+      expect(
+        reassembler.addFragment({
+          fragmentationIndicator: 1, mpuSequenceNumber: mpuSeq,
+          fragmentCounter: 1, itemId: 10,
+          data: new Uint8Array([0xa1]), timestamp: 100n, rapFlag: true,
+          packetSequenceNumber: testPacketSequence(mpuSeq, 1),
+        }),
+      ).toBeNull()
+      expectRejection(
+        () => reassembler.addFragment({
+          fragmentationIndicator: 1, mpuSequenceNumber: mpuSeq,
+          fragmentCounter: 1, itemId: 20,
+          data: new Uint8Array([0xb1]), timestamp: 200n, rapFlag: false,
+          packetSequenceNumber: testPacketSequence(mpuSeq, 1),
+        }),
+        'overlapping-data-unit',
+      )
+      expect(reassembler.pendingCount).toBe(1)
+
+      const a = reassembler.addFragment({
+        fragmentationIndicator: 3, mpuSequenceNumber: mpuSeq,
+        fragmentCounter: 0, data: new Uint8Array([0xa2]), timestamp: 101n, rapFlag: false,
+        packetSequenceNumber: testPacketSequence(mpuSeq, 0),
+      })
+      expect(a).not.toBeNull()
+      expect(a!.data).toEqual(new Uint8Array([0xa1, 0xa2]))
+      expect(a!.rapFlag).toBe(true) // from A's first fragment
+
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 1, mpuSequenceNumber: mpuSeq,
+        fragmentCounter: 1, itemId: 20,
+        data: new Uint8Array([0xb1]), timestamp: 200n, rapFlag: false,
+        packetSequenceNumber: testPacketSequence(mpuSeq, 1, 10),
+      })).toBeNull()
+      const b = reassembler.addFragment({
+        fragmentationIndicator: 3, mpuSequenceNumber: mpuSeq,
+        fragmentCounter: 0, data: new Uint8Array([0xb2]), timestamp: 201n, rapFlag: false,
+        packetSequenceNumber: testPacketSequence(mpuSeq, 0, 10),
+      })
+      expect(b).not.toBeNull()
+      expect(b!.data).toEqual(new Uint8Array([0xb1, 0xb2]))
+    })
+
+    test('reassembles FFmpeg timed MFU fragments by sample number and byte offset', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      const common = {
+        mpuSequenceNumber: 0,
+        movieFragmentSequenceNumber: 9,
+        sampleNumber: 17,
+      }
+
+      expect(reassembler.addFragment({
+        ...common,
+        fragmentationIndicator: 1,
+        fragmentCounter: 2,
+        sampleOffset: 0,
+        data: new Uint8Array([0xa1]),
+        timestamp: 1000n,
+        rapFlag: true,
+        packetSequenceNumber: testPacketSequence(0, 2),
+      })).toBeNull()
+      expect(reassembler.addFragment({
+        ...common,
+        fragmentationIndicator: 2,
+        fragmentCounter: 1,
+        sampleOffset: 1,
+        data: new Uint8Array([0xb2]),
+        timestamp: 1001n,
+        rapFlag: false,
+        packetSequenceNumber: testPacketSequence(0, 1),
+      })).toBeNull()
+      const out = reassembler.addFragment({
+        ...common,
+        fragmentationIndicator: 3,
+        fragmentCounter: 0,
+        sampleOffset: 2,
+        data: new Uint8Array([0xc3]),
+        timestamp: 1002n,
+        rapFlag: false,
+        packetSequenceNumber: testPacketSequence(0, 0),
+      })
+
+      expect(out).not.toBeNull()
+      expect(out!.data).toEqual(new Uint8Array([0xa1, 0xb2, 0xc3]))
+      expect(out!.timestamp).toBe(1000n)
+      expect(out!.sampleNumber).toBe(17)
+      expect(out!.movieFragmentSequenceNumber).toBe(9)
+    })
+
+    test('buffers a counter gap without advancing the active data unit', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      const common = {
+        mpuSequenceNumber: 0,
+        movieFragmentSequenceNumber: 9,
+        sampleNumber: 17,
+        timestamp: 1000n,
+        rapFlag: true,
+      }
+
+      expect(reassembler.addFragment({
+        ...common,
+        fragmentationIndicator: 1,
+        fragmentCounter: 2,
+        sampleOffset: 0,
+        data: new Uint8Array([0xa1, 0xa2]),
+        packetSequenceNumber: testPacketSequence(0, 2),
+      })).toBeNull()
+      expect(reassembler.addFragment({
+        ...common,
+        fragmentationIndicator: 3,
+        fragmentCounter: 0,
+        sampleOffset: 4,
+        data: new Uint8Array([0xc1, 0xc2]),
+        packetSequenceNumber: testPacketSequence(0, 0),
+      })).toBeNull()
+      expect(reassembler.pendingCount).toBe(1)
+
+      const out = reassembler.addFragment({
+        ...common,
+        fragmentationIndicator: 2,
+        fragmentCounter: 1,
+        sampleOffset: 2,
+        data: new Uint8Array([0xb1, 0xb2]),
+        packetSequenceNumber: testPacketSequence(0, 1),
+      })
+      expect(out?.data).toEqual(
+        new Uint8Array([0xa1, 0xa2, 0xb1, 0xb2, 0xc1, 0xc2]),
+      )
+    })
+
+    test('reassembles first-only DU-header fragments across changing packet timestamps', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 1,
+        mpuSequenceNumber: 44,
+        fragmentCounter: 2,
+        movieFragmentSequenceNumber: 9,
+        sampleNumber: 17,
+        sampleOffset: 0,
+        data: new Uint8Array([0xa1]),
+        timestamp: 12345n,
+        rapFlag: true,
+        packetSequenceNumber: testPacketSequence(44, 2),
+      })).toBeNull()
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 2,
+        mpuSequenceNumber: 44,
+        fragmentCounter: 1,
+        data: new Uint8Array([0xb2]),
+        timestamp: 12346n,
+        rapFlag: false,
+        packetSequenceNumber: testPacketSequence(44, 1),
+      })).toBeNull()
+      const out = reassembler.addFragment({
+        fragmentationIndicator: 3,
+        mpuSequenceNumber: 44,
+        fragmentCounter: 0,
+        data: new Uint8Array([0xc3]),
+        timestamp: 12347n,
+        rapFlag: false,
+        packetSequenceNumber: testPacketSequence(44, 0),
+      })
+
+      expect(out).not.toBeNull()
+      expect(out!.data).toEqual(new Uint8Array([0xa1, 0xb2, 0xc3]))
+      expect(out!.timestamp).toBe(12345n)
+      expect(out!.sampleNumber).toBe(17)
+      expect(out!.movieFragmentSequenceNumber).toBe(9)
+    })
+
+    test('reassembles first-only DU-header fragments with an ISO countdown', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      const timestamp = 12345n
+
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 1,
+        mpuSequenceNumber: 44,
+        fragmentCounter: 3,
+        movieFragmentSequenceNumber: 9,
+        sampleNumber: 17,
+        sampleOffset: 0,
+        data: new Uint8Array([0xa1]),
+        timestamp,
+        rapFlag: true,
+        packetSequenceNumber: testPacketSequence(44, 3),
+      })).toBeNull()
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 2,
+        mpuSequenceNumber: 44,
+        fragmentCounter: 2,
+        data: new Uint8Array([0xb2]),
+        timestamp,
+        rapFlag: false,
+        packetSequenceNumber: testPacketSequence(44, 2),
+      })).toBeNull()
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 2,
+        mpuSequenceNumber: 44,
+        fragmentCounter: 1,
+        data: new Uint8Array([0xc3]),
+        timestamp,
+        rapFlag: false,
+        packetSequenceNumber: testPacketSequence(44, 1),
+      })).toBeNull()
+      const out = reassembler.addFragment({
+        fragmentationIndicator: 3,
+        mpuSequenceNumber: 44,
+        fragmentCounter: 0,
+        data: new Uint8Array([0xd4]),
+        timestamp,
+        rapFlag: false,
+        packetSequenceNumber: testPacketSequence(44, 0),
+      })
+
+      expect(out).not.toBeNull()
+      expect(out!.data).toEqual(new Uint8Array([0xa1, 0xb2, 0xc3, 0xd4]))
+      expect(out!.sampleNumber).toBe(17)
+      expect(out!.movieFragmentSequenceNumber).toBe(9)
+    })
+
+    test('rejects fragmented MFUs without an authored DU identity', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      const timestamp = 22222n
+
+      expectRejection(() => reassembler.addFragment({
+        fragmentationIndicator: 1,
+        mpuSequenceNumber: 55,
+        fragmentCounter: 2,
+        data: new Uint8Array([0xa1]),
+        timestamp,
+        rapFlag: true,
+        packetSequenceNumber: testPacketSequence(55, 2),
+      }), 'missing-data-unit-identity')
+      expect(reassembler.pendingCount).toBe(0)
+    })
+
+    test('rejects fragmented MFUs without an authored packet sequence', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      expectRejection(() => reassembler.addFragment({
+        fragmentationIndicator: 1,
+        mpuSequenceNumber: 55,
+        fragmentCounter: 1,
+        itemId: 1,
+        data: new Uint8Array([0xa1]),
+        timestamp: 22222n,
+        rapFlag: true,
+      }), 'missing-packet-sequence')
+      expect(reassembler.pendingCount).toBe(0)
+    })
+
+    test('rejects fragmented MFUs whose authored packet sequence is not u32', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      for (const packetSequenceNumber of [-1, 0x1_0000_0000, 1.5, Number.NaN]) {
+        expectRejection(() => reassembler.addFragment({
+          fragmentationIndicator: 1,
+          mpuSequenceNumber: 55,
+          fragmentCounter: 1,
+          itemId: 1,
+          data: new Uint8Array([0xa1]),
+          timestamp: 22222n,
+          rapFlag: true,
+          packetSequenceNumber,
+        }), 'missing-packet-sequence')
+      }
+      expect(reassembler.pendingCount).toBe(0)
+    })
+
+    test('fails closed when one fragmented DU has interleaved packet sequence gaps', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      const timestamp = 66666n
+
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 1,
+        mpuSequenceNumber: 80,
+        fragmentCounter: 17,
+        movieFragmentSequenceNumber: 241,
+        sampleNumber: 1,
+        sampleOffset: 0,
+        packetSequenceNumber: 1000,
+        data: new Uint8Array([0xa0]),
+        timestamp,
+        rapFlag: true,
+      })).toBeNull()
+
+      for (let i = 1; i < 17; i++) {
+        expect(reassembler.addFragment({
+          fragmentationIndicator: 2,
+          mpuSequenceNumber: 80,
+          fragmentCounter: 17 - i,
+          packetSequenceNumber: 1000 + i * 2,
+          data: new Uint8Array([0xa0 + i]),
+          timestamp,
+          rapFlag: false,
+        })).toBeNull()
+      }
+
+      const out = reassembler.addFragment({
+        fragmentationIndicator: 3,
+        mpuSequenceNumber: 80,
+        fragmentCounter: 0,
+        packetSequenceNumber: 1040,
+        data: new Uint8Array([0xb1]),
+        timestamp,
+        rapFlag: false,
+      })
+
+      expect(out).toBeNull()
+      expect(reassembler.pendingCount).toBe(18)
+      expect(reassembler.stats.reassembledMFUs).toBe(0)
+    })
+
+    test('does not combine adjacent reordered MFUs in one MPU', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      const common = { mpuSequenceNumber: 80, packetId: 7, timestamp: 66666n }
+
+      expect(reassembler.addFragment({
+        ...common,
+        fragmentationIndicator: 3,
+        fragmentCounter: 0,
+        packetSequenceNumber: 103,
+        data: new Uint8Array([0xb2]),
+        rapFlag: false,
+      })).toBeNull()
+      expect(reassembler.addFragment({
+        ...common,
+        fragmentationIndicator: 1,
+        fragmentCounter: 1,
+        packetSequenceNumber: 100,
+        movieFragmentSequenceNumber: 241,
+        sampleNumber: 1,
+        sampleOffset: 0,
+        data: new Uint8Array([0xa1]),
+        rapFlag: true,
+      })).toBeNull()
+
+      const earlier = reassembler.addFragment({
+        ...common,
+        fragmentationIndicator: 3,
+        fragmentCounter: 0,
+        packetSequenceNumber: 101,
+        data: new Uint8Array([0xa2]),
+        rapFlag: false,
+      })
+      expect(earlier?.data).toEqual(new Uint8Array([0xa1, 0xa2]))
+
+      const later = reassembler.addFragment({
+        ...common,
+        fragmentationIndicator: 1,
+        fragmentCounter: 1,
+        packetSequenceNumber: 102,
+        movieFragmentSequenceNumber: 241,
+        sampleNumber: 2,
+        sampleOffset: 0,
+        data: new Uint8Array([0xb1]),
+        rapFlag: false,
+      })
+      expect(later?.data).toEqual(new Uint8Array([0xb1, 0xb2]))
+    })
+
+    test('wraps the fragmented run coordinate at u32 packet sequence', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 1,
+        mpuSequenceNumber: 81,
+        fragmentCounter: 1,
+        packetSequenceNumber: 0xffffffff,
+        itemId: 1,
+        data: new Uint8Array([0xa1]),
+        timestamp: 66666n,
+        rapFlag: true,
+      })).toBeNull()
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 3,
+        mpuSequenceNumber: 81,
+        fragmentCounter: 0,
+        packetSequenceNumber: 0,
+        data: new Uint8Array([0xa2]),
+        timestamp: 66667n,
+        rapFlag: false,
+      })?.data).toEqual(new Uint8Array([0xa1, 0xa2]))
+    })
+
+    test('dedupes recovered copies by ISO fragment-counter position', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      const timestamp = 44444n
+
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 1,
+        mpuSequenceNumber: 77,
+        fragmentCounter: 2,
+        movieFragmentSequenceNumber: 12,
+        sampleNumber: 1,
+        sampleOffset: 0,
+        packetSequenceNumber: 2000,
+        data: new Uint8Array([0xa1]),
+        timestamp,
+        rapFlag: true,
+      })).toBeNull()
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 2,
+        mpuSequenceNumber: 77,
+        fragmentCounter: 1,
+        packetSequenceNumber: 2001,
+        data: new Uint8Array([0xb2]),
+        timestamp,
+        rapFlag: false,
+      })).toBeNull()
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 3,
+        mpuSequenceNumber: 77,
+        fragmentCounter: 0,
+        packetSequenceNumber: 2002,
+        data: new Uint8Array([0xc3]),
+        timestamp,
+        rapFlag: false,
+      })).not.toBeNull()
+
+      reassembler.flush()
+
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 1,
+        mpuSequenceNumber: 78,
+        fragmentCounter: 2,
+        movieFragmentSequenceNumber: 13,
+        sampleNumber: 1,
+        sampleOffset: 0,
+        packetSequenceNumber: 3000,
+        data: new Uint8Array([0xd4]),
+        timestamp,
+        rapFlag: true,
+      })).toBeNull()
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 2,
+        mpuSequenceNumber: 78,
+        fragmentCounter: 1,
+        packetSequenceNumber: 3001,
+        data: new Uint8Array([0xe5]),
+        timestamp,
+        rapFlag: false,
+      })).toBeNull()
+      expectRejection(() => reassembler.addFragment({
+        fragmentationIndicator: 2,
+        mpuSequenceNumber: 78,
+        fragmentCounter: 1,
+        packetSequenceNumber: 3001,
+        data: new Uint8Array([0xe5]),
+        timestamp,
+        rapFlag: false,
+      }), 'fragment-counter-mismatch')
+      const out = reassembler.addFragment({
+        fragmentationIndicator: 3,
+        mpuSequenceNumber: 78,
+        fragmentCounter: 0,
+        packetSequenceNumber: 3002,
+        data: new Uint8Array([0xf6]),
+        timestamp,
+        rapFlag: false,
+      })
+
+      expect(out).not.toBeNull()
+      expect(out!.data).toEqual(new Uint8Array([0xd4, 0xe5, 0xf6]))
+    })
+
+    test('reassembles middle and terminal continuations that arrive before first', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      const timestamp = 54321n
+
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 2,
+        mpuSequenceNumber: 45,
+        fragmentCounter: 1,
+        data: new Uint8Array([0xb2]),
+        timestamp,
+        rapFlag: false,
+        packetSequenceNumber: testPacketSequence(45, 1),
+      })).toBeNull()
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 3,
+        mpuSequenceNumber: 45,
+        fragmentCounter: 0,
+        data: new Uint8Array([0xc3]),
+        timestamp: timestamp + 1n,
+        rapFlag: false,
+        packetSequenceNumber: testPacketSequence(45, 0),
+      })).toBeNull()
+      expect(reassembler.pendingCount).toBe(1)
+      const out = reassembler.addFragment({
+        fragmentationIndicator: 1,
+        mpuSequenceNumber: 45,
+        fragmentCounter: 2,
+        movieFragmentSequenceNumber: 10,
+        sampleNumber: 18,
+        sampleOffset: 0,
+        data: new Uint8Array([0xa1]),
+        timestamp,
+        rapFlag: true,
+        packetSequenceNumber: testPacketSequence(45, 2),
+      })
+
+      expect(out).not.toBeNull()
+      expect(out!.data).toEqual(new Uint8Array([0xa1, 0xb2, 0xc3]))
+      expect(out!.sampleNumber).toBe(18)
+      expect(out!.movieFragmentSequenceNumber).toBe(10)
+      expect(reassembler.pendingCount).toBe(0)
+    })
+
+    test('rejects a duplicate continuation before first without replacing retained media', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      const timestamp = 54322n
+
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 3,
+        mpuSequenceNumber: 46,
+        fragmentCounter: 0,
+        data: new Uint8Array([0xc3]),
+        timestamp,
+        rapFlag: false,
+        packetSequenceNumber: testPacketSequence(46, 0),
+      })).toBeNull()
+      expectRejection(() => reassembler.addFragment({
+        fragmentationIndicator: 3,
+        mpuSequenceNumber: 46,
+        fragmentCounter: 0,
+        data: new Uint8Array([0xff]),
+        timestamp: timestamp + 1n,
+        rapFlag: false,
+        packetSequenceNumber: testPacketSequence(46, 0),
+      }), 'fragment-counter-mismatch')
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 2,
+        mpuSequenceNumber: 46,
+        fragmentCounter: 1,
+        data: new Uint8Array([0xb2]),
+        timestamp: timestamp + 2n,
+        rapFlag: false,
+        packetSequenceNumber: testPacketSequence(46, 1),
+      })).toBeNull()
+
+      const out = reassembler.addFragment({
+        fragmentationIndicator: 1,
+        mpuSequenceNumber: 46,
+        fragmentCounter: 2,
+        movieFragmentSequenceNumber: 10,
+        sampleNumber: 19,
+        sampleOffset: 0,
+        data: new Uint8Array([0xa1]),
+        timestamp: timestamp + 3n,
+        rapFlag: true,
+        packetSequenceNumber: testPacketSequence(46, 2),
+      })
+
+      expect(out).not.toBeNull()
+      expect(out!.data).toEqual(new Uint8Array([0xa1, 0xb2, 0xc3]))
+      expect(reassembler.pendingCount).toBe(0)
+    })
+
+    test('rejects invalid ISO fragmentation-indicator and counter combinations', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      const invalidHeaders = [
+        { fragmentationIndicator: 0, fragmentCounter: 1 },
+        { fragmentationIndicator: 3, fragmentCounter: 1 },
+        { fragmentationIndicator: 1, fragmentCounter: 0 },
+        { fragmentationIndicator: 2, fragmentCounter: 0 },
+        { fragmentationIndicator: -1, fragmentCounter: 1 },
+        { fragmentationIndicator: 4, fragmentCounter: 1 },
+        { fragmentationIndicator: 1.5, fragmentCounter: 1 },
+        { fragmentationIndicator: 1, fragmentCounter: -1 },
+        { fragmentationIndicator: 1, fragmentCounter: 256 },
+        { fragmentationIndicator: 1, fragmentCounter: 1.5 },
+        { fragmentationIndicator: 1, fragmentCounter: Number.NaN },
+      ]
+
+      for (const header of invalidHeaders) {
+        expectRejection(() => reassembler.addFragment({
+          ...header,
+          mpuSequenceNumber: 48,
+          data: new Uint8Array([0xa1]),
+          timestamp: 54324n,
+          rapFlag: false,
+        }), 'invalid-fragment-state')
+      }
+
+      expect(reassembler.pendingCount).toBe(0)
+      expect(reassembler.stats.reassembledMFUs).toBe(0)
+    })
+
+    test('reassembles the maximum ISO chain of 256 payloads', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: null })
+      const common = {
+        mpuSequenceNumber: 47,
+        timestamp: 54323n,
+        rapFlag: false,
+      }
+
+      expect(reassembler.addFragment({
+        ...common,
+        fragmentationIndicator: 1,
+        fragmentCounter: 255,
+        itemId: 1,
+        data: new Uint8Array([0]),
+        rapFlag: true,
+        packetSequenceNumber: testPacketSequence(47, 255),
+      })).toBeNull()
+      for (let counter = 254; counter > 0; counter--) {
+        expect(reassembler.addFragment({
+          ...common,
+          fragmentationIndicator: 2,
+          fragmentCounter: counter,
+          data: new Uint8Array([255 - counter]),
+          packetSequenceNumber: testPacketSequence(47, counter),
+        })).toBeNull()
+      }
+      const out = reassembler.addFragment({
+        ...common,
+        fragmentationIndicator: 3,
+        fragmentCounter: 0,
+        data: new Uint8Array([255]),
+        packetSequenceNumber: testPacketSequence(47, 0),
+      })
+
+      expect(out?.fragmentCount).toBe(256)
+      expect(out?.data).toEqual(Uint8Array.from({ length: 256 }, (_, index) => index))
+    })
+
+    test('should not reassemble without last fragment (FI=3)', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      reassembler.addFragment({
+        fragmentationIndicator: 1, mpuSequenceNumber: 1,
+        fragmentCounter: 2, itemId: 1, data: new Uint8Array([1]),
+        timestamp: 1000n, rapFlag: false,
+        packetSequenceNumber: testPacketSequence(1, 2),
+      })
+      const result = reassembler.addFragment({
+        fragmentationIndicator: 2, mpuSequenceNumber: 1,
+        fragmentCounter: 1, data: new Uint8Array([2]),
+        timestamp: 1000n, rapFlag: false,
+        packetSequenceNumber: testPacketSequence(1, 1),
+      })
+      expect(result).toBeNull()
+      expect(reassembler.pendingCount).toBe(1)
+    })
+
+    test('bounds continuations that arrive before their first fragments', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: null, maxBuffered: 1 })
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 3, mpuSequenceNumber: 1,
+        fragmentCounter: 0, data: new Uint8Array([1]),
+        timestamp: 1000n, rapFlag: false,
+        packetSequenceNumber: testPacketSequence(1, 0),
+      })).toBeNull()
+      expectRejection(() => reassembler.addFragment({
+        fragmentationIndicator: 3, mpuSequenceNumber: 2,
+        fragmentCounter: 0, data: new Uint8Array([2]),
+        timestamp: 1000n, rapFlag: false,
+        packetSequenceNumber: testPacketSequence(2, 0),
+      }), 'active-data-unit-limit')
+      expectRejection(() => reassembler.addFragment({
+        fragmentationIndicator: 1, mpuSequenceNumber: 2,
+        fragmentCounter: 1, itemId: 2, data: new Uint8Array([2]),
+        timestamp: 1000n, rapFlag: true,
+        packetSequenceNumber: testPacketSequence(2, 1),
+      }), 'active-data-unit-limit')
+      expect(reassembler.pendingCount).toBe(1)
+      expect(reassembler.getStatus().pendingFragments).toBe(1)
+
+      const result = reassembler.addFragment({
+        fragmentationIndicator: 1, mpuSequenceNumber: 1,
+        fragmentCounter: 1, itemId: 1, data: new Uint8Array([3]),
+        timestamp: 1000n, rapFlag: true,
+        packetSequenceNumber: testPacketSequence(1, 1),
+      })
+      expect(result?.data).toEqual(new Uint8Array([3, 1]))
+    })
+
+    test('expires a continuation that never receives its first fragment', () => {
+      vi.useFakeTimers()
+      try {
+        const reassembler = new MFUReassembler({ timeoutMs: 50, maxBuffered: 1 })
+        expect(reassembler.addFragment({
+          fragmentationIndicator: 3, mpuSequenceNumber: 1,
+          fragmentCounter: 0, data: new Uint8Array([1]),
+          timestamp: 1000n, rapFlag: false,
+          packetSequenceNumber: testPacketSequence(1, 0),
+        })).toBeNull()
+        vi.advanceTimersByTime(50)
+        expect(reassembler.pendingCount).toBe(0)
+        expect(reassembler.stats.timedOutMFUs).toBe(1)
+      } finally {
+        vi.useRealTimers()
+      }
+    })
+
+    test('retimes retained continuations when the timeout policy changes', () => {
+      vi.useFakeTimers()
+      try {
+        const enabled = new MFUReassembler({ timeoutMs: null, maxBuffered: 1 })
+        expect(enabled.addFragment({
+          fragmentationIndicator: 3, mpuSequenceNumber: 1,
+          fragmentCounter: 0, data: new Uint8Array([1]),
+          timestamp: 1000n, rapFlag: false,
+          packetSequenceNumber: testPacketSequence(1, 0),
+        })).toBeNull()
+        enabled.timeoutMs = 10
+        vi.advanceTimersByTime(10)
+        expect(enabled.pendingCount).toBe(0)
+
+        const disabled = new MFUReassembler({ timeoutMs: 10, maxBuffered: 1 })
+        expect(disabled.addFragment({
+          fragmentationIndicator: 3, mpuSequenceNumber: 2,
+          fragmentCounter: 0, data: new Uint8Array([2]),
+          timestamp: 1000n, rapFlag: false,
+          packetSequenceNumber: testPacketSequence(2, 0),
+        })).toBeNull()
+        disabled.timeoutMs = null
+        vi.advanceTimersByTime(10)
+        expect(disabled.pendingCount).toBe(1)
+        disabled.flush()
+      } finally {
+        vi.useRealTimers()
+      }
+    })
+
+    test('bounds active data units and rejects a new first at maxBuffered', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000, maxBuffered: 2 })
+
+      // Two runs remain active; the third first fragment is rejected.
+      for (let i = 0; i < 2; i++) {
+        reassembler.addFragment({
+          fragmentationIndicator: 1, mpuSequenceNumber: i,
+          fragmentCounter: 1, itemId: i, data: new Uint8Array([i]),
+          timestamp: BigInt(i * 100), rapFlag: false,
+          packetSequenceNumber: testPacketSequence(i, 1),
+        })
+      }
+      expectRejection(() => reassembler.addFragment({
+        fragmentationIndicator: 1, mpuSequenceNumber: 2,
+        fragmentCounter: 1, itemId: 2, data: new Uint8Array([2]),
+        timestamp: 200n, rapFlag: false,
+        packetSequenceNumber: testPacketSequence(2, 1),
+      }), 'active-data-unit-limit')
+      expect(reassembler.pendingCount).toBe(2)
+      expect(reassembler.stats.timedOutMFUs).toBe(0)
+      expect(reassembler.stats.evictedMemoryLimit).toBe(0)
+    })
+
+    test('should report stats correctly', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+
+      // One complete MFU
+      reassembler.addFragment({
+        fragmentationIndicator: 0, mpuSequenceNumber: 1,
+        fragmentCounter: 0, itemId: 1, data: new Uint8Array([1]),
+        timestamp: 1000n, rapFlag: false,
+      })
+
+      const status = reassembler.getStatus()
+      expect(status.bufferedMFUs).toBe(0)
+      expect(status.stats.totalFragments).toBe(1)
+      expect(status.stats.reassembledMFUs).toBe(1)
+    })
+
+    test('rejects an overlapping first without replacing the original fragment', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+
+      reassembler.addFragment({
+        fragmentationIndicator: 1, mpuSequenceNumber: 1,
+        fragmentCounter: 1, itemId: 1, data: new Uint8Array([0xAA]),
+        timestamp: 1000n, rapFlag: true, source: 'multicast',
+        packetSequenceNumber: testPacketSequence(1, 1),
+      })
+      // Duplicate of fragmentCounter=1
+      expectRejection(() => reassembler.addFragment({
+        fragmentationIndicator: 1, mpuSequenceNumber: 1,
+        fragmentCounter: 1, itemId: 2, data: new Uint8Array([0xBB]),
+        timestamp: 1000n, rapFlag: true, source: 'moq',
+        packetSequenceNumber: testPacketSequence(1, 1),
+      }), 'overlapping-data-unit')
+
+      const result = reassembler.addFragment({
+        fragmentationIndicator: 3, mpuSequenceNumber: 1,
+        fragmentCounter: 0, data: new Uint8Array([0xCC]),
+        timestamp: 1000n, rapFlag: false,
+        packetSequenceNumber: testPacketSequence(1, 0),
+      })
+      expect(result).not.toBeNull()
+      expect(result!.data).toEqual(new Uint8Array([0xAA, 0xCC]))
+      expect(result!.fragmentCount).toBe(2)
+      expect(result!.source).toBe('multicast')
+    })
+  })
+
+    test('should retain an assembly with a gap in fragment counters', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+
+      // First fragment declares three succeeding payloads.
+      reassembler.addFragment({
+        fragmentationIndicator: 1, mpuSequenceNumber: 1,
+        fragmentCounter: 3, itemId: 1, data: new Uint8Array([0xAA]),
+        timestamp: 1000n, rapFlag: true,
+        packetSequenceNumber: testPacketSequence(1, 3),
+      })
+      // Counter 1 arrives while counter 2 is missing.
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 2, mpuSequenceNumber: 1,
+        fragmentCounter: 1, data: new Uint8Array([0xCC]),
+        timestamp: 1000n, rapFlag: false,
+        packetSequenceNumber: testPacketSequence(1, 1),
+      })).toBeNull()
+      // Last fragment has the required zero counter.
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 3, mpuSequenceNumber: 1,
+        fragmentCounter: 0, data: new Uint8Array([0xDD]),
+        timestamp: 1000n, rapFlag: false,
+        packetSequenceNumber: testPacketSequence(1, 0),
+      })).toBeNull()
+      expect(reassembler.pendingCount).toBe(1)
+      expect(reassembler.getStatus().pendingFragments).toBe(3)
+    })
+
+    test('accepts a reordered countdown and rejects a stale duplicate', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+
+      // Counters 3, 1, 0 arrive (gap at 2).
+      reassembler.addFragment({
+        fragmentationIndicator: 1, mpuSequenceNumber: 1,
+        fragmentCounter: 3, itemId: 1, data: new Uint8Array([0xAA]),
+        timestamp: 1000n, rapFlag: true,
+        packetSequenceNumber: testPacketSequence(1, 3),
+      })
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 2, mpuSequenceNumber: 1,
+        fragmentCounter: 1, data: new Uint8Array([0xCC]),
+        timestamp: 1000n, rapFlag: false,
+        packetSequenceNumber: testPacketSequence(1, 1),
+      })).toBeNull()
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 2, mpuSequenceNumber: 1,
+        fragmentCounter: 2, data: new Uint8Array([0xBB]),
+        timestamp: 1000n, rapFlag: false,
+        packetSequenceNumber: testPacketSequence(1, 2),
+      })).toBeNull()
+      expectRejection(() => reassembler.addFragment({
+        fragmentationIndicator: 2, mpuSequenceNumber: 1,
+        fragmentCounter: 1, data: new Uint8Array([0xCC]),
+        timestamp: 1001n, rapFlag: false,
+        packetSequenceNumber: testPacketSequence(1, 1),
+      }), 'fragment-counter-mismatch')
+      const result = reassembler.addFragment({
+        fragmentationIndicator: 3, mpuSequenceNumber: 1,
+        fragmentCounter: 0, data: new Uint8Array([0xDD]),
+        timestamp: 1002n, rapFlag: false,
+        packetSequenceNumber: testPacketSequence(1, 0),
+      })
+      expect(result).not.toBeNull()
+      expect(result!.data).toEqual(new Uint8Array([0xAA, 0xBB, 0xCC, 0xDD]))
+      expect(result!.fragmentCount).toBe(4)
+    })
+
+    test('rejects an overlapping first without discarding queued continuations', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      const fragment = (
+        fragmentationIndicator: number,
+        fragmentCounter: number,
+        byte: number,
+      ): MFUFragment => ({
+        fragmentationIndicator,
+        mpuSequenceNumber: 2,
+        fragmentCounter,
+        data: new Uint8Array([byte]),
+        timestamp: 1000n,
+        rapFlag: fragmentationIndicator === 1,
+        packetSequenceNumber: testPacketSequence(2, fragmentCounter),
+        ...(fragmentationIndicator === 1 ? { itemId: 9 } : {}),
+      })
+
+      expect(reassembler.addFragment(fragment(1, 3, 0xAA))).toBeNull()
+      expect(reassembler.addFragment(fragment(2, 1, 0xCC))).toBeNull()
+      expectRejection(
+        () => reassembler.addFragment(fragment(1, 1, 0xEE)),
+        'overlapping-data-unit',
+      )
+      expect(reassembler.addFragment(fragment(2, 2, 0xBB))).toBeNull()
+      expect(reassembler.addFragment(fragment(3, 0, 0xDD))?.data).toEqual(
+        new Uint8Array([0xAA, 0xBB, 0xCC, 0xDD]),
+      )
+    })
+
+    test('rejects a duplicate emitted intrinsic identity', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 1, mpuSequenceNumber: 42,
+        fragmentCounter: 1, itemId: 1, data: new Uint8Array([0xAA]),
+        timestamp: 1000n, rapFlag: true,
+        packetSequenceNumber: testPacketSequence(42, 1),
+      })).toBeNull()
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 3, mpuSequenceNumber: 42,
+        fragmentCounter: 0, data: new Uint8Array([0xAB]),
+        timestamp: 1001n, rapFlag: false,
+        packetSequenceNumber: testPacketSequence(42, 0),
+      })).not.toBeNull()
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 3, mpuSequenceNumber: 42,
+        fragmentCounter: 0, data: new Uint8Array([0xBC]),
+        timestamp: 1002n, rapFlag: false,
+        packetSequenceNumber: testPacketSequence(42, 0, 10),
+      })).toBeNull()
+      expect(reassembler.pendingCount).toBe(1)
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 1, mpuSequenceNumber: 42,
+        fragmentCounter: 1, itemId: 1, data: new Uint8Array([0xBB]),
+        timestamp: 2000n, rapFlag: true,
+        packetSequenceNumber: testPacketSequence(42, 1, 10),
+      })).toBeNull()
+      expect(reassembler.pendingCount).toBe(0)
+
+      const result = reassembler.addFragment({
+        fragmentationIndicator: 1, mpuSequenceNumber: 43,
+        fragmentCounter: 1, itemId: 1, data: new Uint8Array([0xCC]),
+        timestamp: 2000n, rapFlag: false,
+        packetSequenceNumber: testPacketSequence(43, 1),
+      })
+      expect(result).toBeNull()
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 3, mpuSequenceNumber: 43,
+        fragmentCounter: 0, data: new Uint8Array([0xDD]),
+        timestamp: 2001n, rapFlag: false,
+        packetSequenceNumber: testPacketSequence(43, 0),
+      })?.data).toEqual(new Uint8Array([0xCC, 0xDD]))
+    })
+
+    test('does not create active state for an emitted identity duplicate', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 1,
+        mpuSequenceNumber: 50,
+        fragmentCounter: 1,
+        movieFragmentSequenceNumber: 10,
+        sampleNumber: 18,
+        sampleOffset: 0,
+        data: new Uint8Array([0xa1]),
+        timestamp: 1000n,
+        rapFlag: true,
+        packetSequenceNumber: testPacketSequence(50, 1),
+      })).toBeNull()
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 3,
+        mpuSequenceNumber: 50,
+        fragmentCounter: 0,
+        data: new Uint8Array([0xb2]),
+        timestamp: 1000n,
+        rapFlag: false,
+        packetSequenceNumber: testPacketSequence(50, 0),
+      })?.data).toEqual(new Uint8Array([0xa1, 0xb2]))
+      expect(reassembler.pendingCount).toBe(0)
+
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 1,
+        mpuSequenceNumber: 50,
+        fragmentCounter: 1,
+        movieFragmentSequenceNumber: 10,
+        sampleNumber: 18,
+        sampleOffset: 0,
+        data: new Uint8Array([0xa1]),
+        timestamp: 2000n,
+        rapFlag: true,
+        packetSequenceNumber: testPacketSequence(50, 1, 10),
+      })).toBeNull()
+      expect(reassembler.pendingCount).toBe(0)
+    })
+
+    test('flush should clear emitted set and allow re-assembly', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+
+      // Use fragmented MFU (FI=1 start + FI=3 end) — only fragmented MFUs
+      // go through the #emitted dedup set. FI=0 (complete) bypasses it.
+      const first = reassembler.addFragment({
+        fragmentationIndicator: 1, mpuSequenceNumber: 42,
+        fragmentCounter: 1, itemId: 1, data: new Uint8Array([0xAA]),
+        timestamp: 1000n, rapFlag: true,
+        packetSequenceNumber: testPacketSequence(42, 1),
+      })
+      expect(first).toBeNull() // first fragment, not yet complete
+      const assembled = reassembler.addFragment({
+        fragmentationIndicator: 3, mpuSequenceNumber: 42,
+        fragmentCounter: 0, data: new Uint8Array([0xBB]),
+        timestamp: 1000n, rapFlag: true,
+        packetSequenceNumber: testPacketSequence(42, 0),
+      })
+      expect(assembled).not.toBeNull() // complete — mpuSeq 42 now in emitted set
+
+      // Rejected before flush — same mpuSeq already emitted
+      expect(reassembler.addFragment({
+        fragmentationIndicator: 1, mpuSequenceNumber: 42,
+        fragmentCounter: 1, itemId: 1, data: new Uint8Array([0xCC]),
+        timestamp: 1000n, rapFlag: true,
+        packetSequenceNumber: testPacketSequence(42, 1, 10),
+      })).toBeNull()
+
+      // After flush, same mpuSeq should work again
+      reassembler.flush()
+      const r2 = reassembler.addFragment({
+        fragmentationIndicator: 1, mpuSequenceNumber: 42,
+        fragmentCounter: 1, itemId: 1, data: new Uint8Array([0xDD]),
+        timestamp: 1000n, rapFlag: true,
+        packetSequenceNumber: testPacketSequence(42, 1),
+      })
+      expect(r2).toBeNull() // first fragment of new assembly
+      const r3 = reassembler.addFragment({
+        fragmentationIndicator: 3, mpuSequenceNumber: 42,
+        fragmentCounter: 0, data: new Uint8Array([0xEE]),
+        timestamp: 1000n, rapFlag: true,
+        packetSequenceNumber: testPacketSequence(42, 0),
+      })
+      expect(r3).not.toBeNull()
+      expect(r3!.data).toEqual(new Uint8Array([0xDD, 0xEE]))
+    })
+
+  describe('createFragment', () => {
+    test('should create fragment from complete timed MMTP packet', () => {
+      // Build: MMTP(12) + MPU(8, T=1 FI=0 payloadLength=25) + MFU_DU(14) + data(5)
+      const packet = new Uint8Array(12 + 8 + 14 + 5)
+      // MMTP header: byte0 = rap=1, byte1 = MPU type
+      packet[0] = 0x01 // RAP flag set
+      packet[1] = 0x00 // packet_type = MPU
+      // packetId = 1
+      const view = new DataView(packet.buffer)
+      view.setUint16(2, 1, false)
+      view.setUint32(4, 42, false) // timestamp
+      view.setUint32(8, 100, false) // sequence number
+
+      // MPU header at offset 12
+      view.setUint16(12, 25, false) // 6 remaining MPU bytes + 14 DU + 5 media
+      packet[14] = 0x28 // FT=2, T=1, FI=0, A=0
+      packet[15] = 0    // fragment_counter
+      view.setUint32(16, 999, false) // mpuSequenceNumber
+
+      // MFU DU header (14 bytes) at offset 20.
+      view.setUint32(20, 7, false) // movie_fragment_sequence_number
+      view.setUint32(24, 1, false) // sample_number
+      // Video data at offset 34
+      packet[34] = 0xDE; packet[35] = 0xAD; packet[36] = 0xBE
+      packet[37] = 0xEF; packet[38] = 0x01
+
+      const frag = createFragment(packet)
+      expect(frag.mpuSequenceNumber).toBe(999)
+      expect(frag.fragmentationIndicator).toBe(0)
+      expect(frag.rapFlag).toBe(true)
+      expect(frag.movieFragmentSequenceNumber).toBe(7)
+      expect(frag.sampleNumber).toBe(1)
+      expect(frag.sampleOffset).toBe(0)
+      expect(frag.data.length).toBe(5) // 5 bytes of video data
+    })
+
+    test('reads Item_ID from a non-timed MFU DU header', () => {
+      const packet = new Uint8Array(12 + 8 + 4 + 2)
+      const view = new DataView(packet.buffer)
+      view.setUint16(2, 1, false)
+      view.setUint32(4, 42, false)
+      view.setUint32(8, 100, false)
+      view.setUint16(12, 12, false) // 6 remaining MPU bytes + 4 DU + 2 media
+      packet[14] = 0x20 // FT=2, T=0, FI=0
+      view.setUint32(16, 999, false)
+      view.setUint32(20, 0x01020304, false)
+      packet.set([0xde, 0xad], 24)
+
+      const fragment = createFragment(packet)
+      expect(fragment.itemId).toBe(0x01020304)
+      expect(fragment.data).toEqual(new Uint8Array([0xde, 0xad]))
+    })
+  })
+
+  describe('processMMTPWithReassembly', () => {
+    test('should skip FEC repair packets', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      const packet = new Uint8Array(12 + 8 + 14 + 4)
+      packet[0] = 0x10 // fecType=2 (repair)
+      const result = processMMTPWithReassembly(packet, reassembler)
+      expect(result).toBeNull()
+    })
+
+    test('should return reassembled MFU for complete packet', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      const packet = new Uint8Array(12 + 8 + 14 + 4)
+      packet[0] = 0x01 // RAP
+      packet[1] = 0x00 // MPU
+      const view = new DataView(packet.buffer)
+      view.setUint16(2, 1, false) // packetId
+      view.setUint32(4, 100, false) // timestamp
+      view.setUint32(8, 1, false) // seq
+      // MPU: payloadLength=24 (6 + 14 + 4), FT=2 T=1 FI=0 A=0
+      view.setUint16(12, 24, false)
+      packet[14] = 0x28
+      view.setUint32(16, 42, false) // mpuSeq
+      view.setUint32(20, 7, false) // movie_fragment_sequence_number
+      view.setUint32(24, 1, false) // sample_number
+
+      packet[34] = 0x00; packet[35] = 0x00; packet[36] = 0x00; packet[37] = 0x01
+
+      const result = processMMTPWithReassembly(packet, reassembler)
+      expect(result).not.toBeNull()
+      expect(result!.mpuSequenceNumber).toBe(42)
+      expect(result!.rapFlag).toBe(true)
+    })
+  })
+
+  describe('strict delivery provenance', () => {
+    test('folds to multicast only when every fragment is explicitly multicast', () => {
+      expect(deliveryProvenanceOf([{ source: 'multicast' }, { source: 'multicast' }]))
+        .toBe('multicast')
+    })
+
+    test('a single moq fragment makes the whole frame mixed', () => {
+      expect(deliveryProvenanceOf([{ source: 'multicast' }, { source: 'moq' }]))
+        .toBe('mixed')
+      // ...and it does not matter where in the run it lands.
+      expect(deliveryProvenanceOf([{ source: 'moq' }, { source: 'multicast' }]))
+        .toBe('mixed')
+    })
+
+    test('an unattributed fragment degrades multicast to unknown, never to proven', () => {
+      expect(deliveryProvenanceOf([{ source: 'multicast' }, {}])).toBe('unknown')
+      expect(deliveryProvenanceOf([{}])).toBe('unknown')
+    })
+
+    test('mixed absorbs unknown — a moq byte is worse news than a missing label', () => {
+      expect(deliveryProvenanceOf([{ source: 'moq' }, {}])).toBe('mixed')
+      expect(deliveryProvenanceOf([{}, { source: 'moq' }])).toBe('mixed')
+    })
+
+    test('an empty fragment set proves nothing', () => {
+      expect(deliveryProvenanceOf([])).toBe('unknown')
+    })
+
+    test('the fold never upgrades a verdict', () => {
+      expect(foldDeliveryProvenance('mixed', 'multicast')).toBe('mixed')
+      expect(foldDeliveryProvenance('unknown', 'multicast')).toBe('unknown')
+      expect(foldDeliveryProvenance('unknown', 'moq')).toBe('mixed')
+    })
+
+    test('a multicast head with a non-multicast tail is NOT multicast-exclusive', () => {
+      // This is the leak this field exists to close. `source` legitimately
+      // reports 'multicast' — head-fragment-wins is the routing contract —
+      // but the frame contains bytes that never crossed a multicast socket,
+      // so it must never be counted as physical-delivery evidence.
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      reassembler.addFragment({
+        fragmentationIndicator: 1, mpuSequenceNumber: 1,
+        fragmentCounter: 1, itemId: 1, data: new Uint8Array([0xAA]),
+        timestamp: 1000n, rapFlag: true, source: 'multicast',
+        packetSequenceNumber: testPacketSequence(1, 1),
+      })
+      const result = reassembler.addFragment({
+        fragmentationIndicator: 3, mpuSequenceNumber: 1,
+        fragmentCounter: 0, data: new Uint8Array([0xCC]),
+        timestamp: 1000n, rapFlag: false, source: 'moq',
+        packetSequenceNumber: testPacketSequence(1, 0),
+      })
+      expect(result).not.toBeNull()
+      expect(result!.fragmentCount).toBe(2)
+      expect(result!.source).toBe('multicast')
+      expect(result!.deliveryProvenance).toBe('mixed')
+    })
+
+    test('an all-multicast fragmented frame is multicast-exclusive', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      reassembler.addFragment({
+        fragmentationIndicator: 1, mpuSequenceNumber: 2,
+        fragmentCounter: 1, itemId: 1, data: new Uint8Array([0xAA]),
+        timestamp: 2000n, rapFlag: true, source: 'multicast',
+        packetSequenceNumber: testPacketSequence(2, 1),
+      })
+      const result = reassembler.addFragment({
+        fragmentationIndicator: 3, mpuSequenceNumber: 2,
+        fragmentCounter: 0, data: new Uint8Array([0xCC]),
+        timestamp: 2000n, rapFlag: false, source: 'multicast',
+        packetSequenceNumber: testPacketSequence(2, 0),
+      })
+      expect(result).not.toBeNull()
+      expect(result!.deliveryProvenance).toBe('multicast')
+    })
+
+    test('an unlabelled complete frame proves nothing', () => {
+      const reassembler = new MFUReassembler({ timeoutMs: 1000 })
+      const result = reassembler.addFragment({
+        fragmentationIndicator: 0, mpuSequenceNumber: 3,
+        fragmentCounter: 0, itemId: 1, data: new Uint8Array([1]),
+        timestamp: 3000n, rapFlag: true,
+      })
+      expect(result).not.toBeNull()
+      expect(result!.deliveryProvenance).toBe('unknown')
+    })
+  })
+}