@camstack/system 1.2.390 → 1.2.392

package/dist/kernel/status-overlay.d.ts

@@ -1,18 +1,38 @@
-import { StatusOverlay, StatusOverlayAnswer } from '@camstack/types';
+/**
+* status-overlay.ts — the D13 overlay for a CLAIMED cap's `getStatus` (D663,
+* ruling S3).
+*
+* When a composition or a customization claims fields of a device's cap, the
+* hub mirror holds the merged truth and the native provider's own `getStatus`
+* is the wrong answer for EVERY caller — the tRPC router, the status aggregate,
+* a wrapper's `native: true` call, an exporter polling from a forked child.
+* The registry's per-device resolvers wrap the provider they would have
+* returned (here); the three transport entries that resolve a cap call by name
+* ask the same question through `transport/claimed-get-status.ts`. Both import
+* the types from here so neither imports the other.
+*
+* The wrap is a `Proxy`, never a spread. The HA feeder's native is built by the
+* hub's `nativeFallback` as `new Proxy({}, { get })`: an EMPTY target whose
+* every property is a forwarding function. Its spread is `{}` — `wakeForStream`
+* and `reset` vanish and `requireDeviceScoped` answers NOT_IMPLEMENTED for every
+* non-status method of a claimed cap. A class-instance provider loses its
+* prototype methods the same way.
+*/
+import type { StatusOverlay, StatusOverlayAnswer } from "@camstack/types";
 export type { StatusOverlay, StatusOverlayAnswer };
 /** The answer for a device KNOWN to carry no claim — the old path, no overlay. */
 export declare const UNCLAIMED: StatusOverlayAnswer;
 /** Resolves the device's claims first, then answers. What every consumer awaits. */
 export type ClaimedStatusResolver = (capName: string, deviceId: number) => Promise<StatusOverlayAnswer>;
 /**
- * Wrap `provider` so that `getStatus` awaits the overlay, re-read at CALL time
- * (a claim released between resolve and call falls back to the native's own
- * `getStatus`; a device whose claims are not yet known has them resolved
- * first), and every other property is the provider's own.
- *
- * Other properties are read off the TARGET with the target as receiver, and a
- * function is bound to it: a class instance's methods then see their real
- * `this` — a Proxy as `this` would break `#private` fields and prototype
- * getters. The HA-shaped forwarding Proxy is unaffected either way.
- */
+* Wrap `provider` so that `getStatus` awaits the overlay, re-read at CALL time
+* (a claim released between resolve and call falls back to the native's own
+* `getStatus`; a device whose claims are not yet known has them resolved
+* first), and every other property is the provider's own.
+*
+* Other properties are read off the TARGET with the target as receiver, and a
+* function is bound to it: a class instance's methods then see their real
+* `this` — a Proxy as `this` would break `#private` fields and prototype
+* getters. The HA-shaped forwarding Proxy is unaffected either way.
+*/
 export declare function overlayGetStatus<T extends object>(provider: T, answer: () => Promise<StatusOverlayAnswer>): T;

package/dist/kernel/storage-location-registry.d.ts

