@blockcast/mmt-container 0.3.0 → 0.4.0-main.1e94b11199ea

package/src/multicast-transport.ts

@@ -269,7 +269,7 @@ export class MulticastTransport<TPacketContext = never> {
   // inside the window, instead of a clear+set pair on every packet.
   #watchdog: ReturnType<typeof setTimeout> | null = null
   #lastPacketAtMs = 0
-  #failbackWindowMs: number | null = null
+  #failbackWindowMs: number | null | undefined
   #onTakeover: (() => void) | null = null
   #onFailback: ((reason: MulticastFailbackReason) => void) | null = null
   // Data-plane-live edge: the first packet this join accepted. Everything
@@ -644,18 +644,24 @@ export class MulticastTransport<TPacketContext = never> {
     return this.#dataPlaneLive
   }
 
-  setFailbackWindowMs(windowMs: number): void {
-    if (!Number.isFinite(windowMs) || windowMs <= 0) {
+  setFailbackWindowMs(windowMs: number | null): void {
+    if (windowMs !== null && (!Number.isFinite(windowMs) || windowMs <= 0)) {
       throw new Error(
         `[MulticastTransport] failbackWindowMs=${windowMs}. ` +
         `Derive a positive failback window from the stream catalog.`,
       )
     }
     this.#failbackWindowMs = windowMs
-    // An armed timer was scheduled against the previous window; re-derive its
-    // wake-up from the last packet so a narrower window is not enforced late.
-    if (this.#watchdog !== null) {
-      clearTimeout(this.#watchdog)
+    if (windowMs === null) {
+      if (this.#watchdog !== null) clearTimeout(this.#watchdog)
+      this.#watchdog = null
+      return
+    }
+    // Re-enable against the last packet even when the previous policy disabled
+    // the watchdog: a silent live stream may never deliver another packet.
+    if (this.#watchdog !== null) clearTimeout(this.#watchdog)
+    this.#watchdog = null
+    if (this.#dataPlaneLive && this.#onFailback) {
       const silentMs = performance.now() - this.#lastPacketAtMs
       this.#armWatchdog(Math.max(0, Math.ceil(windowMs - silentMs)))
     }
@@ -1022,7 +1028,8 @@ export class MulticastTransport<TPacketContext = never> {
     }
     if (this.#watchdog !== null) return
     if (!this.#onFailback) return
-    if (this.#failbackWindowMs === null) {
+    if (this.#failbackWindowMs === null) return
+    if (this.#failbackWindowMs === undefined) {
       throw new Error(
         '[MulticastTransport] Failback watchdog requires a catalog-derived window',
       )
@@ -1033,7 +1040,7 @@ export class MulticastTransport<TPacketContext = never> {
   #armWatchdog(delayMs: number): void {
     this.#watchdog = setTimeout(() => {
       this.#watchdog = null
-      if (this.#disposed || !this.#onFailback || this.#failbackWindowMs === null) return
+      if (this.#disposed || !this.#onFailback || this.#failbackWindowMs == null) return
       const silentMs = performance.now() - this.#lastPacketAtMs
       if (silentMs < this.#failbackWindowMs) {
         this.#armWatchdog(Math.ceil(this.#failbackWindowMs - silentMs))

package/src/repair-fetch.ts

@@ -1,14 +1,19 @@
 /**
  * D-28 shared repair-fetch scheduler.
  *
- * Player-agnostic orchestration for per-SBN on-demand MoQ FEC repair
+ * Player-agnostic orchestration for per-block on-demand MoQ FEC repair
  * backfill. Each player (moqtail client, hang watch, Shaka MSF bridge)
- * supplies only its protocol verb via {@link RepairFetchTransport}:
+ * supplies only its protocol verb via {@link RepairFetchTransport}, fetching
+ * one block's repair group. Blocks are `iso-ssbg1-v1` (ISO/IEC 23008-1
+ * ssbg_mode1, the only FEC block profile), so that group's MoQ id is the
+ * 62-bit wrap-epoch-extended SS_Start, `extSsStart(wrapEpoch, ssStart)` from
+ * `@blockcast/mmt-fec` -- never the 32-bit block key itself (see
+ * `RepairFetchRequest.sbn`):
  *
- *   - 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)
+ *   - moqtail: standalone FETCH (FetchType.Standalone) of that one group
+ *   - moq-lite/hang: Subscribe with startGroup = endGroup = that group (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
@@ -52,14 +57,42 @@
  * than sent and cancelled -- and an admitted FETCH holds the block open to
  * that deadline, so the multicast span elapsing never aborts it.
  *
+ * Keyframe late-repair budget: a block that may hold a RAP may be given a
+ * longer deadline than the playout budget (`keyframeRepairBudgetMs`). Losing
+ * such a block costs every frame up to the next keyframe, so holding it open
+ * for a FETCH that lands within the budget trades a short hold for a GOP-long
+ * freeze. At a small playout budget (a low-latency target) the presentation
+ * deadline alone leaves less than one round trip by the time the multicast
+ * wait gives up on the block, so every keyframe request would be refused
+ * (`rtt-exceeds-budget`). Eligible (`keyframeBudgetEligible`): a `keyframe`
+ * block (in-band RAP evidence), and an `unknown` block only while its
+ * stream's classifier is `classifying`, where `unknown` means the window rule
+ * could not exclude a RAP. Under `all-protected` every block reads `unknown`
+ * whatever it holds, so there only RAP evidence earns the budget. Never
+ * audio (P1) or delta (P2), and never a block its repair group cannot
+ * complete (received sources + RSB_length < K'). The hold ends when its
+ * FETCH ends without making the block decodable, not at the budget.
+ *
+ * Every deadline is capped by the release gate's hold ceiling measured the
+ * way the gate measures it: from the earliest frame it holds for the stream
+ * (a surviving frame of the block itself is routed before a repair symbol
+ * states the block, so before its anchor), never later than from the anchor.
+ * A FETCH landing after the gate forced that frame out would recover media
+ * the gate then drops as stale.
+ *
  * 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 { parseFecBlockProfile, type FecBlockProfile } from '@blockcast/mmt-base'
+import {
+  repairPriorityForClass,
+  type BlockClass,
+  type ClassifierMode,
+  type RepairPriority,
+} from './block-policy.js'
 import type { RepairLifecycleObserver } from './multicast-manager.js'
 import { REPAIR_PRIORITY_MIN } from './repair-layers.js'
 
@@ -112,18 +145,24 @@ 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.
+   * The block's key: its 32-bit SS_Start (ISO/IEC 23008-1 C.5.3). The field
+   * keeps its historical name, but ssbg_mode1 blocks have no source block
+   * number (BLO-35597 D2a). The repair group's MoQ 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: SS_Start wraps at 2^32, a MoQ group id never goes
+   * backwards.
    */
   readonly sbn: number
-  /** The block profile `sbn` is keyed by (the catalog `fec.blockProfile`). */
+  /**
+   * The block profile `sbn` is keyed by: the catalog `fec.blockProfile`,
+   * which is always `iso-ssbg1-v1`. Required, and validated with
+   * `parseFecBlockProfile` when the request is queued, so a stream configured
+   * with any other token (the retired `k-padded-v1` included) never reaches
+   * the transport.
+   */
   readonly blockProfile: FecBlockProfile
   /** The source packetId the block belongs to. */
   readonly packetId: number
@@ -224,6 +263,30 @@ export function repairFetchSubscriberPriority(
   return { kind: 'carry', subscriberPriority: Math.max(repair, REPAIR_PRIORITY_MIN) }
 }
 
+/** What `RepairFetchHost.fecManager.blockSymbolCounts` reports for one open block. */
+export interface BlockSymbolCounts {
+  readonly sources: number
+  readonly repairs: number
+  readonly authoredLength: number | undefined
+  readonly repairGroupLength: number | undefined
+}
+
+/**
+ * Whether a block of `blockClass` may get the keyframe late-repair budget:
+ * a `keyframe` block always (in-band RAP evidence), an `unknown` block only
+ * while its stream's classifier is `classifying` (the window rule could not
+ * exclude a RAP). An `all-protected` stream reads `unknown` for every block,
+ * delta-only ones included, so there `unknown` is no evidence of a RAP and
+ * earns no hold. Audio and delta never do.
+ */
+export function keyframeBudgetEligible(
+  blockClass: BlockClass,
+  classifierMode: ClassifierMode | undefined,
+): boolean {
+  if (blockClass === 'keyframe') return true
+  return blockClass === 'unknown' && classifierMode === 'classifying'
+}
+
 export interface WireRepairFetchOptions {
   resolveTarget: ResolveRepairTarget
   transport: RepairFetchTransport
@@ -250,6 +313,20 @@ export interface WireRepairFetchOptions {
    * (`presentation-delay-unavailable`).
    */
   presentationDelayMs: (packetId: number, catalogTrackName?: string) => number
+  /**
+   * How long after the first symbol of a block that may hold a RAP a repair
+   * FETCH of it may still land, in ms (optional). Such a block
+   * (`keyframeBudgetEligible`) gets the larger of this and
+   * `presentationDelayMs`, still never later than the release gate's hold
+   * ceiling and never earlier than the multicast wait; RTT admission is
+   * unchanged. Losing a keyframe block costs the rest of its GOP, so a player
+   * may hold the block (and the frames released after it) while its FETCH is
+   * in flight rather than freeze to the next keyframe. Absent, throwing, or
+   * not finite and positive: every block gets the presentation deadline
+   * alone. Never applied to audio, delta, or an `unknown` block of an
+   * `all-protected` stream.
+   */
+  keyframeRepairBudgetMs?: (packetId: number, catalogTrackName?: string) => number
 }
 
 /** Why the D-28 layer asked for a repair: the block's class at its deadline. */
@@ -273,11 +350,25 @@ export type RepairSkipReason =
 export interface RepairFetchHost {
   readonly fecManager: {
     blockProfileForPacket(packetId: number): FecBlockProfile | undefined
-    repairFetchTimeoutMsForBlock(sbn: number, packetId: number, catalogTrackName?: string): number
+    repairFetchTimeoutMsForBlock(sbn: number, packetId: number, catalogTrackName?: string): number | undefined
     /** Receiver-local time of the block's first accepted symbol, if any. */
     blockAnchorAtMs(sbn: number, packetId: number, catalogTrackName?: string): number | undefined
+    /** The stream's classifier mode (optional; absent reads as unknown). */
+    classifierModeFor?(packetId: number, catalogTrackName?: string): { readonly mode: ClassifierMode }
+    /**
+     * An open block's received sources and distinct repair symbols, its K'
+     * (SSB_length) and RSB_length (optional). The repair group carries
+     * RSB_length symbols, so it can complete the block only when
+     * sources + RSB_length >= K'; a FETCH that ended leaving fewer than K'
+     * distinct symbols cannot be decoding it.
+     */
+    blockSymbolCounts?(
+      sbn: number,
+      packetId: number,
+      catalogTrackName?: string,
+    ): BlockSymbolCounts | undefined
     /** How long a terminal block stays authoritative: the release-gate hold ceiling. */
-    terminalRetentionMsForPacket(packetId: number): number
+    terminalRetentionMsForPacket(packetId: number): number | undefined
     /** Keep the block open to `untilAtMs` for an admitted FETCH. */
     holdBlockForRepair(
       sbn: number,
@@ -289,6 +380,20 @@ export interface RepairFetchHost {
     releaseRepairHold(sbn: number, packetId: number, catalogTrackName?: string): void
   }
   onRepairSubscribe(cb: RepairSubscribeCallback): void
+  /**
+   * Arrival time of the earliest frame the in-order release gate holds for
+   * the stream, or undefined (optional; absent, the block's anchor bounds the
+   * ceiling alone). The gate releases that frame `terminalRetentionMsForPacket`
+   * after it, whatever its blocks are doing.
+   */
+  earliestGatedFrameAtMs?(packetId: number, catalogTrackName?: string): number | undefined
+  /** The keyframe budget extended a request's deadline by `extensionMs` (optional). */
+  noteKeyframeBudgetGranted?(
+    extensionMs: number,
+    sbn: number,
+    packetId: number,
+    catalogTrackName?: string,
+  ): void
   addRepairLifecycleObserver(observer: RepairLifecycleObserver): () => void
   addTrackResetObserver(observer: (packetId: number, catalogTrackName: string) => void): () => void
   clearRepairForBlock(sbn: number, packetId: number, catalogTrackName?: string): void
@@ -308,10 +413,24 @@ export interface RepairFetchHost {
     packetId: number,
     catalogTrackName?: string,
   ): void
-  /** A request the scheduler did not send (see RepairSkipReason). */
+  /**
+   * A request the scheduler did not send (see RepairSkipReason).
+   * `measurement.priority` is the request's repair priority (0 keyframe or
+   * unknown, 1 audio, 2 delta).
+   */
   noteRepairSkipped(
     reason: RepairSkipReason,
-    measurement: { readonly rttMs: number | null; readonly budgetMs: number },
+    measurement: { readonly rttMs: number | null; readonly budgetMs: number; readonly priority?: RepairPriority },
+    sbn: number,
+    packetId: number,
+    catalogTrackName?: string,
+  ): void
+  /**
+   * A FETCH the scheduler admitted and handed to the transport (optional):
+   * every attempt, a retry or a reprioritised restart included.
+   */
+  noteRepairFetchSent?(
+    priority: RepairPriority,
     sbn: number,
     packetId: number,
     catalogTrackName?: string,
@@ -339,9 +458,10 @@ interface RepairEntry {
   subscriberPriority: number | undefined
   /**
    * Absolute `performance.now()` millisecond by which a FETCH must land: the
-   * block's presentation deadline (see the module note).
+   * block's presentation deadline (see the module note). Only ever moves
+   * later: a block reclassified from delta can gain the keyframe budget.
    */
-  readonly deadlineAt: number
+  deadlineAt: number
   /** Monotonic enqueue order, the EDF tie-break. */
   readonly order: number
   attempts: number
@@ -404,6 +524,18 @@ export function wireRepairFetch(mc: RepairFetchHost, opts: WireRepairFetchOption
     if (reason === 'preempted') releaseHold(entry)
   }
 
+  /** The keyframe budget for a P0 block, or null: absent, throwing or not positive. */
+  const readKeyframeBudget = (packetId: number, catalogTrackName: string | undefined): number | null => {
+    const reader = opts.keyframeRepairBudgetMs
+    if (reader === undefined) return null
+    try {
+      const budgetMs = reader(packetId, catalogTrackName)
+      return Number.isFinite(budgetMs) && budgetMs > 0 ? budgetMs : null
+    } catch {
+      return null
+    }
+  }
+
   const readRtt = (): number | null => {
     try {
       const rtt = opts.reliableRttMs()
@@ -427,7 +559,7 @@ export function wireRepairFetch(mc: RepairFetchHost, opts: WireRepairFetchOption
     clearRepair(entry.sbn, entry.packetId, entry.catalogTrackName)
     mc.noteRepairSkipped(
       rttMs === null ? 'rtt-unmeasured' : 'rtt-exceeds-budget',
-      { rttMs, budgetMs },
+      { rttMs, budgetMs, priority: entry.priority },
       entry.sbn,
       entry.packetId,
       entry.catalogTrackName,
@@ -479,6 +611,7 @@ export function wireRepairFetch(mc: RepairFetchHost, opts: WireRepairFetchOption
   const start = (entry: RepairEntry, counted = true): void => {
     if (!admit(entry, performance.now())) return
     if (counted) entry.attempts++
+    mc.noteRepairFetchSent?.(entry.priority, entry.sbn, entry.packetId, entry.catalogTrackName)
     const run: FetchRun = { controller: new AbortController(), stopped: null }
     entry.running = run
     // Hold the block open to the presentation deadline while this FETCH can
@@ -529,6 +662,45 @@ export function wireRepairFetch(mc: RepairFetchHost, opts: WireRepairFetchOption
       .forEach((entry) => start(entry))
   }
 
+  /**
+   * Whether the block may still be decoding from what it holds: false only
+   * when the host shows fewer distinct symbols than its K'. A FETCH that
+   * ended leaving it short delivered all it could (its group carries no more
+   * symbols), so holding the block, and every frame behind it, longer buys
+   * nothing: it goes back to its multicast wait. Unknown counts read as
+   * decodable (the FEC layer resolves the block).
+   */
+  const symbolCounts = (
+    sbn: number,
+    packetId: number,
+    catalogTrackName: string | undefined,
+  ): BlockSymbolCounts | undefined => {
+    try {
+      return mc.fecManager.blockSymbolCounts?.(sbn, packetId, catalogTrackName)
+    } catch {
+      return undefined
+    }
+  }
+  const decodable = (entry: RepairEntry): boolean => {
+    const counts = symbolCounts(entry.sbn, entry.packetId, entry.catalogTrackName)
+    if (counts === undefined || counts.authoredLength === undefined) return true
+    return counts.sources + counts.repairs >= counts.authoredLength
+  }
+  /**
+   * Whether the block's repair group can complete it: its received sources
+   * plus every symbol the group carries reach K'. A loss of more sources than
+   * the group has repair symbols (every source-only loss among them: the
+   * block then already holds the whole group) gets no FETCH-length hold. True
+   * while the counts are not known (no repair stated the block yet).
+   */
+  const groupCanComplete = (sbn: number, packetId: number, catalogTrackName: string | undefined): boolean => {
+    const counts = symbolCounts(sbn, packetId, catalogTrackName)
+    if (counts === undefined || counts.authoredLength === undefined || counts.repairGroupLength === undefined) {
+      return true
+    }
+    return counts.sources + counts.repairGroupLength >= counts.authoredLength
+  }
+
   const finish = (entry: RepairEntry, run: FetchRun, fed: number, error: unknown): void => {
     if (run.stopped !== null || entry.running !== run || entries.get(entry.key) !== entry) {
       return
@@ -539,7 +711,7 @@ export function wireRepairFetch(mc: RepairFetchHost, opts: WireRepairFetchOption
       // 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) {
+      if (fed === 0 || !decodable(entry)) {
         releaseHold(entry)
         clearRepair(entry.sbn, entry.packetId, entry.catalogTrackName)
       }
@@ -568,15 +740,18 @@ export function wireRepairFetch(mc: RepairFetchHost, opts: WireRepairFetchOption
 
   // 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.
+  // Any token other than `iso-ssbg1-v1` (the retired `k-padded-v1` included)
+  // is one too: `parseFecBlockProfile` refuses it, whatever an untyped host
+  // returns. 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)
+    const profile: unknown = mc.fecManager.blockProfileForPacket(packetId)
     if (profile === undefined) {
       throw new Error(`[RepairFetch] packetId=${packetId} has no configured fec.blockProfile`)
     }
-    return profile
+    return parseFecBlockProfile(profile, `[RepairFetch] packetId=${packetId} fec.blockProfile`)
   }
 
   const execute = async (entry: RepairEntry, run: FetchRun): Promise<void> => {
@@ -630,6 +805,19 @@ export function wireRepairFetch(mc: RepairFetchHost, opts: WireRepairFetchOption
       if (wire === null) return
       entry.priority = promoted
       entry.subscriberPriority = wire.subscriberPriority
+      // A block that turned out to carry a keyframe gets the keyframe budget
+      // its request would have had (never a shorter deadline than it had).
+      const promotedDeadline = presentationDeadlineAt(
+        entry.sbn,
+        entry.packetId,
+        entry.catalogTrackName,
+        performance.now(),
+        event.to,
+      )
+      if (promotedDeadline !== null && promotedDeadline.deadlineAt > entry.deadlineAt) {
+        entry.deadlineAt = promotedDeadline.deadlineAt
+        noteBudget(entry, promotedDeadline.extensionMs)
+      }
       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
@@ -659,18 +847,26 @@ export function wireRepairFetch(mc: RepairFetchHost, opts: WireRepairFetchOption
    * 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.
+   * reached has no anchor; its deadline is the multicast wait. The ceiling is
+   * measured from the earlier of the anchor and the earliest frame the gate
+   * holds for the stream (see the module note). A block that may hold a RAP
+   * (`keyframeBudgetEligible`) uses the larger of the presentation delay and
+   * the keyframe budget; `extensionMs` is how much later that made it.
    */
   const presentationDeadlineAt = (
     sbn: number,
     packetId: number,
     catalogTrackName: string | undefined,
     now: number,
-  ): number | null => {
-    const waitDeadlineAt =
-      now + mc.fecManager.repairFetchTimeoutMsForBlock(sbn, packetId, catalogTrackName)
+    blockClass: BlockClass,
+  ): { readonly deadlineAt: number; readonly extensionMs: number } | null => {
+    // Undefined: the packetId is no longer configured (released), so it has
+    // no repair budget.
+    const waitMs = mc.fecManager.repairFetchTimeoutMsForBlock(sbn, packetId, catalogTrackName)
+    if (waitMs === undefined) return null
+    const waitDeadlineAt = now + waitMs
     const anchor = mc.fecManager.blockAnchorAtMs(sbn, packetId, catalogTrackName)
-    if (anchor === undefined) return waitDeadlineAt
+    if (anchor === undefined) return { deadlineAt: waitDeadlineAt, extensionMs: 0 }
     let delayMs: number
     try {
       delayMs = opts.presentationDelayMs(packetId, catalogTrackName)
@@ -678,8 +874,40 @@ export function wireRepairFetch(mc: RepairFetchHost, opts: WireRepairFetchOption
       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))
+    const retentionMs = mc.fecManager.terminalRetentionMsForPacket(packetId)
+    if (retentionMs === undefined) return null
+    const ceilingAt = Math.min(anchor, earliestGatedFrameAt(packetId, catalogTrackName) ?? anchor) + retentionMs
+    const deadlineAt = (delay: number): number => Math.max(waitDeadlineAt, Math.min(anchor + delay, ceilingAt))
+    const base = deadlineAt(delayMs)
+    const budgetMs =
+      keyframeBudgetEligible(blockClass, classifierMode(packetId, catalogTrackName)) &&
+      groupCanComplete(sbn, packetId, catalogTrackName)
+        ? readKeyframeBudget(packetId, catalogTrackName)
+        : null
+    if (budgetMs === null || budgetMs <= delayMs) return { deadlineAt: base, extensionMs: 0 }
+    const extended = deadlineAt(budgetMs)
+    return { deadlineAt: extended, extensionMs: extended - base }
+  }
+
+  const earliestGatedFrameAt = (packetId: number, catalogTrackName: string | undefined): number | undefined => {
+    try {
+      const at = mc.earliestGatedFrameAtMs?.(packetId, catalogTrackName)
+      return at !== undefined && Number.isFinite(at) ? at : undefined
+    } catch {
+      return undefined
+    }
+  }
+
+  const classifierMode = (packetId: number, catalogTrackName: string | undefined): ClassifierMode | undefined => {
+    try {
+      return mc.fecManager.classifierModeFor?.(packetId, catalogTrackName).mode
+    } catch {
+      return undefined
+    }
+  }
+
+  const noteBudget = (entry: Pick<RepairEntry, 'sbn' | 'packetId' | 'catalogTrackName'>, extensionMs: number): void => {
+    if (extensionMs > 0) mc.noteKeyframeBudgetGranted?.(extensionMs, entry.sbn, entry.packetId, entry.catalogTrackName)
   }
 
   mc.onRepairSubscribe((sbn, packetId, catalogTrackName, blockClass) => {
@@ -729,12 +957,13 @@ export function wireRepairFetch(mc: RepairFetchHost, opts: WireRepairFetchOption
       return
     }
     const now = performance.now()
-    const deadlineAt = presentationDeadlineAt(sbn, packetId, catalogTrackName, now)
-    if (deadlineAt === null) {
+    const priority = repairPriorityForClass(blockClass)
+    const deadline = presentationDeadlineAt(sbn, packetId, catalogTrackName, now, blockClass)
+    if (deadline === null) {
       clearRepair(sbn, packetId, catalogTrackName)
       mc.noteRepairSkipped(
         'presentation-delay-unavailable',
-        { rttMs: readRtt(), budgetMs: 0 },
+        { rttMs: readRtt(), budgetMs: 0, priority },
         sbn,
         packetId,
         catalogTrackName,
@@ -746,14 +975,15 @@ export function wireRepairFetch(mc: RepairFetchHost, opts: WireRepairFetchOption
       ...identity,
       repairTrack: target.repairTrack,
       blockProfile,
-      priority: repairPriorityForClass(blockClass),
+      priority,
       subscriberPriority: wire.subscriberPriority,
-      deadlineAt,
+      deadlineAt: deadline.deadlineAt,
       order: enqueueOrder++,
       attempts: 0,
       running: null,
     }
     entries.set(key, entry)
+    noteBudget(entry, deadline.extensionMs)
     if (entry.priority < 2) preemptDeltas()
     dispatch()
   })

package/src/repair-layers.ts

@@ -20,7 +20,7 @@
 // rendition's `fec.repairTrack` and needs no `repair.renditions` entry; an
 // entry there is optional and, when present, must agree with the source.
 
-import { parseFecBlockProfile, type FecBlockProfile } from "@blockcast/mmt-base";
+import { isFecBlockProfile, parseFecBlockProfile, type FecBlockProfile } from "@blockcast/mmt-base";
 
 /** Lowest MoQT-scale priority a repair track may declare. */
 export const REPAIR_PRIORITY_MIN = 192;
@@ -44,7 +44,8 @@ export type RepairContractCode =
 	| "track_repair_overlay"
 	| "track_repair_geometry"
 	| "track_fec_bounds"
-	| "track_fec_block_profile";
+	| "track_fec_block_profile"
+	| "track_fec_block_profile_unimplemented";
 
 /** Reports one contract violation and never returns. */
 export type RepairContractFail = (code: RepairContractCode, path: string, message: string) => never;
@@ -69,12 +70,23 @@ export const throwRepairContractError: RepairContractFail = (code, path, message
  * the one rule both catalog dialects, the CMSF validator and the per-track
  * resolver apply.
  *
- * A `fec` block that declares an FEC instance (any `algorithm` other than
- * `"none"`) MUST name its block profile, so an absent or unknown token fails
- * with `track_fec_block_profile` at `path`. A block declaring no FEC instance
- * may omit it (returns undefined), but a token it does carry must be known.
- * The token is never defaulted and never inferred: `k-padded-v1` and
- * `iso-ssbg1-v1` carry identical wire tuples whose repair math differs.
+ * draft-ramadan-moq-fec §5.1 defines exactly one profile, `iso-ssbg1-v1`, and
+ * it is the only one this library implements. A `fec` block that declares an
+ * FEC instance (any `algorithm` other than `"none"`) MUST name it; a block
+ * declaring no FEC instance may omit the token (returns undefined), but a token
+ * it does carry must be implemented. Failures are reported at `path`:
+ *
+ * - `track_fec_block_profile_unimplemented`: a non-empty string that names no
+ *   implemented profile. The retired Blockcast-private `k-padded-v1` is one
+ *   such token; a near-miss such as `"iso-ssbg1"` is another, never
+ *   normalized.
+ * - `track_fec_block_profile`: no token on a declared FEC instance, or a value
+ *   that is not a non-empty string.
+ *
+ * The token is never defaulted and never inferred from the wire. A receiver
+ * treats either failure as "FEC unavailable" for that track alone (it consumes
+ * the source without FEC and joins none of its repair tracks); a conformance
+ * validator rejects the catalog.
  *
  * @param path JSON path of the `blockProfile` field, for the error.
  */
@@ -97,6 +109,14 @@ export function readFecBlockProfile(
 	fail: RepairContractFail,
 ): FecBlockProfile | undefined {
 	if (value === undefined && !declaresFecInstance) return undefined;
+	if (isFecBlockProfile(value)) return value;
+	if (typeof value === "string" && value.length > 0) {
+		return fail(
+			"track_fec_block_profile_unimplemented",
+			path,
+			`${JSON.stringify(value)} is not an implemented FEC block profile; only "iso-ssbg1-v1" is implemented`,
+		);
+	}
 	try {
 		return parseFecBlockProfile(value, "blockProfile");
 	} catch (error) {