@blockcast/mmt-container 0.4.1 → 0.5.0-main.34c7b9c2cfa0

package/src/held-layer-admission.ts

@@ -0,0 +1,161 @@
+/**
+ * The fec-01 6.3.9 receiver check (held-layer anchored RSB_length), in one
+ * place. FECManager and MmtpFecSession both run their repair packets through
+ * HeldLayerAdmission; neither restates the rule.
+ */
+
+import { serial32Distance, serial32Precedes } from '@blockcast/mmt-base'
+
+/**
+ * Why a source track's FEC failed closed at runtime (fec-01 6.3.9): a repair
+ * packet stated an RSB_length below a held layer's total B_i on that layer's
+ * own repair track (`below_own_track_total`), or at or after the anchor, the
+ * earliest block in SS_Start serial order whose repair carried >= B_i
+ * (`below_anchored_total`). Repair for the track is refused from then on.
+ */
+export interface FecFailClosedReason {
+  code: 'below_own_track_total' | 'below_anchored_total'
+  layer: number
+  total: number
+  rsbLength: number
+  ssStart: number
+  anchor?: number
+}
+
+/** One repair layer as the catalog states it: B_i = rsIdOffset + repairSymbols. */
+export interface HeldLayerInput {
+  layer: number
+  repairTrackName: string
+  rsIdOffset: number
+  repairSymbols: number
+}
+
+interface HeldLayerState {
+  layer: number
+  repairTrackName: string
+  total: number
+  /** Earliest (serial order) block start whose repair carried >= total. */
+  anchor?: number
+  /** Latest (serial order) block start whose repair carried < total. */
+  latestBelow?: number
+  /** RSB_length that latestBelow's repair carried, for the fail-closed reason. */
+  latestBelowRsb?: number
+  /** Newest block start seen; anchor and latestBelow are retired behind it. */
+  newest?: number
+  /**
+   * The anchor fell behind the horizon, so no block that can still arrive
+   * precedes it: every later packet must carry >= total. Its serial is no
+   * longer compared, so SS_Start wrapping past it cannot misorder it.
+   */
+  settled?: boolean
+}
+
+/** The largest horizon compared, so every compared serial stays in one half-window. */
+const HORIZON_CAP = 0x40000000
+
+/**
+ * How far (in SS_Start symbols) behind the newest block a 6.3.9 anchor or
+ * below-total block can still matter: the iso retention in blocks times K,
+ * capped at 2^30. Unknown inputs give the cap.
+ */
+export function heldLayerAnchorHorizon(retentionBlocks: number | undefined, k: number): number {
+  return retentionBlocks === undefined || k <= 0 ? HORIZON_CAP : Math.min(HORIZON_CAP, retentionBlocks * k)
+}
+
+/**
+ * fec-01 6.3.9 anchored state for one FEC instance's held layers. For each
+ * held layer i with total B_i = O_i + P_i: the anchor is the earliest block,
+ * in SS_Start serial order, whose repair carried RSB_length >= B_i. The
+ * instance fails closed on (a) a packet on layer i's own repair track (i > 0)
+ * below B_i, or (b) any packet of the instance at or after the anchor below
+ * B_i. Blocks before the anchor (pre-append) stay valid at the previous total.
+ * The result is not latched here: the caller owns what failing closed means.
+ */
+export class HeldLayerAdmission {
+  readonly #layerNames: ReadonlySet<string>
+  readonly #states: HeldLayerState[]
+
+  constructor(layers: readonly HeldLayerInput[], heldLayers: readonly number[] = [0]) {
+    const held = new Set(heldLayers)
+    this.#layerNames = new Set(layers.map((l) => l.repairTrackName))
+    this.#states = layers
+      .filter((l) => held.has(l.layer))
+      .map((l) => ({ layer: l.layer, repairTrackName: l.repairTrackName, total: l.rsIdOffset + l.repairSymbols }))
+  }
+
+  /**
+   * Judges one repair packet, after the 4.5 discards and the size check and
+   * before it places a block. `repairTrackName` is the subscribed repair
+   * track, never inferred from RS_ID; without it only (b) runs. A packet on a
+   * repair track the catalog does not list is `'discard'` and anchors nothing.
+   * `sourceFrontier` is the newest source SS_ID, if any: a repair more than
+   * `horizon` past it is judged without moving the anchored state.
+   *
+   * @returns undefined to admit, `'discard'`, or the fail-closed reason.
+   */
+  admit(
+    repairTrackName: string | undefined,
+    ssStart: number,
+    rsbLength: number,
+    horizon: number,
+    sourceFrontier?: number,
+  ): FecFailClosedReason | 'discard' | undefined {
+    if (repairTrackName !== undefined && !this.#layerNames.has(repairTrackName)) return 'discard'
+    // A repair may run ahead of the media, but one more than `horizon` past the
+    // source frontier must not move the held-layer state: advancing `newest` on
+    // it would retire every real anchor and skip this check until traffic caught
+    // up. Such a repair is still judged below the total: it is on its own track,
+    // or after any anchor by definition. With no anchor yet it says nothing.
+    // It is still admitted: in iso the frontier only moves when a repair places
+    // held sources, so dropping it would stall recovery after a long outage.
+    // IsoBlockLocator.placeRepair may still refuse the same repair as `ahead`:
+    // it measures from `newest`, which held sources move, not from this frontier.
+    const farAhead =
+      sourceFrontier !== undefined &&
+      serial32Precedes(sourceFrontier, ssStart) &&
+      serial32Distance(sourceFrontier, ssStart) > horizon
+    for (const state of this.#states) {
+      let code: FecFailClosedReason['code'] | undefined
+      if (farAhead) {
+        if (rsbLength < state.total) {
+          if (state.layer > 0 && repairTrackName === state.repairTrackName) code = 'below_own_track_total'
+          else if (state.anchor !== undefined || state.settled) code = 'below_anchored_total'
+        }
+      } else {
+        // Serials more than `horizon` behind the newest block are retired, so
+        // every serial still compared sits inside one half-window and SS_Start
+        // wrapping on a long-running stream cannot reorder them.
+        if (state.newest === undefined || serial32Precedes(state.newest, ssStart)) state.newest = ssStart
+        const stale = (s: number) => serial32Distance(s, state.newest!) > horizon
+        if (state.latestBelow !== undefined && stale(state.latestBelow)) {
+          delete state.latestBelow
+          delete state.latestBelowRsb
+        }
+        if (state.anchor !== undefined && stale(state.anchor)) state.settled = true
+        if (rsbLength < state.total) {
+          if (state.layer > 0 && repairTrackName === state.repairTrackName) code = 'below_own_track_total'
+          else if (stale(ssStart)) continue // past retention: undecodable, anchors nothing
+          else if (state.settled || (state.anchor !== undefined && !serial32Precedes(ssStart, state.anchor))) code = 'below_anchored_total'
+          else if (state.latestBelow === undefined || serial32Precedes(state.latestBelow, ssStart)) {
+            state.latestBelow = ssStart
+            state.latestBelowRsb = rsbLength
+          }
+        } else if (!state.settled && !stale(ssStart)) {
+          if (state.anchor === undefined || serial32Precedes(ssStart, state.anchor)) state.anchor = ssStart
+          if (state.latestBelow !== undefined && !serial32Precedes(state.latestBelow, state.anchor)) {
+            code = 'below_anchored_total'
+            ssStart = state.latestBelow
+            rsbLength = state.latestBelowRsb!
+          }
+        }
+      }
+      if (code !== undefined) {
+        return {
+          code, layer: state.layer, total: state.total, rsbLength, ssStart,
+          ...(state.anchor === undefined ? {} : { anchor: state.anchor }),
+        }
+      }
+    }
+    return undefined
+  }
+}

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 {
@@ -653,6 +649,7 @@ export {
   type RepairPriorityReason,
   type RepairSendMeasurement,
   type RepairSkipReason,
+  type RepairStopReason,
   type RepairSubscribeCallback,
   type WireRepairFetchOptions,
 } from './repair-fetch.js'

package/src/mmtp-container-parser.ts

@@ -234,6 +234,14 @@ export interface FecReleaseGate {
   ): FrameGapDecision
   /** Every frame released in order from a gated stream. */
   onReleased?(data: Uint8Array, meta: FrameMeta): void
+  /**
+   * Whether a complete frame is a RAP (draft-ramadan-moq-fec 11.4.2). Asked
+   * for each video frame with a Source FEC Payload ID that enters the gate,
+   * held or released; absent, no frame counts as a RAP.
+   */
+  isRap?(data: Uint8Array, meta: FrameMeta): boolean
+  /** A complete RAP entered the gate at SS_ID `ssId` (see `isRap`). */
+  onRap?(packetId: number, catalogTrackName: string | undefined, ssId: number): void
 }
 
 /** Typed ISO-BMFF timing-sample budget counters. See `timingBudgetStats`. */
@@ -692,6 +700,15 @@ function authoredGap(before: FrameMeta, after: FrameMeta): boolean {
   return b.decodeTime > a.decodeTime + BigInt(a.durationTicks)
 }
 
+/**
+ * Serial-number order on the uint32 SS_ID (RFC 1982 style): `a` follows `b`
+ * within half the space, so a 2^32 wrap does not read a post-wrap block as
+ * below a pre-wrap RAP.
+ */
+function ssIdAfter(a: number, b: number): boolean {
+  return ((a - b) | 0) > 0
+}
+
 interface GatedFrame extends PendingFrame {
   /** performance.now() at push; measures the hold against the gate's limit. */
   arrivedAtMs: number
@@ -704,6 +721,8 @@ interface GatedStream {
   last: PendingFrame | null
   lastSbn: number | undefined
   discontinuity: boolean
+  /** Latest (serial order) SS_ID of a complete RAP that entered the gate since the last reset. */
+  rapSsId: number | undefined
 }
 
 /**
@@ -797,11 +816,17 @@ class FecReleaseSequencer {
       stream.last = null
       stream.lastSbn = undefined
       stream.discontinuity = false
+      stream.rapSsId = undefined
     }
     if (stream.last !== null && compareFrameOrder(frame, stream.last) <= 0) {
       this.#recordStat('droppedStale')
       return
     }
+    const ssId = meta.fecSbn
+    if (meta.trackType === 'video' && ssId !== undefined && this.#gate.isRap?.(data, meta) === true) {
+      if (stream.rapSsId === undefined || ssIdAfter(ssId, stream.rapSsId)) stream.rapSsId = ssId
+      this.#gate.onRap?.(stream.packetId, stream.catalogTrackName, ssId)
+    }
     if (stream.last === null) {
       // The first release establishes decoder sync: video must start on a
       // RAP; earlier deltas are undecodable and are dropped.
@@ -841,6 +866,23 @@ class FecReleaseSequencer {
     return earliest
   }
 
+  /**
+   * Whether a complete RAP above SS_ID `ssId` entered the gate of a stream of
+   * `packetId` (draft-ramadan-moq-fec 11.4.2: repair of a block below it is
+   * moot). Its SS_ID is the one its frame completed in; a frame's packets
+   * hold consecutive SS_IDs in authored order, so a complete RAP with a
+   * packet above `ssId` has every packet of it at or above the first SS_ID
+   * any loss at or below `ssId` could have taken.
+   */
+  rapAbove(packetId: number, catalogTrackName: string | undefined, ssId: number): boolean {
+    for (const stream of this.#streams.values()) {
+      if (stream.packetId !== packetId) continue
+      if (catalogTrackName !== undefined && stream.catalogTrackName !== catalogTrackName) continue
+      if (stream.rapSsId !== undefined && ssIdAfter(stream.rapSsId, ssId)) return true
+    }
+    return false
+  }
+
   /** Re-evaluate held gaps after FEC state changed. */
   poke(streamKey?: string): void {
     if (streamKey !== undefined) {
@@ -946,6 +988,7 @@ class FecReleaseSequencer {
         last: null,
         lastSbn: undefined,
         discontinuity: false,
+        rapSsId: undefined,
       }
       this.#streams.set(streamKey, stream)
     }
@@ -1346,6 +1389,11 @@ export class MmtpContainerParser {
     return this.#fecSequencer?.earliestHeldArrivalMs(packetId, catalogTrackName)
   }
 
+  /** See FecReleaseSequencer.rapAbove; false when no stream is FEC-gated. */
+  fecReleaseRapAbove(packetId: number, catalogTrackName: string | undefined, ssId: number): boolean {
+    return this.#fecSequencer?.rapAbove(packetId, catalogTrackName, ssId) ?? false
+  }
+
   /** Re-evaluate held gaps after FEC block state changed. */
   pokeFecRelease(packetId?: number, catalogTrackName?: string): void {
     if (!this.#fecSequencer) return

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)