@blockcast/mmt-container 0.1.0 → 0.3.0-main.0bde85f7082f

package/node_modules/@blockcast/fec-worker/dist/shred-worker-types.js

@@ -0,0 +1,62 @@
+/**
+ * @blockcast/fec-worker — Shred (Reed-Solomon) Worker Protocol
+ *
+ * A sibling codec to the RaptorQ/MMTP worker (`fec-worker.ts`). Solana-style
+ * shred streams carry a different FEC payload identity than MMTP source/repair
+ * symbols — a shred is `(slot, fecSetIndex, localIndex, numData, numCoding,
+ * isCoding, lastInSet)`, not a flat `ssId` — so they need their own command
+ * shape. The transport harness (Worker spawn, onmessage plumbing, zero-copy
+ * `toOwnedArrayBuffer` transfers) is shared; the decoder WASM is not.
+ *
+ * The worker owns the batch-drain: the consumer transfers a WebTransport
+ * `datagrams.readable` (or any `ReadableStream<Uint8Array>` of raw shred
+ * frames) into the Worker via {@link ShredWorkerCommand} `attachStream`, and
+ * the read loop + wire parse + `ShredFecBuffer.add_shred` all run off the main
+ * thread. Only recovered FEC sets (and coalesced stats) cross back. A
+ * `feedShred` command covers sources that have already demuxed the shred bytes
+ * on the main thread (e.g. a moqtail OBJECT_DATAGRAM callback, or the IWA
+ * multicast bridge).
+ *
+ * Types here are importable from both main thread and Worker contexts.
+ */
+// --- Wire format ------------------------------------------------------------
+/**
+ * Wire header layout the worker parses. Mirrors the deployed shred player's
+ * `onShredBytes` exactly (libmmt shred-forwarder `emit_frame`) so the off-thread
+ * path is bit-identical to the proven on-thread path.
+ *
+ * v3 (28-byte header):
+ *   [0]      version       u8   (3 or 4; any other version is dropped, not misframed)
+ *   [1-8]    slot          u64 LE
+ *   [9-12]   fecSetIndex   u32 LE
+ *   [13-16]  localIndex    u32 LE   (data: 0..numData; coding: numData+position)
+ *   [17]     flags         u8       (bit0 = DATA_COMPLETE, bit1 = IS_CODING_SHRED)
+ *   [18]     numData       u8       (coding shreds only; 0 on data — WASM infers)
+ *   [19]     numCoding     u8       (coding shreds only; 0 on data)
+ *   [20-27]  sendTsUs      u64 LE   (µs since epoch, 0 when unstamped)
+ *   [28+]    erasureShard           (equal length across the FEC set)
+ *
+ * DATA_COMPLETE (last data shred in the set) is passed to `add_shred` as its
+ * `lastInSet` argument — the WASM uses it to infer numData for a set that
+ * received only data shreds (no coding).
+ *
+ * v4 has the same 28-byte header, but its body is the full canonical Agave
+ * shred (signature, headers, erasure shard, chained Merkle root, proof, and
+ * the retransmitter signature on resigned variants) — the form a validator TVU
+ * accepts (BLO-41383). The worker recovers the exact v3 erasure-shard view
+ * from it with the forwarder's own `erasure_shard()` slice, so both versions
+ * reach `add_shred` byte-identical:
+ *   variant      = shred[64]; data 0x9_/0xb_, coding 0x6_/0x7_ (chained merkle;
+ *                  0xb_/0x7_ resigned), must agree with IS_CODING_SHRED
+ *   length       = 1203 (data) / 1228 (coding), exactly
+ *   shard start  = 64 (data: after the signature) / 89 (coding headers)
+ *   shard end    = length - (32 root + 20 * (variant & 0x0f) proof
+ *                            + 64 retransmitter signature if resigned)
+ */
+export const SHRED_WIRE_VERSION = 3;
+/** Wire version whose body is the full canonical shred (see above). */
+export const SHRED_WIRE_VERSION_FULL = 4;
+export const SHRED_HEADER_LEN = 28;
+export const SHRED_FLAG_DATA_COMPLETE = 0x01;
+export const SHRED_FLAG_IS_CODING = 0x02;
+//# sourceMappingURL=shred-worker-types.js.map

