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

package/src/multicast-transport.ts

@@ -0,0 +1,1058 @@
+/**
+ * Thin transport wrapper for SSM multicast — join, socket, watchdog,
+ * takeover/failback.  Delegates raw packets to a callback (MmtpRouter
+ * or any direct consumer).
+ */
+
+import {
+  isMulticastTrackPacketId,
+  subscriptionDeliversPacketBatches,
+  toWindowMulticastSubscribeConfig,
+  type WindowMulticastDelivery,
+  type WindowMulticastGateway,
+  type WindowMulticastSubscription,
+} from '@blockcast/mmt-transport'
+import {
+  MMTP_PACKET_ID_MAX,
+  MMTP_SIGNALING_PACKET_ID,
+  readMMTPPacketId,
+} from '@blockcast/mmt-base'
+
+export interface MulticastTransportConfig {
+  sourceAddress: string
+  groupAddress: string
+  port: number
+  mode?: 'auto' | 'native' | 'tunnel'
+  amtRelay?: string
+  amtRelayPort?: number
+  packetIds?: number[]
+  tracks?: { name: string; packetId: number }[]
+}
+
+export type ResolvedMulticastTransport = 'native' | 'amt'
+
+/**
+ * Why a joined transport handed control back to MoQ.
+ *
+ * - `silence`: the data plane was live (at least one accepted packet since the
+ *   join) and then stayed silent for the catalog-derived failback window.
+ * - `subscription-error`: the provider reported the subscription failed. This
+ *   is the provider's own explicit, typed outcome (a `MulticastError`, branch
+ *   on its `code`), e.g. a bridge whose AMT tunnel it declared dead.
+ */
+export type MulticastFailbackReason =
+  | { readonly kind: 'silence'; readonly windowMs: number }
+  | { readonly kind: 'subscription-error'; readonly error: unknown }
+
+/**
+ * Why a join() resolved false, named by the step at which the join stopped,
+ * never by what an error message says.
+ *
+ * - `disposed`: the transport was disposed before the join started, or while
+ *   the provider's subscribe() was pending.
+ * - `unavailable`: there is no window.multicast gateway with a subscribe().
+ * - `superseded`: a newer join() started while this join's subscribe() was
+ *   pending; the newer join owns the transport.
+ * - `invalid-request`: the join config does not make a valid window.multicast
+ *   request (toWindowMulticastSubscribeConfig refused it), so the provider was
+ *   never asked.
+ * - `provider-rejected`: the provider's subscribe() rejected or threw. The only
+ *   cause that carries the provider's own verdict (`providerError`).
+ * - `invalid-subscription`: subscribe() resolved something that is not a usable
+ *   subscription: no event surface, a malformed `eventTypes`, an unknown
+ *   `delivery`, or an `addEventListener` that threw.
+ * - `delivery-hook-failed`: the consumer's onDelivery hook threw for the
+ *   delivery the subscription declared, e.g. 'ordered-relay' to FEC tracks
+ *   configured without ordered geometry. A local configuration failure, not
+ *   the provider's.
+ */
+export type MulticastJoinDeclineReason =
+  | 'disposed'
+  | 'unavailable'
+  | 'superseded'
+  | 'invalid-request'
+  | 'provider-rejected'
+  | 'invalid-subscription'
+  | 'delivery-hook-failed'
+
+/**
+ * The typed part of a provider's subscribe() rejection. `name` and `code` are
+ * the provider's own typed fields; the frozen multicast contract makes `code`
+ * the one to branch on (e.g. a bridge's `amt_relay_refused`). `message` is
+ * free text carried for humans only: never branch on it.
+ */
+export interface MulticastJoinProviderError {
+  readonly name: string
+  readonly message: string
+  /** Present only when the provider's error carries a string `code`. */
+  readonly code?: string
+}
+
+/**
+ * How a join() resolved: joined, or the typed reason it resolved false.
+ * `providerError` is present only for `provider-rejected`, and only when the
+ * provider's rejection value carries a string `name` and `message`.
+ */
+export type MulticastJoinOutcome =
+  | { readonly ok: true }
+  | {
+      readonly ok: false
+      readonly reason: MulticastJoinDeclineReason
+      readonly providerError?: MulticastJoinProviderError
+    }
+
+/**
+ * Receive counters plus the ingress-filter drop counters.
+ *
+ * `packetsReceived` / `bytesReceived` count only packets that passed the
+ * allow-list and were handed to the page — a rejected packet must never
+ * inflate them.  The `dropped*` counters are the other half of that story:
+ * without them a filtered PID is indistinguishable from a PID that was never
+ * transmitted, which is exactly the ambiguity that makes an all-zero FEC
+ * repair count unreadable (a repair leg dropped here and a repair leg the
+ * publisher never sent produce byte-identical downstream telemetry).
+ */
+export interface MulticastTransportStats {
+  packetsReceived: number
+  bytesReceived: number
+  /** Parsed cleanly, but the packet ID is absent from the join's allow-list. */
+  packetsDroppedUnregisteredPid: number
+  /** MMTP header did not parse; the packet ID is unknown, so it cannot be attributed. */
+  packetsDroppedUnparseable: number
+  /**
+   * packet_id 0, the MMTP signaling flow. Expected traffic on a protected
+   * session (moq_mmt sends the AL-FEC message on it), so it is counted apart
+   * from the unregistered-PID fault counter and never takes a
+   * `droppedPacketIds` slot.
+   */
+  packetsDroppedSignaling: number
+}
+
+/**
+ * join() calls by how they resolved, cumulative for the life of the transport:
+ * across rejoins, failed joins and dispose. `succeeded` plus every `declined`
+ * count is the number of join() calls that resolved, superseded ones
+ * included; a join() that rejects counts in none (see
+ * MulticastTransport.lastJoinOutcome).
+ */
+export interface MulticastJoinStats {
+  /** join() calls that resolved true. */
+  readonly succeeded: number
+  /** join() calls that resolved false, by the reason each one did. */
+  readonly declined: Readonly<Record<MulticastJoinDeclineReason, number>>
+}
+
+const JOIN_SUCCEEDED: MulticastJoinOutcome = Object.freeze({ ok: true })
+
+/**
+ * The typed part of a provider's subscribe() rejection, or undefined when the
+ * rejection value is not an error with a string `name` and `message`. Nothing
+ * is filled in for a field the provider did not type, and the message is
+ * carried, never read.
+ */
+function providerErrorOf(error: unknown): MulticastJoinProviderError | undefined {
+  if (typeof error !== 'object' || error === null) return undefined
+  const fields = error as { readonly name?: unknown; readonly message?: unknown; readonly code?: unknown }
+  let name: unknown
+  let message: unknown
+  let code: unknown
+  try {
+    name = fields.name
+    message = fields.message
+    code = fields.code
+  } catch {
+    // A rejection value whose fields throw on read (a revoked Proxy) types
+    // nothing. Reading it must not turn a declined join into a rejected one.
+    return undefined
+  }
+  if (typeof name !== 'string' || typeof message !== 'string') return undefined
+  return Object.freeze(typeof code === 'string' ? { name, message, code } : { name, message })
+}
+
+/**
+ * Distinct unregistered PIDs retained for diagnostics.  A conformant catalog
+ * advertises a handful of PIDs per endpoint, so this only has to be large
+ * enough to name every leg of a mis-provisioned one; the cap exists so a
+ * malformed or hostile stream cycling the 16-bit PID space cannot grow the map
+ * without bound.  Drops keep counting in aggregate after the cap.
+ */
+const MAX_TRACKED_DROPPED_PIDS = 16
+
+type MulticastGlobals = typeof globalThis & {
+  multicast?: WindowMulticastGateway
+}
+
+function getMulticastGlobals(): MulticastGlobals {
+  return globalThis as MulticastGlobals
+}
+
+function hasMulticastGateway(): boolean {
+  return typeof getMulticastGlobals().multicast?.subscribe === 'function'
+}
+
+/**
+ * The packet one `bytes` event (or one element of a `packets` batch) carries,
+ * as a view of the provider's own bytes. A Uint8Array is used as it is; the
+ * bridge hands every packet over as one, so the common path builds nothing.
+ */
+function normalizeBytesEventDetail(detail: unknown): Uint8Array | null {
+  const value =
+    detail && typeof detail === 'object' && 'data' in detail
+      ? (detail as { data?: unknown }).data
+      : detail
+  if (value instanceof Uint8Array) return value
+  if (value instanceof ArrayBuffer) return new Uint8Array(value)
+  if (ArrayBuffer.isView(value)) {
+    return new Uint8Array(value.buffer, value.byteOffset, value.byteLength)
+  }
+  return null
+}
+
+/**
+ * A provider that can replace a live subscription's MMTP packet-ID filter
+ * without rejoining its socket: the frozen multicast contract's
+ * `Subscription.setPacketIds` (pim `packages/multicast-contract`). It is not
+ * declared on every provider this transport meets, so it is detected, never
+ * assumed.
+ */
+interface PacketFilterUpdater {
+  setPacketIds(packetIds: readonly number[]): Promise<void> | void
+}
+
+function packetFilterUpdater(
+  subscription: WindowMulticastSubscription,
+): PacketFilterUpdater['setPacketIds'] | undefined {
+  const update = (subscription as Partial<PacketFilterUpdater>).setPacketIds
+  return typeof update === 'function' ? update.bind(subscription) : undefined
+}
+
+function sameIds(a: ReadonlySet<number>, b: ReadonlySet<number>): boolean {
+  if (a.size !== b.size) return false
+  for (const id of a) if (!b.has(id)) return false
+  return true
+}
+
+/**
+ * The provider-side packet filter of one live join, and the in-place updates
+ * sent to it. It lives exactly as long as the join: a later join or release
+ * replaces it, and an acknowledgement for a replaced one is ignored.
+ */
+interface ProviderFilter {
+  /**
+   * The filter as the newest acknowledged update left it: the packet IDs the
+   * provider forwards, or null when it forwards every ID. Until an update is
+   * acknowledged it is the join's own filter.
+   */
+  acknowledged: ReadonlySet<number> | null
+  /** Updates sent to the provider, numbered from 1 in send order. */
+  sent: number
+  /** The number of the newest acknowledged update; 0 for the join's own filter. */
+  acknowledgedUpdate: number
+  /** Updates sent and not yet settled. */
+  inFlight: number
+}
+
+/** Which packet surface a join listens to, and its listener. */
+type PacketListener =
+  | { readonly type: 'bytes'; readonly listener: (event: CustomEvent<unknown>) => void }
+  | { readonly type: 'packets'; readonly listener: (event: CustomEvent<readonly unknown[]>) => void }
+
+export class MulticastTransport<TPacketContext = never> {
+  #onPacket: (packet: Uint8Array, context?: TPacketContext) => void
+  #subscription: WindowMulticastSubscription | null = null
+  #packetListener: PacketListener | null = null
+  #resolvedTransport: ResolvedMulticastTransport | undefined
+  #videoConfirmed = false
+  #audioConfirmed = false
+  // One armed no-packets timer per silence window (BLO-36599). Packets only
+  // record #lastPacketAtMs; the timer re-arms for the remainder when it wakes
+  // inside the window, instead of a clear+set pair on every packet.
+  #watchdog: ReturnType<typeof setTimeout> | null = null
+  #lastPacketAtMs = 0
+  #failbackWindowMs: number | null = null
+  #onTakeover: (() => void) | null = null
+  #onFailback: ((reason: MulticastFailbackReason) => void) | null = null
+  // Data-plane-live edge: the first packet this join accepted. Everything
+  // before it is join latency, not silence (see #resetWatchdog).
+  #dataPlaneLive = false
+  #onDataPlaneLive: (() => void) | null = null
+  #errorListener: ((event: CustomEvent<unknown>) => void) | null = null
+  #onDelivery: ((delivery: WindowMulticastDelivery) => void) | null = null
+  #delivery: WindowMulticastDelivery | undefined
+  #disposed = false
+  #stats: MulticastTransportStats = {
+    packetsReceived: 0,
+    bytesReceived: 0,
+    packetsDroppedUnregisteredPid: 0,
+    packetsDroppedUnparseable: 0,
+    packetsDroppedSignaling: 0,
+  }
+  // join() calls by how they resolved; see joinStats.
+  #joinsSucceeded = 0
+  readonly #joinsDeclined: Record<MulticastJoinDeclineReason, number> = {
+    disposed: 0,
+    unavailable: 0,
+    superseded: 0,
+    'invalid-request': 0,
+    'provider-rejected': 0,
+    'invalid-subscription': 0,
+    'delivery-hook-failed': 0,
+  }
+  // The newest resolved join's outcome (see lastJoinOutcome) and the join
+  // generation it belongs to. Generations are issued in start order, so a
+  // join that resolves after a newer join has recorded leaves it standing.
+  #lastJoinOutcome: MulticastJoinOutcome | undefined = undefined
+  #lastJoinOutcomeGeneration = 0
+  #droppedPidCounts = new Map<number, number>()
+  // Accepted bytes per MMTP packet_id; see bytesReceivedForPacketIds. Each
+  // value is a mutable cell, so the per-packet update is one lookup and an
+  // in-place add: no insertion once the key exists, and no re-boxed number
+  // per packet once a count outgrows the small-integer range.
+  readonly #acceptedBytesByPacketId = new Map<number, { bytes: number }>()
+  #packetIds: ReadonlySet<number> | null = null
+  // What the live join delivers with each accepted packet. A field, not a
+  // listener closure, so an in-place admission change (setContext) applies
+  // from the next packet on without rejoining.
+  #context: TPacketContext | undefined = undefined
+  // The live join's provider-side filter. An in-place widening must reach it,
+  // or the provider never delivers the new ID; null without a live join.
+  #providerFilter: ProviderFilter | null = null
+  // IDs an in-place update withdrew while the provider may still be
+  // delivering them. Their late packets are still counted as filtered, but
+  // they are the expected tail of a deliberate change, not a provisioning
+  // fault, so they are counted apart and do not raise the unadvertised-PID
+  // warning.
+  readonly #withdrawnPacketIds = new Set<number>()
+  #withdrawnPacketIdDrops = 0
+  // Distinct packet IDs dropped as provisioning faults: on the wire but in
+  // no allow-list the join or an in-place update declared. Capped with
+  // droppedPacketIds.
+  readonly #unadvertisedPacketIds = new Set<number>()
+  #joinGeneration = 0
+
+  constructor(onPacket: (packet: Uint8Array, context?: TPacketContext) => void) {
+    this.#onPacket = onPacket
+  }
+
+  static isAvailable(): boolean {
+    return hasMulticastGateway()
+  }
+
+  async join(config: MulticastTransportConfig, context?: TPacketContext): Promise<boolean> {
+    const generation = ++this.#joinGeneration
+    this.#releaseSubscription()
+    this.#dataPlaneLive = false
+
+    if (this.#disposed) return this.#declined(generation, 'disposed')
+    if (!MulticastTransport.isAvailable()) {
+      console.warn('[MulticastTransport] Multicast API not available')
+      return this.#declined(generation, 'unavailable')
+    }
+
+    // What a throw from the step in progress means. Each step names its
+    // failure before it runs, so the catch classifies a decline by where the
+    // join stopped, never by what the error says.
+    let failure: MulticastJoinDeclineReason = 'invalid-request'
+    try {
+      const packetIds = config.packetIds?.length ? new Set(config.packetIds) : null
+      console.log(
+        `[MulticastTransport] window.multicast.subscribe(${config.sourceAddress}, ${config.groupAddress}, ${config.port})`,
+      )
+      const subscribeConfig = toWindowMulticastSubscribeConfig({
+        source: config.sourceAddress,
+        group: config.groupAddress,
+        port: config.port,
+        mode: config.mode,
+        amtRelay: config.amtRelay,
+        amtRelayPort: config.amtRelayPort,
+        packetIds: config.packetIds,
+        tracks: config.tracks,
+      })
+      failure = 'provider-rejected'
+      const subscription = await getMulticastGlobals().multicast!.subscribe!(subscribeConfig)
+      failure = 'invalid-subscription'
+      console.log(`[MulticastTransport] window.multicast.subscribe returned:`, !!subscription)
+
+      if (this.#disposed || generation !== this.#joinGeneration) {
+        void subscription.unsubscribe()
+        return this.#declined(generation, this.#displacedReason())
+      }
+      if (typeof subscription.addEventListener !== 'function') {
+        if (typeof subscription.unsubscribe === 'function') {
+          void subscription.unsubscribe()
+        }
+        throw new Error('window.multicast subscription does not support bytes events')
+      }
+
+      // Own the subscription before anything below can throw, so a failed
+      // join's release reaches unsubscribe() instead of leaking it.
+      this.#subscription = subscription
+      const live = () => !this.#disposed && generation === this.#joinGeneration
+      // Exactly one packet surface. A provider that advertises the `packets`
+      // extension delivers each reader batch as one event, so the page pays
+      // one DOM event and one liveness read per batch instead of per packet
+      // (BLO-36599). Every packet still goes through the same filter, counters
+      // and callback, in arrival order, as a view of the provider's bytes.
+      const packetListener: PacketListener = subscriptionDeliversPacketBatches(subscription)
+        ? {
+            type: 'packets',
+            listener: (event) => {
+              if (!live()) return
+              this.#deliverBatch(event.detail, live)
+            },
+          }
+        : {
+            type: 'bytes',
+            listener: (event) => {
+              if (!live()) return
+              if (this.#deliver(event.detail)) this.#resetWatchdog()
+            },
+          }
+      this.#packetListener = packetListener
+      this.#packetIds = packetIds
+      this.#providerFilter = {
+        acknowledged: packetIds,
+        sent: 0,
+        acknowledgedUpdate: 0,
+        inFlight: 0,
+      }
+      this.#context = context
+      // Seed the allow-list's counters so accepted packets never insert. An
+      // id already counted by an earlier join keeps its count: the counters
+      // are cumulative across rejoins, as bytesReceived is.
+      if (packetIds) {
+        for (const packetId of packetIds) {
+          if (!this.#acceptedBytesByPacketId.has(packetId)) {
+            this.#acceptedBytesByPacketId.set(packetId, { bytes: 0 })
+          }
+        }
+      }
+      // The request origin is the accepted acquisition contract.  The
+      // gateway no longer exposes a mutable transport/transportchange
+      // surface, so assign this only after subscribe() has resolved and the
+      // returned subscription has passed the event-surface check above.
+      this.#resolvedTransport = subscribeConfig.origin === 'amt' ? 'amt' : 'native'
+      // The provider alone knows whether its packets are independent
+      // datagrams or an ordered relay of one socket; undeclared promises no
+      // ordering. Announce it before the listener can deliver a packet. A
+      // rejected declaration fails the join and releases the subscription.
+      const delivery = subscription.delivery ?? 'datagram'
+      if (delivery !== 'datagram' && delivery !== 'ordered-relay') {
+        throw new Error(
+          `window.multicast subscription declared unknown delivery ${String(delivery)}`,
+        )
+      }
+      this.#delivery = delivery
+      failure = 'delivery-hook-failed'
+      this.#onDelivery?.(delivery)
+      failure = 'invalid-subscription'
+      // The provider's explicit, terminal subscription failure. Before the
+      // first packet this is the only signal that bounds a join, so it must
+      // reach the failback path rather than be dropped.
+      const onError = (event: CustomEvent<unknown>) => {
+        if (this.#disposed || generation !== this.#joinGeneration) return
+        this.#failBackOnSubscriptionError(event.detail)
+      }
+      this.#errorListener = onError
+      if (packetListener.type === 'packets') {
+        subscription.addEventListener('packets', packetListener.listener)
+      } else {
+        subscription.addEventListener('bytes', packetListener.listener)
+      }
+      subscription.addEventListener('error', onError)
+      // No watchdog here. A resolved subscribe() is the provider's join
+      // outcome, not proof that the data plane is live: over AMT it resolves
+      // once the gateway has sent its Membership Update, and the relay's
+      // upstream join plus one path RTT still precede the first packet. The
+      // silence window is a packet-gap clock for a stream that has flowed;
+      // charging join latency to it failed back joins that went on to play.
+      // The join phase is bounded by the provider's typed error or the host's
+      // takeover deadline (see SessionManager.joinActive). The window starts
+      // at the first accepted packet (#resetWatchdog).
+      console.log(
+        `[MulticastTransport] Joined ${config.groupAddress}:${config.port}`,
+      )
+      return this.#joined(generation)
+    } catch (err) {
+      if (this.#disposed || generation !== this.#joinGeneration) {
+        return this.#declined(generation, this.#displacedReason())
+      }
+      this.#releaseSubscription()
+      console.error('[MulticastTransport] Failed to join SSM group:', err)
+      return this.#declined(
+        generation,
+        failure,
+        failure === 'provider-rejected' ? providerErrorOf(err) : undefined,
+      )
+    }
+  }
+
+  /** Record a join that resolved true; returns its result. */
+  #joined(generation: number): true {
+    this.#joinsSucceeded++
+    this.#recordJoinOutcome(generation, JOIN_SUCCEEDED)
+    return true
+  }
+
+  /** Record a join that resolved false, and why; returns its result. */
+  #declined(
+    generation: number,
+    reason: MulticastJoinDeclineReason,
+    providerError?: MulticastJoinProviderError,
+  ): false {
+    this.#joinsDeclined[reason]++
+    this.#recordJoinOutcome(
+      generation,
+      Object.freeze(
+        providerError === undefined ? { ok: false, reason } : { ok: false, reason, providerError },
+      ),
+    )
+    return false
+  }
+
+  /**
+   * Why a join that no longer owns the transport resolved false. dispose()
+   * advances the join generation too, so disposal is checked first.
+   */
+  #displacedReason(): 'disposed' | 'superseded' {
+    return this.#disposed ? 'disposed' : 'superseded'
+  }
+
+  #recordJoinOutcome(generation: number, outcome: MulticastJoinOutcome): void {
+    if (generation <= this.#lastJoinOutcomeGeneration) return
+    this.#lastJoinOutcomeGeneration = generation
+    this.#lastJoinOutcome = outcome
+  }
+
+  /**
+   * One packet from the subscription: filter, count, and hand it to the
+   * callback. Returns whether it was delivered; the caller notes liveness.
+   */
+  #deliver(detail: unknown): boolean {
+    const packet = normalizeBytesEventDetail(detail)
+    if (!packet) {
+      this.#stats.packetsDroppedUnparseable++
+      return false
+    }
+    if (!this.#acceptPacket(packet)) return false
+    // Read per packet: a callback that changes the admission (an in-place
+    // rendition switch committing on this very packet) takes effect from the
+    // next packet, including the rest of a batch.
+    this.#onPacket(packet, this.#context)
+    return true
+  }
+
+  /**
+   * One `packets` event. Each packet is delivered as a `bytes` event would
+   * have delivered it, including isolation: a packet whose callback throws
+   * does not cost the rest of its batch, as it would not have cost the next
+   * `bytes` event. The first failure is rethrown once the batch is done, so
+   * it reaches the event-listener error reporting a `bytes` listener's throw
+   * reached; any further one is rethrown from its own microtask, which the
+   * host reports the same way, so no failure is swallowed. A callback that
+   * disposes the transport or starts another join ends the batch there, as
+   * the per-packet guard would have ignored the remaining events.
+   */
+  #deliverBatch(
+    batch: readonly unknown[],
+    live: () => boolean,
+  ): void {
+    if (!Array.isArray(batch)) {
+      throw new TypeError('[MulticastTransport] packets event detail must be an array of packets')
+    }
+    let delivered = false
+    let failures: unknown[] | null = null
+    for (let i = 0; i < batch.length; i++) {
+      try {
+        if (this.#deliver(batch[i])) delivered = true
+      } catch (error) {
+        if (failures === null) failures = []
+        failures.push(error)
+      }
+      if (!live()) break
+    }
+    // One liveness read covers the batch: every packet in it arrived in the
+    // same provider task. A batch that delivered nothing, like a rejected
+    // bytes event, is not liveness.
+    if (delivered && live()) this.#resetWatchdog()
+    if (failures !== null) {
+      for (let i = 1; i < failures.length; i++) {
+        const failure = failures[i]
+        queueMicrotask(() => {
+          throw failure
+        })
+      }
+      throw failures[0]
+    }
+  }
+
+  /** Feed a raw packet from an external source (e.g., AMT tunnel or ASM subscription). */
+  feedPacket(data: ArrayBuffer | Uint8Array, context?: TPacketContext): void {
+    if (this.#disposed) return
+    const packet = data instanceof Uint8Array ? data : new Uint8Array(data)
+    if (!this.#acceptPacket(packet)) return
+    this.#onPacket(packet, context)
+    this.#resetWatchdog()
+  }
+
+  confirmVideo(): void {
+    this.#videoConfirmed = true
+    this.#checkTakeover()
+  }
+
+  confirmAudio(): void {
+    this.#audioConfirmed = true
+    this.#checkTakeover()
+  }
+
+  onTakeover(cb: () => void): void {
+    this.#onTakeover = cb
+  }
+
+  onFailback(cb: (reason: MulticastFailbackReason) => void): void {
+    this.#onFailback = cb
+  }
+
+  /**
+   * Called on every successful join, before the joined subscription can
+   * deliver a packet, with how that subscription delivers packets.
+   */
+  onDelivery(cb: (delivery: WindowMulticastDelivery) => void): void {
+    this.#onDelivery = cb
+  }
+
+  /** How the current subscription delivers packets, once joined. */
+  get delivery(): WindowMulticastDelivery | undefined {
+    return this.#delivery
+  }
+
+  /**
+   * Fires once per join, at the first packet the join accepts (after the PID
+   * filter; a rejected packet is not liveness). This is the data-plane-live
+   * edge, where this transport's silence window starts. A join whose source
+   * never sends never reaches it, so a host may start a media-arrival budget
+   * here only if the provider bounds the join phase with a typed subscription
+   * error (see SessionManager.joinActive); otherwise the host starts it when
+   * the subscribe settles.
+   */
+  onDataPlaneLive(cb: () => void): void {
+    this.#onDataPlaneLive = cb
+  }
+
+  /** Whether the current join has accepted a packet (see onDataPlaneLive). */
+  get dataPlaneLive(): boolean {
+    return this.#dataPlaneLive
+  }
+
+  setFailbackWindowMs(windowMs: number): void {
+    if (!Number.isFinite(windowMs) || windowMs <= 0) {
+      throw new Error(
+        `[MulticastTransport] failbackWindowMs=${windowMs}. ` +
+        `Derive a positive failback window from the stream catalog.`,
+      )
+    }
+    this.#failbackWindowMs = windowMs
+    // An armed timer was scheduled against the previous window; re-derive its
+    // wake-up from the last packet so a narrower window is not enforced late.
+    if (this.#watchdog !== null) {
+      clearTimeout(this.#watchdog)
+      const silentMs = performance.now() - this.#lastPacketAtMs
+      this.#armWatchdog(Math.max(0, Math.ceil(windowMs - silentMs)))
+    }
+  }
+
+  get stats(): MulticastTransportStats {
+    return this.#stats
+  }
+
+  /**
+   * How the newest join() to resolve did: `{ ok: true }`, or `{ ok: false }`
+   * with the typed reason it resolved false (and, for `provider-rejected`, the
+   * provider's typed error fields). Undefined until a join resolves. Branch on
+   * `reason` and `providerError.code`, never on log text or
+   * `providerError.message`.
+   *
+   * Newest is by start order: a join that resolves after a newer join has
+   * recorded its outcome does not replace it, so once `await join()` resolves
+   * this names that join's outcome unless a newer join has already resolved.
+   * It records how a join resolved, not whether it is still joined (see
+   * `joined`); a join() that rejects instead of resolving records nothing,
+   * the rejection being its report. Frozen: a later outcome replaces the
+   * object, never changes it.
+   */
+  get lastJoinOutcome(): MulticastJoinOutcome | undefined {
+    return this.#lastJoinOutcome
+  }
+
+  /**
+   * join() calls by how they resolved (see MulticastJoinStats). A fresh frozen
+   * snapshot on every read, so a later join never changes one already read.
+   * Kept apart from `stats`, which is the live counter object.
+   */
+  get joinStats(): MulticastJoinStats {
+    return Object.freeze({
+      succeeded: this.#joinsSucceeded,
+      declined: Object.freeze({ ...this.#joinsDeclined }),
+    })
+  }
+
+  /**
+   * Accepted bytes summed over `packetIds`: the `bytesReceived` share of those
+   * MMTP packet_ids. Counted by the same rule, on every path that counts
+   * `bytesReceived` (only packets that pass the ingress filter; packet_id 0
+   * signaling never), and cumulative for the life of the transport, across
+   * rejoins, as `bytesReceived` is. An id never accepted contributes 0. An
+   * unparseable packet admitted by a join without an allow-list has no
+   * packet_id, so it counts toward `bytesReceived` only.
+   *
+   * Use it to scope an ABR throughput sample to the active tier's source and
+   * repair packet_ids when the join admits more than the active tier (a
+   * shared group joined across rendition switches); `bytesReceived` is then
+   * the whole allow-list's arrival, not the active tier's. A Set, so an id
+   * shared by two tracks of the tier is counted once.
+   *
+   * Monotonic only for a fixed set: each id has counted since it was first
+   * admitted, so after a tier switch the new set's sum is not a continuation
+   * of the old one. A cumulative consumer takes a fresh baseline for the new
+   * set and never differences across sets.
+   */
+  bytesReceivedForPacketIds(packetIds: ReadonlySet<number>): number {
+    let bytes = 0
+    for (const packetId of packetIds) {
+      bytes += this.#acceptedBytesByPacketId.get(packetId)?.bytes ?? 0
+    }
+    return bytes
+  }
+
+  /**
+   * Per-PID drop breakdown, newest-capped at MAX_TRACKED_DROPPED_PIDS distinct
+   * PIDs.  This is what names the offender: `packetsDroppedUnregisteredPid`
+   * says the ingress filter fired, this says it fired on 0x8001.
+   */
+  get droppedPacketIds(): ReadonlyMap<number, number> {
+    return this.#droppedPidCounts
+  }
+
+  /**
+   * Distinct packet IDs dropped as provisioning faults: arriving on the wire
+   * but in no allow-list the join or an in-place update (setPacketIds)
+   * declared, the drops that raise the unadvertised-PID warning. A packet ID
+   * an in-place update withdrew is not one (see withdrawnPacketIdDrops).
+   * Cumulative across rejoins and capped with droppedPacketIds.
+   */
+  get unadvertisedPacketIds(): ReadonlySet<number> {
+    return this.#unadvertisedPacketIds
+  }
+
+  /**
+   * Packets dropped because an in-place update (setPacketIds) withdrew their
+   * packet ID while the provider may still deliver it: the expected tail of
+   * a deliberate change. A subset of packetsDroppedUnregisteredPid,
+   * cumulative across rejoins.
+   */
+  get withdrawnPacketIdDrops(): number {
+    return this.#withdrawnPacketIdDrops
+  }
+
+  /** Whether a subscription is live: joined, and not yet released or replaced. */
+  get joined(): boolean {
+    return this.#subscription !== null
+  }
+
+  /**
+   * What the live join delivers with every accepted packet (the join's
+   * `context`, or the last setContext), or undefined without a live join.
+   */
+  get context(): TPacketContext | undefined {
+    return this.#context
+  }
+
+  /**
+   * The live join's page-side packet-ID allow-list, or null when it admits
+   * every packet ID (a join that carried none, or no live join).
+   */
+  get packetIds(): ReadonlySet<number> | null {
+    return this.#packetIds
+  }
+
+  /**
+   * Replace what the live join delivers with each accepted packet, from the
+   * next packet on. The subscription (socket, group membership, AMT tunnel)
+   * is untouched: this is how an in-place rendition switch moves the router's
+   * ingress identities without leaving and re-joining the group.
+   */
+  setContext(context: TPacketContext): void {
+    if (this.#subscription === null) {
+      throw new Error(
+        '[MulticastTransport] setContext needs a live join; join() carries the first context',
+      )
+    }
+    this.#context = context
+  }
+
+  /**
+   * Replace the live join's packet-ID allow-list in place, without rejoining.
+   *
+   * The page-side filter changes synchronously, before this returns: the
+   * next packet is admitted or dropped by the new list. The provider's own
+   * filter is updated through the subscription's `setPacketIds` when it has
+   * one; the returned promise settles with the provider's acknowledgement of
+   * this update. It resolves at once, telling the provider nothing, only
+   * when the provider cannot be told, or when no earlier update is still in
+   * flight and the provider already forwards exactly this list.
+   *
+   * While an update is in flight the provider's filter is not known, so every
+   * later update is sent: one skipped because it matched the last
+   * acknowledged filter would let the in-flight update land after it, and
+   * leave the provider forwarding a list nobody asked for last. Updates are
+   * numbered in send order and the newest acknowledged one describes the
+   * provider, so an acknowledgement that overtakes an older one is not undone
+   * by it.
+   *
+   * A provider without `setPacketIds` can still be narrowed: its wider filter
+   * keeps delivering the dropped IDs and the page-side filter discards them.
+   * It cannot be widened, since it would never deliver the added IDs; that is
+   * refused with a throw before anything changes. An ID this update withdraws
+   * may keep arriving until the provider applies the narrower list; those
+   * packets are counted as filtered like any other and in
+   * withdrawnPacketIdDrops, but are not unadvertised packet IDs: their
+   * arrival is the expected tail of this change rather than a provisioning
+   * fault.
+   */
+  setPacketIds(packetIds: readonly number[]): Promise<void> {
+    const subscription = this.#subscription
+    const filter = this.#providerFilter
+    if (subscription === null || filter === null) {
+      throw new Error(
+        '[MulticastTransport] setPacketIds needs a live join; join() carries the first allow-list',
+      )
+    }
+    if (!Array.isArray(packetIds) || packetIds.length === 0) {
+      throw new RangeError(
+        '[MulticastTransport] setPacketIds needs a non-empty packet-ID list: ' +
+          'an in-place update names the packet IDs it admits',
+      )
+    }
+    if (!packetIds.every(isMulticastTrackPacketId)) {
+      throw new RangeError(
+        `[MulticastTransport] packetId must be an integer from 1 to ${MMTP_PACKET_ID_MAX}; ` +
+          "packetId 0 is the MMTP signaling flow and is never a track's",
+      )
+    }
+    const next: ReadonlySet<number> = new Set(packetIds)
+    const provider = filter.acknowledged
+    const update = packetFilterUpdater(subscription)
+    // Without an updater nothing is ever sent, so the join's filter is exact.
+    if (update === undefined && provider !== null) {
+      const missing = [...next].filter((id) => !provider.has(id))
+      if (missing.length > 0) {
+        throw new Error(
+          '[MulticastTransport] this subscription cannot widen its packet filter in place ' +
+            `(the provider exposes no setPacketIds); rejoin to admit ${missing.join(', ')}`,
+        )
+      }
+    }
+    const previous = this.#packetIds
+    this.#packetIds = next
+    for (const id of next) {
+      this.#withdrawnPacketIds.delete(id)
+      if (!this.#acceptedBytesByPacketId.has(id)) {
+        this.#acceptedBytesByPacketId.set(id, { bytes: 0 })
+      }
+    }
+    if (previous !== null) {
+      for (const id of previous) if (!next.has(id)) this.#withdrawnPacketIds.add(id)
+    }
+    if (update === undefined) return Promise.resolve()
+    if (filter.inFlight === 0 && provider !== null && sameIds(provider, next)) {
+      return Promise.resolve()
+    }
+    const number = ++filter.sent
+    filter.inFlight++
+    let applied: Promise<void>
+    try {
+      applied = Promise.resolve(update([...next]))
+    } catch (error) {
+      applied = Promise.reject(error)
+    }
+    return applied.then(
+      () => {
+        if (this.#providerFilter !== filter) return
+        filter.inFlight--
+        if (number > filter.acknowledgedUpdate) {
+          filter.acknowledgedUpdate = number
+          filter.acknowledged = next
+        }
+      },
+      (error: unknown) => {
+        // A refused update leaves the provider on the filter it had.
+        if (this.#providerFilter === filter) filter.inFlight--
+        throw error
+      },
+    )
+  }
+
+  get resolvedTransport(): ResolvedMulticastTransport | undefined {
+    return this.#resolvedTransport
+  }
+
+  dispose(): void {
+    ++this.#joinGeneration
+    this.#disposed = true
+    this.#releaseSubscription()
+  }
+
+  #releaseSubscription(): void {
+    if (this.#watchdog) clearTimeout(this.#watchdog)
+    this.#watchdog = null
+    if (this.#subscription) {
+      const packetListener = this.#packetListener
+      if (packetListener?.type === 'packets') {
+        this.#subscription.removeEventListener('packets', packetListener.listener)
+      } else if (packetListener) {
+        this.#subscription.removeEventListener('bytes', packetListener.listener)
+      }
+      if (this.#errorListener) {
+        this.#subscription.removeEventListener('error', this.#errorListener)
+      }
+      void this.#subscription.unsubscribe()
+    }
+    this.#subscription = null
+    this.#packetListener = null
+    this.#errorListener = null
+    this.#resolvedTransport = undefined
+    this.#delivery = undefined
+    this.#packetIds = null
+    this.#providerFilter = null
+    this.#context = undefined
+    this.#withdrawnPacketIds.clear()
+  }
+
+  /** The ingress filter; an accepted packet is counted here, once. */
+  #acceptPacket(packet: Uint8Array): boolean {
+    // This early read is intentional: rejected PIDs must not affect page
+    // delivery, receive statistics, or the failback liveness watchdog. It
+    // refuses exactly what parseMMTPHeader refuses but builds no header
+    // object; the router parses the header once, later (BLO-36599).
+    const packetId = readMMTPPacketId(packet)
+    if (packetId === null) {
+      // Without an allow-list there is no filter to enforce, so an unparseable
+      // packet keeps flowing to the router as before.
+      if (!this.#packetIds) {
+        this.#countAccepted(packet, null)
+        return true
+      }
+      this.#stats.packetsDroppedUnparseable++
+      return false
+    }
+    // packet_id 0 is the MMTP signaling flow and never a track's. Drop it even
+    // when the join carried no allow-list (a legacy catalog whose tracks omit
+    // packetId): the discard rule must not depend on how the catalog was written.
+    if (packetId === MMTP_SIGNALING_PACKET_ID) {
+      this.#stats.packetsDroppedSignaling++
+      return false
+    }
+    if (!this.#packetIds || this.#packetIds.has(packetId)) {
+      this.#countAccepted(packet, packetId)
+      return true
+    }
+    this.#recordUnregisteredPidDrop(packetId)
+    return false
+  }
+
+  /** Receive counters for one accepted packet; `packetId` is null when it has none. */
+  #countAccepted(packet: Uint8Array, packetId: number | null): void {
+    this.#stats.packetsReceived++
+    this.#stats.bytesReceived += packet.byteLength
+    if (packetId === null) return
+    const counter = this.#acceptedBytesByPacketId.get(packetId)
+    if (counter !== undefined) {
+      counter.bytes += packet.byteLength
+    } else {
+      // First sight of this id on a join with no allow-list (an allow-list's
+      // ids are seeded at join). Bounded by the 16-bit packet_id space.
+      this.#acceptedBytesByPacketId.set(packetId, { bytes: packet.byteLength })
+    }
+  }
+
+  #recordUnregisteredPidDrop(packetId: number): void {
+    this.#stats.packetsDroppedUnregisteredPid++
+    const withdrawn = this.#withdrawnPacketIds.has(packetId)
+    if (withdrawn) this.#withdrawnPacketIdDrops++
+    const seen = this.#droppedPidCounts.get(packetId)
+    if (seen !== undefined) {
+      this.#droppedPidCounts.set(packetId, seen + 1)
+      return
+    }
+    if (this.#droppedPidCounts.size >= MAX_TRACKED_DROPPED_PIDS) return
+    this.#droppedPidCounts.set(packetId, 1)
+    if (withdrawn) return
+    this.#unadvertisedPacketIds.add(packetId)
+    // Warn once per distinct PID. A PID arriving on the wire but missing from
+    // the catalog's advertised set is a provisioning fault, not stream noise,
+    // and it is silent in every downstream counter.
+    console.warn(
+      `[MulticastTransport] Dropping packetId=${packetId} (0x${packetId.toString(16)}): ` +
+      `not in the advertised set [${[...(this.#packetIds ?? [])].join(', ')}]. ` +
+      `If this is an FEC repair leg, the catalog is not advertising its packetId.`,
+    )
+  }
+
+  #checkTakeover(): void {
+    if (this.#videoConfirmed && this.#audioConfirmed && this.#onTakeover) {
+      const cb = this.#onTakeover
+      this.#onTakeover = null // fire exactly once
+      cb()
+    }
+  }
+
+  /**
+   * Note liveness now; arm the no-packets timer if none is armed.
+   *
+   * Called only for accepted packets, so the first call of a join is the
+   * data-plane-live edge and is what first arms the silence window: the window
+   * measures silence of a flowing stream, which is undefined before the stream
+   * has flowed.
+   */
+  #resetWatchdog(): void {
+    this.#lastPacketAtMs = performance.now()
+    if (!this.#dataPlaneLive) {
+      this.#dataPlaneLive = true
+      this.#onDataPlaneLive?.()
+    }
+    if (this.#watchdog !== null) return
+    if (!this.#onFailback) return
+    if (this.#failbackWindowMs === null) {
+      throw new Error(
+        '[MulticastTransport] Failback watchdog requires a catalog-derived window',
+      )
+    }
+    this.#armWatchdog(this.#failbackWindowMs)
+  }
+
+  #armWatchdog(delayMs: number): void {
+    this.#watchdog = setTimeout(() => {
+      this.#watchdog = null
+      if (this.#disposed || !this.#onFailback || this.#failbackWindowMs === null) return
+      const silentMs = performance.now() - this.#lastPacketAtMs
+      if (silentMs < this.#failbackWindowMs) {
+        this.#armWatchdog(Math.ceil(this.#failbackWindowMs - silentMs))
+        return
+      }
+      console.warn(
+        `[MulticastTransport] No packets for ${this.#failbackWindowMs}ms; failing back to MoQ`,
+      )
+      this.#onFailback({ kind: 'silence', windowMs: this.#failbackWindowMs })
+    }, delayMs)
+  }
+
+  /** Hand control back to MoQ for a provider-reported subscription failure. */
+  #failBackOnSubscriptionError(error: unknown): void {
+    // The subscription is dead; a silence timer armed against it would only
+    // report the same failure a second time.
+    if (this.#watchdog !== null) clearTimeout(this.#watchdog)
+    this.#watchdog = null
+    console.warn('[MulticastTransport] Subscription failed; failing back to MoQ:', error)
+    this.#onFailback?.({ kind: 'subscription-error', error })
+  }
+}