@camstack/core 0.1.15 → 0.1.16

package/dist/builtins/device-manager/device-manager.addon.mjs

@@ -1,9 +1,2147 @@
-import {
-  DeviceManagerAddon,
-  device_manager_addon_default
-} from "../../chunk-O4V246GG.mjs";
-export {
-  DeviceManagerAddon,
-  device_manager_addon_default as default
+import { randomUUID } from "node:crypto";
+import { BaseAddon, CAP_NAMES_WITH_STATUS, DeviceFeature, DeviceType, EventCategory, WELL_KNOWN_TAB_MAP, deviceManagerCapability, deviceStateCapability, errMsg } from "@camstack/types";
+//#region src/builtins/device-manager/device-event-propagator.ts
+/**
+* Walks the parent chain for every device-sourced event and re-emits a
+* copy on each ancestor scope with `via[]` populated.
+*
+* Design goals:
+*   - Transparent: drivers emit once on their own device scope; the
+*     framework handles fan-out. Zero provider boilerplate.
+*   - Anti-loop: events that already carry `via[]` are skipped (we only
+*     propagate ORIGINAL emissions).
+*   - Anti-cycle: the parent chain is bounded — if the device registry
+*     is corrupt and has a cycle, the walker caps at `MAX_CHAIN_DEPTH`
+*     and logs a warning.
+*   - Lazy: parent chain is resolved on-demand per event (no cached
+*     topology). The lookup is O(depth) which is ≤2 in practice.
+*
+* `via` contract (from SystemEvent.via JSDoc):
+*   - `via[0]` is the originating source (the device that produced the
+*     event). Subsequent entries walk up the parent chain.
+*   - On the re-emission, `source` is the ancestor at that level and
+*     `via[0..i]` is the prefix of the chain up to and including the
+*     first N ancestors below the current one.
+*
+* Example (grandchild → parent → grandparent):
+*   Original:  { source: {id: 7}, data: {...}, via: undefined }
+*   Re-emit 1: { source: {id: 4}, data: {...}, via: [{id: 7}] }
+*   Re-emit 2: { source: {id: 1}, data: {...}, via: [{id: 7}, {id: 4}] }
+*
+* A consumer listening at `source.id === 1` receives re-emit 2 (with
+* `via` showing the chain). A consumer listening at `source.id === 7`
+* with `via === undefined` receives the original only.
+*/
+/** Bounded walk — paranoia against corrupt device registries with cycles. */
+var MAX_CHAIN_DEPTH = 16;
+var DeviceEventPropagator = class {
+	unsubscribe = null;
+	constructor(opts) {
+		this.opts = opts;
+	}
+	start() {
+		if (this.unsubscribe) return;
+		const unsub = this.opts.eventBus.subscribe({}, (ev) => this.handle(ev));
+		this.unsubscribe = unsub;
+	}
+	stop() {
+		if (!this.unsubscribe) return;
+		this.unsubscribe();
+		this.unsubscribe = null;
+	}
+	/** Exposed for tests — lets them inject events without the full bus. */
+	handle(ev) {
+		if (ev.via !== void 0) return;
+		if (ev.source.type !== "device") return;
+		const rawId = ev.source.id;
+		const deviceId = typeof rawId === "number" ? rawId : Number(rawId);
+		if (!Number.isFinite(deviceId)) return;
+		const chain = this.resolveParentChain(deviceId);
+		if (chain.length === 0) return;
+		const via = [ev.source];
+		for (const ancestorId of chain) {
+			const reEmission = {
+				...ev,
+				source: {
+					type: "device",
+					id: ancestorId
+				},
+				via: [...via]
+			};
+			this.opts.eventBus.emit(reEmission);
+			via.push({
+				type: "device",
+				id: ancestorId
+			});
+		}
+	}
+	resolveParentChain(deviceId) {
+		const chain = [];
+		const seen = new Set([deviceId]);
+		let current = this.opts.getParentOf(deviceId);
+		while (current != null) {
+			if (seen.has(current)) {
+				this.opts.logger.warn("device-event-propagator: cycle detected in parent chain — aborting propagation", {
+					tags: { deviceId },
+					meta: {
+						cycleAt: current,
+						chainSoFar: [...chain]
+					}
+				});
+				return chain;
+			}
+			seen.add(current);
+			chain.push(current);
+			if (chain.length >= MAX_CHAIN_DEPTH) {
+				this.opts.logger.warn("device-event-propagator: chain depth limit hit — truncating", {
+					tags: { deviceId },
+					meta: {
+						depth: chain.length,
+						max: MAX_CHAIN_DEPTH
+					}
+				});
+				break;
+			}
+			current = this.opts.getParentOf(current);
+		}
+		return chain;
+	}
 };
+//#endregion
+//#region src/builtins/device-manager/device-manager.addon.ts
+/**
+* Device Manager addon — hub-side singleton that unifies device persistence,
+* live registry queries, and all management operations into a single
+* tRPC-routable capability.
+*
+* Persistence strategy: all device data is stored via `ctx.settings`, the same
+* settings API every other addon uses. No raw SQLite access.
+*
+*   Addon store layout:
+*     deviceIndex  → Record<addonId, stableId[]>          (which devices exist per addon)
+*     deviceMeta   → Record<"addonId:stableId", DeviceMeta> (type, name, parentDeviceId, id)
+*
+*   Device store (per-device config):
+*     readDeviceStore(numericDeviceId)  → config blob
+*     writeDeviceStore(numericDeviceId, patch)
+*
+* Live registry: resolved from the kernel capability registry after Phase 2.
+* This gives direct access to in-memory IDevice instances registered by provider addons.
+* The DeviceManagerAddon is the single owner of the live device operations API.
+*
+* Replaces:
+*   - `device-persistence` capability (absorbed here)
+*   - live operations previously served by `device-management.router.ts`
+*/
+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;
+}
+function deviceKey(addonId, stableId) {
+	return `${addonId}:${stableId}`;
+}
+function isCameraDevice(device) {
+	return "getStreamSources" in device && typeof device.getStreamSources === "function";
+}
+var DEVICE_FEATURE_VALUES = new Set(Object.values(DeviceFeature));
+/**
+* Validate persisted feature strings against the `DeviceFeature` enum
+* — workers serialise the live `device.features` array (so every entry
+* is a valid enum value at write time) but the persisted blob is loose
+* `string[]` on the wire. The narrow keeps unknown values out of the
+* `getDevice` response without losing the enum-typed contract.
+*/
+function persistedFeatures(features) {
+	if (!features) return [];
+	const out = [];
+	for (const f of features) if (DEVICE_FEATURE_VALUES.has(f)) out.push(f);
+	return out;
+}
+function toDeviceInfo(addonId, device, metadata = null, metaRow = null) {
+	const configValues = {};
+	for (const entry of device.config.entries()) configValues[entry.key] = entry.value;
+	const name = metaRow?.name ?? device.name;
+	const location = metaRow?.location !== void 0 ? metaRow.location : device.location;
+	const disabled = metaRow?.disabled ?? device.disabled;
+	return {
+		id: device.id,
+		stableId: device.stableId,
+		addonId,
+		type: device.type,
+		name,
+		location,
+		disabled,
+		parentDeviceId: device.parentDeviceId,
+		role: device.role ?? null,
+		online: device.online,
+		features: [...device.features],
+		isCamera: isCameraDevice(device),
+		config: configValues,
+		metadata
+	};
+}
+function resolveDeviceById(registry, deviceId) {
+	const device = registry.getById(deviceId);
+	if (!device) return null;
+	const addonId = registry.getAddonId(deviceId);
+	if (!addonId) return null;
+	return {
+		addonId,
+		device
+	};
+}
+/**
+* Walk the sections/fields of a contribution and inject `writerCapName` +
+* `writerAddonId` + `source` on each editable field. Readonly fields and
+* structural fields (separator/info/button) pass through untouched. The
+* aggregator is the single place that knows provenance — provider schemas
+* stay clean, UI-bound metadata is attached once at the boundary.
+*/
+function tagContribution(contribution, capName, addonId, kind) {
+	const source = kind === "settings" ? "settings" : "live";
+	return {
+		...contribution.tabs ? { tabs: [...contribution.tabs] } : {},
+		sections: contribution.sections.map((section) => ({
+			...section,
+			fields: section.fields.map((field) => tagField(field, capName, addonId, source, kind))
+		}))
+	};
+}
+function isFieldRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+* Convert a strict `ConfigUISchemaWithValues` (readonly arrays, typed
+* field union) into the cap wire shape `ContributionShape` (mutable
+* arrays, opaque field records). Required because the cap method z.infer
+* uses mutable arrays — readonly arrays are not assignable to mutable
+* even when structurally identical, so a structural copy bridges the gap
+* without disabling the type checker.
+*/
+function toWireShape(input) {
+	const out = { sections: input.sections.map((s) => ({
+		id: s.id,
+		title: s.title,
+		...s.description !== void 0 ? { description: s.description } : {},
+		...s.style !== void 0 ? { style: s.style } : {},
+		...s.defaultCollapsed !== void 0 ? { defaultCollapsed: s.defaultCollapsed } : {},
+		...s.columns !== void 0 ? { columns: s.columns } : {},
+		...s.tab !== void 0 ? { tab: s.tab } : {},
+		...s.location !== void 0 ? { location: s.location } : {},
+		...s.order !== void 0 ? { order: s.order } : {},
+		fields: [...s.fields]
+	})) };
+	if (input.tabs) out.tabs = [...input.tabs];
+	return out;
+}
+function tagField(field, capName, addonId, source, kind) {
+	if (!isFieldRecord(field)) return field;
+	const f = field;
+	const structuralTypes = new Set([
+		"separator",
+		"info",
+		"button"
+	]);
+	if (typeof f.type === "string" && structuralTypes.has(f.type)) return field;
+	const tagged = {
+		...f,
+		source
+	};
+	if (kind === "live" || f.readonlyField === true) tagged.readonlyField = true;
+	else {
+		tagged.writerCapName = capName;
+		tagged.writerAddonId = addonId;
+	}
+	if (f.type === "group") {
+		const children = Array.isArray(f.fields) ? f.fields : [];
+		if (children.length > 0) tagged.fields = children.map((child) => tagField(child, capName, addonId, source, kind));
+	} else if (f.type === "sub-tabs") {
+		const rawTabs = Array.isArray(f.tabs) ? f.tabs : [];
+		if (rawTabs.length > 0) tagged.tabs = rawTabs.map((tab) => {
+			if (!isFieldRecord(tab)) return tab;
+			const tabChildren = Array.isArray(tab.fields) ? tab.fields : [];
+			return {
+				...tab,
+				fields: tabChildren.map((child) => tagField(child, capName, addonId, source, kind))
+			};
+		});
+	}
+	return tagged;
+}
+function mergeAggregates(parts) {
+	const tabDecls = /* @__PURE__ */ new Map();
+	const sections = [];
+	for (const part of parts) {
+		if (part.tabs) {
+			for (const t of part.tabs) if (!tabDecls.has(t.id)) tabDecls.set(t.id, t);
+		}
+		for (const s of part.sections) sections.push(s);
+	}
+	for (const s of sections) {
+		const tabId = s.tab ?? "general";
+		if (tabDecls.has(tabId)) continue;
+		const known = WELL_KNOWN_TAB_MAP[tabId];
+		if (known) tabDecls.set(tabId, {
+			id: known.id,
+			label: known.label,
+			icon: known.icon,
+			order: known.order
+		});
+		else tabDecls.set(tabId, {
+			id: tabId,
+			label: tabId,
+			icon: "wrench",
+			order: 100
+		});
+	}
+	sections.sort((a, b) => {
+		const tabA = a.tab ?? "general";
+		const tabB = b.tab ?? "general";
+		if (tabA !== tabB) {
+			const orderA = tabDecls.get(tabA)?.order ?? 100;
+			const orderB = tabDecls.get(tabB)?.order ?? 100;
+			if (orderA !== orderB) return orderA - orderB;
+			return tabA.localeCompare(tabB);
+		}
+		return (a.order ?? 0) - (b.order ?? 0);
+	});
+	const sortedTabs = [...tabDecls.values()].sort((a, b) => (a.order ?? 100) - (b.order ?? 100));
+	const out = { sections };
+	if (sortedTabs.length > 0) out.tabs = sortedTabs;
+	return out;
+}
+var DeviceManagerAddon = class DeviceManagerAddon extends BaseAddon {
+	constructor() {
+		super({});
+	}
+	/** Shorthand for the kernel-injected capability registry. */
+	get capabilityRegistry() {
+		return this.ctx.kernel.capabilityRegistry;
+	}
+	/**
+	* Parent-chain event propagator. Started in `onInitialize` once the
+	* hub's `deviceRegistry` is available; listens to every device-sourced
+	* event and re-emits a copy on each ancestor scope with `via[]`
+	* populated. Stopped in `onShutdown`.
+	*/
+	propagator = null;
+	/**
+	* Hub-side mirror of every device's cap-keyed runtime state.
+	* Populated whenever any caller writes via `deviceState.setCapSlice`
+	* (the canonical cross-layer write entrypoint) and on first load
+	* via `loadRuntimeState`. Cross-process consumers reach the mirror
+	* through the `deviceState` cap router; per-cap event subscribers
+	* (e.g. `battery.onStatusChanged`) get the same data via
+	* cap-specific events still emitted by the owning device.
+	*
+	* Key: deviceId. Value: per-cap slice map. Empty by default —
+	* slices show up as `setCapSlice` calls trickle in.
+	*/
+	stateMirror = /* @__PURE__ */ new Map();
+	/**
+	* Per-device disk-write debouncer for runtime-state. `setCapSlice`
+	* updates the in-memory mirror synchronously and emits the change
+	* event immediately, but the disk write is coalesced — frequent
+	* back-to-back writes (motion phase transitions, battery pushes,
+	* etc.) collapse to one `writeDeviceRuntimeState` per
+	* `RUNTIME_STATE_DEBOUNCE_MS` window. `flushRuntimeStateWrites`
+	* awaits any in-flight write + scheduled flush so shutdown is
+	* lossless.
+	*/
+	runtimeStateDebounce = /* @__PURE__ */ new Map();
+	static RUNTIME_STATE_DEBOUNCE_MS = 1e3;
+	/**
+	* Cross-process native-provider cache: deviceId (numeric) → capName → { addonId, nodeId }.
+	* Kept in sync with `device.bindings-changed` events emitted by forked
+	* workers. Union'd into `getBindings` so hub-side consumers see every
+	* native cap regardless of which process owns the IDevice. No persistence
+	* — entries re-register when the worker restarts. Purged on
+	* `$node.disconnected` to avoid stale routing after a worker crash.
+	*/
+	remoteNativeCaps = /* @__PURE__ */ new Map();
+	/** Wait for a device-provider by addonId, returning null on timeout. */
+	async waitDeviceProvider(addonId, timeoutMs = 5e3) {
+		const provider = await this.capabilityRegistry?.waitForProvider("device-provider", addonId, timeoutMs);
+		return provider ? provider : null;
+	}
+	/** Require a device-provider by addonId — throws if not found. */
+	async requireDeviceProvider(addonId) {
+		const dp = await this.waitDeviceProvider(addonId);
+		if (!dp) throw new Error(`Device provider "${addonId}" not found or not registered`);
+		return dp;
+	}
+	async readBindingsStore() {
+		return { deviceBindings: (await this.ctx.settings.readAddonStore()).deviceBindings ?? {} };
+	}
+	async writeBindingsStore(next) {
+		await this.ctx.settings.writeAddonStore({ deviceBindings: next.deviceBindings });
+	}
+	resolveWrapperNodeId(_wrapperAddonId) {
+		return "hub";
+	}
+	/**
+	* Active discovery of native caps registered on a worker node.
+	* Called from the `$node.connected` handler to recover from lost
+	* `DeviceBindingsChanged` broadcasts after worker restart.
+	*
+	* Iterates the broker's service registry, picks
+	* `<addonId>.native-provider.<capName>` services owned by the
+	* connected node, calls each service's `$listDeviceIds` action to
+	* fetch the deviceIds the worker has registered that cap on, then
+	* writes entries into `remoteNativeCaps`.
+	*
+	* Best-effort: per-service failures are logged and swallowed so a
+	* single bad service doesn't abort the whole rebuild.
+	*/
+	async discoverWorkerNativeCaps(connectedNodeId, _connectedAddonId) {
+		const cluster = this.ctx.kernel.cluster;
+		if (!cluster) return;
+		const broker = cluster.broker;
+		const services = broker.registry?.getServiceList?.({
+			onlyAvailable: true,
+			withActions: false
+		}) ?? [];
+		const NATIVE_INFIX = ".native-provider.";
+		const matched = services.filter((s) => s.nodeID === connectedNodeId && s.name.includes(NATIVE_INFIX));
+		if (matched.length === 0) return;
+		for (const svc of matched) {
+			const idx = svc.name.indexOf(NATIVE_INFIX);
+			if (idx <= 0) continue;
+			const addonId = svc.name.slice(0, idx);
+			const capName = svc.name.slice(idx + 17);
+			if (!addonId || !capName) continue;
+			try {
+				const action = `${svc.name}.$listDeviceIds`;
+				const deviceIds = await broker.call?.(action, {}, { nodeID: connectedNodeId });
+				if (!deviceIds || deviceIds.length === 0) continue;
+				for (const deviceId of deviceIds) {
+					if (this.capabilityRegistry?.getNativeAddonId(capName, deviceId)) continue;
+					let perDevice = this.remoteNativeCaps.get(deviceId);
+					if (!perDevice) {
+						perDevice = /* @__PURE__ */ new Map();
+						this.remoteNativeCaps.set(deviceId, perDevice);
+					}
+					perDevice.set(capName, {
+						addonId,
+						nodeId: connectedNodeId
+					});
+				}
+				this.ctx.logger.debug("worker native-cap discovered", { meta: {
+					nodeId: connectedNodeId,
+					addonId,
+					capName,
+					deviceIds
+				} });
+			} catch (err) {
+				this.ctx.logger.debug("worker native-cap $listDeviceIds failed", { meta: {
+					service: svc.name,
+					nodeId: connectedNodeId,
+					error: errMsg(err)
+				} });
+			}
+		}
+		this.ctx.logger.info("worker native-cap discovery completed", { meta: {
+			nodeId: connectedNodeId,
+			services: matched.length
+		} });
+	}
+	async getBindings(input) {
+		const storeKey = String(input.deviceId);
+		const perDevice = (await this.readBindingsStore()).deviceBindings[storeKey] ?? {};
+		const entries = [];
+		const seenCaps = /* @__PURE__ */ new Set();
+		for (const [capName, { wrapperAddonId }] of Object.entries(perDevice)) {
+			const hubLocalNative = this.capabilityRegistry?.getNativeAddonId(capName, input.deviceId) ?? null;
+			const remoteNative = this.remoteNativeCaps.get(input.deviceId)?.get(capName) ?? null;
+			const nativeAddonId = hubLocalNative ?? remoteNative?.addonId ?? "";
+			const nativeNodeId = hubLocalNative ? this.ctx.kernel.localNodeId ?? "hub" : remoteNative?.nodeId ?? this.ctx.kernel.localNodeId ?? "hub";
+			if (wrapperAddonId === null && !nativeAddonId) {
+				seenCaps.add(capName);
+				continue;
+			}
+			entries.push({
+				capName,
+				kind: wrapperAddonId ? "wrapped" : "native",
+				providerAddonId: wrapperAddonId ?? nativeAddonId,
+				providerNodeId: wrapperAddonId ? this.resolveWrapperNodeId(wrapperAddonId) : nativeNodeId,
+				nativeAddonId
+			});
+			seenCaps.add(capName);
+		}
+		const remote = this.remoteNativeCaps.get(input.deviceId);
+		if (this.capabilityRegistry) for (const capName of this.capabilityRegistry.getCapsWithDefaultWrapper()) {
+			if (seenCaps.has(capName)) continue;
+			const defaultWrapperAddonId = this.capabilityRegistry.getDefaultWrapperForCap(capName);
+			if (!defaultWrapperAddonId) continue;
+			const hubLocalNative = this.capabilityRegistry.getNativeAddonId(capName, input.deviceId) ?? null;
+			const remoteNative = remote?.get(capName) ?? null;
+			const nativeAddonId = hubLocalNative ?? remoteNative?.addonId ?? "";
+			entries.push({
+				capName,
+				kind: "wrapped",
+				providerAddonId: defaultWrapperAddonId,
+				providerNodeId: this.resolveWrapperNodeId(defaultWrapperAddonId),
+				nativeAddonId
+			});
+			seenCaps.add(capName);
+		}
+		if (this.capabilityRegistry) for (const capName of this.capabilityRegistry.getNativeCapsForDevice(input.deviceId)) {
+			if (seenCaps.has(capName)) continue;
+			const nativeAddonId = this.capabilityRegistry.getNativeAddonId(capName, input.deviceId) ?? "";
+			entries.push({
+				capName,
+				kind: "native",
+				providerAddonId: nativeAddonId,
+				providerNodeId: this.ctx.kernel.localNodeId ?? "hub",
+				nativeAddonId
+			});
+			seenCaps.add(capName);
+		}
+		if (remote) for (const [capName, info] of remote) {
+			if (seenCaps.has(capName)) continue;
+			entries.push({
+				capName,
+				kind: "native",
+				providerAddonId: info.addonId,
+				providerNodeId: info.nodeId,
+				nativeAddonId: info.addonId
+			});
+			seenCaps.add(capName);
+		}
+		return {
+			deviceId: input.deviceId,
+			entries
+		};
+	}
+	/**
+	* Whole-fleet binding dump. Iterates every device known to the
+	* deviceRegistry and reuses the per-device `getBindings` resolver
+	* for each — same routing rules, single round-trip. Used by
+	* `SystemManager.init()` for warm-boot.
+	*
+	* Bindings change rarely (wrapper toggle, device add/remove) so
+	* clients invalidate via the existing
+	* `capability.binding-changed` event rather than re-fetching this
+	* payload periodically.
+	*/
+	async getAllBindings() {
+		const hubRegistry = this.ctx.kernel?.deviceRegistry;
+		if (!hubRegistry) return [];
+		const out = [];
+		for (const device of hubRegistry.getAll()) out.push(await this.getBindings({ deviceId: device.id }));
+		return out;
+	}
+	/**
+	* Resolve a numeric deviceId to a stableId via persisted meta.
+	* Used only by the device-identity section of the device-details
+	* aggregator (see `buildBaseDeviceSection`) to surface the stableId as
+	* a readonly display field. All runtime/registry lookups are keyed by
+	* numeric deviceId; this helper is display-only.
+	*/
+	async lookupPersistedStableId(deviceId) {
+		const meta = (await this.ctx.settings.readAddonStore()).deviceMeta ?? {};
+		for (const [key, m] of Object.entries(meta)) if (m.id === deviceId) {
+			const sep = key.indexOf(":");
+			if (sep < 0) continue;
+			return key.slice(sep + 1);
+		}
+	}
+	async getDeviceAggregate(deviceId, kind) {
+		const registry = this.capabilityRegistry;
+		if (!registry) {
+			this.ctx.logger.debug("capability registry unavailable — aggregate empty", { meta: { kind } });
+			return null;
+		}
+		const method = kind === "settings" ? "getDeviceSettingsContribution" : "getDeviceLiveContribution";
+		const contributors = [];
+		for (const info of registry.listCapabilities()) {
+			if (!registry.getDefinition(info.name)?.exposesDeviceSettings) continue;
+			const seen = /* @__PURE__ */ new Set();
+			const sorted = [...info.providers].sort((a, b) => a.length - b.length);
+			for (const addonId of sorted) {
+				if (addonId.includes("::native-")) continue;
+				const baseId = addonId.includes("@") ? addonId.slice(0, addonId.indexOf("@")) : addonId;
+				if (seen.has(baseId)) continue;
+				seen.add(baseId);
+				contributors.push({
+					capName: info.name,
+					addonId
+				});
+			}
+		}
+		const results = await Promise.all(contributors.map(async ({ capName, addonId }) => {
+			const provider = registry.getProviderByAddon(capName, addonId);
+			if (!provider) throw new Error(`[device-manager] capability "${capName}" lists provider "${addonId}" but getProviderByAddon returned null — registry inconsistency`);
+			try {
+				const contribution = await provider[method]({ deviceId });
+				if (!contribution) return null;
+				return {
+					capName,
+					addonId,
+					contribution: tagContribution(toWireShape(contribution), capName, addonId, kind)
+				};
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				this.ctx.logger.warn("contribution method failed", {
+					tags: {
+						deviceId,
+						addonId
+					},
+					meta: {
+						capName,
+						method,
+						error: msg
+					}
+				});
+				return null;
+			}
+		}));
+		const base = kind === "settings" ? await this.buildBaseDeviceSection(deviceId) : null;
+		const parts = [...base ? [tagContribution(base, "device-manager", "device-manager", kind)] : [], ...results.filter((r) => r !== null).map((r) => r.contribution)];
+		if (parts.length === 0) return null;
+		return mergeAggregates(parts);
+	}
+	/**
+	* Build the device-manager's own contribution to the aggregator — the
+	* device identity (id, stableId, addonId, type, online) + the
+	* driver-specific config exposed by the device class via
+	* `zodEntriesToConfigUI`.
+	*
+	* Two paths, deliberately symmetric with `getSettingsSchema`:
+	*
+	*  - Hub-local: device's IDevice instance lives in this process'
+	*    DeviceRegistry, we read config + schema directly by reference.
+	*  - Cross-process: device lives in a forked worker (RtspCamera on
+	*    provider-rtsp, ONVIF on provider-onvif, …). We ask the worker's
+	*    `device-ops.getSettingsSchema` native provider for a wire-
+	*    serializable ConfigUISchema and merge it in under the same
+	*    "Driver Config" section, so the UI sees the same shape regardless
+	*    of where the IDevice physically runs.
+	*
+	*  Returns `null` only when the device genuinely doesn't exist anywhere
+	*  (no hub-local, no persisted ownership, no device-ops native). The
+	*  aggregator falls back to contributor sections only in that case.
+	*/
+	async buildBaseDeviceSection(deviceId) {
+		const hubRegistry = this.ctx.kernel?.deviceRegistry;
+		const hubLocal = hubRegistry ? resolveDeviceById(hubRegistry, deviceId) : null;
+		const stableId = hubLocal?.device.stableId ?? await this.lookupPersistedStableId(deviceId);
+		const nativeOwner = this.resolveNativeDeviceOwner(deviceId);
+		const addonId = hubLocal?.addonId ?? nativeOwner?.addonId ?? null;
+		if (!hubLocal && !nativeOwner) return null;
+		const sections = [{
+			id: "device-identity",
+			title: "Identity",
+			tab: "general",
+			order: 0,
+			fields: [
+				{
+					type: "text",
+					key: "_deviceId",
+					label: "Device ID",
+					readonlyField: true,
+					value: String(deviceId)
+				},
+				{
+					type: "text",
+					key: "_stableId",
+					label: "Stable ID",
+					readonlyField: true,
+					value: stableId ?? ""
+				},
+				{
+					type: "text",
+					key: "_addonId",
+					label: "Driver",
+					readonlyField: true,
+					value: addonId ?? "unknown"
+				},
+				...hubLocal ? [{
+					type: "text",
+					key: "_type",
+					label: "Type",
+					readonlyField: true,
+					value: hubLocal.device.type
+				}, {
+					type: "text",
+					key: "_online",
+					label: "Online",
+					readonlyField: true,
+					value: hubLocal.device.online ? "yes" : "no"
+				}] : []
+			]
+		}];
+		const driverSchema = await this.resolveDriverConfigSchema(deviceId, hubLocal);
+		if (driverSchema) for (const section of driverSchema.sections) sections.push({
+			id: section.id,
+			title: section.title,
+			tab: section.tab ?? "general",
+			order: section.order ?? 1,
+			fields: [...section.fields],
+			...section.description !== void 0 ? { description: section.description } : {},
+			...section.columns !== void 0 ? { columns: section.columns } : {}
+		});
+		return {
+			sections,
+			...driverSchema?.tabs ? { tabs: [...driverSchema.tabs] } : {}
+		};
+	}
+	/**
+	* Lookup the native owner for `device-ops` on `deviceId` — the native-cap
+	* registry (hub-local and remote) is keyed by numeric id.
+	*/
+	resolveNativeDeviceOwner(deviceId) {
+		const local = this.capabilityRegistry?.getNativeAddonId("device-ops", deviceId) ?? null;
+		if (local) return {
+			addonId: local,
+			nodeId: this.ctx.kernel.localNodeId ?? "hub"
+		};
+		const remote = this.remoteNativeCaps.get(deviceId)?.get("device-ops") ?? null;
+		return remote ? {
+			addonId: remote.addonId,
+			nodeId: remote.nodeId
+		} : null;
+	}
+	/**
+	* Aggregate `status` across every registered cap for a device.
+	*
+	* Walks the supplied cap list (or `CAP_NAMES_WITH_STATUS` when
+	* omitted), looks up a native provider per cap via the capability
+	* registry, calls `provider.getStatus({ deviceId })`, and validates
+	* the return against the cap's own `status.schema`. Validation
+	* failures log a warning and yield `null` for that cap so the
+	* overall aggregate stays usable — a single misbehaving provider
+	* must not blank out a device's entire status view.
+	*
+	* Returned shape is `Record<capName, unknown | null>`; the client-
+	* side hook tightens this to `CapStatusTypeMap` via the generated
+	* `cap-status-types.ts`.
+	*/
+	async getDeviceStatusAggregate(input) {
+		const capNames = input.caps ?? CAP_NAMES_WITH_STATUS;
+		const registry = this.capabilityRegistry;
+		const out = {};
+		if (!registry) {
+			for (const name of capNames) out[name] = null;
+			return out;
+		}
+		await Promise.all(capNames.map(async (capName) => {
+			try {
+				const def = registry.getDefinition(capName);
+				if (!def?.status) {
+					out[capName] = null;
+					return;
+				}
+				const provider = registry.getNativeProvider(capName, input.deviceId);
+				if (!provider || typeof provider.getStatus !== "function") {
+					out[capName] = null;
+					return;
+				}
+				const raw = await provider.getStatus({ deviceId: input.deviceId });
+				if (raw == null) {
+					out[capName] = null;
+					return;
+				}
+				const parsed = def.status.schema.safeParse(raw);
+				if (!parsed.success) {
+					this.ctx.logger.warn("getDeviceStatusAggregate: provider returned invalid status, dropping", {
+						tags: { deviceId: input.deviceId },
+						meta: {
+							capName,
+							issues: parsed.error.issues.slice(0, 3)
+						}
+					});
+					out[capName] = null;
+					return;
+				}
+				out[capName] = parsed.data;
+			} catch (err) {
+				this.ctx.logger.warn("getDeviceStatusAggregate: provider threw, dropping", {
+					tags: { deviceId: input.deviceId },
+					meta: {
+						capName,
+						error: errMsg(err)
+					}
+				});
+				out[capName] = null;
+			}
+		}));
+		return out;
+	}
+	/**
+	* Return the driver-specific device-settings contribution. Hub-local
+	* devices call `getSettingsUISchema()` directly; forked-worker devices
+	* go through the `device-ops.getSettingsSchema` cap method on the
+	* numeric-id-keyed native registry.
+	*/
+	async resolveDriverConfigSchema(deviceId, hubLocal) {
+		if (hubLocal) {
+			const schema = hubLocal.device.getSettingsUISchema();
+			return schema.sections.length === 0 ? null : toWireShape(schema);
+		}
+		const ops = this.capabilityRegistry?.getNativeProvider("device-ops", deviceId);
+		if (!ops) return null;
+		try {
+			const schema = await ops.getSettingsSchema({ deviceId });
+			if (!schema) return null;
+			const wire = schema;
+			return wire.sections.length === 0 ? null : toWireShape(wire);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			this.ctx.logger.warn("cross-process getSettingsSchema failed", {
+				tags: { deviceId },
+				meta: { error: msg }
+			});
+			return null;
+		}
+	}
+	async updateDeviceField(input) {
+		if (input.writerCapName === "device-manager") {
+			const hubRegistry = this.ctx.kernel?.deviceRegistry;
+			const found = hubRegistry ? resolveDeviceById(hubRegistry, input.deviceId) : null;
+			if (found) {
+				await found.device.applySettingsPatch({ [input.key]: input.value });
+				return { success: true };
+			}
+			const ops = this.capabilityRegistry?.getNativeProvider("device-ops", input.deviceId);
+			if (!ops) throw new Error(`[device-manager] device "${input.deviceId}" not found (no hub-local entry, no device-ops native provider)`);
+			await ops.setConfig({
+				deviceId: input.deviceId,
+				values: { [input.key]: input.value }
+			});
+			return { success: true };
+		}
+		const registry = this.capabilityRegistry;
+		if (!registry) throw new Error("[device-manager] updateDeviceField requires capability registry — unavailable on this node");
+		if (!registry.getDefinition(input.writerCapName)?.exposesDeviceSettings) throw new Error(`[device-manager] cap "${input.writerCapName}" does not expose device settings`);
+		const provider = registry.getProviderByAddon(input.writerCapName, input.writerAddonId);
+		if (!provider) throw new Error(`[device-manager] provider "${input.writerAddonId}" not registered for cap "${input.writerCapName}"`);
+		await provider.applyDeviceSettingsPatch({
+			deviceId: input.deviceId,
+			patch: { [input.key]: input.value }
+		});
+		return { success: true };
+	}
+	/**
+	* Batched counterpart of `updateDeviceField`. Groups changes by
+	* `(writerCapName, writerAddonId)` so each contributor receives a
+	* single `applyDeviceSettingsPatch` with all of its updates merged —
+	* avoids N round-trips for simultaneous edits in the same save.
+	*
+	* Per-provider failures are captured in the `failures[]` output so the
+	* admin UI can highlight which sections didn't persist; a failure on
+	* one provider does NOT abort the others.
+	*/
+	async updateDeviceFieldsBatch(input) {
+		const groups = /* @__PURE__ */ new Map();
+		for (const change of input.changes) {
+			const key = `${change.writerCapName}::${change.writerAddonId}`;
+			const existing = groups.get(key);
+			if (existing) existing.patch[change.key] = change.value;
+			else groups.set(key, {
+				writerCapName: change.writerCapName,
+				writerAddonId: change.writerAddonId,
+				patch: { [change.key]: change.value }
+			});
+		}
+		const failures = [];
+		for (const group of groups.values()) try {
+			await this.applyGroupPatch(input.deviceId, group);
+		} catch (err) {
+			failures.push({
+				writerCapName: group.writerCapName,
+				writerAddonId: group.writerAddonId,
+				error: err instanceof Error ? err.message : String(err)
+			});
+		}
+		return {
+			success: true,
+			failures
+		};
+	}
+	/** Apply a single grouped patch to the appropriate provider. Mirrors
+	* `updateDeviceField` routing (special-case device-manager, else
+	* registry lookup). Used by `updateDeviceFieldsBatch`. */
+	async applyGroupPatch(deviceId, group) {
+		if (group.writerCapName === "device-manager") {
+			const hubRegistry = this.ctx.kernel?.deviceRegistry;
+			const found = hubRegistry ? resolveDeviceById(hubRegistry, deviceId) : null;
+			if (found) {
+				await found.device.applySettingsPatch(group.patch);
+				return;
+			}
+			const ops = this.capabilityRegistry?.getNativeProvider("device-ops", deviceId);
+			if (!ops) throw new Error(`[device-manager] device "${deviceId}" not found (no hub-local entry, no device-ops native provider)`);
+			await ops.setConfig({
+				deviceId,
+				values: group.patch
+			});
+			return;
+		}
+		const registry = this.capabilityRegistry;
+		if (!registry) throw new Error("[device-manager] capability registry unavailable");
+		if (!registry.getDefinition(group.writerCapName)?.exposesDeviceSettings) throw new Error(`[device-manager] cap "${group.writerCapName}" does not expose device settings`);
+		const provider = registry.getProviderByAddon(group.writerCapName, group.writerAddonId);
+		if (!provider) throw new Error(`[device-manager] provider "${group.writerAddonId}" not registered for cap "${group.writerCapName}"`);
+		await provider.applyDeviceSettingsPatch({
+			deviceId,
+			patch: group.patch
+		});
+	}
+	async listWrappersForCap(input) {
+		return [...this.capabilityRegistry?.getWrappersForCap(input.capName) ?? []];
+	}
+	async listBindableCapsForDeviceType(input) {
+		const registry = this.capabilityRegistry;
+		if (!registry) return [];
+		return registry.listDeviceScopedCapsForType(input.deviceType).map((capName) => ({
+			capName,
+			wrappers: [...registry.getWrappersForCap(capName)]
+		}));
+	}
+	async setWrapperActive(input) {
+		const storeKey = String(input.deviceId);
+		const store = await this.readBindingsStore();
+		const perDevice = { ...store.deviceBindings[storeKey] ?? {} };
+		if (input.active) perDevice[input.capName] = { wrapperAddonId: input.wrapperAddonId };
+		else perDevice[input.capName] = { wrapperAddonId: null };
+		const nextDeviceBindings = Object.keys(perDevice).length > 0 ? {
+			...store.deviceBindings,
+			[storeKey]: perDevice
+		} : (() => {
+			const { [storeKey]: _drop, ...rest } = store.deviceBindings;
+			return rest;
+		})();
+		await this.writeBindingsStore({ deviceBindings: nextDeviceBindings });
+		this.ctx.eventBus.emit({
+			id: randomUUID(),
+			timestamp: /* @__PURE__ */ new Date(),
+			source: {
+				type: "addon",
+				id: this.ctx.id
+			},
+			category: EventCategory.DeviceBindingsChanged,
+			data: {
+				deviceId: input.deviceId,
+				capName: input.capName,
+				reason: input.active ? "wrapper-activated" : "wrapper-deactivated",
+				addonId: input.wrapperAddonId,
+				nodeId: this.resolveWrapperNodeId(input.wrapperAddonId)
+			}
+		});
+	}
+	async onInitialize() {
+		const settings = this.ctx.settings;
+		if (!settings) {
+			this.ctx.logger.warn("ctx.settings not available — device persistence unavailable");
+			return;
+		}
+		const registry = this.ctx.kernel.deviceRegistry ?? null;
+		if (!registry) this.ctx.logger.warn("device-registry not available — live operations will use persisted data only");
+		const localNodeId = this.ctx.kernel.localNodeId ?? "hub";
+		this.ctx.eventBus.subscribe({ category: EventCategory.DeviceBindingsChanged }, (event) => {
+			const { deviceId, capName, reason, addonId, nodeId } = event.data;
+			if (nodeId === localNodeId) return;
+			if (reason === "native-registered") {
+				let perDevice = this.remoteNativeCaps.get(deviceId);
+				if (!perDevice) {
+					perDevice = /* @__PURE__ */ new Map();
+					this.remoteNativeCaps.set(deviceId, perDevice);
+				}
+				perDevice.set(capName, {
+					addonId,
+					nodeId
+				});
+			} else if (reason === "native-unregistered") {
+				const perDevice = this.remoteNativeCaps.get(deviceId);
+				if (!perDevice) return;
+				perDevice.delete(capName);
+				if (perDevice.size === 0) this.remoteNativeCaps.delete(deviceId);
+			}
+		});
+		const cluster = this.ctx.kernel.cluster;
+		if (cluster) cluster.broker.localBus.on("$node.disconnected", (payload) => {
+			const gone = payload.node.id;
+			const emptyDevices = [];
+			for (const [deviceId, perDevice] of this.remoteNativeCaps) {
+				const toDelete = [];
+				for (const [capName, entry] of perDevice) if (entry.nodeId === gone) toDelete.push(capName);
+				for (const capName of toDelete) perDevice.delete(capName);
+				if (perDevice.size === 0) emptyDevices.push(deviceId);
+			}
+			for (const deviceId of emptyDevices) this.remoteNativeCaps.delete(deviceId);
+		});
+		const requireDeviceOps = (deviceId) => {
+			const ops = this.capabilityRegistry?.getNativeProvider("device-ops", deviceId);
+			if (!ops) throw new Error(`[device-manager] device-ops native provider not found for '${deviceId}'`);
+			return ops;
+		};
+		const readStore = async () => {
+			return await settings.readAddonStore();
+		};
+		const readIndex = async () => {
+			return (await readStore()).deviceIndex ?? {};
+		};
+		const readMeta = async () => {
+			return (await readStore()).deviceMeta ?? {};
+		};
+		/** Hardware-identity metadata map. Lives in a sibling key on the
+		*  device-manager addon store so its writers (`setMetadata`) never
+		*  collide with the lifecycle writers on `deviceMeta`
+		*  (`registerDevice` / `setName` / `setLocation` / `setDisabled`).
+		*  Single-writer per row eliminates the "writer X clobbers writer
+		*  Y's field" bug class — `setMetadata` is the only producer. */
+		const readMetadataMap = async () => {
+			return (await readStore()).deviceMetadata ?? {};
+		};
+		let metaWriteChain = Promise.resolve();
+		const withMetaWriteLock = async (fn) => {
+			const previous = metaWriteChain;
+			let release = () => {};
+			metaWriteChain = new Promise((resolve) => {
+				release = resolve;
+			});
+			try {
+				await previous.catch(() => {});
+				return await fn();
+			} finally {
+				release();
+			}
+		};
+		/**
+		* Resolve a numeric deviceId to the owning `(addonId, stableId)` pair.
+		* Scans persisted meta — live IDevice lookup (hub registry) is handled
+		* separately per call site so callers can decide whether to route to
+		* an in-process driver or to the cross-process `device-ops` bridge.
+		* Returns null when no device with that id is known to the hub.
+		*/
+		const resolvePersistedById = async (deviceId) => {
+			const meta = await readMeta();
+			for (const [key, m] of Object.entries(meta)) if (m.id === deviceId) {
+				const sep = key.indexOf(":");
+				if (sep < 0) continue;
+				return {
+					addonId: key.slice(0, sep),
+					stableId: key.slice(sep + 1),
+					meta: m
+				};
+			}
+			return null;
+		};
+		const idToAddonId = /* @__PURE__ */ new Map();
+		{
+			const meta = await readMeta();
+			for (const [key, m] of Object.entries(meta)) {
+				const sep = key.indexOf(":");
+				if (sep < 0) continue;
+				idToAddonId.set(m.id, key.slice(0, sep));
+			}
+		}
+		if (cluster) cluster.broker.localBus.on("$node.connected", (payload) => {
+			const connectedNodeId = payload.node.id;
+			const lastSlash = connectedNodeId.lastIndexOf("/");
+			if (lastSlash < 0) return;
+			const connectedAddonId = connectedNodeId.slice(lastSlash + 1);
+			if (connectedAddonId.length === 0) return;
+			for (const [deviceId, ownerAddonId] of idToAddonId) {
+				if (ownerAddonId !== connectedAddonId) continue;
+				if (this.capabilityRegistry?.getNativeAddonId("device-ops", deviceId)) continue;
+				let perDevice = this.remoteNativeCaps.get(deviceId);
+				if (!perDevice) {
+					perDevice = /* @__PURE__ */ new Map();
+					this.remoteNativeCaps.set(deviceId, perDevice);
+				}
+				if (!perDevice.has("device-ops")) perDevice.set("device-ops", {
+					addonId: connectedAddonId,
+					nodeId: connectedNodeId
+				});
+			}
+			setTimeout(() => {
+				this.discoverWorkerNativeCaps(connectedNodeId, connectedAddonId).catch((err) => {
+					this.ctx.logger.warn("worker native-cap discovery failed", { meta: {
+						nodeId: connectedNodeId,
+						addonId: connectedAddonId,
+						error: errMsg(err)
+					} });
+				});
+			}, 500);
+		});
+		const allocateNextDeviceId = async () => {
+			const current = (await readStore()).nextDeviceId ?? 1;
+			await settings.writeAddonStore({ nextDeviceId: current + 1 });
+			return current;
+		};
+		const provider = {
+			/** Sync ownership lookup backing persistence fallbacks (e.g. remove()
+			*  when the owning worker is offline). Ownership is keyed by numeric
+			*  deviceId → owning addonId as recorded in the persisted meta. NOT
+			*  a native-cap lookup: an addon can own a device without registering
+			*  every possible cap natively (e.g. RtspCamera without snapshotUrl
+			*  doesn't register the snapshot cap). Use
+			*  `resolveNativeCapOwnerSync` for cap-resolution paths.
+			*/
+			resolveDeviceOwnerSync: (deviceId) => {
+				return idToAddonId.get(deviceId) ?? null;
+			},
+			/** Sync lookup for the addon that registered a native provider for
+			*  `(capName, deviceId)`. Backs `CapabilityRegistry`'s native fallback
+			*  so the hub only synthesizes a cross-process proxy when the cap is
+			*  actually published — never on speculative device ownership.
+			*
+			*  Consults hub-local registrations first (in-process natives),
+			*  then the `remoteNativeCaps` map populated from
+			*  `DeviceBindingsChanged` events emitted by forked-worker
+			*  `registerNativeCap` calls. Both are generic: any addon that hosts
+			*  devices and registers caps via the standard context API shows up
+			*  here without per-addon branching.
+			*/
+			resolveNativeCapOwnerSync: (capName, deviceId) => {
+				const localAddonId = this.capabilityRegistry?.getNativeAddonId(capName, deviceId) ?? null;
+				if (localAddonId) return {
+					addonId: localAddonId,
+					nodeId: this.ctx.kernel.localNodeId ?? "hub"
+				};
+				const remote = this.remoteNativeCaps.get(deviceId)?.get(capName) ?? null;
+				if (remote) return {
+					addonId: remote.addonId,
+					nodeId: remote.nodeId
+				};
+				return null;
+			},
+			/** Idempotent numeric-id reservation. Callers invoke this before
+			*  constructing the owning `IDevice` so `DeviceContext.id` is bound
+			*  at construction time. A repeat call for the same `(addonId,
+			*  stableId)` returns the already-persisted id — same physical
+			*  device reconnecting after a driver restart keeps its original
+			*  number. Fresh pairs burn one slot from the monotonic
+			*  `nextDeviceId` counter and seed a meta placeholder so the
+			*  `deviceMeta` → `id` invariant holds even before
+			*  `registerDevice` completes. */
+			allocateDeviceId: async (input) => {
+				const { addonId, stableId } = input;
+				const key = deviceKey(addonId, stableId);
+				return await withMetaWriteLock(async () => {
+					const meta = await readMeta();
+					const existing = meta[key];
+					if (existing) return { id: existing.id };
+					const id = await allocateNextDeviceId();
+					await settings.writeAddonStore({ deviceMeta: {
+						...meta,
+						[key]: {
+							type: "generic",
+							name: stableId,
+							location: null,
+							disabled: false,
+							parentDeviceId: null,
+							id
+						}
+					} });
+					return { id };
+				});
+			},
+			registerDevice: async (input) => {
+				const { addonId, stableId, id, type, name, parentDeviceId, features, config } = input;
+				const key = deviceKey(addonId, stableId);
+				const featuresArr = Array.isArray(features) ? [...features] : [];
+				const { isFirstRegistration } = await withMetaWriteLock(async () => {
+					const index = await readIndex();
+					const existing = index[addonId] ?? [];
+					const wasInIndex = existing.includes(stableId);
+					if (!wasInIndex) await settings.writeAddonStore({ deviceIndex: {
+						...index,
+						[addonId]: [...existing, stableId]
+					} });
+					const meta = await readMeta();
+					const existingMeta = meta[key];
+					const isFirst = !existingMeta || !wasInIndex;
+					await settings.writeAddonStore({ deviceMeta: {
+						...meta,
+						[key]: {
+							type,
+							name: existingMeta && existingMeta.name !== stableId ? existingMeta.name : name,
+							location: existingMeta?.location ?? null,
+							disabled: existingMeta?.disabled ?? false,
+							parentDeviceId,
+							id,
+							features: featuresArr
+						}
+					} });
+					return { isFirstRegistration: isFirst };
+				});
+				if (Object.keys(config).length > 0) await settings.writeDeviceStore(id, config);
+				idToAddonId.set(id, addonId);
+				if (isFirstRegistration) this.ctx.eventBus.emit({
+					id: randomUUID(),
+					timestamp: /* @__PURE__ */ new Date(),
+					source: {
+						type: "device",
+						id
+					},
+					category: EventCategory.DeviceRegistered,
+					data: {
+						deviceId: id,
+						name: name.length > 0 ? name : stableId,
+						providerId: addonId,
+						parentDeviceId: parentDeviceId ?? null
+					}
+				});
+				else this.ctx.eventBus.emit({
+					id: randomUUID(),
+					timestamp: /* @__PURE__ */ new Date(),
+					source: {
+						type: "device",
+						id
+					},
+					category: EventCategory.DeviceMetaChanged,
+					data: {
+						deviceId: id,
+						name: name.length > 0 ? name : stableId,
+						providerId: addonId,
+						parentDeviceId: parentDeviceId ?? null,
+						features: featuresArr
+					}
+				});
+			},
+			removeDevice: async (input) => {
+				const { deviceId } = input;
+				const persisted = await resolvePersistedById(deviceId);
+				if (!persisted) return;
+				const { addonId, stableId, meta: persistedMeta } = persisted;
+				const key = deviceKey(addonId, stableId);
+				const deviceName = persistedMeta.name;
+				await withMetaWriteLock(async () => {
+					const index = await readIndex();
+					const remaining = (index[addonId] ?? []).filter((sid) => sid !== stableId);
+					const updatedIndex = remaining.length > 0 ? {
+						...index,
+						[addonId]: remaining
+					} : (() => {
+						const { [addonId]: _removed, ...rest } = index;
+						return rest;
+					})();
+					await settings.writeAddonStore({ deviceIndex: updatedIndex });
+					const { [key]: _removedMeta, ...restMeta } = await readMeta();
+					await settings.writeAddonStore({ deviceMeta: restMeta });
+					const map = await readMetadataMap();
+					if (key in map) {
+						const { [key]: _removedMetadata, ...restMap } = map;
+						await settings.writeAddonStore({ deviceMetadata: restMap });
+					}
+				});
+				await settings.clearDeviceStore(deviceId);
+				const bindingsStore = await this.readBindingsStore();
+				const bindingKey = String(deviceId);
+				if (bindingsStore.deviceBindings[bindingKey]) {
+					const { [bindingKey]: _removedBindings, ...restBindings } = bindingsStore.deviceBindings;
+					await this.writeBindingsStore({ deviceBindings: restBindings });
+				}
+				this.remoteNativeCaps.delete(deviceId);
+				this.capabilityRegistry?.unregisterAllNativeForDevice(deviceId);
+				idToAddonId.delete(deviceId);
+				this.ctx.logger.info("removed device", { tags: {
+					deviceId,
+					deviceName: deviceName.length > 0 ? deviceName : stableId
+				} });
+				this.ctx.eventBus.emit({
+					id: randomUUID(),
+					timestamp: /* @__PURE__ */ new Date(),
+					source: {
+						type: "device",
+						id: deviceId
+					},
+					category: EventCategory.DeviceUnregistered,
+					data: {
+						deviceId,
+						providerId: addonId,
+						parentDeviceId: persistedMeta.parentDeviceId ?? null
+					}
+				});
+			},
+			persistConfig: async (input) => {
+				const { deviceId, data } = input;
+				if (!await resolvePersistedById(deviceId)) throw new Error(`[device-manager] persistConfig: unknown device id=${deviceId}`);
+				await settings.writeDeviceStore(deviceId, data);
+			},
+			loadConfig: async (input) => {
+				const { deviceId } = input;
+				if (!await resolvePersistedById(deviceId)) return {};
+				return settings.readDeviceStore(deviceId);
+			},
+			/**
+			* Load the operator-organisational meta surface for one device
+			* (`name` / `location` / `disabled` / `type` / `parentDeviceId`
+			* / `addonId` + `id` / `stableId`). Used by the kernel proxy's
+			* device-context factory to populate `ctx.deviceMeta` before
+			* the device class constructor runs. Returns `null` when no
+			* persisted row exists for the id.
+			*
+			* Reads default `location` to `null` and `disabled` to `false`
+			* for legacy rows that predate the field — production code
+			* relies on the IDevice type contract that both are present.
+			*/
+			loadMeta: async (input) => {
+				const { deviceId } = input;
+				const persisted = await resolvePersistedById(deviceId);
+				if (!persisted) return null;
+				const { addonId, stableId, meta: m } = persisted;
+				const key = deviceKey(addonId, stableId);
+				const metadata = (await readMetadataMap())[key] ?? null;
+				return {
+					id: m.id,
+					stableId,
+					addonId,
+					type: m.type,
+					name: m.name,
+					location: m.location ?? null,
+					disabled: m.disabled ?? false,
+					parentDeviceId: m.parentDeviceId,
+					metadata
+				};
+			},
+			/**
+			* Update the operator-edited display name. Writes the meta
+			* row, emits a `DeviceMetaChanged` event so live consumers
+			* (UI device list, alert center) see the rename without
+			* polling. The live `IDevice.name` mirror is updated by the
+			* kernel proxy on its side (`device-cap-proxy.ts`).
+			*/
+			setName: async (input) => {
+				const { deviceId, name } = input;
+				await withMetaWriteLock(async () => {
+					const persisted = await resolvePersistedById(deviceId);
+					if (!persisted) throw new Error(`[device-manager] setName: unknown device id=${deviceId}`);
+					const { addonId, stableId, meta: m } = persisted;
+					const key = deviceKey(addonId, stableId);
+					const allMeta = await readMeta();
+					await settings.writeAddonStore({ deviceMeta: {
+						...allMeta,
+						[key]: {
+							...m,
+							name
+						}
+					} });
+				});
+				this.ctx.eventBus.emit({
+					id: randomUUID(),
+					timestamp: /* @__PURE__ */ new Date(),
+					source: {
+						type: "device",
+						id: deviceId
+					},
+					category: EventCategory.DeviceMetaChanged,
+					data: {
+						deviceId,
+						field: "name",
+						value: name
+					}
+				});
+			},
+			/**
+			* Update the operator-organisational location label. `null`
+			* clears it. Mirrors the same persist-then-emit shape as
+			* `setName`; consumers subscribe to `DeviceMetaChanged` and
+			* filter on `field: 'location'`.
+			*/
+			setLocation: async (input) => {
+				const { deviceId, location } = input;
+				await withMetaWriteLock(async () => {
+					const persisted = await resolvePersistedById(deviceId);
+					if (!persisted) throw new Error(`[device-manager] setLocation: unknown device id=${deviceId}`);
+					const { addonId, stableId, meta: m } = persisted;
+					const key = deviceKey(addonId, stableId);
+					const allMeta = await readMeta();
+					await settings.writeAddonStore({ deviceMeta: {
+						...allMeta,
+						[key]: {
+							...m,
+							location
+						}
+					} });
+				});
+				this.ctx.eventBus.emit({
+					id: randomUUID(),
+					timestamp: /* @__PURE__ */ new Date(),
+					source: {
+						type: "device",
+						id: deviceId
+					},
+					category: EventCategory.DeviceMetaChanged,
+					data: {
+						deviceId,
+						field: "location",
+						value: location
+					}
+				});
+			},
+			/**
+			* Patch the device's hardware-identity metadata blob. Shallow
+			* merge — `null` removes a key, anything else overwrites.
+			* Drivers populate factual fields on first probe; operators
+			* augment via the Device Info tab. Idempotent: a no-op patch
+			* (every key already present with the same value) doesn't emit
+			* the meta-changed event.
+			*/
+			setMetadata: async (input) => {
+				const { deviceId, patch } = input;
+				const result = await withMetaWriteLock(async () => {
+					const persisted = await resolvePersistedById(deviceId);
+					if (!persisted) throw new Error(`[device-manager] setMetadata: unknown device id=${deviceId}`);
+					const { addonId, stableId } = persisted;
+					const key = deviceKey(addonId, stableId);
+					const map = await readMetadataMap();
+					const next = { ...map[key] ?? {} };
+					let changed = false;
+					for (const [k, v] of Object.entries(patch)) if (v === null) {
+						if (k in next) {
+							delete next[k];
+							changed = true;
+						}
+					} else if (next[k] !== v) {
+						next[k] = v;
+						changed = true;
+					}
+					if (!changed) return { changed: false };
+					const hasFields = Object.keys(next).length > 0;
+					const updatedMap = { ...map };
+					if (hasFields) updatedMap[key] = next;
+					else delete updatedMap[key];
+					await settings.writeAddonStore({ deviceMetadata: updatedMap });
+					return {
+						changed: true,
+						finalMeta: hasFields ? next : null
+					};
+				});
+				if (!result.changed) return;
+				this.ctx.eventBus.emit({
+					id: randomUUID(),
+					timestamp: /* @__PURE__ */ new Date(),
+					source: {
+						type: "device",
+						id: deviceId
+					},
+					category: EventCategory.DeviceMetaChanged,
+					data: {
+						deviceId,
+						field: "metadata",
+						value: result.finalMeta
+					}
+				});
+			},
+			/**
+			* Soft-disable the device. Persisted on the meta row;
+			* lifecycle gating is the driver's responsibility (BaseDevice
+			* exposes `this.disabled` for the driver to consult at the top
+			* of its lifecycle methods).
+			*/
+			setDisabled: async (input) => {
+				const { deviceId, disabled } = input;
+				await withMetaWriteLock(async () => {
+					const persisted = await resolvePersistedById(deviceId);
+					if (!persisted) throw new Error(`[device-manager] setDisabled: unknown device id=${deviceId}`);
+					const { addonId, stableId, meta: m } = persisted;
+					const key = deviceKey(addonId, stableId);
+					const allMeta = await readMeta();
+					await settings.writeAddonStore({ deviceMeta: {
+						...allMeta,
+						[key]: {
+							...m,
+							disabled
+						}
+					} });
+				});
+				this.ctx.eventBus.emit({
+					id: randomUUID(),
+					timestamp: /* @__PURE__ */ new Date(),
+					source: {
+						type: "device",
+						id: deviceId
+					},
+					category: EventCategory.DeviceMetaChanged,
+					data: {
+						deviceId,
+						field: "disabled",
+						value: disabled
+					}
+				});
+			},
+			loadRuntimeState: async (input) => {
+				const { deviceId } = input;
+				if (!await resolvePersistedById(deviceId)) return {};
+				const data = await settings.readDeviceRuntimeState(deviceId);
+				this.seedMirror(deviceId, data);
+				return data;
+			},
+			/**
+			* Union of (1) operator-curated location registry and (2) labels
+			* currently in use on persisted devices. Case-insensitive
+			* dedupe (preserves the first-seen casing). Sorted
+			* case-insensitively for stable UI. Drives the Device Info
+			* location autocomplete.
+			*/
+			listLocations: async () => {
+				const store = await settings.readAddonStore();
+				const meta = store.deviceMeta ?? {};
+				const registry = store.locations ?? [];
+				const seen = /* @__PURE__ */ new Map();
+				const consider = (raw) => {
+					if (typeof raw !== "string") return;
+					const trimmed = raw.trim();
+					if (trimmed.length === 0) return;
+					const key = trimmed.toLowerCase();
+					if (!seen.has(key)) seen.set(key, trimmed);
+				};
+				for (const label of registry) consider(label);
+				for (const m of Object.values(meta)) consider(m.location);
+				return [...seen.values()].sort((a, b) => a.localeCompare(b, void 0, { sensitivity: "base" }));
+			},
+			/**
+			* Add a label to the curated location registry. Idempotent:
+			* existing entries (case-insensitive match) are silently kept.
+			* Empty / whitespace-only inputs throw — operators must supply a
+			* meaningful label.
+			*/
+			addLocation: async (input) => {
+				const trimmed = input.name.trim();
+				if (trimmed.length === 0) throw new Error("[device-manager] addLocation: name must be non-empty");
+				const current = (await settings.readAddonStore()).locations ?? [];
+				if (current.some((l) => l.toLowerCase() === trimmed.toLowerCase())) return;
+				await settings.writeAddonStore({ locations: [...current, trimmed] });
+			},
+			/**
+			* Remove a label from the curated registry. Match is
+			* case-insensitive. Devices that still reference this label keep
+			* their `meta.location` value (the registry is a suggestion
+			* list, not a foreign key) — pass `cascade: true` to also clear
+			* `setLocation` on every device that referenced this exact
+			* label. Cascade only matches case-insensitively + trimmed, same
+			* as the registry equality check.
+			*/
+			removeLocation: async (input) => {
+				const trimmed = input.name.trim();
+				if (trimmed.length === 0) return;
+				const store = await settings.readAddonStore();
+				const current = store.locations ?? [];
+				const remaining = current.filter((l) => l.toLowerCase() !== trimmed.toLowerCase());
+				if (remaining.length !== current.length) await settings.writeAddonStore({ locations: remaining });
+				if (input.cascade !== true) return;
+				const meta = store.deviceMeta ?? {};
+				const updates = { ...meta };
+				const cleared = [];
+				for (const [key, m] of Object.entries(meta)) {
+					if (typeof m.location !== "string") continue;
+					if (m.location.trim().toLowerCase() !== trimmed.toLowerCase()) continue;
+					updates[key] = {
+						...m,
+						location: null
+					};
+					cleared.push(m.id);
+				}
+				if (cleared.length === 0) return;
+				await settings.writeAddonStore({ deviceMeta: updates });
+				for (const deviceId of cleared) this.ctx.eventBus.emit({
+					id: randomUUID(),
+					timestamp: /* @__PURE__ */ new Date(),
+					source: {
+						type: "device",
+						id: deviceId
+					},
+					category: EventCategory.DeviceMetaChanged,
+					data: {
+						deviceId,
+						field: "location",
+						value: null
+					}
+				});
+			},
+			listPersistedByAddon: async (input) => {
+				const { addonId } = input;
+				const [index, meta] = await Promise.all([readIndex(), readMeta()]);
+				return (index[addonId] ?? []).map((stableId) => {
+					const m = meta[deviceKey(addonId, stableId)];
+					return {
+						id: m.id,
+						stableId,
+						type: m.type,
+						name: m.name,
+						location: m.location ?? null,
+						disabled: m.disabled ?? false,
+						parentDeviceId: m.parentDeviceId
+					};
+				});
+			},
+			listAll: async (input) => {
+				const { addonId } = input;
+				const results = [];
+				const seen = /* @__PURE__ */ new Set();
+				const meta = await readMeta();
+				const metadataMap = await readMetadataMap();
+				if (registry) {
+					const liveEntries = addonId ? registry.getAllForAddon(addonId).map((device) => ({
+						addonId,
+						device
+					})) : registry.getAllWithAddonId();
+					for (const { addonId: aid, device } of liveEntries) {
+						const key = deviceKey(aid, device.stableId);
+						const metadata = metadataMap[key] ?? null;
+						const metaRow = meta[key] ?? null;
+						results.push(toDeviceInfo(aid, device, metadata, metaRow));
+						seen.add(key);
+					}
+				}
+				const index = await readIndex();
+				const targetAddons = addonId ? [addonId] : Object.keys(index);
+				for (const aid of targetAddons) for (const stableId of index[aid] ?? []) {
+					const key = deviceKey(aid, stableId);
+					if (seen.has(key)) continue;
+					const m = meta[key];
+					const persistedType = m.type;
+					const persistedConfig = await settings.readDeviceStore(m.id);
+					const metadata = metadataMap[key] ?? null;
+					results.push({
+						id: m.id,
+						stableId,
+						addonId: aid,
+						type: persistedType,
+						name: m?.name ?? stableId,
+						location: m?.location ?? null,
+						disabled: m?.disabled ?? false,
+						parentDeviceId: m?.parentDeviceId ?? null,
+						role: null,
+						online: registry !== null,
+						features: persistedFeatures(m?.features),
+						isCamera: persistedType === DeviceType.Camera,
+						config: persistedConfig ?? {},
+						metadata
+					});
+				}
+				return results;
+			},
+			getDevice: async (input) => {
+				const { deviceId } = input;
+				if (registry) {
+					const found = resolveDeviceById(registry, deviceId);
+					if (found) {
+						const key = deviceKey(found.addonId, found.device.stableId);
+						const [map, metaMap] = await Promise.all([readMetadataMap(), readMeta()]);
+						const metadata = map[key] ?? null;
+						const metaRow = metaMap[key] ?? null;
+						return toDeviceInfo(found.addonId, found.device, metadata, metaRow);
+					}
+				}
+				const persisted = await resolvePersistedById(deviceId);
+				if (!persisted) return null;
+				const { addonId: aid, stableId, meta: m } = persisted;
+				const persistedConfig = await settings.readDeviceStore(m.id);
+				const key = deviceKey(aid, stableId);
+				const metadata = (await readMetadataMap())[key] ?? null;
+				return {
+					id: deviceId,
+					stableId,
+					addonId: aid,
+					type: m.type,
+					name: m.name,
+					location: m.location ?? null,
+					disabled: m.disabled ?? false,
+					parentDeviceId: m.parentDeviceId,
+					role: null,
+					online: true,
+					features: persistedFeatures(m.features),
+					isCamera: false,
+					config: persistedConfig ?? {},
+					metadata
+				};
+			},
+			getChildren: async (input) => {
+				const { parentDeviceId } = input;
+				let ownerAddonId = null;
+				if (registry) {
+					if (registry.getById(parentDeviceId)) ownerAddonId = registry.getAddonId(parentDeviceId);
+				}
+				if (!ownerAddonId) {
+					const persisted = await resolvePersistedById(parentDeviceId);
+					if (!persisted) return [];
+					ownerAddonId = persisted.addonId;
+				}
+				const results = [];
+				const seen = /* @__PURE__ */ new Set();
+				const [index, meta, metadataMap] = await Promise.all([
+					readIndex(),
+					readMeta(),
+					readMetadataMap()
+				]);
+				if (registry) {
+					const liveChildren = registry.getChildren(parentDeviceId);
+					for (const device of liveChildren) {
+						const key = deviceKey(ownerAddonId, device.stableId);
+						const metadata = metadataMap[key] ?? null;
+						const metaRow = meta[key] ?? null;
+						results.push(toDeviceInfo(ownerAddonId, device, metadata, metaRow));
+						seen.add(key);
+					}
+				}
+				const persistedChildren = (index[ownerAddonId] ?? []).filter((sid) => meta[deviceKey(ownerAddonId, sid)]?.parentDeviceId === parentDeviceId);
+				for (const childStableId of persistedChildren) {
+					const key = deviceKey(ownerAddonId, childStableId);
+					if (seen.has(key)) continue;
+					const m = meta[key];
+					const persistedConfig = await settings.readDeviceStore(m.id);
+					const metadata = metadataMap[key] ?? null;
+					results.push({
+						id: m.id,
+						stableId: childStableId,
+						addonId: ownerAddonId,
+						type: m.type,
+						name: m.name,
+						location: m.location ?? null,
+						disabled: m.disabled ?? false,
+						parentDeviceId,
+						role: null,
+						online: registry !== null,
+						features: persistedFeatures(m.features),
+						isCamera: false,
+						config: persistedConfig ?? {},
+						metadata
+					});
+				}
+				return results;
+			},
+			getStreamSources: async (input) => {
+				const { deviceId } = input;
+				if (registry) {
+					const found = resolveDeviceById(registry, deviceId);
+					if (found) {
+						if (!isCameraDevice(found.device)) return [];
+						return (await found.device.getStreamSources()).map((s) => ({
+							id: s.id,
+							label: s.label,
+							protocol: s.protocol,
+							url: s.url,
+							resolution: s.resolution,
+							fps: s.fps,
+							bitrate: s.bitrate,
+							codec: s.codec,
+							profileHint: s.profileHint
+						}));
+					}
+				}
+				if (!await resolvePersistedById(deviceId)) throw new Error(`[device-manager] Device with id ${deviceId} not found`);
+				return (await requireDeviceOps(deviceId).getStreamSources({ deviceId })).map((s) => ({ ...s }));
+			},
+			getConfigSchema: async (input) => {
+				const { deviceId } = input;
+				if (registry) {
+					const found = resolveDeviceById(registry, deviceId);
+					if (found) return found.device.config.entries().map((entry) => ({
+						key: entry.key,
+						value: entry.value,
+						...entry.description !== void 0 ? { description: entry.description } : {}
+					}));
+				}
+				if (!await resolvePersistedById(deviceId)) throw new Error(`[device-manager] Device with id ${deviceId} not found`);
+				return (await requireDeviceOps(deviceId).getConfigEntries({ deviceId })).map((e) => ({ ...e }));
+			},
+			getSettingsSchema: async (input) => {
+				const { deviceId } = input;
+				if (registry) {
+					const found = resolveDeviceById(registry, deviceId);
+					if (found) return found.device.getSettingsUISchema();
+				}
+				if (!await resolvePersistedById(deviceId)) return null;
+				return await requireDeviceOps(deviceId).getSettingsSchema({ deviceId }) ?? null;
+			},
+			updateConfig: async (input) => {
+				const { deviceId } = input;
+				if (registry) {
+					const found = resolveDeviceById(registry, deviceId);
+					if (found) {
+						await found.device.config.setAll(input.values);
+						return { success: true };
+					}
+				}
+				if (!await resolvePersistedById(deviceId)) throw new Error(`[device-manager] Device with id ${deviceId} not found`);
+				await requireDeviceOps(deviceId).setConfig({
+					deviceId,
+					values: input.values
+				});
+				return { success: true };
+			},
+			enable: async (input) => {
+				await provider.setDisabled({
+					deviceId: input.deviceId,
+					disabled: false
+				});
+				return { success: true };
+			},
+			disable: async (input) => {
+				await provider.setDisabled({
+					deviceId: input.deviceId,
+					disabled: true
+				});
+				return { success: true };
+			},
+			remove: async (input) => {
+				const { deviceId } = input;
+				if (registry) {
+					const live = resolveDeviceById(registry, deviceId);
+					if (live) {
+						const deviceName = live.device.name;
+						await live.device.removeDevice();
+						registry.remove(deviceId);
+						await provider.removeDevice({ deviceId });
+						this.ctx.logger.info("removed hub-local device", { tags: {
+							deviceId,
+							deviceName
+						} });
+						return { success: true };
+					}
+				}
+				const persisted = await resolvePersistedById(deviceId);
+				if (!persisted) throw new Error(`[device-manager] Device with id ${deviceId} not found`);
+				const { meta: persistedMeta } = persisted;
+				try {
+					await requireDeviceOps(deviceId).removeDevice({ deviceId });
+				} catch (err) {
+					this.ctx.logger.warn("remove via device-ops failed — clearing persistence anyway", {
+						tags: {
+							deviceId,
+							deviceName: persistedMeta.name
+						},
+						meta: { error: errMsg(err) }
+					});
+				}
+				await provider.removeDevice({ deviceId });
+				return { success: true };
+			},
+			getStreamProfileMap: async (input) => {
+				if (!registry) return {};
+				const found = resolveDeviceById(registry, input.deviceId);
+				if (!found) return {};
+				const storedMap = found.device.config.entries().find((e) => e.key === "_profileMap")?.value;
+				if (storedMap !== void 0 && typeof storedMap === "object" && storedMap !== null) return storedMap;
+				if (!isCameraDevice(found.device)) return {};
+				const sources = await found.device.getStreamSources();
+				const profileMap = {};
+				for (const s of sources) if (s.profileHint && s.id) profileMap[s.profileHint] = s.id;
+				return profileMap;
+			},
+			setStreamProfileMap: async (input) => {
+				const { deviceId } = input;
+				if (registry) {
+					const found = resolveDeviceById(registry, deviceId);
+					if (found) {
+						await found.device.config.setAll({ _profileMap: input.profileMap });
+						return { success: true };
+					}
+				}
+				if (!await resolvePersistedById(deviceId)) throw new Error(`[device-manager] Device with id ${deviceId} not found`);
+				await requireDeviceOps(deviceId).setConfig({
+					deviceId,
+					values: { _profileMap: input.profileMap }
+				});
+				return { success: true };
+			},
+			probeStreams: async (input) => {
+				const streamProbe = this.ctx.kernel.streamProbe;
+				if (!streamProbe) return [];
+				const sources = await provider.getStreamSources({ deviceId: input.deviceId });
+				const results = [];
+				for (const s of sources) {
+					if (!s.url) continue;
+					try {
+						const metadata = await streamProbe.probe(s.url, { force: true });
+						results.push({
+							streamId: s.id,
+							width: metadata.width,
+							height: metadata.height,
+							codec: metadata.codec,
+							fps: metadata.fps,
+							bitrateKbps: metadata.bitrateKbps
+						});
+					} catch (err) {
+						this.ctx.logger.debug("streamProbe.probe failed — returning placeholder", { meta: {
+							deviceId: input.deviceId,
+							streamId: s.id,
+							error: err instanceof Error ? err.message : String(err)
+						} });
+						results.push({ streamId: s.id });
+					}
+				}
+				return results;
+			},
+			discoverDevices: async (input) => {
+				const dp = await this.requireDeviceProvider(input.addonId);
+				if (!await dp.supportsDiscovery({})) throw new Error(`Addon "${input.addonId}" does not support device discovery`);
+				return (await dp.discoverDevices({})).map((d) => ({
+					stableId: d.stableId,
+					type: d.type,
+					suggestedName: d.suggestedName,
+					prefilledConfig: d.prefilledConfig
+				}));
+			},
+			adoptDevice: async (input) => {
+				const dp = await this.requireDeviceProvider(input.addonId);
+				if (!await dp.supportsDiscovery({})) throw new Error(`Addon "${input.addonId}" does not support device adoption`);
+				return dp.adoptDiscoveredDevice({ candidate: input.candidate });
+			},
+			getCreationSchema: async (input) => {
+				const dp = await this.requireDeviceProvider(input.addonId);
+				if (!await dp.supportsManualCreation({})) return null;
+				return await dp.getChildCreationSchema({ type: input.type }) ?? null;
+			},
+			createDevice: async (input) => {
+				const dp = await this.requireDeviceProvider(input.addonId);
+				if (!await dp.supportsManualCreation({})) throw new Error(`Addon "${input.addonId}" does not support manual device creation`);
+				return dp.createDevice({
+					type: input.type,
+					config: input.config
+				});
+			},
+			testCreationField: async (input) => {
+				return (await this.requireDeviceProvider(input.addonId)).testCreationField({
+					type: input.type,
+					key: input.key,
+					value: input.value,
+					...input.formValues !== void 0 ? { formValues: input.formValues } : {}
+				});
+			},
+			testField: async (input) => {
+				const { deviceId } = input;
+				let owningAddonId = null;
+				if (registry) owningAddonId = registry.getAddonId(deviceId);
+				if (!owningAddonId) owningAddonId = (await resolvePersistedById(deviceId))?.addonId ?? null;
+				if (!owningAddonId) throw new Error(`Device with id ${deviceId} not found`);
+				const dp = await this.waitDeviceProvider(owningAddonId);
+				if (!dp) return {
+					status: "ok",
+					labels: [],
+					error: void 0
+				};
+				if (typeof dp.testCreationField !== "function") return {
+					status: "ok",
+					labels: [],
+					error: void 0
+				};
+				return dp.testCreationField({
+					type: DeviceType.Camera,
+					key: input.key,
+					value: input.value
+				});
+			},
+			getBindings: async (input) => {
+				const result = await this.getBindings({ deviceId: input.deviceId });
+				return {
+					deviceId: input.deviceId,
+					entries: result.entries
+				};
+			},
+			getAllBindings: async () => {
+				return this.getAllBindings();
+			},
+			setWrapperActive: async (input) => {
+				return this.setWrapperActive({
+					deviceId: input.deviceId,
+					capName: input.capName,
+					wrapperAddonId: input.wrapperAddonId,
+					active: input.active
+				});
+			},
+			listWrappersForCap: async (input) => this.listWrappersForCap(input),
+			listBindableCapsForDeviceType: async (input) => this.listBindableCapsForDeviceType(input),
+			getDeviceSettingsAggregate: async (input) => {
+				return this.getDeviceAggregate(input.deviceId, "settings");
+			},
+			getDeviceLiveInfoAggregate: async (input) => {
+				return this.getDeviceAggregate(input.deviceId, "live");
+			},
+			getDeviceAggregate: async (input) => {
+				const [settings, live] = await Promise.all([this.getDeviceAggregate(input.deviceId, "settings"), this.getDeviceAggregate(input.deviceId, "live")]);
+				return {
+					settings,
+					live
+				};
+			},
+			updateDeviceField: async (input) => {
+				return this.updateDeviceField({
+					deviceId: input.deviceId,
+					writerCapName: input.writerCapName,
+					writerAddonId: input.writerAddonId,
+					key: input.key,
+					value: input.value
+				});
+			},
+			updateDeviceFieldsBatch: async (input) => {
+				return this.updateDeviceFieldsBatch({
+					deviceId: input.deviceId,
+					changes: input.changes
+				});
+			},
+			getDeviceStatusAggregate: async (input) => this.getDeviceStatusAggregate(input)
+		};
+		this.ctx.logger.info("registered device-manager capability", { meta: { liveRegistry: registry !== null } });
+		if (registry) {
+			this.propagator = new DeviceEventPropagator({
+				eventBus: this.ctx.eventBus,
+				getParentOf: (id) => registry.getById(id)?.parentDeviceId ?? null,
+				logger: {
+					warn: (msg, meta) => this.ctx.logger.warn(msg, meta ?? {}),
+					debug: (msg, meta) => this.ctx.logger.debug(msg, meta ?? {})
+				}
+			});
+			this.propagator.start();
+			this.ctx.logger.info("device-event-propagator started");
+		}
+		return [{
+			capability: deviceManagerCapability,
+			provider
+		}, {
+			capability: deviceStateCapability,
+			provider: {
+				getSnapshot: async (input) => {
+					return this.snapshotForDevice(input.deviceId);
+				},
+				getCapSlice: async (input) => {
+					const slice = this.stateMirror.get(input.deviceId)?.get(input.capName);
+					return slice ? { ...slice } : null;
+				},
+				getAllSnapshots: async () => {
+					const out = {};
+					for (const [deviceId, perCap] of this.stateMirror) {
+						const dev = {};
+						for (const [capName, slice] of perCap) dev[capName] = { ...slice };
+						out[String(deviceId)] = dev;
+					}
+					return out;
+				},
+				setCapSlice: async (input) => {
+					const { deviceId, capName, slice } = input;
+					if (!await resolvePersistedById(deviceId)) throw new Error(`[device-manager] setCapSlice: unknown device id=${deviceId}`);
+					this.applySingleCapUpdate(deviceId, capName, slice);
+					this.scheduleRuntimeStateDiskWrite(deviceId, settings);
+				}
+			}
+		}];
+	}
+	/**
+	* Single-cap mirror update — diff against the current mirror,
+	* persist the new slice in-memory, emit `DeviceStateChanged` for
+	* this cap. No-op on identical writes (both same shape and same
+	* values). Called by `setCapSlice` provider.
+	*/
+	applySingleCapUpdate(deviceId, capName, slice) {
+		let perCap = this.stateMirror.get(deviceId);
+		if (!perCap) {
+			perCap = /* @__PURE__ */ new Map();
+			this.stateMirror.set(deviceId, perCap);
+		}
+		const prior = perCap.get(capName);
+		if (prior && shallowEqual(prior, slice)) return;
+		perCap.set(capName, { ...slice });
+		this.emitStateChanged(deviceId, capName, slice);
+	}
+	/**
+	* Debounced disk writer. Coalesces frequent writes (motion phase
+	* transitions, battery pushes) into one `writeDeviceRuntimeState`
+	* per `RUNTIME_STATE_DEBOUNCE_MS` window. Reads the per-device
+	* blob from the live mirror at flush time so the disk picture is
+	* always the latest state — no risk of writing a stale snapshot.
+	*/
+	scheduleRuntimeStateDiskWrite(deviceId, settings) {
+		let slot = this.runtimeStateDebounce.get(deviceId);
+		if (!slot) {
+			slot = {
+				timer: null,
+				inFlight: null
+			};
+			this.runtimeStateDebounce.set(deviceId, slot);
+		}
+		if (slot.timer) return;
+		slot.timer = setTimeout(() => {
+			slot.timer = null;
+			const blob = this.snapshotForDevice(deviceId);
+			const write = (async () => {
+				try {
+					await settings.writeDeviceRuntimeState(deviceId, blob);
+				} catch (err) {
+					this.ctx.logger.warn("writeDeviceRuntimeState failed", {
+						tags: { deviceId },
+						meta: { error: err instanceof Error ? err.message : String(err) }
+					});
+				} finally {
+					slot.inFlight = null;
+				}
+			})();
+			slot.inFlight = write;
+		}, DeviceManagerAddon.RUNTIME_STATE_DEBOUNCE_MS);
+	}
+	/**
+	* One-shot mirror seed used by `loadRuntimeState` at boot so the
+	* hub knows about every persisted slice without waiting for the
+	* first `setCapSlice` call. No events emitted — this is
+	* initial-state population, not a transition.
+	*/
+	seedMirror(deviceId, blob) {
+		let perCap = this.stateMirror.get(deviceId);
+		if (!perCap) {
+			perCap = /* @__PURE__ */ new Map();
+			this.stateMirror.set(deviceId, perCap);
+		}
+		for (const [capName, raw] of Object.entries(blob)) {
+			if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
+			perCap.set(capName, { ...raw });
+		}
+	}
+	snapshotForDevice(deviceId) {
+		const perCap = this.stateMirror.get(deviceId);
+		if (!perCap) return {};
+		const out = {};
+		for (const [k, v] of perCap) out[k] = { ...v };
+		return out;
+	}
+	emitStateChanged(deviceId, capName, slice) {
+		this.ctx.eventBus.emit({
+			id: randomUUID(),
+			timestamp: /* @__PURE__ */ new Date(),
+			source: {
+				type: "device",
+				id: deviceId
+			},
+			category: EventCategory.DeviceStateChanged,
+			data: {
+				deviceId,
+				capName,
+				slice
+			}
+		});
+	}
+	async onShutdown() {
+		this.propagator?.stop();
+		this.propagator = null;
+		const settings = this.ctx.settings;
+		const pending = [];
+		for (const [deviceId, slot] of this.runtimeStateDebounce) {
+			if (slot.timer) {
+				clearTimeout(slot.timer);
+				slot.timer = null;
+				if (settings) {
+					const blob = this.snapshotForDevice(deviceId);
+					pending.push(settings.writeDeviceRuntimeState(deviceId, blob).catch((err) => {
+						this.ctx.logger.warn("shutdown writeDeviceRuntimeState failed", {
+							tags: { deviceId },
+							meta: { error: err instanceof Error ? err.message : String(err) }
+						});
+					}));
+				}
+			}
+			if (slot.inFlight) pending.push(slot.inFlight);
+		}
+		await Promise.all(pending);
+		this.runtimeStateDebounce.clear();
+	}
+};
+//#endregion
+export { DeviceManagerAddon, DeviceManagerAddon as default };
+
 //# sourceMappingURL=device-manager.addon.mjs.map