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

package/src/track-session.ts

@@ -0,0 +1,778 @@
+/**
+ * TrackSession — per-track transport state machine.
+ * SessionManager — orchestrates all sessions + TransportPool.
+ *
+ * Implements Patent Claim 9 (draft-ramadan-moq-fec APPLICATION-1):
+ *   (a) subscribe unicast
+ *   (b) simultaneously join multicast
+ *   (c) render from unicast during join
+ *   (d) activate multicast on RAP, suppress unicast
+ *   (e) cross-transport FEC repair during transition
+ *   (f) hysteresis before switching away from multicast
+ *   (g) re-subscribe unicast on sustained failure
+ *
+ * PIM: manages transport state without inspecting packet contents.
+ */
+
+import {
+  TransportPool,
+  type Subscription,
+  type SubscriptionMode,
+  type AcquireOptions,
+  type DirectSocketHealth,
+  type TransportPoolOptions,
+} from './transport-pool.js'
+import { deriveFecInterleaveDepth } from '@blockcast/mmt-fec'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type TrackState =
+  | 'idle'
+  | 'unicast'
+  | 'unicast-fallback'
+  | 'joining'
+  | 'multicast'
+  | 'amt'
+  | 'failing'
+
+export interface TrackSessionConfig {
+  trackName: string
+  trackType: 'video' | 'audio'
+  packetId: number
+  /** FEC interleave depth from catalog (ms). Used for hysteresis timer. */
+  fecInterleaveMs: number
+  /** FEC K from catalog. Used for audio worklet latency calculation. */
+  fecK: number
+  /** FEC repair symbols per block (P). NOT symbol size. */
+  fecRepairCount: number
+  /** FEC symbol size in bytes (T). Required for WASM decoder OTI. */
+  fecSymbolSize: number
+  /** MoQ repair track name from catalog FEC config. */
+  repairTrackName?: string
+  /** Frame samples from initData parsing (audio-init-parser.ts). */
+  frameSamples?: number
+  /** Audio sample rate from catalog. */
+  sampleRate?: number
+  /** Ordered transport preference: best first. */
+  preferredTransports: SubscriptionMode[]
+  /** Subscription key for multicast/AMT: "(S,G,port)". */
+  multicastKey?: string
+  /** MoQ track name for unicast subscription. */
+  moqTrackName?: string
+  /** AMT relay address (if AMT is in preference chain). */
+  amtRelay?: string
+  /** MoQ relay URL (for WebTransport subscription). */
+  moqRelayUrl?: string
+}
+
+// ---------------------------------------------------------------------------
+// PIM callbacks (protocol-independent — transport state only)
+// ---------------------------------------------------------------------------
+
+export interface SessionManagerCallbacks {
+  /** Fired on every transport state transition. */
+  onStateChange?(trackName: string, from: TrackState, to: TrackState): void
+  /** Fired to suppress/unsuppress unicast for this track (transport arbitration). */
+  onSuppress?(trackName: string, suppressed: boolean): void
+  /**
+   * Fired when a track sat in `joining` for SessionManager.takeoverDeadlineMs
+   * without a RAP (BLO-9413/D9). The session has already returned to `unicast`
+   * (nothing was suppressed, so nothing to restore) — the host should abandon
+   * the multicast attempt (e.g. MediaRouter.failbackToMoq()) so the router
+   * stops waiting for a keyframe that is never coming.
+   */
+  onTakeoverTimeout?(trackName: string): void
+}
+
+// ---------------------------------------------------------------------------
+// MMTP application-layer extension (FEC lifecycle, media resets)
+// ---------------------------------------------------------------------------
+
+/**
+ * MMTP track events (discriminated union).
+ * Each protocol layer defines its own event union — MMTP events cover
+ * media resets, latency, and FEC lifecycle.
+ */
+export type MmtpTrackEvent =
+  | { type: 'reset' }
+  | { type: 'latency'; latencyMs: number }
+  | { type: 'fec-setup' }
+  | { type: 'fec-teardown' }
+
+/**
+ * MMTP application-layer extension of SessionManagerCallbacks.
+ * Single onTrackEvent dispatches all MMTP-specific events.
+ * PIM consumers use the base SessionManagerCallbacks (no onTrackEvent).
+ *
+ * IWA can define its own subinterface with its own TrackEvent union
+ * (e.g., IwaTrackEvent for socket health, AMT state) using the same pattern.
+ */
+export interface MmtpSessionCallbacks extends SessionManagerCallbacks {
+  onTrackEvent?(trackName: string, event: MmtpTrackEvent, config: TrackSessionConfig): void
+}
+
+/**
+ * Loss-hysteresis window covering the signaled interleave window plus jitter.
+ *
+ * This path lacks media cadence, so it intentionally does not estimate a full
+ * source-plus-repair production horizon. FECManager uses
+ * computeFecDeliveryWindowMs with media cadence when configuring block
+ * inactivity deadlines.
+ *
+ * `fecK` no longer feeds the math; it is still validated as a catalog
+ * well-formedness guard and kept in the signature for positional API compat
+ * (removal is a follow-up with the next cross-repo pin bump).
+ */
+export function computeFecLossWindowMs(fecInterleaveMs: number, fecK: number, jitterBufferMs?: number): number {
+  return computeFecDeliveryWindowMs({
+    interleaveDepthMs: fecInterleaveMs,
+    sourceSymbols: fecK,
+    jitterBufferMs,
+  })
+}
+
+export interface FecDeliveryWindowConfig {
+  interleaveDepthMs: number
+  sourceSymbols: number
+  repairSymbols?: number
+  symbolSize?: number
+  mediaUnitsPerSecond?: number
+  bandwidthBps?: number
+  /**
+   * Jitter + one-way-delay + reorder budget in ms (draft-ramadan-moq-fec §9),
+   * sourced from the catalog `jitterBufferMs`. Added on top of the max-of-spans
+   * core; it is NOT a multiplier. See the margin-policy note in the function.
+   */
+  jitterBufferMs?: number
+}
+
+/**
+ * Catalog-derived silence window that covers interleave geometry plus the time
+ * required to produce or serialize a complete source+repair block. The catalog
+ * field remains D media units; this function does not feed mapper geometry.
+ */
+export function computeFecDeliveryWindowMs(
+  config: FecDeliveryWindowConfig,
+): number {
+  const fecInterleaveMs = config.interleaveDepthMs
+  const fecK = config.sourceSymbols
+  if (fecInterleaveMs <= 0) {
+    throw new Error(
+      `[TrackSession] fecInterleaveMs=${fecInterleaveMs}. ` +
+      `Derive a positive FEC interleave window from the stream catalog.`
+    )
+  }
+  if (fecK <= 0) {
+    throw new Error(
+      `[TrackSession] fecK=${fecK}. ` +
+      `Derive a positive FEC source-symbol count from the stream catalog.`
+    )
+  }
+
+  const spansMs = [fecInterleaveMs]
+  if (config.mediaUnitsPerSecond && config.mediaUnitsPerSecond > 0) {
+    const mediaUnitMs = 1000 / config.mediaUnitsPerSecond
+    // interleaveDepthMs is integer catalog signaling while media-unit duration
+    // is often fractional (for example 4/30s = 133.33ms). Recover D using the
+    // producer's nearest-ms quantization, then cover every source and repair
+    // round-robin cycle. A decoder cannot recover a partial MFU until the
+    // repair tail arrives, so a K-only deadline expires the source fragments
+    // before the final repair symbols that complete them.
+    const interleaveUnits = deriveFecInterleaveDepth(fecInterleaveMs, mediaUnitMs)
+    const deliverySymbols = fecK + Math.max(0, config.repairSymbols ?? 0)
+    spansMs.push(deliverySymbols * interleaveUnits * mediaUnitMs)
+  }
+  if (
+    config.symbolSize &&
+    config.symbolSize > 0 &&
+    config.bandwidthBps &&
+    config.bandwidthBps > 0
+  ) {
+    const repairSymbols = Math.max(0, config.repairSymbols ?? 0)
+    spansMs.push(
+      ((fecK + repairSymbols) * config.symbolSize * 8 * 1000) /
+        config.bandwidthBps,
+    )
+  }
+
+  // draft-ramadan-moq-fec §9: the recovery timeout is a DERIVED budget —
+  // max(interleave span, source+repair production horizon, block serialization) PLUS
+  // an ADDITIVE margin for jitter + one-way delay + reorder. It MUST NOT be a
+  // fixed multiple of the interleave span (this replaces the retired `* 3` /
+  // `* 2` safety factors). The margin is the catalog `jitterBufferMs`.
+  //
+  // MARGIN-POLICY (operator sign-off — see PR): no catalog currently emits
+  // `jitterBufferMs`. Rather than throw (which would break every existing
+  // catalog) or invent a magic constant, the default margin is the un-rounded
+  // interleave window — the spec's natural reorder-budget bound and already a
+  // catalog value. Emit `jitterBufferMs` in the catalog to set it explicitly.
+  const coreMs = Math.max(...spansMs)
+  const marginMs =
+    config.jitterBufferMs !== undefined && config.jitterBufferMs >= 0
+      ? config.jitterBufferMs
+      : fecInterleaveMs
+  return Math.ceil(coreMs) + Math.ceil(marginMs)
+}
+
+/** Convert the shared FEC delivery deadline into an integer media timescale. */
+export function computeFecDeliveryWindowMediaUnits(
+  config: FecDeliveryWindowConfig,
+  timestampTimescale: number,
+): number {
+  if (!Number.isFinite(timestampTimescale) || timestampTimescale <= 0) {
+    throw new Error(
+      `[TrackSession] timestampTimescale=${timestampTimescale}. ` +
+      'Derive a positive media timescale from the container.',
+    )
+  }
+  const deliveryWindow = Math.ceil(
+    computeFecDeliveryWindowMs(config) * timestampTimescale / 1000,
+  )
+  if (!Number.isSafeInteger(deliveryWindow)) {
+    throw new Error('[TrackSession] FEC delivery window exceeds the media timestamp range.')
+  }
+  return deliveryWindow
+}
+
+// ---------------------------------------------------------------------------
+// TrackSession
+// ---------------------------------------------------------------------------
+
+export class TrackSession {
+  readonly config: TrackSessionConfig
+  #state: TrackState = 'idle'
+  #subscription: Subscription | null = null
+  #hysteresisTimer: ReturnType<typeof setTimeout> | null = null
+  #joinDeadlineTimer: ReturnType<typeof setTimeout> | null = null
+  #previousPrimary: SubscriptionMode | null = null
+  #manager: SessionManager
+  // Single suppression authority flag (BLO-9413 failback coherence): every
+  // suppress this session fires is recorded here, and every path that leaves
+  // a suppressed state unwinds through #unsuppress(). Before this flag,
+  // unsubscribe() only un-suppressed from multicast/amt — a session torn down
+  // from `failing` (exactly where a starving track sits) was re-subscribed to
+  // unicast with the host's media still muted: MoQ playing into a dead sink.
+  #suppressFired = false
+
+  constructor(config: TrackSessionConfig, manager: SessionManager) {
+    this.config = config
+    this.#manager = manager
+  }
+
+  // -----------------------------------------------------------------------
+  // State
+  // -----------------------------------------------------------------------
+
+  get state(): TrackState { return this.#state }
+  get subscription(): Subscription | null { return this.#subscription }
+
+  /** True while this session's onSuppress(true) is outstanding (no matching
+   *  onSuppress(false) yet). Test/assertion surface for failback coherence. */
+  get isSuppressed(): boolean { return this.#suppressFired }
+
+  /** Current active transport mode, or null if idle. */
+  get transport(): SubscriptionMode | null {
+    switch (this.#state) {
+      case 'multicast': return 'multicast'
+      case 'amt': return 'amt'
+      case 'unicast': return 'moq'
+      case 'unicast-fallback': return 'moq' // SSM bridge absent — MoQ unicast is the only source
+      case 'joining': return 'moq' // MoQ still primary during join
+      case 'failing': return this.#previousPrimary
+      default: return null
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // Computed (no magic numbers)
+  // -----------------------------------------------------------------------
+
+  /** Audio worklet latency: max(fecInterleaveMs, frameDurationMs * fecK).
+   *  Returns undefined if frame duration unknown (no initData). */
+  get audioLatencyMs(): number | undefined {
+    const fd = this.frameDurationMs
+    if (fd === undefined) {
+      return this.config.fecInterleaveMs > 0 ? this.config.fecInterleaveMs : undefined
+    }
+    return Math.max(this.config.fecInterleaveMs, fd * this.config.fecK)
+  }
+
+  /** Frame duration in ms, derived from frameSamples + sampleRate. */
+  get frameDurationMs(): number | undefined {
+    const { frameSamples, sampleRate } = this.config
+    if (!frameSamples || !sampleRate || sampleRate <= 0) return undefined
+    return (frameSamples / sampleRate) * 1000
+  }
+
+  // -----------------------------------------------------------------------
+  // Transitions (Patent Claim 9)
+  // -----------------------------------------------------------------------
+
+  /** idle → unicast: player subscribes to this track. */
+  subscribe(): void {
+    if (this.#state !== 'idle') return
+    this.#transition('unicast')
+
+    // Emit audio latency on first subscribe
+    if (this.config.trackType === 'audio') {
+      const latency = this.audioLatencyMs
+      if (latency !== undefined) {
+        this.#manager.mmtp?.onTrackEvent?.(this.config.trackName, { type: 'latency', latencyMs: latency }, this.config)
+      }
+    }
+  }
+
+  /** unicast → joining: multicast/AMT capability detected, join in progress. */
+  joinStarted(): void {
+    if (this.#state !== 'unicast') return
+    this.#transition('joining')
+    // FEC decoders must be ready before multicast data arrives (Claim 9e: cross-transport repair)
+    this.#manager.mmtp?.onTrackEvent?.(this.config.trackName, { type: 'fec-setup' }, this.config)
+  }
+
+  /**
+   * any non-fallback state → unicast-fallback. Used when the SSM bridge is
+   * absent (vanilla Chromium / no extension) and the host falls back to a
+   * MoQ unicast subscription per track. Terminal-ish: activateMulticast,
+   * failbackAll, and transportFailed are no-ops while in this state.
+   *
+   * Fires fec-setup so the per-track repair worker spins up — repair packets
+   * still flow over the MoQ repair-track subscription, so FEC source+repair
+   * can converge as in the multicast path.
+   *
+   * Audio latency is NOT re-emitted here: subscribe() already fires latency
+   * once on the idle → unicast edge, and enterUnicastFallback is only ever
+   * reached from a non-idle state (SessionManager skips idle sessions).
+   */
+  enterUnicastFallback(): void {
+    if (this.#state === 'unicast-fallback') return
+    this.#clearHysteresis()
+    this.#transition('unicast-fallback')
+    // Suppress the redundant unicast media decoder. On the no-bridge path the
+    // host feeds MoQ-unicast source packets into MulticastManager (the render
+    // consumer); a second base-media subscribe (the @moq/watch decoder) would
+    // split the single connection's QUIC flow-control budget and stall delivery
+    // (BLO-8969). Fire suppress here, on the fallback edge, so the decoder is
+    // gated off before it subscribes rather than after the relay forward task
+    // has already wedged.
+    this.#suppress()
+    this.#manager.mmtp?.onTrackEvent?.(this.config.trackName, { type: 'fec-setup' }, this.config)
+  }
+
+  /**
+   * unicast-fallback → unicast. Called when the SSM bridge appears mid-session
+   * (extension installed after fallback engaged). Host first aborts the fallback
+   * drainers, then transitions sessions back to unicast so the regular
+   * multicast/AMT preference chain can take over via joinStarted().
+   */
+  exitUnicastFallback(): void {
+    if (this.#state !== 'unicast-fallback') return
+    this.#transition('unicast')
+    // Un-suppress the unicast decoder: the bridge appeared mid-session, so the
+    // host tears down the fallback drainers and the regular preference chain
+    // (joinStarted -> joining -> rapReceived) will re-suppress on multicast RAP.
+    this.#unsuppress()
+  }
+
+  /**
+   * joining → multicast or amt: RAP received on the joined transport (Claim 9d).
+   * Resets audio worklet, then suppresses MoQ.
+   */
+  rapReceived(mode: 'multicast' | 'amt'): void {
+    if (this.#state !== 'joining') return
+    this.#previousPrimary = mode
+    this.#transition(mode)
+    if (this.config.trackType === 'audio') {
+      this.#manager.mmtp?.onTrackEvent?.(this.config.trackName, { type: 'reset' }, this.config)
+    }
+    this.#suppress()
+  }
+
+  /** multicast/amt → failing: loss detected, start hysteresis timer (Claim 9f). */
+  lossDetected(): void {
+    if (this.#state !== 'multicast' && this.#state !== 'amt') return
+    this.#previousPrimary = this.#state as SubscriptionMode
+    this.#transition('failing')
+
+    // Hysteresis timer: sustained loss before failback (Claim 9f). The window
+    // covers a complete FEC block plus safety margin: the catalog interleave
+    // value IS the block span (interleaveDepthMs, §5.1), scaled by the same
+    // safety factor FECManager uses for its block timeout.
+    const hysteresisMs = computeFecLossWindowMs(this.config.fecInterleaveMs, this.config.fecK)
+    this.#hysteresisTimer = setTimeout(() => {
+      this.hysteresisExpired()
+    }, hysteresisMs)
+  }
+
+  /** failing → previous primary: loss recovered within hysteresis window. */
+  lossRecovered(): void {
+    if (this.#state !== 'failing') return
+    this.#clearHysteresis()
+    if (this.#previousPrimary) {
+      this.#transition(this.#previousPrimary as TrackState)
+    }
+  }
+
+  /**
+   * Transport failed (AMT relay down, multicast interface gone).
+   * Try next transport in preference chain.
+   */
+  transportFailed(): void {
+    this.#clearHysteresis()
+    // Unicast-fallback is terminal — the host owns the subscription and
+    // SessionManager transport machinery does not arbitrate it.
+    if (this.#state === 'unicast-fallback') return
+    const current = this.#previousPrimary ?? this.transport
+    const prefs = this.config.preferredTransports
+    const currentIdx = current ? prefs.indexOf(current) : -1
+    const nextMode = prefs[currentIdx + 1]
+
+    if (nextMode) {
+      // Failover to next in chain
+      if (nextMode === 'moq') {
+        this.#transition('unicast')
+        this.#unsuppress()
+        if (this.config.trackType === 'audio') {
+          this.#manager.mmtp?.onTrackEvent?.(this.config.trackName, { type: 'reset' }, this.config)
+        }
+      } else {
+        // Next is multicast or AMT — start joining. `joining` means MoQ is
+        // primary again (see transport getter) — if the failed transport had
+        // suppressed unicast, restore it for the join window or the viewer
+        // watches black video until the next RAP (which may never come).
+        this.#transition('joining')
+        this.#unsuppress()
+      }
+    } else {
+      // End of chain — fall back to unicast (Claim 9g)
+      this.#transition('unicast')
+      this.#unsuppress()
+      if (this.config.trackType === 'audio') {
+        this.#manager.mmtp?.onTrackEvent?.(this.config.trackName, { type: 'reset' }, this.config)
+      }
+    }
+  }
+
+  /** Hysteresis expired → failback to next transport (Claim 9g). */
+  hysteresisExpired(): void {
+    if (this.#state !== 'failing') return
+    this.#clearHysteresis()
+    this.transportFailed()
+  }
+
+  /** → idle: player unsubscribes / tab close / cleanup. */
+  unsubscribe(): void {
+    this.#clearHysteresis()
+    if (this.#state !== 'idle') {
+      this.#transition('idle')
+      // Unwind any outstanding suppression regardless of which state we left.
+      // The old `wasActive` check (multicast/amt only) leaked suppression when
+      // tearing down from `failing` or `unicast-fallback` — failbackAll()'s
+      // unsubscribe→subscribe cycle then re-entered unicast with the host's
+      // media still muted (BLO-9413 freeze: "failing back" logged, video dead).
+      this.#unsuppress()
+    }
+  }
+
+  /** True when SessionManager.enterUnicastFallback put this track into the
+   *  host-driven unicast subscription mode. Host can iterate sessions to
+   *  decide whether to keep its fallback drainer alive across MediaRouter
+   *  arbitration events. */
+  get isUnicastFallback(): boolean {
+    return this.#state === 'unicast-fallback'
+  }
+
+  dispose(): void {
+    this.#clearHysteresis()
+    this.#clearJoinDeadline()
+    this.#state = 'idle'
+    this.#subscription = null
+  }
+
+  // -----------------------------------------------------------------------
+  // Internal
+  // -----------------------------------------------------------------------
+
+  #transition(to: TrackState): void {
+    const from = this.#state
+    if (from === to) return
+    this.#state = to
+    // Takeover deadline (BLO-9413/D9): every entry into `joining` arms it
+    // (joinStarted AND transportFailed-failover both route through here);
+    // every exit cancels it. Without this, a transport that accepts the
+    // subscribe but never delivers a RAP parks the session in `joining`
+    // forever (observed live in the Phase-0 headless repro).
+    if (from === 'joining') this.#clearJoinDeadline()
+    if (to === 'joining') this.#armJoinDeadline()
+    // FEC teardown: leaving FEC-active states → non-FEC state
+    const fecActive = (s: TrackState) =>
+      s === 'joining' ||
+      s === 'multicast' ||
+      s === 'amt' ||
+      s === 'failing' ||
+      s === 'unicast-fallback'
+    if (fecActive(from) && !fecActive(to)) {
+      this.#manager.mmtp?.onTrackEvent?.(this.config.trackName, { type: 'fec-teardown' }, this.config)
+    }
+    this.#manager.callbacks?.onStateChange?.(this.config.trackName, from, to)
+  }
+
+  #clearHysteresis(): void {
+    if (this.#hysteresisTimer !== null) {
+      clearTimeout(this.#hysteresisTimer)
+      this.#hysteresisTimer = null
+    }
+  }
+
+  #armJoinDeadline(): void {
+    this.#clearJoinDeadline()
+    const deadlineMs = this.#manager.takeoverDeadlineMs
+    if (deadlineMs <= 0) return // disabled
+    this.#joinDeadlineTimer = setTimeout(() => {
+      this.#joinDeadlineTimer = null
+      if (this.#state !== 'joining') return
+      // No RAP within the deadline: return to unicast. MoQ was never
+      // suppressed in `joining`, so there is nothing to restore — this edge
+      // must stay silent on onSuppress (asserted in tests).
+      this.#transition('unicast')
+      this.#manager.callbacks?.onTakeoverTimeout?.(this.config.trackName)
+    }, deadlineMs)
+  }
+
+  #clearJoinDeadline(): void {
+    if (this.#joinDeadlineTimer !== null) {
+      clearTimeout(this.#joinDeadlineTimer)
+      this.#joinDeadlineTimer = null
+    }
+  }
+
+  /** Fire onSuppress(true) exactly once per suppression epoch. */
+  #suppress(): void {
+    if (this.#suppressFired) return
+    this.#suppressFired = true
+    this.#manager.callbacks?.onSuppress?.(this.config.trackName, true)
+  }
+
+  /** Unwind an outstanding suppression; no-op when none is outstanding. */
+  #unsuppress(): void {
+    if (!this.#suppressFired) return
+    this.#suppressFired = false
+    this.#manager.callbacks?.onSuppress?.(this.config.trackName, false)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// SessionManager
+// ---------------------------------------------------------------------------
+
+export class SessionManager {
+  readonly pool: TransportPool
+  readonly sessions = new Map<string, TrackSession>()
+  callbacks: SessionManagerCallbacks | null = null
+  /**
+   * Takeover deadline (BLO-9413/D9): max time a session may sit in `joining`
+   * without a RAP before returning to `unicast` and firing onTakeoverTimeout.
+   * MoQ is never suppressed during `joining`, so expiry is a silent abandon —
+   * playback never glitches. Hosts tune per stream (e.g. GOP length); 0
+   * disables.
+   */
+  takeoverDeadlineMs = 5000
+
+  /** Narrow to MMTP callbacks (onTrackEvent). Safe — optional chaining handles PIM-only consumers. */
+  get mmtp(): MmtpSessionCallbacks | null {
+    return this.callbacks as MmtpSessionCallbacks | null
+  }
+
+  constructor(poolOptions?: TransportPoolOptions) {
+    this.pool = new TransportPool(poolOptions)
+
+    // Wire pool failure → per-track failover
+    this.pool.onSubscriptionFailed(sub => {
+      for (const trackName of sub.consumers) {
+        const session = this.sessions.get(trackName)
+        if (session) session.transportFailed()
+      }
+    })
+  }
+
+  // -----------------------------------------------------------------------
+  // Track management
+  // -----------------------------------------------------------------------
+
+  /** Add a track session from catalog config. */
+  addTrack(config: TrackSessionConfig): TrackSession {
+    if (this.sessions.has(config.trackName)) {
+      throw new Error(`[SessionManager] Track "${config.trackName}" already exists`)
+    }
+    const session = new TrackSession(config, this)
+    this.sessions.set(config.trackName, session)
+    return session
+  }
+
+  /** Remove a track session. Releases subscription with grace period. */
+  removeTrack(trackName: string): void {
+    const session = this.sessions.get(trackName)
+    if (!session) return
+    session.unsubscribe()
+
+    // Release pool subscription
+    const subKey = session.config.multicastKey ?? session.config.moqTrackName
+    if (subKey) this.pool.releaseSubscription(subKey, trackName)
+
+    session.dispose()
+    this.sessions.delete(trackName)
+  }
+
+  // -----------------------------------------------------------------------
+  // Atomic multi-track operations
+  // -----------------------------------------------------------------------
+
+  /**
+   * All tracks with multicast RAP → multicast state (atomic).
+   * Called when MediaRouter fires onSourceSwitch('multicast').
+   * Prevents split-brain between video and audio.
+   *
+   * A takeover deadline can return a track from `joining` to `unicast` while
+   * the multicast socket keeps delivering packets. If a valid RAP arrives
+   * later, allow that late-RAP edge to suppress unicast and promote multicast.
+   */
+  activateMulticast(): void {
+    for (const [, session] of this.sessions) {
+      if (session.state === 'unicast') {
+        session.joinStarted()
+      }
+      if (session.state === 'joining') {
+        session.rapReceived('multicast')
+      }
+    }
+  }
+
+  /**
+   * All tracks with AMT RAP → amt state (atomic).
+   */
+  activateAmt(): void {
+    for (const [, session] of this.sessions) {
+      if (session.state === 'unicast') {
+        session.joinStarted()
+      }
+      if (session.state === 'joining') {
+        session.rapReceived('amt')
+      }
+    }
+  }
+
+  /**
+   * All tracks → unicast (failback, atomic).
+   * Called when MulticastManager fires onFailback().
+   * unicast-fallback sessions are skipped — the host owns those subscriptions
+   * and they must drain uninterrupted across transport-state events.
+   *
+   * Coherence invariant (BLO-9413): after this returns, every non-fallback
+   * session is `unicast` (or `idle`) AND unsuppressed — unsubscribe() unwinds
+   * any outstanding suppression regardless of the state it tears down from
+   * (`failing` included; see TrackSession.#suppressFired).
+   */
+  failbackAll(): void {
+    for (const [, session] of this.sessions) {
+      if (
+        session.state !== 'idle' &&
+        session.state !== 'unicast' &&
+        session.state !== 'unicast-fallback'
+      ) {
+        session.unsubscribe()
+        session.subscribe() // re-enter unicast
+      }
+    }
+  }
+
+  /**
+   * All tracks → unicast-fallback (atomic).
+   * Called by the host when the multicast gateway is absent and
+   * the player will subscribe to source tracks over MoQ unicast and feed
+   * packets via MulticastManager.feedUnicastSource() (or manager.router
+   * directly). Sessions in this state stay terminal until the host calls
+   * unsubscribe() / disposes the SessionManager.
+   */
+  enterUnicastFallback(): void {
+    for (const [, session] of this.sessions) {
+      if (session.state === 'idle') continue
+      session.enterUnicastFallback()
+    }
+  }
+
+  /**
+   * True if any session is currently in unicast-fallback. Hosts use this to
+   * gate `multicastTrack.close()` on failback events — closing the shared
+   * broadcast would kill the host's fallback drainers.
+   */
+  hasActiveFallback(): boolean {
+    for (const [, session] of this.sessions) {
+      if (session.isUnicastFallback) return true
+    }
+    return false
+  }
+
+  /**
+   * All fallback tracks → unicast (atomic).
+   * Called when the SSM bridge appears mid-session and the host has aborted
+   * the fallback drainers. The session re-enters the regular preference chain
+   * via joinStarted() (issued by the host immediately after).
+   */
+  exitUnicastFallback(): void {
+    for (const [, session] of this.sessions) {
+      if (session.isUnicastFallback) session.exitUnicastFallback()
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // Cleanup lifecycle
+  // -----------------------------------------------------------------------
+
+  /** Tab closed — release all subscriptions for this tab (grace period). */
+  tabClosed(tabId: string): void {
+    // All tracks owned by this tab → idle
+    for (const [trackName, session] of this.sessions) {
+      session.unsubscribe()
+      this.pool.releaseAllForConsumer(trackName)
+    }
+  }
+
+  /** Bridge WebTransport connection dropped — same as tab close. */
+  bridgeDisconnected(): void {
+    this.tabClosed('bridge')
+  }
+
+  /**
+   * Track selection changed (user or ABR).
+   * Old track released (grace period), new track subscribed.
+   */
+  trackSelectionChanged(oldTrackName: string, newConfig: TrackSessionConfig): void {
+    this.removeTrack(oldTrackName)
+    const session = this.addTrack(newConfig)
+    session.subscribe()
+  }
+
+  // -----------------------------------------------------------------------
+  // Query
+  // -----------------------------------------------------------------------
+
+  /** Get a track session by name. */
+  getTrack(trackName: string): TrackSession | undefined {
+    return this.sessions.get(trackName)
+  }
+
+  // -----------------------------------------------------------------------
+  // Cleanup
+  // -----------------------------------------------------------------------
+
+  dispose(): void {
+    for (const [, session] of this.sessions) {
+      session.dispose()
+    }
+    this.sessions.clear()
+    this.pool.dispose()
+    this.callbacks = null
+  }
+}