@camstack/addon-pipeline 1.2.42 → 1.2.44

package/dist/{dist-BdDd3ql_.js → dist-BuFE5rOK.js}

@@ -1,3 +1,4 @@
+let node_crypto = require("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 (0, node_crypto.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 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 TrackSourceSchema = _enum(["pipeline", "sensor"]);
+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"
@@ -29546,6 +31034,12 @@ Object.defineProperty(exports, "AUDIO_MACRO_LABELS", {
 		return AUDIO_MACRO_LABELS;
 	}
 });
+Object.defineProperty(exports, "AUDIO_PRESETS", {
+	enumerable: true,
+	get: function() {
+		return AUDIO_PRESETS;
+	}
+});
 Object.defineProperty(exports, "BaseAddon", {
 	enumerable: true,
 	get: function() {
@@ -29582,6 +31076,12 @@ Object.defineProperty(exports, "DEFAULT_DETAIL_CROP_CONVENTION", {
 		return DEFAULT_DETAIL_CROP_CONVENTION;
 	}
 });
+Object.defineProperty(exports, "DEFAULT_NATIVE_LEASE_SETTINGS", {
+	enumerable: true,
+	get: function() {
+		return DEFAULT_NATIVE_LEASE_SETTINGS;
+	}
+});
 Object.defineProperty(exports, "DEVICE_BACKEND_TO_FORMAT", {
 	enumerable: true,
 	get: function() {
@@ -29630,12 +31130,36 @@ Object.defineProperty(exports, "HF_BASE_URL", {
 		return HF_BASE_URL;
 	}
 });
+Object.defineProperty(exports, "NativeLeaseAdmissionSchema", {
+	enumerable: true,
+	get: function() {
+		return NativeLeaseAdmissionSchema;
+	}
+});
+Object.defineProperty(exports, "NativeLeaseSettingsSchema", {
+	enumerable: true,
+	get: function() {
+		return NativeLeaseSettingsSchema;
+	}
+});
 Object.defineProperty(exports, "OpsLogEntrySchema", {
 	enumerable: true,
 	get: function() {
 		return OpsLogEntrySchema;
 	}
 });
+Object.defineProperty(exports, "RATE_CONTROL_RELAXED", {
+	enumerable: true,
+	get: function() {
+		return RATE_CONTROL_RELAXED;
+	}
+});
+Object.defineProperty(exports, "RATE_CONTROL_TIGHT", {
+	enumerable: true,
+	get: function() {
+		return RATE_CONTROL_TIGHT;
+	}
+});
 Object.defineProperty(exports, "RecordingConfigSchema", {
 	enumerable: true,
 	get: function() {
@@ -29690,6 +31214,12 @@ Object.defineProperty(exports, "boolean", {
 		return boolean;
 	}
 });
+Object.defineProperty(exports, "buildFfmpegArgs", {
+	enumerable: true,
+	get: function() {
+		return buildFfmpegArgs;
+	}
+});
 Object.defineProperty(exports, "cameraStreamsCapability", {
 	enumerable: true,
 	get: function() {
@@ -29702,6 +31232,12 @@ Object.defineProperty(exports, "createEvent", {
 		return createEvent;
 	}
 });
+Object.defineProperty(exports, "createHwAccelCache", {
+	enumerable: true,
+	get: function() {
+		return createHwAccelCache;
+	}
+});
 Object.defineProperty(exports, "customAction", {
 	enumerable: true,
 	get: function() {
@@ -29744,6 +31280,18 @@ Object.defineProperty(exports, "discriminatedUnion", {
 		return discriminatedUnion;
 	}
 });
+Object.defineProperty(exports, "egressTranscodeSharingKey", {
+	enumerable: true,
+	get: function() {
+		return egressTranscodeSharingKey;
+	}
+});
+Object.defineProperty(exports, "egressTransportFromRequest", {
+	enumerable: true,
+	get: function() {
+		return egressTransportFromRequest;
+	}
+});
 Object.defineProperty(exports, "enumerateInferenceDevices", {
 	enumerable: true,
 	get: function() {
@@ -29774,12 +31322,24 @@ Object.defineProperty(exports, "hydrateSchema", {
 		return hydrateSchema;
 	}
 });
+Object.defineProperty(exports, "invocationFromEncodeProfile", {
+	enumerable: true,
+	get: function() {
+		return invocationFromEncodeProfile;
+	}
+});
 Object.defineProperty(exports, "isEvent", {
 	enumerable: true,
 	get: function() {
 		return isEvent;
 	}
 });
+Object.defineProperty(exports, "isSoftwareDecode", {
+	enumerable: true,
+	get: function() {
+		return isSoftwareDecode;
+	}
+});
 Object.defineProperty(exports, "lazy", {
 	enumerable: true,
 	get: function() {
@@ -29858,6 +31418,12 @@ Object.defineProperty(exports, "pickDetailCropConvention", {
 		return pickDetailCropConvention;
 	}
 });
+Object.defineProperty(exports, "pickNativeLeaseOverride", {
+	enumerable: true,
+	get: function() {
+		return pickNativeLeaseOverride;
+	}
+});
 Object.defineProperty(exports, "pipelineExecutorCapability", {
 	enumerable: true,
 	get: function() {
@@ -29888,6 +31454,12 @@ Object.defineProperty(exports, "recordingExportCapability", {
 		return recordingExportCapability;
 	}
 });
+Object.defineProperty(exports, "resolveEgressDecodeHwAccel", {
+	enumerable: true,
+	get: function() {
+		return resolveEgressDecodeHwAccel;
+	}
+});
 Object.defineProperty(exports, "runtimeDevices", {
 	enumerable: true,
 	get: function() {