@blockcast/mmt-container 0.1.0 → 0.3.0

package/dist/multicast-input.d.ts

@@ -0,0 +1,141 @@
+import { type AmtDiscovery, type MulticastCatalogConfig, 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 declare class MulticastInputError extends Error {
+    readonly kind: MulticastInputErrorKind;
+    readonly endpointIndex: number | null;
+    constructor(kind: MulticastInputErrorKind, endpointIndex: number | null, message: string);
+}
+/**
+ * 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 declare function multicastFromConfig(input: MulticastInput): MulticastCatalogConfig;
+/**
+ * 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 declare function multicastFromEnv(env?: Record<string, string | undefined>): MulticastCatalogConfig | undefined;
+//# sourceMappingURL=multicast-input.d.ts.map

package/dist/multicast-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multicast-input.d.ts","sourceRoot":"","sources":["../src/multicast-input.ts"],"names":[],"mappings":"AAyDA,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAE3B,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,MAAM,mBAAmB,CAAC;AAE3B;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC;IACrD;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAC;IAC1D;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC;IACtD,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;QAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,uBAAuB,GAChC,iBAAiB;AACnB;;;;;GAKG;GACD,mBAAmB,GACnB,qBAAqB;AACvB;;;;;;;GAOG;GACD,oBAAoB;AACtB;;;;;;GAMG;GACD,uBAAuB;AACzB;;;;;GAKG;GACD,uBAAuB;AACzB;;;GAGG;GACD,uBAAuB;AACzB;;;GAGG;GACD,wBAAwB,GACxB,uBAAuB,GACvB,wBAAwB,GACxB,cAAc,GACd,cAAc,GACd,oBAAoB,GACpB,mBAAmB;AACrB;;;;GAIG;GACD,qBAAqB,GACrB,qBAAqB,GACrB,0BAA0B,GAC1B,mBAAmB,GACnB,qBAAqB,GACrB,iBAAiB,GACjB,mBAAmB,CAAC;AAEvB,qBAAa,mBAAoB,SAAQ,KAAK;aAE5B,IAAI,EAAE,uBAAuB;aAC7B,aAAa,EAAE,MAAM,GAAG,IAAI;gBAD5B,IAAI,EAAE,uBAAuB,EAC7B,aAAa,EAAE,MAAM,GAAG,IAAI,EAC5C,OAAO,EAAE,MAAM;CAKhB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,cAAc,GAAG,sBAAsB,CAyLjF;AAiPD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAC/B,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CACqB,GACzD,sBAAsB,GAAG,SAAS,CAgDpC"}

package/dist/multicast-input.js

@@ -0,0 +1,390 @@
+// ../mmt-alta-parse/dist/index.js
+var MPU_HEADER_SIZE = 8;
+var MPU_LENGTH_FIELD_SIZE = 2;
+var MPU_HEADER_REMAINDER_SIZE = MPU_HEADER_SIZE - MPU_LENGTH_FIELD_SIZE;
+
+// ../mmt-base/dist/mmtp.js
+var MPU_HEADER_SIZE2 = 8;
+var MPU_LENGTH_FIELD_SIZE2 = 2;
+var MPU_HEADER_REMAINDER_SIZE2 = MPU_HEADER_SIZE2 - MPU_LENGTH_FIELD_SIZE2;
+var MMTP_SIGNALING_PACKET_ID = 0;
+var MMTP_PACKET_ID_MAX = 65535;
+
+// ../mmt-base/dist/ntp-short.js
+var NTP_SHORT_BITS = 32;
+var NTP_SHORT_MODULUS = 2 ** NTP_SHORT_BITS;
+var NTP_SHORT_HALF_RANGE = 2 ** (NTP_SHORT_BITS - 1);
+
+// ../mmt-base/dist/fec-block-profile.js
+var FEC_BLOCK_PROFILES = Object.freeze([
+  "k-padded-v1",
+  "iso-ssbg1-v1"
+]);
+
+// src/multicast-input.ts
+var MulticastInputError = class extends Error {
+  constructor(kind, endpointIndex, message) {
+    super(message);
+    this.kind = kind;
+    this.endpointIndex = endpointIndex;
+    this.name = "MulticastInputError";
+  }
+};
+function multicastFromConfig(input) {
+  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 !== void 0 && !Array.isArray(input.networkSource)) {
+    throw new MulticastInputError(
+      "invalid_network_source",
+      null,
+      `networkSource must be an array of entries; got ${typeof input.networkSource} \u2014 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 \u2014 a multicast field with zero endpoints declares nothing"
+    );
+  }
+  if (input.version !== void 0 && (!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 !== void 0) {
+    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 = /* @__PURE__ */ new Set();
+  const endpoints = input.endpoints.map((ep, idx) => validateEndpoint(ep, idx, seenTuples));
+  const out = { endpoints };
+  const { entries: networkSource, relayFrom } = resolveNetworkSource(input);
+  networkSource.forEach(validateNetworkSourceEntry);
+  if (networkSource.length > 0) out.networkSource = networkSource;
+  const amtRelays = new Set(
+    networkSource.flatMap((s) => s.type === "amt" && s.discovery !== "driad" && s.relay?.trim() ? [s.relay.trim()] : []).slice(0, 1)
+  );
+  input.endpoints.forEach((ep, idx) => {
+    const relay = ep.relayAddress?.trim();
+    if (!relay || amtRelays.has(relay)) return;
+    const demoted = networkSource.some(
+      (s) => s.type === "amt" && s.discovery === "driad" && s.relay?.trim() === relay
+    );
+    const shadowed = networkSource.some(
+      (s) => s.type === "amt" && s.discovery !== "driad" && s.relay?.trim() === relay
+    );
+    const derived = input.networkSource === void 0;
+    const fromAmtFallback = ", derived from amtFallback/MOQCAST_MULTICAST_AMT_*";
+    const fromRelay = relayFrom === "amtFallback.relayDns" ? fromAmtFallback : relayFrom === "endpoint.relayAddress" ? ", derived from the endpoint relayAddress values" : "";
+    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"))
+    );
+  });
+  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 \u2014 an ATSC3 endpoint is not tunable without them" : "")
+    );
+  });
+  if (input.enabled !== void 0) out.enabled = input.enabled;
+  if (input.version !== void 0) out.version = input.version;
+  if (input.validUntil !== void 0) out.validUntil = input.validUntil;
+  return out;
+}
+function resolveNetworkSource(input) {
+  if (input.networkSource !== void 0) {
+    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" : void 0);
+  if (discovery === void 0) return { entries: [], relayFrom: null };
+  return {
+    entries: [{ type: "amt", discovery, ...relay ? { relay } : {} }],
+    relayFrom: !relay ? null : relayDns ? "amtFallback.relayDns" : "endpoint.relayAddress"
+  };
+}
+var AMT_SOURCE_KEYS = /* @__PURE__ */ new Set(["type", "discovery", "relay", "port"]);
+var ATSC3_SOURCE_KEYS = /* @__PURE__ */ new Set(["type", "frequency", "plpId", "serviceId", "slsUri"]);
+function validateNetworkSourceEntry(s, i) {
+  const err = (kind, why) => new MulticastInputError(kind, null, `networkSource[${i}] ${why}`);
+  const keys = s?.type === "amt" ? AMT_SOURCE_KEYS : s?.type === "atsc3" ? ATSC3_SOURCE_KEYS : void 0;
+  if (!keys) throw err("invalid_network_source", `type must be "amt" or "atsc3"; got ${JSON.stringify(s?.type)}`);
+  const extra = Object.keys(s).filter((k) => !keys.has(k) && s[k] !== void 0);
+  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 !== void 0) {
+      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 === void 0) {
+      throw err("amt_requires_relay", `discovery="manual" requires a relay ("driad" resolves it at runtime)`);
+    }
+    if (s.port !== void 0 && (!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, min, max) => 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) {
+  try {
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function validateEndpoint(ep, idx, seenTuples) {
+  if (ep.protocol === "ssm" && (!ep.sourceAddress || ep.sourceAddress.length === 0)) {
+    throw new MulticastInputError(
+      "ssm_requires_source",
+      idx,
+      `endpoint[${idx}] protocol=ssm requires sourceAddress`
+    );
+  }
+  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 = /* @__PURE__ */ new Set();
+  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 !== void 0 && (!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 = {
+    protocol: ep.protocol,
+    groupAddress: ep.groupAddress,
+    port: ep.port,
+    tracks: ep.tracks.map((t) => ({ name: t.name, packetId: t.packetId }))
+  };
+  if (ep.sourceAddress !== void 0) out.sourceAddress = ep.sourceAddress;
+  if (ep.bandwidth !== void 0) out.bandwidth = ep.bandwidth;
+  return out;
+}
+function isMulticastGroupAddress(addr) {
+  if (addr.includes(":")) {
+    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) {
+  if (addr.includes(":")) {
+    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;
+}
+function multicastFromEnv(env = globalThis.process?.env ?? {}) {
+  const indices = collectMulticastIndices(env);
+  const amtDiscovery = env["MOQCAST_MULTICAST_AMT_DISCOVERY"]?.trim() || void 0;
+  const amtRelayDns = env["MOQCAST_MULTICAST_AMT_RELAY_DNS"]?.trim() || void 0;
+  const hasCatalogAmt = amtDiscovery !== void 0 || amtRelayDns !== void 0;
+  if (indices.length === 0) {
+    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 void 0;
+  }
+  const endpoints = indices.map((idx) => readEndpointAt(env, idx));
+  const input = {
+    endpoints,
+    ...hasCatalogAmt ? {
+      amtFallback: {
+        // `"manual"` mirrors `resolveNetworkSource`: a relay named in
+        // the catalog is, by definition, not discovered.
+        discovery: amtDiscovery ?? "manual",
+        ...amtRelayDns ? { relayDns: amtRelayDns } : {}
+      }
+    } : {}
+  };
+  return multicastFromConfig(input);
+}
+var ENV_PER_FIELD = ["PROTOCOL", "GROUP", "PORT", "SOURCE", "RELAY", "TRACKS", "BANDWIDTH"];
+var ENV_CATALOG_LEVEL = /* @__PURE__ */ new Set(["AMT_DISCOVERY", "AMT_RELAY_DNS"]);
+function collectMulticastIndices(env) {
+  const indices = /* @__PURE__ */ new Set();
+  let hasUnindexed = false;
+  let hasZeroIndexed = false;
+  for (const [key, val] of Object.entries(env)) {
+    if (val === void 0) 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) \u2014 they refer to the same endpoint. Use one form consistently."
+    );
+  }
+  return [...indices].sort((a, b) => a - b);
+}
+function readEndpointAt(env, idx) {
+  const lookup = (field) => {
+    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 !== void 0 ? Number(portStr) : NaN;
+  const tracks = parseTracksEnv(lookup("TRACKS"), idx);
+  const bandwidthStr = lookup("BANDWIDTH");
+  const bandwidth = bandwidthStr !== void 0 ? Number(bandwidthStr) : void 0;
+  const source = lookup("SOURCE");
+  const relay = lookup("RELAY");
+  return {
+    protocol: lookup("PROTOCOL"),
+    groupAddress: lookup("GROUP") ?? "",
+    port,
+    tracks,
+    ...source ? { sourceAddress: source } : {},
+    ...relay ? { relayAddress: relay } : {},
+    ...bandwidth !== void 0 ? { bandwidth } : {}
+  };
+}
+function parseTracksEnv(raw, endpointIdx) {
+  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 ":" \u2014 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 };
+  });
+}
+export {
+  MulticastInputError,
+  multicastFromConfig,
+  multicastFromEnv
+};
+//# sourceMappingURL=multicast-input.js.map