@camstack/addon-pipeline 1.2.288 → 1.2.291

package/dist/stream-broker/index.js

@@ -3,12 +3,12 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../chunk-emK7D4bc.js");
-const require_dist = require("../dist-CegiJ2Pw.js");
-const require_node = require("../node-C8jhiPW2.js");
+const require_dist = require("../dist-D7FonEUB.js");
+const require_node = require("../node-D3C1krEi.js");
 const require_restream_intent = require("../restream-intent-7uDNqMKs.js");
 const require_remote_restream = require("../remote-restream-CO36Sr30.js");
 const require_retire_root_keys = require("../retire-root-keys-Csb8z2f3.js");
-const require_segment_demux_js = require("../segment-demux-js-Dv1EPPdH.js");
+const require_segment_demux_js = require("../segment-demux-js-COooJ-t0.js");
 let node_os = require("node:os");
 node_os = require_chunk.__toESM(node_os);
 let node_crypto = require("node:crypto");
@@ -23181,6 +23181,246 @@ var H264Repacketizer = class {
 	}
 };
 //#endregion
+//#region src/stream-broker/webrtc/delivery-meter.ts
+/** The window the ladder judges delivery over: at least one GOP. */
+function deliveryWindowMs(idrIntervalMs, config) {
+	const gop = idrIntervalMs !== null && Number.isFinite(idrIntervalMs) && idrIntervalMs > 0 ? idrIntervalMs : 0;
+	return Math.min(config.maxWindowMs, Math.max(config.minWindowMs, gop));
+}
+/**
+* When a session's meter may start counting client reports. A session created
+* by a tier change starts after the change blackout (review I1): until the
+* client swaps its player onto the new PC (after the new stream's first
+* decode, 2–5 s), its reporter still reads the OLD PC — 0 kbps — and the
+* first report after the swap is 0 too; both fall inside the new session's
+* sends and read as a failed rung.
+*/
+function deliveryMeterStart(now, afterTierChange, waitAfterChangeMs) {
+	return afterTierChange ? now + waitAfterChangeMs : now;
+}
+/**
+* Bucket width. 100 ms, and edges round to the NEAREST boundary, so a frame is
+* put on the wrong side of a window edge only when it was sent within 50 ms of
+* it — about one frame at 25 fps. Rounding edges inward instead dropped a whole
+* IDR that sat 160 ms inside a window and read a whole rung as 1.5× delivered.
+* 32 s of history is 320 slots.
+*/
+var SEND_BUCKET_MS = 100;
+/**
+* Bytes this session sent, bucketed by time. A fixed ring: `record` is on the
+* RTP send path, so it allocates nothing.
+*/
+var SendHistory = class {
+	bytes;
+	/** The bucket index each slot currently holds; -1 = empty. */
+	ids;
+	constructor(spanMs) {
+		const slots = Math.max(1, Math.ceil(spanMs / SEND_BUCKET_MS));
+		this.bytes = new Float64Array(slots);
+		this.ids = new Float64Array(slots).fill(-1);
+	}
+	record(byteCount, now) {
+		const id = Math.floor(now / SEND_BUCKET_MS);
+		const slot = id % this.ids.length;
+		if (this.ids[slot] !== id) {
+			this.ids[slot] = id;
+			this.bytes[slot] = 0;
+		}
+		this.bytes[slot] = (this.bytes[slot] ?? 0) + byteCount;
+	}
+	bitsBetween(fromMs, toMs) {
+		const first = Math.round(fromMs / SEND_BUCKET_MS);
+		const last = Math.round(toMs / SEND_BUCKET_MS) - 1;
+		let bytes = 0;
+		for (let id = first; id <= last; id += 1) {
+			const slot = id % this.ids.length;
+			if (this.ids[slot] === id) bytes += this.bytes[slot] ?? 0;
+		}
+		return bytes * 8;
+	}
+};
+/**
+* The client's recent reports, and the ratio they imply against a
+* {@link SendHistoryReader}. One meter per adaptive session: `notBefore` is
+* the session's start, because the reports are DEVICE-scoped and a report
+* about time before this session describes the previous one (a re-offer).
+*/
+var DeliveryMeter = class {
+	config;
+	notBefore;
+	reports = [];
+	constructor(config, notBefore) {
+		this.config = config;
+		this.notBefore = notBefore;
+	}
+	/** Fold one client report. The same report read on several ticks counts once. */
+	observe(kbps, endAt) {
+		if (!Number.isFinite(kbps) || kbps < 0 || !Number.isFinite(endAt)) return;
+		if (endAt - this.config.clientSampleSpanMs < this.notBefore) return;
+		if (this.reports.some((r) => r.endAt === endAt)) return;
+		const horizon = endAt - this.config.historySpanMs;
+		this.reports = [...this.reports.filter((r) => r.endAt > horizon), {
+			kbps,
+			endAt
+		}].sort((a, b) => a.endAt - b.endAt);
+	}
+	/**
+	* Is the client reporting at all? A fresh report that does not yet cover a
+	* whole window is "not measured YET" — different from a client that sends
+	* no telemetry, and it must not be climbed on (a 10 %-delivery link would
+	* otherwise promote in the seconds before its first window closes).
+	*/
+	isReporting(now) {
+		const newest = this.reports.at(-1);
+		return newest !== void 0 && now - newest.endAt <= this.config.maxClientSampleAgeMs;
+	}
+	/**
+	* The newest report alone against the same 2 s of sends — the short window
+	* a total freeze is judged on. Null when there is none, or it is stale.
+	*/
+	evaluateNewest(history, now) {
+		const newest = this.reports.at(-1);
+		if (newest === void 0 || now - newest.endAt > this.config.maxClientSampleAgeMs) return null;
+		const span = this.config.clientSampleSpanMs;
+		return {
+			receivedKbps: newest.kbps,
+			sentKbps: history.bitsBetween(newest.endAt - span, newest.endAt) / span,
+			windowMs: span
+		};
+	}
+	/**
+	* Received vs sent over the newest reports that together cover `windowMs`,
+	* or `null` when they do not (yet) — or the newest one is stale.
+	*/
+	evaluate(history, windowMs, now) {
+		const newest = this.reports.at(-1);
+		if (newest === void 0 || now - newest.endAt > this.config.maxClientSampleAgeMs) return null;
+		const span = this.config.clientSampleSpanMs;
+		let covered = 0;
+		let receivedBits = 0;
+		let sentBits = 0;
+		for (let i = this.reports.length - 1; i >= 0 && covered < windowMs; i -= 1) {
+			const r = this.reports[i];
+			if (r === void 0 || now - (r.endAt - span) > this.config.historySpanMs) break;
+			covered += span;
+			receivedBits += r.kbps * span;
+			sentBits += history.bitsBetween(r.endAt - span, r.endAt);
+		}
+		if (covered < windowMs) return null;
+		return {
+			receivedKbps: receivedBits / covered,
+			sentKbps: sentBits / covered,
+			windowMs: covered
+		};
+	}
+};
+//#endregion
+//#region src/stream-broker/webrtc/adaptive-config.ts
+/** How often the adaptive controller re-evaluates the ladder (ms). */
+var ADAPTIVE_TICK_MS = 2e3;
+/** Ladder tuning shared by every adaptive session. */
+var ADAPTIVE_CONFIG = {
+	analyzeWindowMs: 15e3,
+	minFailPercent: .05,
+	waitAfterResetMs: 8e3,
+	upgradeHealthyMs: 4e3,
+	upgradeHealthyGrowthFactor: 3,
+	maxProgressiveUpgradeHealthyMs: 3e4,
+	minTimeBetweenChangesMs: 4e3,
+	maxUpgradeBackoffMs: 9e5,
+	stallDeliveryRatio: .25,
+	recoverDeliveryRatio: .5,
+	freezeDeliveryRatio: .1,
+	freezeMinSentKbps: 16,
+	climbDeliveryRatio: .9,
+	stallConfirmMs: 6e3,
+	waitAfterChangeMs: 8e3,
+	climbCapacityMargin: 1.2,
+	tryClimbDeliveryRatio: .95,
+	tryClimbMaxLossRatio: .01,
+	tryBackoffBaseMs: 3e4,
+	tryBackoffMaxMs: 6e5,
+	trialMs: 2e4,
+	trialMaxMs: 4e4,
+	trialRevertRatio: .9,
+	trialRevertConsecutive: 2
+};
+/** How the delivery window is built from the client's reports. */
+var ADAPTIVE_DELIVERY_CONFIG = {
+	clientSampleSpanMs: 2e3,
+	minWindowMs: 2e3,
+	maxWindowMs: 16e3,
+	maxClientSampleAgeMs: 1e4,
+	historySpanMs: 32e3
+};
+//#endregion
+//#region src/stream-broker/webrtc/climb-capacity.ts
+/** The client ladder's thresholds (`DOWNLINK_MID_MBPS`, `DOWNLINK_HIGH_MBPS`), kbps. */
+var UNMEASURED_RUNG_BAR_KBPS = {
+	low: 0,
+	mid: 2500,
+	high: 8e3
+};
+/** The kbps the next rung needs; `(1800 × 1.2)` or the client threshold. */
+function capacityBarKbps(tier, rungKbps, margin) {
+	return rungKbps !== null && rungKbps > 0 ? rungKbps * margin : UNMEASURED_RUNG_BAR_KBPS[tier];
+}
+function known(v) {
+	return v !== null && Number.isFinite(v) && v > 0;
+}
+function judgeCapacity(evidence, nextTier, nextRungKbps, margin) {
+	const neededKbps = capacityBarKbps(nextTier, nextRungKbps, margin);
+	const { rembKbps, probeKbps, probeFresh } = evidence;
+	if (known(probeKbps) && probeFresh && probeKbps >= neededKbps) return {
+		kind: "sufficient",
+		source: "probe",
+		kbps: probeKbps,
+		neededKbps
+	};
+	if (known(rembKbps) && rembKbps >= neededKbps) return {
+		kind: "sufficient",
+		source: "remb",
+		kbps: rembKbps,
+		neededKbps
+	};
+	if (known(probeKbps) && probeKbps < neededKbps) return {
+		kind: "probe-short",
+		kbps: probeKbps,
+		neededKbps
+	};
+	return {
+		kind: "none",
+		bestKbps: known(rembKbps) ? rembKbps : null,
+		neededKbps
+	};
+}
+/**
+* REMB as it can be trusted. werift stores the LAST received estimate on the
+* sender and never ages it, so a peer that stopped sending REMB (backgrounded,
+* gone) would vouch for room indefinitely (review m5). Chrome re-estimates
+* about once a second and the value moves; an estimate unchanged for
+* `staleMs` (30 000 ms — fifteen ticks) is treated as no estimate at all.
+*/
+var RembWatch = class {
+	staleMs;
+	last = null;
+	changedAt = 0;
+	constructor(staleMs) {
+		this.staleMs = staleMs;
+	}
+	read(kbps, now) {
+		if (kbps === null) {
+			this.last = null;
+			return null;
+		}
+		if (kbps !== this.last) {
+			this.last = kbps;
+			this.changedAt = now;
+		}
+		return now - this.changedAt > this.staleMs ? null : kbps;
+	}
+};
+//#endregion
 //#region src/stream-broker/webrtc/transcode-egress-leg.ts
 /**
 * The request a browser session makes. Structured only: the primitive's schema
@@ -23295,6 +23535,8 @@ function selectAudioClock(mimeType) {
 *
 * Uses werift (optional peer dependency) for server-side WebRTC.
 */
