@camstack/core 0.1.13 → 0.1.15

package/dist/chunk-O4V246GG.mjs

@@ -0,0 +1,2137 @@
+// src/builtins/device-manager/device-manager.addon.ts
+import { randomUUID } from "crypto";
+import {
+  EventCategory,
+  BaseAddon,
+  DeviceType,
+  DeviceFeature,
+  errMsg
+} from "@camstack/types";
+
+// src/builtins/device-manager/device-event-propagator.ts
+var MAX_CHAIN_DEPTH = 16;
+var DeviceEventPropagator = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  unsubscribe = null;
+  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 origin = ev.source;
+    const via = [origin];
+    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 = /* @__PURE__ */ 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 \u2014 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 \u2014 truncating",
+          { tags: { deviceId }, meta: { depth: chain.length, max: MAX_CHAIN_DEPTH } }
+        );
+        break;
+      }
+      current = this.opts.getParentOf(current);
+    }
+    return chain;
+  }
+};
+
+// src/builtins/device-manager/device-manager.addon.ts
+import { CAP_NAMES_WITH_STATUS } from "@camstack/types";
+import { WELL_KNOWN_TAB_MAP } from "@camstack/types";
+import { deviceManagerCapability, deviceStateCapability } from "@camstack/types";
+function shallowEqual(a, b) {
+  const ak = Object.keys(a);
+  const bk = Object.keys(b);
+  if (ak.length !== bk.length) return false;
+  for (const k of ak) {
+    if (a[k] !== b[k]) return false;
+  }
+  return true;
+}
+function deviceKey(addonId, stableId) {
+  return `${addonId}:${stableId}`;
+}
+function isCameraDevice(device) {
+  return "getStreamSources" in device && typeof device.getStreamSources === "function";
+}
+var DEVICE_FEATURE_VALUES = new Set(Object.values(DeviceFeature));
+function persistedFeatures(features) {
+  if (!features) return [];
+  const out = [];
+  for (const f of features) {
+    if (DEVICE_FEATURE_VALUES.has(f)) out.push(f);
+  }
+  return out;
+}
+function toDeviceInfo(addonId, device, metadata = null, metaRow = null) {
+  const configValues = {};
+  for (const entry of device.config.entries()) {
+    configValues[entry.key] = entry.value;
+  }
+  const name = metaRow?.name ?? device.name;
+  const location = metaRow?.location !== void 0 ? metaRow.location : device.location;
+  const disabled = metaRow?.disabled ?? device.disabled;
+  return {
+    // Progressive system-wide id — bound on the live `IDevice` at
+    // construction time (see `DeviceContext.id` / `BaseDevice.id`). The
+    // hub allocates via `allocateDeviceId` BEFORE the device is
+    // instantiated, so every live device exposes one.
+    id: device.id,
+    stableId: device.stableId,
+    addonId,
+    type: device.type,
+    name,
+    location,
+    disabled,
+    parentDeviceId: device.parentDeviceId,
+    // `role` is set by the provider on accessory children (synthesized
+    // via `getAccessoryChildren()` — Reolink siren/floodlight/PIR,
+    // Hikvision supplemental light/siren). Top-level devices and
+    // first-class hub-adopted children leave it `undefined`. Surfacing
+    // it on `DeviceInfo` lets the UI distinguish accessory rows from
+    // adopted-camera rows without re-deriving the heuristic from the
+    // provider's `deviceClasses` map.
+    role: device.role ?? null,
+    online: device.online,
+    features: [...device.features],
+    isCamera: isCameraDevice(device),
+    config: configValues,
+    metadata
+  };
+}
+function resolveDeviceById(registry, deviceId) {
+  const device = registry.getById(deviceId);
+  if (!device) return null;
+  const addonId = registry.getAddonId(deviceId);
+  if (!addonId) return null;
+  return { addonId, device };
+}
+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);
+}
+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 } : {},
+      // `location: 'top-tab'` hoists the section into a discovered top-
+      // level device tab in DeviceDetail. Forgetting to forward it here
+      // strips the marker before the client sees it, so the tab never
+      // shows up — see `DeviceDetail.tsx` aggregate-driven tab discovery.
+      ...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 = /* @__PURE__ */ new Set(["separator", "info", "button"]);
+  if (typeof f.type === "string" && structuralTypes.has(f.type)) return field;
+  const tagged = { ...f, source };
+  if (kind === "live" || f.readonlyField === true) {
+    tagged.readonlyField = true;
+  } else {
+    tagged.writerCapName = capName;
+    tagged.writerAddonId = addonId;
+  }
+  if (f.type === "group") {
+    const children = Array.isArray(f.fields) ? f.fields : [];
+    if (children.length > 0) {
+      tagged.fields = children.map((child) => tagField(child, capName, addonId, source, kind));
+    }
+  } else if (f.type === "sub-tabs") {
+    const rawTabs = Array.isArray(f.tabs) ? f.tabs : [];
+    if (rawTabs.length > 0) {
+      tagged.tabs = rawTabs.map((tab) => {
+        if (!isFieldRecord(tab)) return tab;
+        const tabChildren = Array.isArray(tab.fields) ? tab.fields : [];
+        return {
+          ...tab,
+          fields: tabChildren.map((child) => tagField(child, capName, addonId, source, kind))
+        };
+      });
+    }
+  }
+  return tagged;
+}
+function mergeAggregates(parts) {
+  const tabDecls = /* @__PURE__ */ new Map();
+  const sections = [];
+  for (const part of parts) {
+    if (part.tabs) {
+      for (const t of part.tabs) {
+        if (!tabDecls.has(t.id)) tabDecls.set(t.id, t);
+      }
+    }
+    for (const s of part.sections) {
+      sections.push(s);
+    }
+  }
+  for (const s of sections) {
+    const tabId = s.tab ?? "general";
+    if (tabDecls.has(tabId)) continue;
+    const known = WELL_KNOWN_TAB_MAP[tabId];
+    if (known) {
+      tabDecls.set(tabId, { id: known.id, label: known.label, icon: known.icon, order: known.order });
+    } else {
+      tabDecls.set(tabId, { id: tabId, label: tabId, icon: "wrench", order: 100 });
+    }
+  }
+  sections.sort((a, b) => {
+    const tabA = a.tab ?? "general";
+    const tabB = b.tab ?? "general";
+    if (tabA !== tabB) {
+      const orderA = tabDecls.get(tabA)?.order ?? 100;
+      const orderB = tabDecls.get(tabB)?.order ?? 100;
+      if (orderA !== orderB) return orderA - orderB;
+      return tabA.localeCompare(tabB);
+    }
+    return (a.order ?? 0) - (b.order ?? 0);
+  });
+  const sortedTabs = [...tabDecls.values()].sort((a, b) => (a.order ?? 100) - (b.order ?? 100));
+  const out = { sections };
+  if (sortedTabs.length > 0) out.tabs = sortedTabs;
+  return out;
+}
+var DeviceManagerAddon = class _DeviceManagerAddon extends BaseAddon {
+  constructor() {
+    super({});
+  }
+  /** Shorthand for the kernel-injected capability registry. */
+  get capabilityRegistry() {
+    return this.ctx.kernel.capabilityRegistry;
+  }
+  /**
+   * Parent-chain event propagator. Started in `onInitialize` once the
+   * hub's `deviceRegistry` is available; listens to every device-sourced
+   * event and re-emits a copy on each ancestor scope with `via[]`
+   * populated. Stopped in `onShutdown`.
+   */
+  propagator = null;
+  /**
+   * Hub-side mirror of every device's cap-keyed runtime state.
+   * Populated whenever any caller writes via `deviceState.setCapSlice`
+   * (the canonical cross-layer write entrypoint) and on first load
+   * via `loadRuntimeState`. Cross-process consumers reach the mirror
+   * through the `deviceState` cap router; per-cap event subscribers
+   * (e.g. `battery.onStatusChanged`) get the same data via
+   * cap-specific events still emitted by the owning device.
+   *
+   * Key: deviceId. Value: per-cap slice map. Empty by default —
+   * slices show up as `setCapSlice` calls trickle in.
+   */
+  stateMirror = /* @__PURE__ */ new Map();
+  /**
+   * Per-device disk-write debouncer for runtime-state. `setCapSlice`
+   * updates the in-memory mirror synchronously and emits the change
+   * event immediately, but the disk write is coalesced — frequent
+   * back-to-back writes (motion phase transitions, battery pushes,
+   * etc.) collapse to one `writeDeviceRuntimeState` per
+   * `RUNTIME_STATE_DEBOUNCE_MS` window. `flushRuntimeStateWrites`
+   * awaits any in-flight write + scheduled flush so shutdown is
+   * lossless.
+   */
+  runtimeStateDebounce = /* @__PURE__ */ new Map();
+  static RUNTIME_STATE_DEBOUNCE_MS = 1e3;
+  /**
+   * Cross-process native-provider cache: deviceId (numeric) → capName → { addonId, nodeId }.
+   * Kept in sync with `device.bindings-changed` events emitted by forked
+   * workers. Union'd into `getBindings` so hub-side consumers see every
+   * native cap regardless of which process owns the IDevice. No persistence
+   * — entries re-register when the worker restarts. Purged on
+   * `$node.disconnected` to avoid stale routing after a worker crash.
+   */
+  remoteNativeCaps = /* @__PURE__ */ new Map();
+  /** Wait for a device-provider by addonId, returning null on timeout. */
+  async waitDeviceProvider(addonId, timeoutMs = 5e3) {
+    const provider = await this.capabilityRegistry?.waitForProvider("device-provider", addonId, timeoutMs);
+    return provider ? provider : null;
+  }
+  /** Require a device-provider by addonId — throws if not found. */
+  async requireDeviceProvider(addonId) {
+    const dp = await this.waitDeviceProvider(addonId);
+    if (!dp) {
+      throw new Error(`Device provider "${addonId}" not found or not registered`);
+    }
+    return dp;
+  }
+  // ── Binding store (persisted wrapper activation) ───────────────────────────
+  //
+  // These methods are public so the device-manager capability router can
+  // expose them as cap methods. They read/write through
+  // ctx.settings.readAddonStore/writeAddonStore — the same persistence channel
+  // the rest of the addon uses.
+  async readBindingsStore() {
+    const raw = await this.ctx.settings.readAddonStore();
+    return { deviceBindings: raw.deviceBindings ?? {} };
+  }
+  async writeBindingsStore(next) {
+    await this.ctx.settings.writeAddonStore({ deviceBindings: next.deviceBindings });
+  }
+  resolveWrapperNodeId(_wrapperAddonId) {
+    return "hub";
+  }
+  /**
+   * Active discovery of native caps registered on a worker node.
+   * Called from the `$node.connected` handler to recover from lost
+   * `DeviceBindingsChanged` broadcasts after worker restart.
+   *
+   * Iterates the broker's service registry, picks
+   * `<addonId>.native-provider.<capName>` services owned by the
+   * connected node, calls each service's `$listDeviceIds` action to
+   * fetch the deviceIds the worker has registered that cap on, then
+   * writes entries into `remoteNativeCaps`.
+   *
+   * Best-effort: per-service failures are logged and swallowed so a
+   * single bad service doesn't abort the whole rebuild.
+   */
+  async discoverWorkerNativeCaps(connectedNodeId, _connectedAddonId) {
+    const cluster = this.ctx.kernel.cluster;
+    if (!cluster) return;
+    const broker = cluster.broker;
+    const services = broker.registry?.getServiceList?.({ onlyAvailable: true, withActions: false }) ?? [];
+    const NATIVE_INFIX = ".native-provider.";
+    const matched = services.filter(
+      (s) => s.nodeID === connectedNodeId && s.name.includes(NATIVE_INFIX)
+    );
+    if (matched.length === 0) return;
+    for (const svc of matched) {
+      const idx = svc.name.indexOf(NATIVE_INFIX);
+      if (idx <= 0) continue;
+      const addonId = svc.name.slice(0, idx);
+      const capName = svc.name.slice(idx + NATIVE_INFIX.length);
+      if (!addonId || !capName) continue;
+      try {
+        const action = `${svc.name}.$listDeviceIds`;
+        const deviceIds = await broker.call?.(action, {}, { nodeID: connectedNodeId });
+        if (!deviceIds || deviceIds.length === 0) continue;
+        for (const deviceId of deviceIds) {
+          if (this.capabilityRegistry?.getNativeAddonId(capName, deviceId)) continue;
+          let perDevice = this.remoteNativeCaps.get(deviceId);
+          if (!perDevice) {
+            perDevice = /* @__PURE__ */ new Map();
+            this.remoteNativeCaps.set(deviceId, perDevice);
+          }
+          perDevice.set(capName, { addonId, nodeId: connectedNodeId });
+        }
+        this.ctx.logger.debug("worker native-cap discovered", {
+          meta: { nodeId: connectedNodeId, addonId, capName, deviceIds }
+        });
+      } catch (err) {
+        this.ctx.logger.debug("worker native-cap $listDeviceIds failed", {
+          meta: { service: svc.name, nodeId: connectedNodeId, error: errMsg(err) }
+        });
+      }
+    }
+    this.ctx.logger.info("worker native-cap discovery completed", {
+      meta: { nodeId: connectedNodeId, services: matched.length }
+    });
+  }
+  async getBindings(input) {
+    const storeKey = String(input.deviceId);
+    const store = await this.readBindingsStore();
+    const perDevice = store.deviceBindings[storeKey] ?? {};
+    const entries = [];
+    const seenCaps = /* @__PURE__ */ new Set();
+    for (const [capName, { wrapperAddonId }] of Object.entries(perDevice)) {
+      const hubLocalNative = this.capabilityRegistry?.getNativeAddonId(capName, input.deviceId) ?? null;
+      const remoteNative = this.remoteNativeCaps.get(input.deviceId)?.get(capName) ?? null;
+      const nativeAddonId = hubLocalNative ?? remoteNative?.addonId ?? "";
+      const nativeNodeId = hubLocalNative ? this.ctx.kernel.localNodeId ?? "hub" : remoteNative?.nodeId ?? (this.ctx.kernel.localNodeId ?? "hub");
+      if (wrapperAddonId === null && !nativeAddonId) {
+        seenCaps.add(capName);
+        continue;
+      }
+      entries.push({
+        capName,
+        kind: wrapperAddonId ? "wrapped" : "native",
+        providerAddonId: wrapperAddonId ?? nativeAddonId,
+        providerNodeId: wrapperAddonId ? this.resolveWrapperNodeId(wrapperAddonId) : nativeNodeId,
+        nativeAddonId
+      });
+      seenCaps.add(capName);
+    }
+    const remote = this.remoteNativeCaps.get(input.deviceId);
+    if (this.capabilityRegistry) {
+      for (const capName of this.capabilityRegistry.getCapsWithDefaultWrapper()) {
+        if (seenCaps.has(capName)) continue;
+        const defaultWrapperAddonId = this.capabilityRegistry.getDefaultWrapperForCap(capName);
+        if (!defaultWrapperAddonId) continue;
+        const hubLocalNative = this.capabilityRegistry.getNativeAddonId(capName, input.deviceId) ?? null;
+        const remoteNative = remote?.get(capName) ?? null;
+        const nativeAddonId = hubLocalNative ?? remoteNative?.addonId ?? "";
+        entries.push({
+          capName,
+          kind: "wrapped",
+          providerAddonId: defaultWrapperAddonId,
+          providerNodeId: this.resolveWrapperNodeId(defaultWrapperAddonId),
+          nativeAddonId
+        });
+        seenCaps.add(capName);
+      }
+    }
+    if (this.capabilityRegistry) {
+      for (const capName of this.capabilityRegistry.getNativeCapsForDevice(input.deviceId)) {
+        if (seenCaps.has(capName)) continue;
+        const nativeAddonId = this.capabilityRegistry.getNativeAddonId(capName, input.deviceId) ?? "";
+        entries.push({
+          capName,
+          kind: "native",
+          providerAddonId: nativeAddonId,
+          providerNodeId: this.ctx.kernel.localNodeId ?? "hub",
+          nativeAddonId
+        });
+        seenCaps.add(capName);
+      }
+    }
+    if (remote) {
+      for (const [capName, info] of remote) {
+        if (seenCaps.has(capName)) continue;
+        entries.push({
+          capName,
+          kind: "native",
+          providerAddonId: info.addonId,
+          providerNodeId: info.nodeId,
+          nativeAddonId: info.addonId
+        });
+        seenCaps.add(capName);
+      }
+    }
+    return { deviceId: input.deviceId, entries };
+  }
+  /**
+   * Whole-fleet binding dump. Iterates every device known to the
+   * deviceRegistry and reuses the per-device `getBindings` resolver
+   * for each — same routing rules, single round-trip. Used by
+   * `SystemManager.init()` for warm-boot.
+   *
+   * Bindings change rarely (wrapper toggle, device add/remove) so
+   * clients invalidate via the existing
+   * `capability.binding-changed` event rather than re-fetching this
+   * payload periodically.
+   */
+  async getAllBindings() {
+    const hubRegistry = this.ctx.kernel?.deviceRegistry;
+    if (!hubRegistry) return [];
+    const out = [];
+    for (const device of hubRegistry.getAll()) {
+      out.push(await this.getBindings({ deviceId: device.id }));
+    }
+    return out;
+  }
+  /**
+   * Resolve a numeric deviceId to a stableId via persisted meta.
+   * Used only by the device-identity section of the device-details
+   * aggregator (see `buildBaseDeviceSection`) to surface the stableId as
+   * a readonly display field. All runtime/registry lookups are keyed by
+   * numeric deviceId; this helper is display-only.
+   */
+  async lookupPersistedStableId(deviceId) {
+    const store = await this.ctx.settings.readAddonStore();
+    const meta = store.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);
+      }
+    }
+    return void 0;
+  }
+  // ── Device-details aggregator ──────────────────────────────────────────────
+  //
+  // Walks the bindings for `deviceId` (native + wrapped), picks every
+  // provider whose cap declares `exposesDeviceSettings: true`, and asks
+  // each for its per-device contribution. Contributions are concatenated
+  // into a single `ConfigUISchemaWithValues`; editable fields are tagged
+  // with `writerCapName` + `writerAddonId` so `updateDeviceField` can
+  // route the mutation back to the exact provider that produced them.
+  //
+  // `kind` selects settings vs live-info. The two aggregators share the
+  // enumeration + tagging pipeline; only the method invoked on each
+  // contributing provider differs.
+  async getDeviceAggregate(deviceId, kind) {
+    const registry = this.capabilityRegistry;
+    if (!registry) {
+      this.ctx.logger.debug("capability registry unavailable \u2014 aggregate empty", { meta: { kind } });
+      return null;
+    }
+    const method = kind === "settings" ? "getDeviceSettingsContribution" : "getDeviceLiveContribution";
+    const contributors = [];
+    for (const info of registry.listCapabilities()) {
+      const def = registry.getDefinition(info.name);
+      if (!def?.exposesDeviceSettings) continue;
+      const seen = /* @__PURE__ */ new Set();
+      const sorted = [...info.providers].sort((a, b) => a.length - b.length);
+      for (const addonId of sorted) {
+        if (addonId.includes("::native-")) continue;
+        const baseId = addonId.includes("@") ? addonId.slice(0, addonId.indexOf("@")) : addonId;
+        if (seen.has(baseId)) continue;
+        seen.add(baseId);
+        contributors.push({ capName: info.name, addonId });
+      }
+    }
+    const results = await Promise.all(contributors.map(async ({ capName, addonId }) => {
+      const provider = registry.getProviderByAddon(capName, addonId);
+      if (!provider) {
+        throw new Error(
+          `[device-manager] capability "${capName}" lists provider "${addonId}" but getProviderByAddon returned null \u2014 registry inconsistency`
+        );
+      }
+      try {
+        const contribution = await provider[method]({ deviceId });
+        if (!contribution) return null;
+        return {
+          capName,
+          addonId,
+          contribution: tagContribution(toWireShape(contribution), capName, addonId, kind)
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        this.ctx.logger.warn("contribution method failed", { tags: { deviceId, addonId }, meta: { capName, method, error: msg } });
+        return null;
+      }
+    }));
+    const base = kind === "settings" ? await this.buildBaseDeviceSection(deviceId) : null;
+    const parts = [
+      ...base ? [tagContribution(base, "device-manager", "device-manager", kind)] : [],
+      ...results.filter((r) => r !== null).map((r) => r.contribution)
+    ];
+    if (parts.length === 0) return null;
+    return mergeAggregates(parts);
+  }
+  /**
+   * Build the device-manager's own contribution to the aggregator — the
+   * device identity (id, stableId, addonId, type, online) + the
+   * driver-specific config exposed by the device class via
+   * `zodEntriesToConfigUI`.
+   *
+   * Two paths, deliberately symmetric with `getSettingsSchema`:
+   *
+   *  - Hub-local: device's IDevice instance lives in this process'
+   *    DeviceRegistry, we read config + schema directly by reference.
+   *  - Cross-process: device lives in a forked worker (RtspCamera on
+   *    provider-rtsp, ONVIF on provider-onvif, …). We ask the worker's
+   *    `device-ops.getSettingsSchema` native provider for a wire-
+   *    serializable ConfigUISchema and merge it in under the same
+   *    "Driver Config" section, so the UI sees the same shape regardless
+   *    of where the IDevice physically runs.
+   *
+   *  Returns `null` only when the device genuinely doesn't exist anywhere
+   *  (no hub-local, no persisted ownership, no device-ops native). The
+   *  aggregator falls back to contributor sections only in that case.
+   */
+  async buildBaseDeviceSection(deviceId) {
+    const hubRegistry = this.ctx.kernel?.deviceRegistry;
+    const hubLocal = hubRegistry ? resolveDeviceById(hubRegistry, deviceId) : null;
+    const stableId = hubLocal?.device.stableId ?? await this.lookupPersistedStableId(deviceId);
+    const nativeOwner = this.resolveNativeDeviceOwner(deviceId);
+    const addonId = hubLocal?.addonId ?? nativeOwner?.addonId ?? null;
+    if (!hubLocal && !nativeOwner) return null;
+    const identityFields = [
+      {
+        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 sections = [
+      {
+        id: "device-identity",
+        title: "Identity",
+        tab: "general",
+        order: 0,
+        fields: identityFields
+      }
+    ];
+    const driverSchema = await this.resolveDriverConfigSchema(deviceId, hubLocal);
+    if (driverSchema) {
+      for (const section of driverSchema.sections) {
+        sections.push({
+          id: section.id,
+          title: section.title,
+          tab: section.tab ?? "general",
+          order: section.order ?? 1,
+          fields: [...section.fields],
+          ...section.description !== void 0 ? { description: section.description } : {},
+          ...section.columns !== void 0 ? { columns: section.columns } : {}
+        });
+      }
+    }
+    return {
+      sections,
+      ...driverSchema?.tabs ? { tabs: [...driverSchema.tabs] } : {}
+    };
+  }
+  /**
+   * Lookup the native owner for `device-ops` on `deviceId` — the native-cap
+   * registry (hub-local and remote) is keyed by numeric id.
+   */
+  resolveNativeDeviceOwner(deviceId) {
+    const local = this.capabilityRegistry?.getNativeAddonId("device-ops", deviceId) ?? null;
+    if (local) return { addonId: local, nodeId: this.ctx.kernel.localNodeId ?? "hub" };
+    const remote = this.remoteNativeCaps.get(deviceId)?.get("device-ops") ?? null;
+    return remote ? { addonId: remote.addonId, nodeId: remote.nodeId } : null;
+  }
+  /**
+   * Aggregate `status` across every registered cap for a device.
+   *
+   * Walks the supplied cap list (or `CAP_NAMES_WITH_STATUS` when
+   * omitted), looks up a native provider per cap via the capability
+   * registry, calls `provider.getStatus({ deviceId })`, and validates
+   * the return against the cap's own `status.schema`. Validation
+   * failures log a warning and yield `null` for that cap so the
+   * overall aggregate stays usable — a single misbehaving provider
+   * must not blank out a device's entire status view.
+   *
+   * Returned shape is `Record<capName, unknown | null>`; the client-
+   * side hook tightens this to `CapStatusTypeMap` via the generated
+   * `cap-status-types.ts`.
+   */
+  async getDeviceStatusAggregate(input) {
+    const capNames = input.caps ?? CAP_NAMES_WITH_STATUS;
+    const registry = this.capabilityRegistry;
+    const out = {};
+    if (!registry) {
+      for (const name of capNames) out[name] = null;
+      return out;
+    }
+    await Promise.all(capNames.map(async (capName) => {
+      try {
+        const def = registry.getDefinition(capName);
+        if (!def?.status) {
+          out[capName] = null;
+          return;
+        }
+        const provider = registry.getNativeProvider(capName, input.deviceId);
+        if (!provider || typeof provider.getStatus !== "function") {
+          out[capName] = null;
+          return;
+        }
+        const raw = await provider.getStatus({ deviceId: input.deviceId });
+        if (raw == null) {
+          out[capName] = null;
+          return;
+        }
+        const parsed = def.status.schema.safeParse(raw);
+        if (!parsed.success) {
+          this.ctx.logger.warn("getDeviceStatusAggregate: provider returned invalid status, dropping", {
+            tags: { deviceId: input.deviceId },
+            meta: { capName, issues: parsed.error.issues.slice(0, 3) }
+          });
+          out[capName] = null;
+          return;
+        }
+        out[capName] = parsed.data;
+      } catch (err) {
+        this.ctx.logger.warn("getDeviceStatusAggregate: provider threw, dropping", {
+          tags: { deviceId: input.deviceId },
+          meta: { capName, error: errMsg(err) }
+        });
+        out[capName] = null;
+      }
+    }));
+    return out;
+  }
+  /**
+   * Return the driver-specific device-settings contribution. Hub-local
+   * devices call `getSettingsUISchema()` directly; forked-worker devices
+   * go through the `device-ops.getSettingsSchema` cap method on the
+   * numeric-id-keyed native registry.
+   */
+  async resolveDriverConfigSchema(deviceId, hubLocal) {
+    if (hubLocal) {
+      const schema = hubLocal.device.getSettingsUISchema();
+      return schema.sections.length === 0 ? null : toWireShape(schema);
+    }
+    const ops = this.capabilityRegistry?.getNativeProvider("device-ops", deviceId);
+    if (!ops) return null;
+    try {
+      const schema = await ops.getSettingsSchema({ deviceId });
+      if (!schema) return null;
+      const wire = schema;
+      return wire.sections.length === 0 ? null : toWireShape(wire);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      this.ctx.logger.warn("cross-process getSettingsSchema failed", { tags: { deviceId }, meta: { error: msg } });
+      return null;
+    }
+  }
+  async updateDeviceField(input) {
+    if (input.writerCapName === "device-manager") {
+      const hubRegistry = this.ctx.kernel?.deviceRegistry;
+      const found = hubRegistry ? resolveDeviceById(hubRegistry, input.deviceId) : null;
+      if (found) {
+        await found.device.applySettingsPatch({ [input.key]: input.value });
+        return { success: true };
+      }
+      const ops = this.capabilityRegistry?.getNativeProvider("device-ops", input.deviceId);
+      if (!ops) {
+        throw new Error(`[device-manager] device "${input.deviceId}" not found (no hub-local entry, no device-ops native provider)`);
+      }
+      await ops.setConfig({ deviceId: input.deviceId, values: { [input.key]: input.value } });
+      return { success: true };
+    }
+    const registry = this.capabilityRegistry;
+    if (!registry) {
+      throw new Error("[device-manager] updateDeviceField requires capability registry \u2014 unavailable on this node");
+    }
+    const def = registry.getDefinition(input.writerCapName);
+    if (!def?.exposesDeviceSettings) {
+      throw new Error(`[device-manager] cap "${input.writerCapName}" does not expose device settings`);
+    }
+    const provider = registry.getProviderByAddon(input.writerCapName, input.writerAddonId);
+    if (!provider) {
+      throw new Error(`[device-manager] provider "${input.writerAddonId}" not registered for cap "${input.writerCapName}"`);
+    }
+    await provider.applyDeviceSettingsPatch({
+      deviceId: input.deviceId,
+      patch: { [input.key]: input.value }
+    });
+    return { success: true };
+  }
+  /**
+   * Batched counterpart of `updateDeviceField`. Groups changes by
+   * `(writerCapName, writerAddonId)` so each contributor receives a
+   * single `applyDeviceSettingsPatch` with all of its updates merged —
+   * avoids N round-trips for simultaneous edits in the same save.
+   *
+   * Per-provider failures are captured in the `failures[]` output so the
+   * admin UI can highlight which sections didn't persist; a failure on
+   * one provider does NOT abort the others.
+   */
+  async updateDeviceFieldsBatch(input) {
+    const groups = /* @__PURE__ */ new Map();
+    for (const change of input.changes) {
+      const key = `${change.writerCapName}::${change.writerAddonId}`;
+      const existing = groups.get(key);
+      if (existing) {
+        existing.patch[change.key] = change.value;
+      } else {
+        groups.set(key, {
+          writerCapName: change.writerCapName,
+          writerAddonId: change.writerAddonId,
+          patch: { [change.key]: change.value }
+        });
+      }
+    }
+    const failures = [];
+    for (const group of groups.values()) {
+      try {
+        await this.applyGroupPatch(input.deviceId, group);
+      } catch (err) {
+        failures.push({
+          writerCapName: group.writerCapName,
+          writerAddonId: group.writerAddonId,
+          error: err instanceof Error ? err.message : String(err)
+        });
+      }
+    }
+    return { success: true, failures };
+  }
+  /** Apply a single grouped patch to the appropriate provider. Mirrors
+   * `updateDeviceField` routing (special-case device-manager, else
+   * registry lookup). Used by `updateDeviceFieldsBatch`. */
+  async applyGroupPatch(deviceId, group) {
+    if (group.writerCapName === "device-manager") {
+      const hubRegistry = this.ctx.kernel?.deviceRegistry;
+      const found = hubRegistry ? resolveDeviceById(hubRegistry, deviceId) : null;
+      if (found) {
+        await found.device.applySettingsPatch(group.patch);
+        return;
+      }
+      const ops = this.capabilityRegistry?.getNativeProvider("device-ops", deviceId);
+      if (!ops) {
+        throw new Error(`[device-manager] device "${deviceId}" not found (no hub-local entry, no device-ops native provider)`);
+      }
+      await ops.setConfig({ deviceId, values: group.patch });
+      return;
+    }
+    const registry = this.capabilityRegistry;
+    if (!registry) throw new Error("[device-manager] capability registry unavailable");
+    const def = registry.getDefinition(group.writerCapName);
+    if (!def?.exposesDeviceSettings) {
+      throw new Error(`[device-manager] cap "${group.writerCapName}" does not expose device settings`);
+    }
+    const provider = registry.getProviderByAddon(group.writerCapName, group.writerAddonId);
+    if (!provider) {
+      throw new Error(`[device-manager] provider "${group.writerAddonId}" not registered for cap "${group.writerCapName}"`);
+    }
+    await provider.applyDeviceSettingsPatch({ deviceId, patch: group.patch });
+  }
+  async listWrappersForCap(input) {
+    return [...this.capabilityRegistry?.getWrappersForCap(input.capName) ?? []];
+  }
+  async listBindableCapsForDeviceType(input) {
+    const registry = this.capabilityRegistry;
+    if (!registry) return [];
+    const capNames = registry.listDeviceScopedCapsForType(input.deviceType);
+    return capNames.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 \u2014 device persistence unavailable");
+      return;
+    }
+    const registry = this.ctx.kernel.deviceRegistry ?? null;
+    if (!registry) {
+      this.ctx.logger.warn("device-registry not available \u2014 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 () => {
+      const store = await readStore();
+      return store.deviceIndex ?? {};
+    };
+    const readMeta = async () => {
+      const store = await readStore();
+      return store.deviceMeta ?? {};
+    };
+    const readMetadataMap = async () => {
+      const store = await readStore();
+      return store.deviceMetadata ?? {};
+    };
+    let metaWriteChain = Promise.resolve();
+    const withMetaWriteLock = async (fn) => {
+      const previous = metaWriteChain;
+      let release = () => {
+      };
+      const next = new Promise((resolve) => {
+        release = resolve;
+      });
+      metaWriteChain = next;
+      try {
+        await previous.catch(() => {
+        });
+        return await fn();
+      } finally {
+        release();
+      }
+    };
+    const resolvePersistedById = async (deviceId) => {
+      const meta = await readMeta();
+      for (const [key, m] of Object.entries(meta)) {
+        if (m.id === deviceId) {
+          const sep = key.indexOf(":");
+          if (sep < 0) continue;
+          return { addonId: key.slice(0, sep), stableId: key.slice(sep + 1), meta: m };
+        }
+      }
+      return null;
+    };
+    const idToAddonId = /* @__PURE__ */ new Map();
+    {
+      const meta = await readMeta();
+      for (const [key, m] of Object.entries(meta)) {
+        const sep = key.indexOf(":");
+        if (sep < 0) continue;
+        idToAddonId.set(m.id, key.slice(0, sep));
+      }
+    }
+    if (cluster) {
+      cluster.broker.localBus.on("$node.connected", (payload) => {
+        const connectedNodeId = payload.node.id;
+        const lastSlash = connectedNodeId.lastIndexOf("/");
+        if (lastSlash < 0) return;
+        const connectedAddonId = connectedNodeId.slice(lastSlash + 1);
+        if (connectedAddonId.length === 0) return;
+        for (const [deviceId, ownerAddonId] of idToAddonId) {
+          if (ownerAddonId !== connectedAddonId) continue;
+          if (this.capabilityRegistry?.getNativeAddonId("device-ops", deviceId)) continue;
+          let perDevice = this.remoteNativeCaps.get(deviceId);
+          if (!perDevice) {
+            perDevice = /* @__PURE__ */ new Map();
+            this.remoteNativeCaps.set(deviceId, perDevice);
+          }
+          if (!perDevice.has("device-ops")) {
+            perDevice.set("device-ops", { addonId: connectedAddonId, nodeId: connectedNodeId });
+          }
+        }
+        setTimeout(() => {
+          this.discoverWorkerNativeCaps(connectedNodeId, connectedAddonId).catch((err) => {
+            this.ctx.logger.warn("worker native-cap discovery failed", {
+              meta: { nodeId: connectedNodeId, addonId: connectedAddonId, error: errMsg(err) }
+            });
+          });
+        }, 500);
+      });
+    }
+    const allocateNextDeviceId = async () => {
+      const store = await readStore();
+      const current = store.nextDeviceId ?? 1;
+      await settings.writeAddonStore({ nextDeviceId: current + 1 });
+      return current;
+    };
+    const provider = {
+      /** Sync ownership lookup backing persistence fallbacks (e.g. remove()
+       *  when the owning worker is offline). Ownership is keyed by numeric
+       *  deviceId → owning addonId as recorded in the persisted meta. NOT
+       *  a native-cap lookup: an addon can own a device without registering
+       *  every possible cap natively (e.g. RtspCamera without snapshotUrl
+       *  doesn't register the snapshot cap). Use
+       *  `resolveNativeCapOwnerSync` for cap-resolution paths.
+       */
+      resolveDeviceOwnerSync: (deviceId) => {
+        return idToAddonId.get(deviceId) ?? null;
+      },
+      /** Sync lookup for the addon that registered a native provider for
+       *  `(capName, deviceId)`. Backs `CapabilityRegistry`'s native fallback
+       *  so the hub only synthesizes a cross-process proxy when the cap is
+       *  actually published — never on speculative device ownership.
+       *
+       *  Consults hub-local registrations first (in-process natives),
+       *  then the `remoteNativeCaps` map populated from
+       *  `DeviceBindingsChanged` events emitted by forked-worker
+       *  `registerNativeCap` calls. Both are generic: any addon that hosts
+       *  devices and registers caps via the standard context API shows up
+       *  here without per-addon branching.
+       */
+      resolveNativeCapOwnerSync: (capName, deviceId) => {
+        const localAddonId = this.capabilityRegistry?.getNativeAddonId(capName, deviceId) ?? null;
+        if (localAddonId) {
+          return { addonId: localAddonId, nodeId: this.ctx.kernel.localNodeId ?? "hub" };
+        }
+        const remote = this.remoteNativeCaps.get(deviceId)?.get(capName) ?? null;
+        if (remote) return { addonId: remote.addonId, nodeId: remote.nodeId };
+        return null;
+      },
+      // ── Persistence ────────────────────────────────────────────────────────
+      /** Idempotent numeric-id reservation. Callers invoke this before
+       *  constructing the owning `IDevice` so `DeviceContext.id` is bound
+       *  at construction time. A repeat call for the same `(addonId,
+       *  stableId)` returns the already-persisted id — same physical
+       *  device reconnecting after a driver restart keeps its original
+       *  number. Fresh pairs burn one slot from the monotonic
+       *  `nextDeviceId` counter and seed a meta placeholder so the
+       *  `deviceMeta` → `id` invariant holds even before
+       *  `registerDevice` completes. */
+      allocateDeviceId: async (input) => {
+        const { addonId, stableId } = input;
+        const key = deviceKey(addonId, stableId);
+        return await withMetaWriteLock(async () => {
+          const meta = await readMeta();
+          const existing = meta[key];
+          if (existing) return { id: existing.id };
+          const id = await allocateNextDeviceId();
+          await settings.writeAddonStore({
+            deviceMeta: {
+              ...meta,
+              [key]: {
+                type: "generic",
+                name: stableId,
+                location: null,
+                disabled: false,
+                parentDeviceId: null,
+                id
+              }
+            }
+          });
+          return { id };
+        });
+      },
+      registerDevice: async (input) => {
+        const { addonId, stableId, id, type, name, parentDeviceId, features, config } = input;
+        const key = deviceKey(addonId, stableId);
+        const featuresArr = Array.isArray(features) ? [...features] : [];
+        const { isFirstRegistration } = await withMetaWriteLock(async () => {
+          const index = await readIndex();
+          const existing = index[addonId] ?? [];
+          const wasInIndex = existing.includes(stableId);
+          if (!wasInIndex) {
+            await settings.writeAddonStore({
+              deviceIndex: { ...index, [addonId]: [...existing, stableId] }
+            });
+          }
+          const meta = await readMeta();
+          const existingMeta = meta[key];
+          const isFirst = !existingMeta || !wasInIndex;
+          await settings.writeAddonStore({
+            deviceMeta: {
+              ...meta,
+              [key]: {
+                type,
+                // Prefer the persisted name (set by `setName` pre-construct)
+                // over the construction-time fallback. Only when the meta
+                // row literally still carries `name === stableId` (the
+                // placeholder seeded by `allocateDeviceId`) do we fall
+                // back to the action arg.
+                name: existingMeta && existingMeta.name !== stableId ? existingMeta.name : name,
+                location: existingMeta?.location ?? null,
+                disabled: existingMeta?.disabled ?? false,
+                parentDeviceId,
+                id,
+                features: featuresArr
+              }
+            }
+          });
+          return { isFirstRegistration: isFirst };
+        });
+        if (Object.keys(config).length > 0) {
+          await settings.writeDeviceStore(id, config);
+        }
+        idToAddonId.set(id, addonId);
+        if (isFirstRegistration) {
+          this.ctx.eventBus.emit({
+            id: randomUUID(),
+            timestamp: /* @__PURE__ */ new Date(),
+            source: { type: "device", id },
+            category: EventCategory.DeviceRegistered,
+            data: {
+              deviceId: id,
+              name: name.length > 0 ? name : stableId,
+              providerId: addonId,
+              parentDeviceId: parentDeviceId ?? null
+            }
+          });
+        } else {
+          this.ctx.eventBus.emit({
+            id: randomUUID(),
+            timestamp: /* @__PURE__ */ new Date(),
+            source: { type: "device", id },
+            category: EventCategory.DeviceMetaChanged,
+            data: {
+              deviceId: id,
+              name: name.length > 0 ? name : stableId,
+              providerId: addonId,
+              parentDeviceId: parentDeviceId ?? null,
+              features: featuresArr
+            }
+          });
+        }
+      },
+      removeDevice: async (input) => {
+        const { deviceId } = input;
+        const persisted = await resolvePersistedById(deviceId);
+        if (!persisted) {
+          return;
+        }
+        const { addonId, stableId, meta: persistedMeta } = persisted;
+        const key = deviceKey(addonId, stableId);
+        const deviceName = persistedMeta.name;
+        await withMetaWriteLock(async () => {
+          const index = await readIndex();
+          const remaining = (index[addonId] ?? []).filter((sid) => sid !== stableId);
+          const updatedIndex = remaining.length > 0 ? { ...index, [addonId]: remaining } : (() => {
+            const { [addonId]: _removed, ...rest } = index;
+            return rest;
+          })();
+          await settings.writeAddonStore({ deviceIndex: updatedIndex });
+          const meta = await readMeta();
+          const { [key]: _removedMeta, ...restMeta } = meta;
+          await settings.writeAddonStore({ deviceMeta: restMeta });
+          const map = await readMetadataMap();
+          if (key in map) {
+            const { [key]: _removedMetadata, ...restMap } = map;
+            await settings.writeAddonStore({ deviceMetadata: restMap });
+          }
+        });
+        await settings.clearDeviceStore(deviceId);
+        const bindingsStore = await this.readBindingsStore();
+        const bindingKey = String(deviceId);
+        if (bindingsStore.deviceBindings[bindingKey]) {
+          const { [bindingKey]: _removedBindings, ...restBindings } = bindingsStore.deviceBindings;
+          await this.writeBindingsStore({ deviceBindings: restBindings });
+        }
+        this.remoteNativeCaps.delete(deviceId);
+        this.capabilityRegistry?.unregisterAllNativeForDevice(deviceId);
+        idToAddonId.delete(deviceId);
+        this.ctx.logger.info("removed device", { tags: { deviceId, deviceName: deviceName.length > 0 ? deviceName : stableId } });
+        this.ctx.eventBus.emit({
+          id: randomUUID(),
+          timestamp: /* @__PURE__ */ new Date(),
+          source: { type: "device", id: deviceId },
+          category: EventCategory.DeviceUnregistered,
+          data: {
+            deviceId,
+            providerId: addonId,
+            // Carry parentDeviceId so listeners can filter on "is
+            // this MY child?" without consulting an in-memory map
+            // they had to keep in sync. By the time this event
+            // fires the meta row is already gone — we read it from
+            // the resolved snapshot above.
+            parentDeviceId: persistedMeta.parentDeviceId ?? null
+          }
+        });
+      },
+      persistConfig: async (input) => {
+        const { deviceId, data } = input;
+        const persisted = await resolvePersistedById(deviceId);
+        if (!persisted) throw new Error(`[device-manager] persistConfig: unknown device id=${deviceId}`);
+        await settings.writeDeviceStore(deviceId, data);
+      },
+      loadConfig: async (input) => {
+        const { deviceId } = input;
+        const persisted = await resolvePersistedById(deviceId);
+        if (!persisted) 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 map = await readMetadataMap();
+        const metadata = map[key] ?? null;
+        return {
+          id: m.id,
+          stableId,
+          addonId,
+          type: m.type,
+          name: m.name,
+          location: m.location ?? null,
+          disabled: m.disabled ?? false,
+          parentDeviceId: m.parentDeviceId,
+          metadata
+        };
+      },
+      /**
+       * Update the operator-edited display name. Writes the meta
+       * row, emits a `DeviceMetaChanged` event so live consumers
+       * (UI device list, alert center) see the rename without
+       * polling. The live `IDevice.name` mirror is updated by the
+       * kernel proxy on its side (`device-cap-proxy.ts`).
+       */
+      setName: async (input) => {
+        const { deviceId, name } = input;
+        await withMetaWriteLock(async () => {
+          const persisted = await resolvePersistedById(deviceId);
+          if (!persisted) throw new Error(`[device-manager] setName: unknown device id=${deviceId}`);
+          const { addonId, stableId, meta: m } = persisted;
+          const key = deviceKey(addonId, stableId);
+          const allMeta = await readMeta();
+          await settings.writeAddonStore({
+            deviceMeta: { ...allMeta, [key]: { ...m, name } }
+          });
+        });
+        this.ctx.eventBus.emit({
+          id: randomUUID(),
+          timestamp: /* @__PURE__ */ new Date(),
+          source: { type: "device", id: deviceId },
+          category: EventCategory.DeviceMetaChanged,
+          data: { deviceId, field: "name", value: name }
+        });
+      },
+      /**
+       * Update the operator-organisational location label. `null`
+       * clears it. Mirrors the same persist-then-emit shape as
+       * `setName`; consumers subscribe to `DeviceMetaChanged` and
+       * filter on `field: 'location'`.
+       */
+      setLocation: async (input) => {
+        const { deviceId, location } = input;
+        await withMetaWriteLock(async () => {
+          const persisted = await resolvePersistedById(deviceId);
+          if (!persisted) throw new Error(`[device-manager] setLocation: unknown device id=${deviceId}`);
+          const { addonId, stableId, meta: m } = persisted;
+          const key = deviceKey(addonId, stableId);
+          const allMeta = await readMeta();
+          await settings.writeAddonStore({
+            deviceMeta: { ...allMeta, [key]: { ...m, location } }
+          });
+        });
+        this.ctx.eventBus.emit({
+          id: randomUUID(),
+          timestamp: /* @__PURE__ */ new Date(),
+          source: { type: "device", id: deviceId },
+          category: EventCategory.DeviceMetaChanged,
+          data: { deviceId, field: "location", value: location }
+        });
+      },
+      /**
+       * Patch the device's hardware-identity metadata blob. Shallow
+       * merge — `null` removes a key, anything else overwrites.
+       * Drivers populate factual fields on first probe; operators
+       * augment via the Device Info tab. Idempotent: a no-op patch
+       * (every key already present with the same value) doesn't emit
+       * the meta-changed event.
+       */
+      setMetadata: async (input) => {
+        const { deviceId, patch } = input;
+        const result = await withMetaWriteLock(async () => {
+          const persisted = await resolvePersistedById(deviceId);
+          if (!persisted) throw new Error(`[device-manager] setMetadata: unknown device id=${deviceId}`);
+          const { addonId, stableId } = persisted;
+          const key = deviceKey(addonId, stableId);
+          const map = await readMetadataMap();
+          const current = map[key] ?? {};
+          const next = { ...current };
+          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;
+        const persisted = await resolvePersistedById(deviceId);
+        if (!persisted) return {};
+        const data = await settings.readDeviceRuntimeState(deviceId);
+        this.seedMirror(deviceId, data);
+        return data;
+      },
+      /**
+       * Union of (1) operator-curated location registry and (2) labels
+       * currently in use on persisted devices. Case-insensitive
+       * dedupe (preserves the first-seen casing). Sorted
+       * case-insensitively for stable UI. Drives the Device Info
+       * location autocomplete.
+       */
+      listLocations: async () => {
+        const store = await settings.readAddonStore();
+        const meta = store.deviceMeta ?? {};
+        const registry2 = 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 registry2) consider(label);
+        for (const m of Object.values(meta)) consider(m.location);
+        return [...seen.values()].sort(
+          (a, b) => a.localeCompare(b, void 0, { sensitivity: "base" })
+        );
+      },
+      /**
+       * Add a label to the curated location registry. Idempotent:
+       * existing entries (case-insensitive match) are silently kept.
+       * Empty / whitespace-only inputs throw — operators must supply a
+       * meaningful label.
+       */
+      addLocation: async (input) => {
+        const trimmed = input.name.trim();
+        if (trimmed.length === 0) {
+          throw new Error("[device-manager] addLocation: name must be non-empty");
+        }
+        const store = await settings.readAddonStore();
+        const current = store.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()]);
+        const stableIds = index[addonId] ?? [];
+        return stableIds.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
+          };
+        });
+      },
+      // ── Live queries — serve from live registry when available ────────────
+      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 is not persisted to disk — only set on the live
+              // IDevice (`BaseDevice.role`) by accessory subclasses. The
+              // forked-worker fallback path can't read it, so emit null;
+              // accessories typically run in the same process as their
+              // parent provider, so the live path covers them in practice.
+              role: null,
+              // registry===null was the legacy "offline view" signal; keep it
+              // for that case so existing callers see online=false. When a
+              // registry is present and the device lives elsewhere (forked
+              // worker), default to online=true — persisted state implies it
+              // was successfully registered by its owning process.
+              online: registry !== null,
+              features: persistedFeatures(m?.features),
+              // Live IDevice isn't reachable from the hub, so infer
+              // isCamera from the persisted DeviceType rather than the
+              // method-presence check `toDeviceInfo` uses. Without this
+              // forked-worker cameras looked non-camera to the stream-broker
+              // and never got their RTSP restream wired up.
+              isCamera: persistedType === DeviceType.Camera,
+              config: persistedConfig ?? {},
+              metadata
+            });
+          }
+        }
+        return results;
+      },
+      getDevice: async (input) => {
+        const { deviceId } = input;
+        if (registry) {
+          const found = resolveDeviceById(registry, deviceId);
+          if (found) {
+            const key2 = deviceKey(found.addonId, found.device.stableId);
+            const [map2, metaMap] = await Promise.all([readMetadataMap(), readMeta()]);
+            const metadata2 = map2[key2] ?? null;
+            const metaRow = metaMap[key2] ?? null;
+            return toDeviceInfo(found.addonId, found.device, metadata2, 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 map = await readMetadataMap();
+        const metadata = map[key] ?? null;
+        return {
+          id: deviceId,
+          stableId,
+          addonId: aid,
+          type: m.type,
+          name: m.name,
+          location: m.location ?? null,
+          disabled: m.disabled ?? false,
+          parentDeviceId: m.parentDeviceId,
+          role: null,
+          online: true,
+          features: persistedFeatures(m.features),
+          isCamera: false,
+          config: persistedConfig ?? {},
+          metadata
+        };
+      },
+      getChildren: async (input) => {
+        const { parentDeviceId } = input;
+        let ownerAddonId = null;
+        if (registry) {
+          const liveParent = registry.getById(parentDeviceId);
+          if (liveParent) {
+            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 stableIds = index[ownerAddonId] ?? [];
+        const persistedChildren = stableIds.filter(
+          (sid) => meta[deviceKey(ownerAddonId, sid)]?.parentDeviceId === parentDeviceId
+        );
+        for (const childStableId of persistedChildren) {
+          const key = deviceKey(ownerAddonId, childStableId);
+          if (seen.has(key)) continue;
+          const m = meta[key];
+          const persistedConfig = await settings.readDeviceStore(m.id);
+          const metadata = metadataMap[key] ?? null;
+          results.push({
+            id: m.id,
+            stableId: childStableId,
+            addonId: ownerAddonId,
+            type: m.type,
+            name: m.name,
+            location: m.location ?? null,
+            disabled: m.disabled ?? false,
+            parentDeviceId,
+            role: null,
+            online: registry !== null,
+            features: persistedFeatures(m.features),
+            isCamera: false,
+            config: persistedConfig ?? {},
+            metadata
+          });
+        }
+        return results;
+      },
+      // ── Live runtime methods ──────────────────────────────────────────────
+      getStreamSources: async (input) => {
+        const { deviceId } = input;
+        if (registry) {
+          const found = resolveDeviceById(registry, deviceId);
+          if (found) {
+            if (!isCameraDevice(found.device)) return [];
+            const sources2 = await found.device.getStreamSources();
+            return sources2.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
+            }));
+          }
+        }
+        const persisted = await resolvePersistedById(deviceId);
+        if (!persisted) throw new Error(`[device-manager] Device with id ${deviceId} not found`);
+        const ops = requireDeviceOps(deviceId);
+        const sources = await ops.getStreamSources({ deviceId });
+        return sources.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 } : {}
+            }));
+          }
+        }
+        const persisted = await resolvePersistedById(deviceId);
+        if (!persisted) throw new Error(`[device-manager] Device with id ${deviceId} not found`);
+        const ops = requireDeviceOps(deviceId);
+        const entries = await ops.getConfigEntries({ deviceId });
+        return entries.map((e) => ({ ...e }));
+      },
+      getSettingsSchema: async (input) => {
+        const { deviceId } = input;
+        if (registry) {
+          const found = resolveDeviceById(registry, deviceId);
+          if (found) {
+            return found.device.getSettingsUISchema();
+          }
+        }
+        const persisted = await resolvePersistedById(deviceId);
+        if (!persisted) return null;
+        const ops = requireDeviceOps(deviceId);
+        const schema = await ops.getSettingsSchema({ deviceId });
+        return schema ?? 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 };
+          }
+        }
+        const persisted = await resolvePersistedById(deviceId);
+        if (!persisted) throw new Error(`[device-manager] Device with id ${deviceId} not found`);
+        const ops = requireDeviceOps(deviceId);
+        await ops.setConfig({ deviceId, values: input.values });
+        return { success: true };
+      },
+      // `enable` / `disable` write to deviceMeta.disabled (the canonical
+      // soft-disable flag that drivers consult via `BaseDevice.disabled`
+      // at lifecycle entrypoints, and that `toDeviceInfo` projects onto
+      // the wire by reading the LATEST persisted meta row — see the
+      // `metaRow` argument plumbed through `listAll` / `getDevice` /
+      // `getChildren`).
+      //
+      // Earlier these wrappers wrote `enabled: true/false` into the
+      // device CONFIG blob — wrong store entirely. The config write
+      // succeeded but the flag the rest of the system reads
+      // (deviceMeta) stayed unchanged, so the UI's enable/disable
+      // toggle appeared to do nothing. Delegating to `setDisabled`
+      // routes through the correct withMetaWriteLock path and emits
+      // the `DeviceMetaChanged` event for live invalidation.
+      //
+      // NB: `BaseDevice.disabled` is `readonly` and bound at
+      // construction (base-device.ts:142). Drivers that gate behaviour
+      // off `this.disabled` only see the value the device was
+      // instantiated with — flipping disabled at runtime updates the
+      // wire response immediately, but lifecycle gating inside the
+      // driver only takes effect on the next instantiation. That's
+      // acceptable today: the operator-facing semantic is "hide /
+      // mark inactive in the UI"; the heavyweight teardown semantic
+      // is `remove`.
+      enable: async (input) => {
+        await provider.setDisabled({ deviceId: input.deviceId, disabled: false });
+        return { success: true };
+      },
+      disable: async (input) => {
+        await provider.setDisabled({ deviceId: input.deviceId, disabled: true });
+        return { success: true };
+      },
+      remove: async (input) => {
+        const { deviceId } = input;
+        if (registry) {
+          const live = resolveDeviceById(registry, deviceId);
+          if (live) {
+            const deviceName = live.device.name;
+            await live.device.removeDevice();
+            registry.remove(deviceId);
+            await provider.removeDevice({ deviceId });
+            this.ctx.logger.info("removed hub-local device", { tags: { deviceId, deviceName } });
+            return { success: true };
+          }
+        }
+        const persisted = await resolvePersistedById(deviceId);
+        if (!persisted) throw new Error(`[device-manager] Device with id ${deviceId} not found`);
+        const { meta: persistedMeta } = persisted;
+        try {
+          const ops = requireDeviceOps(deviceId);
+          await ops.removeDevice({ deviceId });
+        } catch (err) {
+          this.ctx.logger.warn("remove via device-ops failed \u2014 clearing persistence anyway", { tags: { deviceId, deviceName: persistedMeta.name }, meta: { error: errMsg(err) } });
+        }
+        await provider.removeDevice({ deviceId });
+        return { success: true };
+      },
+      getStreamProfileMap: async (input) => {
+        if (!registry) return {};
+        const found = resolveDeviceById(registry, input.deviceId);
+        if (!found) return {};
+        const storedMap = found.device.config.entries().find((e) => e.key === "_profileMap")?.value;
+        if (storedMap !== void 0 && typeof storedMap === "object" && storedMap !== null) {
+          return storedMap;
+        }
+        if (!isCameraDevice(found.device)) return {};
+        const sources = await found.device.getStreamSources();
+        const profileMap = {};
+        for (const s of sources) {
+          if (s.profileHint && s.id) {
+            profileMap[s.profileHint] = s.id;
+          }
+        }
+        return profileMap;
+      },
+      setStreamProfileMap: async (input) => {
+        const { deviceId } = input;
+        if (registry) {
+          const found = resolveDeviceById(registry, deviceId);
+          if (found) {
+            await found.device.config.setAll({ _profileMap: input.profileMap });
+            return { success: true };
+          }
+        }
+        const persisted = await resolvePersistedById(deviceId);
+        if (!persisted) throw new Error(`[device-manager] Device with id ${deviceId} not found`);
+        const ops = requireDeviceOps(deviceId);
+        await ops.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 \u2014 returning placeholder", {
+              meta: {
+                deviceId: input.deviceId,
+                streamId: s.id,
+                error: err instanceof Error ? err.message : String(err)
+              }
+            });
+            results.push({ streamId: s.id });
+          }
+        }
+        return results;
+      },
+      // ── Device-provider operations (routed via CapabilityRegistry) ───────
+      discoverDevices: async (input) => {
+        const dp = await this.requireDeviceProvider(input.addonId);
+        const supported = await dp.supportsDiscovery({});
+        if (!supported) {
+          throw new Error(`Addon "${input.addonId}" does not support device discovery`);
+        }
+        const discovered = await dp.discoverDevices({});
+        return discovered.map((d) => ({
+          stableId: d.stableId,
+          type: d.type,
+          suggestedName: d.suggestedName,
+          prefilledConfig: d.prefilledConfig
+        }));
+      },
+      adoptDevice: async (input) => {
+        const dp = await this.requireDeviceProvider(input.addonId);
+        const supported = await dp.supportsDiscovery({});
+        if (!supported) {
+          throw new Error(`Addon "${input.addonId}" does not support device adoption`);
+        }
+        return dp.adoptDiscoveredDevice({
+          candidate: input.candidate
+        });
+      },
+      getCreationSchema: async (input) => {
+        const dp = await this.requireDeviceProvider(input.addonId);
+        const supported = await dp.supportsManualCreation({});
+        if (!supported) return null;
+        const schema = await dp.getChildCreationSchema({ type: input.type });
+        return schema ?? null;
+      },
+      createDevice: async (input) => {
+        const dp = await this.requireDeviceProvider(input.addonId);
+        const supported = await dp.supportsManualCreation({});
+        if (!supported) {
+          throw new Error(`Addon "${input.addonId}" does not support manual device creation`);
+        }
+        return dp.createDevice({ type: input.type, config: input.config });
+      },
+      testCreationField: async (input) => {
+        const dp = await this.requireDeviceProvider(input.addonId);
+        return dp.testCreationField({
+          type: input.type,
+          key: input.key,
+          value: input.value,
+          ...input.formValues !== void 0 ? { formValues: input.formValues } : {}
+        });
+      },
+      testField: async (input) => {
+        const { deviceId } = input;
+        let owningAddonId = null;
+        if (registry) {
+          owningAddonId = registry.getAddonId(deviceId);
+        }
+        if (!owningAddonId) {
+          const persisted = await resolvePersistedById(deviceId);
+          owningAddonId = persisted?.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 });
+      },
+      // ── Bindings — per-device capability provider map ────────────────────
+      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),
+      // ── Device-details aggregators ──────────────────────────────────────
+      getDeviceSettingsAggregate: async (input) => {
+        return this.getDeviceAggregate(input.deviceId, "settings");
+      },
+      getDeviceLiveInfoAggregate: async (input) => {
+        return this.getDeviceAggregate(input.deviceId, "live");
+      },
+      getDeviceAggregate: async (input) => {
+        const [settings2, live] = await Promise.all([
+          this.getDeviceAggregate(input.deviceId, "settings"),
+          this.getDeviceAggregate(input.deviceId, "live")
+        ]);
+        return { settings: settings2, live };
+      },
+      updateDeviceField: async (input) => {
+        return this.updateDeviceField({
+          deviceId: input.deviceId,
+          writerCapName: input.writerCapName,
+          writerAddonId: input.writerAddonId,
+          key: input.key,
+          value: input.value
+        });
+      },
+      updateDeviceFieldsBatch: async (input) => {
+        return this.updateDeviceFieldsBatch({ deviceId: input.deviceId, changes: input.changes });
+      },
+      getDeviceStatusAggregate: async (input) => this.getDeviceStatusAggregate(input)
+    };
+    this.ctx.logger.info("registered device-manager capability", { meta: { liveRegistry: registry !== null } });
+    if (registry) {
+      this.propagator = new DeviceEventPropagator({
+        eventBus: this.ctx.eventBus,
+        getParentOf: (id) => registry.getById(id)?.parentDeviceId ?? null,
+        logger: {
+          warn: (msg, meta) => this.ctx.logger.warn(msg, meta ?? {}),
+          debug: (msg, meta) => this.ctx.logger.debug(msg, meta ?? {})
+        }
+      });
+      this.propagator.start();
+      this.ctx.logger.info("device-event-propagator started");
+    }
+    const deviceStateProvider = {
+      getSnapshot: async (input) => {
+        return this.snapshotForDevice(input.deviceId);
+      },
+      getCapSlice: async (input) => {
+        const perCap = this.stateMirror.get(input.deviceId);
+        const slice = perCap?.get(input.capName);
+        return slice ? { ...slice } : null;
+      },
+      // Whole-system warm-boot dump. Iterates the mirror once and
+      // returns a deeply-cloned `{[deviceId]: {[capName]: slice}}`
+      // payload so callers (SystemManager, dashboards) seed their
+      // local mirror with one round-trip instead of N per-device
+      // calls. Empty inner record for devices with no slices yet.
+      getAllSnapshots: async () => {
+        const out = {};
+        for (const [deviceId, perCap] of this.stateMirror) {
+          const dev = {};
+          for (const [capName, slice] of perCap) dev[capName] = { ...slice };
+          out[String(deviceId)] = dev;
+        }
+        return out;
+      },
+      // Canonical cross-layer write — the single entrypoint every
+      // caller funnels through. In-process providers reach it via
+      // `BaseDevice.runtimeState.setCapState` (which delegates here);
+      // system-scope addons (e.g. pipeline runner writing the motion
+      // slice on phase transitions) call this cap method directly
+      // through `ctx.api.deviceState.setCapSlice.mutate(...)`.
+      setCapSlice: async (input) => {
+        const { deviceId, capName, slice } = input;
+        const persisted = await resolvePersistedById(deviceId);
+        if (!persisted) throw new Error(`[device-manager] setCapSlice: unknown device id=${deviceId}`);
+        this.applySingleCapUpdate(deviceId, capName, slice);
+        this.scheduleRuntimeStateDiskWrite(deviceId, settings);
+      }
+    };
+    return [
+      { capability: deviceManagerCapability, provider },
+      { capability: deviceStateCapability, provider: deviceStateProvider }
+    ];
+  }
+  /**
+   * Single-cap mirror update — diff against the current mirror,
+   * persist the new slice in-memory, emit `DeviceStateChanged` for
+   * this cap. No-op on identical writes (both same shape and same
+   * values). Called by `setCapSlice` provider.
+   */
+  applySingleCapUpdate(deviceId, capName, slice) {
+    let perCap = this.stateMirror.get(deviceId);
+    if (!perCap) {
+      perCap = /* @__PURE__ */ new Map();
+      this.stateMirror.set(deviceId, perCap);
+    }
+    const prior = perCap.get(capName);
+    if (prior && shallowEqual(prior, slice)) return;
+    perCap.set(capName, { ...slice });
+    this.emitStateChanged(deviceId, capName, slice);
+  }
+  /**
+   * Debounced disk writer. Coalesces frequent writes (motion phase
+   * transitions, battery pushes) into one `writeDeviceRuntimeState`
+   * per `RUNTIME_STATE_DEBOUNCE_MS` window. Reads the per-device
+   * blob from the live mirror at flush time so the disk picture is
+   * always the latest state — no risk of writing a stale snapshot.
+   */
+  scheduleRuntimeStateDiskWrite(deviceId, settings) {
+    let slot = this.runtimeStateDebounce.get(deviceId);
+    if (!slot) {
+      slot = { timer: null, inFlight: null };
+      this.runtimeStateDebounce.set(deviceId, slot);
+    }
+    if (slot.timer) return;
+    slot.timer = setTimeout(() => {
+      slot.timer = null;
+      const blob = this.snapshotForDevice(deviceId);
+      const write = (async () => {
+        try {
+          await settings.writeDeviceRuntimeState(deviceId, blob);
+        } catch (err) {
+          this.ctx.logger.warn("writeDeviceRuntimeState failed", {
+            tags: { deviceId },
+            meta: { error: err instanceof Error ? err.message : String(err) }
+          });
+        } finally {
+          slot.inFlight = null;
+        }
+      })();
+      slot.inFlight = write;
+    }, _DeviceManagerAddon.RUNTIME_STATE_DEBOUNCE_MS);
+  }
+  /**
+   * One-shot mirror seed used by `loadRuntimeState` at boot so the
+   * hub knows about every persisted slice without waiting for the
+   * first `setCapSlice` call. No events emitted — this is
+   * initial-state population, not a transition.
+   */
+  seedMirror(deviceId, blob) {
+    let perCap = this.stateMirror.get(deviceId);
+    if (!perCap) {
+      perCap = /* @__PURE__ */ new Map();
+      this.stateMirror.set(deviceId, perCap);
+    }
+    for (const [capName, raw] of Object.entries(blob)) {
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
+      perCap.set(capName, { ...raw });
+    }
+  }
+  snapshotForDevice(deviceId) {
+    const perCap = this.stateMirror.get(deviceId);
+    if (!perCap) return {};
+    const out = {};
+    for (const [k, v] of perCap) out[k] = { ...v };
+    return out;
+  }
+  emitStateChanged(deviceId, capName, slice) {
+    this.ctx.eventBus.emit({
+      id: randomUUID(),
+      timestamp: /* @__PURE__ */ new Date(),
+      source: { type: "device", id: deviceId },
+      category: EventCategory.DeviceStateChanged,
+      data: { deviceId, capName, slice }
+    });
+  }
+  async onShutdown() {
+    this.propagator?.stop();
+    this.propagator = null;
+    const settings = this.ctx.settings;
+    const pending = [];
+    for (const [deviceId, slot] of this.runtimeStateDebounce) {
+      if (slot.timer) {
+        clearTimeout(slot.timer);
+        slot.timer = null;
+        if (settings) {
+          const blob = this.snapshotForDevice(deviceId);
+          pending.push(settings.writeDeviceRuntimeState(deviceId, blob).catch((err) => {
+            this.ctx.logger.warn("shutdown writeDeviceRuntimeState failed", {
+              tags: { deviceId },
+              meta: { error: err instanceof Error ? err.message : String(err) }
+            });
+          }));
+        }
+      }
+      if (slot.inFlight) pending.push(slot.inFlight);
+    }
+    await Promise.all(pending);
+    this.runtimeStateDebounce.clear();
+  }
+};
+var device_manager_addon_default = DeviceManagerAddon;
+
+export {
+  DeviceManagerAddon,
+  device_manager_addon_default
+};
+//# sourceMappingURL=chunk-O4V246GG.mjs.map