@blockcast/mmt-transport 0.2.2 → 0.3.0

package/dist/multicast-catalog-policy.js

@@ -0,0 +1,660 @@
+import { normalizeCatalogEndpoints, } from "./multicast-signaling-reconciler.js";
+import { assertNoRetiredMulticastUrlParams, DEFAULT_AMT_RELAY_PORT, isMulticastTrackPacketId, isUsableMulticastEndpoint, isValidMulticastGroupAddress, } from "./endpoint-config.js";
+export function hasMulticastCatalogBaseline(catalog) {
+    const multicast = catalog?.multicast;
+    return normalizeCatalogEndpoints(catalog).length > 0 || Boolean(multicast?.groupAddress && multicast?.port);
+}
+export function hasUnicastMediaRenditions(catalog) {
+    return Object.keys(catalog?.video?.renditions ?? {}).length > 0 ||
+        Object.keys(catalog?.audio?.renditions ?? {}).length > 0;
+}
+export function isMulticastOnlyCatalog(catalog) {
+    return hasMulticastCatalogBaseline(catalog) && !hasUnicastMediaRenditions(catalog);
+}
+export function requiresMulticastCapability(catalog, capabilities = {}) {
+    return isMulticastOnlyCatalog(catalog) && !capabilities.multicast;
+}
+export function isRecoverableMulticastSignalReadError(error) {
+    const candidate = error;
+    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, endpoints, version) {
+    if (!catalog?.multicast)
+        return catalog;
+    return {
+        ...catalog,
+        multicast: {
+            ...catalog.multicast,
+            version,
+            endpoints: endpoints.map(copyEndpoint),
+        },
+    };
+}
+export function selectMulticastCandidate(catalog, endpoints = normalizeCatalogEndpoints(catalog), search = currentSearchParams()) {
+    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, endpoints = normalizeCatalogEndpoints(catalog), selection = {}) {
+    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, catalog, selection) {
+    if (!endpoint || !isUsableMulticastEndpoint(endpoint) || advertisesInvalidPacketId(endpoint))
+        return null;
+    const config = {
+        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, catalog, search = currentSearchParams()) {
+    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, catalog, selection = {}) {
+    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) => ({
+        name: typeof track?.name === "string" ? track.name : "",
+        packetId: validPacketId(track?.packetId),
+    }))
+        .filter((track) => 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 !== 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 = currentSearchParams()) {
+    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 = {
+        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) {
+    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, b) {
+    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, urlConfig = readPlayerMulticastConfig()) {
+    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, urlConfig = readPlayerMulticastConfig()) {
+    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() {
+    return typeof location === "undefined" ?
+        new URLSearchParams() :
+        new URLSearchParams(location.search);
+}
+function positivePort(value) {
+    const port = Number(value);
+    return Number.isInteger(port) && port > 0 && port <= 65535 ? port : null;
+}
+function copyEndpoint(endpoint) {
+    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) {
+    const sources = Array.isArray(networkSource) ? networkSource : networkSource ? [networkSource] : [];
+    return sources.filter((entry) => entry?.type === "amt").map((entry) => ({ ...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) {
+    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) {
+    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) {
+    return Array.isArray(endpoint.tracks) && endpoint.tracks.some((track) => track?.packetId !== undefined && !isMulticastTrackPacketId(track.packetId));
+}
+function normalizePacketIds(packetIds) {
+    if (!Array.isArray(packetIds))
+        return [];
+    return [...new Set(packetIds.map(validPacketId).filter((id) => id !== undefined))].sort((a, b) => a - b);
+}
+function matchesPreferredTrack(trackName, preferredTrack) {
+    return trackName === preferredTrack || trackName.startsWith(`${preferredTrack}/`);
+}
+function catalogRenditions(catalog, role) {
+    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) {
+    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 = 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, name) {
+    assertNoRetiredTrackFields(catalog);
+    const tracks = Array.isArray(catalog?.tracks) ? catalog.tracks : [];
+    const track = tracks.find((candidate) => 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();
+    if (typeof fec.repairTrack === "string" && fec.repairTrack.length > 0)
+        names.add(fec.repairTrack);
+    const dependsOn = (entry) => 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) {
+    assertNoRetiredTrackFields(catalog);
+    const names = new Set();
+    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, endpoint) {
+    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, endpoints = normalizeCatalogEndpoints(catalog)) {
+    return endpoints.map(endpoint => {
+        const tier = {
+            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.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, role = "video") {
+    return Object.entries(catalogRenditions(catalog, role)).map(([name, config]) => {
+        const { bitrate, codedWidth, codedHeight, framerate } = (config ?? {});
+        if (!isPositiveFinite(bitrate)) {
+            throw new RangeError(`[ABR] catalog ${role} rendition ${name} states no positive bitrate to cost it by`);
+        }
+        const rung = { 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) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+function videoRenditionRank(config, name) {
+    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, endpoints) {
+    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, name);
+        if (!selected || rank < selectedRank) {
+            selected = name;
+            selectedRank = rank;
+        }
+    }
+    return selected;
+}
+//# sourceMappingURL=multicast-catalog-policy.js.map