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

package/src/multicast-manager.ts

@@ -0,0 +1,2783 @@
+/**
+ * Facade composing FECManager + MmtpRouter + MulticastTransport.
+ *
+ * Public methods delegate to the decomposed components. Applications that
+ * need individual layers can use them directly:
+ * - FECManager  — codec-agnostic FEC decode
+ * - MmtpRouter  — MMTP packet parsing + frame routing
+ * - MulticastTransport — SSM join/socket/watchdog
+ */
+
+import { parseFecBlockProfile, type FecBlockProfile } from "@blockcast/mmt-base";
+import {
+  FECManager,
+  MIN_INTERLEAVE_DEPTH_MS,
+  type FECManagerConfig,
+  type WasmFecDecoder,
+  type FecDecoderUnavailableReason,
+  type FecFallbackDecoder,
+  type MulticastSymbolDelivery,
+  type RepairVia,
+} from "./fec-manager.js";
+import {
+  deriveBlockClassifierGeometry,
+  repairPriorityForClass,
+  type BlockClass,
+  type ClassifierMode,
+  type ClassifierReason,
+  type FrameGapDecision,
+  type ReclassificationEvidence,
+  type RepairPriority,
+  type TrackKind,
+} from "./block-policy.js";
+import type {
+  RepairFetchHost,
+  RepairPriorityReason,
+  RepairSkipReason,
+  RepairSubscribeCallback,
+} from "./repair-fetch.js";
+import {
+  MmtpRouter,
+  type FrameCallback,
+  type ManifestIdentityResolver,
+  type MmtpIngressContext,
+  type MmtpStreamIdentity,
+  type StagedStreamSwitch,
+  type StreamSwitchCommit,
+  type TrackPacketCallback,
+} from "./mmtp-router.js";
+import { isMulticastTrackPacketId } from "@blockcast/mmt-transport";
+import {
+  MulticastTransport,
+  type MulticastFailbackReason,
+  type MulticastJoinOutcome,
+  type MulticastJoinStats,
+} from "./multicast-transport.js";
+import { computeFecDeliveryWindowMs } from "./track-session.js";
+import { DEFAULT_AMT_RELAY_PORT } from "./catalog-network-source.js";
+import { deriveFecInterleaveDepth, FecBlockMapper } from "@blockcast/mmt-fec";
+import type {
+  FecBlockSnapshot,
+  FecTrackConfig,
+  FecTrackStats,
+  FecWorkerClient,
+} from "@blockcast/fec-worker";
+import type { MfuReassemblerBackend } from "./mfu-reassembler.js";
+import type { MfuReassemblyPolicy } from "./mfu-reassembly-policy.js";
+import type {
+  ManifestObjectIdentity,
+  ManifestVerifier,
+} from "@blockcast/mmt-manifest-verify";
+import type {
+  BlockAssemblerConfig,
+  CmafBlockSample,
+} from "./cmaf-block-assembler.js";
+import {
+  hasSwitchingSetRole,
+  parseTrackRole,
+  validateSwitchingSet,
+  isFecCatalogConfig,
+  type FecCatalogConfig,
+  type TrackRole,
+} from "./carp-catalog.js";
+
+export interface MulticastEndpointConfig {
+  sourceAddress: string;
+  groupAddress: string;
+  port: number;
+  /** Explicit gateway transport policy. Omitted means gateway-selected auto mode. */
+  mode?: 'auto' | 'native' | 'tunnel';
+  /** AMT relay hostname/IP from catalog endpoint. */
+  relayAddress?: string;
+  /** AMT relay port from catalog endpoint. */
+  relayPort?: number;
+  /** AMT relay hostname/IP from player/UI overrides. Wins over `relayAddress`. */
+  amtRelay?: string;
+  /** AMT relay port from player/UI overrides. Wins over `relayPort`. */
+  amtRelayPort?: number;
+  /** MMTP packet IDs to forward before data enters the page transport queue. */
+  packetIds?: number[];
+  /** Exact catalog tracks carried by this physical multicast endpoint. */
+  tracks?: MmtpIngressContext["tracks"];
+  /**
+   * The catalog `fec.blockProfile` (BLO-35597): `k-padded-v1` or
+   * `iso-ssbg1-v1`. Required for per-track FEC configuration; never defaulted.
+   */
+  fecBlockProfile?: FecBlockProfile;
+  fecK?: number;
+  /** Number of repair symbols per FEC block (P). Used to size recovery reorder latency. */
+  fecRepairSymbols?: number;
+  /** Symbol size in bytes (T). NOT repair count. */
+  fecSymbolSize?: number;
+  /** Catalog fec.reorderToleranceMs — signaled jitter/reorder allowance, ADDED
+   *  to the derived delivery window. Never a multiplier on the span, so one
+   *  network yields the same slack on a wide video span and a narrow audio one.
+   *
+   *  Absence widens the window by zero rather than throwing, unlike the datagram
+   *  MFU deadline in hang-mmt-fec. The distinction is which way absence fails:
+   *  there the tolerance IS the deadline's slack term and guessing one invents
+   *  a reorder budget, so it must fail loud; here the window is already fully
+   *  derived from other catalog values and the tolerance only widens it, so
+   *  adding nothing is the identity and errs toward earlier failback. Do not
+   *  "harmonize" this into a throw, and do not turn the zero into a default. */
+  fecReorderToleranceMs?: number;
+  fecInterleaveDepthMs?: number;
+  /** Aggregate endpoint bandwidth in bits per second from the multicast catalog. */
+  bandwidth?: number;
+  fps?: number;
+  /** Track media kind (repair class `audio` vs video block classification). */
+  trackKind?: TrackKind;
+  /** Catalog codec string (video conceal mode, codec-aware RAP checks). */
+  codec?: string;
+  /** Catalog track timescale for `keyframeIntervalTicks`. */
+  timescale?: number;
+  /** Raw catalog `keyframeIntervalTicks` (never a resolved cadence). */
+  keyframeIntervalTicks?: number;
+  /** Raw catalog `keyframeIntervalMs` (never a resolved cadence). */
+  keyframeIntervalMs?: number;
+  /** Catalog-derived lower bound for packet-silence failback (for example, keyframe repair cadence). */
+  minimumFailbackWindowMs?: number;
+}
+export interface MulticastManagerOptions {
+  /**
+   * MFU reassembly timeout (ms). Threaded to the inner MmtpRouter (and its
+   * MmtpContainerParser). Caller derives from catalog `fec.interleaveDepthMs`,
+   * which is already in milliseconds — `moqenc_mmt.c` converts
+   * `depth_ms = fec_depth * (1000/fps)` before populating the catalog.
+   * Defaults to 1000ms (with parser warning) when omitted.
+   */
+  mfuTimeoutMs?: number;
+  reassemblyPolicy?: MfuReassemblyPolicy;
+  reassembler?: MfuReassemblerBackend;
+  maxBufferedMfus?: number;
+  manifestVerifier?: ManifestVerifier;
+  manifestVerifierOwnership?: "caller" | "router";
+  resolveManifestIdentity?: (
+    packetId: number,
+    sbn: number,
+    esi: number,
+    catalogTrackName?: string,
+  ) => ManifestObjectIdentity | null;
+  resolveManifestIdentityForRoute?: ManifestIdentityResolver;
+  /**
+   * Also write every repair lifecycle event to the console as one
+   * `REPAIR_LIFECYCLE_LOG_PREFIX` JSON line. Off unless asked for: the lines
+   * are serialized on the page thread for every failed block and repair step
+   * (and again for an attached inspector), and addRepairLifecycleObserver is
+   * the lifecycle API. Enable only for interactive debugging (BLO-36599).
+   */
+  logRepairLifecycle?: boolean;
+}
+
+/**
+ * An in-place video rendition switch on the live join: MulticastManager
+ * .switchRendition. Every rendition of a ladder can share one SSM group and
+ * differ only by MMTP packet ID, so the switch remaps packet IDs at a RAP
+ * instead of leaving and re-joining the group.
+ */
+export interface RenditionSwitchRequest {
+  /** The rendition playing now: an ingress track of the live join. */
+  readonly from: MmtpStreamIdentity;
+  /**
+   * The rendition replacing it, already registered as video with everything
+   * it plays through (setPacketIdType, setTrackCodec, configureTrackFec, its
+   * FEC decoder, frame and init callbacks, MSE assembler, repair owner).
+   */
+  readonly to: MmtpStreamIdentity;
+  /**
+   * The live join's complete ingress once the switch commits: every track
+   * that stays admitted (audio, repair legs) plus `to` and its repair legs.
+   * It must carry `to`, nothing on `from`'s packet ID (the commit retires
+   * it), and no live packet ID under another name.
+   */
+  readonly tracks: MmtpIngressContext["tracks"];
+  /**
+   * The allow-list once the switch commits, when it changes: an allow-list
+   * scoped to the active rendition. Omit it for a rendition-stable allow-list
+   * that already admits `to`; the live allow-list is then kept unchanged.
+   */
+  readonly packetIds?: readonly number[];
+  /**
+   * Called synchronously at the commit, inside the frame path, after `from`
+   * is retired and the admission narrowed, and before `to`'s newest init and
+   * its RAP are delivered: reconfigure the decoder here. Throwing fails the
+   * switch (`commit-failed`): `from` cannot be restored, so `to` is retired
+   * as well and none of it is delivered.
+   */
+  readonly onCommit: (commit: StreamSwitchCommit) => void;
+  /** Called once when the switch ends without a completed commit. */
+  readonly onCancel: (cancel: RenditionSwitchCancel) => void;
+}
+
+/**
+ * Why a staged rendition switch ended without a completed commit.
+ *
+ * - `cancelled`: RenditionSwitch.cancel().
+ * - `superseded`: join() or dispose() replaced the admission it was staged on.
+ * - `provider-refused`: the subscription refused to widen its packet filter to
+ *   `to`, so `to` can never arrive.
+ * - `commit-failed`: `onCommit` threw. `from` was already retired, so `to` is
+ *   retired as well and the subscription now delivers neither rendition;
+ *   recover with join().
+ */
+export type RenditionSwitchCancel =
+  | { readonly reason: "cancelled" }
+  | { readonly reason: "superseded" }
+  | { readonly reason: "provider-refused"; readonly error: unknown }
+  | { readonly reason: "commit-failed"; readonly error: unknown };
+
+export type RenditionSwitchState = "staged" | "committed" | "cancelled" | "failed";
+
+/** A rendition switch MulticastManager.switchRendition staged. */
+export interface RenditionSwitch {
+  readonly state: RenditionSwitchState;
+  /**
+   * Abandon the switch before it commits: the pre-switch admission is
+   * restored and `to` is retired (its router registrations and FEC state
+   * released). Returns false once the switch committed or ended.
+   */
+  cancel(): boolean;
+}
+
+interface ActiveRenditionSwitch {
+  readonly from: MmtpStreamIdentity;
+  readonly to: MmtpStreamIdentity;
+  readonly onCommit: (commit: StreamSwitchCommit) => void;
+  readonly onCancel: (cancel: RenditionSwitchCancel) => void;
+  /** The admission the switch was staged on, restored by cancel(). */
+  readonly liveIngress: MmtpIngressContext;
+  readonly livePacketIds: ReadonlySet<number> | null;
+  /** True when staging widened the allow-list (so cancel narrows it back). */
+  readonly widened: boolean;
+  /** The admission once committed. */
+  readonly committedIngress: MmtpIngressContext;
+  readonly committedPacketIds: readonly number[] | undefined;
+  router: StagedStreamSwitch | null;
+  state: RenditionSwitchState;
+}
+
+function freezeIngress(tracks: Iterable<Readonly<{ name: string; packetId: number }>>): MmtpIngressContext {
+  return Object.freeze({
+    tracks: Object.freeze(
+      [...tracks].map(({ name, packetId }) => Object.freeze({ name, packetId })),
+    ),
+  });
+}
+
+function sameIdSet(a: ReadonlySet<number>, b: ReadonlySet<number>): boolean {
+  if (a.size !== b.size) return false;
+  for (const id of a) if (!b.has(id)) return false;
+  return true;
+}
+
+export interface RepairStreamIdentity {
+  readonly packetId: number;
+  /** Non-empty catalog identity, or null when the producer has no track name. */
+  readonly catalogTrackName: string | null;
+}
+
+export interface RepairBlockIdentity extends RepairStreamIdentity {
+  readonly sbn: number;
+}
+
+interface RepairSymbolCounts {
+  readonly multicast: number;
+  readonly moq: number;
+}
+
+/**
+ * Typed repair lifecycle, version 2 (keyframe-protected FEC policy). One
+ * clean cut from version 1: there is no v1 emit and no alias.
+ *
+ * - `requested`: a block short of its source at the repair deadline; its
+ *   class sets the QUIC repair priority (P0 keyframe/unknown, P1 audio,
+ *   P2 delta).
+ * - `reclassified`: new evidence (or a disabled classifier) changed a block's
+ *   class.
+ * - `recovered` / `failed`: every block that could not complete from its
+ *   first-arrival source symbols resolves with exactly one of these.
+ * - `repair-preempted` / `repair-deferred`: the scheduler aborted a delta
+ *   repair for keyframe work, or never ran it before its block resolved.
+ * - `repair-priority`: the catalog could not supply the SUBSCRIBER_PRIORITY a
+ *   repair FETCH must carry (draft-ramadan-moq-fec §11.4.5), so the FETCH was
+ *   sent without the parameter (`omitted`, keyframe/unknown blocks) or not
+ *   sent at all (`declined`, delta/audio blocks).
+ * - `classifier`: a video stream's classifier mode and why.
+ * - `gap`: the stall/conceal decision attached to the first frame released
+ *   after a lossy gap — the very object carried as `gapBefore`.
+ * - `decoder-unavailable`: a stream's Worker decoder left routing.
+ */
+export type RepairLifecycleEvent =
+  | {
+      readonly version: 2;
+      readonly type: "requested";
+      readonly block: RepairBlockIdentity;
+      readonly blockClass: BlockClass;
+      readonly priority: RepairPriority;
+    }
+  | {
+      readonly version: 2;
+      readonly type: "reclassified";
+      readonly block: RepairBlockIdentity;
+      readonly from: BlockClass;
+      readonly to: BlockClass;
+      readonly evidence: ReclassificationEvidence;
+    }
+  | {
+      readonly version: 2;
+      readonly type: "recovered";
+      readonly block: RepairBlockIdentity;
+      readonly blockClass: BlockClass;
+      readonly via: RepairVia;
+      readonly symbols: RepairSymbolCounts;
+    }
+  | {
+      readonly version: 2;
+      readonly type: "failed";
+      readonly block: RepairBlockIdentity;
+      readonly blockClass: BlockClass;
+      readonly symbols: RepairSymbolCounts;
+    }
+  | {
+      readonly version: 2;
+      readonly type: "repair-preempted" | "repair-deferred";
+      readonly block: RepairBlockIdentity;
+    }
+  | {
+      readonly version: 2;
+      /**
+       * The scheduler sent no FETCH for a requested block (BLO-35597): the
+       * measured reliable-path RTT could not come back before the block's
+       * presentation deadline, the path offered no RTT, or the player gave
+       * no presentation delay. `rttMs` is null when unmeasured; `budgetMs` is
+       * the time that was left to the deadline.
+       */
+      readonly type: "repair-skipped";
+      readonly block: RepairBlockIdentity;
+      readonly reason: RepairSkipReason;
+      readonly rttMs: number | null;
+      readonly budgetMs: number;
+    }
+  | {
+      readonly version: 2;
+      readonly type: "repair-priority";
+      readonly block: RepairBlockIdentity;
+      readonly blockClass: BlockClass;
+      readonly action: "omitted" | "declined";
+      readonly reason: RepairPriorityReason;
+    }
+  | {
+      readonly version: 2;
+      readonly type: "classifier";
+      readonly stream: RepairStreamIdentity;
+      readonly mode: ClassifierMode;
+      readonly reason: ClassifierReason | null;
+    }
+  | FrameGapDecision
+  | {
+      readonly version: 2;
+      /**
+       * The stream's Worker decoder left routing (FECManager.clearFecWorker,
+       * or a disposed client evicted on its next symbol). `fallbackDecoder`
+       * says what still decodes the stream: 'sync' when a synchronous WASM
+       * decoder registered for the same stream keeps serving it, 'none' when
+       * nothing does. Only 'none' means the stream's symbols reach no decoder
+       * until a host registers one again; consumers fail closed on that
+       * instead of reading the following silence as a clean stream.
+       */
+      readonly type: "decoder-unavailable";
+      readonly stream: RepairStreamIdentity;
+      readonly reason: FecDecoderUnavailableReason;
+      readonly fallbackDecoder: FecFallbackDecoder;
+    };
+
+/**
+ * Keyframe-protected repair policy counters for one catalog track. Reset
+ * whenever the track's epoch changes (catalog geometry change or reset).
+ *
+ * "Protected" means the block was short of its source at the repair deadline
+ * with class `keyframe` or `unknown`. The `keyframe*` recovered/failed
+ * counters cover every P0 block (class `keyframe` or `unknown`).
+ */
+export interface BlockPolicyStats {
+  readonly packetId: number;
+  readonly catalogTrackName: string | null;
+  readonly epoch: number;
+  classifierMode: ClassifierMode | null;
+  classifierReason: ClassifierReason | null;
+  keyframeBlocksProtected: number;
+  unknownBlocksProtected: number;
+  keyframeBlocksRecoveredInband: number;
+  keyframeBlocksRecoveredQuic: number;
+  keyframeBlocksFailed: number;
+  deltaBlocksShort: number;
+  deltaBlocksRecoveredInband: number;
+  deltaBlocksRecoveredQuic: number;
+  deltaRepairsPreempted: number;
+  deltaRepairsDeferred: number;
+  /** Repair requests sent no FETCH (see the `repair-skipped` event). */
+  repairsSkipped: number;
+  deltaBlocksFailed: number;
+  audioBlocksRecoveredInband: number;
+  audioBlocksRecoveredQuic: number;
+  audioBlocksFailed: number;
+  stalls: number;
+  concealedBlocks: number;
+  concealedGaps: number;
+  concealedFrames: number;
+  concealedAudioMs: number;
+  vanishedBlocks: number;
+}
+
+function newBlockPolicyStats(
+  packetId: number,
+  catalogTrackName: string | null,
+  epoch: number,
+): BlockPolicyStats {
+  return {
+    packetId,
+    catalogTrackName,
+    epoch,
+    classifierMode: null,
+    classifierReason: null,
+    keyframeBlocksProtected: 0,
+    unknownBlocksProtected: 0,
+    keyframeBlocksRecoveredInband: 0,
+    keyframeBlocksRecoveredQuic: 0,
+    keyframeBlocksFailed: 0,
+    deltaBlocksShort: 0,
+    deltaBlocksRecoveredInband: 0,
+    deltaBlocksRecoveredQuic: 0,
+    deltaRepairsPreempted: 0,
+    deltaRepairsDeferred: 0,
+    repairsSkipped: 0,
+    deltaBlocksFailed: 0,
+    audioBlocksRecoveredInband: 0,
+    audioBlocksRecoveredQuic: 0,
+    audioBlocksFailed: 0,
+    stalls: 0,
+    concealedBlocks: 0,
+    concealedGaps: 0,
+    concealedFrames: 0,
+    concealedAudioMs: 0,
+    vanishedBlocks: 0,
+  };
+}
+
+export type RepairLifecycleObserver = (event: RepairLifecycleEvent) => void;
+
+export interface RepairLifecycleSource {
+  addRepairLifecycleObserver(observer: RepairLifecycleObserver): () => void;
+}
+
+/** Minimal event shape accepted by application-owned event targets. */
+export interface RepairLifecycleApplicationEvent {
+  readonly type: string;
+  readonly detail: RepairLifecycleEvent;
+}
+
+/** DOM EventTarget event shape, including the Node 18 Event fallback. */
+export interface RepairLifecycleDomEvent extends Event {
+  readonly detail: RepairLifecycleEvent;
+}
+
+/** Structural target contract shared by DOM and Closure-style event targets. */
+export interface RepairLifecycleEventTarget<
+  TEvent extends RepairLifecycleApplicationEvent,
+> {
+  dispatchEvent(event: TEvent): unknown;
+}
+
+export interface RepairLifecycleEventOptions<
+  TEvent extends RepairLifecycleApplicationEvent = RepairLifecycleDomEvent,
+> {
+  bubbles?: boolean;
+  composed?: boolean;
+  createEvent?: RepairLifecycleEventFactory<TEvent>;
+}
+
+export type RepairLifecycleEventFactory<
+  TEvent extends RepairLifecycleApplicationEvent = RepairLifecycleDomEvent,
+> = (
+  type: typeof REPAIR_LIFECYCLE_EVENT_TYPE,
+  detail: RepairLifecycleEvent,
+  options: Readonly<{ bubbles: boolean; composed: boolean }>,
+) => TEvent;
+
+/** Public EventTarget event carrying an immutable RepairLifecycleEvent detail. */
+export const REPAIR_LIFECYCLE_EVENT_TYPE = "repairlifecycle";
+
+/** Diagnostic JSON-lines prefix. Never consume logs as a lifecycle API. */
+export const REPAIR_LIFECYCLE_LOG_PREFIX =
+  "[MulticastManager] repair-lifecycle ";
+
+function createDefaultRepairLifecycleEvent(
+  detail: RepairLifecycleEvent,
+  options: Readonly<{ bubbles: boolean; composed: boolean }>,
+): RepairLifecycleDomEvent {
+  if (typeof globalThis.CustomEvent === "function") {
+    return new CustomEvent<RepairLifecycleEvent>(REPAIR_LIFECYCLE_EVENT_TYPE, {
+      detail,
+      ...options,
+    });
+  }
+
+  const event = new Event(REPAIR_LIFECYCLE_EVENT_TYPE, options);
+  Object.defineProperty(event, "detail", {
+    value: detail,
+    enumerable: true,
+  });
+  return event as RepairLifecycleDomEvent;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isRepairStreamIdentity(value: unknown): value is RepairStreamIdentity {
+  if (!isRecord(value)) return false;
+  const packetId = value["packetId"];
+  const catalogTrackName = value["catalogTrackName"];
+  return (
+    Number.isSafeInteger(packetId) &&
+    (packetId as number) >= 0 &&
+    (catalogTrackName === null ||
+      (typeof catalogTrackName === "string" && catalogTrackName.length > 0))
+  );
+}
+
+function isRepairBlockIdentity(value: unknown): value is RepairBlockIdentity {
+  if (!isRecord(value)) return false;
+  const sbn = value["sbn"];
+  return (
+    isRepairStreamIdentity(value) &&
+    Number.isSafeInteger(sbn) &&
+    (sbn as number) >= 0
+  );
+}
+
+function isDecoderUnavailableReason(
+  value: unknown,
+): value is FecDecoderUnavailableReason {
+  return value === "cleared" || value === "disposed";
+}
+
+function isFecFallbackDecoder(value: unknown): value is FecFallbackDecoder {
+  return value === "sync" || value === "none";
+}
+
+const BLOCK_CLASSES: ReadonlySet<unknown> = new Set(["keyframe", "delta", "unknown", "audio"]);
+const RECLASSIFICATION_EVIDENCE: ReadonlySet<unknown> = new Set([
+  "rap",
+  "mpu-span",
+  "window",
+  "classifier-disabled",
+]);
+const CLASSIFIER_MODES: ReadonlySet<unknown> = new Set(["classifying", "all-protected"]);
+const CLASSIFIER_REASONS: ReadonlySet<unknown> = new Set([
+  "framerate-absent",
+  "keyframe-cadence-absent",
+  "keyframe-interval-not-integral",
+  "block-spans-gop",
+  "keyframe-interval-not-media-integral",
+  "rap-not-mpu-start",
+  "stream-geometry-absent",
+  "mpu-longer-than-gop",
+  "block-not-contiguous",
+  "rap-spacing-mismatch",
+  "mpu-multiple-fragments",
+  "block-wider-than-interleave",
+]);
+const REPAIR_PRIORITY_REASONS: ReadonlySet<unknown> = new Set([
+  "source-priority-absent",
+  "source-priority-invalid",
+  "repair-priority-absent",
+  "repair-priority-invalid",
+]);
+const GAP_REASONS: Readonly<Record<string, "stall" | "conceal">> = {
+  "rap-lost": "stall",
+  "rap-unknown": "stall",
+  discontinuity: "stall",
+  "delta-lost": "conceal",
+  "rap-next": "conceal",
+  "audio-gap": "conceal",
+  "audio-discontinuity": "conceal",
+};
+
+function hasExactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  const present = Object.keys(value);
+  return present.length === keys.length && keys.every((key) => key in value);
+}
+
+function isNonNegativeSafeInteger(value: unknown): boolean {
+  return Number.isSafeInteger(value) && (value as number) >= 0;
+}
+
+function isSymbolCounts(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    hasExactKeys(value, ["multicast", "moq"]) &&
+    isNonNegativeSafeInteger(value["multicast"]) &&
+    isNonNegativeSafeInteger(value["moq"])
+  );
+}
+
+function isNullableNonNegative(value: unknown): boolean {
+  return value === null || (typeof value === "number" && Number.isFinite(value) && value >= 0);
+}
+
+/** Runtime guard for observer, DOM-event, and cross-realm consumers. */
+export function isRepairLifecycleEvent(
+  value: unknown,
+): value is RepairLifecycleEvent {
+  if (!isRecord(value) || value["version"] !== 2) return false;
+  const block = value["block"];
+  switch (value["type"]) {
+    case "requested": {
+      const blockClass = value["blockClass"];
+      return (
+        hasExactKeys(value, ["version", "type", "block", "blockClass", "priority"]) &&
+        isRepairBlockIdentity(block) &&
+        BLOCK_CLASSES.has(blockClass) &&
+        value["priority"] === repairPriorityForClass(blockClass as BlockClass)
+      );
+    }
+    case "reclassified":
+      return (
+        hasExactKeys(value, ["version", "type", "block", "from", "to", "evidence"]) &&
+        isRepairBlockIdentity(block) &&
+        BLOCK_CLASSES.has(value["from"]) &&
+        BLOCK_CLASSES.has(value["to"]) &&
+        RECLASSIFICATION_EVIDENCE.has(value["evidence"])
+      );
+    case "recovered":
+      return (
+        hasExactKeys(value, ["version", "type", "block", "blockClass", "via", "symbols"]) &&
+        isRepairBlockIdentity(block) &&
+        BLOCK_CLASSES.has(value["blockClass"]) &&
+        (value["via"] === "inband" || value["via"] === "quic") &&
+        isSymbolCounts(value["symbols"])
+      );
+    case "failed":
+      return (
+        hasExactKeys(value, ["version", "type", "block", "blockClass", "symbols"]) &&
+        isRepairBlockIdentity(block) &&
+        BLOCK_CLASSES.has(value["blockClass"]) &&
+        isSymbolCounts(value["symbols"])
+      );
+    case "repair-preempted":
+    case "repair-deferred":
+      return hasExactKeys(value, ["version", "type", "block"]) && isRepairBlockIdentity(block);
+    case "repair-priority": {
+      const blockClass = value["blockClass"];
+      const action = value["action"];
+      const reason = value["reason"];
+      // The action follows from the class: a keyframe/unknown request is
+      // sent without the parameter, a delta/audio one is not sent.
+      const expected =
+        BLOCK_CLASSES.has(blockClass) &&
+        repairPriorityForClass(blockClass as BlockClass) === 0
+          ? "omitted"
+          : "declined";
+      return (
+        hasExactKeys(value, ["version", "type", "block", "blockClass", "action", "reason"]) &&
+        isRepairBlockIdentity(block) &&
+        BLOCK_CLASSES.has(blockClass) &&
+        action === expected &&
+        REPAIR_PRIORITY_REASONS.has(reason) &&
+        (action === "omitted") === (reason === "source-priority-absent" || reason === "source-priority-invalid")
+      );
+    }
+    case "classifier": {
+      const reason = value["reason"];
+      return (
+        hasExactKeys(value, ["version", "type", "stream", "mode", "reason"]) &&
+        isRepairStreamIdentity(value["stream"]) &&
+        CLASSIFIER_MODES.has(value["mode"]) &&
+        (reason === null || CLASSIFIER_REASONS.has(reason))
+      );
+    }
+    case "gap": {
+      const reason = value["reason"];
+      const blocks = value["blocks"];
+      return (
+        hasExactKeys(value, [
+          "version",
+          "type",
+          "stream",
+          "trackKind",
+          "action",
+          "reason",
+          "blocks",
+          "missingFrames",
+          "missingMs",
+          "epoch",
+        ]) &&
+        isRepairStreamIdentity(value["stream"]) &&
+        (value["trackKind"] === "video" || value["trackKind"] === "audio") &&
+        typeof reason === "string" &&
+        GAP_REASONS[reason] !== undefined &&
+        GAP_REASONS[reason] === value["action"] &&
+        Array.isArray(blocks) &&
+        blocks.every(isNonNegativeSafeInteger) &&
+        (value["missingFrames"] === null || isNonNegativeSafeInteger(value["missingFrames"])) &&
+        isNullableNonNegative(value["missingMs"]) &&
+        isNonNegativeSafeInteger(value["epoch"])
+      );
+    }
+    case "decoder-unavailable":
+      return (
+        hasExactKeys(value, ["version", "type", "stream", "reason", "fallbackDecoder"]) &&
+        isRepairStreamIdentity(value["stream"]) &&
+        isDecoderUnavailableReason(value["reason"]) &&
+        isFecFallbackDecoder(value["fallbackDecoder"])
+      );
+    default:
+      return false;
+  }
+}
+
+/**
+ * Forward typed repair lifecycle observations through an application-owned
+ * EventTarget. The adapter retains no history; the returned function detaches
+ * the observer.
+ */
+export function forwardRepairLifecycleEvents<
+  TEvent extends RepairLifecycleApplicationEvent,
+>(
+  source: RepairLifecycleSource,
+  target: RepairLifecycleEventTarget<TEvent>,
+  options: RepairLifecycleEventOptions<TEvent> & {
+    createEvent: RepairLifecycleEventFactory<TEvent>;
+  },
+): () => void;
+export function forwardRepairLifecycleEvents(
+  source: RepairLifecycleSource,
+  target: EventTarget,
+  options?: RepairLifecycleEventOptions,
+): () => void;
+export function forwardRepairLifecycleEvents(
+  source: RepairLifecycleSource,
+  target:
+    | EventTarget
+    | RepairLifecycleEventTarget<RepairLifecycleApplicationEvent>,
+  options: RepairLifecycleEventOptions<RepairLifecycleApplicationEvent> = {},
+): () => void {
+  return source.addRepairLifecycleObserver((event) => {
+    const eventOptions = {
+      bubbles: options.bubbles ?? false,
+      composed: options.composed ?? false,
+    };
+    const forwardedEvent = options.createEvent
+      ? options.createEvent(REPAIR_LIFECYCLE_EVENT_TYPE, event, eventOptions)
+      : createDefaultRepairLifecycleEvent(event, eventOptions);
+    (
+      target as RepairLifecycleEventTarget<RepairLifecycleApplicationEvent>
+    ).dispatchEvent(forwardedEvent);
+  });
+}
+
+function repairStreamIdentity(
+  packetId: number,
+  catalogTrackName?: string,
+): RepairStreamIdentity {
+  if (!Number.isSafeInteger(packetId) || packetId < 0) {
+    throw new TypeError("packetId must be a non-negative safe integer");
+  }
+  if (
+    catalogTrackName !== undefined &&
+    (typeof catalogTrackName !== "string" || catalogTrackName.length === 0)
+  ) {
+    throw new TypeError("catalogTrackName must be a non-empty string when provided");
+  }
+  return {
+    packetId,
+    catalogTrackName: catalogTrackName ?? null,
+  };
+}
+
+function repairBlockIdentity(
+  packetId: number,
+  sbn: number,
+  catalogTrackName?: string,
+): RepairBlockIdentity {
+  const stream = repairStreamIdentity(packetId, catalogTrackName);
+  if (!Number.isSafeInteger(sbn) || sbn < 0) {
+    throw new TypeError("sbn must be a non-negative safe integer");
+  }
+  return { ...stream, sbn };
+}
+
+/**
+ * Reject a catalog geometry value that is present but not usable. Absent stays
+ * absent — an omitted field is resolved from the previously configured track or
+ * left unset — but a supplied non-finite/non-positive value is a catalog defect
+ * and must fail at configuration time rather than collapse a derived deadline
+ * to ~0 packets later.
+ */
+function assertPositiveGeometry(
+  label: string,
+  value: number | undefined,
+): void {
+  if (value === undefined) return;
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(
+      `[MulticastManager] ${label}=${value}. ` +
+        `Derive a positive ${label} from the stream catalog.`,
+    );
+  }
+}
+
+/** Repair-symbol count (P) may legitimately be 0; only reject malformed values. */
+function assertNonNegativeGeometry(
+  label: string,
+  value: number | undefined,
+): void {
+  if (value === undefined) return;
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(
+      `[MulticastManager] ${label}=${value}. ` +
+        `Derive a non-negative ${label} from the stream catalog.`,
+    );
+  }
+}
+
+/**
+ * One contributor to the stream-global FEC timing reduction.
+ *
+ * FEC geometry is per-track, but a MulticastManager owns exactly one transport
+ * and one router, so the failback watchdog and the router's MFU/reorder timing
+ * are stream-global. They are reduced with `max` across every contributor:
+ * failback must not fire, and the router must not evict, while ANY configured
+ * track's FEC block could still complete.
+ */
+interface FecTimingContribution {
+  deliveryWindowMs?: number;
+  interleaveDepthMs?: number;
+  fps?: number;
+  k?: number;
+  repairSymbols?: number;
+  minimumFailbackWindowMs?: number;
+}
+
+function fecReorderWindowFrames(
+  fecInterleaveDepthMs?: number,
+  fps?: number,
+  _k?: number,
+  _repairSymbols?: number,
+): number {
+  if (!fecInterleaveDepthMs || fecInterleaveDepthMs <= 0 || !fps || fps <= 0) return 0;
+  const frameMs = 1000 / fps;
+  // Reorder across the FEC block span: fecInterleaveDepthMs IS the full block
+  // span (§5.1), so this window admits any FEC-recovered frame from the block
+  // without holding frames longer than one block.
+  return deriveFecInterleaveDepth(fecInterleaveDepthMs, frameMs);
+}
+
+/** Catalog track descriptor for configureMultiTrack(). */
+export interface MultiTrackCatalogTrack {
+  name: string;
+  altGroup?: number;
+  framerate?: number;
+  fec?: unknown;
+  /** PacketId for testability — in production, learned at subscribe time (Plan 03). */
+  packetId?: number;
+  /** `"fec-repair"` marks a self-describing repair track (draft-ramadan-moq-fec
+   *  §6.3). Absent on media tracks and on naming-era catalogs. */
+  packaging?: string;
+  /** The one source track this repair track carries repair symbols for. Layers
+   *  1..n and a keyframe overlay are reachable only through `depends`; layer 0
+   *  is additionally named by the source's `fec.repairTrack`. */
+  depends?: string[];
+  /** Base layer index. Absent on a keyframe overlay, which is a separate FEC
+   *  instance rather than a member of the layer chain. */
+  repairLayer?: number;
+  /** `"keyframe"` on an overlay track. */
+  scope?: string;
+}
+
+/** Multi-track catalog shape accepted by configureMultiTrack(). */
+export interface MultiTrackCatalog {
+  tracks: MultiTrackCatalogTrack[];
+}
+
+/** Creates one stateful synchronous FEC decoder per physical catalog stream. */
+export type WasmFecDecoderFactory = (
+  track: Readonly<MultiTrackCatalogTrack>,
+) => WasmFecDecoder;
+
+const DEFAULT_ALT_GROUP = "__default__";
+
+type FecDiagnosticsGateway = {
+  reportFecDiagnostics?: (snapshot: unknown) => void;
+};
+
+/** Active-block tail forwarded to the bridge; mirrors the IWA's bound. */
+const FEC_DIAGNOSTIC_BLOCK_TAIL = 8;
+
+/**
+ * Project a Worker block snapshot onto the bridge/IWA `subscription_diagnostics`
+ * contract. The contract names the per-block repair symbol count `t`; the
+ * Worker's `repairCount` is the same quantity (P) under its unambiguous name.
+ */
+function projectFecDiagnosticBlock(block: FecBlockSnapshot) {
+  return {
+    sbn: block.sbn,
+    state: block.state,
+    sourceReceived: block.sourceReceived,
+    repairReceived: block.repairReceived,
+    k: block.k,
+    t: block.repairCount,
+    firstSymbolTs: block.firstSymbolTs,
+    lastSymbolTs: block.lastSymbolTs,
+    ...(block.completedTs === undefined ? {} : { completedTs: block.completedTs }),
+    deadlineTs: block.deadlineTs,
+    altaVerified: block.altaVerified,
+    relayBlockSigValid: block.relayBlockSigValid,
+  };
+}
+
+/**
+ * Project the Worker track config onto the bridge/IWA contract. Every key
+ * below is a named field of that contract (see pim-multicast-gateway
+ * `normalizeSubscriptionDiagnostics`); `k`/`t`/`symbolSize` are three
+ * independent axes there, so `repairCount` is emitted as `t` and never
+ * confused with the symbol size. Worker-internal fields such as
+ * `deliveryWindowMs` are not part of the contract and are not forwarded.
+ */
+function projectFecDiagnosticConfig(config: FecTrackConfig) {
+  return {
+    codec: config.codec,
+    trackName: config.trackName,
+    trackType: config.trackType,
+    ...(config.resolution === undefined
+      ? {}
+      : { resolution: { w: config.resolution.w, h: config.resolution.h } }),
+    ...(config.framerate === undefined ? {} : { framerate: config.framerate }),
+    ...(config.sampleRate === undefined ? {} : { sampleRate: config.sampleRate }),
+    ...(config.algorithm === undefined ? {} : { algorithm: config.algorithm }),
+    k: config.k,
+    t: config.repairCount,
+    symbolSize: config.symbolSize,
+    interleaveDepth: config.interleaveDepth,
+    interleaveMs: config.interleaveMs,
+    fecMode: config.fecMode,
+    ...(config.repairTrack === undefined ? {} : { repairTrack: config.repairTrack }),
+    altaEnabled: config.altaEnabled,
+    relayBlockSigEnabled: config.relayBlockSigEnabled,
+  };
+}
+
+function publishFecDiagnostics(packetId: number, stats: FecTrackStats): boolean {
+  const gateway = (globalThis as typeof globalThis & {
+    multicast?: FecDiagnosticsGateway;
+  }).multicast;
+  if (typeof gateway?.reportFecDiagnostics !== "function") return false;
+
+  // Keep the control-plane payload bounded and JSON-safe. The Worker snapshot
+  // already bounds active blocks; the bridge needs only the current block tail
+  // and stable counters, not decoder internals or authentication failure text.
+  // The shape is the IWA contract, not the Worker's internal types: spreading
+  // FecTrackConfig raw once shipped `repairCount` with no `t`, and the IWA
+  // discarded every report ("fec_track.stats.config.t must be a finite
+  // non-negative number").
+  const snapshot = {
+    version: 1,
+    packetId,
+    observedAt: Date.now(),
+    stats: {
+      config: projectFecDiagnosticConfig(stats.config),
+      sourceSymbols: stats.sourceSymbols,
+      repairSymbols: stats.repairSymbols,
+      blocksComplete: stats.blocksComplete,
+      blocksRecovered: stats.blocksRecovered,
+      blocksFailed: stats.blocksFailed,
+      // Required by the IWA subscription_diagnostics contract (pim
+      // normalizeSubscriptionDiagnostics rejects a report without it). No
+      // fill frame is ever synthesised any more — concealment is the sink's
+      // hold-last-good-frame — so the value is 0 until that contract drops
+      // the field.
+      greenFillFrames: 0,
+      recoveryRate: stats.recoveryRate,
+      liveSbn: stats.liveSbn,
+      blocks: stats.blocks.slice(-FEC_DIAGNOSTIC_BLOCK_TAIL).map(projectFecDiagnosticBlock),
+      interleaveWindowBlocks: stats.interleaveWindowBlocks,
+      avgRecoveryMs: stats.avgRecoveryMs,
+      maxRecoveryMs: stats.maxRecoveryMs,
+    },
+  };
+
+  gateway.reportFecDiagnostics(snapshot);
+  return true;
+}
+
+function altGroupKey(track: MultiTrackCatalogTrack): string {
+  return track.altGroup === undefined ? DEFAULT_ALT_GROUP : String(track.altGroup);
+}
+
+/**
+ * Every repair track of each source: layer 0 named by the source's
+ * `fec.repairTrack`, plus every self-describing `packaging: "fec-repair"` track
+ * whose `depends` names that source (layers 1..n and a keyframe overlay), per
+ * draft-ramadan-moq-fec §6.3.
+ *
+ * Membership comes from the explicit pointer and from `depends`, never from a
+ * name suffix, so a publisher-chosen name like "parity-alpha" resolves.
+ *
+ * This deliberately does not call `resolveRepairLayers`: that validates the
+ * full layer contract and requires `packaging: "mmtp"` on the source plus a
+ * declared layer-0 repair track, neither of which a `MultiTrackCatalog`
+ * carries. Running it here would throw on every naming-era catalog. Ownership
+ * registration needs membership only; RS_ID offsets and layer ordering are the
+ * decoder's concern, not the router's.
+ */
+function repairTrackNamesBySource(
+  tracks: readonly MultiTrackCatalogTrack[],
+): Map<string, Set<string>> {
+  const bySource = new Map<string, Set<string>>();
+  const add = (source: string, repair: string): void => {
+    if (!source || !repair) return;
+    const names = bySource.get(source) ?? new Set<string>();
+    names.add(repair);
+    bySource.set(source, names);
+  };
+  for (const track of tracks) {
+    if (
+      track.fec !== undefined &&
+      isFecCatalogConfig(track.fec) &&
+      track.fec.repairTrack
+    ) {
+      add(track.name, track.fec.repairTrack);
+    }
+    if (track.packaging === "fec-repair" && Array.isArray(track.depends) && track.depends.length === 1) {
+      add(track.depends[0]!, track.name);
+    }
+  }
+  return bySource;
+}
+
+export class MulticastManager {
+  readonly #fec: FECManager;
+  readonly #router: MmtpRouter;
+  readonly #transport: MulticastTransport<MmtpIngressContext>;
+  #reportedFecDiagnosticsFailure = false;
+
+  // ── Stream-global FEC timing reduction ──
+  //
+  // FEC geometry is per-track; the transport failback watchdog and the router's
+  // MFU/reorder timing are stream-global (one transport, one router). Both
+  // configuration entry points feed the same reduction so neither can silently
+  // clip the other: configureFec() supplies the baseline, configureTrackFec()
+  // supplies one entry per track, and #applyStreamGlobalFecTiming() takes the
+  // max across all of them.
+  #streamFecBaseline?: FecTimingContribution;
+  readonly #trackFecTiming = new Map<number, FecTimingContribution>();
+
+  // ── Phase 14: multi-track state (D-06, D-07, D-17, D-26, D-28) ──
+
+  /** Maps altGroup → track names sharing that altGroup. */
+  #switchingSets: Map<number, string[]> = new Map();
+
+  /** Repair packetIds that should not get their own FEC decoder (they ARE the repair source). */
+  #repairPacketIds: Set<number> = new Set();
+
+  /** Tracks physical-stream FEC blocks with an outstanding repair fetch. */
+  #repairInFlight: Set<string> = new Set();
+
+  /** Causal repair events; observers own any retention they require. */
+  #repairLifecycleObservers = new Set<RepairLifecycleObserver>();
+  readonly #logRepairLifecycle: boolean;
+
+  #trackResetObservers = new Set<
+    (packetId: number, catalogTrackName: string) => void
+  >();
+
+  /** Callback fired when a repair fetch should be issued for a block. */
+  #onRepairSubscribeCb: RepairSubscribeCallback | null = null;
+
+  /** Keyframe-protected repair policy counters per catalog track. */
+  #blockPolicyStats = new Map<string, BlockPolicyStats>();
+
+  /** The staged in-place rendition switch, if any. */
+  #renditionSwitch: ActiveRenditionSwitch | null = null;
+
+  constructor(options?: MulticastManagerOptions) {
+    this.#logRepairLifecycle = options?.logRepairLifecycle === true;
+    this.#fec = new FECManager();
+    this.#fec.addFecStatsObserver((packetId, stats) => {
+      try {
+        if (publishFecDiagnostics(packetId, stats)) {
+          this.#reportedFecDiagnosticsFailure = false;
+        }
+      } catch (error) {
+        if (!this.#reportedFecDiagnosticsFailure) {
+          this.#reportedFecDiagnosticsFailure = true;
+          console.warn('[MulticastManager] Failed to publish FEC diagnostics:', error);
+        }
+      }
+    });
+    this.#router = new MmtpRouter({
+      fecManager: this.#fec,
+      mfuTimeoutMs: options?.mfuTimeoutMs,
+      reassemblyPolicy: options?.reassemblyPolicy,
+      reassembler: options?.reassembler,
+      maxBufferedMfus: options?.maxBufferedMfus,
+      manifestVerifier: options?.manifestVerifier,
+      manifestVerifierOwnership: options?.manifestVerifierOwnership,
+      resolveManifestIdentity: options?.resolveManifestIdentity,
+      resolveManifestIdentityForRoute: options?.resolveManifestIdentityForRoute,
+      // The router has reset its own state for the stream; reset the rest.
+      onPublisherRestart: (packetId, catalogTrackName) => {
+        this.#resetStreamOutsideRouter(packetId, catalogTrackName);
+      },
+      onBlockFailed: (sbn, packetId, catalogTrackName, blockClass) => {
+        const pathCount = this.#fec.blockPathCount(
+          sbn,
+          packetId,
+          catalogTrackName,
+        );
+        const stats = this.#statsFor(packetId, catalogTrackName);
+        if (blockClass === "delta") stats.deltaBlocksFailed++;
+        else if (blockClass === "audio") stats.audioBlocksFailed++;
+        else stats.keyframeBlocksFailed++;
+        this.#emitRepairLifecycle({
+          version: 2,
+          type: "failed",
+          block: repairBlockIdentity(packetId, sbn, catalogTrackName),
+          blockClass,
+          symbols: {
+            multicast: pathCount?.multicastSymbols ?? 0,
+            moq: pathCount?.moqSymbols ?? 0,
+          },
+        });
+      },
+      onFrameGap: (decision) => {
+        const stats = this.#statsFor(
+          decision.stream.packetId,
+          decision.stream.catalogTrackName ?? undefined,
+        );
+        if (decision.action === "stall") {
+          stats.stalls++;
+        } else {
+          stats.concealedGaps++;
+          stats.concealedBlocks += decision.blocks.length;
+          if (decision.trackKind === "audio") {
+            stats.concealedAudioMs += decision.missingMs ?? 0;
+          } else {
+            stats.concealedFrames += decision.missingFrames ?? 0;
+          }
+        }
+        this.#emitRepairLifecycle(decision);
+      },
+    });
+    this.#transport = new MulticastTransport<MmtpIngressContext>((packet, ingress) => {
+      this.#router.feedPacket(packet, "multicast", undefined, ingress);
+    });
+    // Each joined subscription declares how it delivers packets. An ordered
+    // relay decides FEC block fate by stream order instead of the datagram
+    // inactivity deadline (see MulticastSymbolDelivery in fec-manager).
+    this.#transport.onDelivery((delivery) => {
+      this.#fec.setMulticastSymbolDelivery(delivery);
+    });
+
+    // Worker-path FEC recovery: route recovered source-symbol bytes through
+    // MmtpRouter so MFU reassembly + dedup runs. Without this wiring the
+    // FecWorkerClient's recovered frames fire FECManager.onBlockRecovered
+    // into a null callback and VideoDecoder never sees a real frame.
+    this.#fec.onBlockRecovered = (sbn, packetId, data, meta, recoveredTrackName) => {
+      const recovered = new Uint8Array(data);
+      const catalogTrackName = recoveredTrackName
+        ?? this.#fec.catalogTrackNameForBlock(sbn, packetId);
+      if (catalogTrackName === undefined) {
+        this.#router.routeRecoveredSymbol(sbn, recovered, packetId, meta.esi);
+      } else {
+        this.#router.routeRecoveredSymbol(
+          sbn,
+          recovered,
+          packetId,
+          meta.esi,
+          catalogTrackName,
+        );
+      }
+    };
+
+    // D-28: release the in-flight repair slot when a repair-requested block
+    // resolves (completes, recovers, or fails), and emit the gate log line.
+    // The request-side bridge (FECManager.onRepairNeeded) is wired in
+    // onRepairSubscribe() so repair deadlines only arm once a player has
+    // registered a fetcher — consumers without D-28 pay no timer cost.
+    this.#fec.onRepairResolved = (sbn, packetId, _outcome, catalogTrackName) => {
+      this.clearRepairForBlock(sbn, packetId, catalogTrackName);
+    };
+    // Every block that could not complete from its first-arrival source
+    // symbols and completed anyway reports `recovered` exactly once.
+    this.#fec.onBlockRepaired = (sbn, packetId, catalogTrackName, blockClass, via) => {
+      const pathCount = this.#fec.blockPathCount(sbn, packetId, catalogTrackName);
+      const stats = this.#statsFor(packetId, catalogTrackName);
+      if (blockClass === "delta") {
+        if (via === "quic") stats.deltaBlocksRecoveredQuic++;
+        else stats.deltaBlocksRecoveredInband++;
+      } else if (blockClass === "audio") {
+        if (via === "quic") stats.audioBlocksRecoveredQuic++;
+        else stats.audioBlocksRecoveredInband++;
+      } else if (via === "quic") {
+        stats.keyframeBlocksRecoveredQuic++;
+      } else {
+        stats.keyframeBlocksRecoveredInband++;
+      }
+      this.#emitRepairLifecycle({
+        version: 2,
+        type: "recovered",
+        block: repairBlockIdentity(packetId, sbn, catalogTrackName),
+        blockClass,
+        via,
+        symbols: {
+          multicast: pathCount?.multicastSymbols ?? 0,
+          moq: pathCount?.moqSymbols ?? 0,
+        },
+      });
+    };
+    this.#fec.onBlockReclassified = (sbn, packetId, catalogTrackName, from, to, evidence) => {
+      this.#emitRepairLifecycle({
+        version: 2,
+        type: "reclassified",
+        block: repairBlockIdentity(packetId, sbn, catalogTrackName),
+        from,
+        to,
+        evidence,
+      });
+    };
+    this.#fec.onClassifierMode = (packetId, catalogTrackName, mode, reason) => {
+      const stats = this.#statsFor(packetId, catalogTrackName);
+      stats.classifierMode = mode;
+      stats.classifierReason = reason;
+      this.#emitRepairLifecycle({
+        version: 2,
+        type: "classifier",
+        stream: repairStreamIdentity(packetId, catalogTrackName),
+        mode,
+        reason,
+      });
+    };
+    this.#fec.onBlockVanished = (_sbn, packetId, catalogTrackName) => {
+      this.#statsFor(packetId, catalogTrackName).vanishedBlocks++;
+    };
+    this.#fec.onDecoderUnavailable = (event) => {
+      this.#emitRepairLifecycle({
+        version: 2,
+        type: "decoder-unavailable",
+        stream: repairStreamIdentity(event.packetId, event.catalogTrackName),
+        reason: event.reason,
+        fallbackDecoder: event.fallbackDecoder,
+      });
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Decomposed component accessors (for new code)
+  // ---------------------------------------------------------------------------
+
+  get fecManager(): FECManager {
+    return this.#fec;
+  }
+  get router(): MmtpRouter {
+    return this.#router;
+  }
+  get transport(): MulticastTransport<MmtpIngressContext> {
+    return this.#transport;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Stats
+  // ---------------------------------------------------------------------------
+
+  get reassembler() {
+    return this.#router.reassembler;
+  }
+  get diagnostics() {
+    return {
+      ...this.#router.getDiagnostics(),
+      _fec: this.#fec.diagnostics,
+    };
+  }
+  get stats() {
+    return this.#transport.stats;
+  }
+
+  /**
+   * See MulticastTransport.lastJoinOutcome: how the newest join() to resolve
+   * did, and the typed reason it resolved false. join() here adds no false
+   * path of its own, so every false it returns is named there; a join() that
+   * rejects (catalog FEC configuration that configureFec refuses, for one)
+   * records nothing.
+   */
+  get lastJoinOutcome(): MulticastJoinOutcome | undefined {
+    return this.#transport.lastJoinOutcome;
+  }
+  /** See MulticastTransport.joinStats: join() calls by how they resolved. */
+  get joinStats(): MulticastJoinStats {
+    return this.#transport.joinStats;
+  }
+
+  /**
+   * Accepted bytes for these MMTP packet_ids, cumulative like
+   * `stats.bytesReceived`; see MulticastTransport.bytesReceivedForPacketIds.
+   * Scopes an ABR throughput sample to the active tier when the join admits
+   * more packet_ids than that tier's. Monotonic only while the set is fixed:
+   * re-baseline when the queried set changes (e.g. on a tier switch).
+   */
+  bytesReceivedForPacketIds(packetIds: ReadonlySet<number>): number {
+    return this.#transport.bytesReceivedForPacketIds(packetIds);
+  }
+
+  get fecStats() {
+    return this.#fec.fecStats;
+  }
+
+  /** The raw WASM decoder for stats access */
+  get wasmDecoder() {
+    return this.#fec.wasmDecoder;
+  }
+
+  // ---------------------------------------------------------------------------
+  // FEC configuration (delegates to FECManager)
+  // ---------------------------------------------------------------------------
+
+  setFecDecoder(
+    packetId: number,
+    client: WasmFecDecoder,
+    k: number,
+    trackType: "video" | "audio" = "video",
+    config?: FECManagerConfig,
+    catalogTrackName?: string,
+  ) {
+    const fecConfig = { ...config, k, trackKind: config?.trackKind ?? trackType };
+    this.#fec.setFecDecoder(packetId, client, k, fecConfig, catalogTrackName);
+    this.#configureTrackMapper(packetId, fecConfig);
+    this.#router.setPacketIdType(packetId, trackType);
+  }
+
+  /**
+   * Register a Worker-backed FEC decoder for a specific packetId (track).
+   * Worker-backed tracks decode asynchronously — recovered frames arrive via
+   * FECManager.onBlockRecovered callback instead of feedSourceSymbol return value.
+   */
+  setFecWorker(
+    packetId: number,
+    client: FecWorkerClient,
+    trackType: "video" | "audio",
+    config: FECManagerConfig,
+    catalogTrackName?: string,
+  ): void {
+    this.#fec.setFecWorker(
+      packetId,
+      client,
+      { ...config, trackKind: config.trackKind ?? trackType },
+      catalogTrackName,
+    );
+    this.#configureTrackMapper(packetId, config);
+    this.#router.setPacketIdType(packetId, trackType);
+  }
+
+  /**
+   * Stop routing a stream's symbols to its Worker decoder. Returns false when
+   * none is registered; on success one `decoder-unavailable` repair lifecycle
+   * event with reason 'cleared' reaches every observer, carrying whether a
+   * synchronous WASM decoder still serves the stream. The packet mapping and
+   * track type are untouched: the track still exists, it just has no Worker
+   * decoder. Call this before disposing the client.
+   */
+  clearFecWorker(packetId: number, catalogTrackName?: string): boolean {
+    return this.#fec.clearFecWorker(packetId, catalogTrackName);
+  }
+
+  /** Register callback for Worker-level FecTrackStats updates. */
+  setOnFecStatsUpdate(
+    cb: (packetId: number, stats: FecTrackStats) => void,
+  ): void {
+    this.#fec.onFecStatsUpdate = cb;
+  }
+
+  setFramerate(fps: number) {
+    this.#router.setFramerate(fps);
+  }
+
+  #configureTrackMapper(packetId: number, config: FECManagerConfig): void {
+    const k = config.k;
+    const interleaveMs = config.interleaveDepthMs;
+    const fps = config.fps;
+    const blockProfile = config.blockProfile;
+    if (blockProfile !== undefined && k && k > 0 && interleaveMs && interleaveMs > 0 && fps && fps > 0) {
+      this.#router.setFecMapper(
+        new FecBlockMapper({
+          blockProfile,
+          k,
+          interleaveDepthMs: interleaveMs,
+          gopDurationMs: 1000 / fps,
+        }),
+        packetId,
+      );
+    }
+  }
+
+  /**
+   * Reduce every registered FEC timing contributor to the stream-global
+   * deadlines and apply them to the single transport and single router.
+   *
+   * `max`, not `min` or last-write-wins: a narrower track must never pull the
+   * failback watchdog or the router's reorder window in under a wider track's
+   * still-completable FEC block. Recomputed on every registration so a track
+   * that arrives late widens the stream rather than being clipped by it.
+   */
+  #applyStreamGlobalFecTiming(): void {
+    const contributions: FecTimingContribution[] = [
+      ...(this.#streamFecBaseline ? [this.#streamFecBaseline] : []),
+      ...this.#trackFecTiming.values(),
+    ];
+    if (contributions.length === 0) return;
+
+    let deliveryWindowMs: number | undefined;
+    let minimumFailbackWindowMs: number | undefined;
+    let mfuTimeoutMs: number | undefined;
+    let reorderWindowFrames: number | undefined;
+
+    for (const c of contributions) {
+      if (c.deliveryWindowMs !== undefined) {
+        deliveryWindowMs = Math.max(deliveryWindowMs ?? 0, c.deliveryWindowMs);
+      }
+      if (c.minimumFailbackWindowMs !== undefined) {
+        minimumFailbackWindowMs = Math.max(
+          minimumFailbackWindowMs ?? 0,
+          c.minimumFailbackWindowMs,
+        );
+      }
+      // Only a valid §5.1 ms interleave may drive router timing. A sub-floor
+      // value is a raw frame count (no fps to convert with) and would collapse
+      // the MFU timeout to ~0 and the reorder window to a single frame; skip
+      // the derivation rather than clamp it, leaving previously-configured
+      // router timing untouched.
+      const interleaveOk =
+        c.interleaveDepthMs !== undefined &&
+        c.interleaveDepthMs >= MIN_INTERLEAVE_DEPTH_MS;
+      if (interleaveOk && c.deliveryWindowMs) {
+        mfuTimeoutMs = Math.max(mfuTimeoutMs ?? 0, c.deliveryWindowMs);
+      }
+      if (interleaveOk && c.fps && c.fps > 0) {
+        reorderWindowFrames = Math.max(
+          reorderWindowFrames ?? 0,
+          fecReorderWindowFrames(
+            c.interleaveDepthMs,
+            c.fps,
+            c.k,
+            c.repairSymbols,
+          ),
+        );
+      }
+    }
+
+    const failbackWindowMs =
+      deliveryWindowMs === undefined
+        ? minimumFailbackWindowMs
+        : Math.max(deliveryWindowMs, minimumFailbackWindowMs ?? 0);
+    if (failbackWindowMs !== undefined) {
+      this.#transport.setFailbackWindowMs(failbackWindowMs);
+    }
+    if (mfuTimeoutMs !== undefined) {
+      this.#router.setMfuTimeoutMs(mfuTimeoutMs);
+    }
+    if (reorderWindowFrames !== undefined) {
+      this.#router.setReorderWindow(reorderWindowFrames);
+    }
+  }
+
+  /**
+   * Configure one track's FEC geometry, block mapper, and block-inactivity
+   * deadline from that track's own catalog values, then re-reduce the
+   * stream-global deadlines across every registered track.
+   *
+   * This is the packet-specific replacement for the global `configureFec`
+   * side effects: per-track concerns stay per-track, and the genuinely
+   * stream-global ones (transport failback, router MFU timeout, router reorder
+   * window) become an explicit max reduction instead of a last-caller-wins race
+   * in which whichever track configured last silently set the whole stream's
+   * timing.
+   *
+   * `catalogTrackName` scopes the block-classifier geometry (kind, fps,
+   * interleave, cadence) to that one stream. Pass it whenever ABR rungs can
+   * share this packetId: each rung then classifies with its own framerate
+   * and GOP, and a rung on the packetId that was never configured this way
+   * runs all-protected (`stream-geometry-absent`) instead of borrowing a
+   * sibling's geometry. K, T and the delivery timing stay per packetId.
+   */
+  configureTrackFec(
+    packetId: number,
+    config: Pick<
+      MulticastEndpointConfig,
+      | "fecBlockProfile"
+      | "fecK"
+      | "fecRepairSymbols"
+      | "fecSymbolSize"
+      | "fecInterleaveDepthMs"
+      | "fecReorderToleranceMs"
+      | "fps"
+      | "bandwidth"
+      | "minimumFailbackWindowMs"
+      | "trackKind"
+      | "codec"
+      | "timescale"
+      | "keyframeIntervalTicks"
+      | "keyframeIntervalMs"
+    >,
+    catalogTrackName?: string,
+  ): void {
+    if (catalogTrackName !== undefined && catalogTrackName.length === 0) {
+      throw new Error(
+        `[MulticastManager] configureTrackFec(${packetId}) catalogTrackName must be non-empty when given`,
+      );
+    }
+    if (config.fecK === undefined || config.fecInterleaveDepthMs === undefined) {
+      throw new Error(
+        `[MulticastManager] configureTrackFec(${packetId}) requires fecK and ` +
+          "fecInterleaveDepthMs. Derive the per-track FEC geometry from the " +
+          "stream catalog.",
+      );
+    }
+    const blockProfile = parseFecBlockProfile(
+      config.fecBlockProfile,
+      `[MulticastManager] configureTrackFec(${packetId}) fecBlockProfile`,
+    );
+    assertPositiveGeometry("fecK", config.fecK);
+    assertPositiveGeometry("fecInterleaveDepthMs", config.fecInterleaveDepthMs);
+    assertPositiveGeometry("fecSymbolSize", config.fecSymbolSize);
+    assertPositiveGeometry("fps", config.fps);
+    assertPositiveGeometry("bandwidth", config.bandwidth);
+    assertPositiveGeometry(
+      "minimumFailbackWindowMs",
+      config.minimumFailbackWindowMs,
+    );
+    assertPositiveGeometry("timescale", config.timescale);
+    assertPositiveGeometry("keyframeIntervalTicks", config.keyframeIntervalTicks);
+    assertPositiveGeometry("keyframeIntervalMs", config.keyframeIntervalMs);
+    assertNonNegativeGeometry("fecRepairSymbols", config.fecRepairSymbols);
+    // A tolerance is the network path's allowance, added to the encoder's
+    // span. These are public entry points: the catalog parser validates what it
+    // parses, but a direct caller reaches this arithmetic without passing
+    // through it. A negative value silently *shortens* the delivery window
+    // below the signaled span, and Infinity/NaN yields a window no block can
+    // ever miss -- the eviction bound stops bounding. Reuse the shared
+    // non-negative guard rather than an inline check: undefined must stay
+    // undefined (absent means the encoder never signaled one, and must not be
+    // defaulted), while a declared 0 is a real value that has to survive.
+    assertNonNegativeGeometry(
+      "fecReorderToleranceMs",
+      config.fecReorderToleranceMs,
+    );
+
+    // Same derivation as the stream-global path, but from THIS track's
+    // geometry. FECManager already stores a per-track timeoutMs
+    // (configureTrack/timeoutMsForPacket); it just never had the repair-symbol
+    // and bandwidth inputs needed to compute one.
+    const deliveryWindowMs =
+      config.fecInterleaveDepthMs >= MIN_INTERLEAVE_DEPTH_MS
+        ? computeFecDeliveryWindowMs({
+            interleaveDepthMs: config.fecInterleaveDepthMs,
+            sourceSymbols: config.fecK,
+            repairSymbols: config.fecRepairSymbols,
+            symbolSize: config.fecSymbolSize,
+            mediaUnitsPerSecond: config.fps,
+            bandwidthBps: config.bandwidth,
+            jitterBufferMs: config.fecReorderToleranceMs,
+          })
+        : undefined;
+
+    // The block classifier's geometry comes from the raw catalog cadence
+    // fields; a track whose media kind is not known yet classifies fail-closed.
+    const trackKind = config.trackKind ?? this.#router.trackKindFor(packetId);
+    const geometry = trackKind === undefined
+      ? undefined
+      : deriveBlockClassifierGeometry({
+          trackKind,
+          framerate: config.fps,
+          interleaveDepthMs: config.fecInterleaveDepthMs,
+          timescale: config.timescale,
+          keyframeIntervalTicks: config.keyframeIntervalTicks,
+          keyframeIntervalMs: config.keyframeIntervalMs,
+        });
+    const fecConfig: FECManagerConfig = {
+      blockProfile,
+      k: config.fecK,
+      symbolSize: config.fecSymbolSize,
+      interleaveDepthMs: config.fecInterleaveDepthMs,
+      fps: config.fps,
+      timeoutMs: deliveryWindowMs,
+      ...(trackKind === undefined ? {} : { trackKind }),
+      ...(config.codec === undefined ? {} : { codec: config.codec }),
+      ...(geometry === undefined ? {} : { geometry }),
+    };
+    this.#fec.configureTrack(packetId, fecConfig, catalogTrackName);
+    this.#configureTrackMapper(packetId, fecConfig);
+
+    this.#trackFecTiming.set(packetId, {
+      deliveryWindowMs,
+      interleaveDepthMs: config.fecInterleaveDepthMs,
+      fps: config.fps,
+      k: config.fecK,
+      repairSymbols: config.fecRepairSymbols,
+      minimumFailbackWindowMs: config.minimumFailbackWindowMs,
+    });
+    this.#applyStreamGlobalFecTiming();
+  }
+
+  configureFec(
+    config: Pick<
+      MulticastEndpointConfig,
+      | "fecBlockProfile"
+      | "fecK"
+      | "fecRepairSymbols"
+      | "fecSymbolSize"
+      | "fecInterleaveDepthMs"
+      | "fecReorderToleranceMs"
+      | "fps"
+      | "bandwidth"
+      | "minimumFailbackWindowMs"
+    >,
+  ) {
+    const minimumFailbackWindowMs = config.minimumFailbackWindowMs;
+    if (
+      minimumFailbackWindowMs !== undefined &&
+      (!Number.isFinite(minimumFailbackWindowMs) || minimumFailbackWindowMs <= 0)
+    ) {
+      throw new Error(
+        `[MulticastManager] minimumFailbackWindowMs=${minimumFailbackWindowMs}. ` +
+          "Derive a positive failback floor from the stream catalog.",
+      );
+    }
+    // A tolerance is the network path's allowance, added to the encoder's
+    // span. These are public entry points: the catalog parser validates what it
+    // parses, but a direct caller reaches this arithmetic without passing
+    // through it. A negative value silently *shortens* the delivery window
+    // below the signaled span, and Infinity/NaN yields a window no block can
+    // ever miss -- the eviction bound stops bounding. Reuse the shared
+    // non-negative guard rather than an inline check: undefined must stay
+    // undefined (absent means the encoder never signaled one, and must not be
+    // defaulted), while a declared 0 is a real value that has to survive.
+    assertNonNegativeGeometry(
+      "fecReorderToleranceMs",
+      config.fecReorderToleranceMs,
+    );
+    const deliveryWindowMs =
+      config.fecK &&
+      config.fecK > 0 &&
+      config.fecInterleaveDepthMs &&
+      config.fecInterleaveDepthMs >= MIN_INTERLEAVE_DEPTH_MS
+        ? computeFecDeliveryWindowMs({
+            interleaveDepthMs: config.fecInterleaveDepthMs,
+            sourceSymbols: config.fecK,
+            repairSymbols: config.fecRepairSymbols,
+            symbolSize: config.fecSymbolSize,
+            mediaUnitsPerSecond: config.fps,
+            bandwidthBps: config.bandwidth,
+            jitterBufferMs: config.fecReorderToleranceMs,
+          })
+        : undefined;
+    this.#fec.configure({
+      k: config.fecK,
+      symbolSize: config.fecSymbolSize,
+      interleaveDepthMs: config.fecInterleaveDepthMs,
+      fps: config.fps,
+      timeoutMs: deliveryWindowMs,
+    });
+    // External-feed consumers own the multicast socket and call feedPacket()
+    // directly, so they never enter join(). Configure the transport watchdog
+    // here where both transport-owned and external-feed paths share the same
+    // catalog-derived FEC timing.
+    //
+    // This call supplies the stream-global BASELINE contribution. Any track
+    // registered via configureTrackFec() participates in the same max
+    // reduction, so a per-track window can only widen these deadlines, never
+    // narrow them below what this baseline already guarantees.
+    this.#streamFecBaseline = {
+      deliveryWindowMs,
+      interleaveDepthMs: config.fecInterleaveDepthMs,
+      fps: config.fps,
+      k: config.fecK,
+      repairSymbols: config.fecRepairSymbols,
+      minimumFailbackWindowMs,
+    };
+    this.#applyStreamGlobalFecTiming();
+    // Wire FecBlockMapper to MmtpRouter so SBN/ESI derivation works for FEC recovery.
+    //
+    // gopDurationMs MUST be the per-frame interval (1000/fps), NOT the
+    // interleaveDepthMs. Passing interleaveDepthMs collapses D to 1, which
+    // makes the mapper math equivalent to the no-mapper fallback
+    // (floor(ssId/k), ssId%k) and breaks SBN/ESI derivation for any interleaved
+    // FEC. Surfaced by BLO-3323 L14 (pim-multicast-gateway run 26373805710):
+    // with K=32 + interleaveDepthMs=1000ms but gopDurationMs=1000ms, blocks
+    // completed with only ~8 source + ~8 repair symbols (out of 40 expected at
+    // 25-30fps), so the WASM decoder failed to recover any block at 10% loss.
+    const k = config.fecK;
+    const interleaveMs = config.fecInterleaveDepthMs;
+    const fps = config.fps;
+    // The stream-global mapper is the k-padded-v1 SS_ID locator; it exists
+    // only for a stream whose catalog names that profile.
+    const blockProfile = config.fecBlockProfile === undefined
+      ? undefined
+      : parseFecBlockProfile(config.fecBlockProfile, "[MulticastManager] configureFec fecBlockProfile");
+    if (blockProfile !== undefined && k && k > 0 && interleaveMs && interleaveMs > 0 && fps && fps > 0) {
+      const mapper = new FecBlockMapper({
+        blockProfile,
+        k,
+        interleaveDepthMs: interleaveMs,
+        gopDurationMs: 1000 / fps,
+      });
+      this.#router.setFecMapper(mapper);
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Track configuration (delegates to MmtpRouter)
+  // ---------------------------------------------------------------------------
+
+  // Track type discovery callback — fires when setPacketIdType is called.
+  // Players wire this to MediaRouter.registerTrackTypeFromInit() for
+  // init data authority (authoritative until next catalog update).
+  #onTrackTypeDiscovered:
+    | ((packetId: number, trackType: "video" | "audio") => void)
+    | null = null;
+
+  /** Register callback for track type discovery (from init data / inline signaling). */
+  onTrackTypeDiscovered(
+    cb: (packetId: number, trackType: "video" | "audio") => void,
+  ): void {
+    this.#onTrackTypeDiscovered = cb;
+  }
+
+  setPacketIdType(packetId: number, trackType: "video" | "audio") {
+    this.#router.setPacketIdType(packetId, trackType);
+    this.#onTrackTypeDiscovered?.(packetId, trackType);
+  }
+
+  /**
+   * Set the keyframe loss timeout on the inner MmtpRouter (Phase 13).
+   * Applies only to tracks WITHOUT FEC: an FEC track never arms the timer,
+   * because its vanished blocks resolve through catalog-derived block
+   * deadlines and the release gate's stall decision.
+   * Must be called BEFORE setPacketIdType('video'). A reader is passed
+   * through; see MmtpRouter.setKeyframeLostTimeoutMs.
+   */
+  setKeyframeLostTimeoutMs(ms: number | (() => number)): void {
+    this.#router.setKeyframeLostTimeoutMs(ms);
+  }
+
+  setMfuTimeoutMs(ms: number): void {
+    this.#router.setMfuTimeoutMs(ms);
+  }
+
+  setTrackCodec(packetId: number, codec: string) {
+    this.#router.setTrackCodec(packetId, codec);
+    // Never configure an FEC track by side effect: only an already
+    // configured FEC track learns its codec here.
+    if (this.#fec.isTrackConfigured(packetId)) {
+      this.#fec.configureTrack(packetId, { codec });
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Callbacks (delegates to MmtpRouter)
+  // ---------------------------------------------------------------------------
+
+  onVideoFrame(cb: FrameCallback) {
+    this.#router.onVideoFrame(cb);
+  }
+  onAudioFrame(cb: FrameCallback) {
+    this.#router.onAudioFrame(cb);
+  }
+  onTrackFrame(packetId: number, cb: FrameCallback) {
+    this.#router.onTrackFrame(packetId, cb);
+  }
+  onTrackPacket(packetId: number, cb: TrackPacketCallback) {
+    this.#router.onTrackPacket(packetId, cb);
+  }
+  onInitSegment(cb: (data: Uint8Array) => void) {
+    this.#router.onInitSegment(cb);
+  }
+  onTrackInit(packetId: number, cb: (data: Uint8Array) => void) {
+    this.#router.onTrackInit(packetId, cb);
+  }
+  onFecBlockStarted(cb: (sbn: number, packetId: number) => void) {
+    this.#router.onFecBlockStarted(cb);
+  }
+  /** Unrecoverable-FEC-block signal. Players drive decoder recovery from this
+   *  (a starved decoder cannot resync on its own once the block is abandoned). */
+  onFecBlockFailed(
+    cb: (sbn: number, packetId: number, catalogTrackName?: string) => void,
+  ) {
+    this.#router.onFecBlockFailed(cb);
+  }
+
+  // ---------------------------------------------------------------------------
+  // MSE integration (delegates to MmtpRouter)
+  // ---------------------------------------------------------------------------
+
+  enableMseAssembler(
+    packetId: number,
+    config: Omit<BlockAssemblerConfig, "k">,
+    catalogTrackName?: string,
+  ) {
+    return this.#router.enableMseAssembler(packetId, config, catalogTrackName);
+  }
+
+  onMseSegment(packetId: number, cb: (segment: Uint8Array) => void, catalogTrackName?: string) {
+    this.#router.onMseSegment(packetId, cb, catalogTrackName);
+  }
+
+  onMseSample(packetId: number, cb: (sample: CmafBlockSample) => void, catalogTrackName?: string) {
+    this.#router.onMseSample(packetId, cb, catalogTrackName);
+  }
+
+  onMseInitSegment(packetId: number, cb: (init: Uint8Array) => void, catalogTrackName?: string) {
+    this.#router.onMseInitSegment(packetId, cb, catalogTrackName);
+  }
+
+  emitMseInit(packetId: number, catalogTrackName?: string) {
+    this.#router.emitMseInit(packetId, catalogTrackName);
+  }
+
+  markExternalVideoSync(packetId?: number, catalogTrackName?: string) {
+    this.#router.markExternalVideoSync(packetId, catalogTrackName);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Transport (delegates to MulticastTransport)
+  // ---------------------------------------------------------------------------
+
+  onTakeover(cb: () => void) {
+    this.#transport.onTakeover(cb);
+  }
+  onFailback(cb: (reason: MulticastFailbackReason) => void) {
+    this.#transport.onFailback(cb);
+  }
+  /** See MulticastTransport.onDataPlaneLive: the join's first accepted packet. */
+  onDataPlaneLive(cb: () => void) {
+    this.#transport.onDataPlaneLive(cb);
+  }
+  confirmVideo() {
+    this.#transport.confirmVideo();
+  }
+  confirmAudio() {
+    this.#transport.confirmAudio();
+  }
+
+  static isAvailable(): boolean {
+    return MulticastTransport.isAvailable();
+  }
+
+  async join(config: MulticastEndpointConfig): Promise<boolean> {
+    // A join replaces the admission a staged switch was built on. The new
+    // join's config decides what is admitted, so nothing is restored or
+    // retired here: the switch just ends.
+    const staged = this.#renditionSwitch;
+    if (staged !== null) this.#endRenditionSwitch(staged, { reason: "superseded" }, false);
+
+    // Configure every FEC/MFU deadline before subscribing so direct-feed and
+    // transport-owned consumers use the same catalog-derived delivery window.
+    this.configureFec(config);
+
+    // Every transport join starts at an arbitrary multicast symbol. Reset only
+    // join-boundary classification; retain configured tracks, decoders, and
+    // cumulative diagnostics across failback/rejoin cycles.
+    this.#fec.beginMulticastJoin();
+    const selectedPacketIds = config.packetIds?.length
+      ? new Set(config.packetIds)
+      : null;
+    const catalogTracks = config.tracks?.filter(({ packetId }) =>
+      selectedPacketIds === null || selectedPacketIds.has(packetId));
+    const ingressTracks = catalogTracks
+      ? catalogTracks
+      : selectedPacketIds === null
+        ? undefined
+        : [...selectedPacketIds].map((packetId) => ({ name: "", packetId }));
+    const ingress = ingressTracks === undefined
+      ? undefined
+      : {
+          tracks: Object.freeze(
+            ingressTracks.map(({ name, packetId }) =>
+              Object.freeze({ name, packetId }),
+            ),
+          ),
+        };
+    // Precedence between two sources, not a tolerant alias. BOTH operands can
+    // carry a catalog-declared relay, so neither one is "the" inlet:
+    //   `amtRelay`     — the player/UI override, AND the post-migration catalog
+    //                    path: `endpointToMulticastConfig` (packages/transport
+    //                    multicast-catalog-policy.ts) resolves
+    //                    `multicast.networkSource[{type:"amt"}]` into it
+    //                    through `findAmtRelay`.
+    //   `relayAddress` — the pre-migration per-endpoint relay, retained so a
+    //                    catalog published before BLO-37834 still joins.
+    // The override/networkSource value wins, else the legacy endpoint value.
+    // `??`, not `||`, so precedence is deliberately NOT trim-aware: a player
+    // clearing its override field means "no AMT", not "fall back to the legacy
+    // relay". Blank is absent for the port decision below but present here.
+    // Retiring `relayAddress` is the legacy cut (BLO-38068), not this branch.
+    const amtRelay = config.amtRelay ?? config.relayAddress;
+    const transportConfig = {
+      sourceAddress: config.sourceAddress,
+      groupAddress: config.groupAddress,
+      port: config.port,
+      mode: config.mode,
+      amtRelay,
+      // A relay here is a commitment to that relay, not a hint: a relay with no
+      // port does NOT fall back to DRIAD, it joins on RFC 7450's 2268.
+      // `toWindowMulticastSubscribeConfig` (packages/transport
+      // endpoint-config.ts) deliberately has no implicit relay port — it throws
+      // and `MulticastTransport.join` resolves false — so the default is
+      // resolved HERE and arrives there explicit, exactly as the two catalog
+      // readers do it. This is the last of the three readers: the `relayAddress`
+      // half cannot supply a port at all (the pre-migration wire shape has no
+      // port field), and `resolveNetworkSource` emits the same port-less shape.
+      // Keyed on the resolved relay, so a DRIAD entry — which pins no relay —
+      // never has a port manufactured for it. Blank counts as no relay, the
+      // same test `catalogAmtNetworkSource` applies (it trims, then skips) and
+      // the same one `toWindowMulticastSubscribeConfig` re-derives downstream
+      // (`input.amtRelay?.trim()`): a port paired with a relay that consumer
+      // reads as absent is a shape no reader here should manufacture. Only the
+      // default is gated — an explicit `amtRelayPort` is caller data and passes
+      // through whatever the relay looks like, since dropping it would be the
+      // worse behaviour.
+      amtRelayPort:
+        config.amtRelayPort ??
+        config.relayPort ??
+        (amtRelay?.trim() ? DEFAULT_AMT_RELAY_PORT : undefined),
+      packetIds: config.packetIds,
+      tracks: catalogTracks?.map(({ name, packetId }) => ({ name, packetId })),
+    };
+    return ingress === undefined
+      ? this.#transport.join(transportConfig)
+      : this.#transport.join(transportConfig, ingress);
+  }
+
+  // ---------------------------------------------------------------------------
+  // In-place rendition switch
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Switch the live join from one video rendition to another in place: the
+   * subscription (socket, group membership, AMT tunnel) is kept, and the
+   * packet-ID remap commits atomically at a RAP of the incoming rendition.
+   *
+   * Staging widens the admission to carry both renditions: the ingress
+   * tracks become the live ones plus `tracks`, and, when `packetIds` is
+   * given, the allow-list becomes the live one plus `packetIds` (a provider
+   * that cannot widen in place is refused here, before anything changes).
+   * The incoming rendition's packets then feed its FEC and parser while the
+   * outgoing rendition keeps playing, and MmtpRouter.stageStreamSwitch
+   * withholds every incoming frame and its init until the commit.
+   *
+   * The commit is one synchronous step inside the frame path, at the
+   * incoming RAP (see MmtpRouter.stageStreamSwitch for where exactly): the
+   * outgoing packet ID is retired from the router, the admission becomes
+   * exactly `tracks` (and `packetIds`), the outgoing stream's FEC and repair
+   * state is released (FECManager.releasePacket; repair fetches in flight are
+   * aborted through the track-reset observers), `onCommit` runs, and then the
+   * incoming init and RAP are delivered. No outgoing frame is delivered after
+   * it and no incoming frame before it. No timer is armed: the switch waits
+   * on RAPs and on the outgoing stream's own frames.
+   *
+   * Exactly one of `onCommit` and `onCancel` is called per switch. One switch
+   * may be staged at a time.
+   */
+  switchRendition(request: RenditionSwitchRequest): RenditionSwitch {
+    if (this.#renditionSwitch !== null) {
+      throw new Error(
+        "[MulticastManager] a rendition switch is already staged; cancel it before staging another",
+      );
+    }
+    if (typeof request?.onCommit !== "function" || typeof request.onCancel !== "function") {
+      throw new Error("[MulticastManager] switchRendition requires onCommit and onCancel callbacks");
+    }
+    const live = this.#transport.context;
+    if (!this.#transport.joined || live === undefined) {
+      throw new Error(
+        "[MulticastManager] switchRendition needs a live join with catalog ingress tracks: " +
+          "join() with packetIds or tracks first",
+      );
+    }
+    const { from, to } = request;
+    if (!Array.isArray(request.tracks)) {
+      throw new TypeError("[MulticastManager] switchRendition tracks must be an array");
+    }
+    for (const track of request.tracks) {
+      if (
+        typeof track?.name !== "string" ||
+        track.name.length === 0 ||
+        !isMulticastTrackPacketId(track.packetId)
+      ) {
+        throw new RangeError(
+          "[MulticastManager] switchRendition tracks need a non-empty catalog name and a track packet ID each",
+        );
+      }
+    }
+    const holds = (
+      tracks: MmtpIngressContext["tracks"],
+      stream: MmtpStreamIdentity | undefined,
+    ): boolean =>
+      stream !== undefined &&
+      tracks.some((track) => track.name === stream.catalogTrackName && track.packetId === stream.packetId);
+    if (!holds(live.tracks, from)) {
+      throw new Error(
+        `[MulticastManager] switchRendition: from (${from?.catalogTrackName} on ${from?.packetId}) ` +
+          "is not an ingress track of the live join",
+      );
+    }
+    if (to === undefined || live.tracks.some((track) => track.packetId === to.packetId)) {
+      throw new Error(
+        `[MulticastManager] switchRendition: to's packet ID ${to?.packetId} is already admitted ` +
+          "by the live join's ingress; an in-place switch admits a rendition that is not playing",
+      );
+    }
+    if (!holds(request.tracks, to)) {
+      throw new Error("[MulticastManager] switchRendition: tracks must carry to");
+    }
+    if (request.tracks.some((track) => track.packetId === from.packetId)) {
+      throw new Error(
+        `[MulticastManager] switchRendition: tracks must not carry from's packet ID ${from.packetId}; ` +
+          "the commit retires it",
+      );
+    }
+    // While staged, the ingress is the live tracks plus these. One packet ID
+    // under two names is ambiguous to the router, which drops it, so a track
+    // must keep the name the live join gave its packet ID.
+    const renamed = request.tracks.find((track) =>
+      live.tracks.some((liveTrack) => liveTrack.packetId === track.packetId && liveTrack.name !== track.name));
+    if (renamed !== undefined) {
+      throw new Error(
+        `[MulticastManager] switchRendition: tracks name packet ID ${renamed.packetId} ` +
+          `"${renamed.name}", but the live join admits it under another name`,
+      );
+    }
+    const livePacketIds = this.#transport.packetIds;
+    let committedPacketIds: readonly number[] | undefined;
+    if (request.packetIds !== undefined) {
+      if (
+        !Array.isArray(request.packetIds) ||
+        request.packetIds.length === 0 ||
+        !request.packetIds.every(isMulticastTrackPacketId)
+      ) {
+        throw new RangeError(
+          "[MulticastManager] switchRendition packetIds must be a non-empty list of track packet IDs",
+        );
+      }
+      if (!request.packetIds.includes(to.packetId)) {
+        throw new Error("[MulticastManager] switchRendition: packetIds must admit to");
+      }
+      committedPacketIds = Object.freeze([...new Set(request.packetIds)]);
+    } else if (livePacketIds !== null && !livePacketIds.has(to.packetId)) {
+      throw new Error(
+        `[MulticastManager] switchRendition: the live allow-list does not admit to (${to.packetId}); ` +
+          "pass the post-switch packetIds",
+      );
+    }
+
+    const stagedTracks = new Map<string, Readonly<{ name: string; packetId: number }>>();
+    for (const track of [...live.tracks, ...request.tracks]) {
+      stagedTracks.set(`${track.packetId}\0${track.name}`, track);
+    }
+    const stagedIngress = freezeIngress(stagedTracks.values());
+    const stagedPacketIds =
+      committedPacketIds === undefined || livePacketIds === null
+        ? null
+        : new Set([...livePacketIds, ...committedPacketIds]);
+    const widened = stagedPacketIds !== null && !sameIdSet(stagedPacketIds, livePacketIds!);
+
+    const active: ActiveRenditionSwitch = {
+      from: Object.freeze({ packetId: from.packetId, catalogTrackName: from.catalogTrackName }),
+      to: Object.freeze({ packetId: to.packetId, catalogTrackName: to.catalogTrackName }),
+      onCommit: request.onCommit,
+      onCancel: request.onCancel,
+      liveIngress: live,
+      livePacketIds,
+      widened,
+      committedIngress: freezeIngress(request.tracks),
+      committedPacketIds,
+      router: null,
+      state: "staged",
+    };
+    // Throws on an unregistered or non-video stream before any admission changes.
+    active.router = this.#router.stageStreamSwitch({
+      from: active.from,
+      to: active.to,
+      onCommit: (commit) => this.#commitRenditionSwitch(active, commit),
+    });
+    let widening: Promise<void> | undefined;
+    try {
+      if (widened) widening = this.#transport.setPacketIds([...stagedPacketIds!]);
+      this.#transport.setContext(stagedIngress);
+    } catch (error) {
+      active.router.cancel();
+      throw error;
+    }
+    this.#renditionSwitch = active;
+    widening?.catch((error: unknown) => {
+      if (this.#renditionSwitch !== active) return;
+      this.#endRenditionSwitch(active, { reason: "provider-refused", error }, true);
+    });
+    return {
+      get state() {
+        return active.state;
+      },
+      cancel: () => {
+        if (this.#renditionSwitch !== active) return false;
+        this.#endRenditionSwitch(active, { reason: "cancelled" }, true);
+        return true;
+      },
+    };
+  }
+
+  /** The router committed the staged switch (it already retired `from`). */
+  #commitRenditionSwitch(active: ActiveRenditionSwitch, commit: StreamSwitchCommit): void {
+    if (this.#renditionSwitch !== active) return;
+    this.#renditionSwitch = null;
+    active.state = "committed";
+    active.router = null;
+    if (this.#transport.joined) {
+      this.#transport.setContext(active.committedIngress);
+      if (active.committedPacketIds !== undefined) {
+        // The page-side filter narrows now; the provider may keep delivering
+        // the retired IDs until it applies the narrower list, and the page
+        // drops them meanwhile.
+        this.#transport.setPacketIds(active.committedPacketIds).catch((error: unknown) => {
+          console.warn(
+            "[MulticastManager] the provider did not narrow its packet filter after a rendition switch; " +
+              "the page-side filter drops the retired packet IDs",
+            error,
+          );
+        });
+      }
+    }
+    this.#releaseRetiredStream(commit.from);
+    try {
+      active.onCommit(commit);
+    } catch (error) {
+      // The caller could not take `to`. Report it, release what the manager
+      // holds for `to`, and rethrow so the router retires `to` instead of
+      // feeding it to a decoder still configured for `from`.
+      active.state = "failed";
+      this.#releaseRetiredStream(active.to);
+      try {
+        active.onCancel({ reason: "commit-failed", error });
+      } catch (cancelError) {
+        console.warn("[MulticastManager] rendition switch onCancel failed", cancelError);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * End a staged switch without committing. `restore` puts the pre-switch
+   * admission back and retires `to`; a join or dispose supersedes both.
+   */
+  #endRenditionSwitch(
+    active: ActiveRenditionSwitch,
+    cancel: RenditionSwitchCancel,
+    restore: boolean,
+  ): void {
+    if (this.#renditionSwitch !== active) return;
+    this.#renditionSwitch = null;
+    active.state = "cancelled";
+    active.router?.cancel();
+    active.router = null;
+    if (restore) {
+      if (this.#transport.joined) {
+        this.#transport.setContext(active.liveIngress);
+        if (active.widened && active.livePacketIds !== null) {
+          this.#transport.setPacketIds([...active.livePacketIds]).catch((error: unknown) => {
+            console.warn(
+              "[MulticastManager] the provider did not narrow its packet filter after a cancelled " +
+                "rendition switch; the page-side filter drops the incoming packet IDs",
+              error,
+            );
+          });
+        }
+      }
+      this.#router.retirePacketId(active.to.packetId);
+      this.#releaseRetiredStream(active.to);
+    }
+    try {
+      active.onCancel(cancel);
+    } catch (error) {
+      console.warn("[MulticastManager] rendition switch onCancel failed", error);
+    }
+  }
+
+  /** Release what the manager and FEC hold for a stream whose packet ID the router retired. */
+  #releaseRetiredStream(stream: MmtpStreamIdentity): void {
+    // Repair transports abort I/O for a stream on a reset notice
+    // (wireRepairFetch); a retired stream's repair fetches end with it.
+    for (const observer of this.#trackResetObservers) {
+      try {
+        observer(stream.packetId, stream.catalogTrackName);
+      } catch (error) {
+        console.warn("[MulticastManager] track reset observer failed", error);
+      }
+    }
+    for (const key of [...this.#repairInFlight]) {
+      try {
+        const [keyPacketId] = JSON.parse(key);
+        if (keyPacketId === stream.packetId) this.#repairInFlight.delete(key);
+      } catch {
+        // Internal keys are JSON tuples; preserve unknown legacy entries.
+      }
+    }
+    for (const [key, stats] of [...this.#blockPolicyStats]) {
+      if (stats.packetId === stream.packetId) this.#blockPolicyStats.delete(key);
+    }
+    // The retired track stops contributing to the stream-global FEC timing;
+    // the deadlines already applied stay until the next configuration
+    // re-reduces them, which only ever errs toward the wider window.
+    this.#trackFecTiming.delete(stream.packetId);
+    this.#fec.releasePacket(stream.packetId);
+  }
+
+  /** Feed a raw packet from an external source (AMT tunnel, ASM subscription).
+   *
+   *  For MoQ-unicast-fallback mode (no SSM bridge), call
+   *  `manager.router.feedPacket(packet, "moq")` directly to bypass
+   *  MulticastTransport's takeover/watchdog/failback gates while preserving
+   *  transport attribution in FEC path counters.
+   *  The `router` accessor above is already public.
+   */
+  feedPacket(data: ArrayBuffer | Uint8Array, ingress?: MmtpIngressContext) {
+    this.#transport.feedPacket(data, ingress);
+  }
+
+  /**
+   * Declare how packets given to feedPacket() reach this manager. A consumer
+   * that owns the multicast socket itself declares its own leg; join()
+   * applies what the window.multicast subscription declares instead.
+   */
+  setMulticastSymbolDelivery(delivery: MulticastSymbolDelivery): void {
+    this.#fec.setMulticastSymbolDelivery(delivery);
+  }
+
+  /** Process a repair packet from MoQ (reliable QUIC). */
+  processRepairFromMoQ(
+    packet: Uint8Array,
+    ownerPacketId?: number,
+    catalogTrackName?: string,
+  ) {
+    this.#router.feedRepairPacket(packet, ownerPacketId, catalogTrackName);
+  }
+
+  /** Route a Worker-recovered FEC block through the MMTP parser + dedup pipeline. */
+  routeRecoveredBlock(
+    blockId: number,
+    data: Uint8Array,
+    packetId: number,
+    catalogTrackName?: string,
+  ) {
+    this.#router.routeRecoveredBlock(blockId, data, packetId, catalogTrackName);
+  }
+
+  /** Route one Worker-recovered source symbol through the MMTP parser + dedup pipeline. */
+  routeRecoveredSymbol(
+    blockId: number,
+    data: Uint8Array,
+    packetId: number,
+    esi = 0,
+    catalogTrackName?: string,
+  ) {
+    this.#router.routeRecoveredSymbol(blockId, data, packetId, esi, catalogTrackName);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Phase 14: multi-track catalog ingest (D-04, D-06, D-07, D-17, D-26, D-28)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Configure the manager for a multi-track (base/delta/repair) CMAF switching set.
+   *
+   * D-04: Validates completeness via validateSwitchingSet — throws if incomplete.
+   * D-07: Applies per-track FEC configs (base+delta get decoders; repair does not).
+   * D-17: Builds altGroup → track-name index for getSwitchingSet().
+   * D-26: Registers packetId → TrackRole on MmtpRouter for block-complete fanout.
+   *
+   * @param catalog - Multi-track catalog (tracks array with name, altGroup, fec, packetId).
+   * @param wasmDecoderSource - One WASM FEC decoder for a single FEC stream, or
+   *                            a factory returning a distinct decoder per stream.
+   */
+  configureMultiTrack(
+    catalog: MultiTrackCatalog,
+    wasmDecoderSource?: WasmFecDecoder | WasmFecDecoderFactory,
+  ): void {
+    // D-06: Resolve explicit fec.repairTrack pointers FIRST. This allows
+    // publisher-chosen repair track names (e.g. "video/repair-alt") that don't
+    // match the standard "/repair" suffix convention. The explicit pointer wins
+    // over the naming convention: a track pointed to by repairTrack is always
+    // 'repair'. The pointer lives on the owner, and a repair leg is a raw
+    // application/raptorq track the publisher never tags with an altGroup, so
+    // the leg belongs to its owner's group regardless of what the leg itself
+    // declares.
+    //
+    // Layers 1..n and a keyframe overlay are named only by their own `depends`
+    // (draft-ramadan-moq-fec §6.3), so they are resolved here too. A layer that
+    // did not reach this map would fall through to parseTrackRole and be
+    // mis-roled or rejected on its name, and would land in its own altGroup
+    // rather than its owner's.
+    const repairNamesBySource = repairTrackNamesBySource(catalog.tracks);
+    const repairOwnerGroup = new Map<string, string>();
+    const repairOwnerAltGroup = new Map<string, number | undefined>();
+    for (const track of catalog.tracks) {
+      for (const repairName of repairNamesBySource.get(track.name) ?? []) {
+        repairOwnerGroup.set(repairName, altGroupKey(track));
+        repairOwnerAltGroup.set(repairName, track.altGroup);
+      }
+    }
+    const groupKeyFor = (track: MultiTrackCatalogTrack): string =>
+      repairOwnerGroup.get(track.name) ?? altGroupKey(track);
+
+    const trackNamesByGroup = new Map<string, string[]>();
+    for (const track of catalog.tracks) {
+      const groupKey = groupKeyFor(track);
+      const groupNames = trackNamesByGroup.get(groupKey) ?? [];
+      groupNames.push(track.name);
+      trackNamesByGroup.set(groupKey, groupNames);
+    }
+
+    const hasSwitchingSetByGroup = new Map<string, boolean>();
+    for (const [groupKey, trackNames] of trackNamesByGroup) {
+      hasSwitchingSetByGroup.set(groupKey, hasSwitchingSetRole(trackNames));
+    }
+
+    // Resolve role for each track — explicit pointer wins over naming convention.
+    // Normalize non-standard repair names to 'repair' before calling validateSwitchingSet,
+    // which relies on parseTrackRole and would throw on custom repair-track names.
+    const resolvedRoles: TrackRole[] = catalog.tracks.map((track) => {
+      if (repairOwnerGroup.has(track.name)) return "repair";
+      const hasSwitchingSet = hasSwitchingSetByGroup.get(altGroupKey(track)) ?? false;
+      if (!hasSwitchingSet) return "single";
+      return parseTrackRole(track.name);
+    });
+
+    // D-04: Validate completeness per altGroup using resolved roles.
+    // We replicate validateSwitchingSet logic here to avoid re-calling parseTrackRole
+    // (which would throw on explicit-pointer repair track names like "video/repair-alt").
+    const resolvedRolesByGroup = new Map<string, TrackRole[]>();
+    for (let i = 0; i < catalog.tracks.length; i++) {
+      const groupKey = groupKeyFor(catalog.tracks[i]!);
+      const roles = resolvedRolesByGroup.get(groupKey) ?? [];
+      roles.push(resolvedRoles[i]!);
+      resolvedRolesByGroup.set(groupKey, roles);
+    }
+    for (const [groupKey, roles] of resolvedRolesByGroup) {
+      if (!(hasSwitchingSetByGroup.get(groupKey) ?? false)) continue;
+
+      const presentRoles = new Set(roles.filter((r) => r !== "single"));
+      const required: Array<"base" | "delta" | "repair"> = [
+        "base",
+        "delta",
+        "repair",
+      ];
+      const missing = required.filter((r) => !presentRoles.has(r));
+      if (missing.length > 0) {
+        throw new Error(
+          `[MulticastManager] incomplete switching set: missing ${missing.join(", ")}`,
+        );
+      }
+    }
+
+    const fecTrackIndexes: number[] = [];
+    for (let i = 0; i < catalog.tracks.length; i++) {
+      const track = catalog.tracks[i]!;
+      if (resolvedRoles[i] === "repair" || track.fec === undefined) continue;
+      if (!isFecCatalogConfig(track.fec)) {
+        throw new Error(
+          `[MulticastManager] invalid fec config for track '${track.name}'`,
+        );
+      }
+      if (track.packetId !== undefined) fecTrackIndexes.push(i);
+    }
+
+    // Stateful decoders cannot span physical streams: resetting one stream
+    // would otherwise clear or disable every peer sharing that instance.
+    const fecDecoders = new Map<number, WasmFecDecoder>();
+    if (wasmDecoderSource !== undefined && fecTrackIndexes.length > 0) {
+      if (typeof wasmDecoderSource !== "function") {
+        if (fecTrackIndexes.length > 1) {
+          throw new Error(
+            "[MulticastManager] multiple FEC streams require a decoder factory",
+          );
+        }
+        fecDecoders.set(fecTrackIndexes[0]!, wasmDecoderSource);
+      } else {
+        const clients = new Set<WasmFecDecoder>();
+        for (const index of fecTrackIndexes) {
+          const client = wasmDecoderSource(catalog.tracks[index]!);
+          if (clients.has(client)) {
+            throw new Error(
+              "[MulticastManager] decoder factory must return one client per physical stream",
+            );
+          }
+          clients.add(client);
+          fecDecoders.set(index, client);
+        }
+      }
+    }
+
+    // Reset switching-set index and repair packetId set.
+    this.#switchingSets.clear();
+    this.#repairPacketIds.clear();
+    this.#router.clearRepairPacketIdOwners();
+    const catalogTracksByName = new Map(
+      catalog.tracks.map((track) => [track.name, track] as const),
+    );
+
+    for (let i = 0; i < catalog.tracks.length; i++) {
+      const track = catalog.tracks[i]!;
+      const role = resolvedRoles[i]!;
+
+      // D-17: Build altGroup → track-name index. A repair leg belongs to the
+      // switching set of the owner that points at it.
+      const altGroup = repairOwnerAltGroup.has(track.name)
+        ? repairOwnerAltGroup.get(track.name)
+        : track.altGroup;
+      if (altGroup !== undefined) {
+        const existing = this.#switchingSets.get(altGroup) ?? [];
+        existing.push(track.name);
+        this.#switchingSets.set(altGroup, existing);
+      }
+
+      // D-26: Register packetId → role on MmtpRouter (if packetId provided at ingest time).
+      if (track.packetId !== undefined) {
+        this.#router.setPacketIdRole(track.packetId, role);
+      }
+
+      if (role === "repair") {
+        // D-06: Repair track is the repair source — no FEC decoder registered on it.
+        if (track.packetId !== undefined) {
+          this.#repairPacketIds.add(track.packetId);
+        }
+        continue;
+      }
+
+      // D-07: Apply per-track FEC config for non-repair tracks.
+      if (track.fec !== undefined) {
+        const fecCfg = track.fec as FecCatalogConfig;
+        // Every repair layer and the keyframe overlay route to this source's
+        // decoder, not only layer 0. A layer whose packetId had no registered
+        // owner would have its repair symbols dropped as an unknown owner, and
+        // two sources whose RS_ID ranges overlap would be indistinguishable.
+        if (track.packetId !== undefined) {
+          for (const repairName of repairNamesBySource.get(track.name) ?? []) {
+            const repairTrack = catalogTracksByName.get(repairName);
+            if (repairTrack?.packetId !== undefined) {
+              this.#router.setRepairPacketIdOwner(repairTrack.packetId, track.packetId);
+            }
+          }
+        }
+        const wasmDecoder = fecDecoders.get(i);
+        if (track.packetId !== undefined && wasmDecoder !== undefined) {
+          // trackType: base/delta/single video tracks are 'video'; audio would be 'audio'.
+          // At this layer we treat all content tracks as 'video' — audio tracks typically
+          // have no FEC in Phase 14 (D-26 covers video base+delta only). Callers that need
+          // audio FEC can call setFecDecoder() directly after configureMultiTrack().
+          const blockProfile = parseFecBlockProfile(
+            (fecCfg as { blockProfile?: unknown }).blockProfile,
+            `tracks[${JSON.stringify(track.name)}].fec.blockProfile`,
+          );
+          this.#fec.setFecDecoder(
+            track.packetId,
+            wasmDecoder,
+            fecCfg.sourceSymbols,
+            {
+              blockProfile,
+              k: fecCfg.sourceSymbols,
+              symbolSize: fecCfg.symbolSize,
+              interleaveDepthMs: fecCfg.interleaveDepthMs,
+              fps: track.framerate,
+              trackKind: "video",
+            },
+            track.name,
+          );
+          this.#configureTrackMapper(track.packetId, {
+            blockProfile,
+            k: fecCfg.sourceSymbols,
+            symbolSize: fecCfg.symbolSize,
+            interleaveDepthMs: fecCfg.interleaveDepthMs,
+            fps: track.framerate,
+          });
+          this.#router.setPacketIdType(track.packetId, "video");
+        }
+      }
+    }
+  }
+
+  /**
+   * Return the track names belonging to the given altGroup switching set.
+   * D-17: altGroup groups base+delta+repair into one switching set.
+   *
+   * @param altGroup - The altGroup number to look up.
+   * @returns Array of track names in that switching set (empty if none).
+   */
+  getSwitchingSet(altGroup: number): string[] {
+    return this.#switchingSets.get(altGroup) ?? [];
+  }
+
+  /**
+   * Register callback fired when a repair fetch should be issued for an FEC block.
+   *
+   * D-28: At most one outstanding repair fetch per (packetId, sbn) block.
+   * clearRepairForBlock fires automatically when the block resolves (via
+   * FECManager.onRepairResolved); call it manually only on fetch failure
+   * paths the FEC layer cannot observe (fetch error, range not retained,
+   * transport timeout) so a stuck fetch cannot wedge the block's slot.
+   *
+   * Registering also arms the FEC repair deadline: each block gets a one-shot
+   * timer for the derived K-symbol source-production horizon; a block still
+   * short of K when it fires requests repair here. Failure accounting timing
+   * is unchanged.
+   */
+  onRepairSubscribe(cb: RepairSubscribeCallback): void {
+    this.#onRepairSubscribeCb = cb;
+    this.#fec.onRepairNeeded = (sbn, packetId, catalogTrackName, blockClass) => {
+      this.requestRepairForBlock(sbn, packetId, catalogTrackName, blockClass);
+    };
+  }
+
+  /**
+   * Record a repair request whose SUBSCRIBER_PRIORITY the catalog could not
+   * supply (draft-ramadan-moq-fec §11.4.5): sent without the parameter, or
+   * not sent. Emits one `repair-priority` lifecycle event.
+   */
+  noteRepairPriority(
+    action: "omitted" | "declined",
+    reason: RepairPriorityReason,
+    blockClass: BlockClass,
+    sbn: number,
+    packetId: number,
+    catalogTrackName?: string,
+  ): void {
+    this.#emitRepairLifecycle({
+      version: 2,
+      type: "repair-priority",
+      block: repairBlockIdentity(packetId, sbn, catalogTrackName),
+      blockClass,
+      action,
+      reason,
+    });
+  }
+
+  /** Record a repair request the scheduler sent no FETCH for. */
+  noteRepairSkipped(
+    reason: RepairSkipReason,
+    measurement: { readonly rttMs: number | null; readonly budgetMs: number },
+    sbn: number,
+    packetId: number,
+    catalogTrackName?: string,
+  ): void {
+    this.#statsFor(packetId, catalogTrackName).repairsSkipped++;
+    this.#emitRepairLifecycle({
+      version: 2,
+      type: "repair-skipped",
+      block: repairBlockIdentity(packetId, sbn, catalogTrackName),
+      reason,
+      rttMs: measurement.rttMs,
+      budgetMs: measurement.budgetMs,
+    });
+  }
+
+  /**
+   * Record a repair-scheduler decision about a delta block: preempted for
+   * keyframe/audio work, or never dispatched before its block resolved.
+   */
+  noteRepairScheduling(
+    type: "repair-preempted" | "repair-deferred",
+    sbn: number,
+    packetId: number,
+    catalogTrackName?: string,
+  ): void {
+    const stats = this.#statsFor(packetId, catalogTrackName);
+    if (type === "repair-preempted") stats.deltaRepairsPreempted++;
+    else stats.deltaRepairsDeferred++;
+    this.#emitRepairLifecycle({
+      version: 2,
+      type,
+      block: repairBlockIdentity(packetId, sbn, catalogTrackName),
+    });
+  }
+
+  /** Catalog/reset epoch of a packet's streams; gap decisions carry it. */
+  epochFor(packetId: number): number {
+    return this.#fec.epochFor(packetId);
+  }
+
+  /**
+   * Keyframe-protected repair policy counters, keyed by catalog track name
+   * (`packetId:<n>` for a stream with no catalog name). Each track's
+   * counters reset with its epoch.
+   */
+  getBlockPolicyStats(): Record<string, BlockPolicyStats> {
+    const out: Record<string, BlockPolicyStats> = {};
+    for (const [key, stats] of this.#blockPolicyStats) {
+      if (stats.epoch !== this.#fec.epochFor(stats.packetId)) continue;
+      out[key] = { ...stats };
+    }
+    return out;
+  }
+
+  #statsFor(packetId: number, catalogTrackName?: string): BlockPolicyStats {
+    const key = catalogTrackName ?? `packetId:${packetId}`;
+    const epoch = this.#fec.epochFor(packetId);
+    let stats = this.#blockPolicyStats.get(key);
+    if (!stats || stats.epoch !== epoch || stats.packetId !== packetId) {
+      stats = newBlockPolicyStats(packetId, catalogTrackName ?? null, epoch);
+      this.#blockPolicyStats.set(key, stats);
+    }
+    return stats;
+  }
+
+  /**
+   * Observe causal repair lifecycle events without retaining snapshots in the
+   * transport. Returns an unsubscribe function.
+   */
+  addRepairLifecycleObserver(observer: RepairLifecycleObserver): () => void {
+    this.#repairLifecycleObservers.add(observer);
+    return () => this.#repairLifecycleObservers.delete(observer);
+  }
+
+  /** Observe per-stream epoch resets (used by repair transports to abort I/O). */
+  addTrackResetObserver(
+    observer: (packetId: number, catalogTrackName: string) => void,
+  ): () => void {
+    this.#trackResetObservers.add(observer);
+    return () => this.#trackResetObservers.delete(observer);
+  }
+
+  /** Begin a fresh retained-replay epoch for one physical media stream. */
+  resetTrack(packetId: number, catalogTrackName: string): void {
+    if (!catalogTrackName) {
+      throw new Error('[MulticastManager] catalogTrackName is required for track reset');
+    }
+    this.#resetStreamOutsideRouter(packetId, catalogTrackName);
+    this.#router.resetTrack(packetId, catalogTrackName);
+  }
+
+  /** resetTrack() for everything but the router's own state. */
+  #resetStreamOutsideRouter(packetId: number, catalogTrackName: string): void {
+    for (const observer of this.#trackResetObservers) {
+      try {
+        observer(packetId, catalogTrackName);
+      } catch (error) {
+        console.warn('[MulticastManager] track reset observer failed', error);
+      }
+    }
+    for (const key of this.#repairInFlight) {
+      try {
+        const [keyPacketId, keyTrackName] = JSON.parse(key);
+        if (keyPacketId === packetId && keyTrackName === catalogTrackName) {
+          this.#repairInFlight.delete(key);
+        }
+      } catch {
+        // Internal keys are JSON tuples; preserve unknown legacy entries.
+      }
+    }
+    this.#fec.resetTrack(packetId, catalogTrackName);
+  }
+
+  /**
+   * Request a repair-track fetch for the given FEC block.
+   *
+   * D-28: duplicate requests for the same (packetId, sbn) are suppressed
+   * until clearRepairForBlock is called.
+   *
+   * @param sbn - Source Block Number identifying the FEC block needing repair.
+   * @param packetId - MMTP packet_id owning the block (video/audio tracks have
+   *   independent SBN spaces, so the in-flight key must be composite).
+   */
+  requestRepairForBlock(
+    sbn: number,
+    packetId: number,
+    catalogTrackName: string | undefined,
+    blockClass: BlockClass,
+  ): void {
+    // D-28: at most one outstanding fetch per FEC block (per packetId:sbn).
+    // Different blocks are independent and are NOT blocked by each other.
+    const block = repairBlockIdentity(packetId, sbn, catalogTrackName);
+    const key = JSON.stringify([packetId, block.catalogTrackName, sbn]);
+    if (this.#repairInFlight.has(key)) return;
+    this.#repairInFlight.add(key);
+    const stats = this.#statsFor(packetId, catalogTrackName);
+    if (blockClass === "keyframe") stats.keyframeBlocksProtected++;
+    else if (blockClass === "unknown") stats.unknownBlocksProtected++;
+    else if (blockClass === "delta") stats.deltaBlocksShort++;
+    this.#emitRepairLifecycle({
+      version: 2,
+      type: "requested",
+      block,
+      blockClass,
+      priority: repairPriorityForClass(blockClass),
+    });
+    this.#onRepairSubscribeCb?.(sbn, packetId, catalogTrackName, blockClass);
+  }
+
+  /**
+   * Clear in-flight repair state for the given block.
+   * Fired automatically when the block resolves; safe to call redundantly.
+   */
+  clearRepairForBlock(
+    sbn: number,
+    packetId: number,
+    catalogTrackName?: string,
+  ): void {
+    this.#repairInFlight.delete(
+      JSON.stringify([packetId, catalogTrackName ?? null, sbn]),
+    );
+  }
+
+  #emitRepairLifecycle(event: RepairLifecycleEvent): void {
+    // A gap decision is already frozen and is the same object the frame
+    // carries as gapBefore: forward it as is, never a copy.
+    const immutableEvent = event.type === "gap"
+      ? event
+      : (Object.freeze(
+          "stream" in event
+            ? { ...event, stream: Object.freeze({ ...event.stream }) }
+            : {
+                ...event,
+                block: Object.freeze({ ...event.block }),
+                ...("symbols" in event
+                  ? { symbols: Object.freeze({ ...event.symbols }) }
+                  : {}),
+              },
+        ) as RepairLifecycleEvent);
+    // Serialize before invoking observers so a re-entrant observer cannot log
+    // a resolution before the request that caused it.
+    if (this.#logRepairLifecycle) {
+      console.info(
+        `${REPAIR_LIFECYCLE_LOG_PREFIX}${JSON.stringify(immutableEvent)}`,
+      );
+    }
+    for (const observer of this.#repairLifecycleObservers) {
+      try {
+        observer(immutableEvent);
+      } catch (error) {
+        console.warn("[MulticastManager] repair lifecycle observer failed", error);
+      }
+    }
+  }
+
+  dispose() {
+    const staged = this.#renditionSwitch;
+    if (staged !== null) this.#endRenditionSwitch(staged, { reason: "superseded" }, false);
+    this.#trackResetObservers.clear();
+    this.#repairLifecycleObservers.clear();
+    this.#transport.dispose();
+    this.#router.dispose();
+    this.#fec.dispose();
+  }
+}
+
+// Compile-time contract: the manager is the host the D-28 repair scheduler
+// (wireRepairFetch) drives.
+const repairFetchHost = (manager: MulticastManager): RepairFetchHost => manager;
+void repairFetchHost;