@blockcast/mmt-container 0.3.0 → 0.4.0-main.d6f2737828fc

package/test-vectors/catalog-timing.json

@@ -0,0 +1,356 @@
+{
+  "$comment": [
+    "Canonical receiver vectors for catalog-derived FEC timing (BLO-45476).",
+    "Hand-authored; expect null = undefined, expect 'throws' = the value cannot be derived and must fail closed.",
+    "keyframeCadence, mediaUnitsPerSecond and groupDuration pin the neutral catalog rules native receiver adapters share (catalogKeyframeCadenceMs, catalogFecMediaUnitsPerSecond, catalogGroupDurationMs). They are NOT what libmmt's own receiver runs today: resolveCatalogTrackFec reads audio rate from sampleRate ?? samplerate (numeric strings admitted) with no endpoint or timescale fallback, so 'audio MP4-shaped timescale' resolves no rate there; computeBlockClassifierGeometry reads only keyframeInterval*. Converging those is a behaviour change, not part of this extraction.",
+    "deliveryWindow and trackFec run against libmmt's production paths (computeFecDeliveryWindowMs, resolveCatalogTrackFec), so an adapter that drops a catalog field (fec.reorderToleranceMs, say) fails here instead of in the field. An iso-ssbg1-v1 span that is 0 or absent keeps in-band geometry but supplies no elapsed-time deadline; local receiver retention remains bounded without inventing a catalog span.",
+    "interleaveDepth: every row names its D basis. 'access-unit' is what libmmt's receiver and the current publisher run today (D = round(span / (1000/framerate)), multicast-manager FecBlockMapper, fec-manager, block-policy); an adapter must match it to agree with them on block geometry. 'group' is draft-ramadan-moq-fec \u00a75.1/\u00a79 (D over the MoQ group duration); it is the target, not live, and moves only together with the producer contract (BLO-35597). Tick-only groupDurationTicks is authoritative for the group duration."
+  ],
+  "keyframeCadence": [
+    {
+      "name": "interval ticks win over every ms field",
+      "rendition": {
+        "timescale": 90000,
+        "keyframeIntervalTicks": 180000,
+        "keyframeIntervalMs": 1000,
+        "gopDurationMs": 500
+      },
+      "expect": 2000
+    },
+    {
+      "name": "ticks without a timescale fall through to ms",
+      "rendition": {
+        "keyframeIntervalTicks": 180000,
+        "keyframeIntervalMs": 1000
+      },
+      "expect": 1000
+    },
+    {
+      "name": "keyframe duration before GOP duration",
+      "rendition": {
+        "keyframeDurationMs": 1500,
+        "gopDurationMs": 500
+      },
+      "expect": 1500
+    },
+    {
+      "name": "GOP ticks",
+      "rendition": {
+        "timescale": 1000,
+        "gopDurationTicks": 2002
+      },
+      "expect": 2002
+    },
+    {
+      "name": "a group duration is not a keyframe cadence",
+      "rendition": {
+        "timescale": 90000,
+        "groupDurationTicks": 90000,
+        "groupDurationMs": 1000
+      },
+      "expect": null
+    },
+    {
+      "name": "non-positive values are not stated",
+      "rendition": {
+        "keyframeIntervalMs": 0,
+        "gopDurationMs": -1
+      },
+      "expect": null
+    }
+  ],
+  "mediaUnitsPerSecond": [
+    {
+      "name": "video framerate",
+      "type": "video",
+      "rendition": {
+        "framerate": 30,
+        "timescale": 90000
+      },
+      "expect": 30
+    },
+    {
+      "name": "video never reads its timescale",
+      "type": "video",
+      "rendition": {
+        "timescale": 90000
+      },
+      "expect": null
+    },
+    {
+      "name": "audio endpoint rate first",
+      "type": "audio",
+      "rendition": {
+        "sampleRate": 44100
+      },
+      "endpointSampleRate": 48000,
+      "expect": 46.875
+    },
+    {
+      "name": "audio catalog sampleRate",
+      "type": "audio",
+      "rendition": {
+        "sampleRate": 44100,
+        "timescale": 48000
+      },
+      "expect": 43.06640625
+    },
+    {
+      "name": "audio MP4-shaped timescale",
+      "type": "audio",
+      "rendition": {
+        "timescale": 48000
+      },
+      "expect": 46.875
+    },
+    {
+      "name": "a declared but unusable rate is not replaced",
+      "type": "audio",
+      "rendition": {
+        "sampleRate": 0,
+        "timescale": 48000
+      },
+      "expect": null
+    }
+  ],
+  "deliveryWindow": [
+    {
+      "name": "span plus the signaled reorder tolerance",
+      "fec": {
+        "interleaveDepthMs": 133,
+        "sourceSymbols": 32,
+        "reorderToleranceMs": 40
+      },
+      "expect": 173
+    },
+    {
+      "name": "fractional sum rounds up",
+      "fec": {
+        "interleaveDepthMs": 66.7,
+        "sourceSymbols": 8,
+        "reorderToleranceMs": 10.1
+      },
+      "expect": 77
+    },
+    {
+      "name": "a declared 0 tolerance adds nothing",
+      "fec": {
+        "interleaveDepthMs": 100,
+        "sourceSymbols": 8,
+        "reorderToleranceMs": 0
+      },
+      "expect": 100
+    },
+    {
+      "name": "absent tolerance stays absent",
+      "fec": {
+        "interleaveDepthMs": 100.2,
+        "sourceSymbols": 8
+      },
+      "expect": 101
+    },
+    {
+      "name": "K and P never widen the span",
+      "fec": {
+        "interleaveDepthMs": 100,
+        "sourceSymbols": 512,
+        "repairSymbols": 512,
+        "reorderToleranceMs": 20
+      },
+      "expect": 120
+    },
+    {
+      "name": "no span fails closed",
+      "fec": {
+        "sourceSymbols": 8,
+        "reorderToleranceMs": 20
+      },
+      "expect": "throws"
+    },
+    {
+      "name": "no K fails closed",
+      "fec": {
+        "interleaveDepthMs": 100,
+        "reorderToleranceMs": 20
+      },
+      "expect": "throws"
+    },
+    {
+      "name": "negative tolerance fails closed",
+      "fec": {
+        "interleaveDepthMs": 100,
+        "sourceSymbols": 8,
+        "reorderToleranceMs": -1
+      },
+      "expect": "throws"
+    }
+  ],
+  "groupDuration": [
+    {
+      "name": "tick-only group duration is authoritative",
+      "rendition": {
+        "timescale": 90000,
+        "groupDurationTicks": 90000
+      },
+      "expect": 1000
+    },
+    {
+      "name": "ticks win over a disagreeing ms field",
+      "rendition": {
+        "timescale": 90000,
+        "groupDurationTicks": 180000,
+        "groupDurationMs": 1000
+      },
+      "expect": 2000
+    },
+    {
+      "name": "ms-only group duration",
+      "rendition": {
+        "groupDurationMs": 1001
+      },
+      "expect": 1001
+    },
+    {
+      "name": "ticks without a timescale fall through to ms",
+      "rendition": {
+        "groupDurationTicks": 90000,
+        "groupDurationMs": 1000
+      },
+      "expect": 1000
+    },
+    {
+      "name": "nothing stated",
+      "rendition": {
+        "timescale": 90000
+      },
+      "expect": null
+    }
+  ],
+  "interleaveDepth": [
+    {
+      "name": "live basis: 30 fps access units, span 4000 ms -> D=120",
+      "basis": "access-unit",
+      "interleaveDepthMs": 4000,
+      "framerate": 30,
+      "expect": 120
+    },
+    {
+      "name": "draft basis: same stream over the 1000 ms group -> D=4 (target, BLO-35597)",
+      "basis": "group",
+      "interleaveDepthMs": 4000,
+      "groupDurationMs": 1000,
+      "expect": 4
+    },
+    {
+      "name": "NTSC group is exact (4004/1001 = 4)",
+      "basis": "group",
+      "interleaveDepthMs": 4004,
+      "groupDurationMs": 1001,
+      "expect": 4
+    },
+    {
+      "name": "exact half rounds up",
+      "basis": "group",
+      "interleaveDepthMs": 4500,
+      "groupDurationMs": 1000,
+      "expect": 5
+    },
+    {
+      "name": "just below half rounds down",
+      "basis": "group",
+      "interleaveDepthMs": 4499,
+      "groupDurationMs": 1000,
+      "expect": 4
+    },
+    {
+      "name": "zero span fails closed",
+      "basis": "group",
+      "interleaveDepthMs": 0,
+      "groupDurationMs": 1000,
+      "expect": "throws"
+    }
+  ],
+  "trackFec": [
+    {
+      "name": "positive span keeps FEC",
+      "fec": {
+        "interleaveDepthMs": 4000
+      },
+      "expect": {
+        "interleaveMs": 4000,
+        "unavailable": null
+      }
+    },
+    {
+      "name": "zero span: in-band FEC stays active without a deadline",
+      "fec": {
+        "interleaveDepthMs": 0
+      },
+      "expect": {
+        "interleaveMs": 0,
+        "unavailable": null
+      }
+    },
+    {
+      "name": "absent span: in-band FEC stays active without a default",
+      "fec": {},
+      "expect": {
+        "interleaveMs": 0,
+        "unavailable": null
+      }
+    },
+    {
+      "name": "one millisecond is a valid positive span",
+      "fec": {
+        "interleaveDepthMs": 1
+      },
+      "expect": {
+        "interleaveMs": 1,
+        "unavailable": null
+      }
+    },
+    {
+      "name": "negative span fails closed",
+      "fec": {
+        "interleaveDepthMs": -1
+      },
+      "expect": {
+        "interleaveMs": 0,
+        "unavailable": "track_fec"
+      }
+    },
+    {
+      "name": "fractional span fails closed",
+      "fec": {
+        "interleaveDepthMs": 1.5
+      },
+      "expect": {
+        "interleaveMs": 0,
+        "unavailable": "track_fec"
+      }
+    },
+    {
+      "name": "absent reorder tolerance stays absent",
+      "fec": {
+        "interleaveDepthMs": 4000
+      },
+      "expect": {
+        "interleaveMs": 4000,
+        "unavailable": null,
+        "reorderToleranceMs": null
+      }
+    },
+    {
+      "name": "explicit zero reorder tolerance is kept",
+      "fec": {
+        "interleaveDepthMs": 4000,
+        "reorderToleranceMs": 0
+      },
+      "expect": {
+        "interleaveMs": 4000,
+        "unavailable": null,
+        "reorderToleranceMs": 0
+      }
+    }
+  ]
+}

