@camstack/system 1.2.390 → 1.2.391

package/dist/builtins/device-manager/device-event-propagator.d.ts

@@ -1,26 +1,26 @@
-import { IEventBus, SystemEvent } from '@camstack/types';
+import type { IEventBus, SystemEvent } from "@camstack/types";
 export interface DeviceEventPropagatorOptions {
-    readonly eventBus: IEventBus;
-    /**
-     * Resolve the numeric parent id of a device, or `null` when the
-     * device has no parent (or was deleted). The propagator injects a
-     * closure over the hub's `DeviceRegistry` so the lookup is in-
-     * process and O(1) per call.
-     */
-    readonly getParentOf: (deviceId: number) => number | null;
-    /** Structured logger for anti-cycle + anti-loop diagnostics. */
-    readonly logger: {
-        warn: (msg: string, meta?: Record<string, unknown>) => void;
-        debug: (msg: string, meta?: Record<string, unknown>) => void;
-    };
+	readonly eventBus: IEventBus;
+	/**
+	* Resolve the numeric parent id of a device, or `null` when the
+	* device has no parent (or was deleted). The propagator injects a
+	* closure over the hub's `DeviceRegistry` so the lookup is in-
+	* process and O(1) per call.
+	*/
+	readonly getParentOf: (deviceId: number) => number | null;
+	/** Structured logger for anti-cycle + anti-loop diagnostics. */
+	readonly logger: {
+		warn: (msg: string, meta?: Record<string, unknown>) => void;
+		debug: (msg: string, meta?: Record<string, unknown>) => void;
+	};
 }
 export declare class DeviceEventPropagator {
-    private readonly opts;
-    private unsubscribe;
-    constructor(opts: DeviceEventPropagatorOptions);
-    start(): void;
-    stop(): void;
-    /** Exposed for tests — lets them inject events without the full bus. */
-    handle(ev: SystemEvent): void;
-    private resolveParentChain;
+	private readonly opts;
+	private unsubscribe;
+	constructor(opts: DeviceEventPropagatorOptions);
+	start(): void;
+	stop(): void;
+	/** Exposed for tests — lets them inject events without the full bus. */
+	handle(ev: SystemEvent): void;
+	private resolveParentChain;
 }

package/dist/builtins/device-manager/device-extension-linked-slot.d.ts

@@ -1,27 +1,27 @@
-import { IDeviceExtensionProvider } from '@camstack/types';
-import { ProviderContext } from './device-provider-context.js';
+import { type IDeviceExtensionProvider } from "@camstack/types";
+import type { ProviderContext } from "./device-provider-context.js";
 /** The routing prefix of this owner's `slotRef`s. */
 export declare const DEVICE_MANAGER_EXTENSION_SOURCE = "device-manager";
 /** The store the slot reads and writes, named (D62). */
-export declare const LINKED_DEVICES_AUTHORITY = "device-manager:_linkedDeviceIds";
+export declare const LINKED_DEVICES_AUTHORITY: string;
 /** What `refusedTrackedOptIns` judges: the opt-in written, and what it may name. */
 export interface TrackedOptInWrite {
-    readonly tracked: readonly number[];
-    /** The picks being written. */
-    readonly picked: readonly number[];
-    /** Linked by structure: tree children, a picked container's child. */
-    readonly implied: readonly number[];
-    /** The opt-in as stored before this write. */
-    readonly stored: readonly number[];
+	readonly tracked: readonly number[];
+	/** The picks being written. */
+	readonly picked: readonly number[];
+	/** Linked by structure: tree children, a picked container's child. */
+	readonly implied: readonly number[];
+	/** The opt-in as stored before this write. */
+	readonly stored: readonly number[];
 }
 /**
- * Which ids of a written opt-in must be refused: a NEW opt-in for a device the
- * camera does not link. An id already stored is never refused — whatever was
- * read can be written back unchanged (a stale opt-in is removed by leaving it
- * out, never by being unable to save). The written list REPLACES the stored
- * one: since D655 the editor shows every stored opt-in, so nothing it sends
- * back is written blind.
- */
+* Which ids of a written opt-in must be refused: a NEW opt-in for a device the
+* camera does not link. An id already stored is never refused — whatever was
+* read can be written back unchanged (a stale opt-in is removed by leaving it
+* out, never by being unable to save). The written list REPLACES the stored
+* one: since D655 the editor shows every stored opt-in, so nothing it sends
+* back is written blind.
+*/
 export declare function refusedTrackedOptIns(params: TrackedOptInWrite): readonly number[];
 /** Build the `device-extension` provider the device manager registers. */
 export declare function createDeviceManagerExtensionProvider(pctx: ProviderContext): IDeviceExtensionProvider;

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

