@blockcast/mmt-transport 0.2.2 → 0.3.0

package/src/multicast-orchestrator.ts

@@ -1,4 +1,5 @@
-import { endpointKey, selectMulticastTier, type MulticastTierEndpoint } from "./multicast-tier.js";
+import { compareNtpShort, isNtpShort } from "@blockcast/mmt-base";
+import { carriesMedia, endpointKey, selectMulticastTier, type MulticastTierEndpoint } from "./multicast-tier.js";
 
 export type OrchestratorState = "stable" | "joining";
 export type OrchestratorCommand =
@@ -9,6 +10,16 @@ export type OrchestratorCommand =
 export interface MulticastTierPacket {
 	endpointKey: string;
 	keyframe: boolean;
+	/**
+	 * The packet's MMTP header `timestamp`: its UTC sending instant in NTP short
+	 * format (ISO/IEC 23008-1 §9.2.2), which wraps every 2^16 s (~18.2 h). The
+	 * orchestrator orders these only with RFC 1982 serial arithmetic
+	 * (`compareNtpShort`), never with `<` or `Math.max`.
+	 *
+	 * A non-finite value means the host could not read a header; that packet
+	 * neither raises the high-water mark nor commits. Any other value that is
+	 * not NTP short is a host bug and throws a RangeError.
+	 */
 	timestamp: number;
 	hasValidCodecConfig: boolean;
 }
@@ -23,6 +34,7 @@ export interface OrchestratorOptions {
 }
 
 export interface GoodputSample { bitrate: number | undefined; }
+export interface HeadroomSample { healthy: boolean; }
 
 export const DEFAULT_DWELL_MS = 3_000;
 export const DEFAULT_JOIN_DEADLINE_MS = 5_000;
