@camstack/system 1.1.11 → 1.1.12

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

@@ -1,33 +1,8 @@
 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;
+import { ContributionShape } from './device-meta-types.js';
+import { mergeAggregates } from './device-aggregation-merge.js';
+import { ResolvedTargetLink, DependentLink } from './device-link-overlay.js';
+export { mergeAggregates };
 export declare class DeviceManagerAddon extends BaseAddon {
     constructor();
     /** Shorthand for the kernel-injected capability registry. */
@@ -48,22 +23,13 @@ export declare class DeviceManagerAddon extends BaseAddon {
      * (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.
+     * 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 readonly runtimeStateDebounce;
-    private static readonly RUNTIME_STATE_DEBOUNCE_MS;
+    private stateMirrorImpl;
     /**
      * Cross-process native-provider cache: deviceId (numeric) → capName → { addonId, nodeId }.
      * Kept in sync with `DeviceBindingsChanged` push events emitted by forked
@@ -93,8 +59,6 @@ export declare class DeviceManagerAddon extends BaseAddon {
     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). */
@@ -102,173 +66,54 @@ export declare class DeviceManagerAddon extends BaseAddon {
     /** Test/diagnostic accessors. */
     linkTargetKeys(): string[];
     linkDependentsKeys(): string[];
+    /** Replace the cross-device link reverse-index maps in one atomic swap.
+     *  Sole writer of `linkTargets` / `linkDependents` / `expectedSourceStableIds`;
+     *  called by `DeviceMetaStore.rebuildLinkDependents` via the `LinkIndexHost`. */
+    setLinkIndexes(targets: Map<string, ResolvedTargetLink[]>, dependents: Map<string, DependentLink[]>, expectedSourceStableIds: Set<string>): void;
+    /** Build the `LinkIndexHost` the meta store mutates — exposes this addon's
+     *  `devicesWithLinks` gate (read) + `setLinkIndexes` (write) without leaking
+     *  the private maps. */
+    private get linkIndexHost();
+    /** The runtime-state mirror, asserted present (constructed in onInitialize). */
+    private get stateMirror();
+    /** Build the `LinkOverlayHost` the state mirror reads when overlaying linked
+     *  values — exposes the link reverse-index maps + registry via LIVE thunks
+     *  (the maps are reassigned on every `rebuildLinkDependents`). Arrow thunks
+     *  capture `this` lexically so the getters never go stale. */
+    private get linkOverlayHost();
+    /** 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.
+     *
+     *  `expectedSourceStableIds` is exposed via a LIVE thunk: the field is
+     *  reassigned to a fresh Set on every `rebuildLinkDependents`, so a captured
+     *  reference would go stale. `devicesWithLinks` / `remoteNativeCaps` are
+     *  mutated in place (never reassigned) so a direct reference preserves the
+     *  original live semantics. The overlay-emit guard now lives in the state
+     *  mirror — pruning is routed through `dropDeviceOverlays`. */
+    private get providerHost();
     /** 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;
+    /** Build the dependency context the extracted binding resolvers consume. */
+    private get bindingsDeps();
     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;
+    /** Build the dependency context the extracted aggregation functions consume. */
+    private get aggregationDeps();
     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;
@@ -278,45 +123,6 @@ export declare class DeviceManagerAddon extends BaseAddon {
     }): 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<{
@@ -333,10 +139,7 @@ export declare class DeviceManagerAddon extends BaseAddon {
             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;
+    private dispatchDeviceAction;
     listWrappersForCap(input: {
         capName: string;
     }): Promise<string[]>;
@@ -353,100 +156,6 @@ export declare class DeviceManagerAddon extends BaseAddon {
         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;