@blockcast/mmt-fec 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockcast/mmt-fec",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Container-agnostic FEC client for RaptorQ (RFC 6330) decoding via WASM",
   "type": "module",
   "main": "dist/index.js",
@@ -33,11 +33,13 @@
     "./loc": {
       "import": "./dist/loc-symbols.js",
       "types": "./dist/loc-symbols.d.ts"
-    }
+    },
+    "./test-vectors/repair-epoch.json": "./test-vectors/repair-epoch.json"
   },
   "files": [
     "dist",
     "src",
+    "test-vectors",
     "!src/**/*.test.ts",
     "!src/**/*.spec.ts",
     "!src/**/__tests__",
@@ -53,11 +55,8 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@blockcast/mmt-base": "^0.3.0"
+    "@blockcast/mmt-base": "^0.4.0"
   },
-  "bundledDependencies": [
-    "@blockcast/mmt-base"
-  ],
   "devDependencies": {
     "typescript": "^5.3.0",
     "vitest": "^1.0.0"

package/src/block-processor.ts

@@ -1,7 +1,7 @@
 /**
  * FEC Block Processor
  *
- * Splits decoded FEC blocks (K symbols concatenated by WASM RaptorQ decoder)
+ * Splits decoded FEC blocks (SSB_length symbols concatenated by the WASM decoder)
  * into individual MFU fragments ready for reassembly and decoding.
  *
  * Extracted from moqtail.html's inline processFecBlock() for reuse across
@@ -9,14 +9,10 @@
  */
 
 import {
-	MMTP_EXT_TRAILER_HEADER_SIZE,
-	MMTP_EXT_TYPE_ALTA_AUTH,
 	MMTP_HEADER_SIZE,
-	MPU_HEADER_SIZE,
 	SSBG1_LENGTH_FIELD_BYTES,
 	extractMFUPayload,
 	parseFecBlockProfile,
-	parseMPUHeader,
 	parseMMTPHeader,
 	trimSsbg1SourceSymbol,
 	type FecBlockProfile,
@@ -66,9 +62,9 @@ export interface ProcessFecBlockResult {
 /** Options for {@link processFecSymbol}. */
 export interface ProcessFecSymbolOptions {
 	/**
-	 * The stream's catalog `fec.blockProfile`. Required, never defaulted: the
-	 * two profiles lay a packet into a symbol differently, so the same
-	 * recovered bytes trim to different packets under each.
+	 * The stream's catalog `fec.blockProfile`. Required, never defaulted:
+	 * the profile fixes how a packet is laid into a symbol, and the only one
+	 * implemented is `iso-ssbg1-v1`.
 	 */
 	blockProfile: FecBlockProfile;
 	/** Symbol index within the block, used only for diagnostics. */
@@ -84,62 +80,15 @@ export interface ProcessFecBlockOptions {
 	/** Symbol size T in bytes (catalog `fec.symbolSize`). Required: there is no default T. */
 	symbolSize: number;
 	/**
-	 * Source symbols in the decoded block: K under `k-padded-v1`, SSB_length
-	 * under `iso-ssbg1-v1`. When omitted the block must be a whole number of
-	 * T-byte symbols and K is that number; a partial symbol throws.
+	 * Source symbols in the decoded block: its SSB_length (K'). When omitted
+	 * the block must be a whole number of T-byte symbols and K' is that
+	 * number; a partial symbol throws.
 	 */
 	k?: number;
 	/** Keep only symbols for this packetId. */
 	ownerPacketId?: number;
 }
 
-function hasUniformPaddingFrom(data: Uint8Array, start: number): boolean {
-	if (start >= data.length) return false;
-	const pad = data[start]!;
-	if (pad !== 0x00 && pad !== 0xee) return false;
-	for (let i = start + 1; i < data.length; i++) {
-		if (data[i] !== pad) return false;
-	}
-	return true;
-}
-
-function maybeExtendAltaTrailer(symbolData: Uint8Array, packetEnd: number): number {
-	if (packetEnd + MMTP_EXT_TRAILER_HEADER_SIZE > symbolData.length) return packetEnd;
-	const view = new DataView(
-		symbolData.buffer,
-		symbolData.byteOffset + packetEnd,
-		symbolData.byteLength - packetEnd,
-	);
-	const extType = view.getUint16(0, false);
-	if (extType !== MMTP_EXT_TYPE_ALTA_AUTH) return packetEnd;
-
-	const extLen = view.getUint16(2, false);
-	const trailerEnd = packetEnd + MMTP_EXT_TRAILER_HEADER_SIZE + extLen;
-	return trailerEnd <= symbolData.length ? trailerEnd : packetEnd;
-}
-
-function trimDecodedSourceSymbol(symbolData: Uint8Array): Uint8Array | null {
-	if (symbolData.length < MMTP_HEADER_SIZE + MPU_HEADER_SIZE) return null;
-
-	const headerLength = parseMMTPHeader(symbolData).headerLength;
-	if (symbolData.length < headerLength + MPU_HEADER_SIZE) return null;
-	const payload = symbolData.subarray(headerLength);
-	const mpu = parseMPUHeader(payload);
-	const trailingMpuHeaderSize = MPU_HEADER_SIZE - 2;
-	if (mpu.payloadLength < trailingMpuHeaderSize) return null;
-
-	// Recovered source symbols are fixed-width and may be padded, but their wire
-	// boundary is still the ISO length-after-field coordinate. ALTA may extend the
-	// packet from exactly that point; no MFU-content or alternate-length guessing.
-	const declaredEnd = headerLength + 2 + mpu.payloadLength;
-	if (declaredEnd > symbolData.length) return null;
-	const packetEnd = maybeExtendAltaTrailer(symbolData, declaredEnd);
-	if (packetEnd < symbolData.length && !hasUniformPaddingFrom(symbolData, packetEnd)) {
-		return null;
-	}
-	return symbolData.subarray(0, packetEnd);
-}
-
 function emptyProcessResult(): ProcessFecBlockResult {
 	return {
 		symbols: [],
@@ -172,8 +121,8 @@ function resultFromSymbols(
 	parsed.sort(comparePacketSequence);
 
 	// When ownerPacketId is set, only keep symbols matching the track that owns
-	// this FEC block. Other packetIds (including 0 from zero-padded recovery slots)
-	// are garbage and must be rejected to prevent decoder crashes.
+	// this FEC block. Other packetIds are garbage and must be rejected to
+	// prevent decoder crashes.
 	const symbols = ownerPacketId != null
 		? parsed.filter((s) => s.packetId === ownerPacketId)
 		: parsed;
@@ -186,9 +135,8 @@ type FailureCounter = (reason: string) => void;
 /**
  * Gate one candidate MMTP packet on its fixed header: long enough, version 0,
  * parseable, and an MPU packet. Returns the parsed header, or null after
- * counting why it was refused. Both profiles run this exact gate; they differ
- * only in which bytes they hand it (the symbol under k-padded-v1, the
- * length-delimited packet under iso-ssbg1-v1).
+ * counting why it was refused. It sees the length-delimited protected packet,
+ * never the padded symbol.
  */
 function gateMpuHeader(data: Uint8Array, bump: FailureCounter): MMTPHeader | null {
 	if (data.length < MMTP_HEADER_SIZE) {
@@ -223,7 +171,7 @@ function parseProtectedPacket(
 	// packet (fecType=1 per draft-ramadan-moq-mmt-00 §3.1), but the 4-byte
 	// Source FEC Payload ID (ISO 23008-1 §C.5.2) is never part of the protected
 	// packet (C.4.2). Tell extractMFUPayload to skip FEC PID subtraction so it
-	// does not truncate video data; any ALTA trailer must then consume the
+	// does not truncate video data; any legacy authenticator trailer must then consume the
 	// exact suffix after the declared payload.
 	const extraction = extractMFUPayload(packetData, { skipFecId: true });
 	if (!extraction) {
@@ -256,26 +204,6 @@ function parseProtectedPacket(
 	};
 }
 
-/**
- * k-padded-v1: the symbol is the protected packet zero-padded to T with no
- * length field, so the packet ends at its ISO-declared MPU boundary (plus an
- * ALTA trailer starting exactly there) and the rest must be uniform padding.
- */
-function parseKPaddedSymbol(
-	symbolData: Uint8Array,
-	index: number,
-	bump: FailureCounter,
-): ParsedFecSymbol | null {
-	const hdr = gateMpuHeader(symbolData, bump);
-	if (!hdr) return null;
-	const packetData = trimDecodedSourceSymbol(symbolData);
-	if (!packetData) {
-		bump("bad_length");
-		return null;
-	}
-	return parseProtectedPacket(packetData, hdr, index, bump);
-}
-
 /**
  * iso-ssbg1-v1 (ISO/IEC 23008-1 C.3.3 ssbg_mode1): the symbol is
  * `u16be(length) || protected packet || 00h padding`. The length field alone
@@ -300,22 +228,19 @@ function parseSsbg1Symbol(
 /**
  * Parse one recovered FEC source symbol into an MFU fragment.
  *
- * The symbol is laid out by the stream's block profile: under `k-padded-v1`
- * it is the protected MMTP packet zero-padded to T; under `iso-ssbg1-v1` it is
- * the ssbg_mode1 `u16 length || packet || zero padding`. Either way the
- * recovered packet is then parsed identically. Failures are counted by reason
- * (`bad_ssbg1_length` is the ISO length/padding refusal), never thrown.
+ * The symbol is the `iso-ssbg1-v1` ssbg_mode1 `u16 length || packet || zero
+ * padding` (ISO/IEC 23008-1 C.3.3): the length field alone delimits the
+ * protected packet, which is then parsed as an MMTP MPU packet. Failures are
+ * counted by reason (`bad_ssbg1_length` is the length/padding refusal), never
+ * thrown.
  *
- * @throws when `options.blockProfile` is absent or not a known profile token.
+ * @throws when `options.blockProfile` is absent or not `iso-ssbg1-v1`.
  */
 export function processFecSymbol(
 	symbolData: Uint8Array,
 	options: ProcessFecSymbolOptions,
 ): ProcessFecBlockResult {
-	const blockProfile = parseFecBlockProfile(
-		options?.blockProfile,
-		"processFecSymbol options.blockProfile",
-	);
+	parseFecBlockProfile(options?.blockProfile, "processFecSymbol options.blockProfile");
 	const failReasons: Record<string, number> = {};
 	let failedCount = 0;
 	const bump: FailureCounter = (reason) => {
@@ -328,9 +253,7 @@ export function processFecSymbol(
 	const index = options.index ?? 0;
 	let parsed: ParsedFecSymbol | null;
 	try {
-		parsed = blockProfile === "iso-ssbg1-v1"
-			? parseSsbg1Symbol(symbolData, index, bump)
-			: parseKPaddedSymbol(symbolData, index, bump);
+		parsed = parseSsbg1Symbol(symbolData, index, bump);
 	} catch {
 		bump("exception");
 		parsed = null;
@@ -343,14 +266,14 @@ export function processFecSymbol(
 	);
 }
 
-function requireSymbolSize(symbolSize: unknown, blockProfile: FecBlockProfile): number {
+function requireSymbolSize(symbolSize: unknown): number {
 	if (symbolSize === undefined) {
 		throw new Error("processFecBlock options.symbolSize is required: name the catalog fec.symbolSize (T)");
 	}
 	if (typeof symbolSize !== "number" || !Number.isSafeInteger(symbolSize) || symbolSize <= 0) {
 		throw new Error(`processFecBlock options.symbolSize must be a positive integer (got ${String(symbolSize)})`);
 	}
-	if (blockProfile === "iso-ssbg1-v1" && symbolSize <= SSBG1_LENGTH_FIELD_BYTES) {
+	if (symbolSize <= SSBG1_LENGTH_FIELD_BYTES) {
 		throw new Error(
 			`processFecBlock options.symbolSize must exceed the ${SSBG1_LENGTH_FIELD_BYTES}-byte ssbg_mode1 length field (got ${symbolSize})`,
 		);
@@ -362,7 +285,6 @@ function requireSourceSymbolCount(
 	k: number | undefined,
 	blockLength: number,
 	symbolSize: number,
-	blockProfile: FecBlockProfile,
 ): number {
 	if (k === undefined) {
 		if (blockLength % symbolSize !== 0) {
@@ -377,7 +299,7 @@ function requireSourceSymbolCount(
 	}
 	// An iso-ssbg1-v1 block is exactly K' = SSB_length symbols of T bytes
 	// (C.5.3); any other length is not the block the repair symbols described.
-	if (blockProfile === "iso-ssbg1-v1" && blockLength !== k * symbolSize) {
+	if (blockLength !== k * symbolSize) {
 		throw new Error(
 			`processFecBlock: an iso-ssbg1-v1 block of ${k} symbols of ${symbolSize} bytes is ${k * symbolSize} bytes (got ${blockLength})`,
 		);
@@ -389,17 +311,16 @@ function requireSourceSymbolCount(
  * Process a decoded FEC block into individual MFU fragments.
  *
  * The WASM RaptorQ decoder returns every source symbol of the block
- * concatenated (K x T bytes under `k-padded-v1`, SSB_length x T bytes under
- * `iso-ssbg1-v1`). This function splits them apart, recovers each protected
- * packet by the stream's block profile (see {@link processFecSymbol}),
- * extracts the MFU payload via shared extractMFUPayload, and returns
- * structured results sorted for reassembly.
+ * concatenated (SSB_length x T bytes). This function splits them apart,
+ * recovers each protected packet from its ssbg_mode1 length field (see
+ * {@link processFecSymbol}), extracts the MFU payload via shared
+ * extractMFUPayload, and returns structured results sorted for reassembly.
  *
  * @param blockData - Concatenated source symbols from the WASM decoder
  * @param options - Block profile and symbol size T are required; see {@link ProcessFecBlockOptions}
  * @throws when the block profile or symbol size is absent or invalid, when an
- *   omitted `k` cannot be read exactly from the block length, or when an
- *   `iso-ssbg1-v1` block is not exactly `k` symbols long.
+ *   omitted `k` cannot be read exactly from the block length, or when the
+ *   block is not exactly `k` symbols long.
  */
 export function processFecBlock(
 	blockData: Uint8Array,
@@ -409,11 +330,11 @@ export function processFecBlock(
 		options?.blockProfile,
 		"processFecBlock options.blockProfile",
 	);
-	const symbolSize = requireSymbolSize(options.symbolSize, blockProfile);
+	const symbolSize = requireSymbolSize(options.symbolSize);
 
 	if (!blockData || blockData.length === 0) return emptyProcessResult();
 
-	const k = requireSourceSymbolCount(options.k, blockData.length, symbolSize, blockProfile);
+	const k = requireSourceSymbolCount(options.k, blockData.length, symbolSize);
 
 	const failReasons: Record<string, number> = {};
 	let failedCount = 0;

package/src/fec-block-mapper.ts

@@ -8,17 +8,10 @@
  * It deliberately does NOT map MoQ media groups to FEC blocks. A recovered
  * packet's media group is read from its own MMTP/MPU header
  * ({@link recoveredPacketMediaGroup}), never from SBN arithmetic, and a source
- * symbol's block comes from the wire:
- *
- * - `k-padded-v1`: `SBN = floor(SS_ID / K)`, `ESI = SS_ID mod K`
- *   ({@link FecBlockMapper.fromSsId}).
- * - `iso-ssbg1-v1`: a block is the SS_ID range `[SS_Start, SS_Start +
- *   SSB_length)` its Repair FEC Payload ID states (ISO/IEC 23008-1 C.5.3), so
- *   SS_ID alone locates nothing and `fromSsId` throws.
- *
- * Object FEC (draft-ramadan-moq-fec §9.1) is the one exception: there each MoQ
- * group IS its own FEC block, so {@link ObjectBlockMapper} keeps its identity
- * `derive`.
+ * symbol's block comes from the wire: under `iso-ssbg1-v1` a block is the SS_ID
+ * range `[SS_Start, SS_Start + SSB_length)` its Repair FEC Payload ID states
+ * (ISO/IEC 23008-1 C.5.3), so SS_ID alone locates nothing and `fromSsId`
+ * throws for every stream with an FEC instance.
  */
 
 import {
@@ -36,10 +29,7 @@ export interface FecBlockConfig {
   interleaveDepthMs: number
   /** GOP/frame duration (milliseconds). Measured from actual MMTP timestamps. */
   gopDurationMs: number
-  /**
-   * K from catalog fec.sourceSymbols: the source symbols per block under
-   * `k-padded-v1`, the maximum SSB_length under `iso-ssbg1-v1`.
-   */
+  /** K from catalog fec.sourceSymbols: the maximum SSB_length of a block. */
   k: number
   /**
    * The catalog `fec.blockProfile`. Required and validated with
@@ -48,7 +38,7 @@ export interface FecBlockConfig {
   blockProfile: FecBlockProfile
 }
 
-/** FEC coordinates of one MoQ object, for the mappers whose groups are blocks. */
+/** FEC coordinates of one MoQ object, for the mapper whose groups are blocks. */
 export interface FecCoordinates {
   /** Source Block Number */
   sbn: number
@@ -98,7 +88,7 @@ interface NoFecInstanceConfig {
 export class FecBlockMapper {
   /** Media units (GOPs/frames) per FEC block, recovered with positive round-half-up semantics. */
   readonly d: number
-  /** K: source symbols per block (`k-padded-v1`) or the maximum SSB_length (`iso-ssbg1-v1`). */
+  /** K: the maximum SSB_length of a block (catalog `fec.sourceSymbols`). */
   readonly k: number
   /** Block time span (ms) — used as pacing threshold */
   readonly interleaveDepthMs: number
@@ -127,24 +117,17 @@ export class FecBlockMapper {
   }
 
   /**
-   * The `k-padded-v1` locator: SS_ID → (SBN, ESI) with `SBN = floor(SS_ID / K)`
-   * and `ESI = SS_ID mod K`, for MMTP over multicast UDP where the Source FEC
-   * Payload ID carries SS_ID directly.
+   * SS_ID → (SBN, ESI). Only {@link NullBlockMapper} answers: a stream with an
+   * FEC instance is `iso-ssbg1-v1`, whose blocks are located by
+   * `(SS_Start, SSB_length)` range membership and never from SS_ID alone.
    *
-   * @throws under `iso-ssbg1-v1`, where a block is located by
-   *   `(SS_Start, SSB_length)` range membership and never from SS_ID alone
+   * @throws for every stream with an FEC instance
    */
-  fromSsId(ssId: number): { sbn: number; esi: number } {
-    if (this.blockProfile !== 'k-padded-v1') {
-      throw new Error(
-        `fromSsId is the k-padded-v1 locator; a ${this.blockProfile ?? 'non-FEC'} stream locates a block by ` +
-          '(SS_Start, SSB_length) range membership, never from SS_ID alone',
-      )
-    }
-    return {
-      sbn: Math.floor(ssId / this.k),
-      esi: ssId % this.k,
-    }
+  fromSsId(_ssId: number): { sbn: number; esi: number } {
+    throw new Error(
+      `fromSsId: a ${this.blockProfile ?? 'non-FEC'} stream locates a block by ` +
+        '(SS_Start, SSB_length) range membership, never from SS_ID alone',
+    )
   }
 
   /**
@@ -200,77 +183,6 @@ export class NullBlockMapper extends FecBlockMapper {
   }
 }
 
-/**
- * Object-level FEC (§9.1): each MoQ group (frame) is its own FEC block.
- * K_actual = ceil(frame_bytes / symbolSize) — varies per block.
- *
- * SBN = group_id, ESI = object_id.
- * SS_ID = Group_ID * sourceSymbols + Object_ID (§9.1.2).
- *
- * That SS_ID is the K-stride numbering of `k-padded-v1`; `iso-ssbg1-v1`
- * numbers SS_IDs consecutively per source packet (ISO/IEC 23008-1 C.5.2), so
- * §9.1 object FEC is defined only under `k-padded-v1` and the constructor
- * refuses any other profile.
- *
- * The stride of that numbering is the catalog `sourceSymbols`, never a
- * block's own K: a short block (K_actual < sourceSymbols) still starts at
- * `Group_ID * sourceSymbols` (its repair's SS_Start) and leaves the rest of
- * its stride unused, which is exactly `k-padded-v1` with `SSB_length =
- * K_actual`. So the SS_ID locator is the inherited
- * {@link FecBlockMapper.fromSsId} over `k = sourceSymbols`, the exact inverse
- * of {@link ObjectBlockMapper.derive}; it needs no per-block K and infers
- * nothing.
- *
- * This mapper does NOT carry per-block K. Each block discovers its own K from:
- *   1. Clean reception: counting source objects per group
- *   2. Repair packets: SSB_length in the Repair FEC Payload ID (ISO 23008-1 C.5.3)
- *
- * Callers MUST pass per-block K to FecBlockManager.addSourcePacket/addRepairPacket.
- * Created once per stream, GC'd on stream close (Effect cleanup).
- */
-export class ObjectBlockMapper extends FecBlockMapper {
-  /** Catalog sourceSymbols (max K) — used ONLY for SS_ID encoding (§9.1.2).
-   *  Actual per-block K varies: K_actual = ceil(frame_bytes / symbolSize). */
-  readonly sourceSymbolsMax: number
-
-  /**
-   * @param gopDurationMs - GOP/frame duration (ms)
-   * @param sourceSymbolsMax - Catalog `fec.sourceSymbols`
-   * @param blockProfile - Catalog `fec.blockProfile`; must be `k-padded-v1`
-   */
-  constructor(gopDurationMs: number, sourceSymbolsMax: number, blockProfile: FecBlockProfile) {
-    if (sourceSymbolsMax <= 0) throw new Error('ObjectBlockMapper: sourceSymbolsMax must be > 0 (from catalog)')
-    const profile = parseFecBlockProfile(blockProfile, 'ObjectBlockMapper fec.blockProfile')
-    if (profile !== 'k-padded-v1') {
-      throw new Error(
-        `ObjectBlockMapper: §9.1 object FEC numbers SS_ID = Group_ID * K + Object_ID, the k-padded-v1 stride; ` +
-          `it is not defined under ${profile}`,
-      )
-    }
-    // D=1, K=sourceSymbolsMax for SS_ID math only — actual block K varies
-    super({ interleaveDepthMs: gopDurationMs, gopDurationMs, k: sourceSymbolsMax, blockProfile: profile })
-    this.sourceSymbolsMax = sourceSymbolsMax
-  }
-
-  /**
-   * SBN = group_id, ESI = object_id. SS_ID per §9.1.2. Its inverse is the
-   * inherited `fromSsId` (SBN = floor(SS_ID / sourceSymbols), ESI = SS_ID mod
-   * sourceSymbols).
-   */
-  derive(groupId: number, objectId: number): FecCoordinates {
-    return {
-      sbn: groupId,
-      esi: objectId,
-      ssId: groupId * this.sourceSymbolsMax + objectId,
-    }
-  }
-
-  /** One frame of latency: each frame is its own block. */
-  override get pacingThresholdMs(): number {
-    return this.gopDurationMs // one frame latency
-  }
-}
-
 /**
  * Create a FecBlockMapper from catalog FEC config + measured GOP duration.
  *
@@ -278,8 +190,10 @@ export class ObjectBlockMapper extends FecBlockMapper {
  *   {@link NullBlockMapper}; `fec.blockProfile` is not read, since a stream
  *   without FEC names none.
  * - Otherwise `fec.blockProfile` is required (validated with
- *   `parseFecBlockProfile`, throwing when absent or unknown), and
- *   `mode: 'object'` → {@link ObjectBlockMapper}, else {@link FecBlockMapper}.
+ *   `parseFecBlockProfile`, throwing unless it is `iso-ssbg1-v1`) and the
+ *   result is a {@link FecBlockMapper}. `mode: 'object'` (per-group object
+ *   FEC, SS_ID = Group_ID * K + Object_ID) throws: that numbering is the
+ *   retired `k-padded-v1` stride, which `iso-ssbg1-v1` does not define.
  */
 export function createMapper(
   fecConfig: {
@@ -295,9 +209,10 @@ export function createMapper(
     return new NullBlockMapper(gopDurationMs)
   }
   const blockProfile = parseFecBlockProfile(fecConfig.blockProfile, 'fec.blockProfile')
-  // extensions feature — see moqcast-draft docs/fec-extensions-material.md, not in public -00
   if (fecConfig.mode === 'object') {
-    return new ObjectBlockMapper(gopDurationMs, fecConfig.sourceSymbols, blockProfile)
+    throw new Error(
+      `createMapper: object FEC numbers SS_ID = Group_ID * K + Object_ID, which ${blockProfile} does not define`,
+    )
   }
   return new FecBlockMapper({
     interleaveDepthMs: fecConfig.interleaveDepthMs && fecConfig.interleaveDepthMs > 0

package/src/index.ts

@@ -66,13 +66,14 @@ export {
 	deriveFecRetentionBlocks,
 	tryDeriveFecRetentionBlocks,
 	MAX_FEC_RETENTION_BLOCKS,
+	LOCAL_FEC_RETENTION_BLOCKS,
+	LOCAL_FEC_TIMEOUT_MS,
 	playbackLatencyMs,
 } from "./oti.js";
 
 export {
 	FecBlockMapper,
 	NullBlockMapper,
-	ObjectBlockMapper,
 	createMapper,
 	recoveredPacketMediaGroup,
 	type FecBlockConfig,
@@ -89,6 +90,10 @@ export {
 	extendSsId,
 	repairFetchRange,
 	repairGroupIdMatches,
+	RepairEpochReferences,
+	type RepairEpochStats,
 	type RepairFetchAnchor,
 	type RepairFetchRange,
+	type RepairGroupPlan,
+	type RepairLargestOutcome,
 } from "./repair-group.js";

package/src/oti.ts

@@ -118,15 +118,16 @@ function validateOTIFields(F: number, T: number, Z: number, N: number, Al: numbe
  * Resolve a catalog FEC block's span in milliseconds.
  *
  * The catalog carries exactly ONE interleave field: `interleaveDepthMs`, the
- * full FEC block span in MILLISECONDS (draft-ramadan-moq-fec §5.1). Receivers
- * derive D -- the MEDIA UNITS per block, not a block count -- with
- * `deriveFecInterleaveDepth`. Reading D as a block count is BLO-35597.
+ * full FEC block send span in MILLISECONDS (draft-ramadan-moq-fec §5.1).
+ * Block boundaries still come from the wire's SS_Start and SSB_length; this
+ * field never supplies a group count or replaces those coordinates.
  *
- * Absent, non-finite or non-positive → undefined; callers treat that as
- * unconfigured and error rather than guess. Finiteness is checked separately
- * from `> 0` because `Infinity` satisfies `> 0`: a JSON catalog cannot spell
- * `Infinity`, but any overflowing literal (`1e999`) parses to it, and it would
- * then reach `fecBlockBudgetMs` as an unbounded span. The legacy
+ * Absent → undefined. An explicit zero is returned as zero: it is the
+ * catalog's no-elapsed-deadline sentinel, not an invitation to infer a span.
+ * Positive values must be safe integer milliseconds. Finiteness is checked
+ * separately from the range because `Infinity` satisfies `> 0`: a JSON catalog
+ * cannot spell `Infinity`, but any overflowing literal (`1e999`) parses to it,
+ * and it would then reach `fecBlockBudgetMs` as an unbounded span. The legacy
  * `interleaveDepth` frame-count key and
  * the `interleaveMs` alias were removed in the BLO-14526 clean cut — producers
  * emit milliseconds only, and there is deliberately NO fallback read.
@@ -139,7 +140,7 @@ export function catalogFecInterleaveMs(
 	fec: FecInterleaveCatalog | undefined,
 ): number | undefined {
 	const ms = fec?.interleaveDepthMs;
-	return typeof ms === "number" && ms > 0 && Number.isFinite(ms) ? ms : undefined;
+	return typeof ms === "number" && Number.isSafeInteger(ms) && ms >= 0 ? ms : undefined;
 }
 
 /**
@@ -390,6 +391,16 @@ export function deriveFecRetentionBlocks(
  */
 export const MAX_FEC_RETENTION_BLOCKS = 0xff;
 
+/**
+ * Receiver-local block retention used when the catalog carries no elapsed-time
+ * FEC window. This is a memory/cleanup bound only; it is never derived from
+ * media rate and never treated as a catalog deadline.
+ */
+export const LOCAL_FEC_RETENTION_BLOCKS = 2;
+
+/** Receiver-local cleanup budget used when the catalog has no elapsed span. */
+export const LOCAL_FEC_TIMEOUT_MS = 500;
+
 /**
  * `deriveFecRetentionBlocks` without the throw: the block count, or `undefined`
  * when the geometry cannot define one.