@blockcast/mmt-transport 0.2.2 → 0.3.0

package/src/multicast-catalog-policy.ts

@@ -0,0 +1,753 @@
+import {
+	normalizeCatalogEndpoints,
+	type MulticastSignalingEndpoint,
+} from "./multicast-signaling-reconciler.js";
+import {
+	assertNoRetiredMulticastUrlParams,
+	DEFAULT_AMT_RELAY_PORT,
+	isMulticastTrackPacketId,
+	isUsableMulticastEndpoint,
+	isValidMulticastGroupAddress,
+} from "./endpoint-config.js";
+import type { MulticastTierEndpoint } from "./multicast-tier.js";
+import type { QualityLevel } from "./types.js";
+
+type Catalog = Record<string, any>;
+
+export interface PlayerMulticastConfig {
+	group: string;
+	source: string;
+	port: number;
+	mode?: string;
+	amtRelay?: string;
+	amtRelayPort?: number;
+	amtNetworkSource?: unknown;
+	packetIds?: number[];
+}
+
+export interface MulticastTrackSelection {
+	containerKind?: string;
+	rendition?: string;
+}
+
+export function hasMulticastCatalogBaseline(catalog: Catalog): boolean {
+	const multicast = catalog?.multicast;
+	return normalizeCatalogEndpoints(catalog).length > 0 || Boolean(multicast?.groupAddress && multicast?.port);
+}
+
+export function hasUnicastMediaRenditions(catalog: Catalog): boolean {
+	return Object.keys(catalog?.video?.renditions ?? {}).length > 0 ||
+		Object.keys(catalog?.audio?.renditions ?? {}).length > 0;
+}
+
+export function isMulticastOnlyCatalog(catalog: Catalog): boolean {
+	return hasMulticastCatalogBaseline(catalog) && !hasUnicastMediaRenditions(catalog);
+}
+
+export function requiresMulticastCapability(
+	catalog: Catalog,
+	capabilities: { multicast?: boolean } = {},
+): boolean {
+	return isMulticastOnlyCatalog(catalog) && !capabilities.multicast;
+}
+
+export function isRecoverableMulticastSignalReadError(error: unknown): boolean {
+	const candidate = error as { name?: unknown; message?: unknown } | null;
+	const name = String(candidate?.name ?? "");
+	const message = String(candidate?.message ?? error ?? "");
+	return name === "SyntaxError" ||
+		/not valid JSON|unexpected token|JSON\.parse|encoded data was not valid|malformed/i.test(message);
+}
+
+export function withMulticastEndpoints(
+	catalog: Catalog,
+	endpoints: MulticastSignalingEndpoint[],
+	version: number,
+): Catalog {
+	if (!catalog?.multicast) return catalog;
+	return {
+		...catalog,
+		multicast: {
+			...catalog.multicast,
+			version,
+			endpoints: endpoints.map(copyEndpoint),
+		},
+	};
+}
+
+export function selectMulticastCandidate(
+	catalog: Catalog,
+	endpoints = normalizeCatalogEndpoints(catalog),
+	search: string | URLSearchParams = currentSearchParams(),
+): MulticastSignalingEndpoint | null {
+	const params = search instanceof URLSearchParams ? search : new URLSearchParams(search);
+	return selectMulticastCandidateForTracks(catalog, endpoints, {
+		containerKind: params.get("packaging") || params.get("container") || "mmtp",
+		rendition: params.get("rendition") || undefined,
+	});
+}
+
+export function selectMulticastCandidateForTracks(
+	catalog: Catalog,
+	endpoints = normalizeCatalogEndpoints(catalog),
+	selection: MulticastTrackSelection = {},
+): MulticastSignalingEndpoint | null {
+	const packaging = selection.containerKind || "mmtp";
+	const renditionTrack = selection.rendition || "";
+	const preferredTrack = packaging === "mmtp" ? "video" : `video.${packaging}`;
+	const usableEndpoints = endpoints.filter(isUsableMulticastEndpoint);
+	const defaultRenditionTrack = renditionTrack ? "" : lowestServedVideoRendition(catalog, usableEndpoints);
+	return (renditionTrack && usableEndpoints.find(endpoint =>
+		endpoint.tracks?.some(track => matchesPreferredTrack(track.name, renditionTrack)))) ||
+		(defaultRenditionTrack && usableEndpoints.find(endpoint =>
+			endpoint.tracks?.some(track => matchesPreferredTrack(track.name, defaultRenditionTrack)))) ||
+		usableEndpoints.find(endpoint =>
+			endpoint.tracks?.some(track => matchesPreferredTrack(track.name, preferredTrack))) ||
+		usableEndpoints[0] || null;
+}
+
+export function endpointToMulticastConfig(
+	endpoint: MulticastSignalingEndpoint | Record<string, any> | null | undefined,
+	catalog: Catalog,
+	selection?: MulticastTrackSelection,
+): PlayerMulticastConfig | null {
+	if (!endpoint || !isUsableMulticastEndpoint(endpoint) || advertisesInvalidPacketId(endpoint)) return null;
+	const config: PlayerMulticastConfig = {
+		group: endpoint.groupAddress,
+		source: endpoint.sourceAddress || "",
+		port: Number(endpoint.port),
+	};
+	const networkSource = endpoint.networkSource ?? catalog?.multicast?.networkSource;
+	const amt = findAmtRelay(networkSource);
+	if (amt) {
+		config.mode = "tunnel";
+		config.amtRelay = amt.relay;
+		config.amtRelayPort = amt.port;
+	} else if (endpoint.protocol === "amt") {
+		// AMT is wanted and no relay resolved. `mode: "tunnel"` would be
+		// unsatisfiable: `toWindowMulticastSubscribeConfig` refuses tunnel with
+		// no relay by design, and `MulticastTransport.join` swallows that throw
+		// into a plain `false` indistinguishable from a gateway failure
+		// (BLO-38184). Carry the AMT entries instead, as the relay-pending
+		// state: a caller that can resolve DRIAD has the DNS name to resolve,
+		// one that cannot joins native and can still see AMT was asked for. The
+		// entries are carried, not a flag, because a DRIAD entry's own `relay`
+		// is that DNS name and a boolean would discard it.
+		//
+		// The carry is deliberately scoped to `protocol === "amt"` while the
+		// dialable branch above is not: a resolved relay is dialable whatever
+		// the endpoint claims, but a *pending* one is a statement of intent,
+		// and the endpoint's own protocol is where that intent is declared.
+		// Widening this to match the branch above would have the reader assert
+		// AMT intent for an endpoint that never claimed it.
+		//
+		// Only `type: "amt"` entries ride along, and only if there are any:
+		// `findAmtRelay` also returns undefined for the tolerant bare form
+		// (`{type: "amt"}`, no relay) and for a `networkSource` carrying no AMT
+		// entry at all, so an unfiltered carry would populate an `amt*` field
+		// with a payload holding zero AMT entries.
+		const amtEntries = amtNetworkSourceEntries(networkSource);
+		if (amtEntries.length > 0) config.amtNetworkSource = amtEntries;
+	}
+	const packetIds = selection === undefined ?
+		selectEndpointPacketIds(endpoint, catalog) :
+		selectEndpointPacketIdsForTracks(endpoint, catalog, selection);
+	if (packetIds === null) return null;
+	if (packetIds.length > 0) config.packetIds = packetIds;
+	return config;
+}
+
+export function selectEndpointPacketIds(
+	endpoint: MulticastSignalingEndpoint | Record<string, any> | null | undefined,
+	catalog: Catalog,
+	search: string | URLSearchParams = currentSearchParams(),
+): number[] | null {
+	const params = search instanceof URLSearchParams ? search : new URLSearchParams(search);
+	return selectEndpointPacketIdsForTracks(endpoint, catalog, {
+		containerKind: params.get("packaging") || params.get("container") || "mmtp",
+		rendition: params.get("rendition") || undefined,
+	});
+}
+
+export function selectEndpointPacketIdsForTracks(
+	endpoint: MulticastSignalingEndpoint | Record<string, any> | null | undefined,
+	catalog: Catalog,
+	selection: MulticastTrackSelection = {},
+): number[] | null {
+	if (!endpoint || !Array.isArray(endpoint.tracks)) return [];
+	// An empty result means "no packet_id filter" to the join, so an invalid
+	// packet_id must fail here rather than be dropped: dropping the only track
+	// would widen the filter to every packet_id, the signaling flow included.
+	// null ("this endpoint is unusable") matches endpointToMulticastConfig on
+	// the same input, and the widened return type is the signal to callers.
+	if (advertisesInvalidPacketId(endpoint)) return null;
+	const tracks = endpoint.tracks
+		.map((track: any) => ({
+			name: typeof track?.name === "string" ? track.name : "",
+			packetId: validPacketId(track?.packetId),
+		}))
+		.filter((track: { name: string; packetId?: number }): track is { name: string; packetId: number } =>
+			track.name.length > 0 && track.packetId !== undefined);
+	if (tracks.length === 0) return [];
+
+	const packaging = selection.containerKind || "mmtp";
+	const renditionTrack = selection.rendition || "";
+	const videoRenditions = catalogRenditions(catalog, "video");
+	const audioRenditions = catalogRenditions(catalog, "audio");
+	const videoTracks = tracks.filter(track => Object.hasOwn(videoRenditions, track.name));
+	const audioTracks = tracks.filter(track => Object.hasOwn(audioRenditions, track.name));
+	const preferredVideo = packaging === "mmtp" ? "video" : `video.${packaging}`;
+	const preferredAudio = packaging === "mmtp" ? "audio" : `audio.${packaging}`;
+	const video =
+		(renditionTrack ? videoTracks.find(track => track.name === renditionTrack) : undefined) ??
+		videoTracks.find(track => track.name === preferredVideo) ??
+		[...videoTracks].sort((a, b) =>
+			videoRenditionRank(videoRenditions, a.name) - videoRenditionRank(videoRenditions, b.name))[0];
+	const audio = audioTracks.find(track => track.name === preferredAudio) ?? audioTracks[0];
+	const selected = [video, audio].filter(
+		(track): track is { name: string; packetId: number } => track !== undefined,
+	);
+	if (selected.length === 0) return normalizePacketIds(tracks.map(track => track.packetId));
+
+	// Every repair layer and overlay of a selected track is a repair track of
+	// that track (draft-ramadan-moq-fec §6.3), so a layer listed on the endpoint
+	// is selected alongside layer 0 rather than treated as unknown.
+	const selectedRepairNames = new Set(selected.flatMap(track => catalogRepairTracks(catalog, track.name)));
+	const selectedRepairTracks = tracks.filter(track => selectedRepairNames.has(track.name));
+	return normalizePacketIds([...selected, ...selectedRepairTracks].map(track => track.packetId));
+}
+
+/** Read the player's explicit multicast override from `mc_*` URL parameters.
+ *  Throws when an override carries a retired unprefixed alias
+ *  (`assertNoRetiredMulticastUrlParams`). */
+export function readPlayerMulticastConfig(
+	search: string | URLSearchParams = currentSearchParams(),
+): PlayerMulticastConfig | null {
+	const params = search instanceof URLSearchParams ? search : new URLSearchParams(search || "");
+	const group = params.get("mc_group") || "";
+	if (!isValidMulticastGroupAddress(group)) return null;
+	const port = positivePort(params.get("mc_port"));
+	if (!port) return null;
+	assertNoRetiredMulticastUrlParams(params);
+	const mode = params.get("mc_mode") || "";
+	const amtRelay = params.get("mc_amt_relay") || "";
+	const amtRelayPort = positivePort(params.get("mc_amt_relay_port"));
+	const config: PlayerMulticastConfig = {
+		group,
+		source: params.get("mc_source") || "",
+		port,
+	};
+	if (mode) config.mode = mode;
+	if (amtRelay) {
+		config.amtRelay = amtRelay;
+		// Trimmed for the DECISION only, matching `dialableRelay` in
+		// `normalizeMulticastConfig`. `?mc_amt_relay=%20%20` is not a relay, and
+		// stamping `tunnel` here outlives that trim: `normalizeMulticastConfig`
+		// only FORCES `tunnel` when the relay is dialable, and otherwise
+		// PRESERVES whatever `mode` arrived — so a blank override set here turns
+		// a DRIAD catalog's native join into a boundary throw (BLO-38184).
+		if (amtRelay.trim()) config.mode = "tunnel";
+	}
+	if (amtRelayPort) config.amtRelayPort = amtRelayPort;
+	return config;
+}
+
+export function normalizeMulticastConfig(
+	config: Partial<PlayerMulticastConfig> | null | undefined,
+): PlayerMulticastConfig | null {
+	if (!config?.group) return null;
+	// A join list naming an invalid packet_id is refused whole: dropping the
+	// entry could leave the list empty, which the join reads as "no filter".
+	if (Array.isArray(config.packetIds) && !config.packetIds.every(isMulticastTrackPacketId)) return null;
+	const amt = findAmtRelay(config.amtNetworkSource);
+	const amtRelay = config.amtRelay || amt?.relay || "";
+	// Blank is no relay for every decision below, matching the other two readers
+	// and the `input.amtRelay?.trim()` the consumer re-derives. `amtRelay` is
+	// kept verbatim in the output — only what we DECIDE from it is trimmed.
+	// `amtRelay` already coalesces to `""`, so this needs no `?.`.
+	const dialableRelay = amtRelay.trim();
+	// Same RFC 7450 default as `findAmtRelay`, applied to a relay from ANY source
+	// (URL override, player config) rather than only the catalog-derived one.
+	// Two spellings of one port-less relay must normalize alike or
+	// `sameMulticastConfig` reports a change that is not there, and a caller
+	// naming `amtRelay` alone would still reach the join with no port. An
+	// unusable explicit port (0, NaN) falls through to the same default.
+	// Only the DEFAULT is gated on the relay. An explicit `amtRelayPort` is
+	// caller data and passes through whatever the relay looks like, since
+	// dropping it would be the worse behaviour — the same rule
+	// `MulticastManager.join` states. Gating it here too would collapse two
+	// blank-relay configs naming different ports to one `undefined`, hiding a
+	// change `sameMulticastConfig` used to report. The catalog's `amt.port` is
+	// the opposite case and is dropped deliberately: a whitespace-only
+	// `amtRelay` override still wins the `||` in `amtRelay` above, shadowing the
+	// catalog relay, and that relay's port goes with it rather than shipping a
+	// port for a relay nobody will dial.
+	const amtRelayPort = positivePort(String(config.amtRelayPort ?? "")) ??
+		(dialableRelay ? (amt?.port ?? DEFAULT_AMT_RELAY_PORT) : undefined);
+	const packetIds = normalizePacketIds(config.packetIds);
+	// The same `type: "amt"` filter the catalog reader applies. This is the
+	// other public entry point onto the field (a player may hand-build a config
+	// rather than derive one from a catalog), and `amtNetworkSource` is typed
+	// `unknown`, so without it a caller could still land a zero-AMT payload
+	// under an `amt*` name — the shape the reader refuses one function up.
+	// Gated on `dialableRelay`, not bare truthiness: a whitespace-only override
+	// is not a relay, so it must not erase the pending entries one hop before
+	// the join (BLO-38184). Bare truthiness dropped them AND forced
+	// `mode: "tunnel"` below, and the pair throws in `endpoint-config.ts` —
+	// turning "joins native" back into "never".
+	const pendingAmt = dialableRelay ? [] : amtNetworkSourceEntries(config.amtNetworkSource);
+	return {
+		group: config.group,
+		source: config.source || "",
+		port: Number(config.port),
+		mode: dialableRelay ? "tunnel" : (config.mode || "auto"),
+		amtRelay,
+		...(amtRelayPort ? { amtRelayPort } : {}),
+		// Relay-pending DRIAD survives normalization while it is still pending:
+		// dropping it here would erase, one hop before the join, the only thing
+		// telling the call site "AMT was asked for and is unresolved" apart from
+		// "this endpoint was always native" (BLO-38184). Once a relay resolves
+		// the entries have done their job and are not carried. `amtNetworkSource`
+		// is deliberately not part of `sameMulticastConfig`: it is provenance for
+		// the relay, not endpoint identity, so it must not report a change.
+		//
+		// That holds only while no caller acts on the field — today a pending
+		// DRIAD entry and a native endpoint both join `ip-multicast`, so
+		// comparing equal reports the truth. Once a caller resolves DRIAD and
+		// tunnels, a catalog swapping native for DRIAD-AMT becomes a real
+		// join-behaviour change that would compare equal and never re-join:
+		// whoever wires that resolution adds `amtNetworkSource` to
+		// `sameMulticastConfig` in the same change.
+		...(pendingAmt.length > 0 ? { amtNetworkSource: pendingAmt } : {}),
+		...(packetIds.length > 0 ? { packetIds } : {}),
+	};
+}
+
+export function sameMulticastConfig(
+	a: Partial<PlayerMulticastConfig> | null | undefined,
+	b: Partial<PlayerMulticastConfig> | null | undefined,
+): boolean {
+	const left = normalizeMulticastConfig(a);
+	const right = normalizeMulticastConfig(b);
+	return Boolean(left && right &&
+		left.group === right.group &&
+		left.source === right.source &&
+		left.port === right.port &&
+		left.mode === right.mode &&
+		left.amtRelay === right.amtRelay &&
+		(left.amtRelayPort ?? 0) === (right.amtRelayPort ?? 0) &&
+		JSON.stringify(left.packetIds ?? []) === JSON.stringify(right.packetIds ?? []));
+}
+
+/** An omitted `urlConfig` is read from `location.search` by
+ *  `readPlayerMulticastConfig`, which throws on a retired unprefixed alias
+ *  inside an override. */
+export function urlOverrideBlocksMulticastCandidate(
+	candidateConfig: Partial<PlayerMulticastConfig> | null | undefined,
+	urlConfig: PlayerMulticastConfig | null = readPlayerMulticastConfig(),
+): boolean {
+	if (!urlConfig) return false;
+	const candidate = normalizeMulticastConfig(candidateConfig);
+	const explicit = normalizeMulticastConfig(urlConfig);
+	return !candidate || !explicit ||
+		candidate.group !== explicit.group ||
+		candidate.source !== explicit.source ||
+		candidate.port !== explicit.port;
+}
+
+/** Preserve catalog track selection while applying explicit URL transport policy.
+ *  An omitted `urlConfig` is read from `location.search` by
+ *  `readPlayerMulticastConfig`, which throws on a retired unprefixed alias
+ *  inside an override. */
+export function mergeUrlMulticastPolicy(
+	candidateConfig: Partial<PlayerMulticastConfig> | null | undefined,
+	urlConfig: PlayerMulticastConfig | null = readPlayerMulticastConfig(),
+): PlayerMulticastConfig | null {
+	const candidate = normalizeMulticastConfig(candidateConfig);
+	if (!candidate || !urlConfig || urlOverrideBlocksMulticastCandidate(candidate, urlConfig)) return candidate;
+
+	const merged = { ...candidate };
+	if (urlConfig.mode !== undefined) {
+		merged.mode = urlConfig.mode;
+		if (urlConfig.mode !== "tunnel" && urlConfig.amtRelay === undefined) {
+			merged.amtRelay = "";
+			delete merged.amtRelayPort;
+			// Relay-pending DRIAD is an AMT signal like the two above, so an
+			// explicit non-tunnel mode clears it too. Keeping it would leave a
+			// caller that resolves DRIAD holding the DNS name it needs to
+			// tunnel, against a user who just asked for native — the field
+			// saying "AMT was asked for" outliving the instruction overriding
+			// it. Inert today for the same reason `sameMulticastConfig` can
+			// omit the field; whoever wires DRIAD resolution makes it load-
+			// bearing here and there at the same moment.
+			//
+			// The boundary is `!== "tunnel"`, not `=== "native"`, so `auto`
+			// rides along with native and clears — while an ABSENT `mc_mode`
+			// keeps the entries, though both normalize to `mode: "auto"` and
+			// are indistinguishable downstream. That is the shared boundary
+			// the two lines above already use, not a choice made here;
+			// `readPlayerMulticastConfig` applies no allowlist to `mc_mode`,
+			// so any unrecognized value clears too. Whether an explicit `auto`
+			// should override AMT intent is one question for all three lines,
+			// and it is the DRIAD-resolution follow-on's to answer.
+			delete merged.amtNetworkSource;
+		}
+	}
+	if (urlConfig.amtRelay !== undefined) {
+		merged.amtRelay = urlConfig.amtRelay;
+		// Whatever supplied `merged.amtRelayPort`, it was declared for the
+		// BASE-CONFIG relay, so it is shadowed along with that relay by ANY
+		// override — blank or not (BLO-38514). By here the first normalize has
+		// already made the three sources indistinguishable (a caller's explicit
+		// `candidateConfig.amtRelayPort`, the catalog's `amt.port`, and
+		// `DEFAULT_AMT_RELAY_PORT`), and all three drop. That is not in tension
+		// with `:274-283`, which preserves a caller's port against the relay it
+		// was named with; the rule here is different authorship, not provenance.
+		// Ungated on purpose: the blank branch below once owned this line on the
+		// reasoning "a port for a relay nobody will dial", and a non-blank
+		// override is the same shadowing with a worse outcome — it JOINS,
+		// dialing a host the user named on a port only the replaced host ever
+		// declared. A host swap therefore takes `DEFAULT_AMT_RELAY_PORT`
+		// (RFC 7450) from `normalizeMulticastConfig`, not the shadowed host's
+		// port. An explicit `?mc_amt_relay_port=` still wins, below.
+		delete merged.amtRelayPort;
+		// Same trim, same reason as `readPlayerMulticastConfig`. Fixing only one
+		// writer is not enough: `:363` copies `urlConfig.mode` across, and that
+		// mode is already `"tunnel"` from the other writer.
+		if (urlConfig.amtRelay.trim()) {
+			merged.mode = "tunnel";
+			// The delete above closes only ONE of the two port sources.
+			// `normalizeMulticastConfig` re-derives the port as
+			// `positivePort(amtRelayPort) ?? (dialableRelay ? (amt?.port ??
+			// DEFAULT) : undefined)`, and `amt` comes from `amtNetworkSource` —
+			// so a surviving entry naming a port puts the shadowed port straight
+			// back on the new host, which is BLO-38514 verbatim. The entries
+			// describe the relay this override just replaced; they are its
+			// provenance, and they are shadowed with it.
+			//
+			// Nothing is lost by dropping them here: `:297` already discards
+			// `amtNetworkSource` from the OUTPUT whenever the relay is dialable,
+			// which a non-blank override always is. This only stops them acting
+			// as a port source on the way through. Catalog-derived candidates
+			// are safe today for that same reason — `endpointToMulticastConfig`
+			// trims `amt.relay`, so the first normalize drops the entries before
+			// merge sees them — but that is an accident of the catalog path, not
+			// the invariant, and the DRIAD follow-on at `:305-320` retires it.
+			//
+			// Gated on `.trim()`: a blank override is not a relay, must not erase
+			// the pending entries one hop before the join (BLO-38184), and keeps
+			// them as the relay-pending residual the same follow-on resolves.
+			delete merged.amtNetworkSource;
+		}
+		else if (urlConfig.mode === undefined && candidate.amtRelay?.trim()) {
+			// The blank override shadows a DIALABLE catalog relay, and
+			// `candidate.mode` is the `"tunnel"` `normalizeMulticastConfig`
+			// DERIVED from that very relay — normalization output fed back in
+			// as input. The second normalize only ever FORCES `tunnel`, never
+			// clears it, so the derived mode outlives the relay it came from
+			// and the pair throws at the boundary (BLO-38415). Drop it with the
+			// relay. The catalog's port went with it one branch up, now for
+			// every override rather than only this one.
+			//
+			// Gated on an absent `urlConfig.mode`, because a user-asserted
+			// `?mc_mode=tunnel` is not derived from this relay and is not the
+			// caller's to discard — that stays the deliberate
+			// tunnel-with-no-resolved-relay refusal, alongside the relay-pending
+			// DRIAD residual. Gated on the CANDIDATE's relay being dialable,
+			// because only then is its `tunnel` derived; a catalog that named
+			// its own non-tunnel mode keeps it.
+			merged.mode = "auto";
+		}
+	}
+	if (urlConfig.amtRelayPort !== undefined) merged.amtRelayPort = urlConfig.amtRelayPort;
+	return normalizeMulticastConfig(merged);
+}
+
+function currentSearchParams(): URLSearchParams {
+	return typeof location === "undefined" ?
+		new URLSearchParams() :
+		new URLSearchParams(location.search);
+}
+
+function positivePort(value: string | null): number | null {
+	const port = Number(value);
+	return Number.isInteger(port) && port > 0 && port <= 65535 ? port : null;
+}
+
+function copyEndpoint(endpoint: MulticastSignalingEndpoint): MulticastSignalingEndpoint {
+	return { ...endpoint, tracks: endpoint.tracks.map(track => ({ ...track })) };
+}
+
+/** The `type: "amt"` entries of a `networkSource` (array or bare-object form),
+ *  in catalog order. Every reader of the field spells "which entries are AMT"
+ *  the same way here, so none of them can populate an `amt*` field with a
+ *  payload holding zero AMT entries — the two readers of one field must agree
+ *  (`catalogAmtNetworkSource` in `@blockcast/mmt-container` applies the same
+ *  rule). Entries are unfiltered by dialability: `findAmtRelay` decides which
+ *  of them is *dialable*, a narrower question than which of them is AMT.
+ *
+ *  Each entry is shallow-copied, for the same reason `copyEndpoint` copies:
+ *  these ride out in a returned config, and the catalog is not ours to hand
+ *  out references to. A DRIAD resolver writing its resolved relay back into
+ *  the entry it was handed would otherwise mutate the catalog in place — and
+ *  `sameMulticastConfig` deliberately omits this field, so that mutation
+ *  would be invisible to change detection. Primitives only, so one level is
+ *  the whole object. */
+function amtNetworkSourceEntries(networkSource: unknown): any[] {
+	const sources = Array.isArray(networkSource) ? networkSource : networkSource ? [networkSource] : [];
+	return sources.filter((entry: any) => entry?.type === "amt").map((entry: any) => ({ ...entry }));
+}
+
+// A `discovery: "driad"` entry's relay is a discovery hint, not a pinned
+// relay. The entry says "resolve this at runtime", so it must resolve exactly
+// as a relay-less DRIAD entry does: `amtRelay` unset, the relay left to
+// runtime discovery (`TransportManager.connectAmt`). The emitter produces that
+// shape (`amtFallback: {discovery: "driad", relayDns}` derives
+// `{type: "amt", discovery: "driad", relay}`), and before BLO-37834 this
+// reader never read `amtFallback` at all, so pinning that relay would turn a
+// catalog that asked for DRIAD into a manual join. An entry with no
+// `discovery` (the tolerant bare form) keeps its relay.
+function findAmtRelay(networkSource: unknown): { relay: string; port: number } | undefined {
+	const source = amtNetworkSourceEntries(networkSource).find(candidate =>
+		candidate?.discovery !== "driad" &&
+		typeof candidate?.relay === "string" && candidate.relay.trim());
+	if (!source) return undefined;
+	// A relay that names no port — or an unusable one — is reachable on the AMT
+	// well-known port (RFC 7450 §4). Resolving it here rather than at the
+	// `toWindowMulticastSubscribeConfig` boundary keeps that boundary's
+	// "no implicit relay-port default" rule: the port is explicit by the time a
+	// join is built. Without this every catalog carrying a relay and no port —
+	// which is every catalog migrated from `amtFallback.relayDns` or an endpoint
+	// `relayAddress`, the derived path emitting no port at all — reached that
+	// boundary portless and the join threw (BLO-38176).
+	const port = positivePort(String(source.port ?? ""));
+	return { relay: source.relay.trim(), port: port ?? DEFAULT_AMT_RELAY_PORT };
+}
+
+function validPacketId(value: unknown): number | undefined {
+	return isMulticastTrackPacketId(value) ? value : undefined;
+}
+
+/** True when some endpoint track advertises a `packetId` that is present but
+ *  not a valid track packet_id. A track that omits `packetId` (the legacy
+ *  string form) advertises none and is not invalid. */
+function advertisesInvalidPacketId(endpoint: { tracks?: unknown }): boolean {
+	return Array.isArray(endpoint.tracks) && endpoint.tracks.some((track: any) =>
+		track?.packetId !== undefined && !isMulticastTrackPacketId(track.packetId));
+}
+
+function normalizePacketIds(packetIds: unknown): number[] {
+	if (!Array.isArray(packetIds)) return [];
+	return [...new Set(packetIds.map(validPacketId).filter((id): id is number => id !== undefined))].sort(
+		(a, b) => a - b,
+	);
+}
+
+function matchesPreferredTrack(trackName: string, preferredTrack: string): boolean {
+	return trackName === preferredTrack || trackName.startsWith(`${preferredTrack}/`);
+}
+
+function catalogRenditions(catalog: Catalog, role: "video" | "audio"): Record<string, any> {
+	const renditions = { ...(catalog?.[role]?.renditions ?? {}) };
+	for (const track of Array.isArray(catalog?.tracks) ? catalog.tracks : []) {
+		if (track?.role === role && typeof track.name === "string" && track.name.length > 0) {
+			renditions[track.name] = track;
+		}
+	}
+	return renditions;
+}
+
+/** Reject catalog shapes whose repair classification this package cannot
+ *  derive. `commonTrackFields` (root) and `selectionParams` (per track) are
+ *  retired: every track now declares its own `packaging`. A legacy catalog that
+ *  marks its repair tracks only through `commonTrackFields.packaging` would
+ *  otherwise yield an empty repair set here, and every endpoint (repair-only
+ *  ones included) would classify as media. The container-side validator
+ *  (`validateCmsfMmtpCatalog`) rejects these keys too, but transport has no
+ *  dependency edge to it, so this layer must fail closed on its own. */
+function assertNoRetiredTrackFields(catalog: Catalog): void {
+	if (catalog && typeof catalog === "object" && "commonTrackFields" in catalog) {
+		throw new Error("multicast catalog policy: $.commonTrackFields is retired; every track must declare its own packaging");
+	}
+	const tracks: any[] = Array.isArray(catalog?.tracks) ? catalog.tracks : [];
+	tracks.forEach((track, index) => {
+		if (track && typeof track === "object" && "selectionParams" in track) {
+			throw new Error(`multicast catalog policy: $.tracks[${index}].selectionParams is retired; selection fields are flat on the track`);
+		}
+	});
+}
+
+/** Repair tracks a source track (or rendition) depends on for its FEC: layer 0
+ *  named by `fec.repairTrack`, then every self-describing repair track that
+ *  `depends` on it (MSF `tracks[]` entries with `packaging: "fec-repair"`, or
+ *  hang `repair.renditions` entries), per draft-ramadan-moq-fec §6.3. Names
+ *  carry no meaning: membership comes from the pointer and from `depends`,
+ *  never from a name suffix. Empty when the track carries no FEC, including
+ *  `fec.algorithm: "none"`, which the container-side derivations
+ *  (`carp-catalog` and `catalog-fec-params`) also read as no FEC. */
+function catalogRepairTracks(catalog: Catalog, name: string): string[] {
+	assertNoRetiredTrackFields(catalog);
+	const tracks: any[] = Array.isArray(catalog?.tracks) ? catalog.tracks : [];
+	const track = tracks.find((candidate: any) => candidate?.name === name);
+	const rendition = catalog?.video?.renditions?.[name] ?? catalog?.audio?.renditions?.[name];
+	const fec = track?.fec ?? rendition?.fec;
+	if (!fec || fec.algorithm === "none") return [];
+	const names = new Set<string>();
+	if (typeof fec.repairTrack === "string" && fec.repairTrack.length > 0) names.add(fec.repairTrack);
+	const dependsOn = (entry: any): boolean =>
+		Array.isArray(entry?.depends) && entry.depends.length === 1 && entry.depends[0] === name;
+	for (const candidate of tracks) {
+		const packaging = candidate?.packaging;
+		if (packaging === "fec-repair" && typeof candidate?.name === "string" && candidate.name.length > 0 && dependsOn(candidate)) {
+			names.add(candidate.name);
+		}
+	}
+	const repairRenditions = catalog?.repair?.renditions;
+	if (repairRenditions && typeof repairRenditions === "object") {
+		for (const [repairName, entry] of Object.entries(repairRenditions)) {
+			if (repairName.length > 0 && dependsOn(entry)) names.add(repairName);
+		}
+	}
+	return [...names];
+}
+
+/** Every self-describing repair track name in the catalog, in either dialect:
+ *  MSF `tracks[]` entries with `packaging: "fec-repair"` and hang
+ *  `repair.renditions` keys. A repair track describes itself, so membership
+ *  needs no source resolution and never comes from a name suffix. */
+function catalogRepairTrackNames(catalog: Catalog): Set<string> {
+	assertNoRetiredTrackFields(catalog);
+	const names = new Set<string>();
+	for (const track of Array.isArray(catalog?.tracks) ? catalog.tracks : []) {
+		const packaging = track?.packaging;
+		if (packaging === "fec-repair" && typeof track?.name === "string" && track.name.length > 0) {
+			names.add(track.name);
+		}
+	}
+	const repairRenditions = catalog?.repair?.renditions;
+	if (repairRenditions && typeof repairRenditions === "object") {
+		for (const name of Object.keys(repairRenditions)) {
+			if (name.length > 0) names.add(name);
+		}
+	}
+	return names;
+}
+
+/** True when an endpoint carries at least one track that is not a repair
+ *  track, i.e. it can serve media on its own. A repair-layer endpoint carries
+ *  only `fec-repair` tracks and is joined by the loss-driven layer policy, so
+ *  it must be excluded from the bandwidth ladder (`selectMulticastTier`).
+ *  An endpoint listing no tracks is treated as carrying media: that is the
+ *  pre-layer signalling shape, and a naming-era catalog with no repair tracks
+ *  declared classifies every endpoint as media.
+ *
+ *  Throws on a catalog carrying the retired `commonTrackFields` or per-track
+ *  `selectionParams`: repair membership cannot be derived from such a catalog,
+ *  and classifying it as all-media would make repair-only endpoints joinable. */
+export function endpointCarriesMedia(
+	catalog: Catalog,
+	endpoint: { tracks?: { name?: string }[] } | null | undefined,
+): boolean {
+	const tracks = endpoint?.tracks;
+	if (!Array.isArray(tracks) || tracks.length === 0) return true;
+	const repairNames = catalogRepairTrackNames(catalog);
+	if (repairNames.size === 0) return true;
+	return tracks.some(track => typeof track?.name === "string" && !repairNames.has(track.name));
+}
+
+/** Catalog signalling endpoints as bandwidth-ladder endpoints, classified.
+ *
+ *  Every ladder caller must build its `MulticastTierEndpoint[]` through this
+ *  rather than hand-shaping them from the catalog: `carriesMedia` is optional
+ *  and an unset one is treated as carrying media, so an endpoint that was
+ *  never classified stays selectable as a tier and joining it would leave the
+ *  receiver with repair symbols and no media. Classifying at the one place
+ *  endpoints are converted is what makes that impossible to forget.
+ *
+ *  `bandwidth` is carried through only when the endpoint declares a positive
+ *  finite number and is never synthesized, so an endpoint that omits it stays
+ *  unranked exactly as before. Only the fields the ladder reads are copied;
+ *  signalling-only keys stay behind. */
+export function catalogTierEndpoints(
+	catalog: Catalog,
+	endpoints: MulticastSignalingEndpoint[] = normalizeCatalogEndpoints(catalog),
+): MulticastTierEndpoint[] {
+	return endpoints.map(endpoint => {
+		const tier: MulticastTierEndpoint = {
+			groupAddress: endpoint.groupAddress,
+			port: Number(endpoint.port),
+			tracks: endpoint.tracks.map(track =>
+				track.packetId === undefined ? { name: track.name } : { name: track.name, packetId: track.packetId }),
+			carriesMedia: endpointCarriesMedia(catalog, endpoint),
+		};
+		if (endpoint.sourceAddress) tier.sourceAddress = endpoint.sourceAddress;
+		if (endpoint.protocol) tier.protocol = endpoint.protocol;
+		const bandwidth = (endpoint as Record<string, unknown>).bandwidth;
+		if (typeof bandwidth === "number" && Number.isFinite(bandwidth) && bandwidth > 0) tier.bandwidth = bandwidth;
+		return tier;
+	});
+}
+
+/** The ABR ladder a catalog advertises, for `TransportManager.connect()`'s
+ *  `abrLadder`: one rung per rendition of `role` (the role's `renditions` map
+ *  and any `tracks` entry with that role), named by its catalog track name
+ *  and costed at its catalog `bitrate`. `width`, `height` and `fps` are copied
+ *  from `codedWidth`, `codedHeight` and `framerate` only when the catalog
+ *  states them as positive numbers; none is defaulted. Rungs keep catalog
+ *  order; the ABR controller walks them by ascending bitrate.
+ *
+ *  Throws `RangeError` naming the first video rendition whose `bitrate` is not
+ *  a positive finite number. ABR costs measured throughput against each
+ *  rung's bitrate, so a rung without one cannot drive it, and the coded-size
+ *  or name rank `videoRenditionRank` falls back to orders renditions without
+ *  pricing them. A catalog that omits `bitrate` therefore has no ABR ladder:
+ *  have its publisher state one per rendition, or connect with a ladder of
+ *  only the renditions the caller can price. A catalog with no video
+ *  rendition yields an empty ladder, which `connect()` refuses. Pass `"audio"`
+ *  for an audio-only stream; the default is `"video"`. */
+export function catalogQualityLadder(catalog: Catalog, role: "video" | "audio" = "video"): QualityLevel[] {
+	return Object.entries(catalogRenditions(catalog, role)).map(([name, config]) => {
+		const { bitrate, codedWidth, codedHeight, framerate } = (config ?? {}) as Record<string, unknown>;
+		if (!isPositiveFinite(bitrate)) {
+			throw new RangeError(`[ABR] catalog ${role} rendition ${name} states no positive bitrate to cost it by`);
+		}
+		const rung: QualityLevel = { name, bitrate };
+		if (isPositiveFinite(codedWidth)) rung.width = codedWidth;
+		if (isPositiveFinite(codedHeight)) rung.height = codedHeight;
+		if (isPositiveFinite(framerate)) rung.fps = framerate;
+		return rung;
+	});
+}
+
+function isPositiveFinite(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+
+function videoRenditionRank(config: Record<string, any>, name: string): number {
+	if (typeof config?.bitrate === "number" && config.bitrate > 0) return config.bitrate;
+	const width = typeof config?.codedWidth === "number" ? config.codedWidth : 0;
+	const height = typeof config?.codedHeight === "number" ? config.codedHeight : 0;
+	if (width > 0 && height > 0) return width * height;
+	const match = /(?:^|[/_.-])(\d{3,4})p(?:$|[/_.-])/i.exec(name);
+	return match ? Number(match[1]) : Number.POSITIVE_INFINITY;
+}
+
+function lowestServedVideoRendition(
+	catalog: Catalog,
+	endpoints: MulticastSignalingEndpoint[],
+): string {
+	const renditions = catalog?.video?.renditions ?? {};
+	const servedTracks = new Set(endpoints.flatMap(endpoint =>
+		endpoint.tracks?.map(track => track.name) ?? []));
+	let selected = "";
+	let selectedRank = Number.POSITIVE_INFINITY;
+	for (const [name, config] of Object.entries(renditions)) {
+		if (!name || !servedTracks.has(name)) continue;
+		const rank = videoRenditionRank(config as Record<string, any>, name);
+		if (!selected || rank < selectedRank) {
+			selected = name;
+			selectedRank = rank;
+		}
+	}
+	return selected;
+}