@camstack/system 1.0.2

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

@@ -0,0 +1,452 @@
+import { ProviderRegistration, BaseAddon, DeviceBindingEntry } 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.
+ */
+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 declare function mergeAggregates(parts: readonly ContributionShape[]): ContributionShape;
+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 —
+     * slices show up as `setCapSlice` calls trickle in.
+     */
+    private readonly stateMirror;
+    /**
+     * 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.
+     */
+    private readonly runtimeStateDebounce;
+    private static readonly RUNTIME_STATE_DEBOUNCE_MS;
+    /**
+     * 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;
+    /** Device ids that currently have at least one `deviceLinks` entry. O(1) gate
+     *  consulted by `resolveLinkedStatus` so the cap-mount overlay is a no-op for
+     *  the vast majority of devices that have no links. Rebuilt on restore. */
+    private readonly devicesWithLinks;
+    /** Whether a device currently has cross-device links. */
+    devicesWithLinksHas(deviceId: number): boolean;
+    /** `${targetDeviceId}:${targetCap}` → resolved links feeding that cap's slice. */
+    private linkTargets;
+    /** `${sourceDeviceId}:${sourceCap}` → targets to recompute when that source changes. */
+    private linkDependents;
+    /** Loop/churn guard: last overlaid slice emitted per `${deviceId}:${cap}`. */
+    private readonly lastEmittedOverlay;
+    /** Expected source `stableId`s (`${container}-${sourceKey}`) across all links,
+     *  resolved or not — gates the `registerDevice` rebuild so only a registering
+     *  device that IS a link source triggers a reindex (not every boot restore). */
+    private expectedSourceStableIds;
+    /** Test/diagnostic accessors. */
+    linkTargetKeys(): string[];
+    linkDependentsKeys(): string[];
+    /** 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;
+    private readBindingsStore;
+    private writeBindingsStore;
+    private resolveWrapperNodeId;
+    /**
+     * Reduce a provider node id to the routable form `DeviceProxy` can pin.
+     *
+     * Every addon runs in its own `addon-runner` with the composite node id
+     * `${parentNodeId}/${runnerId}` (see `addon-runner.ts`) — e.g.
+     * `hub/provider-reolink` or `dev-agent-0/provider-reolink`. That composite is
+     * an IDENTITY, not a routable target: the `CapRouteResolver` reaches a child
+     * only THROUGH its parent (the hub resolves a hub-local-uds child by
+     * cap+device; an agent forwards to its own child). `DeviceProxy` pins
+     * `entry.providerNodeId` on every cap call, so a binding entry must expose the
+     * parent node id — otherwise the explicit pin classifies as `remote-moleculer`
+     * to an unknown node → `no-provider`, which surfaces as
+     * "this camera doesn't expose …" for client-proxy-driven widget caps
+     * (motion-zones, privacy-mask). Wrappers already report the parent via
+     * `resolveWrapperNodeId`; this aligns natives with the same contract.
+     *
+     * A flat node id (a genuine standalone node with no `/`) is returned
+     * unchanged.
+     */
+    private toRoutableProviderNodeId;
+    /**
+     * Resolve a remote native cap entry for a given `(capName, deviceId)` by
+     * consulting the handshake-fed `HubNodeRegistry` via
+     * `ctx.kernel.listClusterNativeCaps()`. Called when the push-based
+     * `remoteNativeCaps` cache misses — covers the Moleculer transport
+     * handshake window where `DeviceBindingsChanged` events were lost but the
+     * D3 re-handshake (post device restore) has already populated the registry.
+     *
+     * Returns `null` when the entry is genuinely not present in the cluster
+     * view (cap not registered on any worker for that device).
+     */
+    private resolveRemoteNativeCapFromRegistry;
+    getBindings(input: {
+        deviceId: number;
+    }): Promise<{
+        deviceId: number;
+        entries: DeviceBindingEntry[];
+    }>;
+    /**
+     * 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.
+     */
+    getAllBindings(): Promise<Array<{
+        deviceId: number;
+        entries: DeviceBindingEntry[];
+    }>>;
+    /**
+     * 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.
+     */
+    private lookupPersistedStableId;
+    getDeviceAggregate(deviceId: number, kind: 'settings' | 'live'): Promise<ContributionShape | null>;
+    /**
+     * System-scoped per-device contributions — the deliberate exception to
+     * binding-driven aggregation (D12).
+     *
+     * A `scope: 'system'` cap with `exposesDeviceSettings: true` holds per-device
+     * state but is NOT bound per-device: it is a system addon, not a BaseDevice,
+     * so it never calls `registerNativeCap` and never appears in
+     * `getBindings(deviceId)`. The binding-driven loop therefore skips it and its
+     * per-device panel never renders. Two such caps ship today:
+     *   - `stream-broker` (singleton) — the RTSP-restream / pre-buffer settings
+     *     tab, scoped to the cameras whose streams it serves.
+     *   - `device-export` (collection) — the "Export" panel; a device can be
+     *     exposed to MULTIPLE exporters at once (Alexa + HomeKit + HA-MQTT).
+     *
+     * D12 bans fanning a per-device call out to every same-named provider of a
+     * `scope: 'device'` cap, because vendor providers SHARE cap names
+     * (`stream-params`/`ptz` from reolink AND hikvision). System caps are NOT
+     * vendor-shared — a system cap name maps to one active provider (singleton)
+     * or one declared collection — so consulting the cap's own provider(s)
+     * directly is safe. Each provider gates internally by deviceId and returns
+     * null for devices it does not own.
+     *
+     * `seenCaps` skips any system cap that already contributed via a binding so
+     * its section is never duplicated.
+     */
+    private collectSystemDeviceContributions;
+    /**
+     * D14: framework-derived device-config contribution.
+     *
+     * `kind === 'live'` — device-config caps contribute nothing to the live
+     * aggregate (they hold editable config, not live observables).
+     *
+     * `ui.kind === 'widget'` — emits a single structural `type:'widget'`
+     * section; the widget self-persists via the cap's own mutations.
+     *
+     * `ui.kind === 'derived-form'` — calls `getOptions`/`getStatus` on the
+     * bound provider, runs the registered pure builder, and returns the
+     * derived form sections. Returns null when the camera exposes nothing
+     * configurable or the provider is not yet registered.
+     */
+    private deriveDeviceConfigContribution;
+    /**
+     * 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.
+     */
+    private buildBaseDeviceSection;
+    /**
+     * Lookup the native owner for `device-ops` on `deviceId` — the native-cap
+     * registry (hub-local and remote) is keyed by numeric id.
+     */
+    private resolveNativeDeviceOwner;
+    /**
+     * 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`.
+     */
+    private getDeviceStatusAggregate;
+    /**
+     * Return the driver-specific device-settings contribution. Hub-local
+     * devices call `getSettingsUISchema()` directly; forked-worker devices
+     * go through the `device-ops.getSettingsSchema` cap method on the
+     * numeric-id-keyed native registry.
+     *
+     * Returns a discriminated result so callers can distinguish three states:
+     *   'ok'          – schema obtained successfully
+     *   'none'        – driver genuinely has no settings schema
+     *   'unavailable' – worker was unreachable after retries (transient)
+     */
+    private resolveDriverConfigSchema;
+    updateDeviceField(input: {
+        deviceId: number;
+        writerCapName: string;
+        writerAddonId: string;
+        key: string;
+        value: unknown;
+    }): Promise<{
+        success: true;
+    }>;
+    /**
+     * Dispatch a device custom action. Hub-local devices run it directly;
+     * forked/remote devices route through the `device-ops` native cap
+     * (`runAction`) — the same hub-local-then-device-ops fan-out that
+     * `updateDeviceField` uses for `applySettingsPatch`.
+     */
+    private dispatchDeviceAction;
+    /**
+     * Resolve the `DeviceSettingsContribution` provider that owns a tagged
+     * field. The `writerAddonId` on a tagged field equals `entry.providerAddonId`
+     * from the binding that produced it — for `kind:'wrapped'` entries, that is
+     * the wrapper addon id (e.g. 'snapshot-addon'); for native-only entries,
+     * the system addon id.
+     *
+     * Resolution order (Bug-3 fix):
+     *  1. `getProviderByAddon(capName, writerAddonId)` — resolves the
+     *     system-registered provider by the addon id from the tagged field.
+     *     For wrapper bindings (snapshot, motion-detection, etc.) this directly
+     *     returns the wrapper provider, bypassing the native-first resolution
+     *     order of `getProviderForDevice` that caused "method not found".
+     *  2. `getSingleton(capName)` — fallback for stale/mismatched writerAddonIds.
+     *     The active singleton handles the contribution even if the addonId
+     *     stored in the field is out of date (e.g. after an addon rename).
+     *
+     * `getProviderForDevice` is intentionally NOT used here: it returns the
+     * per-device native first when present (e.g. Reolink/ONVIF), and the native
+     * does NOT implement contribution methods — the root cause of Bug-3.
+     */
+    private resolveContributionProvider;
+    /**
+     * 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.
+     */
+    updateDeviceFieldsBatch(input: {
+        deviceId: number;
+        changes: ReadonlyArray<{
+            writerCapName: string;
+            writerAddonId: string;
+            key: string;
+            value: unknown;
+        }>;
+    }): Promise<{
+        success: true;
+        failures: {
+            writerCapName: string;
+            writerAddonId: string;
+            error: string;
+        }[];
+    }>;
+    /** Apply a single grouped patch to the appropriate provider. Mirrors
+     * `updateDeviceField` routing (special-case device-manager, else
+     * registry lookup). Used by `updateDeviceFieldsBatch`. */
+    private applyGroupPatch;
+    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>;
+    protected onInitialize(): Promise<ProviderRegistration[] | void>;
+    /**
+     * 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.
+     */
+    private applySingleCapUpdate;
+    /**
+     * 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.
+     */
+    private scheduleRuntimeStateDiskWrite;
+    /**
+     * One-shot mirror seed used by `loadRuntimeState` at boot so the
+     * hub knows about every persisted slice without waiting for the
+     * first `setCapSlice` call. No events emitted — this is
+     * initial-state population, not a transition.
+     *
+     * Callers that must not carry a stale per-session probe across a
+     * restart pass the blob through `withResetSessionProbe` first (see
+     * `loadRuntimeState`).
+     */
+    private seedMirror;
+    /**
+     * The hub mirror's `feature-probe.lastProbedAt` is a PER-SESSION liveness
+     * signal — it means "this worker process completed a probe THIS session".
+     * Persisted runtime state carries the PRE-RESTART timestamp, which is stale
+     * after a hub or worker restart: the device has not re-probed yet. Seeding it
+     * verbatim makes `resolveDeviceProbed` report `probed:true` during the
+     * restart→reprobe window, which defeats the export carry-forward gate
+     * (`resolveExportFingerprint`, gated on `device.probed`) and posts a spurious
+     * partial `AddOrUpdateReport` to Alexa/HAP before the real probe lands.
+     *
+     * Reset `lastProbedAt` to 0 for the MIRROR seed only — `probed:false` carries
+     * the last-advertised fingerprint forward until the worker republishes a
+     * fresh probe (its post-probe `setCapSlice` raises `lastProbedAt` again, which
+     * also fires `DeviceReady`). The worker's returned `initialRuntimeState` blob
+     * is untouched, and every non-probe slice (e.g. `device-status`/online) is
+     * preserved.
+     */
+    private withResetSessionProbe;
+    /**
+     * Resolve a device's REAL `online` flag for the persisted/forked-worker
+     * list branch. Forked workers own the live `IDevice` in their own process,
+     * so the hub registry can't read `device.online` directly. The owning
+     * driver instead publishes its liveness through the auto-registered
+     * `device-status` runtime-state slice (`markOnline` → `setCapState`), which
+     * the canonical `deviceState.setCapSlice` write entrypoint mirrors into the
+     * hub-side `stateMirror`. We read that mirrored slice here so the list
+     * payload reflects the device's actual reachability instead of a constant.
+     *
+     * Fallback (`fallbackOnline`) preserves the legacy behaviour when no slice
+     * has been published yet: a persisted device with a live registry is
+     * assumed online (it was successfully registered by its owning process),
+     * and the null-registry "offline view" keeps reporting offline. We never
+     * regress a device to offline merely because its mirror is empty.
+     */
+    private resolveDeviceOnline;
+    /**
+     * Derive the `probed` flag for an offline-view (forked-worker, not
+     * live in the hub registry) device projection. Reads the mirrored
+     * `feature-probe` slice the owning worker publishes. Mirrors the
+     * `toDeviceInfo` rule: no mirrored slice → ready (`true`, no probe seen);
+     * slice present → ready iff `lastProbedAt` has advanced past 0. The
+     * mirror is populated when the worker's first `setCapSlice` RPC arrives
+     * (BaseDevice seeds `feature-probe` `lastProbedAt:0` at construction, but
+     * cross-process delivery is async); until then the no-entry path returns
+     * `true` — a brief transient window, same as `resolveDeviceOnline`.
+     */
+    private resolveDeviceProbed;
+    private snapshotForDevice;
+    /**
+     * Read-time overlay of a cap slice with its cross-device linked values.
+     * Returns a cloned raw mirror slice when the (device, cap) pair has no
+     * links. Sources are read from the same in-hub stateMirror — sync, no
+     * cross-process call. The disk writer must NOT use this method; it must
+     * persist raw provider truth via snapshotForDevice.
+     */
+    private overlayedSlice;
+    /**
+     * Like snapshotForDevice but applies the device-link overlay per cap.
+     * Used exclusively by the device-state READ methods (getSnapshot,
+     * getAllSnapshots) so callers see overlayed values. The debounced disk
+     * writer must continue to call snapshotForDevice (raw truth).
+     */
+    private snapshotForDeviceOverlayed;
+    private emitStateChanged;
+    /** Emit DeviceStateChanged for (deviceId, cap) using the OVERLAID slice,
+     *  skipping when the overlay is unchanged since the last emit (loop/churn
+     *  guard). Used for the written pair AND its dependent targets. */
+    private emitOverlayed;
+    protected onShutdown(): Promise<void>;
+}
+export default DeviceManagerAddon;