@blockcast/fec-worker 0.1.0

package/src/shred-worker-client.test.ts

@@ -0,0 +1,182 @@
+import { describe, it, expect } from "vitest";
+import type {
+	ShredWorkerCommand,
+	ShredWorkerEvent,
+	ShredWorkerStats,
+} from "./shred-worker-types.js";
+import { ShredWorkerClient } from "./shred-worker-client.js";
+
+class MockWorker {
+	onmessage: ((e: MessageEvent) => void) | null = null;
+	onerror: ((e: ErrorEvent) => void) | null = null;
+	onmessageerror: ((e: MessageEvent) => void) | null = null;
+	posted: Array<{ data: ShredWorkerCommand; transfer: Transferable[] }> = [];
+	terminated = false;
+
+	postMessage(data: ShredWorkerCommand, transfer?: Transferable[]): void {
+		this.posted.push({ data, transfer: transfer ?? [] });
+	}
+	terminate(): void {
+		this.terminated = true;
+	}
+	emit(event: ShredWorkerEvent): void {
+		this.onmessage?.({ data: event } as MessageEvent);
+	}
+}
+
+function makeStats(overrides: Partial<ShredWorkerStats> = {}): ShredWorkerStats {
+	return {
+		shredsRx: 0,
+		sourceShreds: 0,
+		repairShreds: 0,
+		fecSetsCompleted: 0,
+		bytesReassembled: 0,
+		fecSetsRecovered: 0,
+		pendingFecSets: -1,
+		malformed: 0,
+		versionMismatch: 0,
+		currentSlot: "0",
+		slotSamples: [],
+		...overrides,
+	};
+}
+
+describe("ShredWorkerClient", () => {
+	it("posts configure with the config", () => {
+		const worker = new MockWorker();
+		const client = new ShredWorkerClient(worker as unknown as Worker);
+		client.configure({ maxSlots: 5000, symbolSize: 512, wasmUrl: "/vendor/fec/mmt_wasm.js" });
+		expect(worker.posted[0].data).toEqual({
+			type: "configure",
+			config: { maxSlots: 5000, symbolSize: 512, wasmUrl: "/vendor/fec/mmt_wasm.js" },
+		});
+	});
+
+	it("transfers the readable stream on attachStream", () => {
+		const worker = new MockWorker();
+		const client = new ShredWorkerClient(worker as unknown as Worker);
+		const readable = new ReadableStream<Uint8Array>();
+		client.attachStream(readable);
+		const msg = worker.posted[0];
+		expect(msg.data.type).toBe("attachStream");
+		expect(msg.transfer).toEqual([readable]);
+	});
+
+	it("transfers the frame buffer on feedShred", () => {
+		const worker = new MockWorker();
+		const client = new ShredWorkerClient(worker as unknown as Worker);
+		const frame = new Uint8Array([1, 2, 3]).buffer;
+		client.feedShred(frame);
+		const msg = worker.posted[0];
+		expect(msg.data).toEqual({ type: "feedShred", frame });
+		expect(msg.transfer).toEqual([frame]);
+	});
+
+	it("bounds feedShred to maxInflight when the worker never drains", () => {
+		const worker = new MockWorker();
+		const client = new ShredWorkerClient(worker as unknown as Worker, { maxInflight: 4 });
+		for (let i = 0; i < 10; i++) client.feedShred(new Uint8Array([i]).buffer);
+		const fed = worker.posted.filter((p) => p.data.type === "feedShred");
+		expect(fed.length).toBe(4); // only maxInflight frames posted; the rest dropped
+		expect(client.droppedBackpressure).toBe(6);
+		expect(client.inflight).toBe(4);
+	});
+
+	it("does not transfer (detach) a frame dropped by the in-flight guard", () => {
+		const worker = new MockWorker();
+		const client = new ShredWorkerClient(worker as unknown as Worker, { maxInflight: 1 });
+		client.feedShred(new Uint8Array([1]).buffer); // posted (outstanding 0 -> 1)
+		const dropped = new Uint8Array([9, 9, 9]).buffer;
+		client.feedShred(dropped); // dropped (outstanding 1 >= 1)
+		// A dropped frame is never added to a transfer list, so the caller's buffer
+		// is untouched — no attempt to reuse a detached ArrayBuffer.
+		expect(dropped.byteLength).toBe(3);
+		expect(worker.posted.filter((p) => p.transfer.includes(dropped)).length).toBe(0);
+	});
+
+	it("resumes feeding after the worker reports drain progress via stats", () => {
+		const worker = new MockWorker();
+		const client = new ShredWorkerClient(worker as unknown as Worker, { maxInflight: 4 });
+		for (let i = 0; i < 6; i++) client.feedShred(new Uint8Array([i]).buffer);
+		expect(worker.posted.filter((p) => p.data.type === "feedShred").length).toBe(4);
+		expect(client.droppedBackpressure).toBe(2);
+
+		// Worker heartbeat: it consumed all 4 queued frames -> window reopens.
+		worker.emit({ type: "stats", stats: makeStats({ shredsRx: 4 }) });
+		expect(client.inflight).toBe(0);
+
+		for (let i = 0; i < 3; i++) client.feedShred(new Uint8Array([100 + i]).buffer);
+		expect(worker.posted.filter((p) => p.data.type === "feedShred").length).toBe(7);
+		expect(client.droppedBackpressure).toBe(2); // no NEW drops after the window reopened
+	});
+
+	it("counts malformed + versionMismatch as drained so the window can't inflate", () => {
+		const worker = new MockWorker();
+		const client = new ShredWorkerClient(worker as unknown as Worker, { maxInflight: 4 });
+		for (let i = 0; i < 4; i++) client.feedShred(new Uint8Array([i]).buffer);
+		// Worker drained all 4, but only 1 was valid; 2 malformed + 1 version skew.
+		worker.emit({
+			type: "stats",
+			stats: makeStats({ shredsRx: 1, malformed: 2, versionMismatch: 1 }),
+		});
+		expect(client.inflight).toBe(0);
+	});
+
+	it("maxInflight <= 0 disables the bound entirely", () => {
+		const worker = new MockWorker();
+		const client = new ShredWorkerClient(worker as unknown as Worker, { maxInflight: 0 });
+		for (let i = 0; i < 50; i++) client.feedShred(new Uint8Array([i]).buffer);
+		expect(worker.posted.filter((p) => p.data.type === "feedShred").length).toBe(50);
+		expect(client.droppedBackpressure).toBe(0);
+	});
+
+	it("posts recoverAll with the provided time", () => {
+		const worker = new MockWorker();
+		const client = new ShredWorkerClient(worker as unknown as Worker);
+		client.recoverAll(9999);
+		expect(worker.posted[0].data).toEqual({ type: "recoverAll", nowMs: 9999 });
+	});
+
+	it("dispatches recovered and stats events to callbacks", () => {
+		const worker = new MockWorker();
+		const client = new ShredWorkerClient(worker as unknown as Worker);
+		const recovered: Array<{ len: number; recovered: boolean }> = [];
+		const statsSeen: ShredWorkerStats[] = [];
+		client.onRecovered((data, meta) => recovered.push({ len: data.byteLength, recovered: meta.recovered }));
+		client.onStats((s) => statsSeen.push(s));
+
+		worker.emit({
+			type: "recovered",
+			data: new Uint8Array([1, 2, 3, 4]).buffer,
+			meta: { slot: 5n, fecSetIndex: 1, sendTsUs: 0n, recovered: true },
+		});
+		worker.emit({ type: "stats", stats: makeStats({ shredsRx: 7 }) });
+
+		expect(recovered).toEqual([{ len: 4, recovered: true }]);
+		expect(statsSeen[0].shredsRx).toBe(7);
+	});
+
+	it("routes error events with their code", () => {
+		const worker = new MockWorker();
+		const client = new ShredWorkerClient(worker as unknown as Worker);
+		const errs: Array<[string, string | undefined]> = [];
+		client.onError((m, c) => errs.push([m, c]));
+		worker.emit({ type: "error", message: "boom", code: "wasm-load-failed" });
+		expect(errs).toEqual([["boom", "wasm-load-failed"]]);
+	});
+
+	it("dispose posts dispose, terminates, and is idempotent + no-ops afterward", () => {
+		const worker = new MockWorker();
+		const client = new ShredWorkerClient(worker as unknown as Worker);
+		client.dispose();
+		expect(worker.posted[worker.posted.length - 1]?.data).toEqual({ type: "dispose" });
+		expect(worker.terminated).toBe(true);
+		const postedCount = worker.posted.length;
+		// Post-dispose calls are no-ops.
+		client.feedShred(new Uint8Array([1]).buffer);
+		client.attachStream(new ReadableStream<Uint8Array>());
+		client.recoverAll();
+		client.dispose();
+		expect(worker.posted.length).toBe(postedCount);
+	});
+});

