@camstack/system 1.2.390 → 1.2.392

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

@@ -1,201 +1,201 @@
-import { FeatureManifest, ISettingsStoreProvider } from '@camstack/types';
-import { AppConfig } from './config-schema.js';
-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';
+import type { FeatureManifest, ISettingsStoreProvider } from "@camstack/types";
+import { type AppConfig } from "./config-schema.js";
+import type { ISettingsStore, KernelAddonSettingsView } from "./settings-view-types.js";
+export type { AddonSettingsView, ISettingsStore, KernelAddonSettingsView, SettingsViewBackend } from "./settings-view-types.js";
+import { type SystemSettingsPreload } from "./system-settings-mirror.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`
-     * capability provider has registered (normally during Phase-1 infra boot).
-     * Before this call, runtime reads/writes fall back to bootstrap + defaults.
-     */
-    setSettingsStore(store: ISettingsStore): void;
-    /**
-     * Wire the async `settings-store` door. Used when the engine is isolated
-     * (no sync `ISettingsStore` handle on hub-main). {@link createSettingsView}
-     * 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 + 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
-     * as a convenience alias for legacy call sites; it performs NO runtime
-     * check and is the one documented type-level bridge in this function.
-     */
-    get(configPath: string): unknown;
-    get<T>(configPath: string): T | undefined;
-    private resolveConfigValue;
-    /**
-     * 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.
-     */
-    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').
-     *
-     * Sources are merged in priority order (lowest → highest):
-     *   1. RUNTIME_DEFAULTS — kernel constants.
-     *   2. Bootstrap config  — values loaded from config.yaml at boot.
-     *   3. Settings-store    — runtime writes via the `settings-store` capability.
-     *
-     * Higher layers override earlier ones. Merging (instead of short-circuiting
-     * on the first non-null source) prevents a single store-seeded key from
-     * 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 stale stored `auth.jwtSecret` never answers), 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 — 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 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>;
-    /**
-     * Write (bulk-replace) per-device overrides for a specific addon.
-     * Throws if the settings store is not yet wired.
-     */
-    setAddonDevice(addonId: string, deviceId: string, values: Record<string, unknown>): void;
-    /**
-     * Clear all per-device overrides for a specific addon/device pair.
-     * Resolution falls back to the addon-global value after this call.
-     * No-op if the settings store is not yet wired.
-     */
-    clearAddonDevice(addonId: string, deviceId: string): void;
-    /**
-     * 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>;
-    /**
-     * Replace the device's persisted runtime-state blob.
-     *
-     * THROWS when the store is not wired, and that is deliberate: the caller
-     * (`DeviceStateMirror.scheduleRuntimeStateDiskWrite`) catches and logs, so a
-     * persist that cannot happen leaves a line naming the device. A silent no-op
-     * here is the shape that let a whole collection read zero for months.
-     */
-    setDeviceRuntimeState(deviceId: string, blob: Record<string, unknown>): void;
-    /** Forget the device's runtime state. No-op before the store is wired. */
-    clearDeviceRuntimeState(deviceId: string): void;
-    /**
-     * The addon's `ctx.settings`.
-     *
-     * The backend is chosen on EVERY call, never frozen when the view is built.
-     * That is not a nicety: `settings-store` is owned by `storage-orchestrator`,
-     * so the door is wired by `registerProvider` STRICTLY AFTER that addon's
-     * context — and therefore its settings view — already exists. A view bound at
-     * construction handed the door's own owner the sync-store backend, whose
-     * writes throw for the whole life of the process once `sqlite-settings` runs
-     * isolated (D181: no sync `ISettingsStore` reaches hub-main, only the async
-     * door). Reads were worse than the writes: they answered `{}` in silence.
-     * That is what made `storageMigration.start` fail on its first durable write
-     * while every other addon's persistence worked. See D294.
-     */
-    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 — 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;
-    /**
-     * 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;
-    private getFromBootstrap;
-    private getFromRuntimeDefaults;
-    /**
-     * Perform a prefix-based nested lookup against the settings-store.
-     * e.g. path='features' matches keys 'features.streaming', 'features.notifications', etc.
-     * Returns an object keyed by the sub-key, or undefined if nothing is found.
-     */
-    private getNestedFromSystemSettings;
+	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`
+	* capability provider has registered (normally during Phase-1 infra boot).
+	* Before this call, runtime reads/writes fall back to bootstrap + defaults.
+	*/
+	setSettingsStore(store: ISettingsStore): void;
+	/**
+	* Wire the async `settings-store` door. Used when the engine is isolated
+	* (no sync `ISettingsStore` handle on hub-main). {@link createSettingsView}
+	* 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 + 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
+	* as a convenience alias for legacy call sites; it performs NO runtime
+	* check and is the one documented type-level bridge in this function.
+	*/
+	get(configPath: string): unknown;
+	get<T>(configPath: string): T | undefined;
+	private resolveConfigValue;
+	/**
+	* 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.
+	*/
+	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').
+	*
+	* Sources are merged in priority order (lowest → highest):
+	*   1. RUNTIME_DEFAULTS — kernel constants.
+	*   2. Bootstrap config  — values loaded from config.yaml at boot.
+	*   3. Settings-store    — runtime writes via the `settings-store` capability.
+	*
+	* Higher layers override earlier ones. Merging (instead of short-circuiting
+	* on the first non-null source) prevents a single store-seeded key from
+	* 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 stale stored `auth.jwtSecret` never answers), 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 — 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 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>;
+	/**
+	* Write (bulk-replace) per-device overrides for a specific addon.
+	* Throws if the settings store is not yet wired.
+	*/
+	setAddonDevice(addonId: string, deviceId: string, values: Record<string, unknown>): void;
+	/**
+	* Clear all per-device overrides for a specific addon/device pair.
+	* Resolution falls back to the addon-global value after this call.
+	* No-op if the settings store is not yet wired.
+	*/
+	clearAddonDevice(addonId: string, deviceId: string): void;
+	/**
+	* 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>;
+	/**
+	* Replace the device's persisted runtime-state blob.
+	*
+	* THROWS when the store is not wired, and that is deliberate: the caller
+	* (`DeviceStateMirror.scheduleRuntimeStateDiskWrite`) catches and logs, so a
+	* persist that cannot happen leaves a line naming the device. A silent no-op
+	* here is the shape that let a whole collection read zero for months.
+	*/
+	setDeviceRuntimeState(deviceId: string, blob: Record<string, unknown>): void;
+	/** Forget the device's runtime state. No-op before the store is wired. */
+	clearDeviceRuntimeState(deviceId: string): void;
+	/**
+	* The addon's `ctx.settings`.
+	*
+	* The backend is chosen on EVERY call, never frozen when the view is built.
+	* That is not a nicety: `settings-store` is owned by `storage-orchestrator`,
+	* so the door is wired by `registerProvider` STRICTLY AFTER that addon's
+	* context — and therefore its settings view — already exists. A view bound at
+	* construction handed the door's own owner the sync-store backend, whose
+	* writes throw for the whole life of the process once `sqlite-settings` runs
+	* isolated (D181: no sync `ISettingsStore` reaches hub-main, only the async
+	* door). Reads were worse than the writes: they answered `{}` in silence.
+	* That is what made `storageMigration.start` fail on its first durable write
+	* while every other addon's persistence worked. See D294.
+	*/
+	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 — 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;
+	/**
+	* 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;
+	private getFromBootstrap;
+	private getFromRuntimeDefaults;
+	/**
+	* Perform a prefix-based nested lookup against the settings-store.
+	* e.g. path='features' matches keys 'features.streaming', 'features.notifications', etc.
+	* Returns an object keyed by the sub-key, or undefined if nothing is found.
+	*/
+	private getNestedFromSystemSettings;
 }