@camstack/addon-pipeline 1.2.329 → 1.2.331

package/dist/stream-broker/index.mjs

@@ -1,10 +1,10 @@
 import { r as __toESM } from "../chunk-DnnnRqeS.mjs";
-import { $ as cameraStreamsCapability, At as maskUrlCredentials, Bn as array, C as EncodeProfileSchema, Cn as CAM_PROFILE_ORDER, Dt as loadContributionCapability, En as createEvent, Gn as number, Hn as discriminatedUnion, I as RATE_CONTROL_RELAXED, In as parseProfileBrokerId, Jn as record, Kn as object, L as RATE_CONTROL_TIGHT, Mn as makeProfileBrokerId, Nn as makeSourceBrokerId, Nt as memoizePinnedFfmpeg, O as G711_SCALE_CORRECTION_DB, Ot as logChannelsCapability, Pn as nodePin, Sn as BaseAddon, U as RingBuffer, Vn as boolean, Wn as literal, Wt as rankStreams, Xn as union, Yn as string, Z as batteryCapability, Zn as EventCategory, Zt as resolveEgressDecodeHwAccel, _n as isSoftwareDecode, bn as errMsg, bt as gifDeriveSpeed, c as CLIP_STILL_REASON_CODE_HEADER, dn as AUDIO_PRESETS, dt as egressTransportFromRequest, gn as invocationFromEncodeProfile, it as declareLogChannel, jn as isEvent, kn as expandAudioChunkToF32le, mn as buildFfmpegArgs$1, nt as createHwAccelCache, o as BatteryStatusSchema, on as streamBrokerCapability, ot as deriveBatteryPresence, q as addonWidgetsSourceCapability, rt as createLogChannelsProvider, s as CLIP_BROKER_PACED_RATES, tt as clipExportFailureOf, un as webrtcSessionCapability, ut as egressTranscodeSharingKey, vn as DeviceFeature, vt as ffmpegRate, wn as CamProfileSchema, xn as BOOT_RECOVERY_BACKOFF_MS, xt as gifFromMp4Args, yn as DeviceType, zn as _enum } from "../dist-0HoA3wAi.mjs";
-import { i as NO_COST_CLAIM, n as Fmp4FragmentChild, o as probeFfmpegBinary, r as Fmp4FragmentPlane, t as ChildCostRegistry } from "../node-HOMWRPzW.mjs";
+import { $ as cameraStreamsCapability, $n as union, $t as resolveEgressDecodeHwAccel, At as logChannelsCapability, C as EncodeProfileSchema, Cn as errMsg, Ct as gifFromMp4Args, Dn as CamProfileSchema, E as G711_SCALE_CORRECTION_DB, En as CAM_PROFILE_ORDER, F as RATE_CONTROL_TIGHT, Fn as makeProfileBrokerId, Ft as memoizePinnedFfmpeg, Gn as discriminatedUnion, H as RingBuffer, Hn as _enum, In as makeSourceBrokerId, Jn as number, K as addonWidgetsSourceCapability, Kt as rankStreams, Ln as nodePin, Mn as expandAudioChunkToF32le, Mt as maskUrlCredentials, P as RATE_CONTROL_RELAXED, Pn as isEvent, Qn as string, Sn as DeviceType, St as gifDeriveSpeed, Tn as BaseAddon, Un as array, Wn as boolean, Yn as object, Z as batteryCapability, Zn as record, _n as buildFfmpegArgs$1, at as declareLogChannel, bn as isSoftwareDecode, bt as ffmpegRate, c as CLIP_STILL_REASON_CODE_HEADER, er as EventCategory, ft as egressTranscodeSharingKey, it as createLogChannelsProvider, kn as createEvent, kt as loadContributionCapability, ln as streamBrokerCapability, mn as AUDIO_PRESETS, o as BatteryStatusSchema, pn as webrtcSessionCapability, pt as egressTransportFromRequest, qn as literal, rt as createHwAccelCache, s as CLIP_BROKER_PACED_RATES, st as deriveBatteryPresence, tt as clipExportFailureOf, wn as BOOT_RECOVERY_BACKOFF_MS, xn as DeviceFeature, yn as invocationFromEncodeProfile, zn as parseProfileBrokerId } from "../dist-CNXhBzn6.mjs";
+import { i as NO_COST_CLAIM, n as Fmp4FragmentChild, o as probeFfmpegBinary, r as Fmp4FragmentPlane, t as ChildCostRegistry } from "../node-BmxmlYLx.mjs";
 import { a as parseRestreamPath, d as PREBUFFER_MAX_MS, f as capPreRollRequestMs, i as isLiveEdgeOnlyDial, m as resolvePrebuffer, n as NO_DECLARATION, p as prebufferRetentionMs, s as sdpVariantFor, u as withSentryIntent } from "../restream-intent-DyGmLAU9.mjs";
 import { n as profileForStreamId } from "../remote-restream-BeHi78PZ.mjs";
 import { n as RowMapStore, t as retireRootKeys } from "../retire-root-keys-DZvlso2l.mjs";
