@camstack/system 1.1.10 → 1.1.12

package/dist/builtins/device-manager/device-meta-actions.d.ts

@@ -0,0 +1,159 @@
+import { InferProvider, deviceManagerCapability, AddonContext } from '@camstack/types';
+import { DeviceManagerSettings, DeviceMetaStore } from './device-meta-store.js';
+import { ProviderContext } from './device-provider-context.js';
+type IDeviceManagerProvider = InferProvider<typeof deviceManagerCapability>;
+/**
+ * Stamp (or update) the owning integration id on a device's meta row + emit
+ * `DeviceMetaChanged`. The device-manager chokepoint shared by the
+ * `setIntegrationId` cap handler AND the create/adopt forwarders (queries)
+ * that stamp an integration's ownership onto every device it materializes.
+ * Idempotent. Takes its low-level deps directly (not the full `ProviderContext`)
+ * because `ProviderContext.stampIntegrationId` delegates HERE — passing the
+ * context would be a capture cycle.
+ */
+export declare function stampIntegrationId(metaStore: DeviceMetaStore, settings: DeviceManagerSettings, ctx: AddonContext, deviceId: number, integrationId: string): Promise<void>;
+export declare function allocateDeviceId(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['allocateDeviceId']>[0]): ReturnType<IDeviceManagerProvider['allocateDeviceId']>;
+export declare function registerDevice(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['registerDevice']>[0]): ReturnType<IDeviceManagerProvider['registerDevice']>;
+export declare function removeDevice(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['removeDevice']>[0]): ReturnType<IDeviceManagerProvider['removeDevice']>;
+export declare function persistConfig(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['persistConfig']>[0]): ReturnType<IDeviceManagerProvider['persistConfig']>;
+export declare function loadConfig(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['loadConfig']>[0]): ReturnType<IDeviceManagerProvider['loadConfig']>;
+/**
+ * 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.
+ */
+export declare function loadMeta(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['loadMeta']>[0]): ReturnType<IDeviceManagerProvider['loadMeta']>;
+/**
+ * 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`).
+ */
+export declare function setName(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['setName']>[0]): ReturnType<IDeviceManagerProvider['setName']>;
+/**
+ * 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'`.
+ */
+export declare function setLocation(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['setLocation']>[0]): ReturnType<IDeviceManagerProvider['setLocation']>;
+/**
+ * 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'`.
+ */
+export declare function setType(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['setType']>[0]): ReturnType<IDeviceManagerProvider['setType']>;
+/**
+ * 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.
+ */
+export declare function setIntegrationId(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['setIntegrationId']>[0]): ReturnType<IDeviceManagerProvider['setIntegrationId']>;
+/**
+ * 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.
+ */
+export declare function setLinkDeviceId(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['setLinkDeviceId']>[0]): ReturnType<IDeviceManagerProvider['setLinkDeviceId']>;
+/**
+ * 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.
+ */
+export declare function setPrimaryChildEntityId(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['setPrimaryChildEntityId']>[0]): ReturnType<IDeviceManagerProvider['setPrimaryChildEntityId']>;
+/**
+ * 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.
+ */
+export declare function setChildLayout(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['setChildLayout']>[0]): ReturnType<IDeviceManagerProvider['setChildLayout']>;
+/**
+ * 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`.
+ */
+export declare function setDeviceLinks(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['setDeviceLinks']>[0]): ReturnType<IDeviceManagerProvider['setDeviceLinks']>;
+/**
+ * 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.
+ */
+export declare function setRole(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['setRole']>[0]): ReturnType<IDeviceManagerProvider['setRole']>;
+/**
+ * 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.
+ */
+export declare function applyInitialMeta(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['applyInitialMeta']>[0]): ReturnType<IDeviceManagerProvider['applyInitialMeta']>;
+/**
+ * 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.
+ */
+export declare function setMetadata(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['setMetadata']>[0]): ReturnType<IDeviceManagerProvider['setMetadata']>;
+/**
+ * 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).
+ */
+export declare function setDisabled(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['setDisabled']>[0]): ReturnType<IDeviceManagerProvider['setDisabled']>;
+export declare function loadRuntimeState(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['loadRuntimeState']>[0]): ReturnType<IDeviceManagerProvider['loadRuntimeState']>;
+/**
+ * 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.
+ */
+export declare function listLocations(pctx: ProviderContext): ReturnType<IDeviceManagerProvider['listLocations']>;
+/**
+ * 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.
+ */
+export declare function addLocation(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['addLocation']>[0]): ReturnType<IDeviceManagerProvider['addLocation']>;
+/**
+ * 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.
+ */
+export declare function removeLocation(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['removeLocation']>[0]): ReturnType<IDeviceManagerProvider['removeLocation']>;
+export {};

