@blockcast/mmt-container 0.5.0 → 1.0.0-main.3cb7359ea316

package/src/delta-fallback-config.ts

@@ -3,70 +3,83 @@
  * {@link MediaRouter.configureDelta} (BLO-45475).
  *
  * Generic client policy selects WHICH group to admit (roles, groups, endpoint
- * availability); this module owns the MMTP/FEC half of that decision — the
- * shared repair pointer and the delta block geometry — so no player re-states
+ * availability); this module owns the MMTP/FEC half of that decision — each
+ * track's repair track and the delta block geometry — so no player re-states
  * the catalog FEC schema. It validates and never defaults: a group whose
  * required metadata is absent or contradictory throws, and the caller decides
  * that such a group invalidates the catalog rather than being skipped.
+ *
+ * FEC comes only from `resolveFecBindings` (BLO-50171), the validator's
+ * per-instance result: base and delta each bind their own instance and their
+ * own repair track (draft-ramadan-moq-fec-catalog-00 5 rule 2 forbids one
+ * Track Name in two `repairTrack` members, so a shared repair track is no FEC
+ * on either). The Phase-14 extension keys `deltaFailWindowBlocks` and
+ * `deltaProbeIntervalMs` are read from the bound instance objects; the
+ * validator ignores them as unrecognized instance keys (catalog-00 3.4).
  */
 
+import { resolveFecBindings, type FecSourceBinding } from '@blockcast/mmt-base'
 import { assertDeltaFallbackConfig, type DeltaFallbackConfig } from './media-router.js'
 
-/** The catalog fields this mapping reads from one base or delta track. */
-export interface DeltaFallbackTrack {
-  name: string
-  framerate?: number
-  fec?: {
-    repairTrack?: string
-    sourceSymbols?: number
-    repairSymbols?: number
-    interleaveDepthMs?: number
-    deltaFailWindowBlocks?: number
-    deltaProbeIntervalMs?: number
-  }
-}
-
 export interface ResolvedDeltaFallback {
-  /** The repair track both base and delta name; required at the endpoint. */
-  repairTrackName: string
+  /** The base track's layer-0 repair track. */
+  baseRepairTrackName: string
+  /** The delta track's layer-0 repair track. */
+  deltaRepairTrackName: string
   config: DeltaFallbackConfig
 }
 
+type Obj = Record<string, unknown>
+const recordOf = (v: unknown): Obj | undefined =>
+  typeof v === 'object' && v !== null && !Array.isArray(v) ? (v as Obj) : undefined
+
+/** RFC 6901 lookup; the binding pointers are the validator's own. */
+function at(root: unknown, pointer: string): Obj | undefined {
+  let cur: unknown = root
+  for (const raw of pointer.split('/').slice(1)) {
+    const key = raw.replace(/~1/g, '/').replace(/~0/g, '~')
+    cur = Array.isArray(cur) ? cur[Number(key)] : recordOf(cur)?.[key]
+  }
+  return recordOf(cur)
+}
+
 /**
- * Resolve one switching group. Throws when either track omits
- * `fec.repairTrack`, when the two pointers differ, when the base framerate is
- * not positive, or when the delta omits `fec.sourceSymbols`/`repairSymbols`.
- * Fallback-window, probe and interleave fields are read from the base first
- * (where the catalog places them), then the delta. The assembled config is then
- * held to {@link assertDeltaFallbackConfig}, the same check configureDelta
- * runs, so a group this resolves is a group configureDelta accepts — including
- * the requirement that a probe interval or an interleave depth be present.
+ * Resolve one switching group of `catalog` (either dialect). Throws when
+ * either track has no `ok` FEC binding (the message carries the validator's
+ * code and path), when the base framerate is not positive, or when the
+ * assembled config fails {@link assertDeltaFallbackConfig}, the same check
+ * configureDelta runs. Fallback-window and probe keys are read from the base
+ * instance first, then the delta's; the interleave depth likewise.
  */
