@camstack/types 1.2.40 → 1.2.42

package/dist/index.js

@@ -1,6 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_event_category = require("./event-category-BE4PDZ_3.js");
-const require_sleep = require("./sleep-DTce7-ch.js");
+const require_sleep = require("./sleep-Cvi1JxZp.js");
+const require_canonical_hash = require("./canonical-hash-BcZHRHIx.js");
 const require_enums = require("./enums.js");
 const require_err_msg = require("./err-msg-COpsHMw2.js");
 let zod = require("zod");
@@ -147,6 +148,14 @@ var VideoEncodeSchema = zod.z.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: zod.z.string().optional(),
 	width: zod.z.number().int().positive().optional(),
 	height: zod.z.number().int().positive().optional(),
 	fps: zod.z.number().positive().optional(),
@@ -222,6 +231,560 @@ function encodeProfileFromStreamShape(stream) {
 	};
 }
 //#endregion
+//#region src/ffmpeg/invocation.ts
+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.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.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");
+}
+/**
+* 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 = inv.sink.kind === "stdout" ? [
+		"-f",
+		inv.sink.container,
+		"pipe:1"
+	] : [
+		"-f",
+		"rtsp",
+		"-rtsp_transport",
+		"tcp",
+		"-rtsp_flags",
+		"listen",
+		inv.sink.url
+	];
+	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" } : {
+		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 } : {},
+		...v.fps !== void 0 ? { fps: v.fps } : {},
+		...v.gopFrames !== void 0 ? { gopFrames: v.gopFrames } : {},
+		...v.bf !== void 0 ? { bf: v.bf } : {},
+		...v.bitrateKbps !== void 0 ? { bitrateKbps: v.bitrateKbps } : {}
+	};
+	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 } : {}
+	};
+}
+//#endregion
+//#region src/ffmpeg/encode-defaults.ts
+/**
+* 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"
+};
+/**
+* The browser WebRTC viewer's transcode profile. Used only when the broker
+* MUST spawn ffmpeg (source codec ∉ the browser-accepted set — an H.265 source
+* on an H.264-only browser). Audio is `passthrough` because werift carries the
+* audio plane out-of-band; putting it in the video pipeline would encode a
+* track nothing reads.
+*/
+var WEBRTC_EGRESS_PROFILE = {
+	...BASE_LIVE_EGRESS_PROFILE,
+	video: {
+		...BASE_LIVE_EGRESS_PROFILE.video,
+		bitrateKbps: 3e3,
+		gopFrames: 30,
+		preset: "ultrafast"
+	},
+	audio: "passthrough"
+};
+/**
+* Alexa's egress profile. Alexa's audio ALSO rides the WebRTC session's own
+* audio plane (out-of-band), so this is `passthrough` exactly like the browser
+* — see the ADR for why the previous in-band Opus was encoded and discarded.
+*/
+var ALEXA_EGRESS_PROFILE = {
+	...BASE_LIVE_EGRESS_PROFILE,
+	audio: "passthrough"
+};
+/** 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
+};
+/**
+* Transcode-DOWN ceiling: the shape a remote/unhealthy WebRTC session is
+* reduced to. 360p / 400 kbps is the `low` rung of the adaptive ladder — a
+* session steered here is already failing, so the ceiling is chosen to survive
+* a bad link, not to look good.
+*/
+var TRANSCODE_DOWN_MAX_HEIGHT = 360;
+var TRANSCODE_DOWN_MAX_BITRATE_KBPS = 400;
+/**
+* HomeKit's two-way audio leg. `lowdelay` + a short frame duration because the
+* leg is interactive; `globalHeader` because HAP owns the SDP and ffmpeg must
+* not put extradata in-band. `sampleRateHz` and `frameDurationMs` are
+* NEGOTIATED per session — the controller picks them — so they are absent here
+* and filled in by the caller.
+*/
+var HAP_AUDIO_BITRATE_KBPS = 24;
+var HAP_AUDIO_BASE = {
+	kind: "encode",
+	codec: "opus",
+	bitrateKbps: 24,
+	channels: 1,
+	application: "lowdelay",
+	globalHeader: true,
+	filter: "aresample=async=1000:first_pts=0"
+};
+/** HomeKit's `-bufsize` for the audio plane — four seconds of its 24 kbps. */
+var HAP_AUDIO_VBV_KBITS = 96;
+/** Seconds between forced IDRs on a HomeKit transcode. */
+var HAP_KEYFRAME_INTERVAL_SEC = 4;
+//#endregion
+//#region src/ffmpeg/hwaccel.ts
+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;
+}
+//#endregion
+//#region src/ffmpeg/sharing-key.ts
+/**
+* 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.
+*/
+/** 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) {
+	return {
+		deviceId: request.deviceId,
+		source: request.source.kind === "profile" ? `profile:${request.source.profile}` : `cam-stream:${request.source.camStreamId}`,
+		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) {
+	return `egress:${require_canonical_hash.canonicalHash(canonicalEgressPlan(request))}`;
+}
+//#endregion
 //#region src/health/wiring-health.ts
 /**
 * Deep wiring healthcheck — snapshot of active reachability probes across
@@ -331,6 +894,246 @@ var DEFAULT_RETENTION = {
 	snapshotsDays: 14
 };
 //#endregion
+//#region src/interfaces/camera-switches.ts
+/**
+* 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
+* ([D61](../../../../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 |
+*
+* 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 five functions the operator named (2026-08-05). 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 five-button safety group.
+*/
+var CameraSwitchIdSchema = zod.z.enum([
+	"stream-broker",
+	"object-detection",
+	"audio-analysis",
+	"recording",
+	"notifications"
+]);
+/** Stable render order — broadest blast radius first. */
+var CAMERA_SWITCH_ORDER = [
+	"stream-broker",
+	"object-detection",
+	"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 = zod.z.discriminatedUnion("kind", [
+	zod.z.object({ kind: zod.z.literal("device-disabled") }),
+	zod.z.object({
+		kind: zod.z.literal("wrapper-binding"),
+		capName: zod.z.string()
+	}),
+	zod.z.object({ kind: zod.z.literal("recording-config") }),
+	zod.z.object({ kind: zod.z.literal("notification-mute") })
+]);
+/**
+* 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 = zod.z.enum(["no-provider", "source-unreachable"]);
+/**
+* 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 = zod.z.object({
+	id: CameraSwitchIdSchema,
+	label: zod.z.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: zod.z.string(),
+	/** False = do not render a control. `unavailableReason` says why. */
+	available: zod.z.boolean(),
+	unavailableReason: CameraSwitchUnavailableReasonSchema.optional(),
+	/** Current state. Meaningless when `available` is false — read it as `true`. */
+	enabled: zod.z.boolean(),
+	authority: CameraSwitchAuthoritySchema
+});
+/** The whole group for one camera. */
+var CameraSwitchGroupSchema = zod.z.object({
+	deviceId: zod.z.number().int(),
+	switches: zod.z.array(CameraSwitchSchema).readonly(),
+	/** Unix ms when the group was composed server-side. */
+	fetchedAt: zod.z.number()
+});
+/**
+* The wrapper capability each wrapper-backed switch controls. Named constants
+* because the same strings appear in `legacy-migrations.ts`, in
+* `isCapActiveForDevice` call sites and in the fake harness — a typo in any of
+* them is a switch that silently writes a binding nobody reads.
+*/
+var DETECTION_PIPELINE_CAP_NAME = "detection-pipeline";
+var AUDIO_ANALYSIS_CAP_NAME = "audio-analysis";
+/**
+* THE catalog. One entry per switch; the cost lines are the operator-facing
+* contract and are written to be true rather than reassuring.
+*/
+var CAMERA_SWITCH_CATALOG = {
+	"stream-broker": {
+		id: "stream-broker",
+		label: "Camera",
+		costWhenOff: "Off: the whole camera stops. No live view, no recording, no detection and no notifications — its streams are released and nothing dials it again until you turn it back on.",
+		authority: { kind: "device-disabled" }
+	},
+	"object-detection": {
+		id: "object-detection",
+		label: "Object detection & tracking",
+		costWhenOff: "Off: nothing is detected or tracked on this camera, so it produces no events — and with no events there are no object notifications and no event-triggered recording. Live view and continuous recording are unaffected.",
+		authority: {
+			kind: "wrapper-binding",
+			capName: DETECTION_PIPELINE_CAP_NAME
+		}
+	},
+	"audio-analysis": {
+		id: "audio-analysis",
+		label: "Audio detection & classification",
+		costWhenOff: "Off: no audio is decoded or classified for this camera. Tracks carry no audio labels and no audio-triggered rule can fire. Audio recorded alongside video is unaffected.",
+		authority: {
+			kind: "wrapper-binding",
+			capName: AUDIO_ANALYSIS_CAP_NAME
+		}
+	},
+	recording: {
+		id: "recording",
+		label: "Recording",
+		costWhenOff: "Off: nothing new is written to disk. Footage already recorded stays, but retention keeps deleting it — so this camera’s history shrinks and is not replaced. Your recording schedule is kept and resumes when you turn it back on.",
+		authority: { kind: "recording-config" }
+	},
+	notifications: {
+		id: "notifications",
+		label: "Notifications",
+		costWhenOff: "Off: this camera never notifies anyone, on any rule, with no expiry. Detection, events and recording carry on exactly as before — you simply stop being told about them.",
+		authority: { kind: "notification-mute" }
+	}
+};
+/** Resolve one switch's `{ available, enabled }` pair. */
+function resolveState(descriptor, input) {
+	switch (descriptor.authority.kind) {
+		case "device-disabled": return {
+			available: true,
+			enabled: !input.deviceDisabled
+		};
+		case "wrapper-binding": {
+			const capName = descriptor.authority.capName;
+			if (input.bindableCapNames === null || input.activeWrapperCapNames === null) return {
+				available: false,
+				enabled: true,
+				unavailableReason: "source-unreachable"
+			};
+			if (!input.bindableCapNames.includes(capName)) return {
+				available: false,
+				enabled: true,
+				unavailableReason: "no-provider"
+			};
+			return {
+				available: true,
+				enabled: input.activeWrapperCapNames.includes(capName)
+			};
+		}
+		case "recording-config":
+			if (input.recordingEnabled === null) return {
+				available: false,
+				enabled: true,
+				unavailableReason: "source-unreachable"
+			};
+			return {
+				available: true,
+				enabled: input.recordingEnabled
+			};
+		case "notification-mute":
+			if (input.notificationsMuted === null) return {
+				available: false,
+				enabled: true,
+				unavailableReason: "source-unreachable"
+			};
+			return {
+				available: true,
+				enabled: !input.notificationsMuted
+			};
+	}
+}
+/**
+* Pure derivation of the whole group. No I/O — the orchestrator gathers, this
+* decides, so the decision is testable without a hub.
+*
+* Order is {@link CAMERA_SWITCH_ORDER}; unavailable switches are RETURNED
+* rather than filtered out, so a client can explain the gap instead of
+* silently rendering four buttons where another camera shows five.
+*/
+function deriveCameraSwitches(input) {
+	return CAMERA_SWITCH_ORDER.map((id) => {
+		const descriptor = CAMERA_SWITCH_CATALOG[id];
+		const state = resolveState(descriptor, input);
+		return {
+			id: descriptor.id,
+			label: descriptor.label,
+			costWhenOff: descriptor.costWhenOff,
+			available: state.available,
+			...state.unavailableReason !== void 0 ? { unavailableReason: state.unavailableReason } : {},
+			enabled: state.enabled,
+			authority: descriptor.authority
+		};
+	});
+}
+/**
+* The ids an operator has switched OFF, for a status surface.
+*
+* This is the answer to "a disabled function must be visible as DISABLED, not
+* merely quiet": a camera reporting zero detections with
+* `switchedOff: ['object-detection']` was turned off; the same camera with an
+* empty list is broken. Unavailable switches never appear — a function nobody
+* provides was not switched off by anyone.
+*/
+function switchedOffIds(switches) {
+	return switches.filter((s) => s.available && !s.enabled).map((s) => s.id);
+}
+//#endregion
 //#region src/interfaces/device-capabilities/camera.ts
 /** Friendly display labels for stream quality IDs. */
 var STREAM_QUALITY_LABELS = {
@@ -526,14 +1329,16 @@ var OpsLogOpSchema = zod.z.enum([
 	"manual-delete",
 	"rescan",
 	"retention-run",
-	"relocate"
+	"relocate",
+	"orphan-audit"
 ]);
 /** Why the operation ran. */
 var OpsLogReasonSchema = zod.z.enum([
 	"retention",
 	"quota",
 	"manual",
-	"operator"
+	"operator",
+	"maintenance"
 ]);
 /** One audit row, shared verbatim by both domains. */
 var OpsLogEntrySchema = zod.z.object({
@@ -3314,6 +4119,100 @@ var RtpSourceSchema = zod.z.object({
 	encoder: zod.z.string(),
 	pipelineKey: zod.z.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 = zod.z.enum(["tight", "relaxed"]);
+var EgressTranscodeRequestSchema = zod.z.object({
+	deviceId: zod.z.number().int().nonnegative(),
+	/** Which published stream to read. */
+	source: zod.z.discriminatedUnion("kind", [zod.z.object({
+		kind: zod.z.literal("profile"),
+		profile: require_sleep.CamProfileSchema
+	}), zod.z.object({
+		kind: zod.z.literal("cam-stream"),
+		camStreamId: zod.z.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: zod.z.enum([
+		"dump_extra",
+		"h264_mp4toannexb",
+		"hevc_mp4toannexb"
+	]).optional(),
+	pixelFormat: zod.z.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: zod.z.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: zod.z.string().optional(),
+	/** Attribution for the broker panel. Never part of the sharing key. */
+	tag: zod.z.string().optional()
+});
+var EgressTranscodeSchema = zod.z.object({
+	/** Dial-able RTSP url (host-substituted when `hostname` was supplied). */
+	url: zod.z.string(),
+	/** Release handle. Refcounted — the child dies when the last holder releases. */
+	pipelineKey: zod.z.string(),
+	videoCodec: zod.z.enum(["H264", "H265"]),
+	resolution: zod.z.object({
+		width: zod.z.number().int().positive(),
+		height: zod.z.number().int().positive()
+	}),
+	transcoded: zod.z.boolean(),
+	encoder: zod.z.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: zod.z.string().nullable()
+});
 var streamBrokerCapability = {
 	name: "stream-broker",
 	scope: "system",
@@ -3485,6 +4384,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: require_sleep.method(EgressTranscodeRequestSchema, EgressTranscodeSchema, {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/** Drop one reference. The child dies when the last holder releases. */
+		releaseEgressTranscode: require_sleep.method(zod.z.object({ pipelineKey: zod.z.string() }), zod.z.object({
+			released: zod.z.boolean(),
+			refcount: zod.z.number().int().nonnegative()
+		}), {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
 		* ── Decoded audio-chunk plane (Phase 5 / D9) ──────────────────────
 		*
 		* The serialisable replacement for the live-object `IStreamBroker.
@@ -10029,12 +10962,13 @@ var NcConditionsSchema = zod.z.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: zod.z.enum([
 		"pipeline",
 		"onboard",
 		"sensor",
+		"audio",
 		"any"
 	]).optional(),
 	/**
@@ -10588,6 +11522,10 @@ var NC_CONDITION_CATALOG = [
 			{
 				value: "sensor",
 				label: "Sensor"
+			},
+			{
+				value: "audio",
+				label: "Audio marker"
 			}
 		],
 		operator: "in",
@@ -10598,7 +11536,7 @@ var NC_CONDITION_CATALOG = [
 			"package-event"
 		],
 		phase: "P1",
-		description: "pipeline / onboard / sensor; a record with no stamped source counts as pipeline."
+		description: "pipeline / onboard / sensor / audio; a record with no stamped source counts as pipeline."
 	},
 	{
 		id: "deviceState",
@@ -10950,6 +11888,35 @@ var notificationRulesCapability = {
 			auth: "admin"
 		}),
 		/**
+		* PERMANENT per-camera mute — the notifications half of the per-camera
+		* function switch group ([D61](../../../../docs/decisions/adr-0067.md)).
+		*
+		* Deliberately NOT a snooze. A snooze is bounded at
+		* {@link NC_SNOOZE_MAX_MINUTES} on purpose — "a snooze that could not
+		* expire would be an outage the operator asked for once and forgot" — and
+		* widening it to express "this camera never notifies" would destroy that
+		* property for every snooze. A mute is the other thing: an explicit,
+		* indefinite, admin-only decision, visible in the switch group next to the
+		* other four, and reported on `CameraStatus.switchedOff` so a silent
+		* camera never reads as a working one.
+		*
+		* Returned as ONE list rather than a per-camera query: the group's reader
+		* needs every camera's state, and a per-camera fan-out over the viewer's
+		* single WebSocket is N frames serialised on one socket.
+		*/
+		listDeviceMutes: require_sleep.method(zod.z.object({}), zod.z.object({ mutedDeviceIds: zod.z.array(zod.z.number().int()).readonly() }), { auth: "admin" }),
+		/**
+		* Mute or unmute one camera. Idempotent; an unmute of a camera that was
+		* never muted succeeds.
+		*/
+		setDeviceMuted: require_sleep.method(zod.z.object({
+			deviceId: zod.z.number().int(),
+			muted: zod.z.boolean()
+		}), zod.z.object({ success: zod.z.literal(true) }), {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
 		* Dry-run a rule against recently persisted records (object events for
 		* `immediate`, closed tracks for `track-end`). Mutation kind only to
 		* carry the full rule object safely; no side effects.
@@ -11367,12 +12334,60 @@ var TrackAudioLabelSchema = zod.z.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 = zod.z.enum(["pipeline", "sensor"]);
+var TrackSourceSchema = zod.z.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: zod.z.boolean().optional(),
+	/** Operator marked this track for diagnostic attention. */
+	debug: zod.z.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 = zod.z.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 = zod.z.object({
+	trackId: zod.z.string(),
+	markForTrain: zod.z.boolean(),
+	debug: zod.z.boolean()
+});
 var TrackSchema = zod.z.object({
 	trackId: zod.z.string(),
 	deviceId: zod.z.number(),
@@ -11415,7 +12430,8 @@ var TrackSchema = zod.z.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: zod.z.string(),
@@ -11636,7 +12652,8 @@ var KeyEventSchema = zod.z.object({
 	/** Highest-confidence ObjectEvent id for the track (empty when none). */
 	bestEventId: zod.z.string(),
 	/** Track lifetime in ms (lastSeen - firstSeen). */
-	windowMs: zod.z.number().optional()
+	windowMs: zod.z.number().optional(),
+	...TrackFlagFields
 });
 var TrackedDetectionSchema = zod.z.object({
 	trackId: zod.z.string(),
@@ -11721,16 +12738,32 @@ var RebuildObjectEmbeddingsInput = zod.z.object({
 	deviceId: zod.z.number().optional(),
 	since: zod.z.number().optional(),
 	until: zod.z.number().optional(),
+	/** Stop after this many tracks; the result reports whether more remain. */
+	maxTracks: zod.z.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: zod.z.string().optional(),
 	/**
-	* Fraction added on EACH side of the detection box before cropping.
-	* ~0.2 (a 1.4x window) gives CLIP the surroundings it is trained on; 0 is
-	* the pixel-tight crop the first implementation used.
+	* 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.
 	*/
-	cropMargin: zod.z.number().min(0).max(4).optional(),
-	/** Square the window before extracting, so a tall subject is not squashed. */
-	square: zod.z.boolean().optional(),
-	/** Stop after this many tracks; the result reports whether more remain. */
-	maxTracks: zod.z.number().int().positive().optional()
+	pacingMs: zod.z.number().int().nonnegative().optional()
 });
 /**
 * Result of emptying the CLIP index.
@@ -11763,6 +12796,24 @@ var RebuildStatusSchema = zod.z.object({
 	missingKeyFrame: zod.z.number(),
 	/** Tracks with no usable detection box. */
 	missingBbox: zod.z.number(),
+	/**
+	* 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: zod.z.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: zod.z.number(),
 	failed: zod.z.number(),
 	/** Set once a pass ends: true only when EVERYTHING was covered. */
 	complete: zod.z.boolean().nullable(),
@@ -11952,6 +13003,31 @@ var pipelineAnalyticsCapability = {
 			auth: "admin"
 		}),
 		/**
+		* Set the per-track operator flags (`markForTrain`, `debug`) on ONE track.
+		* The patch is PARTIAL — an omitted key is left untouched — because the
+		* three surfaces that write it (admin Events grid, viewer track detail,
+		* viewer cluster detail) each own one toggle and must not clobber the other.
+		*
+		* Writes the track ROW: `markForTrain`/`debug` are per-TRACK state, so they
+		* live where `label` and `importance` live, not in any per-device settings
+		* store. Updates the in-RAM active track too, so a flag set on a live track
+		* survives its expiry-time persist.
+		*
+		* `auth: 'protected'` (the default), NOT `admin`: the viewer is an
+		* authenticated non-admin surface and two of the three call sites are
+		* there. Revisit if a flag ever gains an effect that costs storage —
+		* `deleteTracks` next door is admin for exactly that reason.
+		*
+		* Returns the RESOLVED state of both flags (absent → `false`) so a caller
+		* can drive its toggle without a re-fetch. Rejects an unknown track.
+		*/
+		setTrackFlags: require_sleep.method(zod.z.object({
+			/** Log/audit scope only — the trackId is globally unique on its own. */
+			deviceId: zod.z.number(),
+			trackId: zod.z.string(),
+			flags: TrackFlagsPatchSchema
+		}), TrackFlagsSchema, { kind: "mutation" }),
+		/**
 		* Durable event-store footprint for the management UI: event rows
 		* (motion + object + audio) counted per camera + total, plus the
 		* event-owned media bytes on disk per camera + total. Stat/count-based,
@@ -12840,6 +13916,53 @@ var DetailResultSchema = zod.z.object({
 	nativeFaceShortSidePx: zod.z.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 = zod.z.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 = zod.z.discriminatedUnion("kind", [zod.z.object({
+	kind: zod.z.literal("ran"),
+	/** The node that actually executed it — the pin, echoed back for the log. */
+	nodeId: zod.z.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: zod.z.string(),
+	details: zod.z.array(DetailResultSchema)
+}), zod.z.object({
+	kind: zod.z.literal("refused"),
+	nodeId: zod.z.string(),
+	reason: StatelessStepRefusalSchema,
+	/** Human-readable specifics — the format tried, the formats shipped, etc. */
+	detail: zod.z.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
@@ -13382,20 +14505,118 @@ var pipelineRunnerCapability = {
 		* for a single tracked detection. The per-frame plane (`runPipeline`
 		* with `plane: 'frame'`) skips crop children entirely; a track-level
 		* caller invokes this per-track, on its own cadence, instead of on
-		* every frame. Takes either a `frameHandle` (shm lease/session —
-		* preferred, zero-copy) or a `cropJpeg` fallback when the lease/
-		* session backing the frame is already gone. `steps` narrows which
-		* configured children to run (default: all configured children for
-		* `parent.className`). Returns `null` when neither frame source is
-		* resolvable (handle evicted and no cropJpeg fallback supplied).
+		* every frame. `steps` narrows which configured children to run
+		* (default: all configured children for `parent.className`).
+		*
+		* ## Three pixel sources, and WHO decides the rectangle
+		*
+		* Tried in this order; the difference between them is not the pixels but
+		* which side derives the crop, and confusing the two is how the CLIP index
+		* ended up holding two incomparable feature spaces:
+		*
+		* 1. `frameHandle` — shm lease/session, preferred and zero-copy. **The
+		*    runner cuts**, applying the cluster crop convention.
+		* 2. `frameJpeg` — a FULL FRAME supplied by the caller (the embedding
+		*    rebuild's stored key frame). **The runner cuts**, applying the same
+		*    convention to the same function, so a rebuilt vector lands in the same
+		*    feature space as a live one.
+		* 3. `cropJpeg` — an ALREADY-CUT tile. **The caller decided the
+		*    rectangle**; the runner applies NO padding and no squaring and feeds
+		*    it to the model verbatim. Only for the lease-miss retry, where the
+		*    caller holds pixels the runner can no longer reach.
+		*
+		* Returns `null` when no source resolves (handle evicted and no fallback
+		* supplied), when the camera is not attached, or when no enabled step
+		* matches — every one of those is logged on the runner with the deviceId.
 		*/
 		runDetailSubtree: require_sleep.method(zod.z.object({
 			deviceId: zod.z.number(),
 			frameHandle: require_sleep.FrameHandleSchema.optional(),
+			/**
+			* FULL FRAME (base64 JPEG). The runner derives the crop rectangle from
+			* `parent.bbox` with the cluster crop convention and cuts it itself —
+			* do NOT pre-crop for this field, that is what `cropJpeg` is.
+			*/
+			frameJpeg: zod.z.string().optional(),
+			/**
+			* PRE-CUT tile (base64 JPEG), used verbatim — NO padding is applied.
+			* The fallback when the lease/session backing the frame is gone and the
+			* caller already holds a crop.
+			*/
 			cropJpeg: zod.z.string().optional(),
 			parent: DetailParentSchema,
 			steps: zod.z.array(zod.z.string()).optional()
-		}), zod.z.object({ details: zod.z.array(DetailResultSchema) }).nullable(), { kind: "mutation" })
+		}), zod.z.object({ details: zod.z.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: require_sleep.method(zod.z.object({
+			/** Catalog step id, e.g. `clip-embedding`. */
+			stepId: zod.z.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: zod.z.string(),
+			/** FULL FRAME, base64 JPEG. The runner cuts — do NOT pre-crop. */
+			frameJpeg: zod.z.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: zod.z.string(),
+			/** Camera the pixels came from. Diagnostics + log tags ONLY — never routing. */
+			sourceDeviceId: zod.z.number()
+		}), RunStatelessStepResultSchema, { kind: "mutation" })
 	}
 };
 //#endregion
@@ -13705,6 +14926,20 @@ var CameraStatusSchema = zod.z.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: zod.z.array(CameraSwitchIdSchema).readonly(),
 	/** Unix timestamp (ms) when this snapshot was composed server-side. */
 	fetchedAt: zod.z.number()
 });
@@ -14104,6 +15339,43 @@ var pipelineOrchestratorCapability = {
 			agentNodeId: zod.z.string().optional()
 		}), CameraPipelineConfigSchema),
 		/**
+		* The whole per-camera function switch group, DERIVED — never a stored
+		* list ([D61](../../../../docs/decisions/adr-0067.md)).
+		*
+		* The group adds no state. Each switch is a view onto the authority that
+		* already owned it (`deviceManager.setDisabled`,
+		* `deviceManager.setWrapperActive`, `RecordingConfig.enabled`,
+		* `notificationRules.setDeviceMuted`), and `switch.authority` says which.
+		* Availability comes from `deviceManager.listBindableCapsForDeviceType`,
+		* so a deployment with no audio analyzer renders no audio switch.
+		*
+		* `auth: 'view'` deliberately — a NON-admin must be able to see that a
+		* camera is quiet because somebody switched it off. Only the mutation is
+		* admin-gated.
+		*/
+		getCameraSwitches: require_sleep.method(zod.z.object({ deviceId: zod.z.number() }), CameraSwitchGroupSchema),
+		/**
+		* Flip ONE switch, routed to its existing authority.
+		*
+		* Never writes a parallel map: `recording` patches `RecordingConfig.enabled`
+		* and leaves `bands` byte-identical (clearing bands to express "off"
+		* destroys the operator's authored schedule and turning the camera back on
+		* would silently record nothing), and the two pipeline switches write the
+		* SAME wrapper binding the legacy `pipelineEnabled` / `audioEnabled`
+		* booleans were migrated onto.
+		*
+		* Rejects a switch this camera does not offer rather than persisting a
+		* write nothing reads.
+		*/
+		setCameraSwitch: require_sleep.method(zod.z.object({
+			deviceId: zod.z.number(),
+			switchId: CameraSwitchIdSchema,
+			enabled: zod.z.boolean()
+		}), CameraSwitchGroupSchema, {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
 		* Server-composed aggregated status for a single camera.
 		*
 		* Fans out in parallel (bounded, per-stage graceful degradation) to
@@ -30124,6 +31396,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"notificationRules.listDeviceMutes": {
+		capName: "notification-rules",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"notificationRules.listRules": {
 		capName: "notification-rules",
 		capScope: "system",
@@ -30142,6 +31420,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"notificationRules.setDeviceMuted": {
+		capName: "notification-rules",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"notificationRules.setRuleEnabled": {
 		capName: "notification-rules",
 		capScope: "system",
@@ -30418,6 +31702,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.setTrackFlags": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineAnalytics.wipeAllAnalytics": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -30724,6 +32014,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineOrchestrator.getCameraSwitches": {
+		capName: "pipeline-orchestrator",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineOrchestrator.getCapabilityBindings": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
@@ -30856,6 +32152,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"pipelineOrchestrator.setCameraSwitch": {
+		capName: "pipeline-orchestrator",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineOrchestrator.setCapabilityBinding": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
@@ -30946,6 +32248,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"pipelineRunner.runStatelessStep": {
+		capName: "pipeline-runner",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"plateGallery.assignPlate": {
 		capName: "plate-gallery",
 		capScope: "system",
@@ -31762,6 +33070,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"streamBroker.acquireEgressTranscode": {
+		capName: "stream-broker",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"streamBroker.assignProfile": {
 		capName: "stream-broker",
 		capScope: "system",
@@ -31870,6 +33184,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"streamBroker.releaseEgressTranscode": {
+		capName: "stream-broker",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"streamBroker.releaseStreamWithCodec": {
 		capName: "stream-broker",
 		capScope: "system",
@@ -33282,7 +34602,8 @@ function createSystemProxy(api) {
 			getLocalMetrics: (input) => dispatch("pipelineRunner", "getLocalMetrics", "query", input),
 			getAllCameraMetrics: (input) => dispatch("pipelineRunner", "getAllCameraMetrics", "query", input),
 			getLocalCameras: (input) => dispatch("pipelineRunner", "getLocalCameras", "query", input),
-			getNativeCrop: (input) => dispatch("pipelineRunner", "getNativeCrop", "query", input)
+			getNativeCrop: (input) => dispatch("pipelineRunner", "getNativeCrop", "query", input),
+			runStatelessStep: (input) => dispatch("pipelineRunner", "runStatelessStep", "mutation", input)
 		},
 		plateGallery: {
 			getPlateMedia: (input) => dispatch("plateGallery", "getPlateMedia", "query", input),
@@ -33369,6 +34690,8 @@ function createSystemProxy(api) {
 			getStreamUrl: (input) => dispatch("streamBroker", "getStreamUrl", "query", input),
 			getStreamWithCodec: (input) => dispatch("streamBroker", "getStreamWithCodec", "mutation", input),
 			releaseStreamWithCodec: (input) => dispatch("streamBroker", "releaseStreamWithCodec", "mutation", input),
+			acquireEgressTranscode: (input) => dispatch("streamBroker", "acquireEgressTranscode", "mutation", input),
+			releaseEgressTranscode: (input) => dispatch("streamBroker", "releaseEgressTranscode", "mutation", input),
 			subscribeAudioChunks: (input) => dispatch("streamBroker", "subscribeAudioChunks", "mutation", input),
 			pullAudioChunks: (input) => dispatch("streamBroker", "pullAudioChunks", "query", input),
 			unsubscribeAudioChunks: (input) => dispatch("streamBroker", "unsubscribeAudioChunks", "mutation", input),
@@ -34881,6 +36204,202 @@ function pointInPolygon(point, polygon) {
 	return inside;
 }
 //#endregion
+//#region src/pipeline/detail-crop.ts
+/**
+* THE detail-crop convention — the single derivation of the rectangle a
+* detail/enrichment step (clip-embedding, face-detection, plate-detection…)
+* is fed.
+*
+* ## Why this is one module and not two constants
+*
+* `object-clip` is ONE vector index, and cosine similarity is only meaningful
+* between vectors produced from the same crop convention. Two encode paths
+* write into it — the live detail plane and the embedding rebuild — and they
+* used to derive their crops independently: `DETAIL_CROP_PADDING_RATIO = 0.15`
+* with no squaring on one side, `DEFAULT_CROP_MARGIN = 0.2` with squaring on
+* by default on the other. Every rebuild therefore poured a second, silently
+* incomparable feature space into the index it exists to keep consistent.
+*
+* So the rectangle is derived HERE, once, from ONE convention value. Both
+* paths now reach this function through `pipelineRunner.runDetailSubtree` —
+* the runner is the only process that cuts (see `detail-subtree.ts`), and the
+* convention is a cluster-global `pipeline-orchestrator` setting. There is
+* deliberately no per-node or per-device scope: a per-accelerator crop margin
+* would reintroduce the same split, merely relocated.
+*
+* ## The default IS the live convention
+*
+* {@link DEFAULT_DETAIL_CROP_CONVENTION} reproduces what the live path has
+* been storing (0.15, no squaring). Anything else would invalidate every
+* vector already in the index on the day it shipped. Changing the convention
+* is legitimate — that is what the operator knob is for — but it must be
+* followed by a rebuild, which is now guaranteed to produce crops from this
+* same function.
+*/
+/**
+* Store identity of the convention in `pipeline-orchestrator`'s GLOBAL
+* (cluster-wide) settings.
+*
+* These live here rather than in the orchestrator because the reader is a
+* different addon — the pipeline runner, over the hub-routed `addon-settings`
+* cap. Addons never import each other, so a key owned by the writer would have
+* to be hand-copied by the reader, and a hand-copied key is how a setting
+* silently stops arriving while both sides still look correct.
+*/
+var DETAIL_CROP_SECTION_ID = "detail-crop";
+var DETAIL_CROP_PADDING_KEY = "detailCropPaddingRatio";
+var DETAIL_CROP_SQUARE_KEY = "detailCropSquare";
+/**
+* Operator-tunable crop convention. Single-valued and cluster-wide — see the
+* module docblock for why it cannot be scoped per node or per device.
+*/
+var DetailCropConventionSchema = zod.z.object({
+	/**
+	* Fraction of the box's own size added on EACH side before cutting.
+	*
+	* CLIP is trained on natural images WITH surroundings; a pixel-tight crop
+	* removes exactly the context it is strongest on (a dog cut to its outline
+	* is a dark blob). The right value is an empirical question, which is why it
+	* is a setting: 0 / 0.15 / 0.2 / 0.5 are the interesting points.
+	*/
+	paddingRatio: zod.z.number().min(0).max(4),
+	/**
+	* Square the window (in PIXELS) before cutting.
+	*
+	* CLIP's input is square, so a tall bbox resized straight to NxN is squashed
+	* — a standing person becomes a shape the model never saw. Squaring costs
+	* extra background, which is context the model wants anyway. Off by default
+	* because the live path has never squared and the stored index reflects that.
+	*/
+	square: zod.z.boolean()
+});
+/**
+* The convention in force when nobody has configured one — byte-for-byte the
+* behaviour of the pre-unification LIVE path (`DETAIL_CROP_PADDING_RATIO`).
+*/
+var DEFAULT_DETAIL_CROP_CONVENTION = {
+	paddingRatio: .15,
+	square: false
+};
+/**
+* Narrow a FLAT settings record to the convention.
+*
+* Per-FIELD fallback, deliberately: a junk padding must not also discard a
+* valid squaring choice. An absent or invalid value resolves to
+* {@link DEFAULT_DETAIL_CROP_CONVENTION} — the historical live behaviour —
+* rather than to a clamped number nobody chose, so a bad read can never
+* quietly change what the stored vectors mean.
+*/
+function readDetailCropConvention(config) {
+	const paddingRatio = DetailCropConventionSchema.shape.paddingRatio.safeParse(config[DETAIL_CROP_PADDING_KEY]);
+	const square = DetailCropConventionSchema.shape.square.safeParse(config[DETAIL_CROP_SQUARE_KEY]);
+	return {
+		paddingRatio: paddingRatio.success ? paddingRatio.data : DEFAULT_DETAIL_CROP_CONVENTION.paddingRatio,
+		square: square.success ? square.data : DEFAULT_DETAIL_CROP_CONVENTION.square
+	};
+}
+function isHydratedField(entry) {
+	return typeof entry === "object" && entry !== null && "key" in entry;
+}
+/**
+* Extract the convention from an `addon-settings.getGlobalSettings` payload.
+*
+* Walks EVERY section rather than looking inside {@link DETAIL_CROP_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 default. A `null` payload
+* (addon mid-boot) is the default convention.
+*/
+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 (entry.key === "detailCropPaddingRatio" || entry.key === "detailCropSquare") flat[entry.key] = entry.value;
+	}
+	return readDetailCropConvention(flat);
+}
+/** Slider bounds for the operator-facing padding knob (orchestrator settings UI). */
+var DETAIL_CROP_PADDING_FIELD = {
+	min: 0,
+	max: 1,
+	step: .05,
+	default: DEFAULT_DETAIL_CROP_CONVENTION.paddingRatio
+};
+/**
+* Derive the crop rectangle for one parent detection.
+*
+* Order: pad by `paddingRatio` of the box's own size → optionally square in
+* pixel space around the padded centre → keep it inside the frame. Pure:
+* always returns a new rect and never mutates `bbox`.
+*
+* Edge handling differs by mode, on purpose:
+*
+* - **unsquared** — TRUNCATED at the frame border, byte-for-byte what the live
+*   path has always done (`padAndClampFrameBbox`). A subject against the edge
+*   gets a slightly smaller window. Changing this would silently reinterpret
+*   every edge-touching vector already in the index.
+* - **squared** — SLID inward instead, because a truncated square is not
+*   square and squaring exists precisely to preserve the aspect the model
+*   sees. It only shrinks when the square is larger than the frame itself.
+*/
+function deriveDetailCropRect(bbox, frameWidth, frameHeight, convention) {
+	const padX = convention.paddingRatio * bbox.w;
+	const padY = convention.paddingRatio * bbox.h;
+	const padded = {
+		x: bbox.x - padX,
+		y: bbox.y - padY,
+		w: bbox.w + 2 * padX,
+		h: bbox.h + 2 * padY
+	};
+	return convention.square ? slideInsideFrame(squareInPixels(padded, frameWidth, frameHeight), frameWidth, frameHeight) : truncateToFrame(padded, frameWidth, frameHeight);
+}
+/**
+* Grow the shorter side to the longer one around the window's centre, bounded
+* by the frame's shorter side — a square larger than the frame cannot exist,
+* and collapsing to the frame's short side is the most that does.
+*/
+function squareInPixels(rect, frameWidth, frameHeight) {
+	const side = Math.min(Math.max(rect.w, rect.h), Math.min(frameWidth, frameHeight));
+	const cx = rect.x + rect.w / 2;
+	const cy = rect.y + rect.h / 2;
+	return {
+		x: cx - side / 2,
+		y: cy - side / 2,
+		w: side,
+		h: side
+	};
+}
+/**
+* Cut the window at the frame border — the pre-unification live behaviour,
+* preserved exactly so unsquared crops keep matching the stored index.
+*/
+function truncateToFrame(rect, frameWidth, frameHeight) {
+	const x1 = Math.max(0, rect.x);
+	const y1 = Math.max(0, rect.y);
+	const x2 = Math.min(frameWidth, rect.x + rect.w);
+	const y2 = Math.min(frameHeight, rect.y + rect.h);
+	return {
+		x: x1,
+		y: y1,
+		w: Math.max(0, x2 - x1),
+		h: Math.max(0, y2 - y1)
+	};
+}
+/**
+* Move the window inside the frame keeping its extent — used only for squared
+* windows, where truncating would destroy the squareness that is the point.
+*/
+function slideInsideFrame(rect, frameWidth, frameHeight) {
+	const w = Math.max(0, Math.min(rect.w, frameWidth));
+	const h = Math.max(0, Math.min(rect.h, frameHeight));
+	return {
+		x: Math.min(Math.max(0, rect.x), Math.max(0, frameWidth - w)),
+		y: Math.min(Math.max(0, rect.y), Math.max(0, frameHeight - h)),
+		w,
+		h
+	};
+}
+//#endregion
 //#region src/helpers/bind-addon-actions.ts
 /**
 * Bind an addon's custom-action catalog to its tRPC surface, returning a
@@ -35133,10 +36652,13 @@ function enumerateInferenceDevices(hw) {
 }
 //#endregion
 exports.ACCESSORY_LABEL = ACCESSORY_LABEL;
+exports.ALEXA_EGRESS_PROFILE = ALEXA_EGRESS_PROFILE;
 exports.ALL_CAPABILITY_DEFINITIONS = ALL_CAPABILITY_DEFINITIONS;
 exports.APPLE_SA_TO_MACRO = APPLE_SA_TO_MACRO;
+exports.AUDIO_ANALYSIS_CAP_NAME = AUDIO_ANALYSIS_CAP_NAME;
 exports.AUDIO_BACKEND_CHOICES = AUDIO_BACKEND_CHOICES;
 exports.AUDIO_MACRO_LABELS = AUDIO_MACRO_LABELS;
+exports.AUDIO_PRESETS = AUDIO_PRESETS;
 exports.AccessoriesStatusSchema = AccessoriesStatusSchema;
 exports.AccessoryKind = AccessoryKind;
 exports.AddBrokerInputSchema = AddBrokerInputSchema;
@@ -35190,6 +36712,7 @@ exports.AutoUpdateSettingsSchema = AutoUpdateSettingsSchema;
 exports.AutomationControlStatusSchema = AutomationControlStatusSchema;
 exports.AvailableIntegrationTypeSchema = AvailableIntegrationTypeSchema;
 exports.BACKEND_TO_FORMAT = BACKEND_TO_FORMAT;
+exports.BASE_LIVE_EGRESS_PROFILE = BASE_LIVE_EGRESS_PROFILE;
 exports.BATTERY_DEVICE_PROFILE = BATTERY_DEVICE_PROFILE;
 exports.BacklightModeSchema = BacklightModeSchema;
 exports.BackupDestinationInfoSchema = BackupDestinationInfoSchema;
@@ -35222,6 +36745,8 @@ exports.BrokerSubscribeInputSchema = SubscribeInputSchema;
 exports.BrokerSubscribeResultSchema = SubscribeResultSchema;
 exports.BrokerTestConnectionResultSchema = TestConnectionResultSchema;
 exports.BrokerUnsubscribeInputSchema = UnsubscribeInputSchema;
+exports.CAMERA_SWITCH_CATALOG = CAMERA_SWITCH_CATALOG;
+exports.CAMERA_SWITCH_ORDER = CAMERA_SWITCH_ORDER;
 exports.CAM_PROFILE_ORDER = require_sleep.CAM_PROFILE_ORDER;
 exports.CAPABILITY_NAMES = CAPABILITY_NAMES;
 exports.CAPABILITY_ROUTER_KEYS = CAPABILITY_ROUTER_KEYS;
@@ -35255,6 +36780,11 @@ exports.CameraSourceStatusSchema = CameraSourceStatusSchema;
 exports.CameraSourceStreamSchema = CameraSourceStreamSchema;
 exports.CameraStatusSchema = CameraStatusSchema;
 exports.CameraStreamSchema = require_sleep.CameraStreamSchema;
+exports.CameraSwitchAuthoritySchema = CameraSwitchAuthoritySchema;
+exports.CameraSwitchGroupSchema = CameraSwitchGroupSchema;
+exports.CameraSwitchIdSchema = CameraSwitchIdSchema;
+exports.CameraSwitchSchema = CameraSwitchSchema;
+exports.CameraSwitchUnavailableReasonSchema = CameraSwitchUnavailableReasonSchema;
 exports.CandidateQueryFilterSchema = CandidateQueryFilterSchema;
 exports.CapScopeSchema = CapScopeSchema;
 exports.CapabilityBindingsSchema = CapabilityBindingsSchema;
@@ -35300,10 +36830,16 @@ exports.DATAPLANE_SECRET_HEADER = require_sleep.DATAPLANE_SECRET_HEADER;
 exports.DEFAULT_ADDON_PLACEMENT = DEFAULT_ADDON_PLACEMENT;
 exports.DEFAULT_AUDIO_ANALYZER_CONFIG = DEFAULT_AUDIO_ANALYZER_CONFIG;
 exports.DEFAULT_DECODER_HWACCEL_CONFIG = DEFAULT_DECODER_HWACCEL_CONFIG;
+exports.DEFAULT_DETAIL_CROP_CONVENTION = DEFAULT_DETAIL_CROP_CONVENTION;
 exports.DEFAULT_EVENT_COLOR = DEFAULT_EVENT_COLOR;
 exports.DEFAULT_FEATURES = DEFAULT_FEATURES;
 exports.DEFAULT_RETENTION = DEFAULT_RETENTION;
 exports.DEFAULT_SCRUB_THUMBNAIL_PRESET = DEFAULT_SCRUB_THUMBNAIL_PRESET;
+exports.DETAIL_CROP_PADDING_FIELD = DETAIL_CROP_PADDING_FIELD;
+exports.DETAIL_CROP_PADDING_KEY = DETAIL_CROP_PADDING_KEY;
+exports.DETAIL_CROP_SECTION_ID = DETAIL_CROP_SECTION_ID;
+exports.DETAIL_CROP_SQUARE_KEY = DETAIL_CROP_SQUARE_KEY;
+exports.DETECTION_PIPELINE_CAP_NAME = DETECTION_PIPELINE_CAP_NAME;
 exports.DEVICE_BACKEND_TO_FORMAT = DEVICE_BACKEND_TO_FORMAT;
 exports.DEVICE_CAP_NAMES = DEVICE_CAP_NAMES;
 exports.DEVICE_PROFILES = DEVICE_PROFILES;
@@ -35323,6 +36859,7 @@ exports.DecodedFrameSchema = require_sleep.DecodedFrameSchema;
 exports.DecoderSessionConfigSchema = DecoderSessionConfigSchema;
 exports.DecoderStatsSchema = DecoderStatsSchema;
 exports.DeleteIntegrationResultSchema = DeleteIntegrationResultSchema;
+exports.DetailCropConventionSchema = DetailCropConventionSchema;
 exports.DetectionSourceSchema = DetectionSourceSchema;
 exports.DeviceCodeSeveritySchema = DeviceCodeSeveritySchema;
 exports.DeviceConfig = DeviceConfig;
@@ -35395,6 +36932,10 @@ exports.FrameInputSchema = FrameInputSchema;
 exports.GasStatusSchema = GasStatusSchema;
 exports.GetStreamWithCodecInputSchema = GetStreamWithCodecInputSchema;
 exports.GlobalMetricsSchema = GlobalMetricsSchema;
+exports.HAP_AUDIO_BASE = HAP_AUDIO_BASE;
+exports.HAP_AUDIO_BITRATE_KBPS = HAP_AUDIO_BITRATE_KBPS;
+exports.HAP_AUDIO_VBV_KBITS = HAP_AUDIO_VBV_KBITS;
+exports.HAP_KEYFRAME_INTERVAL_SEC = HAP_KEYFRAME_INTERVAL_SEC;
 exports.HF_BASE_URL = HF_BASE_URL;
 exports.HF_REPO = HF_REPO;
 exports.HWACCEL_OPTIONS = HWACCEL_OPTIONS;
@@ -35628,6 +37169,8 @@ exports.PtzPositionSchema = PtzPositionSchema;
 exports.PtzPresetSchema = PtzPresetSchema;
 exports.PtzStatusSchema = PtzStatusSchema;
 exports.QueryFilterSchema = QueryFilterSchema;
+exports.RATE_CONTROL_RELAXED = RATE_CONTROL_RELAXED;
+exports.RATE_CONTROL_TIGHT = RATE_CONTROL_TIGHT;
 exports.REACHABILITY_FAILURES_TO_OFFLINE = REACHABILITY_FAILURES_TO_OFFLINE;
 exports.REACHABILITY_POLL_INTERVAL_MS = REACHABILITY_POLL_INTERVAL_MS;
 exports.REACHABILITY_PROBE_TIMEOUT_MS = REACHABILITY_PROBE_TIMEOUT_MS;
@@ -35754,6 +37297,8 @@ exports.SystemMetricsSchema = SystemMetricsSchema;
 exports.SystemMirror = SystemMirror;
 exports.TAXONOMY_COLORS = TAXONOMY_COLORS;
 exports.TIMEZONES = TIMEZONES;
+exports.TRANSCODE_DOWN_MAX_BITRATE_KBPS = TRANSCODE_DOWN_MAX_BITRATE_KBPS;
+exports.TRANSCODE_DOWN_MAX_HEIGHT = TRANSCODE_DOWN_MAX_HEIGHT;
 exports.TamperStatusSchema = TamperStatusSchema;
 exports.TankStatusSchema = TankStatusSchema;
 exports.TargetKindCapsSchema = TargetKindCapsSchema;
@@ -35776,8 +37321,11 @@ exports.TopologyProcessSchema = TopologyProcessSchema;
 exports.TopologyServiceSchema = TopologyServiceSchema;
 exports.TrackCascadeCountsSchema = TrackCascadeCountsSchema;
 exports.TrackEnvelopeSchema = TrackEnvelopeSchema;
+exports.TrackFlagsPatchSchema = TrackFlagsPatchSchema;
+exports.TrackFlagsSchema = TrackFlagsSchema;
 exports.TrackProjectionSchema = TrackProjectionSchema;
 exports.TrackSchema = TrackSchema;
+exports.TrackSourceSchema = TrackSourceSchema;
 exports.TrackStateSchema = TrackStateSchema;
 exports.TrackZoneFilterSchema = TrackZoneFilterSchema;
 exports.TrackedDetectionSchema = TrackedDetectionSchema;
@@ -35813,6 +37361,7 @@ exports.VectorUpsertInputSchema = VectorUpsertInputSchema;
 exports.VectorUpsertResultSchema = VectorUpsertResultSchema;
 exports.VibrationStatusSchema = VibrationStatusSchema;
 exports.VideoEncodeSchema = VideoEncodeSchema;
+exports.WEBRTC_EGRESS_PROFILE = WEBRTC_EGRESS_PROFILE;
 exports.WELL_KNOWN_TABS = require_sleep.WELL_KNOWN_TABS;
 exports.WELL_KNOWN_TAB_MAP = require_sleep.WELL_KNOWN_TAB_MAP;
 exports.WaterHeaterStatusSchema = WaterHeaterStatusSchema;
@@ -35859,6 +37408,7 @@ exports.audioAnalysisCapability = audioAnalysisCapability;
 exports.audioAnalyzerCapability = audioAnalyzerCapability;
 exports.audioCodecCapability = audioCodecCapability;
 exports.audioMetricsCapability = audioMetricsCapability;
+exports.audioPlanFromEncodeProfile = audioPlanFromEncodeProfile;
 exports.authProviderCapability = authProviderCapability;
 exports.autoAssignProfiles = autoAssignProfiles;
 exports.automationControlCapability = automationControlCapability;
@@ -35870,15 +37420,20 @@ exports.bindAddonActions = bindAddonActions;
 exports.brightnessCapability = brightnessCapability;
 exports.brokerCapability = brokerCapability;
 exports.buildAddonRouteProvider = buildAddonRouteProvider;
+exports.buildAudioArgs = buildAudioArgs;
 exports.buildEventKindDescriptor = buildEventKindDescriptor;
+exports.buildFfmpegArgs = buildFfmpegArgs;
+exports.buildInputArgs = buildInputArgs;
 exports.buildModelVariantGroups = buildModelVariantGroups;
 exports.buildNcTaxonomy = buildNcTaxonomy;
 exports.buildStreamParamsConfigSchema = buildStreamParamsConfigSchema;
+exports.buildVideoArgs = buildVideoArgs;
 exports.buttonCapability = buttonCapability;
 exports.cameraCredentialsCapability = cameraCredentialsCapability;
 exports.cameraPipelineConfigCapability = cameraPipelineConfigCapability;
 exports.cameraStreamsCapability = cameraStreamsCapability;
 exports.canConvertUnit = canConvertUnit;
+exports.canonicalEgressPlan = canonicalEgressPlan;
 exports.carbonMonoxideCapability = carbonMonoxideCapability;
 exports.cellsToRects = cellsToRects;
 exports.classifyStream = classifyStream;
@@ -35902,6 +37457,7 @@ exports.createDeviceProxy = require_sleep.createDeviceProxy;
 exports.createDurableState = require_sleep.createDurableState;
 exports.createEvent = require_sleep.createEvent;
 exports.createExpressionScope = createExpressionScope;
+exports.createHwAccelCache = createHwAccelCache;
 exports.createLazyTrpcSource = require_sleep.createLazyTrpcSource;
 exports.createMirrorSource = require_sleep.createMirrorSource;
 exports.createRuntimeStateBridge = createRuntimeStateBridge;
@@ -35915,6 +37471,8 @@ exports.decodeVectorBase64 = decodeVectorBase64;
 exports.decoderCapability = decoderCapability;
 exports.defaultDeviceFor = defaultDeviceFor;
 exports.defineCustomActions = defineCustomActions;
+exports.deriveCameraSwitches = deriveCameraSwitches;
+exports.deriveDetailCropRect = deriveDetailCropRect;
 exports.deriveRecordingMode = deriveRecordingMode;
 exports.describeModelVariant = describeModelVariant;
 exports.detectionPipelineCapability = detectionPipelineCapability;
@@ -35930,6 +37488,7 @@ exports.deviceProviderCapability = deviceProviderCapability;
 exports.deviceStateCapability = deviceStateCapability;
 exports.deviceStatusCapability = deviceStatusCapability;
 exports.doorbellCapability = doorbellCapability;
+exports.egressTranscodeSharingKey = egressTranscodeSharingKey;
 exports.embeddingEncoderCapability = embeddingEncoderCapability;
 exports.emitDownForOwnedCaps = require_sleep.emitDownForOwnedCaps;
 exports.emitReadiness = require_sleep.emitReadiness;
@@ -35972,6 +37531,7 @@ exports.imageCapability = imageCapability;
 exports.imageSettingsCapability = imageSettingsCapability;
 exports.integrationsCapability = integrationsCapability;
 exports.intercomCapability = intercomCapability;
+exports.invocationFromEncodeProfile = invocationFromEncodeProfile;
 exports.isAgentOnlyPlacement = isAgentOnlyPlacement;
 exports.isArrayOutputSchema = isArrayOutputSchema;
 exports.isBaseConditionKey = isBaseConditionKey;
@@ -35982,6 +37542,7 @@ exports.isDeviceScopedCap = require_sleep.isDeviceScopedCap;
 exports.isEvent = require_sleep.isEvent;
 exports.isNode = isNode;
 exports.isObjectInput = isObjectInput;
+exports.isSoftwareDecode = isSoftwareDecode;
 exports.isVoidInput = isVoidInput;
 exports.jobKindSchema = jobKindSchema;
 exports.kebabToCamel = kebabToCamel;
@@ -35996,6 +37557,7 @@ exports.llmRuntimeCapability = llmRuntimeCapability;
 exports.localNetworkCapability = localNetworkCapability;
 exports.locationSimilarity = locationSimilarity;
 exports.lockControlCapability = lockControlCapability;
+exports.logBannerArgs = logBannerArgs;
 exports.logDestinationCapability = logDestinationCapability;
 exports.logLevelAtMost = logLevelAtMost;
 exports.loginMethodCapability = loginMethodCapability;
@@ -36042,7 +37604,9 @@ exports.parseProfileBrokerId = require_sleep.parseProfileBrokerId;
 exports.parseStreamParamsFormPatch = parseStreamParamsFormPatch;
 exports.petFeederCapability = petFeederCapability;
 exports.pickAccessoryControl = pickAccessoryControl;
+exports.pickDetailCropConvention = pickDetailCropConvention;
 exports.pickPreferredRtspEntry = pickPreferredRtspEntry;
+exports.pickVideoEncoder = pickVideoEncoder;
 exports.pickerForCondition = pickerForCondition;
 exports.pipelineAnalyticsCapability = pipelineAnalyticsCapability;
 exports.pipelineExecutorCapability = pipelineExecutorCapability;
@@ -36059,6 +37623,7 @@ exports.procedureAuthKey = procedureAuthKey;
 exports.ptzAutotrackCapability = ptzAutotrackCapability;
 exports.ptzCapability = ptzCapability;
 exports.pythonScriptForBackend = pythonScriptForBackend;
+exports.readDetailCropConvention = readDetailCropConvention;
 exports.readDeviceStateFrom = readDeviceStateFrom;
 exports.readNodePin = require_sleep.readNodePin;
 exports.readinessKey = require_sleep.readinessKey;
@@ -36075,6 +37640,7 @@ exports.resolveCapMount = require_sleep.resolveCapMount;
 exports.resolveDetectionRuntime = resolveDetectionRuntime;
 exports.resolveDeviceControlKind = resolveDeviceControlKind;
 exports.resolveDeviceProfile = resolveDeviceProfile;
+exports.resolveEgressDecodeHwAccel = resolveEgressDecodeHwAccel;
 exports.resolveFormat = resolveFormat;
 exports.resolveHydratedFieldValue = require_sleep.resolveHydratedFieldValue;
 exports.resolveModelFormat = resolveModelFormat;
@@ -36111,6 +37677,7 @@ exports.streamQualityLabel = streamQualityLabel;
 exports.subKindsOf = subKindsOf;
 exports.supportedRuntimes = supportedRuntimes;
 exports.switchCapability = switchCapability;
+exports.switchedOffIds = switchedOffIds;
 exports.synthesizeSourceInfo = synthesizeSourceInfo;
 exports.systemCapability = systemCapability;
 exports.tamperCapability = tamperCapability;