@@ -1,25 +1,25 @@
-import { ContributionShape } from './device-meta-types.js';
-type Sections = ContributionShape['sections'];
+import type { ContributionShape } from "./device-meta-types.js";
+type Sections = ContributionShape["sections"];
 /**
- * The driver's hydrated sections with every keychain-stored secret replaced
- * by its view. Returns the input unchanged when the blob holds no marker.
- */
+* The driver's hydrated sections with every keychain-stored secret replaced
+* by its view. Returns the input unchanged when the blob holds no marker.
+*/
 export declare function viewStoredSecrets(sections: Sections, stored: Record<string, unknown>, declaredPaths: readonly string[]): Sections;
 /** A form patch split into what the driver applies and what the door clears. */
 export interface DriverFormPatch {
-    readonly driverPatch: Record<string, unknown>;
-    readonly clearKeys: readonly string[];
+	readonly driverPatch: Record<string, unknown>;
+	readonly clearKeys: readonly string[];
 }
 /** Split a device-settings form patch (see the module doc). */
 export declare function splitDriverFormPatch(patch: Record<string, unknown>): DriverFormPatch;
 /**
- * Apply a device-settings form patch: the driver gets plain values only, then
- * an explicit clear removes the stored secret at the keychain door (after the
- * driver's own persist, whose `''` the door reads as KEEP).
- */
+* Apply a device-settings form patch: the driver gets plain values only, then
+* an explicit clear removes the stored secret at the keychain door (after the
+* driver's own persist, whose `''` the door reads as KEEP).
+*/
 export declare function applyDriverFormPatch(input: {
-    readonly patch: Record<string, unknown>;
-    readonly applyToDriver: (driverPatch: Record<string, unknown>) => Promise<void>;
-    readonly clearSecrets: (keys: readonly string[]) => Promise<void>;
+	readonly patch: Record<string, unknown>;
+	readonly applyToDriver: (driverPatch: Record<string, unknown>) => Promise<void>;
+	readonly clearSecrets: (keys: readonly string[]) => Promise<void>;
 }): Promise<void>;
 export {};

package/dist/builtins/device-manager/device-linked-devices.d.ts

@@ -1,140 +1,201 @@
-import { IDeviceManagerProvider, LinkedDevicesMode, legacyAutoLinkIds, LinkCandidate } from '@camstack/types';
-import { ProviderContext } from './device-provider-context.js';
+/**
+* Linked devices — camera ↔ companion-device association (first-class
+* device-manager concept).
+*
+* ONE cap read surface (`getLinkedDevices`) resolves the linked set:
+*   - device-tree CHILDREN are ALWAYS included;
+*   - plus the persisted manual list — the operator's picks (D356: nothing
+*     links itself; same-location devices are only SUGGESTED by the picker);
+*   - the camera itself is excluded; the result is deduped.
+*
+* CONTAINERS (`DeviceType.Container` — "parent container for entity-children
+* adopted from a single HA device entry", never renderable standalone, never
+* capability-bearing by construction, see `device-type.ts`) are never a
+* resolved link, in EITHER mode. A container occupies a UI slot and produces
+* no event — the capability always lives on the container's CHILD instead
+* (`getBindings(containerId)` is empty by construction; the child has the
+* cap). Any candidate that resolves to a container is transparently expanded
+* to that container's own children instead of being dropped — this is what
+* lets an operator link "the door lock" when the lock is modelled as a
+* container-with-children device: the always-included children rule and a
+* persisted manual id both funnel through the same expansion
+* (`expandContainer` below), recursively, so a container reached by either
+* path never appears and its real (capability-bearing) descendants do
+* instead. A manually-picked id that names a container is NOT stripped from
+* the persisted `_linkedDeviceIds` config — that would be a write on what is
+* otherwise a read path — it simply now resolves through the same expansion
+* as everything else (to its children, or to nothing if childless). The
+* `linked-devices` extension slot (`device-extension-linked-slot.ts`) never
+* OFFERS a container as a candidate and refuses one as a new pick — it is
+* never a legitimate pick, not just a filtered-out resolution.
+*
+* AUTO mode's same-location match compares each candidate's OWN `location`
+* field directly — no read-time inheritance. (2026-08-26, operator decision,
+* supersedes the read-time `resolveEffectiveLocation` this file used to
+* carry: a container's location-less child does NOT get resolved a location
+* at read time. Instead `setLocation` — device-meta-actions.ts — CASCADES a
+* container's location to every descendant's own `location` column the
+* instant the operator (re)sets it. Since D352 that write-time coverage is
+* complete: a one-shot boot backfill aligned every pre-cascade container
+* (`location-alignment.ts`), and `registerDevice` stamps the nearest located
+* CONTAINER ancestor's location onto a later-adopted child at registration
+* (container-only — a camera's accessories stay location-less on purpose,
+* reachable structurally, so they never become other cameras' companions). A
+* location-less child of a located container is therefore an ANOMALY (a
+* partially-failed cascade, a hand-edited ledger) — still skipped here, a
+* container is never itself a link (file header), full stop. The skip here
+* stays silent — there is no per-read warning in this file — but it is no
+* longer UNREPORTED: `location-alignment.ts`'s boot-time detection re-lists
+* every device on each boot and logs a WARN naming the ancestor and its
+* misaligned descendants, so the anomaly surfaces on a fixed cadence even
+* though no individual read here announces it.
+*
+* CONFIGURATION is the `linked-devices` extension slot (D648): it reads the
+* reserved keys below with `parseLinkedDevicesConfig` and writes them with
+* `applyLinkedDevicesPatch` — the device config blob, the same pattern as
+* `_profileMap`. The hand-written "Linked devices" settings section that
+* wrote the same keys was retired by D655. The one-shot "rebuild this room"
+* action is a CLIENT concern: the Locations page computes the same-location
+* set with `legacyAutoLinkIds` and writes it through the same slot.
+*/
+import type { IDeviceManagerProvider, LinkedDevicesMode } from "@camstack/types";
+import { legacyAutoLinkIds, type LinkCandidate } from "@camstack/types";
 export { legacyAutoLinkIds, type LinkCandidate };
+import type { ProviderContext } from "./device-provider-context.js";
 /** Reserved device-config keys (cf. `_profileMap`). */
 export declare const LINKED_MODE_CONFIG_KEY = "_linkedDevicesMode";
 export declare const LINKED_IDS_CONFIG_KEY = "_linkedDeviceIds";
 /** Reserved key: subset of linked devices that materialize synthetic tracked
- *  events on the camera. Absent ⇒ NONE — producing tracked events is an
- *  explicit operator OPT-IN (2026-07-22 flip: the old absent⇒ALL default
- *  auto-materialized sensor snapshots the operator never asked for). */
+*  events on the camera. Absent ⇒ NONE — producing tracked events is an
+*  explicit operator OPT-IN (2026-07-22 flip: the old absent⇒ALL default
+*  auto-materialized sensor snapshots the operator never asked for). */
 export declare const LINKED_TRACKED_IDS_CONFIG_KEY = "_linkedDeviceTrackedIds";
 /**
- * The three reserved keys, as one set: they stay with a camera's NUMBER on a
- * hardware swap, and a settings save that still carries them (a page opened
- * before D655 retired the section) is refused by name, never dropped.
- */
+* The three reserved keys, as one set: they stay with a camera's NUMBER on a
+* hardware swap, and a settings save that still carries them (a page opened
+* before D655 retired the section) is refused by name, never dropped.
+*/
 export declare const LINKED_DEVICES_RESERVED_KEYS: ReadonlySet<string>;
 export interface LinkedDevicesConfig {
-    /** Always `manual` since D356 — kept on the type because the cap output
-     *  still carries it for clients already shipped. */
-    readonly mode: LinkedDevicesMode;
-    readonly manualIds: readonly number[];
+	/** Always `manual` since D356 — kept on the type because the cap output
+	*  still carries it for clients already shipped. */
+	readonly mode: LinkedDevicesMode;
+	readonly manualIds: readonly number[];
 }
 /** Parse the two reserved keys out of a device-config blob. Tolerant:
- *  ids may arrive as numbers or numeric strings (the multiselect field
- *  stores string option values); anything else is dropped. */
+*  ids may arrive as numbers or numeric strings (the multiselect field
+*  stores string option values); anything else is dropped. */
 export declare function parseLinkedDevicesConfig(blob: Record<string, unknown>): LinkedDevicesConfig;
 /**
- * Pure resolution core: children ∪ (auto → same-location | manual → list),
- * minus self, deduped, CONTAINERS expanded to their children (see file
- * header). Order: children first, then mode additions.
- */
+* Pure resolution core: children ∪ (auto → same-location | manual → list),
+* minus self, deduped, CONTAINERS expanded to their children (see file
+* header). Order: children first, then mode additions.
+*/
 export declare function resolveLinkedDeviceIds(params: {
-    readonly selfId: number;
-    readonly config: LinkedDevicesConfig;
-    readonly candidates: readonly LinkCandidate[];
+	readonly selfId: number;
+	readonly config: LinkedDevicesConfig;
+	readonly candidates: readonly LinkCandidate[];
 }): readonly number[];
 /**
- * Which linked devices materialize synthetic tracked events on the camera.
- * Absent / non-array config key ⇒ NONE — the operator must explicitly pick
- * producers (opt-in; flipped from the legacy absent⇒ALL default, which
- * auto-materialized sensor snapshots for every linked device). Otherwise the
- * configured subset intersected with the currently-resolved linked set (a
- * picked id no longer linked is dropped). Ids may arrive as numbers or numeric
- * strings (the multiselect stores string option values); non-numeric entries
- * are ignored.
- */
+* Which linked devices materialize synthetic tracked events on the camera.
+* Absent / non-array config key ⇒ NONE — the operator must explicitly pick
+* producers (opt-in; flipped from the legacy absent⇒ALL default, which
+* auto-materialized sensor snapshots for every linked device). Otherwise the
+* configured subset intersected with the currently-resolved linked set (a
+* picked id no longer linked is dropped). Ids may arrive as numbers or numeric
+* strings (the multiselect stores string option values); non-numeric entries
+* are ignored.
+*/
 export declare function resolveTrackedEventDeviceIds(config: Record<string, unknown>, linkedIds: readonly number[]): readonly number[];
 /**
- * The persisted tracked-event opt-in AS STORED — not intersected with the
- * linked set, which is the resolver's job. Absent / non-array ⇒ `[]` (NONE,
- * the same answer the resolver gives). Ids may be numbers or numeric strings;
- * anything else is dropped; deduped, in stored order.
- */
+* The persisted tracked-event opt-in AS STORED — not intersected with the
+* linked set, which is the resolver's job. Absent / non-array ⇒ `[]` (NONE,
+* the same answer the resolver gives). Ids may be numbers or numeric strings;
+* anything else is dropped; deduped, in stored order.
+*/
 export declare function parseTrackedOptIn(config: Record<string, unknown>): readonly number[];
 /**
- * The fleet listing every function here needs, and the ONLY projection any of
- * them may ask for.
- *
- * Linked-device policy reads five fields off a candidate — `id`,
- * `parentDeviceId`, `location`, `name`, `features` — and `slim` carries all
- * five. What `slim` drops is `config`, and `config` is not a column: `listAll`
- * materialises it with ONE `readDeviceStore` per device, sequentially, on
- * device-manager's event loop. This module asked for the full projection three
- * times, so every linked-devices read swept the whole fleet's settings rows to
- * use none of them.
- *
- * Measured on the live hub 2026-08-25: `query addon-device-settings` ran
- * 36 814 times a minute against a 967-device fleet — ~38 full-fleet sweeps a
- * minute, ~31 of them the `pipeline-analytics` reverse index rebuilding itself
- * one camera at a time through `getLinkedDevices`. The per-camera `config`
- * this query DOES need is the separate `readDeviceStore(deviceId)` below, and
- * it is one row, not the fleet.
- */
+* The fleet listing every function here needs, and the ONLY projection any of
+* them may ask for.
+*
+* Linked-device policy reads five fields off a candidate — `id`,
+* `parentDeviceId`, `location`, `name`, `features` — and `slim` carries all
+* five. What `slim` drops is `config`, and `config` is not a column: `listAll`
+* materialises it with ONE `readDeviceStore` per device, sequentially, on
+* device-manager's event loop. This module asked for the full projection three
+* times, so every linked-devices read swept the whole fleet's settings rows to
+* use none of them.
+*
+* Measured on the live hub 2026-08-25: `query addon-device-settings` ran
+* 36 814 times a minute against a 967-device fleet — ~38 full-fleet sweeps a
+* minute, ~31 of them the `pipeline-analytics` reverse index rebuilding itself
+* one camera at a time through `getLinkedDevices`. The per-camera `config`
+* this query DOES need is the separate `readDeviceStore(deviceId)` below, and
+* it is one row, not the fleet.
+*/
 export declare const LINK_CANDIDATE_PROJECTION: {
-    readonly projection: "slim";
+	readonly projection: "slim";
 };
 /** The single resolved answer, before it is tagged with its camera. */
