@blockcast/fec-worker 0.1.0 → 0.3.0-main.10140e847083

package/dist/shred-worker-types.js

@@ -26,7 +26,7 @@
  * 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)
+ *   [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)
@@ -39,8 +39,23 @@
  * 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;

package/dist/shred-worker-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"shred-worker-types.js","sourceRoot":"","sources":["../src/shred-worker-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AACpC,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,CAAC;AACnC,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,CAAC;AAC7C,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC"}
+{"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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@blockcast/fec-worker",
-  "version": "0.1.0",
-  "description": "Worker-per-track FEC decode with zero-copy ArrayBuffer transfer and ALTA auth plumbing",
+  "version": "0.3.0-main.10140e847083",
+  "description": "Worker-per-track FEC decode with zero-copy ArrayBuffer transfer",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,7 +19,12 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts",
+    "!src/**/__tests__",
+    "!dist/**/*.test.*",
+    "!dist/**/*.spec.*"
   ],
   "scripts": {
     "build": "tsc && node build.mjs",
@@ -29,9 +34,7 @@
     "test": "vitest run",
     "test:watch": "vitest"
   },
-  "dependencies": {
-    "@blockcast/mmt-alta-parse": "^0.1.0"
-  },
+  "dependencies": {},
   "devDependencies": {
     "esbuild": "^0.28.0",
     "typescript": "^5.3.0",
@@ -42,8 +45,7 @@
     "worker",
     "raptorq",
     "zero-copy",
-    "transferable",
-    "alta"
+    "transferable"
   ],
   "license": "Apache-2.0",
   "repository": {

package/src/block-order.ts

@@ -0,0 +1,59 @@
+/**
+ * Order of iso-ssbg1-v1 FEC blocks on the 32-bit SS_ID (ISO/IEC 23008-1:2023
+ * C.5.2/C.5.3; RFC 1982 serial arithmetic, SERIAL_BITS = 32; BLO-35597 iso:5).
+ * The K-stride (SBN * K) order of the retired k-padded-v1 profile is gone.
+ */
+
+const SPAN = 0x1_0000_0000;
+const HALF = 0x8000_0000;
+
+// --- 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/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.
@@ -54,62 +68,38 @@ export class FecWorkerClient {
 
 	/**
 	 * Configure the Worker with FEC parameters and WASM module.
+	 * `interleaveMs: 0` is a valid no-span catalog value; in that mode the
+	 * caller supplies a positive receiver-local `deliveryWindowMs`.
 	 * 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);
+		this.#worker.postMessage(cmd);
 	}
 
 	/**
 	 * Feed a source symbol to the Worker. data ArrayBuffer is transferred (zero-copy).
-	 * Caller must not access data after this call — it is detached.
-	 *
-	 * 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.
+	 * Caller must not access data after this call — it is transferred with the
+	 * task's symbol batch, before any later command of this client.
 	 */
 	feedSource(
 		ssId: number,
 		data: ArrayBuffer,
 		ts: number,
-		alta?: { auth: ArrayBuffer; payloadEnd: number },
 	): void {
-		if (this.#disposed) return;
-		const cmd: FecWorkerCommand = alta
-			? {
-					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);
+		if (this.#disposed) throw new Error("[FecWorkerClient] feedSource on a disposed client");
+		this.#queueSymbol({ type: "feedSource", ssId, data, ts }, data);
 	}
 
 	/**
@@ -117,8 +107,8 @@ export class FecWorkerClient {
 	 * 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 * SSB_length)
-	 * - ssbLength: K for this block
+	 * - ssStart:   SS_ID of first source symbol in the block (any uint32; the block key)
+	 * - ssbLength: authored source-symbol count (1..configured K)
 	 * - rsId:      repair symbol index within the block
 	 */
 	feedRepair(
@@ -128,17 +118,38 @@ export class FecWorkerClient {
 		data: ArrayBuffer,
 		ts: number,
 	): void {
-		if (this.#disposed) return;
+		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): void {
+		if (!this.#batchSymbols) {
+			this.#worker.postMessage(symbol, [data]);
+			return;
+		}
+		this.#pendingSymbols.push(symbol);
+		this.#pendingTransfer.push(data);
+		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,
 		);
 	}
 
@@ -146,7 +157,8 @@ export class FecWorkerClient {
 	 * Submit relay block signature for verification. sig and hash are transferred.
 	 */
 	relayBlockSig(sbn: number, sig: ArrayBuffer, hash: ArrayBuffer): void {
-		if (this.#disposed) return;
+		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],
@@ -154,13 +166,14 @@ export class FecWorkerClient {
 	}
 
 	/**
-	 * Trigger cleanup after a block's inactivity deadline.
+	 * Trigger cleanup after a block's inactivity deadline. `currentSbn` is the
+	 * block key, the block's SS_Start.
 	 *
 	 * 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) return;
+		if (this.#disposed) throw new Error("[FecWorkerClient] cleanup on a disposed client");
 		if (
 			!Number.isInteger(currentSbn) ||
 			currentSbn < 0 ||
@@ -177,7 +190,8 @@ export class FecWorkerClient {
 
 	/** Reset this track's decoder epoch while preserving Worker configuration. */
 	reset(): void {
-		if (this.#disposed) return;
+		if (this.#disposed) throw new Error("[FecWorkerClient] reset on a disposed client");
+		this.#flushSymbols();
 		this.#pendingResets++;
 		this.#cleanupInFlight = null;
 		this.#queuedCleanupSbns.clear();
@@ -185,6 +199,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 +219,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. */
@@ -222,6 +253,16 @@ export class FecWorkerClient {
 		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.
@@ -229,6 +270,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);
@@ -236,6 +280,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;
@@ -261,9 +315,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);