@blockcast/mmt-container 0.1.0-main.0399efef1f07

package/src/multicast-manager.ts

@@ -0,0 +1,1720 @@
+/**
+ * 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 {
+  FECManager,
+  MIN_INTERLEAVE_DEPTH_MS,
+  type FECManagerConfig,
+  type WasmFecDecoder,
+  type FecDecoderUnavailableReason,
+  type FecFallbackDecoder,
+} from "./fec-manager.js";
+import {
+  MmtpRouter,
+  type FrameCallback,
+  type ManifestIdentityResolver,
+  type MmtpIngressContext,
+  type TrackPacketCallback,
+} from "./mmtp-router.js";
+import { MulticastTransport } from "./multicast-transport.js";
+import { computeFecDeliveryWindowMs } from "./track-session.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. */
+  amtRelay?: string;
+  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"];
+  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;
+  /** 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;
+}
+
+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;
+}
+
+export type RepairLifecycleEvent =
+  | {
+      readonly version: 1;
+      readonly type: "requested";
+      readonly block: RepairBlockIdentity;
+    }
+  | {
+      readonly version: 1;
+      readonly type: "recovered" | "failed";
+      readonly block: RepairBlockIdentity;
+      readonly symbols: {
+        readonly multicast: number;
+        readonly moq: number;
+      };
+    }
+  | {
+      readonly version: 1;
+      /**
+       * 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;
+    };
+
+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";
+}
+
+/** Runtime guard for observer, DOM-event, and cross-realm consumers. */
+export function isRepairLifecycleEvent(
+  value: unknown,
+): value is RepairLifecycleEvent {
+  if (!isRecord(value)) return false;
+  const version = value["version"];
+  const type = value["type"];
+  const block = value["block"];
+  const symbols = value["symbols"];
+  if (version !== 1) return false;
+  if (type === "decoder-unavailable") {
+    return (
+      isRepairStreamIdentity(value["stream"]) &&
+      isDecoderUnavailableReason(value["reason"]) &&
+      isFecFallbackDecoder(value["fallbackDecoder"]) &&
+      block === undefined &&
+      symbols === undefined
+    );
+  }
+  if (
+    (type !== "requested" && type !== "recovered" && type !== "failed") ||
+    !isRepairBlockIdentity(block) ||
+    value["stream"] !== undefined ||
+    value["reason"] !== undefined ||
+    value["fallbackDecoder"] !== undefined
+  ) {
+    return false;
+  }
+  if (type === "requested") return symbols === undefined;
+  if (!isRecord(symbols)) return false;
+  const multicast = symbols["multicast"];
+  const moq = symbols["moq"];
+  return (
+    Number.isSafeInteger(multicast) &&
+    (multicast as number) >= 0 &&
+    Number.isSafeInteger(moq) &&
+    (moq as number) >= 0
+  );
+}
+
+/**
+ * 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,
+      greenFillFrames: stats.greenFillFrames,
+      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>();
+
+  #trackResetObservers = new Set<
+    (packetId: number, catalogTrackName: string) => void
+  >();
+
+  /** Callback fired when a repair fetch should be issued for a block. */
+  #onRepairSubscribeCb:
+    | ((sbn: number, packetId: number, catalogTrackName?: string) => void)
+    | null = null;
+
+  constructor(options?: MulticastManagerOptions) {
+    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,
+      onBlockFailed: (sbn, packetId, catalogTrackName) => {
+        const pathCount = this.#fec.blockPathCount(
+          sbn,
+          packetId,
+          catalogTrackName,
+        );
+        this.#emitRepairLifecycle({
+          version: 1,
+          type: "failed",
+          block: repairBlockIdentity(packetId, sbn, catalogTrackName),
+          symbols: {
+            multicast: pathCount?.multicastSymbols ?? 0,
+            moq: pathCount?.moqSymbols ?? 0,
+          },
+        });
+      },
+    });
+    this.#transport = new MulticastTransport<MmtpIngressContext>((packet, ingress) => {
+      this.#router.feedPacket(packet, "multicast", undefined, ingress);
+    });
+
+    // 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);
+      if (outcome === "failed") return;
+      const pathCount = this.#fec.blockPathCount(
+        sbn,
+        packetId,
+        catalogTrackName,
+      );
+      const multicastSymbols = pathCount?.multicastSymbols ?? 0;
+      const moqSymbols = pathCount?.moqSymbols ?? 0;
+      this.#emitRepairLifecycle({
+        version: 1,
+        type: "recovered",
+        block: repairBlockIdentity(packetId, sbn, catalogTrackName),
+        symbols: {
+          multicast: multicastSymbols,
+          moq: moqSymbols,
+        },
+      });
+    };
+    this.#fec.onDecoderUnavailable = (event) => {
+      this.#emitRepairLifecycle({
+        version: 1,
+        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 {
+    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;
+  }
+
+  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 };
+    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, 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;
+    if (k && k > 0 && interleaveMs && interleaveMs > 0 && fps && fps > 0) {
+      this.#router.setFecMapper(
+        new FecBlockMapper({
+          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.
+   */
+  configureTrackFec(
+    packetId: number,
+    config: Pick<
+      MulticastEndpointConfig,
+      | "fecK"
+      | "fecRepairSymbols"
+      | "fecSymbolSize"
+      | "fecInterleaveDepthMs"
+      | "fecReorderToleranceMs"
+      | "fps"
+      | "bandwidth"
+      | "minimumFailbackWindowMs"
+    >,
+  ): void {
+    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.",
+      );
+    }
+    assertPositiveGeometry("fecK", config.fecK);
+    assertPositiveGeometry("fecInterleaveDepthMs", config.fecInterleaveDepthMs);
+    assertPositiveGeometry("fecSymbolSize", config.fecSymbolSize);
+    assertPositiveGeometry("fps", config.fps);
+    assertPositiveGeometry("bandwidth", config.bandwidth);
+    assertPositiveGeometry(
+      "minimumFailbackWindowMs",
+      config.minimumFailbackWindowMs,
+    );
+    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;
+
+    const fecConfig: FECManagerConfig = {
+      k: config.fecK,
+      symbolSize: config.fecSymbolSize,
+      interleaveDepthMs: config.fecInterleaveDepthMs,
+      fps: config.fps,
+      timeoutMs: deliveryWindowMs,
+    };
+    this.#fec.configureTrack(packetId, fecConfig);
+    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,
+      | "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;
+    if (k && k > 0 && interleaveMs && interleaveMs > 0 && fps && fps > 0) {
+      const mapper = new FecBlockMapper({
+        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.
+   * Must be called BEFORE setPacketIdType('video').
+   * Derive from explicit keyframe/group duration:
+   * Math.ceil(groupDurationMs * KEYFRAME_LOST_TIMEOUT_SLACK).
+   */
+  setKeyframeLostTimeoutMs(ms: number): void {
+    this.#router.setKeyframeLostTimeoutMs(ms);
+  }
+
+  setMfuTimeoutMs(ms: number): void {
+    this.#router.setMfuTimeoutMs(ms);
+  }
+
+  setTrackCodec(packetId: number, codec: string) {
+    this.#router.setTrackCodec(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: () => void) {
+    this.#transport.onFailback(cb);
+  }
+  confirmVideo() {
+    this.#transport.confirmVideo();
+  }
+  confirmAudio() {
+    this.#transport.confirmAudio();
+  }
+
+  static isAvailable(): boolean {
+    return MulticastTransport.isAvailable();
+  }
+
+  async join(config: MulticastEndpointConfig): Promise<boolean> {
+    // 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 }),
+            ),
+          ),
+        };
+    const transportConfig = {
+      sourceAddress: config.sourceAddress,
+      groupAddress: config.groupAddress,
+      port: config.port,
+      mode: config.mode,
+      amtRelay: config.amtRelay ?? config.relayAddress,
+      amtRelayPort: config.amtRelayPort ?? config.relayPort,
+      packetIds: config.packetIds,
+      tracks: catalogTracks?.map(({ name, packetId }) => ({ name, packetId })),
+    };
+    return ingress === undefined
+      ? this.#transport.join(transportConfig)
+      : this.#transport.join(transportConfig, ingress);
+  }
+
+  /** 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);
+  }
+
+  /** 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().
+          this.#fec.setFecDecoder(
+            track.packetId,
+            wasmDecoder,
+            fecCfg.sourceSymbols,
+            {
+              k: fecCfg.sourceSymbols,
+              symbolSize: fecCfg.symbolSize,
+              interleaveDepthMs: fecCfg.interleaveDepthMs,
+              fps: track.framerate,
+            },
+            track.name,
+          );
+          this.#configureTrackMapper(track.packetId, {
+            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: (sbn: number, packetId: number, catalogTrackName?: string) => void,
+  ): void {
+    this.#onRepairSubscribeCb = cb;
+    this.#fec.onRepairNeeded = (sbn, packetId, catalogTrackName) => {
+      this.requestRepairForBlock(sbn, packetId, catalogTrackName);
+    };
+  }
+
+  /**
+   * 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');
+    }
+    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);
+    this.#router.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,
+  ): 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);
+    this.#emitRepairLifecycle({
+      version: 1,
+      type: "requested",
+      block,
+    });
+    if (catalogTrackName === undefined) {
+      this.#onRepairSubscribeCb?.(sbn, packetId);
+    } else {
+      this.#onRepairSubscribeCb?.(sbn, packetId, catalogTrackName);
+    }
+  }
+
+  /**
+   * 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 {
+    const immutableEvent = Object.freeze(
+      event.type === "decoder-unavailable"
+        ? {...event, stream: Object.freeze({...event.stream})}
+        : {
+            ...event,
+            block: Object.freeze({...event.block}),
+            ...(event.type === "requested"
+              ? {}
+              : {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.
+    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() {
+    this.#trackResetObservers.clear();
+    this.#repairLifecycleObservers.clear();
+    this.#transport.dispose();
+    this.#router.dispose();
+    this.#fec.dispose();
+  }
+}