@blockcast/mmt-container 0.1.0 → 0.3.0

package/src/catalog-fec-params.ts

@@ -0,0 +1,729 @@
+// Catalog → per-track FEC geometry resolution.
+//
+// Moved from hang-mmt-fec's js/watch/src/track-fec-params.ts so every player
+// (moq-lib/hang, moqtail, shaka MSF) resolves catalog FEC semantics through
+// one shared implementation — players keep only wiring, not MMT/catalog
+// interpretation. Structural track shape ({ name, type }) keeps this module
+// player-agnostic.
+
+import {
+	FEC_BLOCK_PROFILES,
+	isFecBlockProfile,
+	parseFecBlockProfile,
+	type FecBlockProfile,
+} from "@blockcast/mmt-base";
+import { catalogFecInterleaveMs, type FecInterleaveCatalog } from "@blockcast/mmt-fec";
+import { resolveGroupDurationMs } from "./carp-catalog.js";
+import { MIN_INTERLEAVE_DEPTH_MS, catalogDeclaresFec, isoBlockSpanUsable } from "./fec-state.js";
+import {
+	assembleRepairLayers,
+	assertRepairTrackReachable,
+	describeRepairTrack,
+	rejectRepairFieldsOnMediaTrack,
+	rejectRepairTrackGeometry,
+	repairReachability,
+	dependsTarget,
+	readFecBlockProfile,
+	RepairContractError,
+	type RepairLayerParams,
+	type RepairLayersResolution,
+	type RepairOverlayParams,
+	type RepairSourceGeometry,
+	type RepairTrackDescriptor,
+	throwRepairContractError,
+	validateRepairTrackFields,
+} from "./repair-layers.js";
+import type { RepairTarget } from "./repair-fetch.js";
+
+export { catalogFecInterleaveMs, type FecInterleaveCatalog };
+export { FEC_BLOCK_PROFILES, isFecBlockProfile, parseFecBlockProfile, type FecBlockProfile };
+export {
+	assembleRepairLayers,
+	assertRepairTrackReachable,
+	repairReachability,
+	type AssembleRepairLayersOptions,
+	type RepairReachability,
+	dependsTarget,
+	describeRepairTrack,
+	readFecBlockProfile,
+	rejectRepairFieldsOnMediaTrack,
+	rejectRepairTrackGeometry,
+	REPAIR_TRACK_GEOMETRY_KEYS,
+	REPAIR_TRACK_ONLY_KEYS,
+	validateRepairTrackFields,
+	DEFAULT_REPAIR_PRIORITY,
+	MAX_ENCODING_SYMBOL_ID,
+	MAX_RAPTORQ_SOURCE_SYMBOLS,
+	MAX_REPAIR_SYMBOLS,
+	REPAIR_PRIORITY_MAX,
+	REPAIR_PRIORITY_MIN,
+	RepairContractError,
+	type RepairContractCode,
+	type RepairContractFail,
+	type RepairLayerParams,
+	type RepairLayersResolution,
+	type RepairOverlayParams,
+	type RepairSourceGeometry,
+	type RepairTrackDescriptor,
+} from "./repair-layers.js";
+
+/**
+ * Minimal structural shape of a resolved endpoint track. Callers may carry
+ * extra fields (e.g. hang's ResolvedEndpointTrack adds `pid`) — the resolver
+ * only reads `name` and `type`.
+ */
+export type CatalogTrackRef = {
+	name: string;
+	type: "video" | "audio" | (string & {});
+};
+
+type FecCatalog = FecInterleaveCatalog & {
+	algorithm?: unknown;
+	/** FEC block profile token (BLO-35597): required on a declared FEC
+	 *  instance, read through `readFecBlockProfile`. */
+	blockProfile?: unknown;
+	sourceSymbols?: number;
+	repairSymbols?: number;
+	symbolSize?: number;
+	/** Signaled jitter/reorder allowance in ms (added to the block span). */
+	reorderToleranceMs?: number;
+	/** Layer 0 repair track. Further layers and overlays describe themselves
+	 *  (draft-ramadan-moq-fec §6.3): MSF `tracks[]` entries with
+	 *  `packaging: "fec-repair"`, or hang `repair.renditions` entries, that
+	 *  `depend` on this rendition. */
+	repairTrack?: string;
+};
+
+/** One self-describing repair rendition of the hang catalog's `repair` block
+ *  (draft-ramadan-moq-fec §6.3). Mirrors the MSF fec-repair track fields. */
+export type RepairRenditionCatalog = {
+	depends?: unknown;
+	repairLayer?: unknown;
+	repairSymbols?: unknown;
+	priority?: unknown;
+	scope?: unknown;
+	sourceSymbols?: unknown;
+};
+
+/** The container fields the FEC and group-duration readers consult. */
+type ContainerCatalog = { kind?: unknown; timescale?: unknown };
+
+type RenditionCatalog = KeyframeCadenceCatalog & {
+	container?: ContainerCatalog;
+	fec?: FecCatalog;
+	framerate?: unknown;
+	sampleRate?: unknown;
+	samplerate?: unknown;
+};
+
+type CatalogWithRenditions = {
+	video?: { renditions?: Record<string, RenditionCatalog> };
+	audio?: { renditions?: Record<string, RenditionCatalog> };
+	/** hang-native repair renditions: every repair track beyond layer 0. */
+	repair?: { renditions?: Record<string, RepairRenditionCatalog> };
+};
+
+/** An MSF/CMSF catalog: `tracks[]` entries, each self-describing. */
+type CatalogWithTracks = {
+	tracks?: unknown;
+};
+
+/** Either catalog dialect `resolveRepairLayers` reads. */
+export type RepairLayerCatalog = CatalogWithRenditions | CatalogWithTracks;
+
+export type GroupDurationCatalog = {
+	groupDurationTicks?: number;
+	groupDurationMs?: number;
+	timescale?: number;
+};
+
+/** Rendition fields the group-duration reader consumes. */
+export type GroupDurationRendition = GroupDurationCatalog & {
+	container?: ContainerCatalog;
+};
+
+/**
+ * Largest tick count per Hz of timescale whose millisecond duration
+ * `resolveGroupDurationMs` still accepts: `(ticks / timescale) * 1000` must not
+ * exceed `Number.MAX_SAFE_INTEGER`, so `ticks <= timescale * (MAX_SAFE / 1000)`
+ * (Hz times seconds is ticks).
+ */
+const MAX_SAFE_TICKS_PER_HZ = Number.MAX_SAFE_INTEGER / 1000;
+
+/** A positive safe-integer Hz timescale, or undefined. */
+function timescaleHz(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+
+/**
+ * A rendition's publisher group duration in ms, or undefined when the catalog
+ * carries none.
+ *
+ * `groupDurationTicks` over a timescale wins when both are present, through
+ * `resolveGroupDurationMs` (draft-ramadan-moq-mmt-00 §4.4.4). The timescale is
+ * the MMTP container's when the rendition declares one, else the rendition's
+ * own `timescale`. Only the ticks are forwarded: a catalog `groupDurationMs`
+ * is often a rounded fraction (21.33 for 1024/48000), which the ticks path
+ * never reads but `resolveGroupDurationMs` would reject as a non-integral ms.
+ * Ticks with no usable timescale, and ticks that `resolveGroupDurationMs`
+ * would reject, fall back to `groupDurationMs` rather than guessing a clock.
+ * That rejection is on the product, not the operand: the count must be a safe
+ * integer and `(ticks / timescale) * 1000` must stay within
+ * `Number.MAX_SAFE_INTEGER`, which a safe-integer count can still exceed when
+ * `timescale < 1000`, so the guard below bounds the count by
+ * `timescale * (Number.MAX_SAFE_INTEGER / 1000)` and the reader never throws.
+ * The production catalog signals both fields on every rendition and no
+ * rendition-level timescale, so the `groupDurationMs` fallback is the path it
+ * takes.
+ */
+export function catalogGroupDurationMs(rendition: GroupDurationRendition | undefined): number | undefined {
+	if (!rendition) return undefined;
+	const ticks = numericField(rendition.groupDurationTicks);
+	const ms = numericField(rendition.groupDurationMs);
+	const timescale =
+		timescaleHz(rendition.container?.kind === "mmtp" ? rendition.container.timescale : undefined) ??
+		timescaleHz(rendition.timescale);
+	if (
+		ticks !== undefined &&
+		timescale !== undefined &&
+		Number.isSafeInteger(ticks) &&
+		ticks <= timescale * MAX_SAFE_TICKS_PER_HZ
+	) {
+		return resolveGroupDurationMs({ groupDurationTicks: ticks }, timescale);
+	}
+	return ms;
+}
+
+/**
+ * The group duration of the catalog rendition an endpoint track was resolved
+ * from, by type and name (the same lookup `resolveCatalogTrackFec` performs
+ * for FEC geometry). Undefined when the rendition is missing or carries no
+ * group duration, so a caller that needs one can fail closed by name.
+ */
+export function resolveCatalogTrackGroupDurationMs(
+	catalog: CatalogWithRenditions | undefined,
+	track: CatalogTrackRef,
+): number | undefined {
+	const renditions = track.type === "audio" ? catalog?.audio?.renditions : catalog?.video?.renditions;
+	return catalogGroupDurationMs(renditions?.[track.name]);
+}
+
+export type KeyframeCadenceCatalog = GroupDurationCatalog & {
+	keyframeDurationTicks?: number;
+	keyframeDurationMs?: number;
+	keyframeIntervalTicks?: number;
+	keyframeIntervalMs?: number;
+	gopDurationTicks?: number;
+	gopDurationMs?: number;
+};
+
+/**
+ * Why a track's catalog `fec` block resolved to no FEC although it is not a
+ * plain no-FEC declaration (BLO-35597): it declares an FEC instance but names
+ * no `blockProfile`, or it names a token that is not a known profile
+ * (`track_fec_block_profile`), or it names `iso-ssbg1-v1` without the block
+ * span that bounds that profile's block location (`track_fec`, on
+ * `interleaveDepthMs`). The profile selects the block math and is never
+ * defaulted or inferred, and the span is never borrowed from another track, so
+ * such a track carries no FEC geometry and no repair track, and it is the only
+ * track affected: every other track of the catalog resolves as usual.
+ */
+export type TrackFecUnavailable = {
+	/** The repair-contract code a catalog validator reports for the same field. */
+	readonly code: "track_fec_block_profile" | "track_fec";
+	/** JSON path of the offending field: `blockProfile`, or `interleaveDepthMs`. */
+	readonly path: string;
+	/** What is wrong, worded as the `RepairContractError` a validator throws. */
+	readonly message: string;
+};
+
+export type TrackFecParams = {
+	fecK: number;
+	/** The catalog `fec.blockProfile` (BLO-35597, ISO/IEC 23008-1 Annex C).
+	 *  Present exactly when the track has FEC (`fecK > 0`) and absent on no
+	 *  FEC: it selects the block math (`k-padded-v1`: SS_Start = SBN*K over
+	 *  zero-padded K-symbol blocks; `iso-ssbg1-v1`: ssbg_mode1, K' =
+	 *  SSB_length, consecutive SS_IDs), so it is never defaulted. A declared
+	 *  instance that names no known profile has no FEC; `fecUnavailable` says
+	 *  why. */
+	fecBlockProfile?: FecBlockProfile;
+	/** Present exactly when the track's `fec` block names no usable
+	 *  `blockProfile`, or names `iso-ssbg1-v1` without a usable block span
+	 *  (see `TrackFecUnavailable`). The track then resolves to
+	 *  no FEC (`fecK` 0, no `fecBlockProfile`, no repair track) and this is
+	 *  the reason a caller surfaces. Absent on every other track, with FEC or
+	 *  without. */
+	fecUnavailable?: TrackFecUnavailable;
+	/** P_0: repair symbols per block on layer 0 (the track-level repairSymbols). */
+	fecRepairCount: number;
+	/** Total repair symbols per block across the BASE layers: the wire
+	 *  RSB_length on every base layer packet. Equals fecRepairCount on a
+	 *  single-layer track. A keyframe overlay is a separate FEC instance with
+	 *  its own RSB_length and is not included. */
+	fecTotalRepairCount: number;
+	fecSymbolSize: number;
+	fecInterleaveMs: number;
+	/** Catalog fec.reorderToleranceMs — signaled jitter/reorder allowance, ADDED
+	 *  to the block span to form a deadline. Deliberately `number | undefined`
+	 *  and NOT floored to 0: a declared 0 ("this path needs no slack") and an
+	 *  absent value ("the encoder never said") must stay distinguishable, or a
+	 *  consumer that wants to fail loud on absence silently reads a default
+	 *  instead — which is exactly how the magic 3.0 survived. */
+	fecReorderToleranceMs?: number;
+	repairTrackName?: string;
+	/** Every base repair layer in order, layer 0 first, with derived RS_ID
+	 *  offsets. Present whenever repairTrackName is. */
+	repairLayers?: readonly RepairLayerParams[];
+	/** Keyframe overlay instances declared for this track. Present (possibly
+	 *  empty) whenever repairLayers is. */
+	repairOverlays?: readonly RepairOverlayParams[];
+	fps?: number;
+	sampleRate?: number;
+};
+
+const NO_FEC: TrackFecParams = {
+	fecK: 0,
+	fecRepairCount: 0,
+	fecTotalRepairCount: 0,
+	fecSymbolSize: 0,
+	fecInterleaveMs: 0,
+};
+
+/**
+ * Repair symbols per block a receiver has actually joined: the sum of
+ * `repairSymbols` over the BASE layers whose repair track it joined
+ * (draft-ramadan-moq-fec 6.3). This is a symbol count, not a count of layers.
+ *
+ * A keyframe overlay is a separate FEC instance with its own K, its own
+ * RSB_length and its own RS_ID space, so it is never added here however it was
+ * joined. Counting it would overstate the base instance's P and misreport
+ * CMCD `x-bc-fec-p`.
+ *
+ * Falls back to P_0 when the track declares no layers, which is the
+ * single-layer identity rather than a default: with one layer, P_0 is the
+ * total.
+ */
+export function joinedRepairSymbolCount(
+	params: Pick<TrackFecParams, "fecRepairCount" | "repairLayers">,
+	joinedRepairTrackNames: Iterable<string>,
+): number {
+	const layers = params.repairLayers;
+	if (layers === undefined || layers.length === 0) return params.fecRepairCount;
+	const joined = new Set(joinedRepairTrackNames);
+	let total = 0;
+	for (const layer of layers) {
+		if (joined.has(layer.repairTrackName)) total += layer.repairSymbols;
+	}
+	return total;
+}
+
+function recordOf(value: unknown): Record<string, unknown> | undefined {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+}
+
+/** The MSF `tracks[]` view of a catalog, or undefined for the hang dialect. */
+function msfTracks(catalog: RepairLayerCatalog): { tracks: Record<string, unknown>[] } | undefined {
+	const raw = (catalog as CatalogWithTracks).tracks;
+	if (!Array.isArray(raw)) return undefined;
+	return { tracks: raw.map((t) => recordOf(t) ?? {}) };
+}
+
+/**
+ * Resolve every repair track of one source track: base layers with derived
+ * RS_ID offsets and keyframe overlays (draft-ramadan-moq-fec §6.3), from either
+ * catalog dialect.
+ *
+ * - MSF `tracks[]`: the source is the entry named `source`; repair tracks are
+ *   `packaging: "fec-repair"` entries. Layer 0 is the source's
+ *   `fec.repairTrack`; layers 1..n and overlays `depend` on the source.
+ * - hang: the source is a `video`/`audio` rendition; repair tracks beyond
+ *   layer 0 are `repair.renditions` entries that `depend` on it.
+ *
+ * Returns undefined when the source carries no FEC repair track and nothing
+ * depends on it. Throws `RepairContractError` (code + JSON path) on any
+ * violation, including a repair rendition whose `depends` names a rendition
+ * without FEC, so a player fails closed before joining any repair track.
+ */
+export function resolveRepairLayers(
+	catalog: RepairLayerCatalog | undefined,
+	source: string | CatalogTrackRef,
+): RepairLayersResolution | undefined {
+	if (!catalog) return undefined;
+	const sourceName = typeof source === "string" ? source : source.name;
+
+	// hang dialect first. When a catalog carries hang-native rendition blocks
+	// beside a tracks[] switching-set index (the unified ABR ladder catalog),
+	// the rendition blocks are authoritative, exactly as they are for hang's own
+	// catalog decode. A typed ref resolves only within its own role.
+	const hang = catalog as CatalogWithRenditions;
+	const roles: Array<"video" | "audio"> =
+		typeof source === "string"
+			? ["video", "audio"]
+			: source.type === "audio"
+				? ["audio"]
+				: source.type === "video"
+					? ["video"]
+					: ["video", "audio"];
+	const role = roles.find((r) => recordOf(hang[r]?.renditions?.[sourceName]) !== undefined);
+	if (role !== undefined) {
+		const renditionPath = `$.${role}.renditions[${JSON.stringify(sourceName)}]`;
+		const rendition = recordOf(hang[role]!.renditions![sourceName])!;
+		rejectRepairFieldsOnMediaTrack(renditionPath, rendition, throwRepairContractError);
+		const repairRenditions = recordOf(hang.repair?.renditions) ?? {};
+		const descriptors: RepairTrackDescriptor[] = Object.entries(repairRenditions).map(([name, entry]) => {
+			const path = `$.repair.renditions[${JSON.stringify(name)}]`;
+			const fields = recordOf(entry);
+			if (fields === undefined) {
+				throwRepairContractError("track_repair_layer", path, "a repair rendition must be an object");
+			}
+			rejectRepairTrackGeometry(path, fields, throwRepairContractError);
+			return describeRepairTrack(name, path, fields);
+		});
+		const fecOfRendition = (entry: unknown): Record<string, unknown> | undefined => {
+			const fec = recordOf(recordOf(entry)?.["fec"]);
+			return fec !== undefined && fec["algorithm"] !== "none" ? fec : undefined;
+		};
+		const mediaRenditions = [
+			...Object.values(recordOf(hang.video?.renditions) ?? {}),
+			...Object.values(recordOf(hang.audio?.renditions) ?? {}),
+		];
+		const reachability = repairReachability(mediaRenditions.map((entry) => recordOf(entry)?.["fec"]));
+		for (const d of descriptors) {
+			validateRepairTrackFields(d, throwRepairContractError);
+			assertRepairTrackReachable(d, reachability, throwRepairContractError);
+			const target = dependsTarget(d);
+			if (target === undefined) continue;
+			const targetFec =
+				fecOfRendition(hang.video?.renditions?.[target]) ?? fecOfRendition(hang.audio?.renditions?.[target]);
+			if (targetFec === undefined) {
+				throwRepairContractError(
+					"track_repair_depends",
+					`${d.path}.depends`,
+					`${JSON.stringify(target)} is not a video or audio rendition with FEC`,
+				);
+			}
+		}
+		return assembleRepairLayers(
+			geometryOf(sourceName, `${renditionPath}.fec`, recordOf(rendition["fec"])),
+			descriptors,
+			throwRepairContractError,
+		);
+	}
+
+	const msf = msfTracks(catalog);
+	const msfIndex = msf ? msf.tracks.findIndex((t) => t["name"] === sourceName) : -1;
+	if (!msf || msfIndex < 0) return undefined;
+	const track = msf.tracks[msfIndex]!;
+	const fec = recordOf(track["fec"]);
+	const packagingOf = (t: Record<string, unknown>): unknown => t["packaging"];
+	const fecOfTrack = (t: Record<string, unknown> | undefined): Record<string, unknown> | undefined => {
+		const trackFec = recordOf(t?.["fec"]);
+		return trackFec !== undefined && trackFec["algorithm"] !== "none" ? trackFec : undefined;
+	};
+	// Rule 8 on the resolver path too: a repair track carries no block geometry
+	// and a media track carries no repair-track fields. Without this a repair
+	// track with its own `fec` would count as a FEC source below and name
+	// itself as layer 0, so rule 9 would never see it.
+	const descriptors: RepairTrackDescriptor[] = [];
+	const mediaTracks: Record<string, unknown>[] = [];
+	msf.tracks.forEach((t, i) => {
+		const path = `$.tracks[${i}]`;
+		if (packagingOf(t) === "fec-repair") {
+			rejectRepairTrackGeometry(path, t, throwRepairContractError);
+			if (typeof t["name"] === "string") descriptors.push(describeRepairTrack(t["name"], path, t));
+			return;
+		}
+		rejectRepairFieldsOnMediaTrack(path, t, throwRepairContractError);
+		mediaTracks.push(t);
+	});
+	const reachability = repairReachability(mediaTracks.map((t) => t["fec"]));
+	for (const d of descriptors) {
+		validateRepairTrackFields(d, throwRepairContractError);
+		assertRepairTrackReachable(d, reachability, throwRepairContractError);
+		const target = dependsTarget(d);
+		if (target === undefined) continue;
+		const targetTrack = msf.tracks.find((t) => t["name"] === target);
+		if (targetTrack === undefined || packagingOf(targetTrack) !== "mmtp" || fecOfTrack(targetTrack) === undefined) {
+			throwRepairContractError(
+				"track_repair_depends",
+				`${d.path}.depends`,
+				`${JSON.stringify(target)} is not an mmtp track with FEC`,
+			);
+		}
+	}
+	return assembleRepairLayers(geometryOf(sourceName, `$.tracks[${msfIndex}].fec`, fec), descriptors, throwRepairContractError, {
+		layerZeroMustBeDeclared: true,
+	});
+}
+
+/** A MoQ Transport priority (0..255, lower first), or null. */
+function moqtPriority(value: unknown): number | null {
+	return Number.isSafeInteger(value) && (value as number) >= 0 && (value as number) <= 255 ? (value as number) : null;
+}
+
+/**
+ * The on-demand repair target of one source track, read from the catalog:
+ * its base layer 0 repair track and the two catalog priorities
+ * draft-ramadan-moq-fec §11.4.5 derives the FETCH's SUBSCRIBER_PRIORITY from
+ * (see `repairFetchSubscriberPriority`). This is what a player's
+ * `ResolveRepairTarget` returns once it knows which track owns the block.
+ *
+ * - `repairPriority`: layer 0's catalog `priority`, or 240 when it declares
+ *   none; that value is defined by draft-ramadan-moq-fec §10, not chosen
+ *   here (`resolveRepairLayers` applies it).
+ * - `sourcePriority`: the source track's MSF `tracks[]` entry `priority`
+ *   (MoQ Transport scale). A catalog with no MSF entry for the track (a hang-only catalog,
+ *   whose renditions carry no MoQ Transport priority) yields null, and the
+ *   keyframe repair FETCH is then sent without the parameter.
+ *
+ * Returns null when the track has no repair track.
+ *
+ * @throws RepairContractError exactly as `resolveRepairLayers` does.
+ */
+export function catalogRepairTarget(
+	catalog: RepairLayerCatalog | undefined,
+	source: string | CatalogTrackRef,
+): RepairTarget | null {
+	const repair = resolveRepairLayers(catalog, source);
+	const layerZero = repair?.baseLayers[0];
+	if (!catalog || !layerZero) return null;
+	const sourceName = typeof source === "string" ? source : source.name;
+	const msf = msfTracks(catalog);
+	const entry = msf?.tracks.find((t) => t["name"] === sourceName);
+	const sourcePriority =
+		entry === undefined ? null : moqtPriority(entry["priority"]);
+	return { repairTrack: layerZero.repairTrackName, sourcePriority, repairPriority: layerZero.priority };
+}
+
+function geometryOf(name: string, path: string, fec: Record<string, unknown> | undefined): RepairSourceGeometry {
+	return {
+		name,
+		path,
+		algorithm: fec?.["algorithm"],
+		sourceSymbols: fec?.["sourceSymbols"],
+		repairSymbols: fec?.["repairSymbols"],
+		repairTrack: fec?.["repairTrack"],
+	};
+}
+
+function numericField(value: unknown): number | undefined {
+	const n = typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN;
+	return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
+/** Like `numericField` but admits an explicit 0, and still rejects absent,
+ *  negative and non-finite input. Absence returns undefined so callers can
+ *  tell "declared none" from "never declared". */
+function nonNegativeField(value: unknown): number | undefined {
+	const n = typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN;
+	return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+
+/**
+ * The track-scoped reading of `readFecBlockProfile` (BLO-35597): the same one
+ * rule every catalog reader applies (a declared FEC instance names a known
+ * profile; a block declaring none may omit it, but a token it carries must be
+ * known), with its one failure, `track_fec_block_profile`, returned as the
+ * track's reason instead of thrown. A profile problem costs only its own
+ * track: it never aborts resolving the catalog's other tracks, and the token
+ * is still never defaulted or inferred.
+ */
+function blockProfileUnavailable(
+	value: unknown,
+	path: string,
+	declaresFecInstance: boolean,
+): TrackFecUnavailable | undefined {
+	try {
+		readFecBlockProfile(value, path, declaresFecInstance, throwRepairContractError);
+		return undefined;
+	} catch (error) {
+		if (!(error instanceof RepairContractError) || error.code !== "track_fec_block_profile") throw error;
+		return Object.freeze({ code: "track_fec_block_profile", path: error.path, message: error.message });
+	}
+}
+
+/**
+ * An `iso-ssbg1-v1` instance without a usable block span (`isoBlockSpanUsable`)
+ * has no FEC for its track alone, instead of resolving to a configuration the
+ * FEC manager refuses for every track it holds.
+ */
+function isoSpanUnavailable(fec: unknown, path: string, declaresFecInstance: boolean): TrackFecUnavailable | undefined {
+	if (!declaresFecInstance || isoBlockSpanUsable(fec)) return undefined;
+	return Object.freeze({
+		code: "track_fec",
+		path,
+		message:
+			`[repair-layers:track_fec] ${path}: iso-ssbg1-v1 requires a block span of at least ` +
+			`${MIN_INTERLEAVE_DEPTH_MS} ms, which bounds its block location`,
+	});
+}
+
+/**
+ * Per-track FEC geometry, or `NO_FEC` when the rendition declares none (no
+ * `fec`, or `algorithm: "none"`) or names no usable `blockProfile` or, under
+ * `iso-ssbg1-v1`, no usable block span; the latter two carry `fecUnavailable`.
+ *
+ * @throws RepairContractError from `resolveRepairLayers` when the rendition
+ * declares a `fec` block (any algorithm, `none` included) and the catalog's
+ * repair contract is malformed, and `track_fec` when its `fec` declares an FEC
+ * instance whose `sourceSymbols` or `symbolSize` is not a positive integer;
+ * see `resolveCatalogTrackFec`. An absent or unknown `blockProfile`, or an
+ * `iso-ssbg1-v1` span that is absent or below `MIN_INTERLEAVE_DEPTH_MS`, never
+ * throws: it is this track's `fecUnavailable`.
+ */
+function fecParams(
+	catalog: CatalogWithRenditions | undefined,
+	track: CatalogTrackRef | undefined,
+	rendition: RenditionCatalog | undefined,
+	fps?: number,
+	sampleRate?: number,
+): TrackFecParams {
+	const mediaRate = sampleRate === undefined ? { fps } : { fps, sampleRate };
+	const fec = rendition?.fec;
+	// Every caller passes a track with its rendition.
+	if (!fec || !track) return { ...NO_FEC, ...mediaRate };
+	// The repair contract is enforced for every declared `fec` block, including
+	// one that declares no FEC instance (a repair layer may not depend on it).
+	const repair = resolveRepairLayers(catalog, track);
+	const fecPath = `$.${track.type}.renditions[${JSON.stringify(track.name)}].fec`;
+	// One predicate for "this track has FEC", shared with resolveFecState: K
+	// and T are positive integers, the algorithm is not `none`, and the block
+	// profile is known.
+	if (!catalogDeclaresFec(fec)) {
+		const declaresFecInstance = fec.algorithm !== "none";
+		const kValid = Number.isSafeInteger(fec.sourceSymbols) && (fec.sourceSymbols ?? 0) > 0;
+		const tValid = Number.isSafeInteger(fec.symbolSize) && (fec.symbolSize ?? 0) > 0;
+		if (declaresFecInstance && !(kValid && tValid)) {
+			// Any algorithm but `none` declares an FEC instance, so geometry a
+			// decoder cannot configure is a malformed catalog, not "no FEC".
+			// Returning NO_FEC would silently drop the track's repair
+			// subscription (repairTrackName, repairLayers, repairOverlays).
+			throwRepairContractError(
+				"track_fec",
+				`${fecPath}.${kValid ? "symbolSize" : "sourceSymbols"}`,
+				"must be a positive integer",
+			);
+		}
+		// What remains is `algorithm: "none"` (which carries no profile; a token
+		// it does carry must still be known) or a declared instance naming no
+		// known profile. Neither has FEC; an unusable profile says why, for this
+		// track alone.
+		const fecUnavailable =
+			blockProfileUnavailable(fec.blockProfile, `${fecPath}.blockProfile`, declaresFecInstance) ??
+			isoSpanUnavailable(fec, `${fecPath}.interleaveDepthMs`, declaresFecInstance);
+		return fecUnavailable === undefined ? { ...NO_FEC, ...mediaRate } : { ...NO_FEC, ...mediaRate, fecUnavailable };
+	}
+	// The predicate held, so the profile is known: this read cannot fail.
+	const fecBlockProfile = readFecBlockProfile(fec.blockProfile, `${fecPath}.blockProfile`, true, throwRepairContractError);
+	return {
+		fecK: fec.sourceSymbols ?? 0,
+		fecBlockProfile,
+		fecRepairCount: fec.repairSymbols ?? 0,
+		// The wire RSB_length: every base layer's packets carry the base total (§7.1).
+		fecTotalRepairCount: repair?.totalBaseRepairSymbols ?? fec.repairSymbols ?? 0,
+		fecSymbolSize: fec.symbolSize ?? 0,
+		// interleaveDepthMs is the FEC block span in MILLISECONDS (§5.1) — the
+		// only interleave key the catalog carries post-BLO-14526. Receivers
+		// derive D by positive round-half-up of span / GOP duration where needed.
+		fecInterleaveMs: catalogFecInterleaveMs(fec) ?? 0,
+		// Additive, never a multiplier on the span: jitter belongs to the network
+		// path and the span belongs to the encoder, so scaling one by the other
+		// hands one network different slack per track. `numericField` rejects 0,
+		// so it cannot be reused here — a declared 0 is a legitimate value.
+		fecReorderToleranceMs: nonNegativeField(fec.reorderToleranceMs),
+		repairTrackName: fec.repairTrack,
+		repairLayers: repair?.baseLayers,
+		repairOverlays: repair?.overlays,
+		...mediaRate,
+	};
+}
+
+/**
+ * Resolves per-track FEC geometry from the catalog for the active endpoint tracks.
+ *
+ * `video`/`audio` (and the top-level names and `catalogFps`) describe the
+ * FIRST video and audio track of `tracks`. `forTrack` resolves any track from
+ * its OWN rendition, scoped by its type: a second video track (an ABR rung or
+ * simulcast variant, possibly sharing a packetId) gets its own framerate,
+ * interleave and repair layers, never the first rendition's. A track with no
+ * rendition of its type resolves to no FEC (`fecK` 0) and no media rate.
+ *
+ * The block profile is track-scoped (BLO-35597). A rendition whose `fec`
+ * declares an FEC instance but names no `blockProfile`, or whose `fec` (a
+ * `none` block included) names a token that is not a known profile, resolves
+ * to no FEC: `fecK` 0, no `fecBlockProfile`, no repair track, and
+ * `fecUnavailable` carrying the `track_fec_block_profile` reason at the
+ * field's JSON path for the caller to surface. Every other track resolves as
+ * usual. The profile is never defaulted or inferred; `algorithm: "none"` may
+ * omit it.
+ *
+ * @throws RepairContractError `track_fec` when a rendition's `fec` declares an
+ * FEC instance (any `algorithm` but `none`) whose `sourceSymbols` or
+ * `symbolSize` is not a positive integer, and when a rendition that declares a
+ * `fec` block (any algorithm, `none` included) carries a repair contract that
+ * violates draft-ramadan-moq-fec 6.3 (a gap or
+ * duplicate in the layer chain, a bad `depends` target, an unreachable repair
+ * track, a bound violation). Because the hang dialect validates every `repair.renditions`
+ * entry of the catalog, resolving the video track fails on a malformed audio
+ * repair rendition too. This is deliberate: a player must fail closed before it
+ * joins any repair track. Callers that used to treat this function as total
+ * must catch it and surface the catalog error.
+ */
+export function resolveCatalogTrackFec(
+	catalog: CatalogWithRenditions | undefined,
+	tracks: readonly CatalogTrackRef[],
+): {
+	videoTrackName?: string;
+	audioTrackName?: string;
+	missingVideoRendition?: string;
+	missingAudioRendition?: string;
+	videoForKeyframeRepair?: KeyframeCadenceCatalog;
+	catalogFps?: number;
+	video: TrackFecParams;
+	audio: TrackFecParams;
+	forTrack(track: CatalogTrackRef): TrackFecParams;
+} {
+	const videoTrackName = tracks.find((t) => t.type === "video")?.name;
+	const audioTrackName = tracks.find((t) => t.type === "audio")?.name;
+	const videoRenditions = catalog?.video?.renditions;
+	const audioRenditions = catalog?.audio?.renditions;
+	const video = videoTrackName ? videoRenditions?.[videoTrackName] : undefined;
+	const audio = audioTrackName ? audioRenditions?.[audioTrackName] : undefined;
+	const catalogFps = numericField(video?.framerate);
+	const sampleRate = numericField(audio?.sampleRate ?? audio?.samplerate);
+	const audioFps = sampleRate ? sampleRate / 1024 : undefined;
+	const videoParams = fecParams(catalog, videoTrackName ? { name: videoTrackName, type: "video" } : undefined, video, catalogFps);
+	const audioParams = fecParams(
+		catalog,
+		audioTrackName ? { name: audioTrackName, type: "audio" } : undefined,
+		audio,
+		audioFps,
+		sampleRate,
+	);
+
+	const forTrack = (track: CatalogTrackRef): TrackFecParams => {
+		if (track.type === "audio") {
+			if (track.name === audioTrackName) return audioParams;
+			const rendition = audioRenditions?.[track.name];
+			if (!rendition) return { ...NO_FEC };
+			const rate = numericField(rendition.sampleRate ?? rendition.samplerate);
+			return fecParams(catalog, { name: track.name, type: "audio" }, rendition, rate ? rate / 1024 : undefined, rate);
+		}
+		if (track.name === videoTrackName) return videoParams;
+		const rendition = videoRenditions?.[track.name];
+		if (!rendition) return { ...NO_FEC };
+		return fecParams(catalog, { name: track.name, type: "video" }, rendition, numericField(rendition.framerate));
+	};
+
+	return {
+		videoTrackName,
+		audioTrackName,
+		missingVideoRendition: videoTrackName && videoRenditions && !video ? videoTrackName : undefined,
+		missingAudioRendition: audioTrackName && audioRenditions && !audio ? audioTrackName : undefined,
+		videoForKeyframeRepair: video,
+		catalogFps,
+		video: videoParams,
+		audio: audioParams,
+		forTrack,
+	};
+}