@blockcast/mmt-container 0.1.0-main.149f78a4adae

package/src/carp-catalog.ts

@@ -0,0 +1,776 @@
+/**
+ * CARP Catalog Types — FEC and Multicast catalog extensions.
+ *
+ * Per draft-law-ramadan-moq-carp-reliability §3 (FEC) and §4 (Multicast).
+ * Plain TypeScript interfaces + type guards — no Zod dependency.
+ *
+ * These are the canonical type definitions. Upstream Zod schemas
+ * should derive from these via z.infer<> to avoid duplication.
+ */
+
+import { resolveMulticastAuthCatalog, type MulticastAuthConfig } from "./multicast-auth-catalog.js";
+
+// ── Track Role (Phase 14, D-02..D-05) ─────────────────────────
+
+/**
+ * Track role derived from the last slash-segment of the track name.
+ *
+ * Convention: `{content}/base`, `{content}/delta`, `{content}/repair`.
+ * Single-track (no slash) legacy streams use `"single"`.
+ *
+ * D-01: No `trackRole` / `role` / `kind` field in the catalog.
+ * D-02: Role is expressed via track name suffix only.
+ * D-03: Unknown suffixes throw at parse time (error on bad init).
+ * D-04: Legacy single-track streams (no slash suffix) return `"single"`.
+ * D-05: Single role per track — no multi-role arrays.
+ */
+export type TrackRole = "base" | "delta" | "repair" | "single";
+
+const VALID_ROLE_SUFFIXES = new Set<string>(["base", "delta", "repair"]);
+
+/**
+ * Derive the role of a track from its name.
+ *
+ * - Names with no `/` → `"single"` (legacy single-track streams, D-04).
+ * - Names ending with `/base`, `/delta`, or `/repair` → that role (D-02).
+ * - Empty name → throws (error on bad init).
+ * - Trailing slash (empty last segment) → throws.
+ * - Non-ASCII or control characters anywhere in the name → throws (T-14-01 fuzz hardening).
+ * - Unknown last segment → throws.
+ *
+ * @throws {Error} On empty name, non-ASCII/control chars, empty suffix, or unknown suffix.
+ */
+export function parseTrackRole(trackName: string): TrackRole {
+	if (trackName === "") {
+		throw new Error("[carp-catalog] empty track name");
+	}
+
+	// T-14-01 fuzz hardening: reject non-ASCII and control characters.
+	// This prevents catalog injection attacks where a publisher sends a crafted
+	// track name that bypasses role checks by embedding unusual code points.
+	for (let i = 0; i < trackName.length; i++) {
+		const cp = trackName.charCodeAt(i);
+		// Reject control characters (0x00-0x1F, 0x7F) and non-ASCII (>0x7E)
+		if (cp <= 0x1f || cp === 0x7f || cp > 0x7e) {
+			throw new Error(
+				`[carp-catalog] track name contains non-ASCII or control character (code point 0x${cp.toString(16)}) in "${trackName}"`,
+			);
+		}
+	}
+
+	const lastSlash = trackName.lastIndexOf("/");
+	if (lastSlash === -1) {
+		// No slash — legacy single-track stream (D-04)
+		return "single";
+	}
+
+	const suffix = trackName.slice(lastSlash + 1);
+	if (suffix === "") {
+		throw new Error(
+			`[carp-catalog] empty role suffix in track name "${trackName}"; track names must not end with "/"`,
+		);
+	}
+
+	if (!VALID_ROLE_SUFFIXES.has(suffix)) {
+		throw new Error(
+			`[carp-catalog] unknown role suffix "${suffix}" in track name "${trackName}"; expected one of: base, delta, repair`,
+		);
+	}
+
+	return suffix as TrackRole;
+}
+
+/**
+ * Non-throwing switching-set detector (BLO-8158).
+ *
+ * Returns `true` iff at least one track name carries a media role suffix
+ * (`base` or `delta`) — i.e. the set looks like a base/delta/repair switching
+ * set. A `/repair` track alone is ordinary FEC topology and is not sufficient
+ * evidence of a switching set. Unlike `parseTrackRole`, this NEVER throws:
+ * names without a `/`, and names with an unrecognised suffix (e.g. an ABR
+ * resolution ladder like `video/1080p`, `video/720p`, `video/8k`), simply do
+ * not count as a role.
+ *
+ * Use this for DETECTION ("is this a switching set?"). Once a switching set is
+ * confirmed, `parseTrackRole` / `validateSwitchingSet` still strictly gate the
+ * actual wiring. ABR ladders yield `false` here and fall through to the
+ * ABR/single path instead of throwing.
+ */
+export function hasSwitchingSetRole(names: string[]): boolean {
+	return names.some((name) => {
+		const lastSlash = name.lastIndexOf("/");
+		if (lastSlash === -1) return false;
+		const suffix = name.slice(lastSlash + 1);
+		return suffix === "base" || suffix === "delta";
+	});
+}
+
+/**
+ * Validate that a set of track names forms a complete switching set.
+ *
+ * - Empty or single-track sets (all parsing to `"single"`) → `{ ok: true }`.
+ * - Multi-track sets (any name has a role suffix) MUST include all three
+ *   roles (`base`, `delta`, `repair`). Missing roles are listed.
+ *
+ * Propagates throws from `parseTrackRole` (non-ASCII, unknown suffix, etc.).
+ *
+ * D-04: Legacy single-track streams pass without enforcement.
+ * D-04: Once any suffix appears, the set is multi-track and must be complete.
+ */
+export function validateSwitchingSet(
+	trackNames: string[],
+): { ok: true } | { ok: false; missing: TrackRole[] } {
+	if (trackNames.length === 0) return { ok: true };
+
+	const roles = trackNames.map(parseTrackRole);
+
+	// If every role is "single", this is a legacy single-track stream — pass.
+	if (roles.every((r) => r === "single")) {
+		return { ok: true };
+	}
+
+	// Multi-track: at least one name has a role suffix.
+	// The set MUST contain all three required roles.
+	// Explicit Set<TrackRole> so the TrackRole-typed `required.filter`
+	// callback can call .has(r) without a narrow-mismatch complaint.
+	const presentRoles: Set<TrackRole> = new Set(roles.filter((r) => r !== "single"));
+	const required: TrackRole[] = ["base", "delta", "repair"];
+	const missing = required.filter((r) => !presentRoles.has(r));
+
+	if (missing.length > 0) {
+		return { ok: false, missing };
+	}
+	return { ok: true };
+}
+
+// ── FEC Catalog Extension (CARP §3.2) ─────────────────────────
+
+export type FecAlgorithm = "none" | "raptorq" | "reed-solomon";
+
+export interface FecCatalogConfig {
+	/** FEC algorithm identifier (REQUIRED per §4.1, values per §3.1). */
+	algorithm: FecAlgorithm;
+	/** K — source symbols per block (REQUIRED). */
+	sourceSymbols: number;
+	/** P — repair symbols per block (REQUIRED). */
+	repairSymbols: number;
+	/** T — bytes per symbol, 8-byte aligned (REQUIRED). */
+	symbolSize: number;
+	/** FEC block span in MILLISECONDS (OPTIONAL, default 0 = single-group blocks).
+	 *  D is the positive round-half-up value of interleaveDepthMs / GOP_duration_ms.
+	 *  BLO-14526: renamed from the legacy `interleaveDepth` count-era key — no fallback read. */
+	interleaveDepthMs?: number;
+	/** Declared jitter/reorder allowance in MILLISECONDS.
+	 *  Added to interleaveDepthMs to form a block's deadline; never multiplied
+	 *  by it. Jitter is a property of the network path and the block span is a
+	 *  property of the encoder, so a multiplicative "safety factor" couples two
+	 *  independent quantities and grants different slack per track for the same
+	 *  network. Consumed identically by FECManager, FEC workers and player
+	 *  policies so one signaled value governs end to end. */
+	reorderToleranceMs?: number;
+	/** Track name for repair symbols (REQUIRED per §6.1). */
+	repairTrack: string;
+	/** FEC block mode: "interleaved" (default) or "object" (per-frame). */
+	// extensions feature — see moqcast-draft docs/fec-extensions-material.md, not in public -00
+	mode?: "interleaved" | "object";
+	/** UEP (Unequal Error Protection) — extensions feature, see moqcast-draft docs/fec-extensions-material.md, not in public -00. When present, repair count
+	 *  varies per frame type. repairSymbols becomes the base (P-frame) count.
+	 *  MUST be omitted on multi-track base/delta streams (D-08). */
+	uep?: {
+		/** Keyframe repair ratio: P = ceil(K * keyRatio). Default 0.5. */
+		keyRatio: number;
+		/** Delta frame repair ratio: P = ceil(K * deltaRatio). Default 0.25. */
+		deltaRatio: number;
+	};
+	/**
+	 * Base-only fallback window in FEC blocks (D-11, Phase 14).
+	 *
+	 * When the delta track's FEC block failure rate exceeds the derived threshold
+	 * over this many consecutive blocks, MediaRouter falls back to base-only mode.
+	 * Derivation: framerate * fallback_window_seconds. If absent, construction
+	 * of the multi-track subscriber MUST throw (error on bad init).
+	 *
+	 * Present only on the base track's fec config (not the delta or repair track).
+	 */
+	deltaFailWindowBlocks?: number;
+	/**
+	 * Delta re-subscribe probe interval in milliseconds (D-13, Phase 14).
+	 *
+	 * After a base-only fallback, wait this long before re-subscribing to the
+	 * delta track to check if conditions have improved.
+	 * Derivation: computeFecDeliveryWindowMs(...) — the single FEC recovery-window
+	 * source of truth (draft-ramadan-moq-fec §9). Never a fixed interleave multiple.
+	 *
+	 * Present only on the base track's fec config (not the delta or repair track).
+	 */
+	deltaProbeIntervalMs?: number;
+	/**
+	 * Jitter + one-way-delay + reorder budget in MILLISECONDS (draft §9).
+	 *
+	 * The single catalog source for the ADDITIVE margin that the FEC
+	 * recovery/loss window adds on top of max(interleave span, source+repair horizon,
+	 * block serialization) — see computeFecDeliveryWindowMs. It is a margin, not
+	 * a multiplier. OPTIONAL: when absent, the derivation falls back to the
+	 * un-rounded interleave window as the reorder-budget bound (margin-policy).
+	 */
+	jitterBufferMs?: number;
+}
+
+export function isFecCatalogConfig(obj: unknown): obj is FecCatalogConfig {
+	if (typeof obj !== "object" || obj === null) return false;
+	const o = obj as Record<string, unknown>;
+	const algorithm = o["algorithm"];
+	const symbolSize = o["symbolSize"];
+	return (
+		typeof algorithm === "string" &&
+		(algorithm === "none" || algorithm === "raptorq" || algorithm === "reed-solomon") &&
+		typeof o["sourceSymbols"] === "number" && o["sourceSymbols"] >= 1 &&
+		typeof o["repairSymbols"] === "number" && o["repairSymbols"] >= 1 &&
+		typeof symbolSize === "number" && symbolSize >= 1 &&
+		(algorithm !== "raptorq" || symbolSize % 8 === 0) &&
+		typeof o["repairTrack"] === "string" && (o["repairTrack"] as string).length > 0
+	);
+}
+
+// ── Multicast Catalog Extension (CARP §4.1-4.4) ───────────────
+
+export type MulticastProtocol = "ssm" | "asm" | "amt" | "atsc3";
+
+/**
+ * Per-track endpoint membership, per draft-ramadan-moq-multicast-00 §4.1.
+ *
+ * `packetId` is the MMTP packet_id used for packet-level demux on the
+ * multicast wire. New emitters MUST use this object form; the legacy
+ * `string` form is accepted by parsers for one release for backward
+ * compatibility (BLO-3323 migration).
+ */
+export interface MulticastTrackObject {
+	name: string;
+	packetId: number;
+}
+
+/** Track entry in a multicast endpoint — accepts both legacy and v2 shape. */
+export type MulticastTrack = string | MulticastTrackObject;
+
+export interface MulticastEndpoint {
+	/** Transport protocol. Defaults to SSM when sourceAddress is present. */
+	protocol?: MulticastProtocol;
+	/** SSM source IP address (REQUIRED for SSM). */
+	sourceAddress?: string;
+	/** Multicast group address (REQUIRED). */
+	groupAddress: string;
+	/** UDP port number (REQUIRED). */
+	port: number;
+	/**
+	 * Tracks available on this endpoint (REQUIRED).
+	 *
+	 * Accepts both legacy `string` (track name only) and v2 object form
+	 * (`{ name, packetId }`) for backward compatibility. New emitters
+	 * MUST use the object form (BLO-3323 / draft §4.1). Consumers can
+	 * type-narrow with `typeof t === "string"` to handle both.
+	 */
+	tracks: MulticastTrack[];
+	/** AMT relay hostname (REQUIRED for AMT). */
+	relayAddress?: string;
+	/**
+	 * Aggregate bandwidth of this endpoint in bits per second.
+	 * RECOMMENDED per draft §4.1 — enables capacity-aware joins.
+	 */
+	bandwidth?: number;
+}
+
+export type AmtDiscovery = "driad" | "manual";
+
+export interface MulticastCatalogConfig {
+	/** Enable/disable multicast (OPTIONAL, default true). */
+	enabled?: boolean;
+	/** Multicast endpoints (REQUIRED). */
+	endpoints: MulticastEndpoint[];
+	/** AMT fallback configuration (OPTIONAL). */
+	amtFallback?: {
+		discovery: AmtDiscovery;
+		relayDns?: string;
+	};
+	/**
+	 * Monotonic catalog version. Publishers MUST bump on any
+	 * `endpoints[]` mutation (BLO-3323 catalog freshness model).
+	 */
+	version?: number;
+	/**
+	 * Unix-ms timestamp after which subscribers SHOULD refetch the
+	 * catalog. Refetch-on-multicast-receive-timeout short-circuits this.
+	 */
+	validUntil?: number;
+}
+
+export function isMulticastTrackObject(obj: unknown): obj is MulticastTrackObject {
+	if (typeof obj !== "object" || obj === null) return false;
+	const o = obj as Record<string, unknown>;
+	return typeof o["name"] === "string" && typeof o["packetId"] === "number";
+}
+
+/**
+ * Wire-shape predicate: returns `true` when `obj` matches the
+ * MulticastEndpoint JSON shape strictly enough to be safely cast.
+ *
+ * Intentionally less strict than `multicastFromConfig`'s
+ * `validateEndpoint` (in `multicast-input.ts`):
+ *
+ *   - `tracks: []` is accepted here (Array.isArray check only) but
+ *     rejected by `validateEndpoint` as `empty_tracks`.
+ *   - SSM-specific group-range and source-required checks are not
+ *     enforced here.
+ *   - Bandwidth/AmtFallback/version are not type-checked.
+ *
+ * That asymmetry is deliberate: this predicate guards JSON parsed off
+ * the wire (already-published catalogs that downstream may have
+ * trimmed), while `validateEndpoint` guards publisher input *before*
+ * a catalog is composed. Subscribers are tolerant; publishers are
+ * strict — the catalog format never re-validates upstream invariants.
+ */
+export function isMulticastEndpoint(obj: unknown): obj is MulticastEndpoint {
+	if (typeof obj !== "object" || obj === null) return false;
+	const o = obj as Record<string, unknown>;
+	const protocol = o["protocol"] ??
+		(typeof o["sourceAddress"] === "string" && o["sourceAddress"].length > 0 ? "ssm" : undefined);
+	return (
+		typeof protocol === "string" &&
+		(protocol === "ssm" || protocol === "asm" || protocol === "amt" || protocol === "atsc3") &&
+		typeof o["groupAddress"] === "string" && (o["groupAddress"] as string).length > 0 &&
+		typeof o["port"] === "number" && (o["port"] as number) > 0 && (o["port"] as number) <= 65535 &&
+		Array.isArray(o["tracks"]) &&
+		(o["tracks"] as unknown[]).every((t: unknown) => typeof t === "string" || isMulticastTrackObject(t))
+	);
+}
+
+export function isMulticastCatalogConfig(obj: unknown): obj is MulticastCatalogConfig {
+	if (typeof obj !== "object" || obj === null) return false;
+	const o = obj as Record<string, unknown>;
+	return (
+		Array.isArray(o["endpoints"]) &&
+		(o["endpoints"] as unknown[]).every((ep: unknown) => isMulticastEndpoint(ep))
+	);
+}
+
+// ── Track Timing (mmt-00 §4.4.4) ──────────────────────────────
+
+/**
+ * Per-track group-duration signaling.
+ *
+ * The catalog publishes either `groupDurationMs` (integer ms) or the exact
+ * `groupDurationTicks` value used by `groupIdForTicks` in align.ts. The tick
+ * form is required for cases where milliseconds cannot represent the cadence
+ * exactly:
+ *
+ *   - Per-frame group durations at non-integer-ms cadences
+ *     (1/30 s = 33.333… ms; 1/60 s = 16.666… ms).
+ *   - Audio sample-rate timescales not divisible by 1000 Hz
+ *     (e.g. 44 100 Hz × 333 ms = 14 685.3 ticks).
+ *
+ * If both fields are present, `groupDurationTicks` wins (matches the
+ * spec, mmt-00 §4.4.4).
+ *
+ * @see draft-ramadan-moq-mmt-00 §4.4.4
+ * @see ./align.ts groupIdForTicks
+ */
+export interface TrackTimingConfig {
+	/** Group duration in milliseconds (positive integer). Required unless an
+	 *  exact groupDurationTicks value is supplied. */
+	groupDurationMs?: number;
+	/** Integer-tick override (OPTIONAL, positive integer). Wins over the
+	 *  ms field when both are present. Required when
+	 *  `(groupDurationMs * timescale) % 1000 != 0`. */
+	groupDurationTicks?: number;
+}
+
+export function isTrackTimingConfig(obj: unknown): obj is TrackTimingConfig {
+	if (typeof obj !== "object" || obj === null) return false;
+	const o = obj as Record<string, unknown>;
+	const ms = o["groupDurationMs"];
+	const ticks = o["groupDurationTicks"];
+	if (ms === undefined && ticks === undefined) return false;
+	if (ms !== undefined && (typeof ms !== "number" || !Number.isInteger(ms) || ms <= 0)) return false;
+	if ("groupDurationTicks" in o) {
+		if (ticks === undefined) return ms !== undefined;
+		if (typeof ticks !== "number" || !Number.isInteger(ticks) || ticks <= 0) return false;
+	}
+	return true;
+}
+
+/** Resolve catalog group timing to an operational wall-clock duration.
+ *
+ * `groupDurationTicks` wins when both wire fields are present, matching
+ * mmt-00 §4.4.4. The result may be fractional because exact frame cadences
+ * such as 33_333 ticks at 1 MHz cannot be represented by the wire catalog's
+ * integer `groupDurationMs` field.
+ */
+export function resolveGroupDurationMs(
+	timing: TrackTimingConfig,
+	timescale: number,
+): number {
+	if (!Number.isSafeInteger(timescale) || timescale <= 0) {
+		throw new Error(
+			`[carp-catalog] resolveGroupDurationMs: timescale must be a positive safe integer Hz, got ${timescale}`,
+		);
+	}
+	if (!isTrackTimingConfig(timing)) {
+		throw new Error(
+			`[carp-catalog] resolveGroupDurationMs: invalid TrackTimingConfig: ${JSON.stringify(timing)}`,
+		);
+	}
+	if (timing.groupDurationTicks === undefined) {
+		return timing.groupDurationMs!;
+	}
+
+	const durationMs = (timing.groupDurationTicks / timescale) * 1000;
+	if (!Number.isFinite(durationMs) || durationMs <= 0 || durationMs > Number.MAX_SAFE_INTEGER) {
+		throw new Error(
+			`[carp-catalog] resolveGroupDurationMs: groupDurationTicks=${timing.groupDurationTicks} ` +
+				`at timescale=${timescale} cannot be represented as a positive safe millisecond duration`,
+		);
+	}
+	return durationMs;
+}
+
+export type CmsfCatalog = {
+	version: number;
+	tracks: Record<string, unknown>[];
+	commonTrackFields?: Record<string, unknown>;
+	multicast?: Record<string, unknown>;
+	"multicast.auth"?: MulticastAuthConfig;
+	[key: string]: unknown;
+};
+
+export type CmsfCatalogErrorCode =
+	| "catalog_object"
+	| "catalog_version"
+	| "catalog_tracks"
+	| "track_object"
+	| "track_name"
+	| "track_packaging"
+	| "track_is_live"
+	| "track_codec"
+	| "track_mmtp_mode"
+	| "track_timescale"
+	| "track_group_duration_ms"
+	| "track_group_duration_ticks"
+	| "track_group_duration_exact"
+	| "track_keyframe_interval"
+	| "track_fec"
+	| "track_repair_track"
+	| "track_switching_set"
+	| "multicast_auth"
+	| "multicast_track"
+	| "multicast_packet_id";
+
+export class CmsfCatalogValidationError extends Error {
+	constructor(
+		public readonly code: CmsfCatalogErrorCode,
+		public readonly path: string,
+		message: string,
+	) {
+		super(`[cmsf:${code}] ${path}: ${message}`);
+		this.name = "CmsfCatalogValidationError";
+	}
+}
+
+function catalogError(code: CmsfCatalogErrorCode, path: string, message: string): never {
+	throw new CmsfCatalogValidationError(code, path, message);
+}
+
+/** Validate the common CMSF shape and the MMTP required-field profile. */
+export function validateCmsfMmtpCatalog(value: unknown): CmsfCatalog {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		catalogError("catalog_object", "$", "catalog must be an object");
+	}
+	const catalog = value as Record<string, unknown>;
+	// IETF-draft catalogs (cast `ladder_catalog.rs`, moq-server
+	// `catalog-synthesizer.ts`, consumed by the hang player) carry a string
+	// version tag such as "draft-ietf-moq-catalogformat-01" instead of the CMSF
+	// `version: 1` integer. Nothing keys behavior off the catalog version, so
+	// normalize the tag to a number rather than rejecting the whole catalog —
+	// mirrors the relay (dual-stack-relay `bridge/catalog.rs`
+	// `deserialize_optional_u32_lenient`, #825) and moqtail-ts
+	// `normalizeCatalogVersion`.
+	const rawVersion = catalog["version"];
+	const normalizedVersion =
+		typeof rawVersion === "string"
+			? Number.isFinite(Number(rawVersion))
+				? Number(rawVersion)
+				: rawVersion.startsWith("draft-ietf-moq-catalogformat")
+					? 1
+					: NaN
+			: rawVersion;
+	if (!Number.isInteger(normalizedVersion) || (normalizedVersion as number) <= 0) {
+		catalogError("catalog_version", "$.version", "version must be a positive integer or a recognized format tag");
+	}
+	catalog["version"] = normalizedVersion;
+	if (!Array.isArray(catalog["tracks"])) {
+		catalogError("catalog_tracks", "$.tracks", "tracks must be an array");
+	}
+
+	const common = typeof catalog["commonTrackFields"] === "object" &&
+		catalog["commonTrackFields"] !== null && !Array.isArray(catalog["commonTrackFields"])
+		? catalog["commonTrackFields"] as Record<string, unknown>
+		: {};
+	const tracks = catalog["tracks"] as unknown[];
+	const trackRecords: Record<string, unknown>[] = [];
+	const effective = (track: Record<string, unknown>, field: string): unknown => track[field] ?? common[field];
+	const positiveInteger = (input: unknown): input is number => Number.isSafeInteger(input) && (input as number) > 0;
+	const positiveNumber = (input: unknown): input is number =>
+		typeof input === "number" && Number.isFinite(input) && input > 0;
+
+	for (let index = 0; index < tracks.length; index++) {
+		const raw = tracks[index];
+		const path = `$.tracks[${index}]`;
+		if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+			catalogError("track_object", path, "track must be an object");
+		}
+		const track = raw as Record<string, unknown>;
+		const name = track["name"];
+		if (typeof name !== "string" || name.length === 0) {
+			catalogError("track_name", `${path}.name`, "name must be a non-empty string");
+		}
+		trackRecords.push(track);
+
+		const packaging = effective(track, "packaging");
+		if (typeof packaging !== "string" || packaging.length === 0) {
+			catalogError("track_packaging", `${path}.packaging`, "packaging must be a non-empty string");
+		}
+		const trackHasIsLive = Object.prototype.hasOwnProperty.call(track, "isLive");
+		const hasIsLive = trackHasIsLive || Object.prototype.hasOwnProperty.call(common, "isLive");
+		const isLive = trackHasIsLive ? track["isLive"] : common["isLive"];
+		if (hasIsLive && typeof isLive !== "boolean") {
+			catalogError("track_is_live", `${path}.isLive`, "isLive must be a boolean");
+		}
+		track["isLive"] = isLive ?? true;
+		const selectionValue = effective(track, "selectionParams");
+		const selection = typeof selectionValue === "object" && selectionValue !== null && !Array.isArray(selectionValue)
+			? selectionValue as Record<string, unknown>
+			: undefined;
+		const codec = selection?.["codec"] ?? effective(track, "codec");
+		if (packaging !== "timeline" && packaging !== "mediatimeline" && packaging !== "eventtimeline" && packaging !== "fec-repair" &&
+			(typeof codec !== "string" || codec.length === 0)) {
+			catalogError("track_codec", `${path}.codec`, `codec is required for packaging=${packaging}`);
+		}
+
+		const timescale = effective(track, "timescale");
+		const groupDurationMs = effective(track, "groupDurationMs");
+		const groupDurationTicks = effective(track, "groupDurationTicks");
+		const keyframeIntervalMs = effective(track, "keyframeIntervalMs");
+		const keyframeIntervalTicks = effective(track, "keyframeIntervalTicks");
+		if (groupDurationMs !== undefined && !positiveInteger(groupDurationMs)) {
+			catalogError("track_group_duration_ms", `${path}.groupDurationMs`, "must be a positive integer");
+		}
+		if (groupDurationTicks !== undefined && !positiveInteger(groupDurationTicks)) {
+			catalogError("track_group_duration_ticks", `${path}.groupDurationTicks`, "must be a positive integer");
+		}
+		if ((keyframeIntervalMs !== undefined && !positiveNumber(keyframeIntervalMs)) ||
+			(keyframeIntervalTicks !== undefined && !positiveInteger(keyframeIntervalTicks))) {
+			catalogError("track_keyframe_interval", path, "keyframe interval fields must be positive numbers");
+		}
+		if (packaging === "mmtp") {
+			const mmtpMode = effective(track, "mmtpMode");
+			if (mmtpMode !== "mpu" && mmtpMode !== "mfu") {
+				catalogError("track_mmtp_mode", `${path}.mmtpMode`, "must be mpu or mfu");
+			}
+			if (!positiveInteger(timescale)) {
+				catalogError("track_timescale", `${path}.timescale`, "must be a positive integer");
+			}
+			if (groupDurationMs === undefined && groupDurationTicks === undefined) {
+				catalogError(
+					"track_group_duration_ms",
+					path,
+					"groupDurationMs or groupDurationTicks must be a positive integer",
+				);
+			}
+			if (groupDurationTicks === undefined &&
+				(BigInt(groupDurationMs as number) * BigInt(timescale)) % 1000n !== 0n) {
+				catalogError("track_group_duration_exact", `${path}.groupDurationMs`, "does not resolve to an exact integer tick count");
+			}
+		}
+
+		if (track["fec"] !== undefined) {
+			const fec = track["fec"];
+			if (typeof fec !== "object" || fec === null || Array.isArray(fec)) {
+				catalogError("track_fec", `${path}.fec`, "FEC must be an object");
+			}
+			const config = fec as Record<string, unknown>;
+			const algorithm = config["algorithm"];
+			if (algorithm !== "none" && algorithm !== "raptorq" && algorithm !== "reed-solomon") {
+				catalogError("track_fec", `${path}.fec.algorithm`, "algorithm is not supported");
+			}
+			if ("interleaveDepth" in config || "interleaveMs" in config) {
+				catalogError("track_fec", `${path}.fec`, "interleaveDepthMs is the only supported interleave field");
+			}
+			if (config["interleaveDepthMs"] !== undefined && !positiveInteger(config["interleaveDepthMs"])) {
+				catalogError("track_fec", `${path}.fec.interleaveDepthMs`, "must be a positive integer");
+			}
+			if (algorithm !== "none") {
+				for (const field of ["sourceSymbols", "repairSymbols", "symbolSize"] as const) {
+					if (!positiveInteger(config[field])) {
+						catalogError("track_fec", `${path}.fec.${field}`, "must be a positive integer");
+					}
+				}
+				if (typeof config["repairTrack"] !== "string" || config["repairTrack"].length === 0) {
+					catalogError("track_fec", `${path}.fec.repairTrack`, "must be a non-empty string");
+				}
+			}
+		}
+	}
+
+	for (let index = 0; index < trackRecords.length; index++) {
+		const track = trackRecords[index]!;
+		const fec = track["fec"] as Record<string, unknown> | undefined;
+		if (!fec || fec["algorithm"] === "none") continue;
+		const repairTrack = fec["repairTrack"] as string;
+		const target = trackRecords.find((candidate) => candidate["name"] === repairTrack);
+		if (!target || effective(target, "packaging") !== "fec-repair") {
+			catalogError("track_repair_track", `$.tracks[${index}].fec.repairTrack`, `unknown FEC repair track ${JSON.stringify(repairTrack)}`);
+		}
+	}
+
+	const switchingSets = new Map<number, { name: string; ticks: bigint; timescale: bigint }>();
+	for (let index = 0; index < trackRecords.length; index++) {
+		const track = trackRecords[index]!;
+		if (effective(track, "packaging") !== "mmtp") continue;
+		const altGroup = effective(track, "altGroup");
+		if (!Number.isSafeInteger(altGroup)) continue;
+		const timescale = BigInt(effective(track, "timescale") as number);
+		const durationTicks = effective(track, "groupDurationTicks");
+		const ticks = durationTicks !== undefined
+			? BigInt(durationTicks as number)
+			: BigInt(effective(track, "groupDurationMs") as number) * timescale / 1000n;
+		const anchor = switchingSets.get(altGroup as number);
+		if (anchor && ticks * anchor.timescale !== anchor.ticks * timescale) {
+			catalogError("track_switching_set", `$.tracks[${index}]`, `group duration does not match ${JSON.stringify(anchor.name)} in altGroup ${altGroup}`);
+		}
+		if (!anchor) switchingSets.set(altGroup as number, { name: track["name"] as string, ticks, timescale });
+	}
+
+	const multicast = catalog["multicast"];
+	if (typeof multicast === "object" && multicast !== null && !Array.isArray(multicast)) {
+		const endpoints = (multicast as Record<string, unknown>)["endpoints"];
+		if (Array.isArray(endpoints)) {
+			for (let endpointIndex = 0; endpointIndex < endpoints.length; endpointIndex++) {
+				const endpoint = endpoints[endpointIndex];
+				if (typeof endpoint !== "object" || endpoint === null || Array.isArray(endpoint)) continue;
+				const refs = (endpoint as Record<string, unknown>)["tracks"];
+				if (!Array.isArray(refs)) continue;
+				const packetIds = new Map<number, string>();
+				for (let refIndex = 0; refIndex < refs.length; refIndex++) {
+					const ref = refs[refIndex];
+					if (typeof ref !== "object" || ref === null || Array.isArray(ref)) continue;
+					const trackRef = ref as Record<string, unknown>;
+					const refPath = `$.multicast.endpoints[${endpointIndex}].tracks[${refIndex}]`;
+					const name = trackRef["name"];
+					if (typeof name !== "string" || !trackRecords.some((track) => track["name"] === name)) {
+						catalogError("multicast_track", `${refPath}.name`, `unknown catalog track ${JSON.stringify(name)}`);
+					}
+					const packetId = trackRef["packetId"];
+					if (!Number.isSafeInteger(packetId) || (packetId as number) < 0 || (packetId as number) > 65535) {
+						catalogError("multicast_packet_id", `${refPath}.packetId`, "packetId must be an integer from 0 to 65535");
+					}
+					const previous = packetIds.get(packetId as number);
+					if (previous !== undefined) {
+						catalogError("multicast_packet_id", `${refPath}.packetId`, `packetId is already assigned to ${JSON.stringify(previous)}`);
+					}
+					packetIds.set(packetId as number, name as string);
+				}
+			}
+		}
+	}
+
+	try {
+		resolveMulticastAuthCatalog(catalog);
+	} catch (error) {
+		catalogError(
+			"multicast_auth",
+			"$.multicast.auth",
+			error instanceof Error ? error.message : "invalid multicast.auth v2 block",
+		);
+	}
+
+	return catalog as CmsfCatalog;
+}
+
+/**
+ * Resolve a track's group duration to integer ticks using the supplied
+ * timescale (Hz). Implements mmt-00 §4.4.4:
+ *
+ *   - If `groupDurationTicks` is present, return it (override wins).
+ *   - Else compute `groupDurationMs * timescale / 1000`. The result MUST
+ *     be an exact integer; throws if `(ms * timescale) % 1000 != 0`.
+ *
+ * Throws on invalid timing config or non-positive timescale (CLAUDE.md:
+ * error on bad init).
+ */
+export function resolveGroupDurationTicks(
+	timing: TrackTimingConfig,
+	timescale: number,
+): number {
+	if (!Number.isFinite(timescale) || !Number.isInteger(timescale) || timescale <= 0) {
+		throw new Error(
+			`[carp-catalog] resolveGroupDurationTicks: timescale must be a positive integer Hz, got ${timescale}`,
+		);
+	}
+	if (!isTrackTimingConfig(timing)) {
+		throw new Error(
+			`[carp-catalog] resolveGroupDurationTicks: invalid TrackTimingConfig: ${JSON.stringify(timing)}`,
+		);
+	}
+	if (timing.groupDurationTicks !== undefined) {
+		return timing.groupDurationTicks;
+	}
+	if (timing.groupDurationMs === undefined) {
+		throw new Error(
+			"[carp-catalog] resolveGroupDurationTicks: groupDurationMs is required when groupDurationTicks is absent",
+		);
+	}
+	const product = timing.groupDurationMs * timescale;
+	if (product % 1000 !== 0) {
+		throw new Error(
+			`[carp-catalog] resolveGroupDurationTicks: groupDurationMs=${timing.groupDurationMs} at timescale=${timescale} ` +
+				`produces non-integer ticks (${product / 1000}); publisher must use groupDurationTicks override (mmt-00 §4.4.4)`,
+		);
+	}
+	return product / 1000;
+}
+
+/**
+ * Validate that every track in a switching set agrees on the same
+ * wall-clock group duration (mmt-00 §4.4.4). Per-track timescales may
+ * differ, so raw tick counts cannot be compared directly.
+ *
+ * Returns `{ ok: true }` when all tracks agree (or the set is empty);
+ * `{ ok: false, mismatches }` listing each track whose effective ticks
+ * differ from the first track's value. Subscribers per spec SHOULD
+ * reject the catalog on mismatch.
+ *
+ * Throws if any track's timing config is invalid (per
+ * `resolveGroupDurationTicks`).
+ */
+export function validateSwitchingSetTiming(
+	tracks: Array<{ name: string; timing: TrackTimingConfig; timescale: number }>,
+):
+	| { ok: true }
+	| { ok: false; expectedTicks: number; mismatches: Array<{ name: string; ticks: number }> } {
+	if (tracks.length === 0) return { ok: true };
+	const ticksByTrack = tracks.map((t) => ({
+		name: t.name,
+		ticks: resolveGroupDurationTicks(t.timing, t.timescale),
+		timescale: t.timescale,
+	}));
+	const expectedTicks = ticksByTrack[0].ticks;
+	const expectedTimescale = ticksByTrack[0].timescale;
+	const mismatches = ticksByTrack
+		.slice(1)
+		.filter(
+			(t) =>
+				BigInt(t.ticks) * BigInt(expectedTimescale) !==
+				BigInt(expectedTicks) * BigInt(t.timescale),
+		)
+		.map(({ name, ticks }) => ({ name, ticks }));
+	if (mismatches.length === 0) return { ok: true };
+	return { ok: false, expectedTicks, mismatches };
+}