@blockcast/fec-worker 0.1.0-main.ce3c8aeb7f68 → 0.1.0-main.d0bb31684c09

package/src/fec-worker.ts

@@ -20,6 +20,7 @@ import type {
 	FrameMeta,
 } from "./fec-worker-types.js";
 import { toOwnedArrayBuffer } from "./transfer.js";
+import { blockPrecedes, blocksBehind } from "./block-order.js";
 
 // --- WASM binding types (from mmt-wasm) ---
 // Signatures MUST match a freshly generated external mmt_wasm.d.ts exactly.
@@ -40,8 +41,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 +66,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) ---
@@ -97,7 +99,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<{
@@ -115,11 +116,35 @@ let altaInitFailed = false;    // ALTA configured but WASM init failed; altaEnab
 let relayBlocksVerified = 0;
 let relayBlocksFailed = 0;
 let liveSbn = 0;
-// Highest SBN that has fallen strictly below the decoder's retained
-// interleave window. Numeric ordering is per decoder epoch; reset/configure
-// starts a new epoch before the 32-bit source-symbol counter can wrap.
-let retiredSbnFrontier = -1;
+// Whether liveSbn has been set by a symbol of this decoder epoch. Block order
+// is serial on the 32-bit SS_ID (block-order.ts, BLO-35597 iso:5), where 0 is
+// a real position, so "nothing seen yet" needs its own state.
+let liveSbnKnown = false;
 let repairSymbolSizeMismatch = 0;
+// Source symbols dropped before WASM, by cause. All three sites below were
+// silent, which left the "block settles at exactly K-1 source symbols" shape
+// (BLO-35597 defect 2) with no evidence to attribute it to. A retired drop
+// means a late symbol past retention; a terminal drop means the block had
+// already settled — `state !== "collecting"`, so complete OR recovered OR
+// FAILED, and the failed arm is the one this issue is chasing (a block aged out
+// by synchronizeDecoderHorizon stays in `blocks` until its SBN retires, so a
+// late symbol for a short block lands here); a duplicate drop means a repeated
+// (SBN, ESI), which on this wire is usually a plain duplicate packet — the
+// router's ledger has deliberate gaps — and only sometimes an SBN/ESI
+// derivation collision.
+//
+// These narrow the cause; they do not uniquely attribute it. A symbol LOST IN
+// TRANSIT never reaches handleFeedSource and increments nothing, so all three
+// reading zero on a short block is NOT evidence of a publisher defect — wire
+// loss is the null hypothesis here, and it produces an identical shape. The
+// discriminator for that residual arm is `block.ssbLength` (set at the repair
+// symbol's declared SSB_length, conflict-checked on arrival):
+//   ssbLength < k                        → genuinely short authored block
+//   ssbLength === k, sourceReceived < k  → loss or a still-late symbol
+// With no repair symbol yet seen, ssbLength is undefined and both stay open.
+let sourceDroppedRetired = 0;
+let sourceDroppedTerminal = 0;
+let sourceDroppedDuplicate = 0;
 
 // Recovery timing
 const recoveryTimes: number[] = [];
@@ -179,7 +204,18 @@ function clearBlockTracking(): void {
 	pendingVerify.clear();
 	recoveryTimes.length = 0;
 	liveSbn = 0;
-	retiredSbnFrontier = -1;
+	liveSbnKnown = false;
+}
+
+/**
+ * Whether `sbn` has fallen behind the decoder's retained interleave window:
+ * more than `interleaveDepth` blocks behind the live SBN. liveSbn only moves
+ * forward within a decoder epoch and configure() resets both, so this is the
+ * monotonic retirement frontier the decoder horizon implies.
+ */
+function isRetiredSbn(sbn: number): boolean {
+	return config !== null && liveSbnKnown &&
+		blocksBehind(sbn, liveSbn, config.k) > config.interleaveDepth;
 }
 
 /**
@@ -190,17 +226,16 @@ function clearBlockTracking(): void {
  */
 function trimBlockRetention(): void {
 	for (const [sbn, block] of blocks) {
-		if (!isTerminalBlock(block) || sbn > retiredSbnFrontier) continue;
+		if (!isTerminalBlock(block) || !isRetiredSbn(sbn)) continue;
 		blocks.delete(sbn);
 		retireAcceptedIds(sbn);
 	}
 }
 
 function advanceMediaHorizon(sbn: number): void {
-	if (!config || sbn <= liveSbn) return;
+	if (!config || (liveSbnKnown && !blockPrecedes(liveSbn, sbn, config.k))) return;
 	liveSbn = sbn;
-	const firstRetainedSbn = Math.max(0, liveSbn - config.interleaveDepth);
-	retiredSbnFrontier = Math.max(retiredSbnFrontier, firstRetainedSbn - 1);
+	liveSbnKnown = true;
 	trimBlockRetention();
 }
 
@@ -215,7 +250,7 @@ function markBlockTerminal(
 }
 
 function synchronizeDecoderHorizon(): void {
-	if (!wasmDecoder) return;
+	if (!wasmDecoder || !liveSbnKnown) return;
 	const expired = wasmDecoder.cleanup_by_sbn(liveSbn);
 	for (const sbn of expired) {
 		const block = blocks.get(sbn);
@@ -446,7 +481,6 @@ function buildStatsSnapshot(): FecTrackStats {
 		blocksComplete,
 		blocksRecovered,
 		blocksFailed,
-		greenFillFrames,
 		recoveryRate:
 			blocksComplete + blocksRecovered > 0
 				? Math.round(
@@ -470,6 +504,9 @@ function buildStatsSnapshot(): FecTrackStats {
 		avgRecoveryMs: Math.round(avgRecoveryMs * 100) / 100,
 		maxRecoveryMs: Math.round(maxRecoveryMs * 100) / 100,
 		repairSymbolSizeMismatch,
+		sourceDroppedRetired,
+		sourceDroppedTerminal,
+		sourceDroppedDuplicate,
 		decoder,
 	};
 }
@@ -618,10 +655,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;
 
@@ -702,10 +736,19 @@ function handleFeedSource(
 	// value internally (ISO 23008-1 §C.5.2: SBN = floor(SS_ID / K)).
 	const sbn = config.k > 0 ? Math.floor(cmd.ssId / config.k) : cmd.ssId;
 	const esi = cmd.ssId % config.k;
-	if (sbn <= retiredSbnFrontier) return;
+	if (isRetiredSbn(sbn)) {
+		sourceDroppedRetired++;
+		return;
+	}
 	const existingBlock = blocks.get(sbn);
-	if (existingBlock && isTerminalBlock(existingBlock)) return;
-	if (acceptedSourceEsis.get(sbn)?.has(esi)) return;
+	if (existingBlock && isTerminalBlock(existingBlock)) {
+		sourceDroppedTerminal++;
+		return;
+	}
+	if (acceptedSourceEsis.get(sbn)?.has(esi)) {
+		sourceDroppedDuplicate++;
+		return;
+	}
 
 	const result = wasmDecoder.add_source(cmd.ssId, view, cmd.ts);
 	advanceMediaHorizon(sbn);
@@ -795,7 +838,11 @@ function handleFeedRepair(
 	}
 	const sbn = Math.floor(cmd.ssStart / config.k);
 	const repairEsi = config.k + cmd.rsId;
-	if (sbn <= retiredSbnFrontier) return;
+	// The repair path's mirror drops stay silent and uncounted: BLO-35597
+	// defect 2 is a source-symbol shortfall, so only the source side needed
+	// evidence. The asymmetry is deliberate, not an oversight — extend these
+	// the same way if a repair-side shortfall ever needs attributing.
+	if (isRetiredSbn(sbn)) return;
 	const existingBlock = blocks.get(sbn);
 	if (existingBlock && isTerminalBlock(existingBlock)) return;
 	if (acceptedRepairEsis.get(sbn)?.has(repairEsi)) return;
@@ -879,27 +926,25 @@ function handleCleanup(
 		throw new Error("[FecWorker] cleanup: invalid SBNs");
 	}
 	const sbns = [...new Set(cmd.sbns)].sort((a, b) => a - b);
-	const pendingSbns = sbns.filter((sbn) => sbn > retiredSbnFrontier);
+	const pendingSbns = sbns.filter((sbn) => !isRetiredSbn(sbn));
 	try {
 		if (!wasmDecoder) {
 			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)) {
@@ -916,12 +961,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
@@ -930,29 +969,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) {
@@ -1009,7 +1025,6 @@ function handleReset(): void {
 	blocksComplete = 0;
 	blocksRecovered = 0;
 	blocksFailed = 0;
-	greenFillFrames = 0;
 	altaVerified = 0;
 	altaFailed = 0;
 	altaFailedDetails.length = 0;
@@ -1020,6 +1035,9 @@ function handleReset(): void {
 	relayBlocksVerified = 0;
 	relayBlocksFailed = 0;
 	repairSymbolSizeMismatch = 0;
+	sourceDroppedRetired = 0;
+	sourceDroppedTerminal = 0;
+	sourceDroppedDuplicate = 0;
 	emit({ type: "resetComplete" });
 	if (config) emitSnapshot();
 }