-export function resolveDeltaFallback(base: DeltaFallbackTrack, delta: DeltaFallbackTrack): ResolvedDeltaFallback {
-  const repair = base.fec?.repairTrack
-  if (!repair) throw new Error(`[delta-fallback] base track "${base.name}" missing fec.repairTrack`)
-  const deltaFec = delta.fec
-  if (!deltaFec?.repairTrack) throw new Error(`[delta-fallback] delta track "${delta.name}" missing fec.repairTrack`)
-  if (deltaFec.repairTrack !== repair)
-    throw new Error(
-      `[delta-fallback] inconsistent repair tracks: ${base.name} references "${repair}" but ${delta.name} references "${deltaFec.repairTrack}"`
-    )
-  if (!(typeof base.framerate === 'number' && Number.isFinite(base.framerate) && base.framerate > 0))
-    throw new Error(`[delta-fallback] base track "${base.name}" missing positive framerate`)
-  if (!(isPositive(deltaFec.sourceSymbols) && isPositive(deltaFec.repairSymbols)))
-    throw new Error(`[delta-fallback] delta track "${delta.name}" missing positive fec.sourceSymbols/repairSymbols`)
+export function resolveDeltaFallback(catalog: unknown, baseName: string, deltaName: string): ResolvedDeltaFallback {
+  const bindings = resolveFecBindings(catalog)
+  const bound = (name: string, role: string) => {
+    const b = bindings.get(name)
+    if (!b) throw new Error(`[delta-fallback] ${role} track "${name}" declares no fec`)
+    if (b.status !== 'ok')
+      throw new Error(`[delta-fallback] ${role} track "${name}" has no FEC: ${b.reason.code} at ${b.reason.path}`)
+    const track = at(catalog, b.pointer) ?? {}
+    const instance = (Array.isArray(track['fec']) ? track['fec'] : [])
+      .map(recordOf)
+      .find((o) => o && (o['instanceId'] ?? 0) === b.base.instanceId) ?? {}
+    return { b, track, instance }
+  }
+  const base = bound(baseName, 'base')
+  const delta = bound(deltaName, 'delta')
+  const framerate = base.track['framerate']
+  if (!(typeof framerate === 'number' && Number.isFinite(framerate) && framerate > 0))
+    throw new Error(`[delta-fallback] base track "${baseName}" missing positive framerate`)
+  const key = (k: string) => (base.instance[k] ?? delta.instance[k]) as number | undefined
   const config: DeltaFallbackConfig = {
-    framerate: base.framerate,
-    sourceSymbols: deltaFec.sourceSymbols,
-    repairSymbols: deltaFec.repairSymbols,
-    deltaFailWindowBlocks: base.fec?.deltaFailWindowBlocks ?? deltaFec.deltaFailWindowBlocks,
-    deltaProbeIntervalMs: base.fec?.deltaProbeIntervalMs ?? deltaFec.deltaProbeIntervalMs,
-    interleaveDepthMs: base.fec?.interleaveDepthMs ?? deltaFec.interleaveDepthMs,
+    framerate,
+    sourceSymbols: delta.b.base.sourceSymbols,
+    repairSymbols: delta.b.base.repairSymbols,
+    deltaFailWindowBlocks: key('deltaFailWindowBlocks'),
+    deltaProbeIntervalMs: key('deltaProbeIntervalMs'),
+    interleaveDepthMs: base.b.base.interleaveDepthMs ?? delta.b.base.interleaveDepthMs,
   }
-  assertDeltaFallbackConfig(config, `[delta-fallback] group ${base.name}/${delta.name}`)
-  return { repairTrackName: repair, config }
+  assertDeltaFallbackConfig(config, `[delta-fallback] group ${baseName}/${deltaName}`)
+  return { baseRepairTrackName: repairOf(base.b), deltaRepairTrackName: repairOf(delta.b), config }
 }
 
-function isPositive(value: unknown): value is number {
-  return typeof value === 'number' && Number.isFinite(value) && value > 0
-}
+const repairOf = (b: Extract<FecSourceBinding, { status: 'ok' }>) => b.layers[0]!.repairTrackName

package/src/fec-state.ts

@@ -13,15 +13,7 @@
 // timers or elapsed time. The rules live here so the three players cannot
 // disagree about precedence.
 
-import {
-  catalogFecDeclaresUnconfigurableInstance,
-  fecAlgorithmUnimplemented,
-  isFecBlockProfile,
-  isoBlockSpanUsable,
-} from '@blockcast/mmt-base'
-
-/** The optional elapsed-span rule lives in mmt-base beside the other catalog FEC rules. */
-export { isoBlockSpanUsable }
+import { resolveFecBindings } from '@blockcast/mmt-base'
 
 /** Smallest positive catalog elapsed span; zero/absence means no elapsed deadline. */
 export const MIN_INTERLEAVE_DEPTH_MS = 1
@@ -100,61 +92,14 @@ function recordOf(value: unknown): Record<string, unknown> | undefined {
     : undefined
 }
 
-function isPositiveSafeInteger(value: unknown): boolean {
-  return typeof value === 'number' && Number.isSafeInteger(value) && value > 0
-}
-
 /**
- * Whether one catalog `fec` block (a hang rendition's `fec` or an MSF/CMSF
- * track's `fec`) declares an FEC instance a receiver can configure: source
- * symbols per block (K) and a symbol size (T) are both positive integers, the
- * algorithm is neither `none` nor a token this receiver does not implement
- * (`fecAlgorithmUnimplemented`, draft-ramadan-moq-fec-01 4), `blockProfile` names the implemented profile
- * `iso-ssbg1-v1` (BLO-35597), and the block carries that profile's usable
- * span field (`isoBlockSpanUsable`); zero/absence still permits in-band FEC. Total: it never throws, and answers false for
- * any other value.
- *
- * `resolveCatalogTrackFec` reads this predicate, so the players' parameters and
- * this state never disagree. Of the blocks this rejects, it returns no FEC
- * geometry only for `algorithm: "none"`. One with any other algorithm is a
- * malformed catalog (`FecCatalogConfig` marks both fields REQUIRED; the MSF
- * schema and `validateCmsfMmtpCatalog` enforce them on `tracks[]`, but the
- * hang dialect's `renditions` schema is permissive, so this is where a hang
- * block fails closed), and `resolveCatalogTrackFec` throws a `RepairContractError` for
- * it (`track_fec` unless another repair-contract violation fires first),
- * whether or not the source has repair layers, rather than silently dropping
- * the track's repair subscription.
- *
- * The block profile is part of this predicate because the profile selects the
- * block math and is never defaulted: draft-ramadan-moq-fec §5.1 defines one,
- * `iso-ssbg1-v1`, and a receiver MUST NOT apply FEC under any other token. The
- * retired `k-padded-v1` is simply not a known profile. `resolveCatalogTrackFec`
- * and `MulticastManager.configureMultiTrack` resolve such a track to no FEC
- * with a typed `TrackFecUnavailable` reason (`catalogFecUnavailable`: code
- * `track_fec_block_profile_unimplemented` for an unimplemented token,
- * `track_fec_block_profile` for an absent one), scoped to that track, so their
- * parameters and this state still agree. The CMSF conformance validator
- * (`validateCmsfMmtpCatalog`) rejects the catalog with the same code. An
- * `iso-ssbg1-v1` instance with an invalid span is likewise unavailable for its
- * track alone. Zero or absence supplies no elapsed deadline and uses bounded
- * receiver-local state while decoding in-band FEC.
- *
- * The repair-contract resolvers (`resolveRepairLayers`) gate a `depends` target
- * on `algorithm` alone and never read a source's `symbolSize`. They check its
- * `sourceSymbols` for the RaptorQ K bound, and require a positive integer
- * `sourceSymbols` and `repairSymbols` only when the source has repair layers or
- * an overlay beyond layer 0.
+ * Whether the catalog gives the named source track FEC this receiver can run:
+ * its base instance is `ok` (`resolveFecBindings`, draft-ramadan-moq-fec-catalog-00).
+ * `resolveCatalogTrackFec` reads the same binding, so the players' parameters
+ * and this state never disagree. Total: never throws.
  */
-export function catalogDeclaresFec(fec: unknown): boolean {
-  const block = recordOf(fec)
-  if (block === undefined || block['algorithm'] === 'none' || fecAlgorithmUnimplemented(block['algorithm'])) return false
-  return (
-    isPositiveSafeInteger(block['sourceSymbols']) &&
-    isPositiveSafeInteger(block['symbolSize']) &&
-    isFecBlockProfile(block['blockProfile']) &&
-    isoBlockSpanUsable(block) &&
-    !catalogFecDeclaresUnconfigurableInstance(block)
-  )
+export function catalogDeclaresFec(catalog: unknown, track: string): boolean {
+  return resolveFecBindings(catalog).get(track)?.status === 'ok'
 }
 
 function requireBoolean(value: unknown, field: string): boolean {

package/src/index.ts

@@ -119,10 +119,8 @@ export {
 // CARP Catalog Extensions (draft-law-ramadan-moq-carp-reliability §3-4)
 // + Track Timing (draft-ramadan-moq-mmt-01 §4.4.2)
 export {
-  type FecAlgorithm,
   type FecCatalogConfig,
-  isFecCatalogConfig,
-  isFecCatalogGeometry,
+  type FecInstanceConfig,
   type MulticastProtocol,
   type MulticastTrack,
   type MulticastTrackObject,
@@ -429,7 +427,6 @@ export {
 } from './media-router.js'
 export {
   resolveDeltaFallback,
-  type DeltaFallbackTrack,
   type ResolvedDeltaFallback,
 } from './delta-fallback-config.js'
 
@@ -543,13 +540,7 @@ export {
 	type KeyframeCadenceCatalog,
 	type TrackFecParams,
 	type TrackFecUnavailable,
-	catalogFecUnavailable,
-	catalogFecAvailable,
-	catalogFecDeclaresUnconfigurableInstance,
-	fecAlgorithmUnimplemented,
-	locateCatalogFecSource,
-	type CatalogFecRole,
-	type CatalogFecSource,
+	catalogTrackFecUnavailable,
 	catalogGroupDurationMs,
 	catalogKeyframeCadenceMs,
 	catalogFecMediaUnitsPerSecond,
@@ -559,38 +550,27 @@ export {
 	FEC_BLOCK_PROFILES,
 	isFecBlockProfile,
 	parseFecBlockProfile,
-	readFecBlockProfile,
 	type FecBlockProfile,
 	resolveRepairLayers,
 	catalogRepairTarget,
-	assembleRepairLayers,
-	assertRepairTrackReachable,
-	repairReachability,
-	type AssembleRepairLayersOptions,
-	type RepairReachability,
-	dependsTarget,
-	describeRepairTrack,
-	rejectRepairFieldsOnMediaTrack,
-	rejectRepairTrackGeometry,
-	REPAIR_TRACK_GEOMETRY_KEYS,
-	REPAIR_TRACK_ONLY_KEYS,
-	validateRepairTrackFields,
-	RepairContractError,
 	DEFAULT_REPAIR_PRIORITY,
 	MAX_ENCODING_SYMBOL_ID,
 	MAX_RAPTORQ_SOURCE_SYMBOLS,
 	MAX_REPAIR_SYMBOLS,
 	REPAIR_PRIORITY_MAX,
 	REPAIR_PRIORITY_MIN,
-	type RepairContractCode,
-	type RepairContractFail,
 	type RepairLayerCatalog,
 	type RepairLayerParams,
 	type RepairLayersResolution,
 	type RepairOverlayParams,
-	type RepairRenditionCatalog,
-	type RepairSourceGeometry,
-	type RepairTrackDescriptor,
+	// FEC catalog binding, draft-ramadan-moq-fec-catalog-00 array shape (BLO-50171).
+	validateFecCatalog,
+	type FecCatalogCode,
+	type FecCatalogInstance,
+	type FecCatalogIssue,
+	type FecCatalogOutcome,
+	type FecCatalogReceiver,
+	type FecCatalogReport,
 } from "./catalog-fec-params.js";
 
 // Typed FEC state (active with counters, or inactive with a reason) shared by

package/src/mmtp-fec-session.ts

@@ -74,10 +74,11 @@ export type MmtpFecSessionDecoderConstructor = new (
   algorithm?: string,
 ) => MmtpFecSessionDecoder
 
-/** The catalog `fec` fields the session reads. */
+/** The fields of one `ok` draft-ramadan-moq-fec-catalog-00 instance object
+ *  the session reads (the source track's base instance). */
 export interface MmtpFecSessionCatalogFec {
-  /** `raptorq` (the default when absent) or `reed-solomon`. */
-  algorithm?: unknown
+  /** `raptorq` or `reed-solomon`; required. */
+  scheme?: unknown
   blockProfile?: unknown
   sourceSymbols?: unknown
   /** P_0: layer 0's repair symbols per block, the fec-01 6.3.9 total B_0. */
@@ -235,20 +236,20 @@ export class MmtpFecSession {
   }
 
   /**
-   * @throws when the catalog block lacks or misstates a field the session
-   *   needs: the block profile, K, P_0 (`repairSymbols`), T, `interleaveDepthMs` or
-   *   `reorderToleranceMs`. None is defaulted.
+   * @throws when the instance lacks or misstates a field the session needs:
+   *   the scheme, the block profile, K, P_0 (`repairSymbols`), T,
+   *   `interleaveDepthMs` or `reorderToleranceMs`. None is defaulted.
    */
   constructor(config: MmtpFecSessionConfig) {
     const fec = config?.fec
     if (!fec || typeof fec !== 'object') {
-      throw new Error('MmtpFecSession: the catalog fec block is required')
+      throw new Error('MmtpFecSession: the catalog fec instance is required')
     }
     this.blockProfile = parseFecBlockProfile(fec.blockProfile, 'fec.blockProfile')
-    if (fec.algorithm !== undefined && fec.algorithm !== 'raptorq' && fec.algorithm !== 'reed-solomon') {
-      throw new Error(`MmtpFecSession: fec.algorithm ${JSON.stringify(fec.algorithm)} is not implemented`)
+    if (fec.scheme !== 'raptorq' && fec.scheme !== 'reed-solomon') {
+      throw new Error(`MmtpFecSession: fec.scheme ${JSON.stringify(fec.scheme)} is not implemented`)
     }
-    this.algorithm = fec.algorithm === 'reed-solomon' ? 'reed-solomon' : 'raptorq'
+    this.algorithm = fec.scheme
     this.sourceSymbols = requirePositiveInteger(fec.sourceSymbols, 'fec.sourceSymbols')
     this.repairSymbols = requirePositiveInteger(fec.repairSymbols, 'fec.repairSymbols')
     this.symbolSize = requirePositiveInteger(fec.symbolSize, 'fec.symbolSize')

package/src/mmtp-router.ts

@@ -989,9 +989,6 @@ export class MmtpRouter {
   #onVideoFrame: FrameCallback | null = null;
   #onAudioFrame: FrameCallback | null = null;
 
-  // Init segment (ftyp+moov) from MMTP MPU metadata — needed for MSE SourceBuffer
-  #onInitSegment: ((data: Uint8Array) => void) | null = null;
-
   // Per-track init segment callbacks keyed by packetId
   #trackInitCallbacks = new Map<number, (data: Uint8Array) => void>();
   // Track whether init has been delivered per physical stream — prevent duplicates
@@ -1418,11 +1415,10 @@ export class MmtpRouter {
   }
 
   /**
-   * Init segments delivered for a packetId with no `onTrackInit` handler
-   * since construction, whether the deprecated aggregate `onInitSegment`
-   * callback then received them or nothing did. A supported deployment reads
-   * 0 here; a non-zero value is the evidence that blocks removing the
-   * aggregate callback (MOQT-01, BLO-21181).
+   * Init segments rejected since construction because their packetId had no
+   * `onTrackInit` handler. A rejected init is delivered nowhere; there is no
+   * aggregate fallback (removed in 1.0.0, MOQT-01 / BLO-21181). A supported
+   * deployment reads 0 here.
    */
   get unmappedInitDeliveryCount(): number {
     return this.#unmappedInitDeliveries;
@@ -1640,21 +1636,10 @@ export class MmtpRouter {
     this.#trackPacketCallbacks.set(packetId, cb);
   }
 
-  /**
-   * Register an init segment callback (ftyp+moov from MMTP MPU metadata).
-   * Receives an init only for a packetId with no `onTrackInit` handler.
-   *
-   * @deprecated Use onTrackInit(packetId, cb). Still delivered as a fallback;
-   * removed in the 1.0.0 major, no earlier than one minor release after this
-   * deprecation reaches the `latest` dist-tag (BLO-21181). Count fallback
-   * deliveries with `unmappedInitDeliveryCount`.
-   */
-  onInitSegment(cb: (data: Uint8Array) => void): void {
-    this.#onInitSegment = cb;
-  }
-
   /** Register an init segment callback for a specific MMTP packetId.
-   *  Called when FT=0 init arrives via direct source or FEC recovery. */
+   *  Called when FT=0 init arrives via direct source or FEC recovery. An init
+   *  for a packetId with no handler is rejected and counted by
+   *  `unmappedInitDeliveryCount`. */
   onTrackInit(packetId: number, cb: (data: Uint8Array) => void): void {
     this.#trackInitCallbacks.set(packetId, cb);
   }
@@ -3404,16 +3389,16 @@ export class MmtpRouter {
     if (this.#trackInitDelivered.has(streamKey)) return;
     if (data.byteLength <= 8) return;
     this.#trackInitDelivered.add(streamKey);
+    const track = `packetId=${packetId}${catalogTrackName === undefined ? "" : ` track=${catalogTrackName}`}`;
     const cb = this.#trackInitCallbacks.get(packetId);
-    if (cb) {
-      cb(data);
-    } else {
+    if (!cb) {
+      // No aggregate fallback (MOQT-01): an init nobody mapped is rejected.
       this.#unmappedInitDeliveries++;
-      this.#onInitSegment?.(data);
+      console.log(`[MmtpRouter] Init rejected for ${track}: no onTrackInit handler`);
+      return;
     }
-    console.log(
-      `[MmtpRouter] Init delivered for packetId=${packetId}${catalogTrackName === undefined ? "" : ` track=${catalogTrackName}`} (${data.byteLength}B)`,
-    );
+    cb(data);
+    console.log(`[MmtpRouter] Init delivered for ${track} (${data.byteLength}B)`);
   }
 
   /**