@blockcast/fec-worker 0.1.0

package/dist/fec-worker-types.d.ts

@@ -0,0 +1,252 @@
+/**
+ * @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.
+ */
+/** 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;
+    /** Source symbols per block (K) */
+    k: number;
+    /** Repair symbols per block (P). NOT symbol size. */
+    repairCount: number;
+    /** Bytes per symbol */
+    symbolSize: number;
+    /** Interleave depth in frames (D) */
+    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;
+}
+/** Per-block snapshot for live block visualization and stats. */
+export interface FecBlockSnapshot {
+    /** Source block number */
+    sbn: number;
+    /** Current block state */
+    state: "collecting" | "complete" | "recovered" | "failed" | "green-fill";
+    /** Number of source symbols received */
+    sourceReceived: number;
+    /** Number of repair symbols received */
+    repairReceived: number;
+    /** Expected source symbols (K) */
+    k: 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;
+}
+/** 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;
+    /** Frames replaced with green-fill */
+    greenFillFrames: 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;
+    /** Current live source block number */
+    liveSbn: number;
+    /** Active block snapshots */
+    blocks: FecBlockSnapshot[];
+    /** Number of blocks in the interleave window */
+    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;
+    /** 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" | "repair-symbol-size-mismatch" | "reset-failed" | "unknown-command" | "command-failed" | "worker-runtime" | "worker-message";
+/** 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;
+    /** Source block number this frame belongs to */
+    sbn: number;
+    /** Encoding Symbol ID within the recovered source block (0..K-1). */
+    esi?: number;
+}
+/** 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). The WASM decoder derives SBN = floor(ssId/K)
+     *  and ESI = ssId % K internally — do NOT pre-compute. */
+    ssId: number;
+    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
+     *  (= SBN * SSB_length), from the MMTP Repair FEC Payload ID
+     *  (ISO 23008-1 §C.5.3). */
+    ssStart: number;
+    /** SSB_length: K for this block (variable-K allowed per spec). */
+    ssbLength: number;
+    /** RS_ID: repair symbol index within the block; WASM maps to
+     *  repair ESI = SSB_length + RS_ID. */
+    rsId: number;
+    data: ArrayBuffer;
+    ts: number;
+} | {
+    type: "relayBlockSig";
+    sbn: number;
+    sig: ArrayBuffer;
+    hash: ArrayBuffer;
+} | {
+    type: "cleanup";
+    /** Every timed-out block covered by this coalesced queue-drain barrier. */
+    sbns: number[];
+} | {
+    type: "reset";
+} | {
+    type: "dispose";
+};
+/** 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: "greenFill";
+    sbn: number;
+    data: ArrayBuffer;
+} | {
+    type: "cleanupComplete";
+    sbns: number[];
+} | {
+    type: "resetComplete";
+} | {
+    type: "error";
+    message: string;
+    code?: FecWorkerErrorCode;
+};
+//# sourceMappingURL=fec-worker-types.d.ts.map

package/dist/fec-worker-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fec-worker-types.d.ts","sourceRoot":"","sources":["../src/fec-worker-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,mFAAmF;AACnF,MAAM,WAAW,cAAc;IAC9B,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,SAAS,EAAE,OAAO,GAAG,OAAO,CAAC;IAC7B,2CAA2C;IAC3C,UAAU,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,CAAC,EAAE,MAAM,CAAC;IACV,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,uBAAuB;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,eAAe,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,CAAC;IACzB,wBAAwB;IACxB,OAAO,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC/B,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,uDAAuD;IACvD,WAAW,EAAE,OAAO,CAAC;IACrB,sEAAsE;IACtE,oBAAoB,EAAE,OAAO,CAAC;CAC9B;AAID,iEAAiE;AACjE,MAAM,WAAW,gBAAgB;IAChC,0BAA0B;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,0BAA0B;IAC1B,KAAK,EAAE,YAAY,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,GAAG,YAAY,CAAC;IACzE,wCAAwC;IACxC,cAAc,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,cAAc,EAAE,MAAM,CAAC;IACvB,kCAAkC;IAClC,CAAC,EAAE,MAAM,CAAC;IACV,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,aAAa,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,wGAAwG;IACxG,kBAAkB,EAAE,OAAO,GAAG,IAAI,CAAC;CACnC;AAID,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC7B,0BAA0B;IAC1B,MAAM,EAAE,cAAc,CAAC;IAEvB,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,cAAc,EAAE,MAAM,CAAC;IACvB,+BAA+B;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,eAAe,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,YAAY,EAAE,MAAM,CAAC;IAErB,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB;mFAC+E;IAC/E,WAAW,EAAE,MAAM,CAAC;IACpB;oFACgF;IAChF,qBAAqB,EAAE,MAAM,CAAC;IAC9B,oEAAoE;IACpE,qBAAqB,EAAE,MAAM,CAAC;IAC9B;;wDAEoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB;;kFAE8E;IAC9E,cAAc,EAAE,OAAO,CAAC;IACxB;;;;mDAI+C;IAC/C,iBAAiB,CAAC,EAAE,KAAK,CAAC;QACzB,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,IAAI,EAAE,MAAM,CAAC;KACb,CAAC,CAAC;IACH,wCAAwC;IACxC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,0CAA0C;IAC1C,iBAAiB,EAAE,MAAM,CAAC;IAE1B,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,gDAAgD;IAChD,sBAAsB,EAAE,MAAM,CAAC;IAE/B,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,6FAA6F;IAC7F,OAAO,CAAC,EAAE;QACT,aAAa,EAAE,MAAM,CAAC;QACtB,aAAa,EAAE,MAAM,CAAC;QACtB,cAAc,EAAE,MAAM,CAAC;QACvB,eAAe,EAAE,MAAM,CAAC;QACxB,YAAY,EAAE,MAAM,CAAC;QACrB,cAAc,EAAE,MAAM,CAAC;QACvB,aAAa,EAAE,MAAM,CAAC;KACtB,CAAC;CACF;AAED,qFAAqF;AACrF,MAAM,MAAM,kBAAkB,GAC3B,oCAAoC,GACpC,2BAA2B,GAC3B,6BAA6B,GAC7B,cAAc,GACd,iBAAiB,GACjB,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,CAAC;AAIpB,gEAAgE;AAChE,MAAM,WAAW,SAAS;IACzB,gGAAgG;IAChG,YAAY,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,uEAAuE;IACvE,SAAS,EAAE,OAAO,CAAC;IACnB,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAID,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GACzB;IACA,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,cAAc,CAAC;IACvB,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC;IAC/B;;;;OAIG;IACH,aAAa,CAAC,EAAE,WAAW,CAAC;IAC5B,4GAA4G;IAC5G,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC;CACnC,GACD;IACA,IAAI,EAAE,YAAY,CAAC;IACnB;;8DAE0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,WAAW,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;IACX;;;;mCAI+B;IAC/B,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB;;;;+CAI2C;IAC3C,cAAc,CAAC,EAAE,MAAM,CAAC;CACvB,GACD;IACA,IAAI,EAAE,YAAY,CAAC;IACnB;;gCAE4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB;2CACuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,WAAW,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;CACV,GACD;IACA,IAAI,EAAE,eAAe,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,WAAW,CAAC;IACjB,IAAI,EAAE,WAAW,CAAC;CACjB,GACD;IACA,IAAI,EAAE,SAAS,CAAC;IAChB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,EAAE,CAAC;CACd,GACD;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAIvB,4EAA4E;AAC5E,MAAM,MAAM,cAAc,GACvB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,kBAAkB,CAAA;CAAE,CAAC"}

package/dist/fec-worker-types.js

@@ -0,0 +1,11 @@
+/**
+ * @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.
+ */
+export {};
+//# sourceMappingURL=fec-worker-types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fec-worker-types.js","sourceRoot":"","sources":["../src/fec-worker-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/fec-worker.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @blockcast/fec-worker — Worker Entry Point
+ *
+ * Runs inside DedicatedWorkerGlobalScope. Receives FecWorkerCommand messages,
+ * drives the MmtFecDecoder WASM module, emits FecWorkerEvent messages back.
+ *
+ * WASM bindings are resolved via:
+ *   1. (self as any).__MMT_WASM_BINDINGS__ — set by consumer's loader/importmap
+ *   2. Falls back to error if not available (no defaults)
+ *
+ * This file must NOT import DOM globals incompatible with Worker scope.
+ */
+export {};
+//# sourceMappingURL=fec-worker.d.ts.map

package/dist/fec-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fec-worker.d.ts","sourceRoot":"","sources":["../src/fec-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}