@camstack/system 1.2.389 → 1.2.391

package/dist/builtins/device-manager/runtime-state-persist-gate.d.ts

@@ -1,36 +1,64 @@
-import { RuntimeStatePolicy } from '@camstack/types';
+/**
+* The two pure predicates that decide whether a runtime-state change is worth a
+* SQLite commit. Separated from `DeviceStateMirror` so they can be tested
+* without a mirror, a settings store or a timer.
+*
+* ── Why a gate at all ──────────────────────────────────────────────────────
+* The cost model for `camstack.db` is not bytes and not rows — it is how many
+* commits you offer to the WAL-checkpoint lottery on a FUSE share (D96: p50
+* 0.14 ms for the statement, up to 25 s for the unlucky commit that enters a
+* checkpoint). Runtime state at full fleet activity offers 12–19 commits/s,
+* measured, to maintain 161 KB of state.
+*
+* Two of those commits in three come from caps whose restored value is worth
+* nothing, and about half of what is left comes from a device rewriting its
+* blob to record that it re-read a value that had not moved.
+*
+* ── Why not the mirror's existing `shallowEqual` ───────────────────────────
+* `shallowEqual` is reference equality (`a[k] !== b[k]`). The stored value is
+* the output of `schema.parse` — fresh nested allocations — and the incoming
+* value is a fresh deserialisation, so any slice with an object or array field
+* never dedupes. That is 25+ of the 62 runtime-state caps, including `zones`,
+* `zone-rules`, `camera-streams`, `feature-probe` and `privacy-mask`.
+*
+* The mirror keeps `shallowEqual`: it decides whether to EMIT, and an emit is
+* cheap and must stay eager (`createRuntimeStateBridge.ensureFresh` detects a
+* successful refresh by a clock field advancing — suppress that and a refresh
+* looks like a failure). These predicates decide only whether to WRITE.
+*/
+import type { RuntimeStatePolicy } from "@camstack/types";
 /** Resolves the declared policy for a cap name. */
 export type RuntimeStatePolicyLookup = (capName: string) => RuntimeStatePolicy;
 /** A device's cap-keyed slice map, as mirrored and as persisted. */
 export type RuntimeStateBlob = Readonly<Record<string, Readonly<Record<string, unknown>>>>;
 /**
- * The subset of `blob` that is allowed on disk: slices whose capability
- * declared `durability: 'restored'`.
- *
- * A cap the lookup does not know resolves to `'session'` and is dropped. That
- * direction is deliberate: the cost of losing a session value is a cold window
- * until the provider republishes; the cost of persisting an unasked-for one is
- * a commit per second on the fleet's busiest write path.
- *
- * `$owned` is not a cap: it is the device's claims record (D663) and is kept
- * whatever the lookup says — a restart that forgot who owns a field would hand
- * it back to the native provider.
- */
+* The subset of `blob` that is allowed on disk: slices whose capability
+* declared `durability: 'restored'`.
+*
+* A cap the lookup does not know resolves to `'session'` and is dropped. That
+* direction is deliberate: the cost of losing a session value is a cold window
+* until the provider republishes; the cost of persisting an unasked-for one is
+* a commit per second on the fleet's busiest write path.
+*
+* `$owned` is not a cap: it is the device's claims record (D663) and is kept
+* whatever the lookup says — a restart that forgot who owns a field would hand
+* it back to the native provider.
+*/
 export declare function persistableBlob(blob: RuntimeStateBlob, policyFor: RuntimeStatePolicyLookup): Record<string, Record<string, unknown>>;
 /**
- * Are two slices the same, ignoring the fields the cap declared volatile?
- *
- * A volatile field is still WRITTEN — it simply does not, on its own, justify
- * the write. A field the cap did NOT declare volatile is content, even when its
- * name looks like a clock: the capability is the only authority on which of its
- * fields carry meaning (D4), and the guard makes an undeclared clock visible in
- * the diff rather than assuming it.
- */
+* Are two slices the same, ignoring the fields the cap declared volatile?
+*
+* A volatile field is still WRITTEN — it simply does not, on its own, justify
+* the write. A field the cap did NOT declare volatile is content, even when its
+* name looks like a clock: the capability is the only authority on which of its
+* fields carry meaning (D4), and the guard makes an undeclared clock visible in
+* the diff rather than assuming it.
+*/
 export declare function sliceEffectivelyEqual(a: Readonly<Record<string, unknown>>, b: Readonly<Record<string, unknown>>, volatileFields: readonly string[]): boolean;
 /**
- * Is the whole persistable blob unchanged in every way that matters?
- *
- * A cap slice APPEARING or DISAPPEARING is always a change — the write is a
- * whole-blob replace, so a dropped slice only leaves disk if the write happens.
- */
+* Is the whole persistable blob unchanged in every way that matters?
+*
+* A cap slice APPEARING or DISAPPEARING is always a change — the write is a
+* whole-blob replace, so a dropped slice only leaves disk if the write happens.
+*/
 export declare function effectivelyEqual(before: RuntimeStateBlob, after: RuntimeStateBlob, policyFor: RuntimeStatePolicyLookup): boolean;