package/dist/builtins/device-manager/device-meta-store.d.ts

@@ -0,0 +1,72 @@
+import { DependentLink, ResolvedTargetLink } from './device-link-overlay.js';
+import { AddonContext, IDeviceRegistry } from '@camstack/types';
+import { AddonStore, PersistedDeviceMeta } from './device-meta-types.js';
+/** The settings surface the meta store uses (`ctx.settings`, narrowed non-null). */
+export type DeviceManagerSettings = NonNullable<AddonContext['settings']>;
+/**
+ * Narrow view of the addon's cross-device link state the meta store mutates.
+ * The addon remains the SOLE owner of these maps; the store only reads
+ * `devicesWithLinks` and writes the rebuilt indexes back via `setLinkIndexes`.
+ */
+export interface LinkIndexHost {
+    readonly devicesWithLinks: ReadonlySet<number>;
+    setLinkIndexes(targets: Map<string, ResolvedTargetLink[]>, dependents: Map<string, DependentLink[]>, expectedSourceStableIds: Set<string>): void;
+}
+export declare class DeviceMetaStore {
+    private readonly settings;
+    /** Hub-process device registry (null when this node owns no registry). */
+    readonly registry: IDeviceRegistry | null;
+    private readonly linkHost;
+    /** Synchronous ownership cache, keyed by NUMERIC deviceId → owning addonId.
+     *  The persisted meta store is authoritative but reads are async; hub-side
+     *  callers (e.g. `CapabilityRegistry.getNativeProvider` fallback) need
+     *  ownership without awaiting. Kept in sync with every register/remove and
+     *  warmed from persistence on boot. */
+    readonly idToAddonId: Map<number, string>;
+    /** Serialises every read-modify-write of the deviceMeta / deviceIndex blob
+     *  through one promise chain (see `withMetaWriteLock`). Per-instance state —
+     *  identical to the former `onInitialize` closure variable. */
+    private metaWriteChain;
+    constructor(settings: DeviceManagerSettings, 
+    /** Hub-process device registry (null when this node owns no registry). */
+    registry: IDeviceRegistry | null, linkHost: LinkIndexHost);
+    readStore: () => Promise<AddonStore>;
+    readIndex: () => Promise<Record<string, string[]>>;
+    readMeta: () => Promise<Record<string, PersistedDeviceMeta>>;
+    /** 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. */
+    readMetadataMap: () => Promise<Record<string, Record<string, unknown>>>;
+    withMetaWriteLock: <T>(fn: () => Promise<T>) => Promise<T>;
+    /**
+     * 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.
+     */
+    resolvePersistedById: (deviceId: number) => Promise<{
+        addonId: string;
+        stableId: string;
+        meta: PersistedDeviceMeta;
+    } | null>;
+    /** Direct children of a device: the union of the live registry's children
+     *  and the persisted-meta scan (`parentDeviceId === parentId`), deduplicated
+     *  and excluding self. Shared by the `remove` cascade and the `resetToSource`
+     *  resync purge (#19). */
+    directChildIds: (parentId: number) => Promise<readonly number[]>;
+    /** 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. */
+    resolveSourceDeviceId: (parentStableId: string, sourceKey: string, meta: Record<string, PersistedDeviceMeta>) => number | null;
+    allocateNextDeviceId: () => Promise<number>;
+    /** 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). */
+    rebuildLinkDependents: () => Promise<void>;
+}

