@blockcast/fec-worker 0.1.0-main.c71423b8a4e4 → 0.1.0-main.ca0fdf0ae087

package/src/fec-worker-client.ts

@@ -10,6 +10,7 @@
 
 import type {
 	FecWorkerCommand,
+	FecSymbolCommand,
 	FecWorkerEvent,
 	FecTrackConfig,
 	FecTrackStats,
@@ -23,7 +24,6 @@ export class FecWorkerClient {
 	#onFrame: ((data: ArrayBuffer, meta: FrameMeta) => void) | null = null;
 	#onSnapshot: ((stats: FecTrackStats) => void) | null = null;
 	#onBlockUpdate: ((block: FecBlockSnapshot) => void) | null = null;
-	#onGreenFill: ((sbn: number, data: ArrayBuffer) => void) | null = null;
 	#onCleanupComplete: ((sbn: number) => void) | null = null;
 	#onError: ((message: string, code?: FecWorkerErrorCode) => void) | null = null;
 	#cleanupInFlight: Set<number> | null = null;
@@ -31,6 +31,20 @@ export class FecWorkerClient {
 	#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.
@@ -66,6 +80,7 @@ export class FecWorkerClient {
 		altaWasmModule?: WebAssembly.Module,
 	): void {
 		if (this.#disposed) throw new Error("[FecWorkerClient] disposed");
+		this.#flushSymbols();
 		const cmd: FecWorkerCommand = {
 			type: "configure",
 			config,
@@ -84,7 +99,8 @@ export class FecWorkerClient {
 
 	/**
 	 * Feed a source symbol to the Worker. data ArrayBuffer is transferred (zero-copy).
-	 * Caller must not access data after this call — it is detached.
+	 * 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
@@ -98,18 +114,22 @@ export class FecWorkerClient {
 		alta?: { auth: ArrayBuffer; payloadEnd: number },
 	): void {
 		if (this.#disposed) throw new Error("[FecWorkerClient] feedSource on a disposed client");
-		const cmd: FecWorkerCommand = alta
-			? {
+		if (alta) {
+			this.#queueSymbol(
+				{
 					type: "feedSource",
 					ssId,
 					data,
 					ts,
 					altaAuth: alta.auth,
 					altaPayloadEnd: alta.payloadEnd,
-				}
-			: { type: "feedSource", ssId, data, ts };
-		const transfer: Transferable[] = alta ? [data, alta.auth] : [data];
-		this.#worker.postMessage(cmd, transfer);
+				},
+				data,
+				alta.auth,
+			);
+		} else {
+			this.#queueSymbol({ type: "feedSource", ssId, data, ts }, data);
+		}
 	}
 
 	/**
@@ -129,16 +149,38 @@ export class FecWorkerClient {
 		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: "feedRepair",
-				ssStart,
-				ssbLength,
-				rsId,
-				data,
-				ts,
-			} satisfies FecWorkerCommand,
-			[data],
+			{ type: "feedSymbols", symbols } satisfies FecWorkerCommand,
+			transfer,
 		);
 	}
 
@@ -147,6 +189,7 @@ export class FecWorkerClient {
 	 */
 	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],
@@ -178,6 +221,7 @@ export class FecWorkerClient {
 	/** 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();
@@ -185,6 +229,9 @@ export class FecWorkerClient {
 	}
 
 	#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(
@@ -202,14 +249,28 @@ export class FecWorkerClient {
 		this.#onSnapshot = cb;
 	}
 
-	/** Register callback for individual block state changes. */
+	/**
+	 * 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();
 	}
 
-	/** Register callback for green-fill frames. */
-	onGreenFill(cb: (sbn: number, data: ArrayBuffer) => void): void {
-		this.#onGreenFill = cb;
+	#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. */
@@ -239,6 +300,9 @@ export class FecWorkerClient {
 	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);
@@ -246,6 +310,16 @@ export class FecWorkerClient {
 	}
 
 	#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;
@@ -271,9 +345,6 @@ export class FecWorkerClient {
 			case "blockUpdate":
 				this.#onBlockUpdate?.(event.block);
 				break;
-			case "greenFill":
-				this.#onGreenFill?.(event.sbn, event.data);
-				break;
 			case "cleanupComplete":
 				for (const sbn of event.sbns) {
 					this.#onCleanupComplete?.(sbn);

package/src/fec-worker-types.ts

@@ -57,13 +57,15 @@ export interface FecBlockSnapshot {
 	/** Source block number */
 	sbn: number;
 	/** Current block state */
-	state: "collecting" | "complete" | "recovered" | "failed" | "green-fill";
+	state: "collecting" | "complete" | "recovered" | "failed";
 	/** Number of source symbols received */
 	sourceReceived: number;
 	/** Number of repair symbols received */
 	repairReceived: number;
-	/** Expected source symbols (K) */
+	/** Configured source-block geometry (K) */
 	k: number;
+	/** Authored source symbols (SSB_length) once a repair symbol declared it */
+	ssbLength?: number;
 	/** Expected repair symbols (P) */
 	repairCount: number;
 	/** Timestamp of first symbol arrival (ms) */
@@ -97,8 +99,6 @@ export interface FecTrackStats {
 	blocksRecovered: number;
 	/** Blocks that failed (unrecoverable) */
 	blocksFailed: number;
-	/** Frames replaced with green-fill */
-	greenFillFrames: number;
 	/** Recovery success rate 0-100 */
 	recoveryRate: number;
 
@@ -168,7 +168,9 @@ export interface FecTrackStats {
 export type FecWorkerErrorCode =
 	| "recovered-symbol-size-unconfigured"
 	| "recovered-block-too-short"
+	| "recovered-symbol-ssb-length-invalid"
 	| "repair-symbol-size-mismatch"
+	| "repair-ssb-length-conflict"
 	| "reset-failed"
 	| "unknown-command"
 	| "command-failed"
@@ -185,8 +187,14 @@ export interface FrameMeta {
 	recovered: boolean;
 	/** Source block number this frame belongs to */
 	sbn: number;
-	/** Encoding Symbol ID within the recovered source block (0..K-1). */
+	/** Encoding Symbol ID within the recovered source block (0..ssbLength-1). */
 	esi?: number;
+	/**
+	 * Authored source-symbol count of the recovered block (the repair
+	 * symbols' SSB_length, 1..K). Recovered frames are ESI 0..ssbLength-1;
+	 * ESIs ssbLength..K-1 are encoder zero padding and are never emitted.
+	 */
+	ssbLength?: number;
 }
 
 // --- Worker commands (main -> worker) ---
@@ -241,6 +249,17 @@ export type FecWorkerCommand =
 			data: ArrayBuffer;
 			ts: number;
 	  }
+	| {
+			/**
+			 * Every source and repair symbol the page fed in one task, in feed
+			 * order, sharing one transfer list. The client sends symbols this
+			 * way instead of one message per symbol (BLO-36599); the Worker
+			 * handles each record exactly like the single-symbol command of the
+			 * same `type`, and a record that fails does not stop the others.
+			 */
+			type: "feedSymbols";
+			symbols: FecSymbolCommand[];
+	  }
 	| {
 			type: "relayBlockSig";
 			sbn: number;
@@ -253,8 +272,21 @@ export type FecWorkerCommand =
 			sbns: number[];
 	  }
 	| { type: "reset" }
+	/**
+	 * Ask the Worker to post a blockUpdate on every block transition. Without
+	 * it the Worker posts none: each one is a structured clone and a task on
+	 * the page thread, and the player does not consume them (BLO-36599).
+	 * Sent only to a Worker that announced it in `capabilities`.
+	 */
+	| { type: "subscribeBlockUpdates" }
 	| { type: "dispose" };
 
+/** One symbol record of a `feedSymbols` batch. */
+export type FecSymbolCommand = Extract<
+	FecWorkerCommand,
+	{ type: "feedSource" } | { type: "feedRepair" }
+>;
+
 // --- Worker events (worker -> main) ---
 
 /** Discriminated union of all events emitted from Worker to main thread. */
@@ -262,7 +294,16 @@ export type FecWorkerEvent =
 	| { type: "frame"; data: ArrayBuffer; meta: FrameMeta }
 	| { type: "snapshot"; stats: FecTrackStats }
 	| { type: "blockUpdate"; block: FecBlockSnapshot }
-	| { type: "greenFill"; sbn: number; data: ArrayBuffer }
 	| { type: "cleanupComplete"; sbns: number[] }
 	| { type: "resetComplete" }
+	/**
+	 * Optional commands this Worker accepts, posted once it is configured.
+	 * The client uses `feedSymbols` only after the Worker names it, so a page
+	 * that meets an older cached Worker bundle keeps sending one command per
+	 * symbol instead of a batch that Worker would reject (BLO-36599).
+	 */
+	| { type: "capabilities"; commands: FecWorkerOptionalCommand[] }
 	| { type: "error"; message: string; code?: FecWorkerErrorCode };
+
+/** Commands a client may send only after the Worker announced them. */
+export type FecWorkerOptionalCommand = "feedSymbols" | "subscribeBlockUpdates";

package/src/fec-worker.ts

@@ -40,8 +40,12 @@ interface WasmFecDecoder {
 		timestamp: number,
 	): Uint8Array | undefined;
 	configure_params(k: number, symbolSize: number): void;
-	/** Block-scoped counterpart driven by the manager's exact deadlines. */
-	cleanup_blocks_detailed(sbns: Uint32Array): Uint8Array;
+	/**
+	 * Retire the named blocks (last-chance decode + stats), driven by the
+	 * manager's exact deadlines. Nothing is synthesised for a lost block:
+	 * concealment is the sink's hold-last-good-frame.
+	 */
+	cleanup_blocks_detailed(sbns: Uint32Array): void;
 	/** Remove decoder blocks below its configured live-SBN interleave horizon. */
 	cleanup_by_sbn(current_sbn: number): Uint32Array;
 	flush(): void;
@@ -61,10 +65,7 @@ interface WasmFecDecoder {
 
 interface WasmBindings {
 	initSync(module: { module: WebAssembly.Module }): unknown;
-	MmtFecDecoder: new (
-		interleaveDepth: number,
-		greenFillEnabled: boolean,
-	) => WasmFecDecoder;
+	MmtFecDecoder: new (interleaveDepth: number) => WasmFecDecoder;
 }
 
 // --- Worker state (local to this Worker instance) ---
@@ -75,6 +76,8 @@ let altaEnabled = false;
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 let altaVerifier: any = null;  // JsAltaVerifier instance (loaded from ALTA WASM)
 let snapshotTimer: ReturnType<typeof setInterval> | null = null;
+// blockUpdate events are posted only after a client subscribes (BLO-36599).
+let blockUpdatesSubscribed = false;
 
 // Block tracking
 const blocks = new Map<number, FecBlockSnapshot>();
@@ -95,7 +98,6 @@ let repairSymbols = 0;
 let blocksComplete = 0;
 let blocksRecovered = 0;
 let blocksFailed = 0;
-let greenFillFrames = 0;
 let altaVerified = 0;
 let altaFailed = 0;            // Crypto-confirmed tamper (MAC / sig / hash chain mismatch)
 const altaFailedDetails: Array<{
@@ -444,7 +446,6 @@ function buildStatsSnapshot(): FecTrackStats {
 		blocksComplete,
 		blocksRecovered,
 		blocksFailed,
-		greenFillFrames,
 		recoveryRate:
 			blocksComplete + blocksRecovered > 0
 				? Math.round(
@@ -478,6 +479,7 @@ function emitSnapshot(): void {
 }
 
 function emitBlockUpdate(block: FecBlockSnapshot): void {
+	if (!blockUpdatesSubscribed) return;
 	emit({ type: "blockUpdate", block: { ...block } });
 }
 
@@ -496,16 +498,19 @@ function emitRecoveredSymbols(
 		});
 		return;
 	}
-	if (recoveredBlock.byteLength < symbolSize * config.k) {
+	// The decoder returns only the block's authored source symbols
+	// (SSB_length x T); the encoder's zero padding is not media.
+	const ssbLength = block.ssbLength ?? config.k;
+	if (recoveredBlock.byteLength !== symbolSize * ssbLength) {
 		emit({
 			type: "error",
 			code: "recovered-block-too-short",
-			message: `[FecWorker] recovered block too short: got ${recoveredBlock.byteLength}B, expected at least ${symbolSize * config.k}B`,
+			message: `[FecWorker] recovered block has the wrong length: got ${recoveredBlock.byteLength}B, expected ${symbolSize * ssbLength}B (SSB_length=${ssbLength})`,
 		});
 		return;
 	}
 
-	for (let i = 0; i < config.k; i++) {
+	for (let i = 0; i < ssbLength; i++) {
 		const symbol = recoveredBlock.subarray(i * symbolSize, (i + 1) * symbolSize);
 
 		// Source authentication now runs once at router admission in
@@ -520,6 +525,7 @@ function emitRecoveredSymbols(
 			recovered: true,
 			sbn,
 			esi: i,
+			ssbLength,
 		};
 		emit({ type: "frame", data: buf, meta }, [buf]);
 	}
@@ -611,10 +617,7 @@ async function handleConfigure(
 
 	// Decoder policy and geometry are explicit at the epoch boundary. The WASM
 	// module has no guessed K/T/interleave slow path.
-	wasmDecoder = new wasm.MmtFecDecoder(
-		cmd.config.interleaveDepth,
-		cmd.config.trackType === "video",
-	);
+	wasmDecoder = new wasm.MmtFecDecoder(cmd.config.interleaveDepth);
 	config = cmd.config;
 	altaEnabled = !!cmd.altaPublicKey;
 
@@ -662,6 +665,10 @@ async function handleConfigure(
 
 	wasmDecoder.configure_params(config.k, config.symbolSize);
 
+	// Tell the client which optional commands this Worker accepts, so it can
+	// batch symbols without risking a Worker that predates the batch command.
+	emit({ type: "capabilities", commands: ["feedSymbols", "subscribeBlockUpdates"] });
+
 	// Start periodic snapshot emission (200ms floor)
 	startSnapshotTimer();
 
@@ -716,9 +723,11 @@ function handleFeedSource(
 	// authenticated by the canonical manifest verifier at router admission.
 	if (altaEnabled) altaPending++;
 
-	// Check if block is complete (all K source symbols received)
+	// Check if block is complete (all authored source symbols received:
+	// SSB_length once a repair symbol declared it, otherwise K)
+	const authoredLength = block.ssbLength ?? block.k;
 	if (
-		block.sourceReceived >= block.k &&
+		block.sourceReceived >= authoredLength &&
 		block.state === "collecting"
 	) {
 		markBlockTerminal(block, "complete");
@@ -730,7 +739,7 @@ function handleFeedSource(
 		// of earlier missing symbols after repair arrived. Clean completion is
 		// already routed by the source path, so only emit when the block did not
 		// reach K source arrivals.
-		if (result && result.byteLength > 0 && block.sourceReceived < block.k) {
+		if (result && result.byteLength > 0 && block.sourceReceived < authoredLength) {
 			const recovered = new Uint8Array(toOwnedArrayBuffer(result));
 			const recoveryMs = performance.now() - block.firstSymbolTs;
 			recoveryTimes.push(recoveryMs);
@@ -786,6 +795,16 @@ function handleFeedRepair(
 	const existingBlock = blocks.get(sbn);
 	if (existingBlock && isTerminalBlock(existingBlock)) return;
 	if (acceptedRepairEsis.get(sbn)?.has(repairEsi)) return;
+	// One block has one authored SSB_length; a repair symbol naming another
+	// is dropped before it reaches the decoder (which rejects it too).
+	if (existingBlock?.ssbLength !== undefined && existingBlock.ssbLength !== cmd.ssbLength) {
+		emit({
+			type: "error",
+			code: "repair-ssb-length-conflict",
+			message: `[FecWorker] Dropping repair symbol whose SSB_length ${cmd.ssbLength} conflicts with ${existingBlock.ssbLength} (sbn=${sbn})`,
+		});
+		return;
+	}
 
 	const result = wasmDecoder.add_repair(
 		cmd.ssStart,
@@ -802,13 +821,20 @@ function handleFeedRepair(
 	}
 	repairEsis.add(repairEsi);
 	const block = getOrCreateBlock(sbn);
+	block.ssbLength = cmd.ssbLength;
 	block.repairReceived++;
 	block.lastSymbolTs = performance.now();
 	repairSymbols++;
-		// If WASM returned data, it is the recovered source block: K fixed-width
-		// source symbols concatenated. Split it before emitting so MmtpRouter gets
-		// the same one-symbol shape as a direct source packet.
-		if (result && result.byteLength > 0) {
+		// Every authored source symbol already arrived: knowing SSB_length makes
+		// the block clean. The decoder's return is the source already routed.
+		// Otherwise, returned data is the recovered source block: its SSB_length
+		// fixed-width authored symbols concatenated. Split it before emitting so
+		// MmtpRouter gets the same one-symbol shape as a direct source packet.
+		if (block.sourceReceived >= cmd.ssbLength && block.state === "collecting") {
+			markBlockTerminal(block, "complete");
+			blocksComplete++;
+			emitBlockUpdate(block);
+		} else if (result && result.byteLength > 0) {
 			const recovered = new Uint8Array(toOwnedArrayBuffer(result));
 			const recoveryMs = performance.now() - block.firstSymbolTs;
 			recoveryTimes.push(recoveryMs);
@@ -855,21 +881,19 @@ function handleCleanup(
 			throw new Error("[FecWorker] cleanup: not configured");
 		}
 
-		// Call WASM cleanup only after all earlier symbol commands have drained.
-		// The detailed API carries the true owner of every fill emitted by a
-		// single cleanup pass; command coalescing must not infer ownership from
-		// the largest timed-out SBN.
-		const cleanupRecords = pendingSbns.length > 0
-			? wasmDecoder.cleanup_blocks_detailed(Uint32Array.from(pendingSbns))
-			: new Uint8Array();
+		// Call WASM cleanup only after all earlier symbol commands have drained,
+		// and only for the exact SBNs the manager's deadlines named; command
+		// coalescing must not infer ownership from the largest timed-out SBN.
+		if (pendingSbns.length > 0) {
+			wasmDecoder.cleanup_blocks_detailed(Uint32Array.from(pendingSbns));
+		}
 		// Manager deadlines are block-scoped and may expire a newer SBN while an
 		// older interleaved block is still live. Only accepted media progression
 		// advances the shared JS/Rust horizon; cleanup creates exact tombstones.
 
 		// Rust already finalized every SBN behind the media frontier. For each
 		// remaining exact request, mirror the block-scoped WASM boundary immediately
-		// so JS never retains state for a decoder block that is gone, even if decoding
-		// the trusted cleanup framing were to fail.
+		// so JS never retains state for a decoder block that is gone.
 		for (const sbn of pendingSbns) {
 			let currentBlock = blocks.get(sbn);
 			if (currentBlock && isTerminalBlock(currentBlock)) {
@@ -886,12 +910,6 @@ function handleCleanup(
 			}
 			emitBlockUpdate(currentBlock);
 		}
-
-		const greenFills = decodeCleanupRecords(cleanupRecords);
-		for (const { sbn, data } of greenFills) {
-			greenFillFrames++;
-			emit({ type: "greenFill", sbn, data }, [data]);
-		}
 	} finally {
 		// Message ordering makes this an acknowledgement that every source/repair
 		// command posted before cleanup has completed. The main thread must not
@@ -900,29 +918,6 @@ function handleCleanup(
 	}
 }
 
-function decodeCleanupRecords(
-	framed: Uint8Array,
-): Array<{ sbn: number; data: ArrayBuffer }> {
-	const records: Array<{ sbn: number; data: ArrayBuffer }> = [];
-	const view = new DataView(framed.buffer, framed.byteOffset, framed.byteLength);
-	let offset = 0;
-	while (offset < framed.byteLength) {
-		if (framed.byteLength - offset < 8) {
-			throw new Error("[FecWorker] cleanup_blocks_detailed: truncated record header");
-		}
-		const sbn = view.getUint32(offset, false);
-		const length = view.getUint32(offset + 4, false);
-		offset += 8;
-		if (length > framed.byteLength - offset) {
-			throw new Error("[FecWorker] cleanup_blocks_detailed: truncated record payload");
-		}
-		const data = toOwnedArrayBuffer(framed.subarray(offset, offset + length));
-		records.push({ sbn, data });
-		offset += length;
-	}
-	return records;
-}
-
 function handleDispose(): void {
 	// Clear snapshot timer (MUST clear to prevent leaks)
 	if (snapshotTimer !== null) {
@@ -979,7 +974,6 @@ function handleReset(): void {
 	blocksComplete = 0;
 	blocksRecovered = 0;
 	blocksFailed = 0;
-	greenFillFrames = 0;
 	altaVerified = 0;
 	altaFailed = 0;
 	altaFailedDetails.length = 0;
@@ -994,6 +988,38 @@ function handleReset(): void {
 	if (config) emitSnapshot();
 }
 
+/**
+ * A batch of symbols fed in one page task (BLO-36599). Each record is
+ * handled exactly as its single-symbol command would be, in order, and a
+ * failing record reports the same `command-failed` error that command would
+ * without stopping the records after it.
+ */
+function handleFeedSymbols(
+	cmd: Extract<FecWorkerCommand, { type: "feedSymbols" }>,
+): void {
+	if (!Array.isArray(cmd.symbols)) {
+		throw new Error("[FecWorker] feedSymbols: symbols must be an array");
+	}
+	for (const symbol of cmd.symbols) {
+		try {
+			if (symbol?.type === "feedSource") handleFeedSource(symbol);
+			else if (symbol?.type === "feedRepair") handleFeedRepair(symbol);
+			else {
+				throw new Error(
+					`[FecWorker] feedSymbols: unknown symbol type ${String((symbol as { type?: unknown } | null)?.type)}`,
+				);
+			}
+		} catch (err) {
+			emit({
+				type: "error",
+				code: "command-failed",
+				message:
+					err instanceof Error ? err.message : `[FecWorker] ${String(err)}`,
+			});
+		}
+	}
+}
+
 // --- Main message handler ---
 
 async function dispatchCommand(cmd: FecWorkerCommand): Promise<void> {
@@ -1011,6 +1037,9 @@ async function dispatchCommand(cmd: FecWorkerCommand): Promise<void> {
 			case "feedRepair":
 				handleFeedRepair(cmd);
 				break;
+			case "feedSymbols":
+				handleFeedSymbols(cmd);
+				break;
 			case "relayBlockSig":
 				handleRelayBlockSig(cmd);
 				break;
@@ -1020,6 +1049,9 @@ async function dispatchCommand(cmd: FecWorkerCommand): Promise<void> {
 			case "reset":
 				handleReset();
 				break;
+			case "subscribeBlockUpdates":
+				blockUpdatesSubscribed = true;
+				break;
 			case "dispose":
 				handleDispose();
 				break;

package/src/index.ts

@@ -6,6 +6,8 @@
 
 export type {
 	FecWorkerCommand,
+	FecSymbolCommand,
+	FecWorkerOptionalCommand,
 	FecWorkerEvent,
 	FecWorkerErrorCode,
 	FecTrackConfig,