package/dist/builtins/device-manager/secret-config-paths.d.ts

@@ -1,24 +1,24 @@
 /**
- * The secret config paths each device DECLARES (D783) — `connection.password`,
- * `localKey`, `rows[].token` — as its runner last reported them at
- * `registerDevice`.
- *
- * In memory on purpose: a runner re-registers every device it owns whenever it
- * (re)starts, and a hub-main restart restarts every runner, so the map refills
- * on its own. Until a device has registered, its `DeviceInfo` carries no paths
- * and the non-admin redaction falls back to its keyword backstop — never to
- * "no redaction". Paths only; never a value.
- */
+* The secret config paths each device DECLARES (D783) — `connection.password`,
+* `localKey`, `rows[].token` — as its runner last reported them at
+* `registerDevice`.
+*
+* In memory on purpose: a runner re-registers every device it owns whenever it
+* (re)starts, and a hub-main restart restarts every runner, so the map refills
+* on its own. Until a device has registered, its `DeviceInfo` carries no paths
+* and the non-admin redaction falls back to its keyword backstop — never to
+* "no redaction". Paths only; never a value.
+*/
 export interface SecretConfigPathRegistry {
-    /** The paths last reported for `deviceId`, or `undefined` when none were. */
-    get(deviceId: number): readonly string[] | undefined;
-    /** Replace the paths for `deviceId` with the runner's latest report. */
-    set(deviceId: number, paths: readonly string[]): void;
-    /** Forget a removed device. */
-    delete(deviceId: number): void;
+	/** The paths last reported for `deviceId`, or `undefined` when none were. */
+	get(deviceId: number): readonly string[] | undefined;
+	/** Replace the paths for `deviceId` with the runner's latest report. */
+	set(deviceId: number, paths: readonly string[]): void;
+	/** Forget a removed device. */
+	delete(deviceId: number): void;
 }
 export declare function createSecretConfigPathRegistry(): SecretConfigPathRegistry;
 /** `{ secretConfigPaths }` when any are known, `{}` otherwise — spread into a `DeviceInfo`. */
 export declare function secretConfigPathsField(paths: readonly string[] | undefined): {
-    secretConfigPaths?: string[];
+	secretConfigPaths?: string[];
 };

package/dist/builtins/device-manager/stale-wrapper-activations.d.ts