package/dist/builtins/device-manager/device-meta-types.d.ts

@@ -0,0 +1,169 @@
+import { ChildLayout, DeviceLinks } from '@camstack/types';
+/**
+ * Wire shape matching `z.infer<typeof SettingsSchemaWithValuesSchema>` —
+ * duplicated as a plain interface because importing the Zod schema across
+ * package boundaries confuses `tsc` when the types package pins a
+ * different `zod` minor than the core package. Keeping the shape local
+ * keeps the addon decoupled from the schema's internal type encoding.
+ */
+export interface ContributionShape {
+    tabs?: Array<{
+        id: string;
+        label: string;
+        icon: string;
+        order?: number;
+    }>;
+    sections: Array<{
+        id: string;
+        title: string;
+        description?: string;
+        style?: 'card' | 'accordion';
+        defaultCollapsed?: boolean;
+        columns?: 1 | 2 | 3 | 4;
+        tab?: string;
+        /** Where the section renders. Default 'settings' (Config tab); 'top-tab' hoists into the device-detail tab bar via DeviceDetail discovery. */
+        location?: 'settings' | 'top-tab';
+        order?: number;
+        fields: unknown[];
+    }>;
+}
+export type AggregateTabDecl = NonNullable<ContributionShape['tabs']>[number];
+export type AggregateSection = ContributionShape['sections'][number];
+/**
+ * Discriminated result from `resolveDriverConfigSchema`:
+ *   'ok'          – schema obtained; `schema` field is present.
+ *   'none'        – driver has no settings schema (legitimate empty).
+ *   'unavailable' – cross-process call failed after retries (transient).
+ */
+export type DriverConfigSchemaResult = {
+    status: 'ok';
+    schema: ContributionShape;
+} | {
+    status: 'none';
+} | {
+    status: 'unavailable';
+};
+export interface DeviceBindingsStore {
+    readonly deviceBindings: Record<string, Record<string, {
+        wrapperAddonId: string | null;
+    }>>;
+}
+export interface PersistedDeviceMeta {
+    type: string;
+    name: string;
+    /** The owning addon's own identifier for this device (`stableId`) and the
+     *  owning addon id (`addonId`). Both are now stored as FIELDS on the record
+     *  because the `deviceMeta` map is keyed by the numeric device `id` (not the
+     *  former composite `${addonId}:${stableId}` key). They make each row
+     *  self-describing — meta lookups resolve `(addonId, stableId)` directly from
+     *  the record instead of parsing a composite key. */
+    addonId: string;
+    stableId: string;
+    /** True once an operator explicitly renamed the device via `setName` (#17).
+     *  Drives the `registerDevice` reconcile name-precedence: when set, the
+     *  operator's name is PRESERVED; when unset, the fresh provider/construction
+     *  name wins so an improved auto-name propagates instead of freezing. Absent on
+     *  legacy rows — the reconcile treats a non-placeholder name as user-named for
+     *  safety and stamps the resolved decision forward. */
+    userNamed?: boolean;
+    /**
+     * Operator-organisational label (room / area / zone). `null` when
+     * unset. Mutable through `setLocation` action; surfaced on
+     * `IDevice.location` via the kernel-built `DeviceContext.deviceMeta`
+     * snapshot. Free-text — providers don't interpret it.
+     */
+    location: string | null;
+    /**
+     * Soft-disabled flag. When `true`, the device class is still
+     * instantiated and visible in the UI (so the operator can flip
+     * back on without re-adding) but lifecycle hooks are gated by
+     * `BaseDevice.disabled`. Mutable through `setDisabled` action.
+     */
+    disabled: boolean;
+    /** Numeric parent id (or null for standalone). The hub resolves the
+     *  parent's stableId to its numeric id at registration time, and from
+     *  there everything internal references the parent by `parentDeviceId`
+     *  — `stableId` only crosses the external boundary (autodiscovery and
+     *  `(addonId, stableId)` row lookups). */
+    parentDeviceId: number | null;
+    /** Progressive, system-wide unique id. Allocated through
+     *  `allocateDeviceId` before `registerDevice` runs; backfilled at boot
+     *  for any legacy meta entry missing it (see init migration below).
+     *  Post-init invariant: every persisted device has a numeric id. */
+    id: number;
+    /** Snapshot of `device.features` from the most recent `registerDevice`
+     *  call. Used by `getDevice` when the live `IDevice` instance lives
+     *  on a forked-worker / remote agent and isn't reachable from the
+     *  hub registry. Optional for legacy rows that predate the field —
+     *  callers fall back to an empty array. */
+    features?: readonly string[];
+    /** Stable hash of the device's EXPORT-relevant shape
+     *  (`canonicalDeviceFingerprint({ deviceType, features })`). Recomputed on
+     *  every `registerDevice`; when it changes, a `DeviceProvisioned` event is
+     *  emitted so export adapters reconcile with ONE delta instead of reacting
+     *  to the chatty per-cap `DeviceBindingsChanged`. Optional for legacy rows
+     *  that predate the field. Spec:
+     *  docs/superpowers/specs/2026-06-01-alexa-hap-export-reconciler-design.md */
+    exportFingerprint?: string;
+    /** Owning integration id, stamped at create via `setIntegrationId`. Optional:
+     *  only present when the device was adopted through an integration (e.g. HA).
+     *  Used by `removeByIntegration` to cascade-delete an integration's fleet. */
+    integrationId?: string;
+    /** Linked device id, stamped at create via `setLinkDeviceId`. Optional:
+     *  only present when the device is linked to another device (e.g. HA entity
+     *  linked to a parent camera). `null` explicitly clears a previous link. */
+    linkDeviceId?: number | null;
+    /** Durable primary-child override for a CONTAINER device, set via
+     *  `setPrimaryChildEntityId`. Keyed on the chosen child's
+     *  re-sync/rename-stable `entityId` (its `sourceInfo.id`, falling back to
+     *  `stableId`) so it survives a re-sync that reallocates the child's numeric
+     *  id — unlike the numeric `linkDeviceId`. `null` clears the override. */
+    primaryChildEntityId?: string | null;
+    /** Container-level layout hint: assigns specific child/accessory devices to
+     *  named accordion sections (with optional order). Keyed on each child's
+     *  re-sync-stable accessory `stableIdSuffix`. Set at create, preserved across
+     *  re-register/restore — same lifecycle as `primaryChildEntityId`. */
+    childLayout?: ChildLayout;
+    /** Operator-authored cross-device field wirings (source field → this device's
+     *  cap field). Same create/persist/project/restore lifecycle as `childLayout`.
+     *  Absent ⇒ no links. Overlaid onto the target cap's `getStatus` at read time. */
+    deviceLinks?: DeviceLinks;
+    /** Semantic role string (`DeviceRole`), stamped at create via `setRole`.
+     *  Optional: only present for accessory children that carry a known role
+     *  (e.g. 'numeric-sensor', 'binary-sensor'). `null` clears a previous role. */
+    role?: string | null;
+}
+export interface AddonStore {
+    deviceIndex?: Record<string, string[]>;
+    /** Device meta records keyed by the numeric device `id` (`String(id)`).
+     *  `addonId` and `stableId` are FIELDS on each `PersistedDeviceMeta` record
+     *  — the map key is the numeric id, not the former composite
+     *  `${addonId}:${stableId}` string. */
+    deviceMeta?: Record<string, PersistedDeviceMeta>;
+    /** Hardware-identity metadata blob keyed by the numeric device `id`
+     *  (`String(id)`), the same primary key as `deviceMeta`.
+     *  Stored in a separate key from `deviceMeta` so the lifecycle
+     *  writers (registerDevice / setName / setLocation / setDisabled)
+     *  never need to read or preserve the metadata field — single-writer
+     *  per row eliminates the "writer X clobbers writer Y's field" bug
+     *  class. The `metadata` field on `PersistedDeviceMeta` is a legacy
+     *  fallback consulted only at read time during the lazy migration —
+     *  new writes always go to `deviceMetadata`. */
+    deviceMetadata?: Record<string, Record<string, unknown>>;
+    /** Monotonic counter that feeds `PersistedDeviceMeta.id` for every
+     *  new device. Incremented exactly once per registerDevice; never
+     *  decremented. */
+    nextDeviceId?: number;
+    /**
+     * Operator-curated location registry. Each entry is a free-form room/
+     * area label (e.g. "Cucina", "Garage") that drives the
+     * autocomplete in the Device Info location editor. Devices reference
+     * these as plain strings via `PersistedDeviceMeta.location` — the
+     * registry is purely a suggestion list, NOT a foreign key. Removing a
+     * location from the registry leaves devices that still reference it
+     * intact; `listLocations` returns the union of registered labels +
+     * labels currently in use, so nothing disappears from the UI even if
+     * the operator forgot to register a label before assigning it.
+     */
+    locations?: readonly string[];
+}