-export type ResolvedLinkedDevices = Awaited<ReturnType<IDeviceManagerProvider['getLinkedDevices']>>;
+export type ResolvedLinkedDevices = Awaited<ReturnType<IDeviceManagerProvider["getLinkedDevices"]>>;
 /** Cap implementation of `getLinkedDevices`. */
-export declare function getLinkedDevices(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['getLinkedDevices']>[0]): ReturnType<IDeviceManagerProvider['getLinkedDevices']>;
+export declare function getLinkedDevices(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider["getLinkedDevices"]>[0]): ReturnType<IDeviceManagerProvider["getLinkedDevices"]>;
 /**
- * Cap implementation of `getLinkedDevicesBatch` — ONE fleet listing for the
- * whole set.
- *
- * That listing is the query's cost (see `resolveFor`), and asking per camera
- * does not amortise it: on the live hub 2026-08-25, 30 concurrent
- * `getLinkedDevices` took 4110 ms wall — a queue of thirty full-fleet sweeps
- * on device-manager's event loop — to produce 7260 bytes.
- *
- * Ids are deduped and the answer is one row per REQUESTED id, in the order
- * asked: a camera whose settings read fails still gets a row (resolved against
- * an empty config, i.e. children-only) rather than dropping out of the array.
- */
-export declare function getLinkedDevicesBatch(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['getLinkedDevicesBatch']>[0]): ReturnType<IDeviceManagerProvider['getLinkedDevicesBatch']>;
+* Cap implementation of `getLinkedDevicesBatch` — ONE fleet listing for the
+* whole set.
+*
+* That listing is the query's cost (see `resolveFor`), and asking per camera
+* does not amortise it: on the live hub 2026-08-25, 30 concurrent
+* `getLinkedDevices` took 4110 ms wall — a queue of thirty full-fleet sweeps
+* on device-manager's event loop — to produce 7260 bytes.
+*
+* Ids are deduped and the answer is one row per REQUESTED id, in the order
+* asked: a camera whose settings read fails still gets a row (resolved against
+* an empty config, i.e. children-only) rather than dropping out of the array.
+*/
+export declare function getLinkedDevicesBatch(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider["getLinkedDevicesBatch"]>[0]): ReturnType<IDeviceManagerProvider["getLinkedDevicesBatch"]>;
 /** The two device-store calls the linked-devices write needs — nothing else. */
 export interface LinkedDevicesStoreAccess {
-    readonly settings: Pick<ProviderContext['settings'], 'readDeviceStore' | 'writeDeviceStore'>;
+	readonly settings: Pick<ProviderContext["settings"], "readDeviceStore" | "writeDeviceStore">;
 }
 /**
- * THE write path for the linked-devices keys — the `linked-devices` slot's
- * `set` lands here (D648). Normalizes the pick list and the tracked-event
- * opt-in; an EXPLICIT empty opt-in is stored as `[]`, never deleted, because
- * an absent key and an empty one are read alike today but only `[]` says the
- * operator chose "none".
- */
+* THE write path for the linked-devices keys — the `linked-devices` slot's
+* `set` lands here (D648). Normalizes the pick list and the tracked-event
+* opt-in; an EXPLICIT empty opt-in is stored as `[]`, never deleted, because
+* an absent key and an empty one are read alike today but only `[]` says the
+* operator chose "none".
+*/
 export declare function applyLinkedDevicesPatch(pctx: LinkedDevicesStoreAccess, deviceId: number, patch: Record<string, unknown>): Promise<{
-    success: true;
+	success: true;
 }>;
 /** The one field a pick is judged by. */
 export interface LinkedPickDevice {
-    readonly type: string;
+	readonly type: string;
 }
 /** What `refusedLinkedPicks` judges: the write, and what it is judged against. */
 export interface LinkedPicksInput {
-    readonly selfId: number;
-    readonly picked: readonly number[];
-    readonly persisted: readonly number[];
-    readonly fleet: ReadonlyMap<number, LinkedPickDevice>;
+	readonly selfId: number;
+	readonly picked: readonly number[];
+	readonly persisted: readonly number[];
+	readonly fleet: ReadonlyMap<number, LinkedPickDevice>;
 }
 /** One refused pick, named — the refusal message is built from these. */
 export interface LinkedPickRefusal {
-    readonly deviceId: number;
-    readonly reason: 'self' | 'container' | 'unknown';
+	readonly deviceId: number;
+	readonly reason: "self" | "container" | "unknown";
 }
 /**
- * Which NEW picks a linked-devices write must refuse: the camera itself, a
- * container (never a pick — its children are, D356 and the file header), and
- * an id no device has.
- *
- * Only ids that are not ALREADY persisted are judged. A list written before
- * this rule existed may hold a container or a device that has since been
- * deleted; the editor shows those as unavailable / missing, and keeping them
- * is not a new link. Removing them is the operator's call, never this
- * function's (a missing source is shown, never silently dropped).
- *
- * Since D655 every write of the list goes through the slot, the Locations
- * page's room rebuild included, so this is the only gate a pick passes.
- */
+* Which NEW picks a linked-devices write must refuse: the camera itself, a
+* container (never a pick — its children are, D356 and the file header), and
+* an id no device has.
+*
+* Only ids that are not ALREADY persisted are judged. A list written before
+* this rule existed may hold a container or a device that has since been
+* deleted; the editor shows those as unavailable / missing, and keeping them
+* is not a new link. Removing them is the operator's call, never this
+* function's (a missing source is shown, never silently dropped).
+*
+* Since D655 every write of the list goes through the slot, the Locations
+* page's room rebuild included, so this is the only gate a pick passes.
+*/
 export declare function refusedLinkedPicks(params: LinkedPicksInput): readonly LinkedPickRefusal[];