@blockcast/mmt-container 0.1.0 → 0.3.0-main.ef68de90edb3

package/src/mmtp-container-parser.ts

@@ -0,0 +1,2380 @@
+import {
+  parseMMTPHeader,
+  extractMFUPayloadWithHeader,
+  sourceFecPayloadIdOf,
+  extractAltaTrailer,
+  PACKET_TYPE_MPU,
+  PACKET_TYPE_REPAIR,
+  type MMTPHeader,
+} from '@blockcast/mmt-base'
+import {
+  MFUReassembler,
+  MfuReassemblyError,
+  isMfuReassemblyError,
+  type MfuReassemblerBackend,
+  type MmtpSourcePath,
+  type MmtpDeliveryProvenance,
+  type ReassembledMFU,
+} from './mfu-reassembler.js'
+import {
+  SampleCombiner,
+  SampleCombineError,
+  type AbandonedSample,
+  type CombinedSample,
+  type SampleCombinerOptions,
+  type SampleCombinerStats,
+} from './sample-combiner.js'
+import {
+  classifyH264Keyframe,
+  isHevcIrapNalUnitType,
+  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'
+import type { FrameGapDecision } from './block-policy.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
+  /** In-order release policy for FEC-protected streams (see FecReleaseGate). */
+  fecReleaseGate?: FecReleaseGate
+}
+
+/** 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
+}
+
+/**
+ * One parse of an MMTP packet's header, as returned by
+ * MmtpContainerParser.parsePacket(). Hand it back to feedParsed() so the same
+ * packet's header is not parsed again (BLO-36599).
+ */
+export interface ParsedMmtpPacket {
+  readonly info: PacketInfo
+  /** parseMMTPHeader() of the packet this was parsed from. */
+  readonly header: MMTPHeader
+  /** The skipFecPayloadId option `info.fecPayloadId` was resolved under. */
+  readonly skipFecPayloadId: 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
+  /**
+   * FEC source block (SBN) this frame completed in, when it came from an
+   * FEC-protected packet or an FEC-recovered block. Drives in-order release
+   * on FEC-gated streams.
+   */
+  fecSbn?: number
+  /**
+   * Set on the first frame released after a gap: the blocks between it and
+   * the previous release resolved with lost media, or authored decode time
+   * shows a missing sample. The sink must stall or conceal exactly as decided.
+   */
+  gapBefore?: FrameGapDecision
+}
+
+/**
+ * Per-packet MPU and data-unit identity, read without reassembly. The router
+ * uses it as classification evidence for the FEC block the packet belongs to.
+ */
+export interface SourcePacketIdentity {
+  mpuSequenceNumber: number
+  /** 1-based MFU DU-header sample_number, when this packet carries a DU header. */
+  sampleNumber?: number
+  movieFragmentSequenceNumber?: number
+  /** DU-header offset: the data unit's authored byte position in its sample. */
+  offset?: number
+}
+
+/**
+ * In-order release policy for FEC-protected streams. For such a stream a
+ * frame after a gap is released only once every FEC block that could hold
+ * the missing frames has resolved (completed or failed); the frame-count
+ * reorder window applies only to streams without FEC.
+ */
+export interface FecReleaseGate {
+  /** True when this physical stream's frames are FEC-gated. */
+  gates(packetId: number, catalogTrackName?: string): boolean
+  /**
+   * Resolution of the blocks `[fromSbn, toSbn]`: null while any of them can
+   * still complete, otherwise the SBNs whose media was lost (empty when no
+   * block failed; the release still carries a decision when authored decode
+   * time shows a missing sample). `releasedSbn` is the block of the frame
+   * released before the gap: that frame arrived, so its block is not lost
+   * merely because it has since retired.
+   */
+  resolvedLoss(
+    packetId: number,
+    catalogTrackName: string | undefined,
+    fromSbn: number,
+    toSbn: number,
+    releasedSbn: number,
+  ): readonly number[] | null
+  /**
+   * Longest a frame may wait behind unresolved blocks, in milliseconds from
+   * its arrival: by then every block that could hold the frames before it
+   * must have resolved. Past it the frame is released as a discontinuity.
+   * It must not exceed how long a resolved block stays readable as resolved.
+   */
+  holdLimitMs(packetId: number, catalogTrackName?: string): number
+  /** Decide stall/conceal for the first frame released after a gap. */
+  decide(
+    before: { data: Uint8Array; meta: FrameMeta },
+    after: { data: Uint8Array; meta: FrameMeta },
+    lostBlocks: readonly number[],
+    discontinuity: boolean,
+  ): FrameGapDecision
+  /** Every frame released in order from a gated stream. */
+  onReleased?(data: Uint8Array, meta: FrameMeta): void
+}
+
+/** Typed ISO-BMFF timing-sample budget counters. See `timingBudgetStats`. */
+export interface MmtpTimingBudgetStats {
+  /** Slots currently charged to declared-but-undelivered samples. */
+  pending: number
+  /** Total slots available; `pending === capacity` rejects every new moof. */
+  capacity: number
+  /** Slots returned by samples the combiner abandoned (evicted or timed out). */
+  reclaimed: number
+  /**
+   * Slots reclaimed by window displacement — samples no component ever saw,
+   * so no abandonment event could be raised for them. Separate from
+   * `reclaimed` because the owners differ: `reclaimed` is the combiner giving
+   * up, `evicted` is loss that was never observable at all.
+   */
+  evicted: number
+  /** Movie fragments refused because the budget had no room for their samples. */
+  rejectedMovieFragments: number
+}
+
+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
+    }
+
+/**
+ * Why feed() returned no record. Every `return null` inside feed() names one
+ * of these, so a packet that produced nothing is attributable to the stage
+ * that rejected it rather than to one collapsed failure bucket.
+ *
+ * The distinction is what makes a wedged receive path readable: a media track
+ * that stops producing records looks identical from outside whether the header
+ * failed to parse, MFU extraction failed, or the timing resolver refused the
+ * sample — and those name three different components.
+ */
+export type MmtpFeedDropReason =
+  /** feed() after dispose(); the host is still pushing at a torn-down parser. */
+  | 'disposed'
+  | 'header-parse-failed'
+  | 'mfu-extract-failed'
+  /** MPU present but not a timed MFU, so no media payload to reassemble. */
+  | 'untimed-mpu'
+  | 'init-unexpected-fragmentation'
+  | 'init-normalize-failed'
+  /** No timing resolver, or it refused the initialization segment. */
+  | 'init-timing-refused'
+  | 'fragment-unexpected-fragmentation'
+  | 'fragment-no-resolver'
+  /** addMovieFragment refused — includes the pending-timing-sample budget. */
+  | 'fragment-timing-refused'
+  | 'unknown-fragment-type'
+  | 'mfu-no-resolver'
+  | 'mfu-empty-payload'
+  | 'mfu-du-header-missing'
+  | 'mfu-sample-timing-missing'
+  | 'mfu-offset-out-of-range'
+  | 'mfu-size-mismatch'
+  | 'assembled-identity-missing'
+  | 'assembled-timing-missing'
+  | 'assembled-mpu-mismatch'
+  /**
+   * Refusals inside the combined-sample delivery step, which runs after the
+   * combiner has already produced a whole sample. These are distinct from
+   * their `assembled-*` counterparts: those reject a data unit on the way in,
+   * these reject a sample that was fully reassembled and then found
+   * undeliverable, so collapsing the two would hide a combiner that completes
+   * samples nothing can present.
+   */
+  | 'combined-timing-missing'
+  | 'combined-size-mismatch'
+  /** Frame metadata could not be built — an fMP4 box arrived as a timed MFU
+   *  payload, or the authored timing converts to a non-positive duration. */
+  | 'combined-meta-build-failed'
+  | 'combined-timing-consume-refused'
+  /** feed() threw. Counted so the tally still sums to fedObjects; the error
+   *  is rethrown, never swallowed. */
+  | 'threw'
+
+/**
+ * Every key `outcomes` can carry: one per record kind, one per drop reason.
+ *
+ * Derived from the two unions rather than written out, so a new record kind or
+ * drop reason cannot be counted under a key the type does not admit, and a
+ * consumer can enumerate the vocabulary from the type instead of from prose.
+ */
+export type MmtpFeedOutcomeKey =
+  | MmtpParserRecord['kind']
+  | `drop:${MmtpFeedDropReason}`
+
+/**
+ * Feed tallies owned by the parser.
+ *
+ * These live here rather than on MmtpDecodePipeline because the two players
+ * sit at different layers of this library: hang-mmt-fec drives the pipeline,
+ * while moqtail constructs MmtpContainerParser directly and never builds the
+ * wrapper. feed() is the one chokepoint both cross, so a tally maintained here
+ * instruments both by construction.
+ *
+ * Logs are diagnostic output, not an acceptance API — this is the typed
+ * counter a harness should read instead of scraping console histograms.
+ */
+export interface MmtpParserFeedStats {
+  /** Every packet handed to feed(), including post-dispose calls. */
+  fedObjects: number
+  /**
+   * Mutually exclusive outcome tally: record kinds under their own `kind`,
+   * drops under `drop:<reason>`. The values sum to exactly `fedObjects`, which
+   * is the property that makes a frozen media bucket beside a still-climbing
+   * non-media bucket a readable signal rather than two unrelated numbers.
+   *
+   * Partial because a key appears only once it has been counted; absent and
+   * zero mean the same thing to a reader.
+   */
+  outcomes: Partial<Record<MmtpFeedOutcomeKey, number>>
+  /**
+   * Refusals from a completed older sample delivered while registering a
+   * later packet's authored size. Kept separate because that side effect is
+   * not the packet's own feed outcome.
+   */
+  deferredOutcomes: Partial<Record<MmtpFeedDropReason, number>>
+}
+
+type FrameCallback = (data: Uint8Array, meta: FrameMeta) => void
+type InitCallback = (data: Uint8Array, packetId: number, catalogTrackName?: string) => void
+
+/**
+ * Result of one combined-sample delivery attempt: either the record to return
+ * or the reason the sample could not be delivered.
+ *
+ * Internal to the parser. A bare `null` would be indistinguishable from the
+ * other refusals `feed()` can take, and the whole point of the drop-reason
+ * vocabulary is that a stage which stops producing frames says which stage it
+ * was.
+ */
+type CombinedSampleOutcome =
+  | { readonly record: MmtpParserRecord; readonly reason?: undefined }
+  | { readonly record?: undefined; readonly reason: MmtpFeedDropReason }
+
+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
+  /** FEC source block this packet belongs to (FEC-protected packets only). */
+  fecSbn?: number
+}
+
+// ── 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
+  }
+}
+
+// ── FecReleaseSequencer ─────────────────────────────────────────────
+
+/** Authored decode-time adjacency: the next frame starts where this one ends. */
+function authoredAdjacent(before: FrameMeta, after: FrameMeta): boolean {
+  const a = before.authoredTiming
+  const b = after.authoredTiming
+  if (!a || !b || a.mediaTimescale !== b.mediaTimescale) return false
+  return b.decodeTime === a.decodeTime + BigInt(a.durationTicks)
+}
+
+/**
+ * Authored decode time proves media is missing between two frames: the next
+ * frame starts after this one ends. ISO-BMFF decode times of one track are
+ * contiguous, so this is positive evidence of a missing sample whatever the
+ * reason it went missing (a failed FEC block, or a frame the parser or the
+ * recovery path could not deliver although its block completed).
+ */
+function authoredGap(before: FrameMeta, after: FrameMeta): boolean {
+  const a = before.authoredTiming
+  const b = after.authoredTiming
+  if (!a || !b || a.mediaTimescale !== b.mediaTimescale) return false
+  return b.decodeTime > a.decodeTime + BigInt(a.durationTicks)
+}
+
+interface GatedFrame extends PendingFrame {
+  /** performance.now() at push; measures the hold against the gate's limit. */
+  arrivedAtMs: number
+}
+
+interface GatedStream {
+  packetId: number
+  catalogTrackName?: string
+  buf: GatedFrame[]
+  last: PendingFrame | null
+  lastSbn: number | undefined
+  discontinuity: boolean
+}
+
+/**
+ * In-order release for FEC-protected streams, driven by block resolution
+ * instead of a frame-count window. A frame adjacent (in authored decode time)
+ * to the last released frame is released immediately. A frame after a gap
+ * waits until every block between the last released frame's block and its
+ * own has resolved; a D-28 repair or a late in-band recovery can therefore
+ * still fill the gap. When the resolved blocks lost media, or authored decode
+ * time shows a missing sample, the release carries the gate's stall/conceal
+ * decision as `gapBefore`.
+ *
+ * The wait is bounded here, not by the blocks: a frame held longer than the
+ * gate's `holdLimitMs` since it arrived is released with the gate's
+ * discontinuity decision (a stall), so a block that never resolves cannot
+ * grow the buffer without limit. There is no timer: the check runs on the
+ * next push or poke, so after a total outage held frames are released by the
+ * first packet that arrives, not at the ceiling itself.
+ */
+class FecReleaseSequencer {
+  #streams = new Map<string, GatedStream>()
+  readonly #gate: FecReleaseGate
+  readonly #emit: (data: Uint8Array, meta: FrameMeta) => void
+  readonly #recordStat: (stat: SequencerStat, count?: number) => void
+
+  constructor(
+    gate: FecReleaseGate,
+    emit: (data: Uint8Array, meta: FrameMeta) => void,
+    recordStat: (stat: SequencerStat, count?: number) => void,
+  ) {
+    this.#gate = gate
+    this.#emit = emit
+    this.#recordStat = recordStat
+  }
+
+  get buffered(): number {
+    let total = 0
+    for (const stream of this.#streams.values()) total += stream.buf.length
+    return total
+  }
+
+  push(streamKey: string, data: Uint8Array, meta: FrameMeta, seq: number): void {
+    const frame: GatedFrame = { data, meta: { ...meta }, seq, arrivedAtMs: performance.now() }
+    const stream = this.#streamFor(streamKey, meta)
+    if (meta.sourceDiscontinuity) {
+      this.#recordStat('publisherResets')
+      this.#recordStat('droppedOnPublisherReset', stream.buf.length)
+      stream.buf = []
+      stream.last = null
+      stream.lastSbn = undefined
+      stream.discontinuity = false
+    }
+    if (stream.last !== null && compareFrameOrder(frame, stream.last) <= 0) {
+      this.#recordStat('droppedStale')
+      return
+    }
+    if (stream.last === null) {
+      // The first release establishes decoder sync: video must start on a
+      // RAP; earlier deltas are undecodable and are dropped.
+      if (meta.trackType === 'video' && !meta.keyframe) {
+        this.#recordStat('droppedBeforeStartupKeyframe')
+        return
+      }
+      this.#release(stream, frame, undefined)
+      this.#drain(stream)
+      return
+    }
+    let lo = 0
+    let 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)
+    this.#drain(stream)
+  }
+
+  /** Re-evaluate held gaps after FEC state changed. */
+  poke(streamKey?: string): void {
+    if (streamKey !== undefined) {
+      const stream = this.#streams.get(streamKey)
+      if (stream) this.#drain(stream)
+      return
+    }
+    for (const stream of this.#streams.values()) this.#drain(stream)
+  }
+
+  /**
+   * The source restarted: the next release stalls with `discontinuity`.
+   * Only marks the stream. Frames held behind the restart are released by
+   * the next `poke` (or push), so the caller decides when the drain runs; a
+   * drain from inside FEC bookkeeping would re-enter it mid-update.
+   */
+  markDiscontinuity(streamKey: string): void {
+    const stream = this.#streams.get(streamKey)
+    if (!stream || stream.last === null) return
+    stream.discontinuity = true
+  }
+
+  /** Release everything buffered, in order (finite inputs). */
+  flush(): void {
+    for (const stream of this.#streams.values()) {
+      this.#drain(stream)
+      while (stream.buf.length > 0) {
+        const head = stream.buf[0]!
+        stream.buf.shift()
+        this.#release(stream, head, undefined)
+      }
+    }
+  }
+
+  discardStream(streamKey: string): void {
+    const stream = this.#streams.get(streamKey)
+    if (!stream) return
+    this.#recordStat('droppedOnLiveDispose', stream.buf.length)
+    // Empty the buffer too: a discard can run from inside this stream's own
+    // drain (a released frame whose sink retires the stream), and the drain
+    // loop reads `buf` on every iteration. Deleting the entry alone would let
+    // it keep releasing frames of a stream that no longer exists.
+    stream.buf = []
+    this.#streams.delete(streamKey)
+  }
+
+  /** Release one packet's buffered frames in order and forget its streams. */
+  flushPacket(packetId: number): void {
+    for (const [key, stream] of this.#streams) {
+      if (stream.packetId !== packetId) continue
+      this.#drain(stream)
+      while (stream.buf.length > 0) {
+        const head = stream.buf[0]!
+        stream.buf.shift()
+        this.#release(stream, head, undefined)
+      }
+      this.#streams.delete(key)
+    }
+  }
+
+  discardPacket(packetId: number): void {
+    for (const [key, stream] of this.#streams) {
+      if (stream.packetId !== packetId) continue
+      this.#recordStat('droppedOnLiveDispose', stream.buf.length)
+      stream.buf = []
+      this.#streams.delete(key)
+    }
+  }
+
+  discard(): void {
+    for (const stream of this.#streams.values()) {
+      this.#recordStat('droppedOnLiveDispose', stream.buf.length)
+      stream.buf = []
+    }
+    this.#streams.clear()
+  }
+
+  #streamFor(streamKey: string, meta: FrameMeta): GatedStream {
+    let stream = this.#streams.get(streamKey)
+    if (!stream) {
+      stream = {
+        packetId: meta.packetId,
+        ...(meta.catalogTrackName === undefined ? {} : { catalogTrackName: meta.catalogTrackName }),
+        buf: [],
+        last: null,
+        lastSbn: undefined,
+        discontinuity: false,
+      }
+      this.#streams.set(streamKey, stream)
+    }
+    return stream
+  }
+
+  #drain(stream: GatedStream): void {
+    while (stream.buf.length > 0 && stream.last !== null) {
+      const head = stream.buf[0]!
+      const last = stream.last
+      if (stream.discontinuity) {
+        stream.discontinuity = false
+        stream.buf.shift()
+        this.#release(stream, head, this.#gate.decide(last, head, [], true))
+        continue
+      }
+      if (authoredAdjacent(last.meta, head.meta)) {
+        stream.buf.shift()
+        this.#release(stream, head, undefined)
+        continue
+      }
+      const headSbn = head.meta.fecSbn
+      const from = stream.lastSbn ?? headSbn
+      const to = headSbn ?? stream.lastSbn
+      let lost: readonly number[] = []
+      // Neither side carries a Source FEC Payload ID: on a catalog-declared
+      // FEC track that is the trailer-stripped profile violation, and there
+      // are no blocks to wait on. The gap is still a gap: never release across
+      // it undecided (fail closed), let the gate decide with no known blocks.
+      const unanchored = from === undefined && to === undefined
+      if (from !== undefined && to !== undefined) {
+        const resolved = this.#gate.resolvedLoss(
+          stream.packetId,
+          stream.catalogTrackName,
+          Math.min(from, to),
+          Math.max(from, to),
+          from,
+        )
+        if (resolved === null) {
+          const heldMs = performance.now() - head.arrivedAtMs
+          if (heldMs <= this.#gate.holdLimitMs(stream.packetId, stream.catalogTrackName)) return
+          // Past the point where these blocks must have resolved: nothing
+          // is known about the gap, so stall rather than hold forever.
+          this.#recordStat('forcedWindowFlushes')
+          stream.buf.shift()
+          this.#release(stream, head, this.#gate.decide(last, head, [], true))
+          continue
+        }
+        lost = resolved
+      }
+      stream.buf.shift()
+      // Every gap in the frame sequence gets a decision, not only one whose
+      // blocks failed: a frame can go missing although its block completed
+      // (recovered media whose authored timing is gone, a parser drop), and
+      // releasing the next frame undecided would feed the decoder past a
+      // hole with no stall or hold.
+      this.#release(
+        stream,
+        head,
+        lost.length > 0 || unanchored || authoredGap(last.meta, head.meta)
+          ? this.#gate.decide(last, head, lost, false)
+          : undefined,
+      )
+    }
+  }
+
+  #release(stream: GatedStream, frame: PendingFrame, decision: FrameGapDecision | undefined): void {
+    if (decision) frame.meta.gapBefore = decision
+    stream.last = frame
+    if (frame.meta.fecSbn !== undefined) stream.lastSbn = frame.meta.fecSbn
+    this.#gate.onReleased?.(frame.data, frame.meta)
+    this.#emit(frame.data, frame.meta)
+  }
+}
+
+// ── 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
+  #reclaimedTimingSamples = 0
+  #evictedTimingSamples = 0
+  #rejectedMovieFragments = 0
+  #sequencers = new Map<string, { packetId: number; sequencer: FrameSequencer }>()
+  #fecGate: FecReleaseGate | null = null
+  #fecSequencer: FecReleaseSequencer | null = null
+  #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
+  #fedObjects = 0
+  #reassemblerFragmentsFed = 0
+  #reassemblerDataUnitsReturned = 0
+  #feedOutcomes = new Map<MmtpFeedOutcomeKey, number>()
+  #deferredFeedOutcomes = new Map<MmtpFeedDropReason, number>()
+  #lastOutcome: MmtpFeedOutcomeKey | null = null
+  #lastOutcomeCount = 0
+
+  #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,
+        onAbandon: sample => this.#releaseTimingSlot(streamKey, sample),
+      })
+      this.#sampleCombiners.set(streamKey, combiner)
+    }
+    return combiner
+  }
+
+  /**
+   * Return the timing budget slot of a sample the combiner abandoned.
+   *
+   * Without this, `#pendingTimingSamples` is charged for every sample a moof
+   * declares but credited only when that sample is delivered, so each sample
+   * lost to eviction or timeout burns a slot until the window displaces it.
+   * Window displacement bounds that leak but only reclaims the OLDEST entries;
+   * this path returns a slot the moment the combiner knows the sample is gone,
+   * which keeps the live window as wide as the stream actually needs.
+   *
+   * The parser total is decremented only when the resolver reports it
+   * actually freed a slot, so a resolver already dropped by a track reset, or
+   * a sample released twice, cannot drive the accounting negative.
+   */
+  #releaseTimingSlot(streamKey: string, sample: AbandonedSample): void {
+    const resolver = this.#timingStreams.get(streamKey)?.resolver
+    if (!resolver) return
+    if (!resolver.releaseSample(
+      sample.mpuSequenceNumber,
+      sample.movieFragmentSequenceNumber,
+      sample.sampleNumber,
+    )) return
+    this.#pendingTimingSamples--
+    this.#reclaimedTimingSamples++
+    if (this.#pendingTimingSamples < 0) {
+      throw new Error('[MmtpContainerParser] pending timing sample accounting underflow')
+    }
+  }
+
+  /** 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 (config?.fecReleaseGate) this.setFecReleaseGate(config.fecReleaseGate)
+    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
+  }
+
+  /**
+   * Typed view of the ISO-BMFF timing-sample budget.
+   *
+   * This is the acceptance signal for the budget ratchet: `pending` walking
+   * to `capacity` while `rejectedMovieFragments` climbs is the stream wedging,
+   * and it is observable here rather than only as media silently stopping.
+   * Per repo policy this is a producer-owned counter -- never infer budget
+   * state by parsing logs.
+   */
+  get timingBudgetStats(): Readonly<MmtpTimingBudgetStats> {
+    return {
+      pending: this.#pendingTimingSamples,
+      capacity: this.#maxPendingTimingSamples,
+      reclaimed: this.#reclaimedTimingSamples,
+      evicted: this.#evictedTimingSamples,
+      rejectedMovieFragments: this.#rejectedMovieFragments,
+    }
+  }
+
+  get reorderStats(): Readonly<MmtpReorderStats> {
+    let bufferedFrames = this.#fecSequencer?.buffered ?? 0
+    for (const { sequencer } of this.#sequencers.values()) bufferedFrames += sequencer.buffered
+    return { ...this.#reorderStats, bufferedFrames }
+  }
+
+  /**
+   * Install (or remove) the in-order release policy for FEC-protected
+   * streams. Streams the gate claims are released by block resolution; all
+   * others keep the frame-count reorder window.
+   */
+  setFecReleaseGate(gate: FecReleaseGate | null): void {
+    this.#fecSequencer?.flush()
+    this.#fecGate = gate
+    this.#fecSequencer = gate
+      ? new FecReleaseSequencer(
+          gate,
+          (data, meta) => this.#emitFrame(data, meta),
+          (stat, count = 1) => {
+            this.#reorderStats[stat] += count
+          },
+        )
+      : null
+  }
+
+  /** Re-evaluate held gaps after FEC block state changed. */
+  pokeFecRelease(packetId?: number, catalogTrackName?: string): void {
+    if (!this.#fecSequencer) return
+    this.#fecSequencer.poke(
+      packetId === undefined ? undefined : this.#streamKey(packetId, catalogTrackName),
+    )
+  }
+
+  /**
+   * The FEC source of a stream restarted: stall the next release. Marks
+   * only; follow with `pokeFecRelease` to release frames held behind it.
+   */
+  markFecDiscontinuity(packetId: number, catalogTrackName?: string): void {
+    this.#fecSequencer?.markDiscontinuity(this.#streamKey(packetId, catalogTrackName))
+  }
+
+  /**
+   * MPU and data-unit identity of one MMTP packet, parsed in place (no copy,
+   * no reassembly). Null for non-MPU packets and packets that do not parse.
+   * `header` is the packet's already-parsed MMTP header (parsePacket()), so
+   * the header is not parsed a second time (BLO-36599).
+   */
+  static sourcePacketIdentity(packet: Uint8Array, header: MMTPHeader): SourcePacketIdentity | null {
+    try {
+      const extraction = extractMFUPayloadWithHeader(packet, header)
+      if (!extraction) return null
+      const identity: SourcePacketIdentity = {
+        mpuSequenceNumber: extraction.mpu.mpuSequenceNumber,
+      }
+      if (extraction.mfuDuHeader) {
+        identity.sampleNumber = extraction.mfuDuHeader.sampleNumber
+        identity.movieFragmentSequenceNumber = extraction.mfuDuHeader.movieFragmentSequenceNumber
+        identity.offset = extraction.mfuDuHeader.offset
+      }
+      return identity
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Feed tallies for this parser. A fresh snapshot per call, not a live view,
+   * so a caller can hold one and compare it against a later read.
+   *
+   * Survives dispose() — the counters are the parser's own state and are not
+   * cleared by teardown, because a wedged receive path is usually read after
+   * the fact.
+   */
+  get feedStats(): Readonly<MmtpParserFeedStats> {
+    return {
+      fedObjects: this.#fedObjects,
+      outcomes: Object.fromEntries(this.#feedOutcomes),
+      deferredOutcomes: Object.fromEntries(this.#deferredFeedOutcomes),
+    }
+  }
+
+  /**
+   * Outcome token of the most recent feed(), or null before the first call.
+   *
+   * Exposed alongside `lastFeedOutcomeCount` as two scalars rather than one
+   * object because a wrapper reads them on every packet, and feedStats()
+   * allocates a fresh snapshot per call.
+   */
+  get lastFeedOutcome(): MmtpFeedOutcomeKey | null {
+    return this.#lastOutcome
+  }
+
+  /** How many times `lastFeedOutcome` has now been seen. 1 on its first
+   *  occurrence, which is what a caller logging once per novel outcome needs. */
+  get lastFeedOutcomeCount(): number {
+    return this.#lastOutcomeCount
+  }
+
+  /**
+   * MFU fragments feed() handed to the reassembler, including rejected ones.
+   * A plain scalar a per-packet caller can difference; reading the
+   * reassembler's own stats is a wasm crossing on the Rust backend
+   * (BLO-36599).
+   */
+  get reassemblerFragmentsFed(): number {
+    return this.#reassemblerFragmentsFed
+  }
+
+  /** Data units the reassembler returned complete to feed(). */
+  get reassemblerDataUnitsReturned(): number {
+    return this.#reassemblerDataUnitsReturned
+  }
+
+  #countOutcome(token: MmtpFeedOutcomeKey): void {
+    const count = (this.#feedOutcomes.get(token) ?? 0) + 1
+    this.#feedOutcomes.set(token, count)
+    this.#lastOutcome = token
+    this.#lastOutcomeCount = count
+  }
+
+  #countDeferredOutcome(reason: MmtpFeedDropReason): void {
+    this.#deferredFeedOutcomes.set(
+      reason,
+      (this.#deferredFeedOutcomes.get(reason) ?? 0) + 1,
+    )
+  }
+
+  /**
+   * Count a feed() drop and return null in one expression, so every early
+   * return inside feed() states the reason it took instead of collapsing into
+   * a single failure bucket. Returns null so call sites stay `return this.#drop(...)`.
+   */
+  #drop(reason: MmtpFeedDropReason): null {
+    this.#countOutcome(`drop:${reason}`)
+    return null
+  }
+
+  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
+  }
+
+  /**
+   * Reclaim samples abandoned by the sample combiner's protocol deadline.
+   *
+   * This is deliberately driven by the parser's existing packet/lifecycle
+   * cleanup path rather than by another timer. The reassembler timeout is the
+   * same catalog/FEC-derived deadline that bounds each constituent MFU.
+   */
+  cleanupTimeouts(): void {
+    const timeoutMs = this.#reassembler.timeoutMs
+    if (timeoutMs === null) return
+    for (const combiner of this.#sampleCombiners.values()) {
+      combiner.cleanupTimeouts(timeoutMs)
+    }
+  }
+
+  /**
+   * 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 {
+    return this.parsePacket(packet, options)?.info ?? null
+  }
+
+  /**
+   * parseHeader() that also keeps the parsed MMTP header, so a caller that
+   * goes on to feedParsed() the same packet parses its header exactly once.
+   * The MMTP header is parsed once here and the Source FEC Payload ID is read
+   * from it; parseHeader() used to parse the header three times for an FEC
+   * source packet, and feed() repeated all of it (BLO-36599).
+   */
+  parsePacket(packet: Uint8Array, options?: ParseHeaderOptions): ParsedMmtpPacket | null {
+    try {
+      const header = parseMMTPHeader(packet)
+      const isRepair = header.packetType === PACKET_TYPE_REPAIR
+      const skipFecPayloadId = options?.skipFecPayloadId === true
+      const fecPayloadId =
+        !skipFecPayloadId && !isRepair ? sourceFecPayloadIdOf(packet, header) : null
+      return {
+        info: {
+          packetId: header.packetId,
+          packetType: header.packetType,
+          timestamp: header.timestamp,
+          timestampUs: mmtpTimestampToMicros(header.timestamp),
+          sequenceNumber: header.sequenceNumber,
+          rapFlag: header.rapFlag,
+          fecType: header.fecType,
+          fecPayloadId,
+          isRepair,
+        },
+        header,
+        skipFecPayloadId,
+      }
+    } catch {
+      return null
+    }
+  }
+
+  /** Feed a complete MMTP packet. For two-phase use, call parseHeader() first. */
+  feed(packet: Uint8Array, options?: ParseHeaderOptions): MmtpParserRecord | null {
+    return this.#feedCounted(packet, options, undefined)
+  }
+
+  /**
+   * feed() for a packet this caller already ran through parsePacket(): the
+   * header parse is reused instead of repeated. `parsed` must come from
+   * parsePacket() of this same, unmodified packet. If it was resolved under a
+   * different skipFecPayloadId option, the packet is parsed again.
+   */
+  feedParsed(
+    packet: Uint8Array,
+    parsed: ParsedMmtpPacket,
+    options?: ParseHeaderOptions,
+  ): MmtpParserRecord | null {
+    return this.#feedCounted(packet, options, parsed)
+  }
+
+  #feedCounted(
+    packet: Uint8Array,
+    options: ParseHeaderOptions | undefined,
+    parsed: ParsedMmtpPacket | undefined,
+  ): MmtpParserRecord | null {
+    this.#fedObjects += 1
+    let record: MmtpParserRecord | null
+    try {
+      record = this.#feed(packet, options, parsed)
+    } catch (error) {
+      // Count before rethrowing: a throw is an outcome, and leaving it
+      // uncounted would silently break the sum-to-fedObjects invariant that
+      // makes this tally readable.
+      this.#countOutcome('drop:threw')
+      throw error
+    }
+    // Drops are counted at their own return sites via #drop(), which is what
+    // preserves the reason. Only successful records are counted here.
+    if (record) this.#countOutcome(record.kind)
+    return record
+  }
+
+  #feed(
+    packet: Uint8Array,
+    options: ParseHeaderOptions | undefined,
+    preParsed: ParsedMmtpPacket | undefined,
+  ): MmtpParserRecord | null {
+    if (this.#disposed) return this.#drop('disposed')
+
+    this.cleanupTimeouts()
+
+    const parsed =
+      preParsed !== undefined &&
+      preParsed.skipFecPayloadId === (options?.skipFecPayloadId === true)
+        ? preParsed
+        : this.parsePacket(packet, options)
+    if (!parsed) return this.#drop('header-parse-failed')
+    const info = parsed.info
+
+    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 = extractMFUPayloadWithHeader(packet, parsed.header, {
+      skipFecId: options?.skipFecPayloadId,
+    })
+    if (!extraction) return this.#drop('mfu-extract-failed')
+
+    const { mpu, fragmentType, data, mfuDuHeader } = extraction
+    if (mpu.timedFlag !== 1) return this.#drop('untimed-mpu')
+    const streamKey = this.#streamKey(info.packetId, options?.catalogTrackName)
+
+    if (fragmentType === 0) {
+      if (mpu.fragmentationIndicator !== 0 || mpu.fragmentCounter !== 0)
+        return this.#drop('init-unexpected-fragmentation')
+      // 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 this.#drop('init-normalize-failed')
+      const resolver = this.#timingResolver(streamKey, info.packetId, true)
+      if (!resolver?.addInitialization(normalizedInit)) return this.#drop('init-timing-refused')
+      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 this.#drop('fragment-unexpected-fragmentation')
+      const resolver = this.#timingResolver(streamKey, info.packetId, false)
+      if (!resolver) return this.#drop('fragment-no-resolver')
+      const pendingBefore = resolver.pendingSampleCount
+      const evictedBefore = resolver.evictedSampleCount
+      const remaining = this.#maxPendingTimingSamples - this.#pendingTimingSamples
+      const admitted = resolver.addMovieFragment(mpu.mpuSequenceNumber, data, remaining)
+      // Sync on BOTH paths: the resolver can displace stale timing and still
+      // refuse the fragment in hand, and a global count that missed those
+      // freed slots would keep refusing on a budget that is no longer full.
+      this.#pendingTimingSamples += resolver.pendingSampleCount - pendingBefore
+      this.#evictedTimingSamples += resolver.evictedSampleCount - evictedBefore
+      if (!admitted) {
+        if (resolver.lastMovieFragmentRejection === 'budget') {
+          this.#rejectedMovieFragments++
+        }
+        return this.#drop('fragment-timing-refused')
+      }
+      return {
+        kind: 'fragment',
+        packet: info,
+        data,
+        mpuSequenceNumber: mpu.mpuSequenceNumber,
+        fragmentationIndicator: mpu.fragmentationIndicator,
+        fragmentCounter: mpu.fragmentCounter,
+      }
+    }
+    if (fragmentType !== 2) return this.#drop('unknown-fragment-type')
+
+    const resolver = this.#timingResolver(streamKey, info.packetId, false)
+    if (!resolver) return this.#drop('mfu-no-resolver')
+    if (!Number.isSafeInteger(data.byteLength) || data.byteLength <= 0)
+      return this.#drop('mfu-empty-payload')
+    if (mpu.fragmentationIndicator === 0 || mpu.fragmentationIndicator === 1) {
+      if (!mfuDuHeader || mfuDuHeader.movieFragmentSequenceNumber === 0 ||
+          mfuDuHeader.sampleNumber === 0) {
+        return this.#drop('mfu-du-header-missing')
+      }
+      const headTiming = resolver.sampleTiming(
+        mpu.mpuSequenceNumber,
+        mfuDuHeader.movieFragmentSequenceNumber,
+        mfuDuHeader.sampleNumber,
+      )
+      if (!headTiming) return this.#drop('mfu-sample-timing-missing')
+      // 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 this.#drop('mfu-offset-out-of-range')
+      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 this.#drop('mfu-size-mismatch')
+      if (mpu.fragmentationIndicator === 1 && data.byteLength >= remaining)
+        return this.#drop('mfu-size-mismatch')
+
+      // 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. Registration can complete a previously buffered sample; its
+      // refusal is a side effect of this feed, not this packet's own outcome,
+      // so expose it in deferredOutcomes without double-counting outcomes.
+      const readyOnRegister = this.#sampleCombinerFor(streamKey).registerAuthoredSize(
+        options?.catalogTrackName,
+        mpu.mpuSequenceNumber,
+        mfuDuHeader.movieFragmentSequenceNumber,
+        mfuDuHeader.sampleNumber,
+        headTiming.size,
+      )
+      if (readyOnRegister) {
+        const deferred = this.#emitCombinedSample(
+          readyOnRegister,
+          info,
+          resolver,
+          options?.recovered === true,
+          options?.fecSbn,
+        )
+        if (deferred.record === undefined) this.#countDeferredOutcome(deferred.reason)
+      }
+    }
+
+    let assembled: ReassembledMFU | null
+    this.#reassemblerFragmentsFed++
+    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 (!isMfuReassemblyError(error)) 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,
+      }
+    }
+    this.#reassemblerDataUnitsReturned++
+
+    const movieFragmentSequenceNumber = assembled.movieFragmentSequenceNumber
+    const sampleNumber = assembled.sampleNumber
+    if (movieFragmentSequenceNumber === undefined || sampleNumber === undefined)
+      return this.#drop('assembled-identity-missing')
+    // 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 this.#drop('assembled-timing-missing')
+    if (assembled.mpuSequenceNumber !== mpu.mpuSequenceNumber)
+      return this.#drop('assembled-mpu-mismatch')
+
+    // 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,
+      }
+    }
+
+    const outcome = this.#emitCombinedSample(
+      combined,
+      info,
+      resolver,
+      options?.recovered === true,
+      options?.fecSbn,
+    )
+    if (outcome.record !== undefined) return outcome.record
+    return this.#drop(outcome.reason)
+  }
+
+  /**
+   * 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.
+   *
+   * Reports a refusal as a reason rather than counting it, because the two
+   * call sites owe different accounting. On `#feed()`'s tail return the
+   * refusal *is* that feed()'s outcome and must be attributed; on the
+   * register-completion path it belongs to an earlier sample while this
+   * packet's own fragment continues to its own outcome, so counting it there
+   * would push `outcomes` past `fedObjects` — the very invariant the
+   * attribution exists to keep readable. Leaving the choice at the call site
+   * is what keeps both true.
+   */
+  #emitCombinedSample(
+    combined: CombinedSample,
+    info: PacketInfo,
+    resolver: IsoBmffTimingResolver,
+    recovered: boolean,
+    fecSbn: number | undefined,
+  ): CombinedSampleOutcome {
+    const timing = resolver.sampleTiming(
+      combined.mpuSequenceNumber,
+      combined.movieFragmentSequenceNumber,
+      combined.sampleNumber,
+    )
+    if (!timing) return { reason: 'combined-timing-missing' }
+    // 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 { reason: 'combined-size-mismatch' }
+
+    const meta = this.#buildFrameMeta(
+      combined,
+      info.packetId,
+      info.sequenceNumber,
+      timing,
+      recovered,
+    )
+    if (!meta) return { reason: 'combined-meta-build-failed' }
+    if (fecSbn !== undefined) meta.fecSbn = fecSbn
+    if (!resolver.consumeSample(
+      combined.mpuSequenceNumber,
+      combined.movieFragmentSequenceNumber,
+      combined.sampleNumber,
+      timing,
+    )) return { reason: 'combined-timing-consume-refused' }
+    this.#pendingTimingSamples--
+    this.routeFrame(combined.data, meta)
+    return {
+      record: {
+        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)
+    }
+    this.#fecSequencer?.flushPacket(packetId)
+    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.#fecSequencer?.discardStream(streamKey)
+    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)
+  }
+
+  /**
+   * Retire one packet ID, drop-only: discard every stream of it (reorder and
+   * FEC release buffers, authored timing, half-combined samples, startup
+   * gates) and its track registration, and reset the MFU reassembler for each
+   * catalog stream it carried. Nothing buffered is emitted, as on live
+   * dispose. `catalogTrackNames` names the streams the caller routed on this
+   * packet ID; the parser adds any it holds state for itself. Reassembly
+   * resets are catalog-scoped, as for resetTrack: a stream that never carried
+   * a catalog name keeps its reassembler buffers until they time out or are
+   * evicted.
+   */
+  removeTrack(packetId: number, catalogTrackNames: Iterable<string>): void {
+    const names = new Set<string>(catalogTrackNames)
+    for (const [key, entry] of [...this.#sequencers]) {
+      if (entry.packetId !== packetId) continue
+      entry.sequencer.discard()
+      this.#sequencers.delete(key)
+    }
+    this.#fecSequencer?.discardPacket(packetId)
+    for (const [key, state] of [...this.#timingStreams]) {
+      if (state.packetId !== packetId) continue
+      const name = (JSON.parse(key) as [number, string | null])[1]
+      if (name !== null) names.add(name)
+      this.#dropTimingStream(key)
+    }
+    for (const key of [...this.#sampleCombiners.keys()]) {
+      const [keyPacketId, name] = JSON.parse(key) as [number, string | null]
+      if (keyPacketId !== packetId) continue
+      if (name !== null) names.add(name)
+      this.#dropSampleCombiner(key)
+    }
+    for (const [key, gatedPacketId] of [...this.#reliableMoqStartupGate]) {
+      if (gatedPacketId === packetId) this.#reliableMoqStartupGate.delete(key)
+    }
+    for (const name of names) this.#reassembler.resetStream(name)
+    this.#tracks.delete(packetId)
+    this.#trackFrameCbs.delete(packetId)
+  }
+
+  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
+    if (this.#fecSequencer && this.#fecGate?.gates(meta.packetId, meta.catalogTrackName)) {
+      this.#fecSequencer.push(
+        this.#streamKey(meta.packetId, meta.catalogTrackName),
+        data,
+        meta,
+        seq !== undefined && Number.isFinite(seq) ? seq : 0,
+      )
+      return
+    }
+    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()
+    this.#fecSequencer?.flush()
+  }
+
+  dispose(): void {
+    this.#disposed = true
+    for (const { sequencer } of this.#sequencers.values()) sequencer.discard()
+    this.#sequencers.clear()
+    this.#fecSequencer?.discard()
+    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, 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 }),
+      ...(assembled.mmtpTimestamp === undefined
+        ? {}
+        : { mmtpTimestamp: assembled.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 (H.265 Table 7-1, 16..=23)
+      // and open the sync gate.
+      if (offset >= data.length) return sawNal ? false : undefined
+      sawNal = true
+      const hevcType = (data[offset]! >> 1) & 0x3f
+      if (isHevcIrapNalUnitType(hevcType)) 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 (isHevcIrapNalUnitType(hevcType)) 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
+}