package/dist/builtins/device-manager/device-projection.d.ts

@@ -0,0 +1,74 @@
+import { DeviceFeature, DeviceRole, IDevice, ICameraDevice, IDeviceRegistry, SourceInfo } from '@camstack/types';
+import { PersistedDeviceMeta } from './device-meta-types.js';
+/**
+ * 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.
+ */
+export declare function isTransientMoleculerError(err: unknown): boolean;
+export declare function shallowEqual(a: Record<string, unknown>, b: Record<string, unknown>): boolean;
+/** Returns true when `x` is a non-null, non-array plain object. */
+export declare function isRecord(x: unknown): x is Record<string, unknown>;
+export declare function isCameraDevice(device: IDevice): device is ICameraDevice;
+/**
+ * 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.
+ */
+export declare function persistedFeatures(features: readonly string[] | undefined): DeviceFeature[];
+/**
+ * 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.
+ */
+export declare function buildSourceInfoFromConfig(persistedConfig: Record<string, unknown>, stableId: string, addonId: string): SourceInfo | undefined;
+/** Type guard: a string is a known `DeviceRole` enum member. */
+export declare function isDeviceRole(value: string): value is DeviceRole;
+/** 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. */
+export declare function toDeviceRole(value: string | null | undefined): DeviceRole | null;
+export declare function toDeviceInfo(addonId: string, device: IDevice, metadata?: Record<string, unknown> | null, metaRow?: PersistedDeviceMeta | null): {
+    deviceLinks?: import('@camstack/types').DeviceLinks | undefined;
+    childLayout?: import('@camstack/types').ChildLayout | undefined;
+    primaryChildEntityId?: string | null | undefined;
+    linkDeviceId?: number | null | undefined;
+    integrationId?: string | undefined;
+    id: number;
+    stableId: string;
+    addonId: string;
+    type: import('@camstack/types').DeviceType;
+    name: string;
+    location: string | null;
+    disabled: boolean;
+    parentDeviceId: number | null;
+    role: DeviceRole | null;
+    online: boolean;
+    probed: boolean;
+    features: DeviceFeature[];
+    isCamera: boolean;
+    config: Record<string, unknown>;
+    metadata: Record<string, unknown> | null;
+};
+export declare function resolveDeviceById(registry: IDeviceRegistry, deviceId: number): {
+    addonId: string;
+    device: IDevice;
+} | null;