@@ -44,9 +56,14 @@ export class MulticastOrchestrator {
 	#current: MulticastTierEndpoint | undefined;
 	#target: MulticastTierEndpoint | undefined;
 	#estimate: number | undefined;
-	#favored: { key: string; since: number } | undefined;
+	#favored: { key: string; since: number; source: "goodput" | "headroom" } | undefined;
 	#joinStartedAt = 0;
-	#lastCommittedTimestamp = Number.NEGATIVE_INFINITY;
+	/**
+	 * Latest active-tier send time (NTP short), or undefined before the first.
+	 * "Latest" is serial order, not the numerically largest value: after the
+	 * field wraps, the largest value is the stale one.
+	 */
+	#highWater: number | undefined;
 	readonly #dwellMs: number;
 	readonly #joinDeadlineMs: number;
 
@@ -71,20 +88,70 @@ export class MulticastOrchestrator {
 
 	onGoodput(sample: GoodputSample): OrchestratorCommand | undefined {
 		const bitrate = sample.bitrate;
-		this.#estimate = bitrate;
 		if (!this.#current || this.options.adaptive === false) return undefined;
 		if (this.#state === "joining") return this.poll();
+		if (bitrate === undefined || !Number.isFinite(bitrate)) return undefined;
+		this.#estimate = bitrate;
 		const desired = selectMulticastTier(this.options.endpoints, bitrate);
 		if (!desired) return undefined;
 		const desiredKey = endpointKey(desired);
 		if (desiredKey === endpointKey(this.#current)) {
+			if (this.#favored?.source === "goodput") this.#favored = undefined;
+			return undefined;
+		}
+		if (typeof desired.bandwidth !== "number" || typeof this.#current.bandwidth !== "number" ||
+			desired.bandwidth >= this.#current.bandwidth) {
+			if (this.#favored?.source === "goodput") this.#favored = undefined;
+			return undefined;
+		}
+
+		const now = this.#now();
+		if (!this.#favored || this.#favored.key !== desiredKey || this.#favored.source !== "goodput") {
+			this.#favored = { key: desiredKey, since: now, source: "goodput" };
+			return undefined;
+		}
+		if (now - this.#favored.since < this.#dwellMs) return undefined;
+
+		this.#state = "joining";
+		this.#target = desired;
+		this.#joinStartedAt = now;
+		this.#favored = undefined;
+		return { kind: "join-target", current: this.#current, target: desired };
+	}
+
+	onHeadroom(sample: HeadroomSample): OrchestratorCommand | undefined {
+		if (!this.#current || this.options.adaptive === false || this.#state === "joining") return undefined;
+		if (!sample.healthy) {
+			if (this.#favored?.source === "headroom") this.#favored = undefined;
+			return undefined;
+		}
+		if (this.#favored?.source === "goodput") return undefined;
+
+		const currentBandwidth = this.#current.bandwidth;
+		if (typeof currentBandwidth !== "number") return undefined;
+		// Ranked here rather than through selectMulticastTier: up-selection
+		// advances exactly one adjacent rung, where the selector fits a budget to
+		// an estimate. The media filter is shared so a repair-only endpoint above
+		// the current rung is not joined as an upgrade, which would swap the
+		// receiver onto repair symbols and no media.
+		const desired = this.options.endpoints
+			.filter((endpoint) =>
+				carriesMedia(endpoint) && typeof endpoint.bandwidth === "number" && endpoint.bandwidth > currentBandwidth,
+			)
+			.sort((a, b) => a.bandwidth! - b.bandwidth!)[0];
+		if (!desired) {
 			this.#favored = undefined;
 			return undefined;
 		}
 
+		const desiredKey = endpointKey(desired);
+		if (desiredKey === endpointKey(this.#current)) {
+			this.#favored = undefined;
+			return undefined;
+		}
 		const now = this.#now();
 		if (!this.#favored || this.#favored.key !== desiredKey) {
-			this.#favored = { key: desiredKey, since: now };
+			this.#favored = { key: desiredKey, since: now, source: "headroom" };
 			return undefined;
 		}
 		if (now - this.#favored.since < this.#dwellMs) return undefined;
@@ -96,10 +163,25 @@ export class MulticastOrchestrator {
 		return { kind: "join-target", current: this.#current, target: desired };
 	}
 
+	/**
+	 * Feed a packet from the active tier (to advance the high-water mark) or
+	 * from the in-flight target (to find a committable RAP).
+	 *
+	 * Serial order is only the true order while the compared instants are less
+	 * than `NTP_SHORT_HALF_RANGE` (2^15 s, ~9.1 h) apart. Feeding every
+	 * active-tier packet keeps the mark that close to the live stream. A mark
+	 * refreshed only by commits can fall further behind than that, and a
+	 * target RAP may then compare as older, so the join is abandoned.
+	 */
 	onTierPacket(packet: MulticastTierPacket): OrchestratorCommand | undefined {
 		if (!this.#current) return undefined;
-		if (packet.endpointKey === endpointKey(this.#current) && Number.isFinite(packet.timestamp)) {
-			this.#lastCommittedTimestamp = Math.max(this.#lastCommittedTimestamp, packet.timestamp);
+		const sentAt = tierPacketSendTime(packet);
+		// An instant exactly half the space from the mark (RFC 1982's undefined
+		// case) is neither later nor earlier, so it leaves the mark alone, as a
+		// reordered earlier packet does.
+		if (packet.endpointKey === endpointKey(this.#current) && sentAt !== undefined &&
+			(this.#highWater === undefined || compareNtpShort(sentAt, this.#highWater) === "after")) {
+			this.#highWater = sentAt;
 		}
 		if (this.#state !== "joining" || !this.#target) return undefined;
 		const expired = this.poll();
@@ -108,8 +190,8 @@ export class MulticastOrchestrator {
 			packet.endpointKey !== endpointKey(this.#target) ||
 			!packet.keyframe ||
 			!packet.hasValidCodecConfig ||
-			!Number.isFinite(packet.timestamp) ||
-			packet.timestamp < this.#lastCommittedTimestamp
+			sentAt === undefined ||
+			!this.#reachesHighWater(sentAt)
 		) return undefined;
 
 		const command: OrchestratorCommand = {
@@ -117,7 +199,7 @@ export class MulticastOrchestrator {
 			target: this.#target,
 			old: this.#current,
 		};
-		this.#lastCommittedTimestamp = packet.timestamp;
+		this.#highWater = sentAt;
 		this.#current = this.#target;
 		this.#target = undefined;
 		this.#state = "stable";
@@ -142,9 +224,31 @@ export class MulticastOrchestrator {
 		return command;
 	}
 
+	/**
+	 * Whether a target RAP sent at `sentAt` is at or beyond the active tier's
+	 * high-water mark. A pair exactly half the NTP-short space apart has no
+	 * serial order, so it cannot show that and does not commit.
+	 */
+	#reachesHighWater(sentAt: number): boolean {
+		if (this.#highWater === undefined) return true;
+		const order = compareNtpShort(sentAt, this.#highWater);
+		return order === "after" || order === "equal";
+	}
+
 	#now(): number {
 		const now = this.options.now();
 		if (!Number.isFinite(now)) throw new Error("Multicast orchestrator clock must be finite");
 		return now;
 	}
 }
+
+/** A tier packet's NTP-short send time, or undefined when the host had no header to read. */
+function tierPacketSendTime(packet: MulticastTierPacket): number | undefined {
+	if (!Number.isFinite(packet.timestamp)) return undefined;
+	if (!isNtpShort(packet.timestamp)) {
+		throw new RangeError(
+			`Multicast tier packet timestamp must be an MMTP NTP-short send time, got ${packet.timestamp}`,
+		);
+	}
+	return packet.timestamp;
+}

package/src/multicast-signaling-reconciler.ts

@@ -0,0 +1,156 @@
+import { isMulticastTrackPacketId, isValidMulticastGroupAddress } from "./endpoint-config.js";
+
+export interface MulticastSignalingEndpoint {
+	endpointId: string;
+	endpointVersion: number;
+	protocol: "ssm" | "asm" | "amt";
+	sourceAddress?: string;
+	groupAddress: string;
+	port: number;
+	validUntil?: number;
+	tracks: Array<{ name: string; packetId?: number; [key: string]: unknown }>;
+	[key: string]: unknown;
+}
+
+type Catalog = Record<string, any>;
+type Signal = Record<string, any>;
+
+export function createMulticastSignalingReconciler(catalog: Catalog, options: { catalog?: Catalog } = {}) {
+	const initial = normalizeCatalogEndpoints(catalog);
+	const endpoints = new Map(initial.map(endpoint => [endpoint.endpointId, copyEndpoint(endpoint)]));
+	const versions = new Map(initial.map(endpoint => [endpoint.endpointId, endpoint.endpointVersion]));
+	const seen = new Set<string>();
+	const dormant = new Set<string>();
+	let catalogVersion = Number(catalog?.multicast?.version ?? catalog?.version ?? 0) || 0;
+	const snapshot = (now = Date.now()) => ({
+		catalogVersion,
+		endpoints: [...endpoints.values()].filter(endpoint => !dormant.has(endpoint.endpointId) && !isExpired(endpoint, now)).map(copyEndpoint),
+		dormantEndpointIds: [...dormant].sort(),
+	});
+
+	return {
+		apply(signal: Signal, now = Date.now()) {
+			if (!isObject(signal) || typeof signal.type !== "string" || typeof signal.msgId !== "string") return { applied: false, reason: "invalid-message" };
+			if (seen.has(signal.msgId)) return { applied: false, reason: "duplicate-message" };
+			if (signal.expiresAt != null && Number(signal.expiresAt) < now) return { applied: false, reason: "expired" };
+			const signalCatalogVersion = Number(signal.catalogVersion ?? 0);
+			if (!Number.isFinite(signalCatalogVersion)) return { applied: false, reason: "invalid-message" };
+			if (signalCatalogVersion < catalogVersion) return { applied: false, reason: "stale-catalog" };
+			const result = applyFresh(signal, now);
+			if (result.applied) {
+				seen.add(signal.msgId);
+				// A heartbeat proves liveness but carries no catalog state. Ratcheting
+				// here would incorrectly reject the next real snapshot as stale.
+				if (signal.type !== "heartbeat") {
+					catalogVersion = Math.max(catalogVersion, signalCatalogVersion);
+				}
+			}
+			return result;
+		},
+		snapshot,
+		toCatalog(now = Date.now()) {
+			const current = snapshot(now);
+			return { ...catalog, multicast: { ...catalog.multicast, version: current.catalogVersion, endpoints: current.endpoints } };
+		},
+	};
+
+	function applyFresh(signal: Signal, now: number): { applied: boolean; reason?: string; action?: string } {
+		switch (signal.type) {
+			case "snapshot": {
+				const next = signal.payload?.endpoints;
+				if (!Array.isArray(next)) return { applied: false, reason: "invalid-message" };
+				const normalized = next.map((endpoint, index) => normalizeEndpoint(endpoint, index));
+				if (normalized.some(endpoint => !endpoint || !isValidEndpoint(endpoint, options.catalog))) return { applied: false, reason: "invalid-endpoint" };
+				const ids = new Set(normalized.map(endpoint => endpoint!.endpointId));
+				if (ids.size !== normalized.length) return { applied: false, reason: "duplicate-endpoint" };
+				endpoints.clear(); versions.clear(); dormant.clear();
+				for (const endpoint of normalized as MulticastSignalingEndpoint[]) {
+					versions.set(endpoint.endpointId, endpoint.endpointVersion);
+					if (!isExpired(endpoint, now)) endpoints.set(endpoint.endpointId, copyEndpoint(endpoint));
+				}
+				return { applied: true, action: "snapshot" };
+			}
+			case "add": return upsert(signal.payload?.endpoint, now);
+			case "update": {
+				const id = signal.payload?.endpointId;
+				const fields = signal.payload?.fields;
+				if (!endpoints.has(id)) return { applied: false, reason: "unknown-endpoint" };
+				if (isStale(id, signal.payload?.endpointVersion)) return { applied: false, reason: "stale-endpoint" };
+				if (!isObject(fields) || ["protocol", "sourceAddress", "groupAddress", "port"].some(key => Object.hasOwn(fields, key))) return { applied: false, reason: "invalid-update" };
+				return upsert({ ...endpoints.get(id), ...fields, endpointVersion: signal.payload.endpointVersion }, now);
+			}
+			case "remove": {
+				const id = signal.payload?.endpointId;
+				if (!endpoints.has(id)) return { applied: false, reason: "unknown-endpoint" };
+				const endpointVersion = Number(signal.payload?.endpointVersion);
+				if (!Number.isFinite(endpointVersion)) return { applied: false, reason: "invalid-message" };
+				if (isStale(id, endpointVersion)) return { applied: false, reason: "stale-endpoint" };
+				endpoints.delete(id); dormant.delete(id); versions.set(id, endpointVersion);
+				return { applied: true, action: "drop" };
+			}
+			case "invalidate": {
+				const id = signal.payload?.endpointId;
+				if (!endpoints.has(id)) return { applied: false, reason: "unknown-endpoint" };
+				dormant.add(id);
+				return { applied: true, action: "drop" };
+			}
+			case "heartbeat": return { applied: true, action: "heartbeat" };
+			default: return { applied: false, reason: "unknown-message-type" };
+		}
+	}
+
+	function upsert(value: unknown, now: number) {
+		const endpoint = normalizeEndpoint(value, endpoints.size);
+		if (!endpoint || !isValidEndpoint(endpoint, options.catalog)) return { applied: false, reason: "invalid-endpoint" };
+		if (isStale(endpoint.endpointId, endpoint.endpointVersion)) return { applied: false, reason: "stale-endpoint" };
+		versions.set(endpoint.endpointId, endpoint.endpointVersion);
+		dormant.delete(endpoint.endpointId);
+		if (isExpired(endpoint, now)) endpoints.delete(endpoint.endpointId);
+		else endpoints.set(endpoint.endpointId, copyEndpoint(endpoint));
+		return { applied: true, action: isExpired(endpoint, now) ? "drop" : "candidate" };
+	}
+
+	function isStale(id: string, version: unknown) {
+		const current = versions.get(id);
+		return current !== undefined && Number(version) <= current;
+	}
+}
+
+export function normalizeCatalogEndpoints(catalog: Catalog): MulticastSignalingEndpoint[] {
+	const endpoints = catalog?.multicast?.endpoints;
+	if (!Array.isArray(endpoints)) return [];
+	return endpoints
+		.map(normalizeEndpoint)
+		.filter((endpoint): endpoint is MulticastSignalingEndpoint => !!endpoint && isValidEndpoint(endpoint, catalog));
+}
+
+function normalizeEndpoint(value: unknown, index: number): MulticastSignalingEndpoint | undefined {
+	if (!isObject(value)) return undefined;
+	const endpoint = value as Record<string, any>;
+	const tracks = Array.isArray(endpoint.tracks) ? endpoint.tracks.map(track => typeof track === "string" ? { name: track } : { ...track }).filter(track => track.name) : [];
+	return { ...endpoint, endpointId: endpoint.endpointId || `${endpoint.sourceAddress || ""}|${endpoint.groupAddress || ""}|${endpoint.port || ""}|${index}`, endpointVersion: Number(endpoint.endpointVersion ?? 0), tracks } as MulticastSignalingEndpoint;
+}
+
+function isValidEndpoint(endpoint: MulticastSignalingEndpoint, catalog?: Catalog): boolean {
+	if (!endpoint.endpointId || !Number.isFinite(endpoint.endpointVersion)) return false;
+	if (!["ssm", "asm", "amt"].includes(endpoint.protocol)) return false;
+	if (endpoint.protocol === "ssm" && (typeof endpoint.sourceAddress !== "string" || endpoint.sourceAddress.trim().length === 0)) return false;
+	if (!isValidMulticastGroupAddress(endpoint.groupAddress) || !Number.isInteger(Number(endpoint.port)) || endpoint.port <= 0 || endpoint.port > 65535 || !endpoint.tracks.length) return false;
+	const catalogTracks = new Set([...Object.keys(catalog?.video?.renditions ?? {}), ...Object.keys(catalog?.audio?.renditions ?? {})]);
+	// Every track must carry a valid packet_id (isMulticastTrackPacketId); one
+	// that does not -- including packet_id 0, the MMTP signaling flow --
+	// rejects the whole endpoint rather than silently dropping that track.
+	return endpoint.tracks.every(track => !!track.name && isMulticastTrackPacketId(track.packetId) && (catalogTracks.size === 0 || catalogTracks.has(track.name) || catalogTracks.has(track.name.replace(/\/repair$/, ""))));
+}
+
+function copyEndpoint(endpoint: MulticastSignalingEndpoint): MulticastSignalingEndpoint {
+	return { ...endpoint, tracks: endpoint.tracks.map(track => ({ ...track })) };
+}
+
+function isExpired(endpoint: MulticastSignalingEndpoint, now: number): boolean {
+	return endpoint.validUntil != null && Number(endpoint.validUntil) < now;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object";
+}

package/src/multicast-subscription-pool.ts

@@ -1,4 +1,9 @@
-import { multicastEndpointKey, normalizeMulticastEndpoint } from "./endpoint-config.js";
+import {
+	multicastEndpointKey,
+	normalizeMulticastEndpoint,
+	toWindowMulticastSubscribeConfig,
+} from "./endpoint-config.js";
+import { subscriptionDeliversPacketBatches } from "./packet-batch.js";
 import type {
 	TransportConfig,
 	WindowMulticastGateway,
@@ -15,7 +20,13 @@ export interface MulticastSubscriptionConsumer {
 interface PoolEntry {
 	subscription: WindowMulticastSubscription;
 	consumers: Map<symbol, MulticastSubscriptionConsumer>;
-	bytesListener: (event: CustomEvent<ArrayBuffer>) => void;
+	/**
+	 * Exactly one packet surface is listened to: `packets` when the provider
+	 * advertises it, `bytes` otherwise (BLO-36599).
+	 */
+	packetListener:
+		| { type: "bytes"; listener: (event: CustomEvent<ArrayBuffer>) => void }
+		| { type: "packets"; listener: (event: CustomEvent<readonly ArrayBuffer[]>) => void };
 	stateListener: (event: CustomEvent<WindowMulticastSubscriptionState>) => void;
 	errorListener: (event: CustomEvent<unknown>) => void;
 	closed: boolean;
@@ -103,20 +114,35 @@ export class MulticastSubscriptionPool {
 		endpoint: NonNullable<ReturnType<typeof normalizeMulticastEndpoint>>,
 		onClosed: (entry: PoolEntry) => void,
 	): Promise<PoolEntry> {
-		const subscription = await gateway.subscribe!({
+		const subscription = await gateway.subscribe!(toWindowMulticastSubscribeConfig({
 			group: endpoint.groupAddress,
 			...(endpoint.sourceAddress ? { source: endpoint.sourceAddress } : {}),
 			port: endpoint.port,
-			consume: "bytes",
 			...(endpoint.mode ? { mode: endpoint.mode } : {}),
 			...(endpoint.amtRelay ? { amtRelay: endpoint.amtRelay } : {}),
 			...(endpoint.amtRelayPort ? { amtRelayPort: endpoint.amtRelayPort } : {}),
-		});
+		}));
 		const consumers = new Map<symbol, MulticastSubscriptionConsumer>();
 		let entry: PoolEntry;
-		const bytesListener = (event: CustomEvent<ArrayBuffer>) => {
-			this.#dispatch(consumers, (consumer) => consumer.onBytes(event.detail));
-		};
+		// A batch is delivered as the same per-packet onBytes calls the bytes
+		// surface makes, in arrival order and with each call isolated, so a
+		// consumer cannot tell the two apart; only the DOM event per packet is
+		// gone. The batch array and its elements are the provider's own, uncopied.
+		const packetListener: PoolEntry["packetListener"] = subscriptionDeliversPacketBatches(subscription)
+			? {
+					type: "packets",
+					listener: (event) => {
+						for (const data of event.detail) {
+							this.#dispatch(consumers, (consumer) => consumer.onBytes(data));
+						}
+					},
+				}
+			: {
+					type: "bytes",
+					listener: (event) => {
+						this.#dispatch(consumers, (consumer) => consumer.onBytes(event.detail));
+					},
+				};
 		const stateListener = (event: CustomEvent<WindowMulticastSubscriptionState>) => {
 			this.#dispatch(consumers, (consumer) => consumer.onState?.(event.detail));
 			if (event.detail === "closed" && !entry.closed) {
@@ -128,8 +154,12 @@ export class MulticastSubscriptionPool {
 			const error = event.detail instanceof Error ? event.detail : new Error(String(event.detail));
 			this.#dispatch(consumers, (consumer) => consumer.onError?.(error));
 		};
-		entry = { subscription, consumers, bytesListener, stateListener, errorListener, closed: false };
-		subscription.addEventListener("bytes", bytesListener);
+		entry = { subscription, consumers, packetListener, stateListener, errorListener, closed: false };
+		if (packetListener.type === "packets") {
+			subscription.addEventListener("packets", packetListener.listener);
+		} else {
+			subscription.addEventListener("bytes", packetListener.listener);
+		}
 		subscription.addEventListener("state", stateListener);
 		subscription.addEventListener("error", errorListener);
 		return entry;
@@ -146,7 +176,12 @@ export class MulticastSubscriptionPool {
 	}
 
 	#detach(entry: PoolEntry): void {
-		entry.subscription.removeEventListener("bytes", entry.bytesListener);
+		const { packetListener } = entry;
+		if (packetListener.type === "packets") {
+			entry.subscription.removeEventListener("packets", packetListener.listener);
+		} else {
+			entry.subscription.removeEventListener("bytes", packetListener.listener);
+		}
 		entry.subscription.removeEventListener("state", entry.stateListener);
 		entry.subscription.removeEventListener("error", entry.errorListener);
 	}

package/src/multicast-tier.ts

@@ -5,22 +5,49 @@ export interface MulticastTierEndpoint {
 	tracks: { name: string; packetId?: number }[];
 	bandwidth?: number;
 	protocol?: string;
+	/** False when every track on this endpoint is a `fec-repair` track, so the
+	 *  endpoint carries repair symbols only and no media. A repair-layer
+	 *  endpoint is joined by the loss-driven layer policy, never by the
+	 *  bandwidth ladder: selecting one as a tier would leave the receiver with
+	 *  no media at all. Set by the catalog policy, which resolves repair-track
+	 *  membership from `depends`/`fec.repairTrack` rather than from names.
+	 *  Undefined means "not classified" and is treated as carrying media, so a
+	 *  caller that builds endpoints without the policy is unaffected. */
+	carriesMedia?: boolean;
 }
 
 export function endpointKey(endpoint: MulticastTierEndpoint): string {
 	return `${endpoint.sourceAddress ?? ""}|${endpoint.groupAddress}|${endpoint.port}`;
 }
 
+/**
+ * Whether this endpoint may be selected as a media tier.
+ *
+ * Every path that picks a tier must apply this, not only `selectMulticastTier`:
+ * the orchestrator's headroom up-selection ranks endpoints itself, because it
+ * advances one adjacent rung rather than fitting a bandwidth budget. Exported
+ * so both rankings share one definition of "carries media" instead of
+ * repeating the comparison and drifting apart.
+ */
+export function carriesMedia(endpoint: MulticastTierEndpoint): boolean {
+	return endpoint.carriesMedia !== false;
+}
+
 export function selectMulticastTier(
 	endpoints: readonly MulticastTierEndpoint[],
 	estimate: number | undefined,
 ): MulticastTierEndpoint | undefined {
-	if (endpoints.length <= 1) return endpoints[0];
+	// Repair-only endpoints are never a media tier. Filtering once here covers
+	// every return path below, including the two early returns and the fallback:
+	// a ladder that has only repair-layer endpoints returns undefined rather
+	// than joining one and receiving no media.
+	const media = endpoints.filter(carriesMedia);
+	if (media.length <= 1) return media[0];
 
-	const ranked = endpoints
+	const ranked = media
 		.filter((endpoint) => typeof endpoint.bandwidth === "number" && endpoint.bandwidth > 0)
 		.sort((a, b) => a.bandwidth! - b.bandwidth!);
-	if (ranked.length < 2) return endpoints[0];
+	if (ranked.length < 2) return media[0];
 	if (estimate === undefined) return ranked[0];
 
 	const budget = estimate * 0.8;

package/src/no-modules.ts

@@ -1,4 +1,4 @@
-import { AdaptiveBitrateController } from "./abr-controller.js";
+import { AdaptiveBitrateController, validateQualityLadder } from "./abr-controller.js";
 import {
 	isMulticastExplicitlyDisabled,
 	isUsableMulticastEndpoint,
@@ -6,19 +6,60 @@ import {
 	multicastEndpointKey,
 	normalizeMulticastEndpoint,
 	readUrlMulticastConfig,
+	toWindowMulticastSubscribeConfig,
 } from "./endpoint-config.js";
 import { MulticastOrchestrator } from "./multicast-orchestrator.js";
+import {
+	endpointToMulticastConfig,
+	hasMulticastCatalogBaseline,
+	hasUnicastMediaRenditions,
+	isMulticastOnlyCatalog,
+	isRecoverableMulticastSignalReadError,
+	mergeUrlMulticastPolicy,
+	normalizeMulticastConfig,
+	readPlayerMulticastConfig,
+	requiresMulticastCapability,
+	sameMulticastConfig,
+	selectEndpointPacketIds,
+	selectMulticastCandidate,
+	catalogQualityLadder,
+	urlOverrideBlocksMulticastCandidate,
+	withMulticastEndpoints,
+} from "./multicast-catalog-policy.js";
+import {
+	createMulticastSignalingReconciler,
+	normalizeCatalogEndpoints,
+} from "./multicast-signaling-reconciler.js";
 import { MulticastSubscriptionPool } from "./multicast-subscription-pool.js";
 import { endpointKey, selectMulticastTier } from "./multicast-tier.js";
-import { TransportStallDetector } from "./stall-detector.js";
+import {
+	MOQT_PUBLISHER_PRIORITY,
+	MOQT_SUBSCRIBER_PRIORITY,
+	moqtPublisherPriority,
+	moqtSubscriberPriority,
+} from "./moqt-priority.js";
+import { classifyStall, TransportStallDetector } from "./stall-detector.js";
 import { makeSourceSwitchHandler, wireStarvationDetector } from "./takeover.js";
 import { TransportManager } from "./transport-manager.js";
 import { runUnicastFallback } from "./unicast-fallback.js";
 
 const api = {
 	AdaptiveBitrateController,
+	validateQualityLadder,
+	catalogQualityLadder,
+	classifyStall,
+	createMulticastSignalingReconciler,
+	endpointToMulticastConfig,
+	hasMulticastCatalogBaseline,
+	hasUnicastMediaRenditions,
+	isRecoverableMulticastSignalReadError,
+	isMulticastOnlyCatalog,
 	MulticastOrchestrator,
 	MulticastSubscriptionPool,
+	MOQT_PUBLISHER_PRIORITY,
+	MOQT_SUBSCRIBER_PRIORITY,
+	moqtPublisherPriority,
+	moqtSubscriberPriority,
 	TransportManager,
 	TransportStallDetector,
 	endpointKey,
@@ -26,11 +67,22 @@ const api = {
 	isUsableMulticastEndpoint,
 	isValidMulticastGroupAddress,
 	makeSourceSwitchHandler,
+	mergeUrlMulticastPolicy,
 	multicastEndpointKey,
+	normalizeCatalogEndpoints,
+	normalizeMulticastConfig,
 	normalizeMulticastEndpoint,
+	readPlayerMulticastConfig,
 	readUrlMulticastConfig,
+	toWindowMulticastSubscribeConfig,
+	requiresMulticastCapability,
 	runUnicastFallback,
+	sameMulticastConfig,
+	selectEndpointPacketIds,
+	selectMulticastCandidate,
 	selectMulticastTier,
+	urlOverrideBlocksMulticastCandidate,
+	withMulticastEndpoints,
 	wireStarvationDetector,
 };
 

package/src/packet-batch.ts

@@ -0,0 +1,17 @@
+import type { WindowMulticastSubscription } from "./types.js";
+
+/**
+ * True when `subscription` delivers packets in batches through the `packets`
+ * provider extension (BLO-36599).
+ *
+ * The pim window-multicast-bridge (0.2.0 and later) advertises the extension
+ * in `eventTypes`. It builds only the events some listener asked for, so a
+ * consumer that listens to `packets` alone gets one event per reader batch
+ * instead of one DOM event per packet. A provider without the field, or one
+ * that does not list `packets`, is a v1 provider: listen to `bytes`.
+ */
+export function subscriptionDeliversPacketBatches(
+	subscription: Pick<WindowMulticastSubscription, "eventTypes">,
+): boolean {
+	return subscription.eventTypes?.includes("packets") === true;
+}

package/src/stall-detector.ts

@@ -13,6 +13,43 @@ export interface StallDetectorConfig {
 	now?: () => number;
 }
 
+export interface PlayerStallSnapshot {
+	liveQ?: number | null;
+	decodeCallsDelta?: number | null;
+	fps?: number | null;
+}
+
+export interface PlayerStallClassification {
+	verdict: "DECODE-BOUND" | "PIPELINE-STARVED" | "STARVED-OR-SLOW" | "INDETERMINATE";
+	reason: string;
+}
+
+export function classifyStall({
+	liveQ = null,
+	decodeCallsDelta = null,
+	fps = null,
+}: PlayerStallSnapshot = {}): PlayerStallClassification {
+	if (liveQ != null && liveQ >= 20) {
+		return {
+			verdict: "DECODE-BOUND",
+			reason: `decode queue backlogged now (liveQ=${liveQ})`,
+		};
+	}
+	if (liveQ != null && liveQ <= 2 && decodeCallsDelta != null && decodeCallsDelta <= 1) {
+		return {
+			verdict: "PIPELINE-STARVED",
+			reason: `queue empty (liveQ=${liveQ}) and decode flatlined (Δcalls=${decodeCallsDelta}) — nothing reaching the decoder; suspect delivery/FEC/failback, not decode perf`,
+		};
+	}
+	if (fps != null && fps < 45) {
+		return {
+			verdict: "STARVED-OR-SLOW",
+			reason: `low decode rate (fps=${fps}) without a queue/flatline signal to disambiguate`,
+		};
+	}
+	return { verdict: "INDETERMINATE", reason: "no signal supports a verdict" };
+}
+
 export class TransportStallDetector {
 	#last: FecProgressSnapshot | null = null;
 	#lastSampleAt = 0;