-import { a as require_mp4box_all, c as parseNalLengthSize, i as runFfmpegOnce, n as demuxSegmentPreferJs, o as avccSampleToAnnexB, r as FfmpegFallbackRefusedError, s as buildKeyframeAnnexB, t as demuxSegmentFullJs } from "../segment-demux-js-BU2MXpln.mjs";
+import { a as require_mp4box_all, c as parseNalLengthSize, i as runFfmpegOnce, n as demuxSegmentPreferJs, o as avccSampleToAnnexB, r as FfmpegFallbackRefusedError, s as buildKeyframeAnnexB, t as demuxSegmentFullJs } from "../segment-demux-js-VqsLAgQ0.mjs";
 import { createRequire } from "node:module";
 import * as os from "node:os";
 import { networkInterfaces, tmpdir } from "node:os";
@@ -24418,7 +24418,9 @@ var AdaptiveSession = class AdaptiveSession {
 	*  tier when loss persists — smaller packets survive lossy links better.
 	*  Must stay below H264_REPACKETIZER_MTU (1100). */
 	static ADAPTIVE_LOW_MTU = 900;
-	/** Broker source-RTP pre-buffer accessor + one-shot replay guard. */
+	/** Broker source-RTP pre-buffer accessor + one-shot replay guard. Replaced
+	*  by `switchLiveSource` when an adaptive tier change moves the track onto
+	*  another broker in place. */
 	rtpBootstrap;
 	rtpBootstrapDone = false;
 	/**
@@ -24513,6 +24515,46 @@ var AdaptiveSession = class AdaptiveSession {
 			reason
 		} });
 	}
+	/**
+	* Move the live track onto ANOTHER source of the same codec, in place — an
+	* adaptive tier change on the session the viewer already has (D733).
+	*
+	* Everything `onSourceRestarted` does for a re-dial, because a different
+	* rung IS a different RTP stream (new SSRC, new sequence/timestamp base, new
+	* parameter sets), plus the two things only a different broker changes:
+	*  - the bootstrap accessor now reads the NEW broker's pre-buffer, so the
+	*    next forwarded packet replays its current GOP from the keyframe — the
+	*    decoder switches on an IDR instead of waiting for the camera's next one;
+	*  - the repacketizer is re-seeded with the new rung's SDP parameter sets,
+	*    for a camera that publishes them only in SDP.
+	* The MTU returns to the default a freshly built session would have: the
+	* reduced MTU belongs to the lowest rung's loss recovery, not to the session.
+	*/
+	switchLiveSource(next) {
+		if (this.closed) return;
+		this.rtpBootstrap = next.rtpBootstrap;
+		this.activeRtpReplay?.abort();
+		this.activeRtpReplay = null;
+		this.h264Repacketizer = null;
+		this.h265Repacketizer = null;
+		this.sourceVideoSsrc = null;
+		this.rtpRebasePending = true;
+		this.rtpBootstrapDone = false;
+		this.repacketizerMtu = AdaptiveSession.H264_REPACKETIZER_MTU;
+		const ps = next.parameterSets ?? [];
+		if (ps.length > 0) if (this.sourceCodec === "H265") this.seedH265CodecInfoFromSdp(ps);
+		else this.seedH264CodecInfoFromSdp(ps);
+		this.logger.info("live source switched in place — replaying the new source from its keyframe", {
+			tags: { deviceId: this.deviceId },
+			meta: {
+				phase: "session",
+				sessionId: this.sessionId,
+				deviceId: this.deviceId,
+				reason: next.reason,
+				seededParamSets: ps.length
+			}
+		});
+	}
 	/** Drop the repacketizer + bootstrap/sync state so a newly bound source
 	*  stream re-seeds its SPS/PPS and replays instant-start cleanly. */
 	resetRepacketizer() {
@@ -27205,6 +27247,32 @@ var AdaptiveController = class {
 	onRtt(rttMs, now) {
 		this.rtt.observe(rttMs, now);
 	}
+	/**
+	* The session now serves `tier`, decided OUTSIDE this ladder's own tick
+	* (D733): the viewer's downlink probe placed it there, or the rung the ladder
+	* asked for is not served and the switch landed on the one that is.
+	*
+	* Before D733 both were a close-and-recreate re-offer, which built a NEW
+	* controller on the rung the session landed on. The ladder ends up where that
+	* new controller started: on `tier`, not on trial (a probe IS capacity
+	* evidence; a fallback rung was not tried), with its healthy clock and change
+	* blackout starting now, and with no promotion counted. The measured-failure
+	* memory is kept: a rung this session already proved unusable stays backed off.
+	*/
+	settleOn(tier, now) {
+		this.armed = true;
+		this.hold = null;
+		this.tier = tier;
+		this.mtuReduced = false;
+		this.transcodeEngaged = false;
+		this.trial = null;
+		this.tryCarry = {
+			...this.tryCarry,
+			trialFrom: null
+		};
+		this.commitChange(now);
+		this.healthySince = now;
+	}
 	/** Why the ladder did not climb on the last evaluation; null = at the top, or it just moved. */
 	get climbHold() {
 		return this.hold;
@@ -31227,6 +31295,8 @@ var TimelineSession = class {
 	*  paused across that required quality transition. */
 	rate = 1;
 	liveProfileReported = false;
+	/** The live rung after an in-place tier switch; undefined = `initialLiveProfile`. */
+	liveProfile = void 0;
 	/**
 	* The last position the viewer was SHOWN (every `_emitPosition`). Handed to
 	* `seek` as `travelFromMs` so the seek travel animation works across feeder
@@ -31701,11 +31771,29 @@ var TimelineSession = class {
 		}));
 	}
 	emitLiveProfile() {
-		if (this.liveProfileReported || this.deps.initialLiveProfile === void 0) return;
+		const profile = this.liveProfile ?? this.deps.initialLiveProfile;
+		if (this.liveProfileReported || profile === void 0) return;
 		this.liveProfileReported = true;
 		this.deps.session.sendControl(serializeServerMessage({
 			t: "liveProfile",
-			profile: this.deps.initialLiveProfile
+			profile
+		}));
+	}
+	/**
+	* The live rung moved under this coordinator — an adaptive tier switch that
+	* stayed on the session (D733). Before D733 a tier change built a new
+	* coordinator, which reported its own `initialLiveProfile`; now the same one
+	* outlives the switch and must say what the viewer is watching. Reported at
+	* once when the viewer has already been told a profile, otherwise on its
+	* first control message as before.
+	*/
+	setLiveProfile(profile) {
+		if (this.liveProfile === profile) return;
+		this.liveProfile = profile;
+		if (!this.liveProfileReported) return;
+		this.deps.session.sendControl(serializeServerMessage({
+			t: "liveProfile",
+			profile
 		}));
 	}
 	dispose() {
@@ -34586,7 +34674,7 @@ async function demuxSegmentAudioOpusPreferJs(bytes, opts) {
 		if (direct) return direct;
 	} catch {}
 	if (opts.ffmpegPath === null) {
-		opts.onFfmpegFallback?.("audio track is not Opus (legacy fragment) and the ffmpeg fallback is refused — no pinned ffmpeg on this node (D540)");
+		opts.onFfmpegFallback?.("audio track is not Opus (legacy fragment) and the ffmpeg fallback is refused — no pinned ffmpeg on this node");
 		return [];
 	}
 	opts.onFfmpegFallback?.("audio track is not Opus (legacy fragment)");
@@ -34628,6 +34716,98 @@ function preferLiveAdaptiveCandidates(candidates) {
 	return natives.length > 0 ? natives : [...candidates];
 }
 //#endregion
+//#region src/stream-broker/webrtc/in-place-tier-switch.ts
+/**
+* How long a switch waits for the new rendition's first switchable keyframe.
+* A warm broker commits on its next packet; a cold one needs its dial (2–3 s on
+* this hub) plus the camera's next IDR (≤ 4 s at the GOPs measured). 8 s covers
+* both; past it the old source has been shown the whole time, so nothing froze.
+*/
+var IN_PLACE_SWITCH_KEYFRAME_WAIT_MS = 8e3;
+/** Map a broker's codec string to the session codec it would negotiate; null = unknown. */
+function sessionCodecOf(brokerCodec) {
+	if (brokerCodec === void 0 || brokerCodec === "") return null;
+	const c = brokerCodec.toLowerCase();
+	return c === "h265" || c === "hevc" ? "H265" : "H264";
+}
+/**
+* Whether the switch may stay on the session; the refusal names why not.
+* Facts not known yet (a cold target's codec or audio) do not refuse — the
+* judgement is repeated at commit time, when they are.
+*/
+function judgeInPlaceSwitch(session, target) {
+	if (session.recorded) return "recorded";
+	if (session.forceTranscodeDown) return "transcode-down";
+	if (!session.useRtpRepacketizer) return "not-rtp-passthrough";
+	if (session.needsTranscode) return "transcode";
+	if (!target.tierMatches) return "tier-unavailable";
+	if (!target.isRtp) return "target-not-rtp";
+	if (target.codec !== null && target.codec !== session.sessionCodec) return "codec-differs";
+	if (target.needsBaselineTranscode) return "target-needs-transcode";
+	if (target.audioCodec !== void 0 && !sameAudioCodec(session.audioCodec, target.audioCodec)) return "audio-codec-differs";
+	if (session.usesOpusEgress && !target.supportsOpusEgress) return "opus-egress-unsupported";
+	return null;
+}
+function sameAudioCodec(a, b) {
+	return (a ?? "").toLowerCase() === (b ?? "").toLowerCase();
+}
+/**
+* Subscribe `broker`'s RTP while the session's current source keeps feeding,
+* and commit when the new rendition can start on a keyframe.
+*
+* ONE subscription goes from pending to forwarding — never a second one added
+* during the delivery of the committing packet, which a broker iterating its
+* subscriber set would hand the same packet again (a duplicate behind the
+* replay). A warm-up consumer keeps a cold broker's dial up while pending and
+* is released only after the commit has attached the session's own consumers.
+*/
+function bindPendingSource(opts) {
+	let state = "pending";
+	let warm = opts.broker.onEncodedData(() => {}, {
+		kind: "warmup",
+		media: "both"
+	});
+	const releaseWarm = () => {
+		warm?.();
+		warm = null;
+	};
+	let unsubRtp = null;
+	const timer = setTimeout(() => {
+		if (state !== "pending") return;
+		state = "gone";
+		unsubRtp?.();
+		releaseWarm();
+		opts.onTimeout();
+	}, opts.timeoutMs);
+	unsubRtp = opts.broker.onVideoRtp((rtp) => {
+		if (state === "gone") return;
+		if (state === "committed") {
+			opts.forward(rtp);
+			return;
+		}
+		if (opts.broker.getRtpPreBuffer().length === 0) return;
+		clearTimeout(timer);
+		if (!opts.commit()) {
+			state = "gone";
+			unsubRtp?.();
+			releaseWarm();
+			return;
+		}
+		state = "committed";
+		releaseWarm();
+		opts.forward(rtp);
+	}, opts.attribution);
+	return {
+		unsubscribe: () => {
+			if (state === "pending") clearTimeout(timer);
+			state = "gone";
+			unsubRtp?.();
+			releaseWarm();
+		},
+		committed: () => state === "committed"
+	};
+}
+//#endregion
 //#region src/stream-broker/webrtc/adaptive-tier.ts
 var RANK = {
 	low: 1,
@@ -34807,6 +34987,107 @@ function adaptivePickLogLine(reason) {
 	if (reason === "default-low") return "Adaptive source selected (no client hints — smallest available)";
 	return "Adaptive source selected";
 }
+/**
+* One broker audio packet onto a session's push source — the per-session codec
+* branch (mirrors the live/recorded split). The broker fans out BOTH a
+* PCMU/PCMA stream (always) and, when an Opus session is attached, a parallel
+* `codec:'opus'` stream. Forward only the stream matching THIS session's
+* negotiated codec; drop the other so a PCMU-fallback session never sees Opus
+* and vice-versa. Shared by the session's first broker and by every broker an
+* in-place tier switch moves it to (D733).
+*/
+function forwardBrokerAudio(packet, session, pushFrame) {
+	const pktCodec = packet.codec?.toLowerCase();
+	if (session?.isOpusAudio === true) {
+		if (pktCodec !== "opus") return;
+		pushFrame({
+			type: "audio",
+			frame: {
+				data: packet.data,
+				codec: "Opus",
+				sampleRate: 48e3,
+				channels: 2,
+				timestampMicros: packet.pts * 1e3
+			}
+		});
+		return;
+	}
+	if (pktCodec === "opus") return;
+	pushFrame({
+		type: "audio",
+		frame: {
+			data: packet.data,
+			codec: pktCodec === "pcma" ? "Pcma" : "Pcmu",
+			sampleRate: 8e3,
+			channels: 1,
+			timestampMicros: packet.pts * 1e3
+		}
+	});
+}
+/**
+* The `onVideoRtp` callback of an RTP-passthrough session: source RTP through
+* the codec repacketizer, unless a transcode owns the wire or recorded playback
+* owns the track. One implementation for the session's first broker and for
+* every broker an in-place tier switch moves it to (D733).
+*/
+function makeSourceRtpForwarder(input) {
+	const { session, sessionLogger, sessionId, deviceId, brokerId, sessionCodec } = input;
+	let firstRtpForwarded = false;
+	let gateDropLogged = false;
+	let forwardAfterGateLogged = false;
+	return (rtpData) => {
+		if (session.needsTranscode) return;
+		if (session.isLiveFeedGated) {
+			if (!gateDropLogged) {
+				gateDropLogged = true;
+				forwardAfterGateLogged = false;
+				sessionLogger.info("recorded: live RTP GATED (dropping live video)", {
+					tags: { deviceId },
+					meta: {
+						sessionId,
+						deviceId
+					}
+				});
+			}
+			return;
+		}
+		if (gateDropLogged && !forwardAfterGateLogged) {
+			forwardAfterGateLogged = true;
+			gateDropLogged = false;
+			sessionLogger.info("recorded: live RTP UNGATED (forwarding live video again)", {
+				tags: { deviceId },
+				meta: {
+					sessionId,
+					deviceId
+				}
+			});
+		}
+		if (!firstRtpForwarded) {
+			firstRtpForwarded = true;
+			sessionLogger.info("RTP session: first source RTP forwarded to repacketizer", {
+				tags: { deviceId },
+				meta: {
+					sessionId,
+					brokerId,
+					codec: sessionCodec,
+					bytes: rtpData.length
+				}
+			});
+		}
+		try {
+			session.forwardSourceRtpVideo(rtpData);
+		} catch (err) {
+			sessionLogger.warn("forwardSourceRtpVideo threw", {
+				tags: { deviceId },
+				meta: {
+					sessionId,
+					codec: sessionCodec,
+					error: errMsg(err)
+				}
+			});
+		}
+	};
+}
 /** Push-queue overflow purges are aggregated and reported at most this often. */
 var FRAME_DROP_LOG_INTERVAL_MS = 3e4;
 /**
@@ -35432,34 +35713,7 @@ var BrokerWebrtcServer = class {
 						timestampMicros: packet.pts * 1e3
 					}
 				});
-			} else if (packet.type === "audio") {
-				const pktCodec = packet.codec?.toLowerCase();
-				if (session?.isOpusAudio === true) {
-					if (pktCodec !== "opus") return;
-					pushFrame({
-						type: "audio",
-						frame: {
-							data: packet.data,
-							codec: "Opus",
-							sampleRate: 48e3,
-							channels: 2,
-							timestampMicros: packet.pts * 1e3
-						}
-					});
-				} else {
-					if (pktCodec === "opus") return;
-					pushFrame({
-						type: "audio",
-						frame: {
-							data: packet.data,
-							codec: pktCodec === "pcma" ? "Pcma" : "Pcmu",
-							sampleRate: 8e3,
-							channels: 1,
-							timestampMicros: packet.pts * 1e3
-						}
-					});
-				}
-			}
+			} else if (packet.type === "audio") forwardBrokerAudio(packet, session, pushFrame);
 		}, annexbAttribution);
 		warmUpUnsubscribe?.();
 		this.brokerLinger.cancel(brokerId);
@@ -35580,49 +35834,14 @@ var BrokerWebrtcServer = class {
 					}
 				});
 			}
-			let firstRtpForwarded = false;
-			let gateDropLogged = false;
-			let forwardAfterGateLogged = false;
-			unsubRtp = broker.onVideoRtp((rtpData) => {
-				if (session.needsTranscode) return;
-				if (session.isLiveFeedGated) {
-					if (!gateDropLogged) {
-						gateDropLogged = true;
-						forwardAfterGateLogged = false;
-						sessionLogger.info("recorded: live RTP GATED (dropping live video)", { meta: {
-							sessionId,
-							deviceId
-						} });
-					}
-					return;
-				}
-				if (gateDropLogged && !forwardAfterGateLogged) {
-					forwardAfterGateLogged = true;
-					gateDropLogged = false;
-					sessionLogger.info("recorded: live RTP UNGATED (forwarding live video again)", { meta: {
-						sessionId,
-						deviceId
-					} });
-				}
-				if (!firstRtpForwarded) {
-					firstRtpForwarded = true;
-					sessionLogger.info("RTP session: first source RTP forwarded to repacketizer", { meta: {
-						sessionId,
-						brokerId,
-						codec: sessionCodec,
-						bytes: rtpData.length
-					} });
-				}
-				try {
-					session.forwardSourceRtpVideo(rtpData);
-				} catch (err) {
-					sessionLogger.warn("forwardSourceRtpVideo threw", { meta: {
-						sessionId,
-						codec: sessionCodec,
-						error: errMsg(err)
-					} });
-				}
-			}, rtpAttribution);
+			unsubRtp = broker.onVideoRtp(makeSourceRtpForwarder({
+				session,
+				sessionLogger,
+				sessionId,
+				deviceId,
+				brokerId,
+				sessionCodec
+			}), rtpAttribution);
 		}
 		const unsubSourceRestart = broker.onSourceRestart((reason) => {
 			sessionLogger.info("broker re-dialed the source — re-syncing session", { meta: {
@@ -35648,7 +35867,17 @@ var BrokerWebrtcServer = class {
 			unsubRtp,
 			unsubSdpParams,
 			unsubSourceRestart,
-			closeSource
+			closeSource,
+			rebind: {
+				deviceId,
+				sessionCodec,
+				useRtpRepacketizer,
+				offeredProfileLevelIds,
+				hints,
+				sessionLogger,
+				pushFrame,
+				baseAttribution
+			}
 		};
 		this.sessions.set(sessionId, entry);
 		session.onClosed = () => this.cleanupSession(sessionId);
@@ -36375,6 +36604,88 @@ var BrokerWebrtcServer = class {
 		});
 		controller.onRtt(rttMs, now);
 	}
+	/**
+	* The viewer's downlink probe for ONE session (D733) — the server half of the
+	* probe climb. The player used to answer its own probe with a second session
+	* (a make-before-break reconnect carrying `downlinkMbps`); it now hands the
+	* measurement to the session it already has, and the broker places that
+	* session on the rung the probe picks, in place when the codec allows.
+	*
+	* The client sends a MEASUREMENT, never a tier: the pick is the same
+	* `pickAdaptiveTier` an offer's hints get, against the same viewport the
+	* offer carried, so a tile still ceilings to `low`. A probe only ever
+	* raises the rung — lowering it is the ladder's job, on delivery evidence.
+	*/
+	applyDownlinkProbe(sessionId, downlinkMbps) {
+		const entry = this.sessions.get(sessionId);
+		if (entry === void 0) return {
+			outcome: "held",
+			tier: null,
+			reason: "no-session"
+		};
+		const deviceId = deviceIdFromBrokerId(entry.brokerId);
+		const served = this.profileTierResolver?.(entry.brokerId) ?? null;
+		const controller = entry.adaptiveController;
+		const rebind = entry.rebind;
+		const now = Date.now();
+		const held = (reason) => {
+			this.logger.info("adaptive: downlink probe holds the session where it is", {
+				tags: { deviceId },
+				meta: {
+					sessionId,
+					deviceId,
+					downlinkMbps,
+					tier: served,
+					reason
+				}
+			});
+			return {
+				outcome: "held",
+				tier: served,
+				reason
+			};
+		};
+		if (controller === void 0 || rebind === void 0) return held("not-adaptive");
+		this.recordDeviceProbe(deviceId, probeFromHints(downlinkMbps, now));
+		if (rebind.hints.prefersTier !== void 0) return held("pinned");
+		if (entry.timeline?.currentMode === "recorded") return held("recorded");
+		const pick = pickAdaptiveTier({
+			available: preferLiveAdaptiveCandidates(this.deviceBrokerCandidates(deviceId)).map((c) => c.tier),
+			downlinkMbps,
+			viewportWidth: rebind.hints.viewportWidth,
+			viewportHeight: rebind.hints.viewportHeight
+		});
+		const current = entry.pendingSwitch?.tier ?? controller.currentTier;
+		if (CAM_PROFILE_ORDER.indexOf(pick.tier) >= CAM_PROFILE_ORDER.indexOf(current)) return held(pick.tier === current ? "already-there" : "probe-below-current");
+		controller.settleOn(pick.tier, now);
+		this.logger.info("adaptive: downlink probe places the session on a higher rung", {
+			tags: { deviceId },
+			meta: {
+				sessionId,
+				deviceId,
+				downlinkMbps,
+				from: current,
+				tier: pick.tier,
+				pick: pick.reason
+			}
+		});
+		this.switchSessionTier(entry, deviceId, pick.tier, sessionId);
+		return {
+			outcome: "switching",
+			tier: pick.tier,
+			reason: pick.reason
+		};
+	}
+	/** Every registered broker of `deviceId`, with the tier it currently serves. */
+	deviceBrokerCandidates(deviceId) {
+		const prefix = `${String(deviceId)}/`;
+		const out = [];
+		for (const bid of this.brokers.keys()) if (bid.startsWith(prefix)) out.push({
+			brokerId: bid,
+			tier: this.profileTierResolver?.(bid) ?? null
+		});
+		return out;
+	}
 	/** Adaptive sessions of `deviceId` currently on this broker server. */
 	adaptiveSessionCount(deviceId) {
 		const prefix = `${String(deviceId)}/`;
@@ -36387,6 +36698,322 @@ var BrokerWebrtcServer = class {
 		this.deviceProbe.record(deviceId, probe);
 	}
 	/**
+	* Move an adaptive session to `tier` — ON THE SESSION when it can (D733),
+	* by the close-and-recreate re-offer when it cannot, and the refusal that
+	* forced the re-offer is logged by name.
+	*
+	* A newer switch replaces one still waiting for its keyframe: the ladder's
+	* latest verdict is the one that must land, and an abandoned wait leaves the
+	* old source on the track (nothing froze).
+	*/
+	switchSessionTier(entry, deviceId, tier, sessionId, forceTranscodeDown = false, decision) {
+		entry.pendingSwitch?.cancel();
+		entry.pendingSwitch = void 0;
+		const why = decision?.cause ?? "probe";
+		if (forceTranscodeDown) {
+			this.logInPlaceFallback(entry, deviceId, tier, sessionId, "transcode-down", why);
+			this.scheduleTierReoffer(entry, deviceId, tier, sessionId, true, decision);
+			return;
+		}
+		this.switchTierInPlace(entry, deviceId, tier, sessionId, why).then((outcome) => {
+			if (outcome.kind !== "refused") return;
+			if (this.sessions.get(sessionId) !== entry) return;
+			this.logInPlaceFallback(entry, deviceId, tier, sessionId, outcome.reason, why);
+			this.scheduleTierReoffer(entry, deviceId, tier, sessionId, false, decision);
+		}).catch((err) => {
+			this.logger.warn("adaptive: in-place tier switch threw — falling back to re-offer", {
+				tags: { deviceId },
+				meta: {
+					sessionId,
+					deviceId,
+					tier,
+					error: errMsg(err)
+				}
+			});
+			if (this.sessions.get(sessionId) !== entry) return;
+			this.scheduleTierReoffer(entry, deviceId, tier, sessionId, false, decision);
+		});
+	}
+	logInPlaceFallback(entry, deviceId, tier, sessionId, reason, why) {
+		this.logger.info("adaptive: tier switch needs a re-offer — cannot stay on the session", {
+			tags: { deviceId },
+			meta: {
+				sessionId,
+				deviceId,
+				tier,
+				fromBrokerId: entry.brokerId,
+				reason,
+				cause: why
+			}
+		});
+	}
+	/** What the session is now, for `judgeInPlaceSwitch`. */
+	inPlaceSessionShape(entry, rebind) {
+		return {
+			recorded: entry.timeline?.currentMode === "recorded",
+			forceTranscodeDown: false,
+			useRtpRepacketizer: rebind.useRtpRepacketizer,
+			needsTranscode: entry.session.needsTranscode,
+			sessionCodec: rebind.sessionCodec,
+			audioCodec: this.brokers.get(entry.brokerId)?.getStats().audio?.codec ?? null,
+			usesOpusEgress: entry.releaseOpusEgress !== void 0
+		};
+	}
+	/** What the target rendition is, as far as it is known now. */
+	inPlaceTargetShape(rebind, landed, target) {
+		if (target === void 0) return {
+			tierMatches: false,
+			isRtp: false,
+			codec: null,
+			needsBaselineTranscode: false,
+			audioCodec: void 0,
+			supportsOpusEgress: false
+		};
+		const stats = target.getStats();
+		const codec = sessionCodecOf(stats.codec);
+		let needsBaselineTranscode = false;
+		if (codec === "H264") {
+			const profile = deriveH264ProfileLevelId(target.getSdpParameterSets(), target.getPreBuffer());
+			needsBaselineTranscode = rebind.offeredProfileLevelIds !== void 0 ? resolveClientOfferTranscodeToBaseline("H264", profile, rebind.offeredProfileLevelIds) : resolveBrokerTranscodeToBaseline("H264", profile);
+		}
+		return {
+			tierMatches: landed !== null,
+			isRtp: target.isRtpSource(),
+			codec,
+			needsBaselineTranscode,
+			audioCodec: codec === null ? void 0 : stats.audio?.codec ?? null,
+			supportsOpusEgress: supportsOpusEgress(target)
+		};
+	}
+	/**
+	* The in-place half of a tier switch (D733): resolve the tier's broker,
+	* judge whether the negotiated session carries it as is, subscribe it
+	* make-before-break and commit on its first switchable keyframe.
+	*/
+	async switchTierInPlace(entry, deviceId, tier, sessionId, why) {
+		const rebind = entry.rebind;
+		if (rebind === void 0) return {
+			kind: "refused",
+			reason: "not-rtp-passthrough"
+		};
+		const early = judgeInPlaceSwitch(this.inPlaceSessionShape(entry, rebind), {
+			tierMatches: true,
+			isRtp: true,
+			codec: null,
+			needsBaselineTranscode: false,
+			audioCodec: void 0,
+			supportsOpusEgress: true
+		});
+		if (early !== null) return {
+			kind: "refused",
+			reason: early
+		};
+		try {
+			await this.ensureAdaptiveTierBroker?.(deviceId, tier);
+		} catch (err) {
+			this.logger.warn("adaptive: could not prepare the tier broker for an in-place switch", {
+				tags: { deviceId },
+				meta: {
+					sessionId,
+					deviceId,
+					tier,
+					error: errMsg(err)
+				}
+			});
+			return {
+				kind: "refused",
+				reason: "tier-unavailable"
+			};
+		}
+		if (this.sessions.get(sessionId) !== entry) return { kind: "abandoned" };
+		const targetId = this.selectBestBroker(String(deviceId), { prefersTier: tier });
+		const target = this.brokers.get(targetId);
+		const landed = this.profileTierResolver?.(targetId) ?? null;
+		if (target !== void 0 && targetId === entry.brokerId) {
+			if (landed !== null) entry.adaptiveController?.settleOn(landed, Date.now());
+			rebind.sessionLogger.info("adaptive: wanted tier is not served — the session stays on its rung", {
+				tags: { deviceId },
+				meta: {
+					sessionId,
+					deviceId,
+					tier,
+					landed,
+					brokerId: targetId,
+					cause: why
+				}
+			});
+			return { kind: "committed" };
+		}
+		const judge = () => judgeInPlaceSwitch(this.inPlaceSessionShape(entry, rebind), this.inPlaceTargetShape(rebind, landed, target));
+		const refusal = judge();
+		if (refusal !== null || target === void 0) return {
+			kind: "refused",
+			reason: refusal ?? "tier-unavailable"
+		};
+		const fromBrokerId = entry.brokerId;
+		const startedAt = Date.now();
+		rebind.sessionLogger.info("adaptive: tier switch staying on the session — waiting for a keyframe", {
+			tags: { deviceId },
+			meta: {
+				sessionId,
+				deviceId,
+				tier,
+				fromBrokerId,
+				toBrokerId: targetId,
+				cause: why
+			}
+		});
+		return new Promise((resolve) => {
+			const forward = makeSourceRtpForwarder({
+				session: entry.session,
+				sessionLogger: rebind.sessionLogger,
+				sessionId,
+				deviceId,
+				brokerId: targetId,
+				sessionCodec: rebind.sessionCodec
+			});
+			const pending = bindPendingSource({
+				broker: target,
+				attribution: {
+					...rebind.baseAttribution,
+					media: "video",
+					targetCodec: rebind.sessionCodec,
+					transport: "repacketize"
+				},
+				timeoutMs: IN_PLACE_SWITCH_KEYFRAME_WAIT_MS,
+				commit: () => {
+					if (this.sessions.get(sessionId) !== entry || entry.pendingSwitch !== handle) {
+						resolve({ kind: "abandoned" });
+						return false;
+					}
+					entry.pendingSwitch = void 0;
+					const late = judge();
+					if (late !== null) {
+						resolve({
+							kind: "refused",
+							reason: late
+						});
+						return false;
+					}
+					if (landed !== null && landed !== tier) entry.adaptiveController?.settleOn(landed, Date.now());
+					this.commitInPlaceSwitch(entry, rebind, {
+						sessionId,
+						tier: landed ?? tier,
+						targetId,
+						target,
+						unsubRtp: pending.unsubscribe,
+						waitedMs: Date.now() - startedAt,
+						cause: why
+					});
+					resolve({ kind: "committed" });
+					return true;
+				},
+				forward,
+				onTimeout: () => {
+					if (entry.pendingSwitch === handle) entry.pendingSwitch = void 0;
+					resolve({
+						kind: "refused",
+						reason: "target-no-keyframe"
+					});
+				}
+			});
+			const handle = {
+				tier,
+				cancel: () => {
+					pending.unsubscribe();
+					resolve({ kind: "abandoned" });
+				}
+			};
+			entry.pendingSwitch = handle;
+		});
+	}
+	/**
+	* Swap every subscription of `entry` onto `target` in one synchronous step,
+	* inside the delivery of the target's committing packet: nothing from the old
+	* broker can reach the track after this returns, and the target's next
+	* forward replays its GOP from the keyframe onto a rebased RTP stream.
+	*/
+	commitInPlaceSwitch(entry, rebind, sw) {
+		const { session } = entry;
+		const { deviceId, sessionLogger } = rebind;
+		const old = {
+			brokerId: entry.brokerId,
+			unsubBroker: entry.unsubBroker,
+			unsubRtp: entry.unsubRtp,
+			unsubSdpParams: entry.unsubSdpParams,
+			unsubSourceRestart: entry.unsubSourceRestart,
+			releaseOpusEgress: entry.releaseOpusEgress
+		};
+		const target = sw.target;
+		entry.unsubBroker = target.onEncodedData((packet) => {
+			if (packet.type === "audio") forwardBrokerAudio(packet, session, rebind.pushFrame);
+		}, {
+			...rebind.baseAttribution,
+			media: "audio",
+			transport: "passthrough"
+		});
+		entry.unsubRtp = sw.unsubRtp;
+		if (old.releaseOpusEgress !== void 0 && supportsOpusEgress(target)) {
+			target.acquireOpusEgress();
+			entry.releaseOpusEgress = () => target.releaseOpusEgress();
+		} else entry.releaseOpusEgress = void 0;
+		const parameterSets = target.getSdpParameterSets();
+		session.switchLiveSource({
+			rtpBootstrap: () => target.getRtpPreBuffer(),
+			parameterSets,
+			reason: `tier ${sw.tier} (${sw.cause})`
+		});
+		entry.unsubSdpParams = parameterSets !== null && parameterSets.length > 0 ? null : target.onSdpParameterSets((ps) => {
+			if (rebind.sessionCodec === "H265") session.seedH265CodecInfoFromSdp(ps);
+			else session.seedH264CodecInfoFromSdp(ps);
+		});
+		entry.unsubSourceRestart = target.onSourceRestart((reason) => {
+			sessionLogger.info("broker re-dialed the source — re-syncing session", {
+				tags: { deviceId },
+				meta: {
+					sessionId: sw.sessionId,
+					brokerId: sw.targetId,
+					deviceId,
+					reason
+				}
+			});
+			session.onSourceRestarted(reason);
+		});
+		entry.brokerId = sw.targetId;
+		old.unsubRtp?.();
+		old.unsubBroker();
+		old.unsubSdpParams?.();
+		old.unsubSourceRestart();
+		old.releaseOpusEgress?.();
+		this.brokerLinger.cancel(sw.targetId);
+		let oldStillServed = false;
+		for (const other of this.sessions.values()) if (other.brokerId === old.brokerId) {
+			oldStillServed = true;
+			break;
+		}
+		if (!oldStillServed && !this.stopped) this.brokerLinger.hold(old.brokerId);
+		const pair = session.readNominatedPair();
+		if (pair !== null) {
+			const remoteAddr = pair.remoteType === "host" ? pair.remoteAddr : `${pair.remoteAddr} (${pair.remoteType})`;
+			target.updateConsumerAttributionBySession(sw.sessionId, { remoteAddr });
+		}
+		entry.timeline?.setLiveProfile(sw.tier);
+		sessionLogger.info("adaptive: tier switched in place — same session, same connection", {
+			tags: { deviceId },
+			meta: {
+				sessionId: sw.sessionId,
+				deviceId,
+				tier: sw.tier,
+				fromBrokerId: old.brokerId,
+				toBrokerId: sw.targetId,
+				codec: rebind.sessionCodec,
+				waitedMs: sw.waitedMs,
+				cause: sw.cause,
+				replayPackets: target.getRtpPreBuffer().length
+			}
+		});
+	}
+	/**
 	* Schedule an adaptive tier switch via a close-and-recreate re-offer.
 	*
 	* Records the controller's desired tier (+ forced transcode-down) in
@@ -36399,7 +37026,7 @@ var BrokerWebrtcServer = class {
 	* consumes the recorded intent to pin the recreated session to `tier` and
 	* apply the reduced transcode profile when `forceTranscodeDown` is set.
 	*/
-	switchSessionTier(entry, deviceId, tier, sessionId, forceTranscodeDown = false, decision) {
+	scheduleTierReoffer(entry, deviceId, tier, sessionId, forceTranscodeDown = false, decision) {
 		const prev = this.adaptiveIntent.get(sessionId);
 		const failures = new Map(entry.adaptiveController?.failureCounts ?? prev?.failures);
 		const upgradeCount = entry.adaptiveController?.successfulUpgradeCount ?? prev?.upgradeCount ?? 0;
@@ -36447,6 +37074,8 @@ var BrokerWebrtcServer = class {
 		const entry = this.sessions.get(sessionId);
 		if (!entry) return;
 		this.sessions.delete(sessionId);
+		entry.pendingSwitch?.cancel();
+		entry.pendingSwitch = void 0;
 		let brokerStillServed = false;
 		for (const other of this.sessions.values()) if (other.brokerId === entry.brokerId) {
 			brokerStillServed = true;
@@ -37106,6 +37735,10 @@ var WebrtcSessionProvider = class WebrtcSessionProvider {
 	async getSessionState(input) {
 		return this.webrtcServer.getSessionRenegotiationState(input.sessionId);
 	}
+	/** The viewer's downlink probe for one session (D733) — see the cap's docblock. */
+	async applyDownlinkProbe(input) {
+		return this.webrtcServer.applyDownlinkProbe(input.sessionId, input.downlinkMbps);
+	}
 	/**
 	* The SERVER half of the stream-debug overlay. Thin facade — the gathering
 	* lives in the WebRTC server and the shaping in the pure