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

package/src/multicast-input.ts

@@ -0,0 +1,793 @@
+// Module-local ambient: `multicastFromEnv` reads `process.env` when present
+// (Node, FFI host) and falls back to `{}` in browser contexts. The package
+// targets both, so we don't pull in `@types/node` org-wide — declaring the
+// minimal surface we touch keeps the dependency graph tight and the
+// published .d.ts free of node-isms.
+declare const process: { env: Record<string, string | undefined> } | undefined;
+
+/**
+ * Multicast catalog input contract — validator + builder.
+ *
+ * Per draft-ramadan-moq-multicast-00 §3 + §4.1, the publisher (FFmpeg,
+ * cast bridge, GStreamer, OBS-bridge) populates `multicast.endpoints[]`
+ * in the catalog when its output includes a UDP multicast destination.
+ *
+ * This module is the TypeScript-side validator over a versioned input
+ * shape. Sister-language validators (FFmpeg C, cast Rust) target the
+ * same invariants — eventually via a shared JSON Schema + fixtures
+ * (BLO-3341 follow-up); today parity is enforced by code review against
+ * 1:1 ports. Each publisher's integration MUST also assert that the
+ * declared `(sourceAddress, groupAddress, port)` matches what it
+ * actually emits — that's a separate runtime check the helper cannot
+ * perform.
+ *
+ * Validation invariants (per codex review of BLO-3323 v2):
+ *   - protocol === 'ssm' → sourceAddress REQUIRED
+ *   - protocol === 'amt' → a catalog-level `multicast.networkSource` entry of
+ *     type "amt" REQUIRED; its `relay` is required only for
+ *     `discovery: "manual"` ("driad" resolves the relay at runtime).
+ *     A per-endpoint `relayAddress` input is LIFTED into that entry and is
+ *     never emitted onto the endpoint.
+ *   - protocol === 'atsc3' → a catalog-level `multicast.networkSource` entry of
+ *     type "atsc3" REQUIRED; it carries the frequency, PLP, service id and SLS
+ *     URI, which is the only tuning information an ATSC3 receiver has.
+ *   - protocol === 'ssm' | 'asm' → no `networkSource` entry required: a native
+ *     join describes no alternate bearer (BLO-37926).
+ *   - groupAddress is a valid IPv4 multicast group (224.0.0.0/4)
+ *     or IPv6 multicast group (ff00::/8)
+ *   - SSM groupAddress MUST be in 232.0.0.0/8 (IPv4) or ff3x::/32 (IPv6),
+ *     where the IPv6 form requires P=1 + T=1 (the `3` nibble) AND the
+ *     16-bit reserved-zero second hextet per RFC 3306 §4 / RFC 4607.
+ *   - port in 1..65535
+ *   - tracks non-empty; per-track packetId in 1..65535
+ *   - packetId 0 (`MMTP_SIGNALING_PACKET_ID`) is the MMTP signaling flow
+ *     (FFmpeg `moq_mmt` sends the AL-FEC message 0x0203 on it into the same
+ *     multicast group) and is refused for a track with its own kind,
+ *     `signaling_packet_id`. The kind string matches cast's
+ *     `multicast_input.rs` so the two ports report the same reason.
+ *   - packetIds unique within an endpoint
+ *   - (sourceAddress, groupAddress, port) tuple unique across endpoints
+ *   - bandwidth (if present) > 0
+ *   - validUntil (if present) is a positive unix-ms timestamp
+ *
+ * @see draft-ramadan-moq-multicast-00 §4.1
+ * @see .planning/drafts/blo-3323-multicast-catalog-source-of-truth.md
+ */
+
+import { MMTP_PACKET_ID_MAX, MMTP_SIGNALING_PACKET_ID } from "@blockcast/mmt-base";
+import {
+	type AmtDiscovery,
+	type MulticastCatalogConfig,
+	type MulticastEndpoint,
+	type MulticastProtocol,
+	type MulticastTrackObject,
+	type NetworkSource,
+} from "./carp-catalog.js";
+
+/**
+ * Strict typed input for one multicast endpoint. The publisher provides
+ * this shape (env vars / CLI / config record), the helper validates and
+ * lifts it into a `MulticastEndpoint` ready to embed in the catalog.
+ */
+export interface MulticastEndpointInput {
+	readonly protocol: MulticastProtocol;
+	readonly sourceAddress?: string;
+	readonly groupAddress: string;
+	readonly port: number;
+	/** New emitters MUST use the object form (name + packetId). */
+	readonly tracks: ReadonlyArray<MulticastTrackObject>;
+	/**
+	 * AMT relay for this endpoint.
+	 *
+	 * Publisher-side input only — it is LIFTED into the catalog-level
+	 * `multicast.networkSource` and is never written onto the emitted endpoint
+	 * (the normative endpoint model carries no relay field). Because
+	 * `networkSource` is catalog-level, a relay that differs from the catalog's
+	 * AMT relay cannot be expressed and is rejected with `conflicting_amt_relay`.
+	 *
+	 * Prefer declaring `MulticastInput.networkSource` directly.
+	 */
+	readonly relayAddress?: string;
+	/** Aggregate bandwidth in bits per second. RECOMMENDED per draft §4.1. */
+	readonly bandwidth?: number;
+}
+
+/**
+ * Strict typed input for the catalog-level multicast extension.
+ *
+ * `version` (monotonic) + `validUntil` (unix ms) support the catalog
+ * freshness model: subscribers refetch before expiry, and publishers
+ * MUST republish (with bumped `version`) on any endpoint mutation.
+ */
+export interface MulticastInput {
+	readonly enabled?: boolean;
+	readonly endpoints: ReadonlyArray<MulticastEndpointInput>;
+	/**
+	 * Canonical relay/tuning declaration (draft-ramadan-moq-multicast §4.1).
+	 * When omitted, one is derived from `amtFallback` and any endpoint
+	 * `relayAddress`; when present no derivation happens. Either way every entry
+	 * is validated, and an endpoint `relayAddress` it does not carry is
+	 * rejected (`conflicting_amt_relay`). Omit it entirely for native
+	 * multicast: it describes alternate bearers only (BLO-37926).
+	 */
+	readonly networkSource?: ReadonlyArray<NetworkSource>;
+	/** @deprecated Lifted into `networkSource`; no longer emitted. */
+	readonly amtFallback?: { readonly discovery: AmtDiscovery; readonly relayDns?: string };
+	readonly version?: number;
+	readonly validUntil?: number;
+}
+
+export type MulticastInputErrorKind =
+	| "empty_endpoints"
+	/**
+	 * `endpoints` was not an array at all. Distinct from `empty_endpoints`,
+	 * which reports a well-formed array that declares nothing: a caller
+	 * handling these programmatically needs "you passed the wrong shape"
+	 * apart from "you passed nothing".
+	 */
+	| "invalid_endpoints"
+	| "ssm_requires_source"
+	/**
+	 * Deliberately overloaded, unlike its one-site mirror
+	 * `atsc3_requires_tuning`: an AMT relay can be missing at two layers, and
+	 * both mean "this endpoint names a relay nobody can reach". Raised for an
+	 * `amt` endpoint with no `networkSource` entry of type `"amt"`, and for an
+	 * entry whose `discovery: "manual"` names no `relay`. Splitting them would
+	 * make callers handle two kinds for one operator-visible fault.
+	 */
+	| "amt_requires_relay"
+	/**
+	 * An `atsc3` endpoint with no `networkSource` entry of type `"atsc3"`. The
+	 * ATSC3 entry carries the frequency, PLP, service id and SLS URI — the only
+	 * tuning information there is — so without it the endpoint names a broadcast
+	 * nobody can tune to. The AMT mirror of this is `amt_requires_relay`; native
+	 * joins ("ssm", "asm") describe no bearer and are exempt (BLO-37926).
+	 */
+	| "atsc3_requires_tuning"
+	/**
+	 * An endpoint `relayAddress` is not the relay of any AMT `networkSource`
+	 * entry (another endpoint's relay, `amtFallback.relayDns`, or an explicit
+	 * entry won). `networkSource` is catalog-level, so per-endpoint relays
+	 * cannot be represented; fail closed rather than silently drop one.
+	 */
+	| "conflicting_amt_relay"
+	/**
+	 * A `networkSource` AMT entry's `discovery` was not `"driad"` or `"manual"`,
+	 * the schema enum. Checked on explicit and derived entries alike.
+	 */
+	| "invalid_amt_discovery"
+	/**
+	 * A `networkSource` entry the schema rejects: unknown `type`, a key outside
+	 * its `type`'s shape, a blank `relay`, or an out-of-range ATSC3 field.
+	 */
+	| "invalid_network_source"
+	| "invalid_group_address"
+	| "ssm_group_out_of_range"
+	| "invalid_port"
+	| "empty_tracks"
+	| "invalid_track_name"
+	| "invalid_packet_id"
+	/**
+	 * A track advertised on `MMTP_SIGNALING_PACKET_ID` (0), the MMTP signaling
+	 * flow. Distinct from `invalid_packet_id` so the reason is legible: 0 is a
+	 * well-formed 16-bit value, it is just not a track's to claim.
+	 */
+	| "signaling_packet_id"
+	| "duplicate_packet_id"
+	| "duplicate_endpoint_tuple"
+	| "invalid_bandwidth"
+	| "invalid_valid_until"
+	| "invalid_version"
+	| "invalid_env_shape";
+
+export class MulticastInputError extends Error {
+	constructor(
+		public readonly kind: MulticastInputErrorKind,
+		public readonly endpointIndex: number | null,
+		message: string,
+	) {
+		super(message);
+		this.name = "MulticastInputError";
+	}
+}
+
+/**
+ * Validate a typed publisher input and lift it into a
+ * `MulticastCatalogConfig` ready for `catalog.multicast = …`.
+ *
+ * Throws `MulticastInputError` on any invariant violation. Fail-fast
+ * at config-load time, never at runtime — silent fallbacks hide bugs
+ * upstream (per the project's "no anti-patterns" directive).
+ */
+export function multicastFromConfig(input: MulticastInput): MulticastCatalogConfig {
+	// Both array-valued inputs are checked here, before anything indexes them.
+	// These helpers are consumed out-of-tree from plain JS (see
+	// `validateNetworkSourceEntry`), so the declared types are no guarantee —
+	// and object-instead-of-array is the likely mistake on both: `amtFallback`,
+	// which `networkSource` replaces, was a bare object. Without these a wrong
+	// shape escapes as a raw `TypeError` from `.map`, which a caller catching
+	// `MulticastInputError` does not catch.
+	if (!Array.isArray(input.endpoints)) {
+		throw new MulticastInputError(
+			"invalid_endpoints",
+			null,
+			`endpoints must be an array of endpoint objects; got ${typeof input.endpoints}`,
+		);
+	}
+	if (input.networkSource !== undefined && !Array.isArray(input.networkSource)) {
+		throw new MulticastInputError(
+			"invalid_network_source",
+			null,
+			"networkSource must be an array of entries; got " +
+				`${typeof input.networkSource} — a single entry still goes in a one-element array`,
+		);
+	}
+	if (input.endpoints.length === 0) {
+		throw new MulticastInputError(
+			"empty_endpoints",
+			null,
+			"endpoints[] must be non-empty — a multicast field with zero endpoints declares nothing",
+		);
+	}
+	if (input.version !== undefined && (!Number.isInteger(input.version) || input.version < 0)) {
+		throw new MulticastInputError("invalid_version", null, `version must be a non-negative integer; got ${input.version}`);
+	}
+	if (input.validUntil !== undefined) {
+		if (!Number.isFinite(input.validUntil) || input.validUntil <= 0) {
+			throw new MulticastInputError(
+				"invalid_valid_until",
+				null,
+				`validUntil must be a positive unix-ms timestamp; got ${input.validUntil}`,
+			);
+		}
+	}
+
+	const seenTuples = new Set<string>();
+	const endpoints: MulticastEndpoint[] = input.endpoints.map((ep, idx) => validateEndpoint(ep, idx, seenTuples));
+
+	const out: MulticastCatalogConfig = { endpoints };
+	const { entries: networkSource, relayFrom } = resolveNetworkSource(input);
+	// Checked on the resolved array, so an explicit `input.networkSource` gets
+	// exactly the same checks as one derived from the deprecated inputs.
+	networkSource.forEach(validateNetworkSourceEntry);
+	if (networkSource.length > 0) out.networkSource = networkSource;
+
+	// A relay the emitted catalog would not carry fails closed, on both paths:
+	// `networkSource` is catalog-level, so a per-endpoint relay that differs from
+	// it (another endpoint's, `amtFallback.relayDns`, or an explicit entry) would
+	// otherwise be dropped silently and that endpoint joins the wrong relay.
+	//
+	// A DRIAD entry does not count: both readers skip it, so its `relay` is a
+	// discovery hint, not a relay the catalog carries. Without this the derived
+	// path merges `amtFallback: {discovery: "driad"}` with an endpoint's
+	// `relayAddress` into a driad entry holding that relay, the check passes, and
+	// the join silently falls through to DRIAD -- where the explicit form of the
+	// same input already fails closed here.
+	const amtRelays = new Set(
+		networkSource
+			.flatMap((s) => (s.type === "amt" && s.discovery !== "driad" && s.relay?.trim() ? [s.relay.trim()] : []))
+			// Only the first, because it is the only one either reader can
+			// deliver: `catalogAmtNetworkSource` returns on it and `findAmtRelay`
+			// uses `.find`. Collecting every entry accepts an endpoint naming a
+			// second manual entry, which then joins the first -- the same silent
+			// wrong-relay join this guard exists to prevent, through the one
+			// shape the DRIAD filter does not cover. It also keeps the `(...)`
+			// listing below honest. Sliced rather than `.find`ed so the `amt`
+			// narrowing stays inside the callback.
+			.slice(0, 1),
+	);
+	input.endpoints.forEach((ep, idx) => {
+		const relay = ep.relayAddress?.trim();
+		if (!relay || amtRelays.has(relay)) return;
+		// Two different causes reach this throw and they need different fixes.
+		// If a DRIAD entry carries this exact relay, the catalog is not missing
+		// it -- the entry is present and demoted, so reporting the set as
+		// "(none)" sends the operator looking for an entry they already wrote.
+		// Name the demotion and the two-entry shape that escapes it; both
+		// readers take the first non-DRIAD AMT entry
+		// (`catalog-network-source.ts` `catalogAmtNetworkSource`,
+		// `multicast-catalog-policy.ts` `findAmtRelay`) and
+		// `validateNetworkSourceEntry` has no duplicate-type rule, so a manual
+		// entry beside the DRIAD one is joined while the DRIAD one is kept.
+		const demoted = networkSource.some(
+			(s) => s.type === "amt" && s.discovery === "driad" && s.relay?.trim() === relay,
+		);
+		// Same "written down but undeliverable" family as `demoted`, different
+		// reason and so a different fix: there the entry is skipped for its
+		// discovery, here for its position. Reachable only on the explicit
+		// path -- `resolveNetworkSource` emits at most one entry -- so there is
+		// no provenance clause to add, and saying "is not the relay of any AMT
+		// entry" here would be plainly false: the operator can see the entry.
+		// `amtRelays` holds only the first joinable relay, so reaching this
+		// throw at all already means this one is not it.
+		const shadowed = networkSource.some(
+			(s) => s.type === "amt" && s.discovery !== "driad" && s.relay?.trim() === relay,
+		);
+		// The derived and env paths never wrote `networkSource` at all -- it was
+		// synthesised below in `resolveNetworkSource` -- so naming only that key
+		// would name the one field the operator did not set. This applies to
+		// EVERY cause that reaches this throw, not just the demoted one: the
+		// clause belongs in the shared prefix, or the arm that omits it
+		// reproduces the misdiagnosis the other arm was written to fix.
+		//
+		// The two arms are about different values, so they name different
+		// fields. The demoted arm is about `discovery`: a derived entry is only
+		// `"driad"` when `amtFallback.discovery` said so (the default is
+		// `"manual"`), so `amtFallback` is always the actionable field there.
+		// The set clause is about the *relay*, which `resolveNetworkSource`
+		// takes from `amtFallback.relayDns` or from the endpoint
+		// `relayAddress` values -- and saying "amtFallback" to an operator who
+		// never wrote one is the same defect one level down. Read that source
+		// from `relayFrom` rather than re-inferring it: three review rounds
+		// found a local re-inference here drifting from the rule above it.
+		const derived = input.networkSource === undefined;
+		const fromAmtFallback = ", derived from amtFallback/MOQCAST_MULTICAST_AMT_*";
+		const fromRelay =
+			relayFrom === "amtFallback.relayDns"
+				? fromAmtFallback
+				: relayFrom === "endpoint.relayAddress"
+					? ", derived from the endpoint relayAddress values"
+					: "";
+		// `resolveNetworkSource` lets `relayDns` outrank an endpoint relay, so on
+		// the derived path the set can be non-empty and still not hold this
+		// relay. Blaming per-endpoint representation there is wrong twice over:
+		// there may be only one endpoint, and the field that actually won is
+		// `relayDns`, which is the one the operator can act on. Asking
+		// `amtRelays` instead would miss the case where the winning entry is
+		// `discovery: "driad"` and so filtered out of that set entirely.
+		const relayDns = input.amtFallback?.relayDns?.trim();
+		const outranked = relayFrom === "amtFallback.relayDns" && relayDns !== relay;
+		throw new MulticastInputError(
+			"conflicting_amt_relay",
+			idx,
+			`endpoint[${idx}] relayAddress ${JSON.stringify(relay)} ` +
+				(demoted
+					? `is carried only by a multicast.networkSource AMT entry with discovery="driad"` +
+						`${derived ? fromAmtFallback : ""}, ` +
+						"whose relay is a DRIAD discovery hint that both readers skip, so the catalog names " +
+						"no relay to join; to join it, add a manual entry beside the driad one: " +
+						`[{type:"amt",discovery:"manual",relay:${JSON.stringify(relay)}},{type:"amt",discovery:"driad"}]`
+					: shadowed
+						? `is carried by a multicast.networkSource AMT entry that is not the first one: ` +
+							`both readers join the first AMT entry (${[...amtRelays].join(", ")}) and ignore ` +
+							"the rest, so this relay is never joined; keep a single AMT entry, or put this one first"
+						: `is not the relay of any multicast.networkSource AMT entry ` +
+							`(${[...amtRelays].join(", ") || "none"})${fromRelay}; ` +
+							(outranked
+								? `amtFallback.relayDns/MOQCAST_MULTICAST_AMT_RELAY_DNS (${relayDns}) outranks an ` +
+									"endpoint relay when networkSource is derived -- drop one, or make them agree"
+								: "networkSource is catalog-level and cannot represent per-endpoint relays")),
+		);
+	});
+
+	// A bearer endpoint must name its bearer. The two bearer protocols are
+	// exactly the two `networkSource` types, so an endpoint's own protocol names
+	// the entry it requires. Native joins ("ssm", "asm") describe no bearer and
+	// are exempt (BLO-37926) — the endpoint tuple is the whole join.
+	// Whether an AMT entry needs a relay string ("manual" does, "driad" does
+	// not) is per-entry, checked above.
+	input.endpoints.forEach((ep, idx) => {
+		if (ep.protocol !== "amt" && ep.protocol !== "atsc3") return;
+		if (networkSource.some((s) => s.type === ep.protocol)) return;
+		throw new MulticastInputError(
+			ep.protocol === "amt" ? "amt_requires_relay" : "atsc3_requires_tuning",
+			idx,
+			`endpoint[${idx}] protocol=${ep.protocol} requires a multicast.networkSource entry of ` +
+				`type "${ep.protocol}"` +
+				(ep.protocol === "atsc3"
+					? " carrying frequency, plpId, serviceId and slsUri — an ATSC3 endpoint is not tunable without them"
+					: ""),
+		);
+	});
+
+	if (input.enabled !== undefined) out.enabled = input.enabled;
+	if (input.version !== undefined) out.version = input.version;
+	if (input.validUntil !== undefined) out.validUntil = input.validUntil;
+	return out;
+}
+
+/**
+ * Build the catalog-level `multicast.networkSource` for this input.
+ *
+ * An explicit `input.networkSource` is authoritative and used as given.
+ * Otherwise one AMT entry is derived from the deprecated inputs it replaces:
+ * `amtFallback.discovery`/`relayDns` and any endpoint `relayAddress`;
+ * `discovery` defaults to `"manual"` because a relay named in the catalog is,
+ * by definition, not discovered. Endpoint relays that disagree with the result
+ * are rejected by `multicastFromConfig`, not resolved here.
+ *
+ * `relayFrom` reports which deprecated input supplied the derived relay, so
+ * that rejection can name a field the operator actually set instead of
+ * re-deciding the precedence below at the throw site. It is `null` on the
+ * explicit path and when no relay was derived at all.
+ */
+function resolveNetworkSource(input: MulticastInput): {
+	entries: NetworkSource[];
+	relayFrom: "amtFallback.relayDns" | "endpoint.relayAddress" | null;
+} {
+	if (input.networkSource !== undefined) {
+		return { entries: input.networkSource.map((s) => ({ ...s })), relayFrom: null };
+	}
+
+	const relayDns = input.amtFallback?.relayDns?.trim();
+	const relay = relayDns || input.endpoints.map((ep) => ep.relayAddress?.trim()).find((r) => !!r);
+	const discovery = input.amtFallback?.discovery ?? (relay ? "manual" : undefined);
+	if (discovery === undefined) return { entries: [], relayFrom: null };
+	return {
+		entries: [{ type: "amt", discovery, ...(relay ? { relay } : {}) }],
+		relayFrom: !relay ? null : relayDns ? "amtFallback.relayDns" : "endpoint.relayAddress",
+	};
+}
+
+const AMT_SOURCE_KEYS = new Set(["type", "discovery", "relay", "port"]);
+const ATSC3_SOURCE_KEYS = new Set(["type", "frequency", "plpId", "serviceId", "slsUri"]);
+
+/**
+ * One `networkSource[]` entry against `catalog.schema.json` `$defs/networkSource`
+ * (and moq-rs `NetworkSource`), plus the one semantic rule the schema leaves
+ * out: `discovery: "manual"` names its relay. These helpers are consumed
+ * out-of-tree from plain JS, so the `NetworkSource` type is no guarantee.
+ */
+function validateNetworkSourceEntry(s: NetworkSource, i: number): void {
+	const err = (kind: MulticastInputErrorKind, why: string) =>
+		new MulticastInputError(kind, null, `networkSource[${i}] ${why}`);
+	const keys = s?.type === "amt" ? AMT_SOURCE_KEYS : s?.type === "atsc3" ? ATSC3_SOURCE_KEYS : undefined;
+	if (!keys) throw err("invalid_network_source", `type must be "amt" or "atsc3"; got ${JSON.stringify(s?.type)}`);
+	// Definedness, not presence: `isMulticastCatalogConfig` in `carp-catalog.ts`
+	// already chose `=== undefined` over `in` for exactly this reason, and the
+	// two must agree on what "set" means. A key spread in as `undefined`
+	// (`{...entry, relayDns: undefined}`) is dropped by `JSON.stringify`, so the
+	// emitted catalog is clean and rejecting it would fail a shape that ships
+	// correctly.
+	const extra = Object.keys(s).filter((k) => !keys.has(k) && (s as Record<string, unknown>)[k] !== undefined);
+	if (extra.length > 0) throw err("invalid_network_source", `has keys the schema rejects: ${extra.join(", ")}`);
+
+	if (s.type === "amt") {
+		if (s.discovery !== "driad" && s.discovery !== "manual") {
+			throw err("invalid_amt_discovery", `discovery must be "driad" or "manual"; got ${JSON.stringify(s.discovery)}`);
+		}
+		if (s.relay !== undefined) {
+			// Canonicalize, don't just check: the conflict guard in
+			// `multicastFromConfig` compares `.trim()`ed values, so a padded
+			// explicit relay would pass the guard and then ship padded. The
+			// derived path (`resolveNetworkSource`) already trims, so trimming
+			// here is what makes both paths emit the same canonical string.
+			// Entries are copies by then, so this cannot mutate caller input.
+			const relay = typeof s.relay === "string" ? s.relay.trim() : "";
+			if (!relay) {
+				throw err("invalid_network_source", `relay must be non-blank when present; got ${JSON.stringify(s.relay)}`);
+			}
+			s.relay = relay;
+		}
+		if (s.discovery === "manual" && s.relay === undefined) {
+			throw err("amt_requires_relay", `discovery="manual" requires a relay ("driad" resolves it at runtime)`);
+		}
+		if (s.port !== undefined && (!Number.isInteger(s.port) || s.port < 1 || s.port > 65535)) {
+			throw err("invalid_port", `port must be 1..65535; got ${s.port}`);
+		}
+		return;
+	}
+	const inRange = (v: number, min: number, max: number) => Number.isInteger(v) && v >= min && v <= max;
+	if (!inRange(s.frequency, 1, Number.MAX_SAFE_INTEGER)) {
+		throw err("invalid_network_source", `frequency must be a positive integer; got ${s.frequency}`);
+	}
+	if (!inRange(s.plpId, 0, 63)) throw err("invalid_network_source", `plpId must be 0..63; got ${s.plpId}`);
+	if (!inRange(s.serviceId, 0, 65535)) {
+		throw err("invalid_network_source", `serviceId must be 0..65535; got ${s.serviceId}`);
+	}
+	if (typeof s.slsUri !== "string" || !isAbsoluteUri(s.slsUri)) {
+		throw err("invalid_network_source", `slsUri must be an absolute URI; got ${JSON.stringify(s.slsUri)}`);
+	}
+}
+
+function isAbsoluteUri(value: string): boolean {
+	try {
+		new URL(value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function validateEndpoint(
+	ep: MulticastEndpointInput,
+	idx: number,
+	seenTuples: Set<string>,
+): MulticastEndpoint {
+	if (ep.protocol === "ssm" && (!ep.sourceAddress || ep.sourceAddress.length === 0)) {
+		throw new MulticastInputError(
+			"ssm_requires_source",
+			idx,
+			`endpoint[${idx}] protocol=ssm requires sourceAddress`,
+		);
+	}
+	// NOTE: `protocol: "amt"` no longer requires a per-endpoint relay here. The
+	// relay is catalog-level (`multicast.networkSource`), which this function
+	// cannot see; `multicastFromConfig` enforces it once both halves are in hand.
+
+	if (!isMulticastGroupAddress(ep.groupAddress)) {
+		throw new MulticastInputError(
+			"invalid_group_address",
+			idx,
+			`endpoint[${idx}] groupAddress "${ep.groupAddress}" is not a valid multicast address`,
+		);
+	}
+	if (ep.protocol === "ssm" && !isSsmGroupAddress(ep.groupAddress)) {
+		throw new MulticastInputError(
+			"ssm_group_out_of_range",
+			idx,
+			`endpoint[${idx}] protocol=ssm requires groupAddress in 232.0.0.0/8 (IPv4) or ff3x::/32 (IPv6); got "${ep.groupAddress}"`,
+		);
+	}
+
+	if (!Number.isInteger(ep.port) || ep.port < 1 || ep.port > 65535) {
+		throw new MulticastInputError("invalid_port", idx, `endpoint[${idx}] port must be 1..65535; got ${ep.port}`);
+	}
+
+	if (ep.tracks.length === 0) {
+		throw new MulticastInputError("empty_tracks", idx, `endpoint[${idx}] tracks must be non-empty`);
+	}
+
+	const seenPids = new Set<number>();
+	for (const t of ep.tracks) {
+		if (typeof t.name !== "string" || t.name.length === 0) {
+			throw new MulticastInputError(
+				"invalid_track_name",
+				idx,
+				`endpoint[${idx}] track name must be a non-empty string`,
+			);
+		}
+		if (t.packetId === MMTP_SIGNALING_PACKET_ID) {
+			throw new MulticastInputError(
+				"signaling_packet_id",
+				idx,
+				`endpoint[${idx}] track "${t.name}" packetId ${t.packetId} is the MMTP signaling flow ` +
+					`and must not be advertised for a track; packetId must be 1..${MMTP_PACKET_ID_MAX}`,
+			);
+		}
+		if (!Number.isInteger(t.packetId) || t.packetId < 1 || t.packetId > MMTP_PACKET_ID_MAX) {
+			throw new MulticastInputError(
+				"invalid_packet_id",
+				idx,
+				`endpoint[${idx}] track "${t.name}" packetId must be 1..${MMTP_PACKET_ID_MAX}; got ${t.packetId}`,
+			);
+		}
+		if (seenPids.has(t.packetId)) {
+			throw new MulticastInputError(
+				"duplicate_packet_id",
+				idx,
+				`endpoint[${idx}] duplicate packetId ${t.packetId}`,
+			);
+		}
+		seenPids.add(t.packetId);
+	}
+
+	if (ep.bandwidth !== undefined && (!Number.isFinite(ep.bandwidth) || ep.bandwidth <= 0)) {
+		throw new MulticastInputError(
+			"invalid_bandwidth",
+			idx,
+			`endpoint[${idx}] bandwidth must be positive; got ${ep.bandwidth}`,
+		);
+	}
+
+	const tupleKey = `${ep.sourceAddress ?? ""}|${ep.groupAddress}|${ep.port}`;
+	if (seenTuples.has(tupleKey)) {
+		throw new MulticastInputError(
+			"duplicate_endpoint_tuple",
+			idx,
+			`endpoint[${idx}] duplicates (sourceAddress, groupAddress, port) tuple "${tupleKey}"`,
+		);
+	}
+	seenTuples.add(tupleKey);
+
+	const out: MulticastEndpoint = {
+		protocol: ep.protocol,
+		groupAddress: ep.groupAddress,
+		port: ep.port,
+		tracks: ep.tracks.map((t) => ({ name: t.name, packetId: t.packetId })),
+	};
+	if (ep.sourceAddress !== undefined) out.sourceAddress = ep.sourceAddress;
+	// `relayAddress` is deliberately NOT copied: the relay is lifted to
+	// catalog-level `multicast.networkSource` by `multicastFromConfig`.
+	if (ep.bandwidth !== undefined) out.bandwidth = ep.bandwidth;
+	return out;
+}
+
+function isMulticastGroupAddress(addr: string): boolean {
+	if (addr.includes(":")) {
+		// IPv6: ff00::/8. Prefix-only check; full IPv6 syntax validation
+		// is delegated to the OS bind() call downstream.
+		return /^ff[0-9a-f]{2}:/i.test(addr);
+	}
+	const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(addr);
+	if (!m) return false;
+	for (let i = 1; i <= 4; i++) {
+		const v = Number(m[i]);
+		if (!Number.isInteger(v) || v < 0 || v > 255) return false;
+	}
+	const first = Number(m[1]);
+	return first >= 224 && first <= 239;
+}
+
+function isSsmGroupAddress(addr: string): boolean {
+	if (addr.includes(":")) {
+		// SSM IPv6: ff3x::/32 per RFC 3306 §4. Requires P=1 + T=1 (the `3`
+		// nibble) AND the second 16-bit hextet to be all-zero (RFC 3306's
+		// "prefix length = 0" → next 32 bits are 0). The regex matches
+		// `ff3?:0000:` collapsed forms (`ff3e::`, `ff3e:0::`, `ff3e:0:`,
+		// `ff3e:0000:`) and rejects `ff3e:beef::1` etc.
+		return /^ff3[0-9a-f]:0{0,4}:/i.test(addr);
+	}
+	const m = /^(\d{1,3})\./.exec(addr);
+	return m !== null && Number(m[1]) === 232;
+}
+
+// Env-var helper (BLO-3337): read MOQCAST_MULTICAST_* keys and route
+// through multicastFromConfig so all per-endpoint invariants apply.
+
+/**
+ * Read `MOQCAST_MULTICAST_*` env vars and return a
+ * `MulticastCatalogConfig`. Returns `undefined` when no per-endpoint
+ * key is set.
+ *
+ * Env contract — per-endpoint keys take an optional non-negative index:
+ *
+ *   MOQCAST_MULTICAST[_<idx>]_PROTOCOL=ssm
+ *   MOQCAST_MULTICAST[_<idx>]_GROUP=232.1.1.1
+ *   MOQCAST_MULTICAST[_<idx>]_PORT=5004
+ *   MOQCAST_MULTICAST[_<idx>]_SOURCE=10.0.0.20      (required for ssm)
+ *   MOQCAST_MULTICAST[_<idx>]_RELAY=amt.example.com (required for amt)
+ *   MOQCAST_MULTICAST[_<idx>]_TRACKS=video:1,audio:3
+ *   MOQCAST_MULTICAST[_<idx>]_BANDWIDTH=8000000     (optional, bps)
+ *
+ *   MOQCAST_MULTICAST_AMT_DISCOVERY=driad           (catalog-level)
+ *   MOQCAST_MULTICAST_AMT_RELAY_DNS=relay.example.com (catalog-level)
+ *
+ * The unindexed form (`MOQCAST_MULTICAST_GROUP`) is exactly index 0;
+ * mixing it with explicit `_0_` keys is rejected as ambiguous. Indices
+ * need not be contiguous; observed indices are sorted ascending.
+ */
+export function multicastFromEnv(
+	env: Record<string, string | undefined> = ((globalThis as { process?: { env?: Record<string, string | undefined> } })
+		.process?.env ?? {}) as Record<string, string | undefined>,
+): MulticastCatalogConfig | undefined {
+	const indices = collectMulticastIndices(env);
+	// An empty value is unset: `FOO=${BAR}` with BAR unset, or an empty
+	// configMap value, is a templating outcome, not a setting. Normalising
+	// here gives every test below one notion of "set". Stricter than SOURCE
+	// and RELAY, which gate on truthiness alone and so keep a whitespace-only
+	// value — deliberately, as these two decide whether AMT is declared at all.
+	const amtDiscovery = env["MOQCAST_MULTICAST_AMT_DISCOVERY"]?.trim() || undefined;
+	const amtRelayDns = env["MOQCAST_MULTICAST_AMT_RELAY_DNS"]?.trim() || undefined;
+	// One predicate, both guards: a key significant enough to reject at zero
+	// endpoints is not silently discarded once endpoints are present.
+	const hasCatalogAmt = amtDiscovery !== undefined || amtRelayDns !== undefined;
+	if (indices.length === 0) {
+		// Catalog-level AMT keys without per-endpoint keys is a
+		// misconfiguration, not a no-op: `MOQCAST_MULTICAST_AMT_DISCOVERY`
+		// only makes sense alongside endpoints to fall back FOR. Throw
+		// loudly instead of silently dropping the request — a publisher
+		// that meant to declare AMT fallback shouldn't have its config
+		// disappear without any signal.
+		if (hasCatalogAmt) {
+			throw new MulticastInputError(
+				"invalid_env_shape",
+				null,
+				"MOQCAST_MULTICAST_AMT_* env keys are set but no per-endpoint keys " +
+					"(MOQCAST_MULTICAST_GROUP / _PROTOCOL / _PORT / _TRACKS) were found. " +
+					"AMT discovery is a catalog-level fallback for endpoints; declaring it " +
+					"with zero endpoints is a misconfiguration.",
+			);
+		}
+		return undefined;
+	}
+
+	const endpoints: MulticastEndpointInput[] = indices.map((idx) => readEndpointAt(env, idx));
+
+	const input: MulticastInput = {
+		endpoints,
+		...(hasCatalogAmt
+			? {
+					amtFallback: {
+						// `"manual"` mirrors `resolveNetworkSource`: a relay named in
+						// the catalog is, by definition, not discovered.
+						discovery: (amtDiscovery ?? "manual") as AmtDiscovery,
+						...(amtRelayDns ? { relayDns: amtRelayDns } : {}),
+					},
+				}
+			: {}),
+	};
+	return multicastFromConfig(input);
+}
+
+const ENV_PER_FIELD = ["PROTOCOL", "GROUP", "PORT", "SOURCE", "RELAY", "TRACKS", "BANDWIDTH"];
+const ENV_CATALOG_LEVEL = new Set(["AMT_DISCOVERY", "AMT_RELAY_DNS"]);
+
+function collectMulticastIndices(env: Record<string, string | undefined>): number[] {
+	const indices = new Set<number>();
+	let hasUnindexed = false;
+	let hasZeroIndexed = false;
+
+	for (const [key, val] of Object.entries(env)) {
+		if (val === undefined) continue;
+		if (!key.startsWith("MOQCAST_MULTICAST_")) continue;
+		const suffix = key.slice("MOQCAST_MULTICAST_".length);
+		if (ENV_CATALOG_LEVEL.has(suffix)) continue;
+
+		const m = /^(\d+)_(.+)$/.exec(suffix);
+		if (m) {
+			const idx = Number(m[1]);
+			const field = m[2];
+			if (!ENV_PER_FIELD.includes(field)) continue;
+			if (idx === 0) hasZeroIndexed = true;
+			indices.add(idx);
+		} else if (ENV_PER_FIELD.includes(suffix)) {
+			hasUnindexed = true;
+			indices.add(0);
+		}
+	}
+
+	if (hasUnindexed && hasZeroIndexed) {
+		throw new MulticastInputError(
+			"invalid_env_shape",
+			null,
+			"MOQCAST_MULTICAST_* env contract: cannot mix unindexed keys (MOQCAST_MULTICAST_GROUP) " +
+				"with explicitly-indexed keys at index 0 (MOQCAST_MULTICAST_0_GROUP) — they refer to " +
+				"the same endpoint. Use one form consistently.",
+		);
+	}
+
+	return [...indices].sort((a, b) => a - b);
+}
+
+function readEndpointAt(env: Record<string, string | undefined>, idx: number): MulticastEndpointInput {
+	const lookup = (field: string): string | undefined => {
+		if (idx === 0) {
+			return env[`MOQCAST_MULTICAST_${field}`] ?? env[`MOQCAST_MULTICAST_0_${field}`];
+		}
+		return env[`MOQCAST_MULTICAST_${idx}_${field}`];
+	};
+
+	const portStr = lookup("PORT");
+	const port = portStr !== undefined ? Number(portStr) : NaN;
+	const tracks = parseTracksEnv(lookup("TRACKS"), idx);
+	const bandwidthStr = lookup("BANDWIDTH");
+	const bandwidth = bandwidthStr !== undefined ? Number(bandwidthStr) : undefined;
+	const source = lookup("SOURCE");
+	const relay = lookup("RELAY");
+
+	return {
+		protocol: lookup("PROTOCOL") as MulticastProtocol,
+		groupAddress: lookup("GROUP") ?? "",
+		port,
+		tracks,
+		...(source ? { sourceAddress: source } : {}),
+		...(relay ? { relayAddress: relay } : {}),
+		...(bandwidth !== undefined ? { bandwidth } : {}),
+	};
+}
+
+function parseTracksEnv(raw: string | undefined, endpointIdx: number): MulticastTrackObject[] {
+	if (!raw || raw.length === 0) return [];
+	return raw.split(",").map((entry, i) => {
+		const colon = entry.lastIndexOf(":");
+		if (colon < 0) {
+			throw new MulticastInputError(
+				"invalid_track_name",
+				endpointIdx,
+				`endpoint[${endpointIdx}] TRACKS[${i}] missing ":" — expected "name:packetId", got ${JSON.stringify(entry)}`,
+			);
+		}
+		const name = entry.slice(0, colon).trim();
+		const idStr = entry.slice(colon + 1).trim();
+		const packetId = Number(idStr);
+		if (!name || idStr.length === 0 || !Number.isFinite(packetId) || !Number.isInteger(packetId)) {
+			throw new MulticastInputError(
+				"invalid_packet_id",
+				endpointIdx,
+				`endpoint[${endpointIdx}] TRACKS[${i}] entry malformed (need "name:integer"): ${JSON.stringify(entry)}`,
+			);
+		}
+		return { name, packetId };
+	});
+}