@blockcast/mmt-container 0.1.0 → 0.3.0

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

@@ -0,0 +1,223 @@
+# @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`.

package/node_modules/@blockcast/fec-worker/dist/block-order.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Order of K-stride FEC blocks on the 32-bit SS_ID (ISO/IEC 23008-1:2023
+ * C.5.2; RFC 1982 serial arithmetic, SERIAL_BITS = 32; BLO-35597 iso:5).
+ *
+ * Block `sbn` starts at SS_ID `sbn * K mod 2^32`, and blocks are ordered by
+ * serial comparison of their starts. That is identical to comparing SBNs
+ * with < for any two blocks less than 2^31 SS_IDs apart, so only the order
+ * across the SS_ID wrap changes.
+ *
+ * The canonical helpers are @blockcast/mmt-base `kStrideBlockPrecedes` /
+ * `kStrideBlocksBehind`. This worker bundle does not depend on mmt-base, so
+ * it carries these two, and block-order.test.ts pins them to the same wrap
+ * vectors.
+ */
+/** Whether block `a` precedes block `b`. */
+export declare function blockPrecedes(a: number, b: number, k: number): boolean;
+/**
+ * How many blocks `a` lies behind `b`: 0 unless `a` precedes `b`. Across the
+ * wrap the short pre-wrap block (2^32 mod K symbols) counts as one block.
+ */
+export declare function blocksBehind(a: number, b: number, k: number): number;
+/** Forward RFC 1982 distance from `from` to `to` on the 32-bit SS_ID, in 0..2^32-1. */
+export declare function serialDistance(from: number, to: number): number;
+/** Whether `a` precedes `b` under RFC 1982 serial comparison (SERIAL_BITS = 32). */
+export declare function serialPrecedes(a: number, b: number): boolean;
+/** Whether `ssId` is one of the `ssbLength` consecutive SS_IDs starting at `ssStart`, mod 2^32. */
+export declare function isoBlockContains(ssStart: number, ssbLength: number, ssId: number): boolean;
+/** Whether two SS_ID ranges `[start, start + length)` share any SS_ID, mod 2^32. */
+export declare function isoBlocksOverlap(aStart: number, aLength: number, bStart: number, bLength: number): boolean;
+/**
+ * How many blocks SS_ID `a` lies behind SS_ID `b` (0 unless `a` precedes `b`):
+ * a lower bound, because an iso-ssbg1-v1 block holds at most `kMax` source
+ * symbols, so `n * kMax` SS_IDs always span at least `n` blocks. This is the
+ * one interleave-horizon metric every ISO receiver layer shares (decoder
+ * retention, worker retirement, ordered-relay settlement).
+ */
+export declare function isoBlocksBehind(a: number, b: number, kMax: number): number;
+//# sourceMappingURL=block-order.d.ts.map

package/node_modules/@blockcast/fec-worker/dist/block-order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-order.d.ts","sourceRoot":"","sources":["../src/block-order.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAgBH,4CAA4C;AAC5C,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAEtE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAGpE;AAaD,uFAAuF;AACvF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAG5D;AAED,mGAAmG;AACnG,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1F;AAED,oFAAoF;AACpF,wBAAgB,gBAAgB,CAC/B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACb,OAAO,CAET;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAK1E"}

package/node_modules/@blockcast/fec-worker/dist/block-order.js

