@blockcast/mmt-container 0.1.0 → 0.3.0-main.d9354616fdf2

package/src/carp-catalog.ts

@@ -0,0 +1,1065 @@
+/**
+ * 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 {
+	MMTP_PACKET_ID_MAX,
+	MMTP_SIGNALING_PACKET_ID,
+	isFecBlockProfile,
+	type FecBlockProfile,
+} from "@blockcast/mmt-base";
+import { resolveMulticastAuthCatalog, type MulticastAuthConfig } from "./multicast-auth-catalog.js";
+import {
+	assembleRepairLayers,
+	assertRepairTrackReachable,
+	describeRepairTrack,
+	rejectRepairFieldsOnMediaTrack,
+	rejectRepairTrackGeometry,
+	repairReachability,
+	dependsTarget,
+	readFecBlockProfile,
+	validateRepairTrackFields,
+} from "./repair-layers.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;
+	/** FEC block profile (BLO-35597, ISO/IEC 23008-1 Annex C). REQUIRED when
+	 *  `algorithm` declares an FEC instance (anything but `"none"`); optional
+	 *  on `"none"`, where a present token must still be known. Never defaulted
+	 *  and never inferred from the wire: `k-padded-v1` (zero-padded K-symbol
+	 *  blocks, SS_Start = SBN*K) and `iso-ssbg1-v1` (ssbg_mode1, K' =
+	 *  SSB_length, consecutive SS_IDs) carry identical wire tuples whose repair
+	 *  math differs. */
+	blockProfile?: FecBlockProfile;
+	/** 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). Base layer 0 when the
+	 *  source carries further repair layers or a keyframe overlay: those are
+	 *  self-describing `fec-repair` tracks (`depends`, `repairLayer`, `scope`)
+	 *  per draft-ramadan-moq-fec §6.3, never listed here. */
+	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).
+	 *
+	 * An explicit ADDITIVE margin over the complete signaled FEC block span.
+	 * OPTIONAL: absence does not authorize a local default or a span multiplier.
+	 */
+	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 &&
+		(isFecBlockProfile(o["blockProfile"]) || (algorithm === "none" && o["blockProfile"] === undefined))
+	);
+}
+
+// ── 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, in 1..65535: packet_id 0 (`MMTP_SIGNALING_PACKET_ID`) is
+ * the MMTP signaling flow and is never a track's. 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.
+	 *
+	 * @deprecated Superseded by catalog-level `multicast.networkSource`
+	 * (`{type: "amt", discovery, relay}`). Retained so a catalog published
+	 * before the migration still parses; emitters MUST NOT write it, and
+	 * `catalog.schema.json` already rejects it (`additionalProperties: false`
+	 * on the endpoint), as does moq-rs `MulticastEndpoint`
+	 * (`deny_unknown_fields`, and it carries no relay field at all).
+	 */
+	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";
+
+/**
+ * One `multicast.networkSource[]` entry, per draft-ramadan-moq-multicast §4.1.
+ *
+ * Mirrors moq-rs `NetworkSource` (the normative validator) and the
+ * `networkSource` `$def` in `catalog.schema.json` 1:1 — a change here needs the
+ * same change in both. `discovery: "manual"` requires `relay`; that relay is
+ * the one the player joins. Under `discovery: "driad"` the relay is resolved at
+ * runtime, so `relay` is OPTIONAL and, when present, only a discovery hint
+ * (e.g. the `amtFallback.relayDns` name the derived path carries over): readers
+ * do not join it (`findAmtRelay` in packages/transport
+ * multicast-catalog-policy.ts and `catalogAmtNetworkSource` in
+ * catalog-network-source.ts both skip it), so a DRIAD entry never pins a relay.
+ * `port` is OPTIONAL on the wire: the join boundary itself has no default, but
+ * every reader resolves one before that boundary, so a manual relay without a
+ * port joins on RFC 7450's 2268 rather than failing (BLO-38176).
+ *
+ * Not to be confused with `CatalogNetworkSource` in `catalog-network-source.ts`,
+ * which is also exported from the package root and also describes
+ * `$defs/networkSource`. The split is deliberate and the two must NOT be
+ * unified: this type is the strict EMITTER/wire shape, so tightening it is what
+ * keeps published catalogs normative. That one is the tolerant READER — every
+ * field optional, and it also accepts the bare-object form that hang's zod
+ * RootSchema and older hand-authored catalogs emit. Tightening the reader would
+ * reject catalogs already in the wild, so when this type changes, widen the
+ * reader only if the new shape must be consumed; never narrow it to match.
+ *
+ * This is the one place a catalog declares an AMT relay. It is catalog-level,
+ * not per-endpoint: the normative endpoint model carries no relay field.
+ */
+export type NetworkSource =
+	| { type: "amt"; discovery: AmtDiscovery; relay?: string; port?: number }
+	| { type: "atsc3"; frequency: number; plpId: number; serviceId: number; slsUri: string };
+
+export interface MulticastCatalogConfig {
+	/** Enable/disable multicast (OPTIONAL, default true). */
+	enabled?: boolean;
+	/** Multicast endpoints (REQUIRED). */
+	endpoints: MulticastEndpoint[];
+	/**
+	 * Relay/tuning discovery for these endpoints. Required whenever an endpoint
+	 * declares a bearer protocol (`amt`, `atsc3`), which must name its own entry
+	 * type here; omitted for native joins (`ssm`, `asm`), whose endpoint tuple is
+	 * the whole join.
+	 */
+	networkSource?: NetworkSource[];
+	/**
+	 * AMT fallback configuration.
+	 *
+	 * @deprecated Superseded by `networkSource` — `{discovery, relayDns}` maps
+	 * onto `{type: "amt", discovery, relay}`. `multicastFromConfig` lifts it and
+	 * no longer emits it; the schema rejects it.
+	 */
+	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)) &&
+		// Shape only, not contents — entry validation is `multicastFromConfig`'s.
+		// `networkSource` now carries the relay, so a non-array here must not
+		// narrow clean: every reader of it indexes it.
+		//
+		// `=== undefined`, not `!("networkSource" in o)`: `multicastFromConfig`
+		// tests definedness, and the two must agree on what "set" means. A key
+		// present with value `undefined` is a legal `MulticastCatalogConfig`
+		// (`strict` without `exactOptionalPropertyTypes`) and is what a spread
+		// of an optional field produces — `in` would narrow that valid config
+		// to `false` and a consumer gating on this guard would discard a
+		// working multicast block.
+		(o["networkSource"] === undefined || Array.isArray(o["networkSource"]))
+	);
+}
+
+// ── 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;
+}
+
+/**
+ * Optional unicast archive tier (BLO-41290).
+ *
+ * `origin` is scheme-and-authority only. Object paths are never advertised:
+ * a consumer derives them via the v1 ContentId profile —
+ * `/v1/{ns}/{track}/{group}[/{object}]` under this origin
+ * (`mmt-archive/src/content_id.rs`). Advertising the pair a second time would
+ * be a second source of truth that can disagree with `tracks[]`.
+ *
+ * `{track}` is the track's `name`. `{ns}` is the track's own `namespace` when
+ * it declares one, and otherwise the MoQ subscription's Track Namespace tuple,
+ * of which `ContentId::from_moq` admits exactly one element. The catalog does
+ * not carry that tuple, so for a track omitting `namespace` the derivation
+ * needs the subscription context — the catalog alone is not sufficient. That
+ * inheritance is the load-bearing half of the contract: `namespace` is
+ * optional in the schema, so a catalog can advertise an archive whose object
+ * paths only resolve in a subscribing consumer.
+ *
+ * One origin at the top level, not one per track: the `(namespace, track)` key
+ * lives in the derived path rather than in the origin, so a single origin
+ * already disambiguates every track however many namespaces the catalog spans.
+ * A per-track origin would only buy splitting one catalog across several
+ * archives, which nothing asks for.
+ *
+ * Absence means "no archive advertised". It is never a default URL.
+ */
+export interface ArchiveConfig {
+	origin: string;
+}
+
+/**
+ * The advertised archive origin, or `undefined` when none is advertised.
+ *
+ * Takes a catalog already through `validateCmsfMmtpCatalog`, so the returned
+ * string is canonical and safe to use as a base — no string surgery on a
+ * config blob, and no second place that decides what an origin may look like.
+ */
+export function archiveOrigin(catalog: CmsfCatalog): string | undefined {
+	return catalog.archive?.origin;
+}
+
+/**
+ * Pin the archive origin to exactly one spelling per archive.
+ *
+ * The ContentId codec rejects percent-encoding so every identity has exactly
+ * one URL path; an advertised base must not reintroduce aliasing above it.
+ * `value === new URL(value).origin` is most of the rule — `URL.origin` drops
+ * path, query, fragment and userinfo, lowercases scheme and host, strips the
+ * default port and any trailing slash, and normalizes percent-escapes. So a
+ * separate percent-encoding check would be redundant, not missing: `%6d` in a
+ * host decodes and fails the comparison. `https:` is checked separately
+ * because `http://host` is already its own origin and passes the comparison.
+ *
+ * The comparison alone admits one alias, so the trailing dot is rejected
+ * explicitly: `https://host.` is its own `URL.origin` verbatim, while `host.`
+ * and `host` are the same DNS name. That aliases the advertised *base*, not
+ * the codec input — the origin contributes no path segments, so a trailing
+ * dot never reaches `ContentId::parse_path` — but it still gives one archive
+ * two cache keys, and some TLS stacks treat `host.` as a distinct SNI/CORS
+ * origin.
+ *
+ * `additionalProperties: false` on `archive` is enforced here as well as in
+ * the schema. The runtime validator is the gate `archiveOrigin` documents
+ * itself against, so a second spelling of the origin smuggled in under
+ * another key must be rejected by both, not just by AJV.
+ */
+function validateArchive(catalog: Record<string, unknown>): void {
+	const archive = catalog["archive"];
+	if (archive === undefined) return;
+	if (typeof archive !== "object" || archive === null || Array.isArray(archive)) {
+		catalogError("archive_object", "$.archive", "archive must be an object");
+	}
+	const unknown = Object.keys(archive as Record<string, unknown>).filter(key => key !== "origin");
+	if (unknown.length > 0) {
+		catalogError("archive_object", "$.archive", `archive has unknown field(s) ${unknown.map(key => JSON.stringify(key)).join(", ")}; only "origin" is allowed`);
+	}
+	const origin = (archive as Record<string, unknown>)["origin"];
+	// Absent and present-but-wrong-type are different mistakes and the schema
+	// already distinguishes them (`required` vs `type`). Collapsing both into
+	// "must be a string" tells someone hand-writing a catalog to fix a field
+	// they never wrote. Same wording convention as `codec is required`.
+	//
+	// This is the one archive rule where the two gates report different fields,
+	// deliberately: AJV raises `required` at the parent, `/archive` (its
+	// placement, not a choice — same shape as `fec-block-profile-missing`),
+	// while this raises at `$.archive.origin`. Pointing at the field someone has
+	// to add is the more useful of the two, so the "same field" convention
+	// documented above bends here rather than the message getting vaguer.
+	if (origin === undefined) {
+		catalogError("archive_origin", "$.archive.origin", "origin is required when an archive block is present");
+	}
+	if (typeof origin !== "string") {
+		catalogError("archive_origin", "$.archive.origin", "origin must be a string");
+	}
+	let parsed: URL;
+	try {
+		parsed = new URL(origin);
+	} catch {
+		catalogError("archive_origin", "$.archive.origin", `origin must be an absolute URL, got ${JSON.stringify(origin)}`);
+	}
+	if (parsed.protocol !== "https:") {
+		catalogError("archive_origin", "$.archive.origin", `origin must use https, got ${JSON.stringify(parsed.protocol)}`);
+	}
+	if (origin !== parsed.origin) {
+		catalogError(
+			"archive_origin",
+			"$.archive.origin",
+			`origin must be scheme and authority in canonical form with no path, query, fragment, userinfo or trailing slash; expected ${JSON.stringify(parsed.origin)}, got ${JSON.stringify(origin)}`,
+		);
+	}
+	if (parsed.hostname.endsWith(".")) {
+		catalogError("archive_origin", "$.archive.origin", `origin host must not end in a trailing dot; ${JSON.stringify(parsed.hostname)} and ${JSON.stringify(parsed.hostname.slice(0, -1))} are the same host`);
+	}
+}
+
+export type CmsfCatalog = {
+	version: number;
+	tracks: Record<string, unknown>[];
+	multicast?: Record<string, unknown>;
+	"multicast.auth"?: MulticastAuthConfig;
+	archive?: ArchiveConfig;
+	[key: string]: unknown;
+};
+
+export type CmsfCatalogErrorCode =
+	| "catalog_object"
+	| "catalog_version"
+	| "catalog_tracks"
+	| "catalog_common_track_fields"
+	| "track_object"
+	| "track_name"
+	| "track_packaging"
+	| "track_selection_params"
+	| "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_fec_bounds"
+	| "track_fec_block_profile"
+	| "track_repair_track"
+	| "track_repair_depends"
+	| "track_repair_layer"
+	| "track_repair_priority"
+	| "track_repair_overlay"
+	| "track_repair_geometry"
+	| "track_switching_set"
+	| "multicast_auth"
+	| "multicast_track"
+	| "multicast_packet_id"
+	| "archive_object"
+	| "archive_origin";
+
+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");
+	}
+
+	if ("commonTrackFields" in catalog) {
+		catalogError(
+			"catalog_common_track_fields",
+			"$.commonTrackFields",
+			"commonTrackFields is retired; every track carries its own fields",
+		);
+	}
+	const tracks = catalog["tracks"] as unknown[];
+	const trackRecords: Record<string, unknown>[] = [];
+	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 = track["packaging"];
+		if (typeof packaging !== "string" || packaging.length === 0) {
+			catalogError("track_packaging", `${path}.packaging`, "packaging must be a non-empty string");
+		}
+		const hasIsLive = Object.prototype.hasOwnProperty.call(track, "isLive");
+		const isLive = track["isLive"];
+		if (hasIsLive && typeof isLive !== "boolean") {
+			catalogError("track_is_live", `${path}.isLive`, "isLive must be a boolean");
+		}
+		track["isLive"] = isLive ?? true;
+		if ("selectionParams" in track) {
+			catalogError(
+				"track_selection_params",
+				`${path}.selectionParams`,
+				"selectionParams is retired; codec and the other selection fields are flat on the track",
+			);
+		}
+		const codec = 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 = track["timescale"];
+		const groupDurationMs = track["groupDurationMs"];
+		const groupDurationTicks = track["groupDurationTicks"];
+		const keyframeIntervalMs = track["keyframeIntervalMs"];
+		const keyframeIntervalTicks = 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");
+		}
+		// draft-ramadan-moq-fec §6.3: repair tracks describe themselves and carry
+		// no block geometry; media tracks never carry repair-track fields.
+		if (packaging === "fec-repair") {
+			rejectRepairTrackGeometry(path, track, catalogError);
+			validateRepairTrackFields(describeRepairTrack(name, path, track), catalogError);
+		} else {
+			rejectRepairFieldsOnMediaTrack(path, track, catalogError);
+		}
+		if (packaging === "mmtp") {
+			const mmtpMode = 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 ("enhancementRepair" in config) {
+				catalogError(
+					"track_fec",
+					`${path}.fec.enhancementRepair`,
+					"repair layers are self-describing fec-repair tracks (depends, repairLayer); fec.enhancementRepair is not supported",
+				);
+			}
+			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");
+				}
+			}
+			// Required on a declared FEC instance, optional but known on "none".
+			readFecBlockProfile(config["blockProfile"], `${path}.fec.blockProfile`, algorithm !== "none", catalogError);
+		}
+	}
+
+	// Repair tracks (draft-ramadan-moq-fec §6.3). Every fec-repair track is
+	// described once; each FEC source then assembles its base layer chain and
+	// overlays through the shared contract, which fails closed with a code and
+	// the JSON path of the offending field.
+	const repairDescriptors = trackRecords.flatMap((track, index) =>
+		track["packaging"] === "fec-repair"
+			? [describeRepairTrack(track["name"] as string, `$.tracks[${index}]`, track)]
+			: [],
+	);
+	// Rule 9 (no orphan repair track) reads the same derivation the resolver
+	// uses; see `repairReachability` in repair-layers.ts for its scope.
+	const reachability = repairReachability(
+		trackRecords.filter((track) => track["packaging"] !== "fec-repair").map((track) => track["fec"]),
+	);
+	for (const descriptor of repairDescriptors) {
+		assertRepairTrackReachable(descriptor, reachability, catalogError);
+		const target = dependsTarget(descriptor);
+		if (target === undefined) continue;
+		const source = trackRecords.find((candidate) => candidate["name"] === target);
+		const sourceFec = source?.["fec"] as Record<string, unknown> | undefined;
+		if (!source || source["packaging"] !== "mmtp" || !sourceFec || sourceFec["algorithm"] === "none") {
+			catalogError(
+				"track_repair_depends",
+				`${descriptor.path}.depends`,
+				`${JSON.stringify(target)} is not an mmtp track with FEC`,
+			);
+		}
+	}
+	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;
+		// A dangling fec.repairTrack (missing, or not a fec-repair track) fails
+		// inside the shared contract, so the resolver and this validator agree.
+		assembleRepairLayers(
+			{
+				name: track["name"] as string,
+				path: `$.tracks[${index}].fec`,
+				algorithm: fec["algorithm"],
+				sourceSymbols: fec["sourceSymbols"],
+				repairSymbols: fec["repairSymbols"],
+				repairTrack: fec["repairTrack"],
+			},
+			repairDescriptors,
+			catalogError,
+			{ layerZeroMustBeDeclared: true },
+		);
+	}
+
+	const switchingSets = new Map<number, { name: string; ticks: bigint; timescale: bigint }>();
+	for (let index = 0; index < trackRecords.length; index++) {
+		const track = trackRecords[index]!;
+		if (track["packaging"] !== "mmtp") continue;
+		const altGroup = track["altGroup"];
+		if (!Number.isSafeInteger(altGroup)) continue;
+		const timescale = BigInt(track["timescale"] as number);
+		const durationTicks = track["groupDurationTicks"];
+		const ticks = durationTicks !== undefined
+			? BigInt(durationTicks as number)
+			: BigInt(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 (packetId === MMTP_SIGNALING_PACKET_ID) {
+						catalogError(
+							"multicast_packet_id",
+							`${refPath}.packetId`,
+							`packetId ${packetId} is the MMTP signaling flow and must not be advertised for a track; packetId must be an integer from 1 to ${MMTP_PACKET_ID_MAX}`,
+						);
+					}
+					if (!Number.isSafeInteger(packetId) || (packetId as number) < 1 || (packetId as number) > MMTP_PACKET_ID_MAX) {
+						catalogError("multicast_packet_id", `${refPath}.packetId`, `packetId must be an integer from 1 to ${MMTP_PACKET_ID_MAX}`);
+					}
+					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",
+		);
+	}
+
+	validateArchive(catalog);
+
+	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 };
+}