@blockcast/mmt-container 0.1.0 → 0.3.0

package/node_modules/@blockcast/fec-worker/src/fec-worker-types.ts

@@ -0,0 +1,399 @@
+/**
+ * @blockcast/fec-worker — Shared Type Definitions
+ *
+ * Defines the Worker message protocol (commands/events), FecTrackStats shape
+ * consumed by fec-panel (Phase 5) and CmcdProducer (Phase 6), and auth
+ * interface stubs (ALTA + relay block sig).
+ *
+ * Types here are importable from both main thread and Worker contexts.
+ */
+
+// --- 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' */
+	codec: string;
+	/** Track name from catalog */
+	trackName: string;
+	/** Track media type */
+	trackType: "video" | "audio";
+	/** Video resolution (omitted for audio) */
+	resolution?: { w: number; h: number };
+	/** Video framerate (omitted for audio) */
+	framerate?: number;
+	/** Audio sample rate (omitted for video) */
+	sampleRate?: number;
+
+	/** FEC algorithm identifier: 'raptor', 'reed-solomon', 'none' */
+	algorithm: string;
+	/** 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;
+	/** 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;
+	/** Catalog-derived source+repair delivery window used for decoder cleanup. */
+	deliveryWindowMs: number;
+	/** FEC encoding mode */
+	fecMode: "subframe" | "object";
+	/** MoQ repair track name (optional) */
+	repairTrack?: string;
+
+	/** Whether ALTA publisher auth is enabled (AUTH-01) */
+	altaEnabled: boolean;
+	/** Whether relay block signature verification is enabled (AUTH-01) */
+	relayBlockSigEnabled: boolean;
+}
+
+// --- Block state ---
+
+/** Per-block snapshot for live block visualization and stats. */
+export interface FecBlockSnapshot {
+	/** 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";
+	/** Number of source symbols received */
+	sourceReceived: number;
+	/** Number of repair symbols received */
+	repairReceived: number;
+	/** 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) */
+	firstSymbolTs: number;
+	/** Timestamp of last symbol arrival (ms) */
+	lastSymbolTs: number;
+	/** Timestamp when block completed (ms), undefined if not yet complete */
+	completedTs?: number;
+	/** Deadline timestamp for block completion (ms) */
+	deadlineTs: number;
+	/** Count of source symbols with valid ALTA signature (AUTH-02) */
+	altaVerified: number;
+	/** Relay block signature validity: true/false after verification, null if not yet verified (AUTH-02) */
+	relayBlockSigValid: boolean | null;
+}
+
+// --- Stats ---
+
+/** Aggregate per-track FEC statistics. Consumed by fec-panel and CmcdProducer. */
+export interface FecTrackStats {
+	/** Track configuration */
+	config: FecTrackConfig;
+
+	/** Total source symbols received */
+	sourceSymbols: number;
+	/** Total repair symbols received */
+	repairSymbols: number;
+	/** Blocks completed without recovery needed */
+	blocksComplete: number;
+	/** Blocks recovered via FEC */
+	blocksRecovered: number;
+	/** Blocks that failed (unrecoverable) */
+	blocksFailed: number;
+	/** Recovery success rate 0-100 */
+	recoveryRate: number;
+
+	/** Packets with valid publisher ALTA signature */
+	altaVerified: number;
+	/** Packets with MAC / signature / hash-chain mismatch (tamper-confirmed) */
+	altaFailed: number;
+	/** Packets that couldn't be verified due to missing trailer / not-ready verifier /
+	 *  late-joiner bootstrap gap. Neither tamper nor error — just unverifiable. */
+	altaPending: number;
+	/** Deferred-queue entries evicted by cap (queue full). Separate counter so
+	 *  cap misconfiguration is distinguishable from natural bootstrap-gap noise. */
+	altaPendingEvictedCap: number;
+	/** Deferred-queue entries evicted by TTL (retry window expired). */
+	altaPendingEvictedTtl: number;
+	/** verifyDetached / parse threw an exception (WASM trap, OOM, unmarshal panic).
+	 *  Not counted as altaFailed because the cause isn't crypto — helps ops
+	 *  distinguish infrastructure flake from tamper. */
+	altaError: number;
+	/** True if ALTA was enabled at configure time but the verifier WASM init
+	 *  failed. Ops alerting should treat this as "ALTA disabled due to error",
+	 *  distinct from "ALTA disabled by config" (altaEnabled flag not present). */
+	altaInitFailed: boolean;
+	/** Diagnostic: last ≤16 altaFailed events with full context (seq, error
+	 *  string from the verifier, auth+payload lengths, and which code path
+	 *  raised the failure). Bounded so it can't blow memory. Intended for
+	 *  investigation — not a stable API; consumers should treat it as
+	 *  opt-in and defensive (may be undefined). */
+	altaFailedDetails?: Array<{
+		seq: number;
+		error: string;
+		authLen: number;
+		payloadLen: number;
+		path: string;
+	}>;
+	/** Blocks with valid relay signature */
+	relayBlocksVerified: number;
+	/** Blocks with invalid relay signature */
+	relayBlocksFailed: 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 FEC block span */
+	interleaveWindowBlocks: number;
+
+	/** Average recovery latency (ms) */
+	avgRecoveryMs: number;
+	/** Maximum recovery latency (ms) */
+	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;
+		repairPackets: number;
+		blocksComplete: number;
+		blocksRecovered: number;
+		blocksFailed: number;
+		bytesRecovered: number;
+		pendingBlocks: number;
+	};
+}
+
+/** Stable identities for Worker failures whose message text contains live values. */
+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"
+	| "worker-runtime"
+	| "worker-message";
+
+// --- Frame metadata ---
+
+/** Per-frame metadata emitted with frame events from Worker. */
+export interface FrameMeta {
+	/** ALTA verification result: true/false after check, null when ALTA not configured (AUTH-04) */
+	altaVerified: boolean | null;
+	/** Whether this frame was recovered via FEC (not received directly) */
+	recovered: boolean;
+	/** 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..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) ---
+
+/** Discriminated union of all commands sent from main thread to Worker. */
+export type FecWorkerCommand =
+	| {
+			type: "configure";
+			config: FecTrackConfig;
+			wasmModule: WebAssembly.Module;
+			/**
+			 * ALTA public key as PKCS#8 SubjectPublicKeyInfo DER bytes (self-describing).
+			 * Algorithm (Ed25519 or ECDSA P-256) is auto-detected from the SPKI OID.
+			 * Ed25519 SPKI is 44 bytes; P-256 uncompressed is 91 bytes.
+			 */
+			altaPublicKey?: ArrayBuffer;
+			/** Pre-compiled ALTA WASM module. Structured-cloneable (NOT transferable) — do not add to transfer list. */
+			altaWasmModule?: WebAssembly.Module;
+	  }
+	| {
+			type: "feedSource";
+			/** Flat 32-bit Source Symbol ID from the MMTP Source FEC Payload ID
+			 *  (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
+			 *  trailer). Present when the source packet carried a
+			 *  `[0xF0A1][len][auth]` trailer and ALTA is enabled at the worker.
+			 *  When omitted, the worker skips verification and the packet
+			 *  counts as `altaPending`. */
+			altaAuth?: ArrayBuffer;
+			/** Byte offset within `data` where the signed MMTP payload ends
+			 *  (== where the trailer began on the wire). Required when
+			 *  `altaAuth` is present. Worker constructs
+			 *  `payload = new Uint8Array(data, 0, altaPayloadEnd)` for
+			 *  `verifyDetached(altaAuth, payload)`. */
+			altaPayloadEnd?: number;
+	  }
+	| {
+			type: "feedRepair";
+			/** 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;
+			/** 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 = 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;
+			sig: ArrayBuffer;
+			hash: ArrayBuffer;
+	  }
+	| {
+			type: "cleanup";
+			/** 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. */
+export type FecWorkerEvent =
+	| { type: "frame"; data: ArrayBuffer; meta: FrameMeta }
+	| { type: "snapshot"; stats: FecTrackStats }
+	| { type: "blockUpdate"; block: FecBlockSnapshot }
+	| { 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";