@@ -0,0 +1,78 @@
+/**
+ * Order of K-stride FEC blocks on the 32-bit SS_ID (ISO/IEC 23008-1:2023
+ * C.5.2; RFC 1982 serial arithmetic, SERIAL_BITS = 32; BLO-35597 iso:5).
+ *
+ * Block `sbn` starts at SS_ID `sbn * K mod 2^32`, and blocks are ordered by
+ * serial comparison of their starts. That is identical to comparing SBNs
+ * with < for any two blocks less than 2^31 SS_IDs apart, so only the order
+ * across the SS_ID wrap changes.
+ *
+ * The canonical helpers are @blockcast/mmt-base `kStrideBlockPrecedes` /
+ * `kStrideBlocksBehind`. This worker bundle does not depend on mmt-base, so
+ * it carries these two, and block-order.test.ts pins them to the same wrap
+ * vectors.
+ */
+const SPAN = 0x1_0000_0000;
+const HALF = 0x8000_0000;
+function blockStart(sbn, k) {
+    // sbn < 2^32 and k <= 56 403 keep the product below 2^48: exact.
+    return (sbn * k) % SPAN;
+}
+/** Forward SS_ID distance from block `a`'s start to block `b`'s, or null when `a` does not precede `b`. */
+function precedingDistance(a, b, k) {
+    const distance = (blockStart(b, k) - blockStart(a, k) + SPAN) % SPAN;
+    return distance !== 0 && distance < HALF ? distance : null;
+}
+/** Whether block `a` precedes block `b`. */
+export function blockPrecedes(a, b, k) {
+    return precedingDistance(a, b, k) !== null;
+}
+/**
+ * How many blocks `a` lies behind `b`: 0 unless `a` precedes `b`. Across the
+ * wrap the short pre-wrap block (2^32 mod K symbols) counts as one block.
+ */
+export function blocksBehind(a, b, k) {
+    const distance = precedingDistance(a, b, k);
+    return distance === null ? 0 : Math.ceil(distance / k);
+}
+// --- iso-ssbg1-v1 (ISO/IEC 23008-1 C.3.3 ssbg_mode1; C.5.2/C.5.3) ---------
+//
+// Under the ISO profile SS_ID increments by one per FEC source packet and
+// wraps at 2^32, and a block is the SSB_length consecutive SS_IDs
+// `[SS_Start, SS_Start + SSB_length)`. Blocks are keyed and ordered by their
+// SS_Start, never by an SBN derived from K: the catalog K is only the maximum
+// block length (kMax). The canonical helpers are @blockcast/mmt-base
+// `serial32Distance` / `serial32Precedes` / `isoBlockContains` /
+// `isoBlocksBehindLowerBound`; this bundle carries its own copies (it does not
+// depend on mmt-base), and block-order.test.ts pins them to the same vectors.
+/** Forward RFC 1982 distance from `from` to `to` on the 32-bit SS_ID, in 0..2^32-1. */
+export function serialDistance(from, to) {
+    return (to - from + SPAN) % SPAN;
+}
+/** Whether `a` precedes `b` under RFC 1982 serial comparison (SERIAL_BITS = 32). */
+export function serialPrecedes(a, b) {
+    const distance = serialDistance(a, b);
+    return distance !== 0 && distance < HALF;
+}
+/** Whether `ssId` is one of the `ssbLength` consecutive SS_IDs starting at `ssStart`, mod 2^32. */
+export function isoBlockContains(ssStart, ssbLength, ssId) {
+    return serialDistance(ssStart, ssId) < ssbLength;
+}
+/** Whether two SS_ID ranges `[start, start + length)` share any SS_ID, mod 2^32. */
+export function isoBlocksOverlap(aStart, aLength, bStart, bLength) {
+    return isoBlockContains(aStart, aLength, bStart) || isoBlockContains(bStart, bLength, aStart);
+}
+/**
+ * How many blocks SS_ID `a` lies behind SS_ID `b` (0 unless `a` precedes `b`):
+ * a lower bound, because an iso-ssbg1-v1 block holds at most `kMax` source
+ * symbols, so `n * kMax` SS_IDs always span at least `n` blocks. This is the
+ * one interleave-horizon metric every ISO receiver layer shares (decoder
+ * retention, worker retirement, ordered-relay settlement).
+ */
+export function isoBlocksBehind(a, b, kMax) {
+    if (!Number.isSafeInteger(kMax) || kMax <= 0) {
+        throw new Error(`iso-ssbg1-v1 block horizon needs a positive maximum K (got ${kMax})`);
+    }
+    return serialPrecedes(a, b) ? Math.floor(serialDistance(a, b) / kMax) : 0;
+}
+//# sourceMappingURL=block-order.js.map

