@camstack/system 1.2.390 → 1.2.391

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

@@ -1,266 +1,278 @@
-import { AddonContext, CapabilityDefinition, DeviceBindingEntry, ICapabilityRegistry } from '@camstack/types';
-import { DeviceBindingsStore } from './device-meta-types.js';
-import { DeviceRow, DeviceRowStore } from './device-row-store.js';
-import { StaleWrapperActivations } from './stale-wrapper-activations.js';
-import { WriteLock } from './write-lock.js';
+/**
+* Persisted wrapper-activation + per-device binding resolution for the
+* device-manager addon. Extracted from `device-manager.addon.ts` as free
+* functions that receive an explicit `BindingsDeps` context (dependency
+* injection) instead of closing over the addon instance — keeps the routing
+* logic cohesive and independently testable while preserving the EXACT call
+* semantics, ordering, and side effects of the original class methods.
+*
+* The addon keeps thin delegator methods (`getBindings`, `getAllBindings`, …)
+* that build `BindingsDeps` from its own state and forward here, so every
+* existing internal + cap-router call site is unchanged.
+*/
+import type { AddonContext, CapabilityDefinition, DeviceBindingEntry, ICapabilityRegistry } from "@camstack/types";
+import type { DeviceBindingsStore } from "./device-meta-types.js";
+import type { DeviceRow, DeviceRowStore } from "./device-row-store.js";
+import type { StaleWrapperActivations } from "./stale-wrapper-activations.js";
+import type { WriteLock } from "./write-lock.js";
 /** Push-fed remote native-cap cache shape (numeric deviceId → capName → owner). */
 export type RemoteNativeCaps = Map<number, Map<string, {
-    addonId: string;
-    nodeId: string;
+	addonId: string;
+	nodeId: string;
 }>>;
 /**
- * Low-level dependencies the binding resolver needs. Assembled by the addon
- * from its own (mostly private) state and passed in explicitly — no hidden
- * `this` capture.
- */
+* Low-level dependencies the binding resolver needs. Assembled by the addon
+* from its own (mostly private) state and passed in explicitly — no hidden
+* `this` capture.
+*/
 export interface BindingsDeps {
-    readonly ctx: AddonContext;
-    readonly capabilityRegistry: ICapabilityRegistry | undefined;
-    readonly remoteNativeCaps: RemoteNativeCaps;
-    /** Row access for `device-manager:devices` — the device ledger the type and
-     *  presence gates below consult. */
-    readonly rows: DeviceRowStore;
-    /**
-     * Ordering for every read-modify-write of this addon's `addon-settings` key
-     * range — `deviceBindings` above all, but also `locations`, `nextDeviceId`
-     * and `roleDisplayDefaults`.
-     *
-     * `deviceBindings` is ONE fleet-wide blob keyed by device, so a writer that
-     * only means to touch camera 615 rewrites every camera's row. Nothing
-     * ordered those writers, and the window between the read and the write is a
-     * settings-door round trip — an RPC to the isolated `sqlite-settings` child,
-     * measured at 2.9 s on the live hub mid-drain (D181). Two toggles on
-     * DIFFERENT cameras therefore lost each other, and the value that went
-     * missing was `{ wrapperAddonId: null }`: the marker that keeps a
-     * `defaultActive` wrapper from re-binding. The operator's OFF came back ON
-     * (D62).
-     *
-     * **Writers only.** No read path takes this lock: `getBindings`,
-     * `getBindingsBatch` and `getAllBindings` must never queue behind a write,
-     * and putting a read under it would make a 1 019-device sweep wait on
-     * whatever toggle happens to be in flight.
-     */
-    readonly withAddonStoreWriteLock: WriteLock;
-    /**
-     * The per-process memory of stored activations that name a RETIRED wrapper
-     * (a cap with no `kind: 'wrapper'` any more): each is ignored by step 1 and
-     * said once (task 17 review M1, `stale-wrapper-activations.ts`).
-     */
-    readonly staleWrapperActivations: StaleWrapperActivations;
+	readonly ctx: AddonContext;
+	readonly capabilityRegistry: ICapabilityRegistry | undefined;
+	readonly remoteNativeCaps: RemoteNativeCaps;
+	/** Row access for `device-manager:devices` — the device ledger the type and
+	*  presence gates below consult. */
+	readonly rows: DeviceRowStore;
+	/**
+	* Ordering for every read-modify-write of this addon's `addon-settings` key
+	* range — `deviceBindings` above all, but also `locations`, `nextDeviceId`
+	* and `roleDisplayDefaults`.
+	*
+	* `deviceBindings` is ONE fleet-wide blob keyed by device, so a writer that
+	* only means to touch camera 615 rewrites every camera's row. Nothing
+	* ordered those writers, and the window between the read and the write is a
+	* settings-door round trip — an RPC to the isolated `sqlite-settings` child,
+	* measured at 2.9 s on the live hub mid-drain (D181). Two toggles on
+	* DIFFERENT cameras therefore lost each other, and the value that went
+	* missing was `{ wrapperAddonId: null }`: the marker that keeps a
+	* `defaultActive` wrapper from re-binding. The operator's OFF came back ON
+	* (D62).
+	*
+	* **Writers only.** No read path takes this lock: `getBindings`,
+	* `getBindingsBatch` and `getAllBindings` must never queue behind a write,
+	* and putting a read under it would make a 1 019-device sweep wait on
+	* whatever toggle happens to be in flight.
+	*/
+	readonly withAddonStoreWriteLock: WriteLock;
+	/**
+	* The per-process memory of stored activations that name a RETIRED wrapper
+	* (a cap with no `kind: 'wrapper'` any more): each is ignored by step 1 and
+	* said once (task 17 review M1, `stale-wrapper-activations.ts`).
+	*/
+	readonly staleWrapperActivations: StaleWrapperActivations;
 }
 /**
- * Wire the push-fed cross-process native-cap cache (`remoteNativeCaps`).
- * Workers emit `DeviceBindingsChanged` on `ctx.registerNativeCap` / device
- * removal; we mirror those into `remoteNativeCaps` so `getBindings` returns the
- * full cluster view. Events from the local node are ignored: hub-local natives
- * live in `capabilityRegistry` and are folded in directly by getBindings.
- *
- * Push events are accurate in the steady state but can be lost during the
- * Moleculer transport handshake window (hub restart, crash-respawn,
- * restartAddon). The reliable replacement for lost events is the D3 re-handshake
- * (`listClusterNativeCaps()`), which `resolveNativeCapOwnerSync` /
- * `getBindings` step 4 fall through to on a push miss. The `$node.disconnected`
- * handler purges a gone node's entries; the worker re-handshakes (and re-emits
- * `native-registered`) on its next boot.
- */
+* Wire the push-fed cross-process native-cap cache (`remoteNativeCaps`).
+* Workers emit `DeviceBindingsChanged` on `ctx.registerNativeCap` / device
+* removal; we mirror those into `remoteNativeCaps` so `getBindings` returns the
+* full cluster view. Events from the local node are ignored: hub-local natives
+* live in `capabilityRegistry` and are folded in directly by getBindings.
+*
+* Push events are accurate in the steady state but can be lost during the
+* Moleculer transport handshake window (hub restart, crash-respawn,
+* restartAddon). The reliable replacement for lost events is the D3 re-handshake
+* (`listClusterNativeCaps()`), which `resolveNativeCapOwnerSync` /
+* `getBindings` step 4 fall through to on a push miss. The `$node.disconnected`
+* handler purges a gone node's entries; the worker re-handshakes (and re-emits
+* `native-registered`) on its next boot.
+*/
 export declare function wireRemoteNativeCapSync(ctx: AddonContext, remoteNativeCaps: RemoteNativeCaps): void;
 /**
- * All a bindings-store read or write needs: the settings door. Named narrower
- * than {@link BindingsDeps} so the activation verb (`device-source-activation.ts`)
- * can reach the store without the device ledger and the remote-native cache it
- * never touches — `BindingsDeps` satisfies it structurally, so every existing
- * call site is unchanged.
- */
+* All a bindings-store read or write needs: the settings door. Named narrower
+* than {@link BindingsDeps} so the activation verb (`device-source-activation.ts`)
+* can reach the store without the device ledger and the remote-native cache it
+* never touches — `BindingsDeps` satisfies it structurally, so every existing
+* call site is unchanged.
+*/
 export interface BindingsStoreDeps {
-    readonly ctx: AddonContext;
+	readonly ctx: AddonContext;
 }
 export declare function readBindingsStore(deps: BindingsStoreDeps): Promise<DeviceBindingsStore>;
 export declare function writeBindingsStore(deps: BindingsStoreDeps, next: DeviceBindingsStore): Promise<void>;
 export declare function resolveWrapperNodeId(_wrapperAddonId: string): string;
 /**
- * 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.
- */
+* 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.
+*/
 export declare function toRoutableProviderNodeId(nodeId: string): string;
 /**
- * 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).
- */
+* 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).
+*/
 export declare function resolveRemoteNativeCapFromRegistry(deps: BindingsDeps, capName: string, deviceId: number): {
-    addonId: string;
-    nodeId: string;
+	addonId: string;
+	nodeId: string;
 } | null;
 /**
- * Resolve the device's declared TYPE (`'camera'`, `'event-emitter'`, …), or
- * `undefined` when it cannot be established.
- *
- * The PERSISTED row is the authority: `ctx.kernel.deviceRegistry` is hub-only
- * and has been observed empty in the very process that answers `getBindings`
- * correctly (see the note on `getAllBindings`). The registry is consulted only
- * as a secondary source, for a device constructed but not yet persisted.
- *
- * `undefined` is a first-class answer and callers must treat it as "no
- * filtering" — an absent row must never be the reason a device loses bindings.
- */
+* Resolve the device's declared TYPE (`'camera'`, `'event-emitter'`, …), or
+* `undefined` when it cannot be established.
+*
+* The PERSISTED row is the authority: `ctx.kernel.deviceRegistry` is hub-only
+* and has been observed empty in the very process that answers `getBindings`
+* correctly (see the note on `getAllBindings`). The registry is consulted only
+* as a secondary source, for a device constructed but not yet persisted.
+*
+* `undefined` is a first-class answer and callers must treat it as "no
+* filtering" — an absent row must never be the reason a device loses bindings.
+*/
 export declare function resolveDeviceType(deps: BindingsDeps, row: DeviceRow | null, deviceId: number): string | undefined;
 /**
- * Whether the device-manager's own stores still know a device id.
- *
- * `'unknown'` is NOT `'absent'` — it means the question could not be answered
- * and the caller must behave exactly as it did before asking.
- */
-export type DevicePresence = 'present' | 'absent' | 'unknown';
+* Whether the device-manager's own stores still know a device id.
+*
+* `'unknown'` is NOT `'absent'` — it means the question could not be answered
+* and the caller must behave exactly as it did before asking.
+*/
+export type DevicePresence = "present" | "absent" | "unknown";
 /**
- * Is this device still part of the fleet?
- *
- * The device-manager's own stores are the authority in-process — no RPC. Two
- * sources, in the same order `resolveDeviceType` uses them: the live registry
- * first (a device constructed but not yet persisted is present), then the
- * PERSISTED meta, which is the index `getBindings` already reads and is present
- * wherever this provider runs.
- *
- * `'absent'` is only ever returned against a NON-EMPTY ledger. An empty one
- * means device restore has not run, not that the fleet was deleted (D49) — the
- * same reason `getAllBindings` warns instead of reporting zero devices. That is
- * the only reason this is async: the `COUNT(*)` runs solely on the miss path,
- * where the alternative is to call a device gone because the store is empty.
- *
- * `ledgerNonEmpty` is passed IN rather than defaulted, deliberately. A default
- * that issued its own `rows.count()` would be a per-device read hiding behind
- * an optional argument — the exact shape this file just removed from the
- * activations blob — and nothing would fail when a future caller took it.
- */
+* Is this device still part of the fleet?
+*
+* The device-manager's own stores are the authority in-process — no RPC. Two
+* sources, in the same order `resolveDeviceType` uses them: the live registry
+* first (a device constructed but not yet persisted is present), then the
+* PERSISTED meta, which is the index `getBindings` already reads and is present
+* wherever this provider runs.
+*
+* `'absent'` is only ever returned against a NON-EMPTY ledger. An empty one
+* means device restore has not run, not that the fleet was deleted (D49) — the
+* same reason `getAllBindings` warns instead of reporting zero devices. That is
+* the only reason this is async: the `COUNT(*)` runs solely on the miss path,
+* where the alternative is to call a device gone because the store is empty.
+*
+* `ledgerNonEmpty` is passed IN rather than defaulted, deliberately. A default
+* that issued its own `rows.count()` would be a per-device read hiding behind
+* an optional argument — the exact shape this file just removed from the
+* activations blob — and nothing would fail when a future caller took it.
+*/
 export declare function resolveDevicePresence(deps: BindingsDeps, row: DeviceRow | null, deviceId: number, ledgerNonEmpty: LedgerNonEmpty): Promise<DevicePresence>;
 /** "Does the ledger hold any row at all?", asked at most once per pass. */
 export type LedgerNonEmpty = () => Promise<boolean>;
 /**
- * Does a capability apply to a device of type `deviceType`?
- *
- * The cap's `deviceTypes` is the ONLY declaration consulted (D4: behavioural
- * cap metadata lives in the `*.cap.ts`, never in a manifest). Two deliberate
- * fail-open cases:
- *
- *   - a cap that declares no `deviceTypes` (or an empty list) applies to every
- *     device — the pre-existing, back-compatible semantics;
- *   - an UNKNOWN `deviceType` never filters, so a missing/failed meta lookup
- *     changes nothing (D49: a read that fails must not destroy work).
- */
+* Does a capability apply to a device of type `deviceType`?
+*
+* The cap's `deviceTypes` is the ONLY declaration consulted (D4: behavioural
+* cap metadata lives in the `*.cap.ts`, never in a manifest). Two deliberate
+* fail-open cases:
+*
+*   - a cap that declares no `deviceTypes` (or an empty list) applies to every
+*     device — the pre-existing, back-compatible semantics;
+*   - an UNKNOWN `deviceType` never filters, so a missing/failed meta lookup
+*     changes nothing (D49: a read that fails must not destroy work).
+*/
 export declare function capAppliesToDeviceType(def: CapabilityDefinition | undefined, deviceType: string | undefined): boolean;
 /**
- * An addon's identity, with the node it happens to run on stripped.
- *
- * A capability registered on an agent arrives under `<addonId>@<nodeId>` —
- * `pipeline-analytics@little-unraid`. That is the same ADDON as the hub-local
- * `pipeline-analytics`, and treating the two as different providers is what
- * put `analytics` in device 592's clip picker three times (D554 amended).
- * Where a provider RUNS is a routing fact; it is not part of who it is.
- */
+* An addon's identity, with the node it happens to run on stripped.
+*
+* A capability registered on an agent arrives under `<addonId>@<nodeId>` —
+* `pipeline-analytics@little-unraid`. That is the same ADDON as the hub-local
+* `pipeline-analytics`, and treating the two as different providers is what
+* put `analytics` in device 592's clip picker three times (D554 amended).
+* Where a provider RUNS is a routing fact; it is not part of who it is.
+*/
 export declare function addonIdentityOf(addonId: string): string;
 export declare function getBindings(deps: BindingsDeps, input: {
-    deviceId: number;
+	deviceId: number;
 }): Promise<{
-    deviceId: number;
-    entries: DeviceBindingEntry[];
+	deviceId: number;
+	entries: DeviceBindingEntry[];
 }>;
 /**
- * A NAMED set of devices' bindings, in one round-trip.
- *
- * Same resolver as `getBindings`, so the routing rules and the per-device
- * shape are identical by construction. It exists because the gap between one
- * device and all 988 had nothing in it: measured on the live hub 2026-08-25, a
- * caller needing seventy-five paid either 75 round-trips (1211 ms / 118 KB) or
- * `getAllBindings` (511 ms / 679 KB of mostly-unwanted rows).
- *
- * Sequential on purpose, like `getAllBindings`: `resolveBindingsForDevice`'s
- * remaining per-device work is the routing rules, which run on this process's
- * own event loop, so concurrency buys nothing there and a fan-out of
- * `Promise.all` over hundreds of ids only makes the queue less fair to
- * everything else on it. Both parts that DO amortise across the whole set are
- * fetched ONCE, ahead of the loop, and in parallel with each other:
- *
- *  - the device rows ({@link DeviceRowStore.getMany}) rather than once per
- *    iteration — measured on the live hub 2026-08-25, `get
- *    device-manager:devices` ran 1 656 calls/min steady-state, one row per
- *    call, which is exactly what looping `getBindings`'s own
- *    `rows.get(deviceId)` here produced;
- *  - the wrapper-activation blob, which the per-device resolver used to read
- *    itself — a second settings-door round trip per id, on the call that
- *    exists precisely so a caller needing many devices does not pay per
- *    device. Measured on the live hub 2026-08-30, mid-drain:
- *    `getBindingsBatch` of 1 id = 5.78 s, of 8 ids = 17.16 s — a slope of
- *    1.63 s PER ADDITIONAL DEVICE, on a call that ships 4.5 KB a row.
- */
+* A NAMED set of devices' bindings, in one round-trip.
+*
+* Same resolver as `getBindings`, so the routing rules and the per-device
+* shape are identical by construction. It exists because the gap between one
+* device and all 988 had nothing in it: measured on the live hub 2026-08-25, a
+* caller needing seventy-five paid either 75 round-trips (1211 ms / 118 KB) or
+* `getAllBindings` (511 ms / 679 KB of mostly-unwanted rows).
+*
+* Sequential on purpose, like `getAllBindings`: `resolveBindingsForDevice`'s
+* remaining per-device work is the routing rules, which run on this process's
+* own event loop, so concurrency buys nothing there and a fan-out of
+* `Promise.all` over hundreds of ids only makes the queue less fair to
+* everything else on it. Both parts that DO amortise across the whole set are
+* fetched ONCE, ahead of the loop, and in parallel with each other:
+*
+*  - the device rows ({@link DeviceRowStore.getMany}) rather than once per
+*    iteration — measured on the live hub 2026-08-25, `get
+*    device-manager:devices` ran 1 656 calls/min steady-state, one row per
+*    call, which is exactly what looping `getBindings`'s own
+*    `rows.get(deviceId)` here produced;
+*  - the wrapper-activation blob, which the per-device resolver used to read
+*    itself — a second settings-door round trip per id, on the call that
+*    exists precisely so a caller needing many devices does not pay per
+*    device. Measured on the live hub 2026-08-30, mid-drain:
+*    `getBindingsBatch` of 1 id = 5.78 s, of 8 ids = 17.16 s — a slope of
+*    1.63 s PER ADDITIONAL DEVICE, on a call that ships 4.5 KB a row.
+*/
 export declare function getBindingsBatch(deps: BindingsDeps, input: {
-    deviceIds: readonly number[];
+	deviceIds: readonly number[];
 }): Promise<Array<{
-    deviceId: number;
-    entries: DeviceBindingEntry[];
+	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.
- *
- * **"Single round-trip" was a claim, not a fact, until 2026-08-30.** The
- * per-device resolver read the wrapper-activation blob itself, so this call
- * issued one settings-door RPC per device — 1 020 of them on the live
- * 1 019-device hub, at ~2.9 s each while the storage drain ran. It did not
- * return in 240 s, and `SystemMirror.init` gives it 15 s, so the admin UI
- * could not boot at all. Now the whole pass costs exactly TWO reads (the fleet
- * listing and the blob), issued in parallel, and nothing in the loop awaits a
- * store.
- */
+* 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.
+*
+* **"Single round-trip" was a claim, not a fact, until 2026-08-30.** The
+* per-device resolver read the wrapper-activation blob itself, so this call
+* issued one settings-door RPC per device — 1 020 of them on the live
+* 1 019-device hub, at ~2.9 s each while the storage drain ran. It did not
+* return in 240 s, and `SystemMirror.init` gives it 15 s, so the admin UI
+* could not boot at all. Now the whole pass costs exactly TWO reads (the fleet
+* listing and the blob), issued in parallel, and nothing in the loop awaits a
+* store.
+*/
 export declare function getAllBindings(deps: BindingsDeps): Promise<Array<{
-    deviceId: number;
-    entries: DeviceBindingEntry[];
+	deviceId: number;
+	entries: DeviceBindingEntry[];
 }>>;
 /**
- * The ids of every device bound to at least one of `capNames`, ascending.
- *
- * Built on {@link getAllBindings} so the routing rules (native, wrapped,
- * remote) are the ones `getBindings` applies — a second resolver is how the
- * two would drift. Only ids leave: the whole point is that a caller asking
- * "which devices are openings" does not receive 1 000 binding maps (D636).
- */
+* The ids of every device bound to at least one of `capNames`, ascending.
+*
+* Built on {@link getAllBindings} so the routing rules (native, wrapped,
+* remote) are the ones `getBindings` applies — a second resolver is how the
+* two would drift. Only ids leave: the whole point is that a caller asking
+* "which devices are openings" does not receive 1 000 binding maps (D636).
+*/
 export interface ListDeviceIdsByCapsInput {
-    readonly capNames: readonly string[];
+	readonly capNames: readonly string[];
 }
 export declare function listDeviceIdsByCaps(deps: BindingsDeps, input: ListDeviceIdsByCapsInput): Promise<number[]>;
 /**
- * Resolve a numeric deviceId to a stableId via persisted meta.
- * Used by callers that need a persisted stableId when the live registry
- * does not hold the device (cross-process / mid-restart). Formerly fed
- * the Config Identity section; that section left Config for Overview.
- * 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.
- */
+* Resolve a numeric deviceId to a stableId via persisted meta.
+* Used by callers that need a persisted stableId when the live registry
+* does not hold the device (cross-process / mid-restart). Formerly fed
+* the Config Identity section; that section left Config for Overview.
+* 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.
+*/
 export declare function lookupPersistedStableId(deps: BindingsDeps, deviceId: number): Promise<string | undefined>;

package/dist/builtins/device-manager/device-config-contribution.d.ts

@@ -1,21 +1,21 @@
-import { StreamProfile, StreamProfilePatch } from '@camstack/types';
+import type { StreamProfile, StreamProfilePatch } from "@camstack/types";
 /** A framework-derived contribution shape — sections[] (+ optional tabs[]). */
 export interface DerivedContributionShape {
-    readonly tabs?: ReadonlyArray<{
-        id: string;
-        label: string;
-        icon: string;
-        order?: number;
-    }>;
-    readonly sections: ReadonlyArray<{
-        id: string;
-        title: string;
-        tab?: string;
-        order?: number;
-        description?: string;
-        columns?: 1 | 2 | 3 | 4;
-        fields: readonly unknown[];
-    }>;
+	readonly tabs?: ReadonlyArray<{
+		id: string;
+		label: string;
+		icon: string;
+		order?: number;
+	}>;
+	readonly sections: ReadonlyArray<{
+		id: string;
+		title: string;
+		tab?: string;
+		order?: number;
+		description?: string;
+		columns?: 1 | 2 | 3 | 4;
+		fields: readonly unknown[];
+	}>;
 }
 /** A per-profile mutation callback the cap's provider supplies (profile-based caps only). */
 export type ProfileSetter = (profile: StreamProfile, patch: StreamProfilePatch) => Promise<void>;
@@ -25,21 +25,21 @@ export declare const DAY_NIGHT_BUILDER_ID: "day-night";
 export declare const IMAGE_SETTINGS_BUILDER_ID: "image-settings";
 export declare const RECORDING_ONBOARD_BUILDER_ID: "recording-onboard";
 /**
- * Build the device-detail form section for a `derived-form` device-config
- * cap. Returns null when the camera exposes no configurable property.
- */
+* Build the device-detail form section for a `derived-form` device-config
+* cap. Returns null when the camera exposes no configurable property.
+*/
 export declare function deriveFormContribution(builderId: string, options: unknown, status: unknown): DerivedContributionShape | null;
 /**
- * Route a flat form patch back through a profile-based cap's per-profile
- * `setProfile` mutation (`stream-params`). Throws if `builderId` isn't
- * registered as a profile-based reducer — callers dispatch here only
- * after confirming the bound provider exposes `setProfile`.
- */
+* Route a flat form patch back through a profile-based cap's per-profile
+* `setProfile` mutation (`stream-params`). Throws if `builderId` isn't
+* registered as a profile-based reducer — callers dispatch here only
+* after confirming the bound provider exposes `setProfile`.
+*/
 export declare function applyDerivedFormProfilePatch(builderId: string, patch: Record<string, unknown>, setProfile: ProfileSetter): Promise<void>;
 /**
- * Parse a flat form patch into the settings payload for a `setSettings`-
- * based cap (`day-night`, `image-settings`). The caller forwards the
- * result verbatim to `dcProvider.setSettings({ deviceId, settings })`.
- * Throws if `builderId` isn't registered as a settings-based reducer.
- */
+* Parse a flat form patch into the settings payload for a `setSettings`-
+* based cap (`day-night`, `image-settings`). The caller forwards the
+* result verbatim to `dcProvider.setSettings({ deviceId, settings })`.
+* Throws if `builderId` isn't registered as a settings-based reducer.
+*/
 export declare function parseDerivedFormSettingsPatch(builderId: string, patch: Record<string, unknown>): Record<string, unknown>;

package/dist/builtins/device-manager/device-config-secrets.d.ts

@@ -1,21 +1,40 @@
-import { AddonContext } from '@camstack/types';
+/**
+* The device-config door of the keychain (D787) — device CONNECTION config
+* (camera passwords, controller API keys) lives in device-manager's per-device
+* store, written by the driver's `persistConfig` and read back by its
+* `loadConfig`. Resolving HERE, at the door, means no driver ever sees a
+* marker and no driver has to change.
+*
+* - WRITE: the paths the device's own schema declares secret (D783:
+*   `secretConfigPaths`, from the persist call or from its last
+*   `registerDevice`) go through the keychain save path, owned by the DRIVER
+*   addon (`device/<id>` scope). A value equal to an inline pre-keychain one
+*   stays inline (no silent migration); `''` keeps.
+* - READ: every marker in the stored blob is resolved for the driver; one that
+*   cannot be is LEFT OUT (the driver's schema default applies) and logged by
+*   ref — never answered as `''`, never written back.
+*
+* device-manager runs in hub-main, so it acts for the driver through
+* `ctx.secrets.forOwner` — the in-process delegate no forked addon has.
+*/
+import { type AddonContext } from "@camstack/types";
 export interface DeviceConfigSecretDeps {
-    readonly ctx: AddonContext;
-    readonly readStored: () => Promise<Record<string, unknown>>;
-    readonly write: (patch: Record<string, unknown>) => Promise<void>;
+	readonly ctx: AddonContext;
+	readonly readStored: () => Promise<Record<string, unknown>>;
+	readonly write: (patch: Record<string, unknown>) => Promise<void>;
 }
 /** Persist a device config patch with its declared secrets kept in the keychain. */
 export declare function persistDeviceConfigWithSecrets(deps: DeviceConfigSecretDeps, input: {
-    readonly deviceId: number;
-    readonly ownerAddonId: string;
-    readonly data: Record<string, unknown>;
-    readonly secretPaths: readonly string[];
-    /** The write was made by the operator (no driver stamped it). */
-    readonly operatorWrite: boolean;
+	readonly deviceId: number;
+	readonly ownerAddonId: string;
+	readonly data: Record<string, unknown>;
+	readonly secretPaths: readonly string[];
+	/** The write was made by the operator (no driver stamped it). */
+	readonly operatorWrite: boolean;
 }): Promise<void>;
 /** A stored device config with its markers resolved for the driver. */
 export declare function loadDeviceConfigWithSecrets(ctx: AddonContext, input: {
-    readonly deviceId: number;
-    readonly ownerAddonId: string;
-    readonly stored: Record<string, unknown>;
+	readonly deviceId: number;
+	readonly ownerAddonId: string;
+	readonly stored: Record<string, unknown>;
 }): Promise<Record<string, unknown>>;