@@ -1,32 +1,59 @@
-import { IScopedLogger } from '@camstack/types';
-import { DeviceBindingsStore } from './device-meta-types.js';
 /**
- * True when `capName` is a declared COLLECTION cap: its owners are derived by
- * `getBindings` step 0 and it persists no activation (D556), so a stored row
- * for it is never an owner.
- */
+* A stored wrapper activation that names a cap with NO wrapper any more.
+*
+* `deviceBindings[device][cap].wrapperAddonId` is the operator's choice of a
+* wrapper. When a wrapper is RETIRED (the `virtual-doorbell` on `doorbell`,
+* slice 6, D671), its rows outlive it: nothing deletes them (spec S1 — the
+* cluster is not written by code), and the admin UI no longer offers a toggle
+* for a cap that is not a wrapper cap. Routed as before, such a row shadows
+* the device's native (a composed doorbell) behind an addon that no longer
+* exists, keeps the cap advertised to HA / HAP / Alexa, and refuses every
+* call — without a line (task 17 review M1, D391).
+*
+* So the row is judged against the cap's DECLARED definition — static at boot,
+* never the live registry, because a wrapper runner that is still starting must
+* not read as stale. A string `wrapperAddonId` on a cap that is declared and is
+* not `kind: 'wrapper'` is treated as ABSENT: the cap resolves to its native
+* (or to nothing), exactly as if the row were not there. That loses no
+* doorbell: with a native, the native serves it; without one, the retired
+* addon could not serve it either. A cap this build does not declare is NOT
+* judged (unknown is not stale).
+*
+* It is said once per (device, cap) per process, by name, with the call that
+* clears the row. The whole store is checked once per process, read-only, so a
+* device nobody asks about is still named; a read that fails changes nothing,
+* says it could not check, and the next answered read checks instead (D49).
+* Generic on purpose: the next wrapper retirement gets the same backstop.
+*/
+import { type IScopedLogger } from "@camstack/types";
+import type { DeviceBindingsStore } from "./device-meta-types.js";
+/**
+* True when `capName` is a declared COLLECTION cap: its owners are derived by
+* `getBindings` step 0 and it persists no activation (D556), so a stored row
+* for it is never an owner.
+*/
 export declare function isDeclaredCollectionCap(capName: string): boolean;
 /** A persisted activation of a wrapper on a cap that has none (see module docblock). */
 export declare function isRetiredWrapperActivation(capName: string, wrapperAddonId: string | null | undefined): wrapperAddonId is string;
 /**
- * The per-process memory: which (device, cap) rows have been said, and whether
- * the whole store has been checked once. Owned by the device-manager instance.
- */
+* The per-process memory: which (device, cap) rows have been said, and whether
+* the whole store has been checked once. Owned by the device-manager instance.
+*/
 export declare class StaleWrapperActivations {
-    private readonly logger;
-    private readonly said;
-    private checked;
-    constructor(logger: IScopedLogger);
-    /** Say one row, once per process. */
-    report(deviceId: number, capName: string, wrapperAddonId: string): void;
-    /**
-     * Check a store that was already READ (by a bindings pass) — once per
-     * process. It never throws: it runs inside every bindings pass and under the
-     * boot `void` promise, so a corrupt entry (a null device or row, a hand edit,
-     * a partial write) is skipped — a row it cannot read is not one it can judge
-     * (re-review N1).
-     */
-    checkStore(store: DeviceBindingsStore): void;
-    /** Read the store (read-only) and check it; a failed read changes nothing. */
-    checkOnce(read: () => Promise<DeviceBindingsStore>): Promise<void>;
+	private readonly logger;
+	private readonly said;
+	private checked;
+	constructor(logger: IScopedLogger);
+	/** Say one row, once per process. */
+	report(deviceId: number, capName: string, wrapperAddonId: string): void;
+	/**
+	* Check a store that was already READ (by a bindings pass) — once per
+	* process. It never throws: it runs inside every bindings pass and under the
+	* boot `void` promise, so a corrupt entry (a null device or row, a hand edit,
+	* a partial write) is skipped — a row it cannot read is not one it can judge
+	* (re-review N1).
+	*/
+	checkStore(store: DeviceBindingsStore): void;
+	/** Read the store (read-only) and check it; a failed read changes nothing. */
+	checkOnce(read: () => Promise<DeviceBindingsStore>): Promise<void>;
 }

package/dist/builtins/device-manager/write-lock.d.ts

