@camstack/system 1.0.2

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

@@ -0,0 +1,3292 @@
+import { canonicalDeviceFingerprint } from "@camstack/types/node";
+import { BaseAddon, CAP_NAMES_WITH_STATUS, DeviceFeature, DeviceRole, DeviceStatusSchema, DeviceType, EventCategory, STREAM_PROFILE_META, WELL_KNOWN_TAB_MAP, applyTransform, buildStreamParamsConfigSchema, deviceManagerCapability, deviceStateCapability, deviceStatusCapability, enumerateSchemaFields, errMsg, getByPath, isDeviceConfigCap, parseStreamParamsFormPatch, setByPath, sleep } from "@camstack/types";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+//#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 {
+	opts;
+	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;
+	}
+};
+/**
+* Build the device-detail form section for a `derived-form` device-config
+* cap. Returns null when the camera exposes no configurable property.
+*/
+function deriveFormContribution(builderId, options, status) {
+	if (builderId !== "stream-params") throw new Error(`device-config: unknown derived-form builderId "${builderId}"`);
+	const schema = buildStreamParamsConfigSchema(options, status ?? null);
+	if (!schema) return null;
+	return { sections: schema.sections.map((s) => ({
+		id: s.id,
+		title: s.title,
+		...s.tab !== void 0 ? { tab: s.tab } : {},
+		...s.order !== void 0 ? { order: s.order } : {},
+		...s.description !== void 0 ? { description: s.description } : {},
+		...s.columns !== void 0 ? { columns: s.columns } : {},
+		fields: [...s.fields]
+	})) };
+}
+/**
+* Route a flat form patch back through the cap's per-profile setter.
+*/
+async function applyDerivedFormPatch(builderId, patch, setProfile) {
+	if (builderId !== "stream-params") throw new Error(`device-config: unknown derived-form builderId "${builderId}"`);
+	for (const meta of STREAM_PROFILE_META) {
+		const profilePatch = parseStreamParamsFormPatch(patch, meta.prefix);
+		if (profilePatch) await setProfile(meta.profile, profilePatch);
+	}
+}
+//#endregion
+//#region src/builtins/device-manager/device-link-resolver.ts
+/** Returns true when `x` is a non-null, non-array plain object. */
+function isRecord$1(x) {
+	return x !== null && typeof x === "object" && !Array.isArray(x);
+}
+/** Narrow Zod v4's structural `$ZodType` (returned by `.unwrap()`) back to the
+*  concrete classic `z.ZodType`. Every runtime schema is a `z.ZodType`, so this
+*  is a true `instanceof` guard rather than a cast. */
+function asZodType(schema) {
+	return schema instanceof z.ZodType ? schema : null;
+}
+/** Unwrap ZodNullable / ZodOptional / ZodDefault wrappers to reach the inner
+*  type. This lets the repair logic recognise a `TankStatus.nullable()` field
+*  as a ZodObject so it can fill in missing nullable keys. */
+function unwrapSchema(schema) {
+	if (schema instanceof z.ZodNullable || schema instanceof z.ZodOptional || schema instanceof z.ZodDefault) {
+		const inner = asZodType(schema.unwrap());
+		return inner ? unwrapSchema(inner) : schema;
+	}
+	return schema;
+}
+/** For a ZodObject schema, ensure every nullable key present under `value` is
+*  filled — a missing key whose field accepts `null` is set to `null`. Generic
+*  repair for the common "set one leaf of a previously-null structured field"
+*  case (e.g. TankStatus.level). Recurses into nested object fields. */
+function fillNullableDefaults(schema, value) {
+	const inner = unwrapSchema(schema);
+	if (!(inner instanceof z.ZodObject) || !isRecord$1(value)) return value;
+	const shape = inner.shape;
+	const out = { ...value };
+	for (const [key, field] of Object.entries(shape)) if (out[key] === void 0) {
+		if (field.safeParse(null).success) out[key] = null;
+	} else out[key] = fillNullableDefaults(field, out[key]);
+	return out;
+}
+/**
+* Overlay transformed source values onto `base` by dot-path, then validate the
+* result against the target cap's `statusSchema`. On validation failure the
+* overlay is discarded and `base` is returned unchanged (a misconfigured link
+* must never corrupt a cap response). Pure — all I/O happens in the caller.
+*/
+function mergeLinkedStatus(base, resolved, statusSchema) {
+	let draft = base;
+	let touched = false;
+	for (const { link, sourceValue } of resolved) {
+		if (sourceValue === void 0) continue;
+		draft = setByPath(draft, link.target.fieldPath, sourceValue);
+		touched = true;
+	}
+	if (!touched) return base;
+	if (!statusSchema) return draft;
+	const repaired = fillNullableDefaults(statusSchema, draft);
+	const parsed = statusSchema.safeParse(repaired);
+	if (!parsed.success) return base;
+	return isRecord$1(parsed.data) ? parsed.data : base;
+}
+//#endregion
+//#region src/builtins/device-manager/device-link-overlay.ts
+/** Build both lookup maps from resolved link entries. Pure — order-preserving. */
+function buildLinkIndexes(entries) {
+	const targets = /* @__PURE__ */ new Map();
+	const dependents = /* @__PURE__ */ new Map();
+	for (const { targetDeviceId, link, sourceDeviceId } of entries) {
+		const tKey = `${targetDeviceId}:${link.target.cap}`;
+		const tList = targets.get(tKey) ?? [];
+		tList.push({
+			link,
+			sourceDeviceId
+		});
+		targets.set(tKey, tList);
+		const sKey = `${sourceDeviceId}:${link.source.cap}`;
+		const sList = dependents.get(sKey) ?? [];
+		sList.push({
+			targetDeviceId,
+			targetCap: link.target.cap
+		});
+		dependents.set(sKey, sList);
+	}
+	return {
+		targets,
+		dependents
+	};
+}
+//#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`
+*/
+/**
+* Return true when `err` is a transient Moleculer error that is worth
+* retrying — specifically any `MoleculerRetryableError` subclass
+* (ServiceNotAvailableError, ServiceNotFoundError, BrokerDisconnectedError,
+* RequestTimeoutError, …). Moleculer sets `retryable: true` on all of them.
+*
+* Falls back to a message-substring check for serialised errors that arrive
+* across the Moleculer transport as plain objects rather than real instances.
+*/
+function isTransientMoleculerError(err) {
+	if (err !== null && typeof err === "object") {
+		const e = err;
+		if (e["retryable"] === true) return true;
+		const code = typeof e["code"] === "string" ? e["code"] : "";
+		if (code === "SERVICE_NOT_FOUND" || code === "SERVICE_NOT_AVAILABLE" || code === "REQUEST_TIMEOUT" || code === "BAD_GATEWAY") return true;
+	}
+	if (err instanceof Error) {
+		const msg = err.message;
+		if (msg.includes("is not available") || msg.includes("is not found") || msg.includes("transporter has disconnected") || msg.includes("Request timed out")) return true;
+	}
+	return false;
+}
+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}`;
+}
+/** Returns true when `x` is a non-null, non-array plain object. */
+function isRecord(x) {
+	return x !== null && typeof x === "object" && !Array.isArray(x);
+}
+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;
+}
+/**
+* Build an identity-only `SourceInfo` from the persisted device config blob.
+*
+* Forked-worker accessory children (e.g. HA sensor entities) persist
+* `entityId` and `system` in their config blob at spawn time. The hub has no
+* live `IDevice` instance for these devices, so the persisted-fallback paths
+* in `listAll` / `getDevice` / `getChildren` must reconstruct the identity
+* `SourceInfo` from the config so dispatch routing keeps working.
+*
+* Rendering metadata (unit, precision) flows live through the cap STATUS SLICE
+* and must NOT be derived here. Only `id` + `system` (+ `uniqueId` when
+* present) are projected — purely identity, never rendering hints.
+*
+* Returns `undefined` when no identity anchor is resolvable (pure identity
+* devices like cameras/hubs that don't carry `entityId`/`system` in their
+* config blob) — the hub synthetic fallback applies in that case.
+*/
+function buildSourceInfoFromConfig(persistedConfig, stableId, addonId) {
+	const id = typeof persistedConfig["entityId"] === "string" ? persistedConfig["entityId"] : void 0;
+	const system = typeof persistedConfig["system"] === "string" ? persistedConfig["system"] : void 0;
+	if (id === void 0 && system === void 0) return void 0;
+	const uniqueId = typeof persistedConfig["uniqueId"] === "string" ? persistedConfig["uniqueId"] : void 0;
+	return {
+		id: id ?? stableId,
+		system: system ?? addonId,
+		...uniqueId !== void 0 ? { uniqueId } : {}
+	};
+}
+var DEVICE_ROLE_VALUES = new Set(Object.values(DeviceRole));
+/** Type guard: a string is a known `DeviceRole` enum member. */
+function isDeviceRole(value) {
+	return DEVICE_ROLE_VALUES.has(value);
+}
+/** Narrow a persisted role string (sqlite TEXT column) to a `DeviceRole`.
+*  Unknown / null values resolve to `null` so a stale or unrecognised role
+*  never leaks an off-enum string onto the wire shape. */
+function toDeviceRole(value) {
+	return value != null && isDeviceRole(value) ? value : null;
+}
+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;
+	const probeSlice = device.runtimeState?.getCapState("feature-probe");
+	const probed = probeSlice === void 0 ? true : (probeSlice.lastProbedAt ?? 0) > 0;
+	return {
+		id: device.id,
+		stableId: device.stableId,
+		addonId,
+		type: device.type,
+		name,
+		location,
+		disabled,
+		parentDeviceId: device.parentDeviceId,
+		role: device.role ?? null,
+		online: device.online,
+		probed,
+		features: device.features.length > 0 ? [...device.features] : persistedFeatures(metaRow?.features),
+		isCamera: isCameraDevice(device),
+		config: configValues,
+		metadata,
+		...metaRow?.integrationId !== void 0 ? { integrationId: metaRow.integrationId } : {},
+		...metaRow?.linkDeviceId !== void 0 ? { linkDeviceId: metaRow.linkDeviceId } : {},
+		...metaRow?.primaryChildEntityId !== void 0 ? { primaryChildEntityId: metaRow.primaryChildEntityId } : {},
+		...metaRow?.childLayout !== void 0 ? { childLayout: metaRow.childLayout } : {},
+		...metaRow?.deviceLinks !== void 0 ? { deviceLinks: metaRow.deviceLinks } : {}
+	};
+}
+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 = [];
+	const seenSectionIds = /* @__PURE__ */ new Set();
+	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) {
+			if (s.id !== void 0) {
+				if (seenSectionIds.has(s.id)) continue;
+				seenSectionIds.add(s.id);
+			}
+			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()].toSorted((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 `DeviceBindingsChanged` push events emitted by forked
+	* workers on `ctx.registerNativeCap` / device removal. Union'd into
+	* `getBindings` so hub-side consumers see every native cap regardless of
+	* which process owns the IDevice.
+	*
+	* No persistence — entries re-populate when the worker re-handshakes or
+	* re-emits its native-cap registrations after restart. Entries that were
+	* lost in the Moleculer transport handshake window are recovered lazily:
+	* `resolveNativeCapOwnerSync` and `getBindings` fall through to
+	* `ctx.kernel.listClusterNativeCaps()` (the handshake-fed
+	* `HubNodeRegistry`) when the push-based cache misses.
+	*
+	* The previous pull-based recovery (`syncWorkerNativeCaps`, driven by
+	* `$node.connected` + `addon.restarted`) has been removed in Task 13 —
+	* the D3 re-handshake after device restore is the reliable replacement.
+	*/
+	remoteNativeCaps = /* @__PURE__ */ new Map();
+	/** Device ids that currently have at least one `deviceLinks` entry. O(1) gate
+	*  consulted by `resolveLinkedStatus` so the cap-mount overlay is a no-op for
+	*  the vast majority of devices that have no links. Rebuilt on restore. */
+	devicesWithLinks = /* @__PURE__ */ new Set();
+	/** Whether a device currently has cross-device links. */
+	devicesWithLinksHas(deviceId) {
+		return this.devicesWithLinks.has(deviceId);
+	}
+	/** `${targetDeviceId}:${targetCap}` → resolved links feeding that cap's slice. */
+	linkTargets = /* @__PURE__ */ new Map();
+	/** `${sourceDeviceId}:${sourceCap}` → targets to recompute when that source changes. */
+	linkDependents = /* @__PURE__ */ new Map();
+	/** Loop/churn guard: last overlaid slice emitted per `${deviceId}:${cap}`. */
+	lastEmittedOverlay = /* @__PURE__ */ new Map();
+	/** Expected source `stableId`s (`${container}-${sourceKey}`) across all links,
+	*  resolved or not — gates the `registerDevice` rebuild so only a registering
+	*  device that IS a link source triggers a reindex (not every boot restore). */
+	expectedSourceStableIds = /* @__PURE__ */ new Set();
+	/** Test/diagnostic accessors. */
+	linkTargetKeys() {
+		return [...this.linkTargets.keys()];
+	}
+	linkDependentsKeys() {
+		return [...this.linkDependents.keys()];
+	}
+	/** 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;
+	}
+	/** Require a device-adoption provider by addonId — throws if not found. */
+	async requireDeviceAdoptionProvider(addonId) {
+		const provider = await this.capabilityRegistry?.waitForProvider("device-adoption", addonId, 5e3);
+		if (!provider) throw new Error(`Device-adoption provider "${addonId}" not found or not registered`);
+		return provider;
+	}
+	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";
+	}
+	/**
+	* Reduce a provider node id to the routable form `DeviceProxy` can pin.
+	*
+	* Every addon runs in its own `addon-runner` with the composite node id
+	* `${parentNodeId}/${runnerId}` (see `addon-runner.ts`) — e.g.
+	* `hub/provider-reolink` or `dev-agent-0/provider-reolink`. That composite is
+	* an IDENTITY, not a routable target: the `CapRouteResolver` reaches a child
+	* only THROUGH its parent (the hub resolves a hub-local-uds child by
+	* cap+device; an agent forwards to its own child). `DeviceProxy` pins
+	* `entry.providerNodeId` on every cap call, so a binding entry must expose the
+	* parent node id — otherwise the explicit pin classifies as `remote-moleculer`
+	* to an unknown node → `no-provider`, which surfaces as
+	* "this camera doesn't expose …" for client-proxy-driven widget caps
+	* (motion-zones, privacy-mask). Wrappers already report the parent via
+	* `resolveWrapperNodeId`; this aligns natives with the same contract.
+	*
+	* A flat node id (a genuine standalone node with no `/`) is returned
+	* unchanged.
+	*/
+	toRoutableProviderNodeId(nodeId) {
+		const slash = nodeId.indexOf("/");
+		return slash === -1 ? nodeId : nodeId.slice(0, slash);
+	}
+	/**
+	* Resolve a remote native cap entry for a given `(capName, deviceId)` by
+	* consulting the handshake-fed `HubNodeRegistry` via
+	* `ctx.kernel.listClusterNativeCaps()`. Called when the push-based
+	* `remoteNativeCaps` cache misses — covers the Moleculer transport
+	* handshake window where `DeviceBindingsChanged` events were lost but the
+	* D3 re-handshake (post device restore) has already populated the registry.
+	*
+	* Returns `null` when the entry is genuinely not present in the cluster
+	* view (cap not registered on any worker for that device).
+	*/
+	resolveRemoteNativeCapFromRegistry(capName, deviceId) {
+		const clusterCaps = this.ctx.kernel.listClusterNativeCapsForDevice?.(deviceId) ?? this.ctx.kernel.listClusterNativeCaps?.();
+		if (!clusterCaps) return null;
+		for (const entry of clusterCaps) if (entry.capName === capName && entry.deviceId === deviceId && entry.addonId) return {
+			addonId: entry.addonId,
+			nodeId: entry.nodeId
+		};
+		return null;
+	}
+	async getBindings(input) {
+		const storeKey = String(input.deviceId);
+		const perDevice = (await this.readBindingsStore()).deviceBindings[storeKey] ?? {};
+		const entries = [];
+		const seenCaps = /* @__PURE__ */ new Set();
+		const resolveRemote = (capName) => this.remoteNativeCaps.get(input.deviceId)?.get(capName) ?? this.resolveRemoteNativeCapFromRegistry(capName, input.deviceId);
+		for (const [capName, { wrapperAddonId }] of Object.entries(perDevice)) {
+			const hubLocalNative = this.capabilityRegistry?.getNativeAddonId(capName, input.deviceId) ?? null;
+			const remoteNative = resolveRemote(capName);
+			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) : this.toRoutableProviderNodeId(nativeNodeId),
+				nativeAddonId
+			});
+			seenCaps.add(capName);
+		}
+		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 = resolveRemote(capName);
+			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);
+		}
+		const pushFed = this.remoteNativeCaps.get(input.deviceId);
+		if (pushFed) for (const [capName, info] of pushFed) {
+			if (seenCaps.has(capName)) continue;
+			entries.push({
+				capName,
+				kind: "native",
+				providerAddonId: info.addonId,
+				providerNodeId: this.toRoutableProviderNodeId(info.nodeId),
+				nativeAddonId: info.addonId
+			});
+			seenCaps.add(capName);
+		}
+		const clusterCaps = this.ctx.kernel.listClusterNativeCapsForDevice?.(input.deviceId) ?? this.ctx.kernel.listClusterNativeCaps?.();
+		if (clusterCaps) for (const entry of clusterCaps) {
+			if (entry.deviceId !== input.deviceId) continue;
+			if (seenCaps.has(entry.capName)) continue;
+			if (!entry.addonId) continue;
+			const localNodeId = this.ctx.kernel.localNodeId ?? "hub";
+			if (entry.nodeId === localNodeId) continue;
+			entries.push({
+				capName: entry.capName,
+				kind: "native",
+				providerAddonId: entry.addonId,
+				providerNodeId: this.toRoutableProviderNodeId(entry.nodeId),
+				nativeAddonId: entry.addonId
+			});
+			seenCaps.add(entry.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 { entries: bindingEntries } = await this.getBindings({ deviceId });
+		const seenCaps = new Set(bindingEntries.map((e) => e.capName));
+		const results = await Promise.all(bindingEntries.map(async (entry) => {
+			const def = registry.getDefinition(entry.capName);
+			if (isDeviceConfigCap(def)) return this.deriveDeviceConfigContribution(registry, def, entry, deviceId, kind);
+			if (!def?.exposesDeviceSettings) return null;
+			const provider = registry.getProviderByAddon(entry.capName, entry.providerAddonId);
+			if (!provider) return null;
+			try {
+				const contribution = await provider[method]({ deviceId });
+				if (!contribution) return null;
+				return tagContribution(toWireShape(contribution), entry.capName, entry.providerAddonId, kind);
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				this.ctx.logger.warn("contribution method failed", {
+					tags: {
+						deviceId,
+						addonId: entry.providerAddonId
+					},
+					meta: {
+						capName: entry.capName,
+						method,
+						error: msg
+					}
+				});
+				return null;
+			}
+		}));
+		const base = kind === "settings" ? await this.buildBaseDeviceSection(deviceId) : null;
+		const systemResults = await this.collectSystemDeviceContributions(deviceId, kind, seenCaps);
+		const parts = [
+			...base ? [tagContribution(base, "device-manager", "device-manager", kind)] : [],
+			...results.filter((r) => r !== null),
+			...systemResults
+		];
+		if (parts.length === 0) return null;
+		return mergeAggregates(parts);
+	}
+	/**
+	* System-scoped per-device contributions — the deliberate exception to
+	* binding-driven aggregation (D12).
+	*
+	* A `scope: 'system'` cap with `exposesDeviceSettings: true` holds per-device
+	* state but is NOT bound per-device: it is a system addon, not a BaseDevice,
+	* so it never calls `registerNativeCap` and never appears in
+	* `getBindings(deviceId)`. The binding-driven loop therefore skips it and its
+	* per-device panel never renders. Two such caps ship today:
+	*   - `stream-broker` (singleton) — the RTSP-restream / pre-buffer settings
+	*     tab, scoped to the cameras whose streams it serves.
+	*   - `device-export` (collection) — the "Export" panel; a device can be
+	*     exposed to MULTIPLE exporters at once (Alexa + HomeKit + HA-MQTT).
+	*
+	* D12 bans fanning a per-device call out to every same-named provider of a
+	* `scope: 'device'` cap, because vendor providers SHARE cap names
+	* (`stream-params`/`ptz` from reolink AND hikvision). System caps are NOT
+	* vendor-shared — a system cap name maps to one active provider (singleton)
+	* or one declared collection — so consulting the cap's own provider(s)
+	* directly is safe. Each provider gates internally by deviceId and returns
+	* null for devices it does not own.
+	*
+	* `seenCaps` skips any system cap that already contributed via a binding so
+	* its section is never duplicated.
+	*/
+	async collectSystemDeviceContributions(deviceId, kind, seenCaps) {
+		const registry = this.capabilityRegistry;
+		if (!registry) return [];
+		const method = kind === "settings" ? "getDeviceSettingsContribution" : "getDeviceLiveContribution";
+		const tasks = [];
+		for (const info of registry.listCapabilities()) {
+			const def = registry.getDefinition(info.name);
+			if (!def || def.scope !== "system" || !def.exposesDeviceSettings) continue;
+			if (seenCaps.has(info.name)) continue;
+			const addonIds = def.mode === "collection" ? info.providers : info.activeProvider ? [info.activeProvider] : [];
+			for (const addonId of addonIds) tasks.push((async () => {
+				const provider = registry.getProviderByAddon(info.name, addonId);
+				if (!provider) return null;
+				try {
+					const contribution = await provider[method]({ deviceId });
+					if (!contribution) return null;
+					return tagContribution(toWireShape(contribution), info.name, addonId, kind);
+				} catch (err) {
+					this.ctx.logger.warn("system device-settings contribution skipped", {
+						tags: {
+							deviceId,
+							addonId
+						},
+						meta: {
+							capName: info.name,
+							method,
+							error: err instanceof Error ? err.message : String(err)
+						}
+					});
+					return null;
+				}
+			})());
+		}
+		return (await Promise.all(tasks)).filter((r) => r !== null);
+	}
+	/**
+	* D14: framework-derived device-config contribution.
+	*
+	* `kind === 'live'` — device-config caps contribute nothing to the live
+	* aggregate (they hold editable config, not live observables).
+	*
+	* `ui.kind === 'widget'` — emits a single structural `type:'widget'`
+	* section; the widget self-persists via the cap's own mutations.
+	*
+	* `ui.kind === 'derived-form'` — calls `getOptions`/`getStatus` on the
+	* bound provider, runs the registered pure builder, and returns the
+	* derived form sections. Returns null when the camera exposes nothing
+	* configurable or the provider is not yet registered.
+	*/
+	async deriveDeviceConfigContribution(registry, def, entry, deviceId, kind) {
+		if (kind === "live") return null;
+		const ui = def.deviceConfig.ui;
+		if (ui.kind === "widget") return tagContribution({ sections: [{
+			id: `${entry.capName}-widget`,
+			title: ui.label,
+			tab: ui.tab,
+			order: ui.order ?? 0,
+			...ui.topTab ? { location: "top-tab" } : {},
+			fields: [{
+				type: "widget",
+				key: `${entry.capName}Widget`,
+				label: ui.label,
+				widgetId: ui.widgetId
+			}]
+		}] }, entry.capName, entry.providerAddonId, kind);
+		const provider = registry.getProviderForDevice(entry.capName, deviceId);
+		if (!provider || typeof provider.getOptions !== "function") return null;
+		try {
+			const options = await provider.getOptions({ deviceId });
+			const status = typeof provider.getStatus === "function" ? await provider.getStatus({ deviceId }) : null;
+			const derived = deriveFormContribution(ui.builderId, options, status ?? null);
+			if (!derived) return null;
+			return tagContribution({
+				...derived.tabs ? { tabs: derived.tabs.map((t) => ({ ...t })) } : {},
+				sections: derived.sections.map((s) => ({
+					id: s.id,
+					title: s.title,
+					...s.tab !== void 0 ? { tab: s.tab } : {},
+					...s.order !== void 0 ? { order: s.order } : {},
+					...s.description !== void 0 ? { description: s.description } : {},
+					...s.columns !== void 0 ? { columns: s.columns } : {},
+					fields: [...s.fields]
+				}))
+			}, entry.capName, entry.providerAddonId, kind);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			this.ctx.logger.warn("device-config derivation failed", {
+				tags: {
+					deviceId,
+					addonId: entry.providerAddonId
+				},
+				meta: {
+					capName: entry.capName,
+					error: msg
+				}
+			});
+			return null;
+		}
+	}
+	/**
+	* 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 driverResult = await this.resolveDriverConfigSchema(deviceId, hubLocal);
+		if (driverResult.status === "ok") for (const section of driverResult.schema.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 } : {}
+		});
+		else if (driverResult.status === "unavailable") sections.push({
+			id: "driver-settings-unavailable",
+			title: "Driver Settings",
+			tab: "general",
+			order: 1,
+			fields: [{
+				type: "info",
+				key: "driver-settings-unavailable-notice",
+				label: "Temporarily unavailable",
+				content: "Driver settings are temporarily unavailable — the addon may be restarting. Refresh the page in a moment.",
+				variant: "warning"
+			}]
+		});
+		return {
+			sections,
+			...driverResult.status === "ok" && driverResult.schema.tabs ? { tabs: [...driverResult.schema.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") ?? this.resolveRemoteNativeCapFromRegistry("device-ops", deviceId);
+		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.getProviderForDevice(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.
+	*
+	* Returns a discriminated result so callers can distinguish three states:
+	*   'ok'          – schema obtained successfully
+	*   'none'        – driver genuinely has no settings schema
+	*   'unavailable' – worker was unreachable after retries (transient)
+	*/
+	async resolveDriverConfigSchema(deviceId, hubLocal) {
+		if (hubLocal) {
+			const schema = hubLocal.device.getSettingsUISchema();
+			return schema.sections.length === 0 ? { status: "none" } : {
+				status: "ok",
+				schema: toWireShape(schema)
+			};
+		}
+		const ops = this.capabilityRegistry?.getNativeProvider("device-ops", deviceId);
+		if (!ops) return { status: "none" };
+		const MAX_RETRIES = 2;
+		const RETRY_DELAY_MS = 750;
+		let lastErr;
+		for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+			if (attempt > 0) await sleep(RETRY_DELAY_MS);
+			try {
+				const schema = await ops.getSettingsSchema({ deviceId });
+				if (!schema) return { status: "none" };
+				const wire = schema;
+				return wire.sections.length === 0 ? { status: "none" } : {
+					status: "ok",
+					schema: toWireShape(wire)
+				};
+			} catch (err) {
+				lastErr = err;
+				if (!isTransientMoleculerError(err)) break;
+				if (attempt < MAX_RETRIES) this.ctx.logger.debug("cross-process getSettingsSchema transient failure, retrying", {
+					tags: { deviceId },
+					meta: {
+						attempt: attempt + 1,
+						maxRetries: MAX_RETRIES,
+						error: errMsg(err)
+					}
+				});
+			}
+		}
+		const msg = errMsg(lastErr);
+		this.ctx.logger.warn("cross-process getSettingsSchema failed after retries — driver settings temporarily unavailable", {
+			tags: { deviceId },
+			meta: { error: msg }
+		});
+		return { status: "unavailable" };
+	}
+	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");
+		const def = registry.getDefinition(input.writerCapName);
+		if (isDeviceConfigCap(def)) {
+			if (def.deviceConfig.ui.kind === "widget") return { success: true };
+			const dcProvider = registry.getProviderForDevice(input.writerCapName, input.deviceId);
+			if (!dcProvider) throw new Error(`[device-manager] no provider for device-config cap "${input.writerCapName}" on device ${input.deviceId}`);
+			await applyDerivedFormPatch(def.deviceConfig.ui.builderId, { [input.key]: input.value }, (profile, patch) => dcProvider.setProfile({
+				deviceId: input.deviceId,
+				profile,
+				patch
+			}));
+			return { success: true };
+		}
+		if (!def?.exposesDeviceSettings) throw new Error(`[device-manager] cap "${input.writerCapName}" does not expose device settings`);
+		await this.resolveContributionProvider(registry, def, input.writerCapName, input.writerAddonId, input.deviceId).applyDeviceSettingsPatch({
+			deviceId: input.deviceId,
+			patch: { [input.key]: input.value }
+		});
+		return { success: true };
+	}
+	/**
+	* Dispatch a device custom action. Hub-local devices run it directly;
+	* forked/remote devices route through the `device-ops` native cap
+	* (`runAction`) — the same hub-local-then-device-ops fan-out that
+	* `updateDeviceField` uses for `applySettingsPatch`.
+	*/
+	async dispatchDeviceAction(deviceId, action, input) {
+		const hubRegistry = this.ctx.kernel?.deviceRegistry;
+		const found = hubRegistry ? resolveDeviceById(hubRegistry, deviceId) : null;
+		if (found) return found.device.runDeviceAction(action, input);
+		const ops = this.capabilityRegistry?.getNativeProvider("device-ops", deviceId);
+		if (!ops) throw new Error(`[device-manager] device "${deviceId}" not found for runDeviceAction (no hub-local entry, no device-ops native provider)`);
+		return ops.runAction({
+			deviceId,
+			action,
+			input
+		});
+	}
+	/**
+	* Resolve the `DeviceSettingsContribution` provider that owns a tagged
+	* field. The `writerAddonId` on a tagged field equals `entry.providerAddonId`
+	* from the binding that produced it — for `kind:'wrapped'` entries, that is
+	* the wrapper addon id (e.g. 'snapshot-addon'); for native-only entries,
+	* the system addon id.
+	*
+	* Resolution order (Bug-3 fix):
+	*  1. `getProviderByAddon(capName, writerAddonId)` — resolves the
+	*     system-registered provider by the addon id from the tagged field.
+	*     For wrapper bindings (snapshot, motion-detection, etc.) this directly
+	*     returns the wrapper provider, bypassing the native-first resolution
+	*     order of `getProviderForDevice` that caused "method not found".
+	*  2. `getSingleton(capName)` — fallback for stale/mismatched writerAddonIds.
+	*     The active singleton handles the contribution even if the addonId
+	*     stored in the field is out of date (e.g. after an addon rename).
+	*
+	* `getProviderForDevice` is intentionally NOT used here: it returns the
+	* per-device native first when present (e.g. Reolink/ONVIF), and the native
+	* does NOT implement contribution methods — the root cause of Bug-3.
+	*/
+	resolveContributionProvider(registry, _def, writerCapName, writerAddonId, deviceId) {
+		const byAddon = registry.getProviderByAddon(writerCapName, writerAddonId);
+		if (byAddon) return byAddon;
+		const singleton = registry.getSingleton(writerCapName);
+		if (singleton) return singleton;
+		throw new Error(`[device-manager] no provider for cap "${writerCapName}" (addon "${writerAddonId}") on device ${deviceId}`);
+	}
+	/**
+	* 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");
+		const def = registry.getDefinition(group.writerCapName);
+		if (isDeviceConfigCap(def)) {
+			if (def.deviceConfig.ui.kind === "widget") return;
+			const dcProvider = registry.getProviderForDevice(group.writerCapName, deviceId);
+			if (!dcProvider) throw new Error(`[device-manager] no provider for device-config cap "${group.writerCapName}" on device ${deviceId}`);
+			await applyDerivedFormPatch(def.deviceConfig.ui.builderId, group.patch, (profile, patch) => dcProvider.setProfile({
+				deviceId,
+				profile,
+				patch
+			}));
+			return;
+		}
+		if (!def?.exposesDeviceSettings) throw new Error(`[device-manager] cap "${group.writerCapName}" does not expose device settings`);
+		await this.resolveContributionProvider(registry, def, group.writerCapName, group.writerAddonId, deviceId).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;
+		};
+		/** Resolve a link's `sourceKey` to a live device id: the sibling accessory
+		*  whose stableId is `${parentStableId}-${sourceKey}`. Null when absent.
+		*  Pure over a pre-read meta map so a multi-link resolve reads the store once. */
+		const resolveSourceDeviceId = (parentStableId, sourceKey, meta) => {
+			const wanted = `${parentStableId}-${sourceKey}`;
+			for (const [key, m] of Object.entries(meta)) {
+				const sep = key.indexOf(":");
+				if (sep < 0) continue;
+				if (key.slice(sep + 1) === wanted) return m.id;
+			}
+			return null;
+		};
+		/** Rebuild the `linkTargets` / `linkDependents` reverse-index maps from the
+		*  current persisted meta. Called at boot (once the `devicesWithLinks` seed
+		*  has run) and whenever the link topology can change: `setDeviceLinks`,
+		*  `registerDevice` (a new sibling source may resolve previously-dangling
+		*  links), and `removeDevice` (its entries must be evicted). */
+		const rebuildLinkDependents = async () => {
+			if (this.devicesWithLinks.size === 0) {
+				this.linkTargets = /* @__PURE__ */ new Map();
+				this.linkDependents = /* @__PURE__ */ new Map();
+				this.expectedSourceStableIds = /* @__PURE__ */ new Set();
+				return;
+			}
+			const allMeta = await readMeta();
+			const stableIdById = /* @__PURE__ */ new Map();
+			const idByStableId = /* @__PURE__ */ new Map();
+			for (const [key, m] of Object.entries(allMeta)) {
+				const sep = key.indexOf(":");
+				if (sep < 0) continue;
+				const sid = key.slice(sep + 1);
+				stableIdById.set(m.id, sid);
+				idByStableId.set(sid, m.id);
+			}
+			const entries = [];
+			const expectedSources = /* @__PURE__ */ new Set();
+			for (const targetId of this.devicesWithLinks) {
+				const targetMeta = Object.values(allMeta).find((m) => m.id === targetId);
+				if (!targetMeta) continue;
+				const container = targetMeta.parentDeviceId !== null ? stableIdById.get(targetMeta.parentDeviceId) ?? stableIdById.get(targetId) : stableIdById.get(targetId);
+				if (container === void 0) continue;
+				for (const link of targetMeta.deviceLinks ?? []) {
+					expectedSources.add(`${container}-${link.source.sourceKey}`);
+					const srcId = idByStableId.get(`${container}-${link.source.sourceKey}`);
+					if (srcId === void 0) continue;
+					entries.push({
+						targetDeviceId: targetId,
+						link,
+						sourceDeviceId: srcId
+					});
+				}
+			}
+			const { targets, dependents } = buildLinkIndexes(entries);
+			this.linkTargets = targets;
+			this.linkDependents = dependents;
+			this.expectedSourceStableIds = expectedSources;
+		};
+		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 (Array.isArray(m.deviceLinks) && m.deviceLinks.length > 0) this.devicesWithLinks.add(m.id);
+			}
+		}
+		await rebuildLinkDependents();
+		const allocateNextDeviceId = async () => {
+			const current = (await readStore()).nextDeviceId ?? 1;
+			await settings.writeAddonStore({ nextDeviceId: current + 1 });
+			return current;
+		};
+		const stampIntegrationId = async (deviceId, integrationId) => {
+			await withMetaWriteLock(async () => {
+				const persisted = await resolvePersistedById(deviceId);
+				if (!persisted) throw new Error(`[device-manager] stampIntegrationId: unknown device id=${deviceId}`);
+				const { addonId: aid, stableId, meta: m } = persisted;
+				const key = deviceKey(aid, stableId);
+				const allMeta = await readMeta();
+				await settings.writeAddonStore({ deviceMeta: {
+					...allMeta,
+					[key]: {
+						...m,
+						integrationId
+					}
+				} });
+			});
+			this.ctx.eventBus.emit({
+				id: randomUUID(),
+				timestamp: /* @__PURE__ */ new Date(),
+				source: {
+					type: "device",
+					id: deviceId
+				},
+				category: EventCategory.DeviceMetaChanged,
+				data: {
+					deviceId,
+					field: "integrationId",
+					value: integrationId
+				}
+			});
+		};
+		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.
+			*
+			*  Resolution order:
+			*   1. Hub-local `capabilityRegistry` (in-process natives — fastest path).
+			*   2. Push-fed `remoteNativeCaps` cache (`DeviceBindingsChanged` events
+			*      from forked workers — accurate in steady state).
+			*   3. Handshake-fed `HubNodeRegistry` via `listClusterNativeCaps()`
+			*      (D3 re-handshake after device restore — covers the Moleculer
+			*      transport window where push events were lost). This is the
+			*      reliable replacement for the deleted `syncWorkerNativeCaps` pull.
+			*/
+			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 this.resolveRemoteNativeCapFromRegistry(capName, deviceId);
+			},
+			/** Read-time overlay: merge cross-device linked values onto a target cap's
+			*  status. Returns null when the device has no links for `cap` (caller uses
+			*  the base status untouched). Reads each source cap via the hub registry's
+			*  `getProviderForDevice` (routes cross-process); merge is pure. */
+			resolveLinkedStatus: async ({ deviceId, cap, baseStatus }) => {
+				if (!this.devicesWithLinks.has(deviceId)) return null;
+				const persisted = await resolvePersistedById(deviceId);
+				if (!persisted) return null;
+				const links = (persisted.meta.deviceLinks ?? []).filter((l) => l.target.cap === cap);
+				if (links.length === 0) return null;
+				const registry = this.capabilityRegistry;
+				const schema = registry?.getDefinition(cap)?.status?.schema;
+				if (!schema) return null;
+				const allMeta = await readMeta();
+				let containerStableId = persisted.stableId;
+				const parentId = persisted.meta.parentDeviceId;
+				if (parentId !== null) {
+					for (const [key, m] of Object.entries(allMeta)) if (m.id === parentId) {
+						containerStableId = key.slice(key.indexOf(":") + 1);
+						break;
+					}
+				}
+				const resolved = [];
+				for (const link of links) {
+					const srcId = resolveSourceDeviceId(containerStableId, link.source.sourceKey, allMeta);
+					if (srcId === null) continue;
+					try {
+						const srcProvider = registry?.getProviderForDevice(link.source.cap, srcId);
+						const raw = getByPath(typeof srcProvider?.getStatus === "function" ? await srcProvider.getStatus({ deviceId: srcId }) : void 0, link.source.fieldPath);
+						resolved.push({
+							link,
+							sourceValue: applyTransform(raw, link.transform)
+						});
+					} catch (err) {
+						this.ctx.logger.warn("resolveLinkedStatus: source read failed", {
+							tags: {
+								deviceId,
+								capName: cap
+							},
+							meta: {
+								sourceKey: link.source.sourceKey,
+								error: err instanceof Error ? err.message : String(err)
+							}
+						});
+					}
+				}
+				if (resolved.length === 0) return null;
+				return mergeLinkedStatus(isRecord(baseStatus) ? baseStatus : {}, resolved, schema);
+			},
+			/** 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, exportFingerprint, fingerprintChanged } = 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;
+					const fingerprint = canonicalDeviceFingerprint({
+						deviceId: id,
+						deviceType: type,
+						features: featuresArr
+					});
+					await settings.writeAddonStore({ deviceMeta: {
+						...meta,
+						[key]: {
+							type,
+							name: existingMeta && existingMeta.name !== stableId ? existingMeta.name : name,
+							location: existingMeta?.location ?? null,
+							disabled: existingMeta?.disabled ?? false,
+							...existingMeta?.integrationId !== void 0 ? { integrationId: existingMeta.integrationId } : {},
+							...existingMeta?.linkDeviceId !== void 0 ? { linkDeviceId: existingMeta.linkDeviceId } : {},
+							...existingMeta?.primaryChildEntityId !== void 0 ? { primaryChildEntityId: existingMeta.primaryChildEntityId } : {},
+							...existingMeta?.childLayout !== void 0 ? { childLayout: existingMeta.childLayout } : {},
+							...existingMeta?.deviceLinks !== void 0 ? { deviceLinks: existingMeta.deviceLinks } : {},
+							...existingMeta?.role !== void 0 ? { role: existingMeta.role } : {},
+							parentDeviceId,
+							id,
+							features: featuresArr,
+							exportFingerprint: fingerprint
+						}
+					} });
+					return {
+						isFirstRegistration: isFirst,
+						exportFingerprint: fingerprint,
+						fingerprintChanged: existingMeta?.exportFingerprint !== fingerprint
+					};
+				});
+				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
+					}
+				});
+				if (isFirstRegistration || fingerprintChanged) this.ctx.eventBus.emit({
+					id: randomUUID(),
+					timestamp: /* @__PURE__ */ new Date(),
+					source: {
+						type: "device",
+						id
+					},
+					category: EventCategory.DeviceProvisioned,
+					data: {
+						deviceId: id,
+						fingerprint: exportFingerprint,
+						generation: Date.now()
+					}
+				});
+				if (this.devicesWithLinks.size > 0 && this.expectedSourceStableIds.has(stableId)) await rebuildLinkDependents();
+			},
+			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);
+				await settings.clearDeviceRuntimeState(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.devicesWithLinks.delete(deviceId);
+				for (const key of this.lastEmittedOverlay.keys()) if (key.startsWith(`${deviceId}:`)) this.lastEmittedOverlay.delete(key);
+				await rebuildLinkDependents();
+				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,
+					...m.integrationId !== void 0 ? { integrationId: m.integrationId } : {},
+					...m.linkDeviceId !== void 0 ? { linkDeviceId: m.linkDeviceId } : {},
+					...m.role !== void 0 ? { role: m.role } : {}
+				};
+			},
+			/**
+			* 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
+					}
+				});
+			},
+			/**
+			* Update the device type. Writes the meta row, emits a
+			* `DeviceMetaChanged` event. Used by the kernel to apply
+			* `initialMeta.type` before device construction so the device
+			* constructs with its real type instead of the `allocateDeviceId`
+			* placeholder `'generic'`.
+			*/
+			setType: async (input) => {
+				const { deviceId, type } = input;
+				await withMetaWriteLock(async () => {
+					const persisted = await resolvePersistedById(deviceId);
+					if (!persisted) throw new Error(`[device-manager] setType: 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,
+							type
+						}
+					} });
+				});
+				this.ctx.eventBus.emit({
+					id: randomUUID(),
+					timestamp: /* @__PURE__ */ new Date(),
+					source: {
+						type: "device",
+						id: deviceId
+					},
+					category: EventCategory.DeviceMetaChanged,
+					data: {
+						deviceId,
+						field: "type",
+						value: type
+					}
+				});
+			},
+			/**
+			* Stamp (or update) the owning integration id on the device's
+			* meta row. Called by the kernel's `create()` pre-seed path
+			* when `initialMeta.integrationId` is set (analogous to
+			* `setName` / `setType`). Idempotent.
+			*/
+			setIntegrationId: async (input) => {
+				await stampIntegrationId(input.deviceId, input.integrationId);
+			},
+			/**
+			* Stamp (or update) the linked device id on the device's meta
+			* row. Called by the kernel's `create()` pre-seed path when
+			* `initialMeta.linkDeviceId` is set (analogous to `setIntegrationId`).
+			* Idempotent. `null` explicitly clears a previous link.
+			*/
+			setLinkDeviceId: async (input) => {
+				const { deviceId, linkDeviceId } = input;
+				await withMetaWriteLock(async () => {
+					const persisted = await resolvePersistedById(deviceId);
+					if (!persisted) throw new Error(`[device-manager] setLinkDeviceId: unknown device id=${deviceId}`);
+					const { addonId: aid, stableId, meta: m } = persisted;
+					const key = deviceKey(aid, stableId);
+					const allMeta = await readMeta();
+					await settings.writeAddonStore({ deviceMeta: {
+						...allMeta,
+						[key]: {
+							...m,
+							linkDeviceId
+						}
+					} });
+				});
+				this.ctx.eventBus.emit({
+					id: randomUUID(),
+					timestamp: /* @__PURE__ */ new Date(),
+					source: {
+						type: "device",
+						id: deviceId
+					},
+					category: EventCategory.DeviceMetaChanged,
+					data: {
+						deviceId,
+						field: "linkDeviceId",
+						value: linkDeviceId
+					}
+				});
+			},
+			/**
+			* Set (or clear) the durable primary-child override on a CONTAINER
+			* device's meta row, keyed on the chosen child's re-sync/rename-stable
+			* `entityId`. Mirrors `setLinkDeviceId` but persists a string entityId
+			* (survives a re-sync that reallocates the child's numeric id) instead
+			* of the numeric child id. `null` clears the override → priority default.
+			*/
+			setPrimaryChildEntityId: async (input) => {
+				const { deviceId, primaryChildEntityId } = input;
+				await withMetaWriteLock(async () => {
+					const persisted = await resolvePersistedById(deviceId);
+					if (!persisted) throw new Error(`[device-manager] setPrimaryChildEntityId: unknown device id=${deviceId}`);
+					const { addonId: aid, stableId, meta: m } = persisted;
+					const key = deviceKey(aid, stableId);
+					const allMeta = await readMeta();
+					await settings.writeAddonStore({ deviceMeta: {
+						...allMeta,
+						[key]: {
+							...m,
+							primaryChildEntityId
+						}
+					} });
+				});
+				this.ctx.eventBus.emit({
+					id: randomUUID(),
+					timestamp: /* @__PURE__ */ new Date(),
+					source: {
+						type: "device",
+						id: deviceId
+					},
+					category: EventCategory.DeviceMetaChanged,
+					data: {
+						deviceId,
+						field: "primaryChildEntityId",
+						value: primaryChildEntityId
+					}
+				});
+			},
+			/**
+			* Set (or replace) the container-level `childLayout` on a device's
+			* meta row. Mirrors `setPrimaryChildEntityId` but persists the
+			* accordion-section layout array (parent-only). Persisted, projected,
+			* and preserved across re-register/restore.
+			*/
+			setChildLayout: async (input) => {
+				const { deviceId, childLayout } = input;
+				await withMetaWriteLock(async () => {
+					const persisted = await resolvePersistedById(deviceId);
+					if (!persisted) throw new Error(`[device-manager] setChildLayout: unknown device id=${deviceId}`);
+					const { addonId: aid, stableId, meta: m } = persisted;
+					const key = deviceKey(aid, stableId);
+					const allMeta = await readMeta();
+					await settings.writeAddonStore({ deviceMeta: {
+						...allMeta,
+						[key]: {
+							...m,
+							childLayout
+						}
+					} });
+				});
+				this.ctx.eventBus.emit({
+					id: randomUUID(),
+					timestamp: /* @__PURE__ */ new Date(),
+					source: {
+						type: "device",
+						id: deviceId
+					},
+					category: EventCategory.DeviceMetaChanged,
+					data: {
+						deviceId,
+						field: "childLayout",
+						value: childLayout
+					}
+				});
+			},
+			/**
+			* Set (or replace) the operator-authored cross-device field wirings on
+			* a device's meta row. Mirrors `setChildLayout` but persists the
+			* `deviceLinks` array. Persisted, projected, and preserved across
+			* re-register/restore. Also maintains the in-memory `devicesWithLinks`
+			* Set used as an O(1) gate by `resolveLinkedStatus`.
+			*/
+			setDeviceLinks: async (input) => {
+				const { deviceId, deviceLinks } = input;
+				await withMetaWriteLock(async () => {
+					const persisted = await resolvePersistedById(deviceId);
+					if (!persisted) throw new Error(`[device-manager] setDeviceLinks: unknown device id=${deviceId}`);
+					const { addonId: aid, stableId, meta: m } = persisted;
+					const key = deviceKey(aid, stableId);
+					const allMeta = await readMeta();
+					await settings.writeAddonStore({ deviceMeta: {
+						...allMeta,
+						[key]: {
+							...m,
+							deviceLinks
+						}
+					} });
+				});
+				if (deviceLinks.length > 0) this.devicesWithLinks.add(deviceId);
+				else this.devicesWithLinks.delete(deviceId);
+				await rebuildLinkDependents();
+				this.ctx.eventBus.emit({
+					id: randomUUID(),
+					timestamp: /* @__PURE__ */ new Date(),
+					source: {
+						type: "device",
+						id: deviceId
+					},
+					category: EventCategory.DeviceMetaChanged,
+					data: {
+						deviceId,
+						field: "deviceLinks",
+						value: deviceLinks
+					}
+				});
+			},
+			/**
+			* Stamp (or update) the semantic role on the device's meta row.
+			* Called by the kernel's `create()` / `spawnAccessoryChild`
+			* pre-seed when `initialMeta.role` is set (analogous to
+			* `setIntegrationId`). Idempotent. `null` clears a previous role.
+			*/
+			setRole: async (input) => {
+				const { deviceId, role } = input;
+				await withMetaWriteLock(async () => {
+					const persisted = await resolvePersistedById(deviceId);
+					if (!persisted) throw new Error(`[device-manager] setRole: unknown device id=${deviceId}`);
+					const { addonId: aid, stableId, meta: m } = persisted;
+					const key = deviceKey(aid, stableId);
+					const allMeta = await readMeta();
+					await settings.writeAddonStore({ deviceMeta: {
+						...allMeta,
+						[key]: {
+							...m,
+							role
+						}
+					} });
+				});
+				this.ctx.eventBus.emit({
+					id: randomUUID(),
+					timestamp: /* @__PURE__ */ new Date(),
+					source: {
+						type: "device",
+						id: deviceId
+					},
+					category: EventCategory.DeviceMetaChanged,
+					data: {
+						deviceId,
+						field: "role",
+						value: role
+					}
+				});
+			},
+			/**
+			* Batched meta pre-seed. Applies every provided field to the
+			* device's meta row in ONE read-modify-write under a single
+			* `withMetaWriteLock` acquisition (one `deviceMeta` blob write),
+			* then emits one `DeviceMetaChanged` event per field that was
+			* supplied — preserving the exact semantics of the individual
+			* setters (`setName` / `setLocation` / `setType` /
+			* `setIntegrationId` / `setLinkDeviceId` / `setRole`). Omitted
+			* fields are left untouched; `null` clears `location` /
+			* `linkDeviceId` / `role`. Idempotent.
+			*
+			* Collapses the per-child meta pre-seed (up to 6 individual
+			* setter round-trips, each its own lock + write) into one — the
+			* dominant cost when the kernel's `spawnAccessoryChild` reconciles
+			* a many-entity container.
+			*/
+			applyInitialMeta: async (input) => {
+				const { deviceId, name, location, type, integrationId, linkDeviceId, role } = input;
+				await withMetaWriteLock(async () => {
+					const persisted = await resolvePersistedById(deviceId);
+					if (!persisted) throw new Error(`[device-manager] applyInitialMeta: unknown device id=${deviceId}`);
+					const { addonId: aid, stableId, meta: m } = persisted;
+					const key = deviceKey(aid, stableId);
+					const allMeta = await readMeta();
+					const merged = {
+						...m,
+						...name !== void 0 ? { name } : {},
+						...location !== void 0 ? { location } : {},
+						...type !== void 0 ? { type } : {},
+						...integrationId !== void 0 ? { integrationId } : {},
+						...linkDeviceId !== void 0 ? { linkDeviceId } : {},
+						...role !== void 0 ? { role } : {}
+					};
+					await settings.writeAddonStore({ deviceMeta: {
+						...allMeta,
+						[key]: merged
+					} });
+				});
+				const emitMetaChanged = (field, value) => {
+					this.ctx.eventBus.emit({
+						id: randomUUID(),
+						timestamp: /* @__PURE__ */ new Date(),
+						source: {
+							type: "device",
+							id: deviceId
+						},
+						category: EventCategory.DeviceMetaChanged,
+						data: {
+							deviceId,
+							field,
+							value
+						}
+					});
+				};
+				if (name !== void 0) emitMetaChanged("name", name);
+				if (location !== void 0) emitMetaChanged("location", location);
+				if (type !== void 0) emitMetaChanged("type", type);
+				if (integrationId !== void 0) emitMetaChanged("integrationId", integrationId);
+				if (linkDeviceId !== void 0) emitMetaChanged("linkDeviceId", linkDeviceId);
+				if (role !== void 0) emitMetaChanged("role", role);
+			},
+			/**
+			* 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, this.withResetSessionProbe(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()].toSorted((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: toDeviceRole(m?.role),
+						online: this.resolveDeviceOnline(m.id, registry !== null),
+						probed: this.resolveDeviceProbed(m.id),
+						features: persistedFeatures(m?.features),
+						isCamera: persistedType === DeviceType.Camera,
+						config: persistedConfig ?? {},
+						metadata,
+						...m?.integrationId !== void 0 ? { integrationId: m.integrationId } : {},
+						...m?.linkDeviceId !== void 0 ? { linkDeviceId: m.linkDeviceId } : {},
+						...m?.primaryChildEntityId !== void 0 ? { primaryChildEntityId: m.primaryChildEntityId } : {},
+						...m?.childLayout !== void 0 ? { childLayout: m.childLayout } : {},
+						...m?.deviceLinks !== void 0 ? { deviceLinks: m.deviceLinks } : {},
+						...(() => {
+							const si = buildSourceInfoFromConfig(persistedConfig ?? {}, stableId, aid);
+							return si !== void 0 ? { sourceInfo: si } : {};
+						})()
+					});
+				}
+				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;
+				const sourceInfoGetDevice = buildSourceInfoFromConfig(persistedConfig ?? {}, stableId, aid);
+				return {
+					id: deviceId,
+					stableId,
+					addonId: aid,
+					type: m.type,
+					name: m.name,
+					location: m.location ?? null,
+					disabled: m.disabled ?? false,
+					parentDeviceId: m.parentDeviceId,
+					role: toDeviceRole(m.role),
+					online: this.resolveDeviceOnline(deviceId, true),
+					probed: this.resolveDeviceProbed(deviceId),
+					features: persistedFeatures(m.features),
+					isCamera: false,
+					config: persistedConfig ?? {},
+					metadata,
+					...m.integrationId !== void 0 ? { integrationId: m.integrationId } : {},
+					...m.linkDeviceId !== void 0 ? { linkDeviceId: m.linkDeviceId } : {},
+					...m.primaryChildEntityId !== void 0 ? { primaryChildEntityId: m.primaryChildEntityId } : {},
+					...m.childLayout !== void 0 ? { childLayout: m.childLayout } : {},
+					...m.deviceLinks !== void 0 ? { deviceLinks: m.deviceLinks } : {},
+					...sourceInfoGetDevice !== void 0 ? { sourceInfo: sourceInfoGetDevice } : {}
+				};
+			},
+			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;
+					const sourceInfoChild = buildSourceInfoFromConfig(persistedConfig ?? {}, childStableId, ownerAddonId);
+					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: toDeviceRole(m.role),
+						online: this.resolveDeviceOnline(m.id, registry !== null),
+						probed: this.resolveDeviceProbed(m.id),
+						features: persistedFeatures(m.features),
+						isCamera: false,
+						config: persistedConfig ?? {},
+						metadata,
+						...m.integrationId !== void 0 ? { integrationId: m.integrationId } : {},
+						...m.linkDeviceId !== void 0 ? { linkDeviceId: m.linkDeviceId } : {},
+						...m.primaryChildEntityId !== void 0 ? { primaryChildEntityId: m.primaryChildEntityId } : {},
+						...m.childLayout !== void 0 ? { childLayout: m.childLayout } : {},
+						...m.deviceLinks !== void 0 ? { deviceLinks: m.deviceLinks } : {},
+						...sourceInfoChild !== void 0 ? { sourceInfo: sourceInfoChild } : {}
+					});
+				}
+				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;
+				const directChildIds = async (parentId) => {
+					const ids = /* @__PURE__ */ new Set();
+					if (registry) for (const c of registry.getChildren(parentId)) ids.add(c.id);
+					const meta = await readMeta();
+					for (const m of Object.values(meta)) if (m.parentDeviceId === parentId) ids.add(m.id);
+					ids.delete(parentId);
+					return [...ids];
+				};
+				const removeOne = async (id) => {
+					if (registry) {
+						const live = resolveDeviceById(registry, id);
+						if (live) {
+							const deviceName = live.device.name;
+							await live.device.removeDevice();
+							registry.remove(id);
+							await provider.removeDevice({ deviceId: id });
+							this.ctx.logger.info("removed hub-local device", { tags: {
+								deviceId: id,
+								deviceName
+							} });
+							return;
+						}
+					}
+					const persisted = await resolvePersistedById(id);
+					if (!persisted) return;
+					const { meta: persistedMeta } = persisted;
+					try {
+						await requireDeviceOps(id).removeDevice({ deviceId: id });
+					} catch (err) {
+						this.ctx.logger.warn("remove via device-ops failed — clearing persistence anyway", {
+							tags: {
+								deviceId: id,
+								deviceName: persistedMeta.name
+							},
+							meta: { error: errMsg(err) }
+						});
+					}
+					await provider.removeDevice({ deviceId: id });
+				};
+				const removeCascade = async (id) => {
+					for (const childId of await directChildIds(id)) await removeCascade(childId);
+					await removeOne(id);
+				};
+				await removeCascade(deviceId);
+				return { success: true };
+			},
+			/**
+			* Cascade-delete every top-level device whose `integrationId`
+			* matches. Enumerates a SNAPSHOT of the meta map so concurrent
+			* removals don't clobber each other. Only top-level parents are
+			* enumerated — children cascade via the per-parent `removeCascade`
+			* inside the delegated `remove` call. Idempotent: devices with no
+			* `integrationId` never match.
+			*/
+			removeByIntegration: async (input) => {
+				const { integrationId } = input;
+				const meta = await readMeta();
+				const parentKeys = Object.keys(meta).filter((key) => {
+					const m = meta[key];
+					return m !== void 0 && m.integrationId === integrationId && m.parentDeviceId === null;
+				});
+				let removed = 0;
+				for (const _key of parentKeys) {
+					const m = meta[_key];
+					if (!m) continue;
+					await provider.remove({ deviceId: m.id });
+					removed++;
+				}
+				return { removed };
+			},
+			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`);
+				const summary = await dp.adoptDiscoveredDevice({ candidate: input.candidate });
+				if (input.integrationId !== void 0) try {
+					await stampIntegrationId(summary.id, input.integrationId);
+				} catch (err) {
+					this.ctx.logger.warn("adoptDevice: integrationId stamp failed (device adopted)", {
+						tags: {
+							deviceId: summary.id,
+							integrationId: input.integrationId
+						},
+						meta: { error: errMsg(err) }
+					});
+				}
+				return summary;
+			},
+			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`);
+				const summary = await dp.createDevice({
+					type: input.type,
+					config: input.config
+				});
+				if (input.integrationId !== void 0) try {
+					await stampIntegrationId(summary.id, input.integrationId);
+				} catch (err) {
+					this.ctx.logger.warn("createDevice: integrationId stamp failed (device created)", {
+						tags: {
+							deviceId: summary.id,
+							integrationId: input.integrationId
+						},
+						meta: { error: errMsg(err) }
+					});
+				}
+				return summary;
+			},
+			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 } : {}
+				});
+			},
+			adoptionListCandidates: async ({ addonId, ...rest }) => {
+				return (await this.requireDeviceAdoptionProvider(addonId)).listCandidates(rest);
+			},
+			adoptionRefresh: async ({ addonId, integrationId }) => {
+				return (await this.requireDeviceAdoptionProvider(addonId)).refresh({ integrationId });
+			},
+			adoptionAdopt: async ({ addonId, ...rest }) => {
+				return (await this.requireDeviceAdoptionProvider(addonId)).adopt(rest);
+			},
+			adoptionRelease: async ({ addonId, ...rest }) => {
+				return (await this.requireDeviceAdoptionProvider(addonId)).release(rest);
+			},
+			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
+				};
+			},
+			runDeviceAction: async (input) => {
+				return this.dispatchDeviceAction(input.deviceId, input.action, input.input);
+			},
+			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),
+			getWireableFields: async ({ deviceId }) => {
+				const reg = this.capabilityRegistry;
+				if (!reg) return { caps: [] };
+				const { entries } = await this.getBindings({ deviceId });
+				const seen = /* @__PURE__ */ new Set();
+				const caps = [];
+				for (const entry of entries) {
+					if (seen.has(entry.capName)) continue;
+					seen.add(entry.capName);
+					const def = reg.getDefinition(entry.capName);
+					if (!def || def.kind === "wrapper") continue;
+					const schema = def.status?.schema;
+					if (!schema) continue;
+					const fields = enumerateSchemaFields(schema).map((f) => f.enumValues !== void 0 ? {
+						path: f.path,
+						kind: f.kind,
+						enumValues: [...f.enumValues]
+					} : {
+						path: f.path,
+						kind: f.kind
+					});
+					if (fields.length > 0) caps.push({
+						cap: entry.capName,
+						fields
+					});
+				}
+				return { caps };
+			}
+		};
+		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.snapshotForDeviceOverlayed(input.deviceId);
+				},
+				getCapSlice: async (input) => {
+					return this.overlayedSlice(input.deviceId, input.capName);
+				},
+				getAllSnapshots: async () => {
+					const out = {};
+					for (const [deviceId, perCap] of this.stateMirror) {
+						const dev = {};
+						for (const [capName, slice] of perCap) dev[capName] = this.overlayedSlice(deviceId, 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.emitOverlayed(deviceId, capName);
+		const deps = this.linkDependents.get(`${deviceId}:${capName}`);
+		if (deps) for (const d of deps) this.emitOverlayed(d.targetDeviceId, d.targetCap);
+	}
+	/**
+	* 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.
+	*
+	* Callers that must not carry a stale per-session probe across a
+	* restart pass the blob through `withResetSessionProbe` first (see
+	* `loadRuntimeState`).
+	*/
+	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 });
+		}
+	}
+	/**
+	* The hub mirror's `feature-probe.lastProbedAt` is a PER-SESSION liveness
+	* signal — it means "this worker process completed a probe THIS session".
+	* Persisted runtime state carries the PRE-RESTART timestamp, which is stale
+	* after a hub or worker restart: the device has not re-probed yet. Seeding it
+	* verbatim makes `resolveDeviceProbed` report `probed:true` during the
+	* restart→reprobe window, which defeats the export carry-forward gate
+	* (`resolveExportFingerprint`, gated on `device.probed`) and posts a spurious
+	* partial `AddOrUpdateReport` to Alexa/HAP before the real probe lands.
+	*
+	* Reset `lastProbedAt` to 0 for the MIRROR seed only — `probed:false` carries
+	* the last-advertised fingerprint forward until the worker republishes a
+	* fresh probe (its post-probe `setCapSlice` raises `lastProbedAt` again, which
+	* also fires `DeviceReady`). The worker's returned `initialRuntimeState` blob
+	* is untouched, and every non-probe slice (e.g. `device-status`/online) is
+	* preserved.
+	*/
+	withResetSessionProbe(blob) {
+		const probe = blob["feature-probe"];
+		if (!probe || typeof probe !== "object" || Array.isArray(probe)) return blob;
+		return {
+			...blob,
+			"feature-probe": {
+				...probe,
+				lastProbedAt: 0
+			}
+		};
+	}
+	/**
+	* Resolve a device's REAL `online` flag for the persisted/forked-worker
+	* list branch. Forked workers own the live `IDevice` in their own process,
+	* so the hub registry can't read `device.online` directly. The owning
+	* driver instead publishes its liveness through the auto-registered
+	* `device-status` runtime-state slice (`markOnline` → `setCapState`), which
+	* the canonical `deviceState.setCapSlice` write entrypoint mirrors into the
+	* hub-side `stateMirror`. We read that mirrored slice here so the list
+	* payload reflects the device's actual reachability instead of a constant.
+	*
+	* Fallback (`fallbackOnline`) preserves the legacy behaviour when no slice
+	* has been published yet: a persisted device with a live registry is
+	* assumed online (it was successfully registered by its owning process),
+	* and the null-registry "offline view" keeps reporting offline. We never
+	* regress a device to offline merely because its mirror is empty.
+	*/
+	resolveDeviceOnline(deviceId, fallbackOnline) {
+		const raw = this.stateMirror.get(deviceId)?.get(deviceStatusCapability.name);
+		if (!raw) return fallbackOnline;
+		const parsed = DeviceStatusSchema.safeParse(raw);
+		if (!parsed.success) return fallbackOnline;
+		return parsed.data.online;
+	}
+	/**
+	* Derive the `probed` flag for an offline-view (forked-worker, not
+	* live in the hub registry) device projection. Reads the mirrored
+	* `feature-probe` slice the owning worker publishes. Mirrors the
+	* `toDeviceInfo` rule: no mirrored slice → ready (`true`, no probe seen);
+	* slice present → ready iff `lastProbedAt` has advanced past 0. The
+	* mirror is populated when the worker's first `setCapSlice` RPC arrives
+	* (BaseDevice seeds `feature-probe` `lastProbedAt:0` at construction, but
+	* cross-process delivery is async); until then the no-entry path returns
+	* `true` — a brief transient window, same as `resolveDeviceOnline`.
+	*/
+	resolveDeviceProbed(deviceId) {
+		const raw = this.stateMirror.get(deviceId)?.get("feature-probe");
+		if (!raw) return true;
+		return (typeof raw.lastProbedAt === "number" ? raw.lastProbedAt : 0) > 0;
+	}
+	snapshotForDevice(deviceId) {
+		const perCap = this.stateMirror.get(deviceId);
+		if (!perCap) return {};
+		const out = {};
+		for (const [k, v] of perCap) out[k] = { ...v };
+		return out;
+	}
+	/**
+	* Read-time overlay of a cap slice with its cross-device linked values.
+	* Returns a cloned raw mirror slice when the (device, cap) pair has no
+	* links. Sources are read from the same in-hub stateMirror — sync, no
+	* cross-process call. The disk writer must NOT use this method; it must
+	* persist raw provider truth via snapshotForDevice.
+	*/
+	overlayedSlice(deviceId, cap) {
+		const raw = this.stateMirror.get(deviceId)?.get(cap) ?? null;
+		const links = this.linkTargets.get(`${deviceId}:${cap}`);
+		if (!links || links.length === 0) return raw ? { ...raw } : null;
+		const resolved = links.map((rl) => ({
+			link: rl.link,
+			sourceValue: applyTransform(getByPath(this.stateMirror.get(rl.sourceDeviceId)?.get(rl.link.source.cap), rl.link.source.fieldPath), rl.link.transform)
+		}));
+		const schema = this.capabilityRegistry?.getDefinition(cap)?.status?.schema;
+		return mergeLinkedStatus(raw ? { ...raw } : {}, resolved, schema);
+	}
+	/**
+	* Like snapshotForDevice but applies the device-link overlay per cap.
+	* Used exclusively by the device-state READ methods (getSnapshot,
+	* getAllSnapshots) so callers see overlayed values. The debounced disk
+	* writer must continue to call snapshotForDevice (raw truth).
+	*/
+	snapshotForDeviceOverlayed(deviceId) {
+		const perCap = this.stateMirror.get(deviceId);
+		if (!perCap) return {};
+		const out = {};
+		for (const capName of perCap.keys()) {
+			const s = this.overlayedSlice(deviceId, capName);
+			if (s) out[capName] = s;
+		}
+		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
+			}
+		});
+	}
+	/** Emit DeviceStateChanged for (deviceId, cap) using the OVERLAID slice,
+	*  skipping when the overlay is unchanged since the last emit (loop/churn
+	*  guard). Used for the written pair AND its dependent targets. */
+	emitOverlayed(deviceId, cap) {
+		const slice = this.overlayedSlice(deviceId, cap);
+		if (!slice) return;
+		const key = `${deviceId}:${cap}`;
+		const prev = this.lastEmittedOverlay.get(key);
+		if (prev && shallowEqual(prev, slice)) return;
+		this.lastEmittedOverlay.set(key, slice);
+		this.emitStateChanged(deviceId, cap, 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, mergeAggregates };