@blockcast/mmt-container 0.1.0 → 0.3.0

package/src/repair-fetch.ts

@@ -0,0 +1,772 @@
+/**
+ * D-28 shared repair-fetch scheduler.
+ *
+ * Player-agnostic orchestration for per-SBN on-demand MoQ FEC repair
+ * backfill. Each player (moqtail client, hang watch, Shaka MSF bridge)
+ * supplies only its protocol verb via {@link RepairFetchTransport}:
+ *
+ *   - moqtail: standalone FETCH (FetchType.Standalone) for group [sbn, sbn+1)
+ *   - moq-lite/hang: Subscribe with startGroup=sbn, endGroup=sbn (the relay
+ *     propagates startGroup upstream to pull the past group from the origin's
+ *     producer cache)
+ *
+ * Everything else — registration, fire-time repair-track resolution,
+ * keyframe-first admission, preemption, feeding symbols, and in-flight slot
+ * release — is identical across players and lives here. The Player owns the
+ * scheduler: one per `wireRepairFetch` call, and its disposer aborts
+ * everything.
+ *
+ * Priority (from the block's class, see `repairPriorityForClass`):
+ *   - P0 (keyframe / unknown) and P1 (audio) dispatch as soon as they are
+ *     enqueued, with no cap. Each has its own fail deadline, and a cap would
+ *     turn a recoverable protected block into a stall; their number is
+ *     already bounded by the blocks one fail window can hold.
+ *   - P2 (delta) dispatches only while no P0/P1 is queued or in flight,
+ *     earliest absolute fail deadline first. Enqueuing a P0/P1 aborts every
+ *     in-flight P2 (`repair-preempted`), which returns to the queue while its
+ *     block is unresolved. A P2 that never ran before its block resolved is
+ *     reported as `repair-deferred`.
+ *   - A block reclassified to a higher class while its P2 fetch is in flight
+ *     is re-issued at once under the new class's wire priority: the running
+ *     FETCH is aborted (FETCH_CANCEL) and a new one sent.
+ *
+ * Wire priority (draft-ramadan-moq-fec §11.4.5): every request carries the
+ * MoQ Transport SUBSCRIBER_PRIORITY its FETCH must use, derived from the two
+ * catalog priorities `ResolveRepairTarget` returns (see
+ * `repairFetchSubscriberPriority`): a keyframe-bearing (or unknown) block's
+ * FETCH is sent in the Source Media range at no more than the source
+ * track's priority, so it is delivered ahead of every repair track and not
+ * shed with repair data; a delta or audio FETCH is sent at no less than the
+ * fetched repair track's priority, so it is shed first.
+ *
+ * Deadline and admission (BLO-35597): a repair FETCH rides the reliable path,
+ * so its deadline is the block's PRESENTATION deadline, not the multicast
+ * reassembly deadline. The player states how long after a block's first
+ * symbol its media can still be presented (`presentationDelayMs`); from the
+ * block's receiver-local anchor that gives an absolute deadline, never earlier
+ * than the multicast wait and never later than the release gate's hold ceiling
+ * (`terminalRetentionMsForPacket`), which bounds how long any successor frame
+ * may wait behind the block. A FETCH is sent only when the measured
+ * reliable-path RTT (`reliableRttMs`) is less than the time left to that
+ * deadline -- a request that cannot come back in time is never sent, rather
+ * than sent and cancelled -- and an admitted FETCH holds the block open to
+ * that deadline, so the multicast span elapsing never aborts it.
+ *
+ * The scheduler arms no timers. A fetch ends when its transport completes or
+ * throws, when it is preempted, when any later scheduling event finds it past
+ * its presentation deadline, when its block resolves (recovered, or failed at
+ * that deadline), on track reset, or on dispose.
+ */
+
+import type { FecBlockProfile } from '@blockcast/mmt-base'
+import { repairPriorityForClass, type BlockClass, type RepairPriority } from './block-policy.js'
+import type { RepairLifecycleObserver } from './multicast-manager.js'
+import { REPAIR_PRIORITY_MIN } from './repair-layers.js'
+
+/** The MoQ Transport priority scale: 0..255, a lower value is delivered first. */
+const MOQT_PRIORITY_MAX = 255
+
+/**
+ * The highest value in the Source Media priority range of
+ * draft-ramadan-moq-fec §10 (64..191): one below the repair range, which
+ * starts at `REPAIR_PRIORITY_MIN` (192).
+ */
+export const SOURCE_MEDIA_PRIORITY_MAX = REPAIR_PRIORITY_MIN - 1
+
+/** What `ResolveRepairTarget` returns for one repair-bearing stream. */
+export interface RepairTarget {
+  /** The repair track to FETCH (base layer 0 of the block's source). */
+  readonly repairTrack: string
+  /**
+   * The catalog `priority` of the SOURCE track the block belongs to, on the
+   * MoQ Transport scale (0..255, lower first), or null when the catalog
+   * carries none. Never a player constant: a keyframe repair must not be
+   * delivered behind the source it repairs, and only the catalog says what
+   * that source's priority is.
+   */
+  readonly sourcePriority: number | null
+  /**
+   * The catalog priority of `repairTrack` (MoQ Transport scale). Layer 0
+   * that declares none has the value draft-ramadan-moq-fec §10 defines
+   * (240); `resolveRepairLayers` / `catalogRepairTarget` already apply it.
+   * Null only when the resolver cannot read the repair track's entry.
+   */
+  readonly repairPriority: number | null
+}
+
+/** Resolve a packetId to its repair track and priorities at FIRE TIME.
+ *
+ *  Called on every repair request, never cached by the shell: ABR ladder
+ *  rungs can share a packetId (e.g. video/720p and video/360p both p:1), so
+ *  the mapping must reflect the track active when the request fires, not
+ *  when the shell was wired. Return null when the packetId has no
+ *  repair-bearing track — the request is released without a fetch.
+ *  `catalogRepairTarget` builds the answer from a catalog. */
+export type ResolveRepairTarget = (
+  packetId: number,
+  catalogTrackName?: string,
+) => RepairTarget | null
+
+/** One on-demand repair FETCH, as the scheduler hands it to the transport. */
+export interface RepairFetchRequest {
+  /** Repair track whose block `sbn` is fetched. */
+  readonly repairTrack: string
+  /**
+   * The block's key, by `blockProfile` (BLO-35597 D2a):
+   * - `k-padded-v1`: the source block number, which IS the repair-track MoQ
+   *   group id (fetch `[sbn, sbn]`).
+   * - `iso-ssbg1-v1`: the block's 32-bit SS_Start. The MoQ group id is the
+   *   62-bit `extSsStart(wrapEpoch, sbn)`; a receiver that knows only a lost
+   *   SS_ID fetches `repairFetchRange(lostSsId, kMax, anchor)`, where `anchor`
+   *   is `{ previousBlockStart }` (the extended start of the last block
+   *   delimited before it) or `{ reference }` (an epoch reference). Never use
+   *   it as a group id directly.
+   */
+  readonly sbn: number
+  /** The block profile `sbn` is keyed by (the catalog `fec.blockProfile`). */
+  readonly blockProfile: FecBlockProfile
+  /** The source packetId the block belongs to. */
+  readonly packetId: number
+  /**
+   * Aborts when the scheduler no longer wants the group: preemption by
+   * keyframe work, reprioritisation, block resolution, track reset, dispose.
+   */
+  readonly signal: AbortSignal
+  /**
+   * The SUBSCRIBER_PRIORITY parameter the FETCH MUST carry, on the MoQ
+   * Transport scale (0..255, lower delivered first), as
+   * draft-ramadan-moq-fec §11.4.5 requires. `undefined` means OMIT the
+   * parameter: the catalog carries no priority to derive it from, and the
+   * publisher then uses the value draft-ietf-moq-transport-16 §9.2.2.3
+   * defines for an omitted parameter (128, inside the Source Media range).
+   * A transport never substitutes a value of its own. A transport whose API
+   * uses another scale (moq-lite's higher-wins weight, say) maps this one
+   * without reordering it against the source and repair subscriptions.
+   */
+  readonly subscriberPriority: number | undefined
+}
+
+/** Protocol-specific fetch of one FEC block's repair group.
+ *
+ *  Yield each repair object payload (MMTP packet bytes, ISO 23008-1 §C.5.3
+ *  Repair FEC Payload ID framing). Return when the group ends.
+ *
+ *  Put `request.subscriberPriority` on the FETCH (see RepairFetchRequest).
+ *
+ *  When `request.signal` aborts, the transport MUST cancel the FETCH ON THE
+ *  WIRE, not merely stop reading: send FETCH_CANCEL for its Request ID
+ *  (draft-ietf-moq-transport-16 §9.18; STOP_SENDING on an open data stream
+ *  as well, §5.2), and do it from the abort handler itself, before it
+ *  returns. A relay that is never told keeps sending the group, so a
+ *  preempted delta repair keeps competing with the keyframe repair that
+ *  preempted it. The scheduler may issue the next request for the same block
+ *  (reprioritisation) as soon as it aborts one, and §11.4.5 allows at most
+ *  one repair FETCH outstanding per block and repair layer, so the cancel
+ *  must already be queued ahead of that request. A FETCH whose Request ID
+ *  is not known yet is cancelled as soon as FETCH_OK assigns it. */
+export type RepairFetchTransport = (request: RepairFetchRequest) => AsyncIterable<Uint8Array>
+
+/** Why a request could not carry a catalog-derived priority. */
+export type RepairPriorityReason =
+  | 'source-priority-absent'
+  | 'source-priority-invalid'
+  | 'repair-priority-absent'
+  | 'repair-priority-invalid'
+
+/**
+ * The wire priority of one repair request (draft-ramadan-moq-fec §11.4.5).
+ *
+ * - `carry`: send the FETCH with `subscriberPriority`.
+ * - `omit`: send it without SUBSCRIBER_PRIORITY. Only a keyframe-bearing or
+ *   unknown block's request is ever sent this way: the publisher then uses
+ *   128 (draft-ietf-moq-transport-16 §9.2.2.3), which lies in the Source
+ *   Media range, and without a catalog source priority there is no bound
+ *   below it to honour.
+ * - `decline`: send no FETCH. A delta or audio FETCH MUST carry a priority
+ *   at least its repair track's, so at least 192, and the omitted value (128)
+ *   would put best-effort repair ahead of every repair track. Unicast repair
+ *   is optional for those classes (§11.4.3, §11.4.4); in-band FEC and
+ *   concealment still apply.
+ */
+export type RepairFetchPriority =
+  | { readonly kind: 'carry'; readonly subscriberPriority: number }
+  | { readonly kind: 'omit'; readonly reason: RepairPriorityReason }
+  | { readonly kind: 'decline'; readonly reason: RepairPriorityReason }
+
+function isMoqtPriority(value: number): boolean {
+  return Number.isSafeInteger(value) && value >= 0 && value <= MOQT_PRIORITY_MAX
+}
+
+/**
+ * Derive the SUBSCRIBER_PRIORITY of a repair FETCH from the block's class and
+ * the catalog priorities of its source and repair tracks
+ * (draft-ramadan-moq-fec §11.4.5 and the §10 ranges):
+ *
+ * - keyframe / unknown: in the Source Media range and no greater than the
+ *   source track's priority, i.e. min(source, 191); omitted when the catalog
+ *   carries no source priority.
+ * - delta / audio: no lower than the fetched repair track's priority and at
+ *   least 192, i.e. max(repair, 192); declined when it carries none.
+ */
+export function repairFetchSubscriberPriority(
+  blockClass: BlockClass,
+  target: Pick<RepairTarget, 'sourcePriority' | 'repairPriority'>,
+): RepairFetchPriority {
+  if (repairPriorityForClass(blockClass) === 0) {
+    const source = target.sourcePriority
+    if (source === null) return { kind: 'omit', reason: 'source-priority-absent' }
+    if (!isMoqtPriority(source)) return { kind: 'omit', reason: 'source-priority-invalid' }
+    return { kind: 'carry', subscriberPriority: Math.min(source, SOURCE_MEDIA_PRIORITY_MAX) }
+  }
+  const repair = target.repairPriority
+  if (repair === null) return { kind: 'decline', reason: 'repair-priority-absent' }
+  if (!isMoqtPriority(repair)) return { kind: 'decline', reason: 'repair-priority-invalid' }
+  return { kind: 'carry', subscriberPriority: Math.max(repair, REPAIR_PRIORITY_MIN) }
+}
+
+export interface WireRepairFetchOptions {
+  resolveTarget: ResolveRepairTarget
+  transport: RepairFetchTransport
+  /**
+   * Maximum transport attempts per block (required). A retry happens only
+   * when the transport rejects with an error `shouldRetry` classifies as
+   * retryable, before any symbol was fed, while the block's deadline remains.
+   */
+  attemptLimit: number
+  /** Classify a transport error as a transient publisher/relay retention race. */
+  shouldRetry?: (error: unknown) => boolean
+  /**
+   * The measured round-trip time of the reliable path the transport fetches
+   * over, in ms (required). Read at every admission, so it tracks the live
+   * session. A value that is not finite and positive, or a throw, means the
+   * path offers no measurement: nothing can show the FETCH would come back in
+   * time, so none is sent (`rtt-unmeasured`). Never a default.
+   */
+  reliableRttMs: () => number
+  /**
+   * How long after a block's first symbol arrived its media can still be
+   * presented, in ms (required): the player's own playout budget for the
+   * stream. Same fail-closed rule as `reliableRttMs`
+   * (`presentation-delay-unavailable`).
+   */
+  presentationDelayMs: (packetId: number, catalogTrackName?: string) => number
+}
+
+/** Why the D-28 layer asked for a repair: the block's class at its deadline. */
+export type RepairSubscribeCallback = (
+  sbn: number,
+  packetId: number,
+  catalogTrackName: string | undefined,
+  blockClass: BlockClass,
+) => void
+
+/** Why the scheduler sent no FETCH for a block it was asked to repair. */
+export type RepairSkipReason =
+  /** The reliable path offered no RTT measurement; arrival cannot be shown. */
+  | 'rtt-unmeasured'
+  /** The measured RTT is not less than the time left to the deadline. */
+  | 'rtt-exceeds-budget'
+  /** The player gave no usable presentation delay for the block's stream. */
+  | 'presentation-delay-unavailable'
+
+/** The subset of MulticastManager the scheduler drives. */
+export interface RepairFetchHost {
+  readonly fecManager: {
+    blockProfileForPacket(packetId: number): FecBlockProfile | undefined
+    repairFetchTimeoutMsForBlock(sbn: number, packetId: number, catalogTrackName?: string): number
+    /** Receiver-local time of the block's first accepted symbol, if any. */
+    blockAnchorAtMs(sbn: number, packetId: number, catalogTrackName?: string): number | undefined
+    /** How long a terminal block stays authoritative: the release-gate hold ceiling. */
+    terminalRetentionMsForPacket(packetId: number): number
+    /** Keep the block open to `untilAtMs` for an admitted FETCH. */
+    holdBlockForRepair(
+      sbn: number,
+      packetId: number,
+      catalogTrackName: string | undefined,
+      untilAtMs: number,
+    ): boolean
+    /** The admitted FETCH ended without delivering: back to the multicast wait. */
+    releaseRepairHold(sbn: number, packetId: number, catalogTrackName?: string): void
+  }
+  onRepairSubscribe(cb: RepairSubscribeCallback): void
+  addRepairLifecycleObserver(observer: RepairLifecycleObserver): () => void
+  addTrackResetObserver(observer: (packetId: number, catalogTrackName: string) => void): () => void
+  clearRepairForBlock(sbn: number, packetId: number, catalogTrackName?: string): void
+  processRepairFromMoQ(packet: Uint8Array, ownerPacketId?: number, catalogTrackName?: string): void
+  noteRepairScheduling(
+    type: 'repair-preempted' | 'repair-deferred',
+    sbn: number,
+    packetId: number,
+    catalogTrackName?: string,
+  ): void
+  /** A request whose wire priority the catalog could not supply. */
+  noteRepairPriority(
+    action: 'omitted' | 'declined',
+    reason: RepairPriorityReason,
+    blockClass: BlockClass,
+    sbn: number,
+    packetId: number,
+    catalogTrackName?: string,
+  ): void
+  /** A request the scheduler did not send (see RepairSkipReason). */
+  noteRepairSkipped(
+    reason: RepairSkipReason,
+    measurement: { readonly rttMs: number | null; readonly budgetMs: number },
+    sbn: number,
+    packetId: number,
+    catalogTrackName?: string,
+  ): void
+}
+
+type StopReason = 'preempted' | 'reprioritized' | 'expired' | 'resolved' | 'reset' | 'disposed'
+
+interface FetchRun {
+  readonly controller: AbortController
+  stopped: StopReason | null
+}
+
+interface RepairEntry {
+  readonly key: string
+  readonly sbn: number
+  readonly packetId: number
+  readonly catalogTrackName?: string
+  readonly repairTrack: string
+  readonly target: RepairTarget
+  /** The block profile `sbn` is keyed by, resolved before the entry is queued. */
+  readonly blockProfile: FecBlockProfile
+  priority: RepairPriority
+  /** SUBSCRIBER_PRIORITY for this entry's class; undefined = omit it. */
+  subscriberPriority: number | undefined
+  /**
+   * Absolute `performance.now()` millisecond by which a FETCH must land: the
+   * block's presentation deadline (see the module note).
+   */
+  readonly deadlineAt: number
+  /** Monotonic enqueue order, the EDF tie-break. */
+  readonly order: number
+  attempts: number
+  running: FetchRun | null
+}
+
+/**
+ * Wire the D-28 repair-fetch scheduler onto a MulticastManager.
+ *
+ * Call AFTER the manager has a repair-bearing FEC configuration (players gate
+ * this on the first fec-setup that carries a repairTrack) — registration arms
+ * the per-block repair deadlines in the FEC layer.
+ *
+ * Returns a dispose function that aborts outstanding fetches and stops new
+ * ones from being issued.
+ */
+export function wireRepairFetch(mc: RepairFetchHost, opts: WireRepairFetchOptions): () => void {
+  if (!Number.isSafeInteger(opts.attemptLimit) || opts.attemptLimit < 1) {
+    throw new Error(
+      `[RepairFetch] attemptLimit=${String(opts.attemptLimit)} must be a positive integer`,
+    )
+  }
+  if (typeof opts.reliableRttMs !== 'function') {
+    throw new Error('[RepairFetch] reliableRttMs is required: repair admission needs the measured reliable-path RTT')
+  }
+  if (typeof opts.presentationDelayMs !== 'function') {
+    throw new Error('[RepairFetch] presentationDelayMs is required: a repair FETCH is due by the block\'s presentation deadline')
+  }
+  const entries = new Map<string, RepairEntry>()
+  const warnedNoTarget = new Set<string>()
+  let disposed = false
+  let enqueueOrder = 0
+
+  const requestKey = (sbn: number, packetId: number, catalogTrackName?: string): string =>
+    JSON.stringify([packetId, catalogTrackName ?? null, sbn])
+  const noTargetKey = (packetId: number, catalogTrackName?: string): string =>
+    JSON.stringify([packetId, catalogTrackName ?? null])
+
+  const clearRepair = (sbn: number, packetId: number, catalogTrackName?: string): void => {
+    if (catalogTrackName === undefined) mc.clearRepairForBlock(sbn, packetId)
+    else mc.clearRepairForBlock(sbn, packetId, catalogTrackName)
+  }
+  const note = (type: 'repair-preempted' | 'repair-deferred', entry: RepairEntry): void => {
+    mc.noteRepairScheduling(type, entry.sbn, entry.packetId, entry.catalogTrackName)
+  }
+
+  const releaseHold = (entry: RepairEntry): void => {
+    if (entry.catalogTrackName === undefined) mc.fecManager.releaseRepairHold(entry.sbn, entry.packetId)
+    else mc.fecManager.releaseRepairHold(entry.sbn, entry.packetId, entry.catalogTrackName)
+  }
+
+  const stop = (entry: RepairEntry, reason: StopReason): void => {
+    const run = entry.running
+    if (!run) return
+    entry.running = null
+    run.stopped = reason
+    run.controller.abort()
+    // A preempted delta returns to the queue; until it runs again nothing is
+    // in flight that could land, so the block goes back to its multicast wait.
+    if (reason === 'preempted') releaseHold(entry)
+  }
+
+  const readRtt = (): number | null => {
+    try {
+      const rtt = opts.reliableRttMs()
+      return Number.isFinite(rtt) && rtt > 0 ? rtt : null
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * RTT admission: send only a FETCH the measured round trip says can land
+   * before the entry's deadline. A refused entry is released, not queued: the
+   * deadline only gets closer.
+   */
+  const admit = (entry: RepairEntry, now: number): boolean => {
+    const budgetMs = entry.deadlineAt - now
+    const rttMs = readRtt()
+    if (rttMs !== null && rttMs < budgetMs) return true
+    retire(entry)
+    releaseHold(entry)
+    clearRepair(entry.sbn, entry.packetId, entry.catalogTrackName)
+    mc.noteRepairSkipped(
+      rttMs === null ? 'rtt-unmeasured' : 'rtt-exceeds-budget',
+      { rttMs, budgetMs },
+      entry.sbn,
+      entry.packetId,
+      entry.catalogTrackName,
+    )
+    return false
+  }
+
+  const retire = (entry: RepairEntry): void => {
+    if (entries.get(entry.key) === entry) entries.delete(entry.key)
+  }
+
+  const urgentOutstanding = (): boolean => {
+    for (const entry of entries.values()) {
+      if (entry.priority < 2) return true
+    }
+    return false
+  }
+
+  const preemptDeltas = (): void => {
+    for (const entry of entries.values()) {
+      if (entry.priority !== 2 || !entry.running) continue
+      stop(entry, 'preempted')
+      note('repair-preempted', entry)
+    }
+  }
+
+  /**
+   * The wire priority for `blockClass`, or null when no FETCH may be sent.
+   * A priority the catalog cannot supply is reported once per request.
+   */
+  const wirePriority = (
+    entry: Pick<RepairEntry, 'target' | 'sbn' | 'packetId' | 'catalogTrackName'>,
+    blockClass: BlockClass,
+  ): { subscriberPriority: number | undefined } | null => {
+    const derived = repairFetchSubscriberPriority(blockClass, entry.target)
+    if (derived.kind === 'carry') return { subscriberPriority: derived.subscriberPriority }
+    mc.noteRepairPriority(
+      derived.kind === 'omit' ? 'omitted' : 'declined',
+      derived.reason,
+      blockClass,
+      entry.sbn,
+      entry.packetId,
+      entry.catalogTrackName,
+    )
+    return derived.kind === 'omit' ? { subscriberPriority: undefined } : null
+  }
+
+  /** `counted` is false for a reprioritisation restart, which is no retry. */
+  const start = (entry: RepairEntry, counted = true): void => {
+    if (!admit(entry, performance.now())) return
+    if (counted) entry.attempts++
+    const run: FetchRun = { controller: new AbortController(), stopped: null }
+    entry.running = run
+    // Hold the block open to the presentation deadline while this FETCH can
+    // still land: the multicast span elapsing must not abort it.
+    mc.fecManager.holdBlockForRepair(
+      entry.sbn,
+      entry.packetId,
+      entry.catalogTrackName,
+      entry.deadlineAt,
+    )
+    void execute(entry, run)
+  }
+
+  const dispatch = (): void => {
+    if (disposed) return
+    const now = performance.now()
+    const queued: RepairEntry[] = []
+    for (const entry of [...entries.values()]) {
+      if (entry.running) {
+        // A fetch still running at its block's fail bound can no longer land
+        // in time. Cancel it here rather than trust the transport or the FEC
+        // layer's resolution to end it: a hung P0/P1 left running would keep
+        // urgentOutstanding() true and gate every P2 for the session.
+        if (entry.deadlineAt <= now) {
+          stop(entry, 'expired')
+          retire(entry)
+          clearRepair(entry.sbn, entry.packetId, entry.catalogTrackName)
+        }
+        continue
+      }
+      if (entry.deadlineAt <= now) {
+        // The block's fail bound has passed; its resolution is imminent and
+        // no fetch can land in time.
+        retire(entry)
+        if (entry.priority === 2 && entry.attempts === 0) note('repair-deferred', entry)
+        clearRepair(entry.sbn, entry.packetId, entry.catalogTrackName)
+        continue
+      }
+      queued.push(entry)
+    }
+    for (const entry of queued) {
+      if (entry.priority < 2) start(entry)
+    }
+    if (urgentOutstanding()) return
+    queued
+      .filter((entry) => entry.priority === 2)
+      .sort((a, b) => a.deadlineAt - b.deadlineAt || a.order - b.order)
+      .forEach((entry) => start(entry))
+  }
+
+  const finish = (entry: RepairEntry, run: FetchRun, fed: number, error: unknown): void => {
+    if (run.stopped !== null || entry.running !== run || entries.get(entry.key) !== entry) {
+      return
+    }
+    entry.running = null
+    if (error === undefined) {
+      retire(entry)
+      // A fetch that ended without feeding anything cannot resolve the block;
+      // release the slot and the hold so failure accounting is not wedged. A
+      // fetch that fed symbols leaves resolution to the FEC layer.
+      if (fed === 0) {
+        releaseHold(entry)
+        clearRepair(entry.sbn, entry.packetId, entry.catalogTrackName)
+      }
+      dispatch()
+      return
+    }
+    const retryable =
+      fed === 0 &&
+      entry.attempts < opts.attemptLimit &&
+      entry.deadlineAt > performance.now() &&
+      opts.shouldRetry?.(error) === true
+    if (retryable) {
+      // Back through the same admission rule: a P2 retry waits for P0/P1.
+      dispatch()
+      return
+    }
+    retire(entry)
+    if (fed === 0) releaseHold(entry)
+    clearRepair(entry.sbn, entry.packetId, entry.catalogTrackName)
+    console.warn(
+      `[RepairFetch] fetch failed pid=${entry.packetId} sbn=${entry.sbn} track=${entry.repairTrack}:`,
+      error,
+    )
+    dispatch()
+  }
+
+  // The profile the block key is in; a stream reaching repair was configured
+  // from its catalog, so an absent profile is a wiring fault, not a default.
+  // Resolved when the request arrives (onRepairSubscribe below), never inside
+  // execute: there its throw would read as an ordinary fetch failure, warned
+  // once per block while the stream silently lost unicast repair.
+  const blockProfileOf = (packetId: number): FecBlockProfile => {
+    const profile = mc.fecManager.blockProfileForPacket(packetId)
+    if (profile === undefined) {
+      throw new Error(`[RepairFetch] packetId=${packetId} has no configured fec.blockProfile`)
+    }
+    return profile
+  }
+
+  const execute = async (entry: RepairEntry, run: FetchRun): Promise<void> => {
+    let fed = 0
+    try {
+      for await (const packet of opts.transport({
+        repairTrack: entry.repairTrack,
+        sbn: entry.sbn,
+        blockProfile: entry.blockProfile,
+        packetId: entry.packetId,
+        signal: run.controller.signal,
+        subscriberPriority: entry.subscriberPriority,
+      })) {
+        if (run.stopped !== null || entry.running !== run) break
+        fed++
+        if (entry.catalogTrackName === undefined) {
+          mc.processRepairFromMoQ(packet, entry.packetId)
+        } else {
+          mc.processRepairFromMoQ(packet, entry.packetId, entry.catalogTrackName)
+        }
+      }
+      finish(entry, run, fed, undefined)
+    } catch (error) {
+      finish(entry, run, fed, error ?? new Error('repair transport rejected'))
+    }
+  }
+
+  const removeResetObserver = mc.addTrackResetObserver((packetId, catalogTrackName) => {
+    for (const entry of [...entries.values()]) {
+      if (entry.packetId !== packetId || entry.catalogTrackName !== catalogTrackName) continue
+      retire(entry)
+      stop(entry, 'reset')
+    }
+    // A reset is when the packetId -> repair-track mapping can change, so
+    // re-arm the once-per-track warn for the new epoch.
+    warnedNoTarget.delete(noTargetKey(packetId, catalogTrackName))
+    dispatch()
+  })
+
+  const removeLifecycleObserver = mc.addRepairLifecycleObserver((event) => {
+    if (disposed) return
+    if (event.type === 'reclassified') {
+      const entry = entries.get(
+        requestKey(event.block.sbn, event.block.packetId, event.block.catalogTrackName ?? undefined),
+      )
+      if (!entry || entry.priority !== 2) return
+      const promoted = repairPriorityForClass(event.to)
+      if (promoted >= entry.priority) return
+      const wire = wirePriority(entry, event.to)
+      // A block leaves P2 only for P0, whose request is never declined.
+      if (wire === null) return
+      entry.priority = promoted
+      entry.subscriberPriority = wire.subscriberPriority
+      if (entry.running) {
+        // The running FETCH carries the delta priority. Cancel it and send
+        // the block's repair again under its new class (§11.4.5): a keyframe
+        // repair must not stay queued behind source media.
+        stop(entry, 'reprioritized')
+        start(entry, false)
+      }
+      preemptDeltas()
+      dispatch()
+      return
+    }
+    if (event.type !== 'recovered' && event.type !== 'failed') return
+    const entry = entries.get(
+      requestKey(event.block.sbn, event.block.packetId, event.block.catalogTrackName ?? undefined),
+    )
+    if (!entry) return
+    retire(entry)
+    if (entry.running) stop(entry, 'resolved')
+    else if (entry.priority === 2 && entry.attempts === 0) note('repair-deferred', entry)
+    dispatch()
+  })
+
+  /**
+   * The block's presentation deadline, or null when the player gives none.
+   *
+   * anchor + presentationDelay, clamped below by the multicast wait (the block
+   * is open that long whatever happens, so a FETCH landing inside it still
+   * counts) and above by anchor + the release gate's hold ceiling (a successor
+   * frame may not wait behind a block longer than that). A block no symbol
+   * reached has no anchor; its deadline is the multicast wait.
+   */
+  const presentationDeadlineAt = (
+    sbn: number,
+    packetId: number,
+    catalogTrackName: string | undefined,
+    now: number,
+  ): number | null => {
+    const waitDeadlineAt =
+      now + mc.fecManager.repairFetchTimeoutMsForBlock(sbn, packetId, catalogTrackName)
+    const anchor = mc.fecManager.blockAnchorAtMs(sbn, packetId, catalogTrackName)
+    if (anchor === undefined) return waitDeadlineAt
+    let delayMs: number
+    try {
+      delayMs = opts.presentationDelayMs(packetId, catalogTrackName)
+    } catch {
+      return null
+    }
+    if (!(Number.isFinite(delayMs) && delayMs > 0)) return null
+    const ceilingAt = anchor + mc.fecManager.terminalRetentionMsForPacket(packetId)
+    return Math.max(waitDeadlineAt, Math.min(anchor + delayMs, ceilingAt))
+  }
+
+  mc.onRepairSubscribe((sbn, packetId, catalogTrackName, blockClass) => {
+    if (disposed) {
+      clearRepair(sbn, packetId, catalogTrackName)
+      return
+    }
+    // Throws on a wiring fault, here and synchronously, before anything is
+    // queued (see blockProfileOf).
+    const blockProfile = blockProfileOf(packetId)
+
+    // Fire-time resolution — see ResolveRepairTarget.
+    const target = opts.resolveTarget(packetId, catalogTrackName)
+    if (!target) {
+      // A starved block with no repair target can only resolve via the fail
+      // bound. Say so, once per track: a null target is also the documented
+      // answer for a rung that carries no repair, and the typed lifecycle
+      // events already enumerate every block.
+      const warnKey = noTargetKey(packetId, catalogTrackName)
+      if (!warnedNoTarget.has(warnKey)) {
+        warnedNoTarget.add(warnKey)
+        console.warn(
+          `[RepairFetch] no repair target for pid=${packetId} sbn=${sbn}` +
+            `${catalogTrackName === undefined ? '' : ` track=${catalogTrackName}`}; releasing without a fetch`,
+        )
+      }
+      clearRepair(sbn, packetId, catalogTrackName)
+      return
+    }
+
+    const key = requestKey(sbn, packetId, catalogTrackName)
+    const previous = entries.get(key)
+    if (previous) {
+      retire(previous)
+      stop(previous, 'reset')
+    }
+    const identity = {
+      target,
+      sbn,
+      packetId,
+      ...(catalogTrackName === undefined ? {} : { catalogTrackName }),
+    }
+    const wire = wirePriority(identity, blockClass)
+    if (wire === null) {
+      // No conformant FETCH exists for this block (see RepairFetchPriority).
+      clearRepair(sbn, packetId, catalogTrackName)
+      return
+    }
+    const now = performance.now()
+    const deadlineAt = presentationDeadlineAt(sbn, packetId, catalogTrackName, now)
+    if (deadlineAt === null) {
+      clearRepair(sbn, packetId, catalogTrackName)
+      mc.noteRepairSkipped(
+        'presentation-delay-unavailable',
+        { rttMs: readRtt(), budgetMs: 0 },
+        sbn,
+        packetId,
+        catalogTrackName,
+      )
+      return
+    }
+    const entry: RepairEntry = {
+      key,
+      ...identity,
+      repairTrack: target.repairTrack,
+      blockProfile,
+      priority: repairPriorityForClass(blockClass),
+      subscriberPriority: wire.subscriberPriority,
+      deadlineAt,
+      order: enqueueOrder++,
+      attempts: 0,
+      running: null,
+    }
+    entries.set(key, entry)
+    if (entry.priority < 2) preemptDeltas()
+    dispatch()
+  })
+
+  return () => {
+    disposed = true
+    removeResetObserver()
+    removeLifecycleObserver()
+    for (const entry of [...entries.values()]) {
+      clearRepair(entry.sbn, entry.packetId, entry.catalogTrackName)
+      if (entry.running) releaseHold(entry)
+      stop(entry, 'disposed')
+    }
+    entries.clear()
+  }
+}