+/** A REMB unchanged this long is no estimate (`RembWatch`). */
+var REMB_STALE_MS = 3e4;
 var _werift;
 async function loadWerift() {
 	if (_werift) return _werift;
@@ -24816,6 +25058,7 @@ var AdaptiveSession = class AdaptiveSession {
 			this.maybeRebaseRtp(pkt.header.sequenceNumber, pkt.header.timestamp);
 			try {
 				this.videoSender.sendRtp(pkt);
+				this.videoSendHistory.record(pkt.payload.length, Date.now());
 				this.lastVideoRtpTs = pkt.header.timestamp >>> 0;
 				if (this.firstVideoRtpTs === null) {
 					this.firstVideoRtpTs = this.lastVideoRtpTs;
@@ -25387,6 +25630,26 @@ var AdaptiveSession = class AdaptiveSession {
 	get rtpPacketsSentTotal() {
 		return this.rtpPacketsSent;
 	}
+	/**
+	* Video RTP PAYLOAD bytes this session sent, bucketed by time — the "sent"
+	* half of the adaptive ladder's delivery ratio (D635). Payload, not wire
+	* size, because the client's `bytesReceived` excludes RTP headers.
+	*/
+	videoSendHistory = new SendHistory(ADAPTIVE_DELIVERY_CONFIG.historySpanMs);
+	get sentVideoHistory() {
+		return this.videoSendHistory;
+	}
+	/**
+	* The receiver's bandwidth estimate (REMB) in kbps, or `null` when the peer
+	* has sent none. werift stores the last REMB on the sender; `-1`/absent in
+	* the loss line means the same "no estimate", which is not "zero".
+	*/
+	receiverEstimateKbps(now) {
+		const raw = this.videoSender?.receiverEstimatedMaxBitrate;
+		return this.rembWatch.read(typeof raw === "bigint" && raw > 0n ? Number(raw) / 1e3 : null, now);
+	}
+	/** Ages the REMB werift keeps forever — see `RembWatch`. */
+	rembWatch = new RembWatch(REMB_STALE_MS);
 	rtpLogCounter = 0;
 	/** One-shot guards for the "first video/audio RTP" debug markers. */
 	firstVideoRtpLogged = false;
@@ -25709,6 +25972,7 @@ var AdaptiveSession = class AdaptiveSession {
 					} });
 				}
 				this.videoSender.sendRtp(pkt);
+				this.videoSendHistory.record(payload.length, Date.now());
 				this.rtpPacketsSent++;
 				this.logFirstVideoRtp("writeVideoNals", codec);
 				if (this.debug && (this.rtpPacketsSent === 1 || this.rtpPacketsSent % 500 === 0)) this.logger.info("RTP packets sent", { meta: {
@@ -26176,6 +26440,42 @@ var LossTracker = class {
 //#endregion
 //#region src/stream-broker/webrtc/stall-tracker.ts
 /**
+* The one place the device-scoped telemetry is judged ownable. With more than
+* one adaptive session of the device, the record may be another viewer's:
+* delivery is unknown ("no telemetry" semantics — the loss path judges) and
+* the sample says so, so the ladder refuses a try-climb on it.
+*/
+function buildStallSample(input) {
+	if (input.adaptiveSessionsOnDevice > 1) return {
+		delivery: null,
+		recent: null,
+		clientReporting: false,
+		telemetryShared: true,
+		serverSending: input.serverSending
+	};
+	return {
+		delivery: input.delivery,
+		recent: input.recent,
+		clientReporting: input.clientReporting,
+		telemetryShared: false,
+		serverSending: input.serverSending
+	};
+}
+var UNKNOWN_EVIDENCE = {
+	clientKbps: null,
+	sentKbps: null,
+	deliveryRatio: null,
+	deliveryWindowMs: null,
+	stalledForMs: 0,
+	serverSending: false
+};
+function ratioOf(delivery) {
+	if (delivery === null) return null;
+	const { receivedKbps, sentKbps } = delivery;
+	if (!Number.isFinite(receivedKbps) || !Number.isFinite(sentKbps) || sentKbps <= 0) return null;
+	return receivedKbps / sentKbps;
+}
+/**
 * Windowed "the media stopped arriving" detector. Pure state machine: no
 * clock of its own, no side effects — `observe` is the only mutator and every
 * decision is a function of the samples it was given.
@@ -26185,11 +26485,9 @@ var StallTracker = class {
 	/** When the current uninterrupted stall began; null when not stalling. */
 	stallStartedAt = null;
 	blackoutUntil = 0;
-	lastEvidence = {
-		clientKbps: null,
-		stalledForMs: 0,
-		serverSending: false
-	};
+	lastEvidence = UNKNOWN_EVIDENCE;
+	clientReporting = false;
+	telemetryShared = false;
 	constructor(config) {
 		this.config = config;
 	}
@@ -26202,38 +26500,36 @@ var StallTracker = class {
 	* Fold one evaluation into the window. Returns nothing; ask `isStalled`.
 	*
 	* Three outcomes, and the middle one is the reason this is not a simple
-	* boolean: a rate at or above `recoverKbpsFloor` CLEARS the stall, a rate
-	* below `stallKbpsFloor` starts or extends it, and anything between the two
-	* (or unknown, or with the server idle) HOLDS whatever the window already
-	* believed. Holding is what stops a borderline link from oscillating.
+	* boolean: a ratio at or above `recoverDeliveryRatio` CLEARS the stall, a
+	* ratio below `stallDeliveryRatio` with the server sending starts or extends
+	* it, and anything between the two (or unknown, or nothing sent) HOLDS
+	* whatever the window already believed.
 	*/
 	observe(sample, now) {
+		const ratio = ratioOf(sample.delivery);
+		const measured = (stalledForMs) => ({
+			clientKbps: sample.delivery?.receivedKbps ?? null,
+			sentKbps: sample.delivery?.sentKbps ?? null,
+			deliveryRatio: ratio,
+			deliveryWindowMs: sample.delivery?.windowMs ?? null,
+			stalledForMs,
+			serverSending: sample.serverSending
+		});
+		this.clientReporting = sample.clientReporting;
+		this.telemetryShared = sample.telemetryShared;
 		if (now < this.blackoutUntil) {
 			this.stallStartedAt = null;
-			this.lastEvidence = {
-				clientKbps: sample.clientKbps,
-				stalledForMs: 0,
-				serverSending: sample.serverSending
-			};
+			this.lastEvidence = measured(0);
 			return;
 		}
-		const kbps = sample.clientKbps;
-		const age = sample.clientSampleAgeMs;
-		if (!(kbps !== null && Number.isFinite(kbps) && age !== null && age <= this.config.maxClientSampleAgeMs) || kbps === null) {
-			this.lastEvidence = {
-				clientKbps: null,
-				stalledForMs: this.stalledForMs(now),
-				serverSending: sample.serverSending
-			};
-			return;
-		}
-		if (kbps >= this.config.recoverKbpsFloor) this.stallStartedAt = null;
-		else if (kbps < this.config.stallKbpsFloor && sample.serverSending) this.stallStartedAt ??= now;
-		this.lastEvidence = {
-			clientKbps: kbps,
-			stalledForMs: this.stalledForMs(now),
-			serverSending: sample.serverSending
-		};
+		const recent = sample.recent !== null && sample.recent.sentKbps >= this.config.freezeMinSentKbps ? ratioOf(sample.recent) : null;
+		const frozen = recent !== null && recent < this.config.freezeDeliveryRatio;
+		const recovered = recent !== null && recent >= this.config.recoverDeliveryRatio;
+		const starved = ratio !== null && ratio < this.config.stallDeliveryRatio && !recovered;
+		const current = recent ?? ratio;
+		if ((frozen || starved) && sample.serverSending) this.stallStartedAt ??= now;
+		else if (current !== null && current >= this.config.recoverDeliveryRatio) this.stallStartedAt = null;
+		this.lastEvidence = measured(this.stalledForMs(now));
 	}
 	stalledForMs(now) {
 		return this.stallStartedAt === null ? 0 : now - this.stallStartedAt;
@@ -26244,25 +26540,42 @@ var StallTracker = class {
 		return this.stalledForMs(now) >= this.config.stallConfirmMs;
 	}
 	/**
-	* May the ladder PROMOTE on this evaluation?
+	* May the ladder PROMOTE on this evaluation, as far as the transport knows?
 	*
-	* False when the last fresh measurement was below `recoverKbpsFloor` —
-	* either a stall building, or a link crawling along in the dead band.
-	* Promoting there spends bandwidth the session has just been shown not to
-	* have, and the loss path cannot object: a stream delivering almost nothing
-	* reports almost no loss. Same doctrine as `LossTracker.hasEvidence` — a
-	* climb needs POSITIVE evidence, not the absence of a complaint.
+	* No while a stall is building, and no while the rung we are on is not
+	* landing (nearly) whole — promoting there spends bandwidth the session has
+	* just been shown not to have, and the loss path cannot object: a stream
+	* delivering almost nothing reports almost no loss.
 	*
-	* Unknown does not block. A deployment with no client telemetry at all must
+	* Unknown refuses only while the client IS reporting — the window is simply
+	* not covered yet, and climbing then would promote a link measured at 10 %
+	* a few seconds later. A deployment with no client telemetry at all must
 	* behave exactly as it did before this tracker existed; the loss path's own
 	* `hasEvidence` is the gate there.
 	*/
-	isClimbSafe(now) {
-		if (now < this.blackoutUntil) return true;
-		if (this.stallStartedAt !== null) return false;
-		const last = this.lastEvidence.clientKbps;
-		if (last === null) return true;
-		return last >= this.config.recoverKbpsFloor;
+	climbSafety(now) {
+		if (now < this.blackoutUntil) return { safe: true };
+		if (this.stallStartedAt !== null) return {
+			safe: false,
+			reason: "stall-building"
+		};
+		const ratio = this.lastEvidence.deliveryRatio;
+		if (ratio === null) return this.clientReporting ? {
+			safe: false,
+			reason: "delivery"
+		} : { safe: true };
+		return ratio >= this.config.climbDeliveryRatio ? { safe: true } : {
+			safe: false,
+			reason: "delivery"
+		};
+	}
+	/** Was the device's client record possibly another viewer's at the last evaluation? */
+	get isTelemetryShared() {
+		return this.telemetryShared;
+	}
+	/** Was the client reporting at the last evaluation (even if not yet covering a window)? */
+	get isClientReporting() {
+		return this.clientReporting;
 	}
 	/** What the last `observe` measured — for the switch's log line. */
 	evidence(now) {
@@ -26273,9 +26586,142 @@ var StallTracker = class {
 	}
 };
 //#endregion
+//#region src/stream-broker/webrtc/rtt-stability.ts
+/** 16 s — the longest delivery window, so both halves of a try look at the same span. */
+var RTT_WINDOW_MS = 16e3;
+var MIN_SAMPLES = 3;
+var MIN_SPREAD_MS = 20;
+var SPREAD_FRACTION = .5;
+var RttWindow = class {
+	samples = [];
+	observe(rttMs, now) {
+		if (rttMs === null || !Number.isFinite(rttMs) || rttMs <= 0) return;
+		this.samples = [...this.samples.filter((s) => now - s.at <= RTT_WINDOW_MS), {
+			rttMs,
+			at: now
+		}];
+	}
+	stability(now) {
+		const recent = this.samples.filter((s) => now - s.at <= RTT_WINDOW_MS);
+		if (recent.length < MIN_SAMPLES) return "unknown";
+		const values = recent.map((s) => s.rttMs);
+		const min = Math.min(...values);
+		return Math.max(...values) - min <= Math.max(MIN_SPREAD_MS, min * SPREAD_FRACTION) ? "stable" : "unstable";
+	}
+};
+//#endregion
+//#region src/stream-broker/webrtc/try-climb.ts
+var NO_TRY_HISTORY = {
+	failures: 0,
+	notBefore: 0,
+	lastRevert: null,
+	trialFrom: null
+};
+/** Backoff after the Nth consecutive failed try: base × 2^(N−1), capped. */
+function tryBackoffMs(failures, baseMs, maxMs) {
+	if (failures <= 0) return 0;
+	return Math.min(baseMs * 2 ** (failures - 1), maxMs);
+}
+/** Watches one tried rung through its first window. Pure: fed, never reads a clock. */
+var TrialWatch = class {
+	from;
+	config;
+	startedAt = null;
+	lowStreak = 0;
+	measured = 0;
+	constructor(from, config) {
+		this.from = from;
+		this.config = config;
+	}
+	/**
+	* Start the trial over: it must be judged afresh on live media. Called when
+	* recorded playback takes the track (review m14) — time off live must never
+	* count toward keeping a rung that was never measured.
+	*/
+	restart() {
+		this.startedAt = null;
+		this.lowStreak = 0;
+		this.measured = 0;
+	}
+	judge(now, input) {
+		this.startedAt ??= now;
+		if (input.stalled || input.lossFailing) return {
+			kind: "revert",
+			deliveryRatio: input.deliveryRatio,
+			stalled: input.stalled
+		};
+		if (input.deliveryRatio !== null) {
+			this.measured += 1;
+			this.lowStreak = input.deliveryRatio < this.config.trialRevertRatio ? this.lowStreak + 1 : 0;
+			if (this.lowStreak >= this.config.trialRevertConsecutive) return {
+				kind: "revert",
+				deliveryRatio: input.deliveryRatio,
+				stalled: false
+			};
+		}
+		const forMs = now - this.startedAt;
+		const judged = this.measured >= this.config.trialRevertConsecutive || !input.clientReporting;
+		if (forMs >= this.config.trialMs && judged || forMs >= this.config.trialMaxMs) return { kind: "kept" };
+		return {
+			kind: "running",
+			forMs
+		};
+	}
+};
+/**
+* The try-climb memory per DEVICE on this broker, with a TTL (review I4).
+* The per-session intent survives only a re-offer; without this, every new
+* viewer session of a camera whose next rung keeps failing started again at
+* try #1. The trial itself (`trialFrom`) never carries to a new session.
+*/
+var DeviceTryMemory = class {
+	ttlMs;
+	entries = /* @__PURE__ */ new Map();
+	/** @param ttlMs forget a device not refreshed for this long — 600 000 ms, the backoff cap. */
+	constructor(ttlMs) {
+		this.ttlMs = ttlMs;
+	}
+	set(deviceId, carry, now) {
+		this.entries.set(deviceId, {
+			carry,
+			at: now
+		});
+	}
+	get(deviceId, now) {
+		const entry = this.entries.get(deviceId);
+		if (entry === void 0) return null;
+		if (now - entry.at > this.ttlMs) {
+			this.entries.delete(deviceId);
+			return null;
+		}
+		return {
+			...entry.carry,
+			trialFrom: null
+		};
+	}
+};
+//#endregion
 //#region src/stream-broker/webrtc/adaptive-controller.ts
 var TIER_ORDER = require_dist.CAM_PROFILE_ORDER;
 /**
+* The cause as the wire (`WebrtcLadderDecision.cause`) can carry it. The wire
+* enum predates the try-climb, and widening it would make a server built
+* before it reject this broker's debug answer (the router validates output).
+* A trial revert is reported as what undelivered bytes are — `stall` when the
+* stall confirmed, else `loss` — and the climb hold carries the exact account
+* ("tried mid, reverted: delivery 0.60").
+*/
+function wireLadderCause(decision, stallConfirmMs) {
+	if (decision.cause !== "trial-revert") return { cause: decision.cause };
+	return {
+		cause: decision.stall.stalledForMs >= stallConfirmMs ? "stall" : "loss",
+		causeDetail: "trial-revert"
+	};
+}
+function positiveOrNull(v) {
+	return v !== null && Number.isFinite(v) && v > 0 ? v : null;
+}
+/**
 * Ladder state machine for an adaptive WebRTC session. Fed loss samples
 * (RTCP RR or client-reported) via `onLoss`; `tick` evaluates the ladder.
 * Downgrade order: tier high→mid→low, then MTU reduction at low, then
@@ -26289,7 +26735,16 @@ var TIER_ORDER = require_dist.CAM_PROFILE_ORDER;
 *     a session that has produced no RTCP at all is not "healthy", it is
 *     silent, and climbing on silence spends bandwidth never shown to exist;
 *  3. the target tier's re-attempt backoff, which doubles per measured
-*     failure of that tier in this session.
+*     failure of that tier in this session;
+*  4. the transport showing the CURRENT rung landing whole
+*     (`StallTracker.climbSafety`, a delivery ratio over one GOP — D635);
+*  5. capacity: evidence (REMB or the viewer's probe) clearing the next
+*     rung's bar confirms the climb; a MEASURED probe below it holds; with no
+*     evidence either way the ladder TRIES the rung on a clean path (delivery
+*     ≥ 0.95, loss < 1 %, RTT stable) and reverts within the rung's first
+*     window if it does not land, backing off 30 s → 10 min (D635, round 2).
+*
+* Every tick that does not promote leaves a {@link ClimbHold} naming why.
 */
 var AdaptiveController = class {
 	opts;
@@ -26310,6 +26765,16 @@ var AdaptiveController = class {
 	armed = false;
 	failures;
 	upgradeCount;
+	capacity = {
+		rembKbps: null,
+		probeKbps: null,
+		probeFresh: false
+	};
+	rtt = new RttWindow();
+	tryCarry;
+	/** Non-null while the current rung is a trial. */
+	trial;
+	hold = null;
 	constructor(opts) {
 		this.opts = opts;
 		this.tracker = new LossTracker(opts.config);
@@ -26317,6 +26782,16 @@ var AdaptiveController = class {
 		this.tier = opts.initialTier;
 		this.failures = new Map(opts.priorFailures ?? []);
 		this.upgradeCount = Math.max(0, opts.priorUpgradeCount ?? 0);
+		const carried = opts.tryClimb ?? NO_TRY_HISTORY;
+		this.tryCarry = carried.trialFrom === opts.initialTier ? {
+			...carried,
+			trialFrom: null
+		} : carried;
+		this.trial = this.tryCarry.trialFrom !== null ? new TrialWatch(this.tryCarry.trialFrom, opts.config) : null;
+	}
+	/** What the NEXT controller of this viewer session must inherit about tries. */
+	get tryClimbCarry() {
+		return this.tryCarry;
 	}
 	get currentTier() {
 		return this.tier;
@@ -26349,6 +26824,27 @@ var AdaptiveController = class {
 		this.stalls.observe(sample, now);
 	}
 	/**
+	* The capacity witnesses, kbps — `null` when unknown: the receiver's REMB
+	* (capped by what is sent, so evidence only FOR room) and the viewer's
+	* downlink probe for this session (a path measurement, evidence both ways).
+	* See `climb-capacity.ts`.
+	*/
+	onCapacity(evidence) {
+		this.capacity = {
+			rembKbps: positiveOrNull(evidence.rembKbps),
+			probeKbps: positiveOrNull(evidence.probeKbps),
+			probeFresh: evidence.probeFresh
+		};
+	}
+	/** The client's round-trip time, ms; null/0 = unknown. One of a try's conditions. */
+	onRtt(rttMs, now) {
+		this.rtt.observe(rttMs, now);
+	}
+	/** Why the ladder did not climb on the last evaluation; null = at the top, or it just moved. */
+	get climbHold() {
+		return this.hold;
+	}
+	/**
 	* Freeze the ladder for this evaluation instead of ticking it.
 	*
 	* Called while the session's track is NOT carrying the live source — D42
@@ -26369,6 +26865,8 @@ var AdaptiveController = class {
 			this.lastChangeAt = now;
 		}
 		this.healthySince = now;
+		this.trial?.restart();
+		this.setHold("suspended", now);
 		this.stalls.markChanged(now);
 	}
 	tick(now) {
@@ -26377,26 +26875,132 @@ var AdaptiveController = class {
 			this.healthySince = now;
 			this.lastChangeAt = now;
 		}
+		if (this.trial !== null && this.judgeTrial(now)) return;
 		if (this.stalls.isStalled(now)) {
 			this.healthySince = now;
+			this.hold = null;
 			this.handleFailing(now, "stall");
 			return;
 		}
 		if (this.tracker.isFailing(now)) {
 			this.healthySince = now;
+			this.hold = null;
 			this.handleFailing(now, "loss");
 			return;
 		}
-		if (!this.stalls.isClimbSafe(now)) {
+		const safety = this.stalls.climbSafety(now);
+		if (!safety.safe) {
 			this.healthySince = now;
+			this.setHold(safety.reason, now);
 			return;
 		}
 		if (!this.tracker.hasEvidence(now)) {
 			this.healthySince = now;
+			this.setHold("no-evidence", now);
 			return;
 		}
 		this.handleHealthy(now);
 	}
+	nextTier() {
+		const idx = TIER_ORDER.indexOf(this.tier);
+		return idx <= 0 ? null : TIER_ORDER[idx - 1] ?? null;
+	}
+	/**
+	* Record why this evaluation did not climb. At the top rung there is nothing
+	* to hold — except a `trial`, which names the rung being tried.
+	*/
+	setHold(code, now, extra = {}) {
+		const next = code === "trial" ? this.tier : this.nextTier();
+		if (next === null) {
+			this.hold = null;
+			return;
+		}
+		const ev = this.stalls.evidence(now);
+		const clockRunning = code === "warming" || code === "cooldown" || code === "capacity" || code === "try-unclean" || code === "try-backoff";
+		const nextTierKbps = this.opts.expectedTierKbps?.(next) ?? null;
+		this.hold = {
+			code,
+			nextTier: next,
+			deliveryRatio: ev.deliveryRatio,
+			deliveryWindowMs: ev.deliveryWindowMs,
+			climbDeliveryRatio: this.opts.config.climbDeliveryRatio,
+			capacityKbps: this.capacity.rembKbps,
+			probeKbps: this.capacity.probeKbps,
+			nextTierKbps,
+			capacityMargin: this.opts.config.climbCapacityMargin,
+			neededKbps: capacityBarKbps(next, nextTierKbps, this.opts.config.climbCapacityMargin),
+			tryBlockedBy: extra.tryBlockedBy ?? null,
+			tryDeliveryRatio: this.opts.config.tryClimbDeliveryRatio,
+			tryMaxLossRatio: this.opts.config.tryClimbMaxLossRatio,
+			retryInMs: code === "try-backoff" ? Math.max(0, this.tryCarry.notBefore - now) : null,
+			lastRevert: this.tryCarry.lastRevert,
+			trialForMs: code === "trial" ? extra.trialForMs ?? 0 : null,
+			trialMs: code === "trial" ? this.opts.config.trialMs : null,
+			healthyForMs: clockRunning ? now - this.healthySince : null,
+			requiredHealthyMs: this.requiredHealthyMs(next),
+			since: this.hold?.code === code ? this.hold.since : now
+		};
+	}
+	/**
+	* Judge the rung on trial. Returns true when this evaluation is consumed
+	* (still running, or reverted); false when the trial was just kept and the
+	* ordinary ladder takes over.
+	*/
+	judgeTrial(now) {
+		const watch = this.trial;
+		if (watch === null) return false;
+		const verdict = watch.judge(now, {
+			deliveryRatio: this.stalls.evidence(now).deliveryRatio,
+			clientReporting: this.stalls.isClientReporting,
+			stalled: this.stalls.isStalled(now),
+			lossFailing: this.tracker.isFailing(now)
+		});
+		if (verdict.kind === "running") {
+			this.healthySince = now;
+			this.setHold("trial", now, { trialForMs: verdict.forMs });
+			return true;
+		}
+		this.trial = null;
+		if (verdict.kind === "kept") {
+			this.tryCarry = NO_TRY_HISTORY;
+			this.healthySince = now;
+			return false;
+		}
+		const failures = this.tryCarry.failures + 1;
+		const tried = this.tier;
+		this.tryCarry = {
+			failures,
+			notBefore: now + tryBackoffMs(failures, this.opts.config.tryBackoffBaseMs, this.opts.config.tryBackoffMaxMs),
+			lastRevert: {
+				tier: tried,
+				deliveryRatio: verdict.deliveryRatio,
+				stalled: verdict.stalled,
+				at: now
+			},
+			trialFrom: null
+		};
+		this.hold = null;
+		this.tier = watch.from;
+		this.mtuReduced = false;
+		this.transcodeEngaged = false;
+		this.opts.onSwitchTier(watch.from, this.decisionAt(now, "trial-revert"));
+		this.commitChange(now);
+		this.healthySince = now;
+		return true;
+	}
+	/**
+	* Which clean-path condition refuses a TRY, or null when the path is clean.
+	* A client that sends no telemetry at all cannot measure delivery; there the
+	* loss path is the judge, as it was before delivery existed.
+	*/
+	tryBlocker(now) {
+		if (this.stalls.isTelemetryShared) return "shared-telemetry";
+		const ratio = this.stalls.evidence(now).deliveryRatio;
+		if (ratio === null ? this.stalls.isClientReporting : ratio < this.opts.config.tryClimbDeliveryRatio) return "delivery";
+		if (this.tracker.lossRatio() >= this.opts.config.tryClimbMaxLossRatio) return "loss";
+		if (this.rtt.stability(now) === "unstable") return "rtt";
+		return null;
+	}
 	canUpgrade(now) {
 		return now - this.lastChangeAt >= this.opts.config.minTimeBetweenChangesMs;
 	}
@@ -26417,11 +27021,12 @@ var AdaptiveController = class {
 		this.stalls.markChanged(now);
 	}
 	/** The measurement this decision rests on, snapshotted for the log line. */
-	decisionAt(now, cause) {
+	decisionAt(now, cause, trial = false) {
 		return {
 			cause,
 			lossRatio: this.tracker.lossRatio(),
-			stall: this.stalls.evidence(now)
+			stall: this.stalls.evidence(now),
+			trial
 		};
 	}
 	handleFailing(now, cause) {
@@ -26448,21 +27053,223 @@ var AdaptiveController = class {
 		}
 	}
 	handleHealthy(now) {
-		const idx = TIER_ORDER.indexOf(this.tier);
-		if (idx <= 0) return;
-		const next = TIER_ORDER[idx - 1];
-		if (now - this.healthySince < this.requiredHealthyMs(next)) return;
-		if (!this.canUpgrade(now)) return;
+		const next = this.nextTier();
+		if (next === null) {
+			this.hold = null;
+			return;
+		}
+		const capacity = judgeCapacity(this.capacity, next, this.opts.expectedTierKbps?.(next) ?? null, this.opts.config.climbCapacityMargin);
+		if (capacity.kind === "probe-short") {
+			this.setHold("capacity", now);
+			return;
+		}
+		if (capacity.kind === "none" && now < this.tryCarry.notBefore) {
+			this.setHold("try-backoff", now);
+			return;
+		}
+		if (now - this.healthySince < this.requiredHealthyMs(next)) {
+			this.setHold("warming", now);
+			return;
+		}
+		if (!this.canUpgrade(now)) {
+			this.setHold("cooldown", now);
+			return;
+		}
+		if (capacity.kind === "sufficient") {
+			this.promote(now, next, false);
+			return;
+		}
+		const blocker = this.tryBlocker(now);
+		if (blocker !== null) {
+			this.setHold("try-unclean", now, { tryBlockedBy: blocker });
+			return;
+		}
+		this.promote(now, next, true);
+	}
+	promote(now, next, trial) {
+		const from = this.tier;
+		this.hold = null;
 		this.tier = next;
 		this.mtuReduced = false;
 		this.transcodeEngaged = false;
 		this.upgradeCount += 1;
-		this.opts.onSwitchTier(next, this.decisionAt(now, "healthy"));
+		this.tryCarry = {
+			...this.tryCarry,
+			trialFrom: trial ? from : null
+		};
+		this.trial = trial ? new TrialWatch(from, this.opts.config) : null;
+		this.opts.onSwitchTier(next, this.decisionAt(now, "healthy", trial));
 		this.commitChange(now);
 		this.healthySince = now;
 	}
 };
 //#endregion
+//#region src/stream-broker/webrtc/climb-hold.ts
+/** The wire shape: the hold plus the line the broker logs. */
+function toWireClimbHold(h) {
+	return {
+		...h,
+		summary: describeClimbHold(h)
+	};
+}
+function seconds(ms) {
+	return `${(ms / 1e3).toFixed(1)}s`;
+}
+/** A rate, or "unknown" — never a fabricated 0 kbps (D393). */
+function kbps(v) {
+	return v === null ? "unknown" : `${String(Math.round(v))} kbps`;
+}
+function deliveryPart(h) {
+	if (h.deliveryRatio === null || h.deliveryWindowMs === null) return null;
+	return `delivery ${h.deliveryRatio.toFixed(2)} over ${seconds(h.deliveryWindowMs)}`;
+}
+/** `mid needs 2160 kbps (1800 × 1.2)`, or `(client threshold)` for an unmeasured rung. */
+function barPart(h) {
+	const basis = h.nextTierKbps !== null && h.nextTierKbps > 0 ? `(${String(Math.round(h.nextTierKbps))} × ${String(h.capacityMargin)})` : "(client threshold)";
+	return `${h.nextTier} needs ${kbps(h.neededKbps)} ${basis}`;
+}
+function witnesses(h) {
+	return `${h.capacityKbps === null ? "no REMB" : `REMB ${kbps(h.capacityKbps)}`}, ${h.probeKbps === null ? "no probe" : `probe ${kbps(h.probeKbps)}`}`;
+}
+function blockerPart(h) {
+	switch (h.tryBlockedBy) {
+		case "delivery": return h.deliveryRatio === null ? "delivery not measured" : `delivery ${h.deliveryRatio.toFixed(2)} < ${h.tryDeliveryRatio.toFixed(2)}`;
+		case "loss": return `loss ≥ ${String(Math.round(h.tryMaxLossRatio * 1e3) / 10)}%`;
+		case "rtt": return "RTT unstable";
+		case "shared-telemetry": return "another viewer shares this camera's telemetry";
+		case null: return "unknown";
+	}
+}
+function revertPart(h) {
+	const r = h.lastRevert;
+	if (r === null) return "a try reverted";
+	const why = r.stalled ? "stall" : r.deliveryRatio === null ? "loss" : `delivery ${r.deliveryRatio.toFixed(2)}`;
+	return `tried ${r.tier}, reverted: ${why}`;
+}
+/**
+* One line, English, numbers included — the same text the broker logs and the
+* viewer shows under its localized hold label. Every number is one the
+* controller actually used; an unknown one is said to be unknown.
+*/
+function describeClimbHold(h) {
+	const delivery = deliveryPart(h);
+	switch (h.code) {
+		case "stall-building": return `held: stall building (${delivery ?? "delivery unknown"})`;
+		case "delivery": return delivery === null ? "held: delivery not yet measured over one GOP" : `held: ${delivery} < ${h.climbDeliveryRatio.toFixed(2)}`;
+		case "no-evidence": return "held: no receiver feedback in the loss window";
+		case "warming": return `climbing: healthy ${seconds(h.healthyForMs ?? 0)} of ${seconds(h.requiredHealthyMs ?? 0)} before ${h.nextTier}`;
+		case "cooldown": return "held: too soon after the last change";
+		case "capacity": return `held: probe ${kbps(h.probeKbps)}, ${h.capacityKbps === null ? "no REMB" : `REMB ${kbps(h.capacityKbps)}`} < ${barPart(h)}`;
+		case "try-unclean": return `held: no capacity evidence for ${h.nextTier} (${witnesses(h)}); not clean enough to try: ${blockerPart(h)}`;
+		case "try-backoff": return `held: ${revertPart(h)}; next try in ${seconds(h.retryInMs ?? 0)}`;
+		case "trial": return `trying ${h.nextTier}: ${seconds(h.trialForMs ?? 0)} of ${seconds(h.trialMs ?? 0)} (reverts if it does not land)`;
+		case "suspended": return "held: recorded playback on the track (ladder suspended)";
+	}
+}
+/**
+* Which hold changes deserve a log line (review m3). A code logs when it
+* differs from the last one logged AND has not itself been logged within
+* `quietMs` — a link hovering at 0.90–0.95 delivery cycles delivery →
+* warming → try-unclean and used to write a line every 4–8 s for ever.
+* Progress (`warming`, `trial`) never logs; the switch line covers moves.
+*/
+var HoldLogGate = class {
+	quietMs;
+	last = null;
+	loggedAt = /* @__PURE__ */ new Map();
+	constructor(quietMs) {
+		this.quietMs = quietMs;
+	}
+	shouldLog(code, now) {
+		if (code === "warming" || code === "trial") return false;
+		if (code === this.last) return false;
+		const at = this.loggedAt.get(code);
+		if (at !== void 0 && now - at < this.quietMs) return false;
+		this.last = code;
+		this.loggedAt.set(code, now);
+		return true;
+	}
+};
+//#endregion
+//#region src/stream-broker/webrtc/rung-bitrate.ts
+/**
+* Shortest lifetime whose average means anything: 4 000 ms ≈ one GOP on the
+* cameras this hub serves; less than that is one IDR divided by nothing.
+*/
+var MIN_AVERAGE_UPTIME_MS = 4e3;
+function expectedRungKbps(stats) {
+	const lifetime = stats.totalBytes > 0 && stats.uptimeMs >= MIN_AVERAGE_UPTIME_MS ? Math.round(stats.totalBytes * 8 / stats.uptimeMs) : null;
+	const windowKbps = stats.status === "streaming" && stats.bitrateKbps > 0 ? stats.bitrateKbps : null;
+	if (windowKbps === null) return lifetime;
+	return lifetime === null ? windowKbps : Math.max(windowKbps, lifetime);
+}
+/** The client's probe cache TTL (`DOWNLINK_TTL_MS`): the oldest a hinted probe can be. */
+var HINT_PROBE_MAX_AGE_MS = 3e4;
+function mbpsToKbps(mbps) {
+	return mbps !== void 0 && Number.isFinite(mbps) && mbps > 0 ? mbps * 1e3 : null;
+}
+/** The probe an offer carried, dated conservatively; null when it carried none. */
+function probeFromHints(downlinkMbps, now) {
+	const kbps = mbpsToKbps(downlinkMbps);
+	return kbps === null ? null : {
+		kbps,
+		at: now - HINT_PROBE_MAX_AGE_MS
+	};
+}
+/** The probe a telemetry report carried; null when it carried none. */
+function probeFromReport(report, now) {
+	const kbps = mbpsToKbps(report.downlinkMbps);
+	if (kbps === null) return null;
+	return {
+		kbps,
+		at: now - Math.max(0, report.reportAgeMs) - Math.max(0, report.downlinkAgeMs)
+	};
+}
+/** The more recent of two probes (either may be absent). */
+function newerProbe(a, b) {
+	if (a === null) return b;
+	if (b === null) return a;
+	return b.at >= a.at ? b : a;
+}
+function isProbeFresh(probe, now) {
+	return probe !== null && now - probe.at <= 12e4;
+}
+/**
+* How long the broker keeps a device's probe at all. 600 000 ms (10 min, the
+* try-backoff cap). A SHORT probe holds a climb until a newer probe replaces
+* it — and a viewer that cannot probe (no token yet, a share link, whose token
+* is not session-grade) never supplies one, so without an end one viewer's
+* 1.2 Mbps reading would hold every such viewer of the camera on `capacity`
+* until the broker restarted (review N1).
+*/
+var PROBE_MEMORY_TTL_MS = 6e5;
+/** The newest probe per device, bounded in time and forgotten with the device's last session. */
+var DeviceProbeMemory = class {
+	ttlMs;
+	probes = /* @__PURE__ */ new Map();
+	constructor(ttlMs) {
+		this.ttlMs = ttlMs;
+	}
+	/** Keep `probe` if it is newer than what is held; an absent one changes nothing. */
+	record(deviceId, probe) {
+		const kept = newerProbe(this.probes.get(deviceId) ?? null, probe);
+		if (kept !== null) this.probes.set(deviceId, kept);
+	}
+	get(deviceId, now) {
+		const probe = this.probes.get(deviceId);
+		if (probe === void 0) return null;
+		if (now - probe.at > this.ttlMs) {
+			this.probes.delete(deviceId);
+			return null;
+		}
+		return probe;
+	}
+	/** The device's last adaptive session ended: nobody's probe speaks for the next viewer. */
+	forget(deviceId) {
+		this.probes.delete(deviceId);
+	}
+};
+//#endregion
 //#region src/stream-broker/webrtc/session-debug.ts
 /** `<deviceId>/<camStreamId>` → the camStreamId, or null when it is not one. */
 function camStreamIdOf(brokerId) {
@@ -26501,7 +27308,8 @@ var DEAD = {
 	trackMode: null,
 	lastDecision: null,
 	tierFailures: [],
-	upgradeCount: null
+	upgradeCount: null,
+	climbHold: null
 };
 function projectSessionDebug(input) {
 	const { session } = input;
@@ -26538,7 +27346,8 @@ function projectSessionDebug(input) {
 			tier,
 			failures
 		})),
-		upgradeCount: input.ladder?.upgradeCount ?? null
+		upgradeCount: input.ladder?.upgradeCount ?? null,
+		climbHold: input.ladder?.climbHold ?? null
 	};
 }
 var PLAYBACK_PROFILE_FALLBACK_ORDER = [
@@ -26564,6 +27373,22 @@ function gapReachable(gap, epochMs) {
 }
 //#endregion
 //#region src/stream-broker/recorded/control-protocol.ts
+/**
+* The rates a clip may be OFFERED at — re-exported from the capability, which
+* is where the one list lives (D612). The broker owns the clamp; the cap owns
+* the ladder; a second list here would be the second authority D62 forbids.
+*
+* Declared at the top of the file because the clamp and the `setRate` bound
+* are DERIVED from its ends (D621). They were three literals — this array, a
+* `Math.min(4, …)` and a `.max(4)` — and that is precisely how 8 and 16 came
+* to be offered while the clamp served 4 with no line anywhere saying so. One
+* decision now has one place to be written down.
+*/
+var BROKER_PACED_RATES = require_dist.CLIP_BROKER_PACED_RATES;
+/** The slowest offered rate. Anything slower is clamped up to it. */
+var MIN_PACED_RATE = Math.min(...BROKER_PACED_RATES);
+/** The fastest offered rate. Anything faster is refused at the wire. */
+var MAX_PACED_RATE = Math.max(...BROKER_PACED_RATES);
 var ControlMessageSchema = require_dist.discriminatedUnion("t", [
 	require_dist.object({
 		t: require_dist.literal("playRecorded"),
@@ -26630,7 +27455,7 @@ var ControlMessageSchema = require_dist.discriminatedUnion("t", [
 	}),
 	require_dist.object({
 		t: require_dist.literal("setRate"),
-		rate: require_dist.number().min(0).max(4)
+		rate: require_dist.number().min(0).max(MAX_PACED_RATE)
 	}),
 	require_dist.object({
 		t: require_dist.literal("stepFrame"),
@@ -26643,22 +27468,41 @@ var ControlMessageSchema = require_dist.discriminatedUnion("t", [
 	})
 ]);
 /**
-* Clamp a requested playback rate onto the supported domain: {0} ∪ [0.25, 4].
-* 0 (and any non-finite / non-positive input) pauses; anything else is a
-* continuous rate clamped into [0.25, 4]. Single server-side authority — the
-* feeder applies it to every inbound `setRate`.
+* Clamp a requested playback rate onto the supported domain:
+* {0} ∪ [{@link MIN_PACED_RATE}, {@link MAX_PACED_RATE}] — the ends of
+* {@link BROKER_PACED_RATES} itself. 0 (and any non-finite / non-positive
+* input) pauses; anything else is a continuous rate clamped into that band.
+* Single server-side authority — the feeder applies it to every inbound
+* `setRate`.
+*
+* That every ladder entry survives this unchanged is now structural rather
+* than a discipline. What is NOT structural, and is therefore the gate that
+* matters, is whether the pacer really empties a clip `rate` times faster:
+* `clip-stream-feeder.spec` drives every entry and measures it.
 */
 function clampPlaybackRate(rate) {
 	if (!Number.isFinite(rate) || rate <= 0) return 0;
-	return Math.min(4, Math.max(.25, rate));
+	return Math.min(MAX_PACED_RATE, Math.max(MIN_PACED_RATE, rate));
 }
 /**
-* The rates a clip may be OFFERED at — re-exported from the capability, which
-* is where the one list lives (D612). The broker owns the clamp; the cap owns
-* the ladder; a second list here would be the second authority D62 forbids.
-* `control-protocol.spec` pins that every entry survives {@link clampPlaybackRate}.
+* Does a clip carry SOUND at this rate?
+*
+* ONE predicate, read by the branch that DROPS the audio
+* (`ClipStreamFeeder.pushNextAudio`) and by the branch that TELLS the viewer
+* why it is silent — because a second copy of `rate !== 1` is exactly the
+* disagreeing second switch D62 forbids, and the telling would then be able
+* to describe a drop that did not happen (or miss one that did).
+*
+* *"L'audio non serve in velocità non 1x!!!"* — the operator, 2026-09-23.
+* Resampling would need a decoder this path has not got, and pitch-shifted
+* sound is worse than none.
+*
+* Rate 0 is PAUSE, not a rate: nothing plays at all there, so it is not this
+* predicate's business and callers hold their last non-zero rate instead.
 */
-var BROKER_PACED_RATES = require_dist.CLIP_BROKER_PACED_RATES;
+function audioPlaysAtRate(rate) {
+	return rate === 1;
+}
 var ServerMessageSchema = require_dist.discriminatedUnion("t", [
 	require_dist.object({
 		t: require_dist.literal("state"),
@@ -26699,6 +27543,14 @@ var ServerMessageSchema = require_dist.discriminatedUnion("t", [
 		clipId: require_dist.string().min(1),
 		durationMs: require_dist.number().positive()
 	}),
+	require_dist.object({
+		t: require_dist.literal("clipIncomplete"),
+		clipId: require_dist.string().min(1),
+		code: require_dist._enum(["stream-short", "stream-empty"]),
+		/** The provider's own sentence, already Latin-1 safe. Shown where the
+		*  stream error is shown. */
+		reason: require_dist.string().min(1)
+	}),
 	require_dist.object({
 		t: require_dist.literal("clipAudio"),
 		clipId: require_dist.string().min(1),
@@ -26711,8 +27563,23 @@ var ServerMessageSchema = require_dist.discriminatedUnion("t", [
 			"no-audio-track",
 			"unsupported-codec",
 			"codec-mismatch",
-			"stream-failed"
-		]).optional()
+			"stream-failed",
+			"rate"
+		]).optional(),
+		/**
+		* The rate the sound is suppressed AT. Present iff `reason` is `rate`,
+		* and refused otherwise — see the check below.
+		*/
+		rate: require_dist.number().positive().optional()
+	}).check((ctx) => {
+		const value = ctx.value;
+		if (value.reason === "rate" === (value.rate !== void 0)) return;
+		ctx.issues.push({
+			code: "custom",
+			message: "`rate` is present exactly when `reason` is `rate`",
+			input: value,
+			path: ["rate"]
+		});
 	})
 ]);
 function parseControlMessage(raw) {
@@ -27684,7 +28551,7 @@ var RecordedFeeder = class {
 	/** Audio clock (PCMU 8 kHz / Opus 48 kHz); re-anchored together with video. */
 	audioClock;
 	clockHasAdvanced = false;
-	/** Playback rate: 0 (paused) or a continuous factor in [0.25, 4]. */
+	/** Playback rate: 0 (paused) or a continuous factor in [0.25, 8]. */
 	rate = 1;
 	disposed = false;
 	seekToken = 0;
@@ -28265,7 +29132,7 @@ var RecordedFeeder = class {
 	}
 	/**
 	* Set playback rate. 0 pauses in place (the pacing loop aborts on its next
-	* guard check); any other value is clamped to [0.25, 4].
+	* guard check); any other value is clamped to [0.25, 8].
 	*
 	* Rate-change strategy (documented choice): every transition TO a non-zero
 	* rate — resume from pause AND a playing→playing rate change — re-enters via
@@ -30130,17 +30997,25 @@ var TimelineSession = class {
 		this.lastPositionMs = null;
 		const feeder = this.enterRecorded();
 		await feeder.seek(offsetMs);
-		await Promise.all([this.reportClipDuration(clipId, feeder), this.reportClipAudio(clipId, feeder)]);
+		await Promise.all([
+			this.reportClipDuration(clipId, feeder),
+			this.reportClipAudio(clipId, feeder),
+			this.reportClipIncomplete(clipId, feeder)
+		]);
 	}
 	/**
 	* Tell the viewer whether this clip has sound.
 	*
-	* Silence has three causes the operator cannot tell apart by listening —
-	* a camera with no microphone, a transport that carried no audio, and a
-	* session that negotiated none — so the viewer is told which. Every branch
-	* that sends nothing says so (D391): a feeder that cannot answer, an answer
-	* that rejected, and an answer that landed after the pointer had left the
-	* clip, which must not be pinned on whatever came next.
+	* Silence has causes the operator cannot tell apart by listening — a camera
+	* with no microphone, a transport that carried no audio, a session that
+	* negotiated none, and (D621) a clip playing at anything but 1×, where the
+	* broker drops every frame on purpose — so the viewer is told which. Every
+	* branch that sends nothing says so (D391): a feeder that cannot answer, an
+	* answer that rejected, and an answer that landed after the pointer had left
+	* the clip, which must not be pinned on whatever came next.
+	*
+	* The first answer SETTLES; the rate does not, so this also subscribes for
+	* as long as the clip is on the pointer.
 	*/
 	async reportClipAudio(clipId, feeder) {
 		if (feeder.audio === void 0) {
@@ -30161,11 +31036,25 @@ var TimelineSession = class {
 			});
 			return;
 		}
+		this.sendClipAudio(clipId, report);
+		feeder.watchAudio?.((later) => this.sendClipAudio(clipId, later));
+	}
+	/**
+	* Send one `clipAudio`, or say why nothing was sent.
+	*
+	* ONE place, for the settle and for every later change: they are the same
+	* statement about the same clip, and a second builder is how the two would
+	* come to disagree about what `reason` means. The clip-identity guard lives
+	* here too — a report that lands after the pointer has left names a clip
+	* nobody is playing, and the viewer would mute whatever came next.
+	*/
+	sendClipAudio(clipId, report) {
 		if (this.clip?.clipId !== clipId) {
 			this.deps.onLog?.("clip playback: audio dropped — the pointer has left this clip", {
 				deviceId: this.deps.deviceId,
 				clipId,
-				carried: report.carried
+				carried: report.carried,
+				reason: report.reason
 			});
 			return;
 		}
@@ -30175,6 +31064,7 @@ var TimelineSession = class {
 			carried: report.carried,
 			codec: report.codec,
 			reason: report.reason,
+			rate: report.rate,
 			detail: report.detail
 		});
 		this.deps.session.sendControl(serializeServerMessage({
@@ -30182,7 +31072,63 @@ var TimelineSession = class {
 			clipId,
 			carried: report.carried,
 			...report.codec !== null ? { codec: report.codec } : {},
-			...report.reason !== null ? { reason: report.reason } : {}
+			...report.reason !== null ? { reason: report.reason } : {},
+			...report.reason === "rate" && report.rate !== void 0 ? { rate: report.rate } : {}
+		}));
+	}
+	/**
+	* Tell the operator that the clip he is watching did not arrive whole
+	* (D623), in the surface that already shows him a stream error.
+	*
+	* Awaited AFTER the stream ends, which is when the provider gets to speak,
+	* and guarded by the clip identity for the same reason the audio report is:
+	* a late answer names a clip nobody is playing and the viewer would put the
+	* complaint on whatever came next.
+	*
+	* There is no retry here and there must not be one. *"Se cade la sessione
+	* cade non fa niente"* — the operator, 2026-09-23. A second dial would
+	* contend for the camera's single replay lane exactly while that lane is
+	* already failing.
+	*/
+	async reportClipIncomplete(clipId, feeder) {
+		if (feeder.incomplete === void 0) {
+			this.deps.onLog?.("clip playback: completeness not reported — this feeder cannot ask the provider", {
+				deviceId: this.deps.deviceId,
+				clipId
+			});
+			return;
+		}
+		let report;
+		try {
+			report = await feeder.incomplete();
+		} catch (err) {
+			this.deps.onLog?.("clip playback: completeness not reported — the answer failed", {
+				deviceId: this.deps.deviceId,
+				clipId,
+				error: err instanceof Error ? err.message : String(err)
+			});
+			return;
+		}
+		if (report === null) return;
+		if (this.clip?.clipId !== clipId) {
+			this.deps.onLog?.("clip playback: completeness dropped — the pointer has left this clip", {
+				deviceId: this.deps.deviceId,
+				clipId,
+				code: report.code
+			});
+			return;
+		}
+		this.deps.onLog?.("clip playback: the clip did not arrive whole", {
+			deviceId: this.deps.deviceId,
+			clipId,
+			code: report.code,
+			reason: report.reason
+		});
+		this.deps.session.sendControl(serializeServerMessage({
+			t: "clipIncomplete",
+			clipId,
+			code: report.code,
+			reason: report.reason
 		}));
 	}
 	/**
@@ -31584,7 +32530,7 @@ function createFmp4StreamDemuxer(options = {}) {
 *   faster than the camera sends.
 * - `stepFrame(-1)` and the scrub verbs are refused by name; `stepFrame(+1)`
 *   pushes the next buffered unit.
-* - `setRate` is the PLAYER's rate over frames already here ({0} ∪ [0.25, 4],
+* - `setRate` is the PLAYER's rate over frames already here ({0} ∪ [0.25, 8],
 *   the recorded domain). The camera's own `playSpeed` (8, 16 — real, the app
 *   reopens the replay at 8) is a different mechanism and is NOT wired: it
 *   would go on the dial (`videoclips.dialClipStream` → the cmd-5 replay's
@@ -31650,6 +32596,11 @@ function createFmp4StreamDemuxer(options = {}) {
 * `data`, which the broker's `onLog` puts in `tags`.
 */
 /**
+* The reason an in-flight open is abandoned, carried on the abort so the
+* opener's refusal and the provider's log line say the same thing.
+*/
+var CLIP_STREAM_ABANDONED = "clip-stream-abandoned";
+/**
 * The same ceiling as the file path (`CLIP_SOURCE_MAX_BYTES`): a clip the
 * file path would refuse `too-large` is one this path stops taking. Frames
 * behind the head are released as they are pushed, so the backlog is the
@@ -31672,6 +32623,8 @@ var ClipStreamFeeder = class {
 	deps;
 	phase = "idle";
 	connection = null;
+	/** Armed for the length of one `open()`; aborted by {@link teardown}. */
+	opening = null;
 	demuxer;
 	clock = new MonotonicClock();
 	/** The RTP rate the audio sender negotiated — a CONVERSION, not a clock. */
@@ -31684,10 +32637,28 @@ var ClipStreamFeeder = class {
 	audioPushed = 0;
 	audioDroppedLate = 0;
 	audioDroppedRate = 0;
+	/**
+	* The last report handed to a caller — the settle promise's value, or the
+	* newest one {@link watchAudio}'s listener was given. What a change is
+	* measured against, so the same answer is never announced twice.
+	*/
+	audioEmitted = null;
+	/**
+	* The last NON-ZERO rate. Pause is the absence of a rate, not a rate: a
+	* `clipAudio` blaming the speed while the clip is stopped would be false,
+	* and un-pausing would have to take it back.
+	*/
+	audioRate = 1;
+	audioListener = null;
 	audioDroppedSeek = 0;
 	firstAudioLogged = false;
 	audioReport = null;
 	audioWaiters = [];
+	/** The provider's last word, and whether it has been given. Settled is not
+	*  the same as non-null: a whole stream settles `null` (D623). */
+	incompleteSettled = false;
+	incompleteReport = null;
+	incompleteWaiters = [];
 	clockHasAdvanced = false;
 	rate = 1;
 	queue = [];
@@ -31719,12 +32690,16 @@ var ClipStreamFeeder = class {
 	firstFrameLogged = false;
 	maxBufferedBytes;
 	stallTimeoutMs;
+	prerollMs;
+	/** True while the pacer is waiting for the cushion to refill after a starve. */
+	rebuffering = false;
 	now;
 	tags;
 	constructor(deps) {
 		this.deps = deps;
 		this.maxBufferedBytes = deps.maxBufferedBytes ?? CLIP_STREAM_BUFFER_MAX_BYTES;
 		this.stallTimeoutMs = deps.stallTimeoutMs ?? 15e3;
+		this.prerollMs = deps.prerollMs ?? 600;
 		this.now = deps.now ?? (() => Date.now());
 		this.tags = {
 			deviceId: deps.handle.deviceId,
@@ -31822,6 +32797,8 @@ var ClipStreamFeeder = class {
 		this.clock.setRate(next);
 		const wasPaused = this.rate === 0;
 		this.rate = next;
+		this.audioRate = next;
+		this.refreshAudioReport();
 		if (this.phase !== "streaming" || this.pendingSeekMs !== null) return;
 		if (wasPaused) this.emitState("playing", "set-rate-resume", this.seekToken);
 		this.startPacing();
@@ -31856,6 +32833,19 @@ var ClipStreamFeeder = class {
 		return new Promise((resolve) => this.durationWaiters.push(resolve));
 	}
 	/**
+	* Did the provider deliver this clip whole? (D623)
+	*
+	* Resolves `null` for a whole stream AND for one that never got to say —
+	* cut, disposed, or opened against a provider that adds no trailer. Both are
+	* "nothing to tell the operator", and neither may be reported as a defect:
+	* a cut already announces itself as `state: error`, and inventing a second
+	* complaint for it would file one fault twice.
+	*/
+	incomplete() {
+		if (this.incompleteSettled) return Promise.resolve(this.incompleteReport);
+		return new Promise((resolve) => this.incompleteWaiters.push(resolve));
+	}
+	/**
 	* What this clip turned out to carry as sound — the answer the viewer needs
 	* to say "this clip has no audio" rather than leave the operator wondering.
 	*
@@ -31865,15 +32855,31 @@ var ClipStreamFeeder = class {
 	*/
 	audio() {
 		const settled = this.audioReport;
-		if (settled !== null) return Promise.resolve(settled);
+		if (settled !== null) return Promise.resolve(this.audioNow(settled));
 		return new Promise((resolve) => this.audioWaiters.push(resolve));
 	}
+	/**
+	* Follow the audio answer for as long as this clip is on the pointer.
+	*
+	* {@link audio} settles ONCE, because what the stream carries is decided
+	* once — at the `moov`. The RATE is not: it moves under the operator's
+	* finger, and a one-shot report cannot say that the clip which had sound a
+	* second ago is silent now because he pressed 2×. The listener is told only
+	* when the answer really changes, never the settle it already awaited.
+	*
+	* One listener, replaced rather than added to: there is one session behind
+	* one clip, and a list would outlive the pointer.
+	*/
+	watchAudio(listener) {
+		this.audioListener = listener;
+	}
 	dispose() {
 		if (this.phase === "disposed") return;
 		const before = this.phase;
 		this.phase = "disposed";
 		this.teardown();
 		this.settleDuration(null);
+		this.settleIncomplete(null);
 		this.settleAudio({
 			carried: false,
 			codec: null,
@@ -31944,13 +32950,15 @@ var ClipStreamFeeder = class {
 				audioReason: answer.audioReason ?? null
 			});
 		}
+		const abandon = new AbortController();
+		this.opening = abandon;
 		let opened;
 		try {
 			opened = await this.deps.open(answer.url, {
 				onData: (chunk) => this.onData(chunk),
-				onEnd: () => this.onEnd(),
+				onEnd: (report) => this.onEnd(report),
 				onError: (err) => this.cut("stream-failed", err.message)
-			});
+			}, abandon.signal);
 		} catch (err) {
 			opened = {
 				kind: "refused",
@@ -31959,8 +32967,15 @@ var ClipStreamFeeder = class {
 				detail: describe(err)
 			};
 		}
+		if (this.opening === abandon) this.opening = null;
 		if (this.phase !== "opening") {
 			if (opened.kind === "open") opened.connection.destroy();
+			this.log("clip-stream:open-abandoned", {
+				phase: this.phase,
+				opened: opened.kind,
+				sinceDialMs: this.now() - (this.dialedAt ?? this.now()),
+				...opened.kind === "refused" ? { code: opened.code } : {}
+			});
 			return;
 		}
 		if (opened.kind === "refused") {
@@ -31980,6 +32995,7 @@ var ClipStreamFeeder = class {
 		this.phase = "refused";
 		this.teardown();
 		this.settleDuration(null);
+		this.settleIncomplete(null);
 		this.settleAudio({
 			carried: false,
 			codec: null,
@@ -32101,10 +33117,24 @@ var ClipStreamFeeder = class {
 			return;
 		}
 		while (this.rate === 0 && this.pendingSteps > 0 && this.pushNext()) this.pendingSteps -= 1;
-		if (this.rate > 0 && this.paceTimer === null) this.tick();
+		if (this.rate === 0) return;
+		if (this.rebuffering) {
+			if (this.cushionShortfallMs() > 0) return;
+			this.rebuffering = false;
+			this.log("clip-stream:refilled", {
+				headMs: this.headMs,
+				arrivedMs: this.arrivedMs,
+				queued: this.queue.length,
+				starved: this.starved
+			});
+			this.startPacing();
+			return;
+		}
+		if (this.paceTimer === null) this.tick();
 	}
-	onEnd() {
+	onEnd(report) {
 		if (!this.takesBytes()) return;
+		this.settleIncomplete(report);
 		this.streamEnded = true;
 		this.clearStall();
 		this.streamEnd = this.demuxer.end();
@@ -32122,13 +33152,20 @@ var ClipStreamFeeder = class {
 			this.resolvePendingSeek(this.seekToken);
 			return;
 		}
-		if (this.rate > 0 && this.paceTimer === null) this.tick();
+		if (this.rate === 0) return;
+		if (this.rebuffering || this.anchorWall > this.now()) {
+			this.rebuffering = false;
+			this.startPacing();
+			return;
+		}
+		if (this.paceTimer === null) this.tick();
 	}
 	cut(reason, detail) {
 		if (this.phase !== "streaming" && this.phase !== "opening") return;
 		this.phase = "cut";
 		this.teardown();
 		this.settleDuration(null);
+		this.settleIncomplete(null);
 		this.settleAudio({
 			carried: false,
 			codec: null,
@@ -32262,9 +33299,24 @@ var ClipStreamFeeder = class {
 		this.audioQueue = this.audioQueue.slice(drop);
 		this.audioDroppedSeek += drop;
 	}
+	/**
+	* How much of the cushion is MISSING, in milliseconds of media.
+	*
+	* Zero once the stream has ended — there is nothing more coming, so waiting
+	* for it would hang the clip — and zero for any source that already holds
+	* more than the cushion, which is every fast one.
+	*/
+	cushionShortfallMs() {
+		if (this.streamEnded) return 0;
+		const head = this.headMs;
+		const arrived = this.arrivedMs;
+		if (head === null || arrived === null) return this.prerollMs;
+		return Math.max(0, this.prerollMs - (arrived - head));
+	}
 	startPacing() {
 		this.stopPacing();
-		this.anchorWall = this.now();
+		const shortfall = this.cushionShortfallMs();
+		this.anchorWall = this.now() + shortfall;
 		this.anchorPts = this.headMs ?? this.queue[0]?.ptsMs ?? 0;
 		this.startPositionReports();
 		this.tick();
@@ -32289,7 +33341,10 @@ var ClipStreamFeeder = class {
 			const audio = this.audioQueue[0];
 			if (video === void 0 && audio === void 0) {
 				if (this.streamEnded) this.finish();
-				else this.noteStarved();
+				else {
+					this.rebuffering = true;
+					this.noteStarved();
+				}
 				return;
 			}
 			const takeVideo = video !== void 0 && (audio === void 0 || video.ptsMs <= audio.ptsMs);
@@ -32325,7 +33380,7 @@ var ClipStreamFeeder = class {
 		if (frame === void 0) return false;
 		this.audioQueue = this.audioQueue.slice(1);
 		this.audioQueuedBytes -= frame.data.byteLength;
-		if (this.rate !== 1) {
+		if (!audioPlaysAtRate(this.rate)) {
 			this.audioDroppedRate += 1;
 			return true;
 		}
@@ -32423,11 +33478,53 @@ var ClipStreamFeeder = class {
 			audioQueued: this.audioQueue.length
 		};
 	}
+	/** One-shot, like the duration beside it: the provider speaks once, at the
+	*  end of the body, and a cut settles `null` so nobody waits for ever. */
+	settleIncomplete(report) {
+		if (this.incompleteSettled) return;
+		this.incompleteSettled = true;
+		this.incompleteReport = report;
+		if (report !== null) this.log("clip-stream:incomplete", {
+			code: report.code,
+			reason: report.reason
+		});
+		for (const resolve of this.incompleteWaiters.splice(0)) resolve(report);
+	}
 	settleAudio(report) {
 		if (this.audioReport !== null) return;
 		this.audioReport = report;
+		const now = this.audioNow(report);
+		this.audioEmitted = now;
 		const waiters = this.audioWaiters.splice(0);
-		for (const resolve of waiters) resolve(report);
+		for (const resolve of waiters) resolve(now);
+	}
+	/**
+	* The audio answer AS IT STANDS — the stream's own settled fact, with the
+	* rate laid over it.
+	*
+	* The overlay only ever applies to a clip that really is carrying sound. A
+	* clip whose camera has no microphone is silent at 1× too, and replacing
+	* `no-audio-track` with `rate` would swap the true cause for a transient
+	* one and send the operator to the speed chip.
+	*/
+	audioNow(settled) {
+		if (!settled.carried || audioPlaysAtRate(this.audioRate)) return settled;
+		return {
+			carried: false,
+			codec: null,
+			reason: "rate",
+			rate: this.audioRate
+		};
+	}
+	/** Tell the listener when — and only when — the answer has actually moved. */
+	refreshAudioReport() {
+		const settled = this.audioReport;
+		if (settled === null) return;
+		const next = this.audioNow(settled);
+		const last = this.audioEmitted;
+		if (last !== null && last.reason === next.reason && last.rate === next.rate) return;
+		this.audioEmitted = next;
+		this.audioListener?.(next);
 	}
 	settleDuration(value) {
 		if (this.duration !== null) return;
@@ -32442,6 +33539,9 @@ var ClipStreamFeeder = class {
 		this.stopPacing();
 		this.stopPositionReports();
 		this.clearStall();
+		const opening = this.opening;
+		this.opening = null;
+		opening?.abort(/* @__PURE__ */ new Error(CLIP_STREAM_ABANDONED));
 		const connection = this.connection;
 		this.connection = null;
 		connection?.destroy();
@@ -32483,6 +33583,62 @@ var ClipStreamFeeder = class {
 function describe(err) {
 	return err instanceof Error ? err.message : String(err);
 }
+//#endregion
+//#region src/stream-broker/recorded/clip-stream-http.ts
+/**
+* clip-stream-http — the `node:http` half of {@link ClipStreamOpener}.
+*
+* Dials the URL `videoclips.dialClipStream` handed back — plain HTTP on the
+* provider's own token-gated listener, never the hub's proxy (an addon holds
+* no user credential, and the hub proxy takes only those) — and turns the
+* response into what the feeder drives: `pause`/`resume`/`destroy` on the
+* socket and the three events.
+*
+* A status other than 200 is a REFUSAL, named by the provider's own headers
+* (`x-camstack-reason-code`, `x-camstack-reason`), never a stream of nothing.
+* A 200 that does not declare `x-camstack-clip-transport: forward-only` is
+* refused too: it means the URL is not the stream route, and playing a
+* progressive file through a forward-only feeder would look like it worked
+* until the first seek.
+*/
+/**
+* The codes a provider may add AFTER its body, and the only two this hop
+* carries onward.
+*
+* A stream's status line is spent on its first fragment, so a serve the camera
+* cut short has nothing left to say it with but a trailer — and a trailer this
+* reader did not know about would be read as a whole clip, which is the defect
+* D623 is about, one hop further out. Anything else a provider writes there is
+* ITS diagnostic and stays in ITS log: a viewer is shown what it can act on.
+*/
+var CARRIED_TRAILER_CODES = ["stream-short", "stream-empty"];
+function trailerText(trailers, name) {
+	const value = trailers[name];
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+/**
+* What the provider said about its own stream once the last byte was out.
+*
+* `null` for a stream that added nothing, which is a whole one — the absence
+* is the statement, and it is never read as "unknown". A code with no sentence
+* is still reported, with the code standing in for one: a consumer that
+* branches on the code must not lose the branch because the prose was dropped
+* by a proxy.
+*/
+function readClipStreamTrailers(trailers) {
+	const code = trailerText(trailers, require_dist.CLIP_STILL_REASON_CODE_HEADER);
+	if (code === void 0 || !CARRIED_TRAILER_CODES.includes(code)) return null;
+	return {
+		code: code === "stream-empty" ? "stream-empty" : "stream-short",
+		reason: trailerText(trailers, "x-camstack-reason") ?? code
+	};
+}
+/** The abort's reason, as a sentence the provider's log can be matched against. */
+function describeReason(reason) {
+	if (reason instanceof Error) return reason.message;
+	if (typeof reason === "string") return reason;
+	return "the clip stream was abandoned before it opened";
+}
 function headerText(res, name) {
 	const value = res.headers[name];
 	if (Array.isArray(value)) return value[0];
@@ -32490,14 +33646,26 @@ function headerText(res, name) {
 }
 function createHttpClipStreamOpener(options = {}) {
 	const headersTimeoutMs = options.headersTimeoutMs ?? 3e4;
-	return (url, handlers) => new Promise((resolve) => {
+	return (url, handlers, signal) => new Promise((resolve) => {
 		let settled = false;
+		let onAbort = null;
 		const settle = (value) => {
 			if (settled) return;
 			settled = true;
 			clearTimeout(timer);
+			if (onAbort !== null) signal.removeEventListener("abort", onAbort);
 			resolve(value);
 		};
+		const abandoned = () => ({
+			kind: "refused",
+			status: 0,
+			code: "abandoned",
+			detail: describeReason(signal.reason)
+		});
+		if (signal.aborted) {
+			resolve(abandoned());
+			return;
+		}
 		let target;
 		try {
 			target = new URL(url);
@@ -32526,7 +33694,16 @@ function createHttpClipStreamOpener(options = {}) {
 		const timer = setTimeout(() => {
 			req.destroy(/* @__PURE__ */ new Error(`no status line in ${headersTimeoutMs} ms`));
 		}, headersTimeoutMs);
+		onAbort = () => {
+			req.destroy(new Error(describeReason(signal.reason)));
+			settle(abandoned());
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
 		req.on("error", (err) => {
+			if (signal.aborted) {
+				settle(abandoned());
+				return;
+			}
 			settle({
 				kind: "refused",
 				status: 0,
@@ -32557,7 +33734,7 @@ function createHttpClipStreamOpener(options = {}) {
 				return;
 			}
 			res.on("data", (chunk) => handlers.onData(chunk));
-			res.on("end", () => handlers.onEnd());
+			res.on("end", () => handlers.onEnd(readClipStreamTrailers(res.trailers)));
 			res.on("error", (err) => handlers.onError(err));
 			settle({
 				kind: "open",
@@ -33147,24 +34324,13 @@ function pickAdaptiveTier(input) {
 *
 * Flow: Camera → RTSP → Broker → EncodedPacket → RTP packetization → WebRTC
 */
-/** How often the adaptive controller re-evaluates the ladder (ms). */
-var ADAPTIVE_TICK_MS = 2e3;
-/** Ladder tuning shared by every adaptive session. */
-var ADAPTIVE_CONFIG = {
-	analyzeWindowMs: 15e3,
-	minFailPercent: .05,
-	waitAfterResetMs: 8e3,
-	upgradeHealthyMs: 4e3,
-	upgradeHealthyGrowthFactor: 3,
-	maxProgressiveUpgradeHealthyMs: 3e4,
-	minTimeBetweenChangesMs: 4e3,
-	maxUpgradeBackoffMs: 9e5,
-	stallKbpsFloor: 64,
-	stallConfirmMs: 6e3,
-	recoverKbpsFloor: 128,
-	waitAfterChangeMs: 8e3,
-	maxClientSampleAgeMs: 1e4
-};
+/**
+* A hold code that has been logged stays quiet this long before it may log
+* again (`HoldLogGate`). 60 000 ms: a hovering link changes code every 4–8 s.
+*/
+var HOLD_LOG_QUIET_MS = 6e4;
+/** A failing adaptive tick logs at most once per this long, per session. */
+var TICK_FAILURE_LOG_QUIET_MS = 6e4;
 /**
 * True when `broker` is an in-process StreamBroker exposing the Opus egress
 * controls. Uses `in` narrowing + `typeof` checks (no cast) so the returned
@@ -33401,6 +34567,14 @@ var BrokerWebrtcServer = class {
 	*/
 	lastLadderDecision = /* @__PURE__ */ new Map();
 	/**
+	* Try-climb memory per DEVICE (review I4): a new viewer session of a camera
+	* whose next rung keeps failing inherits the backoff instead of starting at
+	* try #1. Forgotten after the backoff cap without a refresh.
+	*/
+	deviceTryMemory = new DeviceTryMemory(ADAPTIVE_CONFIG.tryBackoffMaxMs);
+	/** The newest viewer probe per device, from offers and telemetry (`probe-evidence.ts`). */
+	deviceProbe = new DeviceProbeMemory(PROBE_MEMORY_TTL_MS);
+	/**
 	* brokerId → where its media is ingested. Injected by the manager, which
 	* owns the ownership map; unset (or a null answer) means UNRESOLVED, and
 	* the overlay says so rather than naming the local node.
@@ -34398,7 +35572,8 @@ var BrokerWebrtcServer = class {
 		};
 		if (streamId.endsWith("/adaptive")) {
 			const initialTier = this.profileTierResolver?.(brokerId) ?? "high";
-			this.startAdaptive(entry, deviceId, initialTier, sessionId, intent?.failures, intent?.upgradeCount);
+			this.recordDeviceProbe(deviceId, probeFromHints(hints.downlinkMbps, Date.now()));
+			this.startAdaptive(entry, deviceId, initialTier, sessionId, intent);
 		}
 		return {
 			sessionId,
@@ -34516,11 +35691,13 @@ var BrokerWebrtcServer = class {
 		const ladder = controller !== void 0 ? {
 			lastDecision: decision,
 			failures: [...controller.failureCounts],
-			upgradeCount: controller.successfulUpgradeCount
+			upgradeCount: controller.successfulUpgradeCount,
+			climbHold: controller.climbHold === null ? null : toWireClimbHold(controller.climbHold)
 		} : decision !== null ? {
 			lastDecision: decision,
 			failures: [],
-			upgradeCount: 0
+			upgradeCount: 0,
+			climbHold: null
 		} : null;
 		let brokerStats = null;
 		try {
@@ -34563,7 +35740,7 @@ var BrokerWebrtcServer = class {
 	/** Snapshot the ladder's move so the overlay can name it later. */
 	recordLadderDecision(sessionId, decision, tier, forcedTranscodeDown) {
 		this.lastLadderDecision.set(sessionId, {
-			cause: decision.cause,
+			...wireLadderCause(decision, ADAPTIVE_CONFIG.stallConfirmMs),
 			tier,
 			forcedTranscodeDown,
 			lossRatio: decision.lossRatio,
@@ -34574,6 +35751,39 @@ var BrokerWebrtcServer = class {
 		});
 	}
 	/**
+	* The IDR interval the broker feeding a session measured, or null when it
+	* has measured none (a fresh broker reports 0). Sizes the delivery window.
+	*/
+	brokerIdrIntervalMs(brokerId) {
+		try {
+			const idr = this.brokers.get(brokerId)?.getStats().idrIntervalMs ?? null;
+			return idr !== null && idr > 0 ? idr : null;
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* The expected bitrate of `tier` for this device, from the broker serving
+	* that rung — null when no such broker is registered here or it has
+	* measured nothing. Unknown never vetoes a climb (D315/D393).
+	*/
+	expectedTierKbps(deviceId, tier) {
+		const prefix = `${String(deviceId)}/`;
+		const candidates = [];
+		for (const [bid, broker] of this.brokers) if (bid.startsWith(prefix)) candidates.push({
+			brokerId: bid,
+			tier: this.profileTierResolver?.(bid) ?? null,
+			broker
+		});
+		const match = preferLiveAdaptiveCandidates(candidates).find((c) => c.tier === tier);
+		if (match === void 0) return null;
+		try {
+			return expectedRungKbps(match.broker.getStats());
+		} catch {
+			return null;
+		}
+	}
+	/**
 	* Wire an {@link AdaptiveController} to a freshly-created adaptive session.
 	* The controller is fed loss from two sources — RTCP Receiver Reports
 	* (`onReceiverReport`) and, when injected, the device's client-reported
@@ -34590,12 +35800,20 @@ var BrokerWebrtcServer = class {
 	* whichever produces the higher loss ratio across its window. The async
 	* poll is guarded against overlapping ticks via `tickInFlight`.
 	*/
-	startAdaptive(entry, deviceId, initialTier, sessionId, priorFailures, priorUpgradeCount) {
+	startAdaptive(entry, deviceId, initialTier, sessionId, intent) {
+		const startedAt = Date.now();
+		/** Rung bitrates, looked up at most once per tier per tick (review m12). */
+		const rungKbps = /* @__PURE__ */ new Map();
 		const controller = new AdaptiveController({
 			initialTier,
-			priorFailures,
-			priorUpgradeCount,
+			priorFailures: intent?.failures,
+			priorUpgradeCount: intent?.upgradeCount,
+			tryClimb: intent?.tryClimb ?? this.deviceTryMemory.get(deviceId, startedAt) ?? void 0,
 			config: ADAPTIVE_CONFIG,
+			expectedTierKbps: (tier) => {
+				if (!rungKbps.has(tier)) rungKbps.set(tier, this.expectedTierKbps(deviceId, tier));
+				return rungKbps.get(tier) ?? null;
+			},
 			onSwitchTier: (tier, decision) => {
 				this.recordLadderDecision(sessionId, decision, tier, false);
 				this.switchSessionTier(entry, deviceId, tier, sessionId, false, decision);
@@ -34612,6 +35830,9 @@ var BrokerWebrtcServer = class {
 						reason: decision.cause,
 						lossRatio: Number(decision.lossRatio.toFixed(4)),
 						clientKbps: decision.stall.clientKbps,
+						sentKbps: decision.stall.sentKbps,
+						deliveryRatio: decision.stall.deliveryRatio,
+						deliveryWindowMs: decision.stall.deliveryWindowMs,
 						stalledForMs: decision.stall.stalledForMs,
 						serverSending: decision.stall.serverSending
 					}
@@ -34631,14 +35852,39 @@ var BrokerWebrtcServer = class {
 		*  sending?" half of the stall verdict. */
 		let lastRtpSent = entry.session.rtpPacketsSentTotal;
 		const CLIENT_LOSS_SPAN = 1e3;
+		const meter = new DeliveryMeter(ADAPTIVE_DELIVERY_CONFIG, deliveryMeterStart(startedAt, intent !== void 0, ADAPTIVE_CONFIG.waitAfterChangeMs));
+		const holdLog = new HoldLogGate(HOLD_LOG_QUIET_MS);
+		let lastTickFailureLogAt = Number.NEGATIVE_INFINITY;
+		const logHoldChange = (now) => {
+			const hold = controller.climbHold;
+			if (hold === null || !holdLog.shouldLog(hold.code, now)) return;
+			this.logger.info("adaptive: climb held", {
+				tags: { deviceId },
+				meta: {
+					sessionId,
+					deviceId,
+					tier: controller.currentTier,
+					nextTier: hold.nextTier,
+					code: hold.code,
+					summary: describeClimbHold(hold),
+					deliveryRatio: hold.deliveryRatio,
+					deliveryWindowMs: hold.deliveryWindowMs,
+					capacityKbps: hold.capacityKbps,
+					probeKbps: hold.probeKbps,
+					nextTierKbps: hold.nextTierKbps
+				}
+			});
+		};
 		entry.adaptiveTimer = setInterval(() => {
 			if (tickInFlight) return;
 			tickInFlight = true;
 			(async () => {
 				try {
+					rungKbps.clear();
 					if (entry.timeline?.currentMode === "recorded") {
 						controller.suspend(Date.now());
 						lastRtpSent = entry.session.rtpPacketsSentTotal;
+						logHoldChange(Date.now());
 						return;
 					}
 					const client = this.clientNetworkStats ? await this.clientNetworkStats(deviceId) : null;
@@ -34646,11 +35892,15 @@ var BrokerWebrtcServer = class {
 					const rtpSent = entry.session.rtpPacketsSentTotal;
 					const serverSending = rtpSent > lastRtpSent;
 					lastRtpSent = rtpSent;
-					controller.onThroughput({
-						clientKbps: client ? client.estimatedBandwidthKbps : null,
-						clientSampleAgeMs: client ? Math.max(0, now - client.lastUpdated) : null,
-						serverSending
-					}, now);
+					this.feedAdaptive({
+						entry,
+						deviceId,
+						controller,
+						meter,
+						client,
+						serverSending,
+						now
+					});
 					const pct = client?.packetLossPercent ?? null;
 					if (pct !== null && pct !== void 0) {
 						clientHighestSequence += CLIENT_LOSS_SPAN;
@@ -34661,6 +35911,21 @@ var BrokerWebrtcServer = class {
 						}, now);
 					}
 					controller.tick(now);
+					this.deviceTryMemory.set(deviceId, controller.tryClimbCarry, now);
+					logHoldChange(now);
+				} catch (err) {
+					const now = Date.now();
+					if (now - lastTickFailureLogAt >= TICK_FAILURE_LOG_QUIET_MS) {
+						lastTickFailureLogAt = now;
+						this.logger.warn("adaptive: tick failed", {
+							tags: { deviceId },
+							meta: {
+								sessionId,
+								deviceId,
+								error: require_dist.errMsg(err)
+							}
+						});
+					}
 				} finally {
 					tickInFlight = false;
 				}
@@ -34668,6 +35933,55 @@ var BrokerWebrtcServer = class {
 		}, ADAPTIVE_TICK_MS);
 	}
 	/**
+	* One evaluation's transport, capacity and RTT evidence into the controller.
+	* The device-scoped client record is used as this session's own only when
+	* this is the device's ONLY adaptive session here (review I2).
+	*/
+	feedAdaptive(feed) {
+		const { entry, deviceId, controller, meter, client, now } = feed;
+		const sessionsOnDevice = this.adaptiveSessionCount(deviceId);
+		const shared = sessionsOnDevice > 1;
+		let rttMs = null;
+		if (client) {
+			const reportAgeMs = Math.max(0, now - client.lastUpdated);
+			meter.observe(client.estimatedBandwidthKbps, client.lastUpdated);
+			if (!shared) {
+				this.recordDeviceProbe(deviceId, probeFromReport({
+					downlinkMbps: client.downlinkMbps,
+					downlinkAgeMs: client.downlinkAgeMs ?? 0,
+					reportAgeMs
+				}, now));
+				if (reportAgeMs <= ADAPTIVE_DELIVERY_CONFIG.maxClientSampleAgeMs) rttMs = client.rttMs ?? null;
+			}
+		}
+		const history = entry.session.sentVideoHistory;
+		controller.onThroughput(buildStallSample({
+			delivery: meter.evaluate(history, deliveryWindowMs(this.brokerIdrIntervalMs(entry.brokerId), ADAPTIVE_DELIVERY_CONFIG), now),
+			recent: meter.evaluateNewest(history, now),
+			clientReporting: meter.isReporting(now),
+			serverSending: feed.serverSending,
+			adaptiveSessionsOnDevice: sessionsOnDevice
+		}), now);
+		const probe = this.deviceProbe.get(deviceId, now);
+		controller.onCapacity({
+			rembKbps: entry.session.receiverEstimateKbps(now),
+			probeKbps: probe?.kbps ?? null,
+			probeFresh: isProbeFresh(probe, now)
+		});
+		controller.onRtt(rttMs, now);
+	}
+	/** Adaptive sessions of `deviceId` currently on this broker server. */
+	adaptiveSessionCount(deviceId) {
+		const prefix = `${String(deviceId)}/`;
+		let count = 0;
+		for (const s of this.sessions.values()) if (s.adaptiveController !== void 0 && s.brokerId.startsWith(prefix)) count += 1;
+		return count;
+	}
+	/** Keep the newest probe per device; an absent one changes nothing. */
+	recordDeviceProbe(deviceId, probe) {
+		this.deviceProbe.record(deviceId, probe);
+	}
+	/**
 	* Schedule an adaptive tier switch via a close-and-recreate re-offer.
 	*
 	* Records the controller's desired tier (+ forced transcode-down) in
@@ -34684,11 +35998,18 @@ var BrokerWebrtcServer = class {
 		const prev = this.adaptiveIntent.get(sessionId);
 		const failures = new Map(entry.adaptiveController?.failureCounts ?? prev?.failures);
 		const upgradeCount = entry.adaptiveController?.successfulUpgradeCount ?? prev?.upgradeCount ?? 0;
+		const tryClimb = entry.adaptiveController?.tryClimbCarry ?? prev?.tryClimb;
 		this.adaptiveIntent.set(sessionId, {
 			prefersTier: tier,
 			forceTranscodeDown: forceTranscodeDown || (prev?.forceTranscodeDown ?? false),
 			failures,
-			upgradeCount
+			upgradeCount,
+			tryClimb: tryClimb ?? {
+				failures: 0,
+				notBefore: 0,
+				lastRevert: null,
+				trialFrom: null
+			}
 		});
 		const epoch = (entry.session.pendingRenegotiation?.epoch ?? 0) + 1;
 		entry.session.pendingRenegotiation = {
@@ -34706,8 +36027,12 @@ var BrokerWebrtcServer = class {
 				failures: Object.fromEntries(failures),
 				upgradeCount,
 				reason: decision?.cause ?? "unknown",
+				trial: decision?.trial ?? false,
 				lossRatio: decision ? Number(decision.lossRatio.toFixed(4)) : null,
 				clientKbps: decision?.stall.clientKbps ?? null,
+				sentKbps: decision?.stall.sentKbps ?? null,
+				deliveryRatio: decision?.stall.deliveryRatio ?? null,
+				deliveryWindowMs: decision?.stall.deliveryWindowMs ?? null,
 				stalledForMs: decision?.stall.stalledForMs ?? null,
 				serverSending: decision?.stall.serverSending ?? null
 			}
@@ -34724,6 +36049,10 @@ var BrokerWebrtcServer = class {
 		}
 		if (!brokerStillServed && !this.stopped) this.brokerLinger.hold(entry.brokerId);
 		this.adaptiveIntent.delete(sessionId);
+		if (entry.adaptiveController !== void 0) {
+			const deviceId = deviceIdFromBrokerId(entry.brokerId);
+			if (this.adaptiveSessionCount(deviceId) === 0) this.deviceProbe.forget(deviceId);
+		}
 		this.pruneLadderDecisions();
 		if (entry.adaptiveTimer) clearInterval(entry.adaptiveTimer);
 		if (entry.attributionTimer) clearTimeout(entry.attributionTimer);
@@ -35884,7 +37213,10 @@ var StreamBrokerAddon = class extends require_dist.BaseAddon {
 					return {
 						packetLossPercent: client.packetLossPercent,
 						estimatedBandwidthKbps: client.estimatedBandwidthKbps,
-						lastUpdated: client.lastUpdated
+						lastUpdated: client.lastUpdated,
+						rttMs: client.rttMs,
+						...client.downlinkMbps !== void 0 ? { downlinkMbps: client.downlinkMbps } : {},
+						...client.downlinkAgeMs !== void 0 ? { downlinkAgeMs: client.downlinkAgeMs } : {}
 					};
 				} catch {
 					return null;
@@ -35892,8 +37224,8 @@ var StreamBrokerAddon = class extends require_dist.BaseAddon {
 					clearTimeout(timer);
 				}
 			},
-			locateRecordedSegment: (args) => this.ctx.api.recording.locateSegment.query(args),
-			readRecordedSegmentBytes: async (args) => (await this.ctx.api.recording.readSegmentBytes.query(args)).data,
+			locateRecordedSegment: (args) => this.ctx.api.recordingArchive.locateSegment.query(args),
+			readRecordedSegmentBytes: async (args) => (await this.ctx.api.recordingArchive.readSegmentBytes.query(args)).data,
 			readClipBytes: async (args) => {
 				const res = await this.ctx.api.videoclips.readClipBytes.query({
 					deviceId: args.deviceId,
@@ -35926,7 +37258,7 @@ var StreamBrokerAddon = class extends require_dist.BaseAddon {
 			},
 			readRecordedGopBytes: async (args) => {
 				try {
-					return await this.ctx.api.recording.readGopBytes.query({
+					return await this.ctx.api.recordingArchive.readGopBytes.query({
 						deviceId: args.deviceId,
 						profile: args.profile,
 						startMs: args.startMs,
@@ -35941,7 +37273,7 @@ var StreamBrokerAddon = class extends require_dist.BaseAddon {
 						});
 					}
 					return {
-						data: (await this.ctx.api.recording.readSegmentBytes.query({
+						data: (await this.ctx.api.recordingArchive.readSegmentBytes.query({
 							deviceId: args.deviceId,
 							profile: args.profile,
 							startMs: args.startMs