@@ -1,17 +1,17 @@
 /**
- * The promise-chain mutex the device-manager orders its read-modify-writes
- * with.
- *
- * One owner at a time, FIFO, no timers and no timeout: a waiter is parked on
- * the previous holder's completion, so nothing is delayed that was not already
- * waiting for a store round trip. A rejected holder still releases the chain —
- * a failed write must not wedge every writer behind it.
- *
- * Extracted from `DeviceMetaStore.withMetaWriteLock`, which was the only
- * instance until the addon's OWN settings row set needed the same ordering.
- * Two subtly different copies of a mutex is not a thing this file wants to
- * exist.
- */
+* The promise-chain mutex the device-manager orders its read-modify-writes
+* with.
+*
+* One owner at a time, FIFO, no timers and no timeout: a waiter is parked on
+* the previous holder's completion, so nothing is delayed that was not already
+* waiting for a store round trip. A rejected holder still releases the chain —
+* a failed write must not wedge every writer behind it.
+*
+* Extracted from `DeviceMetaStore.withMetaWriteLock`, which was the only
+* instance until the addon's OWN settings row set needed the same ordering.
+* Two subtly different copies of a mutex is not a thing this file wants to
+* exist.
+*/
 /** Run `fn` with exclusive ownership of one lock. */
 export type WriteLock = <T>(fn: () => Promise<T>) => Promise<T>;
 export declare function createWriteLock(): WriteLock;

package/dist/builtins/hub-forwarder/hub-forwarder-destination.d.ts

@@ -1,44 +1,44 @@
-import { IClusterBroker, ILogDestination, IScopedLogger, LogEntry, LogFilter } from '@camstack/types';
+import type { IClusterBroker, ILogDestination, IScopedLogger, LogEntry, LogFilter } from "@camstack/types";
 /**
- * Log destination for agent mode.
- *
- * - Writes to console ONLY when hub is not yet reachable (cold-start
- *   fallback). Forked-worker agents share stdout with their parent
- *   hub, so logging to local console AND forwarding to hub's
- *   `log-receiver` would print the entry twice on the hub terminal.
- *   Once the hub is discovered, local console output stops and the
- *   hub's own ConsoleDestination owns the render.
- * - When a Moleculer broker is connected and the hub node is reachable,
- *   forwards every log entry to the hub via `log-receiver.ingest`.
- * - Entries written before the hub is reachable are buffered internally
- *   (ring-buffered to `DEFAULT_OUTBOUND_BUFFER_SIZE`) and flushed on connect,
- *   so boot-time logs still reach the hub without any external replay trigger.
- */
+* Log destination for agent mode.
+*
+* - Writes to console ONLY when hub is not yet reachable (cold-start
+*   fallback). Forked-worker agents share stdout with their parent
+*   hub, so logging to local console AND forwarding to hub's
+*   `log-receiver` would print the entry twice on the hub terminal.
+*   Once the hub is discovered, local console output stops and the
+*   hub's own ConsoleDestination owns the render.
+* - When a Moleculer broker is connected and the hub node is reachable,
+*   forwards every log entry to the hub via `log-receiver.ingest`.
+* - Entries written before the hub is reachable are buffered internally
+*   (ring-buffered to `DEFAULT_OUTBOUND_BUFFER_SIZE`) and flushed on connect,
+*   so boot-time logs still reach the hub without any external replay trigger.
+*/
 export declare class HubForwarderDestination implements ILogDestination {
-    private broker;
-    private hubConnected;
-    private readonly outboundBuffer;
-    private statusLogger;
-    initialize(): Promise<void>;
-    /**
-     * Provide a logger for the destination's own status messages
-     * (discovery, disconnect, reconnect). Routed through the agent's
-     * LogManager but never through this same destination — the owning
-     * addon must hand in a logger that does NOT route back here, or
-     * status writes will recurse.
-     */
-    setStatusLogger(logger: IScopedLogger): void;
-    private status;
-    /**
-     * Attach the Moleculer broker so hub forwarding can start.
-     * Called by the owning addon from `onInitialize(ctx)` with
-     * `ctx.kernel.cluster?.broker`.
-     */
-    connectBroker(broker: IClusterBroker): void;
-    write(entry: LogEntry): void;
-    query(_filter: LogFilter): Promise<readonly LogEntry[]>;
-    shutdown(): Promise<void>;
-    private bufferOutbound;
-    private flushOutbound;
-    private forward;
+	private broker;
+	private hubConnected;
+	private readonly outboundBuffer;
+	private statusLogger;
+	initialize(): Promise<void>;
+	/**
+	* Provide a logger for the destination's own status messages
+	* (discovery, disconnect, reconnect). Routed through the agent's
+	* LogManager but never through this same destination — the owning
+	* addon must hand in a logger that does NOT route back here, or
+	* status writes will recurse.
+	*/
+	setStatusLogger(logger: IScopedLogger): void;
+	private status;
+	/**
+	* Attach the Moleculer broker so hub forwarding can start.
+	* Called by the owning addon from `onInitialize(ctx)` with
+	* `ctx.kernel.cluster?.broker`.
+	*/
+	connectBroker(broker: IClusterBroker): void;
+	write(entry: LogEntry): void;
+	query(_filter: LogFilter): Promise<readonly LogEntry[]>;
+	shutdown(): Promise<void>;
+	private bufferOutbound;
+	private flushOutbound;
+	private forward;
 }