package/node_modules/@blockcast/fec-worker/dist/block-order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-order.js","sourceRoot":"","sources":["../src/block-order.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,IAAI,GAAG,aAAa,CAAC;AAC3B,MAAM,IAAI,GAAG,WAAW,CAAC;AAEzB,SAAS,UAAU,CAAC,GAAW,EAAE,CAAS;IACzC,iEAAiE;IACjE,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC;AACzB,CAAC;AAED,2GAA2G;AAC3G,SAAS,iBAAiB,CAAC,CAAS,EAAE,CAAS,EAAE,CAAS;IACzD,MAAM,QAAQ,GAAG,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IACrE,OAAO,QAAQ,KAAK,CAAC,IAAI,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5D,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,aAAa,CAAC,CAAS,EAAE,CAAS,EAAE,CAAS;IAC5D,OAAO,iBAAiB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,CAAS,EAAE,CAAS,EAAE,CAAS;IAC3D,MAAM,QAAQ,GAAG,iBAAiB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5C,OAAO,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC;AACxD,CAAC;AAED,6EAA6E;AAC7E,EAAE;AACF,0EAA0E;AAC1E,kEAAkE;AAClE,6EAA6E;AAC7E,8EAA8E;AAC9E,qEAAqE;AACrE,iEAAiE;AACjE,+EAA+E;AAC/E,8EAA8E;AAE9E,uFAAuF;AACvF,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,EAAU;IACtD,OAAO,CAAC,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;AAClC,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,cAAc,CAAC,CAAS,EAAE,CAAS;IAClD,MAAM,QAAQ,GAAG,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACtC,OAAO,QAAQ,KAAK,CAAC,IAAI,QAAQ,GAAG,IAAI,CAAC;AAC1C,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,SAAiB,EAAE,IAAY;IAChF,OAAO,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,SAAS,CAAC;AAClD,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,gBAAgB,CAC/B,MAAc,EACd,OAAe,EACf,MAAc,EACd,OAAe;IAEf,OAAO,gBAAgB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,gBAAgB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AAC/F,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,CAAS,EAAE,CAAS,EAAE,IAAY;IACjE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CAAC,8DAA8D,IAAI,GAAG,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC3E,CAAC"}

