@blockcast/fec-worker 0.1.0 → 0.3.0

package/src/fec-worker-types.ts

@@ -10,6 +10,22 @@
 
 // --- Config ---
 
+/**
+ * FEC block profile (BLO-35597, ISO/IEC 23008-1 Annex C): the catalog
+ * `fec.blockProfile` token. Both profiles carry identical wire tuples whose
+ * block math differs, so it is required and never inferred.
+ *
+ * - `k-padded-v1` (legacy): SBN = floor(SS_ID / K), ESI = SS_ID % K;
+ *   SS_Start = SBN * K; repair ESI = K + RS_ID.
+ * - `iso-ssbg1-v1` (C.3.3 ssbg_mode1): SS_ID increments by one per source
+ *   packet mod 2^32; a block is `[SS_Start, SS_Start + SSB_length)` keyed by
+ *   SS_Start; `k` is only the maximum SSB_length; repair ESI =
+ *   SSB_length + RS_ID.
+ *
+ * Mirrors @blockcast/mmt-base `FecBlockProfile`.
+ */
+export type FecBlockProfile = "k-padded-v1" | "iso-ssbg1-v1";
+
 /** Per-track FEC configuration. Matches design spec section 3.2 FecTrackConfig. */
 export interface FecTrackConfig {
 	/** Codec string, e.g. 'avc1.64001f', 'mp4a.40.2' */
@@ -27,13 +43,22 @@ export interface FecTrackConfig {
 
 	/** FEC algorithm identifier: 'raptor', 'reed-solomon', 'none' */
 	algorithm: string;
-	/** Source symbols per block (K) */
+	/** Block profile; the Worker refuses to configure without a known token. */
+	blockProfile: FecBlockProfile;
+	/** Source symbols per block (K). Under `iso-ssbg1-v1` the maximum SSB_length (kMax). */
 	k: number;
 	/** Repair symbols per block (P). NOT symbol size. */
 	repairCount: number;
 	/** Bytes per symbol */
 	symbolSize: number;
-	/** Interleave depth in frames (D) */
+	/** Retained decoder horizon as a BLOCK COUNT (SBN distance), not D.
+	 *  `isRetiredSbn` retires blocks more than this many blocks behind
+	 *  `liveSbn` (serial order on SS_ID, BLO-35597 iso:5) and
+	 *  `MmtFecDecoder::new` documents it as "the number of interleaved blocks".
+	 *  Under `iso-ssbg1-v1` the distance is `isoBlocksBehind(SS_ID, live SS_ID, k)`
+	 *  (block-order.ts), the lower bound every ISO receiver layer shares.
+	 *  Never assign `deriveFecInterleaveDepth()` here — that returns media units
+	 *  per block, which is a different quantity (BLO-35597). */
 	interleaveDepth: number;
 	/** Interleave depth in milliseconds (D * frameDurationMs) */
 	interleaveMs: number;
@@ -54,16 +79,22 @@ export interface FecTrackConfig {
 
 /** Per-block snapshot for live block visualization and stats. */
 export interface FecBlockSnapshot {
-	/** Source block number */
+	/** Block key: the source block number under `k-padded-v1`, the block's
+	 *  SS_Start under `iso-ssbg1-v1`. */
 	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); under `iso-ssbg1-v1` the block's SSB_length. */
 	k: number;
+	/** Authored source symbols (SSB_length) once a repair symbol declared it.
+	 *  Under `iso-ssbg1-v1` a block is only known from a repair symbol, so it is
+	 *  always set — except on a cleanup tombstone for a block the Worker never
+	 *  saw, whose length nothing declared. */
+	ssbLength?: number;
 	/** Expected repair symbols (P) */
 	repairCount: number;
 	/** Timestamp of first symbol arrival (ms) */
@@ -97,8 +128,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;
 
@@ -139,11 +168,12 @@ export interface FecTrackStats {
 	/** Blocks with invalid relay signature */
 	relayBlocksFailed: number;
 
-	/** Current live source block number */
+	/** Live media position: the newest source block number under
+	 *  `k-padded-v1`, the newest accepted SS_ID / SS_Start under `iso-ssbg1-v1`. */
 	liveSbn: number;
 	/** Active block snapshots */
 	blocks: FecBlockSnapshot[];
-	/** Number of blocks in the interleave window */
+	/** Number of blocks in the FEC block span */
 	interleaveWindowBlocks: number;
 
 	/** Average recovery latency (ms) */
@@ -152,6 +182,51 @@ export interface FecTrackStats {
 	maxRecoveryMs: number;
 	/** Repair symbols rejected before WASM because their byte length did not match T. */
 	repairSymbolSizeMismatch?: number;
+	/**
+	 * Source symbols whose SBN had already fallen below the retained window.
+	 *
+	 * This and its two peers below are dropped before WASM and narrow the
+	 * explanations for a block that settles at K-1 source symbols (BLO-35597
+	 * defect 2): a late symbol past retention, a symbol for a block that had
+	 * already settled (complete, recovered *or failed*), or a repeated
+	 * (SBN, ESI).
+	 *
+	 * They narrow; they do not uniquely attribute. A symbol lost in transit
+	 * never reaches the worker and increments nothing, so all three reading
+	 * zero on a short block means only that no *receiver-side* drop was
+	 * recorded — wire loss and a short authored block both remain open. Use
+	 * `FecBlockSnapshot.ssbLength` to separate them: below `k` is a genuinely
+	 * short authored block, equal to `k` with fewer accepted is loss-or-late.
+	 * `ssbLength` is undefined until a repair symbol declares it, in which case
+	 * both stay open.
+	 *
+	 * All three are cumulative across decoder epochs: `configure` clears block
+	 * tracking but none of them, so they stay comparable against the
+	 * `sourceSymbols` denominator. Only a reset zeroes them.
+	 */
+	sourceDroppedRetired?: number;
+	/** Source symbols for a block that had already completed, recovered or failed. */
+	sourceDroppedTerminal?: number;
+	/**
+	 * Source symbols repeating an (SBN, ESI) already accepted in the current
+	 * epoch; `configure` clears the accepted-ESI sets.
+	 *
+	 * Unlike the other two, this one cannot fire once a block settles — the
+	 * terminal check returns first, and marking a block terminal retires its
+	 * accepted-ESI set anyway — so a non-zero value means the repeat reached
+	 * the worker while the block was **still collecting**. It attributes the
+	 * timing, not the origin: usually a duplicate packet on the wire,
+	 * sometimes an SBN/ESI derivation collision.
+	 */
+	sourceDroppedDuplicate?: number;
+	/**
+	 * `iso-ssbg1-v1` only: accepted source symbols whose block never became
+	 * known (no repair symbol named a range containing them) before their
+	 * SS_ID fell behind the retained horizon. They were already fed to the
+	 * decoder and routed directly; this counts the bookkeeping retired with
+	 * them, i.e. evidence that a block's repair symbols never arrived.
+	 */
+	sourceUnplacedRetired?: number;
 	/** Native decoder counters, converted to numbers so browser diagnostics remain JSON-safe. */
 	decoder?: {
 		sourcePackets: number;
@@ -168,7 +243,15 @@ 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"
+	/** `iso-ssbg1-v1`: a repair's `[SS_Start, SS_Start + SSB_length)` overlaps a different known block. */
+	| "repair-block-overlap"
+	/** `iso-ssbg1-v1`: a recovered symbol's ssbg_mode1 length field exceeds T-2 or its padding is non-zero. */
+	| "recovered-ssbg1-symbol-invalid"
+	/** `iso-ssbg1-v1`: the decoder returned a recovered block for a source the Worker could not place in a known block. */
+	| "recovered-block-unplaced"
 	| "reset-failed"
 	| "unknown-command"
 	| "command-failed"
@@ -183,10 +266,19 @@ export interface FrameMeta {
 	altaVerified: boolean | null;
 	/** Whether this frame was recovered via FEC (not received directly) */
 	recovered: boolean;
-	/** Source block number this frame belongs to */
+	/** Block key this frame belongs to: SBN (`k-padded-v1`) or SS_Start (`iso-ssbg1-v1`) */
 	sbn: number;
-	/** Encoding Symbol ID within the recovered source block (0..K-1). */
+	/** Encoding Symbol ID within the recovered source block (0..ssbLength-1).
+	 *  Under `iso-ssbg1-v1` a recovered frame is the full T-byte ssbg_mode1
+	 *  symbol (length field, packet, zero padding); the Worker validates but
+	 *  never trims it. */
 	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) ---
@@ -209,9 +301,13 @@ export type FecWorkerCommand =
 	| {
 			type: "feedSource";
 			/** Flat 32-bit Source Symbol ID from the MMTP Source FEC Payload ID
-			 *  (ISO 23008-1 §C.5.2). The WASM decoder derives SBN = floor(ssId/K)
-			 *  and ESI = ssId % K internally — do NOT pre-compute. */
+			 *  (ISO 23008-1 §C.5.2). Under `k-padded-v1` the WASM decoder derives
+			 *  SBN = floor(ssId/K) and ESI = ssId % K internally — do NOT
+			 *  pre-compute. Under `iso-ssbg1-v1` SS_IDs are consecutive per source
+			 *  packet mod 2^32 and the block comes from a repair's range. */
 			ssId: number;
+			/** `k-padded-v1`: the source symbol. `iso-ssbg1-v1`: the protected
+			 *  packet exactly, unpadded and without its SS_ID (at most T-2 bytes). */
 			data: ArrayBuffer;
 			ts: number;
 			/** Optional ALTA authenticator bytes (detached mode — 08-07 MMTP
@@ -229,18 +325,30 @@ export type FecWorkerCommand =
 	  }
 	| {
 			type: "feedRepair";
-			/** SS_Start: SS_ID of the first source symbol in the block
-			 *  (= SBN * SSB_length), from the MMTP Repair FEC Payload ID
-			 *  (ISO 23008-1 §C.5.3). */
+			/** SS_Start: SS_ID of the first source symbol in the block, from the
+			 *  MMTP Repair FEC Payload ID (ISO 23008-1 §C.5.3). `k-padded-v1`:
+			 *  = SBN * configured K. `iso-ssbg1-v1`: any uint32; the block key. */
 			ssStart: number;
-			/** SSB_length: K for this block (variable-K allowed per spec). */
+			/** Authored source-symbol count for this block; 1..configured K. */
 			ssbLength: number;
-			/** RS_ID: repair symbol index within the block; WASM maps to
-			 *  repair ESI = SSB_length + RS_ID. */
+			/** RS_ID: repair symbol index within the block; WASM maps to repair
+			 *  ESI = configured K + RS_ID (`k-padded-v1`) or SSB_length + RS_ID
+			 *  (`iso-ssbg1-v1`). */
 			rsId: number;
 			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;
@@ -249,12 +357,26 @@ export type FecWorkerCommand =
 	  }
 	| {
 			type: "cleanup";
-			/** Every timed-out block covered by this coalesced queue-drain barrier. */
+			/** Every timed-out block covered by this coalesced queue-drain barrier,
+			 *  by block key: SBN (`k-padded-v1`) or SS_Start (`iso-ssbg1-v1`). */
 			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 +384,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";