@camstack/addon-pipeline 1.2.197 → 1.2.198

package/dist/stream-broker/index.mjs

@@ -1,10 +1,10 @@
 import { r as __toESM } from "../chunk-DnnnRqeS.mjs";
-import { $t as literal, A as addonWidgetsSourceCapability, At as buildFfmpegArgs$1, Bt as isEvent, C as RATE_CONTROL_RELAXED, Dt as errMsg, Et as webrtcSessionCapability, F as cameraStreamsCapability, Ft as CAM_PROFILE_ORDER, Gt as parseProfileBrokerId, H as deriveBatteryPresence, Ht as makeSourceBrokerId, I as createHwAccelCache, It as DeviceFeature, Jt as _enum, K as egressTranscodeSharingKey, L as createLogChannelsProvider, Lt as DeviceType, Mt as isSoftwareDecode, Nt as BOOT_RECOVERY_BACKOFF_MS, O as RingBuffer, Ot as AUDIO_PRESETS, P as batteryCapability, Pt as BaseAddon, Rt as createEvent, Ut as nodePin, Vt as makeProfileBrokerId, Xt as boolean, Yt as array, Zt as discriminatedUnion, an as union, en as number, h as EncodeProfileSchema, i as BatteryStatusSchema, in as string, it as maskUrlCredentials, jt as invocationFromEncodeProfile, nt as logChannelsCapability, on as EventCategory, q as egressTransportFromRequest, rn as record, tn as object, tt as loadContributionCapability, w as RATE_CONTROL_TIGHT, wt as streamBrokerCapability, yt as resolveEgressDecodeHwAccel, z as declareLogChannel } from "../dist-Y4BsF_EC.mjs";
-import { i as NO_COST_CLAIM, n as Fmp4FragmentChild, r as Fmp4FragmentPlane, t as ChildCostRegistry } from "../node-B5ouEQYN.mjs";
+import { A as addonWidgetsSourceCapability, C as RATE_CONTROL_RELAXED, Dt as webrtcSessionCapability, F as cameraStreamsCapability, Ft as BaseAddon, H as deriveBatteryPresence, Ht as makeProfileBrokerId, I as createHwAccelCache, It as CAM_PROFILE_ORDER, K as egressTranscodeSharingKey, Kt as parseProfileBrokerId, L as createLogChannelsProvider, Lt as DeviceFeature, Mt as invocationFromEncodeProfile, Nt as isSoftwareDecode, O as RingBuffer, Ot as errMsg, P as batteryCapability, Pt as BOOT_RECOVERY_BACKOFF_MS, Qt as discriminatedUnion, Rt as DeviceType, Ut as makeSourceBrokerId, Vt as isEvent, Wt as nodePin, Xt as array, Yt as _enum, Zt as boolean, an as string, en as literal, h as EncodeProfileSchema, i as BatteryStatusSchema, in as record, it as maskUrlCredentials, jt as buildFfmpegArgs$1, kt as AUDIO_PRESETS, nn as object, nt as logChannelsCapability, on as union, q as egressTransportFromRequest, sn as EventCategory, tn as number, tt as loadContributionCapability, w as RATE_CONTROL_TIGHT, wt as streamBrokerCapability, yt as resolveEgressDecodeHwAccel, z as declareLogChannel, zt as createEvent } from "../dist-oFIHnD88.mjs";
+import { i as NO_COST_CLAIM, n as Fmp4FragmentChild, r as Fmp4FragmentPlane, t as ChildCostRegistry } from "../node-B4zETsJ9.mjs";
 import { t as parseRestreamPath } from "../restream-intent-B4BXZra7.mjs";
 import { n as profileForStreamId } from "../remote-restream-BeHi78PZ.mjs";
-import { n as RowMapStore, t as retireRootKeys } from "../retire-root-keys-DZvlso2l.mjs";
-import { i as require_mp4box_all, n as demuxSegmentPreferJs, r as runFfmpegOnce, t as demuxSegmentFullJs } from "../segment-demux-js-DXPgq2cf.mjs";
+import { a as retireRootKeys, i as resolvePrebuffer, n as capPreRollRequestMs, o as RowMapStore, r as prebufferRetentionMs, t as PREBUFFER_MAX_MS } from "../prebuffer-DmBYRQWg.mjs";
+import { i as require_mp4box_all, n as demuxSegmentPreferJs, r as runFfmpegOnce, t as demuxSegmentFullJs } from "../segment-demux-js-DZysrgdC.mjs";
 import { createRequire } from "node:module";
 import * as os from "node:os";
 import { networkInterfaces, tmpdir } from "node:os";
@@ -1782,247 +1782,66 @@ function rankInitialAssignment(streams) {
 		...byRank
 	};
 }
+//#endregion
+//#region src/stream-broker/prebuffer-migration.ts
 /**
-* Ceiling for a configured pre-roll.
+* MIGRATION of the retired per-stream pre-roll override onto the one prebuffer.
 *
-* Three costs grow with this number and none of them is the operator's to
-* discover: retained RTP bytes on the ingest node, the media backlog a decoder
-* must drain before it reaches the live edge, and the span a detection burst is
-* allowed to carry past the D57 bound. 6 s covers a 4-5 s IDR interval plus a
-* full GOP of head-room and matches the decoder-seed ring's own retention, so
-* both planes can honour the same maximum.
-*/
-var PRE_ROLL_MAX_MS = 6e3;
-var NOTHING = {
-	startIndex: -1,
-	ageMs: 0,
-	gopsBack: 0
-};
-/**
-* A configured pre-roll in ms, or `0` when the input carries no instruction.
+* `DeviceOverride.preRollMs` was the per-camera-stream DETECTION pre-roll: how
+* much history a decode dial could be handed. D381 retires it — there is one
+* retention now and it is the prebuffer's — but a key that is merely removed
+* from a non-strict `z.object` is **stripped in silence** on the next save,
+* which is the failure D380 came within one commit of shipping.
 *
-* `maxMs` is the ceiling of the WINDOW being resolved: detection's
-* ({@link PRE_ROLL_MAX_MS}) bounds a decoder's drain, recording's
-* ({@link RECORDING_PRE_ROLL_MAX_MS}) bounds the recorder's keep gate. One
-* clamp for both so a new window cannot arrive with its own rounding rules.
+* So the key is retired EXPLICITLY: read once, converted into the
+* configuration that now carries its meaning, and cleared. An operator who had
+* typed "3 s of history on 617's substream" keeps 3 s of history on 617's
+* substream; they do not silently get the cluster default, and they do not
+* silently get nothing.
 */
-function clampPreRoll(value, maxMs) {
-	if (value === void 0) return 0;
-	if (!Number.isFinite(value) || value <= 0) return 0;
-	return Math.min(maxMs, Math.max(250, value));
-}
 /**
-* {@link clampPreRoll} at the WIDEST ceiling any window in this system may
-* carry.
+* Fold a retired `preRollMs` map into the prebuffer overrides.
 *
-* Used by the three functions that operate on a window ALREADY resolved by
-* `resolvePreRollMs` / `resolveRecordingPreRollMs` — the selection, the packet
-* ceiling and the span bound. Clamping those at the DETECTION ceiling was
-* correct while there was one window and became a silent 6 s truncation of
-* every recording burst the moment there were two: the selector would refuse
-* the keyframe the recorder asked for, and the span bound would withhold the
-* burst for being as wide as the operator configured — D192's failure, one
-* layer down.
-*/
-function usablePreRoll(value) {
-	return clampPreRoll(value, RECORDING_PRE_ROLL_MAX_MS);
-}
-/**
-* Choose the keyframe access unit a pre-roll burst starts at.
-*
-* The OLDEST mark that is still inside the window wins; when none is (the
-* current GOP is itself older than `preRollMs`, i.e. a long-GOP camera with a
-* short pre-roll) the newest mark is returned, because the alternative to the
-* current GOP is nothing at all — the blind start Stage 0 exists to prevent.
+* An EXPLICIT prebuffer override wins and the retired value is dropped: the
+* operator answered the same question later and more directly, and a migration
+* that overwrote it would be this subsystem's original sin one more time — two
+* writers for one number.
 *
-* The boundary is INCLUSIVE: a keyframe exactly `preRollMs` old is inside.
-* Everything delivered after a keyframe is younger than it, so starting at a
-* mark inside the window is what makes "no frame older than `preRollMs` is
-* delivered" a property of the slice rather than a per-packet filter.
-*
-* Scans instead of assuming order: a caller that appends marks and rebases
-* indices after a trim is one refactor away from handing this an unsorted
-* array, and the failure would be a silently wider window.
+* Rounds UP to whole seconds. The prebuffer is configured in seconds and the
+* retired knob in milliseconds; rounding down would hand back a window
+* narrower than the one that was running, which is the direction that loses
+* media.
 */
