@blockcast/mmt-wasm 0.3.0 → 0.4.0-main.2654dbc2ed6d

package/package.json

@@ -1,40 +1,40 @@
 {
-	"name": "@blockcast/mmt-wasm",
-	"version": "0.3.0",
-	"description": "wasm-bindgen builds of the libmmt Rust core (RaptorQ FEC, MMTP MFU reassembly): `pkg` for ESM bundlers and `pkg-no-modules` as a global script for Closure-compiled pages",
-	"main": "pkg/mmt_wasm.js",
-	"types": "pkg/mmt_wasm.d.ts",
-	"exports": {
-		".": {
-			"types": "./pkg/mmt_wasm.d.ts",
-			"import": "./pkg/mmt_wasm.js"
-		},
-		"./mmt_wasm_bg.wasm": "./pkg/mmt_wasm_bg.wasm",
-		"./no-modules": {
-			"types": "./pkg-no-modules/mmt_wasm.d.ts",
-			"default": "./pkg-no-modules/mmt_wasm.js"
-		},
-		"./no-modules/mmt_wasm_bg.wasm": "./pkg-no-modules/mmt_wasm_bg.wasm",
-		"./package.json": "./package.json"
-	},
-	"files": [
-		"pkg",
-		"pkg-no-modules"
-	],
-	"scripts": {
-		"build": "make -C ../.. mmt-wasm",
-		"test": "node build-contract.test.mjs"
-	},
-	"keywords": [
-		"mmt",
-		"mmtp",
-		"raptorq",
-		"wasm"
-	],
-	"license": "Apache-2.0",
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/Blockcast/libmmt.git",
-		"directory": "packages/mmt-wasm"
-	}
+  "name": "@blockcast/mmt-wasm",
+  "version": "0.4.0-main.2654dbc2ed6d",
+  "description": "wasm-bindgen builds of the libmmt Rust core (RaptorQ FEC, MMTP MFU reassembly): `pkg` for ESM bundlers and `pkg-no-modules` as a global script for Closure-compiled pages",
+  "main": "pkg/mmt_wasm.js",
+  "types": "pkg/mmt_wasm.d.ts",
+  "exports": {
+    ".": {
+      "types": "./pkg/mmt_wasm.d.ts",
+      "import": "./pkg/mmt_wasm.js"
+    },
+    "./mmt_wasm_bg.wasm": "./pkg/mmt_wasm_bg.wasm",
+    "./no-modules": {
+      "types": "./pkg-no-modules/mmt_wasm.d.ts",
+      "default": "./pkg-no-modules/mmt_wasm.js"
+    },
+    "./no-modules/mmt_wasm_bg.wasm": "./pkg-no-modules/mmt_wasm_bg.wasm",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "pkg",
+    "pkg-no-modules"
+  ],
+  "scripts": {
+    "build": "make -C ../.. mmt-wasm",
+    "test": "node build-contract.test.mjs"
+  },
+  "keywords": [
+    "mmt",
+    "mmtp",
+    "raptorq",
+    "wasm"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Blockcast/libmmt.git",
+    "directory": "packages/mmt-wasm"
+  }
 }

package/pkg/mmt_wasm.d.ts