package/test-vectors/catalog-validation.json

@@ -21,7 +21,7 @@
             "groupDurationTicks": 360000,
             "fec": {
               "algorithm": "raptorq",
-              "blockProfile": "k-padded-v1",
+              "blockProfile": "iso-ssbg1-v1",
               "sourceSymbols": 32,
               "repairSymbols": 8,
               "symbolSize": 1320,
@@ -182,7 +182,7 @@
             "groupDurationMs": 4000,
             "fec": {
               "algorithm": "raptorq",
-              "blockProfile": "k-padded-v1",
+              "blockProfile": "iso-ssbg1-v1",
               "sourceSymbols": 32
             }
           }
@@ -247,7 +247,7 @@
     {
       "name": "unknown FEC block profile",
       "valid": false,
-      "error_code": "track_fec_block_profile",
+      "error_code": "track_fec_block_profile_unimplemented",
       "catalog": {
         "version": 1,
         "tracks": [
@@ -279,6 +279,41 @@
         ]
       }
     },
+    {
+      "name": "retired k-padded-v1 block profile",
+      "valid": false,
+      "error_code": "track_fec_block_profile_unimplemented",
+      "catalog": {
+        "version": 1,
+        "tracks": [
+          {
+            "name": "video",
+            "packaging": "mmtp",
+            "isLive": true,
+            "codec": "avc1.640028",
+            "mmtpMode": "mfu",
+            "timescale": 90000,
+            "groupDurationMs": 4000,
+            "groupDurationTicks": 360000,
+            "fec": {
+              "algorithm": "raptorq",
+              "blockProfile": "k-padded-v1",
+              "sourceSymbols": 32,
+              "repairSymbols": 8,
+              "symbolSize": 1320,
+              "interleaveDepthMs": 133,
+              "repairTrack": "video/repair"
+            }
+          },
+          {
+            "name": "video/repair",
+            "packaging": "fec-repair",
+            "isLive": true,
+            "priority": 240
+          }
+        ]
+      }
+    },
     {
       "name": "ISO ssbg_mode1 block profile",
       "valid": true,
@@ -316,7 +351,7 @@
     {
       "name": "disabled FEC with an unknown block profile",
       "valid": false,
-      "error_code": "track_fec_block_profile",
+      "error_code": "track_fec_block_profile_unimplemented",
       "catalog": {
         "version": 1,
         "tracks": [
@@ -435,7 +470,7 @@
             "groupDurationMs": 1000,
             "fec": {
               "algorithm": "raptorq",
-              "blockProfile": "k-padded-v1",
+              "blockProfile": "iso-ssbg1-v1",
               "sourceSymbols": 32,
               "repairSymbols": 8,
               "symbolSize": 1320,

package/node_modules/@blockcast/fec-worker/README.md

@@ -1,223 +0,0 @@
-# @blockcast/fec-worker
-
-A Web Worker wrapper around `@blockcast/mmt-fec` that moves the RaptorQ decode off the main thread. The main-thread client posts source and repair symbols to a dedicated worker via `postMessage` with `Transferable` `ArrayBuffer` ownership transfer, so packet payloads cross the thread boundary with **zero copies**. Decoded / FEC-recovered frames travel back the same way. Critical for IWA / web players where main-thread blocking on FEC decode would cause frame drops at the renderer.
-
-## Install
-
-```bash
-pnpm add @blockcast/fec-worker
-```
-
-The package is dual-shaped: the main-thread side (`FecWorkerClient`, types) is the default export; the worker entry is exposed as the `./worker` subpath so consumers can hand its URL to `new Worker(...)` (or to the `FecWorkerClient` constructor, which spawns it for you).
-
-## Quick start
-
-```ts
-import { FecWorkerClient, type FecTrackConfig } from "@blockcast/fec-worker"
-
-// Worker URL resolved against your bundler. ?worker / new URL() / import.meta —
-// any pattern that gives you a module-Worker URL works.
-const workerUrl = new URL("./fec-worker-entry.js", import.meta.url)
-
-const client = new FecWorkerClient(workerUrl)
-
-client.onFrame((data, meta) => {
-  // data is an ArrayBuffer transferred from the worker (zero-copy).
-  // meta tells you whether this frame was recovered via FEC and (if ALTA is
-  // configured) whether its source-packet trailer verified.
-  decoder.decode(data) // hand off to WebCodecs / MSE
-})
-client.onSnapshot((stats) => fecPanel.render(stats))
-client.onError((msg) => console.error("[fec]", msg))
-
-// Configure with a pre-compiled mmt-wasm Module from your loader's importmap.
-const config: FecTrackConfig = {
-  codec: "avc1.64001f",
-  trackName: "video/base",
-  trackType: "video",
-  resolution: { w: 1920, h: 1080 },
-  framerate: 30,
-  algorithm: "raptor",
-  blockProfile: "k-padded-v1", // catalog fec.blockProfile: required, never defaulted
-  k: 32, // under "iso-ssbg1-v1", the maximum SSB_length
-  repairCount: 8,
-  symbolSize: 1312,
-  interleaveDepth: 30,
-  interleaveMs: 1000, // 30 frames @ 30 fps
-  deliveryWindowMs: 2000, // computeFecDeliveryWindowMs(...) from the catalog
-  fecMode: "subframe",
-  altaEnabled: false,
-  relayBlockSigEnabled: false,
-}
-client.configure(config, mmtWasmModule)
-
-// Feed packets as they arrive from transport. ArrayBuffers are transferred —
-// caller MUST NOT touch `data` after the call.
-client.feedSource(ssId, packetBuffer, captureTs)
-client.feedRepair(ssStart, ssbLength, rsId, repairBuffer, captureTs)
-```
-
-`FecWorkerClient` accepts either a `URL` (it spawns the worker for you with `{ type: "module" }`) or a pre-created `Worker` instance (used in tests for constructor injection).
-
-## Why a Worker
-
-A 1080p30 stream with `K=32, P=8, symbolSize=1312` produces ~1 RaptorQ source-block decode every second per track. Decode time is amortized across SIMD lanes inside the WASM, but the *worst-case* block — one with the maximum recoverable loss pattern — can spike past 16 ms. Run that on the main thread and you've blown a frame; the renderer drops, the user sees a stutter, and CMCD reports a pacing violation.
-
-Pushing the decode into a dedicated Worker keeps the main thread free for input handling, MSE buffer maintenance, and frame pacing. The same module compiled into both contexts decodes identically; what changes is who's blocked when a worst-case block hits.
-
-This is the **Worker-per-track FEC pipeline** architectural decision tracked in the parent monorepo as a v2.0 milestone (`pim-multicast-gateway/.planning/MILESTONES.md` — "Worker-per-track FEC pipeline with zero-copy ArrayBuffer transfers"). Each track (base / delta / repair / audio) runs in its own Worker, so a stall on one track's decode never starves the others.
-
-## Architecture
-
-```
-   Main thread                              │   FEC Worker (per track)
-                                            │
-   transport packet                         │
-        │                                   │
-        ▼                                   │
-   FecWorkerClient.feedSource(...)          │
-        │                                   │
-        │  postMessage(cmd, [data, ...])    │
-        │   ─ data: ArrayBuffer (transferred, neutered on sender)
-        │   ─ wasmModule: WebAssembly.Module (structured-cloned)
-        ├──────────────────────────────────►│  self.onmessage
-        │                                   │       │
-        │                                   │       ▼
-        │                                   │  WasmFecDecoder.add_source(...)
-        │                                   │       │
-        │                                   │       ▼  (recovered or pass-through)
-        │                                   │  postMessage({type:"frame", data}, [data])
-        │◄──────────────────────────────────┤
-        │                                   │
-        ▼                                   │
-   FecWorkerClient.onFrame(data, meta)      │
-        │                                   │
-        ▼                                   │
-   WebCodecs / MSE                          │
-```
-
-Buffers cross the boundary via the `Transferable` list. After `postMessage`, the sender's `ArrayBuffer` is detached — touching it throws. This is the contract that makes zero-copy safe: there is no aliased view that could be mutated mid-decode.
-
-`WebAssembly.Module` is structured-cloneable (not transferable) and is *cloned* (cheap — the underlying compiled module is shared across realms). The ALTA public key, on the other hand, is a regular `ArrayBuffer` and *is* transferred.
-
-Errors that escape the worker's `try/catch` (in either the sync command path or the async configure path) are emitted as `{type: "error", message}` events rather than thrown — the main thread surfaces them through `onError`.
-
-## Message protocol
-
-All messages are typed as discriminated unions in `fec-worker-types.ts`. Both the worker and the client import the same definitions, so adding a message variant is a single-file change that the compiler enforces on both sides.
-
-### Inbound — `FecWorkerCommand` (main → worker)
-
-| `type` | Payload | Transferred |
-|--------|---------|-------------|
-| `configure` | `config: FecTrackConfig`, `wasmModule: WebAssembly.Module`, `altaPublicKey?: ArrayBuffer`, `altaWasmModule?: WebAssembly.Module` | `altaPublicKey` only — WASM modules are structured-cloned |
-| `feedSource` | `ssId: number`, `data: ArrayBuffer`, `ts: number`, optional `altaAuth: ArrayBuffer` + `altaPayloadEnd: number` | `data` and `altaAuth` |
-| `feedRepair` | `ssStart: number`, `ssbLength: number`, `rsId: number`, `data: ArrayBuffer`, `ts: number` | `data` |
-| `relayBlockSig` | `sbn: number`, `sig: ArrayBuffer`, `hash: ArrayBuffer` | `sig`, `hash` |
-| `cleanup` | `sbns: number[]` (all timed-out blocks covered by this coalesced barrier) | none |
-| `subscribeBlockUpdates` | — (send only after `capabilities` lists it) | none |
-| `dispose` | — | none |
-
-`feedSource` carries the **flat 32-bit Source Symbol ID** from the MMTP Source FEC Payload ID (ISO 23008-1 §C.5.2). The WASM decoder derives `SBN = floor(ssId / K)` and `ESI = ssId % K` internally — do not pre-compute these.
-
-`feedRepair` carries the wire-level Repair FEC Payload ID fields directly (ISO 23008-1 §C.5.3): `ssStart` is the SS_ID of the first source symbol in the block (`SBN * configured K`), `ssbLength` is the authored source-symbol count in `1..configured K`, and `rsId` is the repair index within the block. The decoder's block geometry and repair ESI use the configured K; K is never inferred from repair traffic.
-
-### Outbound — `FecWorkerEvent` (worker → main)
-
-| `type` | Payload | Transferred back |
-|--------|---------|------------------|
-| `frame` | `data: ArrayBuffer`, `meta: FrameMeta` | `data` |
-| `snapshot` | `stats: FecTrackStats` | none (structured clone) |
-| `capabilities` | `commands: FecWorkerOptionalCommand[]` (after `configure`) | none |
-| `blockUpdate` | `block: FecBlockSnapshot` (only after `subscribeBlockUpdates`) | none |
-| `cleanupComplete` | `sbns: number[]` | none |
-| `error` | `message: string` | none |
-
-The Worker posts `blockUpdate` only to a client that sent `subscribeBlockUpdates`: each one is a structured clone and a page-thread task, and the snapshot already counts every transition. `FecWorkerClient` subscribes when `onBlockUpdate` is registered and the Worker has announced the command. A Worker that predates the command posts `blockUpdate` unasked and is never sent it (BLO-36599).
-
-`FrameMeta` carries `recovered: boolean` (this frame came out of the FEC decode, not the direct path), `sbn: number`, and `altaVerified: boolean | null` (signature outcome, or `null` when ALTA is not configured / verification is pending).
-
-## Lifecycle
-
-```
-new FecWorkerClient(url)
-        │  worker spawned with { type: "module" }
-        ▼
-client.configure(config, wasmModule [, altaPublicKey, altaWasmModule])
-        │  worker initSyncs WASM, instantiates MmtFecDecoder(interleaveDepth, blockProfile),
-        │  refuses a decoder whose get_block_profile() differs,
-        │  immediately configures exact catalog K/T (no decoder defaults),
-        │  derives pendingVerifyCap = ceil(D × 1.5) and TTL = ceil(K × interleaveMs × 1.5)
-        │  from catalog values, throws if any of K / D / interleaveMs ≤ 0,
-        │  starts the 200 ms snapshot timer, emits initial snapshot
-        ▼
-client.feedSource(...) / feedRepair(...)         ◄── steady state
-        │  every transferred ArrayBuffer detaches on the main thread
-        │  decoded / recovered frames flow back as {type:"frame"}
-        │  every 200 ms a {type:"snapshot"} carries FecTrackStats
-        ▼
-client.cleanup(sbn)                              ◄── per-block inactivity deadline
-        │  coalesces queued SBNs behind one worker queue-drain barrier
-        │  evicts blocks relative to max(sbns) − D × 3
-        │  retires exactly those SBNs via WASM cleanup_blocks_detailed(); a lost
-        │  block is never answered with a synthesised frame (sinks hold the last
-        │  good frame, per @blockcast/mmt-container conceal-timeline)
-        │  acknowledges every SBN in {type:"cleanupComplete", sbns}
-        │  any block still in "collecting" at eviction time is counted as failed
-        ▼
-client.dispose()
-           sends {type:"dispose"}, terminates worker. WASM decoder and ALTA
-           verifier are explicitly free()'d before terminate so their linear
-           memory is released (FinalizationRegistry would not run between
-           dispose and terminate). Idempotent.
-```
-
-### Backpressure
-
-`postMessage` is fire-and-forget at the JS level — there is no built-in flow control. If the main thread can't drain `frame` events fast enough, the worker's outbound queue grows. The remedy is upstream of this package: pace your input (`feedSource` / `feedRepair`) against actual decode capacity by watching the `avgRecoveryMs` / `maxRecoveryMs` fields of each `snapshot`. Spikes in `maxRecoveryMs` past your frame budget are the early signal.
-
-## Stats
-
-The `snapshot` event delivers a `FecTrackStats` every 200 ms (catalog-derived; not configurable from this layer). Key fields:
-
-| Field | Meaning |
-|-------|---------|
-| `sourceSymbols`, `repairSymbols` | Raw ingress counters |
-| `blocksComplete` | Block had all K source symbols without needing repair |
-| `blocksRecovered` | Block was recovered using ≥1 repair symbol |
-| `blocksFailed` | Block aged out before reaching K |
-| `recoveryRate` | `recovered / (recovered + failed)`, 0–100 |
-| `avgRecoveryMs`, `maxRecoveryMs` | Rolling decode latency (capped at 1000 samples) |
-| `liveSbn` | Highest source-block number observed |
-| `repairSymbolSizeMismatch` | Repair symbols rejected before WASM because their byte length did not match `T` |
-| `sourceDroppedRetired` / `sourceDroppedTerminal` / `sourceDroppedDuplicate` | Source symbols dropped before WASM, by **first matching** cause (see below) |
-| `blocks` | Up to `max(D × 3, 24)` recent `FecBlockSnapshot`s for live visualization |
-| `interleaveWindowBlocks` | `D` from config |
-
-The three `sourceDropped*` counters split by cause for the same reason the ALTA four-way split exists — so a dashboard can tell the failure modes apart. They are tested in a fixed order, each returning early — `Retired` → `Terminal` → `Duplicate` — so a symbol counts once, under the **first** cause that matches: a symbol that is both past retention and a repeat counts only as `Retired`, and `Terminal` absorbs every post-settle duplicate. A block that settles at K-1 source symbols (BLO-35597 defect 2) is explained by a late symbol past retention (`Retired`), a symbol for a block that had already settled — complete, recovered **or failed** (`Terminal`), or a repeated `(SBN, ESI)` (`Duplicate`). `Retired` and `Terminal` narrow the cause; they do not attribute it. `Duplicate` does: it cannot fire once a block settles — the `Terminal` check returns first, and `markBlockTerminal` retires the block's accepted-ESI set anyway — so a non-zero `Duplicate` is positive evidence that a repeated `(SBN, ESI)` reached the worker while the block was **still collecting** — usually a duplicate packet on the wire, sometimes an SBN/ESI derivation collision. It attributes the **timing**, not the origin. A symbol lost in transit never reaches the worker and increments nothing, so **all three reading zero is not evidence of a publisher defect** — wire loss produces an identical shape. Separate those with `FecBlockSnapshot.ssbLength`: below `k` is a genuinely short authored block, equal to `k` with fewer accepted is loss-or-late, undefined (no repair symbol yet) leaves both open. All three are cumulative across decoder epochs, so they stay comparable against the `sourceSymbols` denominator; only a reset zeroes them.
-
-When ALTA is enabled, the snapshot also carries the four-state verification accounting — `altaVerified` (crypto passed), `altaFailed` (tamper-confirmed), `altaPending` (unverifiable, e.g. missing trailer / late-joiner anchor gap), `altaError` (verifier threw — infrastructure flake, not tamper) — plus `altaInitFailed` (true if the ALTA WASM didn't initialize), `altaPendingEvictedCap` / `altaPendingEvictedTtl` (deferred-queue eviction reasons), and a bounded `altaFailedDetails[]` ring with the last ≤16 tamper events. The four-way split exists so ops alerting can distinguish a network problem (`altaPending` rising) from an attack (`altaFailed` rising) from a runtime bug (`altaError` rising).
-
-`FecTrackStats` is also the shape consumed downstream by `@blockcast/mmt-container`'s `CmcdProducer` and the diagnostics `fec-panel` — keep it stable when you extend it.
-
-## Related packages
-
-- **`@blockcast/mmt-fec`** — the wrapped library. Container-agnostic RaptorQ decoder + block manager + reorder buffer. Lives on the main thread when you don't need a Worker; this package is the off-thread variant of the same decoder.
-- **`@blockcast/mmt-container`** — the consumer that wires this Worker into the data path. `FecManager` instantiates one `FecWorkerClient` per track, routes MMTP source/repair payloads in, and pumps recovered frames into the MFU reassembler / fmp4 segmenter.
-- **`@blockcast/mmt-alta-parse`** — ALTA trailer extraction. Used inside the Worker to parse the `[0xF0A1][len][auth]` trailer off recovered source symbols (publisher-stripped trailers don't appear on direct-source packets, which carry the trailer in band).
-
-## Testing
-
-```bash
-pnpm test           # vitest run
-pnpm test:watch     # vitest in watch mode
-pnpm typecheck      # tsc --noEmit
-```
-
-Tests cover:
-- The message-protocol type narrowing (`fec-worker-types.test.ts`)
-- The main-thread client's transfer-list construction, callback dispatch, and dispose idempotence (`fec-worker-client.test.ts`) — the Worker is injected via constructor as a stub so the tests don't need a real WASM build
-
-## License
-
-Apache-2.0 — see `LICENSE`.