-function selectPreRollStart(marks, preRollMs) {
-	if (marks.length === 0) return NOTHING;
-	const window = usablePreRoll(preRollMs);
-	let newest = marks[0];
-	let chosen = null;
-	for (const mark of marks) {
-		if (mark.ageMs < newest.ageMs) newest = mark;
-		if (window > 0 && mark.ageMs <= window && (chosen === null || mark.ageMs > chosen.ageMs)) chosen = mark;
-	}
-	const pick = chosen ?? newest;
-	let gopsBack = 0;
-	for (const mark of marks) if (mark.ageMs < pick.ageMs) gopsBack++;
-	return {
-		startIndex: pick.index,
-		ageMs: pick.ageMs,
-		gopsBack
+function migrateRetiredPreRollOverride(input) {
+	const retired = input.preRollMs;
+	if (retired === void 0 || Object.keys(retired).length === 0) return {
+		override: input,
+		migrated: [],
+		superseded: []
 	};
-}
-/**
-* Ceiling for the RECORDING window.
-*
-* Wider than {@link PRE_ROLL_MAX_MS} because the two windows are bounded by
-* different things. Detection's ceiling is the backlog a decoder must drain
-* before it reaches the live edge — media the analyser pays for frame by frame.
-* A recorder drains nothing: ffmpeg copies the burst to disk. What bounds THIS
-* number is the recorder's retroactive keep window (`preBufferSec`), because
-* footage the broker hands the writer from before that bound is deleted by the
-* keep gate the moment it finalizes — the divergence D191/D192 exist to forbid.
-* `packages/addon-pipeline/src/recorder/addon/__tests__/band-decision.spec.ts`
-* fails if this is ever raised past the shipped keep window.
-*/
-var RECORDING_PRE_ROLL_MAX_MS = 15e3;
-/**
-* Shipped RECORDING pre-roll on a mains camera. Operator decision, 2026-08-20.
-*
-* Unlike detection's, this one ships ON. The audit of the same day measured the
-* reason: on camera 1438 the footage began AFTER the motion in 60 % of
-* episodes, because the writer is spawned at the trigger and ffmpeg's first
-* frame is at best the live edge. A recording feature whose media starts after
-* the event is not a tuning question.
-*/
-var DEFAULT_RECORDING_PRE_ROLL_MS = 1e4;
-/**
-* Budget when the broker has not measured a bitrate for this stream yet — the
-* historical flat cap, kept verbatim as the honest "we do not know".
-*
-* `bitrateKbps` is 0 for the first stats window after every dial and after
-* every reset, so this is the value in force exactly while the ring is filling
-* for the first time.
-*/
-var PRE_ROLL_UNKNOWN_BITRATE_BYTES = 8 * 1024 * 1024;
-/**
-* Hard ceiling on the WHOLE source-RTP ring (history + the current GOP).
-*
-* Lives here, next to the pre-roll budget, because the two numbers are one
-* number: a history budget above the ring cap is not a wider window, it is a
-* ring that overflows and calls `resetRtpPreBuffer`, which drops the join
-* bootstrap of EVERY consumer — WebRTC viewers included — for as long as the
-* condition holds. Keeping them in separate files is how they came to disagree.
-* Read by `StreamBroker.captureRtpForPreBuffer`.
-*/
-var RTP_RING_MAX_BYTES = 24 * 1024 * 1024;
-/**
-* Absolute per-stream ceiling on retained pre-roll HISTORY.
-*
-* The bitrate-derived budget is what the window COSTS; this is the most any one
-* stream may spend regardless. Past it the operator has configured a window this
-* node cannot afford on that camera, and the broker says so rather than
-* delivering silently less (D192).
-*
-* **DERIVED, not chosen.** It was a free-standing `32 * 1024 * 1024` — 8 MiB
-* ABOVE the ring it has to fit inside. A ≳13 Mbps stream at a 10 s window was
-* therefore authorised to overflow its own ring and cycle `resetRtpPreBuffer`:
-* the pre-roll knob, turned up, would have taken every viewer's join bootstrap
-* with it. Deriving it from {@link RTP_RING_MAX_BYTES} minus the current-GOP
-* reserve makes the inversion unrepresentable rather than merely fixed.
-*/
-var PRE_ROLL_ABSOLUTE_MAX_BYTES = RTP_RING_MAX_BYTES - 8 * 1024 * 1024;
-/**
-* Headroom over the OBSERVED mean bitrate.
-*
-* `BrokerStatsSchema.bitrateKbps` is a mean over the stats window; a GOP
-* carrying an IDR plus a scene change is well above it. Budgeting at exactly
-* the mean would drop the oldest GOP on every busy second, so the window would
-* be the one the operator asked for only while nothing moved — which is the
-* opposite of when it is needed.
-*/
-var PRE_ROLL_BITRATE_HEADROOM = 1.5;
-/**
-* The byte budget for the history a `windowMs` pre-roll needs on a stream
-* observed at `observedKbps`.
-*
-* Replaces a FLAT 8 MiB cap. That constant was a promise the feature could not
-* keep in either direction: above ~6.5 Mbps it silently truncated the window
-* (a 4K main stream asked for 10 s and got 6), and below it, it authorised a
-* doorbell at 512 kbps to hold 8 MiB — 16x what its own window weighs.
-*/
-function preRollBudgetBytes(windowMs, observedKbps) {
-	if (!Number.isFinite(windowMs) || windowMs <= 0) return {
-		bytes: 0,
-		clamped: false
-	};
-	if (!Number.isFinite(observedKbps) || observedKbps <= 0) return {
-		bytes: PRE_ROLL_UNKNOWN_BITRATE_BYTES,
-		clamped: false
-	};
-	const raw = Math.round(windowMs * observedKbps * PRE_ROLL_BITRATE_HEADROOM / 8);
-	if (raw > 16777216) return {
-		bytes: PRE_ROLL_ABSOLUTE_MAX_BYTES,
-		clamped: true
-	};
-	return {
-		bytes: raw,
-		clamped: false
-	};
-}
-/**
-* The RECORDING window a broker retains and serves to a `/recording` dial.
-*
-* Precedence: stream override -> battery / terminal relay (0) -> cluster
-* default -> {@link DEFAULT_RECORDING_PRE_ROLL_MS}. An override wins over the
-* battery rule on purpose: the rule is a DEFAULT about where retention is
-* wasted, and an operator who typed a number for that stream has answered the
-* question the default was guessing at.
-*/
-function resolveRecordingPreRollMs(input) {
-	const override = clampPreRoll(input.overrides?.[input.camStreamId], RECORDING_PRE_ROLL_MAX_MS);
-	if (override > 0) return override;
-	if (input.batteryOperated === true) return 0;
-	if (input.terminalRelay === true) return 0;
-	if (input.clusterMs === void 0) return DEFAULT_RECORDING_PRE_ROLL_MS;
-	return clampPreRoll(input.clusterMs, RECORDING_PRE_ROLL_MAX_MS);
-}
-/**
-* Combine the cluster default and the per-camera-stream override into the one
-* pre-roll a broker applies. Precedence: stream override → cluster default →
-* OFF. Each layer is validated independently, so a bad override falls back to a
-* good cluster value rather than to nothing.
-*
-* `0` means INHERIT, never "off for this stream". It is what a cleared number
-* input posts, and the shipped cluster default is 0, so inherit and off
-* coincide on every unconfigured stream.
-*/
-function resolvePreRollMs(input) {
-	const override = clampPreRoll(input.overrides?.[input.camStreamId], PRE_ROLL_MAX_MS);
-	if (override > 0) return override;
-	if (input.terminalRelay === true) return 0;
-	return clampPreRoll(input.clusterMs, PRE_ROLL_MAX_MS);
-}
-/**
-* The packet ceiling for a burst carrying `preRollMs` of pre-roll.
-*
-* `PRIME_MAX_PACKETS` is a defensive backstop against RTP timestamps that
-* stopped describing the stream — "far more packets than this much media time
-* can contain" — not a tuning knob. Read as an absolute it would silently kill
-* pre-roll on exactly the cameras that need it (a 4K main stream at 8 Mbps
-* fills 2 000 MTU-sized packets in under 3 s), so it is applied as the RATE it
-* always was: the same packets-per-span, over the span actually requested.
-* Never shrinks the ceiling.
-*/
-function preRollPacketCeiling(bound, preRollMs) {
-	const window = usablePreRoll(preRollMs);
-	if (window <= 0 || bound.maxSpanMs <= 0) return bound.maxPackets;
-	const factor = Math.max(1, Math.ceil(window / bound.maxSpanMs));
-	return bound.maxPackets * factor;
-}
-/**
-* The span bound a DETECTION session's burst is held to while pre-roll is on.
-*
-* D57's bound is untouched for every other consumer; for this one it becomes
-* the wider of the two, because withholding a burst for being as wide as the
-* operator configured would make the knob read as ON and behave as OFF.
-*/
-function preRollSpanBound(bound, preRollMs) {
-	const window = usablePreRoll(preRollMs);
-	if (window <= 0) return bound;
+	const preBuffer = { ...input.preBuffer };
+	const migrated = [];
+	const superseded = [];
+	for (const [camStreamId, ms] of Object.entries(retired)) {
+		if (!Number.isFinite(ms) || ms <= 0) continue;
+		if (input.preBuffer?.[camStreamId] !== void 0) {
+			superseded.push(camStreamId);
+			continue;
+		}
+		preBuffer[camStreamId] = {
+			enabled: true,
+			seconds: Math.min(15, Math.max(1, Math.ceil(ms / 1e3)))
+		};
+		migrated.push(camStreamId);
+	}
+	const { preRollMs: _retired, ...rest } = input;
 	return {
-		maxSpanMs: Math.max(bound.maxSpanMs, window),
-		maxPackets: preRollPacketCeiling(bound, window)
+		override: Object.keys(preBuffer).length > 0 ? {
+			...rest,
+			preBuffer
+		} : rest,
+		migrated,
+		superseded
 	};
 }
 //#endregion
@@ -2198,6 +2017,200 @@ var PacedRtpReplay = class {
 	}
 };
 //#endregion
+//#region src/stream-broker/pre-roll.ts
+/**
+* PRE-ROLL MECHANICS — how a window of retained history is CUT, BUDGETED and
+* BOUNDED. Not how wide it is: that is the prebuffer's, and the prebuffer's
+* alone (`prebuffer.ts`, D381).
+*
+* WHAT LIVES HERE. Three mechanisms, none of them a setting:
+*
+* - {@link selectPreRollStart} — which retained keyframe access unit a burst
+*   starts at. Keyframe-aligned because D57's "the whole GOP or none of it" is
+*   the reason this selects among marks rather than slicing by time.
+* - {@link preRollBudgetBytes} — what a window of a given width WEIGHS on a
+*   stream of a measured bitrate, and the ring ceiling it has to fit inside.
+* - {@link preRollSpanBound} / {@link preRollPacketCeiling} — D57's join bound,
+*   widened for the one session that asked for history, with the packet ceiling
+*   scaled by the same factor so the defensive backstop stays a RATE.
+*
+* WHAT USED TO LIVE HERE AND DOES NOT. `resolvePreRollMs`,
+* `resolveRecordingPreRollMs`, `DEFAULT_PRE_ROLL_MS`,
+* `DEFAULT_RECORDING_PRE_ROLL_MS` and their two ceilings — a whole
+* CONFIGURATION layer, two windows deep, that decided how much history each
+* kind of consumer got. It is gone: the prebuffer decides, once, and a consumer
+* asks for what it holds. The mechanics below are unchanged, because the
+* failures they encode (an unpaced burst, a flat byte cap, a silently truncated
+* window) are about cutting history, not about choosing how much to keep.
+*
+* WHAT IT STILL CANNOT DO. Spending history is not creating it. A source that
+* was idle when motion fired has none, the selection falls back to the current
+* GOP, and the honest outcome is the ordinary join burst.
+*/
+var NOTHING = {
+	startIndex: -1,
+	ageMs: 0,
+	gopsBack: 0
+};
+/**
+* Clamp a window ALREADY resolved by the prebuffer to something this module can
+* cut.
+*
+* One clamp for every mechanism below — the selection, the packet ceiling and
+* the span bound — so a caller cannot get a wider window out of one of them
+* than out of the others. {@link PREBUFFER_MAX_MS} is the ceiling because the
+* prebuffer is the only thing that sets a window now; it was
+* `RECORDING_PRE_ROLL_MAX_MS`, and before that the DETECTION ceiling, which
+* silently truncated every recording burst to 6 s the moment there were two
+* windows — D192's failure, one layer down.
+*/
+function usablePreRoll(value) {
+	if (value === void 0) return 0;
+	if (!Number.isFinite(value) || value <= 0) return 0;
+	return Math.min(PREBUFFER_MAX_MS, value);
+}
+/**
+* Choose the keyframe access unit a pre-roll burst starts at.
+*
+* The OLDEST mark that is still inside the window wins; when none is (the
+* current GOP is itself older than `preRollMs`, i.e. a long-GOP camera with a
+* short pre-roll) the newest mark is returned, because the alternative to the
+* current GOP is nothing at all — the blind start Stage 0 exists to prevent.
+*
+* The boundary is INCLUSIVE: a keyframe exactly `preRollMs` old is inside.
+* Everything delivered after a keyframe is younger than it, so starting at a
+* mark inside the window is what makes "no frame older than `preRollMs` is
+* delivered" a property of the slice rather than a per-packet filter.
+*
+* Scans instead of assuming order: a caller that appends marks and rebases
+* indices after a trim is one refactor away from handing this an unsorted
+* array, and the failure would be a silently wider window.
+*/
+function selectPreRollStart(marks, preRollMs) {
+	if (marks.length === 0) return NOTHING;
+	const window = usablePreRoll(preRollMs);
+	let newest = marks[0];
+	let chosen = null;
+	for (const mark of marks) {
+		if (mark.ageMs < newest.ageMs) newest = mark;
+		if (window > 0 && mark.ageMs <= window && (chosen === null || mark.ageMs > chosen.ageMs)) chosen = mark;
+	}
+	const pick = chosen ?? newest;
+	let gopsBack = 0;
+	for (const mark of marks) if (mark.ageMs < pick.ageMs) gopsBack++;
+	return {
+		startIndex: pick.index,
+		ageMs: pick.ageMs,
+		gopsBack
+	};
+}
+/**
+* Budget when the broker has not measured a bitrate for this stream yet — the
+* historical flat cap, kept verbatim as the honest "we do not know".
+*
+* `bitrateKbps` is 0 for the first stats window after every dial and after
+* every reset, so this is the value in force exactly while the ring is filling
+* for the first time.
+*/
+var PRE_ROLL_UNKNOWN_BITRATE_BYTES = 8 * 1024 * 1024;
+/**
+* Hard ceiling on the WHOLE source-RTP ring (history + the current GOP).
+*
+* Lives here, next to the pre-roll budget, because the two numbers are one
+* number: a history budget above the ring cap is not a wider window, it is a
+* ring that overflows and calls `resetRtpPreBuffer`, which drops the join
+* bootstrap of EVERY consumer — WebRTC viewers included — for as long as the
+* condition holds. Keeping them in separate files is how they came to disagree.
+* Read by `StreamBroker.captureRtpForPreBuffer`.
+*/
+var RTP_RING_MAX_BYTES = 24 * 1024 * 1024;
+/**
+* Absolute per-stream ceiling on retained pre-roll HISTORY.
+*
+* The bitrate-derived budget is what the window COSTS; this is the most any one
+* stream may spend regardless. Past it the operator has configured a window this
+* node cannot afford on that camera, and the broker says so rather than
+* delivering silently less (D192).
+*
+* **DERIVED, not chosen.** It was a free-standing `32 * 1024 * 1024` — 8 MiB
+* ABOVE the ring it has to fit inside. A ≳13 Mbps stream at a 10 s window was
+* therefore authorised to overflow its own ring and cycle `resetRtpPreBuffer`:
+* the pre-roll knob, turned up, would have taken every viewer's join bootstrap
+* with it. Deriving it from {@link RTP_RING_MAX_BYTES} minus the current-GOP
+* reserve makes the inversion unrepresentable rather than merely fixed.
+*/
+var PRE_ROLL_ABSOLUTE_MAX_BYTES = RTP_RING_MAX_BYTES - 8 * 1024 * 1024;
+/**
+* Headroom over the OBSERVED mean bitrate.
+*
+* `BrokerStatsSchema.bitrateKbps` is a mean over the stats window; a GOP
+* carrying an IDR plus a scene change is well above it. Budgeting at exactly
+* the mean would drop the oldest GOP on every busy second, so the window would
+* be the one the operator asked for only while nothing moved — which is the
+* opposite of when it is needed.
+*/
+var PRE_ROLL_BITRATE_HEADROOM = 1.5;
+/**
+* The byte budget for the history a `windowMs` pre-roll needs on a stream
+* observed at `observedKbps`.
+*
+* Replaces a FLAT 8 MiB cap. That constant was a promise the feature could not
+* keep in either direction: above ~6.5 Mbps it silently truncated the window
+* (a 4K main stream asked for 10 s and got 6), and below it, it authorised a
+* doorbell at 512 kbps to hold 8 MiB — 16x what its own window weighs.
+*/
+function preRollBudgetBytes(windowMs, observedKbps) {
+	if (!Number.isFinite(windowMs) || windowMs <= 0) return {
+		bytes: 0,
+		clamped: false
+	};
+	if (!Number.isFinite(observedKbps) || observedKbps <= 0) return {
+		bytes: PRE_ROLL_UNKNOWN_BITRATE_BYTES,
+		clamped: false
+	};
+	const raw = Math.round(windowMs * observedKbps * PRE_ROLL_BITRATE_HEADROOM / 8);
+	if (raw > 16777216) return {
+		bytes: PRE_ROLL_ABSOLUTE_MAX_BYTES,
+		clamped: true
+	};
+	return {
+		bytes: raw,
+		clamped: false
+	};
+}
+/**
+* The packet ceiling for a burst carrying `preRollMs` of pre-roll.
+*
+* `PRIME_MAX_PACKETS` is a defensive backstop against RTP timestamps that
+* stopped describing the stream — "far more packets than this much media time
+* can contain" — not a tuning knob. Read as an absolute it would silently kill
+* pre-roll on exactly the cameras that need it (a 4K main stream at 8 Mbps
+* fills 2 000 MTU-sized packets in under 3 s), so it is applied as the RATE it
+* always was: the same packets-per-span, over the span actually requested.
+* Never shrinks the ceiling.
+*/
+function preRollPacketCeiling(bound, preRollMs) {
+	const window = usablePreRoll(preRollMs);
+	if (window <= 0 || bound.maxSpanMs <= 0) return bound.maxPackets;
+	const factor = Math.max(1, Math.ceil(window / bound.maxSpanMs));
+	return bound.maxPackets * factor;
+}
+/**
+* The span bound a DETECTION session's burst is held to while pre-roll is on.
+*
+* D57's bound is untouched for every other consumer; for this one it becomes
+* the wider of the two, because withholding a burst for being as wide as the
+* operator configured would make the knob read as ON and behave as OFF.
+*/
+function preRollSpanBound(bound, preRollMs) {
+	const window = usablePreRoll(preRollMs);
+	if (window <= 0) return bound;
+	return {
+		maxSpanMs: Math.max(bound.maxSpanMs, window),
+		maxPackets: preRollPacketCeiling(bound, window)
+	};
+}
+//#endregion
 //#region src/stream-broker/rtsp/annexb-deframer.ts
 /**
 * Annex-B NAL unit deframer.
@@ -2975,7 +2988,7 @@ var RtspRestreamer = class {
 		if (primePackets.length === 0) return;
 		const firstTs = primePackets[0].data.readUInt32BE(4);
 		const spanMs = (primePackets[primePackets.length - 1].data.readUInt32BE(4) - firstTs | 0) / 90;
-		const preRollPlans = /* @__PURE__ */ new Map();
+		const preRollState = { plan: null };
 		const bound = this.currentPrimeBound();
 		/**
 		* Resolve (and memoize) the plan for one intent.
@@ -2987,10 +3000,9 @@ var RtspRestreamer = class {
 		* current GOP or a supplier bug can, and D57's remedy (join clean at the
 		* next live keyframe) is the right one for a burst nobody asked for.
 		*/
-		const planFor = (intent) => {
-			const cached = preRollPlans.get(intent);
-			if (cached) return cached;
-			const burst = this.preRollSupplier?.(intent);
+		const planFor = () => {
+			if (preRollState.plan) return preRollState.plan;
+			const burst = this.preRollSupplier?.();
 			const window = fromRing && burst && burst.preRollMs > 0 ? burst.packets() : [];
 			const packets = window.length > primePackets.length ? window.map((data) => ({
 				data,
@@ -3005,7 +3017,7 @@ var RtspRestreamer = class {
 				spanMs: windowSpanMs,
 				overBound: packets.length > 0 && (windowSpanMs > windowBound.maxSpanMs || packets.length > windowBound.maxPackets)
 			};
-			preRollPlans.set(intent, plan);
+			preRollState.plan = plan;
 			return plan;
 		};
 		const served = [];
@@ -3018,7 +3030,7 @@ var RtspRestreamer = class {
 			const detectionIntent = session.isDetectionIntent();
 			const preRollIntent = session.preRollIntent();
 			if (preRollIntent !== null) {
-				const plan = planFor(preRollIntent);
+				const plan = planFor();
 				if (plan.active) {
 					if (plan.overBound) {
 						this.dropsWithheldSpan++;
@@ -3063,11 +3075,10 @@ var RtspRestreamer = class {
 		}
 		if (withheld > 0) this.reportDrops(false);
 		if (served.length === 0) return;
-		/** Media actually delivered to this intent, or `-1` when none joined. */
-		const servedSpanMs = (intent) => {
-			const plan = preRollPlans.get(intent);
-			return plan === void 0 ? -1 : Math.round(plan.spanMs);
-		};
+		/** Media actually delivered, or `-1` when nobody asked for history at all. */
+		const servedSpanMs = preRollState.plan === null ? -1 : Math.round(preRollState.plan.spanMs);
+		/** Which declared intents joined this burst — `0` is "none", not "off". */
+		const intentsServed = new Set(servedPreRoll.values());
 		this.logger?.info("restream prime (lat-probe)", {
 			tags: { deviceId: this.deviceId },
 			meta: {
@@ -3080,10 +3091,10 @@ var RtspRestreamer = class {
 				boundPackets: bound.maxPackets,
 				withheld,
 				detectionIntentServed,
-				detectionPreRollMs: this.preRollSupplier?.("detection").preRollMs ?? 0,
-				recordingPreRollMs: this.preRollSupplier?.("recording").preRollMs ?? 0,
-				detectionPreRollSpanMs: servedSpanMs("detection"),
-				recordingPreRollSpanMs: servedSpanMs("recording"),
+				prebufferMs: this.preRollSupplier?.().preRollMs ?? 0,
+				preRollSpanMs: servedSpanMs,
+				recordingIntentServed: intentsServed.has("recording"),
+				detectionPreRollServed: intentsServed.has("detection"),
 				preRollServed: servedPreRoll.size
 			}
 		});
@@ -3092,16 +3103,15 @@ var RtspRestreamer = class {
 			prime: true,
 			keyframeAuStart: false
 		}));
-		const preRollItems = /* @__PURE__ */ new Map();
-		for (const intent of new Set(servedPreRoll.values())) preRollItems.set(intent, (preRollPlans.get(intent)?.packets ?? []).map((packet) => ({
+		const preRollItems = servedPreRoll.size > 0 ? (preRollState.plan?.packets ?? []).map((packet) => ({
 			packet,
 			prime: true,
 			keyframeAuStart: false
-		})));
+		})) : [];
 		for (const sessionId of served) {
 			this.pendingKeyframe.delete(sessionId);
 			const intent = servedPreRoll.get(sessionId);
-			this.startPrimeReplay(sessionId, intent ? preRollItems.get(intent) ?? items : items, intent ?? null);
+			this.startPrimeReplay(sessionId, intent ? preRollItems : items, intent ?? null);
 		}
 	}
 	/**
@@ -11530,8 +11540,29 @@ var StreamBroker = class StreamBroker {
 	firstKeyframeReceived = false;
 	/** Timer for push-mode stall detection. */
 	pushStallTimer;
-	/** Whether pre-buffer counts as demand (keeps the stream alive even with 0 subscribers). */
-	_preBufferEnabled = true;
+	/**
+	* Whether the prebuffer holds this stream dialed with zero real subscribers.
+	*
+	* **Starts OFF, and only {@link setPrebuffer} ever writes it.** It used to
+	* start `true`, which is how this broker came to hold a state the settings
+	* screen contradicted: `stream-broker-manager` resolved the same question as
+	* `enabled ?? false` and showed OFF, while an unconfigured broker was already
+	* warm. Neither was "the current configuration" — there were two — and that
+	* is the defect D381 retires. Unconfigured now means off; the manager applies
+	* the resolved prebuffer to every broker it creates, so the honest default
+	* (ON for a mains camera's warm profile) arrives from the one place that
+	* decides it.
+	*/
+	_preBufferEnabled = false;
+	/**
+	* The open prebuffer hold, or `null` when the prebuffer is off.
+	*
+	* A real object rather than a flag plus a synthetic row, so "who is keeping
+	* camera 617 warm?" is answered by something that EXISTS: it has an id, it
+	* has a start time, and `hasDemand()` consults it the way it consults every
+	* other holder.
+	*/
+	prebufferHold = null;
 	/**
 	* Seconds of AnnexB video retained SPECIFICALLY so a notification clip can be
 	* cut around a past instant (`renderPreBufferClip`). 0 = no clip retention.
@@ -11598,26 +11629,22 @@ var StreamBroker = class StreamBroker {
 	*/
 	rtpRingKeyframeMarks = [];
 	/**
-	* Media time (ms) of history a DETECTION decode dial may be handed before the
-	* live edge — motion-start Stage 2. `0` (default) = off, and every path here
-	* then behaves exactly as it did before pre-roll existed. Resolved per stream
-	* by `resolvePreRollMs` and pushed by the manager.
-	*/
-	detectionPreRollMs = 0;
-	/**
-	* Media time (ms) of history a RECORDING dial (`/recording`) is handed — the
-	* `events`-band recorder's ffmpeg, which is spawned AT the trigger and whose
-	* first frame is otherwise at best the live edge.
+	* Media time (ms) of history this broker RETAINS and will hand to a consumer
+	* that declared it attaches after the edge it needs to see.
 	*
-	* A SECOND number, not a wider first one (D193). The two windows are set by
-	* the operator for different reasons and cost different things: detection's
-	* is a backlog a decoder must drain, recording's is bytes copied to disk.
-	* Raising one to serve the other would change every detection dial on the
-	* fleet to buy a recorder ten seconds — the coupling the 2026-08-20 census
-	* named before anything was turned on. Resolved by `resolveRecordingPreRollMs`
-	* and pushed by the manager.
+	* ONE number (D381), derived from the ONE prebuffer configuration by
+	* `prebufferRetentionMs` and pushed by the manager through
+	* {@link setPrebuffer}. It replaced `detectionPreRollMs` and
+	* `recordingPreRollMs`, which were two configurations of the same retention
+	* that the operator had to keep consistent by hand — and a third,
+	* `preBufferSec`, which sized an Annex-B ring that is never fed for an RTP
+	* source and therefore retained nothing at all on every warm camera in the
+	* fleet.
+	*
+	* A consumer never sets this and never asks for a number wider than it: a
+	* request is capped at read time by {@link capPreRollRequestMs}.
 	*/
-	recordingPreRollMs = 0;
+	prebufferMs = 0;
 	/**
 	* Effective join-burst bound for this stream's RTSP restream — the cluster
 	* default, or this camera stream's override. Applies to the RESTREAM
@@ -11669,11 +11696,10 @@ var StreamBroker = class StreamBroker {
 		if (logger) this.rtspRestreamer.setLogger(logger.child("rtsp"));
 		this.rtspRestreamer.setRtpPreBufferSupplier(() => this.getRtpPreBuffer());
 		this.rtspRestreamer.setPrimeBoundSupplier(() => this.joinBurstBound);
-		this.rtspRestreamer.setPreRollSupplier((intent) => {
-			const windowMs = intent === "recording" ? this.recordingPreRollMs : this.detectionPreRollMs;
+		this.rtspRestreamer.setPreRollSupplier(() => {
 			return {
-				packets: () => this.getRtpPreRollBuffer(windowMs),
-				preRollMs: windowMs
+				packets: () => this.getRtpPreRollBuffer(),
+				preRollMs: this.prebufferMs
 			};
 		});
 		this.preBuffer = new EncodedRingBuffer(StreamBroker.DEFAULT_PRE_BUFFER_SEC);
@@ -12079,9 +12105,30 @@ var StreamBroker = class StreamBroker {
 			}
 		});
 	}
-	/** Set whether pre-buffer counts as demand. When false and no other consumers, the broker suspends. */
+	/**
+	* Open or release the prebuffer HOLD — the session that keeps this stream
+	* dialed with no real consumer attached.
+	*
+	* Opening it is what "prebuffer on" MEANS: there is a holder, it has a name
+	* and a start time, and it appears in `listClients()` beside every other
+	* holder. Re-arming an already-open hold keeps its `since`, so the operator
+	* reads how long this camera has been held warm rather than how long ago the
+	* settings were last re-applied.
+	*/
 	setPreBufferEnabled(enabled) {
+		if (enabled === this._preBufferEnabled) return;
 		this._preBufferEnabled = enabled;
+		this.prebufferHold = enabled ? {
+			id: `prebuffer:${this.deviceId}`,
+			since: Date.now()
+		} : null;
+		this.logger?.info(enabled ? "prebuffer hold opened" : "prebuffer hold released", {
+			tags: { deviceId: this.numericDeviceId },
+			meta: {
+				brokerId: this.deviceId,
+				retentionMs: this.prebufferMs
+			}
+		});
 		this.checkDemand();
 	}
 	/** True when at least one consumer needs the stream alive. */
@@ -12092,7 +12139,7 @@ var StreamBroker = class StreamBroker {
 		if (this.audioChunkPlane.subscriberCount > 0) return true;
 		if (this.rtspRestreamer.getSessionCount() > 0) return true;
 		if (this.pipeServer.getClientCount() > 0) return true;
-		if (this._preBufferEnabled) return true;
+		if (this.prebufferHold !== null) return true;
 		return false;
 	}
 	/**
@@ -12716,48 +12763,36 @@ var StreamBroker = class StreamBroker {
 		this.rtpRingKeyframeMarks = [];
 	}
 	/**
-	* Configure how much history a DETECTION dial may be handed (Stage 2).
+	* Install THE prebuffer for this stream — the one configuration that decides
+	* whether this broker holds the source warm and how much history it keeps.
 	*
-	* Also widens the decoder-seed ring so the PUSH (Annex-B) plane can honour
-	* the same number: that ring is what `getSeedPackets` replays into a
-	* freshly-armed decoder, and a 6 s retention cannot serve a 6 s pre-roll plus
-	* the GOP that carries it.
-	*/
-	setDetectionPreRollMs(ms) {
-		const next = Number.isFinite(ms) && ms > 0 ? ms : 0;
-		if (next === this.detectionPreRollMs) return;
-		this.detectionPreRollMs = next;
+	* Every ring this broker owns is sized from it, each fed by the source type
+	* it belongs to: the source-RTP ring (RTSP cameras, the history a join burst
+	* is cut from), the Annex-B `preBuffer` (push sources), and the decoder seed.
+	* That is the correction this record exists for — the seconds used to size
+	* ONLY the Annex-B ring, which is never fed for an RTP source, so on every
+	* warm camera in this fleet the configured seconds retained nothing while two
+	* other numbers quietly sized the history that did exist.
+	*/
+	setPrebuffer(config) {
+		const next = prebufferRetentionMs(config);
+		this.setPreBufferEnabled(config.enabled);
+		this.setPreBufferDuration(config.seconds);
+		if (next === this.prebufferMs) return;
+		this.prebufferMs = next;
 		const seedSec = Math.max(StreamBroker.DECODER_SEED_BUFFER_SEC, Math.ceil(next / 1e3) + 2);
 		this.decoderSeedBuffer.setDuration(seedSec);
 	}
 	/**
-	* Configure how much history a RECORDING dial is handed.
+	* How far back the ring is kept — the prebuffer, and nothing else.
 	*
-	* Touches the RETENTION (through {@link getPreRollRetentionMs}) and nothing
-	* else: no decoder seed, no change to what any other consumer is served.
-	*/
-	setRecordingPreRollMs(ms) {
-		const next = Number.isFinite(ms) && ms > 0 ? ms : 0;
-		this.recordingPreRollMs = next;
-	}
-	/** The DETECTION pre-roll in force for this stream (ms). `0` = off. */
-	getDetectionPreRollMs() {
-		return this.detectionPreRollMs;
-	}
-	/** The RECORDING pre-roll in force for this stream (ms). `0` = off. */
-	getRecordingPreRollMs() {
-		return this.recordingPreRollMs;
-	}
-	/**
-	* How far back the ring is kept: the WIDER of the two windows.
-	*
-	* One retention serves both because the bytes are the same bytes — the ring
-	* is cut per intent at read time ({@link getRtpPreRollBuffer}), so a 10 s
-	* recording window does not hand a detection dial 10 s of backlog. Retaining
-	* per intent would be two rings of the same packets.
+	* It used to be `max(detectionPreRollMs, recordingPreRollMs)`: a maximum over
+	* CONFIGURATIONS, which is what made "how much history does camera 617 hold"
+	* a question with two answers and no owner. There is one configuration now,
+	* so the retention is it.
 	*/
 	getPreRollRetentionMs() {
-		return Math.max(this.detectionPreRollMs, this.recordingPreRollMs);
+		return this.prebufferMs;
 	}
 	/**
 	* Byte budget for the EXTRA history pre-roll retains, over and above the
@@ -12791,7 +12826,7 @@ var StreamBroker = class StreamBroker {
 	* both, so a fix to the boundary cannot land on only one plane.
 	*/
 	getDecoderSeedPackets() {
-		if (this.detectionPreRollMs <= 0) return this.decoderSeedBuffer.getPackets();
+		if (this.prebufferMs <= 0) return this.decoderSeedBuffer.getPackets();
 		const all = this.decoderSeedBuffer.getAllPackets();
 		if (all.length === 0) return [];
 		const newestPts = all[all.length - 1].pts;
@@ -12803,7 +12838,7 @@ var StreamBroker = class StreamBroker {
 				ageMs: newestPts - packet.pts
 			});
 		}
-		const selection = selectPreRollStart(marks, this.detectionPreRollMs);
+		const selection = selectPreRollStart(marks, this.prebufferMs);
 		return selection.startIndex < 0 ? [] : all.slice(selection.startIndex);
 	}
 	/** Retained keyframe AUs as ages in ms of media time behind `newestTs`. */
@@ -12873,8 +12908,9 @@ var StreamBroker = class StreamBroker {
 	* when motion fired retained nothing, and the honest outcome there is the
 	* Stage 0 burst rather than a pretend one.
 	*/
-	getRtpPreRollBuffer(windowMs) {
+	getRtpPreRollBuffer(requestedMs) {
 		if (!this.rtpRingHasKeyframe) return [];
+		const windowMs = capPreRollRequestMs(requestedMs, this.prebufferMs);
 		if (windowMs <= 0 || this.rtpRing.length === 0) return this.getRtpPreBuffer();
 		const newestTs = this.rtpRing[this.rtpRing.length - 1].readUInt32BE(4);
 		const selection = selectPreRollStart(this.rtpPreRollMarks(newestTs), windowMs);
@@ -12897,8 +12933,7 @@ var StreamBroker = class StreamBroker {
 			tags: { deviceId: this.numericDeviceId },
 			meta: {
 				retentionMs,
-				detectionPreRollMs: this.detectionPreRollMs,
-				recordingPreRollMs: this.recordingPreRollMs,
+				prebufferMs: this.prebufferMs,
 				bitrateKbps: this.bitrateKbps,
 				budgetBytes: budget.bytes
 			}
@@ -13154,15 +13189,16 @@ var StreamBroker = class StreamBroker {
 			subscribedAt: entry.subscribedAt,
 			packetsDelivered: entry.packetsDelivered
 		});
-		if (this._preBufferEnabled && encoded.length === 0) encoded.push({
-			id: "prebuffer-hold",
+		const hold = this.prebufferHold;
+		if (hold) encoded.push({
+			id: hold.id,
 			channel: "annexb",
 			attribution: {
 				kind: "warmup",
 				userAgent: "prebuffer",
 				media: "video"
 			},
-			subscribedAt: this.startedAt,
+			subscribedAt: hold.since,
 			packetsDelivered: 0
 		});
 		return {
@@ -15078,7 +15114,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 	cachedIngestOwnerAt = 0;
 	static INGEST_OWNER_CACHE_TTL_MS = 6e4;
 	lastOwnershipReconcile = Promise.resolve();
-	defaultPreBufferSec = 10;
+	defaultPreBufferSec = 5;
 	/**
 	* Cluster-wide default join-burst span bound (D57). `undefined` until the
 	* addon applies its config, at which point every live broker is re-bounded.
@@ -15087,20 +15123,6 @@ var StreamBrokerManager = class StreamBrokerManager {
 	* happened to own its ingest (D52/D56).
 	*/
 	defaultJoinBurstMaxSpanMs;
-	/**
-	* Cluster-wide default pre-roll (ms) — motion-start Stage 2. Cluster-scoped
-	* for the same reason as the join-burst bound (a movable ingest role must not
-	* change a camera's behaviour), and 0 by default: pre-roll spends retained
-	* bytes on the ingest node, so it is turned on per camera that needs it.
-	*/
-	defaultPreRollMs = 0;
-	/**
-	* Cluster-wide default RECORDING pre-roll (ms). `undefined` until the addon
-	* pushes its config — which is a different fact from `0` and must stay so:
-	* `0` is an operator turning the feature OFF, `undefined` is a boot that has
-	* not read the setting yet and takes `DEFAULT_RECORDING_PRE_ROLL_MS`.
-	*/
-	defaultRecordingPreRollMs = void 0;
 	webrtcServer = null;
 	/**
 	* brokerId → the remote-encoded adapter backing a non-owned camera's WebRTC
@@ -15706,8 +15728,14 @@ var StreamBrokerManager = class StreamBrokerManager {
 			return always;
 		}
 	}
+	/**
+	* The cluster-wide prebuffer SECONDS — the only duration in this subsystem
+	* (D381). Pushed into every live broker, because a broker created before the
+	* edit would otherwise keep the old retention for the life of the stream.
+	*/
 	setDefaultPreBufferSec(sec) {
 		this.defaultPreBufferSec = sec;
+		this.pushPrebufferToLiveBrokers();
 	}
 	/**
 	* Set the cluster-wide default join-burst span bound and push the newly
@@ -15739,48 +15767,16 @@ var StreamBrokerManager = class StreamBrokerManager {
 		}));
 	}
 	/**
-	* Set the cluster-wide default pre-roll and push the newly effective value
-	* into every live broker — same reasoning as the join-burst bound: a broker
-	* outlives the setting that configured it.
+	* Set the cluster-wide default prebuffer SECONDS and push the newly
+	* effective configuration into every live broker — a broker outlives the
+	* setting that configured it, so an un-pushed edit would apply to cameras
+	* published afterwards and to no others.
 	*/
-	setDefaultPreRollMs(ms) {
-		this.defaultPreRollMs = ms;
+	pushPrebufferToLiveBrokers() {
 		for (const [brokerId, broker] of this.brokers) {
 			const parsed = parseBrokerId(brokerId);
 			if (!parsed) continue;
-			this.applyPreRoll(broker, parsed.deviceId, parsed.camStreamId);
-		}
-	}
-	/**
-	* Resolve and install this stream's pre-roll (Stage 2). A `pull-http` relay
-	* — the terminal cameras — takes the cluster default as 0 (operator
-	* decision); an explicit per-stream override still reaches it.
-	*/
-	applyPreRoll(broker, deviceId, camStreamId) {
-		const terminalRelay = this.cameraStreams.get(deviceId)?.get(camStreamId)?.kind === "pull-http";
-		broker.setDetectionPreRollMs(resolvePreRollMs({
-			camStreamId,
-			clusterMs: this.defaultPreRollMs,
-			overrides: this.deviceOverrides.get(deviceId)?.preRollMs,
-			terminalRelay
-		}));
-		broker.setRecordingPreRollMs(resolveRecordingPreRollMs({
-			camStreamId,
-			clusterMs: this.defaultRecordingPreRollMs,
-			terminalRelay,
-			batteryOperated: this.deviceHasFeature(deviceId, DeviceFeature.BatteryOperated)
-		}));
-	}
-	/**
-	* Set the cluster-wide default RECORDING pre-roll and push it into every live
-	* broker — same reasoning as detection's: a broker outlives its setting.
-	*/
-	setDefaultRecordingPreRollMs(ms) {
-		this.defaultRecordingPreRollMs = ms;
-		for (const [brokerId, broker] of this.brokers) {
-			const parsed = parseBrokerId(brokerId);
-			if (!parsed) continue;
-			this.applyPreRoll(broker, parsed.deviceId, parsed.camStreamId);
+			this.applyPrebufferConfig(broker, parsed.deviceId, parsed.camStreamId);
 		}
 	}
 	setEventBus(bus) {
@@ -17764,7 +17760,17 @@ var StreamBrokerManager = class StreamBrokerManager {
 	}
 	loadPersistedDeviceOverrides(overrides) {
 		this.deviceOverrides.clear();
-		for (const [k, v] of overrides) this.deviceOverrides.set(k, v);
+		for (const [deviceId, persisted] of overrides) {
+			const { override, migrated, superseded } = migrateRetiredPreRollOverride(persisted);
+			if (migrated.length > 0 || superseded.length > 0) this.logger.info("retired per-stream pre-roll folded into the prebuffer", {
+				tags: { deviceId },
+				meta: {
+					migrated,
+					superseded
+				}
+			});
+			this.deviceOverrides.set(deviceId, override);
+		}
 		(async () => {
 			for (const [deviceId, override] of overrides) {
 				if (!override.derivedStreams) continue;
@@ -17796,19 +17802,6 @@ var StreamBrokerManager = class StreamBrokerManager {
 		})();
 	}
 	/**
-	* Effective pre-buffer duration for a brokerId's profile.
-	*
-	* Priority: per-profile override → legacy single-value override →
-	* battery-aware default (0 when the device has BatteryOperated and
-	* no override) → addon default.
-	*/
-	getEffectivePreBufferSec(deviceId, camStreamId, addonDefault, forceForDetection = false) {
-		const perStream = this.deviceOverrides.get(deviceId)?.preBuffer?.[camStreamId];
-		if (perStream) return perStream.enabled || forceForDetection ? perStream.seconds : 0;
-		if (this.deviceHasFeature(deviceId, DeviceFeature.BatteryOperated)) return 0;
-		return addonDefault;
-	}
-	/**
 	* Per-device streaming debug flag — controls verbose info-level
 	* logging across the broker, WebRTC server, and session for one
 	* device. Off by default.
@@ -17948,9 +17941,9 @@ var StreamBrokerManager = class StreamBrokerManager {
 			const profile = findProfileForStream(assignment.map, camStreamId);
 			const rtspEnabled = this.rtspProvider.isEnabled(brokerId);
 			const rtspEntry = this.rtspProvider.getEntry(brokerId);
-			const perStream = override?.preBuffer?.[camStreamId];
-			const preBufferEnabled = perStream?.enabled ?? false;
-			const preBufferSec = perStream?.seconds ?? this.defaultPreBufferSec;
+			const effectivePrebuffer = this.effectivePrebuffer(deviceId, camStreamId);
+			const preBufferEnabled = effectivePrebuffer.enabled;
+			const preBufferSec = effectivePrebuffer.enabled ? effectivePrebuffer.seconds : this.defaultPreBufferSec;
 			const hwAccelValue = override?.hwaccel?.[camStreamId] ?? "copy";
 			const sourceParserOptionSettings = sourceParserOptionsFor(sourceTypeForParser(stream.kind));
 			const sourceParserField = sourceParserOptionSettings.length > 0 ? [{
@@ -18046,16 +18039,17 @@ var StreamBrokerManager = class StreamBrokerManager {
 					style: "switch",
 					key: `preBufferEnabled:${camStreamId}`,
 					label: "Pre-buffer",
-					description: "Keep a rolling buffer for instant playback on events. Forced on when detection uses this stream.",
-					default: false,
+					description: "Hold this stream dialed and keep the last few seconds of it, so anything that attaches after an event — a recording, a detection decode — starts BEFORE the event instead of at the live edge. This is the only history setting in the system: recordings and detection ask for what is kept here and never configure a window of their own. Costs a permanent connection to the camera and memory on the ingest node. On by default for a mains camera's main profile; off for a battery camera, which has nothing to hold between wakes.",
+					default: preBufferEnabled,
 					value: preBufferEnabled
 				},
 				{
 					type: "slider",
 					key: `preBufferSec:${camStreamId}`,
 					label: "Pre-buffer Duration",
+					description: "Seconds of history kept while the pre-buffer is on. A consumer is served this much or less — never more, and never more than the stream has actually been warm for.",
 					min: 0,
-					max: 30,
+					max: 15,
 					step: 1,
 					unit: "s",
 					default: this.defaultPreBufferSec,
@@ -18075,19 +18069,6 @@ var StreamBrokerManager = class StreamBrokerManager {
 					default: 0,
 					value: override?.joinBurstMaxSpanMs?.[camStreamId] ?? 0
 				},
-				{
-					type: "number",
-					key: `preRollMs:${camStreamId}`,
-					label: "Detection pre-roll",
-					description: "How much video from BEFORE the motion edge a detection decode is handed when it attaches, so the first analysed frames predate the trigger. Costs retained memory on the ingest node while this stream is dialed, and only reaches back as far as the stream has been warm — it never dials a camera. Served to the detection decode alone: viewers, recordings and HomeKit legs are unaffected. 0 = inherit the cluster default (off).",
-					min: 0,
-					max: PRE_ROLL_MAX_MS,
-					step: 250,
-					unit: "ms",
-					span: 2,
-					default: 0,
-					value: override?.preRollMs?.[camStreamId] ?? 0
-				},
 				{
 					type: "select",
 					key: `hwaccel:${camStreamId}`,
@@ -18296,36 +18277,29 @@ var StreamBrokerManager = class StreamBrokerManager {
 				this.rtspProvider.setEnabled(brokerId, Boolean(value));
 				continue;
 			}
-			if (fieldKey.startsWith("preBufferEnabled:")) {
-				const camStreamId = fieldKey.slice(17);
+			if (fieldKey.startsWith("preBufferEnabled:") || fieldKey.startsWith("preBufferSec:")) {
+				const isSwitch = fieldKey.startsWith("preBufferEnabled:");
+				const camStreamId = fieldKey.slice((isSwitch ? "preBufferEnabled:" : "preBufferSec:").length);
 				overrideDirty = true;
 				const pb = { ...nextOverride.preBuffer };
-				const current = pb[camStreamId] ?? this.defaultStreamPreBuffer(deviceId, camStreamId);
-				const enabled = Boolean(value);
-				pb[camStreamId] = {
+				const current = pb[camStreamId] ?? this.effectivePrebuffer(deviceId, camStreamId);
+				pb[camStreamId] = isSwitch ? {
+					enabled: Boolean(value),
+					seconds: current.seconds > 0 ? current.seconds : this.defaultPreBufferSec
+				} : {
 					...current,
-					enabled
+					seconds: typeof value === "number" && Number.isFinite(value) ? value : this.defaultPreBufferSec
 				};
 				nextOverride.preBuffer = pb;
 				const broker = this.brokers.get(brokerIdFor(deviceId, camStreamId));
-				if (broker) {
-					broker.setPreBufferDuration(enabled ? pb[camStreamId]?.seconds ?? this.defaultPreBufferSec : 0);
-					broker.setPreBufferEnabled(enabled);
-				}
-				continue;
-			}
-			if (fieldKey.startsWith("preBufferSec:")) {
-				const camStreamId = fieldKey.slice(13);
-				const seconds = typeof value === "number" && Number.isFinite(value) ? value : this.defaultPreBufferSec;
-				overrideDirty = true;
-				const pb = { ...nextOverride.preBuffer };
-				pb[camStreamId] = {
-					...pb[camStreamId] ?? this.defaultStreamPreBuffer(deviceId, camStreamId),
-					seconds
-				};
-				nextOverride.preBuffer = pb;
-				const broker = this.brokers.get(brokerIdFor(deviceId, camStreamId));
-				if (broker && pb[camStreamId]?.enabled !== false) broker.setPreBufferDuration(seconds);
+				if (broker) broker.setPrebuffer(resolvePrebuffer({
+					camStreamId,
+					clusterSeconds: this.defaultPreBufferSec,
+					overrides: pb,
+					defaultWarm: this.isDefaultWarm(deviceId, camStreamId),
+					batteryOperated: this.deviceHasFeature(deviceId, DeviceFeature.BatteryOperated),
+					terminalRelay: this.cameraStreams.get(deviceId)?.get(camStreamId)?.kind === "pull-http"
+				}));
 				continue;
 			}
 			if (fieldKey.startsWith("joinBurstMaxSpanMs:")) {
@@ -18343,22 +18317,6 @@ var StreamBrokerManager = class StreamBrokerManager {
 				}));
 				continue;
 			}
-			if (fieldKey.startsWith("preRollMs:")) {
-				const camStreamId = fieldKey.slice(10);
-				overrideDirty = true;
-				const pr = { ...nextOverride.preRollMs };
-				if (typeof value === "number" && Number.isFinite(value) && value > 0) pr[camStreamId] = Math.min(PRE_ROLL_MAX_MS, Math.max(250, value));
-				else delete pr[camStreamId];
-				nextOverride.preRollMs = pr;
-				const broker = this.brokers.get(brokerIdFor(deviceId, camStreamId));
-				if (broker) broker.setDetectionPreRollMs(resolvePreRollMs({
-					camStreamId,
-					clusterMs: this.defaultPreRollMs,
-					overrides: pr,
-					terminalRelay: this.cameraStreams.get(deviceId)?.get(camStreamId)?.kind === "pull-http"
-				}));
-				continue;
-			}
 			if (fieldKey.startsWith("hwaccel:")) {
 				const camStreamId = fieldKey.slice(8);
 				overrideDirty = true;
@@ -18704,7 +18662,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 		if (current.map.high !== newMap.high) for (const camStreamId of [current.map.high, newMap.high]) {
 			if (!camStreamId) continue;
 			const broker = this.brokers.get(brokerIdFor(deviceId, camStreamId));
-			if (broker) this.applyPreBufferConfig(broker, deviceId, camStreamId);
+			if (broker) this.applyPrebufferConfig(broker, deviceId, camStreamId);
 		}
 		for (const [camId, prevCount] of oldPushConsumers) if ((newPushConsumers.get(camId) ?? 0) === 0 && prevCount > 0) this.emitCamStreamIdle(deviceId, camId);
 		for (const [camId, nextCount] of newPushConsumers) if ((oldPushConsumers.get(camId) ?? 0) === 0 && nextCount > 0) {
@@ -18987,11 +18945,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 		const cam = this.cameraStreams.get(deviceId)?.get(camStreamId);
 		if (!cam) return;
 		const brokerId = brokerIdFor(deviceId, camStreamId);
-		const live = this.brokers.get(brokerId);
-		if (live) {
-			this.applyPreRoll(live, deviceId, camStreamId);
-			return;
-		}
+		if (this.brokers.get(brokerId)) return;
 		const existingEnsure = this.brokerEnsures.get(brokerId);
 		if (existingEnsure) {
 			await existingEnsure;
@@ -19038,10 +18992,9 @@ var StreamBrokerManager = class StreamBrokerManager {
 		broker.setRestreamUrlResolver(() => this.rtspProvider.getEntry(brokerId)?.mutedUrl ?? null);
 		broker.setFfmpegBinaryPath(this.ffmpegConfig.binaryPath);
 		if (this.costRegistry !== null) broker.setCostRegistry(this.costRegistry);
-		this.applyPreBufferConfig(broker, deviceId, camStreamId);
+		this.applyPrebufferConfig(broker, deviceId, camStreamId);
 		this.applyAudioMuteConfig(broker, deviceId);
 		this.applyJoinBurstBound(broker, deviceId, camStreamId);
-		this.applyPreRoll(broker, deviceId, camStreamId);
 		this.applyClipRetention(deviceId);
 		if (this.deviceOverrides.get(deviceId)?.streamingDebug) broker.setStreamingDebug(true);
 		broker.setSourceProvider(() => {
@@ -19259,63 +19212,47 @@ var StreamBrokerManager = class StreamBrokerManager {
 		return this.brokers.get(brokerIdFor(deviceId, camStreamId))?.getStats().audio?.codec ?? null;
 	}
 	/**
-	* Whether a stream is warmed BY DEFAULT (no explicit override): the device's
-	* `high` profile, on a non-battery camera, from a source that is worth
-	* keeping hot. Single source of truth used by both the broker-config default
-	* (`applyPreBufferConfig`) and the settings-patch override synthesis
-	* (`defaultStreamPreBuffer`) so a seconds-only patch never silently disables
-	* the high-profile warm default.
+	* Whether a stream is warmed BY DEFAULT — the device's `high` profile.
 	*
-	* `pull-http` is excluded. The warm default is not free storage — it is
-	* PERMANENT SYNTHETIC DEMAND: `StreamBroker.hasDemand()` returns true on
-	* `_preBufferEnabled` alone, so a warm stream is dialed forever regardless
-	* of subscribers. For an MJPEG relay that means the ingest transcode
-	* (`HTTP_MJPEG_H264_OUTPUT_ARGS` → libx264) runs forever too. Measured on
-	* the live hub: the terminal addon's glances relay burned ~12% of a core
-	* and held its PTY open for hours with zero viewers. The trade the warm
-	* default buys elsewhere — a seeded GOP instead of a ~5-8 s cold start —
-	* does not apply here: an MJPEG relay is cheap to re-dial (no camera
-	* handshake) and expensive to keep hot. An explicit operator ON override
-	* still warms it; this is a DEFAULT, not a ban.
+	* ONE input to {@link resolvePrebuffer}, not a decision of its own. Battery
+	* and `pull-http` used to be tested here as well AND in
+	* `getEffectivePreBufferSec` AND in `resolveRecordingPreRollMs`: three
+	* statements of one rule, which is how they came to be able to disagree
+	* about a single camera. They are stated once now, in `prebuffer.ts`.
 	*/
 	isDefaultWarm(deviceId, camStreamId) {
-		if (!(findProfileForStream(this.assignments.get(deviceId)?.map ?? {}, camStreamId) === "high")) return false;
-		if (this.deviceHasFeature(deviceId, DeviceFeature.BatteryOperated)) return false;
-		return this.cameraStreams.get(deviceId)?.get(camStreamId)?.kind !== "pull-http";
+		return findProfileForStream(this.assignments.get(deviceId)?.map ?? {}, camStreamId) === "high";
 	}
 	/**
-	* Default `StreamPreBuffer` for a brand-new override entry — mirrors
-	* the effective broker default: `enabled` reflects the high-profile warm
-	* default (`isDefaultWarm`), so a seconds-only patch on a warm high stream
-	* inherits `enabled: true` instead of silently forcing it OFF. Operators
-	* still override explicitly per-stream via the device-settings sub-tabs;
-	* detection / recording paths pass `forceForDetection` to
-	* `getEffectivePreBufferSec` when they need a buffered window irrespective
-	* of the operator toggle.
-	*/
-	defaultStreamPreBuffer(deviceId, camStreamId) {
-		return {
-			enabled: this.isDefaultWarm(deviceId, camStreamId),
-			seconds: this.defaultPreBufferSec
-		};
+	* THE prebuffer for a (device, stream) — the one answer every caller uses.
+	*
+	* The settings screen reads it to display, the patch handler reads it to
+	* apply, and {@link applyPrebufferConfig} reads it to install. That is the
+	* D315-shaped half of this record: what the operator is SHOWN is resolved by
+	* the same function that decides what runs, so a switch can no longer report
+	* off on a function that is on — which is exactly what the settings
+	* contribution did while it answered `perStream?.enabled ?? false` and the
+	* broker's own flag shipped `true`.
+	*/
+	effectivePrebuffer(deviceId, camStreamId) {
+		return resolvePrebuffer({
+			camStreamId,
+			clusterSeconds: this.defaultPreBufferSec,
+			overrides: this.deviceOverrides.get(deviceId)?.preBuffer,
+			defaultWarm: this.isDefaultWarm(deviceId, camStreamId),
+			batteryOperated: this.deviceHasFeature(deviceId, DeviceFeature.BatteryOperated),
+			terminalRelay: this.cameraStreams.get(deviceId)?.get(camStreamId)?.kind === "pull-http"
+		});
 	}
 	/**
-	* Apply the effective pre-buffer config to a fresh broker instance.
-	* Default behaviour: the HIGH profile stream is warm (see below);
-	* every other stream stays OFF — idle until the operator opts in or
-	* a detection / recording subscriber attaches. An explicit per-stream
-	* operator override always wins over both defaults.
+	* Install the effective prebuffer on a broker. Idempotent — safe on every
+	* publish, every re-publish and every settings edit, which is what lets a
+	* camera discovered late (a battery flag that arrives after the first dial)
+	* converge instead of holding the wrong retention for the life of the
+	* process.
 	*/
-	applyPreBufferConfig(broker, deviceId, camStreamId) {
-		const perStream = this.deviceOverrides.get(deviceId)?.preBuffer?.[camStreamId];
-		if (perStream) {
-			broker.setPreBufferEnabled(perStream.enabled);
-			broker.setPreBufferDuration(perStream.enabled ? perStream.seconds : 0);
-			return;
-		}
-		const defaultWarm = this.isDefaultWarm(deviceId, camStreamId);
-		broker.setPreBufferEnabled(defaultWarm);
-		broker.setPreBufferDuration(defaultWarm ? this.defaultPreBufferSec : 0);
+	applyPrebufferConfig(broker, deviceId, camStreamId) {
+		broker.setPrebuffer(this.effectivePrebuffer(deviceId, camStreamId));
 	}
 	/** Push the persisted mute onto a broker. Idempotent — safe on every pass. */
 	applyAudioMuteConfig(broker, deviceId) {
@@ -29655,12 +29592,10 @@ var StreamBrokerAddon = class extends BaseAddon {
 	lastProbePersistAt = 0;
 	constructor() {
 		super({
-			defaultPreBufferSec: 10,
+			defaultPreBufferSec: 5,
 			rtspPort: 8554,
 			catalogReconcileIntervalSec: 30,
 			joinBurstMaxSpanMs: DEFAULT_PRIME_BURST_BOUND.maxSpanMs,
-			preRollMs: 0,
-			recordingPreRollMs: DEFAULT_RECORDING_PRE_ROLL_MS,
 			binaryPath: "",
 			hwaccel: "copy"
 		});
@@ -29730,8 +29665,6 @@ var StreamBrokerAddon = class extends BaseAddon {
 		this.brokerManager.setCostRegistry(this.costRegistry);
 		this.brokerManager.setDefaultPreBufferSec(this.config.defaultPreBufferSec);
 		this.brokerManager.setDefaultJoinBurstMaxSpanMs(this.config.joinBurstMaxSpanMs);
-		this.brokerManager.setDefaultPreRollMs(this.config.preRollMs);
-		this.brokerManager.setDefaultRecordingPreRollMs(this.config.recordingPreRollMs);
 		this.brokerManager.setEventBus(this.ctx.eventBus);
 		const localNode = this.ctx.kernel.localNodeId;
 		const localNodeId = localNode ? localNode.includes("/") ? localNode.split("/")[0] : localNode : void 0;
@@ -30253,11 +30186,11 @@ var StreamBrokerAddon = class extends BaseAddon {
 					type: "number",
 					key: "defaultPreBufferSec",
 					label: "Pre-buffer Duration",
-					description: "Seconds of video to keep buffered before a detection event",
-					min: 0,
-					max: 30,
+					description: "Seconds of history a warm stream keeps. This is the ONLY history setting in the system: an event recording and a detection decode are both served from it and neither configures a window of its own — each is handed this much or whatever the stream has actually been warm for, whichever is less. It costs memory on whichever node ingests the camera, roughly this many seconds of that stream’s bitrate. Turn the pre-buffer on or off per camera stream in the camera’s Streams settings.",
+					min: 1,
+					max: 15,
 					step: 1,
-					default: 10,
+					default: 5,
 					unit: "s"
 				},
 				{
@@ -30302,28 +30235,6 @@ var StreamBrokerAddon = class extends BaseAddon {
 					default: DEFAULT_PRIME_BURST_BOUND.maxSpanMs,
 					unit: "ms"
 				},
-				{
-					type: "number",
-					key: "preRollMs",
-					label: "Detection pre-roll",
-					description: "Cluster-wide default for how much video from BEFORE the motion edge a detection decode is handed when it attaches, so the first analysed frames predate the trigger. Off (0) by default: it retains extra video in memory on whichever node ingests the camera, and it can only reach as far back as that stream has been warm — it never dials a camera on its own. Only the detection decode receives it; viewers, recordings and HomeKit legs keep the ordinary join burst. Terminal (MJPEG relay) cameras ignore this default. Override per camera stream.",
-					min: 0,
-					max: PRE_ROLL_MAX_MS,
-					step: 250,
-					default: 0,
-					unit: "ms"
-				},
-				{
-					type: "number",
-					key: "recordingPreRollMs",
-					label: "Recording pre-roll",
-					description: "Cluster-wide default for how much video from BEFORE the trigger an event recording begins with. The recorder’s ffmpeg is spawned AT the trigger, so without this its first frame is at best the live edge — measured on one camera, the footage started after the motion in 60 % of episodes. It spends retained video in memory on whichever node ingests the camera and can only reach as far back as that stream has been warm; it never dials a camera on its own. Battery cameras and terminal (MJPEG relay) cameras take 0. Set 0 to turn it off.",
-					min: 0,
-					max: RECORDING_PRE_ROLL_MAX_MS,
-					step: 500,
-					default: DEFAULT_RECORDING_PRE_ROLL_MS,
-					unit: "ms"
-				},
 				{
 					type: "number",
 					key: "catalogReconcileIntervalSec",