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

package/src/cmaf-block-assembler.ts

@@ -0,0 +1,1255 @@
+/**
+ * FEC-aware CMAF sample assembler for MSE multicast.
+ *
+ * Emits source frames on arrival and FEC-recovered frames in media order.
+ * Nothing is synthesised for a lost video block: the sink holds the last good
+ * frame (HoldLastTimeline). A lost audio span is concealed only when libmmt's
+ * release gate decided it (`gapBefore` with reason `audio-gap`), by repeating
+ * the last good access unit into each missing slot (AudioGapConcealer).
+ *
+ * One assembler instance per track (video or audio). MulticastManager owns
+ * these instances and calls them directly with SBN/ESI from the FEC pipeline.
+ */
+
+import {
+  encodeDataSegment,
+  buildVideoInitSegment,
+  buildHevcVideoInitSegment,
+  buildAudioInitSegment,
+  normalizeAacSampleForCmaf,
+} from './mmtp-to-cmaf.js'
+import { AudioGapConcealer } from './conceal-timeline.js'
+import type { FrameGapDecision } from './block-policy.js'
+import {
+  classifyH264Keyframe,
+  detectH264Keyframe,
+  hevcNalUnitType,
+  isAnnexB,
+  isCompleteAvccSample,
+  prepareHevcCmafSample,
+  splitAnnexBNalUnits,
+  splitAvccNalUnits,
+  splitH264SampleNalUnits,
+  videoCodecFamily,
+  videoSampleEntryFromCodecString,
+  type VideoCodecFamily,
+  type VideoSampleEntry,
+} from './codec-utils.js'
+import {
+  scaleAuthoredTicks,
+  scaleAuthoredTiming,
+  type AuthoredTiming,
+} from './authored-timing.js'
+import type { MmtpDeliveryProvenance } from './mfu-reassembler.js'
+
+const INT32_MIN = -0x80000000
+const INT32_MAX = 0x7fffffff
+
+interface BlockFrame {
+  data: Uint8Array
+  timestamp: number
+  keyframe: boolean
+  /** True only for locally generated concealment frames. */
+  synthetic?: boolean
+  /** Raw MMTP short-NTP header timestamp; never used for CMAF timing. */
+  mmtpTimestamp?: bigint
+  /** Exact ISO-BMFF timing retained from the parser for FEC/source ordering. */
+  authoredTiming?: AuthoredTiming
+  /** MMTP packet_sequence_number identifying the delivered access unit. */
+  packetSequenceNumber?: number
+  /** Every authoritative MMTP source-packet sequence that formed this sample. */
+  packetSequenceNumbers?: number[]
+  /** Subset of packetSequenceNumbers reconstructed by FEC. */
+  repairedPacketSequenceNumbers?: number[]
+  /** Native MMTP MPU group coordinate retained across source/FEC ordering. */
+  mpuSequenceNumber?: number
+  /** Timed-MFU sample identity; absent when the MFU header is untimed. */
+  movieFragmentSequenceNumber?: number
+  sampleNumber?: number
+  catalogTrackName?: string
+  /**
+   * Whole-frame delivery verdict folded across every contributing fragment.
+   * Absent means no caller declared one; it is never an implied 'multicast'.
+   */
+  deliveryProvenance?: MmtpDeliveryProvenance
+  /** libmmt's stall/conceal decision for the gap before this frame. */
+  gapBefore?: FrameGapDecision
+}
+
+export interface CmafBlockSample {
+  data: Uint8Array
+  timestamp: number
+  duration: number
+  keyframe: boolean
+  /**
+   * True only for locally generated concealment samples. These samples carry
+   * codec bytes and a media timestamp, but no authored MMTP identity; object
+   * consumers must not validate them as source MFUs.
+   */
+  synthetic?: boolean
+  /**
+   * Raw MMTP short-NTP header timestamp retained for timing telemetry.
+   * This is intentionally separate from the authored media timestamp above.
+   */
+  mmtpTimestamp?: bigint
+  /** Signed PTS-DTS offset in the configured CMAF timescale. */
+  compositionTimeOffset?: number
+  /** Exact ISO-BMFF timing in the media track's native timescale. */
+  authoredTiming?: AuthoredTiming
+  /** MMTP packet_sequence_number identifying the delivered access unit. */
+  packetSequenceNumber?: number
+  /** Every authoritative MMTP source-packet sequence that formed this sample. */
+  packetSequenceNumbers?: number[]
+  /** Subset of packetSequenceNumbers reconstructed by FEC. */
+  repairedPacketSequenceNumbers?: number[]
+  /** Native MMTP MPU group coordinate retained for exact replay selection. */
+  mpuSequenceNumber?: number
+  /**
+   * Timed-MFU sample identity `(movie_fragment_sequence_number,
+   * sample_number)` from the MFU data-unit header, carried alongside
+   * `mpuSequenceNumber` so a consumer can address the sample by its native
+   * MMTP coordinates. Absent when the MFU header is untimed.
+   */
+  movieFragmentSequenceNumber?: number
+  sampleNumber?: number
+  /** Immutable catalog identity supplied by the owning ingress subscription. */
+  catalogTrackName?: string
+  /**
+   * Whole-frame delivery verdict, carried so MSE `onSample` consumers can see
+   * the same evidence the non-MSE frame path gets. Without it the MSE branch
+   * silently loses a computed 'mixed' or 'multicast' finding.
+   */
+  deliveryProvenance?: MmtpDeliveryProvenance
+  /**
+   * libmmt's stall/conceal decision for the gap before this sample
+   * (`RoutedFrameMeta.gapBefore`). MSE sinks feed it to HoldLastTimeline.
+   */
+  gapBefore?: FrameGapDecision
+}
+
+export type CmafSampleOrderPolicy =
+  | { mode: 'arrival' }
+  | {
+    /** Release samples according to media progression, without a wall clock. */
+    mode: 'media-window'
+    /** Delivery window in the same units as CmafBlockSample.timestamp. */
+    deliveryWindow: number
+    /** Optional modulo period for wrapped input timestamps, in timestamp units. */
+    timestampWrapPeriod?: number
+  }
+
+export interface CmafSampleOrderStats {
+  staleSamples: number
+  duplicateSamples: number
+  preRapDeadlineDrops: number
+  noRapFlushDrops: number
+  forcedReleases: number
+  /**
+   * Samples refused because they carried `authoredTiming` while this track's
+   * `admitAuthoredTiming` was false. Non-zero means the contract rollback
+   * switch is engaged AND the producer is still sending authored batches —
+   * a rollback is meant to be paired with that producer reverting to raw.
+   */
+  unadmittedAuthoredSamples: number
+  /**
+   * Video samples refused because their bitstream could not be read: HEVC
+   * whose framing is neither a complete 4-byte length-prefixed sample nor
+   * Annex B, or that holds no NAL unit to write. Writing them would put bytes
+   * the hvcC's lengthSizeMinusOne = 3 does not describe into the mdat.
+   */
+  unreadableVideoSamples: number
+}
+
+/**
+ * Cumulative counters of what the assembler emitted and which block events
+ * it saw. `emits` counts emit calls (one per direct frame, recovered block,
+ * recovered drain or block flush); `samples` and `keyframes` count the
+ * samples those calls carried.
+ */
+export interface CmafEmitStats {
+  emits: number
+  samples: number
+  keyframes: number
+  addedFrames: number
+  recoveredBlocks: number
+  completedBlocks: number
+  failedBlocks: number
+}
+
+/**
+ * Cumulative audio gap concealment counters since construction. Every audio
+ * gap decision the assembler sees lands in exactly one of the gap counters.
+ */
+export interface CmafAudioConcealStats {
+  /** Last-good AUs written into the slots of `audio-gap` decisions. */
+  repeatedUnits: number
+  /**
+   * Gap decisions re-anchored at the next AU by design: an
+   * `audio-discontinuity`, or no good AU emitted yet.
+   */
+  reanchoredGaps: number
+  /**
+   * `audio-gap` decisions that could not be sized and were re-anchored
+   * instead: the AU after the gap, or the last good AU, carried no authored
+   * ISO-BMFF timing, or the two were authored in different media timescales.
+   * libmmt only decides an `audio-gap` from authored ticks (`decideGap`), so
+   * non-zero means a caller handed the assembler a decision without the
+   * timing it was computed from.
+   */
+  untimedGaps: number
+}
+
+export interface BlockAssemblerConfig {
+  /** Number of source symbols per FEC block */
+  k: number
+  /** Timescale for CMAF segments (default 1_000_000 = microseconds) */
+  timescale?: number
+  /** ISO track ID (default 1) */
+  trackId?: number
+  /** Track type — determines init segment format and audio concealment */
+  trackType: 'video' | 'audio'
+  /** Video/audio codec string (e.g. 'avc1.64002a', 'mp4a.40.2'). */
+  codec?: string
+  // Video config (required when trackType='video')
+  /** Raw avcC payload from catalog description — for the init segment */
+  avcC?: Uint8Array
+  /** Raw hvcC payload for an HEVC init segment (e.g. built from in-band
+   *  VPS/SPS/PPS by `generateHvcCFromParameterSets`). Requires `codec` to name
+   *  the `hev1` or `hvc1` sample entry. */
+  hvcC?: Uint8Array
+  /** Video width in pixels */
+  width?: number
+  /** Video height in pixels */
+  height?: number
+  // Audio config (required when trackType='audio')
+  /** Audio codec string (e.g. 'mp4a.40.2', 'opus') */
+  audioCodec?: string
+  /** Audio sample rate (e.g. 48000) */
+  sampleRate?: number
+  /** Audio channel count (e.g. 1 or 2) */
+  channels?: number
+  /** Raw AudioSpecificConfig from catalog */
+  asc?: Uint8Array
+  // Shared
+  /** Frames per second — fallback for duration estimation */
+  fps?: number
+  /** Explicit sample ordering policy. Datagram/FEC callers use media-window. */
+  sampleOrder?: CmafSampleOrderPolicy
+  /**
+   * Bounded sample reorder depth for callback mode.
+   *
+   * Default 0 preserves immediate emission. When set on video tracks with
+   * onSample enabled, samples are sorted by timestamp and the oldest sample is
+   * emitted only after this many newer samples are available.
+   * @deprecated Use sampleOrder with an explicit policy.
+   */
+  sampleReorderWindow?: number
+  /**
+   * Authored-timing admission for this track (default `true` — admitted).
+   *
+   * This is the rollback switch named by the authored-audio-CTS contract's
+   * removal gate (BLO-30397). Assemblers are keyed on
+   * `(packetId, catalogTrackName)` (`mmtp-router.ts` `#mseAssemblerKey`), so
+   * this switch is per **track**. A producer feeding several tracks must be
+   * de-admitted on each of them: nothing applies it across a track set
+   * (BLO-34821).
+   *
+   * Set `false` and a sample carrying `authoredTiming` is **rejected**, not
+   * zeroed: the contract forbids rolling back "by zeroing already-authored
+   * offsets", because a zeroed offset is byte-indistinguishable from a feed
+   * that authored nothing (BLO-30401 measured both as 0 A/V skew). Raw samples
+   * — those with no `authoredTiming` at all — are unaffected and keep emitting
+   * a v0 trun with no composition-offset field.
+   */
+  admitAuthoredTiming?: boolean
+}
+
+interface OrderedSample extends CmafBlockSample {
+  advancesHorizon: boolean
+}
+
+export class CmafBlockAssembler {
+  #config: Required<
+    Pick<
+      BlockAssemblerConfig,
+      'k' | 'timescale' | 'trackId' | 'trackType' | 'admitAuthoredTiming'
+    >
+  >
+  #pendingRecovered = new Map<number, BlockFrame>()
+  #sequence = 1
+  #baseTs = -1
+  /**
+   * Last decoder-proven audio AU, repeated into slots a gap decision names.
+   * It is noted and planned on the AU's authored clock (`AuthoredTiming`
+   * ticks), never on this assembler's CMAF timescale: on the default
+   * 1_000_000 an AAC AU is 1024e6 / sampleRate µs, which is not an integer.
+   */
+  #audioConcealer = new AudioGapConcealer<Uint8Array>()
+  /**
+   * Media timescale of the AU the concealer holds; `'untimed'` when the last
+   * emitted audio AU carried no authored timing, `null` before any AU.
+   */
+  #audioConcealClock: number | 'untimed' | null = null
+  #audioConcealStats: CmafAudioConcealStats = {
+    repeatedUnits: 0,
+    reanchoredGaps: 0,
+    untimedGaps: 0,
+  }
+  #frameDuration: number
+  #lastEmittedTs = -1
+  #lastSourceTs = -1
+  #sampleReorderWindow = 0
+  #sampleOrder: CmafSampleOrderPolicy = { mode: 'arrival' }
+  #sampleOrderCapacity = 0
+  #sampleReorderQueue: OrderedSample[] = []
+  #recoveredHorizonTs = -1
+  #sampleOrderStats: CmafSampleOrderStats = {
+    staleSamples: 0,
+    duplicateSamples: 0,
+    preRapDeadlineDrops: 0,
+    noRapFlushDrops: 0,
+    forcedReleases: 0,
+    unadmittedAuthoredSamples: 0,
+    unreadableVideoSamples: 0,
+  }
+  /** Codec family whose bitstream keyframe rule overrides the metadata flag
+   *  (AVC IDR, HEVC IRAP), or null when the bitstream is not validated. */
+  #videoKeyframeFamily: VideoCodecFamily | null = null
+  /** HEVC sample entry chosen from the catalog codec string. */
+  #hevcSampleEntry: 'hev1' | 'hvc1' | null = null
+  #keyframeRejectDumpCount = 0
+
+  /** Callback: emits a complete moof+mdat CMAF segment */
+  onSegment: ((segment: Uint8Array) => void) | null = null
+  /** Callback: emits a gated/deduped raw sample for callers that already own the MSE timeline. */
+  onSample: ((sample: CmafBlockSample) => void) | null = null
+  /** Callback: emits an init segment (ftyp+moov) */
+  onInitSegment: ((init: Uint8Array) => void) | null = null
+
+  // Video keyframe gate (BLO-3035 layer 3): Chrome's CHUNK_DEMUXER rejects a
+  // moof+mdat whose first sample is non-sync with no prior reference frames
+  // ("CHUNK_DEMUXER_ERROR_APPEND_FAILED: Failed to prepare video sample for
+  // decode") and detaches the SourceBuffer for the rest of the session.
+  // Mid-stream join almost guarantees the first FEC blocks are mid-GOP — all
+  // delta frames. Gate emission until the first block containing an IDR;
+  // within that block, splice samples to start at the IDR index. Audio passes
+  // unconditionally — valid for the codecs supported here (AAC, Opus) where
+  // every frame is independently decodable. SBR-only AAC, USAC, or HE-AAC v2
+  // with PCE re-entry would need a similar gate.
+  #armedVideo = false
+
+  /** Truncate `frames` to start at the first keyframe for video tracks before
+   *  the first emission. Returns the (possibly spliced) frames, or null to
+   *  drop the block entirely. Audio + already-armed video: identity. */
+  #applyVideoKeyframeGate<T extends { data: Uint8Array; keyframe: boolean }>(frames: T[]): T[] | null {
+    const keyedFrames = this.#normalizeVideoKeyframes(frames)
+    if (this.#config.trackType !== 'video' || this.#armedVideo) return keyedFrames
+    const firstKfIdx = keyedFrames.findIndex(f => f.keyframe)
+    if (firstKfIdx < 0) return null
+    return firstKfIdx === 0 ? keyedFrames : keyedFrames.slice(firstKfIdx)
+  }
+
+  #normalizeVideoKeyframes<T extends { data: Uint8Array; keyframe: boolean }>(frames: T[]): T[] {
+    if (this.#config.trackType !== 'video' || this.#videoKeyframeFamily === null) return frames
+    const out: T[] = []
+    for (const frame of frames) {
+      const effective = this.#withEffectiveVideoKeyframe(frame)
+      if (effective !== null) out.push(effective)
+    }
+    return out
+  }
+
+  /** The frame with its bitstream keyframe (and, for HEVC, mdat framing);
+   *  null when the frame is refused and must not be emitted. */
+  #withEffectiveVideoKeyframe<T extends { data: Uint8Array; keyframe: boolean }>(frame: T): T | null {
+    if (this.#config.trackType !== 'video' || this.#videoKeyframeFamily === null) return frame
+    if (this.#videoKeyframeFamily === 'hevc') {
+      // HEVC keyframe = IRAP (H.265 Table 7-1). The mdat carries 4-byte
+      // length-prefixed NAL units to match the hvcC's lengthSizeMinusOne = 3;
+      // normalization is idempotent, so a frame seen twice is unchanged. A
+      // frame that cannot be read is refused, not written as-is and not
+      // passed off as a delta frame.
+      const prepared = prepareHevcCmafSample(frame.data, this.#hevcSampleEntry!)
+      if (prepared === null) {
+        this.#sampleOrderStats.unreadableVideoSamples++
+        return null
+      }
+      const { keyframe, data } = prepared
+      if (!keyframe) this.#dumpRejectedVideoKeyframe(frame.data, frame.keyframe)
+      return keyframe === frame.keyframe && data === frame.data ? frame : { ...frame, keyframe, data }
+    }
+    const keyframe = detectH264Keyframe(frame.data)
+    if (!keyframe) this.#dumpRejectedVideoKeyframe(frame.data, frame.keyframe)
+    return keyframe === frame.keyframe ? frame : { ...frame, keyframe }
+  }
+
+  #dumpRejectedVideoKeyframe(data: Uint8Array, metadataKeyframe: boolean): void {
+    if (this.#keyframeRejectDumpCount >= 12) return
+    this.#keyframeRejectDumpCount++
+    if (this.#videoKeyframeFamily === 'hevc') {
+      const nals = isCompleteAvccSample(data)
+        ? splitAvccNalUnits(data)
+        : isAnnexB(data) ? splitAnnexBNalUnits(data) : []
+      console.log(
+        `[L4-KF-GATE] reject#${this.#keyframeRejectDumpCount} len=${data.length} ` +
+        `metadataKf=${metadataKeyframe} family=hevc ` +
+        `nalTypes=[${nals.slice(0, 16).map((nal) => (nal.length >= 2 ? hevcNalUnitType(nal) : -1)).join(',')}]`,
+      )
+      return
+    }
+    const sample = splitH264SampleNalUnits(data)
+    const nalTypes = describeH264NalTypes(sample.nals)
+    const classify = classifyH264Keyframe(data)
+    const hex = Array.from(data.subarray(0, Math.min(48, data.length)))
+      .map(b => (b as number).toString(16).padStart(2, '0'))
+      .join(' ')
+    console.log(
+      `[L4-KF-GATE] reject#${this.#keyframeRejectDumpCount} len=${data.length} ` +
+      `metadataKf=${metadataKeyframe} classify=${classify} format=${sample.format} ` +
+      `nalTypes=[${nalTypes.join(',')}] first48=[${hex}]`,
+    )
+  }
+
+  /** Mark video as already synchronized by an external decoder path.
+   *  Used by MoQ→multicast MSE continuity when MoQ has already appended a
+   *  keyframe to the same SourceBuffer timeline before multicast takeover. */
+  markVideoSynced(): void {
+    if (this.#config.trackType === 'video') this.#armedVideo = true
+  }
+
+  /** Emit each frame as its own single-sample moof+mdat segment. Matches the
+   *  case-20 path (`MmtpToCmaf.wrapVideoSample` → `encodeDataSegment`) byte-
+   *  for-byte per frame. Working hypothesis (pending Chromium-source
+   *  validation against `media/filters/chunk_demuxer.cc`):
+   *  `encodeMultiSampleSegment` blobs are accepted by ChunkDemuxer in this
+   *  pipeline but only the first sample renders for live, possibly because
+   *  the pipeline expects per-frame moof boundaries. Track in BLO-3035.
+   *
+   *  Stale-tfdt defense-in-depth: drops any frame whose timestamp is older
+   *  than `#lastEmittedTs`. The SBN watermark already prevents out-of-order
+   *  FEC-block emissions, but `addBypassFrame` (oversized MFU / no-FEC path)
+   *  doesn't touch the watermark — a bypass frame at t=T followed by a FEC
+   *  block whose frames precede T would otherwise inject earlier tfdt and
+   *  detach the SourceBuffer. */
+  #ordersSamples(): boolean {
+    return this.#sampleOrder.mode === 'media-window' || this.#sampleReorderWindow > 0
+  }
+
+  #unwrapTimestamp(timestamp: number): number {
+    const wrapPeriod = this.#sampleOrder.mode === 'media-window'
+      ? this.#sampleOrder.timestampWrapPeriod
+      : undefined
+    if (!wrapPeriod) return timestamp
+    const reference = this.#lastSourceTs >= 0
+      ? this.#lastSourceTs
+      : this.#recoveredHorizonTs >= 0
+        ? this.#recoveredHorizonTs
+        : this.#lastEmittedTs
+    if (reference < 0) return timestamp
+    return timestamp + Math.round((reference - timestamp) / wrapPeriod) * wrapPeriod
+  }
+
+  #emitSample(
+    data: Uint8Array,
+    timestamp: number,
+    duration: number,
+    keyframe: boolean,
+    advancesHorizon: boolean,
+    catalogTrackName: string | undefined,
+    mpuSequenceNumber: number | undefined,
+    packetSequenceNumber: number | undefined,
+    packetSequenceNumbers: number[] | undefined,
+    repairedPacketSequenceNumbers: number[] | undefined,
+    authoredTiming: AuthoredTiming | undefined,
+    // Required, not optional: an omitted optional argument is silently
+    // undefined, which is exactly how this field went missing from the
+    // recovered path in the first place. Callers with nothing to declare pass
+    // `undefined` on purpose.
+    deliveryProvenance: MmtpDeliveryProvenance | undefined,
+    /** Raw MMTP short-NTP header timestamp for telemetry only. */
+    mmtpTimestamp: bigint | undefined,
+    // Same rule as deliveryProvenance: required so a caller cannot drop the
+    // timed-MFU identity by omission. Untimed MFUs pass `undefined`.
+    movieFragmentSequenceNumber: number | undefined,
+    sampleNumber: number | undefined,
+    /** True only for locally generated concealment samples. */
+    synthetic: boolean | undefined,
+    /** libmmt's decision for the gap before this sample, carried to sinks. */
+    gapBefore: FrameGapDecision | undefined,
+  ): void {
+    // Authored-timing admission — the rollback switch the BLO-30397 removal
+    // gate names. Refuse the sample outright rather than stripping its offset:
+    // the contract forbids rolling back "by zeroing already-authored offsets",
+    // and BLO-30401 measured why — a zeroed offset and a never-authored one are
+    // behaviourally identical downstream (same buffered ranges, same duration,
+    // no diagnostic), so a silent strip would look exactly like success while
+    // audio ran early forever. A de-admitted producer is expected to revert to
+    // raw batches, which are untouched by this branch.
+    if (authoredTiming !== undefined && !this.#config.admitAuthoredTiming) {
+      this.#sampleOrderStats.unadmittedAuthoredSamples++
+      return
+    }
+    const scaledTiming = authoredTiming === undefined
+      ? null
+      : scaleAuthoredTiming(authoredTiming, this.#config.timescale)
+    if (authoredTiming !== undefined && scaledTiming === null) return
+    const authoredTimestamp = scaledTiming?.timestamp ?? timestamp
+    const authoredDuration = scaledTiming?.duration ?? duration
+    let compositionTimeOffset: number | undefined
+    if (authoredTiming !== undefined) {
+      const scaledOffset = scaleAuthoredTicks(
+        authoredTiming.presentationTime - authoredTiming.decodeTime,
+        authoredTiming.mediaTimescale,
+        this.#config.timescale,
+      )
+      if (scaledOffset === null) return
+      // trun stores composition offsets as integer target-timescale ticks.
+      // Preserve the nearest representable tick, then enforce the signed
+      // int32 serialization range on the rounded value.
+      const roundedOffset = Math.round(scaledOffset)
+      if (
+        !Number.isSafeInteger(roundedOffset) ||
+        roundedOffset < INT32_MIN ||
+        roundedOffset > INT32_MAX
+      ) return
+      compositionTimeOffset = roundedOffset
+    }
+    const unwrappedTimestamp = this.#unwrapTimestamp(authoredTimestamp)
+    if (unwrappedTimestamp <= this.#lastEmittedTs) {
+      this.#sampleOrderStats.staleSamples++
+      return
+    }
+
+    const sample = this.#withEffectiveVideoKeyframe({
+      data,
+      timestamp: unwrappedTimestamp,
+      duration: authoredDuration,
+      keyframe,
+      ...(mmtpTimestamp === undefined ? {} : { mmtpTimestamp }),
+      ...(compositionTimeOffset === undefined ? {} : { compositionTimeOffset }),
+      advancesHorizon,
+      ...(authoredTiming === undefined ? {} : { authoredTiming }),
+      ...(packetSequenceNumber === undefined ? {} : { packetSequenceNumber }),
+      ...(packetSequenceNumbers === undefined ? {} : { packetSequenceNumbers }),
+      ...(repairedPacketSequenceNumbers === undefined
+        ? {}
+        : { repairedPacketSequenceNumbers }),
+      ...(mpuSequenceNumber === undefined ? {} : { mpuSequenceNumber }),
+      ...(movieFragmentSequenceNumber === undefined ? {} : { movieFragmentSequenceNumber }),
+      ...(sampleNumber === undefined ? {} : { sampleNumber }),
+      ...(catalogTrackName === undefined ? {} : { catalogTrackName }),
+      ...(deliveryProvenance === undefined ? {} : { deliveryProvenance }),
+      ...(synthetic === undefined ? {} : { synthetic }),
+      ...(gapBefore === undefined ? {} : { gapBefore }),
+    })
+    if (sample === null) return
+    if (advancesHorizon && unwrappedTimestamp > this.#lastSourceTs) {
+      this.#lastSourceTs = unwrappedTimestamp
+    } else if (!advancesHorizon && unwrappedTimestamp > this.#recoveredHorizonTs) {
+      this.#recoveredHorizonTs = unwrappedTimestamp
+    }
+
+    if (this.#ordersSamples()) {
+      this.#queueSample(sample)
+      return
+    }
+    this.#emitArrivalOrdered(sample)
+  }
+
+  #emitArrivalOrdered(sample: OrderedSample): void {
+    if (this.#config.trackType === 'video' && !this.#armedVideo && !sample.keyframe) {
+      this.#sampleOrderStats.preRapDeadlineDrops++
+      return
+    }
+    this.#emitSampleNow(sample)
+  }
+
+  #queueSample(sample: OrderedSample): void {
+    if (this.#sampleReorderQueue.some(s => s.timestamp === sample.timestamp)) {
+      this.#sampleOrderStats.duplicateSamples++
+      return
+    }
+    this.#sampleReorderQueue.push(sample)
+    this.#sampleReorderQueue.sort((a, b) => a.timestamp - b.timestamp)
+    this.#drainSampleReorder(false)
+    this.#enforceSampleOrderCapacity()
+  }
+
+  #releaseHorizon(): number {
+    return this.#lastSourceTs >= 0 ? this.#lastSourceTs : this.#recoveredHorizonTs
+  }
+
+  #sampleIsReleasable(sample: OrderedSample, flushAll: boolean): boolean {
+    if (flushAll) return true
+    if (this.#sampleOrder.mode === 'media-window') {
+      const horizon = this.#releaseHorizon()
+      return horizon >= 0 && sample.timestamp < horizon - this.#sampleOrder.deliveryWindow
+    }
+    return this.#sampleReorderQueue.length > this.#sampleReorderWindow
+  }
+
+  #dropPreRapSamples(flushAll: boolean): boolean {
+    if (this.#config.trackType !== 'video' || this.#armedVideo) return false
+
+    const firstRap = this.#sampleReorderQueue.findIndex(
+      sample => sample.keyframe && this.#sampleIsReleasable(sample, flushAll),
+    )
+    if (firstRap >= 0) {
+      if (firstRap > 0) {
+        this.#sampleOrderStats.preRapDeadlineDrops += firstRap
+        this.#sampleReorderQueue.splice(0, firstRap)
+      }
+      return false
+    }
+
+    let dropped = 0
+    while (
+      this.#sampleReorderQueue[0] &&
+      this.#sampleIsReleasable(this.#sampleReorderQueue[0]!, flushAll)
+    ) {
+      this.#sampleReorderQueue.shift()
+      dropped++
+    }
+    if (flushAll) this.#sampleOrderStats.noRapFlushDrops += dropped
+    else this.#sampleOrderStats.preRapDeadlineDrops += dropped
+    return dropped > 0
+  }
+
+  #drainSampleReorder(flushAll: boolean): void {
+    while (this.#sampleReorderQueue.length > 0) {
+      if (this.#dropPreRapSamples(flushAll) && this.#sampleReorderQueue.length === 0) return
+      const sample = this.#sampleReorderQueue[0]
+      if (!sample || !this.#sampleIsReleasable(sample, flushAll)) return
+      this.#sampleReorderQueue.shift()
+      this.#emitQueuedSample(sample)
+    }
+  }
+
+  #emitQueuedSample(sample: OrderedSample): void {
+    const next = this.#sampleReorderQueue.find(s => s.timestamp > sample.timestamp)
+    const duration = sample.authoredTiming
+      ? sample.duration
+      : next ? next.timestamp - sample.timestamp : sample.duration
+    this.#emitSampleNow({
+      ...sample,
+      duration: duration > 0
+        ? duration
+        : sample.authoredTiming ? sample.duration : this.#frameDuration,
+    })
+  }
+
+  #enforceSampleOrderCapacity(): void {
+    if (this.#sampleOrder.mode !== 'media-window') return
+    while (this.#sampleReorderQueue.length > this.#sampleOrderCapacity) {
+      const sample = this.#sampleReorderQueue.shift()
+      if (!sample) return
+      this.#sampleOrderStats.forcedReleases++
+      console.warn(
+        `[CmafBlockAssembler] ${this.#config.trackType} media-window queue exceeded ` +
+        `${this.#sampleOrderCapacity} samples; force-releasing timestamp=${sample.timestamp}`,
+      )
+      if (this.#config.trackType === 'video' && !this.#armedVideo && !sample.keyframe) {
+        this.#sampleOrderStats.preRapDeadlineDrops++
+        continue
+      }
+      this.#emitQueuedSample(sample)
+    }
+  }
+
+  #emitSampleNow(sample: CmafBlockSample): void {
+    if (sample.timestamp <= this.#lastEmittedTs) {
+      this.#sampleOrderStats.staleSamples++
+      return
+    }
+    this.#concealAudioGapBefore(sample)
+    this.#writeSampleNow(sample, true)
+  }
+
+  #writeSampleNow(sample: CmafBlockSample, rememberAudio: boolean): void {
+    const { timestamp, duration, keyframe } = sample
+    this.#lastEmittedTs = timestamp
+    if (this.#config.trackType === 'video' && keyframe) this.#armedVideo = true
+    const data = this.#normalizeSampleData(sample.data)
+    if (this.#config.trackType === 'audio' && rememberAudio && data.length > 0) {
+      // Keep decoder-proven codec data for concealment of a later gap that
+      // libmmt's release gate decided, on the AU's own authored clock.
+      this.#noteAudioAccessUnit(data, sample.authoredTiming)
+    }
+    if (this.onSample) {
+      this.onSample(data === sample.data ? sample : { ...sample, data })
+    } else {
+      const baseTime = this.#rebase(timestamp)
+      const segment = encodeDataSegment(
+        data,
+        baseTime,
+        duration,
+        keyframe,
+        this.#sequence++,
+        this.#config.trackId,
+        sample.compositionTimeOffset,
+      )
+      this.onSegment?.(segment)
+    }
+  }
+
+  /**
+   * Record an emitted audio AU for concealment in its authored media ticks —
+   * the clock libmmt's `audio-gap` decision was computed in, where an AAC AU
+   * is exactly 1024 ticks. An AU with no authored timing has no exact clock,
+   * so nothing is held for it and a later `audio-gap` is counted as untimed.
+   */
+  #noteAudioAccessUnit(data: Uint8Array, timing: AuthoredTiming | undefined): void {
+    if (timing === undefined) {
+      this.#audioConcealer.reset()
+      this.#audioConcealClock = 'untimed'
+      return
+    }
+    this.#audioConcealer.note({
+      payload: data,
+      pts: timing.presentationTime,
+      duration: timing.durationTicks,
+    })
+    this.#audioConcealClock = timing.mediaTimescale
+  }
+
+  /**
+   * Repeat the last good AU into exactly the slots an `audio-gap` decision
+   * names. A synthesised AAC access unit is not portable across every
+   * AudioSpecificConfig, so only known-good encoded audio is repeated; with
+   * no good AU yet, or on `audio-discontinuity`, the sink re-anchors at the
+   * next sample and nothing is written.
+   *
+   * The gap is sized in authored ticks and each slot is mapped onto this
+   * assembler's timescale by `scaleAuthoredTiming`, the conversion every
+   * source AU goes through, so a slot lands exactly where the AU it replaces
+   * would have. Nothing here can throw into the packet path: a gap that
+   * cannot be sized exactly is re-anchored and counted.
+   */
+  #concealAudioGapBefore(sample: CmafBlockSample): void {
+    const decision = sample.gapBefore
+    if (this.#config.trackType !== 'audio' || !decision || decision.trackKind !== 'audio') return
+    const timing = sample.authoredTiming
+    const clock = this.#audioConcealClock
+    if (
+      timing === undefined ||
+      clock === 'untimed' ||
+      (clock !== null && clock !== timing.mediaTimescale)
+    ) {
+      // No single authored clock covers both this AU and the one held, so
+      // the gap has no exact size in ticks.
+      if (decision.reason === 'audio-gap') this.#audioConcealStats.untimedGaps++
+      else this.#audioConcealStats.reanchoredGaps++
+      return
+    }
+    const plan = this.#audioConcealer.plan(decision, { pts: timing.presentationTime })
+    if (plan.kind !== 'conceal') {
+      this.#audioConcealStats.reanchoredGaps++
+      return
+    }
+    for (const slot of plan.repeat) {
+      // Every input here is one this sample's own timing already scaled
+      // successfully (same media timescale and duration, an earlier pts), so
+      // the conversion cannot fail for a slot.
+      const scaled = scaleAuthoredTiming({
+        decodeTime: slot.pts,
+        presentationTime: slot.pts,
+        durationTicks: slot.duration,
+        mediaTimescale: timing.mediaTimescale,
+      }, this.#config.timescale)
+      if (scaled === null) continue
+      const slotTimestamp = this.#unwrapTimestamp(scaled.timestamp)
+      if (slotTimestamp <= this.#lastEmittedTs || slotTimestamp >= sample.timestamp) continue
+      this.#writeSampleNow({
+        data: slot.payload.slice(),
+        timestamp: slotTimestamp,
+        duration: scaled.duration,
+        keyframe: true,
+        synthetic: true,
+      }, false)
+      this.#audioConcealStats.repeatedUnits++
+    }
+  }
+
+  #emitPerSample(
+    frames: BlockFrame[],
+    audioDurationOverride?: number,
+    advancesHorizon = false,
+  ): void {
+    for (let i = 0; i < frames.length; i++) {
+      const f = frames[i]!
+      // Per-frame duration from delta to next frame, or fallback.
+      let duration: number
+      if (this.#config.trackType === 'audio') {
+        duration = audioDurationOverride ?? this.#frameDuration
+      } else if (i < frames.length - 1) {
+        duration = frames[i + 1]!.timestamp - f.timestamp
+      } else if (i > 0) {
+        duration = f.timestamp - frames[i - 1]!.timestamp
+      } else {
+        duration = audioDurationOverride ?? this.#frameDuration
+      }
+      if (duration <= 0) duration = audioDurationOverride ?? this.#frameDuration
+      this.#emitSample(
+        f.data,
+        f.timestamp,
+        duration,
+        f.keyframe,
+        advancesHorizon,
+        f.catalogTrackName,
+        f.mpuSequenceNumber,
+        f.packetSequenceNumber,
+        f.packetSequenceNumbers,
+        f.repairedPacketSequenceNumbers,
+        f.authoredTiming,
+        f.deliveryProvenance,
+        f.mmtpTimestamp,
+        f.movieFragmentSequenceNumber,
+        f.sampleNumber,
+        f.synthetic,
+        f.gapBefore,
+      )
+    }
+  }
+
+  // Cumulative emit counters (see emitStats). They replace the BLO-3035 L4
+  // diagnostics, which hashed and hex-dumped every video keyframe and ran a
+  // 1 s setInterval console aggregate on the MSE path (BLO-36599).
+  #emitStats: CmafEmitStats = {
+    emits: 0,
+    samples: 0,
+    keyframes: 0,
+    addedFrames: 0,
+    recoveredBlocks: 0,
+    completedBlocks: 0,
+    failedBlocks: 0,
+  }
+
+  #countEmit(samples: ReadonlyArray<{ keyframe: boolean }>): void {
+    this.#emitStats.emits++
+    this.#emitStats.samples += samples.length
+    for (const sample of samples) if (sample.keyframe) this.#emitStats.keyframes++
+  }
+
+  constructor(config: BlockAssemblerConfig) {
+    this.#config = {
+      k: config.k,
+      timescale: config.timescale ?? 1_000_000,
+      trackId: config.trackId ?? 1,
+      trackType: config.trackType,
+      admitAuthoredTiming: config.admitAuthoredTiming ?? true,
+    }
+
+    // Compute default frame duration from fps (updated from timestamp deltas at runtime)
+    if (config.fps && config.fps > 0) {
+      this.#frameDuration = Math.round(this.#config.timescale / config.fps)
+    } else if (config.trackType === 'audio' && config.sampleRate) {
+      this.#frameDuration = Math.round(this.#config.timescale * 1024 / config.sampleRate)
+    } else {
+      // No fps info — will be refined from actual timestamp deltas
+      this.#frameDuration = 33333
+    }
+
+    const sampleReorderWindow = config.sampleReorderWindow ?? 0
+    if (!Number.isFinite(sampleReorderWindow) || sampleReorderWindow < 0) {
+      throw new Error('[CmafBlockAssembler] sampleReorderWindow must be finite and non-negative')
+    }
+    if (config.sampleOrder && sampleReorderWindow > 0) {
+      throw new Error('[CmafBlockAssembler] configure sampleOrder or sampleReorderWindow, not both')
+    }
+    this.#sampleReorderWindow = Math.floor(sampleReorderWindow)
+    this.#sampleOrder = config.sampleOrder ?? { mode: 'arrival' }
+    if (this.#sampleOrder.mode === 'media-window') {
+      const { deliveryWindow, timestampWrapPeriod } = this.#sampleOrder
+      if (!Number.isSafeInteger(deliveryWindow) || deliveryWindow <= 0) {
+        throw new Error(
+          '[CmafBlockAssembler] media-window deliveryWindow must be a positive safe integer',
+        )
+      }
+      if (
+        timestampWrapPeriod !== undefined &&
+        (!Number.isSafeInteger(timestampWrapPeriod) || timestampWrapPeriod <= deliveryWindow * 2)
+      ) {
+        throw new Error(
+          '[CmafBlockAssembler] timestampWrapPeriod must be a safe integer larger than two delivery windows',
+        )
+      }
+      const samplesPerSecond = config.trackType === 'audio' && config.sampleRate
+        ? config.sampleRate / 1024
+        : config.fps
+      if (!samplesPerSecond || !Number.isFinite(samplesPerSecond) || samplesPerSecond <= 0) {
+        throw new Error(
+          '[CmafBlockAssembler] media-window ordering requires catalog-derived media cadence',
+        )
+      }
+      this.#sampleOrderCapacity =
+        Math.ceil(deliveryWindow * samplesPerSecond / this.#config.timescale) + 1
+    }
+    const videoSampleEntry = config.trackType === 'video' ? resolveVideoSampleEntry(config) : null
+    this.#videoKeyframeFamily = videoSampleEntry === null
+      ? null
+      : videoSampleEntry === 'unvalidated' ? null : videoCodecFamily(videoSampleEntry)
+    this.#hevcSampleEntry = videoSampleEntry === 'hev1' || videoSampleEntry === 'hvc1' ? videoSampleEntry : null
+    if (config.trackType === 'video') {
+      console.log(
+        `[L4-KF-CONFIG] validate=${this.#videoKeyframeFamily ?? false} ` +
+        `codec=${config.codec ?? ''} avcC=${config.avcC?.length ?? 0} hvcC=${config.hvcC?.length ?? 0}`,
+      )
+    }
+
+    // Store config for init segment generation
+    this._videoConfig = config.trackType === 'video' && config.avcC
+      ? { avcC: config.avcC, width: config.width ?? 0, height: config.height ?? 0 }
+      : config.trackType === 'video' && config.hvcC && this.#hevcSampleEntry
+        ? {
+            hvcC: config.hvcC,
+            hevcSampleEntry: this.#hevcSampleEntry,
+            width: config.width ?? 0,
+            height: config.height ?? 0,
+          }
+        : null
+    this._audioConfig = config.trackType === 'audio' && config.sampleRate && config.channels
+      ? { sampleRate: config.sampleRate, channels: config.channels, asc: config.asc }
+      : null
+  }
+
+  private _videoConfig: {
+    avcC?: Uint8Array
+    hvcC?: Uint8Array
+    hevcSampleEntry?: 'hev1' | 'hvc1'
+    width: number
+    height: number
+  } | null
+  private _audioConfig: { sampleRate: number; channels: number; asc?: Uint8Array } | null
+
+  get sampleOrderStats(): Readonly<CmafSampleOrderStats> {
+    return { ...this.#sampleOrderStats }
+  }
+
+  /** Cumulative emit and block-event counters since construction. */
+  get emitStats(): Readonly<CmafEmitStats> {
+    return { ...this.#emitStats }
+  }
+
+  /** Cumulative audio gap concealment counters since construction. */
+  get audioConcealStats(): Readonly<CmafAudioConcealStats> {
+    return { ...this.#audioConcealStats }
+  }
+
+  /** Emit a single frame immediately as a one-sample moof+mdat segment.
+   *
+   *  BLO-3035 layer 4 (4b): the prior SBN-grouped buffering scheme stranded
+   *  frames whenever a multi-packet frame spanned FEC block boundaries —
+   *  intermediate SBNs had packets-but-no-frames and got `completeBlock`
+   *  events that landed on empty `#blocks` (→ `pendingFlush` leak), while
+   *  the SBN where the multi-packet frame finally completed received the
+   *  `addFrame` but its `trackBlock` count never reached K (→ `pendingBlocks`
+   *  leak). Result: ~50% of received frames never reached MSE.
+   *
+   *  This path now mirrors `addBypassFrame` — emit on arrival, no buffering.
+   *  FEC recovery (`addRecoveredBlock`) keeps its SBN-watermark dedup against
+   *  the same SBN being re-emitted from two paths. Out-of-order regression
+   *  is guarded by the per-frame `lastEmittedTs` check (also enforced in
+   *  `#emitPerSample`). The `sbn`/`esi` parameters are kept for the call-site
+   *  signature but no longer affect routing. */
+  addFrame(
+    sbn: number,
+    esi: number,
+    data: Uint8Array,
+    timestamp: number,
+    keyframe: boolean,
+    catalogTrackName?: string,
+    mpuSequenceNumber?: number,
+    packetSequenceNumber?: number,
+    packetSequenceNumbers?: number[],
+    repairedPacketSequenceNumbers?: number[],
+    authoredTiming?: AuthoredTiming,
+    deliveryProvenance?: MmtpDeliveryProvenance,
+    mmtpTimestamp?: bigint,
+    movieFragmentSequenceNumber?: number,
+    sampleNumber?: number,
+    gapBefore?: FrameGapDecision,
+  ): void {
+    void sbn; void esi
+    this.#emitStats.addedFrames++
+
+    if (!this.#ordersSamples()) this.#drainRecoveredUpTo(timestamp)
+
+    // Per-frame duration: default to catalog-derived `#frameDuration`. For
+    // variable-rate content Chrome refines duration from the next sample's
+    // DTS at append time, so a fallback here is safe.
+    this.#emitSample(
+      data,
+      timestamp,
+      this.#frameDuration,
+      keyframe,
+      true,
+      catalogTrackName,
+      mpuSequenceNumber,
+      packetSequenceNumber,
+      packetSequenceNumbers,
+      repairedPacketSequenceNumbers,
+      authoredTiming,
+      deliveryProvenance,
+      mmtpTimestamp,
+      movieFragmentSequenceNumber,
+      sampleNumber,
+      undefined,
+      gapBefore,
+    )
+
+    this.#countEmit([{ keyframe }])
+  }
+
+  /** Mark a block as complete (all K source symbols received or FEC recovery succeeded).
+   *  If all frames are already buffered, flushes immediately. Otherwise sets pending-flush. */
+  completeBlock(sbn: number): void {
+    void sbn
+    this.#emitStats.completedBlocks++
+    // Source samples are emitted directly from addFrame(). A clean FEC block
+    // completion is still useful for stats, but it must not enqueue stale
+    // pending flushes from the retired block-buffered path.
+  }
+
+  /**
+   * Record an unrecoverable block. Nothing is synthesised: the release gate
+   * attaches the stall/conceal decision to the next released frame, and the
+   * sink holds the last good frame (video) or repeats the last good AU into
+   * the decided slots (audio).
+   */
+  failBlock(sbn: number): void {
+    void sbn
+    this.#emitStats.failedBlocks++
+  }
+
+  /** Add all frames from a FEC-recovered block at once and emit immediately. */
+  addRecoveredBlock(sbn: number, frames: BlockFrame[]): void {
+    void sbn
+    this.#emitStats.recoveredBlocks++
+
+    if (frames.length === 0) return
+    const normalized = this.#normalizeVideoKeyframes(frames)
+    if (normalized.length === 0) return
+    this.#countEmit(normalized)
+    if (this.#ordersSamples()) {
+      this.#emitPerSample(normalized, undefined, false)
+      return
+    }
+
+    // Arrival mode preserves the legacy protection against future recovered
+    // samples advancing past source media. Explicit media-window mode routes
+    // both paths through one queue instead.
+    if (this.#lastSourceTs >= 0) {
+      this.#enqueueRecovered(normalized)
+      this.#drainRecoveredUpTo(this.#lastSourceTs)
+    } else {
+      const gated = this.#applyVideoKeyframeGate(normalized)
+      if (gated) this.#emitPerSample(gated, undefined, false)
+    }
+  }
+
+  /** Emit a single frame immediately as a one-sample segment (for oversized packets bypassing FEC). */
+  addBypassFrame(
+    data: Uint8Array,
+    timestamp: number,
+    keyframe: boolean,
+    catalogTrackName?: string,
+    mpuSequenceNumber?: number,
+    packetSequenceNumber?: number,
+    packetSequenceNumbers?: number[],
+    repairedPacketSequenceNumbers?: number[],
+    authoredTiming?: AuthoredTiming,
+    deliveryProvenance?: MmtpDeliveryProvenance,
+    mmtpTimestamp?: bigint,
+    movieFragmentSequenceNumber?: number,
+    sampleNumber?: number,
+    gapBefore?: FrameGapDecision,
+  ): void {
+    if (!this.#ordersSamples()) this.#drainRecoveredUpTo(timestamp)
+    this.#emitSample(
+      data,
+      timestamp,
+      this.#frameDuration,
+      keyframe,
+      true,
+      catalogTrackName,
+      mpuSequenceNumber,
+      packetSequenceNumber,
+      packetSequenceNumbers,
+      repairedPacketSequenceNumbers,
+      authoredTiming,
+      deliveryProvenance,
+      mmtpTimestamp,
+      movieFragmentSequenceNumber,
+      sampleNumber,
+      undefined,
+      gapBefore,
+    )
+  }
+
+  /** Build and emit init segment from catalog config. */
+  emitInit(): void {
+    let init: Uint8Array | null = null
+    if (this._videoConfig?.avcC) {
+      init = buildVideoInitSegment(
+        this._videoConfig.avcC,
+        this._videoConfig.width,
+        this._videoConfig.height,
+        this.#config.timescale,
+        this.#config.trackId,
+      )
+    } else if (this._videoConfig?.hvcC && this._videoConfig.hevcSampleEntry) {
+      init = buildHevcVideoInitSegment(
+        this._videoConfig.hevcSampleEntry,
+        this._videoConfig.hvcC,
+        this._videoConfig.width,
+        this._videoConfig.height,
+        this.#config.timescale,
+        this.#config.trackId,
+      )
+    } else if (this._audioConfig) {
+      init = buildAudioInitSegment(
+        this._audioConfig.sampleRate,
+        this._audioConfig.channels,
+        this._audioConfig.asc,
+        this.#config.timescale,
+        this.#config.trackId,
+      )
+    }
+    if (init) this.onInitSegment?.(init)
+  }
+
+  /** Drain all ordered samples at end-of-stream or before reconfiguration. */
+  flush(): void {
+    if (this.#ordersSamples()) {
+      this.#drainSampleReorder(true)
+      return
+    }
+    if (this.#pendingRecovered.size === 0) return
+    const frames = [...this.#pendingRecovered.values()].sort((a, b) => a.timestamp - b.timestamp)
+    this.#pendingRecovered.clear()
+    const gated = this.#applyVideoKeyframeGate(frames)
+    if (gated) this.#emitPerSample(gated, undefined, false)
+    else if (this.#config.trackType === 'video') {
+      this.#sampleOrderStats.noRapFlushDrops += frames.length
+    }
+  }
+
+  /** Drop all queued state and begin a fresh timestamp epoch. */
+  reset(): void {
+    this.#pendingRecovered.clear()
+    this.#sequence = 1
+    this.#baseTs = -1
+    this.#lastEmittedTs = -1
+    this.#lastSourceTs = -1
+    this.#recoveredHorizonTs = -1
+    this.#audioConcealer.reset()
+    this.#audioConcealClock = null
+    this.#armedVideo = false
+    this.#sampleReorderQueue = []
+  }
+
+  dispose(): void {
+    this.reset()
+    this.onSegment = null
+    this.onSample = null
+    this.onInitSegment = null
+  }
+
+  // ── Private ──
+
+  /** Rebase an absolute timestamp to relative media time (starting near 0). */
+  #rebase(timestamp: number): number {
+    if (this.#baseTs < 0) this.#baseTs = timestamp
+    return timestamp - this.#baseTs
+  }
+
+  #normalizeSampleData(data: Uint8Array): Uint8Array {
+    return this.#config.trackType === 'audio' ? normalizeAacSampleForCmaf(data) : data
+  }
+
+  #enqueueRecovered(frames: BlockFrame[]): void {
+    for (const frame of frames) {
+      if (this.#lastEmittedTs >= 0 && frame.timestamp <= this.#lastEmittedTs) {
+        this.#sampleOrderStats.staleSamples++
+        continue
+      }
+      if (this.#pendingRecovered.has(frame.timestamp)) {
+        this.#sampleOrderStats.duplicateSamples++
+        continue
+      }
+      this.#pendingRecovered.set(frame.timestamp, frame)
+    }
+  }
+
+  #drainRecoveredUpTo(horizonTs: number): void {
+    if (this.#pendingRecovered.size === 0) return
+    const ready = [...this.#pendingRecovered.values()]
+      .filter(frame => frame.timestamp <= horizonTs)
+      .sort((a, b) => a.timestamp - b.timestamp)
+
+    for (const frame of ready) {
+      this.#pendingRecovered.delete(frame.timestamp)
+      this.#emitSample(
+        frame.data,
+        frame.timestamp,
+        this.#frameDuration,
+        frame.keyframe,
+        false,
+        frame.catalogTrackName,
+        frame.mpuSequenceNumber,
+        frame.packetSequenceNumber,
+        frame.packetSequenceNumbers,
+        frame.repairedPacketSequenceNumbers,
+        frame.authoredTiming,
+        frame.deliveryProvenance,
+        frame.mmtpTimestamp,
+        frame.movieFragmentSequenceNumber,
+        frame.sampleNumber,
+        frame.synthetic,
+        frame.gapBefore,
+      )
+      this.#countEmit([frame])
+    }
+  }
+}
+
+/**
+ * Video sample entry whose bitstream keyframe rule the assembler enforces,
+ * selected from the catalog codec string (never sniffed):
+ *
+ * - `avc1`/`avc3`/`hev1`/`hvc1` from `config.codec`.
+ * - No codec string: `avc1` (the legacy H.264 contract, which an avcC
+ *   confirms). An hvcC without a codec string is refused because the sample
+ *   entry (hev1 vs hvc1) cannot be chosen without it.
+ * - Any other video codec (AV1, VP9): 'unvalidated' — its metadata keyframe
+ *   flag is trusted, as before.
+ *
+ * A configuration record that contradicts the codec family is refused.
+ */
+function resolveVideoSampleEntry(config: BlockAssemblerConfig): VideoSampleEntry | 'unvalidated' {
+  if (!config.codec) {
+    if (config.hvcC) {
+      throw new Error('[CmafBlockAssembler] hvcC requires a catalog codec string naming hev1 or hvc1')
+    }
+    return 'avc1'
+  }
+  const fourCc = config.codec.split('.')[0]
+  if (fourCc !== 'avc1' && fourCc !== 'avc3' && fourCc !== 'hev1' && fourCc !== 'hvc1') {
+    if (config.avcC || config.hvcC) {
+      throw new Error(`[CmafBlockAssembler] codec ${config.codec} contradicts the supplied avcC/hvcC`)
+    }
+    return 'unvalidated'
+  }
+  const sampleEntry = videoSampleEntryFromCodecString(config.codec)
+  const family = videoCodecFamily(sampleEntry)
+  if ((family === 'avc' && config.hvcC) || (family === 'hevc' && config.avcC)) {
+    throw new Error(`[CmafBlockAssembler] codec ${config.codec} contradicts the supplied avcC/hvcC`)
+  }
+  return sampleEntry
+}
+
+function describeH264NalTypes(nals: Uint8Array[]): number[] {
+  return nals.slice(0, 16).map((nal) => (
+    nal[0] !== undefined ? nal[0] & 0x1f : -1
+  ))
+}