@@ -1,55 +1,55 @@
-import { StorageAccess, StorageLocationDeclaration } from '@camstack/types';
+import type { StorageAccess, StorageLocationDeclaration } from "@camstack/types";
 /**
- * Read-only view over all aggregated storage-location declarations.
- *
- * Built at kernel boot by {@link buildStorageLocationRegistry} from the
- * `storageLocations` arrays declared in each installed addon's manifest.
- */
+* Read-only view over all aggregated storage-location declarations.
+*
+* Built at kernel boot by {@link buildStorageLocationRegistry} from the
+* `storageLocations` arrays declared in each installed addon's manifest.
+*/
 export interface StorageLocationRegistry {
-    /** Returns the declaration for `id`, or `undefined` if not declared. */
-    get(id: string): StorageLocationDeclaration | undefined;
-    /** Returns `true` when at least one addon declared `id`. */
-    has(id: string): boolean;
-    /**
-     * Returns the cardinality of `id`, or `null` when no addon declared it.
-     * Convenience shortcut over `get(id)?.cardinality`.
-     */
-    cardinalityOf(id: string): 'single' | 'multi' | null;
-    /**
-     * The declared {@link StorageAccess} of `id`, or `null` when no addon
-     * declared it. An UNDECLARED `access` on a DECLARED id resolves to
-     * `STORAGE_ACCESS_FALLBACK` (`'local-path'`) — fail-closed, so a kind that
-     * says nothing is treated as doing raw filesystem I/O and refuses a remote
-     * provider. `null` is reserved for "nobody declared this id at all", which
-     * callers treat separately.
-     */
-    accessOf(id: string): StorageAccess | null;
-    /**
-     * Stable, immutable list of all aggregated declarations (insertion order of
-     * first occurrence per `id`).
-     */
-    list(): readonly StorageLocationDeclaration[];
+	/** Returns the declaration for `id`, or `undefined` if not declared. */
+	get(id: string): StorageLocationDeclaration | undefined;
+	/** Returns `true` when at least one addon declared `id`. */
+	has(id: string): boolean;
+	/**
+	* Returns the cardinality of `id`, or `null` when no addon declared it.
+	* Convenience shortcut over `get(id)?.cardinality`.
+	*/
+	cardinalityOf(id: string): "single" | "multi" | null;
+	/**
+	* The declared {@link StorageAccess} of `id`, or `null` when no addon
+	* declared it. An UNDECLARED `access` on a DECLARED id resolves to
+	* `STORAGE_ACCESS_FALLBACK` (`'local-path'`) — fail-closed, so a kind that
+	* says nothing is treated as doing raw filesystem I/O and refuses a remote
+	* provider. `null` is reserved for "nobody declared this id at all", which
+	* callers treat separately.
+	*/
+	accessOf(id: string): StorageAccess | null;
+	/**
+	* Stable, immutable list of all aggregated declarations (insertion order of
+	* first occurrence per `id`).
+	*/
+	list(): readonly StorageLocationDeclaration[];
 }
 /**
- * Aggregates per-addon {@link StorageLocationDeclaration} arrays into a single
- * {@link StorageLocationRegistry}.
- *
- * Merge rules:
- * - Declarations are keyed by `id`; iteration order follows first occurrence.
- * - **First declarer wins** for metadata (`displayName`, `description`,
- *   `defaultsTo`): if a later addon declares the same `id`, its metadata is
- *   silently ignored.
- * - **Cardinality conflict throws**: if two addons declare the same `id` with
- *   different `cardinality` values an `Error` is thrown immediately (message
- *   contains the words "cardinality" and the conflicting `id`).
- * - **Access conflict throws**, for the same reason and more sharply: the
- *   EFFECTIVE access (declared, else `STORAGE_ACCESS_FALLBACK`) must agree.
- *   "First declarer wins" is the right rule for a display name and a
- *   catastrophic one for a safety constraint — it would let a second addon
- *   silently widen a kind that the first one restricted, which is exactly the
- *   accident this constraint exists to make impossible.
- *
- * @param perAddon - One entry per addon; each entry is that addon's
- *   `storageLocations` declaration array.
- */
+* Aggregates per-addon {@link StorageLocationDeclaration} arrays into a single
+* {@link StorageLocationRegistry}.
+*
+* Merge rules:
+* - Declarations are keyed by `id`; iteration order follows first occurrence.
+* - **First declarer wins** for metadata (`displayName`, `description`,
+*   `defaultsTo`): if a later addon declares the same `id`, its metadata is
+*   silently ignored.
+* - **Cardinality conflict throws**: if two addons declare the same `id` with
+*   different `cardinality` values an `Error` is thrown immediately (message
+*   contains the words "cardinality" and the conflicting `id`).
+* - **Access conflict throws**, for the same reason and more sharply: the
+*   EFFECTIVE access (declared, else `STORAGE_ACCESS_FALLBACK`) must agree.
+*   "First declarer wins" is the right rule for a display name and a
+*   catastrophic one for a safety constraint — it would let a second addon
+*   silently widen a kind that the first one restricted, which is exactly the
+*   accident this constraint exists to make impossible.
+*
+* @param perAddon - One entry per addon; each entry is that addon's
+*   `storageLocations` declaration array.
+*/
 export declare function buildStorageLocationRegistry(perAddon: readonly (readonly StorageLocationDeclaration[])[]): StorageLocationRegistry;

package/dist/kernel/store-settings-view.d.ts

