@camstack/addon-pipeline 1.2.42 → 1.2.44

package/dist/{dist-COK_1Ot8.mjs → dist-DOu93i_g.mjs}

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 //#region ../types/dist/event-category-41fKf-q9.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
@@ -6589,9 +6590,38 @@ var CAP_NODE_PIN_CONTEXT_KEY = "__camstackNodePin";
 /**
 * Build the tRPC request options that pin a single capability call to `nodeId`.
 * Pass as the second argument to `.query(input, …)` / `.mutate(input, …)`.
+*
+* ## The id is normalised here, and it has to be
+*
+* A forked addon reads its own node from `ctx.kernel.localNodeId`, and inside a
+* worker that value is a RUNNER id — `hub/export-hap`, not `hub`. Routing
+* compares a pin against real node ids, so such a pin matches nothing and the
+* call fails with `no provider registered for cap "…"`. The local-first
+* resolver already guarded against this (`localNodeId.split('/')[0]`), which
+* made the hazard invisible: unpinned calls worked, and only an explicit pin —
+* the thing you reach for when you specifically need THIS node — silently
+* addressed a node that does not exist.
+*
+* Cost of it being missing: `addon-export-hap` pinned `decoder.getInfo` to its
+* own node to read the host's hardware-decode backend. It never once answered,
+* so every HomeKit egress transcode decoded in SOFTWARE — including 4K H.265 —
+* while D67's whole premise was that the decoder addon is the authority on
+* hardware. The warn said `decoding in SOFTWARE` and read as "this node has no
+* hardware", which was false.
+*
+* Normalising in the ONE constructor fixes every caller at once, which is why
+* it is here and not at the call sites.
 */
 function nodePin(nodeId) {
-	return { context: { [CAP_NODE_PIN_CONTEXT_KEY]: nodeId } };
+	return { context: { [CAP_NODE_PIN_CONTEXT_KEY]: toNodeId(nodeId) } };
+}
+/**
+* A runner id is `<nodeId>/<addonId>`; a node id has no slash. Taking the head
+* is idempotent, so passing an already-clean id costs nothing.
+*/
+function toNodeId(idOrRunnerId) {
+	const head = idOrRunnerId.split("/")[0];
+	return head === void 0 || head.length === 0 ? idOrRunnerId : head;
 }
 /**
 * Output schema shared by the contribution + live methods.
@@ -7090,6 +7120,39 @@ function sleep(ms) {
 	return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
 }
 //#endregion
+//#region ../types/dist/canonical-hash-7nfBbEqR.mjs
+/**
+* Deterministic SHA-256 hash of an arbitrary serialisable value. The
+* canonical form sorts object keys alphabetically at every depth so two
+* structurally-equal inputs with different key insertion orders produce
+* the same hash. Returns a 64-char lowercase hex digest.
+*
+* Used by export adapters (Alexa, HAP) to short-circuit re-discovery /
+* accessory-rebuild work when the upstream shape is byte-identical to
+* the last applied state — preventing user-visible "re-discovery"
+* notifications on every addon-runner respawn. Each respawn re-fires
+* `DeviceBindingsChanged` for every cap registration, which without
+* this guard would propagate redundant pushes.
+*
+* Note: this is a SYMPTOMATIC fix layered on top of the binding-change
+* subscription. The proper fix is a single "device ready" lifecycle
+* barrier so exports react only when the full cap set has landed —
+* tracked separately for post-HA-integration work.
+*/
+function canonicalHash(value) {
+	const canonical = JSON.stringify(value, replaceWithSortedKeys);
+	return createHash("sha256").update(canonical ?? "").digest("hex");
+}
+function replaceWithSortedKeys(_key, value) {
+	if (value && typeof value === "object" && !Array.isArray(value)) {
+		const obj = value;
+		const out = {};
+		for (const k of Object.keys(obj).toSorted()) out[k] = obj[k];
+		return out;
+	}
+	return value;
+}
+//#endregion
 //#region ../types/dist/err-msg-IQTHeDzc.mjs
 /**
 import { errMsg } from '@camstack/types'
@@ -7113,6 +7176,14 @@ var EncodeProfileSchema = object({
 			"main",
 			"high"
 		]).optional(),
+		/**
+		* `-level`, e.g. `'3.1'`. A consumer that ADVERTISES a level in its SDP
+		* (`profile-level-id=42e01f` is Baseline 3.1) must constrain the encoder to
+		* it, or it ships a stream that does not match its own advertisement — the
+		* defect class that kept HomeKit black for a year and that Alexa carried
+		* silently. Optional because a browser negotiates the level itself.
+		*/
+		level: string().optional(),
 		width: number().int().positive().optional(),
 		height: number().int().positive().optional(),
 		fps: number().positive().optional(),
@@ -7159,6 +7230,557 @@ var EncodeProfileSchema = object({
 	*/
 	outputArgs: array(string()).optional()
 });
