@blockcast/fec-worker 0.1.0

package/src/__tests__/fec-worker-repair-size.test.ts

@@ -0,0 +1,1029 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { FecWorkerCommand, FecWorkerEvent, FecTrackConfig } from "../fec-worker-types.js";
+
+const EMPTY_WASM_MODULE = new WebAssembly.Module(
+	new Uint8Array([0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00]),
+);
+const UINT32_MAX = 0xffff_ffff;
+const UINT24_MAX = 0xff_ffff;
+const MAX_INTERLEAVE_DEPTH = 0xff;
+const MAX_SYMBOL_SIZE = 0xfff8;
+const MAX_RAPTORQ_SOURCE_SYMBOLS_PER_BLOCK = 56_403;
+
+const BASE_CONFIG: FecTrackConfig = {
+	codec: "avc1.64001f",
+	trackName: "video",
+	trackType: "video",
+	algorithm: "raptorq",
+	k: 4,
+	repairCount: 2,
+	symbolSize: 8,
+	interleaveDepth: 4,
+	interleaveMs: 100,
+	deliveryWindowMs: 200,
+	fecMode: "subframe",
+	altaEnabled: false,
+	relayBlockSigEnabled: false,
+};
+
+function nextTick(): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+async function setupWorker(options: {
+	addRepairResult?: Uint8Array;
+	cleanupBlocksDetailedResult?: Uint8Array;
+	cleanupBySbn?: (currentSbn: number) => Uint32Array;
+	config?: Partial<FecTrackConfig>;
+} = {}) {
+	const events: FecWorkerEvent[] = [];
+	const addSource = vi.fn(() => undefined);
+	const addRepair = vi.fn(() => options.addRepairResult);
+	let greenFillEnabled = false;
+	const cleanupBlocksDetailed = vi.fn(
+		() => greenFillEnabled
+			? options.cleanupBlocksDetailedResult ?? new Uint8Array()
+			: new Uint8Array(),
+	);
+	const cleanupBySbn = vi.fn(
+		options.cleanupBySbn ?? (() => new Uint32Array()),
+	);
+	const decoderConstructed = vi.fn();
+	const configureParams = vi.fn();
+	const flushDecoder = vi.fn();
+
+	class MockDecoder {
+		constructor(interleaveDepth: number, enableGreenFill: boolean) {
+			greenFillEnabled = enableGreenFill;
+			decoderConstructed(interleaveDepth, enableGreenFill);
+		}
+
+		add_source = addSource;
+		add_repair = addRepair;
+		configure_params = configureParams;
+		cleanup_blocks_detailed = cleanupBlocksDetailed;
+		cleanup_by_sbn = cleanupBySbn;
+		flush = flushDecoder;
+		pending_blocks = vi.fn(() => 0);
+		reset_stats = vi.fn();
+		get_stats = vi.fn(() => ({
+			source_packets: 0n,
+			repair_packets: 0n,
+			blocks_complete: 0n,
+			blocks_recovered: 0n,
+			blocks_failed: 0n,
+			bytes_recovered: 0n,
+			recovery_rate: () => 0,
+		}));
+		free = vi.fn();
+	}
+
+	const worker = {
+		__MMT_WASM_BINDINGS__: {
+			initSync: vi.fn(),
+			MmtFecDecoder: MockDecoder,
+		},
+		onmessage: undefined as ((event: MessageEvent<FecWorkerCommand>) => void) | undefined,
+		postMessage: vi.fn((event: FecWorkerEvent) => {
+			events.push(event);
+		}),
+	};
+
+	vi.stubGlobal("self", worker);
+	vi.resetModules();
+	await import("../fec-worker.ts");
+
+	const post = async (cmd: FecWorkerCommand) => {
+		worker.onmessage?.({ data: cmd } as MessageEvent<FecWorkerCommand>);
+		await nextTick();
+		await nextTick();
+	};
+
+	await post({
+		type: "configure",
+		config: { ...BASE_CONFIG, ...options.config },
+		wasmModule: EMPTY_WASM_MODULE,
+	});
+
+	return {
+		addSource,
+		addRepair,
+		cleanupBlocksDetailed,
+		cleanupBySbn,
+		decoderConstructed,
+		configureParams,
+		flush: flushDecoder,
+		events,
+		post,
+	};
+}
+
+function frameCleanupRecords(
+	records: Array<{ sbn: number; data: Uint8Array }>,
+): Uint8Array {
+	const size = records.reduce((total, record) => total + 8 + record.data.byteLength, 0);
+	const framed = new Uint8Array(size);
+	const view = new DataView(framed.buffer);
+	let offset = 0;
+	for (const record of records) {
+		view.setUint32(offset, record.sbn, false);
+		view.setUint32(offset + 4, record.data.byteLength, false);
+		offset += 8;
+		framed.set(record.data, offset);
+		offset += record.data.byteLength;
+	}
+	return framed;
+}
+
+afterEach(() => {
+	vi.unstubAllGlobals();
+});
+
+describe("FEC Worker repair symbol sizing", () => {
+	it("keeps WASM green fill enabled for video tracks", async () => {
+		const worker = await setupWorker();
+		try {
+			expect(worker.decoderConstructed).toHaveBeenCalledWith(
+				BASE_CONFIG.interleaveDepth,
+				true,
+			);
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+
+	it("does not emit H.264 green fill for failed audio blocks", async () => {
+		const worker = await setupWorker({
+			config: {
+				codec: "mp4a.40.2",
+				trackName: "audio",
+				trackType: "audio",
+			},
+			cleanupBlocksDetailedResult: frameCleanupRecords([
+				{ sbn: 16, data: new Uint8Array([0, 0, 0, 1, 0x0d]) },
+			]),
+		});
+		try {
+			expect(worker.decoderConstructed).toHaveBeenCalledWith(
+				BASE_CONFIG.interleaveDepth,
+				false,
+			);
+
+			await worker.post({ type: "cleanup", sbns: [16] });
+
+			expect(worker.events.some((event) => event.type === "greenFill")).toBe(false);
+			expect(worker.events).toContainEqual({
+				type: "cleanupComplete",
+				sbns: [16],
+			});
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+
+	it("drops malformed repair symbols before calling WASM add_repair", async () => {
+		const worker = await setupWorker();
+		try {
+			await worker.post({
+				type: "feedRepair",
+				ssStart: 8,
+				ssbLength: 4,
+				rsId: 0,
+				data: new Uint8Array([1, 2, 3]).buffer,
+				ts: 1000,
+			});
+
+			expect(worker.addRepair).not.toHaveBeenCalled();
+			expect(worker.events.some((event) =>
+				event.type === "error" &&
+				event.message.includes("Dropping repair symbol with invalid size"),
+			)).toBe(true);
+			await new Promise((resolve) => setTimeout(resolve, 220));
+			const snapshot = worker.events.filter((event) => event.type === "snapshot").at(-1);
+			expect(snapshot?.type).toBe("snapshot");
+			if (snapshot?.type === "snapshot") {
+				expect(snapshot.stats.repairSymbols).toBe(0);
+				expect(snapshot.stats.blocks).toEqual([]);
+				expect(snapshot.stats.repairSymbolSizeMismatch).toBe(1);
+			}
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+
+	it("deduplicates direct source and repair commands before decoder and counters", async () => {
+		const worker = await setupWorker();
+		try {
+			const source = {
+				type: "feedSource" as const,
+				ssId: 8,
+				data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+				ts: 1000,
+			};
+			const repair = {
+				type: "feedRepair" as const,
+				ssStart: 8,
+				ssbLength: BASE_CONFIG.k,
+				rsId: 0,
+				data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+				ts: 1001,
+			};
+			await worker.post(source);
+			await worker.post({...source, data: source.data.slice(0)});
+			await worker.post(repair);
+			await worker.post({...repair, data: repair.data.slice(0)});
+
+			expect(worker.addSource).toHaveBeenCalledOnce();
+			expect(worker.addRepair).toHaveBeenCalledOnce();
+			await new Promise((resolve) => setTimeout(resolve, 220));
+			const snapshot = worker.events.filter((event) => event.type === "snapshot").at(-1);
+			expect(snapshot?.type).toBe("snapshot");
+			if (snapshot?.type === "snapshot") {
+				expect(snapshot.stats.sourceSymbols).toBe(1);
+				expect(snapshot.stats.repairSymbols).toBe(1);
+				expect(snapshot.stats.blocks).toEqual([
+					expect.objectContaining({sbn: 2, sourceReceived: 1, repairReceived: 1}),
+				]);
+			}
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+
+	it("rejects noncanonical repair aliases and deduplicates canonical decoder identity", async () => {
+		const worker = await setupWorker();
+		try {
+			const data = () => new Uint8Array(BASE_CONFIG.symbolSize).buffer;
+			await worker.post({
+				type: "feedRepair",
+				ssStart: 8,
+				ssbLength: 4,
+				rsId: 1,
+				data: data(),
+				ts: 1000,
+			});
+			await worker.post({
+				type: "feedRepair",
+				ssStart: 9,
+				ssbLength: 4,
+				rsId: 1,
+				data: data(),
+				ts: 1001,
+			});
+			await worker.post({
+				type: "feedRepair",
+				ssStart: 6,
+				ssbLength: 3,
+				rsId: 2,
+				data: data(),
+				ts: 1002,
+			});
+
+			expect(worker.addRepair).toHaveBeenCalledOnce();
+			expect(worker.addRepair).toHaveBeenCalledWith(
+				8,
+				4,
+				1,
+				expect.any(Uint8Array),
+				1000,
+			);
+			expect(worker.events).toContainEqual(
+				expect.objectContaining({
+					type: "error",
+					code: "command-failed",
+					message: "[FecWorker] feedRepair: invalid repair symbol",
+				}),
+			);
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+
+	it("rejects repair geometry that disagrees with the configured fixed K", async () => {
+		const worker = await setupWorker({ config: { k: 4 } });
+		try {
+			for (const ssId of [6, 7, 8]) {
+				await worker.post({
+					type: "feedSource",
+					ssId,
+					data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+					ts: 1000 + ssId,
+				});
+			}
+			await worker.post({
+				type: "feedRepair",
+				ssStart: 6,
+				ssbLength: 3,
+				rsId: 0,
+				data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+				ts: 1010,
+			});
+
+			expect(worker.addSource).toHaveBeenCalledTimes(3);
+			expect(worker.addRepair).not.toHaveBeenCalled();
+			expect(worker.events).toContainEqual(
+				expect.objectContaining({
+					type: "error",
+					code: "command-failed",
+					message: "[FecWorker] feedRepair: invalid repair symbol",
+				}),
+			);
+			await new Promise((resolve) => setTimeout(resolve, 220));
+			const snapshot = worker.events.filter((event) => event.type === "snapshot").at(-1);
+			expect(snapshot?.type).toBe("snapshot");
+			if (snapshot?.type === "snapshot") {
+				expect(snapshot.stats.blocks).toHaveLength(2);
+				expect(snapshot.stats.blocks).toEqual(expect.arrayContaining([
+					expect.objectContaining({ sbn: 1, sourceReceived: 2, repairReceived: 0 }),
+					expect.objectContaining({ sbn: 2, sourceReceived: 1, repairReceived: 0 }),
+				]));
+			}
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+
+	it("accepts UINT32_MAX source IDs and rejects values that would wrap in WASM", async () => {
+		const worker = await setupWorker();
+		try {
+			await worker.post({
+				type: "feedSource",
+				ssId: UINT32_MAX,
+				data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+				ts: 1000,
+			});
+			await worker.post({
+				type: "feedSource",
+				ssId: UINT32_MAX + 1,
+				data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+				ts: 1001,
+			});
+
+			expect(worker.addSource).toHaveBeenCalledOnce();
+			expect(worker.addSource).toHaveBeenCalledWith(
+				UINT32_MAX,
+				expect.any(Uint8Array),
+				1000,
+			);
+			expect(worker.events).toContainEqual(
+				expect.objectContaining({
+					type: "error",
+					code: "command-failed",
+					message: "[FecWorker] feedSource: invalid source symbol",
+				}),
+			);
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+
+	it("enforces the RaptorQ allocation and MMTP repair-coordinate bounds", async () => {
+		const worker = await setupWorker({
+			config: { k: MAX_RAPTORQ_SOURCE_SYMBOLS_PER_BLOCK },
+		});
+		try {
+			const ssStart = Math.floor(
+				UINT32_MAX / MAX_RAPTORQ_SOURCE_SYMBOLS_PER_BLOCK,
+			) * MAX_RAPTORQ_SOURCE_SYMBOLS_PER_BLOCK;
+			const valid = {
+				type: "feedRepair" as const,
+				ssStart,
+				ssbLength: MAX_RAPTORQ_SOURCE_SYMBOLS_PER_BLOCK,
+				rsId: UINT24_MAX - MAX_RAPTORQ_SOURCE_SYMBOLS_PER_BLOCK,
+				data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+				ts: 1000,
+			};
+			await worker.post(valid);
+			for (const invalid of [
+				{ ...valid, ssStart: UINT32_MAX + 1 },
+				{ ...valid, ssStart: ssStart + 1 },
+				{
+					...valid,
+					ssbLength: MAX_RAPTORQ_SOURCE_SYMBOLS_PER_BLOCK + 1,
+				},
+				{ ...valid, rsId: valid.rsId + 1 },
+			]) {
+				await worker.post({ ...invalid, data: invalid.data.slice(0) });
+			}
+
+			expect(worker.addRepair).toHaveBeenCalledOnce();
+			expect(worker.addRepair).toHaveBeenCalledWith(
+				ssStart,
+				MAX_RAPTORQ_SOURCE_SYMBOLS_PER_BLOCK,
+				UINT24_MAX - MAX_RAPTORQ_SOURCE_SYMBOLS_PER_BLOCK,
+				expect.any(Uint8Array),
+				1000,
+			);
+			expect(
+				worker.events.filter(
+					(event) =>
+						event.type === "error" &&
+						event.message === "[FecWorker] feedRepair: invalid repair symbol",
+				),
+			).toHaveLength(4);
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+
+	it("rejects catalog K above the RaptorQ source-block allocation limit", async () => {
+		const worker = await setupWorker();
+		try {
+			await worker.post({
+				type: "configure",
+				config: {
+					...BASE_CONFIG,
+					k: MAX_RAPTORQ_SOURCE_SYMBOLS_PER_BLOCK + 1,
+				},
+				wasmModule: EMPTY_WASM_MODULE,
+			});
+
+			expect(worker.events).toContainEqual(
+				expect.objectContaining({
+					type: "error",
+					code: "command-failed",
+					message: expect.stringContaining(
+						`k must be an integer in 1..${MAX_RAPTORQ_SOURCE_SYMBOLS_PER_BLOCK}`,
+					),
+				}),
+			);
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+
+	it("rejects invalid interleave geometry before constructing a decoder", async () => {
+		const worker = await setupWorker({
+			config: { interleaveDepth: MAX_INTERLEAVE_DEPTH },
+		});
+		try {
+			for (const config of [
+				{ interleaveDepth: Number.NaN },
+				{ interleaveDepth: Number.POSITIVE_INFINITY },
+				{ interleaveDepth: 1.5 },
+				{ interleaveDepth: MAX_INTERLEAVE_DEPTH + 1 },
+				{ interleaveDepth: UINT32_MAX + 1 },
+				{ interleaveMs: Number.NaN },
+				{ interleaveMs: Number.POSITIVE_INFINITY },
+			]) {
+				await worker.post({
+					type: "configure",
+					config: { ...BASE_CONFIG, ...config },
+					wasmModule: EMPTY_WASM_MODULE,
+				});
+			}
+
+			expect(worker.decoderConstructed).toHaveBeenCalledOnce();
+			expect(worker.decoderConstructed).toHaveBeenCalledWith(
+				MAX_INTERLEAVE_DEPTH,
+				true,
+			);
+			expect(
+				worker.events.filter(
+					(event) => event.type === "error" && event.code === "command-failed",
+				),
+			).toHaveLength(7);
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+
+	it("bounds symbolSize to the Rust u16 contract before decoder construction", async () => {
+		const worker = await setupWorker({
+			config: { symbolSize: MAX_SYMBOL_SIZE },
+		});
+		try {
+			expect(worker.configureParams).toHaveBeenCalledWith(
+				BASE_CONFIG.k,
+				MAX_SYMBOL_SIZE,
+			);
+			for (const symbolSize of [
+				0,
+				1.5,
+				MAX_SYMBOL_SIZE - 1,
+				MAX_SYMBOL_SIZE + 1,
+				Number.NaN,
+				Number.POSITIVE_INFINITY,
+			]) {
+				await worker.post({
+					type: "configure",
+					config: { ...BASE_CONFIG, symbolSize },
+					wasmModule: EMPTY_WASM_MODULE,
+				});
+			}
+
+			expect(worker.decoderConstructed).toHaveBeenCalledOnce();
+			expect(worker.configureParams).toHaveBeenCalledOnce();
+			expect(
+				worker.events.filter(
+					(event) => event.type === "error" && event.code === "command-failed",
+				),
+			).toHaveLength(6);
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+
+	it("configures exact catalog geometry before admitting symbols", async () => {
+		const worker = await setupWorker({ config: { k: 2, symbolSize: 8 } });
+		try {
+			expect(worker.configureParams).toHaveBeenCalledWith(2, 8);
+			await worker.post({
+				type: "feedSource",
+				ssId: 0,
+				data: new Uint8Array(8).buffer,
+				ts: 1000,
+			});
+			await worker.post({ type: "reset" });
+			expect(worker.flush).toHaveBeenCalledOnce();
+			expect(worker.events).toContainEqual({ type: "resetComplete" });
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+
+	it("keeps evicted clean-block identities retired behind the decoder horizon", async () => {
+		const worker = await setupWorker({
+			config: { k: 1, interleaveDepth: 1 },
+		});
+		try {
+			for (let ssId = 0; ssId < 25; ssId++) {
+				await worker.post({
+					type: "feedSource",
+					ssId,
+					data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+					ts: 1000 + ssId,
+				});
+			}
+			expect(worker.addSource).toHaveBeenCalledTimes(25);
+
+			await worker.post({
+				type: "feedSource",
+				ssId: 24,
+				data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+				ts: 2000,
+			});
+			expect(worker.addSource).toHaveBeenCalledTimes(25);
+
+			await worker.post({
+				type: "feedSource",
+				ssId: 0,
+				data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+				ts: 2001,
+			});
+			expect(worker.addSource).toHaveBeenCalledTimes(25);
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+
+	it("accepts out-of-order media inside the retained decoder horizon", async () => {
+		const worker = await setupWorker({
+			config: { k: 2, interleaveDepth: 4 },
+		});
+		try {
+			await worker.post({
+				type: "feedSource",
+				ssId: 200,
+				data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+				ts: 1000,
+			});
+			for (let sbn = 96; sbn < 100; sbn++) {
+				await worker.post({
+					type: "feedSource",
+					ssId: sbn * 2,
+					data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+					ts: 1001 + sbn - 96,
+				});
+			}
+			expect(worker.addSource).toHaveBeenCalledTimes(5);
+
+			await worker.post({
+				type: "feedSource",
+				ssId: 200,
+				data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+				ts: 2000,
+			});
+
+			expect(worker.addSource).toHaveBeenCalledTimes(5);
+			expect(worker.cleanupBySbn).toHaveBeenLastCalledWith(100);
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+
+	it("keeps a lower interleaved block live when a higher SBN expires first", async () => {
+		const worker = await setupWorker({
+			config: { k: 2, interleaveDepth: 4 },
+		});
+		try {
+			await worker.post({
+				type: "feedSource",
+				ssId: 190,
+				data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+				ts: 1000,
+			});
+			await worker.post({ type: "cleanup", sbns: [100] });
+			await worker.post({
+				type: "feedSource",
+				ssId: 191,
+				data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+				ts: 1001,
+			});
+			await new Promise((resolve) => setTimeout(resolve, 220));
+
+			expect(worker.cleanupBlocksDetailed).toHaveBeenCalledWith(Uint32Array.of(100));
+			expect(worker.cleanupBySbn).toHaveBeenCalledTimes(2);
+			expect(worker.cleanupBySbn).toHaveBeenLastCalledWith(95);
+			expect(worker.addSource).toHaveBeenCalledTimes(2);
+			const snapshot = worker.events.filter((event) => event.type === "snapshot").at(-1);
+			expect(snapshot?.type).toBe("snapshot");
+			if (snapshot?.type === "snapshot") {
+				expect(snapshot.stats.sourceSymbols).toBe(2);
+				expect(snapshot.stats.blocksComplete).toBe(1);
+				expect(snapshot.stats.blocksFailed).toBe(1);
+				expect(snapshot.stats.blocks).toHaveLength(2);
+				expect(snapshot.stats.blocks).toEqual(expect.arrayContaining([
+					expect.objectContaining({ sbn: 95, state: "complete" }),
+					expect.objectContaining({ sbn: 100, state: "failed" }),
+				]));
+			}
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+
+	it("does not recreate or recount a block already retired by the media horizon", async () => {
+		const worker = await setupWorker({
+			config: { k: 2, interleaveDepth: 1 },
+			cleanupBySbn: (currentSbn) =>
+				currentSbn === 2 ? Uint32Array.of(0) : new Uint32Array(),
+		});
+		try {
+			await worker.post({
+				type: "feedSource",
+				ssId: 0,
+				data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+				ts: 1000,
+			});
+			await worker.post({
+				type: "feedSource",
+				ssId: 4,
+				data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+				ts: 1001,
+			});
+			await worker.post({ type: "cleanup", sbns: [0] });
+			await new Promise((resolve) => setTimeout(resolve, 220));
+
+			expect(worker.cleanupBlocksDetailed).not.toHaveBeenCalled();
+			expect(worker.events).toContainEqual({ type: "cleanupComplete", sbns: [0] });
+			const retiredUpdates = worker.events.filter(
+				(event) => event.type === "blockUpdate" && event.block.sbn === 0,
+			);
+			expect(retiredUpdates).toHaveLength(1);
+			const snapshot = worker.events.filter((event) => event.type === "snapshot").at(-1);
+			expect(snapshot?.type).toBe("snapshot");
+			if (snapshot?.type === "snapshot") {
+				expect(snapshot.stats.blocksFailed).toBe(1);
+				expect(snapshot.stats.blocks).toEqual([
+					expect.objectContaining({ sbn: 2, state: "collecting" }),
+				]);
+			}
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+
+	it("does not reopen a high finalized SBN after retiring older horizon tombstones", async () => {
+		const worker = await setupWorker({
+			config: { k: 2, interleaveDepth: 1 },
+		});
+		try {
+			for (const ssId of [200, 201]) {
+				await worker.post({
+					type: "feedSource",
+					ssId,
+					data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+					ts: 1000 + ssId,
+				});
+			}
+			for (let sbn = 0; sbn < 24; sbn++) {
+				await worker.post({ type: "cleanup", sbns: [sbn] });
+			}
+			await worker.post({
+				type: "feedSource",
+				ssId: 200,
+				data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+				ts: 2000,
+			});
+			await new Promise((resolve) => setTimeout(resolve, 220));
+
+			expect(worker.addSource).toHaveBeenCalledTimes(2);
+			expect(worker.events.some((event) => event.type === "frame")).toBe(false);
+			const snapshot = worker.events.filter((event) => event.type === "snapshot").at(-1);
+			expect(snapshot?.type).toBe("snapshot");
+			if (snapshot?.type === "snapshot") {
+				expect(snapshot.stats.sourceSymbols).toBe(2);
+				expect(snapshot.stats.blocks).toEqual([
+					expect.objectContaining({ sbn: 100, state: "complete" }),
+				]);
+			}
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+
+	it("clears block tombstones and accepted IDs before reconfiguration", async () => {
+		const worker = await setupWorker({ config: { k: 1 } });
+		try {
+			const source = {
+				type: "feedSource" as const,
+				ssId: 7,
+				data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+				ts: 1000,
+			};
+			const repair = {
+				type: "feedRepair" as const,
+				ssStart: 7,
+				ssbLength: 1,
+				rsId: 0,
+				data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+				ts: 999,
+			};
+			await worker.post(repair);
+			await worker.post(source);
+			await worker.post({ ...source, data: source.data.slice(0) });
+			await worker.post({ ...repair, data: repair.data.slice(0) });
+			expect(worker.addSource).toHaveBeenCalledOnce();
+			expect(worker.addRepair).toHaveBeenCalledOnce();
+
+			await worker.post({
+				type: "configure",
+				config: { ...BASE_CONFIG, k: 1 },
+				wasmModule: EMPTY_WASM_MODULE,
+			});
+			const configuredSnapshot = worker.events
+				.filter((event) => event.type === "snapshot")
+				.at(-1);
+			expect(configuredSnapshot?.type).toBe("snapshot");
+			if (configuredSnapshot?.type === "snapshot") {
+				expect(configuredSnapshot.stats.blocks).toEqual([]);
+			}
+
+			await worker.post({ ...repair, data: repair.data.slice(0), ts: 1999 });
+			await worker.post({ ...source, data: source.data.slice(0), ts: 2000 });
+			expect(worker.addSource).toHaveBeenCalledTimes(2);
+			expect(worker.addRepair).toHaveBeenCalledTimes(2);
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+
+	it("ignores forged path labels on raw Worker commands", async () => {
+		const worker = await setupWorker();
+		try {
+			await worker.post({
+				type: "feedSource",
+				ssId: 8,
+				data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+				ts: 1000,
+				source: "multicast",
+			} as unknown as FecWorkerCommand);
+			await worker.post({
+				type: "feedRepair",
+				ssStart: 8,
+				ssbLength: BASE_CONFIG.k,
+				rsId: 0,
+				data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+				ts: 1001,
+				source: "moq",
+			} as unknown as FecWorkerCommand);
+
+			await new Promise((resolve) => setTimeout(resolve, 220));
+			const snapshot = worker.events.filter((event) => event.type === "snapshot").at(-1);
+			expect(snapshot?.type).toBe("snapshot");
+			if (snapshot?.type === "snapshot") {
+				const block = snapshot.stats.blocks.find((candidate) => candidate.sbn === 2);
+				expect(block).not.toHaveProperty("multicastSymbols");
+				expect(block).not.toHaveProperty("moqSymbols");
+			}
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+
+	it("passes exact-size repair symbols to WASM add_repair", async () => {
+		const worker = await setupWorker();
+		try {
+			const data = new Uint8Array(BASE_CONFIG.symbolSize);
+			await worker.post({
+				type: "feedRepair",
+				ssStart: 8,
+				ssbLength: 4,
+				rsId: 1,
+				data: data.buffer,
+				ts: 1000,
+			});
+
+			expect(worker.addRepair).toHaveBeenCalledOnce();
+			expect(worker.addRepair).toHaveBeenCalledWith(
+				8,
+				4,
+				1,
+				expect.any(Uint8Array),
+				1000,
+			);
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+
+	it("identifies each recovered source-symbol slot in frame metadata", async () => {
+		const worker = await setupWorker({
+			addRepairResult: new Uint8Array(BASE_CONFIG.k * BASE_CONFIG.symbolSize),
+		});
+		try {
+			await worker.post({
+				type: "feedRepair",
+				ssStart: 8,
+				ssbLength: BASE_CONFIG.k,
+				rsId: 0,
+				data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+				ts: 1000,
+			});
+
+			const frames = worker.events.filter((event) => event.type === "frame");
+			expect(frames).toHaveLength(BASE_CONFIG.k);
+			expect(frames.map((event) => event.type === "frame" ? event.meta : null)).toEqual([
+				expect.objectContaining({ recovered: true, sbn: 2, esi: 0 }),
+				expect.objectContaining({ recovered: true, sbn: 2, esi: 1 }),
+				expect.objectContaining({ recovered: true, sbn: 2, esi: 2 }),
+				expect.objectContaining({ recovered: true, sbn: 2, esi: 3 }),
+			]);
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+
+	it("cleanup finalizes partial JS state and rejects late duplicate or unique symbols", async () => {
+		const worker = await setupWorker();
+		try {
+			await worker.post({
+				type: "feedSource",
+				ssId: 8,
+				data: new Uint8Array([1, 2, 3, 4]).buffer,
+				ts: 1000,
+			});
+			await worker.post({ type: "cleanup", sbns: [2] });
+			await worker.post({
+				type: "feedSource",
+				ssId: 8,
+				data: new Uint8Array([1, 2, 3, 4]).buffer,
+				ts: 1001,
+			});
+			await worker.post({
+				type: "feedSource",
+				ssId: 9,
+				data: new Uint8Array([1, 2, 3, 4]).buffer,
+				ts: 1002,
+			});
+			await new Promise((resolve) => setTimeout(resolve, 220));
+			expect(worker.events).toContainEqual({ type: "cleanupComplete", sbns: [2] });
+			expect(worker.addSource).toHaveBeenCalledOnce();
+
+			const snapshots = worker.events.filter((event) => event.type === "snapshot");
+			const last = snapshots.at(-1);
+			expect(last?.type).toBe("snapshot");
+			if (last?.type !== "snapshot") return;
+			expect(last.stats.blocksFailed).toBe(1);
+			expect(
+				last.stats.blocks.find((block) => block.sbn === 2)?.state,
+			).toBe("failed");
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+
+	it("cleanup tombstones an unseen SBN before later source or repair admission", async () => {
+		const worker = await setupWorker();
+		try {
+			await worker.post({ type: "cleanup", sbns: [2] });
+			await worker.post({
+				type: "feedSource",
+				ssId: 8,
+				data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+				ts: 1000,
+			});
+			await worker.post({
+				type: "feedRepair",
+				ssStart: 8,
+				ssbLength: BASE_CONFIG.k,
+				rsId: 0,
+				data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+				ts: 1001,
+			});
+			await new Promise((resolve) => setTimeout(resolve, 220));
+
+			expect(worker.cleanupBlocksDetailed).toHaveBeenCalledWith(Uint32Array.of(2));
+			expect(worker.events).toContainEqual({ type: "cleanupComplete", sbns: [2] });
+			expect(worker.addSource).not.toHaveBeenCalled();
+			expect(worker.addRepair).not.toHaveBeenCalled();
+			const snapshot = worker.events.filter((event) => event.type === "snapshot").at(-1);
+			expect(snapshot?.type).toBe("snapshot");
+			if (snapshot?.type === "snapshot") {
+				expect(snapshot.stats.blocksFailed).toBe(1);
+				expect(snapshot.stats.blocks).toEqual([
+					expect.objectContaining({
+						sbn: 2,
+						state: "failed",
+						sourceReceived: 0,
+						repairReceived: 0,
+					}),
+				]);
+			}
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+
+	it("rejects every non-uint32 cleanup SBN without WASM, JS, or acknowledgement side effects", async () => {
+		const worker = await setupWorker();
+		try {
+			await worker.post({
+				type: "feedSource",
+				ssId: 8,
+				data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+				ts: 1000,
+			});
+			for (const sbn of [UINT32_MAX + 1, -1, 1.5, Number.NaN, Number.POSITIVE_INFINITY]) {
+				await worker.post({
+					type: "cleanup",
+					sbns: [sbn],
+				} as FecWorkerCommand);
+			}
+
+			expect(worker.cleanupBlocksDetailed).not.toHaveBeenCalled();
+			expect(worker.events.some((event) => event.type === "cleanupComplete")).toBe(false);
+			expect(
+				worker.events.filter(
+					(event) =>
+						event.type === "error" &&
+						event.message === "[FecWorker] cleanup: invalid SBNs",
+				),
+			).toHaveLength(5);
+
+			await worker.post({
+				type: "feedSource",
+				ssId: 9,
+				data: new Uint8Array(BASE_CONFIG.symbolSize).buffer,
+				ts: 1001,
+			});
+			expect(worker.addSource).toHaveBeenCalledTimes(2);
+			await new Promise((resolve) => setTimeout(resolve, 220));
+			const snapshot = worker.events.filter((event) => event.type === "snapshot").at(-1);
+			expect(snapshot?.type).toBe("snapshot");
+			if (snapshot?.type === "snapshot") {
+				expect(snapshot.stats.blocksFailed).toBe(0);
+				expect(snapshot.stats.blocks).toEqual([
+					expect.objectContaining({ sbn: 2, sourceReceived: 2, state: "collecting" }),
+				]);
+			}
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+
+	it("emits per-SBN green fill records from one coalesced cleanup pass", async () => {
+		const fill16 = new Uint8Array([0, 0, 0, 1, 0x0d]);
+		const fill18 = new Uint8Array([0, 0, 0, 1, 0x0d]);
+		const worker = await setupWorker({
+			cleanupBlocksDetailedResult: frameCleanupRecords([
+				{ sbn: 16, data: fill16 },
+				{ sbn: 18, data: fill18 },
+			]),
+		});
+		try {
+			await worker.post({ type: "cleanup", sbns: [18, 16, 18] });
+
+			expect(worker.cleanupBlocksDetailed).toHaveBeenCalledOnce();
+			expect(worker.cleanupBlocksDetailed).toHaveBeenCalledWith(
+				Uint32Array.from([16, 18]),
+			);
+			const fills = worker.events.filter((event) => event.type === "greenFill");
+			expect(fills).toHaveLength(2);
+			expect(fills.map((event) => event.type === "greenFill" ? event.sbn : null))
+				.toEqual([16, 18]);
+			expect(
+				fills.map((event) =>
+					event.type === "greenFill" ? [...new Uint8Array(event.data)] : null,
+				),
+			).toEqual([[...fill16], [...fill18]]);
+			expect(worker.events).toContainEqual({
+				type: "cleanupComplete",
+				sbns: [16, 18],
+			});
+		} finally {
+			await worker.post({ type: "dispose" });
+		}
+	});
+});