@@ -1,17 +1,17 @@
-import { SettingsViewBackend } from './settings-view-types.js';
+import type { SettingsViewBackend } from "./settings-view-types.js";
 /** The `ConfigManager` surface this backend reads and writes through. */
 export interface StoreViewHost {
-    hasSyncStore(): boolean;
-    getBootstrap(configPath: string): unknown;
-    getAddonConfig(addonId: string): Record<string, unknown>;
-    setAddonConfig(addonId: string, config: Record<string, unknown>): void;
-    getAddonDevice(addonId: string, deviceId: string): Record<string, unknown>;
-    setAddonDevice(addonId: string, deviceId: string, values: Record<string, unknown>): void;
-    clearAddonDevice(addonId: string, deviceId: string): void;
-    getDeviceRuntimeState(deviceId: string): Record<string, unknown>;
-    setDeviceRuntimeState(deviceId: string, blob: Record<string, unknown>): void;
-    clearDeviceRuntimeState(deviceId: string): void;
-    getSection(section: string): Record<string, unknown>;
-    setSection(section: string, data: Record<string, unknown>): void;
+	hasSyncStore(): boolean;
+	getBootstrap(configPath: string): unknown;
+	getAddonConfig(addonId: string): Record<string, unknown>;
+	setAddonConfig(addonId: string, config: Record<string, unknown>): void;
+	getAddonDevice(addonId: string, deviceId: string): Record<string, unknown>;
+	setAddonDevice(addonId: string, deviceId: string, values: Record<string, unknown>): void;
+	clearAddonDevice(addonId: string, deviceId: string): void;
+	getDeviceRuntimeState(deviceId: string): Record<string, unknown>;
+	setDeviceRuntimeState(deviceId: string, blob: Record<string, unknown>): void;
+	clearDeviceRuntimeState(deviceId: string): void;
+	getSection(section: string): Record<string, unknown>;
+	setSection(section: string, data: Record<string, unknown>): void;
 }
 export declare function createStoreSettingsView(addonId: string, cm: StoreViewHost): SettingsViewBackend;

package/dist/kernel/system-settings-mirror.d.ts

@@ -1,34 +1,46 @@
-import { ISettingsStoreProvider } from '@camstack/types';
+/**
+* The boot-time mirror of the few `system-settings` keys a SYNCHRONOUS reader
+* needs while the settings engine is isolated — D675.
+*
+* `ConfigManager.get` is synchronous and hub-main has only the async door
+* (D231). The capability registry's preference readers and the hub
+* `AuthService` still read synchronously, so the keys they need
+* (`PRELOADED_SYSTEM_PREFIXES` / `PRELOADED_SYSTEM_KEYS`) are read from the door
+* ONCE, when it is wired, into memory. No polling, no retry (D3): a failed read
+* stays failed until the next boot, and every reader is told so rather than
+* handed "unset".
+*/
+import type { ISettingsStoreProvider } from "@camstack/types";
 /** The outcome of the one boot read, for the caller that logs and replays it. */
 export type SystemSettingsPreload = {
-    readonly kind: 'loaded';
-    readonly keyCount: number;
+	readonly kind: "loaded";
+	readonly keyCount: number;
 } | {
-    readonly kind: 'failed';
-    readonly error: string;
+	readonly kind: "failed";
+	readonly error: string;
 };
 export declare class SystemSettingsMirror {
-    private state;
-    /** The door the current read belongs to; a replaced door owns the mirror. */
-    private door;
-    private preload;
-    /**
-     * Writes to preloaded keys made through THIS process. They win over the boot
-     * read (they are newer) and survive a failed one, so an operator's Save is
-     * reported back even when the boot read was lost.
-     */
-    private readonly writes;
-    /** Start the ONE read for `door`. Called by `ConfigManager.setSettingsDoor`. */
-    load(door: ISettingsStoreProvider): void;
-    /** The in-flight / settled boot read, or `null` before any door. */
-    whenLoaded(): Promise<SystemSettingsPreload> | null;
-    /**
-     * A preloaded key's value: `undefined` when the store holds none, or a THROW
-     * (`preload-pending` / `preload-failed`) when it is not known.
-     */
-    get(key: string): unknown;
-    /** Record a write to a preloaded key so the mirror reports it. */
-    noteWrite(key: string, value: unknown): void;
-    /** Every row under the preloaded prefixes plus each preloaded key. Never rejects. */
-    private read;
+	private state;
+	/** The door the current read belongs to; a replaced door owns the mirror. */
+	private door;
+	private preload;
+	/**
+	* Writes to preloaded keys made through THIS process. They win over the boot
+	* read (they are newer) and survive a failed one, so an operator's Save is
+	* reported back even when the boot read was lost.
+	*/
+	private readonly writes;
+	/** Start the ONE read for `door`. Called by `ConfigManager.setSettingsDoor`. */
+	load(door: ISettingsStoreProvider): void;
+	/** The in-flight / settled boot read, or `null` before any door. */
+	whenLoaded(): Promise<SystemSettingsPreload> | null;
+	/**
+	* A preloaded key's value: `undefined` when the store holds none, or a THROW
+	* (`preload-pending` / `preload-failed`) when it is not known.
+	*/
+	get(key: string): unknown;
+	/** Record a write to a preloaded key so the mirror reports it. */
+	noteWrite(key: string, value: unknown): void;
+	/** Every row under the preloaded prefixes plus each preloaded key. Never rejects. */
+	private read;
 }

