@blockcast/mmt-container 0.4.1 → 0.5.0-main.2c1f81817995

package/src/index.ts

@@ -39,15 +39,11 @@ export {
 export { isCompleteFmp4DataUnit } from './fmp4-completion.js'
 
 
-// source-auth (authenticated-manifest / Merkle) is intentionally NOT re-exported
-// from the eager index barrel. It statically imports blake3 from @noble/hashes,
-// and re-exporting it here pulls that bare specifier into every browser consumer
-// of @blockcast/mmt-container (the moq-lib / shred / moqtail players load the
-// barrel as raw ESM via an import map, where @noble/hashes has no mapping →
-// "Failed to resolve module specifier". No browser player uses source-auth.)
-// Consumers that need it import the dedicated subpath: '@blockcast/mmt-container/source-auth'.
-// The same rule covers the @blockcast/mmt-manifest-verify surface (ManifestVerifier et al.):
-// import it from that package (or the subpath above) directly, never from this barrel.
+// The bc-provenance v2 surface (@blockcast/mmt-manifest-verify) is intentionally
+// NOT re-exported from the eager index barrel: it imports @noble/curves and
+// @noble/hashes, bare specifiers the moq-lib / shred / moqtail players (which
+// load the barrel as raw ESM via an import map) cannot resolve. Import it from
+// that package directly. The router's provenance hooks take it by type only.
 
 // H.264/AVC + H.265/HEVC Codec Utilities
 export {

package/src/mmtp-fec-session.ts

@@ -18,6 +18,11 @@
  * The retention is derived from the catalog's `fecBlockBudgetMs`, and a
  * catalog missing either input throws rather than defaulting.
  *
+ * Every repair packet runs the fec-01 6.3.9 held-layer check (layer 0, B_0 =
+ * catalog `fec.repairSymbols`) through the same HeldLayerAdmission FECManager
+ * uses. A packet below B_0 at or after the anchor fails the session closed:
+ * `stats.failClosed` reports why, and every later repair is refused.
+ *
  * Every repair packet that cannot be used is counted under the reason it was
  * refused, and every block ends under exactly one outcome, so a stream whose
  * FEC is doing nothing can be told apart from one with nothing to repair.
@@ -37,6 +42,14 @@ import {
   type FecBlockProfile,
 } from '@blockcast/mmt-base'
 import { deriveFecRetentionBlocks, fecBlockBudgetMs } from '@blockcast/mmt-fec'
+import {
+  HeldLayerAdmission,
+  heldLayerAnchorHorizon,
+  type FecFailClosedReason,
+  type HeldLayerInput,
+} from './held-layer-admission.js'
+
+export type { FecFailClosedReason, HeldLayerInput } from './held-layer-admission.js'
 
 /** The mmt-wasm `MmtFecDecoder` members the session drives. */
 export interface MmtpFecSessionDecoder {
@@ -67,6 +80,10 @@ export interface MmtpFecSessionCatalogFec {
   algorithm?: unknown
   blockProfile?: unknown
   sourceSymbols?: unknown
+  /** P_0: layer 0's repair symbols per block, the fec-01 6.3.9 total B_0. */
+  repairSymbols?: unknown
+  /** Layer 0's repair track; names it for addRepair()'s `repairTrackName`. */
+  repairTrack?: unknown
   symbolSize?: unknown
   interleaveDepthMs?: unknown
   reorderToleranceMs?: unknown
@@ -77,6 +94,14 @@ export interface MmtpFecSessionConfig {
   fec: MmtpFecSessionCatalogFec
   /** Builds the RaptorQ decoder, normally `wasm_bindgen.MmtFecDecoder`. */
   Decoder: MmtpFecSessionDecoderConstructor
+  /**
+   * The source's repair layers as the catalog resolves them
+   * (`TrackFecParams.repairLayers`), for a caller that subscribes more than
+   * layer 0. Absent: layer 0 alone, B_0 = `fec.repairSymbols`.
+   */
+  repairLayers?: readonly HeldLayerInput[]
+  /** The layers the caller holds (fec-01 6.3.9). Absent: [0]. */
+  heldLayers?: readonly number[]
 }
 
 /**
@@ -139,6 +164,16 @@ export interface MmtpFecSessionStats {
    * contributed nothing to its block and do not make it mixed.
    */
   mixedPath: MmtpFecSessionMixedPathStats
+  /**
+   * fec-01 6.3.9: null until a repair packet at or after the anchor (the
+   * earliest block, in SS_Start serial order, whose repair carried
+   * RSB_length >= B_0) states an RSB_length below B_0; then why. Terminal:
+   * every later repair is refused under `repair:fail-closed` (the packet that
+   * failed it is counted there too), and block state stays as it was. Sources
+   * are still taken and can still complete a block from repair admitted
+   * before the failure.
+   */
+  failClosed: FecFailClosedReason | null
 }
 
 interface BlockState {
@@ -160,6 +195,8 @@ export class MmtpFecSession {
   readonly blockProfile: FecBlockProfile
   readonly algorithm: 'raptorq' | 'reed-solomon'
   readonly sourceSymbols: number
+  /** P_0 = B_0, the held total every repair packet is checked against. */
+  readonly repairSymbols: number
   readonly symbolSize: number
   /** The decoder's retention, in blocks, derived from the catalog budget. */
   readonly retentionBlocks: number
@@ -178,6 +215,9 @@ export class MmtpFecSession {
   /** The newest SS_ID when the remembered SS_IDs were last pruned. */
   #prunedAt: number | undefined
   #repairPacketId: number | undefined
+  #newestSource: number | undefined
+  #heldLayers: HeldLayerAdmission
+  #anchorHorizon: number
   #stats: MmtpFecSessionStats = {
     sourceSymbols: 0,
     repairSymbols: 0,
@@ -191,11 +231,12 @@ export class MmtpFecSession {
     sourceSymbolsByPath: { moq: 0, multicast: 0 },
     repairSymbolsByPath: { moq: 0, multicast: 0 },
     mixedPath: { clean: 0, recovered: 0, failed: 0, released: 0 },
+    failClosed: null,
   }
 
   /**
    * @throws when the catalog block lacks or misstates a field the session
-   *   needs: the block profile, K, T, `interleaveDepthMs` or
+   *   needs: the block profile, K, P_0 (`repairSymbols`), T, `interleaveDepthMs` or
    *   `reorderToleranceMs`. None is defaulted.
    */
   constructor(config: MmtpFecSessionConfig) {
@@ -209,6 +250,7 @@ export class MmtpFecSession {
     }
     this.algorithm = fec.algorithm === 'reed-solomon' ? 'reed-solomon' : 'raptorq'
     this.sourceSymbols = requirePositiveInteger(fec.sourceSymbols, 'fec.sourceSymbols')
+    this.repairSymbols = requirePositiveInteger(fec.repairSymbols, 'fec.repairSymbols')
     this.symbolSize = requirePositiveInteger(fec.symbolSize, 'fec.symbolSize')
     const interleaveDepthMs = requireNumber(fec.interleaveDepthMs, 'fec.interleaveDepthMs')
     const reorderToleranceMs = requireNumber(fec.reorderToleranceMs, 'fec.reorderToleranceMs')
@@ -216,6 +258,18 @@ export class MmtpFecSession {
       fecBlockBudgetMs(interleaveDepthMs, reorderToleranceMs),
       interleaveDepthMs,
     )
+    this.#heldLayers = new HeldLayerAdmission(
+      config.repairLayers ?? [
+        {
+          layer: 0,
+          repairTrackName: typeof fec.repairTrack === 'string' ? fec.repairTrack : '',
+          rsIdOffset: 0,
+          repairSymbols: this.repairSymbols,
+        },
+      ],
+      config.heldLayers,
+    )
+    this.#anchorHorizon = heldLayerAnchorHorizon(this.retentionBlocks, this.sourceSymbols)
     if (typeof config.Decoder !== 'function') {
       throw new Error('MmtpFecSession: a decoder constructor (wasm_bindgen.MmtFecDecoder) is required')
     }
@@ -241,6 +295,7 @@ export class MmtpFecSession {
       sourceSymbolsByPath: { ...this.#stats.sourceSymbolsByPath },
       repairSymbolsByPath: { ...this.#stats.repairSymbolsByPath },
       mixedPath: { ...this.#stats.mixedPath },
+      failClosed: this.#stats.failClosed && { ...this.#stats.failClosed },
     }
   }
 
@@ -266,6 +321,7 @@ export class MmtpFecSession {
     this.#stats.sourceSymbols++
     this.#stats.sourceSymbolsByPath[path]++
     this.#noteNewest(ssId)
+    if (this.#newestSource === undefined || serial32Precedes(this.#newestSource, ssId)) this.#newestSource = ssId
 
     const start = this.#blockStartOf(ssId)
     const block = start === undefined ? undefined : this.#blocks.get(start)
@@ -298,14 +354,17 @@ export class MmtpFecSession {
    * Feeds one object of the repair track: a whole MMTP repair packet (ISO/IEC
    * 23008-1 C.5.3). A repair track carries one repair flow, so the first
    * repair packet fixes its packet ID and a packet of any other is refused.
-   * `path` is where it was received, as for addSource().
+   * `path` is where it was received, as for addSource(). `repairTrackName`
+   * is the repair track it was received on, for the 6.3.9 own-track rule; a
+   * track the layers do not list is refused as `repair:unlisted-track`.
    *
    * @returns the protected packets this repair symbol recovered, as for
    *   addSource().
    */
-  addRepair(packet: Uint8Array, path: MmtpFecSessionPath = 'moq'): Uint8Array[] {
+  addRepair(packet: Uint8Array, path: MmtpFecSessionPath = 'moq', repairTrackName?: string): Uint8Array[] {
     const decoder = this.#decoder
     if (!decoder) return this.#drop('repair:released')
+    if (this.#stats.failClosed) return this.#drop('repair:fail-closed')
     const pathBit = PATH_BITS[path]
     if (!pathBit) return this.#drop('repair:unknown-path')
     let header
@@ -328,6 +387,20 @@ export class MmtpFecSession {
     if (this.algorithm === 'reed-solomon' && frame.ssbLength + frame.rsbLength > 255) {
       return this.#drop('repair:rs-block-length')
     }
+    // fec-01 6.3.9, after the 4.5 discards and the size check, before a block
+    // is placed. Without a track name only the anchored rule (b) applies.
+    const verdict = this.#heldLayers.admit(
+      repairTrackName,
+      frame.ssStart,
+      frame.rsbLength,
+      this.#anchorHorizon,
+      this.#newestSource,
+    )
+    if (verdict === 'discard') return this.#drop('repair:unlisted-track')
+    if (verdict !== undefined) {
+      this.#stats.failClosed = verdict
+      return this.#drop('repair:fail-closed')
+    }
 
     const start = frame.ssStart
     let block = this.#blocks.get(start)