package/dist/builtins/hub-forwarder/hub-forwarder.addon.d.ts

@@ -1,15 +1,16 @@
-import { ProviderRegistration, BaseAddon } from '@camstack/types';
-import { HubForwarderDestination } from './hub-forwarder-destination.js';
+import type { ProviderRegistration } from "@camstack/types";
+import { BaseAddon } from "@camstack/types";
+import { HubForwarderDestination } from "./hub-forwarder-destination.js";
 /**
- * Agent-only addon that provides the `log-destination` capability.
- * Writes all logs to the console and forwards to the hub via Moleculer when
- * reachable. The broker is read from `ctx.kernel.cluster?.broker`; outbound
- * log replay on hub-connect is handled internally by the destination.
- */
+* Agent-only addon that provides the `log-destination` capability.
+* Writes all logs to the console and forwards to the hub via Moleculer when
+* reachable. The broker is read from `ctx.kernel.cluster?.broker`; outbound
+* log replay on hub-connect is handled internally by the destination.
+*/
 export declare class HubForwarderAddon extends BaseAddon {
-    private destination;
-    constructor();
-    protected onInitialize(): Promise<ProviderRegistration[]>;
-    getDestination(): HubForwarderDestination | null;
-    protected onShutdown(): Promise<void>;
+	private destination;
+	constructor();
+	protected onInitialize(): Promise<ProviderRegistration[]>;
+	getDestination(): HubForwarderDestination | null;
+	protected onShutdown(): Promise<void>;
 }

package/dist/builtins/hub-forwarder/index.d.ts

@@ -1,3 +1,3 @@
-export { HubForwarderAddon } from './hub-forwarder.addon.js';
-export { HubForwarderAddon as default } from './hub-forwarder.addon.js';
-export { HubForwarderDestination } from './hub-forwarder-destination.js';
+export { HubForwarderAddon } from "./hub-forwarder.addon.js";
+export { HubForwarderAddon as default } from "./hub-forwarder.addon.js";
+export { HubForwarderDestination } from "./hub-forwarder-destination.js";

package/dist/builtins/keychain/index.d.ts

@@ -1 +1 @@
-export { KeychainAddon, default } from './keychain.addon.js';
+export { KeychainAddon, default } from "./keychain.addon.js";

package/dist/builtins/keychain/key-sources.d.ts

