@blockcast/mmt-container 0.1.0-main.149f78a4adae

package/src/fec-manager.ts

@@ -0,0 +1,1939 @@
+/**
+ * FEC Manager — codec-agnostic FEC decode service.
+ *
+ * Receives (packetId, sbn, esi, symbolData) tuples from any transport
+ * (MMTP, LOC, etc.) and manages FEC block lifecycle: source counting,
+ * WASM RaptorQ decode, block timeout, and recovery/failure notification.
+ *
+ * Extracted from MulticastManager to decouple FEC block logic from
+ * MMTP packet parsing and frame routing.
+ */
+
+import { computeFecDeliveryWindowMs } from './track-session.js'
+import { deriveFecInterleaveDepth } from '@blockcast/mmt-fec'
+
+import type { MmtpDeliveryProvenance } from './mfu-reassembler.js'
+import type {
+  FecWorkerClient,
+  FecTrackStats,
+  FecBlockSnapshot,
+  FrameMeta,
+  FecWorkerErrorCode,
+} from '@blockcast/fec-worker'
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimum valid FEC interleave depth in milliseconds, per spec §5.1
+ * (the interactive/gaming floor; broadcast/ATSC 3.0 ranges up to 10000ms).
+ *
+ * A protocol constant, NOT a tuning knob. Values below this floor are almost
+ * certainly a raw frame count (e.g. `2`) that a caller passed when no framerate
+ * was available to convert to ms (common on audio tracks). Feeding such a value
+ * into computeFecTimeout treats it as `2ms`, yielding a near-zero FEC block
+ * timeout that abandons startup FEC blocks before their repair symbols arrive
+ * (measured: moqtail startupFailed=4, shaka dropped=5.8% on startup). Timing
+ * derivations MUST reject sub-floor values and fall back to the established
+ * timeout instead of collapsing.
+ */
+export const MIN_INTERLEAVE_DEPTH_MS = 33
+const WORKER_ERROR_LOG_CAP = 5
+const WORKER_ERROR_KIND_CAP = 32
+const WORKER_ERROR_OVERFLOW_KIND = 'other'
+const STARTUP_REPAIR_WAIT_SOURCE_BOUNDARIES = 2
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Algorithm-agnostic FEC decoder backend interface.
+ *
+ * Implementations:
+ *   - RaptorQ WASM (mmt_wasm.js) — RFC 6330
+ *   - Reed-Solomon WASM — future
+ *   - XOR — future
+ *
+ * Source/repair symbol IDs follow ISO 23008-1 §C.5.2/C.5.3:
+ *   source: SS_ID (flat 32-bit symbol identifier)
+ *   repair: SS_Start + SSB_length + RS_ID (block-scoped repair coords)
+ */
+export type WasmFecDecoder = {
+  add_source(ss_id: number, data: Uint8Array, ts: number): Uint8Array | null
+  add_repair(ss_start: number, ssb_length: number, rs_id: number, data: Uint8Array, ts: number): Uint8Array | null
+  configure(oti: Uint8Array): void
+  cleanup(current_time: number): Uint8Array
+  cleanup_blocks_detailed(sbns: Uint32Array): Uint8Array
+  flush?(): void
+  reset_stats?(): void
+}
+
+/** Algorithm-agnostic FEC stats snapshot. */
+export interface FecStats {
+  sourcePackets: number
+  repairPackets: number
+  duplicateSymbols: number
+  blocksClean: number
+  blocksRecovered: number
+  blocksFailed: number
+  greenFillFrames: number
+  blocksComplete: number
+  mixedPathBlocks: number
+  recentBlockPathCounts: FecBlockPathCount[]
+  k: number
+  /** Of blocks with loss, what percentage were recovered (0-100). */
+  recoveryRate: number
+  /** What percentage of blocks had any loss (0-100). */
+  packetLossRate: number
+  /** Per-MMTP-packet-ID counters for the synchronous WASM decoder path. */
+  tracks: FecPacketStats[]
+  /** Latest Worker/WASM snapshot for each packet ID. */
+  workers: Array<FecTrackStats & { packetId: number }>
+  /** Main-thread repair symbols rejected before dispatch because their size did not match T. */
+  repairSymbolSizeMismatches: number
+  /** Bounded Worker error counts keyed by stable code, or message text for legacy errors. */
+  workerErrors: Record<string, number>
+}
+
+export interface FecPacketStats {
+  packetId: number
+  sourcePackets: number
+  repairPackets: number
+  duplicateSymbols: number
+  blocksClean: number
+  blocksRecovered: number
+  blocksFailed: number
+  greenFillFrames: number
+  blocksComplete: number
+  k: number
+  recoveryRate: number
+  packetLossRate: number
+}
+
+export type FecSymbolSource = 'multicast' | 'moq'
+
+export interface FecBlockPathCount {
+  packetId: number
+  sbn: number
+  catalogTrackName?: string
+  multicastSymbols: number
+  moqSymbols: number
+  complete: boolean
+}
+
+type FecLifecycleTrace = {
+  atMs: number
+  event: 'repair-requested' | 'repair-arrived' | 'timeout-queued' | 'cleanup-ack' | 'recovered' | 'failed'
+  packetId: number
+  sbn: number
+  catalogTrackName?: string
+  sourceCount: number
+  sourceEsis: number[]
+  repairRsIds: number[]
+  decoderPath: 'worker' | 'sync' | 'none'
+  deadlineRemainingMs?: number
+  pendingCleanup: boolean
+  rsId?: number
+}
+
+export interface FECManagerConfig {
+  k?: number
+  /** Symbol size in bytes (T). NOT repair count. */
+  symbolSize?: number
+  interleaveDepthMs?: number
+  fps?: number
+  /** Guarded block inactivity deadline derived from the full delivery geometry. */
+  timeoutMs?: number
+}
+
+interface ResolvedFECTrackConfig {
+  k: number
+  symbolSize: number
+  interleaveDepthMs: number
+  timeoutMs: number
+  fps?: number
+}
+
+interface MutableFecCounters {
+  sourcePackets: number
+  repairPackets: number
+  duplicateSymbols: number
+  blocksClean: number
+  blocksRecovered: number
+  blocksFailed: number
+  greenFillFrames: number
+}
+
+function newFecCounters(): MutableFecCounters {
+  return {
+    sourcePackets: 0,
+    repairPackets: 0,
+    duplicateSymbols: 0,
+    blocksClean: 0,
+    blocksRecovered: 0,
+    blocksFailed: 0,
+    greenFillFrames: 0,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// FECManager
+// ---------------------------------------------------------------------------
+
+export class FECManager {
+  // Per-track WASM RaptorQ decoders, keyed by physical stream identity.
+  #fecDecoders = new Map<string, { client: WasmFecDecoder; k: number }>()
+  /** @deprecated Use setFecDecoder(packetId, ...). Backwards-compat shim. */
+
+  // Per-track Worker-backed FEC decoders, keyed by physical stream identity.
+  // Worker-backed tracks use async decode — recovered frames arrive via onFrame callback,
+  // not synchronous return from feedSourceSymbol/feedRepairSymbol.
+  #workerClients = new Map<string, FecWorkerClient>()
+  // Worker setup can finish while an interleaved block is already collecting
+  // on the sync decoder. Keep that block on its original decoder so later
+  // source/repair symbols do not split across two RaptorQ states.
+  #syncDecoderBlockOwners = new Map<string, WasmFecDecoder>()
+  #decoderBlockOwners = new WeakMap<object, Map<number, {
+    catalogTrackName?: string
+    conflicted: boolean
+  }>>()
+
+  #fecK = 4
+  #fecSymbolSize = 0
+  #fecTimeoutMs = 500 // default 500ms; refined by setFramerate() when fps known
+  #trackConfigs = new Map<number, ResolvedFECTrackConfig>()
+  #fecStats = newFecCounters()
+  #fecTrackStats = new Map<number, MutableFecCounters>()
+  #fecWorkerStats = new Map<number, FecTrackStats>()
+  #fecStatsObservers = new Set<(packetId: number, stats: FecTrackStats) => void>()
+
+  // Block inactivity tracking: (packetId, SBN) -> timer. The deadline is
+  // derived from catalog geometry and refreshed on progress; only an idle
+  // block fails.
+  #activeBlocks = new Map<string, ReturnType<typeof setTimeout>>()
+  #activeBlockDeadlinesMs = new Map<string, number>()
+  #activeBlockTimeoutOwners = new Map<string, object>()
+  #lifecycleTrace: FecLifecycleTrace[] = []
+  // Worker-backed timeouts enqueue cleanup behind all prior symbol messages.
+  // Failure remains pending until cleanupComplete acknowledges that queue drain.
+  #pendingWorkerCleanups = new Set<string>()
+  #pendingWorkerCleanupClients = new Map<string, FecWorkerClient>()
+  // Source symbol count per track-scoped block — marks complete when K symbols arrive.
+  #blockSourceCounts = new Map<string, number>()
+  #blockSourceEsis = new Map<string, Set<number>>()
+  #blockRepairRsIds = new Map<string, Set<number>>()
+  // Blocks already recovered — prevents late source symbols from restarting timeouts.
+  // WASM removes blocks after recovery; late symbols create empty blocks returning null,
+  // which would falsely start new timeouts without this guard.
+  #completedBlocks = new Set<string>()
+  #seenSymbols = new Set<string>()
+  #blockPathCounts = new Map<string, FecBlockPathCount>()
+  // Exact catalog identity observed on accepted symbols for each FEC block.
+  // Conflicting identities collapse to null so recovery fails closed.
+  #blockCatalogTrackNames = new Map<string, string | null>()
+  // A receiver joins an already-running live stream in the middle of D
+  // interleaved source blocks. This applies to both multicast and reliable MoQ:
+  // a MoQ group boundary is not an FEC ESI=0 boundary. Those blocks are not
+  // packet loss because their earlier ESIs predate the subscription. Ignore
+  // each such block until ESI=0 establishes a complete boundary for the track.
+  // After that boundary, a first observed ESI>0 is real delivery loss and must
+  // continue through normal FEC recovery/failure accounting.
+  #startupAlignedPackets = new Set<string>()
+  #startupPartialBlocks = new Set<string>()
+  // A live multicast join can observe an ESI=0 source boundary before the
+  // repair lane catches up. Returning false here also drops that media packet
+  // at MmtpRouter, so the readiness probe is multicast-only and bounded: an
+  // actual multicast repair unlocks the next boundary, while a second source
+  // boundary fails open. Reliable MoQ media continues through normal startup
+  // alignment and retained MoQ repair cannot prove multicast readiness.
+  #startupRequireRepairReady = false
+  #startupRepairReadyPackets = new Set<string>()
+  #startupRepairBoundaryCounts = new Map<string, number>()
+  #startupRepairFailOpenPackets = new Set<string>()
+  // SBNs that reached K source-symbol arrivals via trackBlock. Used by the
+  // worker recovery suppression check (see onFrame handler below) so we only
+  // suppress `recovered=true` emits for blocks that ALSO completed cleanly
+  // via source symbols. Separating this from #completedBlocks (which is also
+  // populated by every worker frame emit, by failed timeouts, and by external
+  // callers) was the BLO-3323 L15 fix: the prior predicate caused blocksRecovered
+  // to stay at 0 because the SBN was always in #completedBlocks by the time the
+  // worker fired recovered=true.
+  #cleanlyCompletedBlocks = new Set<string>()
+  // D-28: blocks whose repair deadline already fired onRepairNeeded. At most
+  // one repair request per block; entries are removed when the block
+  // completes, recovers, or fails.
+  #repairRequestedBlocks = new Set<string>()
+  // D-28: repair-deadline timers refreshed by accepted source progress until
+  // the first repair request. A `null` value marks a deadline that already
+  // fired (never re-armed). At most K accepted source symbols can refresh the
+  // horizon, so browser scheduling delay cannot create an early loss signal
+  // and repair traffic cannot keep a block alive indefinitely.
+  #repairDeadlines = new Map<string, ReturnType<typeof setTimeout> | null>()
+  // Worker recovery emits all K source symbols. Track recovery once per block
+  // while routing only ESI slots that were absent from the direct source path.
+  #workerRecoveredBlocks = new Set<string>()
+
+  // Framerate detection state
+  #fpsDetected = false
+  #fecFps?: number
+  #fecInterleaveDepthMs = 0
+
+  // Worker error log rate-limiter — bounds console.warn output and exported
+  // error cardinality when the FEC Worker emits the same failure repeatedly
+  // with volatile packet details (e.g. ssStart) in the message text.
+  // Stable Worker codes aggregate those messages; uncoded/legacy messages are
+  // capped into an `other` bucket. This also covers wasm-bindgen
+  // "recursive use of an object" bubbled from add_source/add_repair during
+  // overlapping message processing). Without this, Point 5 of the 7-point
+  // validation harness — which caps headless warnings at 500 — fails even
+  // though the errors are duplicates of a single underlying event.
+  #workerErrorCounts = new Map<string, number>()
+  #repairSymbolSizeMismatchCount = 0
+
+  // Event callbacks — block lifecycle notifications for MmtpRouter wiring.
+  // NOTE: For sync WASM path, recovery routing is handled by MmtpRouter from
+  // feedSourceSymbol/feedRepairSymbol return values. For Worker path, recovery
+  // arrives via onBlockRecovered callback.
+  onBlockStarted:
+    | ((sbn: number, packetId: number, catalogTrackName?: string) => void)
+    | null = null
+  onBlockComplete:
+    | ((sbn: number, packetId: number, catalogTrackName?: string) => void)
+    | null = null
+  onBlockFailed:
+    | ((sbn: number, packetId?: number, catalogTrackName?: string) => void)
+    | null = null
+
+  // D-28 on-demand repair callbacks. When onRepairNeeded is registered, each
+  // block arms a one-shot repair deadline after the derived K-symbol source
+  // horizon; a block still short of K when it fires requests a per-SBN MoQ
+  // repair fetch upstream. The inactivity fail bound is unchanged either way —
+  // repair and failure are orthogonal timers, so wiring D-28 never delays
+  // failure accounting. onRepairResolved fires when a repair-requested block
+  // leaves the active set, with the outcome ("completed" after clean completion
+  // or recovery, "failed" at the fail bound) so the upstream in-flight slot
+  // (MulticastManager.clearRepairForBlock) can be released and logged.
+  onRepairNeeded:
+    | ((sbn: number, packetId: number, catalogTrackName?: string) => void)
+    | null = null
+  onRepairResolved:
+    | ((
+        sbn: number,
+        packetId: number,
+        outcome: 'completed' | 'failed',
+        catalogTrackName?: string,
+      ) => void)
+    | null = null
+
+  // Worker-path callbacks — async recovery and stats from FecWorkerClient.
+  onBlockRecovered: ((sbn: number, packetId: number, data: ArrayBuffer, meta: FrameMeta, catalogTrackName?: string) => void) | null = null
+  onFecStatsUpdate: ((packetId: number, stats: FecTrackStats) => void) | null = null
+  onGreenFill: ((sbn: number, packetId: number, data: ArrayBuffer) => void) | null = null
+
+  #streamKey(packetId: number, catalogTrackName?: string): string {
+    return catalogTrackName === undefined
+      ? `${packetId}`
+      : `${packetId}:${encodeURIComponent(catalogTrackName)}`
+  }
+
+  #belongsToPacket(key: string, packetId: number): boolean {
+    return Number(key.split(':', 1)[0]) === packetId
+  }
+
+  #belongsToStream(key: string, packetId: number, catalogTrackName: string): boolean {
+    if (!this.#belongsToPacket(key, packetId)) return false
+    const parts = key.split(':')
+    const encodedTrackName = encodeURIComponent(catalogTrackName)
+    if (parts.length === 2) return parts[1] === encodedTrackName
+    if (parts.length >= 3) return parts[2] === encodedTrackName
+    return false
+  }
+
+  #packetIdsForStreamKeys(keys: Set<string>): number[] {
+    return [...new Set([...keys].map((key) => Number(key.split(':', 1)[0])))]
+  }
+
+  #blockKey(sbn: number, packetId: number, catalogTrackName?: string): string {
+    const base = `${packetId}:${sbn}`
+    return catalogTrackName === undefined
+      ? base
+      : `${base}:${encodeURIComponent(catalogTrackName)}`
+  }
+
+  #parseBlockKey(key: string): { packetId: number; sbn: number; catalogTrackName?: string } {
+    const [packetIdText, sbnText, ...catalogParts] = key.split(':')
+    const catalogTrackName = catalogParts.length > 0
+      ? decodeURIComponent(catalogParts.join(':'))
+      : undefined
+    return {
+      packetId: Number(packetIdText) || 0,
+      sbn: Number(sbnText) || 0,
+      ...(catalogTrackName === undefined ? {} : { catalogTrackName }),
+    }
+  }
+
+  #decoderForPacket(packetId: number, catalogTrackName?: string) {
+    return this.#fecDecoders.get(this.#streamKey(packetId, catalogTrackName))
+      ?? this.#fecDecoders.get(this.#streamKey(packetId))
+  }
+
+  #workerForPacket(packetId: number, catalogTrackName?: string) {
+    return this.#workerClients.get(this.#streamKey(packetId, catalogTrackName))
+      ?? this.#workerClients.get(this.#streamKey(packetId))
+  }
+
+  #claimDecoderBlock(
+    client: object,
+    sbn: number,
+    catalogTrackName?: string,
+  ): boolean {
+    let blocks = this.#decoderBlockOwners.get(client)
+    if (!blocks) {
+      blocks = new Map()
+      this.#decoderBlockOwners.set(client, blocks)
+    }
+    const owner = blocks.get(sbn)
+    if (!owner) {
+      blocks.set(sbn, { catalogTrackName, conflicted: false })
+      if (blocks.size > 512) {
+        const stale = [...blocks.keys()].slice(0, 256)
+        for (const key of stale) blocks.delete(key)
+      }
+      return true
+    }
+    if (owner.conflicted) return false
+    if (owner.catalogTrackName === catalogTrackName) return true
+    owner.conflicted = true
+    return false
+  }
+
+  #decoderBlockCatalogTrackName(client: object, sbn: number): string | undefined {
+    const owner = this.#decoderBlockOwners.get(client)?.get(sbn)
+    return owner?.conflicted ? undefined : owner?.catalogTrackName
+  }
+
+  #resetDecoderBlockOwners(client: object, catalogTrackName: string): void {
+    const blocks = this.#decoderBlockOwners.get(client)
+    if (!blocks) return
+    for (const [sbn, owner] of blocks) {
+      if (owner.catalogTrackName === catalogTrackName || owner.conflicted) {
+        blocks.delete(sbn)
+      }
+    }
+    if (blocks.size === 0) this.#decoderBlockOwners.delete(client)
+  }
+
+  #discardFecDecoderClient(client: WasmFecDecoder): void {
+    for (const [key, entry] of this.#fecDecoders) {
+      if (entry.client === client) this.#fecDecoders.delete(key)
+    }
+    this.#decoderBlockOwners.delete(client)
+  }
+
+  #assertExclusiveDecoderClient(
+    streamKey: string,
+    client: object,
+    registrations: Iterable<readonly [string, object]>,
+    kind: 'decoder' | 'worker',
+  ): void {
+    for (const [registeredKey, registeredClient] of registrations) {
+      if (registeredClient !== client || registeredKey === streamKey) continue
+      throw new Error(
+        `[FECManager] ${kind} client is already registered for stream ${registeredKey}; ` +
+        `create one client per physical stream`,
+      )
+    }
+  }
+
+  #statsForPacket(packetId: number): MutableFecCounters {
+    let stats = this.#fecTrackStats.get(packetId)
+    if (!stats) {
+      stats = newFecCounters()
+      this.#fecTrackStats.set(packetId, stats)
+    }
+    return stats
+  }
+
+  #markPathBlockComplete(sbn: number, packetId: number, catalogTrackName?: string): void {
+    const block = this.#blockPathCounts.get(this.#blockKey(sbn, packetId, catalogTrackName))
+    if (block) block.complete = true
+  }
+
+  /** Cancel and forget a block's D-28 repair-deadline timer. */
+  #clearRepairDeadline(key: string): void {
+    const timer = this.#repairDeadlines.get(key)
+    if (timer != null) clearTimeout(timer)
+    this.#repairDeadlines.delete(key)
+  }
+
+  #requestRepair(
+    sbn: number,
+    packetId: number,
+    catalogTrackName?: string,
+  ): void {
+    const key = this.#blockKey(sbn, packetId, catalogTrackName)
+    if (
+      this.#completedBlocks.has(key) ||
+      !this.onRepairNeeded ||
+      this.#repairRequestedBlocks.has(key)
+    ) return
+
+    const deadline = this.#repairDeadlines.get(key)
+    if (deadline) clearTimeout(deadline)
+    this.#repairDeadlines.set(key, null)
+    this.#repairRequestedBlocks.add(key)
+
+    // Preserve the source-progress inactivity deadline and append exactly one
+    // bounded repair-fetch grace. Once requested, noteBlockActivity() no
+    // longer moves this terminal cleanup boundary.
+    const config = this.#resolveTrackConfig(packetId)
+    const graceMs = this.#repairGraceMs(config)
+    const now = performance.now()
+    const currentDeadline = this.#activeBlockDeadlinesMs.get(key) ?? now
+    this.#armBlockTimeout(
+      sbn,
+      packetId,
+      catalogTrackName,
+      Math.max(1, Math.ceil(Math.max(now, currentDeadline) + graceMs - now)),
+    )
+    this.#traceLifecycle('repair-requested', sbn, packetId, catalogTrackName)
+    if (catalogTrackName === undefined) {
+      this.onRepairNeeded(sbn, packetId)
+    } else {
+      this.onRepairNeeded(sbn, packetId, catalogTrackName)
+    }
+  }
+
+  #traceLifecycle(
+    event: FecLifecycleTrace['event'],
+    sbn: number,
+    packetId: number,
+    catalogTrackName?: string,
+    rsId?: number,
+  ): void {
+    const key = this.#blockKey(sbn, packetId, catalogTrackName)
+    const deadline = this.#activeBlockDeadlinesMs.get(key)
+    const decoderPath = this.#syncDecoderBlockOwners.has(key)
+      ? 'sync'
+      : this.#workerForPacket(packetId, catalogTrackName)
+        ? 'worker'
+        : this.#decoderForPacket(packetId, catalogTrackName)
+          ? 'sync'
+          : 'none'
+    this.#lifecycleTrace.push({
+      atMs: Date.now(),
+      event,
+      packetId,
+      sbn,
+      ...(catalogTrackName === undefined ? {} : { catalogTrackName }),
+      sourceCount: this.#blockSourceCounts.get(key) ?? 0,
+      sourceEsis: [...(this.#blockSourceEsis.get(key) ?? [])].sort((a, b) => a - b),
+      repairRsIds: [...(this.#blockRepairRsIds.get(key) ?? [])].sort((a, b) => a - b),
+      decoderPath,
+      ...(deadline === undefined
+        ? {}
+        : { deadlineRemainingMs: Math.max(0, deadline - performance.now()) }),
+      pendingCleanup: this.#pendingWorkerCleanups.has(key),
+      ...(rsId === undefined ? {} : { rsId }),
+    })
+    if (this.#lifecycleTrace.length > 64) this.#lifecycleTrace.splice(0, 32)
+  }
+
+  #defaultTrackConfig(): ResolvedFECTrackConfig {
+    return {
+      k: this.#fecK,
+      symbolSize: this.#fecSymbolSize,
+      interleaveDepthMs: this.#fecInterleaveDepthMs,
+      fps: this.#fecFps,
+      timeoutMs: this.#fecTimeoutMs,
+    }
+  }
+
+  #resolveTrackConfig(packetId: number): ResolvedFECTrackConfig {
+    return this.#trackConfigs.get(packetId) ?? this.#defaultTrackConfig()
+  }
+
+  #computeTimeout(config: {
+    k: number
+    interleaveDepthMs: number
+    fps?: number
+    timeoutMs?: number
+  }): number {
+    if (config.timeoutMs && config.timeoutMs > 0) return config.timeoutMs
+    // Only a valid §5.1 ms interleave (>= MIN_INTERLEAVE_DEPTH_MS) drives the
+    // timeout. A sub-floor value is a raw frame count (no fps to convert with);
+    // fall back to the established #fecTimeoutMs rather than collapse to ~0.
+    if (config.interleaveDepthMs >= MIN_INTERLEAVE_DEPTH_MS) {
+      return Math.max(
+        this.#fecTimeoutMs,
+        computeFecDeliveryWindowMs({
+          interleaveDepthMs: config.interleaveDepthMs,
+          sourceSymbols: config.k,
+          mediaUnitsPerSecond: config.fps,
+        }),
+      )
+    }
+    return this.#fecTimeoutMs
+  }
+
+  #repairDeadlineMs(config: ResolvedFECTrackConfig): number {
+    const halfFailBoundMs = Math.ceil(config.timeoutMs / 2)
+    if (
+      config.k > 0 &&
+      config.interleaveDepthMs >= MIN_INTERLEAVE_DEPTH_MS &&
+      config.fps !== undefined &&
+      Number.isFinite(config.fps) &&
+      config.fps > 0
+    ) {
+      const mediaUnitMs = 1000 / config.fps
+      const interleaveUnits = deriveFecInterleaveDepth(
+        config.interleaveDepthMs,
+        mediaUnitMs,
+      )
+      const sourceHorizonMs = Math.ceil(config.k * interleaveUnits * mediaUnitMs)
+      if (sourceHorizonMs < config.timeoutMs) return sourceHorizonMs
+    }
+    return halfFailBoundMs
+  }
+
+  #repairGraceMs(config: ResolvedFECTrackConfig): number {
+    return Math.max(1, config.timeoutMs - this.#repairDeadlineMs(config))
+  }
+
+  #armBlockTimeout(
+    sbn: number,
+    packetId: number,
+    catalogTrackName: string | undefined,
+    delayMs: number,
+  ): void {
+    const key = this.#blockKey(sbn, packetId, catalogTrackName)
+    const current = this.#activeBlocks.get(key)
+    if (current) clearTimeout(current)
+    const boundedDelayMs = Math.max(1, Math.ceil(delayMs))
+    this.#activeBlockDeadlinesMs.set(key, performance.now() + boundedDelayMs)
+    const owner = {}
+    this.#activeBlockTimeoutOwners.set(key, owner)
+    const timer = setTimeout(() => {
+      // clearTimeout() cannot retract a callback that the browser already
+      // moved onto its task queue. Only the timer that still owns this
+      // block's deadline may fail it or enqueue Worker cleanup.
+      if (this.#activeBlockTimeoutOwners.get(key) !== owner) return
+      this.#activeBlocks.delete(key)
+      this.#activeBlockDeadlinesMs.delete(key)
+      this.#activeBlockTimeoutOwners.delete(key)
+      this.#traceLifecycle('timeout-queued', sbn, packetId, catalogTrackName)
+
+      // A block that began on the synchronous decoder remains owned by that
+      // decoder even if Worker setup completed later. Cleanup must follow the
+      // same ownership rule as source and repair symbol dispatch.
+      const syncOwner = this.#syncDecoderBlockOwners.get(key)
+      if (syncOwner) {
+        this.#routeSyncCleanup(syncOwner, sbn, packetId)
+        this.#failBlock(sbn, packetId, false, catalogTrackName)
+        return
+      }
+
+      const workerClient = this.#workerForPacket(packetId, catalogTrackName)
+      if (workerClient) {
+        this.#pendingWorkerCleanups.add(key)
+        this.#pendingWorkerCleanupClients.set(key, workerClient)
+        workerClient.cleanup(sbn)
+      } else {
+        const decoder = this.#decoderForPacket(packetId, catalogTrackName)?.client
+        if (decoder) {
+          this.#routeSyncCleanup(decoder, sbn, packetId)
+          this.#failBlock(sbn, packetId, false, catalogTrackName)
+        } else {
+          this.#failBlock(sbn, packetId, false, catalogTrackName)
+        }
+      }
+    }, boundedDelayMs)
+    this.#activeBlocks.set(key, timer)
+  }
+
+  #upsertTrackConfig(packetId: number, config: FECManagerConfig): ResolvedFECTrackConfig {
+    const previous = this.#trackConfigs.get(packetId) ?? this.#defaultTrackConfig()
+    const timingChanged =
+      config.k !== undefined ||
+      config.interleaveDepthMs !== undefined ||
+      config.fps !== undefined
+    const next: ResolvedFECTrackConfig = {
+      k: config.k ?? previous.k,
+      symbolSize:
+        config.symbolSize != null && config.symbolSize > 0
+          ? config.symbolSize
+          : previous.symbolSize,
+      interleaveDepthMs: config.interleaveDepthMs ?? previous.interleaveDepthMs,
+      fps: config.fps ?? previous.fps,
+      timeoutMs: config.timeoutMs ?? (timingChanged ? 0 : previous.timeoutMs),
+    }
+    next.timeoutMs = this.#computeTimeout(next)
+    this.#trackConfigs.set(packetId, next)
+    return next
+  }
+
+  #normalizeSymbolData(packetId: number, data: Uint8Array): Uint8Array {
+    const symbolSize = this.symbolSizeForPacket(packetId)
+    if (symbolSize <= 0 || data.byteLength === symbolSize) return data
+    const normalized = new Uint8Array(symbolSize)
+    normalized.set(data.subarray(0, symbolSize))
+    return normalized
+  }
+
+  #blockKeysFor(sbn: number, packetId?: number, catalogTrackName?: string): string[] {
+    if (packetId != null && catalogTrackName !== undefined) {
+      return [this.#blockKey(sbn, packetId, catalogTrackName)]
+    }
+
+    const keys = new Set<string>()
+    for (const source of [
+      this.#activeBlocks,
+      this.#blockSourceCounts,
+      this.#blockCatalogTrackNames,
+    ]) {
+      for (const key of source.keys()) {
+        const block = this.#parseBlockKey(key)
+        if (
+          block.sbn === sbn &&
+          (packetId === undefined || block.packetId === packetId)
+        ) keys.add(key)
+      }
+    }
+    for (const source of [this.#completedBlocks, this.#cleanlyCompletedBlocks]) {
+      for (const key of source) {
+        const block = this.#parseBlockKey(key)
+        if (
+          block.sbn === sbn &&
+          (packetId === undefined || block.packetId === packetId)
+        ) keys.add(key)
+      }
+    }
+
+    if (packetId !== undefined) {
+      if (keys.size === 0) return [this.#blockKey(sbn, packetId)]
+      return keys.size === 1 ? [...keys] : []
+    }
+    return keys.size > 0 ? [...keys] : [this.#blockKey(sbn, 0, catalogTrackName)]
+  }
+
+  // -----------------------------------------------------------------------
+  // Accessors
+  // -----------------------------------------------------------------------
+
+  /** Internal state for diagnostics — not part of the public stats API. */
+  get diagnostics() {
+    return {
+      timeoutMs: this.#fecTimeoutMs,
+      activeBlocks: this.#activeBlocks.size,
+      completedBlocks: this.#completedBlocks.size,
+      pendingCounts: Object.fromEntries(this.#blockSourceCounts),
+      fpsDetected: this.#fpsDetected,
+      interleaveDepthMs: this.#fecInterleaveDepthMs,
+      startupAlignedPackets: this.#packetIdsForStreamKeys(this.#startupAlignedPackets),
+      startupPartialBlocks: this.#startupPartialBlocks.size,
+      startupRepairReadyPackets: this.#packetIdsForStreamKeys(this.#startupRepairReadyPackets),
+      startupRepairFailOpenPackets: this.#packetIdsForStreamKeys(this.#startupRepairFailOpenPackets),
+      pendingWorkerCleanups: this.#pendingWorkerCleanups.size,
+      repairTrackedBlocks: this.#blockRepairRsIds.size,
+      lifecycleTrace: this.#lifecycleTrace.map((entry) => ({ ...entry })),
+    }
+  }
+
+  get fecStats(): FecStats {
+    const s = this.#fecStats
+    const affected = s.blocksRecovered + s.blocksFailed
+    const total = s.blocksClean + affected
+    const tracks = [...this.#fecTrackStats.entries()]
+      .sort(([left], [right]) => left - right)
+      .map(([packetId, stats]) => {
+        const trackAffected = stats.blocksRecovered + stats.blocksFailed
+        const trackTotal = stats.blocksClean + trackAffected
+        return {
+          ...stats,
+          packetId,
+          blocksComplete: trackTotal,
+          k: this.#resolveTrackConfig(packetId).k,
+          recoveryRate: trackAffected > 0
+            ? (stats.blocksRecovered / trackAffected) * 100
+            : 100,
+          packetLossRate: trackTotal > 0 ? (trackAffected / trackTotal) * 100 : 0,
+        }
+      })
+    return {
+      ...s,
+      blocksComplete: total,
+      mixedPathBlocks: Array.from(this.#blockPathCounts.values()).filter(
+        (block) => block.multicastSymbols > 0 && block.moqSymbols > 0,
+      ).length,
+      recentBlockPathCounts: Array.from(this.#blockPathCounts.values()).slice(-24),
+      k: this.#fecK,
+      // True recovery rate: of blocks that HAD loss, how many were recovered?
+      recoveryRate: affected > 0 ? (s.blocksRecovered / affected) * 100 : 100,
+      packetLossRate: total > 0 ? (affected / total) * 100 : 0,
+      tracks,
+      workers: [...this.#fecWorkerStats.entries()]
+        .sort(([left], [right]) => left - right)
+        .map(([packetId, stats]) => ({
+          ...stats,
+          config: {
+            ...stats.config,
+            resolution: stats.config.resolution ? { ...stats.config.resolution } : undefined,
+          },
+          blocks: stats.blocks.map((block) => ({ ...block })),
+          decoder: stats.decoder ? { ...stats.decoder } : undefined,
+          altaFailedDetails: stats.altaFailedDetails?.map((detail) => ({ ...detail })),
+          packetId,
+        })),
+      repairSymbolSizeMismatches: this.#repairSymbolSizeMismatchCount,
+      workerErrors: Object.fromEntries(this.#workerErrorCounts),
+    }
+  }
+
+  /**
+   * Observe Worker-backed per-track snapshots without taking ownership of the
+   * legacy single-callback slot. Infrastructure diagnostics and a player may
+   * therefore consume the same source event without wrapping or replacing one
+   * another's callback.
+   */
+  addFecStatsObserver(
+    observer: (packetId: number, stats: FecTrackStats) => void,
+  ): () => void {
+    this.#fecStatsObservers.add(observer)
+    return () => this.#fecStatsObservers.delete(observer)
+  }
+
+  /** Start a new multicast transport join without discarding track/decoder state. */
+  beginMulticastJoin(): void {
+    this.#startupAlignedPackets.clear()
+    this.#startupPartialBlocks.clear()
+    this.#startupRequireRepairReady = true
+    this.#startupRepairReadyPackets.clear()
+    this.#startupRepairBoundaryCounts.clear()
+    this.#startupRepairFailOpenPackets.clear()
+  }
+
+  /** Begin a fresh decode epoch for one physical stream. */
+  resetTrack(packetId: number, catalogTrackName: string): void {
+    if (!Number.isInteger(packetId) || packetId < 0) {
+      throw new Error(`[FECManager] invalid packetId for reset: ${packetId}`)
+    }
+    if (!catalogTrackName) {
+      throw new Error('[FECManager] catalogTrackName is required for track reset')
+    }
+    const resetMap = <T>(map: Map<string, T>): void => {
+      for (const key of map.keys()) {
+        if (!this.#belongsToStream(key, packetId, catalogTrackName)) continue
+        map.delete(key)
+      }
+    }
+    const resetTimerMap = (
+      map: Map<string, ReturnType<typeof setTimeout> | null>,
+    ): void => {
+      for (const [key, timer] of map) {
+        if (!this.#belongsToStream(key, packetId, catalogTrackName)) continue
+        if (timer != null) clearTimeout(timer)
+        map.delete(key)
+      }
+    }
+    const resetSet = (set: Set<string>): void => {
+      for (const key of set) {
+        if (this.#belongsToStream(key, packetId, catalogTrackName)) set.delete(key)
+      }
+    }
+
+    resetTimerMap(this.#activeBlocks)
+    resetTimerMap(this.#repairDeadlines)
+    resetMap(this.#activeBlockDeadlinesMs)
+    resetMap(this.#activeBlockTimeoutOwners)
+    resetMap(this.#pendingWorkerCleanupClients)
+    resetMap(this.#blockSourceCounts)
+    resetMap(this.#blockSourceEsis)
+    resetMap(this.#blockRepairRsIds)
+    resetMap(this.#blockPathCounts)
+    resetMap(this.#blockCatalogTrackNames)
+    resetMap(this.#syncDecoderBlockOwners)
+    resetMap(this.#startupRepairBoundaryCounts)
+    resetSet(this.#pendingWorkerCleanups)
+    resetSet(this.#completedBlocks)
+    resetSet(this.#cleanlyCompletedBlocks)
+    resetSet(this.#repairRequestedBlocks)
+    resetSet(this.#workerRecoveredBlocks)
+    resetSet(this.#startupAlignedPackets)
+    resetSet(this.#startupPartialBlocks)
+    resetSet(this.#startupRepairReadyPackets)
+    resetSet(this.#startupRepairFailOpenPackets)
+    resetSet(this.#seenSymbols)
+
+    const decoderClients = new Set<WasmFecDecoder>()
+    for (const [key, entry] of this.#fecDecoders) {
+      if (this.#belongsToStream(key, packetId, catalogTrackName)) {
+        decoderClients.add(entry.client)
+      }
+    }
+    const clients = new Set<object>()
+    for (const client of decoderClients) {
+      if (
+        typeof client.flush === 'function' &&
+        typeof client.reset_stats === 'function'
+      ) {
+        try {
+          client.flush()
+          client.reset_stats()
+          clients.add(client)
+        } catch {
+          this.#discardFecDecoderClient(client)
+        }
+      } else {
+        this.#discardFecDecoderClient(client)
+      }
+    }
+    for (const [key, client] of this.#workerClients) {
+      if (!this.#belongsToStream(key, packetId, catalogTrackName)) continue
+      client.reset()
+      clients.add(client)
+    }
+    for (const client of clients) this.#resetDecoderBlockOwners(client, catalogTrackName)
+  }
+
+  /** Record a transport symbol and reject later duplicates of the same packetId/SBN/ESI. */
+  feedSymbolFromSource(
+    packetId: number,
+    sbn: number,
+    esi: number,
+    _data: Uint8Array,
+    source: FecSymbolSource,
+    catalogTrackName?: string,
+  ): boolean {
+    const blockKey = this.#blockKey(sbn, packetId, catalogTrackName)
+    const streamKey = this.#streamKey(packetId, catalogTrackName)
+    const k = this.kForPacket(packetId)
+    const isSourceSymbol = esi >= 0 && esi < k
+    const isStartupPartial = this.#startupPartialBlocks.has(blockKey)
+    const awaitingMulticastRepair =
+      this.#startupRequireRepairReady &&
+      source === 'multicast' &&
+      !this.#startupRepairReadyPackets.has(streamKey) &&
+      !this.#startupRepairFailOpenPackets.has(streamKey)
+    if (awaitingMulticastRepair) {
+      if (!isSourceSymbol) {
+        this.#startupRepairReadyPackets.add(streamKey)
+        this.#startupRepairBoundaryCounts.delete(streamKey)
+        this.#markStartupPartial(blockKey)
+        return false
+      }
+
+      if (esi === 0) {
+        const boundaries = (this.#startupRepairBoundaryCounts.get(streamKey) ?? 0) + 1
+        this.#startupRepairBoundaryCounts.set(streamKey, boundaries)
+        if (boundaries >= STARTUP_REPAIR_WAIT_SOURCE_BOUNDARIES) {
+          this.#startupRepairBoundaryCounts.delete(streamKey)
+          this.#startupRepairFailOpenPackets.add(streamKey)
+        } else {
+          this.#markStartupPartial(blockKey)
+          return false
+        }
+      } else {
+        this.#markStartupPartial(blockKey)
+        return false
+      }
+    }
+    if (isSourceSymbol && esi === 0) {
+      // ESI=0 establishes a complete source boundary for this SBN. Remove
+      // only this block: other interleaved SBNs may still be join partials.
+      this.#startupPartialBlocks.delete(blockKey)
+      this.#startupAlignedPackets.add(streamKey)
+    } else if (
+      isStartupPartial ||
+      !this.#startupAlignedPackets.has(streamKey)
+    ) {
+      this.#markStartupPartial(blockKey)
+      return false
+    }
+
+    // A completed block remains authoritative after its individual symbol
+    // identities age out of the bounded #seenSymbols cache. Without this
+    // guard, a delayed copy from the other transport can recreate the block
+    // inside a Worker decoder; that orphan never receives the full source and
+    // repair set, so cleanup later reports a false failure/green fill.
+    if (this.#completedBlocks.has(blockKey)) {
+      this.#fecStats.duplicateSymbols++
+      this.#statsForPacket(packetId).duplicateSymbols++
+      return false
+    }
+
+    const symbolKey = `${blockKey}:${esi}`
+    if (this.#seenSymbols.has(symbolKey)) {
+      this.#fecStats.duplicateSymbols++
+      this.#statsForPacket(packetId).duplicateSymbols++
+      return false
+    }
+    this.#seenSymbols.add(symbolKey)
+
+    const counts = this.#blockPathCounts.get(blockKey) ?? {
+      packetId,
+      sbn,
+      ...(catalogTrackName === undefined ? {} : { catalogTrackName }),
+      multicastSymbols: 0,
+      moqSymbols: 0,
+      complete: false,
+    }
+    if (source === 'multicast') counts.multicastSymbols++
+    else counts.moqSymbols++
+    this.#blockPathCounts.set(blockKey, counts)
+    this.#observeBlockCatalogTrackName(blockKey, catalogTrackName)
+
+    if (this.#seenSymbols.size > 4096) {
+      this.#seenSymbols = new Set(Array.from(this.#seenSymbols).slice(-2048))
+    }
+    if (this.#blockPathCounts.size > 512) {
+      this.#blockPathCounts = new Map(Array.from(this.#blockPathCounts).slice(-256))
+    }
+    if (this.#blockCatalogTrackNames.size > 512) {
+      this.#blockCatalogTrackNames = new Map(
+        Array.from(this.#blockCatalogTrackNames).slice(-256),
+      )
+    }
+
+    return true
+  }
+
+  #observeBlockCatalogTrackName(blockKey: string, catalogTrackName?: string): void {
+    if (catalogTrackName === undefined) return
+    if (!this.#blockCatalogTrackNames.has(blockKey)) {
+      this.#blockCatalogTrackNames.set(blockKey, catalogTrackName)
+      return
+    }
+    if (this.#blockCatalogTrackNames.get(blockKey) !== catalogTrackName) {
+      this.#blockCatalogTrackNames.set(blockKey, null)
+    }
+  }
+
+  /** Exact catalog identity retained for async recovery, if unambiguous. */
+  catalogTrackNameForBlock(
+    sbn: number,
+    packetId: number,
+    catalogTrackName?: string,
+  ): string | undefined {
+    if (catalogTrackName !== undefined) {
+      return this.#blockCatalogTrackNames.get(
+        this.#blockKey(sbn, packetId, catalogTrackName),
+      ) ?? undefined
+    }
+    const names = new Set<string>()
+    for (const [key, name] of this.#blockCatalogTrackNames) {
+      const block = this.#parseBlockKey(key)
+      if (block.packetId === packetId && block.sbn === sbn && name !== null) names.add(name)
+    }
+    return names.size === 1 ? [...names][0] : undefined
+  }
+
+  #markStartupPartial(blockKey: string): void {
+    this.#startupPartialBlocks.add(blockKey)
+    if (this.#startupPartialBlocks.size > 128) {
+      this.#startupPartialBlocks = new Set(
+        Array.from(this.#startupPartialBlocks).slice(-64),
+      )
+    }
+  }
+
+  /** Per-block state snapshot for FecBlockGrid visualization.
+   *  Returns the most recent blocks (active + recently completed). */
+  getBlockStates(): Array<{
+    sbn: number;
+    packetId?: number;
+    state: 'collecting' | 'complete' | 'failed';
+    sourceCount: number;
+    k: number;
+    progress: number;
+  }> {
+    const blocks: Array<{ sbn: number; packetId?: number; state: 'collecting' | 'complete' | 'failed'; sourceCount: number; k: number; progress: number }> = [];
+    // Active blocks (still collecting symbols)
+    for (const [key] of this.#activeBlocks) {
+      const { packetId, sbn } = this.#parseBlockKey(key);
+      const count = this.#blockSourceCounts.get(key) ?? 0;
+      const k = this.kForPacket(packetId);
+      blocks.push({ sbn, packetId, state: 'collecting', sourceCount: count, k, progress: k > 0 ? Math.min(count / k, 1) : 0 });
+    }
+    // Recently completed blocks (last 16)
+    const completed = [...this.#completedBlocks].slice(-16);
+    for (const key of completed) {
+      const { packetId, sbn } = this.#parseBlockKey(key);
+      if (!this.#activeBlocks.has(key)) {
+        const k = this.kForPacket(packetId);
+        blocks.push({ sbn, packetId, state: 'complete', sourceCount: k, k, progress: 1 });
+      }
+    }
+    blocks.sort((a, b) => a.sbn - b.sbn || (a.packetId ?? 0) - (b.packetId ?? 0));
+    return blocks.slice(-24); // cap at 24 most recent
+  }
+
+  /** The raw WASM decoder for stats access (first registered decoder) */
+  get wasmDecoder(): WasmFecDecoder | null {
+    return this.#fecDecoders.values().next().value?.client ?? null
+  }
+
+  get k(): number { return this.#fecK }
+  kForPacket(packetId: number): number { return this.#resolveTrackConfig(packetId).k }
+  /** FEC symbol size in bytes. */
+  get symbolSize(): number { return this.#fecSymbolSize }
+  symbolSizeForPacket(packetId: number): number { return this.#resolveTrackConfig(packetId).symbolSize }
+  /** FEC interleave window in milliseconds (0 = no interleaving). */
+  get interleaveDepthMs(): number { return this.#fecInterleaveDepthMs }
+  interleaveDepthMsForPacket(packetId: number): number { return this.#resolveTrackConfig(packetId).interleaveDepthMs }
+  /** Resolved per-track block fail bound in milliseconds. */
+  timeoutMsForPacket(packetId: number): number { return this.#resolveTrackConfig(packetId).timeoutMs }
+  /** Resolved per-track D-28 repair request deadline in milliseconds. */
+  repairDeadlineMsForPacket(packetId: number): number {
+    return this.#repairDeadlineMs(this.#resolveTrackConfig(packetId))
+  }
+  /** Remaining fetch budget for a specific repair-requested block. */
+  repairFetchTimeoutMsForBlock(
+    sbn: number,
+    packetId: number,
+    catalogTrackName?: string,
+  ): number {
+    const deadlineMs = this.#activeBlockDeadlinesMs.get(
+      this.#blockKey(sbn, packetId, catalogTrackName),
+    )
+    if (deadlineMs !== undefined) {
+      return Math.max(1, Math.ceil(deadlineMs - performance.now()))
+    }
+    const trackConfig = this.#resolveTrackConfig(packetId)
+    return Math.max(1, trackConfig.timeoutMs - this.#repairDeadlineMs(trackConfig))
+  }
+
+  // -----------------------------------------------------------------------
+  // Configuration
+  // -----------------------------------------------------------------------
+
+  /** Configure FEC parameters. */
+  configure(config: FECManagerConfig): void {
+    if (config.k != null) this.#fecK = config.k
+    if (config.symbolSize != null && config.symbolSize > 0) this.#fecSymbolSize = config.symbolSize
+    if (config.interleaveDepthMs != null) this.#fecInterleaveDepthMs = config.interleaveDepthMs
+    if (config.fps != null && Number.isFinite(config.fps) && config.fps > 0) {
+      this.#fecFps = config.fps
+    }
+    // interleaveDepthMs is in milliseconds per spec §5.1.
+    // Valid range: 33ms (interactive/gaming) to 10000ms (broadcast ATSC 3.0).
+    // Warn if value looks like frame count instead of ms (common misconfiguration).
+    if (config.interleaveDepthMs != null && config.interleaveDepthMs > 0 && config.interleaveDepthMs < MIN_INTERLEAVE_DEPTH_MS) {
+      console.warn(`[FECManager] interleaveDepthMs=${config.interleaveDepthMs} looks like frame count, not milliseconds (§5.1 requires ms). Expected range: ${MIN_INTERLEAVE_DEPTH_MS}-10000ms.`)
+    }
+    if (config.timeoutMs != null && config.timeoutMs > 0) {
+      this.#fecTimeoutMs = config.timeoutMs
+    } else if (
+      config.interleaveDepthMs != null &&
+      config.interleaveDepthMs >= MIN_INTERLEAVE_DEPTH_MS
+    ) {
+      this.#fecTimeoutMs = computeFecDeliveryWindowMs({
+        interleaveDepthMs: config.interleaveDepthMs,
+        sourceSymbols: this.#fecK,
+        symbolSize: this.#fecSymbolSize,
+        mediaUnitsPerSecond: config.fps,
+      })
+    }
+    // A shared multicast parser receives every packetId. Keep existing track
+    // deadlines at least as wide as the selected video delivery envelope so a
+    // short audio interleave cannot expire during browser/AMT scheduling gaps.
+    for (const [packetId, track] of this.#trackConfigs) {
+      if (track.timeoutMs < this.#fecTimeoutMs) {
+        this.#trackConfigs.set(packetId, { ...track, timeoutMs: this.#fecTimeoutMs })
+      }
+    }
+  }
+
+  /** Configure FEC parameters for one packetId without changing legacy defaults. */
+  configureTrack(packetId: number, config: FECManagerConfig): void {
+    this.#upsertTrackConfig(packetId, config)
+  }
+
+  /** Register a FEC decoder for a specific packetId (track). */
+  setFecDecoder(
+    packetId: number,
+    client: WasmFecDecoder,
+    k: number,
+    config?: FECManagerConfig,
+    catalogTrackName?: string,
+  ): void {
+    const streamKey = this.#streamKey(packetId, catalogTrackName)
+    this.#assertExclusiveDecoderClient(
+      streamKey,
+      client,
+      [...this.#fecDecoders].map(([key, entry]) => [key, entry.client] as const),
+      'decoder',
+    )
+    const trackConfig = this.#upsertTrackConfig(packetId, { ...config, k })
+    this.#fecDecoders.set(streamKey, { client, k: trackConfig.k })
+  }
+
+  /**
+   * Register a Worker-backed FEC decoder for a specific packetId (track).
+   *
+   * Worker-backed tracks decode asynchronously — feedSourceSymbol/feedRepairSymbol
+   * return null immediately, and recovered frames arrive via the onBlockRecovered callback.
+   *
+   * Takes precedence over sync WASM decoders for the same packetId.
+   */
+  setFecWorker(
+    packetId: number,
+    client: FecWorkerClient,
+    config: FECManagerConfig,
+    catalogTrackName?: string,
+  ): void {
+    const k = config?.k
+    if (k === undefined || !Number.isFinite(k) || k <= 0) {
+      throw new Error(`[FECManager] packetId=${packetId} Worker requires an explicit positive k`)
+    }
+    const symbolSize = config.symbolSize
+    if (symbolSize === undefined || !Number.isFinite(symbolSize) || symbolSize <= 0) {
+      throw new Error(
+        `[FECManager] packetId=${packetId} Worker requires an explicit positive symbolSize`,
+      )
+    }
+    const streamKey = this.#streamKey(packetId, catalogTrackName)
+    this.#assertExclusiveDecoderClient(
+      streamKey,
+      client,
+      this.#workerClients,
+      'worker',
+    )
+    if (config) this.#upsertTrackConfig(packetId, config)
+    const workerK = this.#resolveTrackConfig(packetId).k
+    this.#workerClients.set(streamKey, client)
+
+    client.onFrame((data: ArrayBuffer, meta: FrameMeta) => {
+      if (meta.recovered) {
+        // Recovered Worker events represent one exact source-symbol position.
+        // Block-completion accounting needs that exact ESI, and counting an
+        // ESI-less event as recovered would report healthy FEC while dropping
+        // the media. Enforce the Worker contract before any recovery metric.
+        if (!Number.isInteger(meta.esi) || meta.esi! < 0 || meta.esi! >= workerK) {
+          const kind = 'recovered-symbol-missing-esi'
+          const seen = this.#workerErrorCounts.get(kind) ?? 0
+          this.#workerErrorCounts.set(kind, seen + 1)
+          if (seen < WORKER_ERROR_LOG_CAP) {
+            console.warn(
+              `[FECManager] Dropping recovered symbol without valid ESI: pid=${packetId} sbn=${meta.sbn} esi=${String(meta.esi)}`,
+            )
+          }
+          return
+        }
+        const esi = meta.esi!
+
+        // Suppress duplicate routing when the worker fires recovered=true
+        // for a block ALREADY CLEANLY COMPLETED by K source symbols.
+        //
+        // BLO-3323 L15: predicate was previously `#completedBlocks.has(sbn)`,
+        // but `#completedBlocks` is populated by 5 paths (clean K-arrival,
+        // failed timeout, every worker frame emit via markBlockCompleted below,
+        // external markBlockCompleted, and cancelBlockTimeout). The first
+        // worker frame for a block adds the SBN, so subsequent recovered=true
+        // emits for the same block were always suppressed → blocksRecovered
+        // stayed at 0 even when recovery actually fired. Switching to the
+        // narrower #cleanlyCompletedBlocks set (populated only by trackBlock
+        // when count >= K) preserves the original dedup intent (BLO-3035
+        // layer 4 — don't double-route a block already received via source)
+        // while letting genuinely-recovered blocks bump the counter.
+        const recoveredCatalogTrackName = catalogTrackName
+          ?? this.#decoderBlockCatalogTrackName(client, meta.sbn)
+        if (!this.#claimDecoderBlock(client, meta.sbn, recoveredCatalogTrackName)) return
+        const blockKey = this.#blockKey(meta.sbn, packetId, recoveredCatalogTrackName)
+        const cleanlyCompleted = this.#cleanlyCompletedBlocks.has(blockKey)
+        if (!cleanlyCompleted) {
+          if (!this.#workerRecoveredBlocks.has(blockKey)) {
+            this.#traceLifecycle(
+              'recovered',
+              meta.sbn,
+              packetId,
+              recoveredCatalogTrackName,
+            )
+            this.#workerRecoveredBlocks.add(blockKey)
+            this.#fecStats.blocksRecovered++
+            this.#statsForPacket(packetId).blocksRecovered++
+            if (this.#workerRecoveredBlocks.size > 1000) {
+              const stale = Array.from(this.#workerRecoveredBlocks).slice(0, 500)
+              for (const key of stale) this.#workerRecoveredBlocks.delete(key)
+            }
+          }
+
+          // RaptorQ returns the full K-symbol block, not only erased symbols.
+          // The direct path already parsed every source ESI in #seenSymbols;
+          // routing those symbols again injects duplicate MFU fragments and can
+          // leave a real FI=3 tail followed by duplicate FI=2 fragments.
+          const symbolKey = `${blockKey}:${esi}`
+          if (!this.#seenSymbols.has(symbolKey)) {
+            this.#seenSymbols.add(symbolKey)
+            this.onBlockRecovered?.(
+              meta.sbn,
+              packetId,
+              data,
+              meta,
+              recoveredCatalogTrackName,
+            )
+          }
+        }
+
+        // The worker emits recovered source symbols in ESI order. Complete the
+        // block only after the final slot so assemblers receive every missing
+        // symbol before their completion callback flushes buffered media.
+        if (
+          esi >= workerK - 1 &&
+          !this.#completedBlocks.has(blockKey)
+        ) {
+          this.cancelBlockTimeout(meta.sbn, packetId, recoveredCatalogTrackName)
+          if (recoveredCatalogTrackName === undefined) {
+            this.onBlockComplete?.(meta.sbn, packetId)
+          } else {
+            this.onBlockComplete?.(
+              meta.sbn,
+              packetId,
+              recoveredCatalogTrackName,
+            )
+          }
+        }
+      } else {
+        const completedCatalogTrackName = catalogTrackName
+          ?? this.#decoderBlockCatalogTrackName(client, meta.sbn)
+        this.markBlockCompleted(meta.sbn, packetId, completedCatalogTrackName)
+      }
+    })
+
+    client.onSnapshot((stats: FecTrackStats) => {
+      this.#fecWorkerStats.set(packetId, stats)
+      try {
+        this.onFecStatsUpdate?.(packetId, stats)
+      } catch (error) {
+        console.warn('[FECManager] FEC stats callback failed:', error)
+      }
+      for (const observer of this.#fecStatsObservers) {
+        try {
+          observer(packetId, stats)
+        } catch (error) {
+          console.warn('[FECManager] FEC stats observer failed:', error)
+        }
+      }
+    })
+
+    client.onGreenFill((sbn: number, data: ArrayBuffer) => {
+      this.#fecStats.greenFillFrames++
+      this.#statsForPacket(packetId).greenFillFrames++
+      this.onGreenFill?.(sbn, packetId, data)
+    })
+
+    client.onCleanupComplete((sbn: number) => {
+      const cleanupKeys = [...this.#pendingWorkerCleanups].filter((key) => {
+        const block = this.#parseBlockKey(key)
+        return block.packetId === packetId &&
+          block.sbn === sbn &&
+          this.#pendingWorkerCleanupClients.get(key) === client
+      })
+      for (const key of cleanupKeys) {
+        this.#pendingWorkerCleanups.delete(key)
+        this.#pendingWorkerCleanupClients.delete(key)
+        if (this.#completedBlocks.has(key)) continue
+        const block = this.#parseBlockKey(key)
+        this.#traceLifecycle(
+          'cleanup-ack',
+          sbn,
+          packetId,
+          block.catalogTrackName,
+        )
+        this.#failBlock(sbn, packetId, false, block.catalogTrackName)
+      }
+    })
+
+    client.onError((msg: string, code?: FecWorkerErrorCode) => {
+      const requestedKind = code ?? msg
+      const kind =
+        this.#workerErrorCounts.has(requestedKind) ||
+        this.#workerErrorCounts.size < WORKER_ERROR_KIND_CAP - 1
+          ? requestedKind
+          : WORKER_ERROR_OVERFLOW_KIND
+      const seen = this.#workerErrorCounts.get(kind) ?? 0
+      this.#workerErrorCounts.set(kind, seen + 1)
+      if (seen < WORKER_ERROR_LOG_CAP) {
+        console.warn('[FECManager] Worker error:', msg)
+      } else if (seen === WORKER_ERROR_LOG_CAP) {
+        console.warn(
+          `[FECManager] Worker error (suppressing further copies of ${kind}): ${msg}`,
+        )
+      }
+    })
+  }
+
+  /** Called by player when framerate is known (from decoder output). Refines FEC block timeout. */
+  setFramerate(fps: number): void {
+    if (this.#fpsDetected || fps <= 0) return
+    this.#fpsDetected = true
+    this.#fecFps = fps
+    // Only a valid §5.1 ms interleave refines the timeout; a sub-floor value is
+    // a raw frame count and would collapse it (see MIN_INTERLEAVE_DEPTH_MS).
+    if (this.#fecInterleaveDepthMs >= MIN_INTERLEAVE_DEPTH_MS) {
+      this.#fecTimeoutMs = computeFecDeliveryWindowMs({
+        interleaveDepthMs: this.#fecInterleaveDepthMs,
+        sourceSymbols: this.#fecK,
+        symbolSize: this.#fecSymbolSize,
+        mediaUnitsPerSecond: fps,
+      })
+    }
+    for (const [packetId, config] of this.#trackConfigs) {
+      if (config.fps !== undefined || config.interleaveDepthMs < MIN_INTERLEAVE_DEPTH_MS) continue
+      this.#trackConfigs.set(packetId, {
+        ...config,
+        fps,
+        timeoutMs: Math.max(
+          this.#fecTimeoutMs,
+          computeFecDeliveryWindowMs({
+            interleaveDepthMs: config.interleaveDepthMs,
+            sourceSymbols: config.k,
+            symbolSize: config.symbolSize,
+            mediaUnitsPerSecond: fps,
+          }),
+        ),
+      })
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // Symbol feeding (codec-agnostic)
+  // -----------------------------------------------------------------------
+
+  /**
+   * Feed a source symbol to the WASM FEC decoder.
+   *
+   * Does NOT track block source counts or fire lifecycle events — call
+   * `trackBlock()` separately BEFORE this method (MmtpRouter does this).
+   *
+   * @returns Recovered block data if WASM completed the block, else null.
+   *          Caller is responsible for routing recovered data and updating
+   *          block completion state via `markBlockCompleted()`.
+   */
+  feedSourceSymbol(
+    packetId: number,
+    ssId: number,
+    symbolData: Uint8Array,
+    alta?: { auth: Uint8Array; payloadEnd: number },
+    catalogTrackName?: string,
+  ): Uint8Array | null {
+    this.#fecStats.sourcePackets++
+    this.#statsForPacket(packetId).sourcePackets++
+    const fecData = this.#normalizeSymbolData(packetId, symbolData)
+    const sbn = Math.floor(ssId / this.kForPacket(packetId))
+    const blockKey = this.#blockKey(sbn, packetId, catalogTrackName)
+    const syncBlockOwner = this.#syncDecoderBlockOwners.get(blockKey)
+
+    // Worker-backed track: dispatch async, return null (recovery via onFrame callback)
+    const workerClient = this.#workerForPacket(packetId, catalogTrackName)
+    if (workerClient && !syncBlockOwner) {
+      if (!this.#claimDecoderBlock(workerClient, sbn, catalogTrackName)) return null
+      // Create clean ArrayBuffer copy — prevents transferring a shared underlying buffer
+      // when symbolData is a view into a larger packet (T-03-06)
+      const buf = fecData.buffer.slice(
+        fecData.byteOffset,
+        fecData.byteOffset + fecData.byteLength,
+      ) as ArrayBuffer
+      // Pass the flat SS_ID through to the worker. The WASM decoder derives
+      // SBN/ESI internally per ISO 23008-1 §C.5.2; the WASM add_source
+      // signature is (ss_id, data, timestamp) — pre-computing sbn/esi on this
+      // side produces wrong WASM argument alignment and silently breaks
+      // block assembly.
+      if (alta) {
+        // Copy auth into a fresh ArrayBuffer to transfer zero-copy. The
+        // underlying buffer of the parsed trailer view belongs to the wire
+        // packet, which may be transferred separately or reused.
+        const authBuf = alta.auth.buffer.slice(
+          alta.auth.byteOffset,
+          alta.auth.byteOffset + alta.auth.byteLength,
+        ) as ArrayBuffer
+        workerClient.feedSource(ssId, buf, performance.now(), {
+          auth: authBuf,
+          payloadEnd: alta.payloadEnd,
+        })
+      } else {
+        workerClient.feedSource(ssId, buf, performance.now())
+      }
+      return null
+    }
+
+    // Synchronous WASM path.
+    const entry = this.#decoderForPacket(packetId, catalogTrackName)
+    const client = syncBlockOwner ?? entry?.client
+    if (!client) return null
+    if (!this.#claimDecoderBlock(client, sbn, catalogTrackName)) return null
+    this.#syncDecoderBlockOwners.set(blockKey, client)
+
+    let recovered: Uint8Array | null = null
+    try {
+      recovered = client.add_source(ssId, fecData, performance.now())
+    } catch {
+      // WASM RefCell panic — decoder instance shared with multicast repair path
+    }
+    if (recovered || this.#completedBlocks.has(blockKey)) {
+      this.#syncDecoderBlockOwners.delete(blockKey)
+    }
+
+    return recovered
+  }
+
+  /**
+   * Feed a repair symbol to the WASM FEC decoder.
+   *
+   * @returns Recovered block data if repair completed the block, else null.
+   *          Caller is responsible for routing recovered data and updating
+   *          block completion state via `markBlockCompleted()`.
+   */
+  feedRepairSymbol(
+    packetId: number,
+    ssStart: number,
+    ssbLength: number,
+    rsId: number,
+    repairData: Uint8Array,
+    catalogTrackName?: string,
+  ): Uint8Array | null {
+    this.#fecStats.repairPackets++
+    this.#statsForPacket(packetId).repairPackets++
+    const symbolSize = this.symbolSizeForPacket(packetId)
+    if (symbolSize > 0 && repairData.byteLength !== symbolSize) {
+      this.#repairSymbolSizeMismatchCount++
+      if (this.#repairSymbolSizeMismatchCount <= 5 || this.#repairSymbolSizeMismatchCount % 100 === 0) {
+        console.warn(
+          `[FECManager] Dropping repair symbol with invalid size: got ${repairData.byteLength}B, expected ${symbolSize}B (packetId=${packetId}, ssStart=${ssStart}, ssbLength=${ssbLength}, rsId=${rsId})`,
+        )
+      }
+      return null
+    }
+    const fecData = repairData
+
+    // Repair symbols are block activity: refresh the inactivity fail bound so
+    // a block being actively repaired over MoQ is not failed mid-recovery.
+    // The multicast in-band path already does this at the router; this covers
+    // the MoQ backfill path, which bypasses the router's packet accounting.
+    // ssbLength is SSB_length = K (ISO 23008-1 §C.5.3), so ssStart/ssbLength
+    // is the block number. The legacy feedSymbol shape passes ssbLength=1
+    // with flat symbol ids — its ratio is not a block number, so skip it.
+    if (ssbLength > 1) {
+      this.noteBlockActivity(
+        Math.floor(ssStart / ssbLength),
+        packetId,
+        catalogTrackName,
+      )
+    }
+
+    const sbn = ssbLength > 0 ? Math.floor(ssStart / ssbLength) : 0
+    const blockKey = this.#blockKey(sbn, packetId, catalogTrackName)
+    if (this.#completedBlocks.has(blockKey)) return null
+    const syncBlockOwner = this.#syncDecoderBlockOwners.get(blockKey)
+    let repairIds = this.#blockRepairRsIds.get(blockKey)
+    if (!repairIds) {
+      repairIds = new Set()
+      this.#blockRepairRsIds.set(blockKey, repairIds)
+    }
+    repairIds.add(rsId)
+    if (this.#repairRequestedBlocks.has(blockKey)) {
+      this.#traceLifecycle('repair-arrived', sbn, packetId, catalogTrackName, rsId)
+    }
+
+    // Worker-backed track: dispatch async, return null (recovery via onFrame callback)
+    const workerClient = this.#workerForPacket(packetId, catalogTrackName)
+    if (workerClient && !syncBlockOwner) {
+      if (!this.#claimDecoderBlock(workerClient, sbn, catalogTrackName)) return null
+      // Create clean ArrayBuffer copy (T-03-06)
+      const buf = fecData.buffer.slice(
+        fecData.byteOffset,
+        fecData.byteOffset + fecData.byteLength,
+      ) as ArrayBuffer
+      // Forward the wire-level Repair FEC Payload ID (ISO 23008-1 §C.5.3)
+      // directly. WASM add_repair signature is
+      // (ss_start, ssb_length, rs_id, data, timestamp) — pre-computing
+      // (sbn, esi) on this side misaligns WASM args and produces 0% recovery.
+      workerClient.feedRepair(ssStart, ssbLength, rsId, buf, performance.now())
+      return null
+    }
+
+    // Synchronous WASM path.
+    const entry = this.#decoderForPacket(packetId, catalogTrackName)
+    const client = syncBlockOwner ?? entry?.client
+    if (!client) return null
+    if (!this.#claimDecoderBlock(client, sbn, catalogTrackName)) return null
+    this.#syncDecoderBlockOwners.set(blockKey, client)
+
+    let recovered: Uint8Array | null = null
+    try {
+      recovered = client.add_repair(ssStart, ssbLength, rsId, fecData, performance.now())
+    } catch {
+      // WASM add_repair failure — block will timeout and be marked failed
+    }
+    if (recovered) this.#syncDecoderBlockOwners.delete(blockKey)
+
+    return recovered
+  }
+
+  #routeSyncCleanup(
+    decoder: WasmFecDecoder,
+    sbn: number,
+    packetId: number,
+  ): void {
+    let framed: Uint8Array
+    try {
+      framed = decoder.cleanup_blocks_detailed(Uint32Array.of(sbn))
+    } catch (error) {
+      console.warn(`[FECManager] Scoped cleanup failed for SBN ${sbn}:`, error)
+      return
+    }
+
+    const view = new DataView(framed.buffer, framed.byteOffset, framed.byteLength)
+    let offset = 0
+    while (offset < framed.byteLength) {
+      if (framed.byteLength - offset < 8) {
+        console.warn(`[FECManager] Scoped cleanup returned a truncated record for SBN ${sbn}`)
+        return
+      }
+      const fillSbn = view.getUint32(offset, false)
+      const length = view.getUint32(offset + 4, false)
+      offset += 8
+      if (length > framed.byteLength - offset) {
+        console.warn(`[FECManager] Scoped cleanup returned a truncated payload for SBN ${sbn}`)
+        return
+      }
+      const data = framed.slice(offset, offset + length).buffer as ArrayBuffer
+      offset += length
+      this.#fecStats.greenFillFrames++
+      this.#statsForPacket(packetId).greenFillFrames++
+      this.onGreenFill?.(fillSbn, packetId, data)
+    }
+  }
+
+  /**
+   * Unified symbol feeder. Dispatches to feedSourceSymbol or feedRepairSymbol.
+   */
+  feedSymbol(packetId: number, symbolId: number, data: Uint8Array, isRepair: boolean): Uint8Array | null {
+    if (isRepair) {
+      return this.feedRepairSymbol(packetId, symbolId, 1, symbolId, data)
+    }
+    return this.feedSourceSymbol(packetId, symbolId, data)
+  }
+
+  // -----------------------------------------------------------------------
+  // Block lifecycle
+  // -----------------------------------------------------------------------
+
+  /**
+   * Track a source symbol for an FEC block. Refreshes the inactivity deadline
+   * on each symbol and marks the block clean when K source symbols arrive.
+   */
+  trackBlock(
+    sbn: number,
+    packetId: number,
+    catalogTrackName?: string,
+    esi?: number,
+  ): void {
+    const key = this.#blockKey(sbn, packetId, catalogTrackName)
+    const trackConfig = this.#resolveTrackConfig(packetId)
+    const k = trackConfig.k
+
+    // Skip blocks already recovered — late source symbols must not restart timeouts
+    if (this.#completedBlocks.has(key)) return
+
+    // Count source symbols per block
+    const count = (this.#blockSourceCounts.get(key) ?? 0) + 1
+    this.#blockSourceCounts.set(key, count)
+    if (Number.isInteger(esi) && esi! >= 0 && esi! < k) {
+      let sourceEsis = this.#blockSourceEsis.get(key)
+      if (!sourceEsis) {
+        sourceEsis = new Set()
+        this.#blockSourceEsis.set(key, sourceEsis)
+      }
+      sourceEsis.add(esi!)
+    }
+    if (count === 1) {
+      if (catalogTrackName === undefined) {
+        this.onBlockStarted?.(sbn, packetId)
+      } else {
+        this.onBlockStarted?.(sbn, packetId, catalogTrackName)
+      }
+    }
+
+    // When K source symbols received, block is clean (no loss, no FEC needed).
+    if (k > 0 && count >= k) {
+      this.#fecStats.blocksClean++
+      this.#statsForPacket(packetId).blocksClean++
+      this.cancelBlockTimeout(sbn, packetId, catalogTrackName)
+      this.#blockSourceCounts.delete(key)
+      this.#blockSourceEsis.delete(key)
+      this.#blockRepairRsIds.delete(key)
+      this.#completedBlocks.add(key)
+      // BLO-3323 L15: track which SBNs reached K source-symbol arrivals so the
+      // worker recovery suppression can distinguish "block completed by source"
+      // (legitimately suppress duplicate recovery) from "block touched by any
+      // prior emit / timeout / external mark" (do NOT suppress recovery).
+      this.#cleanlyCompletedBlocks.add(key)
+      this.#markPathBlockComplete(sbn, packetId, catalogTrackName)
+      if (catalogTrackName === undefined) {
+        this.onBlockComplete?.(sbn, packetId)
+      } else {
+        this.onBlockComplete?.(sbn, packetId, catalogTrackName)
+      }
+      // MmtpRouter feeds the K-th source immediately after this callback.
+      // Defer cleanup so that synchronous feed selects the same decoder; this
+      // also clears blocks whose K-th packet was too large for decoder input.
+      queueMicrotask(() => this.#syncDecoderBlockOwners.delete(key))
+      return
+    }
+
+    this.noteBlockActivity(sbn, packetId, catalogTrackName, true)
+
+    // Source ESI is intentionally not a repair trigger. Multicast delivery is
+    // unordered, so K-1 may precede an interior symbol in a clean block. The
+    // progress-refreshed source horizon above is the earliest loss signal.
+  }
+
+  /** Refresh deadlines after accepted block activity. */
+  noteBlockActivity(
+    sbn: number,
+    packetId: number,
+    catalogTrackName?: string,
+    sourceProgress = false,
+  ): void {
+    const key = this.#blockKey(sbn, packetId, catalogTrackName)
+
+    // Late symbols must not resurrect a block that already completed or failed.
+    if (this.#completedBlocks.has(key)) return
+    // The worker cleanup command is already queued after all symbols that made
+    // the inactivity deadline. Symbols arriving after that boundary are late
+    // and must not arm a second timer before the acknowledgement resolves it.
+    if (this.#pendingWorkerCleanups.has(key)) return
+
+    // #requestRepair appends one bounded grace to the active deadline. Source
+    // or repair symbols may still complete the block, but cannot extend it.
+    if (this.#repairRequestedBlocks.has(key)) return
+
+    const trackConfig = this.#resolveTrackConfig(packetId)
+    const timeoutMs = trackConfig.timeoutMs
+    if (timeoutMs <= 0) return
+
+    // D-28: accepted source progress refreshes the pre-request horizon. There
+    // are at most K such arrivals; repair traffic never refreshes this timer.
+    const repairDeadline = this.#repairDeadlines.get(key)
+    if (
+      this.onRepairNeeded &&
+      (repairDeadline === undefined || sourceProgress)
+    ) {
+      if (repairDeadline != null) clearTimeout(repairDeadline)
+      this.#repairDeadlines.set(
+        key,
+        setTimeout(() => {
+          this.#requestRepair(sbn, packetId, catalogTrackName)
+        }, this.#repairDeadlineMs(trackConfig)),
+      )
+    }
+
+    this.#armBlockTimeout(sbn, packetId, catalogTrackName, timeoutMs)
+  }
+
+  #failBlock(
+    sbn: number,
+    packetId: number,
+    countGreenFill: boolean,
+    catalogTrackName?: string,
+  ): void {
+    const key = this.#blockKey(sbn, packetId, catalogTrackName)
+    this.#traceLifecycle('failed', sbn, packetId, catalogTrackName)
+    this.#clearRepairDeadline(key)
+    const activeTimer = this.#activeBlocks.get(key)
+    if (activeTimer) {
+      clearTimeout(activeTimer)
+      this.#activeBlocks.delete(key)
+    }
+    this.#activeBlockDeadlinesMs.delete(key)
+    if (this.#repairRequestedBlocks.delete(key)) {
+      if (catalogTrackName === undefined) {
+        this.onRepairResolved?.(sbn, packetId, 'failed')
+      } else {
+        this.onRepairResolved?.(sbn, packetId, 'failed', catalogTrackName)
+      }
+    }
+    this.#blockSourceCounts.delete(key)
+    this.#blockSourceEsis.delete(key)
+    this.#blockRepairRsIds.delete(key)
+    this.#activeBlockTimeoutOwners.delete(key)
+    this.#syncDecoderBlockOwners.delete(key)
+    this.#completedBlocks.add(key)
+    this.#markPathBlockComplete(sbn, packetId, catalogTrackName)
+    this.#fecStats.blocksFailed++
+    this.#statsForPacket(packetId).blocksFailed++
+    if (countGreenFill) {
+      this.#fecStats.greenFillFrames++
+      this.#statsForPacket(packetId).greenFillFrames++
+    }
+    if (catalogTrackName === undefined) {
+      this.onBlockFailed?.(sbn, packetId)
+    } else {
+      this.onBlockFailed?.(sbn, packetId, catalogTrackName)
+    }
+  }
+
+  /** Check whether a block has already been completed (clean or recovered). */
+  isBlockCompleted(sbn: number, packetId?: number, catalogTrackName?: string): boolean {
+    return this.#blockKeysFor(sbn, packetId, catalogTrackName).some((key) => this.#completedBlocks.has(key))
+  }
+
+  /** Mark a block as completed externally (e.g., after routing recovered data). */
+  markBlockCompleted(sbn: number, packetId?: number, catalogTrackName?: string): void {
+    for (const key of this.#blockKeysFor(sbn, packetId, catalogTrackName)) {
+      this.#completedBlocks.add(key)
+      this.#pendingWorkerCleanups.delete(key)
+      this.#pendingWorkerCleanupClients.delete(key)
+      const block = this.#parseBlockKey(key)
+      this.#markPathBlockComplete(block.sbn, block.packetId, block.catalogTrackName)
+      this.#clearRepairDeadline(key)
+      if (this.#repairRequestedBlocks.delete(key)) {
+        if (block.catalogTrackName === undefined) {
+          this.onRepairResolved?.(block.sbn, block.packetId, 'completed')
+        } else {
+          this.onRepairResolved?.(
+            block.sbn,
+            block.packetId,
+            'completed',
+            block.catalogTrackName,
+          )
+        }
+      }
+      this.#blockSourceCounts.delete(key)
+      this.#blockSourceEsis.delete(key)
+      this.#blockRepairRsIds.delete(key)
+      const timer = this.#activeBlocks.get(key)
+      if (timer) {
+        clearTimeout(timer)
+        this.#activeBlocks.delete(key)
+      }
+      this.#activeBlockDeadlinesMs.delete(key)
+      this.#activeBlockTimeoutOwners.delete(key)
+    }
+  }
+
+  /** Increment blocksRecovered stat (called by MmtpRouter after routing recovery). */
+  countRecovery(packetId?: number): void {
+    this.#fecStats.blocksRecovered++
+    if (packetId != null) this.#statsForPacket(packetId).blocksRecovered++
+  }
+
+  /**
+   * Strict delivery provenance for one FEC block.
+   *
+   * A recovered symbol is a function of every symbol that entered its block,
+   * so it can only be attributed to multicast when NO symbol in that block
+   * arrived over MoQ. Repair symbols routinely arrive over reliable QUIC
+   * (`MmtpRouter.feedRepairPacket`), so a block that recovered with MoQ help
+   * produced bytes that never crossed a multicast socket.
+   *
+   * An untracked block returns 'unknown' rather than a guess: absence of
+   * evidence is not evidence of multicast.
+   */
+  blockDeliveryProvenance(
+    sbn: number,
+    packetId: number,
+    catalogTrackName?: string,
+  ): MmtpDeliveryProvenance {
+    const counts = this.blockPathCount(sbn, packetId, catalogTrackName)
+    if (!counts) return 'unknown'
+    if (counts.moqSymbols > 0) return 'mixed'
+    if (counts.multicastSymbols > 0) return 'multicast'
+    return 'unknown'
+  }
+
+  /** Per-path symbol counts for one block (D-28 gate logging), if tracked. */
+  blockPathCount(
+    sbn: number,
+    packetId: number,
+    catalogTrackName?: string,
+  ): FecBlockPathCount | null {
+    return this.#blockPathCounts.get(
+      this.#blockKey(sbn, packetId, catalogTrackName),
+    ) ?? null
+  }
+
+  /** Cancel block timeout (block completed via clean reception or FEC recovery). */
+  cancelBlockTimeout(sbn: number, packetId?: number, catalogTrackName?: string): void {
+    for (const key of this.#blockKeysFor(sbn, packetId, catalogTrackName)) {
+      this.#completedBlocks.add(key)
+      this.#pendingWorkerCleanups.delete(key)
+      this.#pendingWorkerCleanupClients.delete(key)
+      const block = this.#parseBlockKey(key)
+      this.#markPathBlockComplete(block.sbn, block.packetId, block.catalogTrackName)
+      this.#clearRepairDeadline(key)
+      if (this.#repairRequestedBlocks.delete(key)) {
+        if (block.catalogTrackName === undefined) {
+          this.onRepairResolved?.(block.sbn, block.packetId, 'completed')
+        } else {
+          this.onRepairResolved?.(
+            block.sbn,
+            block.packetId,
+            'completed',
+            block.catalogTrackName,
+          )
+        }
+      }
+      this.#blockSourceCounts.delete(key)
+      this.#blockSourceEsis.delete(key)
+      this.#blockRepairRsIds.delete(key)
+      const timer = this.#activeBlocks.get(key)
+      if (timer) {
+        clearTimeout(timer)
+        this.#activeBlocks.delete(key)
+      }
+      this.#activeBlockDeadlinesMs.delete(key)
+      this.#activeBlockTimeoutOwners.delete(key)
+    }
+    // Trim old entries to prevent unbounded growth (keep last ~500 blocks)
+    if (this.#completedBlocks.size > 1000) {
+      const iter = this.#completedBlocks.values()
+      for (let i = 0; i < 500; i++) iter.next()
+      // Sets iterate in insertion order — first 500 are oldest
+      const keep = new Set<string>()
+      for (const v of iter) keep.add(v)
+      this.#completedBlocks = keep
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // Cleanup
+  // -----------------------------------------------------------------------
+
+  dispose(): void {
+    for (const timer of this.#activeBlocks.values()) clearTimeout(timer)
+    this.#activeBlocks.clear()
+    this.#activeBlockDeadlinesMs.clear()
+    this.#activeBlockTimeoutOwners.clear()
+    this.#pendingWorkerCleanups.clear()
+    this.#pendingWorkerCleanupClients.clear()
+    for (const timer of this.#repairDeadlines.values()) {
+      if (timer != null) clearTimeout(timer)
+    }
+    this.#repairDeadlines.clear()
+    this.#blockSourceCounts.clear()
+    this.#blockSourceEsis.clear()
+    this.#blockRepairRsIds.clear()
+    this.#completedBlocks.clear()
+    this.#cleanlyCompletedBlocks.clear()
+    this.#repairRequestedBlocks.clear()
+    this.#workerRecoveredBlocks.clear()
+    this.#syncDecoderBlockOwners.clear()
+    this.#startupAlignedPackets.clear()
+    this.#startupPartialBlocks.clear()
+    this.#startupRequireRepairReady = false
+    this.#startupRepairReadyPackets.clear()
+    this.#startupRepairBoundaryCounts.clear()
+    this.#startupRepairFailOpenPackets.clear()
+    this.#seenSymbols.clear()
+    this.#blockPathCounts.clear()
+    this.#blockCatalogTrackNames.clear()
+    this.#trackConfigs.clear()
+    this.#fecDecoders.clear()
+    // Dispose Worker clients (T-03-07: prevent Worker leak)
+    for (const client of new Set(this.#workerClients.values())) client.dispose()
+    this.#workerClients.clear()
+  }
+}