package/dist/builtins/device-manager/device-provider-context.d.ts

@@ -0,0 +1,65 @@
+import { AddonContext, IDeviceAdoptionProvider, IDeviceManagerProvider, IDeviceOpsProvider, IDeviceRegistry, ICapabilityRegistry, InferProvider, deviceProviderCapability } from '@camstack/types';
+import { DeviceManagerSettings, DeviceMetaStore } from './device-meta-store.js';
+import { BindingsDeps } from './device-bindings-store.js';
+type IDeviceProviderCap = InferProvider<typeof deviceProviderCapability>;
+/**
+ * The addon-instance surface the extracted provider functions need. Exposed by
+ * the addon as a host object so the functions never capture `this` directly and
+ * the addon stays the sole owner of its private state.
+ */
+export interface ProviderHost {
+    readonly ctx: AddonContext;
+    readonly capabilityRegistry: ICapabilityRegistry | undefined;
+    /** Device ids that currently carry at least one `deviceLinks` entry. */
+    readonly devicesWithLinks: Set<number>;
+    /** Expected link-source stableIds, gating the `registerDevice` rebuild. */
+    readonly expectedSourceStableIds: Set<string>;
+    /** Drop a removed device's overlay-emit guard entries (state-mirror keyed
+     *  `${deviceId}:${cap}`). Called from `removeDevice`. */
+    dropDeviceOverlays(deviceId: number): void;
+    /** Push-fed remote native-cap cache (numeric deviceId → capName → owner). */
+    readonly remoteNativeCaps: Map<number, Map<string, {
+        addonId: string;
+        nodeId: string;
+    }>>;
+    /** Seed the runtime-state mirror for a device (boot path, no events). */
+    seedMirror(deviceId: number, blob: Record<string, unknown>): void;
+    /** Reset a stale per-session `feature-probe` timestamp before mirror seeding. */
+    withResetSessionProbe(blob: Record<string, unknown>): Record<string, unknown>;
+    /** Resolve a device's real `online` flag from the mirrored device-status slice. */
+    resolveDeviceOnline(deviceId: number, fallbackOnline: boolean): boolean;
+    /** Resolve a device's `probed` flag from the mirrored feature-probe slice. */
+    resolveDeviceProbed(deviceId: number): boolean;
+    /** Wait for a device-provider by addonId, returning null on timeout. */
+    waitDeviceProvider(addonId: string, timeoutMs?: number): Promise<IDeviceProviderCap | null>;
+    /** Require a device-provider by addonId — throws if not found. */
+    requireDeviceProvider(addonId: string): Promise<IDeviceProviderCap>;
+    /** Require a device-adoption provider by addonId — throws if not found. */
+    requireDeviceAdoptionProvider(addonId: string): Promise<IDeviceAdoptionProvider>;
+}
+/**
+ * Full context the provider-method modules consume. `provider` is a lazy getter
+ * for the assembled `IDeviceManagerProvider` so the few methods that self-call
+ * sibling cap methods (e.g. `remove` → `removeDevice`, `removeByIntegration` →
+ * `remove`, `enable`/`disable` → `setDisabled`) resolve the live implementation
+ * without a capture cycle at construction time.
+ */
+export interface ProviderContext {
+    readonly host: ProviderHost;
+    readonly metaStore: DeviceMetaStore;
+    readonly settings: DeviceManagerSettings;
+    /** Hub-process device registry (null when this node owns no registry). */
+    readonly registry: IDeviceRegistry | null;
+    readonly bindingsDeps: BindingsDeps;
+    /** Resolve the per-device `device-ops` native provider (throws when absent). */
+    requireDeviceOps(deviceId: number): IDeviceOpsProvider;
+    /** Stamp an integration id onto a device's meta row + emit DeviceMetaChanged. */
+    stampIntegrationId(deviceId: number, integrationId: string): Promise<void>;
+    /** The assembled `IDeviceManagerProvider`, resolved lazily so the few methods
+     *  that self-call sibling cap methods (`remove` → `removeDevice`,
+     *  `removeByIntegration` → `remove`, `enable`/`disable` → `setDisabled`,
+     *  `probeStreams`/`getStreamProfileMap` → `getStreamSources`) reach the live
+     *  implementation without a construction-time capture cycle. */
+    readonly provider: IDeviceManagerProvider;
+}
+export {};

