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

package/src/track-session.ts

@@ -0,0 +1,994 @@
+/**
+ * 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 { fecBlockBudgetMs } 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
+  /** Explicit catalog jitter/reorder allowance in ms. */
+  fecReorderToleranceMs?: number
+  /** FEC K from catalog. Used for audio worklet latency calculation. */
+  fecK: number
+  /** FEC repair symbols per block (P). NOT symbol size. */
+  fecRepairCount: number
+  /**
+   * Repair symbols per block this receiver actually joined: the sum of
+   * `repairSymbols` over the joined BASE layers, not a count of layers
+   * (draft-ramadan-moq-fec 6.3). A keyframe overlay is a separate FEC instance
+   * and is not included.
+   *
+   * This is runtime join state, not catalog geometry: a receiver on a clean
+   * path joins layer 0 only while a lossy one adds layers, so the catalog's
+   * total P is not what this receiver is receiving. Diagnostics that report P
+   * (the worker snapshot, CMCD `x-bc-fec-p`) must read this.
+   *
+   * Absent when the caller joins no layers explicitly, in which case P_0 is
+   * what was joined. That is an identity on a single-layer track, not a
+   * catalog default: with one layer, P_0 is the total.
+   */
+  joinedRepairCount?: 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) and it keeps its FEC
+   * decoder armed, because the multicast socket is still joined and the router
+   * still admits the stream's symbols. The host should abandon the router-side
+   * attempt (e.g. MediaRouter.failbackToMoq()) so the router stops waiting for
+   * a keyframe that is never coming; it must not dispose the decoder here. The
+   * decoder is released on the next transport edge (unsubscribe, failbackAll,
+   * or transportFailed falling back to unicast) through fec-teardown.
+   */
+  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 FEC block span plus jitter.
+ *
+ * `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
+  /**
+   * Explicit jitter/reorder allowance in ms, added once to the complete span.
+   * Callers pass their signaled catalog allowance, never a local default.
+   */
+  jitterBufferMs?: number
+}
+
+/**
+ * The catalog interleaveDepthMs is the complete FEC block span, including the
+ * repair tail. K, P, cadence, and bandwidth must not expand it again. Geometry
+ * fields remain accepted for existing callers, but do not feed deadline math.
+ */
+export function computeFecDeliveryWindowMs(
+  config: FecDeliveryWindowConfig,
+): number {
+  const fecInterleaveMs = config.interleaveDepthMs
+  const fecK = config.sourceSymbols
+  if (!Number.isFinite(fecInterleaveMs) || fecInterleaveMs <= 0) {
+    throw new Error(
+      `[TrackSession] fecInterleaveMs=${fecInterleaveMs}. ` +
+      `Derive a positive FEC interleave window from the stream catalog.`
+    )
+  }
+  if (!Number.isFinite(fecK) || fecK <= 0) {
+    throw new Error(
+      `[TrackSession] fecK=${fecK}. ` +
+      `Derive a positive FEC source-symbol count from the stream catalog.`
+    )
+  }
+
+  // Absence stays absent; it does not authorize a synthesized reorder budget.
+  if (config.jitterBufferMs === undefined) return Math.ceil(fecInterleaveMs)
+  return fecBlockBudgetMs(fecInterleaveMs, config.jitterBufferMs)
+}
+
+/** 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
+  // Single FEC authority flag: set by the fec-setup edges (joinStarted,
+  // enterUnicastFallback), cleared by the fec-teardown edge in #transition.
+  // Setup and teardown are paired by construction, so a takeover timeout that
+  // parks the session in `unicast` keeps the decoder the still-joined
+  // transport is feeding, and the later unsubscribe still tears it down.
+  #fecArmed = 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). A session re-joining after a takeover timeout
+    // still owns its decoder, so fec-setup fires once per FEC epoch.
+    this.#armFec()
+  }
+
+  /**
+   * 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.#armFec()
+  }
+
+  /**
+   * 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). Use the
+    // same complete span plus explicit allowance as FECManager and workers.
+    const hysteresisMs = computeFecLossWindowMs(
+      this.config.fecInterleaveMs,
+      this.config.fecK,
+      this.config.fecReorderToleranceMs,
+    )
+    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 !== undefined && nextMode !== 'moq') {
+      // Next is multicast or AMT: start joining. `joining` means MoQ is
+      // primary again (see transport getter), so 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).
+      // The chain position moves with the attempt: a join that times out
+      // parks the session in `unicast` with this transport recorded, so the
+      // next failure continues past it rather than re-trying the transport
+      // that already failed and re-firing onTakeoverTimeout on every lap.
+      this.#previousPrimary = nextMode
+      this.#transition('joining')
+      this.#unsuppress()
+      return
+    }
+    // MoQ is next, or the chain is exhausted: unicast either way (Claim 9g).
+    // For a session parked in `unicast` with its decoder retained after a
+    // takeover timeout, this transition is a self-edge and fires no teardown,
+    // so the release is explicit. It is the "transportFailed falling back to
+    // unicast" release path the onTakeoverTimeout doc names, and #disarmFec is
+    // idempotent, so it is a no-op when the transition already fired the
+    // teardown. The audio reset is not flag-guarded, so it is tied to the edge
+    // itself: a session already resting in unicast changed no transport and
+    // owes the host no reset, however many pool subscriptions fail for it.
+    const from = this.#state
+    this.#previousPrimary = null
+    this.#transition('unicast')
+    this.#disarmFec()
+    this.#unsuppress()
+    if (from !== 'unicast' && 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'
+  }
+
+  /**
+   * True while this track owns a FEC decoder (fec-setup fired, fec-teardown
+   * not yet). Stays true across a takeover timeout that parked the session in
+   * `unicast`; SessionManager.failbackAll uses it to release such sessions.
+   */
+  get isFecArmed(): boolean {
+    return this.#fecArmed
+  }
+
+  /**
+   * Start the deadline a `joining` entry deferred while the join was inactive
+   * (SessionManager.joinActive). The track gets the FULL deadline from here,
+   * because that is when media can first arrive. No-op outside `joining` and
+   * when a deadline is already running, so it never shortens or restarts one.
+   *
+   * The `joinActive` guard is what makes this safe to call from anywhere: a
+   * track parked in `joining` with a deferred (null) timer satisfies the other
+   * two, so without it a host calling this while the join is still inactive
+   * would arm the exact deadline the gate exists to defer -- silently
+   * reinstating BLO-34289. It is a no-op for the internal caller, which writes
+   * `#joinActive = true` before iterating the sessions.
+   */
+  armDeferredJoinDeadline(): void {
+    if (this.#state !== 'joining' || this.#joinDeadlineTimer !== null) return
+    if (!this.#manager.joinActive) return
+    this.#armJoinDeadline(this.#manager.takeoverDeadlineMs)
+  }
+
+  dispose(): void {
+    this.#clearHysteresis()
+    this.#clearJoinDeadline()
+    this.#state = 'idle'
+    this.#subscription = null
+    // Release through the teardown edge, not a bare assignment: the
+    // retained-FEC park makes `unicast` + isFecArmed a resting state, and
+    // SessionManager.dispose() calls this directly (removeTrack() reaches it
+    // via unsubscribe(), which has already disarmed). A bare assignment there
+    // drops the host's decoder without a fec-teardown -- a leaked Worker.
+    this.#disarmFec()
+  }
+
+  // -----------------------------------------------------------------------
+  // Internal
+  // -----------------------------------------------------------------------
+
+  #transition(to: TrackState, opts?: { retainFec?: boolean }): void {
+    const from = this.#state
+    if (from === to) return
+    // 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). The value is
+    // resolved before any state write, so the one residual failure -- a
+    // manager whose deadline was never set at all, which addTrack() refuses --
+    // leaves the session in its previous state rather than half-transitioned.
+    // Invalid values never reach here: SessionManager's setter refuses them.
+    // The read is unconditional even when `joinActive` defers the arm, so a
+    // manager without a deadline still fails closed on every joining edge.
+    const joinDeadlineMs = to === 'joining' ? this.#manager.takeoverDeadlineMs : undefined
+    this.#state = to
+    if (from === 'joining') this.#clearJoinDeadline()
+    if (joinDeadlineMs !== undefined && this.#manager.joinActive) {
+      this.#armJoinDeadline(joinDeadlineMs)
+    }
+    // FEC teardown: entering a state without a FEC decoder releases the one
+    // this track armed, unless the caller keeps it (takeover timeout: the
+    // transport is still joined and still feeding the decoder).
+    const fecActive = (s: TrackState) =>
+      s === 'joining' ||
+      s === 'multicast' ||
+      s === 'amt' ||
+      s === 'failing' ||
+      s === 'unicast-fallback'
+    if (!fecActive(to) && !opts?.retainFec) this.#disarmFec()
+    this.#manager.callbacks?.onStateChange?.(this.config.trackName, from, to)
+  }
+
+  #clearHysteresis(): void {
+    if (this.#hysteresisTimer !== null) {
+      clearTimeout(this.#hysteresisTimer)
+      this.#hysteresisTimer = null
+    }
+  }
+
+  #armJoinDeadline(deadlineMs: number): void {
+    this.#clearJoinDeadline()
+    if (deadlineMs === 0) return // a declared 0 disables the deadline
+    this.#joinDeadlineTimer = setTimeout(() => {
+      this.#joinDeadlineTimer = null
+      if (this.#state !== 'joining') return
+      // No RAP within the deadline: return to unicast for arbitration only.
+      // MoQ was never suppressed in `joining`, so there is nothing to restore
+      // and this edge stays silent on onSuppress (asserted in tests). The
+      // multicast socket is still joined and the router still admits this
+      // stream's symbols, so the FEC decoder stays armed; the next transport
+      // edge releases it.
+      this.#transition('unicast', { retainFec: true })
+      this.#manager.callbacks?.onTakeoverTimeout?.(this.config.trackName)
+    }, deadlineMs)
+  }
+
+  #clearJoinDeadline(): void {
+    if (this.#joinDeadlineTimer !== null) {
+      clearTimeout(this.#joinDeadlineTimer)
+      this.#joinDeadlineTimer = null
+    }
+  }
+
+  /** Fire fec-setup exactly once per FEC epoch. */
+  #armFec(): void {
+    if (this.#fecArmed) return
+    this.#fecArmed = true
+    this.#manager.mmtp?.onTrackEvent?.(this.config.trackName, { type: 'fec-setup' }, this.config)
+  }
+
+  /** Fire fec-teardown for an armed decoder; no-op when none is armed. */
+  #disarmFec(): void {
+    if (!this.#fecArmed) return
+    this.#fecArmed = false
+    this.#manager.mmtp?.onTrackEvent?.(this.config.trackName, { type: 'fec-teardown' }, this.config)
+  }
+
+  /** 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
+// ---------------------------------------------------------------------------
+
+/**
+ * Largest takeover deadline setTimeout represents faithfully. setTimeout
+ * coerces its delay to a signed 32-bit int, so a larger value fires on the
+ * next tick (Node also warns TimeoutOverflowWarning) instead of after the
+ * window the host asked for -- silently inverting the feature. Rejecting it
+ * keeps the classic units bug (seconds-as-ms, a wrong timescale) loud.
+ */
+export const MAX_TAKEOVER_DEADLINE_MS = 2_147_483_647
+
+/**
+ * How long `joinActive` may stay false before the library says so. The deferral
+ * is unbounded by construction -- that is the feature -- so a host that never
+ * flips it back parks every track in `joining` with no timer at all: exactly the
+ * forever-join the takeover deadline exists to prevent, only silent. MoQ stays
+ * unsuppressed so the viewer sees video, but onTakeoverTimeout never fires, the
+ * FEC decoder stays armed, and the preference chain never advances past the
+ * transport that failed. It looks like a slow join. A host is one un-awaited
+ * rejection between `false` and `true` away from it, so the library complains
+ * rather than trusting every future host to get all of its exit paths right.
+ *
+ * Generous against a genuinely slow subscribe -- a bridge reconnect or AMT relay
+ * handshake is seconds -- so anything still unsettled here is broken, not slow.
+ */
+export const JOIN_DEFER_WARN_MS = 30_000
+
+export class SessionManager {
+  readonly pool: TransportPool
+  readonly sessions = new Map<string, TrackSession>()
+  callbacks: SessionManagerCallbacks | null = null
+  #takeoverDeadlineMs: number | undefined = undefined
+  #joinActive = true
+  #joinDeferWarnTimer: ReturnType<typeof setTimeout> | null = null
+
+  /**
+   * Takeover deadline (BLO-9413/D9): the 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 abandons the takeover
+   * without a playback glitch. The host derives it from the catalog (RAP
+   * cadence from groupDurationTicks/timescale plus the signaled FEC delivery
+   * window or reorder tolerance) and sets it before addTrack(). There is no
+   * default: an unset value fails addTrack() closed, and reading the getter
+   * before assignment throws the same way, so no host ever holds a
+   * `number | undefined` it could coalesce back into a default.
+   * `hasTakeoverDeadline` answers whether one was admitted. A declared 0
+   * disables the deadline. The value is an integer number of milliseconds:
+   * setTimeout truncates fractions, so a host that divides ticks by a
+   * timescale must round before assigning.
+   *
+   * Assignment validates, so the diagnostic lands at the host's own call site.
+   * That is what bounds the blast radius: `joining` is entered from
+   * joinStarted(), from the transportFailed() failover branch -- itself
+   * reachable from a setTimeout via hysteresisExpired(), where no caller could
+   * catch a throw -- and from the activateMulticast()/activateAmt()/pool-failure
+   * loops, where a throw on one session would abandon its siblings mid-loop
+   * (the split-brain those loops exist to prevent). Refusing a bad value at
+   * assignment means no host mutation can make an already-admitted session
+   * throw out of a transport edge.
+   */
+  get takeoverDeadlineMs(): number {
+    return this.#requireTakeoverDeadlineMs()
+  }
+
+  set takeoverDeadlineMs(value: number) {
+    if (!Number.isInteger(value) || value < 0 || value > MAX_TAKEOVER_DEADLINE_MS) {
+      throw new Error(
+        `[SessionManager] takeoverDeadlineMs must be an integer from 0 to ${MAX_TAKEOVER_DEADLINE_MS} (0 disables it, larger values overflow setTimeout); got ${String(value)}`,
+      )
+    }
+    this.#takeoverDeadlineMs = value
+  }
+
+  /** True once the host has admitted a deadline; a declared 0 counts. */
+  get hasTakeoverDeadline(): boolean {
+    return this.#takeoverDeadlineMs !== undefined
+  }
+
+  /**
+   * Whether the transport the joining tracks are waiting on is actually
+   * subscribed. The takeover deadline is a media-arrival budget and media
+   * cannot arrive before the join exists, so while this is false, entering
+   * `joining` arms no deadline; flipping it true starts the FULL deadline for
+   * every track already parked there.
+   *
+   * Default true, which is the arm-on-`joining` behaviour every host had
+   * before: a host that only calls joinStarted() after its own join resolves
+   * (moqtail-private's player, post-BLO-33339) is already at the right edge and
+   * needs no gate. A host that arms joinStarted() up front — to have FEC
+   * decoders ready before the first datagram — sets this false before addTrack()
+   * and true when its subscribe settles. Charging a slow subscribe (bridge
+   * reconnect, AMT relay handshake) against the media budget expired the
+   * deadline before the subscription existed and abandoned the join on the
+   * happy path. BLO-34289.
+   *
+   * The flag tracks the host's primary join, not per-track transport state. A
+   * track that fails over to the next transport in its own chain while this is
+   * false (transportFailed's failover branch also enters `joining`) has that
+   * deadline gated on the primary join activating, not on its own transport.
+   * Under the documented usage -- false once at setup, true once the subscribe
+   * settles -- the two coincide.
+   *
+   * The gate is on the ENTRY into `joining`, and false cannot take back a
+   * deadline already running: the `true -> false` edge arms the warn below and
+   * clears nothing. So set it false BEFORE the `joining` entry it is meant to
+   * gate. A host that instead flipped it false after a `transportFailed()`
+   * failover had already entered `joining` would leave the full deadline
+   * counting against a subscribe that had not begun -- BLO-34289 again, on the
+   * failover edge. Clearing running deadlines on that edge is deliberately NOT
+   * done: this flag is manager-wide, so one transport's brief false would
+   * cancel an unrelated track's live deadline and then re-arm it at FULL length
+   * on the next activation (armDeferredJoinDeadline sees `joining` + a null
+   * timer and cannot tell a cleared deadline from a deferred one). Every
+   * unrelated transport blip would restart the whole budget, so under repeated
+   * failover a track that should have timed out is extended indefinitely and
+   * never advances. Only a false that never returns true loses the timer
+   * outright, and JOIN_DEFER_WARN_MS already covers that.
+   *
+   * Leaving this false is not free: see JOIN_DEFER_WARN_MS.
+   */
+  get joinActive(): boolean {
+    return this.#joinActive
+  }
+
+  set joinActive(active: boolean) {
+    const wasActive = this.#joinActive
+    this.#joinActive = active
+    if (!active) {
+      // Edge-triggered: a host re-declaring false has not restarted its
+      // subscribe, and total deferral is what the warning is about.
+      if (wasActive) this.#armJoinDeferWarn()
+      return
+    }
+    this.#clearJoinDeferWarn()
+    if (wasActive) return
+    for (const [, session] of this.sessions) session.armDeferredJoinDeadline()
+  }
+
+  #armJoinDeferWarn(): void {
+    this.#joinDeferWarnTimer = setTimeout(() => {
+      this.#joinDeferWarnTimer = null
+      const deferred = [...this.sessions.values()].filter(s => s.state === 'joining').length
+      console.warn(
+        `[SessionManager] joinActive has been false for ${JOIN_DEFER_WARN_MS} ms and ${deferred} track(s) sit in 'joining' with no takeover deadline. Set joinActive = true when the subscribe settles, on every exit path including failures, or these tracks never time out, never release their FEC decoders, and never advance to the next transport.`,
+      )
+    }, JOIN_DEFER_WARN_MS)
+  }
+
+  #clearJoinDeferWarn(): void {
+    if (this.#joinDeferWarnTimer === null) return
+    clearTimeout(this.#joinDeferWarnTimer)
+    this.#joinDeferWarnTimer = null
+  }
+
+  /** 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
+  // -----------------------------------------------------------------------
+
+  /**
+   * The admitted takeover deadline. Throws only when the host never set one,
+   * every other invalid value being refused by the setter, and returns a
+   * declared 0 as 0. The getter and addTrack() both route through it, so a
+   * session cannot exist without an admitted deadline, which is what makes
+   * the #transition() read unable to throw on an already-admitted session.
+   */
+  #requireTakeoverDeadlineMs(): number {
+    const value = this.#takeoverDeadlineMs
+    if (value === undefined) {
+      throw new Error(
+        '[SessionManager] takeoverDeadlineMs is unset; set a catalog-derived takeover deadline (0 disables it) before adding tracks',
+      )
+    }
+    return value
+  }
+
+  /** 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`)
+    }
+    this.#requireTakeoverDeadlineMs()
+    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 and the track keeps its FEC
+   * decoder armed. If a valid RAP arrives later, that late-RAP edge suppresses
+   * unicast and promotes multicast without a second fec-setup.
+   */
+  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`), unsuppressed, and without a FEC decoder.
+   * unsubscribe() unwinds any outstanding suppression regardless of the state
+   * it tears down from (`failing` included; see TrackSession.#suppressFired),
+   * and a session that a takeover timeout parked in `unicast` with its decoder
+   * still armed is cycled too, because this transport edge is what releases
+   * that decoder (unsubscribe fires fec-teardown).
+   */
+  failbackAll(): void {
+    for (const [, session] of this.sessions) {
+      const parkedWithFec = session.state === 'unicast' && session.isFecArmed
+      if (
+        parkedWithFec ||
+        (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 {
+    this.#clearJoinDeferWarn()
+    for (const [, session] of this.sessions) {
+      session.dispose()
+    }
+    this.sessions.clear()
+    this.pool.dispose()
+    this.callbacks = null
+  }
+}