package/dist/kernel/system-settings-policy.d.ts

@@ -1,46 +1,27 @@
-/**
- * Which `system-settings` keys the STORE may answer, and which the kernel
- * loads from the door into memory at boot — D675.
- *
- * ## The store never answers for a bootstrap section
- *
- * `system-settings` may still hold `auth.jwtSecret`, `auth.adminUsername` and
- * `auth.adminPassword` — written there by `local-auth` (and by older builds)
- * next to `auth.tokenExpiry`. Since D797 none of the three is a setting at
- * all (the signing key is the keychain's, the first-boot admin is fixed), and
- * the stale rows must still never answer: merging them back in would let a
- * stale DB copy stand in for a credential. The one-off ops script deletes them.
- *
- * So a bootstrap-owned section is answered from env + config.yaml ONLY, and
- * the store may add exactly the keys in {@link STORE_READABLE_BOOTSTRAP_KEYS}:
- * the values the operator edits on System → Authentication (`auth.tokenExpiry`,
- * `auth.accessTokenExpiry`, `auth.trustedProxies`). Widening this list is a security decision, not a
- * convenience.
- */
 /** The only keys under a bootstrap-owned section the store may answer. */
 export declare const STORE_READABLE_BOOTSTRAP_KEYS: ReadonlySet<string>;
 /** May the settings store answer `key`, or is it env + config.yaml only? */
 export declare function storeMayAnswer(key: string): boolean;
 /**
- * Key prefixes loaded from the door into memory ONCE at boot, so the
- * synchronous readers that need them (the capability registry's preference
- * readers, `capabilities.getPreference`) answer the persisted value after a
- * reboot. Capability preferences are the only prefix: every other synchronous
- * caller of `ConfigManager.get` either reads a bootstrap key or runs before the
- * door exists.
- */
+* Key prefixes loaded from the door into memory ONCE at boot, so the
+* synchronous readers that need them (the capability registry's preference
+* readers, `capabilities.getPreference`) answer the persisted value after a
+* reboot. Capability preferences are the only prefix: every other synchronous
+* caller of `ConfigManager.get` either reads a bootstrap key or runs before the
+* door exists.
+*/
 export declare const PRELOADED_SYSTEM_PREFIXES: readonly string[];
 /**
- * Single keys loaded the same way. `auth.tokenExpiry` is read synchronously on
- * every mint by the hub's `AuthService` (`AuthManager.signToken`), and
- * `auth.trustedProxies` on every public auth request (`auth-network-policy.ts`).
- */
+* Single keys loaded the same way. `auth.tokenExpiry` is read synchronously on
+* every mint by the hub's `AuthService` (`AuthManager.signToken`), and
+* `auth.trustedProxies` on every public auth request (`auth-network-policy.ts`).
+*/
 export declare const PRELOADED_SYSTEM_KEYS: readonly string[];
 /** Is `key` served from the boot-time mirror when the engine is isolated? */
 export declare function isPreloadedSystemKey(key: string): boolean;
 /**
- * The stored keys of `section` the store may answer (`storeMayAnswer`,
- * D675): everything for an ordinary section, only the allow-listed keys for a
- * bootstrap-owned one.
- */
+* The stored keys of `section` the store may answer (`storeMayAnswer`,
+* D675): everything for an ordinary section, only the allow-listed keys for a
+* bootstrap-owned one.
+*/
 export declare function filterStoreSection(section: string, stored: Record<string, unknown>): Record<string, unknown>;