@camstack/addon-pipeline 1.2.243 → 1.2.245

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-Zw3eICiX.js");
-const require_node = require("../node-BAzE1jef.js");
+const require_dist = require("../dist-CWWQf3ci.js");
+const require_node = require("../node-DLZWItaN.js");
 const require_restream_intent = require("../restream-intent-C4adO0P8.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-mwoA6eC7.js");
+const require_segment_demux_js = require("../segment-demux-js-C6B53KjT.js");
 let node_os = require("node:os");
 node_os = require_chunk.__toESM(node_os);
 let node_crypto = require("node:crypto");
@@ -10710,8 +10710,23 @@ var AudioCodecSession = class {
 var EncodedRingBuffer = class {
 	packets = [];
 	maxDurationMs;
-	constructor(maxDurationSec = 10) {
+	maxBytes;
+	bytes = 0;
+	clampedByBytes = false;
+	/**
+	* @param maxDurationSec how much WALL TIME to keep.
+	* @param maxBytes how much MEMORY that is allowed to cost. `0` = unbounded,
+	*   which is what this buffer was before and is why it needed a bound: the
+	*   retention is set in SECONDS, but what a second costs depends entirely on
+	*   which profile got armed. On the operator's fleet the cheap profile runs
+	*   at 34-118 kbps while the main stream runs at up to 11 Mbps — a 25:1
+	*   ratio — so one rule arming a clip on the main stream turns a 60-second
+	*   retention into 82 MB on a single camera, silently, in native memory.
+	*   A time limit cannot express that; only a byte limit can.
+	*/
+	constructor(maxDurationSec = 10, maxBytes = 0) {
 		this.maxDurationMs = maxDurationSec * 1e3;
+		this.maxBytes = Math.max(0, maxBytes);
 	}
 	/** Update the buffer duration (in seconds). Evicts old packets immediately. */
 	setDuration(seconds) {
@@ -10725,8 +10740,23 @@ var EncodedRingBuffer = class {
 	/** Push a new packet into the buffer and evict expired ones. */
 	push(packet) {
 		this.packets.push(packet);
+		this.bytes += packet.data.length;
 		this.evict();
 	}
+	/** What the retained window currently costs, in bytes. */
+	getBufferedBytes() {
+		return this.bytes;
+	}
+	/**
+	* True when the byte budget — not the clock — is what bounds this window.
+	*
+	* Worth asking rather than inferring from a short buffer: a window cut by
+	* bytes holds LESS time than it was configured for, and a consumer that
+	* believes the configured number will look for footage that was never kept.
+	*/
+	isClampedByBytes() {
+		return this.clampedByBytes;
+	}
 	/**
 	* Get buffered packets, starting from the most recent keyframe.
 	* Returns packets in chronological order (oldest first).
@@ -10768,6 +10798,8 @@ var EncodedRingBuffer = class {
 	/** Clear all buffered packets. */
 	clear() {
 		this.packets.length = 0;
+		this.bytes = 0;
+		this.clampedByBytes = false;
 	}
 	/**
 	* Remove packets older than maxDurationMs based on PTS.
@@ -10788,7 +10820,19 @@ var EncodedRingBuffer = class {
 		const cutoff = newest - this.maxDurationMs;
 		let removeCount = 0;
 		while (removeCount < this.packets.length && (this.packets[removeCount].pts < cutoff || this.packets[removeCount].pts > newest)) removeCount++;
-		if (removeCount > 0) this.packets.splice(0, removeCount);
+		if (removeCount > 0) {
+			for (let i = 0; i < removeCount; i++) this.bytes -= this.packets[i].data.length;
+			this.packets.splice(0, removeCount);
+		}
+		if (this.maxBytes > 0 && this.bytes > this.maxBytes) {
+			this.clampedByBytes = true;
+			let dropped = 0;
+			while (dropped < this.packets.length && this.bytes > this.maxBytes) {
+				this.bytes -= this.packets[dropped].data.length;
+				dropped++;
+			}
+			if (dropped > 0) this.packets.splice(0, dropped);
+		} else if (this.maxBytes > 0) this.clampedByBytes = false;
 	}
 };
 //#endregion
@@ -12807,6 +12851,27 @@ var StreamBroker = class StreamBroker {
 	/** Maximum allowed pre-buffer duration in seconds */
 	static MAX_PRE_BUFFER_SEC = 30;
 	/**
+	* Ceiling for the notification clip ring, in seconds.
+	*
+	* Separate from `MAX_PRE_BUFFER_SEC` because the two rings live on different
+	* cost axes: the pre-buffer holds the MAIN stream (the fleet's 22 warm
+	* streams sum 107 Mbps), the clip ring holds the cheapest profile (the same
+	* 22 sum 4.3 Mbps — a 25:1 ratio). A minute of the cheap one costs ~32 MB
+	* across the whole fleet; a minute of the main one would cost ~800 MB.
+	*/
+	static MAX_CLIP_RETENTION_SEC = 120;
+	/**
+	* What ONE camera's clip ring may cost, whatever profile ends up armed.
+	*
+	* The same 16 MiB the RTP pre-roll ring already uses, deliberately — one
+	* number for "how much native memory one stream's history may hold". It
+	* holds a full minute of any realistic cheap stream (up to ~2.2 Mbps) and
+	* clamps a rule that arms the MAIN stream to about twelve seconds instead of
+	* letting it take 82 MB. A window cut by this says so
+	* (`isClampedByBytes`).
+	*/
+	static CLIP_RING_MAX_BYTES = 16 * 1024 * 1024;
+	/**
 	* Retention for the decoder-seed GOP ring. Only ever needs to hold the
 	* current GOP (a fresh keyframe evicts the previous GOP on read), so a few
 	* seconds covers every realistic keyframe interval; cameras with a GOP longer
@@ -14584,15 +14649,31 @@ var StreamBroker = class StreamBroker {
 	}
 	/** Retain `seconds` of AnnexB video for notification clips (0 = stop, frees the ring). */
 	setClipRetention(seconds) {
-		const clamped = Math.max(0, Math.min(seconds, StreamBroker.MAX_PRE_BUFFER_SEC));
+		const clamped = Math.max(0, Math.min(seconds, StreamBroker.MAX_CLIP_RETENTION_SEC));
 		if (clamped === this.clipRetentionSec) return;
+		const previous = this.clipRetentionSec;
 		this.clipRetentionSec = clamped;
+		this.logger?.info(clamped === 0 ? "Clip retention off" : "Clip retention set", { meta: {
+			seconds: clamped,
+			requested: seconds,
+			previousSeconds: previous
+		} });
 		if (clamped === 0) {
 			this.clipBuffer = null;
 			return;
 		}
 		if (this.clipBuffer) this.clipBuffer.setDuration(clamped);
-		else this.clipBuffer = new EncodedRingBuffer(clamped);
+		else this.clipBuffer = new EncodedRingBuffer(clamped, StreamBroker.CLIP_RING_MAX_BYTES);
+	}
+	/**
+	* Seconds this stream's clip ring is currently holding. `0` = no ring.
+	*
+	* A READ of what was applied, for the manager's own bound (how long a cut may
+	* wait for its post-roll) and for the tests that pin the retention a camera's
+	* notification rules ask for.
+	*/
+	getClipRetentionSec() {
+		return this.clipRetentionSec;
 	}
 	/**
 	* The retained clip window, oldest first. Empty when retention is off.
@@ -16225,13 +16306,57 @@ function formatClockHHMM(at) {
 *  reach `streaming` with audio detected, and the stats poll cadence. */
 var PROBE_STREAM_TIMEOUT_MS = 6e3;
 var PROBE_STREAM_POLL_MS = 250;
-var CLIP_RETENTION_SEC = 25;
+/**
+* How much history a notification clip may be cut from on a camera the
+* notification centre has **not spoken about yet**.
+*
+* Retention is no longer flat: every camera holds what its own notification
+* rules ask for ({@link refreshClipRetentionPlan}), which is nothing at all on
+* a camera whose rules never cut footage. This number is what a camera holds
+* while that ask is UNKNOWN — before the first successful pull, and after a
+* pull that failed or answered with a rule set that has not loaded. Absence
+* must not read as zero: dropping a ring on boot, before the rules arrive,
+* loses the footage for exactly the first events after every restart, which is
+* when an operator is most likely to be watching. So an unknown camera keeps
+* what the whole fleet used to keep, and only an ANSWER can take it away.
+*
+* Sixty seconds, raised from 25 on 2026-09-15 after measuring what the
+* alternative sources can actually serve. The recordings' availability edge is
+* not a number but a PHASE: asking for the same 10-second window at different
+* anchors, full coverage arrived at −18 s on one camera and −26 s on two
+* others, depending on where the request falls in the 10-second segment cycle.
+* A notification window is `[anchor−4, anchor+6]`, so at 25 s the ring served
+* an anchor roughly 6–19 s old while the recordings began at 14–26 s — and on
+* an unlucky phase those bands did not meet, which is the silent "no clip" the
+* operator kept receiving. No fixed threshold closes a gap that opens and
+* closes with the segment cycle; margin over the WORST phase does.
+*
+* It is affordable only because this ring runs on the cheap profile: the
+* fleet's 22 cheap streams sum 4.3 Mbps, so a minute costs ~32 MB across every
+* camera — against ~800 MB for the same minute of the main stream. And it is
+* SAFE only because the ring is now bounded by bytes
+* (`StreamBroker.CLIP_RING_MAX_BYTES`): a rule that arms a clip on the main
+* stream is clamped to what 16 MiB holds rather than taking 82 MB.
+*/
+var CLIP_RETENTION_UNKNOWN_SEC = 60;
 /** Cheapest-first — the profile a clip is cut from when the rule says nothing. */
 var CLIP_PROFILE_BY_COST = [
 	"low",
 	"mid",
 	"high"
 ];
+/**
+* Head-room added to an OBSERVED ask (`preRoll + postRoll + this`).
+*
+* The notification centre derives the same shape from its own rules
+* (`NC_CLIP_DISPATCH_MARGIN_SEC`) and for the same reason: a cut is taken
+* seconds after the moment it is about — the row is queued, drained, and its
+* still is waited for — so a ring sized to the window alone drops the pre-roll
+* a heartbeat before the renderer asks for it. Deliberately NOT imported from
+* the notification addon: addons never import each other, and this is the
+* broker's own floor for a consumer that is not the notification centre.
+*/
+var CLIP_OBSERVED_ASK_MARGIN_SEC = 10;
 /** How long `renderPreBufferClip` will wait for the post-roll to accumulate. */
 var CLIP_POST_ROLL_POLL_MS = 250;
 /**
@@ -18105,6 +18230,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 		} else this.disabledDevices.delete(d.id);
 		const live = cameras.filter((d) => !d.disabled);
 		await Promise.allSettled(live.map((d) => this.reconcileDeviceCatalog(d.id, "poll")));
+		await this.refreshClipRetentionPlan();
 		await Promise.allSettled(live.map((d) => this.reconcileDeviceAudioPlane(d.id)));
 		const liveIds = new Set(live.map((d) => d.id));
 		for (const deviceId of [...this.audioPlaneState.keys()]) if (!liveIds.has(deviceId)) this.audioPlaneState.delete(deviceId);
@@ -18643,8 +18769,8 @@ var StreamBrokerManager = class StreamBrokerManager {
 		const assigned = CLIP_PROFILE_BY_COST.filter((p) => map[p] !== void 0);
 		const wanted = pickClipProfile(assigned, input.profile);
 		if (!wanted) throw new Error(`No profile assigned for device ${input.deviceId}`);
-		this.armClipRetention(input.deviceId, wanted);
-		const until = Math.min(input.aroundMs + input.postRollSec * 1e3, Date.now() + CLIP_RETENTION_SEC * 1e3);
+		this.noteClipAsk(input.deviceId, wanted, input.preRollSec + input.postRollSec + CLIP_OBSERVED_ASK_MARGIN_SEC);
+		const until = Math.min(input.aroundMs + input.postRollSec * 1e3, Date.now() + this.clipRetentionSecFor(input.deviceId) * 1e3);
 		while (Date.now() < until) await new Promise((resolve) => setTimeout(resolve, CLIP_POST_ROLL_POLL_MS));
 		const candidates = [wanted, ...assigned.filter((p) => p !== wanted)];
 		let profile = null;
@@ -20366,8 +20492,18 @@ var StreamBrokerManager = class StreamBrokerManager {
 		this.applyClipRetention(deviceId);
 	}
 	/**
-	* Keep a clip window retained on the ONE profile clips are cut from — the
-	* cheapest assigned, which is what `pickClipProfile` defaults to.
+	* Apply the retention THIS camera's notification rules actually ask for.
+	*
+	* Three inputs, one number:
+	*
+	*  1. the PLAN — `notificationRules.getClipRetentionAsks`, the rules' own
+	*     demand per camera ({@link refreshClipRetentionPlan});
+	*  2. what a cut has been OBSERVED asking for on this camera
+	*     ({@link noteClipAsk}) — the old reactive arming, folded into the same
+	*     ask so there is one mechanism rather than two;
+	*  3. nothing at all, when the plan has never arrived — see
+	*     {@link CLIP_RETENTION_UNKNOWN_SEC}. An unknown camera is not a camera
+	*     that needs nothing.
 	*
 	* Retention is opportunistic: it never dials a camera, it only fills while
 	* something else already holds the stream up (usually the detection pipeline
@@ -20376,32 +20512,159 @@ var StreamBrokerManager = class StreamBrokerManager {
 	*/
 	applyClipRetention(deviceId) {
 		const map = this.assignments.get(deviceId)?.map ?? {};
-		const clipProfile = CLIP_PROFILE_BY_COST.find((p) => map[p] !== void 0);
-		const armed = this.clipRetentionArmed.get(deviceId);
+		const resolved = this.resolveClipRetention(deviceId, map);
 		for (const profile of require_dist.CAM_PROFILE_ORDER) {
 			const camStreamId = map[profile];
 			if (!camStreamId) continue;
-			const wanted = profile === clipProfile || armed?.has(profile) === true;
-			this.brokers.get(brokerIdFor(deviceId, camStreamId))?.setClipRetention(wanted ? CLIP_RETENTION_SEC : 0);
+			const wanted = resolved.profiles.has(profile) ? resolved.seconds : 0;
+			this.brokers.get(brokerIdFor(deviceId, camStreamId))?.setClipRetention(wanted);
+		}
+		this.reportClipRetention(deviceId, resolved);
+	}
+	/**
+	* The seconds and the profiles this camera's ring should hold, and WHY.
+	*
+	* The MAX over every ask that reaches the camera — the asks describe the
+	* rules, the bounding belongs here (and, below this, to the ring's own byte
+	* budget, which is never raised for an ask).
+	*/
+	resolveClipRetention(deviceId, map) {
+		const cheapest = CLIP_PROFILE_BY_COST.find((p) => map[p] !== void 0);
+		const observed = this.clipRetentionObserved.get(deviceId);
+		const profiles = /* @__PURE__ */ new Set();
+		let seconds = 0;
+		let source;
+		if (this.clipRetentionAsks === null) {
+			seconds = CLIP_RETENTION_UNKNOWN_SEC;
+			source = "unknown";
+		} else {
+			source = "rules";
+			for (const ask of this.clipRetentionAsks) {
+				if (ask.deviceId !== void 0 && ask.deviceId !== deviceId) continue;
+				if (ask.seconds > seconds) seconds = ask.seconds;
+				if (ask.profile !== void 0) profiles.add(ask.profile);
+			}
+		}
+		if (observed !== void 0) for (const [profile, asked] of observed) {
+			if (asked > seconds) {
+				seconds = asked;
+				source = source === "unknown" ? "unknown" : "observed";
+			}
+			profiles.add(profile);
 		}
+		if (seconds <= 0) return {
+			seconds: 0,
+			profiles: /* @__PURE__ */ new Set(),
+			source
+		};
+		if (cheapest !== void 0) profiles.add(cheapest);
+		return {
+			seconds,
+			profiles,
+			source
+		};
+	}
+	/**
+	* Say it, once per transition, per camera.
+	*
+	* This mechanism MOVES — a rule created, disabled or deleted changes what a
+	* camera holds within one reconcile tick — and a retention that changes
+	* silently is a retention nobody can correlate with a missing clip. The
+	* broker's own `setClipRetention` logs the buffer it allocated; this line
+	* says who asked for it.
+	*/
+	reportClipRetention(deviceId, resolved) {
+		const signature = `${resolved.seconds}:${resolved.source}:${[...resolved.profiles].sort().join(",")}`;
+		const previous = this.clipRetentionApplied.get(deviceId);
+		if (previous === signature) return;
+		this.clipRetentionApplied.set(deviceId, signature);
+		this.logger.info(resolved.seconds === 0 ? "clip retention: none — no notification rule on this camera cuts footage" : "clip retention set from the notification rules", {
+			tags: { deviceId },
+			meta: {
+				seconds: resolved.seconds,
+				profiles: [...resolved.profiles],
+				source: resolved.source,
+				previous: previous ?? "none"
+			}
+		});
+	}
+	/** Seconds this camera's ring is currently asked to hold (0 when none). */
+	clipRetentionSecFor(deviceId) {
+		return this.resolveClipRetention(deviceId, this.assignments.get(deviceId)?.map ?? {}).seconds;
 	}
 	/**
-	* Profiles a rule has actually asked a clip from, beyond the cheapest one
-	* retained by default.
+	* PULL the notification centre's per-camera asks and apply them.
+	*
+	* A pull, not a push: a camera's ring lives on the node that ingests it while
+	* `notification-rules` is a singleton, so a push would have to enumerate the
+	* cluster. It also makes the failure mode right — a pull that fails, or one
+	* answered by a centre whose rules have not loaded, changes NOTHING (D49: a
+	* read that fails must never be able to destroy work, and dropping a ring is
+	* destroying work). Only an answer about a rule set that was actually read
+	* can take retention away.
 	*
-	* This must be REMEMBERED, not just applied: catalog reconcile re-runs
-	* `applyClipRetention` on a timer, and without this the arming was wiped
-	* within the minute — a rule asking for `high` fell back to `low` forever
-	* and looked like the choice did nothing.
+	* Rides the catalog reconcile, which is also the D8 backstop that re-derives
+	* after a rule is created, edited, enabled, disabled or deleted — bounded
+	* staleness (one tick), never a mirror that only follows the rules at boot.
 	*/
+	async refreshClipRetentionPlan() {
+		const api = this.api;
+		if (!api) return;
+		let plan;
+		try {
+			plan = await api.notificationRules.getClipRetentionAsks.query({});
+		} catch (err) {
+			this.logger.debug("clip retention plan unavailable — keeping the one in force", { meta: {
+				error: require_dist.errMsg(err),
+				known: this.clipRetentionAsks !== null
+			} });
+			return;
+		}
+		if (!plan.rulesLoaded) {
+			this.logger.debug("clip retention plan: the notification centre has not read its rules yet", { meta: { known: this.clipRetentionAsks !== null } });
+			return;
+		}
+		this.clipRetentionAsks = plan.asks;
+		for (const deviceId of this.assignments.keys()) this.applyClipRetention(deviceId);
+	}
 	/** Produced event artifacts waiting to be fetched by handle (D9/D18). */
 	eventMedia = new EventMediaStore();
-	clipRetentionArmed = /* @__PURE__ */ new Map();
-	armClipRetention(deviceId, profile) {
-		const armed = this.clipRetentionArmed.get(deviceId) ?? /* @__PURE__ */ new Set();
-		if (armed.has(profile)) return;
-		armed.add(profile);
-		this.clipRetentionArmed.set(deviceId, armed);
+	/**
+	* The notification rules' own asks, per camera. `null` = never answered.
+	*
+	* `null` and `[]` are DIFFERENT and the difference is a camera's footage:
+	* `[]` means the centre read its rules and none of them cut footage here,
+	* `null` means nobody has said. Only the first one is allowed to zero a ring.
+	*/
+	clipRetentionAsks = null;
+	/**
+	* What a cut was OBSERVED asking for, per camera and profile.
+	*
+	* The old `armClipRetention`, folded into the ask above so retention has ONE
+	* input shape. It still exists because the plan describes the notification
+	* rules and a cut can come from elsewhere (a clips API, an export, a rule
+	* created a second ago on another node): a consumer that asked for a window
+	* this ring did not hold gets it next time. It is REMEMBERED because the
+	* reconcile re-applies retention on a timer, and without that the arming was
+	* wiped within the minute — a rule asking for `high` fell back to `low`
+	* forever and looked like the choice did nothing.
+	*/
+	clipRetentionObserved = /* @__PURE__ */ new Map();
+	/** Last reported (seconds, source, profiles) per camera — transitions only. */
+	clipRetentionApplied = /* @__PURE__ */ new Map();
+	/**
+	* A cut asked this camera for `seconds` on `profile` — remember it.
+	*
+	* ONE ask, with both halves: the reactive arming used to carry the profile
+	* and inherit the flat duration, so a consumer that needed a longer window
+	* had no way to say so and a consumer that needed none still paid.
+	*/
+	noteClipAsk(deviceId, profile, seconds) {
+		const observed = this.clipRetentionObserved.get(deviceId) ?? /* @__PURE__ */ new Map();
+		const bounded = Math.max(0, Math.min(seconds, CLIP_RETENTION_UNKNOWN_SEC));
+		if ((observed.get(profile) ?? 0) >= bounded && this.clipRetentionObserved.has(deviceId)) return;
+		observed.set(profile, Math.max(observed.get(profile) ?? 0, bounded));
+		this.clipRetentionObserved.set(deviceId, observed);
 		this.applyClipRetention(deviceId);
 	}
 	countPushConsumers(map, deviceId) {
@@ -20701,6 +20964,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 			return;
 		}
 		this.brokers.set(brokerId, broker);
+		this.applyClipRetention(deviceId);
 		const existingToken = this.persistedTokens.get(brokerId);
 		const warmUp = () => broker.onEncodedData(() => {});
 		this.rtspServer.registerRestreamer(brokerId, broker.getRtspRestreamer(), warmUp, existingToken);
@@ -24277,6 +24541,18 @@ var AdaptiveSession = class AdaptiveSession {
 	}
 	static MAX_RTP_PAYLOAD = 1100;
 	rtpPacketsSent = 0;
+	/**
+	* Cumulative RTP packets this session has put on the wire.
+	*
+	* Read by the adaptive ladder's stall detector: "the client received
+	* nothing" only means the link is broken if the broker was SENDING at the
+	* time. Without this half, a paused camera, a battery source between wakes
+	* or any legitimately idle feed reads as a stall and walks the ladder to
+	* the floor for nothing.
+	*/
+	get rtpPacketsSentTotal() {
+		return this.rtpPacketsSent;
+	}
 	rtpLogCounter = 0;
 	/** One-shot guards for the "first video/audio RTP" debug markers. */
 	firstVideoRtpLogged = false;
@@ -25064,6 +25340,105 @@ var LossTracker = class {
 	}
 };
 //#endregion
+//#region src/stream-broker/webrtc/stall-tracker.ts
+/**
+* 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.
+*/
+var StallTracker = class {
+	config;
+	/** When the current uninterrupted stall began; null when not stalling. */
+	stallStartedAt = null;
+	blackoutUntil = 0;
+	lastEvidence = {
+		clientKbps: null,
+		stalledForMs: 0,
+		serverSending: false
+	};
+	constructor(config) {
+		this.config = config;
+	}
+	/** A tier change just happened — ignore the re-offer's own dead air. */
+	markChanged(now) {
+		this.stallStartedAt = null;
+		this.blackoutUntil = now + this.config.waitAfterChangeMs;
+	}
+	/**
+	* 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.
+	*/
+	observe(sample, now) {
+		if (now < this.blackoutUntil) {
+			this.stallStartedAt = null;
+			this.lastEvidence = {
+				clientKbps: sample.clientKbps,
+				stalledForMs: 0,
+				serverSending: sample.serverSending
+			};
+			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
+		};
+	}
+	stalledForMs(now) {
+		return this.stallStartedAt === null ? 0 : now - this.stallStartedAt;
+	}
+	/** True once the stall has persisted for `stallConfirmMs`. */
+	isStalled(now) {
+		if (now < this.blackoutUntil) return false;
+		return this.stalledForMs(now) >= this.config.stallConfirmMs;
+	}
+	/**
+	* May the ladder PROMOTE on this evaluation?
+	*
+	* 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.
+	*
+	* Unknown does not block. 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;
+	}
+	/** What the last `observe` measured — for the switch's log line. */
+	evidence(now) {
+		return {
+			...this.lastEvidence,
+			stalledForMs: this.stalledForMs(now)
+		};
+	}
+};
+//#endregion
 //#region src/stream-broker/webrtc/adaptive-controller.ts
 var TIER_ORDER = require_dist.CAM_PROFILE_ORDER;
 /**
@@ -25085,6 +25460,7 @@ var TIER_ORDER = require_dist.CAM_PROFILE_ORDER;
 var AdaptiveController = class {
 	opts;
 	tracker;
+	stalls;
 	tier;
 	mtuReduced = false;
 	transcodeEngaged = false;
@@ -25103,6 +25479,7 @@ var AdaptiveController = class {
 	constructor(opts) {
 		this.opts = opts;
 		this.tracker = new LossTracker(opts.config);
+		this.stalls = new StallTracker(opts.config);
 		this.tier = opts.initialTier;
 		this.failures = new Map(opts.priorFailures ?? []);
 		this.upgradeCount = Math.max(0, opts.priorUpgradeCount ?? 0);
@@ -25125,6 +25502,19 @@ var AdaptiveController = class {
 		this.tracker.track(sample, now);
 	}
 	/**
+	* Fold one TRANSPORT measurement into the ladder — what the client actually
+	* received, and whether the broker was sending at the time.
+	*
+	* This is the half the ladder was missing. Packet loss cannot see a freeze
+	* (a stream delivering nothing reports 0 % loss, because there are no gaps
+	* in a sequence that received no packets), and the client's downlink hint
+	* cannot see one either — it is a one-shot HTTP burst measured at connect
+	* time, on a path the media does not take. See `stall-tracker.ts`.
+	*/
+	onThroughput(sample, now) {
+		this.stalls.observe(sample, now);
+	}
+	/**
 	* Freeze the ladder for this evaluation instead of ticking it.
 	*
 	* Called while the session's track is NOT carrying the live source — D42
@@ -25145,6 +25535,7 @@ var AdaptiveController = class {
 			this.lastChangeAt = now;
 		}
 		this.healthySince = now;
+		this.stalls.markChanged(now);
 	}
 	tick(now) {
 		if (!this.armed) {
@@ -25152,9 +25543,18 @@ var AdaptiveController = class {
 			this.healthySince = now;
 			this.lastChangeAt = now;
 		}
+		if (this.stalls.isStalled(now)) {
+			this.healthySince = now;
+			this.handleFailing(now, "stall");
+			return;
+		}
 		if (this.tracker.isFailing(now)) {
 			this.healthySince = now;
-			this.handleFailing(now);
+			this.handleFailing(now, "loss");
+			return;
+		}
+		if (!this.stalls.isClimbSafe(now)) {
+			this.healthySince = now;
 			return;
 		}
 		if (!this.tracker.hasEvidence(now)) {
@@ -25180,26 +25580,36 @@ var AdaptiveController = class {
 	commitChange(now) {
 		this.lastChangeAt = now;
 		this.tracker.markChanged(now);
+		this.stalls.markChanged(now);
+	}
+	/** The measurement this decision rests on, snapshotted for the log line. */
+	decisionAt(now, cause) {
+		return {
+			cause,
+			lossRatio: this.tracker.lossRatio(),
+			stall: this.stalls.evidence(now)
+		};
 	}
-	handleFailing(now) {
+	handleFailing(now, cause) {
+		const decision = this.decisionAt(now, cause);
 		const idx = TIER_ORDER.indexOf(this.tier);
 		if (idx < TIER_ORDER.length - 1) {
 			const failed = this.tier;
 			this.failures.set(failed, (this.failures.get(failed) ?? 0) + 1);
 			this.tier = TIER_ORDER[idx + 1];
-			this.opts.onSwitchTier(this.tier);
+			this.opts.onSwitchTier(this.tier, decision);
 			this.commitChange(now);
 			return;
 		}
 		if (!this.mtuReduced) {
 			this.mtuReduced = true;
-			this.opts.onReduceMtu();
+			this.opts.onReduceMtu(decision);
 			this.commitChange(now);
 			return;
 		}
 		if (!this.transcodeEngaged) {
 			this.transcodeEngaged = true;
-			this.opts.onTranscodeDown();
+			this.opts.onTranscodeDown(decision);
 			this.commitChange(now);
 		}
 	}
@@ -25213,7 +25623,7 @@ var AdaptiveController = class {
 		this.mtuReduced = false;
 		this.transcodeEngaged = false;
 		this.upgradeCount += 1;
-		this.opts.onSwitchTier(next);
+		this.opts.onSwitchTier(next, this.decisionAt(now, "healthy"));
 		this.commitChange(now);
 		this.healthySince = now;
 	}
@@ -29354,7 +29764,12 @@ var ADAPTIVE_CONFIG = {
 	upgradeHealthyGrowthFactor: 3,
 	maxProgressiveUpgradeHealthyMs: 3e4,
 	minTimeBetweenChangesMs: 4e3,
-	maxUpgradeBackoffMs: 9e5
+	maxUpgradeBackoffMs: 9e5,
+	stallKbpsFloor: 64,
+	stallConfirmMs: 6e3,
+	recoverKbpsFloor: 128,
+	waitAfterChangeMs: 8e3,
+	maxClientSampleAgeMs: 1e4
 };
 /**
 * True when `broker` is an in-process StreamBroker exposing the Opus egress
@@ -29498,7 +29913,7 @@ var BrokerWebrtcServer = class {
 	staticIceServers;
 	icePortRange;
 	iceAdditionalHostAddresses;
-	clientLossPct;
+	clientNetworkStats;
 	locateRecordedSegment;
 	readRecordedSegmentBytes;
 	readRecordedGopBytes;
@@ -29565,7 +29980,7 @@ var BrokerWebrtcServer = class {
 		this.staticIceServers = options.iceServers;
 		this.icePortRange = options.icePortRange;
 		this.iceAdditionalHostAddresses = options.iceAdditionalHostAddresses;
-		this.clientLossPct = options.clientLossPct;
+		this.clientNetworkStats = options.clientNetworkStats;
 		this.locateRecordedSegment = options.locateRecordedSegment;
 		this.readRecordedSegmentBytes = options.readRecordedSegmentBytes;
 		this.readRecordedGopBytes = options.readRecordedGopBytes;
@@ -30503,12 +30918,27 @@ var BrokerWebrtcServer = class {
 			priorFailures,
 			priorUpgradeCount,
 			config: ADAPTIVE_CONFIG,
-			onSwitchTier: (tier) => {
-				this.switchSessionTier(entry, deviceId, tier, sessionId);
+			onSwitchTier: (tier, decision) => {
+				this.switchSessionTier(entry, deviceId, tier, sessionId, false, decision);
 			},
-			onReduceMtu: () => entry.session.setRepacketizerMtu(AdaptiveSession.ADAPTIVE_LOW_MTU),
-			onTranscodeDown: () => {
-				this.switchSessionTier(entry, deviceId, "low", sessionId, true);
+			onReduceMtu: (decision) => {
+				entry.session.setRepacketizerMtu(AdaptiveSession.ADAPTIVE_LOW_MTU);
+				this.logger.info("adaptive: reducing repacketizer MTU", {
+					tags: { deviceId },
+					meta: {
+						sessionId,
+						deviceId,
+						mtu: AdaptiveSession.ADAPTIVE_LOW_MTU,
+						reason: decision.cause,
+						lossRatio: Number(decision.lossRatio.toFixed(4)),
+						clientKbps: decision.stall.clientKbps,
+						stalledForMs: decision.stall.stalledForMs,
+						serverSending: decision.stall.serverSending
+					}
+				});
+			},
+			onTranscodeDown: (decision) => {
+				this.switchSessionTier(entry, deviceId, "low", sessionId, true, decision);
 			}
 		});
 		entry.session.onReceiverReport((s) => controller.onLoss(s, Date.now()));
@@ -30516,6 +30946,9 @@ var BrokerWebrtcServer = class {
 		let clientHighestSequence = 0;
 		let clientPacketsLost = 0;
 		let tickInFlight = false;
+		/** RTP packets sent as of the previous evaluation — the "was the broker
+		*  sending?" half of the stall verdict. */
+		let lastRtpSent = entry.session.rtpPacketsSentTotal;
 		const CLIENT_LOSS_SPAN = 1e3;
 		entry.adaptiveTimer = setInterval(() => {
 			if (tickInFlight) return;
@@ -30524,10 +30957,20 @@ var BrokerWebrtcServer = class {
 				try {
 					if (entry.timeline?.currentMode === "recorded") {
 						controller.suspend(Date.now());
+						lastRtpSent = entry.session.rtpPacketsSentTotal;
 						return;
 					}
-					const pct = this.clientLossPct ? await this.clientLossPct(deviceId) : null;
+					const client = this.clientNetworkStats ? await this.clientNetworkStats(deviceId) : null;
 					const now = Date.now();
+					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);
+					const pct = client?.packetLossPercent ?? null;
 					if (pct !== null && pct !== void 0) {
 						clientHighestSequence += CLIENT_LOSS_SPAN;
 						clientPacketsLost += Math.round(Math.max(0, Math.min(100, pct)) / 100 * CLIENT_LOSS_SPAN);
@@ -30556,7 +30999,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) {
+	switchSessionTier(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;
@@ -30580,7 +31023,12 @@ var BrokerWebrtcServer = class {
 				forceTranscodeDown,
 				epoch,
 				failures: Object.fromEntries(failures),
-				upgradeCount
+				upgradeCount,
+				reason: decision?.cause ?? "unknown",
+				lossRatio: decision ? Number(decision.lossRatio.toFixed(4)) : null,
+				clientKbps: decision?.stall.clientKbps ?? null,
+				stalledForMs: decision?.stall.stalledForMs ?? null,
+				serverSending: decision?.stall.serverSending ?? null
 			}
 		});
 	}
@@ -31652,11 +32100,17 @@ var StreamBrokerAddon = class extends require_dist.BaseAddon {
 					return [];
 				}
 			},
-			clientLossPct: async (deviceId) => {
+			clientNetworkStats: async (deviceId) => {
 				const ctrl = new AbortController();
 				const timer = setTimeout(() => ctrl.abort(), NETWORK_QUALITY_STATS_TIMEOUT_MS);
 				try {
-					return (await this.ctx.api.networkQuality.getDeviceStats.query({ deviceId }, { signal: ctrl.signal }))?.client?.packetLossPercent ?? null;
+					const client = (await this.ctx.api.networkQuality.getDeviceStats.query({ deviceId }, { signal: ctrl.signal }))?.client;
+					if (!client) return null;
+					return {
+						packetLossPercent: client.packetLossPercent,
+						estimatedBandwidthKbps: client.estimatedBandwidthKbps,
+						lastUpdated: client.lastUpdated
+					};
 				} catch {
 					return null;
 				} finally {