package/src/shred-worker-client.ts

@@ -0,0 +1,222 @@
+/**
+ * @blockcast/fec-worker — Shred Worker Main-Thread Client
+ *
+ * Thin wrapper over the shred (Reed-Solomon) worker, mirroring
+ * {@link FecWorkerClient}'s shape. Spawns one Worker, speaks the
+ * {@link ShredWorkerCommand}/{@link ShredWorkerEvent} protocol, and keeps the
+ * datagram read loop + wire parse + WASM FEC off the main thread.
+ *
+ * Typical wiring for a WebTransport datagram source (fully off-thread):
+ *
+ *   const client = new ShredWorkerClient(new URL("./shred-fec-worker.js", import.meta.url));
+ *   client.onRecovered((data, meta) => renderRecoveredSet(data, meta));
+ *   client.configure({ maxSlots: 5000, symbolSize: 512, wasmUrl: "/vendor/fec/mmt_wasm.js" });
+ *   client.attachStream(wt.datagrams.readable); // transferred; main does no read() per packet
+ *
+ * For sources that demux on the main thread (moqtail OBJECT_DATAGRAM callback,
+ * IWA multicast bridge), push each raw frame with {@link feedShred} instead.
+ *
+ * {@link feedShred} is a fire-and-forget `postMessage` with no native
+ * backpressure, so a consumer that decodes slower than the ingest rate (a
+ * backgrounded/throttled tab, WASM RS falling behind a ~4k shred/s feed) would
+ * grow the worker's inbound message queue without limit — the queue lives in the
+ * renderer process and has been observed to reach multiple GB, GC-thrashing the
+ * page into a wedge. The client bounds it with an in-flight window keyed off the
+ * worker's own periodic stats heartbeat (no per-frame ack round-trip); see
+ * {@link ShredWorkerClientOptions.maxInflight}.
+ */
+
+import type {
+	ShredWorkerCommand,
+	ShredWorkerConfig,
+	ShredWorkerEvent,
+	ShredWorkerStats,
+	ShredWorkerErrorCode,
+	RecoveredMeta,
+} from "./shred-worker-types.js";
+
+/** Construction-time options for {@link ShredWorkerClient}. */
+export interface ShredWorkerClientOptions {
+	/**
+	 * Cap on frames posted via {@link ShredWorkerClient.feedShred} but not yet
+	 * drained by the worker, before further frames are dropped ("skip-to-live" at
+	 * the worker boundary). Bounds the worker's inbound message queue — the sole
+	 * unbounded structure on the main-thread-demux (`feedShred`) path.
+	 *
+	 * The drain signal is the worker's periodic `stats` heartbeat: the monotonic
+	 * total of frames it has taken off the queue (`shredsRx + malformed +
+	 * versionMismatch`). No per-frame acknowledgement crosses the boundary, so the
+	 * bound is heartbeat-granular — size it above one heartbeat's worth of ingest
+	 * (default 250ms heartbeat × ~4k frames/s ≈ ~1k frames).
+	 *
+	 * Default {@link DEFAULT_MAX_INFLIGHT} (8192 frames ≈ ~10 MB at ~1.3 KB/frame).
+	 * Set to `0` (or any value `<= 0`) to disable the bound entirely — only do so
+	 * for a source with its own backpressure (e.g. a bounded {@link
+	 * ShredWorkerClient.attachStream} producer). Note the bound assumes `feedShred`
+	 * is the sole ingest path; mixing it with `attachStream` (whose frames also
+	 * advance the heartbeat total) makes the window under-count and benignly
+	 * disables the drop.
+	 */
+	maxInflight?: number;
+}
+
+/** Default {@link ShredWorkerClientOptions.maxInflight} (~10 MB of queued frames). */
+export const DEFAULT_MAX_INFLIGHT = 8192;
+
+export class ShredWorkerClient {
+	readonly #worker: Worker;
+	#onRecovered: ((data: ArrayBuffer, meta: RecoveredMeta) => void) | null = null;
+	#onStats: ((stats: ShredWorkerStats) => void) | null = null;
+	#onError: ((message: string, code?: ShredWorkerErrorCode) => void) | null = null;
+	#disposed = false;
+
+	/** feedShred in-flight backpressure accounting (see ShredWorkerClientOptions.maxInflight). */
+	readonly #maxInflight: number;
+	#sent = 0; // frames posted via feedShred (monotonic)
+	#processed = 0; // worker-consumed total from the last stats heartbeat (monotonic)
+	#droppedBackpressure = 0; // frames dropped by the in-flight guard (monotonic)
+
+	/**
+	 * @param workerOrUrl - A URL (a Worker is created internally, `type: module`)
+	 *   or a pre-created Worker (for testing via constructor injection).
+	 * @param opts - Optional {@link ShredWorkerClientOptions}.
+	 */
+	constructor(workerOrUrl: Worker | URL, opts: ShredWorkerClientOptions = {}) {
+		this.#maxInflight = opts.maxInflight ?? DEFAULT_MAX_INFLIGHT;
+		this.#worker =
+			workerOrUrl instanceof URL
+				? new Worker(workerOrUrl, { type: "module" })
+				: workerOrUrl;
+		this.#worker.onmessage = (e: MessageEvent<ShredWorkerEvent>) =>
+			this.#handleEvent(e.data);
+		this.#worker.onerror = (e) =>
+			this.#onError?.(formatWorkerError(e), "worker-runtime");
+		this.#worker.onmessageerror = () =>
+			this.#onError?.("failed to deserialize worker message", "worker-message");
+	}
+
+	/** Configure the decoder (WASM load + ShredFecBuffer construction happen in the worker). */
+	configure(config: ShredWorkerConfig): void {
+		if (this.#disposed) throw new Error("[ShredWorkerClient] disposed");
+		this.#post({ type: "configure", config });
+	}
+
+	/**
+	 * Hand the worker a stream of raw shred frames to batch-drain. The stream is
+	 * transferred — the caller must not use it afterward. One active stream at a
+	 * time; attaching a new one cancels the previous.
+	 */
+	attachStream(readable: ReadableStream<Uint8Array>): void {
+		if (this.#disposed) return;
+		this.#post({ type: "attachStream", readable }, [readable]);
+	}
+
+	/**
+	 * Feed one already-demuxed raw shred frame. `frame` is transferred zero-copy;
+	 * the caller must not access it afterward.
+	 *
+	 * Dropped (frame NOT transferred, so the caller's buffer stays intact) when the
+	 * in-flight window is full — i.e. the worker is more than `maxInflight` frames
+	 * behind. This is the memory bound: a slow/wedged consumer costs bounded
+	 * skip-to-live drops (see {@link droppedBackpressure}), never an unbounded
+	 * renderer-heap blow-up.
+	 */
+	feedShred(frame: ArrayBuffer): void {
+		if (this.#disposed) return;
+		if (this.#maxInflight > 0 && this.#sent - this.#processed >= this.#maxInflight) {
+			this.#droppedBackpressure++;
+			return;
+		}
+		this.#sent++;
+		this.#post({ type: "feedShred", frame }, [frame]);
+	}
+
+	/** Explicitly drive loss recovery (in addition to the worker's internal timer). */
+	recoverAll(nowMs: number = Date.now()): void {
+		if (this.#disposed) return;
+		this.#post({ type: "recoverAll", nowMs });
+	}
+
+	/** Register callback for recovered/completed FEC sets. `data` is a transferred buffer. */
+	onRecovered(cb: (data: ArrayBuffer, meta: RecoveredMeta) => void): void {
+		this.#onRecovered = cb;
+	}
+
+	/** Register callback for the coalesced stats heartbeat. */
+	onStats(cb: (stats: ShredWorkerStats) => void): void {
+		this.#onStats = cb;
+	}
+
+	/** Register callback for worker errors. */
+	onError(cb: (message: string, code?: ShredWorkerErrorCode) => void): void {
+		this.#onError = cb;
+	}
+
+	/**
+	 * Frames dropped by the in-flight backpressure guard since construction
+	 * (monotonic). Surface this in the UI so sustained loss is visible rather than
+	 * silent — a rising counter means the consumer can't keep pace with ingest.
+	 */
+	get droppedBackpressure(): number {
+		return this.#droppedBackpressure;
+	}
+
+	/**
+	 * Frames posted via {@link feedShred} but not yet reported drained by the
+	 * worker's last stats heartbeat (best-effort, heartbeat-granular; never < 0).
+	 */
+	get inflight(): number {
+		return Math.max(0, this.#sent - this.#processed);
+	}
+
+	/** Dispose the worker. Idempotent. */
+	dispose(): void {
+		if (this.#disposed) return;
+		this.#disposed = true;
+		try {
+			this.#worker.postMessage({ type: "dispose" } satisfies ShredWorkerCommand);
+		} catch {
+			/* worker may already be gone */
+		}
+		this.#worker.terminate();
+	}
+
+	#post(cmd: ShredWorkerCommand, transfer: Transferable[] = []): void {
+		this.#worker.postMessage(cmd, transfer);
+	}
+
+	#handleEvent(event: ShredWorkerEvent): void {
+		switch (event.type) {
+			case "recovered":
+				this.#onRecovered?.(event.data, event.meta);
+				break;
+			case "stats":
+				// The worker's monotonic consumed-frame total is the drain signal for
+				// the feedShred in-flight guard. shredsRx counts only valid frames;
+				// malformed + versionMismatch are consumed off the queue too, so the
+				// sum is the true "frames taken off the queue" and keeps the window
+				// from inflating (and false-dropping) on a malformed/skewed source.
+				this.#processed =
+					event.stats.shredsRx + event.stats.malformed + event.stats.versionMismatch;
+				this.#onStats?.(event.stats);
+				break;
+			case "error":
+				if (event.code) this.#onError?.(event.message, event.code);
+				else this.#onError?.(event.message);
+				break;
+		}
+	}
+}
+
+function formatWorkerError(event: ErrorEvent): string {
+	const parts = ["Worker error"];
+	if (event.message) parts.push(event.message);
+	if (event.filename) {
+		const loc = [event.filename];
+		if (event.lineno) loc.push(String(event.lineno));
+		if (event.colno) loc.push(String(event.colno));
+		parts.push(`at ${loc.join(":")}`);
+	}
+	if (event.error instanceof Error && event.error.stack) parts.push(event.error.stack);
+	return parts.join(": ");
+}

package/src/shred-worker-types.ts

@@ -0,0 +1,194 @@
+/**
+ * @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; non-3 frames are 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).
+ */
+export const SHRED_WIRE_VERSION = 3;
+export const SHRED_HEADER_LEN = 28;
+export const SHRED_FLAG_DATA_COMPLETE = 0x01;
+export const SHRED_FLAG_IS_CODING = 0x02;
+
+// --- Config -----------------------------------------------------------------
+
+/** Per-decoder configuration for the shred FEC worker. */
+export interface ShredWorkerConfig {
+	/** Ring capacity in slots (matches `new ShredFecBuffer(maxSlots, symbolSize)`). */
+	maxSlots: number;
+	/** Symbol size in bytes (Solana shred payloads are fixed-size within a set). */
+	symbolSize: number;
+	/**
+	 * Module URL for the shred WASM (wasm-bindgen ESM exporting `default` init +
+	 * `ShredFecBuffer`). The worker `import()`s it and calls `await default()`.
+	 * Ignored when `self.__SHRED_WASM_BINDINGS__` is pre-injected (tests / custom
+	 * loaders), mirroring the RaptorQ worker's `__MMT_WASM_BINDINGS__` contract.
+	 */
+	wasmUrl?: string;
+	/**
+	 * How often (ms) the worker coalesces and posts a `stats` event. The read
+	 * loop never posts per-shred; only recovered frames and this heartbeat cross
+	 * the boundary. Default 250ms.
+	 */
+	statsIntervalMs?: number;
+	/**
+	 * How often (ms) the worker runs `try_recover_all(now)` to drain timed-out
+	 * FEC sets that `add_shred` didn't complete (loss scenarios). Default 50ms,
+	 * matching the player's on-thread recovery timer. Set to 0 to disable (the
+	 * consumer may instead drive it explicitly with `recoverAll`).
+	 */
+	recoverIntervalMs?: number;
+}
+
+// --- Stats ------------------------------------------------------------------
+
+/**
+ * First-shred-per-slot sample, collected by the worker and drained into each
+ * coalesced `stats` heartbeat. Lets the main thread run app-specific,
+ * slot-derived stats (e.g. the turbine-leg latency estimator, per-slot latency
+ * percentiles) WITHOUT re-parsing the wire header — the worker stays the single
+ * source of truth for parsing, and these cross the boundary aggregated (a
+ * handful per heartbeat), never per-packet.
+ */
+export interface SlotSample {
+	/** Slot number (first shred of this slot the worker saw). */
+	slot: bigint;
+	/** Publisher send timestamp (µs since epoch) of that first shred, 0 when unstamped. */
+	sendTsUs: bigint;
+	/** Frame byte length of that first shred. */
+	bytes: number;
+}
+
+/** Aggregate shred-decode counters, emitted on the coalesced `stats` heartbeat. */
+export interface ShredWorkerStats {
+	/** Total shred frames parsed (data + coding). */
+	shredsRx: number;
+	/** Data (source) shreds observed. */
+	sourceShreds: number;
+	/** Coding (repair) shreds observed. */
+	repairShreds: number;
+	/** FEC sets completed (direct completion + FEC recovery). */
+	fecSetsCompleted: number;
+	/** Bytes handed back as recovered/completed sets. */
+	bytesReassembled: number;
+	/** Sets recovered specifically via `try_recover_all` (loss recovery). */
+	fecSetsRecovered: number;
+	/** Current `ShredFecBuffer.pending_fec_sets()`, or -1 when unavailable. */
+	pendingFecSets: number;
+	/** Frames dropped for being shorter than the v3 header. */
+	malformed: number;
+	/** Frames dropped for carrying a non-v3 version byte (forwarder/worker skew). */
+	versionMismatch: number;
+	/** Highest slot number observed (as a string — bigint isn't JSON-safe for UI). */
+	currentSlot: string;
+	/** First-shred-per-slot samples parsed since the previous heartbeat (drained each emit). */
+	slotSamples: SlotSample[];
+}
+
+/** Stable identities for worker failures whose message text carries live values. */
+export type ShredWorkerErrorCode =
+	| "wasm-load-failed"
+	| "wasm-bindings-missing"
+	| "not-configured"
+	| "stream-read-failed"
+	| "unknown-command"
+	| "worker-runtime"
+	| "worker-message";
+
+// --- Recovered frame metadata ----------------------------------------------
+
+/** Metadata attached to each recovered set the worker emits. */
+export interface RecoveredMeta {
+	/**
+	 * Slot the recovered set belongs to. Attributed on both the direct-completion
+	 * path and the identity-carrying recovery drain
+	 * (`try_recover_all_with_identity`); only 0n on the legacy `ShredReassembler`
+	 * fallback, which has no identity variant. Do NOT branch on `slot === 0n` as
+	 * "unattributed" — that would drop the majority of recovered sets.
+	 */
+	slot: bigint;
+	/** FEC set index within the slot (0 only on the legacy identity-less fallback). */
+	fecSetIndex: number;
+	/**
+	 * Publisher send timestamp (µs since epoch), 0 when unstamped/unknown. On
+	 * direct completion this is the completing shred's stamp; on the recovery
+	 * drain it is the set's first-seen shred stamp (shreds of a set are sent µs
+	 * apart, so the two are equivalent latency baselines).
+	 */
+	sendTsUs: bigint;
+	/** True when produced by loss recovery (`try_recover_all`) rather than direct completion. */
+	recovered: boolean;
+}
+
+// --- Commands (main -> worker) ----------------------------------------------
+
+/** Discriminated union of all commands sent from the main thread to the shred worker. */
+export type ShredWorkerCommand =
+	| { type: "configure"; config: ShredWorkerConfig }
+	| {
+			/**
+			 * Hand the worker a stream of raw shred frames to batch-drain. Each
+			 * chunk is one wire frame (one WebTransport datagram). The stream is
+			 * transferred (add to the postMessage transfer list) — the main thread
+			 * must not touch it afterward.
+			 */
+			type: "attachStream";
+			readable: ReadableStream<Uint8Array>;
+	  }
+	| {
+			/**
+			 * Feed one already-demuxed raw shred frame. `frame` is transferred
+			 * zero-copy — the caller must not access it after posting. Use this for
+			 * sources whose demux stays on the main thread (moqtail OBJECT_DATAGRAM
+			 * callback, IWA multicast bridge).
+			 */
+			type: "feedShred";
+			frame: ArrayBuffer;
+	  }
+	| { type: "recoverAll"; nowMs: number }
+	| { type: "dispose" };
+
+// --- Events (worker -> main) ------------------------------------------------
+
+/** Discriminated union of all events emitted from the shred worker to the main thread. */
+export type ShredWorkerEvent =
+	| { type: "recovered"; data: ArrayBuffer; meta: RecoveredMeta }
+	| { type: "stats"; stats: ShredWorkerStats }
+	| { type: "error"; message: string; code?: ShredWorkerErrorCode };

package/src/transfer.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { toOwnedArrayBuffer } from "./transfer.js";
+
+describe("toOwnedArrayBuffer", () => {
+	it("copies exactly the bytes in an offset Uint8Array view", () => {
+		const backing = new Uint8Array([0, 1, 2, 3, 4, 5]);
+		const view = backing.subarray(2, 5);
+
+		const owned = toOwnedArrayBuffer(view);
+
+		expect([...new Uint8Array(owned)]).toEqual([2, 3, 4]);
+		expect(owned.byteLength).toBe(3);
+		expect(owned).not.toBe(backing.buffer);
+	});
+
+	it("does not alias the source buffer after copying", () => {
+		const source = new Uint8Array([9, 8, 7]);
+		const owned = toOwnedArrayBuffer(source);
+
+		source[1] = 1;
+
+		expect([...new Uint8Array(owned)]).toEqual([9, 8, 7]);
+	});
+});

package/src/transfer.ts

@@ -0,0 +1,12 @@
+/**
+ * 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: Uint8Array): ArrayBuffer {
+	const copy = new Uint8Array(view.byteLength);
+	copy.set(view);
+	return copy.buffer;
+}