@@ -1,37 +1,37 @@
-import { KeychainKeySource } from '@camstack/types';
+import type { KeychainKeySource } from "@camstack/types";
 /** The `keychain` section of `config.yaml`. */
 export interface KeychainKeyConfig {
-    readonly keyFile?: string | undefined;
-    readonly previousKeyFile?: string | undefined;
+	readonly keyFile?: string | undefined;
+	readonly previousKeyFile?: string | undefined;
 }
 export type KeyLoadResult = {
-    readonly kind: 'loaded';
-    readonly key: Buffer;
+	readonly kind: "loaded";
+	readonly key: Buffer;
 } | {
-    readonly kind: 'absent';
+	readonly kind: "absent";
 } | {
-    readonly kind: 'unreadable';
-    readonly error: string;
+	readonly kind: "unreadable";
+	readonly error: string;
 };
 export interface KeySourceCandidate {
-    readonly source: KeychainKeySource;
-    readonly primary: boolean;
-    load(): Promise<KeyLoadResult>;
+	readonly source: KeychainKeySource;
+	readonly primary: boolean;
+	load(): Promise<KeyLoadResult>;
 }
 /** The default key file's location under the data root. */
 export declare function defaultKeyFilePath(dataDir: string): string;
 export interface KeySourceOptions {
-    readonly config: KeychainKeyConfig;
-    readonly dataDir: string;
+	readonly config: KeychainKeyConfig;
+	readonly dataDir: string;
 }
 /** Every candidate, primary first. */
 export declare function buildKeySourceCandidates(opts: KeySourceOptions): readonly KeySourceCandidate[];
 /**
- * Write a master key to the default location: directory 0700, file 0600,
- * atomically (temp + rename), never over an existing file unless `replace`.
- * Returns the previous file's new name when one was moved aside.
- */
+* Write a master key to the default location: directory 0700, file 0600,
+* atomically (temp + rename), never over an existing file unless `replace`.
+* Returns the previous file's new name when one was moved aside.
+*/
 export declare function writeDefaultKeyFile(dataDir: string, key: Buffer, opts: {
-    readonly replace: boolean;
-    readonly nowMs: number;
+	readonly replace: boolean;
+	readonly nowMs: number;
 }): Promise<string | null>;

package/dist/builtins/keychain/keychain-crypto.d.ts

@@ -10,10 +10,10 @@ export declare function shortFingerprint(fingerprint: string): string;
 /** Constant-time string equality (lengths may differ). */
 export declare function constantTimeEquals(a: string, b: string): boolean;
 /**
- * Key material from a key file: base64 (the format we write) or hex of
- * exactly 32 bytes, surrounding whitespace ignored. Anything else is `null` —
- * a file holding a password or a PEM is refused, never stretched into a key.
- */
+* Key material from a key file: base64 (the format we write) or hex of
+* exactly 32 bytes, surrounding whitespace ignored. Anything else is `null` —
+* a file holding a password or a PEM is refused, never stretched into a key.
+*/
 export declare function decodeKeyMaterial(text: string): Buffer | null;
 export declare function encodeKeyMaterial(key: Buffer): string;
 /** Wrap a data key under a master key. */

package/dist/builtins/keychain/keychain-reset-trigger.d.ts

@@ -1,25 +1,25 @@
-import { KeychainResetRecord } from '@camstack/types';
-import { KeychainLogger, KeychainService } from './keychain-service.js';
+import { type KeychainResetRecord } from "@camstack/types";
+import type { KeychainLogger, KeychainService } from "./keychain-service.js";
 /** The trigger's name, inside `<dataDir>/.keychain/`. */
 export declare const KEYCHAIN_RESET_TRIGGER = "RESET_KEYCHAIN";
 export declare function keychainResetTriggerPath(dataDir: string): string;
 export type KeychainResetTriggerOutcome = {
-    readonly kind: 'absent';
+	readonly kind: "absent";
 } | {
-    readonly kind: 'ignored-unlocked';
+	readonly kind: "ignored-unlocked";
 } | {
-    readonly kind: 'deferred';
-    readonly reason: string;
+	readonly kind: "deferred";
+	readonly reason: string;
 } | {
-    readonly kind: 'refused';
-    readonly error: string;
+	readonly kind: "refused";
+	readonly error: string;
 } | {
-    readonly kind: 'reset';
-    readonly record: KeychainResetRecord;
+	readonly kind: "reset";
+	readonly record: KeychainResetRecord;
 };
 export interface KeychainResetTriggerInput {
-    readonly service: Pick<KeychainService, 'getState' | 'resetAs' | 'resetReport'>;
-    readonly dataDir: string;
-    readonly logger: KeychainLogger;
+	readonly service: Pick<KeychainService, "getState" | "resetAs" | "resetReport">;
+	readonly dataDir: string;
+	readonly logger: KeychainLogger;
 }
 export declare function applyKeychainResetTrigger(input: KeychainResetTriggerInput): Promise<KeychainResetTriggerOutcome>;