+var AUDIO_ENCODER_BY_CODEC = {
+	opus: "libopus",
+	aac: "aac",
+	pcmu: "pcm_mulaw",
+	pcma: "pcm_alaw"
+};
+/**
+* Camera-microphone audio, per codec. Lives HERE rather than in
+* `encode-defaults.ts` only to avoid an import cycle (`encode-defaults` depends
+* on these types); it is re-exported from there, which is where to read it.
+*
+* Every source in this repo is a mono camera mic. The former broker preset
+* encoded Opus at `channels: 2`, spending bitrate duplicating one channel —
+* that is the value this consolidation changed.
+*/
+var AUDIO_PRESETS = {
+	aac: {
+		kind: "encode",
+		codec: "aac",
+		bitrateKbps: 128,
+		sampleRateHz: 48e3,
+		channels: 1
+	},
+	opus: {
+		kind: "encode",
+		codec: "opus",
+		bitrateKbps: 64,
+		sampleRateHz: 48e3,
+		channels: 1
+	},
+	pcmu: {
+		kind: "encode",
+		codec: "pcmu",
+		sampleRateHz: 8e3,
+		channels: 1
+	}
+};
+/** `-hide_banner -loglevel <level>` — every ffmpeg site opens with this. */
+function logBannerArgs(level) {
+	return [
+		"-hide_banner",
+		"-loglevel",
+		level
+	];
+}
+/** `true` when the resolved value means "decode in software" (⇒ no `-hwaccel`). */
+function isSoftwareDecode(decodeHwAccel) {
+	return !decodeHwAccel || decodeHwAccel === "none" || decodeHwAccel === "copy";
+}
+/**
+* Every INPUT option, in order, terminated by `-i <url>`. Nothing may be
+* appended to this list by a caller — that is the whole point of the function.
+*/
+function buildInputArgs(input, decodeHwAccel) {
+	const args = [];
+	if (!isSoftwareDecode(decodeHwAccel)) args.push("-hwaccel", String(decodeHwAccel));
+	if (input.extraArgs?.length) args.push(...input.extraArgs);
+	if (input.analyzeDurationUs !== void 0) args.push("-analyzeduration", String(input.analyzeDurationUs));
+	if (input.probeSizeBytes !== void 0) args.push("-probesize", String(input.probeSizeBytes));
+	if (input.fflags?.length) for (const flag of input.fflags) args.push("-fflags", flag);
+	if (input.rtspTransport) args.push("-rtsp_transport", input.rtspTransport);
+	args.push("-i", input.url);
+	return args;
+}
+/** The `-vf` filter args, or `[]` when a consumer `-vf` already claims the slot. */
+function buildVideoFilterArgs(scale, outputArgs) {
+	if (!scale) return [];
+	if (outputArgs.some((a) => a === "-vf")) return [];
+	if (scale.mode === "exact") return ["-vf", `scale=${scale.width}:${scale.height}`];
+	return ["-vf", `scale='min(${scale.width},iw)':'min(${scale.height},ih)':force_original_aspect_ratio=decrease:force_divisible_by=2`];
+}
+/** Rate-control args for an encode plan. */
+function buildRateControlArgs(video) {
+	const kbps = video.bitrateKbps;
+	if (kbps === void 0) return [];
+	const rc = video.rateControl ?? {
+		kind: "cap",
+		vbvSeconds: 2
+	};
+	const bufsize = Math.max(1, Math.round(kbps * rc.vbvSeconds));
+	return [
+		...rc.kind === "cbr" ? ["-b:v", `${kbps}k`] : [],
+		"-maxrate",
+		`${kbps}k`,
+		"-bufsize",
+		`${bufsize}k`
+	];
+}
+/** The whole video block (`-vf` … `-c:v` … knobs), after `-i`. */
+function buildVideoArgs(video, outputArgs) {
+	if (video.kind === "copy") return [
+		"-c:v",
+		"copy",
+		...video.bitstreamFilter ? ["-bsf:v", video.bitstreamFilter] : []
+	];
+	const args = [
+		...buildVideoFilterArgs(video.scale, outputArgs),
+		"-c:v",
+		video.encoder
+	];
+	if (video.preset !== void 0) args.push("-preset", video.preset);
+	if (video.tune !== void 0) args.push("-tune", video.tune);
+	if (video.profile !== void 0) args.push("-profile:v", video.profile);
+	if (video.level !== void 0) args.push("-level", video.level);
+	if (video.pixelFormat !== void 0) args.push("-pix_fmt", video.pixelFormat);
+	if (video.fps !== void 0) args.push("-r", String(video.fps));
+	if (video.gopFrames !== void 0) args.push("-g", String(video.gopFrames));
+	if (video.forceKeyFramesSeconds !== void 0) args.push("-force_key_frames", `expr:gte(t,n_forced*${video.forceKeyFramesSeconds})`);
+	if (video.bf !== void 0) args.push("-bf", String(video.bf));
+	args.push(...buildRateControlArgs(video));
+	if (video.bitstreamFilter !== void 0) args.push("-bsf:v", video.bitstreamFilter);
+	return args;
+}
+/** The whole audio block, after `-i`. */
+function buildAudioArgs(audio) {
+	if (audio.kind === "none") return ["-an"];
+	if (audio.kind === "copy") return ["-c:a", "copy"];
+	const args = [];
+	if (audio.filter !== void 0) args.push("-af", audio.filter);
+	args.push("-c:a", AUDIO_ENCODER_BY_CODEC[audio.codec]);
+	if (audio.application !== void 0) args.push("-application", audio.application);
+	if (audio.frameDurationMs !== void 0) args.push("-frame_duration", String(audio.frameDurationMs));
+	if (audio.globalHeader === true) args.push("-flags", "+global_header");
+	if (audio.sampleRateHz !== void 0) args.push("-ar", String(audio.sampleRateHz));
+	if (audio.bitrateKbps !== void 0) args.push("-b:a", `${audio.bitrateKbps}k`);
+	if (audio.vbvBufferKbits !== void 0) args.push("-bufsize", `${audio.vbvBufferKbits}k`);
+	if (audio.channels !== void 0) args.push("-ac", String(audio.channels));
+	return args;
+}
+/** RTP output-leg args (`-payload_type`, `-ssrc`, `-sdp_file`, `-f rtp <url>`). */
+function buildRtpOutputArgs(out) {
+	const args = [];
+	if (out.payloadType !== void 0) args.push("-payload_type", String(out.payloadType));
+	if (out.ssrc !== void 0) args.push("-ssrc", String(out.ssrc));
+	if (out.sdpFile !== void 0) args.push("-sdp_file", out.sdpFile);
+	args.push("-f", "rtp", out.url);
+	return args;
+}
+/** `true` when the sink is a raw elementary bytestream that cannot mux audio. */
+function isElementaryVideoSink(sink) {
+	return sink.kind === "stdout" && (sink.container === "h264" || sink.container === "hevc");
+}
+/**
+* The fragmented-MP4 muxer flags, in the order the recorder has proven them
+* (`recorder/addon/ffmpeg-args.ts` passes the same `movflags` string through
+* `-segment_format_options`, across every vendor in the fleet):
+*
+* - `frag_keyframe` — cut a fragment at each key frame, so every fragment
+*   opens on a sync sample. HKSV's whole requirement.
+* - `empty_moov` — write `ftyp`+`moov` up front with no samples in it, which
+*   is what makes the head a standalone INITIALISATION segment.
+* - `default_base_moof` — fragment offsets are self-relative, so a fragment is
+*   demuxable without the bytes that preceded it. D31's byte-range read path
+*   depends on exactly this property of the recorder's segments.
+*/
+var FMP4_MOVFLAGS = "+frag_keyframe+empty_moov+default_base_moof";
+/**
+* The terminal sink args for every non-`rtp-outputs` sink. Exhaustive over the
+* union so a new member cannot fall through to `['-f', container, 'pipe:1']`,
+* which is what a plain `container` read would have done for `mp4` — a valid
+* argv that writes a NON-fragmented, unseekable-to-a-pipe MP4 and produces one
+* unusable byte stream.
+*/
+function buildStdoutOrRtspSinkArgs(sink) {
+	if (sink.kind === "rtsp-listen") return [
+		"-f",
+		"rtsp",
+		"-rtsp_transport",
+		"tcp",
+		"-rtsp_flags",
+		"listen",
+		sink.url
+	];
+	if (sink.kind === "rtp-outputs") return [];
+	return sink.container === "mp4" ? buildFmp4SinkArgs(sink) : [
+		"-f",
+		sink.container,
+		"pipe:1"
+	];
+}
+/** `-movflags … -min_frag_duration <us> -f mp4 pipe:1`. */
+function buildFmp4SinkArgs(sink) {
+	return [
+		"-movflags",
+		FMP4_MOVFLAGS,
+		"-min_frag_duration",
+		String(Math.max(0, Math.round(sink.fragmentMs * 1e3))),
+		"-f",
+		"mp4",
+		"pipe:1"
+	];
+}
+/**
+* A second output mapping source audio to RTP-over-UDP. `0:a:0?` makes the
+* audio optional so a source with no audio skips it instead of failing the
+* whole invocation.
+*/
+function buildAudioSidecarArgs(sidecar) {
+	return [
+		"-map",
+		"0:a:0?",
+		...buildAudioArgs(sidecar.codec === "pcma" ? {
+			kind: "encode",
+			codec: "pcma",
+			sampleRateHz: 8e3,
+			channels: 1
+		} : AUDIO_PRESETS[sidecar.codec]),
+		...buildRtpOutputArgs({
+			url: sidecar.rtpUrl,
+			sdpFile: sidecar.sdpFile
+		})
+	];
+}
+/**
+* Assemble the full ffmpeg argument list. Layout:
+*
+*   -hide_banner -loglevel <level>
+*   [-hwaccel <backend|auto>]        ─┐ INPUT options — strictly before -i.
+*   [<input.extraArgs>]               │
+*   [-fflags <flag>…]                 │
+*   [-rtsp_transport tcp]             │
+*   -i <url>                         ─┘
+*   <video block>  <threads>  <audio block>   ─┐ OUTPUT options.
+*   <consumer outputArgs verbatim>             │
+*   <sink>                                    ─┘ terminal
+*/
+function buildFfmpegArgs(inv) {
+	const head = [...logBannerArgs(inv.logLevel), ...buildInputArgs(inv.input, inv.decodeHwAccel)];
+	const threadArgs = inv.threadCount > 0 ? ["-threads", String(inv.threadCount)] : [];
+	if (inv.sink.kind === "rtp-outputs") {
+		const videoLeg = inv.sink.video ? [
+			"-an",
+			"-map",
+			"0:v:0",
+			...buildVideoArgs(inv.video, inv.outputArgs),
+			...threadArgs,
+			...inv.outputArgs,
+			...buildRtpOutputArgs(inv.sink.video)
+		] : [];
+		const audioLeg = inv.sink.audio ? [
+			"-vn",
+			"-map",
+			"0:a:0?",
+			...buildAudioArgs(inv.audio),
+			...buildRtpOutputArgs(inv.sink.audio)
+		] : [];
+		return [
+			...head,
+			...videoLeg,
+			...audioLeg
+		];
+	}
+	const audioArgs = isElementaryVideoSink(inv.sink) ? ["-an"] : buildAudioArgs(inv.audio);
+	const sinkArgs = buildStdoutOrRtspSinkArgs(inv.sink);
+	return [
+		...head,
+		...buildVideoArgs(inv.video, inv.outputArgs),
+		...threadArgs,
+		...audioArgs,
+		...inv.outputArgs,
+		...sinkArgs,
+		...inv.audioSidecar ? buildAudioSidecarArgs(inv.audioSidecar) : []
+	];
+}
+/**
+* Hardware ENCODER ids per decode-hwaccel backend — a static, deterministic
+* map (the same shape the reference NVR uses: platform → encoder, no probe).
+*/
+var ENCODER_IDS_BY_BACKEND = {
+	videotoolbox: {
+		h264: "h264_videotoolbox",
+		h265: "hevc_videotoolbox"
+	},
+	vaapi: {
+		h264: "h264_vaapi",
+		h265: "hevc_vaapi"
+	},
+	qsv: {
+		h264: "h264_qsv",
+		h265: "hevc_qsv"
+	},
+	cuda: {
+		h264: "h264_nvenc",
+		h265: "hevc_nvenc"
+	},
+	nvdec: {
+		h264: "h264_nvenc",
+		h265: "hevc_nvenc"
+	},
+	amf: {
+		h264: "h264_amf",
+		h265: "hevc_amf"
+	}
+};
+/**
+* The hardware encoder for a target codec on `backend`, or the software one.
+* `'auto'` is NOT a backend identity (it is an instruction to ffmpeg), so it
+* maps to software encoding.
+*/
+function pickVideoEncoder(target, backend, useHardware) {
+	const software = target === "h264" ? "libx264" : "libx265";
+	if (!useHardware || backend === null || isSoftwareDecode(backend) || backend === "auto") return software;
+	const ids = ENCODER_IDS_BY_BACKEND[backend.toLowerCase()];
+	if (!ids) return software;
+	return target === "h264" ? ids.h264 : ids.h265;
+}
+/** Map an `EncodeProfile.audio` to an audio plan. */
+function audioPlanFromEncodeProfile(audio) {
+	if (audio === "passthrough") return { kind: "none" };
+	if (audio.codec === "copy") return { kind: "copy" };
+	return {
+		kind: "encode",
+		codec: audio.codec,
+		...audio.bitrateKbps !== void 0 ? { bitrateKbps: audio.bitrateKbps } : {},
+		...audio.sampleRateHz !== void 0 ? { sampleRateHz: audio.sampleRateHz } : {},
+		...audio.channels !== void 0 ? { channels: audio.channels } : {}
+	};
+}
+/**
+* Adapt an `EncodeProfile` (the operator/consumer-facing shape) into an
+* {@link FfmpegInvocation}. This is the ONLY bridge between the two models —
+* a second one is how the repo grew two argv builders that disagreed about
+* hardware.
+*
+* Smart video copy: when the source already speaks the requested codec the
+* encode block is elided entirely and ffmpeg runs as a re-muxer on the video
+* plane. Width / height / fps / bitrate in the profile are a downstream BUDGET,
+* not a forced rescale.
+*/
+function invocationFromEncodeProfile(input) {
+	const v = input.profile.video;
+	const shouldCopy = v.codec === "copy" || input.forceReencode !== true && v.codec === input.sourceCodec;
+	const scale = v.width !== void 0 && v.height !== void 0 ? {
+		mode: "fit",
+		width: v.width,
+		height: v.height
+	} : null;
+	const target = v.codec === "h265" ? "h265" : "h264";
+	const video = shouldCopy ? {
+		kind: "copy",
+		...input.bitstreamFilter !== void 0 ? { bitstreamFilter: input.bitstreamFilter } : {}
+	} : {
+		kind: "encode",
+		encoder: pickVideoEncoder(target, input.decodeHwAccel, input.hardwareEncoders === true),
+		scale,
+		...v.preset !== void 0 ? { preset: v.preset } : {},
+		...v.tune !== void 0 ? { tune: v.tune } : {},
+		...v.profile !== void 0 ? { profile: v.profile } : {},
+		...v.level !== void 0 ? { level: v.level } : {},
+		...input.pixelFormat !== void 0 ? { pixelFormat: input.pixelFormat } : {},
+		...v.fps !== void 0 ? { fps: v.fps } : {},
+		...v.gopFrames !== void 0 ? { gopFrames: v.gopFrames } : {},
+		...input.forceKeyFramesSeconds !== void 0 ? { forceKeyFramesSeconds: input.forceKeyFramesSeconds } : {},
+		...v.bf !== void 0 ? { bf: v.bf } : {},
+		...v.bitrateKbps !== void 0 ? { bitrateKbps: v.bitrateKbps } : {},
+		...input.rateControl !== void 0 ? { rateControl: input.rateControl } : {},
+		...input.bitstreamFilter !== void 0 ? { bitstreamFilter: input.bitstreamFilter } : {}
+	};
+	return {
+		logLevel: input.logLevel ?? "error",
+		decodeHwAccel: input.decodeHwAccel,
+		input: {
+			url: input.sourceUrl,
+			rtspTransport: "tcp",
+			fflags: ["+discardcorrupt"],
+			...input.profile.inputArgs?.length ? { extraArgs: input.profile.inputArgs } : {}
+		},
+		video,
+		audio: audioPlanFromEncodeProfile(input.profile.audio),
+		threadCount: input.threadCount ?? 0,
+		outputArgs: input.profile.outputArgs ?? [],
+		sink: input.sink,
+		...input.audioSidecar !== void 0 ? { audioSidecar: input.audioSidecar } : {}
+	};
+}
+/**
+* The shape every live egress starts from: H.264 Baseline 3.1 at 720p25.
+* Baseline because it is the one profile every consumer in this repo decodes
+* (Echo, iOS, an old browser); 3.1 because that is what the SDPs advertise.
+*/
+var BASE_LIVE_EGRESS_PROFILE = {
+	video: {
+		codec: "h264",
+		profile: "baseline",
+		level: "3.1",
+		width: 1280,
+		height: 720,
+		fps: 25,
+		bitrateKbps: 2500,
+		gopFrames: 25,
+		bf: 0,
+		preset: "veryfast",
+		tune: "zerolatency"
+	},
+	audio: "passthrough"
+};
+({ ...BASE_LIVE_EGRESS_PROFILE }), { ...BASE_LIVE_EGRESS_PROFILE.video };
+({ ...BASE_LIVE_EGRESS_PROFILE });
+/** VBV window for a consumer whose budget is enforced per second (HomeKit). */
+var RATE_CONTROL_TIGHT = {
+	kind: "cbr",
+	vbvSeconds: 1
+};
+/** VBV window for a consumer that tolerates a keyframe spike (browser, Echo). */
+var RATE_CONTROL_RELAXED = {
+	kind: "cap",
+	vbvSeconds: 2
+};
+function createHwAccelCache(options) {
+	const now = options.now ?? (() => Date.now());
+	let value = null;
+	let writtenAt = Number.NEGATIVE_INFINITY;
+	return {
+		read() {
+			return now() - writtenAt < options.ttlMs ? value : void 0;
+		},
+		write(next) {
+			value = next;
+			writtenAt = now();
+		}
+	};
+}
+/** `true` when a value means "decode in software". */
+function meansSoftware(value) {
+	return !value || value === "none" || value === "copy";
+}
+/**
+* Resolve the `-hwaccel` value for an egress transcode. Hardware is the
+* DEFAULT — an egress that decodes in software on a hub with working vaapi is
+* paying for nothing — and every software outcome is announced.
+*
+* Returns a concrete backend name, the literal `'auto'`, or `null` for
+* software decode (⇒ {@link buildFfmpegArgs} emits no `-hwaccel` at all).
+*/
+async function resolveEgressDecodeHwAccel(deps) {
+	const override = deps.override;
+	if (override !== void 0 && override !== null && override !== "") return meansSoftware(override) ? null : override;
+	const cached = deps.cache?.read();
+	if (cached !== void 0) return cached;
+	let backend;
+	try {
+		backend = await deps.readDecoderBackend();
+	} catch (err) {
+		const kernelPreferred = await deps.readKernelPreferred().catch(() => []);
+		deps.onFallback({
+			reason: "decoder-unreadable",
+			kernelPreferred,
+			error: err instanceof Error ? err.message : String(err)
+		});
+		deps.cache?.write(null);
+		return null;
+	}
+	if (backend === "") {
+		const kernelPreferred = await deps.readKernelPreferred().catch(() => []);
+		deps.onFallback({
+			reason: "decoder-unprobed",
+			kernelPreferred
+		});
+		deps.cache?.write(null);
+		return null;
+	}
+	const resolved = meansSoftware(backend) ? null : backend;
+	deps.cache?.write(resolved);
+	return resolved;
+}
+/**
+* The sharing key for `streamBroker.acquireEgressTranscode`.
+*
+* **Two requesters asking for exactly the same argument set reach the same
+* process.** Exact match, never fuzzy: a quantised ladder that merged
+* NEARLY-identical requests would make the stream a consumer receives depend
+* on who else is watching and in what order they arrived — unpredictable in
+* precisely the way a debugging session cannot tolerate. Same arguments ⇒ same
+* process. Different arguments ⇒ different process, and that is fine; the
+* operator accepted the cost ("it's fine to have several processes").
+*
+* Derived from the STRUCTURED plan, not from a flag array. `pipelineKeyFor`
+* (`transcode-pipeline.ts`) folds `getStreamWithCodec`'s raw `outputArgs` into
+* its key, so that method's extensibility hatch and its sharing key are the
+* same field — a consumer needing one extra flag silently forks the child, and
+* two consumers that want the same thing but spell it differently never share.
+* Here every knob is a named field, and defaults are APPLIED before hashing so
+* an omitted field and its explicit default land on the same key.
+*/
+/**
+* The transport a CAP request describes. `fragments` is deliberately
+* unreachable from here — the request schema has no way to ask for it, so the
+* cap path can never be handed a fragment child by accident.
+*/
+function egressTransportFromRequest(request) {
+	return { transport: request.publishLocally === true ? "push" : "dial" };
+}
+/** Absent optional ⇒ this sentinel, so `undefined` and "not set" agree. */
+var UNSET = "\0unset";
+function canonicalVideo(video) {
+	return {
+		codec: video.codec,
+		profile: video.profile ?? UNSET,
+		level: video.level ?? UNSET,
+		width: video.width ?? -1,
+		height: video.height ?? -1,
+		fps: video.fps ?? -1,
+		bitrateKbps: video.bitrateKbps ?? -1,
+		gopFrames: video.gopFrames ?? -1,
+		bf: video.bf ?? -1,
+		preset: video.preset ?? UNSET,
+		tune: video.tune ?? UNSET
+	};
+}
+function canonicalAudio(audio) {
+	if (audio === "passthrough") return { codec: "passthrough" };
+	return {
+		codec: audio.codec,
+		bitrateKbps: audio.bitrateKbps ?? -1,
+		sampleRateHz: audio.sampleRateHz ?? -1,
+		channels: audio.channels ?? -1
+	};
+}
+/**
+* The normalised plan a key is computed from. Exported so a test — and a
+* future operator-facing "why are these two not sharing?" surface — can diff
+* two requests without reversing a hash.
+*/
+function canonicalEgressPlan(request, delivery = egressTransportFromRequest(request)) {
+	return {
+		deviceId: request.deviceId,
+		source: request.source.kind === "profile" ? `profile:${request.source.profile}` : `cam-stream:${request.source.camStreamId}`,
+		transport: delivery.transport,
+		fragmentMs: delivery.fragmentMs ?? -1,
+		video: canonicalVideo(request.encode.video),
+		audio: canonicalAudio(request.encode.audio),
+		rateControl: request.rateControl ?? "relaxed",
+		bitstreamFilter: request.bitstreamFilter ?? UNSET,
+		pixelFormat: request.pixelFormat ?? UNSET,
+		decodeHwAccel: request.decodeHwAccel ?? UNSET
+	};
+}
+/**
+* The refcount / dedup key. `canonicalHash` sorts object keys at every depth,
+* so a request built with a different field order produces the same digest.
+*
+* The handle this keys is IMMUTABLE: there is no `reconfigure`. A consumer
+* whose requirements change RELEASES and re-acquires; the refcount does the
+* rest. That is what stops co-tenants disturbing each other — the co-tenant
+* hazard that made Alexa's shared `derived:alexa-<id>` stream a hazard was
+* exactly a mutable shared object, where one consumer's downgrade dragged
+* every other consumer to 360p.
+*/
+function egressTranscodeSharingKey(request, delivery = egressTransportFromRequest(request)) {
+	return `egress:${canonicalHash(canonicalEgressPlan(request, delivery))}`;
+}
 /**
 * Deep wiring healthcheck — snapshot of active reachability probes across
 * every declared capability + widget of every installed plugin, on every
@@ -7209,6 +7831,154 @@ object({
 	})
 });
 /**
+* Per-camera FUNCTION SWITCHES — the one coherent on/off surface over the
+* pipeline functions an operator thinks in terms of.
+*
+* ## This file adds no state
+*
+* Every switch here is a VIEW onto an authority that already existed
+* ([D62](../../../../docs/decisions/adr-0062.md)). The whole point of the
+* group is that there is exactly one place each function is turned off, and
+* the group routes to it:
+*
+* | Switch | Authority | Proven "off stops the work" gate |
+* | --- | --- | --- |
+* | `stream-broker` | `deviceManager.setDisabled` | `StreamBrokerManager.reconcileAllCatalogs` releases the brokers; `ensureBroker` refuses re-creation |
+* | `object-detection` | `deviceManager.setWrapperActive('detection-pipeline')` | `PipelineSettingsStore.resolvePipelineForDevice` returns `{ steps: [], audio: null }` |
+* | `audio-analysis` | `deviceManager.setWrapperActive('audio-analysis')` | `AudioSubscriptionController.subscribeAudioStream` returns `null` before opening the stream |
+* | `recording` | `recording.setDeviceConfig` → `RecordingConfig.enabled` | `band-decision.shouldRecord` returns false; the controller detaches the device |
+* | `notifications` | `notificationRules.setDeviceMuted` | `NotificationCenter.evaluateAndEnqueue` returns before any rule is evaluated |
+* | `privacy-mask` | `privacyMask.setMask({ enabled })` → the CAMERA | the camera blanks the masked regions itself; every stream and recording carries the black boxes |
+* | `device-audio` | `privacyMask.setAudioEnabled` → the CAMERA | the camera stops encoding an audio track at all; every consumer sees silent video |
+*
+* ## The two switches whose authority is not on this server
+*
+* `privacy-mask` and `device-audio` write the CAMERA. That is not a loophole
+* in "the group stores nothing" — it is the purest form of it: the camera
+* holds the fact, every read is a read-through, and there is no server-side
+* copy that could drift. Their availability therefore cannot come from
+* `listBindableCapsForDeviceType` (a device-NATIVE cap carries no wrappers and
+* is filtered out there); it comes from the cap's own camera-probed
+* `privacyMask.getOptions()`, which is strictly more honest — it answers for
+* THIS camera rather than for the device type
+* ([D74](../../../../docs/decisions/adr-0074.md)).
+*
+* ## `privacy-mask` is the one row whose ON is not "the function is working"
+*
+* Every other switch means *this camera's function is doing its job*, so
+* `enabled: false` is a thing an operator took away. `privacy-mask` means **the
+* MASK is active** — `enabled: true` is video deliberately obscured. The
+* polarity is not a choice made here: `addon-export-hap`'s privacy `Switch`
+* (`builders/privacy-switch.ts`) already mirrors `patch.enabled` verbatim, and
+* a HomeKit toggle that disagreed with the app's toggle for the same camera is
+* worse than either surface not having one.
+*
+* Two consequences follow and both are load-bearing:
+*
+* - **It never counts as `switchedOff`.** `countsAsSwitchedOff` is `false` for
+*   exactly this row. With the polarity above, every camera that has NOT drawn
+*   a privacy mask would otherwise report `switchedOff: ['privacy-mask']` — the
+*   normal, healthy state of most cameras rendered as an operator disablement.
+* - **Its cost line names BOTH directions.** `costWhenOff` is rendered
+*   unconditionally by both clients, so for this row it has to read correctly
+*   whichever way the switch is sitting.
+*
+* The wrapper-binding pair is not a new idea: `legacy-migrations.ts` already
+* migrated the legacy `audioEnabled` / `pipelineEnabled` /
+* `motionDetectionEnabled` booleans ONTO `setWrapperActive`. The group is the
+* surface that decision never got.
+*
+* ## Two rules that are load-bearing
+*
+* - **Recording's switch is `enabled`, never the bands.** `bands` is the only
+*   authored intent and `mode` is derived from it (`deriveRecordingMode`).
+*   Expressing "off" by clearing bands destroys the operator's schedule and
+*   turning the camera back on would then silently record nothing.
+* - **A switch that is off must be reported as off**, not merely produce
+*   nothing. {@link CameraSwitch.enabled} is what a status surface renders as
+*   "disabled by an operator" instead of "broken" — see
+*   `CameraStatus.switchedOff`.
+*/
+/**
+* The functions the operator named — five on 2026-08-05, plus the camera's own
+* microphone on 2026-08-07. Deliberately NOT one id per pipeline step: face
+* recognition and plate/LPR are per-step toggles on
+* `pipelineOrchestrator.setCameraStepToggle` and belong in the pipeline
+* editor, not in a safety group.
+*/
+var CameraSwitchIdSchema = _enum([
+	"stream-broker",
+	"object-detection",
+	"privacy-mask",
+	"device-audio",
+	"audio-analysis",
+	"recording",
+	"notifications"
+]);
+/**
+* WHERE the switch's state actually lives. A discriminated union rather than a
+* string so both the writer (the orchestrator's `setCameraSwitch`) and any
+* reader can exhaustively narrow — and so "the group added a parallel map" is
+* a compile error rather than a review comment.
+*/
+var CameraSwitchAuthoritySchema = discriminatedUnion("kind", [
+	object({ kind: literal("device-disabled") }),
+	object({
+		kind: literal("wrapper-binding"),
+		capName: string()
+	}),
+	object({ kind: literal("recording-config") }),
+	object({ kind: literal("notification-mute") }),
+	object({
+		kind: literal("camera-audio"),
+		capName: string()
+	}),
+	object({
+		kind: literal("camera-mask"),
+		capName: string()
+	})
+]);
+/**
+* Why a switch is not offered for this camera. Rendered instead of the
+* control, never as a dead control — an absent function and a broken one must
+* not look the same.
+*/
+var CameraSwitchUnavailableReasonSchema = _enum([
+	"no-provider",
+	"source-unreachable",
+	"not-configured"
+]);
+/**
+* One switch, resolved for one camera.
+*
+* `label` and `costWhenOff` travel ON THE WIRE rather than being looked up
+* client-side: the viewer is a separate repository that does not import
+* `@camstack/types`, and a cost line duplicated in two clients is a cost line
+* that will disagree with itself. Five rows per camera is nothing.
+*/
+var CameraSwitchSchema = object({
+	id: CameraSwitchIdSchema,
+	label: string(),
+	/**
+	* What the operator LOSES while this is off, in one sentence. Required, not
+	* optional: a switch that cannot say what it costs should not ship.
+	*/
+	costWhenOff: string(),
+	/** False = do not render a control. `unavailableReason` says why. */
+	available: boolean(),
+	unavailableReason: CameraSwitchUnavailableReasonSchema.optional(),
+	/** Current state. Meaningless when `available` is false — read it as `true`. */
+	enabled: boolean(),
+	authority: CameraSwitchAuthoritySchema
+});
+/** The whole group for one camera. */
+var CameraSwitchGroupSchema = object({
+	deviceId: number().int(),
+	switches: array(CameraSwitchSchema).readonly(),
+	/** Unix ms when the group was composed server-side. */
+	fetchedAt: number()
+});
+/**
 * Ops-log — the durable, append-only operations audit shared by the
 * recordings and events management surfaces.
 *
@@ -7227,14 +7997,16 @@ var OpsLogOpSchema = _enum([
 	"manual-delete",
 	"rescan",
 	"retention-run",
-	"relocate"
+	"relocate",
+	"orphan-audit"
 ]);
 /** Why the operation ran. */
 var OpsLogReasonSchema = _enum([
 	"retention",
 	"quota",
 	"manual",
-	"operator"
+	"operator",
+	"maintenance"
 ]);
 /** One audit row, shared verbatim by both domains. */
 var OpsLogEntrySchema = object({
@@ -9221,6 +9993,126 @@ var RtpSourceSchema = object({
 	encoder: string(),
 	pipelineKey: string()
 });
+/**
+* The encode request — **structured and serialisable, with NO raw-flag escape
+* hatch.** This is deliberate and it is the one lesson taken from
+* `getStreamWithCodec`: that method's `outputArgs: string[]` is simultaneously
+* its extensibility mechanism AND part of `pipelineKeyFor`'s sharing key, so
+* adding a flag silently forks the shared child, and two consumers that mean
+* the same thing but spell it differently never share. Here every knob is a
+* NAMED field: a new requirement becomes a schema field (and a codegen run),
+* never an opaque array.
+*
+* `inputArgs` / `outputArgs` are omitted from the profile for the same reason.
+* The operator-facing derived-stream transform editor still has them — that is
+* a different surface (`publishCameraStream({ kind: 'derived' })`) with a
+* different purpose (reshaping a badly-behaved SOURCE), and it is unchanged.
+*/
+var EgressEncodeSchema = EncodeProfileSchema.omit({
+	inputArgs: true,
+	outputArgs: true
+});
+/**
+* How the encoder is bounded. `'tight'` is a one-second VBV window for a
+* consumer whose budget is enforced per second (HomeKit); `'relaxed'` is two
+* seconds, letting a keyframe spike borrow from the next second (a browser,
+* an Echo). Named rather than numeric so the INTENT survives.
+*/
+var EgressRateControlSchema = _enum(["tight", "relaxed"]);
+var EgressTranscodeRequestSchema = object({
+	deviceId: number().int().nonnegative(),
+	/** Which published stream to read. */
+	source: discriminatedUnion("kind", [object({
+		kind: literal("profile"),
+		profile: CamProfileSchema
+	}), object({
+		kind: literal("cam-stream"),
+		camStreamId: string().min(1)
+	})]),
+	encode: EgressEncodeSchema,
+	rateControl: EgressRateControlSchema.optional(),
+	/**
+	* `-bsf:v`. A consumer that negotiates its OWN SDP (HomeKit) cannot carry
+	* out-of-band extradata and needs `dump_extra` on both the copy and encode
+	* branches. Enumerated, not free text.
+	*/
+	bitstreamFilter: _enum([
+		"dump_extra",
+		"h264_mp4toannexb",
+		"hevc_mp4toannexb"
+	]).optional(),
+	/**
+	* Publish the transcode as a LOCAL push cam stream, instead of leaving the
+	* consumer to dial the returned url. The broker picks the id and returns it
+	* as `camStreamId` — a caller-supplied one would be circular, since the
+	* sharing key is computed FROM this request.
+	*
+	* The url is still returned and still the contract for a transcode pinned to
+	* another node. But dialling it locally costs an RTSP round trip that changes
+	* the transport underneath the consumer: a dialled stream is an RTP source,
+	* so `isRtpSource()` is true and the session takes the RTP-passthrough +
+	* repacketizer branch. The push branch — the one the derived mechanism has
+	* live hours on — is never reached. Measured on Alexa: broker registered, RTP
+	* arriving, key frame arriving, black screen, on a chain healthy at every
+	* other point.
+	*
+	* Same idea the transport already applies to CALLS, where `classifyCapRoute`
+	* gives priority to `hub-in-process` so a local call never leaves the node.
+	* This is that rule for media.
+	*/
+	publishLocally: boolean().optional(),
+	pixelFormat: _enum(["yuv420p", "nv12"]).optional(),
+	/**
+	* Operator/consumer override for decode hardware. ABSENT is the normal case
+	* and the one that matters: the broker then resolves the backend from the
+	* DECODER ADDON's per-node `probedBestHwaccel` (see
+	* `@camstack/types` `ffmpeg/hwaccel.ts`), which is the ranking known to work
+	* on this hardware — never the raw kernel resolver's qsv-first order.
+	*/
+	decodeHwAccel: _enum([
+		"auto",
+		"none",
+		"videotoolbox",
+		"vaapi",
+		"qsv",
+		"cuda"
+	]).optional(),
+	/**
+	* Host to embed in the returned restream `url`. The broker mints hub-local
+	* `127.0.0.1` URLs; a consumer on another node passes a cluster-resolvable
+	* host (`NodeTopologyService.reachableHostByNode`) so the returned URL is
+	* dialable from there. Same contract as `getStreamWithCodec.hostname` —
+	* `substituteRtspHost` rewrites only the dial address, never the restreamer.
+	*/
+	hostname: string().optional(),
+	/** Attribution for the broker panel. Never part of the sharing key. */
+	tag: string().optional()
+});
+var EgressTranscodeSchema = object({
+	/** Dial-able RTSP url (host-substituted when `hostname` was supplied). */
+	url: string(),
+	/** Release handle. Refcounted — the child dies when the last holder releases. */
+	pipelineKey: string(),
+	videoCodec: _enum(["H264", "H265"]),
+	resolution: object({
+		width: number().int().positive(),
+		height: number().int().positive()
+	}),
+	transcoded: boolean(),
+	encoder: string(),
+	/**
+	* The decode backend the child ACTUALLY ran with — `null` for software.
+	* Returned rather than assumed: a consumer that asked for hardware and got
+	* software needs to be able to see that without reading the broker's logs.
+	*/
+	decodeHwAccel: string().nullable(),
+	/**
+	* Set when `publishLocally` was honoured: attach to THIS instead of dialling
+	* `url`, and the session takes the push/deframe transport rather than the
+	* RTP-passthrough one. `null` means the consumer must dial.
+	*/
+	camStreamId: string().nullable()
+});
 var streamBrokerCapability = {
 	name: "stream-broker",
 	scope: "system",
@@ -9392,6 +10284,40 @@ var streamBrokerCapability = {
 			auth: "admin"
 		}),
 		/**
+		* THE ffmpeg primitive. Acquire an encoded stream matching a structured
+		* encode plan; the broker builds the argv through the ONE builder
+		* (`@camstack/types` `ffmpeg/invocation.ts`), resolves decode hardware from
+		* the DECODER ADDON's per-node ranking, and returns a dialable RTSP url.
+		*
+		* **Refcounted and deduplicated on EXACT match.** Two requesters whose
+		* requests produce the same `egressTranscodeSharingKey` receive the SAME
+		* `pipelineKey` and the same child process. Nearly-identical requests are
+		* NOT merged.
+		*
+		* **The handle is immutable.** There is deliberately no `reconfigure`
+		* method and this one never accepts a `pipelineKey` alongside encode
+		* parameters: a consumer whose requirements change releases and
+		* re-acquires. A mutable shared handle is exactly what made Alexa's old
+		* `derived:alexa-<id>` stream a co-tenant hazard — one consumer's
+		* downgrade dragged every other consumer down with it.
+		*
+		* Placement: unpinned, `classifyCapRoute` serves this hub-in-process
+		* (Priority 1). A caller that wants the transcode elsewhere passes
+		* `nodePin(nodeId)` and a `hostname` it can dial.
+		*/
+		acquireEgressTranscode: method(EgressTranscodeRequestSchema, EgressTranscodeSchema, {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/** Drop one reference. The child dies when the last holder releases. */
+		releaseEgressTranscode: method(object({ pipelineKey: string() }), object({
+			released: boolean(),
+			refcount: number().int().nonnegative()
+		}), {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
 		* ── Decoded audio-chunk plane (Phase 5 / D9) ──────────────────────
 		*
 		* The serialisable replacement for the live-object `IStreamBroker.
@@ -14271,12 +15197,13 @@ var NcConditionsSchema = object({
 	* source; otherwise the subject's source must equal it. Legacy records
 	* with no stamped source are treated as `pipeline`. The union spans both
 	* record kinds — object events carry `pipeline` | `onboard`, synthetic
-	* tracks carry `sensor`.
+	* tracks carry `sensor` (a linked device) or `audio` (a D62 audio marker).
 	*/
 	source: _enum([
 		"pipeline",
 		"onboard",
 		"sensor",
+		"audio",
 		"any"
 	]).optional(),
 	/**
@@ -14852,6 +15779,12 @@ method(object({}), object({ rules: array(NcRuleSchema) }), { auth: "admin" }), m
 }), object({ success: literal(true) }), {
 	kind: "mutation",
 	auth: "admin"
+}), method(object({}), object({ mutedDeviceIds: array(number().int()).readonly() }), { auth: "admin" }), method(object({
+	deviceId: number().int(),
+	muted: boolean()
+}), object({ success: literal(true) }), {
+	kind: "mutation",
+	auth: "admin"
 }), method(object({
 	rule: NcRuleInputSchema,
 	lookbackMinutes: number().int().min(1).max(1440).default(60)
@@ -15190,12 +16123,60 @@ var TrackAudioLabelSchema = object({
 });
 /**
 * How a track was produced. `pipeline` (default / absent) = the spatial
-* detection+tracking pipeline. `sensor` = a SYNTHETIC track projected from a
-* linked sensor/control state change (no positions; carries a snapshot). The
-* spatial subsystems (tracker association, occupancy count, re-id/embedding,
-* resurrection) MUST skip `sensor` tracks — they have no bbox trajectory.
+* detection+tracking pipeline. Every OTHER value is a SYNTHETIC projection —
+* no positions, a single snapshot, and no bbox trajectory at all:
+*
+*  - `sensor` — a linked sensor/control device state change.
+*  - `audio` — an audio event on the camera itself that was anomalous for
+*    THAT camera, loud, and heard while nothing visual was happening (D62).
+*
+* The spatial subsystems (tracker association, occupancy count, re-id /
+* embedding, resurrection) MUST skip every synthetic source. Test for that
+* with `isSpatialTrack`, which allow-lists `pipeline` — a `!== 'sensor'`
+* check silently readmits every source added after it was written.
+*/
+var TrackSourceSchema = _enum([
+	"pipeline",
+	"sensor",
+	"audio"
+]);
+/**
+* Per-track OPERATOR flags — set by hand from the admin UI or the viewer, never
+* by the pipeline. Spread into `TrackSchema` and `KeyEventSchema` from one place
+* so the two surfaces cannot drift.
+*
+* **Absent ≠ false.** A track that has never been touched omits the field; an
+* explicitly un-flagged track carries `false`. Legacy rows written before the
+* columns existed read as absent, and a consumer that needs a boolean should say
+* `flag === true`, not `flag !== false`.
+*
+* What the flags DO is deliberately UNDEFINED at the time of writing: they are
+* operator curation, and the behaviour they drive will be specified separately.
+* In particular a `markForTrain` track is NOT pinned against retention — see
+* `docs/decisions/adr-0059.md` for why that is a store-level change, not a flag.
 */
-var TrackSourceSchema = _enum(["pipeline", "sensor"]);
+var TrackFlagFields = {
+	/** Operator marked this track as training material. */
+	markForTrain: boolean().optional(),
+	/** Operator marked this track for diagnostic attention. */
+	debug: boolean().optional()
+};
+/**
+* The write half: a PARTIAL patch. An omitted key is left untouched, so setting
+* one flag can never clear the other — the toggles are independent and are
+* driven from three surfaces that do not know about each other.
+*/
+var TrackFlagsPatchSchema = object(TrackFlagFields);
+/**
+* The resolved flag state after a write. Both fields are REQUIRED here (absent
+* collapses to `false`) so a caller can drive a toggle's checked state off the
+* mutation result without a re-fetch.
+*/
+var TrackFlagsSchema = object({
+	trackId: string(),
+	markForTrain: boolean(),
+	debug: boolean()
+});
 var TrackSchema = object({
 	trackId: string(),
 	deviceId: number(),
@@ -15238,7 +16219,8 @@ var TrackSchema = object({
 	/** Normalized 0..1 trajectory envelope (see {@link TrackEnvelopeSchema}).
 	*  Populated from the persisted envelope columns on historical reads;
 	*  absent on legacy rows, dims-less tracks and active (in-RAM) tracks. */
-	envelope: TrackEnvelopeSchema.optional()
+	envelope: TrackEnvelopeSchema.optional(),
+	...TrackFlagFields
 });
 var BaseEventFields = {
 	id: string(),
@@ -15451,7 +16433,8 @@ var KeyEventSchema = object({
 	/** Highest-confidence ObjectEvent id for the track (empty when none). */
 	bestEventId: string(),
 	/** Track lifetime in ms (lastSeen - firstSeen). */
-	windowMs: number().optional()
+	windowMs: number().optional(),
+	...TrackFlagFields
 });
 object({
 	trackId: string(),
@@ -15537,7 +16520,31 @@ var RebuildObjectEmbeddingsInput = object({
 	since: number().optional(),
 	until: number().optional(),
 	/** Stop after this many tracks; the result reports whether more remain. */
-	maxTracks: number().int().positive().optional()
+	maxTracks: number().int().positive().optional(),
+	/**
+	* Run every embedding on THIS node instead of round-robining the fleet.
+	*
+	* Named `executeOnNodeId` and not `nodeId` on purpose: an inline `nodeId`
+	* field in cap args is read by `parent-unowned-call.ts` as a ROUTING PIN, so
+	* calling it that would pin the rebuild REQUEST itself to that node — the
+	* rebuild orchestration lives on the hub, and only the per-track step runs
+	* remotely. This field is data; the per-track pin is applied inside.
+	*
+	* Absent ⇒ round-robin over every online node whose runner can serve the
+	* pinned model.
+	*/
+	executeOnNodeId: string().optional(),
+	/**
+	* Milliseconds to wait between tracks; omit for the built-in default, `0` to
+	* run flat out.
+	*
+	* A rebuild is bulk maintenance on hub-main's single thread. Measured
+	* 2026-08-06, an unpaced pass held that thread busy 82.2 s out of 120 and
+	* pushed `nodes.topology` from 0.25 s to 26 s for 43 minutes. The value in
+	* force is logged at start and finish so a deliberately slow pass reads
+	* differently from a stalled one.
+	*/
+	pacingMs: number().int().nonnegative().optional()
 });
 /**
 * Result of emptying the CLIP index.
@@ -15571,13 +16578,23 @@ var RebuildStatusSchema = object({
 	/** Tracks with no usable detection box. */
 	missingBbox: number(),
 	/**
-	* Tracks the pipeline REFUSED rather than broke on: the camera is not
-	* attached, or `clip-embedding` is not enabled in its step tree. Separate
-	* from `failed` because the remedy is a configuration change, not an engine
-	* investigation — and because a pass over decommissioned cameras would
-	* otherwise read as a total engine outage.
+	* Tracks an executing node REFUSED rather than broke on — an unreadable key
+	* frame, a step that threw. Separate from `failed` because the remedy is
+	* different, and because a whole camera silently contributing zero vectors
+	* is the shape of failure a rebuild must never hide.
 	*/
 	notRunnable: number(),
+	/**
+	* The pass stopped because NO node could serve the pinned model.
+	*
+	* Distinct from `notRunnable` on purpose: that one says "this track was
+	* refused", this one says "the cluster cannot do this work at all" — every
+	* candidate node either lacks the `clip-embedding` step, lacks a build of the
+	* pinned model for its engine format, or dropped out. The remedy is a model /
+	* engine change, not a per-camera one. Non-zero here always comes with
+	* `complete: false`.
+	*/
+	noCapableNode: number(),
 	failed: number(),
 	/** Set once a pass ends: true only when EVERYTHING was covered. */
 	complete: boolean().nullable(),
@@ -15649,7 +16666,12 @@ DeviceType.Camera, method(object({ deviceId: number() }), array(TrackSchema).rea
 }), {
 	kind: "mutation",
 	auth: "admin"
-}), method(object({}), EventStoreFootprintSchema, {
+}), method(object({
+	/** Log/audit scope only — the trackId is globally unique on its own. */
+	deviceId: number(),
+	trackId: string(),
+	flags: TrackFlagsPatchSchema
+}), TrackFlagsSchema, { kind: "mutation" }), method(object({}), EventStoreFootprintSchema, {
 	kind: "query",
 	auth: "admin"
 }), method(object({
@@ -16411,6 +17433,53 @@ var DetailResultSchema = object({
 	nativeFaceShortSidePx: number().optional()
 });
 /**
+* Why an executing node REFUSED a stateless step run (`runStatelessStep`).
+*
+* A refusal is a first-class answer, not an error, because the caller's next
+* move depends on WHICH one it is — and because "the pass produced nothing"
+* must never be reachable without a named, counted cause. The two tiers:
+*
+* - **node-level** (`unknown-step`, `model-not-servable`) — this node can
+*   never serve this (step, model) pair. The caller drops it from its rotation
+*   and retries the same work elsewhere; nothing about the work changes.
+* - **work-level** (`unreadable-frame`, `execution-failed`) — this node is
+*   fine, this one request is not. Retrying it on another node would only
+*   spread the same failure.
+*/
+var StatelessStepRefusalSchema = _enum([
+	"unknown-step",
+	"model-not-servable",
+	"unreadable-frame",
+	"execution-failed"
+]);
+/**
+* Answer to `runStatelessStep` — a discriminated union rather than a nullable
+* result, because `null` is exactly what made the camera-bound detail path
+* unable to tell "refused" from "never asked".
+*/
+var RunStatelessStepResultSchema = discriminatedUnion("kind", [object({
+	kind: literal("ran"),
+	/** The node that actually executed it — the pin, echoed back for the log. */
+	nodeId: string(),
+	/**
+	* The model the step ran with.
+	*
+	* The node verified this exact id has a build for the format it dispatched
+	* on BEFORE running, so the executor's format resolution returns it
+	* unchanged. A caller that pinned a model must compare this field and
+	* treat a mismatch as a refusal — the whole point of the pin is that a
+	* pass writes one feature space.
+	*/
+	modelId: string(),
+	details: array(DetailResultSchema)
+}), object({
+	kind: literal("refused"),
+	nodeId: string(),
+	reason: StatelessStepRefusalSchema,
+	/** Human-readable specifics — the format tried, the formats shipped, etc. */
+	detail: string()
+})]);
+/**
 * Per-camera tunable ranges + defaults. Single source of truth used
 * by both the Zod data schema (validation + default fallback) and
 * the device settings UI (slider min/max/step). Touch one place and
@@ -16855,7 +17924,77 @@ var pipelineRunnerCapability = {
 			cropJpeg: string().optional(),
 			parent: DetailParentSchema,
 			steps: array(string()).optional()
-		}), object({ details: array(DetailResultSchema) }).nullable(), { kind: "mutation" })
+		}), object({ details: array(DetailResultSchema) }).nullable(), { kind: "mutation" }),
+		/**
+		* Run ONE enrichment step against caller-supplied pixels, with NO camera
+		* session — no attach, no frame handle, no device affinity.
+		*
+		* ## Why this exists next to `runDetailSubtree` and not inside it
+		*
+		* `runDetailSubtree` resolves its step tree from the LIVE ATTACH STATE. That
+		* is correct for it: its reason to exist is a frame HANDLE, and a handle is
+		* only resolvable while a decode session is open. But it makes the method
+		* useless to anything walking history — cameras run `detectionMode:
+		* 'on-motion'` and detach ~30 s after motion stops, so a fleet-wide
+		* embedding rebuild found most cameras detached and rebuilt only whatever
+		* happened to be attached at that second (measured 2026-08-06: 1125 tracks
+		* scanned, 121 rebuilt, 601 refused as "camera is not attached").
+		*
+		* A caller that ships its own pixels needs none of that machinery. So this
+		* method takes the three things a step actually needs — an image, a box, a
+		* step id — resolves the step from the CATALOG rather than from an
+		* attachment, and runs it on whichever node the caller pinned.
+		*
+		* ## What it deliberately keeps
+		*
+		* The crop rectangle is derived by the SAME `deriveDetailCropRect` call the
+		* live detail plane uses, from the same cluster-wide convention
+		* ([D52](../../../docs/decisions/adr-0052.md)). `frameJpeg` is a FULL frame,
+		* never a pre-cut tile, for exactly the reason `runDetailSubtree` documents:
+		* a caller that cuts is a second feature space.
+		*
+		* ## What it deliberately drops
+		*
+		* No device jump and no `deviceKey`: the jump roster comes from the attach
+		* config, which does not exist here. The step runs on the node's default
+		* engine. This is a maintenance path, not a latency-sensitive one.
+		*
+		* ## Routing
+		*
+		* NOT device-bound. `sourceDeviceId` is DIAGNOSTIC — the camera whose track
+		* these pixels came from, so every log line on the executing node can carry
+		* `tags: { deviceId }`. It is deliberately not named `deviceId`: that field
+		* is a routing hint that would send the call to the camera's owning node,
+		* which is the placement constraint this method exists to remove. Callers
+		* choose the node with `nodePin(nodeId)`; unpinned, an unowned call is
+		* served hub-in-process like any other singleton.
+		*/
+		runStatelessStep: method(object({
+			/** Catalog step id, e.g. `clip-embedding`. */
+			stepId: string(),
+			/**
+			* REQUIRED model pin. The node runs this exact model or refuses with
+			* `model-not-servable` — it never substitutes a format default, because
+			* a fleet pass that round-robins across nodes would then fill one index
+			* from several encoders.
+			*/
+			modelId: string(),
+			/** FULL FRAME, base64 JPEG. The runner cuts — do NOT pre-crop. */
+			frameJpeg: string(),
+			/**
+			* The subject box, NORMALISED [0,1] against `frameJpeg`. Normalised on
+			* purpose: the caller stores boxes against a downscaled analysis frame
+			* while the stored key frame is native-resolution, and the only side
+			* that reliably knows the image's pixel dimensions is the side that
+			* decodes it. Denormalising here removes a second reader of the
+			* dimensions and the class of mismatch that comes with it.
+			*/
+			bbox: NativeCropBboxSchema,
+			/** Parent class of the subject (`person`, `vehicle`, …) — carried into the result. */
+			className: string(),
+			/** Camera the pixels came from. Diagnostics + log tags ONLY — never routing. */
+			sourceDeviceId: number()
+		}), RunStatelessStepResultSchema, { kind: "mutation" })
 	}
 };
 var CameraPipelineConfigSchema = object({
@@ -17155,6 +18294,20 @@ var CameraStatusSchema = object({
 	detection: CameraDetectionStatusSchema.nullable(),
 	audio: CameraAudioStatusSchema.nullable(),
 	recording: CameraRecordingStatusSchema.nullable(),
+	/**
+	* Per-camera function switches an OPERATOR has turned off
+	* ([D61](../../../../docs/decisions/adr-0067.md)).
+	*
+	* This is the difference between DISABLED and BROKEN. A camera whose
+	* `detection` block reports zero fps and whose `switchedOff` contains
+	* `'object-detection'` was switched off by a person; the same camera with an
+	* empty list is failing. Every status surface must render the two
+	* differently — a quiet camera that looks identical to a dead one is the
+	* silence-reads-as-never-happened trap this repo keeps paying for.
+	*
+	* Empty when nothing is off. Never contains a switch no provider offers.
+	*/
+	switchedOff: array(CameraSwitchIdSchema).readonly(),
 	/** Unix timestamp (ms) when this snapshot was composed server-side. */
 	fetchedAt: number()
 });
@@ -17323,7 +18476,14 @@ method(object({
 }), method(object({
 	deviceId: number(),
 	agentNodeId: string().optional()
-}), CameraPipelineConfigSchema), method(object({ deviceId: number() }), CameraStatusSchema), method(object({ deviceIds: array(number()).optional() }), array(CameraStatusSchema).readonly()), method(_void(), array(PipelineTemplateSchema).readonly()), method(object({
+}), CameraPipelineConfigSchema), method(object({ deviceId: number() }), CameraSwitchGroupSchema), method(object({
+	deviceId: number(),
+	switchId: CameraSwitchIdSchema,
+	enabled: boolean()
+}), CameraSwitchGroupSchema, {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({ deviceId: number() }), CameraStatusSchema), method(object({ deviceIds: array(number()).optional() }), array(CameraStatusSchema).readonly()), method(_void(), array(PipelineTemplateSchema).readonly()), method(object({
 	name: string(),
 	description: string().optional(),
 	config: CameraPipelineConfigSchema
@@ -17646,9 +18806,15 @@ DeviceType.Camera, method(object({
 	* Bypass the cache freshness check and fetch directly from the
 	* native (or stream-broker fallback). Triggered by the UI's
 	* "refresh" button so an operator can force a fresh frame
-	* even when the cache is well within `snapshotMaxAgeMs`.
-	* On battery cams this WILL wake the camera — accept the
-	* cost only when the user explicitly asks for it.
+	* even when the cache is well within the device's
+	* `snapshotMaxAgeS` window.
+	*
+	* **`force` is an OPERATOR signal, not a freshness preference.** On a
+	* battery camera it is the one thing that walks past the wrapper's
+	* sleep gate and wakes the camera, so a background caller — a poller,
+	* an event handler, a thumbnail — must NEVER set it. Every such caller
+	* gets the cached frame, which on a sleeping battery camera is the
+	* correct answer: stale but honest beats woken.
 	*/
 	force: boolean().optional()
 }), SnapshotImageSchema.nullable()), method(object({ deviceId: number() }), _void(), {
@@ -22025,12 +23191,30 @@ object({
 });
 DeviceType.Sensor;
 /**
-* Privacy mask = up to `maxRegions` SHAPES the camera blanks out (NOT a
-* cell grid). Reolink `<shelterList>` zones are rectangles; Hikvision
-* ISAPI `<RegionCoordinatesList>` zones are free polygons (this camera:
-* exactly 4 vertices, not necessarily axis-aligned). The cap composes the
-* shared rect|polygon subset of the MaskShape vocabulary. All coords are
-* normalized 0..1 (top-left origin).
+* PRIVACY — what the camera deliberately does not capture. Two planes:
+*
+*  - **video**: up to `maxRegions` SHAPES the camera blanks out (NOT a cell
+*    grid). Reolink `<shelterList>` zones are rectangles; Hikvision ISAPI
+*    `<RegionCoordinatesList>` zones are free polygons (this camera: exactly
+*    4 vertices, not necessarily axis-aligned). The cap composes the shared
+*    rect|polygon subset of the MaskShape vocabulary. All coords are
+*    normalized 0..1 (top-left origin).
+*  - **audio**: the camera's microphone. `setAudioEnabled(false)` stops the
+*    camera encoding an audio track at all, so EVERY consumer — live view,
+*    recording, the audio analyzer, an export — sees silent video. There is
+*    no server-side copy of this fact; the camera is the store and every read
+*    is a read-through, which is why a switch over it cannot drift
+*    ([D62](../../../../docs/decisions/adr-0062.md)).
+*
+* Both belong here for one reason: they are the two things an operator turns
+* off when the answer to "what is this camera allowed to record" changes, and
+* both are applied ON the device, before anything leaves it.
+*
+* **The audio flag has exactly one writer.** `stream-params` used to carry a
+* per-profile `audio` in its patch schema — reachable from no UI and honoured
+* by one provider — and it was removed when this landed. A second writer onto
+* one device register is the shape of every knob this repo has shipped that
+* disagreed with the one the reader read.
 */
 /** A privacy-mask region's geometry — rectangle or free polygon. */
 var PrivacyMaskShapeSchema = discriminatedUnion("kind", [MaskRectShapeSchema, MaskPolygonShapeSchema]);
@@ -22046,16 +23230,40 @@ object({
 	enabled: boolean(),
 	/** Active zones (normalized 0..1). Length ≤ maxRegions. */
 	regions: array(PrivacyMaskRegionSchema),
+	/**
+	* Is the camera capturing sound right now? Read from the camera, never from
+	* a server-side mirror.
+	*
+	* `null` means "no answer" — either this camera exposes no controllable
+	* microphone (`getOptions().supportsAudioMute === false`) or the read
+	* failed. A consumer must render `null` as UNKNOWN and never as `false`:
+	* "the microphone is off" and "we could not ask" look identical to an
+	* operator only until one of them is wrong.
+	*
+	* On a camera whose profiles carry the flag independently (Reolink writes
+	* it per stream), `true` means AT LEAST ONE profile still carries audio —
+	* privacy is only satisfied when every one of them is silent.
+	*/
+	audioEnabled: boolean().nullable(),
 	lastFetchedAt: number()
 });
-/** Per-camera availability. */
+/** Per-camera availability. Probed, never assumed from the model name. */
 var PrivacyMaskOptionsSchema = object({
 	/** Maximum number of supported zones. */
 	maxRegions: number(),
 	/** Shape kinds this camera accepts — Reolink: ['rect']; Hikvision: ['rect','polygon']. */
 	supportedShapes: array(MaskShapeKindSchema),
 	/** Polygon vertex bounds when 'polygon' is supported (Hikvision: {min:4,max:4}). */
-	polygonVertices: MaskPolygonVerticesSchema.optional()
+	polygonVertices: MaskPolygonVerticesSchema.optional(),
+	/**
+	* Does this camera expose a microphone switch we can actually write?
+	*
+	* Camera-probed: `true` only when the firmware answered with an audio flag
+	* we know how to patch. A camera that never answered is `false` — a control
+	* the operator can press that changes nothing is worse than no control, and
+	* the switch group renders "not available" instead.
+	*/
+	supportsAudioMute: boolean()
 });
 /** Partial change — every field optional. */
 var PrivacyMaskPatchSchema = object({
@@ -22068,6 +23276,12 @@ DeviceType.Camera, method(object({ deviceId: number() }), PrivacyMaskOptionsSche
 }), _void(), {
 	kind: "mutation",
 	auth: "admin"
+}), method(object({
+	deviceId: number(),
+	enabled: boolean()
+}), _void(), {
+	kind: "mutation",
+	auth: "admin"
 });
 var PtzPresetSchema = object({
 	id: string(),
@@ -22277,6 +23491,21 @@ var LocateSegmentResultSchema = discriminatedUnion("kind", [object({
 })]);
 /** Raw bytes of one finalized footage segment (read off disk on the recording node). */
 var ReadSegmentBytesResultSchema = object({ data: _instanceof(Uint8Array) });
+/**
+* One GOP of a finalized segment, cut by byte range through the segment's own
+* `mfra` (D31 on the D42 feeder path). `data` is the `ftyp`+`moov` head plus
+* the single `moof`+`mdat` covering the requested instant — standalone-
+* demuxable, never the whole file. When the segment's index cannot be parsed
+* the provider degrades INSIDE the mechanism to the whole segment (still one
+* `data`, `gopStartMs` = the segment start) — a worse read, not another path.
+*/
+var ReadGopBytesResultSchema = object({
+	data: _instanceof(Uint8Array),
+	/** Absolute epoch ms of the returned fragment's first sample. */
+	gopStartMs: number(),
+	/** Media ms the returned fragment covers. */
+	gopDurMs: number()
+});
 var recordingCapability = {
 	name: "recording",
 	scope: "system",
@@ -22344,6 +23573,18 @@ var recordingCapability = {
 			kind: "query",
 			auth: "admin"
 		}),
+		/** Read the single GOP of segment `startMs` covering `epochMs`, by mfra
+		*  byte range — the scrub-granular read (D31 letter on the feeder path).
+		*  See {@link ReadGopBytesResultSchema} for the degradation contract. */
+		readGopBytes: method(object({
+			deviceId: number(),
+			profile: string(),
+			startMs: number(),
+			epochMs: number()
+		}), ReadGopBytesResultSchema, {
+			kind: "query",
+			auth: "admin"
+		}),
 		setDeviceConfig: method(object({
 			deviceId: number(),
 			config: RecordingConfigSchema
@@ -22895,6 +24136,16 @@ var StreamProfileConfigSchema = object({
 		"baseline"
 	]).optional(),
 	gop: number().optional(),
+	/**
+	* Whether THIS profile currently carries an audio track. READ-ONLY here.
+	*
+	* There is no matching field on {@link StreamProfilePatchSchema}: the
+	* camera's microphone is owned by `privacy-mask` (`setAudioEnabled`), which
+	* writes every profile at once so "audio off" means silent everywhere. A
+	* per-profile writer beside it would let a camera be half-muted and would be
+	* a second knob onto one device register — the failure D62 exists to
+	* prevent. Absent when the firmware does not report the flag.
+	*/
 	audio: boolean().optional()
 });
 object({
@@ -22935,7 +24186,13 @@ var StreamParamsOptionsSchema = object({
 	ext: StreamProfileOptionsSchema.optional()
 });
 /** A partial change to one profile — every field optional; a provider
-*  ignores fields it doesn't support. */
+*  ignores fields it doesn't support.
+*
+*  There is deliberately NO `audio` here. It existed until 2026-08-07,
+*  reachable from no form and honoured by exactly one provider, while the
+*  camera's microphone is a whole-device fact. It now has one writer,
+*  `privacyMask.setAudioEnabled`, which writes every profile — see
+*  `privacy-mask.cap.ts`. */
 var StreamProfilePatchSchema = object({
 	width: number().optional(),
 	height: number().optional(),
@@ -22948,8 +24205,7 @@ var StreamProfilePatchSchema = object({
 		"main",
 		"baseline"
 	]).optional(),
-	gop: number().optional(),
-	audio: boolean().optional()
+	gop: number().optional()
 });
 DeviceType.Camera, method(object({ deviceId: number() }), StreamParamsOptionsSchema), method(object({
 	deviceId: number(),
@@ -26472,6 +27728,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"notificationRules.listDeviceMutes": {
+		capName: "notification-rules",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"notificationRules.listRules": {
 		capName: "notification-rules",
 		capScope: "system",
@@ -26490,6 +27752,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"notificationRules.setDeviceMuted": {
+		capName: "notification-rules",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"notificationRules.setRuleEnabled": {
 		capName: "notification-rules",
 		capScope: "system",
@@ -26766,6 +28034,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.setTrackFlags": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineAnalytics.wipeAllAnalytics": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -27072,6 +28346,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineOrchestrator.getCameraSwitches": {
+		capName: "pipeline-orchestrator",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineOrchestrator.getCapabilityBindings": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
@@ -27204,6 +28484,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"pipelineOrchestrator.setCameraSwitch": {
+		capName: "pipeline-orchestrator",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineOrchestrator.setCapabilityBinding": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
@@ -27294,6 +28580,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"pipelineRunner.runStatelessStep": {
+		capName: "pipeline-runner",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"plateGallery.assignPlate": {
 		capName: "plate-gallery",
 		capScope: "system",
@@ -27426,6 +28718,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"privacyMask.setAudioEnabled": {
+		capName: "privacy-mask",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"privacyMask.setMask": {
 		capName: "privacy-mask",
 		capScope: "device",
@@ -27594,6 +28892,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"recording.readGopBytes": {
+		capName: "recording",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"recording.readSegmentBytes": {
 		capName: "recording",
 		capScope: "system",
@@ -28110,6 +29414,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"streamBroker.acquireEgressTranscode": {
+		capName: "stream-broker",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"streamBroker.assignProfile": {
 		capName: "stream-broker",
 		capScope: "system",
@@ -28218,6 +29528,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"streamBroker.releaseEgressTranscode": {
+		capName: "stream-broker",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"streamBroker.releaseStreamWithCodec": {
 		capName: "stream-broker",
 		capScope: "system",
@@ -29216,7 +30532,7 @@ function readDetailCropConvention(config) {
 		square: square.success ? square.data : DEFAULT_DETAIL_CROP_CONVENTION.square
 	};
 }
-function isHydratedField(entry) {
+function isHydratedField$1(entry) {
 	return typeof entry === "object" && entry !== null && "key" in entry;
 }
 /**
@@ -29231,7 +30547,7 @@ function pickDetailCropConvention(view) {
 	if (view === null) return DEFAULT_DETAIL_CROP_CONVENTION;
 	const flat = {};
 	for (const section of view.sections) for (const entry of section.fields) {
-		if (!isHydratedField(entry) || typeof entry.key !== "string") continue;
+		if (!isHydratedField$1(entry) || typeof entry.key !== "string") continue;
 		if (entry.key === "detailCropPaddingRatio" || entry.key === "detailCropSquare") flat[entry.key] = entry.value;
 	}
 	return readDetailCropConvention(flat);
@@ -29311,6 +30627,178 @@ function slideInsideFrame(rect, frameWidth, frameHeight) {
 		h
 	};
 }
+var NATIVE_LEASE_TTL_KEY = "nativeLeaseTtlMs";
+var NATIVE_LEASE_BUDGET_KEY = "nativeLeaseBudgetMb";
+var NATIVE_LEASE_ACTIVITY_KEY = "nativeLeaseActivityMs";
+var NATIVE_LEASE_ADMISSION_KEY = "nativeLeaseAdmission";
+/**
+* WHICH delivered frames the decode worker retains a native copy of.
+*
+* - `all` — every frame the worker delivered to the runner. The shipped
+*   behaviour, and the only correct one if something can ask for a crop of a
+*   frame the runner never sent to inference.
+* - `inferred` — only the frames the runner ADMITTED to its detection queue.
+*   A native-crop request always names a `frameId` that rode an inference
+*   result, so that is the only set a request can name. How much it drops is
+*   the two-plane governor's admit ratio and nothing else: measured at ~50% on
+*   this cluster, not the ~80% the design sketch assumed, because the governor
+*   was not throttling as hard as the sketch supposed. Read
+*   `leaseAdmitted`/`leaseOffered` off the metrics line for the camera in front
+*   of you rather than quoting a number from here. The newest delivered frame is
+*   croppable regardless — it is still the worker's reserved slot, not a lease —
+*   which covers the one-frame race between a mark and the supersede that
+*   consumes it.
+*/
+var NativeLeaseAdmissionSchema = _enum(["all", "inferred"]);
+/**
+* Operator-tunable native-lease settings. Bounds are enforced HERE (not only in
+* the slider) because the value also travels to a forked child process, where a
+* junk number would silently become a 0-length or unbounded retention window.
+*/
+var NativeLeaseSettingsSchema = object({
+	/**
+	* How long a retained native frame is served before it counts as a miss.
+	*
+	* Must cover the FULL late-crop horizon: detection inference + the
+	* cross-process inference-result hop to hub post-analysis + tracking + the
+	* tRPC crop round-trip back. Below ~500 ms the busiest cameras' subject crops
+	* outrun it and fall back to the ≤640 detection frame; above ~3 s the resident
+	* RAM per busy camera grows linearly with no measured hit-rate gain.
+	*/
+	ttlMs: number().int().min(250).max(1e4),
+	/**
+	* Hard per-decode-worker RAM ceiling for retained native frames, in MB.
+	*
+	* Intended as a SAFETY ceiling with the TTL as the effective cap — but check
+	* which one is actually binding before reasoning from that. At the shipped
+	* 1024 MB and a 2 800 ms TTL, a 4K camera hits the CEILING first (~43 frames
+	* at ~24 MB each) and the TTL never gets to expire anything; `leaseMb` /
+	* `leaseFrames` on the metrics line say which. When the ceiling binds, a
+	* change that admits fewer frames buys retention WINDOW at constant RAM
+	* rather than giving RAM back — lower this knob if RAM is what you wanted.
+	* `0` DISABLES the lease entirely and falls the worker back to the tiny
+	* leak-prone GPU surface ring (~85% crop miss; that is what the lease exists
+	* to replace).
+	*/
+	budgetMb: number().int().min(0).max(4096),
+	/**
+	* Demand window: eager per-frame native retention runs only within this many
+	* ms of the last native-crop request (or of the dial starting).
+	*
+	* `0` means ALWAYS ON — it disables the gate, it does not disable retention.
+	* That is the legacy behaviour that saturated an N100 (24 native-4K downloads
+	* per second on a camera with zero crop demand), so leave it non-zero unless
+	* you are reproducing that.
+	*/
+	activityMs: number().int().min(0).max(12e4),
+	/**
+	* Which delivered frames are retained at all — see
+	* {@link NativeLeaseAdmissionSchema}. This is the only knob of the four that
+	* changes WHAT is kept rather than for how long, so it is also the only one
+	* that can turn a crop that used to hit into a miss. The worker counts every
+	* crop request naming a frame it did NOT see marked
+	* (`leaseUnmarkedCrops` on the session-decode metrics line): a non-zero value
+	* there is the signal that some caller names frames outside the inference set
+	* and that this must go back to `all`.
+	*/
+	admission: NativeLeaseAdmissionSchema
+});
+/**
+* The values in force when the operator has set nothing — byte-for-byte the
+* constants the decode worker shipped with as env-var defaults, so making these
+* settings changed no behaviour on the day it landed.
+*/
+var DEFAULT_NATIVE_LEASE_SETTINGS = {
+	ttlMs: 1200,
+	budgetMb: 1024,
+	activityMs: 15e3,
+	admission: "inferred"
+};
+DEFAULT_NATIVE_LEASE_SETTINGS.ttlMs;
+DEFAULT_NATIVE_LEASE_SETTINGS.budgetMb;
+DEFAULT_NATIVE_LEASE_SETTINGS.activityMs;
+DEFAULT_NATIVE_LEASE_SETTINGS.admission;
+/**
+* Parse one knob, reporting `null` for absent, junk, out-of-bounds — AND for a
+* value equal to the shipped default.
+*
+* That last rule is not tidiness, it is the difference between the documented
+* precedence being true and being a lie. `addon-settings.getGlobalSettings`
+* returns a HYDRATED payload, and `hydrateField` fills an unstored field with
+* the schema's own `default` (verified live on the hub: a cluster that has never
+* opened the form still reports `nativeLeaseTtlMs = 1200`). A reader that took
+* that at face value would report all three knobs as "set" on every cluster on
+* the day this shipped, permanently retiring the `CAMSTACK_SESSION_NATIVE_LEASE_*`
+* emergency override that the precedence promises. There is no raw-store read on
+* this cap to distinguish the two, so the default value itself is treated as
+* "the operator has expressed no preference" — which is also what leaving a
+* slider untouched means.
+*
+* The cost is one honest edge: an operator who deliberately selects the default
+* value in order to overrule an env var does not get it. Clear the env var
+* instead; the worker's spawn line names the source, so this is visible rather
+* than mysterious.
+*/
+function readKnob(knob, raw) {
+	const parsed = NativeLeaseSettingsSchema.shape[knob].safeParse(raw);
+	if (!parsed.success) return null;
+	return parsed.data === DEFAULT_NATIVE_LEASE_SETTINGS[knob] ? null : parsed.data;
+}
+/** {@link readKnob} for the one non-numeric knob. Same default-means-unset rule. */
+function readAdmissionKnob(raw) {
+	const parsed = NativeLeaseAdmissionSchema.safeParse(raw);
+	if (!parsed.success) return null;
+	return parsed.data === DEFAULT_NATIVE_LEASE_SETTINGS.admission ? null : parsed.data;
+}
+/**
+* Narrow a FLAT settings record to the knobs the operator set.
+*
+* Per-FIELD parse, deliberately: a junk TTL must not also discard a valid
+* budget. An absent, out-of-bounds or default-valued knob is OMITTED (not
+* clamped, not defaulted) so the caller can still fall through to the env
+* override — clamping here would turn a typo into a value nobody chose. See
+* {@link readKnob} for why the default counts as unset.
+*/
+function readNativeLeaseOverride(config) {
+	const ttlMs = readKnob("ttlMs", config[NATIVE_LEASE_TTL_KEY]);
+	const budgetMb = readKnob("budgetMb", config[NATIVE_LEASE_BUDGET_KEY]);
+	const activityMs = readKnob("activityMs", config[NATIVE_LEASE_ACTIVITY_KEY]);
+	const admission = readAdmissionKnob(config[NATIVE_LEASE_ADMISSION_KEY]);
+	return {
+		...ttlMs === null ? {} : { ttlMs },
+		...budgetMb === null ? {} : { budgetMb },
+		...activityMs === null ? {} : { activityMs },
+		...admission === null ? {} : { admission }
+	};
+}
+function isHydratedField(entry) {
+	return typeof entry === "object" && entry !== null && "key" in entry;
+}
+var LEASE_KEYS = [
+	NATIVE_LEASE_TTL_KEY,
+	NATIVE_LEASE_BUDGET_KEY,
+	NATIVE_LEASE_ACTIVITY_KEY,
+	NATIVE_LEASE_ADMISSION_KEY
+];
+/**
+* Extract the operator's lease overrides from an
+* `addon-settings.getGlobalSettings` payload.
+*
+* Walks EVERY section rather than looking inside {@link NATIVE_LEASE_SECTION_ID}
+* alone: the keys are unique across the addon's schema, and a section rename
+* must not silently revert the whole cluster to the defaults. A `null` payload
+* (addon mid-boot) means "operator set nothing" — the env/default fallback then
+* applies, which is the correct read of "I could not ask".
+*/
+function pickNativeLeaseOverride(view) {
+	if (view === null) return {};
+	const flat = {};
+	for (const section of view.sections) for (const entry of section.fields) {
+		if (!isHydratedField(entry) || typeof entry.key !== "string") continue;
+		if (LEASE_KEYS.includes(entry.key)) flat[entry.key] = entry.value;
+	}
+	return readNativeLeaseOverride(flat);
+}
 var AUTO = {
 	value: "auto",
 	label: "Auto"
@@ -29528,4 +31016,4 @@ function enumerateInferenceDevices(hw) {
 	return out;
 }
 //#endregion
-export { nodePin as $, mapAudioLabelToMacro as A, streamBrokerCapability as B, defineCustomActions as C, enumerateInferenceDevices as D, detectionPipelineCapability as E, pipelineRunnerCapability as F, CAM_PROFILE_ORDER as G, webrtcSessionCapability as H, recordingCapability as I, createEvent as J, DeviceFeature as K, recordingExportCapability as L, motionDetectionCapability as M, pickDetailCropConvention as N, evaluateZoneRules as O, pipelineExecutorCapability as P, makeSourceBrokerId as Q, runtimeDevices as R, defaultDeviceFor as S, deriveRecordingMode as T, errMsg as U, supportedRuntimes as V, BaseAddon as W, isEvent as X, hydrateSchema as Y, makeProfileBrokerId as Z, addonWidgetsSourceCapability as _, COCO_TO_MACRO as a, array as at, cameraStreamsCapability as b, DEVICE_BACKEND_TO_FORMAT as c, lazy as ct, ExportRecordSchema as d, object as dt, parseJsonUnknown as et, HF_BASE_URL as f, record as ft, YAMNET_TO_MACRO as g, RingBuffer as h, EventCategory as ht, COCO_80_LABELS as i, _enum as it, maskUrlCredentials as j, hfModelUrl as k, EVENT_PAD_MS as l, literal as lt, RecordingConfigSchema as m, union as mt, AUDIO_BACKEND_CHOICES as n, selectAssignedProfileSlots as nt, DEFAULT_AUDIO_ANALYZER_CONFIG as o, boolean as ot, OpsLogEntrySchema as p, string as pt, DeviceType as q, AUDIO_MACRO_LABELS as r, sleep as rt, DEFAULT_DETAIL_CROP_CONVENTION as s, discriminatedUnion as st, APPLE_SA_TO_MACRO as t, parseProfileBrokerId as tt, EncodeProfileSchema as u, number as ut, audioAnalysisCapability as v, deriveDetailCropRect as w, customAction as x, audioAnalyzerCapability as y, storageEvictableCapability as z };
+export { storageEvictableCapability as $, defaultDeviceFor as A, invocationFromEncodeProfile as B, addonWidgetsSourceCapability as C, literal as Ct, cameraStreamsCapability as D, string as Dt, buildFfmpegArgs as E, record as Et, egressTranscodeSharingKey as F, pickDetailCropConvention as G, mapAudioLabelToMacro as H, egressTransportFromRequest as I, pipelineRunnerCapability as J, pickNativeLeaseOverride as K, enumerateInferenceDevices as L, deriveDetailCropRect as M, deriveRecordingMode as N, createHwAccelCache as O, union as Ot, detectionPipelineCapability as P, runtimeDevices as Q, evaluateZoneRules as R, YAMNET_TO_MACRO as S, lazy as St, audioAnalyzerCapability as T, object as Tt, maskUrlCredentials as U, isSoftwareDecode as V, motionDetectionCapability as W, recordingExportCapability as X, recordingCapability as Y, resolveEgressDecodeHwAccel as Z, OpsLogEntrySchema as _, sleep as _t, COCO_80_LABELS as a, CAM_PROFILE_ORDER as at, RecordingConfigSchema as b, boolean as bt, DEFAULT_DETAIL_CROP_CONVENTION as c, createEvent as ct, EVENT_PAD_MS as d, makeProfileBrokerId as dt, streamBrokerCapability as et, EncodeProfileSchema as f, makeSourceBrokerId as ft, NativeLeaseSettingsSchema as g, selectAssignedProfileSlots as gt, NativeLeaseAdmissionSchema as h, parseProfileBrokerId as ht, AUDIO_PRESETS as i, BaseAddon as it, defineCustomActions as j, customAction as k, EventCategory as kt, DEFAULT_NATIVE_LEASE_SETTINGS as l, hydrateSchema as lt, HF_BASE_URL as m, parseJsonUnknown as mt, AUDIO_BACKEND_CHOICES as n, webrtcSessionCapability as nt, COCO_TO_MACRO as o, DeviceFeature as ot, ExportRecordSchema as p, nodePin as pt, pipelineExecutorCapability as q, AUDIO_MACRO_LABELS as r, errMsg as rt, DEFAULT_AUDIO_ANALYZER_CONFIG as s, DeviceType as st, APPLE_SA_TO_MACRO as t, supportedRuntimes as tt, DEVICE_BACKEND_TO_FORMAT as u, isEvent as ut, RATE_CONTROL_RELAXED as v, _enum as vt, audioAnalysisCapability as w, number as wt, RingBuffer as x, discriminatedUnion as xt, RATE_CONTROL_TIGHT as y, array as yt, hfModelUrl as z };