@blockcast/mmt-container 0.1.0-main.09c5546569f1

package/src/mmtp-container-parser.ts

@@ -0,0 +1,1510 @@
+import {
+  parseMMTPHeader,
+  extractMFUPayload,
+  extractFecPayloadId,
+  hasSourceFecPayloadId,
+  extractAltaTrailer,
+  PACKET_TYPE_MPU,
+  PACKET_TYPE_REPAIR,
+} from '@blockcast/mmt-base'
+import {
+  MFUReassembler,
+  MfuReassemblyError,
+  type MfuReassemblerBackend,
+  type MmtpSourcePath,
+  type MmtpDeliveryProvenance,
+  type ReassembledMFU,
+} from './mfu-reassembler.js'
+import {
+  SampleCombiner,
+  SampleCombineError,
+  type CombinedSample,
+  type SampleCombinerOptions,
+  type SampleCombinerStats,
+} from './sample-combiner.js'
+import {
+  classifyH264Keyframe,
+  mmtpTimestampToMicros,
+  normalizeMmtpInitSegment,
+} from './codec-utils.js'
+import {
+  mmtpFrameReorderWindowFrames,
+  mfuReassemblyTimeoutMs,
+  type MfuReassemblyPolicy,
+} from './mfu-reassembly-policy.js'
+import {
+  IsoBmffTimingResolver,
+  mediaTicksToMicroseconds,
+  type IsoBmffSampleTiming,
+} from './iso-bmff-timing.js'
+import type { AuthoredTiming } from './authored-timing.js'
+
+// ── Types ───────────────────────────────────────────────────────────
+
+export interface TrackInfo {
+  type: 'video' | 'audio'
+  codec: string
+  /** Catalog/in-band frame cadence available to downstream media stages. */
+  framerate?: number
+  /** Catalog MMTP group duration available to downstream media stages. */
+  groupDurationMs?: number
+}
+
+export interface MmtpParserConfig {
+  tracks?: Map<number, TrackInfo>
+  reorderWindow?: number
+  /** MFU reassembly timeout (ms). Derive from FEC interleaveDepthMs or frame duration.
+   *  Pass null for live clock-free operation; memory remains bounded by maxBuffered.
+   *  Defaults to 1000ms if not provided. */
+  mfuTimeoutMs?: number | null
+  /** Explicit transport policy. Reliable MoQ is clock-free; datagrams require
+   * a catalog/in-band-derived deadline. Mutually exclusive with mfuTimeoutMs. */
+  reassemblyPolicy?: MfuReassemblyPolicy
+  /** Max concurrent active MFUs. A new first fragment is rejected at the bound. */
+  maxBufferedMfus?: number
+  /**
+   * Max subsample data units held for one partitioned sample (moqcast #37).
+   * A sample needs `ceil(sampleSize / (256 * maxPayload))` data units; at the
+   * ~1300-byte payloads this producer emits, one data unit spans ~327 KB, so
+   * the default admits a ~5 MB sample — beyond any 8K intra frame — while
+   * still bounding the per-insert overlap scan. Raise it only alongside a
+   * larger authored frame size, never to paper over a lost data unit.
+   */
+  maxSubsampleSegments?: number
+  /** Alternate backend. The TypeScript and Rust/WASM implementations enforce
+   * the same authored active-DU contract. */
+  reassembler?: MfuReassemblerBackend
+  /** Default track info for auto-discovered packetIds.
+   *  When the parser receives an MMTP packet with an unregistered packetId,
+   *  it creates a new track entry using this info. Required for correct
+   *  keyframe detection with HEVC/AV1/VP9 (without it, defaults to H.264). */
+  defaultTrack?: TrackInfo
+}
+
+/** Structured result from parseHeader(). Used by MmtpRouter for two-phase parsing:
+ *  1. parseHeader() → get packetId + fecPayloadId for FEC feeding
+ *  2. feed() → MFU extraction, reassembly, keyframe detection, emit */
+export interface PacketInfo {
+  packetId: number
+  packetType: number
+  timestamp: bigint
+  /** MMTP timestamp converted to monotonic microseconds for pacing/sync users. */
+  timestampUs: number
+  sequenceNumber: number
+  rapFlag: boolean
+  fecType: number
+  /** FEC source symbol ID (from 4-byte FEC Payload ID at packet end). Null if no FEC. */
+  fecPayloadId: { ssId: number } | null
+  /** True if this is a repair packet (packetType=0x03). */
+  isRepair: boolean
+}
+
+export interface FrameMeta {
+  /** Authored ISO-BMFF presentation time converted to microseconds. */
+  timestamp: number
+  /** Authored ISO-BMFF decode time converted to microseconds. */
+  decodeTimestamp?: number
+  /** Authored ISO-BMFF sample duration converted to microseconds. */
+  duration?: number
+  /** Exact authored decode time in mediaTimescale units. */
+  decodeTime?: bigint
+  /** Exact authored presentation time in mediaTimescale units. */
+  presentationTime?: bigint
+  /** Exact authored duration in mediaTimescale units. */
+  durationTicks?: number
+  /** mdhd media timescale for the exact timing fields. */
+  mediaTimescale?: number
+  /** Exact authored ISO-BMFF timing carried without narrowing to microseconds. */
+  authoredTiming?: AuthoredTiming
+  keyframe: boolean
+  packetId: number
+  trackType: 'video' | 'audio' | null
+  packetSequenceNumber?: number
+  /** Every authoritative MMTP source-packet sequence that formed this frame. */
+  packetSequenceNumbers?: number[]
+  /** Subset of packetSequenceNumbers reconstructed by FEC. */
+  repairedPacketSequenceNumbers?: number[]
+  /** Immutable catalog identity supplied by the owning ingress subscription. */
+  catalogTrackName?: string
+  /** Raw MMTP short-NTP timestamp retained for adapters that own the timeline. */
+  mmtpTimestamp?: bigint
+  mpuSequenceNumber?: number
+  movieFragmentSequenceNumber?: number
+  sampleNumber?: number
+  fragmentCount?: number
+  rapFlag?: boolean
+  priority?: number
+  recovered?: boolean
+  /** Starts a new publisher/source epoch for ordering and timestamp state. */
+  sourceDiscontinuity?: boolean
+  /** Source of the accepted FI=1/FI=0 frame path. Absent for recovery. */
+  source?: MmtpSourcePath
+  /**
+   * Strict whole-frame delivery provenance. Unlike `source`, which names the
+   * head fragment's transport for routing, this is folded over every
+   * contributing fragment (and, for FEC-recovered frames, over the transports
+   * that supplied the block's symbols). Only 'multicast' is evidence of
+   * multicast-exclusive delivery. Absent means no producer on this path
+   * recorded provenance — consumers MUST treat that as unproven, never as
+   * multicast.
+   */
+  deliveryProvenance?: MmtpDeliveryProvenance
+}
+
+export interface MmtpReorderStats {
+  droppedBeforeStartupKeyframe: number
+  droppedIncompleteStartupInterval: number
+  droppedStale: number
+  forcedWindowFlushes: number
+  droppedOnLiveDispose: number
+  publisherResets: number
+  droppedOnPublisherReset: number
+  bufferedFrames: number
+}
+
+export interface MmtpReorderFrameDiagnostics {
+  timestampUs: number
+  keyframe: boolean
+  sequenceNumber: number
+  packetSequenceNumber?: number
+  movieFragmentSequenceNumber?: number
+  sampleNumber?: number
+  fragmentCount?: number
+}
+
+export interface MmtpReorderStreamDiagnostics {
+  packetId: number
+  bufferedFrames: number
+  lastEmitted: MmtpReorderFrameDiagnostics | null
+  startupKeyframe: MmtpReorderFrameDiagnostics | null
+  head: MmtpReorderFrameDiagnostics[]
+  tail: MmtpReorderFrameDiagnostics[]
+  keyframes: MmtpReorderFrameDiagnostics[]
+}
+
+export type MmtpParserRecord =
+  | {
+      kind: 'repair' | 'non-media'
+      packet: PacketInfo
+      byteLength: number
+    }
+  | {
+      kind: 'init' | 'fragment'
+      packet: PacketInfo
+      data: Uint8Array
+      mpuSequenceNumber: number
+      fragmentationIndicator: number
+      fragmentCounter: number
+    }
+  | {
+      kind: 'pending'
+      packet: PacketInfo
+      mpuSequenceNumber: number
+      fragmentationIndicator: number
+      fragmentCounter: number
+    }
+  | {
+      kind: 'rejected'
+      packet: PacketInfo
+      mpuSequenceNumber: number
+      fragmentationIndicator: number
+      fragmentCounter: number
+      error: {
+        /**
+         * Either a single data unit's own fragment chain was rejected, or
+         * combining reassembled data units into a sample was (moqcast #37).
+         * Both are fail-closed drops of the same packet, so they share this
+         * record; the code says which class it came from.
+         */
+        code: MfuReassemblyError['code'] | SampleCombineError['code']
+        message: string
+      }
+    }
+  | {
+      kind: 'frame'
+      packet: PacketInfo
+      data: Uint8Array
+      meta: FrameMeta
+      mpuSequenceNumber: number
+      fragmentCount: number
+      rapFlag: boolean
+      priority?: number
+    }
+
+type FrameCallback = (data: Uint8Array, meta: FrameMeta) => void
+type InitCallback = (data: Uint8Array, packetId: number, catalogTrackName?: string) => void
+
+export function isMfuKeyframeMetadata(rapFlag: boolean, priority?: number): boolean {
+  return rapFlag || (priority ?? 0) > 0x80
+}
+
+/** Per-packet detached ALTA authenticator trailer (08-07 Path 2).
+ *  - `auth`: the authenticator bytes (length-prefixed at packet end).
+ *  - `payloadEnd`: byte offset within the source packet where signed
+ *     payload ends — consumers reconstruct `payload = packet[0..payloadEnd]`
+ *     for verify_detached. */
+export interface ParsedAltaTrailer {
+  auth: Uint8Array
+  payloadEnd: number
+}
+
+/** Source-symbol exposure for FEC consumers.
+ *
+ *  Fires from {@link MmtpContainerParser.feed} once per FEC-protected source
+ *  packet — after parseHeader confirms fec_payload_id is present, before MFU
+ *  extraction.
+ *
+ *  Arguments:
+ *  - `packetId`  – MMTP header `packet_id` (track identifier)
+ *  - `ssId`      – flat Source Symbol ID from the 4-byte fec_payload_id trailer
+ *  - `rawSymbol` – packet bytes minus the 4-byte fec_payload_id trailer.
+ *                  NOT zero-padded to FEC symbol size — consumer pads if needed
+ *                  (FEC symbol size is FEC-config, not parser-config).
+ *  - `alta`      – detached ALTA authenticator if present, else undefined
+ *
+ *  Designed so consumers (player, Shaka shim, upstream moqtail) can wire
+ *  source-symbol delivery to whatever FEC pipeline they own, without depending
+ *  on libmmt's MulticastManager/MmtpRouter/FECManager stack. */
+type SourceSymbolCallback = (
+  packetId: number,
+  ssId: number,
+  rawSymbol: Uint8Array,
+  alta: ParsedAltaTrailer | undefined,
+) => void
+
+export interface ParseHeaderOptions {
+  /** Recovered source symbols already had the trailing Source FEC Payload ID stripped. */
+  skipFecPayloadId?: boolean
+  /** Mark frames emitted from this packet as FEC-recovered. */
+  recovered?: boolean
+  /** Exact catalog track bound to this packet by its ingress subscription. */
+  catalogTrackName?: string
+  /** Source transport for parser-owned frame attribution. */
+  source?: MmtpSourcePath
+  /**
+   * Explicit strict provenance for the fragments this packet produces.
+   * The router sets it for FEC-recovered packets, which carry no `source`
+   * but whose FEC block's symbol provenance is known.
+   */
+  deliveryProvenance?: MmtpDeliveryProvenance
+}
+
+// ── FrameSequencer ──────────────────────────────────────────────────
+
+interface PendingFrame {
+  data: Uint8Array
+  meta: FrameMeta
+  seq: number
+}
+
+interface SequencerStream {
+  buf: PendingFrame[]
+  lastEmitted: PendingFrame | null
+}
+
+function reorderFrameDiagnostics(frame: PendingFrame): MmtpReorderFrameDiagnostics {
+  return {
+    timestampUs: frame.meta.timestamp,
+    keyframe: frame.meta.keyframe,
+    sequenceNumber: frame.seq,
+    ...(frame.meta.packetSequenceNumber === undefined
+      ? {}
+      : { packetSequenceNumber: frame.meta.packetSequenceNumber }),
+    ...(frame.meta.movieFragmentSequenceNumber === undefined
+      ? {}
+      : { movieFragmentSequenceNumber: frame.meta.movieFragmentSequenceNumber }),
+    ...(frame.meta.sampleNumber === undefined ? {} : { sampleNumber: frame.meta.sampleNumber }),
+    ...(frame.meta.fragmentCount === undefined
+      ? {}
+      : { fragmentCount: frame.meta.fragmentCount }),
+  }
+}
+
+type SequencerStat = Exclude<keyof MmtpReorderStats, 'bufferedFrames'>
+
+function serialSequenceDelta(a: number, b: number): number {
+  return (a - b) | 0
+}
+
+function compareFrameOrder(
+  a: PendingFrame,
+  b: PendingFrame,
+): number {
+  if (a.meta.decodeTime !== undefined && b.meta.decodeTime !== undefined &&
+      a.meta.mediaTimescale === b.meta.mediaTimescale) {
+    if (a.meta.decodeTime < b.meta.decodeTime) return -1
+    if (a.meta.decodeTime > b.meta.decodeTime) return 1
+  } else {
+    const decodeDelta = (a.meta.decodeTimestamp ?? a.meta.timestamp) -
+      (b.meta.decodeTimestamp ?? b.meta.timestamp)
+    if (decodeDelta !== 0) return decodeDelta
+  }
+  const movieDelta = serialSequenceDelta(
+    a.meta.movieFragmentSequenceNumber ?? 0,
+    b.meta.movieFragmentSequenceNumber ?? 0,
+  )
+  if (movieDelta !== 0) return movieDelta
+  const sampleDelta = (a.meta.sampleNumber ?? 0) - (b.meta.sampleNumber ?? 0)
+  return sampleDelta !== 0 ? sampleDelta : serialSequenceDelta(a.seq, b.seq)
+}
+
+class FrameSequencer {
+  #streams = new Map<number, SequencerStream>()
+  #windowSize: number
+  #emit: (data: Uint8Array, meta: FrameMeta) => void
+  #recordStat: (stat: SequencerStat, count?: number) => void
+
+  constructor(
+    windowSize: number,
+    emit: (data: Uint8Array, meta: FrameMeta) => void,
+    recordStat: (stat: SequencerStat, count?: number) => void = () => {},
+  ) {
+    this.#windowSize = windowSize
+    this.#emit = emit
+    this.#recordStat = recordStat
+  }
+
+  push(data: Uint8Array, meta: FrameMeta, seq: number): void {
+    if (this.#windowSize <= 0) {
+      this.#emit(data, meta)
+      return
+    }
+    const frame: PendingFrame = { data, meta: { ...meta }, seq }
+    const stream = this.#streamFor(meta.packetId)
+    if (meta.sourceDiscontinuity) {
+      this.#recordStat('publisherResets')
+      this.#recordStat('droppedOnPublisherReset', stream.buf.length)
+      stream.buf = []
+      stream.lastEmitted = null
+      frame.meta.sourceDiscontinuity = true
+    }
+    if (this.#isStale(stream, frame)) {
+      this.#recordStat('droppedStale')
+      return
+    }
+    if (meta.keyframe && stream.lastEmitted === null) {
+      // The first RAP establishes decoder sync. Discard any pre-RAP media and
+      // emit it immediately so startup does not pay the reorder-window delay.
+      this.#recordStat('droppedBeforeStartupKeyframe', stream.buf.length)
+      stream.buf = []
+      this.#emitFrame(stream, frame)
+      return
+    }
+    let lo = 0, hi = stream.buf.length
+    while (lo < hi) {
+      const mid = (lo + hi) >>> 1
+      if (compareFrameOrder(stream.buf[mid]!, frame) < 0) lo = mid + 1
+      else hi = mid
+    }
+    stream.buf.splice(lo, 0, frame)
+    while (stream.buf.length > this.#windowSize) this.#flushHead(stream)
+  }
+
+  flush(): void {
+    for (const packetId of [...this.#streams.keys()].sort((a, b) => a - b)) {
+      const stream = this.#streams.get(packetId)
+      while (stream && stream.buf.length > 0) this.#flushHead(stream)
+    }
+  }
+
+  get buffered(): number {
+    let total = 0
+    for (const stream of this.#streams.values()) total += stream.buf.length
+    return total
+  }
+
+  get diagnostics(): Omit<MmtpReorderStreamDiagnostics, 'packetId'>[] {
+    return [...this.#streams.values()].map(stream => ({
+      bufferedFrames: stream.buf.length,
+      lastEmitted: stream.lastEmitted ? reorderFrameDiagnostics(stream.lastEmitted) : null,
+      startupKeyframe: null,
+      head: stream.buf.slice(0, 4).map(reorderFrameDiagnostics),
+      tail: stream.buf.slice(-4).map(reorderFrameDiagnostics),
+      keyframes: stream.buf.filter(frame => frame.meta.keyframe).slice(0, 8)
+        .map(reorderFrameDiagnostics),
+    }))
+  }
+
+  discard(): void {
+    for (const stream of this.#streams.values()) {
+      this.#recordStat('droppedOnLiveDispose', stream.buf.length)
+      stream.buf = []
+    }
+    this.#streams.clear()
+  }
+
+  #streamFor(packetId: number): SequencerStream {
+    let stream = this.#streams.get(packetId)
+    if (!stream) {
+      stream = { buf: [], lastEmitted: null }
+      this.#streams.set(packetId, stream)
+    }
+    return stream
+  }
+
+  #flushHead(stream: SequencerStream): boolean {
+    const f = stream.buf.shift()
+    if (!f) return false
+    return this.#emitFrame(stream, f)
+  }
+
+  #isStale(stream: SequencerStream, frame: PendingFrame): boolean {
+    return stream.lastEmitted !== null &&
+      compareFrameOrder(frame, stream.lastEmitted) <= 0
+  }
+
+  #emitFrame(stream: SequencerStream, frame: PendingFrame): boolean {
+    if (this.#isStale(stream, frame)) {
+      this.#recordStat('droppedStale')
+      return false
+    }
+    stream.lastEmitted = frame
+    this.#emit(frame.data, frame.meta)
+    return true
+  }
+}
+
+// ── fMP4 box detection ──────────────────────────────────────────────
+
+const FMPU_BOX_TYPES = new Set(['ftyp', 'moov', 'moof'])
+
+function isFmp4Box(data: Uint8Array): boolean {
+  if (data.length < 8) return false
+  const type = String.fromCharCode(data[4]!, data[5]!, data[6]!, data[7]!)
+  return FMPU_BOX_TYPES.has(type)
+}
+
+interface TimingStreamState {
+  packetId: number
+  resolver: IsoBmffTimingResolver
+}
+
+// ── MmtpContainerParser ─────────────────────────────────────────────
+
+export class MmtpContainerParser {
+  #tracks = new Map<number, TrackInfo>()
+  #defaultTrack: TrackInfo | null = null
+  #reassembler: MfuReassemblerBackend
+  /**
+   * Combines subsample data units back into whole samples (moqcast #37), one
+   * combiner per parser stream. Per-stream is required, not an optimization:
+   * {@link SampleCombiner} identifies a sample by
+   * `(catalogTrackName, mpu, movieFragment, sampleNumber)`, so two streams
+   * that carry no catalog identity would collide on every sample number and
+   * each would see the other's data units as duplicates of its own. The
+   * parser already isolates timing and reordering by this same stream key.
+   *
+   * Inert until a producer partitions — which it does the moment a frame
+   * exceeds one data unit's 256-payload capacity (~327 KB here, routinely
+   * exceeded by 4K/8K intra frames).
+   */
+  #sampleCombiners = new Map<string, SampleCombiner>()
+  #sampleCombinerOptions: SampleCombinerOptions
+  /** Counters folded in from combiners dropped by a track reset, so the
+   *  totals below stay monotonic across a publisher change. */
+  #retiredSampleCombinerStats: SampleCombinerStats = {
+    combinedSamples: 0,
+    passthroughSamples: 0,
+    timedOutSamples: 0,
+    evictedSamples: 0,
+  }
+  #timingStreams = new Map<string, TimingStreamState>()
+  #maxPendingTimingSamples: number
+  #pendingTimingSamples = 0
+  #sequencers = new Map<string, { packetId: number; sequencer: FrameSequencer }>()
+  #reorderWindow = 0
+  #reassemblyPolicy: MfuReassemblyPolicy | null = null
+  #frameCb: FrameCallback | null = null
+  #initCb: InitCallback | null = null
+  #sourceSymbolCb: SourceSymbolCallback | null = null
+  #trackFrameCbs = new Map<number, FrameCallback>()
+  #reorderStats: Omit<MmtpReorderStats, 'bufferedFrames'> = {
+    droppedBeforeStartupKeyframe: 0,
+    droppedIncompleteStartupInterval: 0,
+    droppedStale: 0,
+    forcedWindowFlushes: 0,
+    droppedOnLiveDispose: 0,
+    publisherResets: 0,
+    droppedOnPublisherReset: 0,
+  }
+  /** Streams (keyed by physical parser stream, value is packetId) that have
+   *  observed their first RAP under a reliable-moq policy. Reliable MoQ
+   *  resolves to a zero parser reorder window (transport ordering is
+   *  protocol-owned), so #sequencerFor returns null and its own startup gate
+   *  never runs; this map preserves an order-independent "discard delta
+   *  frames before the first RAP" gate for that path without reintroducing
+   *  reordering into the parser. */
+  #reliableMoqStartupGate = new Map<string, number>()
+  #disposed = false
+
+  #streamKey(packetId: number, catalogTrackName?: string): string {
+    return JSON.stringify([packetId, catalogTrackName ?? null])
+  }
+
+  #sampleCombinerFor(streamKey: string): SampleCombiner {
+    let combiner = this.#sampleCombiners.get(streamKey)
+    if (combiner === undefined) {
+      combiner = new SampleCombiner(this.#sampleCombinerOptions)
+      this.#sampleCombiners.set(streamKey, combiner)
+    }
+    return combiner
+  }
+
+  /** Drop one stream's combiner, folding its counters into the retained
+   *  totals so a reset cannot make the exposed stats run backwards. */
+  #dropSampleCombiner(streamKey: string): void {
+    const combiner = this.#sampleCombiners.get(streamKey)
+    if (combiner === undefined) return
+    const stats = combiner.stats
+    this.#retiredSampleCombinerStats.combinedSamples += stats.combinedSamples
+    this.#retiredSampleCombinerStats.passthroughSamples += stats.passthroughSamples
+    this.#retiredSampleCombinerStats.timedOutSamples += stats.timedOutSamples
+    this.#retiredSampleCombinerStats.evictedSamples += stats.evictedSamples
+    this.#sampleCombiners.delete(streamKey)
+  }
+
+  constructor(config?: MmtpParserConfig) {
+    if (config?.reassemblyPolicy && config.mfuTimeoutMs !== undefined) {
+      throw new Error('[MmtpContainerParser] use reassemblyPolicy or mfuTimeoutMs, not both')
+    }
+    const reassemblyPolicy = config?.reassemblyPolicy ?? null
+    const requestedReorderWindow = config?.reorderWindow ?? 0
+    if (!Number.isFinite(requestedReorderWindow) || requestedReorderWindow < 0) {
+      throw new Error('[MmtpContainerParser] reorderWindow must be a finite number >= 0')
+    }
+    const normalizedReorderWindow = Math.ceil(requestedReorderWindow)
+    const requestedMfuTimeout = reassemblyPolicy
+      ? mfuReassemblyTimeoutMs(reassemblyPolicy)
+      : config?.mfuTimeoutMs
+    if (reassemblyPolicy) {
+      mmtpFrameReorderWindowFrames(reassemblyPolicy, normalizedReorderWindow)
+    }
+    if (
+      requestedMfuTimeout !== undefined &&
+      requestedMfuTimeout !== null &&
+      requestedMfuTimeout <= 0
+    ) {
+      throw new Error('[MmtpContainerParser] mfuTimeoutMs must be > 0')
+    }
+    const maxPendingTimingSamples = config?.maxBufferedMfus ?? 100
+    if (!Number.isInteger(maxPendingTimingSamples) || maxPendingTimingSamples <= 0) {
+      throw new Error('[MmtpContainerParser] maxBufferedMfus must be a positive integer')
+    }
+    this.#maxPendingTimingSamples = maxPendingTimingSamples
+
+    const maxSubsampleSegments = config?.maxSubsampleSegments ?? 16
+    if (!Number.isInteger(maxSubsampleSegments) || maxSubsampleSegments <= 0) {
+      throw new Error('[MmtpContainerParser] maxSubsampleSegments must be a positive integer')
+    }
+
+    // Everything above only reads `config` — the full policy/window
+    // combination is validated before this point, so it is now safe to
+    // mutate this instance or an injected, caller-owned reassembler.
+    this.#reassemblyPolicy = reassemblyPolicy
+    if (config?.reassembler) {
+      this.#reassembler = config.reassembler
+      // An injected backend owns its existing transport policy unless this
+      // parser was given an explicit policy/legacy timeout override.
+      if (requestedMfuTimeout !== undefined) {
+        this.#reassembler.timeoutMs = requestedMfuTimeout
+      }
+    } else {
+      this.#reassembler = new MFUReassembler({
+        timeoutMs: requestedMfuTimeout === undefined ? 1000 : requestedMfuTimeout,
+        ...(config?.maxBufferedMfus === undefined ? {} : { maxBuffered: config.maxBufferedMfus }),
+      })
+    }
+    this.#reorderWindow = normalizedReorderWindow
+    this.#sampleCombinerOptions = {
+      maxBuffered: maxPendingTimingSamples,
+      // The parser resolves every timed sample's authored size from FT=1
+      // before its data units reach the combiner, so "no size yet" always
+      // means the size has not arrived -- never that the host declines to
+      // supply one. Waiting is therefore correct: treating an offset-zero
+      // data unit as a whole sample in that window would truncate a
+      // partitioned sample instead of completing it.
+      requireAuthoredSize: true,
+      maxSegmentsPerSample: maxSubsampleSegments,
+    }
+    this.#defaultTrack = config?.defaultTrack ?? null
+    if (this.#defaultTrack) this.#validateReassemblyPolicy()
+    if (config?.tracks) {
+      for (const [id, info] of config.tracks) {
+        this.#validateReassemblyPolicy()
+        this.#tracks.set(id, info)
+      }
+    }
+  }
+
+  /** The MFU reassembler that buffers fragmented MFUs fed via feed().
+   *  Exposed so a co-operating FEC-recovery layer (MmtpRouter) feeds recovered
+   *  fragments into the SAME reassembler: a frame split between source-received
+   *  and FEC-recovered fragments must share one buffer to complete (BLO-8151).
+   *  Before this was shared, recovered video symbols reported "0 emitted,
+   *  pending-reassembly=N" because they landed in a separate instance. */
+  get reassembler(): MfuReassemblerBackend {
+    return this.#reassembler
+  }
+
+  /**
+   * Subsample-combining counters (moqcast #37). `combinedSamples` counts
+   * samples reassembled from two or more data units and `passthroughSamples`
+   * those that arrived whole; the two are deliberately separate, so a
+   * producer that silently stopped partitioning cannot hide behind a single
+   * "samples delivered" total. This is the typed acceptance signal for
+   * large-frame playback — never parse the console for it.
+   */
+  get sampleCombinerStats(): Readonly<SampleCombinerStats> {
+    const total = { ...this.#retiredSampleCombinerStats }
+    for (const combiner of this.#sampleCombiners.values()) {
+      const stats = combiner.stats
+      total.combinedSamples += stats.combinedSamples
+      total.passthroughSamples += stats.passthroughSamples
+      total.timedOutSamples += stats.timedOutSamples
+      total.evictedSamples += stats.evictedSamples
+    }
+    return total
+  }
+
+  get reorderStats(): Readonly<MmtpReorderStats> {
+    let bufferedFrames = 0
+    for (const { sequencer } of this.#sequencers.values()) bufferedFrames += sequencer.buffered
+    return { ...this.#reorderStats, bufferedFrames }
+  }
+
+  get reorderDiagnostics(): ReadonlyArray<MmtpReorderStreamDiagnostics> {
+    const streams: MmtpReorderStreamDiagnostics[] = []
+    for (const { packetId, sequencer } of this.#sequencers.values()) {
+      for (const diagnostics of sequencer.diagnostics) streams.push({ packetId, ...diagnostics })
+    }
+    return streams
+  }
+
+  /**
+   * Phase 1 of two-phase parsing. Returns structured header info for FEC feeding.
+   * Call this before feed() when you need to extract FEC payload ID and feed
+   * symbols to FECManager before MFU extraction.
+   * Returns null for malformed packets.
+   */
+  parseHeader(packet: Uint8Array, options?: ParseHeaderOptions): PacketInfo | null {
+    try {
+      const header = parseMMTPHeader(packet)
+      const isRepair = header.packetType === PACKET_TYPE_REPAIR
+      const fecPayloadId =
+        !options?.skipFecPayloadId &&
+        !isRepair && hasSourceFecPayloadId(packet)
+          ? extractFecPayloadId(packet)
+          : null
+      return {
+        packetId: header.packetId,
+        packetType: header.packetType,
+        timestamp: header.timestamp,
+        timestampUs: mmtpTimestampToMicros(header.timestamp),
+        sequenceNumber: header.sequenceNumber,
+        rapFlag: header.rapFlag,
+        fecType: header.fecType,
+        fecPayloadId,
+        isRepair,
+      }
+    } catch {
+      return null
+    }
+  }
+
+  /** Feed a complete MMTP packet. For two-phase use, call parseHeader() first. */
+  feed(packet: Uint8Array, options?: ParseHeaderOptions): MmtpParserRecord | null {
+    if (this.#disposed) return null
+
+    const info = this.parseHeader(packet, options)
+    if (!info) return null
+
+    if (info.packetType !== PACKET_TYPE_MPU) {
+      return {
+        kind: info.isRepair ? 'repair' : 'non-media',
+        packet: info,
+        byteLength: packet.byteLength,
+      }
+    }
+
+    // ── FEC source-symbol exposure ──
+    // Fire onSourceSymbol BEFORE MFU extraction so the consumer-side FEC
+    // pipeline (e.g. FecWorkerClient.feedSource) starts as early as possible.
+    // Source-only: parseHeader already gates fecPayloadId on !isRepair.
+    if (info.fecPayloadId !== null && this.#sourceSymbolCb) {
+      // Strip the 4-byte fec_payload_id trailer per ISO 23008-1 §C.5.2.
+      // Symbol-size zero-padding is the consumer's responsibility — FEC
+      // symbol size is a FEC-config concern, not a parser concern.
+      const rawSymbol = packet.subarray(0, packet.length - 4)
+      const altaTrailer = extractAltaTrailer(packet)
+      const alta = altaTrailer
+        ? { auth: altaTrailer.auth, payloadEnd: altaTrailer.signedEnd }
+        : undefined
+      try {
+        this.#sourceSymbolCb(info.packetId, info.fecPayloadId.ssId, rawSymbol, alta)
+      } catch {
+        // Source-symbol consumer threw — never block MFU extraction on
+        // FEC-pipeline errors. The frame path stays viable; the consumer
+        // is responsible for its own error surfacing.
+      }
+    }
+
+    const extraction = extractMFUPayload(packet, {
+      skipFecId: options?.skipFecPayloadId,
+    })
+    if (!extraction) return null
+
+    const { mpu, fragmentType, data, mfuDuHeader } = extraction
+    if (mpu.timedFlag !== 1) return null
+    const streamKey = this.#streamKey(info.packetId, options?.catalogTrackName)
+
+    if (fragmentType === 0) {
+      if (mpu.fragmentationIndicator !== 0 || mpu.fragmentCounter !== 0) return null
+      // ISO MMTP MPU metadata may carry an `mmpu` box between the ftyp and
+      // moov boxes.  That box is valid MMTP metadata but is not a legal
+      // top-level MSE initialization box. Normalize at the parser boundary so
+      // every container consumer (including MSE and rendition handoff paths)
+      // receives append-safe ftyp+moov bytes rather than having to remember
+      // this wire-format detail independently.
+      const normalizedInit = normalizeMmtpInitSegment(data)
+      if (!normalizedInit) return null
+      const resolver = this.#timingResolver(streamKey, info.packetId, true)
+      if (!resolver?.addInitialization(normalizedInit)) return null
+      this.#initCb?.(normalizedInit, info.packetId, options?.catalogTrackName)
+      return {
+        kind: 'init',
+        packet: info,
+        data: normalizedInit,
+        mpuSequenceNumber: mpu.mpuSequenceNumber,
+        fragmentationIndicator: mpu.fragmentationIndicator,
+        fragmentCounter: mpu.fragmentCounter,
+      }
+    }
+
+    if (fragmentType === 1) {
+      if (mpu.fragmentationIndicator !== 0 || mpu.fragmentCounter !== 0) return null
+      const resolver = this.#timingResolver(streamKey, info.packetId, false)
+      if (!resolver) return null
+      const pendingBefore = resolver.pendingSampleCount
+      const remaining = this.#maxPendingTimingSamples - this.#pendingTimingSamples
+      if (!resolver.addMovieFragment(mpu.mpuSequenceNumber, data, remaining)) return null
+      this.#pendingTimingSamples += resolver.pendingSampleCount - pendingBefore
+      return {
+        kind: 'fragment',
+        packet: info,
+        data,
+        mpuSequenceNumber: mpu.mpuSequenceNumber,
+        fragmentationIndicator: mpu.fragmentationIndicator,
+        fragmentCounter: mpu.fragmentCounter,
+      }
+    }
+    if (fragmentType !== 2) return null
+
+    const resolver = this.#timingResolver(streamKey, info.packetId, false)
+    if (!resolver) return null
+    if (!Number.isSafeInteger(data.byteLength) || data.byteLength <= 0) return null
+    if (mpu.fragmentationIndicator === 0 || mpu.fragmentationIndicator === 1) {
+      if (!mfuDuHeader || mfuDuHeader.movieFragmentSequenceNumber === 0 ||
+          mfuDuHeader.sampleNumber === 0) {
+        return null
+      }
+      const headTiming = resolver.sampleTiming(
+        mpu.mpuSequenceNumber,
+        mfuDuHeader.movieFragmentSequenceNumber,
+        mfuDuHeader.sampleNumber,
+      )
+      if (!headTiming) return null
+      // A data unit's authored base offset is its position within the sample
+      // (moqcast #37): 0 for a whole-sample DU, nonzero for one subsample DU
+      // among siblings. Sizes below are therefore relative to that base, not
+      // to the sample's start -- comparing a subsample DU against the whole
+      // sample's size is what dropped every partitioned 4K/8K frame.
+      const offset = mfuDuHeader.offset
+      if (!Number.isSafeInteger(offset) || offset < 0 || offset >= headTiming.size) return null
+      const remaining = headTiming.size - offset
+      // FI=0 carries its data unit whole, in a single payload. Only a
+      // partitioned sample's FINAL data unit can be shorter than a full data
+      // unit -- every earlier one spans exactly 256 payloads and so is always
+      // fragmented -- which makes a whole-carried DU exactly the bytes left
+      // from its base. At offset 0 this is the pre-amendment check unchanged.
+      if (mpu.fragmentationIndicator === 0 && data.byteLength !== remaining) return null
+      if (mpu.fragmentationIndicator === 1 && data.byteLength >= remaining) return null
+
+      // Publish the authored size before this data unit can complete, so the
+      // combiner never has to guess whether an offset-zero DU is a whole
+      // sample. Registering can itself complete a sample whose data units all
+      // arrived while the size was still unknown; that sample is delivered
+      // through routeFrame like any other, and this packet's own fragment
+      // continues below.
+      const readyOnRegister = this.#sampleCombinerFor(streamKey).registerAuthoredSize(
+        options?.catalogTrackName,
+        mpu.mpuSequenceNumber,
+        mfuDuHeader.movieFragmentSequenceNumber,
+        mfuDuHeader.sampleNumber,
+        headTiming.size,
+      )
+      if (readyOnRegister) {
+        this.#emitCombinedSample(readyOnRegister, info, resolver, options?.recovered === true)
+      }
+    }
+
+    let assembled: ReassembledMFU | null
+    try {
+      assembled = this.#reassembler.addFragment({
+        fragmentationIndicator: mpu.fragmentationIndicator,
+        mpuSequenceNumber: mpu.mpuSequenceNumber,
+        fragmentCounter: mpu.fragmentCounter,
+        data,
+        timestamp: info.timestamp,
+        rapFlag: info.rapFlag,
+        priority: mfuDuHeader?.priority,
+        sampleNumber: mfuDuHeader?.sampleNumber,
+        movieFragmentSequenceNumber: mfuDuHeader?.movieFragmentSequenceNumber,
+        sampleOffset: mfuDuHeader?.offset,
+        packetSequenceNumber: info.sequenceNumber,
+        recovered: options?.recovered === true,
+        source: options?.source,
+        deliveryProvenance: options?.deliveryProvenance,
+        catalogTrackName: options?.catalogTrackName,
+        packetId: info.packetId,
+      })
+    } catch (error) {
+      if (!(error instanceof MfuReassemblyError)) throw error
+      console.warn(
+        `[MmtpContainerParser] rejected MFU fragment: code=${error.code} ` +
+        `mpu=${mpu.mpuSequenceNumber} fi=${mpu.fragmentationIndicator} ` +
+        `counter=${mpu.fragmentCounter}`,
+      )
+      return {
+        kind: 'rejected',
+        packet: info,
+        mpuSequenceNumber: mpu.mpuSequenceNumber,
+        fragmentationIndicator: mpu.fragmentationIndicator,
+        fragmentCounter: mpu.fragmentCounter,
+        error: { code: error.code, message: error.message },
+      }
+    }
+
+    if (!assembled) {
+      return {
+        kind: 'pending',
+        packet: info,
+        mpuSequenceNumber: mpu.mpuSequenceNumber,
+        fragmentationIndicator: mpu.fragmentationIndicator,
+        fragmentCounter: mpu.fragmentCounter,
+      }
+    }
+
+    const movieFragmentSequenceNumber = assembled.movieFragmentSequenceNumber
+    const sampleNumber = assembled.sampleNumber
+    if (movieFragmentSequenceNumber === undefined || sampleNumber === undefined) return null
+    // Resolve authored timing BEFORE the combiner sees this data unit. An
+    // assembled data unit whose sample identity has no authored timing is not
+    // a sample this stream declared, so it must be dropped outright -- letting
+    // it buffer would occupy a combiner slot and could evict a legitimate
+    // partitioned sample waiting on a sibling.
+    if (!resolver.sampleTiming(
+      assembled.mpuSequenceNumber,
+      movieFragmentSequenceNumber,
+      sampleNumber,
+    )) return null
+    if (assembled.mpuSequenceNumber !== mpu.mpuSequenceNumber) return null
+
+    // One reassembled data unit is not necessarily one whole sample. A
+    // partitioned sample completes only once every sibling data unit has
+    // arrived and they are byte-adjacent from zero to the authored size; an
+    // unpartitioned sample passes straight through with no buffering.
+    let combined: CombinedSample | null
+    try {
+      combined = this.#sampleCombinerFor(streamKey).addMfu(assembled)
+    } catch (error) {
+      if (!(error instanceof SampleCombineError)) throw error
+      console.warn(
+        `[MmtpContainerParser] rejected subsample data unit: code=${error.code} ` +
+        `mpu=${assembled.mpuSequenceNumber} sample=${sampleNumber} ` +
+        `offset=${assembled.sampleOffset ?? 0}`,
+      )
+      return {
+        kind: 'rejected',
+        packet: info,
+        mpuSequenceNumber: mpu.mpuSequenceNumber,
+        fragmentationIndicator: mpu.fragmentationIndicator,
+        fragmentCounter: mpu.fragmentCounter,
+        error: { code: error.code, message: error.message },
+      }
+    }
+    if (!combined) {
+      return {
+        kind: 'pending',
+        packet: info,
+        mpuSequenceNumber: mpu.mpuSequenceNumber,
+        fragmentationIndicator: mpu.fragmentationIndicator,
+        fragmentCounter: mpu.fragmentCounter,
+      }
+    }
+
+    return this.#emitCombinedSample(combined, info, resolver, options?.recovered === true)
+  }
+
+  /**
+   * Deliver one combined sample: resolve its authored timing, build frame
+   * metadata, retire the timing entry, and route it. Shared by the ordinary
+   * completion path and by the rarer completion that falls out of registering
+   * an authored size for data units that arrived before it.
+   */
+  #emitCombinedSample(
+    combined: CombinedSample,
+    info: PacketInfo,
+    resolver: IsoBmffTimingResolver,
+    recovered: boolean,
+  ): MmtpParserRecord | null {
+    const timing = resolver.sampleTiming(
+      combined.mpuSequenceNumber,
+      combined.movieFragmentSequenceNumber,
+      combined.sampleNumber,
+    )
+    if (!timing) return null
+    // The combiner already completes against the registered authored size;
+    // re-checking here keeps the unpartitioned passthrough path fail-closed
+    // on the same invariant rather than trusting it by construction.
+    if (combined.data.byteLength !== timing.size) return null
+
+    const meta = this.#buildFrameMeta(
+      combined,
+      info.packetId,
+      info.sequenceNumber,
+      timing,
+      recovered,
+    )
+    if (!meta) return null
+    if (!resolver.consumeSample(
+      combined.mpuSequenceNumber,
+      combined.movieFragmentSequenceNumber,
+      combined.sampleNumber,
+      timing,
+    )) return null
+    this.#pendingTimingSamples--
+    this.routeFrame(combined.data, meta)
+    return {
+      kind: 'frame',
+      packet: info,
+      data: combined.data,
+      meta,
+      mpuSequenceNumber: combined.mpuSequenceNumber,
+      fragmentCount: combined.fragmentCount,
+      rapFlag: combined.rapFlag,
+      ...(combined.priority === undefined ? {} : { priority: combined.priority }),
+    }
+  }
+
+  onInit(cb: InitCallback): void {
+    this.#initCb = cb
+  }
+
+  onFrame(cb: FrameCallback): void {
+    this.#frameCb = cb
+  }
+
+  /** Register a per-packet FEC source-symbol callback. Fires for each MMTP
+   *  source MPU packet that carries a Source FEC Payload ID (ISO 23008-1 §C.5.2).
+   *
+   *  Consumer responsibilities:
+   *  - Zero-pad `rawSymbol` to the FEC `symbolSize` if shorter (FEC config is
+   *    out-of-band — typically from the CMSF catalog's `fec.symbolSize`).
+   *  - Decide oversized handling (rawSymbol.length > symbolSize is not FEC-
+   *    decodable; consumer typically skips that block's source-feed).
+   *  - Look up the right FEC consumer (e.g. FecWorkerClient) by packetId.
+   *
+   *  Designed for spec-clean reuse: Shaka, upstream moqtail, or any consumer
+   *  that uses MmtpContainerParser can wire FEC source delivery without
+   *  pulling in MulticastManager/MmtpRouter/FECManager. */
+  onSourceSymbol(cb: SourceSymbolCallback): void {
+    this.#sourceSymbolCb = cb
+  }
+
+  onTrackFrame(packetId: number, cb: FrameCallback): void {
+    this.#trackFrameCbs.set(packetId, cb)
+  }
+
+  setTrack(packetId: number, info: TrackInfo): void {
+    this.#validateReassemblyPolicy()
+    for (const [key, entry] of this.#sequencers) {
+      if (entry.packetId !== packetId) continue
+      entry.sequencer.flush()
+      this.#sequencers.delete(key)
+    }
+    for (const [key, state] of this.#timingStreams) {
+      if (state.packetId === packetId) this.#dropTimingStream(key)
+    }
+    for (const key of [...this.#sampleCombiners.keys()]) {
+      if ((JSON.parse(key) as [number, string | null])[0] === packetId) {
+        this.#dropSampleCombiner(key)
+      }
+    }
+    for (const [key, gatedPacketId] of this.#reliableMoqStartupGate) {
+      if (gatedPacketId === packetId) this.#reliableMoqStartupGate.delete(key)
+    }
+    this.#tracks.set(packetId, info)
+  }
+
+  /** Drop one physical stream's ordering and MFU state for retained replay. */
+  resetTrack(packetId: number, catalogTrackName: string): void {
+    if (!catalogTrackName) {
+      throw new Error('[MmtpContainerParser] catalogTrackName is required for track reset')
+    }
+    for (const [key, entry] of this.#sequencers) {
+      if (key !== this.#streamKey(packetId, catalogTrackName)) continue
+      entry.sequencer.discard()
+      this.#sequencers.delete(key)
+    }
+    const streamKey = this.#streamKey(packetId, catalogTrackName)
+    this.#dropTimingStream(streamKey)
+    this.#reliableMoqStartupGate.delete(streamKey)
+    this.#reassembler.resetStream(catalogTrackName)
+    // Drop half-combined samples too: a partitioned sample whose siblings
+    // straddle the reset would otherwise complete against a stale authored
+    // size and hand the decoder bytes from two different publisher epochs.
+    this.#dropSampleCombiner(streamKey)
+  }
+
+  setMfuTimeoutMs(ms: number | null): void {
+    if (ms !== null && ms <= 0) throw new Error('[MmtpContainerParser] mfuTimeoutMs must be > 0')
+    this.#reassembler.timeoutMs = ms
+  }
+
+  setReassemblyPolicy(policy: MfuReassemblyPolicy): void {
+    const timeoutMs = mfuReassemblyTimeoutMs(policy)
+    this.#validateReassemblyPolicy(policy)
+    this.#flushSequencers()
+    this.#reassemblyPolicy = policy
+    this.#reliableMoqStartupGate.clear()
+    this.setMfuTimeoutMs(timeoutMs)
+  }
+
+  setReorderWindow(windowSize: number): void {
+    if (!Number.isFinite(windowSize) || windowSize < 0) {
+      throw new Error('[MmtpContainerParser] reorderWindow must be a finite number >= 0')
+    }
+    const nextWindow = Math.ceil(windowSize)
+    this.#validateReassemblyPolicy(this.#reassemblyPolicy, nextWindow)
+    this.#flushSequencers()
+    this.#reorderWindow = nextWindow
+    if (this.#reorderWindow <= 0) this.#sequencers.clear()
+  }
+
+  /** Route an already-assembled frame through the same reorder/callback path
+   * used by source packets. FEC recovery uses this to merge recovered frames
+   * with direct source frames before the decoder sees them. */
+  routeFrame(data: Uint8Array, meta: FrameMeta): void {
+    const seq = meta.packetSequenceNumber
+    const sequencer = this.#sequencerFor(meta.packetId, meta.trackType, meta.catalogTrackName)
+    if (sequencer && seq !== undefined && Number.isFinite(seq)) {
+      sequencer.push(data, meta, seq)
+      return
+    }
+    if (this.#reassemblyPolicy?.transport === 'reliable-moq' &&
+      meta.trackType === 'video' &&
+      !this.#passReliableMoqStartupGate(meta)) {
+      return
+    }
+    this.#emitFrame(data, meta)
+  }
+
+  /**
+   * Claim and return the authored timing for a recovered sample. Recovery does
+   * not pass through the ordinary `feed()` completion path, so it must retire
+   * the same bounded resolver entry once the router accepts the recovered
+   * sample. A missing entry is a fail-closed signal: callers must not replace
+   * it with an MMTP send timestamp or cadence guess.
+   */
+  consumeAuthoredTimingFor(
+    packetId: number,
+    mpuSequenceNumber: number,
+    movieFragmentSequenceNumber: number | undefined,
+    sampleNumber: number | undefined,
+    catalogTrackName?: string,
+  ): AuthoredTiming | null {
+    if (movieFragmentSequenceNumber === undefined || sampleNumber === undefined) return null
+    const resolver = this.#timingResolver(
+      this.#streamKey(packetId, catalogTrackName),
+      packetId,
+      false,
+    )
+    const timing = resolver?.sampleTiming(
+      mpuSequenceNumber,
+      movieFragmentSequenceNumber,
+      sampleNumber,
+    )
+    if (!timing || !resolver || !resolver.consumeSample(
+      mpuSequenceNumber,
+      movieFragmentSequenceNumber,
+      sampleNumber,
+      timing,
+    )) return null
+    this.#pendingTimingSamples--
+    if (this.#pendingTimingSamples < 0) {
+      throw new Error('[MmtpContainerParser] pending timing sample accounting underflow')
+    }
+    return {
+      decodeTime: timing.decodeTime,
+      presentationTime: timing.presentationTime,
+      durationTicks: timing.duration,
+      mediaTimescale: timing.timescale,
+    }
+  }
+
+  /** Order-independent reliable-moq startup gate: discard delta frames for a
+   *  stream until its first RAP is observed, without buffering/reordering. */
+  #passReliableMoqStartupGate(meta: FrameMeta): boolean {
+    const streamKey = this.#streamKey(meta.packetId, meta.catalogTrackName)
+    if (meta.sourceDiscontinuity) this.#reliableMoqStartupGate.delete(streamKey)
+    if (this.#reliableMoqStartupGate.has(streamKey)) return true
+    if (!meta.keyframe) {
+      this.#reorderStats.droppedBeforeStartupKeyframe++
+      return false
+    }
+    this.#reliableMoqStartupGate.set(streamKey, meta.packetId)
+    return true
+  }
+
+  /** Emit all ordered frames currently buffered by the parser. Finite-stream
+   * consumers may call this before dispose(); live cancellation should not. */
+  flush(): void {
+    if (this.#disposed) return
+    this.#flushSequencers()
+  }
+
+  dispose(): void {
+    this.#disposed = true
+    for (const { sequencer } of this.#sequencers.values()) sequencer.discard()
+    this.#sequencers.clear()
+    this.#timingStreams.clear()
+    this.#pendingTimingSamples = 0
+    this.#reliableMoqStartupGate.clear()
+    this.#reassembler.reset()
+    this.#frameCb = null
+    this.#initCb = null
+    this.#trackFrameCbs.clear()
+  }
+
+  // ── Private ─────────────────────────────────────────────────────
+
+  #timingResolver(
+    streamKey: string,
+    packetId: number,
+    create: boolean,
+  ): IsoBmffTimingResolver | null {
+    const existing = this.#timingStreams.get(streamKey)
+    if (existing) return existing.resolver
+    if (!create) return null
+    const resolver = new IsoBmffTimingResolver(this.#maxPendingTimingSamples)
+    this.#timingStreams.set(streamKey, { packetId, resolver })
+    return resolver
+  }
+
+  #dropTimingStream(streamKey: string): void {
+    const state = this.#timingStreams.get(streamKey)
+    if (!state) return
+    this.#timingStreams.delete(streamKey)
+    this.#pendingTimingSamples -= state.resolver.pendingSampleCount
+    if (this.#pendingTimingSamples < 0) {
+      throw new Error('[MmtpContainerParser] pending timing sample accounting underflow')
+    }
+  }
+
+  #validateReassemblyPolicy(
+    policy: MfuReassemblyPolicy | null = this.#reassemblyPolicy,
+    reorderWindow = this.#reorderWindow,
+  ): void {
+    if (!policy) return
+    mmtpFrameReorderWindowFrames(policy, reorderWindow)
+  }
+
+  #buildFrameMeta(
+    assembled: CombinedSample,
+    packetId: number,
+    seq: number,
+    timing: IsoBmffSampleTiming,
+    recovered = false,
+  ): FrameMeta | null {
+    const { data, timestamp: mmtpTimestamp, rapFlag, priority } = assembled
+
+    if (isFmp4Box(data)) return null
+    const presentationTimestamp = mediaTicksToMicroseconds(
+      timing.presentationTime,
+      timing.timescale,
+    )
+    const decodeTimestamp = mediaTicksToMicroseconds(timing.decodeTime, timing.timescale)
+    const duration = mediaTicksToMicroseconds(BigInt(timing.duration), timing.timescale)
+    if (presentationTimestamp === null || decodeTimestamp === null || duration === null ||
+        duration <= 0) {
+      return null
+    }
+
+    let track = this.#tracks.get(packetId)
+    if (!track && this.#defaultTrack) {
+      track = this.#defaultTrack
+      this.#tracks.set(packetId, track)
+    }
+    const codec = track?.codec ?? ''
+
+    const keyframe = MmtpContainerParser.isKeyframe(data, isMfuKeyframeMetadata(rapFlag, priority), codec)
+
+    const meta: FrameMeta = {
+      timestamp: presentationTimestamp,
+      decodeTimestamp,
+      duration,
+      decodeTime: timing.decodeTime,
+      presentationTime: timing.presentationTime,
+      durationTicks: timing.duration,
+      mediaTimescale: timing.timescale,
+      authoredTiming: {
+        decodeTime: timing.decodeTime,
+        presentationTime: timing.presentationTime,
+        durationTicks: timing.duration,
+        mediaTimescale: timing.timescale,
+      },
+      keyframe,
+      packetId,
+      trackType: track?.type ?? null,
+      packetSequenceNumber: seq,
+      ...(assembled.packetSequenceNumbers === undefined
+        ? {}
+        : { packetSequenceNumbers: assembled.packetSequenceNumbers }),
+      ...(assembled.repairedPacketSequenceNumbers === undefined
+        ? {}
+        : { repairedPacketSequenceNumbers: assembled.repairedPacketSequenceNumbers }),
+      ...(assembled.catalogTrackName === undefined
+        ? {}
+        : { catalogTrackName: assembled.catalogTrackName }),
+      mmtpTimestamp,
+      mpuSequenceNumber: assembled.mpuSequenceNumber,
+      ...(assembled.movieFragmentSequenceNumber === undefined
+        ? {}
+        : { movieFragmentSequenceNumber: assembled.movieFragmentSequenceNumber }),
+      ...(assembled.sampleNumber === undefined ? {} : { sampleNumber: assembled.sampleNumber }),
+      fragmentCount: assembled.fragmentCount,
+      rapFlag,
+      ...(priority === undefined ? {} : { priority }),
+      ...(assembled.source === undefined ? {} : { source: assembled.source }),
+      deliveryProvenance: assembled.deliveryProvenance,
+    }
+    if (recovered || (assembled.repairedPacketSequenceNumbers?.length ?? 0) > 0) {
+      meta.recovered = true
+    }
+
+    return meta
+  }
+
+  #sequencerFor(
+    packetId: number,
+    _trackType: FrameMeta['trackType'],
+    catalogTrackName?: string,
+  ): FrameSequencer | null {
+    const windowSize = this.#reassemblyPolicy
+      ? mmtpFrameReorderWindowFrames(this.#reassemblyPolicy, this.#reorderWindow)
+      : this.#reorderWindow
+    if (windowSize <= 0) return null
+    const streamKey = this.#streamKey(packetId, catalogTrackName)
+    let sequencer = this.#sequencers.get(streamKey)?.sequencer
+    if (!sequencer) {
+      sequencer = new FrameSequencer(windowSize, (data, meta) => {
+        this.#emitFrame(data, meta)
+      }, (stat, count = 1) => {
+        this.#reorderStats[stat] += count
+      })
+      this.#sequencers.set(streamKey, { packetId, sequencer })
+    }
+    return sequencer
+  }
+
+  #flushSequencers(): void {
+    for (const { sequencer } of this.#sequencers.values()) sequencer.flush()
+    this.#sequencers.clear()
+  }
+
+  /** Authored presentation timestamp of the last emitted frame, in microseconds. */
+  lastFrameTimestamp: number | undefined = undefined
+
+  #emitFrame(data: Uint8Array, meta: FrameMeta): void {
+    this.lastFrameTimestamp = meta.timestamp
+    const trackCb = this.#trackFrameCbs.get(meta.packetId)
+    trackCb?.(data, meta)
+    this.#frameCb?.(data, meta)
+  }
+
+  // ── Static utilities ──────────────────────────────────────────
+
+  static isKeyframe(data: Uint8Array, rapFlag: boolean, codec = ''): boolean {
+    const payloadKeyframe = MmtpContainerParser.#scanForKeyframe(data, codec)
+    if (payloadKeyframe !== undefined) return payloadKeyframe
+    return rapFlag
+  }
+
+  static #scanForKeyframe(data: Uint8Array, codec: string): boolean | undefined {
+    const c = codec.toLowerCase()
+    if (data.length === 0) return undefined
+
+    if (c.startsWith('av01')) {
+      return scanAv1ObusForKeyframe(data)
+    }
+
+    if (c.startsWith('vp09') || c.startsWith('vp8')) {
+      return (data[0]! & 0x04) === 0
+    }
+
+    const isHevc = c.startsWith('hev1') || c.startsWith('hvc1')
+    if (isHevc) {
+      if (data.length < 5) return undefined
+      if (startsWithAnnexB(data)) {
+        return MmtpContainerParser.#scanAnnexBForKeyframe(data, true)
+      }
+      return MmtpContainerParser.#scanLengthPrefixedHevcForKeyframe(data)
+    }
+
+    if (c === '' || c.startsWith('avc')) {
+      return classifyH264Keyframe(data, { allowPartialAvcc: true })
+    }
+
+    return undefined
+  }
+
+  static #scanLengthPrefixedHevcForKeyframe(data: Uint8Array): boolean | undefined {
+    let sawNal = false
+    let offset = 0
+    while (offset + 4 < data.length) {
+      const nalLen =
+        (data[offset]! << 24) |
+        (data[offset + 1]! << 16) |
+        (data[offset + 2]! << 8) |
+        data[offset + 3]!
+      offset += 4
+      if (nalLen <= 0) return sawNal ? false : undefined
+      // The router's sync probe may see only the first fragment of a large
+      // length-prefixed NAL. The length can exceed this packet, but the NAL
+      // header is still enough to classify IRAP/IDR and open the sync gate.
+      if (offset >= data.length) return sawNal ? false : undefined
+      sawNal = true
+      const hevcType = (data[offset]! >> 1) & 0x3f
+      if (hevcType >= 16 && hevcType <= 21) return true
+      if (offset + nalLen > data.length) break
+      offset += nalLen
+    }
+    return sawNal ? false : undefined
+  }
+
+  static #scanAnnexBForKeyframe(data: Uint8Array, isHevc: boolean): boolean | undefined {
+    let offset = 0
+    let sawNal = false
+    while (offset < data.length) {
+      const start = findAnnexBStart(data, offset)
+      if (!start) return sawNal ? false : undefined
+      const headerOffset = start.offset + start.length
+      if (headerOffset >= data.length) return sawNal ? false : undefined
+      sawNal = true
+      if (isHevc) {
+        if (headerOffset + 1 >= data.length) return sawNal ? false : undefined
+        const hevcType = (data[headerOffset]! >> 1) & 0x3f
+        if (hevcType >= 16 && hevcType <= 21) return true
+      } else {
+        const nalType = data[headerOffset]! & 0x1f
+        if (nalType === 5) return true
+      }
+      offset = headerOffset + 1
+    }
+    return sawNal ? false : undefined
+  }
+}
+
+function scanAv1ObusForKeyframe(data: Uint8Array): boolean | undefined {
+  let offset = 0
+  let sawSequenceHeader = false
+  let sawFrame = false
+
+  while (offset < data.length) {
+    const obu = readAv1Obu(data, offset)
+    if (!obu) return sawFrame ? false : undefined
+    offset = obu.nextOffset
+
+    if (obu.type === 1) {
+      sawSequenceHeader = true
+      continue
+    }
+    if (obu.type !== 3 && obu.type !== 6) continue
+
+    sawFrame = true
+    if (!sawSequenceHeader) {
+      continue
+    }
+
+    const keyframe = readAv1FrameHeaderKeyframe(data.subarray(obu.payloadOffset, obu.payloadEnd))
+    if (keyframe !== undefined) return keyframe
+  }
+
+  return sawFrame ? false : undefined
+}
+
+function readAv1Obu(
+  data: Uint8Array,
+  offset: number,
+): { type: number; payloadOffset: number; payloadEnd: number; nextOffset: number } | null {
+  if (offset >= data.length) return null
+  const header = data[offset]!
+  if ((header & 0x80) !== 0 || (header & 0x01) !== 0) return null
+
+  const type = (header >> 3) & 0x0f
+  const extensionFlag = (header & 0x04) !== 0
+  const hasSizeField = (header & 0x02) !== 0
+  let cursor = offset + 1
+  if (extensionFlag) cursor += 1
+  if (cursor > data.length) return null
+
+  let payloadSize = data.length - cursor
+  if (hasSizeField) {
+    const leb = readLeb128(data, cursor)
+    if (!leb) return null
+    payloadSize = leb.value
+    cursor = leb.nextOffset
+  }
+
+  const payloadEnd = cursor + payloadSize
+  if (payloadEnd > data.length) return null
+  return { type, payloadOffset: cursor, payloadEnd, nextOffset: payloadEnd }
+}
+
+function readLeb128(data: Uint8Array, offset: number): { value: number; nextOffset: number } | null {
+  let value = 0
+  for (let i = 0; i < 8; i++) {
+    if (offset + i >= data.length) return null
+    const byte = data[offset + i]!
+    value += (byte & 0x7f) * (2 ** (i * 7))
+    if ((byte & 0x80) === 0) return { value, nextOffset: offset + i + 1 }
+  }
+  return null
+}
+
+function readAv1FrameHeaderKeyframe(payload: Uint8Array): boolean | undefined {
+  if (payload.length === 0) return undefined
+  const first = payload[0]!
+  const showExistingFrame = (first & 0x80) !== 0
+  if (showExistingFrame) return false
+  const frameType = (first >> 5) & 0x03
+  return frameType === 0
+}
+
+function startsWithAnnexB(data: Uint8Array): boolean {
+  return (
+    (data.length >= 4 && data[0] === 0 && data[1] === 0 && data[2] === 1) ||
+    (data.length >= 5 && data[0] === 0 && data[1] === 0 && data[2] === 0 && data[3] === 1)
+  )
+}
+
+function findAnnexBStart(data: Uint8Array, offset: number): { offset: number; length: 3 | 4 } | null {
+  for (let i = offset; i + 3 <= data.length; i++) {
+    if (data[i] !== 0 || data[i + 1] !== 0) continue
+    if (data[i + 2] === 1) return { offset: i, length: 3 }
+    if (i + 3 < data.length && data[i + 2] === 0 && data[i + 3] === 1) {
+      return { offset: i, length: 4 }
+    }
+  }
+  return null
+}