package/dist/builtins/device-manager/device-queries.d.ts

@@ -0,0 +1,38 @@
+import { InferProvider, deviceManagerCapability } from '@camstack/types';
+import { ProviderContext } from './device-provider-context.js';
+type IDeviceManagerProvider = InferProvider<typeof deviceManagerCapability>;
+export declare function listPersistedByAddon(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['listPersistedByAddon']>[0]): ReturnType<IDeviceManagerProvider['listPersistedByAddon']>;
+export declare function listAll(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['listAll']>[0]): ReturnType<IDeviceManagerProvider['listAll']>;
+export declare function getDevice(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['getDevice']>[0]): ReturnType<IDeviceManagerProvider['getDevice']>;
+export declare function getChildren(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['getChildren']>[0]): ReturnType<IDeviceManagerProvider['getChildren']>;
+export declare function getStreamSources(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['getStreamSources']>[0]): ReturnType<IDeviceManagerProvider['getStreamSources']>;
+export declare function getConfigSchema(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['getConfigSchema']>[0]): ReturnType<IDeviceManagerProvider['getConfigSchema']>;
+export declare function getSettingsSchema(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['getSettingsSchema']>[0]): ReturnType<IDeviceManagerProvider['getSettingsSchema']>;
+export declare function updateConfig(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['updateConfig']>[0]): ReturnType<IDeviceManagerProvider['updateConfig']>;
+export declare function enable(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['enable']>[0]): ReturnType<IDeviceManagerProvider['enable']>;
+export declare function disable(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['disable']>[0]): ReturnType<IDeviceManagerProvider['disable']>;
+export declare function remove(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['remove']>[0]): ReturnType<IDeviceManagerProvider['remove']>;
+/**
+ * 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.
+ */
+export declare function removeByIntegration(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['removeByIntegration']>[0]): ReturnType<IDeviceManagerProvider['removeByIntegration']>;
+export declare function getStreamProfileMap(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['getStreamProfileMap']>[0]): ReturnType<IDeviceManagerProvider['getStreamProfileMap']>;
+export declare function setStreamProfileMap(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['setStreamProfileMap']>[0]): ReturnType<IDeviceManagerProvider['setStreamProfileMap']>;
+export declare function probeStreams(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['probeStreams']>[0]): ReturnType<IDeviceManagerProvider['probeStreams']>;
+export declare function discoverDevices(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['discoverDevices']>[0]): ReturnType<IDeviceManagerProvider['discoverDevices']>;
+export declare function adoptDevice(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['adoptDevice']>[0]): ReturnType<IDeviceManagerProvider['adoptDevice']>;
+export declare function getCreationSchema(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['getCreationSchema']>[0]): ReturnType<IDeviceManagerProvider['getCreationSchema']>;
+export declare function createDevice(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['createDevice']>[0]): ReturnType<IDeviceManagerProvider['createDevice']>;
+export declare function testCreationField(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['testCreationField']>[0]): ReturnType<IDeviceManagerProvider['testCreationField']>;
+export declare function adoptionListCandidates(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['adoptionListCandidates']>[0]): ReturnType<IDeviceManagerProvider['adoptionListCandidates']>;
+export declare function adoptionRefresh(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['adoptionRefresh']>[0]): ReturnType<IDeviceManagerProvider['adoptionRefresh']>;
+export declare function adoptionAdopt(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['adoptionAdopt']>[0]): ReturnType<IDeviceManagerProvider['adoptionAdopt']>;
+export declare function adoptionRelease(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['adoptionRelease']>[0]): ReturnType<IDeviceManagerProvider['adoptionRelease']>;
+export declare function adoptionResync(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['adoptionResync']>[0]): ReturnType<IDeviceManagerProvider['adoptionResync']>;
+export declare function testField(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['testField']>[0]): ReturnType<IDeviceManagerProvider['testField']>;
+export {};