@camstack/system 1.2.316 → 1.2.317

package/dist/kernel/bootstrap-config.d.ts

@@ -0,0 +1,8 @@
+import { AppConfig, BootstrapConfig } from './config-schema.js';
+/** config.yaml, env overrides applied, parsed. */
+export declare function loadBootstrapConfig(configPath: string): BootstrapConfig;
+export declare function writeBootstrapSection(configPath: string, section: string, data: Record<string, unknown>): BootstrapConfig;
+/**
+ * Returns a merged view of bootstrap config + runtime defaults for backward compat.
+ */
+export declare function buildRawAppConfig(bootstrapConfig: BootstrapConfig): AppConfig;

package/dist/kernel/capability-registry.d.ts

@@ -31,6 +31,17 @@ export type CollectionConfigReader = (capability: string) => readonly string[] |
  * cannot present it. See docs/decisions/adr-0188-an-unregister-carries-proof-of-ownership.md.
  */
 export type ProviderOwnerToken = string;
+/** What {@link CapabilityRegistry.applyPersistedPreferences} changed. */
+export interface PersistedPreferenceReplay {
+    readonly singletons: ReadonlyArray<{
+        readonly capability: string;
+        readonly addonId: string;
+    }>;
+    readonly disabled: ReadonlyArray<{
+        readonly capability: string;
+        readonly addonId: string;
+    }>;
+}
 export declare class CapabilityRegistry {
     private readonly capabilities;
     private readonly logger;
@@ -234,6 +245,25 @@ export declare class CapabilityRegistry {
      * successor's live registration ([D188](../../../../docs/decisions/adr-0188-an-unregister-carries-proof-of-ownership.md)).
      */
     unregisterProvider(capabilityName: string, addonId: string, owner?: ProviderOwnerToken): void;
+    /**
+     * Re-apply the operator's PERSISTED preferences to providers that
+     * registered before those preferences could be read — once, when the boot
+     * read of them settles (D675).
+     *
+     * `registerProvider` consults the preference readers at the moment a
+     * provider registers. With the settings engine isolated (D231) the
+     * preferences arrive over an async door, so a provider can register before
+     * they are known; the readers then answer "no preference" and the default
+     * wins. This replays the answer the readers give NOW over every registered
+     * provider: a singleton whose persisted choice is registered and not active
+     * is switched to it, and a collection provider the operator disabled is
+     * disabled again. It is one pass, triggered by the read settling — not a
+     * wait, a poll or a retry (D3).
+     *
+     * `skip` names the capabilities that must not be switched live (infra caps
+     * need a restart — the same rule `capabilities.setPreference` applies).
+     */
+    applyPersistedPreferences(skip: (capability: string) => boolean): PersistedPreferenceReplay;
     /** Enable a previously disabled collection provider. */
     enableCollectionProvider(capability: string, addonId: string): void;
     /** Disable a collection provider (keeps it registered but excluded from active list). */

package/dist/kernel/config-manager.d.ts

@@ -1,101 +1,16 @@
 import { AppConfig } from './config-schema.js';
-import { AddonStoreRead, FeatureManifest, ISettingsStoreProvider } from '@camstack/types';
-export interface AddonSettingsView {
-    readAddonStore(): Promise<Record<string, unknown>>;
-    /** See `IAddonContext['settings'].readAddonStoreResult` (D651). */
-    readAddonStoreResult?(): Promise<AddonStoreRead>;
-    writeAddonStore(patch: Record<string, unknown>): Promise<void>;
-    readDeviceStore(deviceId: number): Promise<Record<string, unknown>>;
-    /** See `IAddonContext['settings'].readDeviceStoreBatch` — optional there and
-     *  here for the same reason: only the door-backed view can answer it in one
-     *  range scan, and a caller must fall back rather than refuse. */
-    readDeviceStoreBatch?(deviceIds: readonly number[]): Promise<ReadonlyMap<number, Record<string, unknown>>>;
-    writeDeviceStore(deviceId: number, patch: Record<string, unknown>): Promise<void>;
-    clearDeviceStore(deviceId: number): Promise<void>;
-    getSection(section: string): Promise<Record<string, unknown>>;
-    setSection(section: string, patch: Record<string, unknown>): Promise<void>;
-    /**
-     * Per-device runtime state — separate namespace from
-     * `readDeviceStore` / `writeDeviceStore` (which is the addon's
-     * config blob: host, password, deviceCache, …). Holds mutable
-     * runtime signals discovered after boot: battery snapshot, sleep
-     * flag, last-seen timestamps. Stored under a kernel-internal
-     * `__device-state` namespace so the device's config schema
-     * never has to know about it (clean separation of operator
-     * intent from runtime telemetry).
-     *
-     * Patch semantics: shallow merge. Pass the FULL persistent slice
-     * each call (the kernel doesn't try to compute deltas) — concrete
-     * implementations of `DeviceRuntimeState` already coalesce in
-     * memory, so the kernel just persists the latest blob.
-     */
-    readDeviceRuntimeState(deviceId: number): Promise<Record<string, unknown>>;
-    writeDeviceRuntimeState(deviceId: number, data: Record<string, unknown>): Promise<void>;
-    clearDeviceRuntimeState(deviceId: number): Promise<void>;
-}
-/**
- * A CONCRETE backend behind {@link ConfigManager.createSettingsView} — the
- * sync-`ISettingsStore` one or the async-door one.
- *
- * `readDeviceStoreBatch` is required here and optional on
- * {@link AddonSettingsView} because both of these can answer it, so the view
- * the kernel hands an addon never has to decide whether the method exists.
- * The optionality on the public interface stays for the implementation that
- * genuinely cannot batch: a forked runner's UDS-backed view.
- */
-export interface SettingsViewBackend extends AddonSettingsView {
-    readDeviceStoreBatch(deviceIds: readonly number[]): Promise<ReadonlyMap<number, Record<string, unknown>>>;
-}
-export interface ISettingsStore {
-    getSystem(key: string): unknown;
-    setSystem(key: string, value: unknown): void;
-    getAllSystem(): Record<string, unknown>;
-    /** Addon-level global settings (apply to every device unless overridden). */
-    getAllAddon(addonId: string): Record<string, unknown>;
-    setAllAddon(addonId: string, config: Record<string, unknown>): void;
-    /** Legacy per-provider settings (used by some older wiring paths). */
-    getAllProvider(providerId: string): Record<string, unknown>;
-    setProvider(providerId: string, key: string, value: unknown): void;
-    /** Legacy flat per-device settings. Kept for backward compatibility
-     *  with pre-addon wiring; new code should use the addon-device API. */
-    getAllDevice(deviceId: string): Record<string, unknown>;
-    setDevice(deviceId: string, key: string, value: unknown): void;
-    /**
-     * Multi-level addon settings: per-device overrides for a specific addon.
-     *
-     * Resolution chain when the frontend asks for the effective value of a
-     * field on a given device:
-     *   1. schema default (from `ConfigUISchema.field.default`)
-     *   2. `getAllAddon(addonId)`           — addon global value
-     *   3. `getAddonDevice(addonId, devId)` — per-device override (wins)
-     *
-     * Only fields declared with `scope: 'device'` in the addon's
-     * `ConfigUISchema` should ever be persisted here.
-     */
-    getAddonDevice(addonId: string, deviceId: string): Record<string, unknown>;
-    setAddonDevice(addonId: string, deviceId: string, values: Record<string, unknown>): void;
-    clearAddonDevice(addonId: string, deviceId: string): void;
-    /**
-     * Per-device runtime state — the whole cap-slice map as ONE row in the
-     * `device-runtime-state` collection.
-     *
-     * These are separate from `getAddonDevice`/`setAddonDevice` because runtime
-     * state is not an addon's config: it belongs to the device, it is replaced
-     * wholesale on every flush, and it is written orders of magnitude more often.
-     * It USED to share that keyspace under a synthetic `__device-state` addonId,
-     * which cost one row (and one INSERT) per cap slice per flush and left the
-     * collection it is named for empty on every installation. The backend keeps
-     * reading the legacy prefix; see `SqliteSettingsBackend.getDeviceRuntimeState`.
-     */
-    getDeviceRuntimeState(deviceId: string): Record<string, unknown>;
-    setDeviceRuntimeState(deviceId: string, blob: Record<string, unknown>): void;
-    clearDeviceRuntimeState(deviceId: string): void;
-}
+import { FeatureManifest, ISettingsStoreProvider } from '@camstack/types';
+import { ISettingsStore, KernelAddonSettingsView } from './settings-view-types.js';
+import { SystemSettingsPreload } from './system-settings-mirror.js';
+export type { AddonSettingsView, ISettingsStore, KernelAddonSettingsView, SettingsViewBackend, } from './settings-view-types.js';
+export type { SystemSettingsPreload } from './system-settings-mirror.js';
 export declare class ConfigManager {
     private readonly configPath;
     private bootstrapConfig;
     private settingsStore;
     private settingsDoor;
+    /** Boot-time mirror of the preloaded `system-settings` keys (door mode, D675). */
+    private readonly systemMirror;
     constructor(configPath: string);
     /**
      * Wire the settings-store backend. Called once, after the `settings-store`
@@ -109,9 +24,25 @@ export declare class ConfigManager {
      * prefers the sync store when both are present.
      */
     setSettingsDoor(door: ISettingsStoreProvider): void;
+    /**
+     * Resolves once the boot read of the preloaded `system-settings` keys has
+     * settled — the hook the addon registry uses to log it and to replay the
+     * capability preferences onto providers that registered before it (D675).
+     * `null` when no door has been wired (a sync store needs no preload).
+     */
+    whenSystemSettingsPreloaded(): Promise<SystemSettingsPreload> | null;
+    private backendMode;
+    /** The refusal every sync addon-scoped reader raises without a sync store. */
+    private refuseSyncRead;
     /**
      * Get a config value by dot-notation path.
-     * Priority: bootstrap config (yaml) → settings-store → RUNTIME_DEFAULTS fallback.
+     * Priority: bootstrap config (yaml + env) → settings-store → RUNTIME_DEFAULTS.
+     *
+     * The store layer (D675) never answers a bootstrap-owned key outside the
+     * allow-list (`storeMayAnswer`). With only the door (production) it answers
+     * the PRELOADED keys from the boot mirror and REFUSES the rest
+     * ({@link SettingsReadUnavailableError}) — it used to skip the store in
+     * silence. Before any backend is wired it is absent (boot-time readers).
      *
      * Returns `unknown` — callers must narrow via `typeof`/type guards, OR use
      * the generic overload at their own risk. The generic overload exists only
@@ -122,10 +53,19 @@ export declare class ConfigManager {
     get<T>(configPath: string): T | undefined;
     private resolveConfigValue;
     /**
-     * Write a value to the settings-store.
-     * Throws if the settings store is not yet wired.
+     * The settings-store layer of {@link get}: the stored value, `undefined`
+     * when the store holds nothing (or may not answer this key), or a THROW
+     * when the store cannot be asked.
      */
-    set(key: string, value: unknown): void;
+    private readStoreLayer;
+    /**
+     * Write a value to the settings-store. Resolves only once the write LANDED:
+     * on the isolated engine it awaits the door, and a failed write REJECTS and
+     * is not reported back by the mirror (D675 — it used to be fire-and-forget,
+     * so a lost write read as saved for the life of the process). Rejects when
+     * no store is wired.
+     */
+    set(key: string, value: unknown): Promise<void>;
     /**
      * Bulk-read all keys that belong to a logical section.
      * A "section" is the first segment of a dot-notation key (e.g. 'features', 'logging').
@@ -140,30 +80,48 @@ export declare class ConfigManager {
      * shadowing the rest of the section that only lives in config.yaml.
      * The kernel is agnostic about the store backend — any `ISettingsStore`
      * implementation (sqlite, redis, in-memory, …) behaves identically here.
+     *
+     * D675: a bootstrap-owned section takes ONLY allow-listed keys from the
+     * store (a stored `auth.jwtSecret` never replaces env), and with only the
+     * door wired this sync read THROWS — the settings view's `getSection` reads
+     * the door.
      */
     getSection(section: string): Record<string, unknown>;
+    /** Runtime defaults, then config.yaml + env — the layers under the store. */
+    private sectionBase;
+    /**
+     * {@link getSection} through the async door — what the door-backed settings
+     * view answers (D675). Same layers, same allow-list; a failed door read
+     * THROWS rather than handing back the defaults as if nothing were stored.
+     */
+    private readSectionThroughDoor;
     /**
      * Bulk-write a logical section to the settings-store.
      * Each entry in `data` is persisted under the key `section.<entryKey>`.
      */
     setSection(section: string, data: Record<string, unknown>): void;
-    /** Read all config for an addon from addon_settings. */
+    /**
+     * Read all config for an addon — SYNC store only. THROWS without one: its
+     * old bootstrap fallback answered `{}` for every addon on every
+     * isolated-engine hub (D675). Async three-way: {@link readAddonGlobalStrict}.
+     */
     getAddonConfig(addonId: string): Record<string, unknown>;
+    /**
+     * One addon's global store, three-way (D675): the record, `{}` when the
+     * store ANSWERED with nothing, or a THROW when it could not be asked.
+     * Behind `addonSettingsRaw.getGlobal` and `$hub.getAddonConfig`.
+     */
+    readAddonGlobalStrict(addonId: string): Promise<Record<string, unknown>>;
+    /** One addon's per-device overrides, three-way like {@link readAddonGlobalStrict}. */
+    readAddonDeviceStrict(addonId: string, deviceId: number): Promise<Record<string, unknown>>;
     /** Write (bulk-replace) config for an addon to addon_settings. */
     setAddonConfig(addonId: string, config: Record<string, unknown>): void;
-    /** Read all config for a provider from provider_settings. */
-    getProviderConfig(providerId: string): Record<string, unknown>;
-    /** Write (upsert) a single key for a provider to provider_settings. */
-    setProviderConfig(providerId: string, key: string, value: unknown): void;
-    /** Read all config for a device from device_settings. */
-    getDeviceConfig(deviceId: string): Record<string, unknown>;
-    /** Write (upsert) a single key for a device to device_settings. */
-    setDeviceConfig(deviceId: string, key: string, value: unknown): void;
     /**
      * Read per-device overrides for a specific addon. Returns a flat record
      * of field → value. Missing keys fall back to the addon-global value via
      * `getAddonConfig(addonId)` — that composition is the resolver service's
      * responsibility, not ConfigManager's.
+     * SYNC store only — THROWS without one (D675); async: {@link readAddonDeviceStrict}.
      */
     getAddonDevice(addonId: string, deviceId: string): Record<string, unknown>;
     /**
@@ -178,9 +136,8 @@ export declare class ConfigManager {
      */
     clearAddonDevice(addonId: string, deviceId: string): void;
     /**
-     * The device's persisted runtime-state blob. `{}` before the settings store
-     * is wired — the same answer as "this device has never persisted a slice",
-     * which is what every caller already handles.
+     * The device's persisted runtime-state blob. THROWS before the store is
+     * wired: a store not asked is not an empty row (D677, D675).
      */
     getDeviceRuntimeState(deviceId: string): Record<string, unknown>;
     /**
@@ -208,42 +165,31 @@ export declare class ConfigManager {
      * That is what made `storageMigration.start` fail on its first durable write
      * while every other addon's persistence worked. See D294.
      */
-    createSettingsView(addonId: string): AddonSettingsView;
+    createSettingsView(addonId: string): KernelAddonSettingsView;
     /** The async-door backend of {@link createSettingsView}. */
     private createDoorBackedSettingsView;
     /** The sync-`ISettingsStore` backend of {@link createSettingsView}. */
     private createStoreSettingsView;
+    /** Is a SYNC `ISettingsStore` wired? (The store-backed view's D294-window test.) */
+    hasSyncStore(): boolean;
     /** Get a value from the parsed bootstrap config.
      *  Generic overload is a documented type-level bridge — callers are responsible
      *  for passing a T that matches the config.yaml shape. */
     getBootstrap(configPath: string): unknown;
     getBootstrap<T>(configPath: string): T | undefined;
-    /** Features accessor -- reads from settings-store when available, falls back to RUNTIME_DEFAULTS */
-    get features(): FeatureManifest;
     /**
-     * Returns a merged view of bootstrap config + runtime defaults for backward compat.
+     * Features — the sync store when wired, else RUNTIME_DEFAULTS DELIBERATELY
+     * (not `get()`, which refuses in door mode, D675): nothing writes
+     * `features.*` beyond sqlite-settings' first-boot seed of these defaults.
      */
+    get features(): FeatureManifest;
+    /** Bootstrap config + runtime defaults, for backward compat. */
     get raw(): AppConfig;
-    /** Sections that live in config.yaml. Everything else goes to the settings-store. */
-    private static readonly BOOTSTRAP_SECTIONS;
     /**
-     * Atomically update one top-level section of config.yaml and sync in-memory.
-     * Only bootstrap sections (server, auth, mode) are written to YAML.
-     * Runtime settings must use setSection() which writes to the settings-store.
+     * Atomically update one top-level bootstrap section (server, auth, mode) of
+     * config.yaml and sync in-memory. Runtime settings use setSection().
      */
     update(section: string, data: Record<string, unknown>): void;
-    /**
-     * Deep-set a value in a nested plain object using a dot-notation path.
-     * Returns a new object (immutable).
-     */
-    private setNested;
-    /**
-     * Apply env var overrides onto the raw YAML object.
-     * Only bootstrap-level env vars are applied.
-     */
-    private applyEnvOverrides;
-    private loadYaml;
-    private warnDefaultCredentials;
     private getFromBootstrap;
     private getFromRuntimeDefaults;
     /**

package/dist/kernel/index.d.ts

@@ -19,7 +19,7 @@ export { overlayGetStatus, UNCLAIMED } from './status-overlay.js';
 export type { ClaimedStatusResolver, StatusOverlay, StatusOverlayAnswer } from './status-overlay.js';
 export { describeProviderKindDrift } from './provider-kind-drift.js';
 export type { ProviderKindHint } from './provider-kind-drift.js';
-export type { CapabilityRouter, CapabilityRouterFactory, ConfigReader, ProviderOwnerToken, } from './capability-registry.js';
+export type { CapabilityRouter, CapabilityRouterFactory, ConfigReader, PersistedPreferenceReplay, ProviderOwnerToken, } from './capability-registry.js';
 export { CustomActionRegistry, type CustomActionEntry } from './custom-action-registry.js';
 export { INFRA_CAPABILITIES, isInfraCapability } from './infra-capabilities.js';
 export type { InfraCapability } from './infra-capabilities.js';
@@ -27,7 +27,10 @@ export { isolatedBuiltinPhase, partitionIsolatedBuiltinIds, runHubAddonBoot, wai
 export type { IsolatedBuiltinPhase, IsolatedBuiltinWaves, CapabilityName, WaitUntilReadyOptions, HubAddonBootSteps, } from './isolated-builtin-phase.js';
 export { createDoorSettingsView } from './settings-door-view.js';
 export { ConfigManager } from './config-manager.js';
-export type { ISettingsStore } from './config-manager.js';
+export type { ISettingsStore, KernelAddonSettingsView, SystemSettingsPreload, } from './config-manager.js';
+export { SettingsReadUnavailableError, isSettingsReadUnavailable } from './settings-read-error.js';
+export type { SettingsReadRefusal } from './settings-read-error.js';
+export { storeMayAnswer, STORE_READABLE_BOOTSTRAP_KEYS } from './system-settings-policy.js';
 export { bootstrapSchema, RUNTIME_DEFAULTS, DEFAULT_DATA_PATH } from './config-schema.js';
 export type { BootstrapConfig, AppConfig, ServerMode } from './config-schema.js';
 export type { AddonSettingsView } from './config-manager.js';

package/dist/kernel/moleculer/runtime-state-load.d.ts

@@ -0,0 +1,19 @@
+import { IScopedLogger } from '@camstack/types';
+/** Where the load was for — named on the refusal line. */
+export type RuntimeStateLoadPhase = 'create' | 'accessory-child' | 'rebuild' | 'context';
+/** A device build refused because its runtime state could not be loaded. */
+export declare class RuntimeStateLoadError extends Error {
+    readonly deviceId: number;
+    constructor(deviceId: number, reason: string, options?: ErrorOptions);
+}
+export interface RuntimeStateLoadTarget {
+    readonly deviceId: number;
+    readonly stableId: string;
+    readonly phase: RuntimeStateLoadPhase;
+}
+/**
+ * Load the device's runtime state, or throw {@link RuntimeStateLoadError}
+ * after one warn naming the device. An answer that is not an object is a
+ * failed load too — it would hydrate as nothing.
+ */
+export declare function loadRuntimeStateOrRefuse(load: () => Promise<unknown>, logger: IScopedLogger, target: RuntimeStateLoadTarget): Promise<Record<string, unknown>>;

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

@@ -1,7 +1,30 @@
 import { ISettingsStoreProvider } from '@camstack/types';
 import { SettingsViewBackend } from './config-manager.js';
+/**
+ * Every `system-settings` row under `prefix`, keyed by the suffix — or a throw.
+ *
+ * `system-settings` stores the value ITSELF (`setSystem` / `door.set` write
+ * `JSON.stringify(value)`), mostly scalars. The engine's `query` hands a KV row
+ * back parsed only when its text is an object or an array; a scalar comes back
+ * as `{ value: <its JSON text> }` — `"12h"` arrives as `{ value: '"12h"' }`.
+ * That is not a value anyone stored, and guessing it back would misread a
+ * stored object that happens to be `{ value: … }`. So the range read only
+ * ENUMERATES the keys (same keyset walk and refusal as every prefix read
+ * here), and each value is taken from `get`, which parses the row exactly
+ * (D675). These reads are small and rare: a section's handful of keys when a
+ * form opens, and the capability preferences once at boot.
+ */
+export declare function loadSystemSettingsPrefix(door: ISettingsStoreProvider, prefix: string, 
+/** Suffixes the caller may read. A refused one is never FETCHED — the
+ *  `auth` section's credential rows never enter this process (D675). */
+mayRead?: (suffix: string) => boolean): Promise<Record<string, unknown>>;
+/**
+ * The `system-settings` section surface a door-backed view delegates to.
+ * `getSection` is ASYNC: it reads the section through the door (D675) — a
+ * synchronous reader has no store to ask when the engine is isolated.
+ */
 export interface DoorSectionAccess {
-    getSection(section: string): Record<string, unknown>;
+    getSection(section: string): Promise<Record<string, unknown>>;
     setSection(section: string, patch: Record<string, unknown>): void | Promise<void>;
 }
 export declare function createDoorSettingsView(addonId: string, door: ISettingsStoreProvider, sections: DoorSectionAccess): SettingsViewBackend;

package/dist/kernel/settings-read-error.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The refusal a SYNCHRONOUS settings reader raises when it cannot answer — D675.
+ *
+ * `ConfigManager`'s sync readers (`get`, `getSection`, `getAddonConfig`, …)
+ * used to answer `{}` / a runtime default whenever no sync `ISettingsStore`
+ * was wired. Since D231 isolated `sqlite-settings`, hub-main never gets one:
+ * only the async door. So every such read answered "nothing stored" for the
+ * life of the process, and "nothing stored" is exactly what a store holding
+ * nothing looks like (D315, D393). The readers now refuse instead, and this
+ * is what they throw, so a caller can tell "the store could not be asked"
+ * from every other failure and from "never written".
+ */
+/**
+ * Why the read was refused.
+ *
+ * - `door-only` — the engine is isolated: only the async door is wired, and a
+ *   synchronous caller cannot await it. Use the settings view instead.
+ * - `not-wired` — no backend at all yet (the D294 window, before
+ *   `setSettingsStore` / `setSettingsDoor`).
+ * - `preload-pending` — the key is one of the few the kernel loads from the
+ *   door into memory at boot, and that one read has not settled yet.
+ * - `preload-failed` — that boot read failed; the value is unknown until the
+ *   next boot (one read, no polling — D3).
+ * - `read-failed` — the async read itself threw.
+ */
+export type SettingsReadRefusal = 'door-only' | 'not-wired' | 'preload-pending' | 'preload-failed' | 'read-failed';
+export declare class SettingsReadUnavailableError extends Error {
+    /** The reader that refused, e.g. `ConfigManager.getAddonConfig`. */
+    readonly reader: string;
+    readonly reason: SettingsReadRefusal;
+    readonly name = "SettingsReadUnavailableError";
+    constructor(
+    /** The reader that refused, e.g. `ConfigManager.getAddonConfig`. */
+    reader: string, reason: SettingsReadRefusal, detail: string);
+}
+/** Narrow an unknown throw to {@link SettingsReadUnavailableError}. */
+export declare function isSettingsReadUnavailable(err: unknown): err is SettingsReadUnavailableError;

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

@@ -0,0 +1,105 @@
+import { AddonStoreRead, StoredKeyRead } from '@camstack/types';
+export interface AddonSettingsView {
+    readAddonStore(): Promise<Record<string, unknown>>;
+    /** See `IAddonContext['settings'].readAddonStoreResult` (D651). */
+    readAddonStoreResult?(): Promise<AddonStoreRead>;
+    /** See `IAddonContext['settings'].readAddonStoreKeyResult` (D675). */
+    readAddonStoreKeyResult?(key: string): Promise<StoredKeyRead>;
+    writeAddonStore(patch: Record<string, unknown>): Promise<void>;
+    readDeviceStore(deviceId: number): Promise<Record<string, unknown>>;
+    /** See `IAddonContext['settings'].readDeviceStoreBatch` — optional there and
+     *  here for the same reason: only the door-backed view can answer it in one
+     *  range scan, and a caller must fall back rather than refuse. */
+    readDeviceStoreBatch?(deviceIds: readonly number[]): Promise<ReadonlyMap<number, Record<string, unknown>>>;
+    writeDeviceStore(deviceId: number, patch: Record<string, unknown>): Promise<void>;
+    clearDeviceStore(deviceId: number): Promise<void>;
+    getSection(section: string): Promise<Record<string, unknown>>;
+    setSection(section: string, patch: Record<string, unknown>): Promise<void>;
+    /**
+     * Per-device runtime state — separate namespace from
+     * `readDeviceStore` / `writeDeviceStore` (which is the addon's
+     * config blob: host, password, deviceCache, …). Holds mutable
+     * runtime signals discovered after boot: battery snapshot, sleep
+     * flag, last-seen timestamps. Stored under a kernel-internal
+     * `__device-state` namespace so the device's config schema
+     * never has to know about it (clean separation of operator
+     * intent from runtime telemetry).
+     *
+     * Patch semantics: shallow merge. Pass the FULL persistent slice
+     * each call (the kernel doesn't try to compute deltas) — concrete
+     * implementations of `DeviceRuntimeState` already coalesce in
+     * memory, so the kernel just persists the latest blob.
+     */
+    readDeviceRuntimeState(deviceId: number): Promise<Record<string, unknown>>;
+    writeDeviceRuntimeState(deviceId: number, data: Record<string, unknown>): Promise<void>;
+    clearDeviceRuntimeState(deviceId: number): Promise<void>;
+}
+/**
+ * A CONCRETE backend behind {@link ConfigManager.createSettingsView} — the
+ * sync-`ISettingsStore` one or the async-door one.
+ *
+ * `readDeviceStoreBatch` is required here and optional on
+ * {@link AddonSettingsView} because both of these can answer it, so the view
+ * the kernel hands an addon never has to decide whether the method exists.
+ * The optionality on the public interface stays for the implementation that
+ * genuinely cannot batch: a forked runner's UDS-backed view.
+ */
+export interface SettingsViewBackend extends AddonSettingsView {
+    readDeviceStoreBatch(deviceIds: readonly number[]): Promise<ReadonlyMap<number, Record<string, unknown>>>;
+    readAddonStoreKeyResult(key: string): Promise<StoredKeyRead>;
+}
+export interface ISettingsStore {
+    getSystem(key: string): unknown;
+    setSystem(key: string, value: unknown): void;
+    getAllSystem(): Record<string, unknown>;
+    /** Addon-level global settings (apply to every device unless overridden). */
+    getAllAddon(addonId: string): Record<string, unknown>;
+    setAllAddon(addonId: string, config: Record<string, unknown>): void;
+    /** Legacy per-provider settings (used by some older wiring paths). */
+    getAllProvider(providerId: string): Record<string, unknown>;
+    setProvider(providerId: string, key: string, value: unknown): void;
+    /** Legacy flat per-device settings. Kept for backward compatibility
+     *  with pre-addon wiring; new code should use the addon-device API. */
+    getAllDevice(deviceId: string): Record<string, unknown>;
+    setDevice(deviceId: string, key: string, value: unknown): void;
+    /**
+     * Multi-level addon settings: per-device overrides for a specific addon.
+     *
+     * Resolution chain when the frontend asks for the effective value of a
+     * field on a given device:
+     *   1. schema default (from `ConfigUISchema.field.default`)
+     *   2. `getAllAddon(addonId)`           — addon global value
+     *   3. `getAddonDevice(addonId, devId)` — per-device override (wins)
+     *
+     * Only fields declared with `scope: 'device'` in the addon's
+     * `ConfigUISchema` should ever be persisted here.
+     */
+    getAddonDevice(addonId: string, deviceId: string): Record<string, unknown>;
+    setAddonDevice(addonId: string, deviceId: string, values: Record<string, unknown>): void;
+    clearAddonDevice(addonId: string, deviceId: string): void;
+    /**
+     * Per-device runtime state — the whole cap-slice map as ONE row in the
+     * `device-runtime-state` collection.
+     *
+     * These are separate from `getAddonDevice`/`setAddonDevice` because runtime
+     * state is not an addon's config: it belongs to the device, it is replaced
+     * wholesale on every flush, and it is written orders of magnitude more often.
+     * It USED to share that keyspace under a synthetic `__device-state` addonId,
+     * which cost one row (and one INSERT) per cap slice per flush and left the
+     * collection it is named for empty on every installation. The backend keeps
+     * reading the legacy prefix; see `SqliteSettingsBackend.getDeviceRuntimeState`.
+     */
+    getDeviceRuntimeState(deviceId: string): Record<string, unknown>;
+    setDeviceRuntimeState(deviceId: string, blob: Record<string, unknown>): void;
+    clearDeviceRuntimeState(deviceId: string): void;
+}
+/**
+ * The settings view `ConfigManager.createSettingsView` returns. Its three-way
+ * reads are REQUIRED here (optional on the public {@link AddonSettingsView}
+ * only for a forked runner's UDS view), so a caller holding a `ConfigManager`
+ * never has to decide whether they exist.
+ */
+export interface KernelAddonSettingsView extends AddonSettingsView {
+    readAddonStoreResult(): Promise<AddonStoreRead>;
+    readAddonStoreKeyResult(key: string): Promise<StoredKeyRead>;
+}

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

@@ -0,0 +1,17 @@
+import { 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;
+}
+export declare function createStoreSettingsView(addonId: string, cm: StoreViewHost): SettingsViewBackend;

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

@@ -0,0 +1,34 @@
+import { 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: '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;
+}