package/node_modules/@blockcast/fec-worker/dist/shred-worker-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shred-worker-types.js","sourceRoot":"","sources":["../src/shred-worker-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AACpC,uEAAuE;AACvE,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AACzC,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,CAAC;AACnC,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,CAAC;AAC7C,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC"}

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

@@ -0,0 +1,9 @@
+/**
+ * Return a fresh ArrayBuffer containing exactly the bytes in `view`.
+ *
+ * Worker outputs must not transfer buffers that might be owned by a WASM
+ * binding or by a larger shared packet. A fresh JS-owned buffer gives
+ * postMessage() exclusive ownership without detaching unrelated memory.
+ */
+export declare function toOwnedArrayBuffer(view: Uint8Array): ArrayBuffer;
+//# sourceMappingURL=transfer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transfer.d.ts","sourceRoot":"","sources":["../src/transfer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW,CAIhE"}

package/node_modules/@blockcast/fec-worker/dist/transfer.js

@@ -0,0 +1,13 @@
+/**
+ * Return a fresh ArrayBuffer containing exactly the bytes in `view`.
+ *
+ * Worker outputs must not transfer buffers that might be owned by a WASM
+ * binding or by a larger shared packet. A fresh JS-owned buffer gives
+ * postMessage() exclusive ownership without detaching unrelated memory.
+ */
+export function toOwnedArrayBuffer(view) {
+    const copy = new Uint8Array(view.byteLength);
+    copy.set(view);
+    return copy.buffer;
+}
+//# sourceMappingURL=transfer.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transfer.js","sourceRoot":"","sources":["../src/transfer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAgB;IAClD,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC7C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACf,OAAO,IAAI,CAAC,MAAM,CAAC;AACpB,CAAC"}

package/node_modules/@blockcast/fec-worker/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@blockcast/fec-worker",
+  "version": "0.3.0",
+  "description": "Worker-per-track FEC decode with zero-copy ArrayBuffer transfer and ALTA auth plumbing",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./worker": {
+      "import": "./dist/fec-worker.js"
+    },
+    "./shred-worker": {
+      "import": "./dist/shred-fec-worker.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts",
+    "!src/**/__tests__",
+    "!dist/**/*.test.*",
+    "!dist/**/*.spec.*"
+  ],
+  "scripts": {
+    "build": "tsc && node build.mjs",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@blockcast/mmt-alta-parse": "^0.3.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "keywords": [
+    "fec",
+    "worker",
+    "raptorq",
+    "zero-copy",
+    "transferable",
+    "alta"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Blockcast/libmmt.git",
+    "directory": "packages/fec-worker"
+  }
+}

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

@@ -0,0 +1,93 @@
+/**
+ * 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: number, k: number): number {
+	// 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: number, b: number, k: number): number | null {
+	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: number, b: number, k: number): boolean {
+	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: number, b: number, k: number): number {
+	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: number, to: number): number {
+	return (to - from + SPAN) % SPAN;
+}
+
+/** Whether `a` precedes `b` under RFC 1982 serial comparison (SERIAL_BITS = 32). */
+export function serialPrecedes(a: number, b: number): boolean {
+	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: number, ssbLength: number, ssId: number): boolean {
+	return serialDistance(ssStart, ssId) < ssbLength;
+}
+
+/** Whether two SS_ID ranges `[start, start + length)` share any SS_ID, mod 2^32. */
+export function isoBlocksOverlap(
+	aStart: number,
+	aLength: number,
+	bStart: number,
+	bLength: number,
+): boolean {
+	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: number, b: number, kMax: number): number {
+	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;
+}

package/node_modules/@blockcast/fec-worker/src/fec-worker-client.ts

