@blockcast/mmt-container 0.1.0 → 0.3.0

package/src/fec-starvation-detector.ts

@@ -0,0 +1,128 @@
+/**
+ * FecStarvationDetector — post-cutover source-starvation detection (BLO-9413/D4).
+ *
+ * The packet-presence watchdog (MulticastTransport, 5s) only catches TOTAL
+ * silence: any packet — including FEC repair — resets it. The observed
+ * BLO-9413 failure delivered repair symbols continuously while ZERO source
+ * symbols arrived (`sourceSymbols:0, repairSymbols:551, blocksComplete:0`):
+ * the watchdog stayed fed forever while nothing reconstructable reached the
+ * decoder. This detector closes that hole by watching delivery progress and
+ * driving the designed-but-previously-uncalled TrackSession loss arcs:
+ *
+ *   starvation sustained ≥ windowMs → onStarvation()  → session.lossDetected()
+ *   block progress resumes          → onRecovery()    → session.lossRecovered()
+ *
+ * TrackSession's own FEC block-span hysteresis then decides whether a recovery
+ * cancels the failback — this detector deliberately does NOT add a second
+ * hysteresis layer.
+ *
+ * Push-fed: call update() with each FecTrackStats-shaped snapshot (e.g. from
+ * MulticastManager.setOnFecStatsUpdate or a host sampler). Hosts that can also
+ * observe decoded/appended media should include a monotonic mediaFrames count:
+ * media progress is delivery progress even if sparse FEC block counters do not
+ * advance in the same sample window. Evaluation happens only on update — a
+ * fully dead transport stops producing updates and stays the transport
+ * watchdog's responsibility (total-silence backstop).
+ */
+
+/** Monotonic counters sampled from the FEC layer (FecTrackStats subset). */
+export interface FecStarvationSnapshot {
+  sourceSymbols: number
+  repairSymbols: number
+  blocksComplete: number
+  blocksRecovered: number
+  /** Optional host-observed decoded/appended media frames for this packetId. */
+  mediaFrames?: number
+}
+
+export interface FecStarvationDetectorConfig {
+  /**
+   * How long starvation must persist before onStarvation fires. Derive from
+   * the stream's FEC block-span config — no magic defaults, matching the
+   * TrackSession hysteresis convention.
+   */
+  windowMs: number
+  /** Starvation sustained ≥ windowMs. Fires once per starvation episode. */
+  onStarvation(): void
+  /** Healthy delivery resumed after onStarvation fired. Fires once per episode. */
+  onRecovery(): void
+  /** Injectable clock for tests. Defaults to Date.now. */
+  now?: () => number
+}
+
+export class FecStarvationDetector {
+  #config: FecStarvationDetectorConfig
+  #now: () => number
+  #last: FecStarvationSnapshot | null = null
+  #lastSampleAt = 0
+  #starvedSince: number | null = null
+  #latched = false
+
+  constructor(config: FecStarvationDetectorConfig) {
+    if (config.windowMs <= 0) {
+      throw new Error(
+        `[FecStarvationDetector] windowMs=${config.windowMs}. Derive a positive window ` +
+        `from the stream's FEC block-span config — a non-positive ` +
+        `window would fire on the first repair packet of a healthy stream.`
+      )
+    }
+    this.#config = config
+    this.#now = config.now ?? Date.now
+  }
+
+  /** True while a starvation episode is active (onStarvation fired, no recovery yet). */
+  get isStarved(): boolean { return this.#latched }
+
+  update(snapshot: FecStarvationSnapshot): void {
+    const last = this.#last
+    const prevSampleAt = this.#lastSampleAt
+    const now = this.#now()
+    this.#last = { ...snapshot }
+    this.#lastSampleAt = now
+    if (last === null) return // first sample = baseline only
+
+    const srcDelta = snapshot.sourceSymbols - last.sourceSymbols
+    const repDelta = snapshot.repairSymbols - last.repairSymbols
+    const doneDelta =
+      (snapshot.blocksComplete - last.blocksComplete) +
+      (snapshot.blocksRecovered - last.blocksRecovered)
+    const mediaDelta = (snapshot.mediaFrames ?? 0) - (last.mediaFrames ?? 0)
+
+    const packetsFlowing = srcDelta > 0 || repDelta > 0
+    if (!packetsFlowing && mediaDelta <= 0) return // total silence — transport watchdog's domain
+
+    // Starving: traffic arrives but nothing reconstructable comes out. Source
+    // and repair symbols arrive at symbol cadence while complete/recovered
+    // blocks arrive at block cadence; requiring source and block deltas in the
+    // same snapshot false-fails healthy live streams. A repaired block is still
+    // decodable media, and host-observed frame progress is even stronger
+    // evidence, so either resets the starvation clock.
+    const starving = doneDelta === 0 && mediaDelta <= 0
+
+    if (starving) {
+      // The episode began when delivery was last known healthy — the previous
+      // sample's timestamp, not this sample's arrival (the deltas in THIS
+      // sample describe the interval since then).
+      if (this.#starvedSince === null) this.#starvedSince = prevSampleAt
+      if (!this.#latched && now - this.#starvedSince >= this.#config.windowMs) {
+        this.#latched = true
+        this.#config.onStarvation()
+      }
+      return
+    }
+
+    // Healthy sample: completed or recovered blocks are reaching the decoder.
+    this.#starvedSince = null
+    if (this.#latched) {
+      this.#latched = false
+      this.#config.onRecovery()
+    }
+  }
+
+  /** Reset episode state (e.g. on transport switch / re-join). Keeps no baseline. */
+  reset(): void {
+    this.#last = null
+    this.#starvedSince = null
+    this.#latched = false
+  }
+}

package/src/fec-state.ts

@@ -0,0 +1,219 @@
+// Typed FEC state shared by every player (hang/moq-lib, moqtail, Shaka MSF).
+//
+// A player's FEC counters are `null` in three unrelated situations: the
+// session is on reliable MoQ, where FEC has nothing to protect (FEC protects
+// only lossy multicast/AMT datagrams); no multicast bridge exists, so no lossy
+// leg can be joined; or the catalog declares no FEC for the tracks the player
+// selected. `null` also meant "nothing decoded yet" and "the pipeline broke",
+// so an idle session and a broken one looked identical.
+//
+// `resolveFecState` names which case holds. Each reason is read from a fact the
+// player already owns -- its catalog, its transport policy, its bridge probe
+// and its physical subscription -- and never from counters, console text,
+// timers or elapsed time. The rules live here so the three players cannot
+// disagree about precedence.
+
+import { isFecBlockProfile } from '@blockcast/mmt-base'
+
+/**
+ * Minimum valid FEC interleave depth in milliseconds, per spec §5.1
+ * (the interactive/gaming floor; broadcast/ATSC 3.0 ranges up to 10000ms).
+ *
+ * A protocol constant, NOT a tuning knob. Values below this floor are almost
+ * certainly a raw frame count (e.g. `2`) that a caller passed when no framerate
+ * was available to convert to ms (common on audio tracks). Feeding such a value
+ * into computeFecTimeout treats it as `2ms`, yielding a near-zero FEC block
+ * timeout that abandons startup FEC blocks before their repair symbols arrive
+ * (measured: moqtail startupFailed=4, shaka dropped=5.8% on startup). Timing
+ * derivations MUST reject sub-floor values and fall back to the established
+ * timeout instead of collapsing.
+ */
+export const MIN_INTERLEAVE_DEPTH_MS = 33
+
+/** Why FEC is not protecting this session. */
+export type FecInactiveReason = 'no-catalog-fec' | 'reliable-moq' | 'no-multicast-bridge'
+
+/** Every inactive reason, in resolution order. */
+export const FEC_INACTIVE_REASONS: readonly FecInactiveReason[] = Object.freeze([
+  'no-catalog-fec',
+  'reliable-moq',
+  'no-multicast-bridge',
+] as const)
+
+/** The transport policy vocabulary every player accepts. */
+export type FecTransportPolicy = 'auto' | 'moq-only' | 'multicast-only'
+
+const TRANSPORT_POLICIES: ReadonlySet<string> = new Set<FecTransportPolicy>(['auto', 'moq-only', 'multicast-only'])
+
+/** FEC is not protecting this session; `reason` says why. Carries no counters. */
+export interface FecInactiveState {
+  readonly state: 'inactive'
+  readonly reason: FecInactiveReason
+}
+
+/**
+ * FEC is the protection in force for this session's delivery path.
+ *
+ * Flat on purpose: the player's existing counters stay at the paths every
+ * consumer already reads (`fec.blocksRecovered`, `fec.tracks`, `fec.blocks`),
+ * with `state` added beside them. A consumer that ignores `state` reads an
+ * active report exactly as before and an inactive one as "no counters", which
+ * is what `null` meant to it.
+ */
+export type FecActiveState<S extends object> = S & { readonly state: 'active' }
+
+export type FecState<S extends object> = FecActiveState<S> | FecInactiveState
+
+/** An active state whose decoder has not reported any counter yet. */
+export type NoFecCounters = Record<never, never>
+
+/** The authoritative facts `resolveFecState` reads. */
+export interface FecStateEvidence<S extends object> {
+  /**
+   * The counters the player reports today, or null/undefined when it has none.
+   * Payload only: it never decides the state, because moqtail and Shaka report
+   * a zeroed snapshot as soon as a MulticastManager exists, which is before any
+   * bridge or subscription does.
+   */
+  readonly stats: S | null | undefined
+  /**
+   * Whether the catalog declares FEC (see `catalogDeclaresFec`) for at least
+   * one media track the player selected.
+   */
+  readonly catalogFec: boolean
+  /** The player's configured transport policy. */
+  readonly transportPolicy: FecTransportPolicy
+  /** Whether a multicast bridge (`window.multicast`) is available to the page. */
+  readonly bridgeAvailable: boolean
+  /**
+   * Whether a physical multicast/AMT subscription is live: the bridge accepted
+   * it and it has not been closed. A requested leg is not a joined one.
+   */
+  readonly multicastLegJoined: boolean
+}
+
+const INACTIVE: Readonly<Record<FecInactiveReason, FecInactiveState>> = Object.freeze({
+  'no-catalog-fec': Object.freeze({ state: 'inactive', reason: 'no-catalog-fec' }),
+  'reliable-moq': Object.freeze({ state: 'inactive', reason: 'reliable-moq' }),
+  'no-multicast-bridge': Object.freeze({ state: 'inactive', reason: 'no-multicast-bridge' }),
+})
+
+function recordOf(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined
+}
+
+function isPositiveSafeInteger(value: unknown): boolean {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value > 0
+}
+
+/**
+ * Whether one catalog `fec` block (a hang rendition's `fec` or an MSF/CMSF
+ * track's `fec`) declares an FEC instance a receiver can configure: source
+ * symbols per block (K) and a symbol size (T) are both positive integers, the
+ * algorithm is not `none`, and `blockProfile` names a known block profile
+ * (BLO-35597). Total: it never throws, and answers false for any other value.
+ *
+ * `resolveCatalogTrackFec` reads this predicate, so the players' parameters and
+ * this state never disagree. Of the blocks this rejects, it returns no FEC
+ * geometry only for `algorithm: "none"`. One with any other algorithm is a
+ * malformed catalog (`FecCatalogConfig` marks both fields REQUIRED; the MSF
+ * schema and `validateCmsfMmtpCatalog` enforce them on `tracks[]`, but the
+ * hang dialect's `renditions` schema is permissive, so this is where a hang
+ * block fails closed), and `resolveCatalogTrackFec` throws a `RepairContractError` for
+ * it (`track_fec` unless another repair-contract violation fires first),
+ * whether or not the source has repair layers, rather than silently dropping
+ * the track's repair subscription.
+ *
+ * The block profile is part of this predicate because the profile selects the
+ * block math and is never defaulted: without a known one no receiver can
+ * configure the instance. `resolveCatalogTrackFec` resolves such a track to no
+ * FEC with a typed `fecUnavailable` reason (`track_fec_block_profile`), scoped
+ * to that track, so its parameters and this state still agree. The CMSF
+ * conformance validator (`validateCmsfMmtpCatalog`) still rejects the catalog
+ * with `track_fec_block_profile`. An `iso-ssbg1-v1` instance without a usable
+ * block span (`isoBlockSpanUsable`) is likewise no FEC for its track alone,
+ * with `fecUnavailable` code `track_fec` on its `interleaveDepthMs`.
+ *
+ * The repair-contract resolvers (`resolveRepairLayers`) gate a `depends` target
+ * on `algorithm` alone and never read a source's `symbolSize`. They check its
+ * `sourceSymbols` for the RaptorQ K bound, and require a positive integer
+ * `sourceSymbols` and `repairSymbols` only when the source has repair layers or
+ * an overlay beyond layer 0.
+ */
+export function catalogDeclaresFec(fec: unknown): boolean {
+  const block = recordOf(fec)
+  if (block === undefined || block['algorithm'] === 'none') return false
+  return (
+    isPositiveSafeInteger(block['sourceSymbols']) &&
+    isPositiveSafeInteger(block['symbolSize']) &&
+    isFecBlockProfile(block['blockProfile']) &&
+    isoBlockSpanUsable(block)
+  )
+}
+
+/**
+ * Whether a `fec` block that names `iso-ssbg1-v1` carries the block span its
+ * block location is bounded by: `interleaveDepthMs`, a finite number of
+ * milliseconds no smaller than `MIN_INTERLEAVE_DEPTH_MS`. Without it a receiver
+ * cannot bound the sources it holds before a repair states their block, so the
+ * instance cannot be configured (BLO-35597). Any other block needs no span here.
+ */
+export function isoBlockSpanUsable(fec: unknown): boolean {
+  const block = recordOf(fec)
+  if (block === undefined || block['blockProfile'] !== 'iso-ssbg1-v1') return true
+  const ms = block['interleaveDepthMs']
+  return typeof ms === 'number' && Number.isFinite(ms) && ms >= MIN_INTERLEAVE_DEPTH_MS
+}
+
+function requireBoolean(value: unknown, field: string): boolean {
+  if (typeof value !== 'boolean') {
+    throw new TypeError(`resolveFecState: ${field} must be a boolean, got ${typeof value}`)
+  }
+  return value
+}
+
+/**
+ * Resolve a player's FEC state. First match wins:
+ *
+ * 1. The catalog declares no FEC for a selected track: `no-catalog-fec`. FEC
+ *    geometry comes only from the catalog, so there is nothing to configure on
+ *    any path.
+ * 2. The policy is `moq-only`: `reliable-moq`. Media travels only over QUIC,
+ *    which is reliable, so FEC has no loss to repair, bridge or not.
+ * 3. No multicast bridge: `no-multicast-bridge`. No lossy leg can exist, and on
+ *    `auto` this is the reason the session is on reliable MoQ.
+ * 4. The policy is `multicast-only`, or a lossy subscription is live: active.
+ *    `multicast-only` commits the session to the lossy leg, so FEC is in force
+ *    before the join completes; whether the join succeeded is the physical
+ *    attestation's question, not this one. The counters may be absent until
+ *    the decoder reports.
+ * 5. Otherwise (`auto`, a bridge, no live subscription): `reliable-moq`.
+ *
+ * Throws on malformed evidence rather than picking a reason for it.
+ */
+export function resolveFecState<S extends object>(evidence: FecStateEvidence<S> & { readonly stats: S }): FecState<S>
+export function resolveFecState<S extends object>(evidence: FecStateEvidence<S>): FecState<S | NoFecCounters>
+export function resolveFecState<S extends object>(evidence: FecStateEvidence<S>): FecState<S | NoFecCounters> {
+  const catalogFec = requireBoolean(evidence.catalogFec, 'catalogFec')
+  const bridgeAvailable = requireBoolean(evidence.bridgeAvailable, 'bridgeAvailable')
+  const multicastLegJoined = requireBoolean(evidence.multicastLegJoined, 'multicastLegJoined')
+  const { transportPolicy, stats } = evidence
+  if (typeof transportPolicy !== 'string' || !TRANSPORT_POLICIES.has(transportPolicy)) {
+    throw new TypeError(`resolveFecState: unsupported transportPolicy ${JSON.stringify(transportPolicy)}`)
+  }
+  if (stats !== null && stats !== undefined && recordOf(stats) === undefined) {
+    throw new TypeError('resolveFecState: stats must be a plain object, null or undefined')
+  }
+
+  if (!catalogFec) return INACTIVE['no-catalog-fec']
+  if (transportPolicy === 'moq-only') return INACTIVE['reliable-moq']
+  if (!bridgeAvailable) return INACTIVE['no-multicast-bridge']
+  if (transportPolicy === 'multicast-only' || multicastLegJoined) {
+    // The discriminant is written last so a stats field of the same name can
+    // never masquerade as a state.
+    return { ...(stats ?? {}), state: 'active' } as FecActiveState<S | NoFecCounters>
+  }
+  return INACTIVE['reliable-moq']
+}

package/src/fec-worker-setup.ts

@@ -0,0 +1,283 @@
+/**
+ * Shared fec-setup helper.
+ *
+ * Wires a FecWorkerClient into a MulticastManager for a specific track.
+ * Both moq-lib (`hang-mmt-fec/js/watch/src/element.ts`) and moqtail
+ * (`moqtail-private/apps/client-js/src/lib/player.ts`) call this from their
+ * SessionManager `fec-setup` handler so the Worker+ALTA setup lives in one
+ * place instead of being duplicated across ~80 lines per player.
+ *
+ * Callers are responsible for holding the returned `dispose()` and calling it
+ * from their `fec-teardown` path (and/or effect cleanup). It unregisters the
+ * Worker from MulticastManager before terminating it, so no symbol is routed
+ * to a dead Worker; do not dispose the client directly.
+ */
+
+import { parseFecBlockProfile, type FecBlockProfile } from '@blockcast/mmt-base'
+import type { FecWorkerClient, FecTrackConfig } from '@blockcast/fec-worker'
+import type { MulticastManager } from './multicast-manager.js'
+import { deriveFecRetentionBlocks } from '@blockcast/mmt-fec'
+import { computeFecDeliveryWindowMs } from './track-session.js'
+
+/** Asset URLs the helper needs. Callers pass the already-resolved set. */
+export interface FecWorkerAssetUrls {
+  /** URL to the fec-worker entry bundle (new Worker() target). */
+  fecWorker: string
+  /** URL to the RaptorQ WASM module (compiled via compileStreaming). */
+  rqWasm: string
+  /** URL to the ALTA WASM module. Fetched only when an ALTA key is provided. */
+  altaWasm: string
+}
+
+export interface FecWorkerSetupOptions {
+  /** MulticastManager that should receive the configured Worker. */
+  multicastManager: MulticastManager
+  /** MMTP packetId this track occupies (from catalog). */
+  packetId: number
+  /** Human-readable track name (catalog key). */
+  trackName: string
+  /** Track type from catalog. Never inferred from name. */
+  trackType: 'video' | 'audio'
+  /**
+   * The catalog `fec.blockProfile` (BLO-35597). Required: `k-padded-v1` or
+   * `iso-ssbg1-v1`; never defaulted, never inferred.
+   */
+  fecBlockProfile: FecBlockProfile
+  /** FEC K from catalog (source symbols per block). Under iso-ssbg1-v1 the maximum SSB_length. */
+  fecK: number
+  /** Symbol size in bytes (T) — the ALTA-adjusted value if ALTA is signed. */
+  fecSymbolSize: number
+  /** Repair symbols per block (P). */
+  fecRepairCount: number
+  /**
+   * Repair symbols per block this receiver actually joined: the sum of
+   * `repairSymbols` over the joined BASE layers (draft-ramadan-moq-fec 6.3).
+   * Reported as P by the worker snapshot and CMCD `x-bc-fec-p`, because the
+   * catalog total is not what this receiver joined. Falls back to
+   * `fecRepairCount`, which is the same value on a single-layer track.
+   */
+  joinedRepairCount?: number
+  /** Interleave depth in ms. */
+  fecInterleaveMs: number
+  /** Explicit catalog jitter/reorder allowance in ms. */
+  fecReorderToleranceMs?: number
+  /** Duration of one FEC media unit in ms (video frame or audio access unit). */
+  mediaUnitDurationMs: number
+  /** Optional repair track name (MoQ). Forwarded to FecTrackConfig. */
+  repairTrackName?: string
+  /** Audio sample rate (optional — audio tracks only). */
+  sampleRate?: number
+  /** Codec string (optional; "unknown" is acceptable for first setup). */
+  codec?: string
+  /** Video framerate (optional metadata forwarded to the worker). */
+  framerate?: number
+  /** Base64 SPKI public key (optional). Accepts padded/unpadded, std or url-safe alphabet. */
+  altaPublicKeySpki?: string
+  /** Absolute or origin-relative asset URLs. */
+  assetUrls: FecWorkerAssetUrls
+  /** Optional FecWorkerClient factory — main use is test injection. */
+  clientFactory?: (workerUrl: URL) => FecWorkerClient
+}
+
+export interface FecWorkerSetupResult {
+  /** The configured client (already registered with MulticastManager). */
+  client: FecWorkerClient
+  /** True when the ALTA public key decoded and the ALTA WASM compiled. */
+  altaEnabled: boolean
+  /** Removes the Worker from MulticastManager routing, then releases it. */
+  dispose: () => void
+}
+
+/**
+ * Configure a FecWorkerClient and attach it to `multicastManager` via
+ * `setFecWorker(packetId, client, trackType, config, trackName)`. Worker-path takes precedence
+ * over any sync WASM decoder already registered for the same packetId —
+ * sync decoders remain as a fallback.
+ *
+ * Any loader failure is re-thrown so the caller can log and leave the sync
+ * WASM decoder active as fallback (same pattern both players used before).
+ */
+export async function setupFecWorkerForTrack(
+  opts: FecWorkerSetupOptions,
+): Promise<FecWorkerSetupResult> {
+  // These two were previously validated as a side effect of calling
+  // deriveFecInterleaveDepth() here. That call is gone (see below), so the
+  // guards are explicit — a zero or non-finite span/media-unit must still fail
+  // closed rather than size a window from a hardcoded depth.
+  //
+  // `mediaUnitDurationMs` no longer influences the retention this function
+  // computes: it survives only as `mediaUnitsPerSecond`, which
+  // `computeFecDeliveryWindowMs` (track-session.ts) documents as geometry
+  // accepted for existing callers and deliberately not fed to deadline math.
+  // The guard stays anyway — this is a trust boundary for a catalog-supplied
+  // value, and the test `rejects missing media-unit timing instead of using a
+  // hardcoded depth` pins it. Not dead code. Cite both by symbol, not by line:
+  // a line number here is invalidated by the next edit to the file it points
+  // at, and this comment is the guard's only stated defence.
+  if (!Number.isFinite(opts.fecInterleaveMs) || opts.fecInterleaveMs <= 0) {
+    // Names the catalog field (`fec.interleaveDepthMs`), not the local option
+    // (`opts.fecInterleaveMs`), because that is the knob an operator fixes.
+    throw new Error(
+      `[FEC] interleaveDepthMs (opts.fecInterleaveMs) must be finite and > 0 ` +
+        `(got ${opts.fecInterleaveMs})`,
+    )
+  }
+  if (!Number.isFinite(opts.mediaUnitDurationMs) || opts.mediaUnitDurationMs <= 0) {
+    throw new Error(
+      `[FEC] mediaUnitDurationMs must be finite and > 0 (got ${opts.mediaUnitDurationMs})`,
+    )
+  }
+  const blockProfile = parseFecBlockProfile(
+    opts.fecBlockProfile,
+    `[FEC] ${opts.trackName} fec.blockProfile`,
+  )
+  const deliveryWindowMs = computeFecDeliveryWindowMs({
+    interleaveDepthMs: opts.fecInterleaveMs,
+    sourceSymbols: opts.fecK,
+    repairSymbols: opts.fecRepairCount,
+    symbolSize: opts.fecSymbolSize,
+    mediaUnitsPerSecond: 1000 / opts.mediaUnitDurationMs,
+    jitterBufferMs: opts.fecReorderToleranceMs,
+  })
+  // `FecTrackConfig.interleaveDepth` is a BLOCK COUNT, not D. Every consumer
+  // measures SBN distance with it: the worker's `advanceMediaHorizon` does
+  // `liveSbn - interleaveDepth`, and `MmtFecDecoder::new` documents its
+  // argument as "the number of interleaved blocks" before `cleanup_by_sbn`
+  // subtracts it from an SBN and counts the remainder `blocks_failed`.
+  //
+  // `deriveFecInterleaveDepth` returns D — MEDIA UNITS per block — so feeding
+  // it here mixed units and sized the retention window in the wrong quantity.
+  // It survived where D happened to land near the real block count and retired
+  // live blocks where it did not. Measured against the live ISS catalog at
+  // reorderToleranceMs=100, retention vs the block's own deadline (the worker
+  // arms `deadlineTs = now + deliveryWindowMs` per block):
+  //
+  //   720p  span 33ms  D=1 -> 2 blocks =  66ms  vs deadline 133ms  UNDER by 67ms
+  //   480p  span 67ms  D=2 -> 3 blocks = 201ms  vs deadline 167ms  ok
+  //   360p  span 67ms  D=2 -> 3 blocks = 201ms  vs deadline 167ms  ok
+  //   audio span 43ms  D=2 -> 3 blocks = 129ms  vs deadline 143ms  UNDER by 14ms
+  //
+  // 480p/360p passed only because D=2 coincided with a workable block count.
+  // On 720p and audio the decoder expired blocks — counting them failed — while
+  // the receiver's own deadline for them had not yet passed.
+  //
+  // Derive the count from the two quantities that define it, so retention
+  // always covers the deadline already armed for that block: the blocks that
+  // can be in flight within one block's budget, plus the one being filled.
+  //
+  // `deriveFecRetentionBlocks` is THE one derivation of this horizon -- the
+  // FECManager's ordered-relay settlement consumes the same function, so the
+  // two cannot drift apart again (BLO-35597 Decision E). It fails closed above
+  // the 255 the WASM decoder and the ISO/IEC 23008-1 AL-FEC signaling byte
+  // accept, rather than clamping to a retention shorter than this window.
+  const interleaveDepthBlocks = deriveFecRetentionBlocks(
+    deliveryWindowMs,
+    opts.fecInterleaveMs,
+  )
+  // Resolve URL against location.origin when available (browser runtime).
+  // Absolute URLs pass through unchanged per the URL() spec.
+  const origin =
+    typeof location !== 'undefined' && location.origin ? location.origin : 'http://localhost'
+  const workerUrl = new URL(opts.assetUrls.fecWorker, origin)
+
+  const FecWorkerCtor = await import('@blockcast/fec-worker')
+  const client = opts.clientFactory
+    ? opts.clientFactory(workerUrl)
+    : new FecWorkerCtor.FecWorkerClient(workerUrl)
+
+  // Compile RaptorQ WASM once; ALTA WASM only when we have a key to decode.
+  const rqWasm = await WebAssembly.compileStreaming(fetch(opts.assetUrls.rqWasm))
+
+  let altaKeyBuffer: ArrayBuffer | undefined
+  let altaWasmModule: WebAssembly.Module | undefined
+  if (opts.altaPublicKeySpki) {
+    const b64 = opts.altaPublicKeySpki.replace(/-/g, '+').replace(/_/g, '/')
+    const padded = b64.padEnd(Math.ceil(b64.length / 4) * 4, '=')
+    try {
+      const keyBytes = Uint8Array.from(atob(padded), c => c.charCodeAt(0))
+      // SPKI size range: Ed25519=44, P-256=91; tolerate 32..=256 for forward-compat.
+      if (keyBytes.length >= 32 && keyBytes.length <= 256) {
+        altaKeyBuffer = keyBytes.buffer
+        altaWasmModule = await WebAssembly.compileStreaming(fetch(opts.assetUrls.altaWasm))
+      } else {
+        console.warn(
+          `[fec-worker-setup] ALTA SPKI wrong length for "${opts.trackName}": ` +
+            `${keyBytes.length} (expected 32..256) — ALTA disabled`,
+        )
+      }
+    } catch (e) {
+      console.warn(`[fec-worker-setup] ALTA key decode / WASM compile failed for "${opts.trackName}":`, e)
+    }
+  }
+
+  const altaEnabled = !!(altaKeyBuffer && altaWasmModule)
+  const fecTrackConfig = {
+    codec: opts.codec ?? 'unknown',
+    trackName: opts.trackName,
+    trackType: opts.trackType,
+    framerate: opts.framerate,
+    sampleRate: opts.sampleRate,
+    algorithm: 'raptor',
+    blockProfile,
+    k: opts.fecK,
+    // P as this receiver joined it, not the catalog total: the worker snapshot
+    // and CMCD `x-bc-fec-p` are read from this. Identity on a single layer.
+    repairCount: opts.joinedRepairCount ?? opts.fecRepairCount,
+    symbolSize: opts.fecSymbolSize,
+    interleaveDepth: interleaveDepthBlocks,
+    interleaveMs: opts.fecInterleaveMs,
+    deliveryWindowMs,
+    fecMode: 'subframe' as const,
+    repairTrack: opts.repairTrackName,
+    altaEnabled,
+    relayBlockSigEnabled: false,
+  } as unknown as FecTrackConfig
+
+  client.configure(fecTrackConfig, rqWasm, altaKeyBuffer, altaWasmModule)
+  try {
+    opts.multicastManager.setFecWorker(opts.packetId, client, opts.trackType, {
+      blockProfile,
+      k: opts.fecK,
+      symbolSize: opts.fecSymbolSize,
+      interleaveDepthMs: opts.fecInterleaveMs,
+      // FEC timing is expressed in media units. For audio this is the access-unit
+      // cadence (for example 1024/48kHz), not a video-only framerate field.
+      fps: 1000 / opts.mediaUnitDurationMs,
+      timeoutMs: deliveryWindowMs,
+    }, opts.trackName)
+  } catch (e) {
+    // The manager refused the registration (for example the stream still
+    // routes to another Worker). The Worker this call created is not in
+    // routing and nothing else holds it, so release it before reporting.
+    try {
+      client.dispose()
+    } catch {
+      /* dispose errors are non-fatal */
+    }
+    throw e
+  }
+
+  let disposed = false
+  return {
+    client,
+    altaEnabled,
+    dispose: () => {
+      if (disposed) return
+      disposed = true
+      // Unregister first so no symbol is routed to a dead Worker between the
+      // dispose below and the manager noticing. A false return means the
+      // Worker was already gone from routing, which this helper never does on
+      // its own, so make that loud instead of leaving it to the next symbol.
+      if (!opts.multicastManager.clearFecWorker(opts.packetId, opts.trackName)) {
+        console.warn(
+          `[fec-worker-setup] packetId=${opts.packetId} track=${opts.trackName} Worker was not registered when disposed`,
+        )
+      }
+      try {
+        client.dispose()
+      } catch {
+        /* dispose errors are non-fatal */
+      }
+    },
+  }
+}

package/src/fmp4-completion.ts

@@ -0,0 +1,47 @@
+/**
+ * fMP4 data-unit completion policy (BLO-13291).
+ *
+ * FFmpeg's `mmt` muxer in fMP4-fragments mode (mfu_mode=0, mmtenc_fmp4.c
+ * send_media_fragment) delivers one complete moof+mdat (optionally
+ * sidx-prefixed) per MPU data unit, split across FI=1/2/3 MMTP fragments.
+ * Neither wire counter can prove the chain is byte-complete:
+ *
+ * - MPU payload header byte 3 is the eight-bit fragment counter. It proves
+ *   ordering, but cannot declare the total byte length of a fragmented DU.
+ * - Each fragment's payload_length bounds that packet only; it does not declare
+ *   the total size of the multi-packet fMP4 data unit.
+ * - packet_sequence_number has legitimate gaps: repair and signaling packets
+ *   consume sequence slots in the same flow at every FEC block boundary.
+ *
+ * The data unit is self-describing instead: ISOBMFF top-level box headers
+ * declare their 32-bit sizes. A candidate assembly is complete exactly when
+ * it parses as a whole number of known top-level boxes covering its full
+ * length. Any interior hole shifts subsequent box headers (type/size garbage)
+ * or leaves a declared size overrunning the buffer; missing tail bytes leave
+ * the final box short.
+ */
+
+/** Top-level box types the MMT fMP4 writers emit around a data unit. */
+const TOP_LEVEL_BOX_TYPES = new Set(['ftyp', 'styp', 'moov', 'moof', 'mdat', 'sidx', 'free', 'skip', 'prft', 'emsg'])
+
+/**
+ * True when `candidate` parses as one or more complete top-level ISOBMFF
+ * boxes covering exactly its byte length. size==0 ("to end of file") and
+ * size==1 (64-bit largesize) are treated as unverifiable and return false —
+ * the MMT muxers never emit them for streamed data units.
+ */
+export function isCompleteFmp4DataUnit(candidate: Uint8Array): boolean {
+  if (candidate.length < 8) return false
+  const dv = new DataView(candidate.buffer, candidate.byteOffset, candidate.byteLength)
+  let pos = 0
+  while (pos < candidate.length) {
+    if (pos + 8 > candidate.length) return false
+    const size = dv.getUint32(pos)
+    if (size < 8) return false
+    const type = String.fromCharCode(candidate[pos + 4]!, candidate[pos + 5]!, candidate[pos + 6]!, candidate[pos + 7]!)
+    if (!TOP_LEVEL_BOX_TYPES.has(type)) return false
+    if (pos + size > candidate.length) return false
+    pos += size
+  }
+  return pos === candidate.length
+}