@camstack/system 1.2.390 → 1.2.391

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

@@ -1,201 +1,227 @@
-import { DeviceBindingEntry, BaseAddon, ProviderRegistration } from '@camstack/types';
-import { mergeAggregates } from './device-aggregation-merge.js';
-import { ListDeviceIdsByCapsInput } from './device-bindings-store.js';
-import { ContributionShape } from './device-meta-types.js';
+/**
+* Device Manager addon — hub-side singleton that unifies device persistence,
+* live registry queries, and all management operations into a single
+* tRPC-routable capability.
+*
+* Persistence strategy: all device data is stored via `ctx.settings`, the same
+* settings API every other addon uses. No raw SQLite access.
+*
+*   Addon store layout:
+*     deviceIndex  → Record<addonId, stableId[]>          (which devices exist per addon)
+*     deviceMeta   → Record<numericId, DeviceMeta>        (keyed by numeric device id;
+*                                                          addonId + stableId are FIELDS on the record)
+*
+*   Device store (per-device config):
+*     readDeviceStore(numericDeviceId)  → config blob
+*     writeDeviceStore(numericDeviceId, patch)
+*
+* Live registry: resolved from the kernel capability registry after Phase 2.
+* This gives direct access to in-memory IDevice instances registered by provider addons.
+* The DeviceManagerAddon is the single owner of the live device operations API.
+*
+* Replaces:
+*   - `device-persistence` capability (absorbed here)
+*   - live operations previously served by `device-management.router.ts`
+*/
+import type { DeviceBindingEntry } from "@camstack/types";
+import { BaseAddon, ProviderRegistration } from "@camstack/types";
+import { mergeAggregates } from "./device-aggregation-merge.js";
+import { type ListDeviceIdsByCapsInput } from "./device-bindings-store.js";
+import type { ContributionShape } from "./device-meta-types.js";
 export { mergeAggregates };
 export declare class DeviceManagerAddon extends BaseAddon {
-    constructor();
-    /** Shorthand for the kernel-injected capability registry. */
-    private get 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`.
-     */
-    private propagator;
-    /**
-     * 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.
-     *
-     * The mirror + its debounced disk-writer + the cross-device link overlay
-     * live in `DeviceStateMirror`. Constructed once in `onInitialize` (needs
-     * `ctx`); `null` before initialise / when `ctx.settings` is absent.
-     */
-    private stateMirrorImpl;
-    /**
-     * Removes the claimed-status overlay this addon installed on the capability
-     * registry (D663, S3): `getStatus` of a claimed cap answers the mirror for
-     * every caller while it is installed. Run in `onShutdown`; `null` before
-     * init or when the kernel handed the addon no registry.
-     */
-    private uninstallStatusOverlay;
-    /**
-     * Cross-process native-provider cache: deviceId (numeric) → capName → { addonId, nodeId }.
-     * Kept in sync with `DeviceBindingsChanged` push events emitted by forked
-     * workers on `ctx.registerNativeCap` / device removal. Union'd into
-     * `getBindings` so hub-side consumers see every native cap regardless of
-     * which process owns the IDevice.
-     *
-     * No persistence — entries re-populate when the worker re-handshakes or
-     * re-emits its native-cap registrations after restart. Entries that were
-     * lost in the Moleculer transport handshake window are recovered lazily:
-     * `resolveNativeCapOwnerSync` and `getBindings` fall through to
-     * `ctx.kernel.listClusterNativeCaps()` (the handshake-fed
-     * `HubNodeRegistry`) when the push-based cache misses.
-     *
-     * The previous pull-based recovery (`syncWorkerNativeCaps`, driven by
-     * `$node.connected` + `addon.restarted`) has been removed in Task 13 —
-     * the D3 re-handshake after device restore is the reliable replacement.
-     */
-    private remoteNativeCaps;
-    /** Background adoption jobs — lazily constructed (needs `ctx.logger`). */
-    private adoptionJobEngine;
-    /**
-     * ONE removal fence for this process, shared by the provider context and the
-     * adoption-job engine.
-     *
-     * It used to be constructed inline into the context, so the job engine had
-     * no way to reach it and an operator re-adopting hardware they had just
-     * deleted was refused for the whole 5-minute TTL — their own action, denied.
-     * Two fences would be worse than one: the engine would suspend a fence that
-     * `allocateDeviceId` never consults.
-     */
-    private readonly removalFence;
-    /** Declared secret config paths per device, as last registered (D783). */
-    private readonly secretConfigPaths;
-    /** The keychain side of driver device forms (D789), wired in onInitialize. */
-    private deviceFormSecrets;
-    /** The runtime-state mirror, asserted present (constructed in onInitialize). */
-    private get stateMirror();
-    /**
-     * The per-field claims index (D663): which devices carry a claim, for the
-     * seed and for `listClaims`. Constructed at init and loaded before the first
-     * provider method can run; a load that fails leaves it `not-loaded`, and
-     * every seed reads its row until a later call loads it.
-     */
-    private fieldClaimsImpl;
-    /** The claims index, asserted present (constructed in onInitialize). */
-    private get fieldClaims();
-    /** Build the `ProviderHost` the extracted provider-method modules
-     *  (`device-meta-actions`, `device-queries`) reach — exposes the addon's
-     *  private state/methods they need without leaking the class internals.
-     *
-     *  `remoteNativeCaps` is mutated in place (never reassigned) so a direct
-     *  reference preserves the live semantics. */
-    private get providerHost();
-    /**
-     * Background adoption jobs. In-RAM and process-lifetime: a restart forgets
-     * them, which is safe because adoption is keyed by a stable id — re-running a
-     * job re-adopts nothing (see `AdoptionJobEngine`).
-     */
-    private get adoptionJobsImpl();
-    /** Wait for a device-provider by addonId, returning null on timeout. */
-    private waitDeviceProvider;
-    /** Require a device-provider by addonId — throws if not found. */
-    private requireDeviceProvider;
-    /** Require a device-adoption provider by addonId — throws if not found. */
-    private requireDeviceAdoptionProvider;
-    /** Addon ids that currently register a `device-provider`. */
-    private listDeviceProviderIds;
-    /** "provider-gree" → "Gree" — a human label for the discovery modal. */
-    private discoveryProviderLabel;
-    /** Provider ids that report `supportsDiscovery() === true` (probed in parallel). */
-    private listDiscoveryCapableProviderIds;
-    /**
-     * Row access for `device-manager:devices`. Built once in `onInitialize`
-     * (which is also where the collection is declared) — every consumer reaches
-     * it through {@link bindingsDeps} or the `ProviderContext`.
-     */
-    private deviceRows;
-    /**
-     * The ONE lock ordering every read-modify-write of this addon's
-     * `addon-settings` key range (`deviceBindings`, `locations`, `nextDeviceId`,
-     * `roleDisplayDefaults`).
-     *
-     * It lives on the addon rather than on `DeviceMetaStore` because the writers
-     * do not all go through that class — `setWrapperActive` and `removeDevice`'s
-     * bindings purge reach the store through `BindingsDeps` — and two locks over
-     * one key range is the same defect one level up. Handed to both.
-     */
-    private readonly addonStoreWriteLock;
-    /** Stored activations of RETIRED wrappers, said once per process (task 17 review M1). */
-    private staleWrapperActivationsImpl;
-    private get staleWrapperActivations();
-    /** Build the dependency context the extracted binding resolvers consume. */
-    private get bindingsDeps();
-    getBindings(input: {
-        deviceId: number;
-    }): Promise<{
-        deviceId: number;
-        entries: DeviceBindingEntry[];
-    }>;
-    getBindingsBatch(input: {
-        deviceIds: readonly number[];
-    }): Promise<Array<{
-        deviceId: number;
-        entries: DeviceBindingEntry[];
-    }>>;
-    getAllBindings(): Promise<Array<{
-        deviceId: number;
-        entries: DeviceBindingEntry[];
-    }>>;
-    listDeviceIdsByCaps(input: ListDeviceIdsByCapsInput): Promise<number[]>;
-    /** Build the dependency context the extracted aggregation functions consume. */
-    private get aggregationDeps();
-    getDeviceAggregate(deviceId: number, kind: 'settings' | 'live'): Promise<ContributionShape | null>;
-    private getDeviceStatusAggregate;
-    updateDeviceField(input: {
-        deviceId: number;
-        writerCapName: string;
-        writerAddonId: string;
-        key: string;
-        value: unknown;
-    }): Promise<{
-        success: true;
-    }>;
-    updateDeviceFieldsBatch(input: {
-        deviceId: number;
-        changes: ReadonlyArray<{
-            writerCapName: string;
-            writerAddonId: string;
-            key: string;
-            value: unknown;
-        }>;
-    }): Promise<{
-        success: true;
-        failures: {
-            writerCapName: string;
-            writerAddonId: string;
-            error: string;
-        }[];
-    }>;
-    private dispatchDeviceAction;
-    listWrappersForCap(input: {
-        capName: string;
-    }): Promise<string[]>;
-    listBindableCapsForDeviceType(input: {
-        deviceType: string;
-    }): Promise<Array<{
-        capName: string;
-        wrappers: string[];
-    }>>;
-    setWrapperActive(input: {
-        deviceId: number;
-        capName: string;
-        wrapperAddonId: string;
-        active: boolean;
-    }): Promise<void>;
-    /** The narrow dependency bag the activation verb needs (D556). */
-    private get wrapperActivationDeps();
-    protected onInitialize(): Promise<ProviderRegistration[] | void>;
-    protected onShutdown(): Promise<void>;
+	constructor();
+	/** Shorthand for the kernel-injected capability registry. */
+	private get 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`.
+	*/
+	private propagator;
+	/**
+	* 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.
+	*
+	* The mirror + its debounced disk-writer + the cross-device link overlay
+	* live in `DeviceStateMirror`. Constructed once in `onInitialize` (needs
+	* `ctx`); `null` before initialise / when `ctx.settings` is absent.
+	*/
+	private stateMirrorImpl;
+	/**
+	* Removes the claimed-status overlay this addon installed on the capability
+	* registry (D663, S3): `getStatus` of a claimed cap answers the mirror for
+	* every caller while it is installed. Run in `onShutdown`; `null` before
+	* init or when the kernel handed the addon no registry.
+	*/
+	private uninstallStatusOverlay;
+	/**
+	* Cross-process native-provider cache: deviceId (numeric) → capName → { addonId, nodeId }.
+	* Kept in sync with `DeviceBindingsChanged` push events emitted by forked
+	* workers on `ctx.registerNativeCap` / device removal. Union'd into
+	* `getBindings` so hub-side consumers see every native cap regardless of
+	* which process owns the IDevice.
+	*
+	* No persistence — entries re-populate when the worker re-handshakes or
+	* re-emits its native-cap registrations after restart. Entries that were
+	* lost in the Moleculer transport handshake window are recovered lazily:
+	* `resolveNativeCapOwnerSync` and `getBindings` fall through to
+	* `ctx.kernel.listClusterNativeCaps()` (the handshake-fed
+	* `HubNodeRegistry`) when the push-based cache misses.
+	*
+	* The previous pull-based recovery (`syncWorkerNativeCaps`, driven by
+	* `$node.connected` + `addon.restarted`) has been removed in Task 13 —
+	* the D3 re-handshake after device restore is the reliable replacement.
+	*/
+	private remoteNativeCaps;
+	/** Background adoption jobs — lazily constructed (needs `ctx.logger`). */
+	private adoptionJobEngine;
+	/**
+	* ONE removal fence for this process, shared by the provider context and the
+	* adoption-job engine.
+	*
+	* It used to be constructed inline into the context, so the job engine had
+	* no way to reach it and an operator re-adopting hardware they had just
+	* deleted was refused for the whole 5-minute TTL — their own action, denied.
+	* Two fences would be worse than one: the engine would suspend a fence that
+	* `allocateDeviceId` never consults.
+	*/
+	private readonly removalFence;
+	/** Declared secret config paths per device, as last registered (D783). */
+	private readonly secretConfigPaths;
+	/** The keychain side of driver device forms (D789), wired in onInitialize. */
+	private deviceFormSecrets;
+	/** The runtime-state mirror, asserted present (constructed in onInitialize). */
+	private get stateMirror();
+	/**
+	* The per-field claims index (D663): which devices carry a claim, for the
+	* seed and for `listClaims`. Constructed at init and loaded before the first
+	* provider method can run; a load that fails leaves it `not-loaded`, and
+	* every seed reads its row until a later call loads it.
+	*/
+	private fieldClaimsImpl;
+	/** The claims index, asserted present (constructed in onInitialize). */
+	private get fieldClaims();
+	/** Build the `ProviderHost` the extracted provider-method modules
+	*  (`device-meta-actions`, `device-queries`) reach — exposes the addon's
+	*  private state/methods they need without leaking the class internals.
+	*
+	*  `remoteNativeCaps` is mutated in place (never reassigned) so a direct
+	*  reference preserves the live semantics. */
+	private get providerHost();
+	/**
+	* Background adoption jobs. In-RAM and process-lifetime: a restart forgets
+	* them, which is safe because adoption is keyed by a stable id — re-running a
+	* job re-adopts nothing (see `AdoptionJobEngine`).
+	*/
+	private get adoptionJobsImpl();
+	/** Wait for a device-provider by addonId, returning null on timeout. */
+	private waitDeviceProvider;
+	/** Require a device-provider by addonId — throws if not found. */
+	private requireDeviceProvider;
+	/** Require a device-adoption provider by addonId — throws if not found. */
+	private requireDeviceAdoptionProvider;
+	/** Addon ids that currently register a `device-provider`. */
+	private listDeviceProviderIds;
+	/** "provider-gree" → "Gree" — a human label for the discovery modal. */
+	private discoveryProviderLabel;
+	/** Provider ids that report `supportsDiscovery() === true` (probed in parallel). */
+	private listDiscoveryCapableProviderIds;
+	/**
+	* Row access for `device-manager:devices`. Built once in `onInitialize`
+	* (which is also where the collection is declared) — every consumer reaches
+	* it through {@link bindingsDeps} or the `ProviderContext`.
+	*/
+	private deviceRows;
+	/**
+	* The ONE lock ordering every read-modify-write of this addon's
+	* `addon-settings` key range (`deviceBindings`, `locations`, `nextDeviceId`,
+	* `roleDisplayDefaults`).
+	*
+	* It lives on the addon rather than on `DeviceMetaStore` because the writers
+	* do not all go through that class — `setWrapperActive` and `removeDevice`'s
+	* bindings purge reach the store through `BindingsDeps` — and two locks over
+	* one key range is the same defect one level up. Handed to both.
+	*/
+	private readonly addonStoreWriteLock;
+	/** Stored activations of RETIRED wrappers, said once per process (task 17 review M1). */
+	private staleWrapperActivationsImpl;
+	private get staleWrapperActivations();
+	/** Build the dependency context the extracted binding resolvers consume. */
+	private get bindingsDeps();
+	getBindings(input: {
+		deviceId: number;
+	}): Promise<{
+		deviceId: number;
+		entries: DeviceBindingEntry[];
+	}>;
+	getBindingsBatch(input: {
+		deviceIds: readonly number[];
+	}): Promise<Array<{
+		deviceId: number;
+		entries: DeviceBindingEntry[];
+	}>>;
+	getAllBindings(): Promise<Array<{
+		deviceId: number;
+		entries: DeviceBindingEntry[];
+	}>>;
+	listDeviceIdsByCaps(input: ListDeviceIdsByCapsInput): Promise<number[]>;
+	/** Build the dependency context the extracted aggregation functions consume. */
+	private get aggregationDeps();
+	getDeviceAggregate(deviceId: number, kind: "settings" | "live"): Promise<ContributionShape | null>;
+	private getDeviceStatusAggregate;
+	updateDeviceField(input: {
+		deviceId: number;
+		writerCapName: string;
+		writerAddonId: string;
+		key: string;
+		value: unknown;
+	}): Promise<{
+		success: true;
+	}>;
+	updateDeviceFieldsBatch(input: {
+		deviceId: number;
+		changes: ReadonlyArray<{
+			writerCapName: string;
+			writerAddonId: string;
+			key: string;
+			value: unknown;
+		}>;
+	}): Promise<{
+		success: true;
+		failures: {
+			writerCapName: string;
+			writerAddonId: string;
+			error: string;
+		}[];
+	}>;
+	private dispatchDeviceAction;
+	listWrappersForCap(input: {
+		capName: string;
+	}): Promise<string[]>;
+	listBindableCapsForDeviceType(input: {
+		deviceType: string;
+	}): Promise<Array<{
+		capName: string;
+		wrappers: string[];
+	}>>;
+	setWrapperActive(input: {
+		deviceId: number;
+		capName: string;
+		wrapperAddonId: string;
+		active: boolean;
+	}): Promise<void>;
+	/** The narrow dependency bag the activation verb needs (D556). */
+	private get wrapperActivationDeps();
+	protected onInitialize(): Promise<ProviderRegistration[] | void>;
+	protected onShutdown(): Promise<void>;
 }
 export default DeviceManagerAddon;