@camstack/system 1.2.254 → 1.2.255

package/dist/{dist-CnQsUe15.js → dist-BJj6Akye.js}

@@ -1,4 +1,5 @@
 let zod = require("zod");
+require("node:crypto");
 //#region ../types/dist/event-category-BVDXG4tB.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
@@ -1025,6 +1026,22 @@ function typeOf(field) {
 	}
 }
 /**
+* Narrow a SystemEvent to a typed event by checking its category.
+* Returns `true` (and narrows the type) if the category matches.
+*
+* @example
+* ```typescript
+* eventBus.subscribe({ category: 'addon.started' }, (event) => {
+*   if (isEvent(event, 'addon.started')) {
+*     event.data.addonId  // ✓ typed as string
+*   }
+* })
+* ```
+*/
+function isEvent(event, category) {
+	return event.category === category;
+}
+/**
 * Create a typed event with less boilerplate.
 *
 * @example
@@ -3387,6 +3404,360 @@ function sleep(ms) {
 	return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
 }
 //#endregion
+//#region ../types/dist/canonical-hash-biq7T_dN.mjs
+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.lowDelay === true) args.push("-flags", "low_delay");
+	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;
+}
+/**
+* Derive the output `-map` selectors. The three cases, in the order they are
+* decided:
+*
+* 1. **A filter graph** — the picture is the graph's declared video pad, and
+*    the audio is its audio pad when it has one, otherwise input 0's mic. A
+*    graph's output is not addressable any other way.
+* 2. **N inputs, no graph** — map input 0 EXPLICITLY. ffmpeg's own selection
+*    picks the "best" stream across ALL inputs, so the egress would silently
+*    become whichever camera happens to have the largest frame.
+* 3. **One input, no graph** — no `-map`. Anything else would change the argv
+*    of every call site that exists today for no gain.
+*/
+function resolveStreamMaps(selection) {
+	const graph = selection.filterGraph;
+	if (graph) return {
+		video: `[${graph.videoOutLabel}]`,
+		audio: graph.audioOutLabel ? `[${graph.audioOutLabel}]` : "0:a:0?"
+	};
+	if (selection.extraInputs?.length) return {
+		video: "0:v:0",
+		audio: "0:a:0?"
+	};
+	return {
+		video: null,
+		audio: null
+	};
+}
+/** The `-vf` filter args, or `[]` when a consumer `-vf` already claims the slot. */
+function buildVideoFilterArgs(scale, outputArgs, filterGraph) {
+	if (filterGraph) {
+		if (scale) throw new Error("FfmpegInvocation: video.scale cannot be combined with a filter graph — scale inside the graph instead (the -vf would feed an output the graph already feeds)");
+		if (outputArgs.some((a) => a === "-vf")) throw new Error("FfmpegInvocation: outputArgs carries a -vf while a filter graph feeds the same output — fold the filter into the graph");
+		return [];
+	}
+	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, filterGraph) {
+	if (video.kind === "copy") {
+		if (filterGraph) throw new Error("FfmpegInvocation: a filter graph produces a NEW picture, so video.kind must be `encode`");
+		return [
+			"-c:v",
+			"copy",
+			...video.bitstreamFilter ? ["-bsf:v", video.bitstreamFilter] : []
+		];
+	}
+	const args = [
+		...buildVideoFilterArgs(video.scale, outputArgs, filterGraph),
+		"-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.singleSlicePerFrame === true && video.encoder === "libx264") args.push("-x264-params", "sliced-threads=0");
+	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"
+	];
+}
+/**
+* How far BELOW the negotiated fragment length `-min_frag_duration` is set.
+*
+* `-min_frag_duration` refuses to cut before that much media has accumulated,
+* and then waits for the next key frame. Set to exactly `fragmentMs`, the
+* commonest camera configuration in existence — a key-frame grid EQUAL to the
+* requested fragment length — lands the deadline on the same instant as the key
+* frame, loses the race, and skips to the following one: **every fragment comes
+* out at twice the requested length.**
+*
+* Measured on the live fleet 2026-08-07, camera 615, `-c:v copy` (D84):
+*
+* | slot | GOP | `-min_frag_duration` | median gap |
+* | --- | --- | --- | --- |
+* | 1280×720 | 40 f @ 10 fps = 4.0 s | 4000 ms | **7944 ms** |
+* | 1280×720 | 40 f @ 10 fps = 4.0 s | 3600 ms | 3973 ms |
+* | 3840×2160 | 100 f @ 25 fps = 4.0 s | 4000 ms | 8042 ms |
+* | 3840×2160 | 100 f @ 25 fps = 4.0 s | 3600 ms | 3998 ms |
+*
+* A doubled fragment is not a cosmetic overshoot: HKSV requires every fragment
+* to be no longer than the length the controller SELECTED, so the shipped-but-
+* inert phase-1 sink would have violated the contract on its first real clip.
+*
+* 10 % is chosen against the two failures either side of it. Too small and
+* ordinary jitter (measured spread 3953-4096 ms) re-loses the race; too large
+* and a source with a key frame slightly EARLY than the grid gets cut there,
+* yielding a short fragment for no reason.
+*/
+var FMP4_MIN_FRAG_MARGIN = .9;
+/** `-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 * FMP4_MIN_FRAG_MARGIN * 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>                         ─┘ …repeated per extraInput
+*   [-filter_complex <graph>]         ─ global, after the LAST -i
+*   [-map <video>]  <video block>  <threads>  ─┐ OUTPUT options.
+*   [-map <audio>]  <audio block>              │
+*   <consumer outputArgs verbatim>             │
+*   <sink>                                    ─┘ terminal
+*
+* The `-map`s are DERIVED (see {@link resolveStreamMaps}), never constants:
+* one input with no graph emits none at all, which is why the argv of every
+* call site that predates the N-input extension is unchanged to the byte.
+*
+* {@link FfmpegInvocation.audioSidecar} is the one map that stays literal
+* (`0:a:0?`): the sidecar is defined as the SOURCE's microphone on its own RTP
+* output, not as whatever the main output happens to carry.
+*/
+function buildFfmpegArgs(inv) {
+	const graph = inv.filterGraph ?? null;
+	const head = [
+		...logBannerArgs(inv.logLevel),
+		...buildInputArgs(inv.input, inv.decodeHwAccel),
+		...(inv.extraInputs ?? []).flatMap((extra) => buildInputArgs(extra, inv.decodeHwAccel)),
+		...graph ? ["-filter_complex", graph.graph] : []
+	];
+	const threadArgs = inv.threadCount > 0 ? ["-threads", String(inv.threadCount)] : [];
+	const maps = resolveStreamMaps(inv);
+	const videoMapArgs = maps.video ? ["-map", maps.video] : [];
+	const audioMapArgs = maps.audio ? ["-map", maps.audio] : [];
+	if (inv.sink.kind === "rtp-outputs") {
+		const videoLeg = inv.sink.video ? [
+			"-an",
+			"-map",
+			maps.video ?? "0:v:0",
+			...buildVideoArgs(inv.video, inv.outputArgs, graph),
+			...threadArgs,
+			...inv.outputArgs,
+			...buildRtpOutputArgs(inv.sink.video)
+		] : [];
+		const audioLeg = inv.sink.audio ? [
+			"-vn",
+			"-map",
+			maps.audio ?? "0:a:0?",
+			...buildAudioArgs(inv.audio),
+			...buildRtpOutputArgs(inv.sink.audio)
+		] : [];
+		return [
+			...head,
+			...videoLeg,
+			...audioLeg
+		];
+	}
+	const mutedAudio = isElementaryVideoSink(inv.sink) || inv.audio.kind === "none";
+	const audioArgs = isElementaryVideoSink(inv.sink) ? ["-an"] : buildAudioArgs(inv.audio);
+	return [
+		...head,
+		...videoMapArgs,
+		...buildVideoArgs(inv.video, inv.outputArgs, graph),
+		...threadArgs,
+		...mutedAudio ? [] : audioMapArgs,
+		...audioArgs,
+		...inv.outputArgs,
+		...buildStdoutOrRtspSinkArgs(inv.sink),
+		...inv.audioSidecar ? buildAudioSidecarArgs(inv.audioSidecar) : []
+	];
+}
+//#endregion
 //#region ../types/dist/err-msg-IQTHeDzc.mjs
 /**
 import { errMsg } from '@camstack/types'
@@ -3912,6 +4283,14 @@ var CameraSwitchGroupSchema = zod.z.object({
 	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 value a redacted secret is replaced with on every read surface.
 *
 * It is also the WRITE-BACK token: an `upsertLocation` that sends this value
@@ -10974,6 +11353,45 @@ var SourceInfoSchema = zod.z.object({
 	raw: zod.z.record(zod.z.string(), zod.z.unknown()).optional()
 });
 /**
+* Build the synthetic SourceInfo every existing provider falls back to
+* when no upstream value has been persisted. Keeps non-migrated providers
+* (Reolink / Hikvision / ONVIF / RTSP) functional without code
+* changes — `id` reuses the CamStack stableId, `system` reuses the addon
+* id. Real upstream identity replaces this once a provider migrates and
+* calls `updateSourceInfo()` with concrete values.
+*/
+function synthesizeSourceInfo(input) {
+	return {
+		id: input.stableId,
+		system: input.addonId
+	};
+}
+/**
+* Shallow-merge a partial patch over a prior SourceInfo. `undefined`
+* patch values are ignored (no field clobber); to clear a field
+* explicitly, providers omit it from the patch and rebuild from scratch
+* via `updateSourceInfo({})` cycles — uncommon enough that we don't
+* bother with a `null`-means-delete sentinel.
+*
+* The `raw` field is also shallow-merged: passing `raw: { foo: 1 }`
+* merges over existing `raw` keys instead of replacing the whole bag.
+*/
+function mergeSourceInfo(prev, patch) {
+	const next = { ...prev };
+	for (const [k, v] of Object.entries(patch)) {
+		if (v === void 0) continue;
+		if (k === "raw" && typeof v === "object" && v !== null) {
+			next.raw = {
+				...prev.raw,
+				...v
+			};
+			continue;
+		}
+		next[k] = v;
+	}
+	return next;
+}
+/**
 * Coerce common unit-of-measurement string variants to a canonical form
 * so the UI's display templates can rely on stable strings. Pure
 * passthrough for unknown units — kept conservative on purpose, the goal
@@ -11019,6 +11437,27 @@ function normalizeUnit(raw) {
 	return trimmed;
 }
 /**
+* Key under which `SourceInfo` lives inside `DeviceMeta.metadata`. The
+* blob is a free-form `Record<string, unknown>` shared with hardware-
+* identity fields (`manufacturer`, `model`, `firmware`, …); SourceInfo
+* lives under a single nested key to keep it composable with those.
+*/
+var SOURCE_INFO_METADATA_KEY = "sourceInfo";
+/**
+* Extract a SourceInfo from a `DeviceMeta.metadata` blob, validating
+* with Zod. Returns `null` when the blob is missing or the nested
+* `sourceInfo` key fails validation — callers fall back to the
+* synthetic default in that case (see `synthesizeSourceInfo`).
+*/
+function extractSourceInfoFromMetadata(metadata) {
+	if (!metadata) return null;
+	const raw = metadata[SOURCE_INFO_METADATA_KEY];
+	if (!raw) return null;
+	const parsed = SourceInfoSchema.safeParse(raw);
+	if (!parsed.success) return null;
+	return parsed.data;
+}
+/**
 * device-discovery — device-scoped capability for parents that host /
 * enumerate child devices (Reolink Hub / NVR, ONVIF gateway, future
 * integrations). The parent advertises a list of discoverable children,
@@ -33369,6 +33808,25 @@ var ptzAutotrackCapability = {
 	scope: "device",
 	deviceNative: true,
 	mode: "singleton",
+	/**
+	* Two kinds of provider behind one name, the same shape `snapshot` and
+	* `doorbell` use:
+	*
+	*  - **Native**: the camera's own firmware autotrack, registered per device by
+	*    the driver when the probe says it exists (Reolink: yes; Hikvision:
+	*    model-dependent).
+	*  - **Wrapper**: the emulated implementation (`@camstack/system`'s `autotrack` builtin),
+	*    which follows a subject with `ptz.move` pulses driven by the detection
+	*    pipeline. `defaultActive: false` — the operator binds it per camera in
+	*    the bindings UI, exactly as `virtual-doorbell` is bound.
+	*
+	* The binding chooses WHICH implementation answers; `setEnabled` stays the
+	* one switch for the function either way. A camera never has both driving its
+	* head, which is the whole reason this is not a second cap with a second
+	* toggle (D62, D520).
+	*/
+	kind: "wrapper",
+	defaultActive: false,
 	deviceTypes: [DeviceType.Camera],
 	deviceConfig: { ui: {
 		kind: "widget",
@@ -37511,6 +37969,807 @@ var AccessoryKind = {
 	PrivacyMask: DeviceRole.PrivacyMask
 };
 AccessoryKind.Siren, AccessoryKind.Floodlight, AccessoryKind.Spotlight, AccessoryKind.PirSensor, AccessoryKind.Chime, AccessoryKind.Autotrack, AccessoryKind.Nightvision, AccessoryKind.PrivacyMask;
+var DeviceConfig = class DeviceConfig {
+	schema;
+	data;
+	persistFn;
+	constructor(schema, data, persist) {
+		this.schema = schema;
+		this.data = data;
+		this.persistFn = persist;
+	}
+	/**
+	* Build a `DeviceConfig` from a persisted blob, with automatic
+	* recovery from schema-validation failures. Boot must never be
+	* blocked by stale persisted values: if Zod rejects the blob,
+	* we drop every offending top-level field, retry, and persist
+	* the cleaned blob so the bad value is healed in the DB on next
+	* write. The most common trigger is a tightened range constraint
+	* (e.g. `max(100) → max(50)`) on a field that already has an
+	* out-of-range value persisted from the previous schema. Without
+	* this safety net, the device would fail to instantiate and end
+	* up with no caps registered — exactly the failure mode that
+	* stranded device 15 when `motionSensitivity: 90` no longer fit
+	* the new `1..50` schema.
+	*
+	* Recovery rules:
+	*  1. Try `safeParse(initialData)`. If it succeeds, done.
+	*  2. On failure, walk `error.issues`, collect the top-level path
+	*     of each issue, and drop those keys from `initialData`.
+	*  3. Re-run `safeParse`. If the cleaned blob now passes (Zod
+	*     fills the missing keys with schema defaults / undefined for
+	*     `.optional()`), persist it via `persist()` so the bad
+	*     values disappear from the DB, and return the device.
+	*  4. If the cleaned blob STILL fails (very rare — would require
+	*     a non-recoverable required field), fall back to
+	*     `schema.parse({})` so the device still boots with pure
+	*     schema defaults. Persist nothing in that path so the next
+	*     successful `setAll` still writes a coherent blob.
+	*/
+	static fromSchema(schema, persist, initialData = {}, onRecover) {
+		const first = schema.safeParse(initialData);
+		if (first.success) return new DeviceConfig(schema, first.data, persist);
+		const droppedKeys = /* @__PURE__ */ new Set();
+		for (const issue of first.error.issues) {
+			const top = issue.path[0];
+			if (typeof top === "string") droppedKeys.add(top);
+		}
+		const cleaned = { ...initialData };
+		for (const k of droppedKeys) delete cleaned[k];
+		const second = schema.safeParse(cleaned);
+		onRecover?.({
+			droppedKeys: [...droppedKeys],
+			issues: first.error.issues
+		});
+		if (second.success) {
+			persist(second.data).catch(() => {});
+			return new DeviceConfig(schema, second.data, persist);
+		}
+		return new DeviceConfig(schema, schema.parse({}), persist);
+	}
+	get values() {
+		return this.data;
+	}
+	get(key) {
+		return this.data[key];
+	}
+	async set(key, value) {
+		const next = this.schema.parse({
+			...this.data,
+			[key]: value
+		});
+		this.data = next;
+		await this.persistFn(this.data);
+	}
+	/**
+	* Merge an untyped patch onto the current config and persist. Accepts
+	* `Record<string, unknown>` because the patch typically comes from the
+	* UI form layer (a `ConfigField.key → value` map) where the caller
+	* doesn't hold the Zod schema's static type. Runtime validation is
+	* authoritative: `this.schema.parse` rejects unknown keys or invalid
+	* shapes before touching storage.
+	*/
+	async setAll(partial) {
+		const next = this.schema.parse({
+			...this.data,
+			...partial
+		});
+		this.data = next;
+		await this.persistFn(this.data);
+	}
+	async deleteKey(key) {
+		const { [key]: _, ...rest } = this.data;
+		const next = this.schema.parse(rest);
+		this.data = next;
+		await this.persistFn(this.data);
+	}
+	entries() {
+		const shape = this.schema.shape;
+		return Object.entries(shape).map(([key, fieldSchema]) => ({
+			key,
+			schema: fieldSchema,
+			value: this.data[key],
+			description: fieldSchema.description
+		}));
+	}
+};
+/**
+* Concrete implementation. Routes every successful write through
+* `writer(capName, slice)` — the kernel hooks this up to
+* `device-state.setCapSlice`, the canonical cross-layer write
+* entrypoint, which handles disk persistence (debounced on the hub)
+* and mirror updates.
+*
+* Schema validation runs in-process before the writer is called —
+* the round-trip should never carry an invalid slice. `flush()`
+* awaits any in-flight writer promises so shutdown is lossless.
+*
+* `initial` is the persisted blob loaded at boot. Slices for caps
+* whose schema hasn't been installed yet are kept in-memory verbatim
+* and validated when the cap registers later.
+*/
+var DeviceRuntimeState = class DeviceRuntimeState {
+	writer;
+	/** In-flight writer promises tracked so `flush()` can await them. */
+	pendingWrites = /* @__PURE__ */ new Set();
+	/** Per-cap committed slice — after schema validation when known. */
+	slices;
+	/** Per-cap registered schema (set by `installCapSchema`). */
+	schemas = /* @__PURE__ */ new Map();
+	listeners = /* @__PURE__ */ new Set();
+	capListeners = /* @__PURE__ */ new Map();
+	constructor(initial, writer) {
+		this.writer = writer;
+		this.slices = /* @__PURE__ */ new Map();
+		for (const [k, v] of Object.entries(initial)) if (v && typeof v === "object" && !Array.isArray(v)) this.slices.set(k, { ...v });
+	}
+	static fromInitial(initial, writer) {
+		return new DeviceRuntimeState(initial, writer);
+	}
+	installCapSchema(capName, schema) {
+		const existing = this.schemas.get(capName);
+		if (existing) {
+			if (existing !== schema) throw new Error(`[DeviceRuntimeState] capability "${capName}" registered a different runtime-state schema; each cap must declare ONE shape across every provider`);
+			return;
+		}
+		this.schemas.set(capName, schema);
+		const stored = this.slices.get(capName);
+		if (stored) {
+			const result = schema.safeParse(stored);
+			if (result.success) this.slices.set(capName, result.data);
+			else this.slices.delete(capName);
+		}
+	}
+	getCapState(capName) {
+		const slice = this.slices.get(capName);
+		if (!slice) return void 0;
+		return Object.freeze({ ...slice });
+	}
+	getCapField(capName, key) {
+		return this.slices.get(capName)?.[key];
+	}
+	setCapState(capName, value) {
+		this.applyCapWrite(capName, value, false);
+	}
+	patchCapState(capName, partial) {
+		this.applyCapWrite(capName, partial, true);
+	}
+	/**
+	* Internal worker. `merge` controls whether `value` replaces or
+	* shallow-merges into the existing slice. Schema validation runs
+	* on the FINAL composed object regardless.
+	*/
+	applyCapWrite(capName, value, merge) {
+		const schema = this.schemas.get(capName);
+		if (!schema) throw new Error(`[DeviceRuntimeState] no schema registered for cap "${capName}" — did the device register it via ctx.registerNativeCap before writing?`);
+		const current = this.slices.get(capName) ?? {};
+		const next = merge ? {
+			...current,
+			...value
+		} : { ...value };
+		const parsed = schema.parse(next);
+		if (shallowEqual(current, parsed)) return;
+		this.slices.set(capName, parsed);
+		this.fireListeners([capName]);
+		const writePromise = this.writer(capName, { ...parsed }).catch(() => {});
+		this.pendingWrites.add(writePromise);
+		writePromise.finally(() => {
+			this.pendingWrites.delete(writePromise);
+		});
+	}
+	fireListeners(changed) {
+		const snap = this.snapshot();
+		for (const cb of this.listeners) try {
+			cb(changed, snap);
+		} catch {}
+		for (const capName of changed) {
+			const subs = this.capListeners.get(capName);
+			if (!subs) continue;
+			const slice = this.getCapState(capName);
+			for (const cb of subs) try {
+				cb(slice);
+			} catch {}
+		}
+	}
+	subscribe(cb) {
+		this.listeners.add(cb);
+		return () => {
+			this.listeners.delete(cb);
+		};
+	}
+	subscribeCap(capName, cb) {
+		let subs = this.capListeners.get(capName);
+		if (!subs) {
+			subs = /* @__PURE__ */ new Set();
+			this.capListeners.set(capName, subs);
+		}
+		const adapter = (slice) => {
+			cb(slice);
+		};
+		subs.add(adapter);
+		return () => {
+			const set = this.capListeners.get(capName);
+			if (!set) return;
+			set.delete(adapter);
+			if (set.size === 0) this.capListeners.delete(capName);
+		};
+	}
+	snapshot() {
+		const out = {};
+		for (const [k, v] of this.slices) out[k] = Object.freeze({ ...v });
+		return Object.freeze(out);
+	}
+	async flush() {
+		if (this.pendingWrites.size === 0) return;
+		const inflight = [...this.pendingWrites];
+		await Promise.allSettled(inflight);
+	}
+};
+function shallowEqual(a, b) {
+	const ak = Object.keys(a);
+	const bk = Object.keys(b);
+	if (ak.length !== bk.length) return false;
+	for (const k of ak) if (a[k] !== b[k]) return false;
+	return true;
+}
+/**
+* Runtime registry: cap-property-name → cap definition. `BaseDevice`'s
+* `state` getter looks up the cap definition here to construct a
+* `sliceProxy()` lazily on first access. Generated alongside the type
+* so type and runtime registry can never drift apart.
+*/
+var DEVICE_LOCAL_STATE_CAPS = {
+	airQualitySensor: airQualitySensorCapability,
+	alarmPanel: alarmPanelCapability,
+	ambientLightSensor: ambientLightSensorCapability,
+	audioMetrics: audioMetricsCapability,
+	automationControl: automationControlCapability,
+	battery: batteryCapability,
+	binary: binaryCapability,
+	brightness: brightnessCapability,
+	cameraStreams: cameraStreamsCapability,
+	carbonMonoxide: carbonMonoxideCapability,
+	climateControl: climateControlCapability,
+	color: colorCapability,
+	connectivity: connectivityCapability,
+	consumables: consumablesCapability,
+	contact: contactCapability,
+	control: controlCapability,
+	cover: coverCapability,
+	dayNight: dayNightCapability,
+	deviceDiscovery: deviceDiscoveryCapability,
+	deviceStatus: deviceStatusCapability,
+	doorbell: doorbellCapability,
+	enumSensor: enumSensorCapability,
+	eventEmitter: eventEmitterCapability,
+	fanControl: fanControlCapability,
+	featureProbe: featureProbeCapability,
+	flood: floodCapability,
+	gas: gasCapability,
+	humidifier: humidifierCapability,
+	humiditySensor: humiditySensorCapability,
+	image: imageCapability,
+	imageSettings: imageSettingsCapability,
+	intercom: intercomCapability,
+	lawnMowerControl: lawnMowerControlCapability,
+	lockControl: lockControlCapability,
+	mediaPlayer: mediaPlayerCapability,
+	motion: motionCapability,
+	motionTrigger: motionTriggerCapability,
+	motionZones: motionZonesCapability,
+	nativeObjectDetection: nativeObjectDetectionCapability,
+	navigation: navigationCapability,
+	networkLink: networkLinkCapability,
+	notifier: notifierCapability,
+	numericSensor: numericSensorCapability,
+	petFeeder: petFeederCapability,
+	powerMeter: powerMeterCapability,
+	presence: presenceCapability,
+	pressureSensor: pressureSensorCapability,
+	privacyMask: privacyMaskCapability,
+	ptzAutotrack: ptzAutotrackCapability,
+	recordingSignal: recordingSignalCapability,
+	sceneMonitor: sceneMonitorCapability,
+	scriptRunner: scriptRunnerCapability,
+	smoke: smokeCapability,
+	streamCatalog: streamCatalogCapability,
+	streamParams: streamParamsCapability,
+	streamSignals: streamSignalsCapability,
+	switch: switchCapability,
+	tamper: tamperCapability,
+	temperatureSensor: temperatureSensorCapability,
+	update: updateCapability,
+	vacuumControl: vacuumControlCapability,
+	valve: valveCapability,
+	vibration: vibrationCapability,
+	waterHeater: waterHeaterCapability,
+	weather: weatherCapability,
+	zoneAnalytics: zoneAnalyticsCapability,
+	zoneRules: zoneRulesCapability,
+	zones: zonesCapability
+};
+var BaseDevice = class {
+	id;
+	stableId;
+	type;
+	name;
+	parentDeviceId;
+	role;
+	/**
+	* Cap-keyed runtime-state slice is the single source of truth for
+	* `online`. Both getter and setter proxy to the slice — drivers can
+	* write `this.online = true` ergonomically, and the cap event fires
+	* automatically through the runtime-state writer. `markOnline()` is
+	* kept as the explicit method form mandated by `IDevice`.
+	*/
+	get online() {
+		return this.runtimeState.getCapState("device-status")?.online ?? false;
+	}
+	set online(value) {
+		this.markOnline(value);
+	}
+	/**
+	* Generic per-cap runtime-state namespace. One entry per cap with
+	* `runtimeState:` declared, auto-generated by codegen — see
+	* `device-local-state.ts`. Drivers access via:
+	*
+	*   `this.state.battery.sleeping = true`        // patches the battery slice
+	*   `const pct = this.state.battery.percentage` // reads the battery slice
+	*   `this.state.deviceStatus.online = true`     // mirrors `markOnline(true)`
+	*
+	* Adding a new cap with `runtimeState:` automatically extends this
+	* namespace — drivers don't have to declare proxies. Reads return
+	* `undefined` when the slice hasn't been seeded; writes patch via
+	* `runtimeState.patchCapState` and validate against the cap's schema
+	* (so partial writes need the slice to be seeded with the required
+	* fields first — drivers do this on cap registration).
+	*
+	* For caps not exposed in `DeviceLocalState`, drivers can build their
+	* own typed proxy via `this.sliceProxy(cap)`.
+	*/
+	get state() {
+		if (!this._stateProxyCache) {
+			const cache = {};
+			const handler = { get: (_target, key) => {
+				const k = key;
+				if (k in cache) return cache[k];
+				const cap = DEVICE_LOCAL_STATE_CAPS[k];
+				if (!cap) return void 0;
+				const proxy = this.sliceProxy(cap);
+				cache[k] = proxy;
+				return proxy;
+			} };
+			this._stateProxyCache = new Proxy(cache, handler);
+		}
+		return this._stateProxyCache;
+	}
+	_stateProxyCache;
+	config;
+	/**
+	* Per-device runtime state, cap-keyed. Always installed — slices
+	* for individual caps materialise as those caps register their
+	* native providers (`ctx.registerNativeCap`). The cap's own
+	* `runtimeState` schema is the source of truth for the slice
+	* shape; drivers don't redeclare it, they just write through.
+	*
+	* Read: `this.runtimeState.getCapState('battery')` →
+	*   `{percentage, charging, sleeping, lastUpdated}` for any
+	*   provider that registers `batteryCapability`.
+	* Write: `this.runtimeState.setCapState('battery', { … })`.
+	*
+	* Cross-process consumers reach this state through the
+	* `deviceState` cap router (or via cap-specific events the driver
+	* emits — e.g. `battery.onStatusChanged`). The local handle is
+	* accessed in-process by the driver to avoid roundtrips.
+	*/
+	runtimeState;
+	ctx;
+	/**
+	* Operator-organisational location label (room / area / zone).
+	* Read from `ctx.deviceMeta.location`; mutated via
+	* `kernel.devices.setLocation(id, value)`. Free-text — providers
+	* don't interpret it; the UI groups devices by this for filters
+	* like "show me all cameras in Kitchen". `null` when unset.
+	*/
+	location;
+	/**
+	* Soft-disabled flag. When `true`, the device class is still
+	* instantiated and visible in the UI (so the operator can flip
+	* back on without re-adding) but lifecycle hooks (publishToBroker,
+	* alarm-stream subscribe, …) MUST be gated by the driver to skip
+	* work. The `BaseDevice` enforces this by exposing the flag here;
+	* it does NOT mutate cap behaviour automatically — drivers consult
+	* `this.disabled` at the top of their lifecycle methods. Read from
+	* `ctx.deviceMeta.disabled`; mutated via
+	* `kernel.devices.setDisabled(id, value)`.
+	*/
+	disabled;
+	/**
+	* Cached materialised `SourceInfo` — either the value persisted under
+	* `metadata.sourceInfo` at construction time, or a synthetic
+	* `{ id: stableId, system: addonId }` for providers that haven't
+	* migrated yet. Lazily populated on first `sourceInfo` read so the
+	* cost of Zod-parsing the meta blob is paid once per device boot.
+	* Invalidated by `updateSourceInfo()` so providers see the new value
+	* back through the getter without a re-fetch from the meta surface.
+	*/
+	_sourceInfoCache = null;
+	constructor(ctx, schema, options) {
+		this.ctx = ctx;
+		this.id = ctx.id;
+		this.stableId = ctx.stableId;
+		this.type = options.type;
+		if (!ctx.deviceMeta) throw new Error(`BaseDevice constructor: ctx.deviceMeta is required (id=${ctx.id} stableId=${ctx.stableId})`);
+		this.name = ctx.deviceMeta.name;
+		this.location = ctx.deviceMeta.location;
+		this.disabled = ctx.deviceMeta.disabled;
+		this.role = options.role;
+		this.parentDeviceId = ctx.parentDeviceId;
+		const seedData = ctx.persistedConfig ?? {};
+		this.config = DeviceConfig.fromSchema(schema, (data) => ctx.persistConfig(data), seedData, ({ droppedKeys, issues }) => {
+			ctx.logger.warn("Device config recovery: dropping invalid persisted fields", {
+				tags: {
+					deviceId: ctx.id,
+					stableId: ctx.stableId
+				},
+				meta: {
+					droppedKeys: [...droppedKeys],
+					firstIssue: issues[0]?.message ?? null
+				}
+			});
+		});
+		let cachedProxy = null;
+		const writer = async (capName, slice) => {
+			if (!cachedProxy) cachedProxy = ctx.fetchDevice(ctx.id);
+			await (await cachedProxy).deviceState.setCapSlice({
+				capName,
+				slice
+			});
+		};
+		const initial = ctx.initialRuntimeState ?? {};
+		this.runtimeState = DeviceRuntimeState.fromInitial(initial, writer);
+		ctx.bindRuntimeState?.(this.runtimeState);
+		ctx.registerNativeCap?.(deviceStatusCapability, {});
+		const seed = {
+			online: true,
+			lastChangedAt: Date.now()
+		};
+		this.runtimeState.setCapState("device-status", seed);
+		ctx.registerNativeCap?.(featureProbeCapability, {});
+		this.runtimeState.setCapState("feature-probe", {
+			flags: {},
+			deviceType: null,
+			model: null,
+			channelCount: null,
+			lastProbedAt: 0,
+			lastFetchedAt: 0
+		});
+	}
+	deviceActions = /* @__PURE__ */ new Map();
+	/** Declare a device custom action + its typed handler. Idempotent per name. */
+	registerDeviceAction(name, spec, handler) {
+		this.deviceActions.set(name, {
+			spec,
+			handler
+		});
+	}
+	/** Invoke a registered device action. Validates input against the spec. */
+	async runDeviceAction(action, input) {
+		const entry = this.deviceActions.get(action);
+		if (!entry) throw new Error(`unknown device action "${action}" on device ${this.id}`);
+		const parsed = entry.spec.input.parse(input);
+		return entry.handler(parsed);
+	}
+	async removeDevice() {}
+	/**
+	* Set the device's online flag. Called by `BaseDeviceProvider` after
+	* aggregating per-profile stream-broker health, or directly by drivers
+	* that have provider-side liveness signals (e.g. ONVIF heartbeats,
+	* Reolink Baichuan firmware push events). Mirrors the new value into
+	* the `device-status` runtime-state slice so cross-process consumers
+	* pick it up via the standard cap-state channel. Subclasses can
+	* override to gate side effects on the transition.
+	*/
+	markOnline(online) {
+		if (this.online === online) return;
+		const next = {
+			online,
+			lastChangedAt: Date.now()
+		};
+		this.runtimeState.setCapState("device-status", next);
+	}
+	/**
+	* Upstream-system identity + rendering envelope for this device. See
+	* `SourceInfo` for the field contract. Always returns a valid object:
+	* if the persisted `metadata.sourceInfo` blob is absent or fails Zod
+	* validation, falls back to a synthetic `{ id: stableId, system: addonId }`
+	* so providers that haven't migrated keep working without code changes.
+	*
+	* The value is cached after the first read. `updateSourceInfo()`
+	* invalidates the cache so subsequent reads see the new patch. The
+	* returned object is frozen to prevent accidental in-place mutation —
+	* use `updateSourceInfo({ patch })` to change fields.
+	*/
+	get sourceInfo() {
+		if (this._sourceInfoCache) return this._sourceInfoCache;
+		const resolved = extractSourceInfoFromMetadata(this.ctx.deviceMeta.metadata) ?? synthesizeSourceInfo({
+			stableId: this.stableId,
+			addonId: this.ctx.deviceMeta.addonId
+		});
+		this._sourceInfoCache = Object.freeze({ ...resolved });
+		return this._sourceInfoCache;
+	}
+	/**
+	* Convenience accessor for the upstream dispatch key. Equivalent to
+	* `this.sourceInfo.id` — providers use this to keep a
+	* `Map<sourceId, IDevice>` for routing inbound push events.
+	*/
+	get sourceId() {
+		return this.sourceInfo.id;
+	}
+	/**
+	* Patch the device's `SourceInfo`. Shallow-merges `patch` over the
+	* current value, persists the merged result under
+	* `metadata.sourceInfo` via the `device-manager.setMetadata` cap, and
+	* emits `EventCategory.DeviceSourceInfoChanged` for live consumers.
+	*
+	* Safe to call from anywhere in the device's lifetime — the call is
+	* idempotent for `undefined` patch values (ignored) and best-effort
+	* for persistence (a transient device-manager error doesn't unwind
+	* the local cache update, so subsequent reads still see the patch).
+	*
+	* Drivers populate this on adoption + on every metadata change push
+	* from the upstream source. Subscribers (UI, export adapters) react
+	* via the `DeviceSourceInfoChanged` event without polling.
+	*/
+	async updateSourceInfo(patch) {
+		const next = mergeSourceInfo(this.sourceInfo, patch);
+		this._sourceInfoCache = Object.freeze({ ...next });
+		const action = this.ctx.api?.deviceManager?.setMetadata;
+		if (action) try {
+			await action.mutate({
+				deviceId: this.id,
+				patch: { [SOURCE_INFO_METADATA_KEY]: next }
+			});
+		} catch {}
+		this.ctx.eventBus.emit(createEvent("device.source-info-changed", {
+			type: "device",
+			id: this.stableId
+		}, {
+			deviceId: this.id,
+			sourceInfo: next
+		}));
+	}
+	/**
+	* Re-publish the device's current `features` array to the persisted
+	* meta blob. Drivers call this after a probe finishes when the live
+	* `features` getter has gained new flags (e.g. `hasIntercom` flips
+	* to true → `DeviceFeature.TwoWayAudio` joins the list).
+	*
+	* Without this, only the construction-time snapshot is written —
+	* `deviceManager.registerDevice` is invoked once per boot, so probe-
+	* driven additions don't reach the persisted index until the next
+	* server restart, and `getDevice` / `listAll` keep returning the
+	* stale list for forked-worker devices (whose live IDevice instance
+	* is invisible to the hub registry).
+	*
+	* Idempotent: re-calling with the same features just no-ops on the
+	* persisted meta. Best-effort: lookup or write failures are logged
+	* at debug and swallowed — the live `device.features` getter is
+	* still authoritative within this process, so callers never block
+	* device boot on a meta refresh.
+	*/
+	async refreshFeatures() {
+		const action = this.ctx.api?.deviceManager?.registerDevice;
+		if (!action) return;
+		try {
+			await action.mutate({
+				addonId: this.ctx.deviceMeta.addonId,
+				stableId: this.stableId,
+				id: this.id,
+				type: this.type,
+				name: this.name,
+				parentDeviceId: this.parentDeviceId,
+				features: [...this.features],
+				config: {}
+			});
+		} catch (err) {}
+	}
+	/**
+	* Typed read-through to a cap-keyed runtime-state slice. Drivers
+	* call `this.getCapSlice(batteryCapability)` and the return type
+	* is inferred from the cap's `runtimeState` Zod schema — no string
+	* key, no manual generic. Returns `null` when the slice hasn't
+	* been written yet (e.g. driver hasn't seeded battery yet).
+	*/
+	getCapSlice(cap) {
+		return this.runtimeState.getCapState(cap.name) ?? null;
+	}
+	/**
+	* Typed writer to a cap-keyed runtime-state slice. Routes through
+	* the runtime-state writer (validate → persist → emit cap event).
+	* Equivalent to `this.runtimeState.setCapState(cap.name, value)`
+	* but with the cap's `runtimeState` schema enforcing the value
+	* shape at compile time. Mirrors the symmetry of
+	* `getCapSlice` / `setCapSlice` for cross-cap consistency.
+	*/
+	setCapSlice(cap, value) {
+		this.runtimeState.setCapState(cap.name, value);
+	}
+	/**
+	* Field-level read/write proxy over a cap's runtime-state slice.
+	* Drivers that want ergonomic per-field access declare:
+	*
+	* ```ts
+	* protected battery = this.sliceProxy(batteryCapability)
+	* // …
+	* this.battery.sleeping = true        // patches the slice
+	* const charging = this.battery.charging  // reads the slice
+	* ```
+	*
+	* Reads return `undefined` when the slice hasn't been seeded yet
+	* (cap not registered, or seeded but the field is absent). Writes
+	* route through `runtimeState.patchCapState` so the cap's `runtimeState`
+	* schema validates the merged result and the cap event fires.
+	*
+	* Pattern is generic — same shape works for `battery`, `device-status`,
+	* `motion`, `doorbell`, anything with a `runtimeState:` schema. Drivers
+	* declare one proxy per cap they read/write directly.
+	*/
+	sliceProxy(cap) {
+		return new Proxy({}, {
+			get: (_, key) => {
+				return this.runtimeState.getCapState(cap.name)?.[key];
+			},
+			set: (_, key, value) => {
+				this.runtimeState.patchCapState(cap.name, { [key]: value });
+				return true;
+			},
+			has: (_, key) => {
+				const slice = this.runtimeState.getCapState(cap.name);
+				return slice ? key in slice : false;
+			},
+			ownKeys: () => {
+				const slice = this.runtimeState.getCapState(cap.name);
+				return slice ? Object.keys(slice) : [];
+			},
+			getOwnPropertyDescriptor: (_, key) => {
+				const slice = this.runtimeState.getCapState(cap.name);
+				if (!slice || !(key in slice)) return void 0;
+				return {
+					configurable: true,
+					enumerable: true,
+					value: slice[key]
+				};
+			}
+		});
+	}
+	/**
+	* Default empty settings UI. Drivers override this to expose an
+	* editable form in the device-details page. Returning an empty sections
+	* array signals "nothing to contribute" — the aggregator drops the
+	* contribution entirely rather than rendering a blank panel.
+	*/
+	getSettingsUISchema() {
+		return { sections: [] };
+	}
+	/**
+	* Default write path: forward the flat patch directly to storage.
+	* Drivers that project a UI shape different from storage (e.g. `RtspCamera`
+	* exposing `mainStreamUrl`/`subStreamUrl` over `streams[]`) override this
+	* to reshape before `config.setAll`.
+	*/
+	async applySettingsPatch(patch) {
+		await this.config.setAll(patch);
+	}
+	/**
+	* Phase 3 — populate device-scoped state needed by downstream phases
+	* (accessory reconciliation, public `features` array, optional cap
+	* registration). Called ONCE per construction, after register but
+	* before `getAccessoryChildren()`.
+	*
+	* Drivers write the `feature-probe` runtime-state slice via
+	* `this.runtimeState.setCapState('feature-probe', {...})` — flag bag
+	* is open (Reolink writes `hasPtz/hasIntercom`, Hikvision writes
+	* `hasSupplementalLight/hasAlarmIo`, etc).
+	*
+	* Default: nothing to probe → mark the device PROBED (set `lastProbedAt`) so
+	* the kernel treats it as ready immediately. A device that derives its shape
+	* from a spec (a container, or an accessory sensor) rather than from a
+	* hardware probe has no probe to "complete"; without stamping `lastProbedAt`
+	* it would look perpetually un-probed — logging "Initial probe did not
+	* complete" on every boot and spinning a pointless retry chain. Drivers that
+	* DO probe override this and write their own `feature-probe` slice (including
+	* `lastProbedAt`) once their probe actually succeeds.
+	*/
+	async onProbe() {
+		const base = this.runtimeState.getCapState("feature-probe") ?? {
+			flags: {},
+			deviceType: null,
+			model: null,
+			channelCount: null,
+			lastProbedAt: 0,
+			lastFetchedAt: 0
+		};
+		this.runtimeState.setCapState("feature-probe", {
+			...base,
+			lastProbedAt: Date.now()
+		});
+	}
+	/**
+	* Phase 5 — fired after the device + its accessories are registered.
+	* Drivers publish streams to the broker, kick off background tasks,
+	* or subscribe to lib events that need a fully-registered device id.
+	*
+	* Default: no-op.
+	*
+	* RENAMED FROM `onCreated` (which still exists for back-compat in this
+	* pass). The new name reflects the post-probe, post-accessory contract.
+	*/
+	async onActivate() {}
+	/**
+	* Re-run the probe + reconcile accessories + refresh features meta.
+	* Drivers call this when device-side state changes (battery cam wakes,
+	* firmware update, manual operator trigger).
+	*
+	* The kernel injects `_kernelReprobe` on registration so this method
+	* delegates to the same orchestrator that runs the boot-time phase
+	* 3 + 4 sequence. Drivers should NOT override this — they override
+	* `onProbe()` instead.
+	*/
+	async reprobe() {
+		if (this._kernelReprobe) await this._kernelReprobe();
+		else await this.onProbe();
+	}
+	/**
+	* Kernel-injected callback that runs the full post-probe orchestration
+	* (onProbe → registerDevice meta refresh → accessory reconciliation).
+	* Set by `device-cap-proxy.register()`. Drivers should not touch this
+	* directly — call `reprobe()` instead.
+	*/
+	_kernelReprobe;
+	/**
+	* Declare accessory child devices the kernel should auto-spawn
+	* after `onProbe()` resolves. Each spec fully describes one child
+	* — stableId suffix (deterministic per kind for restore-safety),
+	* meta (type / name / location), config (initial blob the child
+	* self-hydrates), and a factory that constructs the concrete
+	* class with whatever closure-captured refs it needs (typically
+	* `this` for the parent reference).
+	*
+	* The kernel handles the rest: allocateDeviceId, persistInitialConfig
+	* (skipped on restore when the row already exists),
+	* persistInitialMeta, createContext, factory invocation, register,
+	* and recursive lifecycle (probe + accessories + activate).
+	*
+	* Implementations should derive children from
+	* `this.runtimeState.getCapState('feature-probe')` (post-probe truth).
+	* Drivers can use the `getProbeFlags()` helper to read the flag bag
+	* with a typed cast.
+	*
+	* Default: no children.
+	*/
+	getAccessoryChildren() {
+		return [];
+	}
+	/**
+	* Read the current feature-probe flag bag with a typed cast. Helper
+	* for `getAccessoryChildren()` and `features` getters that derive
+	* outputs from the probe results.
+	*/
+	getProbeFlags() {
+		return this.runtimeState.getCapState("feature-probe")?.flags ?? {};
+	}
+	/**
+	* Returns true once `onProbe` has completed at least once
+	* (`lastProbedAt > 0`). Drivers gate `getAccessoryChildren()` on this
+	* to avoid spawning stale accessories on a fresh device whose probe
+	* hasn't landed yet.
+	*/
+	hasProbed() {
+		return (this.runtimeState.getCapState("feature-probe")?.lastProbedAt ?? 0) > 0;
+	}
+};
 /**
 * THE derivation. One crop rectangle, one presence verdict — see D52 for why
 * this repo insists a derived value has exactly one implementation.
@@ -47503,6 +48762,12 @@ Object.defineProperty(exports, "ALL_CAPABILITY_DEFINITIONS", {
 		return ALL_CAPABILITY_DEFINITIONS;
 	}
 });
+Object.defineProperty(exports, "AUDIO_ANALYSIS_CAP_NAME", {
+	enumerable: true,
+	get: function() {
+		return AUDIO_ANALYSIS_CAP_NAME;
+	}
+});
 Object.defineProperty(exports, "AlertSchema", {
 	enumerable: true,
 	get: function() {
@@ -47521,6 +48786,12 @@ Object.defineProperty(exports, "BaseAddon", {
 		return BaseAddon;
 	}
 });
+Object.defineProperty(exports, "BaseDevice", {
+	enumerable: true,
+	get: function() {
+		return BaseDevice;
+	}
+});
 Object.defineProperty(exports, "BatteryStatusSchema", {
 	enumerable: true,
 	get: function() {
@@ -47569,6 +48840,12 @@ Object.defineProperty(exports, "DEFAULT_FIRST_SIGHTING_FRESHNESS_MS", {
 		return DEFAULT_FIRST_SIGHTING_FRESHNESS_MS;
 	}
 });
+Object.defineProperty(exports, "DETECTION_PIPELINE_CAP_NAME", {
+	enumerable: true,
+	get: function() {
+		return DETECTION_PIPELINE_CAP_NAME;
+	}
+});
 Object.defineProperty(exports, "DEVICE_SETTINGS_CONTRIBUTION_METHODS", {
 	enumerable: true,
 	get: function() {
@@ -47617,6 +48894,12 @@ Object.defineProperty(exports, "EventCategory", {
 		return EventCategory;
 	}
 });
+Object.defineProperty(exports, "FIRST_LEVEL_MACRO_CLASSES", {
+	enumerable: true,
+	get: function() {
+		return FIRST_LEVEL_MACRO_CLASSES;
+	}
+});
 Object.defineProperty(exports, "LOG_LEVEL_RANK", {
 	enumerable: true,
 	get: function() {
@@ -47803,12 +49086,24 @@ Object.defineProperty(exports, "batteryCapability", {
 		return batteryCapability;
 	}
 });
+Object.defineProperty(exports, "buildFfmpegArgs", {
+	enumerable: true,
+	get: function() {
+		return buildFfmpegArgs;
+	}
+});
 Object.defineProperty(exports, "buildStreamParamsConfigSchema", {
 	enumerable: true,
 	get: function() {
 		return buildStreamParamsConfigSchema;
 	}
 });
+Object.defineProperty(exports, "cameraGridLayoutCapability", {
+	enumerable: true,
+	get: function() {
+		return cameraGridLayoutCapability;
+	}
+});
 Object.defineProperty(exports, "collectSecretConfigKeys", {
 	enumerable: true,
 	get: function() {
@@ -47845,6 +49140,12 @@ Object.defineProperty(exports, "dataStoreProviderCapability", {
 		return dataStoreProviderCapability;
 	}
 });
+Object.defineProperty(exports, "declarationOwnerNodeId", {
+	enumerable: true,
+	get: function() {
+		return declarationOwnerNodeId;
+	}
+});
 Object.defineProperty(exports, "decodeVectorBase64", {
 	enumerable: true,
 	get: function() {
@@ -47983,6 +49284,12 @@ Object.defineProperty(exports, "isDeviceConfigCap", {
 		return isDeviceConfigCap;
 	}
 });
+Object.defineProperty(exports, "isEvent", {
+	enumerable: true,
+	get: function() {
+		return isEvent;
+	}
+});
 Object.defineProperty(exports, "isLocationEnabled", {
 	enumerable: true,
 	get: function() {
@@ -48133,6 +49440,12 @@ Object.defineProperty(exports, "procedureAuthKey", {
 		return procedureAuthKey;
 	}
 });
+Object.defineProperty(exports, "ptzAutotrackCapability", {
+	enumerable: true,
+	get: function() {
+		return ptzAutotrackCapability;
+	}
+});
 Object.defineProperty(exports, "readinessKey", {
 	enumerable: true,
 	get: function() {
@@ -48253,6 +49566,12 @@ Object.defineProperty(exports, "storageProviderCapability", {
 		return storageProviderCapability;
 	}
 });
+Object.defineProperty(exports, "streamCatalogCapability", {
+	enumerable: true,
+	get: function() {
+		return streamCatalogCapability;
+	}
+});
 Object.defineProperty(exports, "streamQualityLabel", {
 	enumerable: true,
 	get: function() {