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

package/src/block-policy.ts

@@ -0,0 +1,903 @@
+/**
+ * Keyframe-protected FEC repair policy.
+ *
+ * Every FEC block still gets in-band FEC decode. What this module decides is
+ * (1) which blocks may hold a keyframe (RAP), so a block short of K at its
+ * repair deadline can be repaired over QUIC with the right priority, and
+ * (2) what a sink must do with the first frame released after a gap: stall
+ * until the next RAP, or conceal and keep playing.
+ *
+ * The two decisions are deliberately independent. Classification only sets
+ * repair priority. The stall/conceal decision is made again per released gap
+ * from the media that is actually missing, so a wrong classification can only
+ * lower a block's repair priority; it can never make playback wrong.
+ *
+ * Everything here is derived from catalog-authored timing and in-band MMTP
+ * evidence. There are no timers, no cadence heuristics, and no defaults: a
+ * track whose geometry cannot be derived exactly runs in the defined
+ * fail-closed mode `all-protected`, where every block is treated as possibly
+ * keyframe-bearing.
+ *
+ * All three players (moqtail, hang, Shaka) consume this one implementation.
+ */
+
+import { deriveFecInterleaveDepth } from '@blockcast/mmt-fec'
+
+// ─── Classes and priorities ─────────────────────────────────────────
+
+/**
+ * Repair class of one FEC block.
+ *
+ * - `keyframe`: the block holds (or held) a RAP / MPU start.
+ * - `delta`: the block provably holds only non-RAP video frames.
+ * - `unknown`: neither could be proven; treated exactly like `keyframe`.
+ * - `audio`: an audio block.
+ */
+export type BlockClass = 'keyframe' | 'delta' | 'unknown' | 'audio'
+
+/** Repair priority. Lower is more urgent. */
+export type RepairPriority = 0 | 1 | 2
+
+export type TrackKind = 'video' | 'audio'
+
+/** P0 = keyframe/unknown (stall-preventing), P1 = audio, P2 = delta. */
+export function repairPriorityForClass(blockClass: BlockClass): RepairPriority {
+  switch (blockClass) {
+    case 'keyframe':
+    case 'unknown':
+      return 0
+    case 'audio':
+      return 1
+    case 'delta':
+      return 2
+  }
+}
+
+// ─── Geometry ───────────────────────────────────────────────────────
+
+export type ClassifierMode = 'classifying' | 'all-protected'
+
+/** Why a track runs `all-protected`. */
+export type ClassifierReason =
+  // Geometry (catalog) reasons.
+  | 'framerate-absent'
+  | 'keyframe-cadence-absent'
+  | 'keyframe-interval-not-integral'
+  | 'block-spans-gop'
+  /**
+   * The catalog keyframe interval is not an exact integer number of ticks
+   * in the media track's own timescale (ISO-BMFF `mdhd`), so released RAP
+   * spacing cannot be verified and hold-last cannot predict the next RAP.
+   * Nothing is wrong with the stream; the cadence is simply unprovable.
+   */
+  | 'keyframe-interval-not-media-integral'
+  /**
+   * Another stream on this packetId was configured with its own geometry
+   * and this one was not, so no geometry provably belongs to it (ABR rungs
+   * sharing a packetId).
+   */
+  | 'stream-geometry-absent'
+  // In-band invariant violations (positive evidence only).
+  | 'rap-not-mpu-start'
+  | 'mpu-longer-than-gop'
+  | 'block-not-contiguous'
+  | 'rap-spacing-mismatch'
+  | 'mpu-multiple-fragments'
+  | 'block-wider-than-interleave'
+
+/** Raw catalog timing for one track. Never a resolved cadence. */
+export interface BlockClassifierGeometryInput {
+  readonly trackKind: TrackKind
+  /** Catalog `framerate` (frames per second). */
+  readonly framerate?: number
+  /** Catalog `fec.interleaveDepthMs`: the full FEC block span (§5.1). */
+  readonly interleaveDepthMs: number
+  /** Catalog track `timescale` for `keyframeIntervalTicks`. */
+  readonly timescale?: number
+  /** Catalog `keyframeIntervalTicks` (preferred when the timescale is present). */
+  readonly keyframeIntervalTicks?: number
+  /** Catalog `keyframeIntervalMs`. */
+  readonly keyframeIntervalMs?: number
+}
+
+/** Exact keyframe interval as a rational number of seconds: ticks / timescale. */
+export interface KeyframeInterval {
+  readonly ticks: number
+  readonly timescale: number
+}
+
+export type BlockClassifierGeometry =
+  | { readonly trackKind: 'audio' }
+  | {
+      readonly trackKind: 'video'
+      readonly mode: 'classifying'
+      /** F: one frame's duration in milliseconds (1000 / framerate). */
+      readonly frameDurationMs: number
+      /** D: media units per FEC block (deriveFecInterleaveDepth). */
+      readonly interleaveUnits: number
+      /** G: frames per GOP. */
+      readonly gopFrames: number
+      readonly keyframeInterval: KeyframeInterval
+    }
+  | {
+      readonly trackKind: 'video'
+      readonly mode: 'all-protected'
+      readonly reason: ClassifierReason
+    }
+
+/**
+ * Integer value of `numerator / denominator` when it is one, else null.
+ *
+ * Catalog framerates are JSON numbers, so an NTSC rate arrives as the double
+ * nearest 30000/1001. One multiply and one divide each add at most half an
+ * ulp of relative error (IEEE-754), so a quotient within two ulps of an
+ * integer IS that integer; anything further is genuinely non-integral.
+ */
+function exactInteger(numerator: number, denominator: number): number | null {
+  if (!Number.isFinite(numerator) || !Number.isFinite(denominator) || denominator === 0) {
+    return null
+  }
+  const quotient = numerator / denominator
+  const rounded = Math.round(quotient)
+  if (rounded < 1) return null
+  const representationError = 2 * Number.EPSILON * Math.abs(quotient)
+  return Math.abs(quotient - rounded) <= representationError ? rounded : null
+}
+
+function isPositiveFinite(value: number | undefined): value is number {
+  return value !== undefined && Number.isFinite(value) && value > 0
+}
+
+/**
+ * Derive the per-track classifier geometry from raw catalog fields.
+ *
+ * `all-protected` is the policy's defined fail-closed state, not a default:
+ * it is returned with the exact reason. The only throw is for a value the
+ * catalog validator already rejects (a non-positive block span).
+ */
+export function deriveBlockClassifierGeometry(
+  input: BlockClassifierGeometryInput,
+): BlockClassifierGeometry {
+  if (!isPositiveFinite(input.interleaveDepthMs)) {
+    throw new Error(
+      `[BlockPolicy] interleaveDepthMs=${input.interleaveDepthMs} is not a positive block span; ` +
+        'the catalog validator rejects this',
+    )
+  }
+  if (input.trackKind === 'audio') return { trackKind: 'audio' }
+
+  if (!isPositiveFinite(input.framerate)) {
+    return { trackKind: 'video', mode: 'all-protected', reason: 'framerate-absent' }
+  }
+  const framerate = input.framerate
+
+  let keyframeInterval: KeyframeInterval
+  if (isPositiveFinite(input.keyframeIntervalTicks) && isPositiveFinite(input.timescale)) {
+    keyframeInterval = { ticks: input.keyframeIntervalTicks, timescale: input.timescale }
+  } else if (isPositiveFinite(input.keyframeIntervalMs)) {
+    keyframeInterval = { ticks: input.keyframeIntervalMs, timescale: 1000 }
+  } else {
+    return { trackKind: 'video', mode: 'all-protected', reason: 'keyframe-cadence-absent' }
+  }
+
+  const gopFrames = exactInteger(keyframeInterval.ticks * framerate, keyframeInterval.timescale)
+  if (gopFrames === null) {
+    return {
+      trackKind: 'video',
+      mode: 'all-protected',
+      reason: 'keyframe-interval-not-integral',
+    }
+  }
+
+  const frameDurationMs = 1000 / framerate
+  const interleaveUnits = deriveFecInterleaveDepth(input.interleaveDepthMs, frameDurationMs)
+  if (interleaveUnits >= gopFrames) {
+    return { trackKind: 'video', mode: 'all-protected', reason: 'block-spans-gop' }
+  }
+
+  return {
+    trackKind: 'video',
+    mode: 'classifying',
+    frameDurationMs,
+    interleaveUnits,
+    gopFrames,
+    keyframeInterval,
+  }
+}
+
+/**
+ * The keyframe interval expressed in a media track's timescale, or null when
+ * the geometry is not `classifying` or the interval is not an exact integer
+ * number of media ticks.
+ */
+export function keyframeIntervalMediaTicks(
+  geometry: BlockClassifierGeometry,
+  mediaTimescale: number,
+): bigint | null {
+  if (geometry.trackKind !== 'video' || geometry.mode !== 'classifying') return null
+  if (!Number.isSafeInteger(mediaTimescale) || mediaTimescale <= 0) return null
+  const { ticks, timescale } = geometry.keyframeInterval
+  if (!Number.isSafeInteger(ticks) || !Number.isSafeInteger(timescale)) return null
+  const scaled = BigInt(ticks) * BigInt(mediaTimescale)
+  const divisor = BigInt(timescale)
+  if (scaled % divisor !== 0n) return null
+  return scaled / divisor
+}
+
+// ─── Evidence ───────────────────────────────────────────────────────
+
+/**
+ * In-band evidence from ONE first-arrival source symbol received from the
+ * network. Recovered symbols and repair symbols never contribute, and the
+ * MFU `priority > 0x80` hint is not evidence.
+ */
+export interface SourceSymbolEvidence {
+  /** The MMTP header R (RAP) bit. */
+  readonly rap: boolean
+  /** MPU_sequence_number, when parsed from this packet. */
+  readonly mpu?: number
+  /**
+   * 0-based sample position within the MPU: the MFU DU-header
+   * `sample_number` minus one (ISO/IEC 23008-1 numbers samples from 1, and
+   * the parser rejects `sample_number` 0). Present only when this packet
+   * carried a DU header.
+   */
+  readonly idx?: number
+  /** movie_fragment_sequence_number from the DU header, when present. */
+  readonly movieFragment?: number
+  /**
+   * DU-header `offset`: the data unit's authored byte position within its
+   * sample (0 for a whole-sample data unit, the partition boundary for a
+   * subsample data unit). Present only with `idx`; absent reads as 0.
+   */
+  readonly offset?: number
+  /**
+   * The MMTP header packet_sequence_number (contiguous per packet_id). Not
+   * classification evidence: FECManager uses it to bound how many blocks the
+   * producer can have started between two source symbols, so an outage is
+   * never mistaken for a source restart.
+   */
+  readonly packetSequenceNumber?: number
+}
+
+export type ReclassificationEvidence = 'rap' | 'mpu-span' | 'window' | 'classifier-disabled'
+
+export type ClassifierChange =
+  | {
+      readonly kind: 'reclassified'
+      readonly sbn: number
+      readonly from: BlockClass
+      readonly to: BlockClass
+      readonly evidence: ReclassificationEvidence
+    }
+  | {
+      readonly kind: 'mode'
+      readonly mode: 'all-protected'
+      readonly reason: ClassifierReason
+    }
+
+interface BlockEvidence {
+  rapSeen: boolean
+  mpus: Set<number>
+  idxMin?: number
+  idxMax?: number
+  cls: BlockClass
+}
+
+/** A data-unit start (a packet carrying a DU header) and the block it is in. */
+interface DataUnitStart {
+  readonly movieFragment: number
+  readonly idx: number
+  readonly offset: number
+  readonly sbn: number
+}
+
+/** Authored order of two data-unit starts of one MPU. */
+function compareDataUnitStarts(
+  a: Omit<DataUnitStart, 'sbn'>,
+  b: Omit<DataUnitStart, 'sbn'>,
+): number {
+  return a.movieFragment - b.movieFragment || a.idx - b.idx || a.offset - b.offset
+}
+
+/**
+ * Per-stream block classifier.
+ *
+ * Classes only move toward more protection or narrower evidence:
+ * `unknown→delta` and `unknown→keyframe` / `delta→keyframe` on evidence, and
+ * `delta→unknown` when an invariant disables classification. `keyframe` is
+ * terminal.
+ *
+ * The delta window rule rests on three premises, each guarded by an
+ * invariant that fires on positive evidence only:
+ *
+ * - P1: the source packets of one block are one contiguous run of the
+ *   stream's authored order, and blocks follow each other in SBN order
+ *   (`block-not-contiguous`). The producer assigns SS_IDs in authored order
+ *   and a block is the SS_ID range [SBN*K, SBN*K + K), so this holds for a
+ *   block that closes at K symbols in the middle of a frame: that frame's
+ *   fragments then land in two ADJACENT blocks, which is still one run each.
+ *   A frame split across adjacent blocks is not a violation.
+ * - P2: that run touches at most D media units, counting a frame continued
+ *   from the previous block (`block-wider-than-interleave`). The producer
+ *   counts a media-unit boundary only once the open block holds a symbol.
+ * - P3: an MPU starts with its only RAP and holds at most G frames
+ *   (`rap-not-mpu-start`, `mpu-longer-than-gop`, `rap-spacing-mismatch`), in
+ *   one movie fragment (`mpu-multiple-fragments`).
+ *
+ * P1 and P2 are what make a block's frames contiguous and lie within
+ * [idxMax − D + 1, idxMin + D − 1] of its MPU. What refutes P1 is a pair of
+ * source packets whose wire-stated authored order and SBN order disagree:
+ * a later MPU in an earlier block, a later data unit of one MPU (by
+ * movie_fragment_sequence_number, sample_number, then DU offset) in an
+ * earlier block, or one data unit in two blocks. That is the signature of a
+ * round-robin interleave, which scatters one run over several concurrent
+ * blocks. Non-adjacency alone is not: a sample larger than K packets
+ * legitimately spans blocks SBN..SBN+n.
+ */
+export class BlockClassifier {
+  #geometry: BlockClassifierGeometry
+  #mode: ClassifierMode
+  #reason: ClassifierReason | null
+  /**
+   * False once the stream showed that an MPU boundary does not bound its
+   * RAPs (a RAP inside an MPU, or an MPU longer than a GOP). Recorded in
+   * every mode: the stall/conceal decision relies on it even when the
+   * catalog geometry already runs the classifier `all-protected`.
+   */
+  #mpuBoundsRaps = true
+  #blocks = new Map<number, BlockEvidence>()
+  /**
+   * P1 ledger, kept for the MPUs within the classification horizon (the
+   * highest MPU seen and the one before it): the SBN span of every source
+   * packet of each MPU, and each MPU's data-unit starts in authored order.
+   * Valid only within one continuous SBN sequence; a source discontinuity
+   * clears it (`noteSourceDiscontinuity`).
+   */
+  #mpuSbnSpans = new Map<number, { min: number; max: number }>()
+  #dataUnitStarts = new Map<number, DataUnitStart[]>()
+  #highestMpu: number | null = null
+  /** MPU → movie_fragment_sequence_number observed in it. */
+  #mpuFragments = new Map<number, number>()
+  #lastRap: { mpu: number; presentationTime: bigint; mediaTimescale: number } | null = null
+
+  constructor(geometry: BlockClassifierGeometry) {
+    this.#geometry = geometry
+    this.#mode = 'classifying'
+    this.#reason = null
+    this.reset(geometry)
+  }
+
+  get geometry(): BlockClassifierGeometry {
+    return this.#geometry
+  }
+
+  get mode(): ClassifierMode {
+    return this.#mode
+  }
+
+  get reason(): ClassifierReason | null {
+    return this.#reason
+  }
+
+  /**
+   * Whether "same MPU on both sides of a gap" still proves the gap held no
+   * RAP. It stops holding for the rest of the epoch once a RAP was received
+   * inside an MPU or an MPU ran longer than a GOP.
+   */
+  get mpuBoundsRaps(): boolean {
+    return this.#mpuBoundsRaps
+  }
+
+  /** Begin a fresh epoch (catalog change or track reset). */
+  reset(geometry: BlockClassifierGeometry = this.#geometry): void {
+    this.#geometry = geometry
+    this.#blocks.clear()
+    this.#clearContiguityLedger()
+    this.#mpuFragments.clear()
+    this.#lastRap = null
+    this.#mpuBoundsRaps = true
+    if (geometry.trackKind === 'video' && geometry.mode === 'all-protected') {
+      this.#mode = 'all-protected'
+      this.#reason = geometry.reason
+    } else {
+      this.#mode = 'classifying'
+      this.#reason = null
+    }
+  }
+
+  /**
+   * Retire this classifier (its stream moves to a new catalog epoch). Every
+   * block it had classified `delta` loses the evidence behind that class and
+   * reads `unknown` from now on; the returned changes say so.
+   */
+  retire(): ClassifierChange[] {
+    const changes: ClassifierChange[] = []
+    for (const [sbn, block] of this.#blocks) {
+      if (block.cls !== 'delta') continue
+      block.cls = 'unknown'
+      changes.push({
+        kind: 'reclassified',
+        sbn,
+        from: 'delta',
+        to: 'unknown',
+        evidence: 'classifier-disabled',
+      })
+    }
+    return changes
+  }
+
+  /**
+   * The stream's SBN sequence restarted (FECManager source discontinuity:
+   * a publisher restart, or the SS_ID space wrapped). Authored order and SBN
+   * order are comparable only within one continuous sequence, so the P1
+   * ledger starts again.
+   */
+  noteSourceDiscontinuity(): void {
+    this.#clearContiguityLedger()
+  }
+
+  /** Register a block that exists without evidence (a vanished block). */
+  touch(sbn: number): void {
+    this.#blockFor(sbn)
+  }
+
+  /** Forget a resolved block. */
+  forget(sbn: number): void {
+    this.#blocks.delete(sbn)
+  }
+
+  classOf(sbn: number): BlockClass {
+    if (this.#geometry.trackKind === 'audio') return 'audio'
+    return this.#blocks.get(sbn)?.cls ?? 'unknown'
+  }
+
+  /** Record one first-arrival source symbol's evidence for block `sbn`. */
+  observe(sbn: number, evidence: SourceSymbolEvidence): ClassifierChange[] {
+    if (this.#geometry.trackKind === 'audio') return []
+    const changes: ClassifierChange[] = []
+    const block = this.#blockFor(sbn)
+
+    if (evidence.rap) block.rapSeen = true
+    if (evidence.mpu !== undefined) block.mpus.add(evidence.mpu)
+    if (evidence.idx !== undefined) {
+      block.idxMin = block.idxMin === undefined ? evidence.idx : Math.min(block.idxMin, evidence.idx)
+      block.idxMax = block.idxMax === undefined ? evidence.idx : Math.max(block.idxMax, evidence.idx)
+    }
+
+    // A RAP inside an MPU refutes "an MPU boundary bounds RAPs" whatever the
+    // classifier mode, because gap decisions rely on it in every mode.
+    if (evidence.rap && evidence.idx !== undefined && evidence.idx !== 0) {
+      this.#mpuBoundsRaps = false
+    }
+
+    const violation = this.#checkInvariants(sbn, block, evidence)
+    if (violation !== null) changes.push(...this.#disable(violation))
+
+    const next = this.#classify(block)
+    if (next !== block.cls && this.#allowed(block.cls, next)) {
+      changes.push({
+        kind: 'reclassified',
+        sbn,
+        from: block.cls,
+        to: next,
+        evidence: this.#evidenceFor(block, next),
+      })
+      block.cls = next
+    }
+    return changes
+  }
+
+  /**
+   * Record a RAP frame released in order. Released MPU-start RAPs of MPUs m
+   * and m+n must be exactly n keyframe intervals apart in the media
+   * timescale, compared as integers.
+   *
+   * Comparing only consecutive MPUs would miss exactly the case the window
+   * rule cannot survive: a short MPU whose successor's RAP was lost (that
+   * RAP-bearing block is the one a wrong G calls delta), because the next
+   * released RAP then belongs to m+2. Every MPU is one interval long, so the
+   * span to any later released RAP proves or refutes all MPUs in between.
+   */
+  noteReleasedRap(
+    mpu: number,
+    presentationTime: bigint,
+    mediaTimescale: number,
+  ): ClassifierChange[] {
+    if (this.#geometry.trackKind === 'audio' || this.#mode === 'all-protected') {
+      return []
+    }
+    // Verification compares integers in the media timescale. When the
+    // catalog interval is not an exact tick count there, spacing is
+    // unprovable: fail closed, naming the cause, rather than blaming the
+    // encoder with rap-spacing-mismatch on a perfectly spaced RAP.
+    const interval = keyframeIntervalMediaTicks(this.#geometry, mediaTimescale)
+    if (interval === null) return this.#disable('keyframe-interval-not-media-integral')
+    const previous = this.#lastRap
+    // A further RAP inside an already-anchored MPU is not an MPU start; the
+    // MPU keeps its first RAP as the spacing anchor (rap-not-mpu-start owns
+    // mid-MPU RAPs).
+    if (previous !== null && previous.mpu === mpu && previous.mediaTimescale === mediaTimescale) {
+      return []
+    }
+    this.#lastRap = { mpu, presentationTime, mediaTimescale }
+    if (
+      previous === null ||
+      mpu < previous.mpu ||
+      previous.mediaTimescale !== mediaTimescale
+    ) {
+      return []
+    }
+    if (
+      presentationTime - previous.presentationTime === interval * BigInt(mpu - previous.mpu)
+    ) {
+      return []
+    }
+    return this.#disable('rap-spacing-mismatch')
+  }
+
+  #blockFor(sbn: number): BlockEvidence {
+    let block = this.#blocks.get(sbn)
+    if (!block) {
+      block = { rapSeen: false, mpus: new Set(), cls: 'unknown' }
+      this.#blocks.set(sbn, block)
+    }
+    return block
+  }
+
+  #checkInvariants(
+    sbn: number,
+    block: BlockEvidence,
+    evidence: SourceSymbolEvidence,
+  ): ClassifierReason | null {
+    if (this.#mode === 'all-protected' || this.#geometry.trackKind !== 'video') return null
+    const geometry = this.#geometry
+    if (geometry.mode !== 'classifying') return null
+    if (evidence.rap && evidence.idx !== undefined && evidence.idx !== 0) {
+      return 'rap-not-mpu-start'
+    }
+    if (evidence.idx !== undefined && evidence.idx >= geometry.gopFrames) {
+      return 'mpu-longer-than-gop'
+    }
+    // A block closes at the latest after D media units, so the DU headers it
+    // carries from one MPU lie within D consecutive positions. A wider span
+    // means the producer closes blocks some other way (at K symbols, or
+    // round-robin across concurrent blocks) and the window rule is void.
+    if (
+      block.mpus.size === 1 &&
+      block.idxMin !== undefined &&
+      block.idxMax !== undefined &&
+      block.idxMax - block.idxMin >= geometry.interleaveUnits
+    ) {
+      return 'block-wider-than-interleave'
+    }
+    if (evidence.mpu !== undefined && evidence.movieFragment !== undefined) {
+      const fragment = this.#mpuFragments.get(evidence.mpu)
+      if (fragment === undefined) {
+        this.#mpuFragments.set(evidence.mpu, evidence.movieFragment)
+        // One entry per MPU still inside the classification horizon.
+        for (const mpu of this.#mpuFragments.keys()) {
+          if (mpu + 1 < evidence.mpu) this.#mpuFragments.delete(mpu)
+        }
+      } else if (fragment !== evidence.movieFragment) {
+        // sample_number is then a position within a movie fragment, not
+        // within the MPU, and the window rule's geometry does not hold.
+        return 'mpu-multiple-fragments'
+      }
+    }
+    if (evidence.mpu !== undefined && this.#contradictsAuthoredOrder(sbn, evidence.mpu, evidence)) {
+      return 'block-not-contiguous'
+    }
+    return null
+  }
+
+  #clearContiguityLedger(): void {
+    this.#mpuSbnSpans.clear()
+    this.#dataUnitStarts.clear()
+    this.#highestMpu = null
+  }
+
+  /**
+   * P1 check for one source packet of MPU `mpu` in block `sbn`, then record
+   * it. True when some recorded packet's authored order and SBN order
+   * disagree with this one's (see the class comment). Only positions the
+   * wire states are compared: MPU order for every packet, and data-unit
+   * order for packets that carry a DU header. A packet of one data unit
+   * that continues into the next block carries no DU header and so only
+   * takes part through its MPU, which is exactly what makes an adjacent
+   * straddle consistent.
+   */
+  #contradictsAuthoredOrder(sbn: number, mpu: number, evidence: SourceSymbolEvidence): boolean {
+    // Every packet of MPU m precedes every packet of MPU m' > m.
+    for (const [other, span] of this.#mpuSbnSpans) {
+      if (other < mpu && span.max > sbn) return true
+      if (other > mpu && span.min < sbn) return true
+    }
+    const inHorizon = this.#highestMpu === null || mpu + 1 >= this.#highestMpu
+    let insertAt = -1
+    let starts: DataUnitStart[] | undefined
+    let start: DataUnitStart | undefined
+    if (evidence.idx !== undefined) {
+      start = {
+        movieFragment: evidence.movieFragment ?? 0,
+        idx: evidence.idx,
+        offset: evidence.offset ?? 0,
+        sbn,
+      }
+      starts = this.#dataUnitStarts.get(mpu)
+      if (starts !== undefined) {
+        let lo = 0
+        let hi = starts.length
+        while (lo < hi) {
+          const mid = (lo + hi) >>> 1
+          if (compareDataUnitStarts(starts[mid]!, start) < 0) lo = mid + 1
+          else hi = mid
+        }
+        const at = starts[lo]
+        if (at !== undefined && compareDataUnitStarts(at, start) === 0) {
+          // One data unit has one first packet: seen in another block, the
+          // SBN-to-authored-order map is not a function.
+          if (at.sbn !== sbn) return true
+        } else {
+          const before = starts[lo - 1]
+          if (before !== undefined && before.sbn > sbn) return true
+          if (at !== undefined && at.sbn < sbn) return true
+          insertAt = lo
+        }
+      }
+    }
+    if (!inHorizon) return false
+    const span = this.#mpuSbnSpans.get(mpu)
+    if (span === undefined) this.#mpuSbnSpans.set(mpu, { min: sbn, max: sbn })
+    else {
+      if (sbn < span.min) span.min = sbn
+      if (sbn > span.max) span.max = sbn
+    }
+    if (start !== undefined) {
+      if (starts === undefined) this.#dataUnitStarts.set(mpu, [start])
+      else if (insertAt >= 0) starts.splice(insertAt, 0, start)
+    }
+    if (this.#highestMpu === null || mpu > this.#highestMpu) {
+      this.#highestMpu = mpu
+      for (const other of [...this.#mpuSbnSpans.keys()]) {
+        if (other + 1 < mpu) {
+          this.#mpuSbnSpans.delete(other)
+          this.#dataUnitStarts.delete(other)
+        }
+      }
+    }
+    return false
+  }
+
+  #disable(reason: ClassifierReason): ClassifierChange[] {
+    if (reason === 'rap-not-mpu-start' || reason === 'mpu-longer-than-gop') {
+      this.#mpuBoundsRaps = false
+    }
+    if (this.#mode === 'all-protected') return []
+    this.#mode = 'all-protected'
+    this.#reason = reason
+    const changes: ClassifierChange[] = [{ kind: 'mode', mode: 'all-protected', reason }]
+    for (const [sbn, block] of this.#blocks) {
+      if (block.cls !== 'delta') continue
+      block.cls = 'unknown'
+      changes.push({
+        kind: 'reclassified',
+        sbn,
+        from: 'delta',
+        to: 'unknown',
+        evidence: 'classifier-disabled',
+      })
+    }
+    return changes
+  }
+
+  #classify(block: BlockEvidence): BlockClass {
+    if (block.rapSeen || block.mpus.size >= 2) return 'keyframe'
+    if (this.#mode === 'all-protected') return 'unknown'
+    const geometry = this.#geometry
+    if (geometry.trackKind !== 'video' || geometry.mode !== 'classifying') return 'unknown'
+    if (
+      block.mpus.size === 1 &&
+      block.idxMin !== undefined &&
+      block.idxMax !== undefined
+    ) {
+      // A block closes every D media units, so its frames are contiguous and
+      // lie in [idxMax − D + 1, idxMin + D − 1] of MPU m. Index 0 is the only
+      // RAP of an MPU and G bounds its length.
+      const span = geometry.interleaveUnits - 1
+      if (block.idxMax - span >= 1 && block.idxMin + span <= geometry.gopFrames - 1) {
+        return 'delta'
+      }
+    }
+    return 'unknown'
+  }
+
+  #allowed(from: BlockClass, to: BlockClass): boolean {
+    if (from === 'keyframe') return false
+    if (from === 'unknown') return to === 'delta' || to === 'keyframe'
+    if (from === 'delta') return to === 'keyframe'
+    return false
+  }
+
+  #evidenceFor(block: BlockEvidence, to: BlockClass): ReclassificationEvidence {
+    if (to === 'delta') return 'window'
+    return block.rapSeen ? 'rap' : 'mpu-span'
+  }
+}
+
+// ─── Stall vs conceal ───────────────────────────────────────────────
+
+export interface GapStreamIdentity {
+  readonly packetId: number
+  /** Non-empty catalog identity, or null when the producer has no track name. */
+  readonly catalogTrackName: string | null
+}
+
+/** What the sink knows about one side of a released gap. */
+export interface GapFrameEvidence {
+  /**
+   * Codec-aware RAP check: `MmtpContainerParser.isKeyframe(data, rapFlag,
+   * codec)`, bitstream-only for recovered frames. Never the priority hint.
+   */
+  readonly rap: boolean
+  /**
+   * MPU_sequence_number of the frame. Omit it once the stream showed that
+   * an MPU boundary does not bound its RAPs (`BlockClassifier.mpuBoundsRaps`):
+   * same-MPU then no longer proves a gap lost only deltas.
+   */
+  readonly mpu?: number
+  /** 0-based sample position within the MPU, when the geometry verifies it. */
+  readonly idx?: number
+  /** Authored presentation time in `timescale` ticks. */
+  readonly pts?: bigint
+  /** Authored sample duration in `timescale` ticks. */
+  readonly durationTicks?: number
+  /** The media timescale of `pts` and `durationTicks`. */
+  readonly timescale?: number
+}
+
+export type FrameGapAction = 'stall' | 'conceal'
+
+export type FrameGapReason =
+  | 'rap-lost'
+  | 'rap-unknown'
+  | 'discontinuity'
+  | 'delta-lost'
+  | 'rap-next'
+  | 'audio-gap'
+  | 'audio-discontinuity'
+
+/**
+ * The decision attached to the first frame released after a gap
+ * (`RoutedFrameMeta.gapBefore`). It is the same frozen object the manager
+ * emits as its `gap` repair lifecycle event, so a sink that acts on the frame
+ * and an observer that counts events see one fact.
+ */
+export interface FrameGapDecision {
+  readonly version: 2
+  readonly type: 'gap'
+  readonly stream: GapStreamIdentity
+  readonly trackKind: TrackKind
+  readonly action: FrameGapAction
+  readonly reason: FrameGapReason
+  /** FEC blocks in the gap whose media was lost (failed or vanished). */
+  readonly blocks: readonly number[]
+  /** Missing video frames or audio access units, when exactly known. */
+  readonly missingFrames: number | null
+  /** Authored duration of the missing media in milliseconds, when known. */
+  readonly missingMs: number | null
+  /** Manager epoch of the stream when the decision was made. */
+  readonly epoch: number
+}
+
+export interface DecideGapInput {
+  readonly stream: GapStreamIdentity
+  readonly trackKind: TrackKind
+  /** Last frame released before the gap. */
+  readonly before: GapFrameEvidence
+  /** First frame released after the gap. */
+  readonly after: GapFrameEvidence
+  /** The stream restarted (FEC SBN went backwards or the publisher reset). */
+  readonly discontinuity: boolean
+  readonly blocks: readonly number[]
+  /**
+   * The most media units the gap can hold: the FEC blocks spanned from the
+   * frame before to the frame after, times D (media units per block,
+   * ceil(interleaveDepthMs / unit duration), §5.1). A block touches at most D
+   * units whether it closes at D or at K symbols. Null when the span or D is
+   * unknown. An audio PTS delta that implies more AUs than this is a clock
+   * jump, not loss, and re-anchors instead of concealing every slot.
+   */
+  readonly maxMissingUnits: number | null
+  readonly epoch: number
+}
+
+function durationMs(units: number, before: GapFrameEvidence): number | null {
+  if (
+    before.durationTicks === undefined ||
+    before.timescale === undefined ||
+    before.timescale <= 0
+  ) {
+    return null
+  }
+  return (units * before.durationTicks * 1000) / before.timescale
+}
+
+/**
+ * Pure stall/conceal decision for the first frame released after a gap.
+ *
+ * Video stalls only when a RAP may be inside the gap: the frame after it is
+ * not a RAP and either sits in another MPU (`rap-lost`) or the MPU cannot be
+ * proven on both sides (`rap-unknown`), or the stream restarted
+ * (`discontinuity`). A gap inside one MPU lost only deltas (`delta-lost`) and
+ * a RAP after the gap resynchronises by itself (`rap-next`). Audio never
+ * stalls: an exact gap is concealed per access unit (`audio-gap`), anything
+ * else re-anchors at the next frame (`audio-discontinuity`).
+ */
+export function decideGap(input: DecideGapInput): FrameGapDecision {
+  const { before, after } = input
+  let action: FrameGapAction
+  let reason: FrameGapReason
+  let missingFrames: number | null = null
+
+  if (input.trackKind === 'audio') {
+    action = 'conceal'
+    reason = 'audio-discontinuity'
+    if (
+      !input.discontinuity &&
+      before.pts !== undefined &&
+      after.pts !== undefined &&
+      before.durationTicks !== undefined &&
+      Number.isSafeInteger(before.durationTicks) &&
+      before.durationTicks > 0
+    ) {
+      const auDuration = BigInt(before.durationTicks)
+      const missingTicks = after.pts - before.pts - auDuration
+      const bound = input.maxMissingUnits
+      if (
+        missingTicks > 0n &&
+        missingTicks % auDuration === 0n &&
+        bound !== null &&
+        missingTicks / auDuration <= BigInt(bound)
+      ) {
+        reason = 'audio-gap'
+        missingFrames = Number(missingTicks / auDuration)
+      }
+    }
+  } else if (input.discontinuity) {
+    action = 'stall'
+    reason = 'discontinuity'
+  } else if (after.rap) {
+    action = 'conceal'
+    reason = 'rap-next'
+  } else if (before.mpu === undefined || after.mpu === undefined) {
+    action = 'stall'
+    reason = 'rap-unknown'
+  } else if (before.mpu !== after.mpu) {
+    action = 'stall'
+    reason = 'rap-lost'
+  } else {
+    action = 'conceal'
+    reason = 'delta-lost'
+    if (before.idx !== undefined && after.idx !== undefined) {
+      const missing = after.idx - before.idx - 1
+      missingFrames = missing > 0 ? missing : null
+    }
+  }
+
+  return Object.freeze({
+    version: 2 as const,
+    type: 'gap' as const,
+    stream: Object.freeze({
+      packetId: input.stream.packetId,
+      catalogTrackName: input.stream.catalogTrackName,
+    }),
+    trackKind: input.trackKind,
+    action,
+    reason,
+    blocks: Object.freeze([...input.blocks]),
+    missingFrames,
+    missingMs: missingFrames === null ? null : durationMs(missingFrames, before),
+    epoch: input.epoch,
+  })
+}