@@ -0,0 +1,392 @@
+/**
+ * @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 {
+	FecWorkerCommand,
+	FecSymbolCommand,
+	FecWorkerEvent,
+	FecTrackConfig,
+	FecTrackStats,
+	FecBlockSnapshot,
+	FrameMeta,
+	FecWorkerErrorCode,
+} from "./fec-worker-types.js";
+
+export class FecWorkerClient {
+	readonly #worker: Worker;
+	#onFrame: ((data: ArrayBuffer, meta: FrameMeta) => void) | null = null;
+	#onSnapshot: ((stats: FecTrackStats) => void) | null = null;
+	#onBlockUpdate: ((block: FecBlockSnapshot) => void) | null = null;
+	#onCleanupComplete: ((sbn: number) => void) | null = null;
+	#onError: ((message: string, code?: FecWorkerErrorCode) => void) | null = null;
+	#cleanupInFlight: Set<number> | null = null;
+	#queuedCleanupSbns = new Set<number>();
+	#pendingResets = 0;
+	#resetFailed = false;
+	#disposed = false;
+	// Symbols fed during the current task, sent as one feedSymbols message
+	// when the task's microtasks run (BLO-36599). A packet stream delivers many
+	// symbols per task, and each postMessage is a structured-clone round trip
+	// on the page thread; the batch boundary is the task, not a size or timer.
+	#pendingSymbols: FecSymbolCommand[] = [];
+	#pendingTransfer: Transferable[] = [];
+	#flushQueued = false;
+	// Batching starts only once the Worker announced it accepts feedSymbols.
+	#batchSymbols = false;
+	// The Worker posts blockUpdate events only to a client that subscribed,
+	// which this client does once a callback is registered and the Worker
+	// announced the command (BLO-36599).
+	#blockUpdatesAnnounced = false;
+	#blockUpdatesSubscribed = false;
+
+	/**
+	 * Create a FecWorkerClient.
+	 * @param workerOrUrl - Either a Worker instance (for testing) or a URL to create one
+	 */
+	constructor(workerOrUrl: Worker | URL) {
+		if (workerOrUrl instanceof URL) {
+			this.#worker = new Worker(workerOrUrl, { type: "module" });
+		} else {
+			this.#worker = workerOrUrl;
+		}
+		this.#worker.onmessage = (e: MessageEvent<FecWorkerEvent>) =>
+			this.#handleEvent(e.data);
+		this.#worker.onerror = (e) => {
+			this.#onError?.(formatWorkerError(e), "worker-runtime");
+		};
+		this.#worker.onmessageerror = (e) => {
+			this.#onError?.(formatWorkerMessageError(e), "worker-message");
+		};
+	}
+
+	/**
+	 * 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 {
+		if (this.#disposed) throw new Error("[FecWorkerClient] disposed");
+		this.#flushSymbols();
+		const cmd: FecWorkerCommand = {
+			type: "configure",
+			config,
+			wasmModule,
+			altaPublicKey,
+			altaWasmModule,
+		};
+		// WebAssembly.Module is structured-cloneable, NOT transferable.
+		// Pass it in the message body (Chrome clones it automatically).
+		// Only ArrayBuffers (like altaPublicKey) go in the transfer list.
+		const transferList: Transferable[] = [];
+		if (altaPublicKey) transferList.push(altaPublicKey);
+		// altaWasmModule is structured-cloneable — NOT added to transferList
+		this.#worker.postMessage(cmd, transferList);
+	}
+
+	/**
+	 * 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 {
+		if (this.#disposed) throw new Error("[FecWorkerClient] feedSource on a disposed client");
+		if (alta) {
+			this.#queueSymbol(
+				{
+					type: "feedSource",
+					ssId,
+					data,
+					ts,
+					altaAuth: alta.auth,
+					altaPayloadEnd: alta.payloadEnd,
+				},
+				data,
+				alta.auth,
+			);
+		} else {
+			this.#queueSymbol({ type: "feedSource", ssId, data, ts }, data);
+		}
+	}
+
+	/**
+	 * 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 {
+		if (this.#disposed) throw new Error("[FecWorkerClient] feedRepair on a disposed client");
+		this.#queueSymbol({ type: "feedRepair", ssStart, ssbLength, rsId, data, ts }, data);
+	}
+
+	#queueSymbol(symbol: FecSymbolCommand, data: ArrayBuffer, auth?: ArrayBuffer): void {
+		if (!this.#batchSymbols) {
+			this.#worker.postMessage(symbol, auth ? [data, auth] : [data]);
+			return;
+		}
+		this.#pendingSymbols.push(symbol);
+		this.#pendingTransfer.push(data);
+		if (auth) this.#pendingTransfer.push(auth);
+		if (this.#flushQueued) return;
+		this.#flushQueued = true;
+		queueMicrotask(() => {
+			this.#flushQueued = false;
+			this.#flushSymbols();
+		});
+	}
+
+	/**
+	 * Send the symbols fed so far. Every other command calls this first, so a
+	 * cleanup barrier, reset or signature still follows all earlier symbols.
+	 */
+	#flushSymbols(): void {
+		if (this.#pendingSymbols.length === 0 || this.#disposed) return;
+		const symbols = this.#pendingSymbols;
+		const transfer = this.#pendingTransfer;
+		this.#pendingSymbols = [];
+		this.#pendingTransfer = [];
+		this.#worker.postMessage(
+			{ type: "feedSymbols", symbols } satisfies FecWorkerCommand,
+			transfer,
+		);
+	}
+
+	/**
+	 * Submit relay block signature for verification. sig and hash are transferred.
+	 */
+	relayBlockSig(sbn: number, sig: ArrayBuffer, hash: ArrayBuffer): void {
+		if (this.#disposed) throw new Error("[FecWorkerClient] relayBlockSig on a disposed client");
+		this.#flushSymbols();
+		this.#worker.postMessage(
+			{ type: "relayBlockSig", sbn, sig, hash } satisfies FecWorkerCommand,
+			[sig, hash],
+		);
+	}
+
+	/**
+	 * 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 {
+		if (this.#disposed) throw new Error("[FecWorkerClient] cleanup on a disposed client");
+		if (
+			!Number.isInteger(currentSbn) ||
+			currentSbn < 0 ||
+			currentSbn > 0xffff_ffff
+		) {
+			throw new Error("[FecWorkerClient] cleanup: SBN must be a uint32");
+		}
+		if (this.#cleanupInFlight) {
+			this.#queuedCleanupSbns.add(currentSbn);
+			return;
+		}
+		this.#postCleanup(new Set([currentSbn]));
+	}
+
+	/** Reset this track's decoder epoch while preserving Worker configuration. */
+	reset(): void {
+		if (this.#disposed) throw new Error("[FecWorkerClient] reset on a disposed client");
+		this.#flushSymbols();
+		this.#pendingResets++;
+		this.#cleanupInFlight = null;
+		this.#queuedCleanupSbns.clear();
+		this.#worker.postMessage({ type: "reset" } satisfies FecWorkerCommand);
+	}
+
+	#postCleanup(sbns: Set<number>): void {
+		// The cleanup is a queue-drain barrier: every symbol fed before it is
+		// posted must reach the Worker first.
+		this.#flushSymbols();
+		this.#cleanupInFlight = sbns;
+		const orderedSbns = [...sbns].sort((a, b) => a - b);
+		this.#worker.postMessage(
+			{ type: "cleanup", sbns: orderedSbns } satisfies FecWorkerCommand,
+		);
+	}
+
+	/** Register callback for decoded/recovered frames (FEC-03). */
+	onFrame(cb: (data: ArrayBuffer, meta: FrameMeta) => void): void {
+		this.#onFrame = cb;
+	}
+
+	/** Register callback for periodic stats snapshots (FEC-04). */
+	onSnapshot(cb: (stats: FecTrackStats) => void): void {
+		this.#onSnapshot = cb;
+	}
+
+	/**
+	 * 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 {
+		this.#onBlockUpdate = cb;
+		this.#subscribeBlockUpdates();
+	}
+
+	#subscribeBlockUpdates(): void {
+		if (
+			this.#disposed ||
+			this.#blockUpdatesSubscribed ||
+			!this.#blockUpdatesAnnounced ||
+			!this.#onBlockUpdate
+		) return;
+		this.#blockUpdatesSubscribed = true;
+		this.#worker.postMessage(
+			{ type: "subscribeBlockUpdates" } satisfies FecWorkerCommand,
+		);
+	}
+
+	/** Register callback fired after the Worker drains all commands queued before cleanup. */
+	onCleanupComplete(cb: (sbn: number) => void): void {
+		this.#onCleanupComplete = cb;
+	}
+
+	/** Register callback for Worker errors. */
+	onError(cb: (message: string, code?: FecWorkerErrorCode) => void): void {
+		this.#onError = cb;
+	}
+
+	/**
+	 * 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 {
+		return this.#disposed;
+	}
+
+	/**
+	 * Dispose the Worker. Sends dispose command then terminates.
+	 * Idempotent — safe to call multiple times.
+	 */
+	dispose(): void {
+		if (this.#disposed) return;
+		this.#disposed = true;
+		// A terminated Worker decodes nothing; symbols still batched are dropped.
+		this.#pendingSymbols = [];
+		this.#pendingTransfer = [];
+		this.#cleanupInFlight = null;
+		this.#queuedCleanupSbns.clear();
+		this.#worker.postMessage({ type: "dispose" } satisfies FecWorkerCommand);
+		this.#worker.terminate();
+	}
+
+	#handleEvent(event: FecWorkerEvent): void {
+		if (event.type === "capabilities") {
+			if (Array.isArray(event.commands) && event.commands.includes("feedSymbols")) {
+				this.#batchSymbols = true;
+			}
+			if (Array.isArray(event.commands) && event.commands.includes("subscribeBlockUpdates")) {
+				this.#blockUpdatesAnnounced = true;
+				this.#subscribeBlockUpdates();
+			}
+			return;
+		}
+		if (event.type === "resetComplete") {
+			this.#pendingResets = Math.max(0, this.#pendingResets - 1);
+			this.#resetFailed = false;
+			return;
+		}
+		if (event.type === "error") {
+			if (event.code === "reset-failed") {
+				this.#pendingResets = Math.max(0, this.#pendingResets - 1);
+				this.#resetFailed = true;
+			}
+			if (event.code) this.#onError?.(event.message, event.code);
+			else this.#onError?.(event.message);
+			return;
+		}
+		if (this.#pendingResets > 0 || this.#resetFailed) return;
+		switch (event.type) {
+			case "frame":
+				this.#onFrame?.(event.data, event.meta);
+				break;
+			case "snapshot":
+				this.#onSnapshot?.(event.stats);
+				break;
+			case "blockUpdate":
+				this.#onBlockUpdate?.(event.block);
+				break;
+			case "cleanupComplete":
+				for (const sbn of event.sbns) {
+					this.#onCleanupComplete?.(sbn);
+				}
+				this.#cleanupInFlight = null;
+				if (this.#queuedCleanupSbns.size > 0) {
+					const next = this.#queuedCleanupSbns;
+					this.#queuedCleanupSbns = new Set();
+					this.#postCleanup(next);
+				}
+				break;
+		}
+	}
+}
+
+function formatWorkerError(event: ErrorEvent): string {
+	const parts = ["Worker error"];
+	if (event.message) parts.push(event.message);
+	if (event.filename) {
+		const location = [event.filename];
+		if (event.lineno) location.push(String(event.lineno));
+		if (event.colno) location.push(String(event.colno));
+		parts.push(`at ${location.join(":")}`);
+	}
+	if (event.error instanceof Error) {
+		if (event.error.message && event.error.message !== event.message) {
+			parts.push(event.error.message);
+		}
+		if (event.error.stack) parts.push(event.error.stack);
+	} else if (event.error != null) {
+		parts.push(String(event.error));
+	}
+	return parts.join(": ");
+}
+
+function formatWorkerMessageError(event: MessageEvent): string {
+	const data = event.data;
+	const detail =
+		data == null ? "" :
+			data instanceof Error ? `: ${data.message}` :
+				`: ${Object.prototype.toString.call(data)}`;
+	return `Worker messageerror: failed to deserialize worker message${detail}`;
+}