package/node_modules/@blockcast/fec-worker/dist/fec-worker-client.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @blockcast/fec-worker — Main-Thread Client
+ *
+ * Wraps one Worker per track instance. Provides typed API for the
+ * FecWorkerCommand/FecWorkerEvent protocol with zero-copy ArrayBuffer transfers.
+ *
+ * Constructor accepts either a URL (creates Worker internally) or a pre-created
+ * Worker instance (for testing via constructor injection).
+ */
+import type { FecTrackConfig, FecTrackStats, FecBlockSnapshot, FrameMeta, FecWorkerErrorCode } from "./fec-worker-types.js";
+export declare class FecWorkerClient {
+    #private;
+    /**
+     * Create a FecWorkerClient.
+     * @param workerOrUrl - Either a Worker instance (for testing) or a URL to create one
+     */
+    constructor(workerOrUrl: Worker | URL);
+    /**
+     * Configure the Worker with FEC parameters and WASM module.
+     * wasmModule is transferred (not neutered — WebAssembly.Module is shareable).
+     * altaPublicKey is PKCS#8 SPKI DER bytes (self-describing — algorithm detected from OID).
+     *   Transferred (detached from sender).
+     * altaWasmModule is structured-cloneable (NOT transferable — do not add to transfer list).
+     */
+    configure(config: FecTrackConfig, wasmModule: WebAssembly.Module, altaPublicKey?: ArrayBuffer, altaWasmModule?: WebAssembly.Module): void;
+    /**
+     * Feed a source symbol to the Worker. data ArrayBuffer is transferred (zero-copy).
+     * Caller must not access data after this call — it is transferred with the
+     * task's symbol batch, before any later command of this client.
+     *
+     * Optional `alta` carries the detached ALTA authenticator bytes and the
+     * byte offset in `data` where the signed payload ends. The auth buffer is
+     * transferred zero-copy alongside `data`. Use {@link getMmtpAltaTrailer}
+     * upstream (mmtp-router) to extract it from the wire packet.
+     */
+    feedSource(ssId: number, data: ArrayBuffer, ts: number, alta?: {
+        auth: ArrayBuffer;
+        payloadEnd: number;
+    }): void;
+    /**
+     * Feed a repair symbol to the Worker. data ArrayBuffer is transferred (zero-copy).
+     * Caller must not access data after this call — it is detached.
+     *
+     * Carries the wire-level Repair FEC Payload ID fields (ISO 23008-1 §C.5.3):
+     * - ssStart:   SS_ID of first source symbol in the block (= SBN * configured K
+     *              under `k-padded-v1`; any uint32, the block key, under `iso-ssbg1-v1`)
+     * - ssbLength: authored source-symbol count (1..configured K)
+     * - rsId:      repair symbol index within the block
+     */
+    feedRepair(ssStart: number, ssbLength: number, rsId: number, data: ArrayBuffer, ts: number): void;
+    /**
+     * Submit relay block signature for verification. sig and hash are transferred.
+     */
+    relayBlockSig(sbn: number, sig: ArrayBuffer, hash: ArrayBuffer): void;
+    /**
+     * Trigger cleanup after a block's inactivity deadline. `currentSbn` is the
+     * block key: the SBN under `k-padded-v1`, the SS_Start under `iso-ssbg1-v1`.
+     *
+     * While one queue-drain barrier is in flight, later SBNs are coalesced into
+     * the next command without losing their individual acknowledgement identity.
+     */
+    cleanup(currentSbn: number): void;
+    /** Reset this track's decoder epoch while preserving Worker configuration. */
+    reset(): void;
+    /** Register callback for decoded/recovered frames (FEC-03). */
+    onFrame(cb: (data: ArrayBuffer, meta: FrameMeta) => void): void;
+    /** Register callback for periodic stats snapshots (FEC-04). */
+    onSnapshot(cb: (stats: FecTrackStats) => void): void;
+    /**
+     * Register callback for individual block state changes. The Worker posts
+     * them only once asked, so registering subscribes (after the Worker
+     * announces `subscribeBlockUpdates`). An older Worker that does not
+     * announce it posts them unasked.
+     */
+    onBlockUpdate(cb: (block: FecBlockSnapshot) => void): void;
+    /** Register callback fired after the Worker drains all commands queued before cleanup. */
+    onCleanupComplete(cb: (sbn: number) => void): void;
+    /** Register callback for Worker errors. */
+    onError(cb: (message: string, code?: FecWorkerErrorCode) => void): void;
+    /**
+     * True once dispose() ran. A disposed client cannot decode, fill, or
+     * acknowledge anything, so routing symbols to it discards them; every
+     * command method (feedSource, feedRepair, relayBlockSig, cleanup, reset)
+     * throws rather than pretend otherwise. Callers check this first.
+     */
+    get disposed(): boolean;
+    /**
+     * Dispose the Worker. Sends dispose command then terminates.
+     * Idempotent — safe to call multiple times.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=fec-worker-client.d.ts.map

package/node_modules/@blockcast/fec-worker/dist/fec-worker-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fec-worker-client.d.ts","sourceRoot":"","sources":["../src/fec-worker-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAIX,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,SAAS,EACT,kBAAkB,EAClB,MAAM,uBAAuB,CAAC;AAE/B,qBAAa,eAAe;;IA2B3B;;;OAGG;gBACS,WAAW,EAAE,MAAM,GAAG,GAAG;IAgBrC;;;;;;OAMG;IACH,SAAS,CACR,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,WAAW,CAAC,MAAM,EAC9B,aAAa,CAAC,EAAE,WAAW,EAC3B,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,GACjC,IAAI;IAmBP;;;;;;;;;OASG;IACH,UAAU,CACT,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,WAAW,EACjB,EAAE,EAAE,MAAM,EACV,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,WAAW,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAC9C,IAAI;IAoBP;;;;;;;;;OASG;IACH,UAAU,CACT,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,WAAW,EACjB,EAAE,EAAE,MAAM,GACR,IAAI;IAqCP;;OAEG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI;IASrE;;;;;;OAMG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAgBjC,8EAA8E;IAC9E,KAAK,IAAI,IAAI;IAoBb,+DAA+D;IAC/D,OAAO,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,KAAK,IAAI,GAAG,IAAI;IAI/D,+DAA+D;IAC/D,UAAU,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG,IAAI;IAIpD;;;;;OAKG;IACH,aAAa,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,IAAI;IAkB1D,0FAA0F;IAC1F,iBAAiB,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAIlD,2CAA2C;IAC3C,OAAO,CAAC,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,kBAAkB,KAAK,IAAI,GAAG,IAAI;IAIvE;;;;;OAKG;IACH,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;OAGG;IACH,OAAO,IAAI,IAAI;CA6Df"}