@@ -45,6 +45,12 @@ export class FecStats {
    * Blocks that expired with fewer than K symbols (delivery issue, not FEC issue)
    */
   blocks_delivery_failed: bigint;
+  /**
+   * `iso-ssbg1-v1` held sources evicted, oldest arrival first, because the
+   * unplaced pool was at its `(interleave_depth + 1) * K` cap: no sweep
+   * (`cleanup_by_ss_start` / `retire_unplaced`) retired them first.
+   */
+  unplaced_evicted: bigint;
 }
 
 export class MfuFragmentJs {
@@ -100,27 +106,15 @@ export class MmtFecDecoder {
   /**
    * Add a repair symbol per ISO 23008-1 §C.5.3.
    *
-   * Repair carries (SS_Start, SSB_length, RS_ID).
-   * SS_Start = SS_ID of first source in block = SBN * K.
-   * SSB_length = the authored source-symbol count in this block (1..=K).
-   * SBN = SS_Start / configured K.
-   * Repair ESI = K + RS_ID.
-   *
-   * The decoder's configured K is the fixed RaptorQ geometry. A short
-   * authored block (`SSB_length < K`) is the producer's K-symbol RaptorQ
-   * block with ESIs `SSB_length..K` zero-filled and never transmitted
-   * (fec-raptorq `InterleavedEncoder::force_complete`). The block records
-   * `SSB_length`, completes once that many source symbols arrived, and
-   * recovers from `SSB_length` received symbols by supplying the known
-   * padding itself. A conflicting `SSB_length` for one block is rejected
-   * without changing that block.
-   *
-   * Under `iso-ssbg1-v1` the block is `[SS_Start, SS_Start + SSB_length)`
-   * with `1 <= SSB_length <= K` (K is only the maximum), its RaptorQ geometry
-   * is K' = SSB_length with no padding, and repair ESI = SSB_length + RS_ID
-   * (C.5.3). The first repair defines the block and claims every held source
-   * in range. A conflicting SSB_length, or a range overlapping a different
-   * known block, is refused without changing any block. Output is the K'*T
+   * Repair carries (SS_Start, SSB_length, RS_ID). The block is
+   * `[SS_Start, SS_Start + SSB_length)` with `1 <= SSB_length <= K` (the
+   * configured K is only the maximum), its RaptorQ geometry is
+   * K' = SSB_length with no padding, and repair ESI = SSB_length + RS_ID.
+   * The first repair defines the block and claims every held source in
+   * range. A conflicting SSB_length, a range overlapping a different known
+   * block, or a start more than `interleave_depth` blocks behind the last
+   * `cleanup_by_ss_start`'s `current` (`iso_blocks_behind_lower_bound`), is
+   * refused without changing any block. Output is the K'*T
    * concatenated ssbg_mode1 symbols: split by T and trim by the length field.
    */
   add_repair(ss_start: number, ssb_length: number, rs_id: number, data: Uint8Array, timestamp: number): Uint8Array | undefined;
@@ -130,13 +124,12 @@ export class MmtFecDecoder {
    * SS_ID is a flat 32-bit counter. An unconfigured decoder rejects the
    * packet.
    *
-   * - `k-padded-v1`: derives SBN = floor(SS_ID / K), ESI = SS_ID % K and
-   *   zero-pads `data` to T.
-   * - `iso-ssbg1-v1`: builds the C.3.3 ssbg_mode1 symbol
-   *   `u16be(len) || data || zero padding` (refusing `len + 2 > T`) and
-   *   places it at ESI = serial distance from the start of the known block
-   *   whose `[SS_Start, SS_Start + SSB_length)` contains SS_ID. A source
-   *   whose block no repair has defined yet is held by SS_ID until one does.
+   * Builds the C.3.3 ssbg_mode1 symbol `u16be(len) || data || zero padding`
+   * (refusing `len + 2 > T`) and places it at ESI = serial distance from the
+   * start of the known block whose `[SS_Start, SS_Start + SSB_length)`
+   * contains SS_ID. A source whose block no repair has defined yet is held
+   * by SS_ID until one does; at most `(interleave_depth + 1) * K` are held, and
+   * the oldest arrival is evicted first (`FecStats::unplaced_evicted`).
    *
    * # Arguments
    * * `ss_id` - Source symbol ID (32-bit monotonic counter)
@@ -152,18 +145,6 @@ export class MmtFecDecoder {
    * Get alignment (Al) parameter from OTI
    */
   get_alignment(): number;
-  /**
-   * `k-padded-v1` only: cleanup blocks more than `interleave_depth` blocks
-   * behind `current_sbn`. Refused under `iso-ssbg1-v1`, which has no SBN
-   * (use `cleanup_by_ss_start`).
-   *
-   * Blocks are ordered by RFC 1982 serial comparison of their first SS_ID
-   * (`sbn * K mod 2^32`, ISO/IEC 23008-1 C.5.2; BLO-35597 iso:5). For a
-   * stream that has not wrapped SS_ID that is exactly the old
-   * `sbn < current_sbn - interleave_depth`; after the wrap it still retires
-   * the pre-wrap blocks instead of keeping them forever.
-   */
-  cleanup_by_sbn(current_sbn: number): Uint32Array;
   /**
    * Get sub-blocks (N) parameter from OTI
    */
@@ -177,11 +158,11 @@ export class MmtFecDecoder {
    */
   get_symbol_size(): number;
   /**
-   * `iso-ssbg1-v1` only: retire the held source symbols that no repair can
-   * place any more, by the same rule as `cleanup_by_ss_start`, without
-   * retiring any block. For a caller that retires blocks itself, by their
-   * deadlines (`cleanup_blocks_detailed`), and needs only this half. Returns
-   * how many it retired.
+   * Retire the held source symbols that no repair can place any more, by
+   * the same rule as `cleanup_by_ss_start`, without retiring any block. For
+   * a caller that retires blocks itself, by their deadlines
+   * (`cleanup_blocks_detailed`), and needs only this half. Returns how many
+   * it retired.
    */
   retire_unplaced(current: number): number;
   /**
@@ -201,11 +182,11 @@ export class MmtFecDecoder {
    */
   get_source_blocks(): number;
   /**
-   * `iso-ssbg1-v1` only: retire every block, and every held source symbol,
-   * lying more than `interleave_depth` blocks behind SS_ID `current`, the
-   * newest SS_ID the caller has seen (no block start or held source follows
-   * it). A block start or held source that `current` has moved at least
-   * half the SS_ID space past no longer precedes it and is retired too
+   * Retire every block, and every held source symbol, lying more than
+   * `interleave_depth` blocks behind SS_ID `current`, the newest SS_ID the
+   * caller has seen (no block start or held source follows it). A block
+   * start or held source that `current` has moved at least half the SS_ID
+   * space past no longer precedes it and is retired too
    * (`iso_past_horizon`).
    *
    * Blocks have no SBN under ssbg_mode1, so distance is measured on the
@@ -221,21 +202,21 @@ export class MmtFecDecoder {
    */
   get_interleave_depth(): number;
   /**
-   * Finalize only the source blocks whose host-owned deadlines fired.
-   * Keys are SBNs under `k-padded-v1` and SS_Starts under `iso-ssbg1-v1`.
+   * Finalize only the source blocks whose host-owned deadlines fired,
+   * named by their SS_Starts.
    *
    * The JavaScript FEC manager owns per-block repair grace. A timeout for one
    * block must therefore not run the decoder's global age scan and evict a
    * peer block that is still waiting for fetched repair.
    */
-  cleanup_blocks_detailed(sbns: Uint32Array): void;
+  cleanup_blocks_detailed(ss_starts: Uint32Array): void;
   /**
    * Create a new FEC decoder
    *
    * # Arguments
    * * `interleave_depth` - Explicit positive number of interleaved blocks.
-   * * `block_profile` - Catalog `fec.blockProfile`: `"k-padded-v1"` or
-   *   `"iso-ssbg1-v1"`. Required; any other value is refused.
+   * * `block_profile` - Catalog `fec.blockProfile`: `"iso-ssbg1-v1"`.
+   *   Required; any other value is refused.
    */
   constructor(interleave_depth: number, block_profile: string);
   /**
@@ -250,7 +231,8 @@ export class MmtFecDecoder {
    * Configure FEC from 12-byte OTI
    *
    * # Arguments
-   * * `oti` - 12-byte Object Transmission Information from S-TSID fecOTI
+   * * `oti` - 12-byte RFC 6330 Common FEC OTI: decoder geometry per
+   *   draft-fec-01 Section 4.2 (Z = 1, N = 1, Al = 8)
    */
   configure(oti: Uint8Array): void;
   /**
@@ -270,33 +252,28 @@ export class MmtFecEncoder {
    * `[SS_Start:4][RSB_length:3][RS_ID:3][SSB_length:3][symbol: T]`.
    * Callers split on that stride; `entry i` is at `i * (13 + T)`.
    *
-   * `k-padded-v1`: `block` is the Source Block Number and `source_block`
-   * MUST be exactly `K * symbol_size` bytes — the caller pads the final
-   * (short) block with zeros, mirroring `InterleavedEncoder` and the FFmpeg
-   * path. `SS_Start = block * K` (wrapping), `SSB_length = K`.
-   *
-   * `iso-ssbg1-v1`: `block` is the SS_Start (the block's first SS_ID) and
-   * `source_block` is the block's K' ssbg_mode1 symbols (`1 <= K' <= K`,
-   * `len % T == 0`, each a well-formed C.3.3 symbol). RaptorQ runs over K'
-   * symbols (F = K'*T) and `SSB_length = K'`.
+   * `ss_start` is the block's first SS_ID and `source_block` is the
+   * block's K' ssbg_mode1 symbols (`1 <= K' <= K`, `len % T == 0`, each a
+   * well-formed C.3.3 symbol). RaptorQ runs over K' symbols (F = K'*T) and
+   * `SSB_length = K'`.
    *
    * # Arguments
-   * * `block`        - SBN (`k-padded-v1`) or SS_Start (`iso-ssbg1-v1`).
+   * * `ss_start`     - SS_Start: the block's first SS_ID.
    * * `source_block` - The block's source symbols, as described above.
    * * `repair_count` - Number of repair symbols (P) to generate.
    */
-  encode_repair(block: number, source_block: Uint8Array, repair_count: number): Uint8Array;
+  encode_repair(ss_start: number, source_block: Uint8Array, repair_count: number): Uint8Array;
   /**
    * Create an encoder for a fixed `(K, symbol_size)` block geometry.
    *
    * Builds the OTI as `ObjectTransmissionInformation::new(K*T, T, 1, 1, 8)`
-   * (single source block, single sub-block, byte alignment) — matching the
-   * decoder's recovery model in [`FecBlock::try_decode`] — and pre-computes
-   * the shared `SourceBlockEncodingPlan` so per-block encoding is cheap.
+   * (single source block, single sub-block, byte alignment) — the geometry
+   * [`MmtFecDecoder::configure`] reads back. K is the maximum SSB_length;
+   * each block is encoded over its own K' symbols (see
+   * [`MmtFecEncoder::encode_repair`]).
    *
-   * `block_profile` is the catalog `fec.blockProfile` (`"k-padded-v1"` or
-   * `"iso-ssbg1-v1"`); any other value is refused. Under `iso-ssbg1-v1`, K
-   * is the maximum SSB_length.
+   * `block_profile` is the catalog `fec.blockProfile` (`"iso-ssbg1-v1"`);
+   * any other value is refused.
    */
   constructor(k: number, symbol_size: number, block_profile: string);
   /**
@@ -808,7 +785,7 @@ export interface InitOutput {
   readonly __wbg_get_fecstats_bytes_recovered: (a: number) => bigint;
   readonly __wbg_get_fecstats_repair_packets: (a: number) => bigint;
   readonly __wbg_get_fecstats_source_packets: (a: number) => bigint;
-  readonly __wbg_get_reassemblerstatsjs_ambiguous_fallback_fragments: (a: number) => bigint;
+  readonly __wbg_get_fecstats_unplaced_evicted: (a: number) => bigint;
   readonly __wbg_mfufragmentjs_free: (a: number, b: number) => void;
   readonly __wbg_mmtfecdecoder_free: (a: number, b: number) => void;
   readonly __wbg_mmtfecencoder_free: (a: number, b: number) => void;
@@ -821,7 +798,6 @@ export interface InitOutput {
   readonly __wbg_moqfecencoder_free: (a: number, b: number) => void;
   readonly __wbg_moqfecstatsjs_free: (a: number, b: number) => void;
   readonly __wbg_reassembledmfujs_free: (a: number, b: number) => void;
-  readonly __wbg_reassemblerstatsjs_free: (a: number, b: number) => void;
   readonly __wbg_recoveredset_free: (a: number, b: number) => void;
   readonly __wbg_samplecombinerstatsjs_free: (a: number, b: number) => void;
   readonly __wbg_set_fecstats_blocks_complete: (a: number, b: bigint) => void;
@@ -831,7 +807,7 @@ export interface InitOutput {
   readonly __wbg_set_fecstats_bytes_recovered: (a: number, b: bigint) => void;
   readonly __wbg_set_fecstats_repair_packets: (a: number, b: bigint) => void;
   readonly __wbg_set_fecstats_source_packets: (a: number, b: bigint) => void;
-  readonly __wbg_set_reassemblerstatsjs_ambiguous_fallback_fragments: (a: number, b: bigint) => void;
+  readonly __wbg_set_fecstats_unplaced_evicted: (a: number, b: bigint) => void;
   readonly __wbg_shredfecbuffer_free: (a: number, b: number) => void;
   readonly __wbg_shredreassembler_free: (a: number, b: number) => void;
   readonly annexb_access_unit_is_keyframe: (a: number, b: number, c: number, d: number) => [number, number, number];
@@ -862,7 +838,6 @@ export interface InitOutput {
   readonly mmtfecdecoder_add_repair: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number, number];
   readonly mmtfecdecoder_add_source: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
   readonly mmtfecdecoder_cleanup_blocks_detailed: (a: number, b: number, c: number) => void;
-  readonly mmtfecdecoder_cleanup_by_sbn: (a: number, b: number) => [number, number, number, number];
   readonly mmtfecdecoder_cleanup_by_ss_start: (a: number, b: number) => [number, number, number, number];
   readonly mmtfecdecoder_configure: (a: number, b: number, c: number) => [number, number];
   readonly mmtfecdecoder_configure_params: (a: number, b: number, c: number) => [number, number];
@@ -957,7 +932,6 @@ export interface InitOutput {
   readonly reassembledmfujs_sample_number: (a: number) => number;
   readonly reassembledmfujs_stream_identity: (a: number) => number;
   readonly reassembledmfujs_timestamp: (a: number) => number;
-  readonly recoveredset_fec_set_index: (a: number) => number;
   readonly recoveredset_payload: (a: number) => [number, number];
   readonly recoveredset_slot: (a: number) => bigint;
   readonly shredfecbuffer_add_shred: (a: number, b: bigint, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => [number, number];
@@ -974,7 +948,9 @@ export interface InitOutput {
   readonly moqfecstatsjs_blocksComplete: (a: number) => number;
   readonly moqfecstatsjs_blocksIncomplete: (a: number) => number;
   readonly moqfecstatsjs_totalSymbolsReceived: (a: number) => number;
+  readonly recoveredset_fec_set_index: (a: number) => number;
   readonly shredreassembler_pending_fec_sets: (a: number) => number;
+  readonly __wbg_get_reassemblerstatsjs_ambiguous_fallback_fragments: (a: number) => bigint;
   readonly __wbg_get_reassemblerstatsjs_duplicate_fragments: (a: number) => bigint;
   readonly __wbg_get_reassemblerstatsjs_evicted_data_units: (a: number) => bigint;
   readonly __wbg_get_reassemblerstatsjs_evicted_memory_limit: (a: number) => bigint;
@@ -986,6 +962,8 @@ export interface InitOutput {
   readonly __wbg_get_samplecombinerstatsjs_evicted_samples: (a: number) => bigint;
   readonly __wbg_get_samplecombinerstatsjs_passthrough_samples: (a: number) => bigint;
   readonly __wbg_get_samplecombinerstatsjs_timed_out_samples: (a: number) => bigint;
+  readonly __wbg_reassemblerstatsjs_free: (a: number, b: number) => void;
+  readonly __wbg_set_reassemblerstatsjs_ambiguous_fallback_fragments: (a: number, b: bigint) => void;
   readonly __wbg_set_reassemblerstatsjs_duplicate_fragments: (a: number, b: bigint) => void;
   readonly __wbg_set_reassemblerstatsjs_evicted_data_units: (a: number, b: bigint) => void;
   readonly __wbg_set_reassemblerstatsjs_evicted_memory_limit: (a: number, b: bigint) => void;