@camstack/system 1.0.2

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

@@ -0,0 +1,412 @@
+import { CapabilityDefinition, CapabilityDeclaration, CapabilityMode, CapabilityInfo, CapabilityProviderMap, SingletonCapabilityMap, CollectionCapabilityMap, IScopedLogger, IEventBus } from '@camstack/types';
+import { ConfigManager } from './config-manager.js';
+/** Result of creating a capability router (opaque to the kernel). */
+export type CapabilityRouter = unknown;
+/** Factory that creates a tRPC router from a capability definition + provider getter. */
+export type CapabilityRouterFactory = (definition: CapabilityDefinition, getProvider: () => unknown | null) => CapabilityRouter;
+/** Reader function that resolves user's singleton preference for a capability. */
+export type ConfigReader = (capability: string) => string | undefined;
+/**
+ * Reader function that resolves the persisted set of disabled addonIds for a
+ * collection capability. Parallel to {@link ConfigReader} but for the
+ * collection mode — returns the addonIds an operator has disabled so the
+ * registry can restore them as disabled on a fresh boot. An empty array (or
+ * `undefined`) means "nothing persisted, all providers enabled".
+ *
+ * Wired by the server layer in `addon-registry.service.ts` to read the same
+ * `capabilities.collection.<cap>` ConfigService key the `capabilities` router
+ * writes. Keeps the registry decoupled from `ConfigService` — exactly like
+ * {@link ConfigReader} does for singletons.
+ */
+export type CollectionConfigReader = (capability: string) => readonly string[] | undefined;
+export declare class CapabilityRegistry {
+    private readonly capabilities;
+    private readonly logger;
+    private readonly eventBus;
+    private routerFactory;
+    private configReader;
+    private collectionConfigReader;
+    private configManager;
+    private _ready;
+    /** Boot-time dependency graph: capability → dependsOn names (from CapabilityDeclaration) */
+    private readonly capabilityDeps;
+    /** Per-device singleton overrides: deviceId → (capability → addonId) */
+    private readonly deviceOverrides;
+    /** capName → (nodeId → bare addonId) per-node singleton overrides. */
+    private readonly singletonNodeOverrides;
+    /** Optional reader for persisted per-node overrides: (cap, nodeId) → addonId. */
+    private nodeConfigReader;
+    /** Per-device collection filters: deviceId → (capability → addonIds[]) */
+    private readonly deviceCollectionFilters;
+    /** autoActivate flags per (capability, addonId) — from addon manifests */
+    private readonly autoActivateFlags;
+    /**
+     * Per-device native providers: capName → deviceId (numeric) → { addonId, provider }.
+     *
+     * Backs `DeviceContext.registerNativeCap`. Lets device-driver addons
+     * (OnvifCamera, RtspCamera, etc.) publish capability implementations
+     * scoped to a single device; the device-proxy router resolves these by
+     * `(capName, deviceId)` to dispatch incoming calls.
+     *
+     * Distinct from the `capabilities[].providers` map (system-wide providers
+     * keyed by addonId) — native providers are device-instance-scoped and
+     * never participate in singleton/collection resolution.
+     */
+    private readonly nativeProviders;
+    /**
+     * Wrapper provider registrations: capName → Set<addonId>. Tracked separately
+     * from `capabilities[].providers` because wrappers aren't system-wide
+     * providers — they're user-toggleable decorators addons declare via
+     * `ProviderRegistration.kind === 'wrapper'`. Consumers query this map (via
+     * `getWrappersForCap`) to render the "pick a wrapper for this device"
+     * dropdown in the device-bindings UI.
+     */
+    private readonly wrapperProviders;
+    /**
+     * Wrapper registrations that declared `ProviderRegistration.defaultActive:
+     * true`. Keyed by `capName` and valued by `addonId` — the first wrapper
+     * flagged default-active wins per cap. Consumed by `device-manager.getBindings`
+     * to synthesise a wrapper binding when no explicit activation has been
+     * persisted for a (device, cap) pair and no native provider exists either —
+     * otherwise the default wrapper would sit dormant waiting for a manual
+     * `setWrapperActive({active: true})` that never comes.
+     */
+    private readonly wrapperDefaults;
+    /**
+     * Pending {@link waitForProvider} waiters, keyed by
+     * `"${capabilityName}::${addonId}"`. Resolved by {@link registerProvider}
+     * as soon as the matching pair is registered — the mechanism that replaces
+     * the 100ms polling loop the device-management router used to run while
+     * waiting for forked providers to finish announcing their Moleculer service.
+     */
+    private readonly pendingWaiters;
+    /** Period for the "still waiting" log emitted by `waitForProvider`. */
+    private static readonly WAIT_HEARTBEAT_INTERVAL_MS;
+    constructor(logger: IScopedLogger, eventBus?: IEventBus);
+    /** Set the config reader for singleton preference resolution. */
+    setConfigReader(reader: ConfigReader): void;
+    /**
+     * Set the config reader for collection-provider enable/disable persistence.
+     * Consulted by {@link registerProvider} so a provider an operator disabled
+     * in a previous session comes back disabled after a hub reboot.
+     */
+    setCollectionConfigReader(reader: CollectionConfigReader): void;
+    /** Set the config manager for persisted device activation state. */
+    setConfigManager(manager: ConfigManager): void;
+    /** Register boot-time dependency edges (from CapabilityDeclaration.dependsOn). */
+    setDependencies(capabilityName: string, dependsOn: readonly string[]): void;
+    /** Set the router factory — called by the server layer once at boot. */
+    setRouterFactory(factory: CapabilityRouterFactory): void;
+    /** Mark boot complete. Before this, getProvider() returns null. */
+    ready(): void;
+    isReady(): boolean;
+    /**
+     * Declare a capability from its definition.
+     * Creates the auto-mounted router (if factory is set).
+     * Called during addon manifest loading, before providers are registered.
+     */
+    declareCapability(definition: CapabilityDefinition): void;
+    /**
+     * Register manifest metadata (dependsOn + autoActivate) for a capability,
+     * and — when the capability's definition declares `kind: 'wrapper'` —
+     * register the addon as a wrapper provider.
+     *
+     * The capability MUST already be declared via `declareCapability` from
+     * its full `CapabilityDefinition`. Behavioural metadata (`mode`, `kind`,
+     * `defaultActive`) is owned exclusively by the cap definition — never
+     * the manifest (D4, base-layer rework; mirrors the Session 5 A5 `mode`
+     * consolidation). The manifest declaration carries only the cap name,
+     * `dependsOn`, `autoActivate`, and `optional`.
+     */
+    declareFromManifest(declaration: CapabilityDeclaration, addonId?: string): void;
+    /**
+     * Register a provider for a capability.
+     * For singleton: auto-activates if user-preferred or first registered.
+     * For collection: adds to the collection.
+     *
+     * Phase 12 (settings redesign follow-up): throws if the same
+     * `(capabilityName, addonId)` pair is registered more than once.
+     * Previously the second call would silently replace the first via
+     * `state.providers.set(addonId, provider)` — that was the root cause
+     * of the "analysis-pipeline registered three times" bug observed in
+     * the kernel cleanup log (`analytics` addon called `registerProvider`
+     * twice plus the `analysis-pipeline` addon called it a third time).
+     *
+     * Double-register of the same pair is always a programmer error —
+     * two legitimately different addons implementing the same cap keep
+     * using different `addonId`s and the user picks one via `configReader`.
+     */
+    registerProvider(capabilityName: string, addonId: string, provider: unknown): void;
+    /** Unregister a provider. For singleton: clears active. For collection: removes from list. */
+    unregisterProvider(capabilityName: string, addonId: string): void;
+    /** Enable a previously disabled collection provider. */
+    enableCollectionProvider(capability: string, addonId: string): void;
+    /** Disable a collection provider (keeps it registered but excluded from active list). */
+    disableCollectionProvider(capability: string, addonId: string): void;
+    /**
+     * Register a native capability provider scoped to a single device.
+     * Throws if the same `(capName, deviceId)` is registered twice — that is
+     * always a programmer error: device-driver addons must call
+     * `DeviceContext.registerNativeCap` exactly once per cap per device.
+     */
+    registerNativeProvider(capName: string, deviceId: number, addonId: string, provider: unknown): void;
+    /** Remove a single native provider entry. No-op if absent. */
+    unregisterNativeProvider(capName: string, deviceId: number): void;
+    /** Remove every native provider entry for a device — called on device removal. */
+    unregisterAllNativeForDevice(deviceId: number): void;
+    /** Fallback resolver for native providers that aren't registered in-process. */
+    private nativeFallback;
+    /**
+     * Install a fallback resolver for cross-process native caps. When a device's
+     * live `IDevice` lives in a forked worker (e.g. `provider-rtsp`), the native
+     * cap it published via `DeviceContext.registerNativeCap` is reachable over
+     * the broker — but the hub's `nativeProviders` map never saw it. The fallback
+     * is called by {@link getNativeProvider} on local-miss and is expected to
+     * return a proxy object whose methods issue `broker.call` into the owning
+     * worker. Set once at hub boot time.
+     */
+    setNativeFallback(resolver: (capName: string, deviceId: number) => unknown | null): void;
+    /** Resolve the native provider for `(capName, deviceId)` or null. */
+    getNativeProvider<T = unknown>(capName: string, deviceId: number): T | null;
+    /** Resolve the addonId that registered the native provider for `(capName, deviceId)`. */
+    getNativeAddonId(capName: string, deviceId: number): string | null;
+    /** List the capability names for which this device has a native provider registered. */
+    getNativeCapsForDevice(deviceId: number): readonly string[];
+    /**
+     * Mark `addonId` as providing a wrapper implementation for `capName`. Called
+     * by `declareFromManifest` when the capability's `CapabilityDefinition` declares
+     * `kind: 'wrapper'` (D4 — the cap definition is the single source of truth for wrapper behaviour).
+     * Idempotent — re-registration keeps a single entry.
+     */
+    registerWrapper(capName: string, addonId: string, opts?: {
+        defaultActive?: boolean;
+    }): void;
+    /** Remove a wrapper registration. No-op if absent. */
+    unregisterWrapper(capName: string, addonId: string): void;
+    /** Remove every wrapper registration owned by `addonId`. Called on addon stop. */
+    unregisterAllWrappersForAddon(addonId: string): void;
+    /** Return the addon ids that declared a wrapper for `capName`. */
+    getWrappersForCap(capName: string): readonly string[];
+    /**
+     * Return the wrapper addon flagged `defaultActive: true` for `capName`, or
+     * null when no wrapper declared itself the default. Used by
+     * `device-manager.getBindings` to auto-bind default wrappers on devices
+     * without an explicit user activation.
+     */
+    getDefaultWrapperForCap(capName: string): string | null;
+    /** List capability names that have at least one wrapper flagged `defaultActive: true`. */
+    getCapsWithDefaultWrapper(): readonly string[];
+    /**
+     * Get the active provider for a singleton capability.
+     *
+     * When called with a declared capability name (a key of
+     * `CapabilityProviderMap`), the return type is inferred automatically —
+     * no caller-side casts needed. Arbitrary string names fall back to
+     * `unknown`.
+     */
+    getProvider<K extends keyof CapabilityProviderMap>(capabilityName: K): CapabilityProviderMap[K] | null;
+    getProvider(capabilityName: string): unknown | null;
+    /**
+     * Unified per-device resolver (D13). Resolves a `(cap, device)` pair to
+     * its provider transparently — native (per-device) first, then a
+     * device-bound system provider. Callers no longer branch on
+     * `kind: 'native' | 'wrapped'`; `kind` is metadata on the binding only.
+     *
+     * Resolution order:
+     * 1. Native provider registered for the exact `(capName, deviceId)` pair.
+     * 2. System provider: for singleton caps, honours per-device overrides and
+     *    activation via `resolveForDevice`; for collection caps, returns the
+     *    first registered provider.
+     * 3. `null` when neither exists.
+     */
+    getProviderForDevice<T = unknown>(capName: string, deviceId: number): T | null;
+    /** Get all providers for a collection capability. */
+    getAllProviders<K extends keyof CapabilityProviderMap>(capabilityName: K): readonly CapabilityProviderMap[K][];
+    getAllProviders(capabilityName: string): readonly unknown[];
+    /** Get provider by addon ID (for per-device resolution). */
+    getProviderByAddon<K extends keyof CapabilityProviderMap>(capabilityName: K, addonId: string): CapabilityProviderMap[K] | null;
+    getProviderByAddon<T = unknown>(capabilityName: string, addonId: string): T | null;
+    /**
+     * Wait for a specific `(capabilityName, addonId)` provider to become
+     * available, up to `timeoutMs`. Resolves synchronously with the live
+     * provider if it is already registered; otherwise queues a waiter that
+     * {@link registerProvider} fulfils as soon as the matching pair shows up.
+     * Resolves to `null` on timeout instead of rejecting — the caller
+     * ({@link device-management.router}) already branches on `null` to return
+     * a user-facing "provider not available" error.
+     *
+     * Replaces the 100ms polling loop from the post-settings-redesign
+     * `waitForDeviceProvider` helper. On the happy path there is zero
+     * overhead and zero behavioural change; on the race path the wait
+     * unblocks on the next `registerProvider` call without any intermediate
+     * sleeps. See `[WAIT-EVENT]` in the 2026-04-12 handover.
+     */
+    waitForProvider<K extends keyof CapabilityProviderMap>(capabilityName: K, addonId: string, timeoutMs: number): Promise<CapabilityProviderMap[K] | null>;
+    waitForProvider(capabilityName: string, addonId: string, timeoutMs: number): Promise<unknown | null>;
+    /**
+     * Get the active singleton provider for a capability.
+     *
+     * Declared capability names resolve to their typed provider via
+     * `SingletonCapabilityMap` — a cap declared as `collection` in its
+     * `.cap.ts` definition is rejected at the type level. Arbitrary strings
+     * (non-declared capabilities) fall back to the caller-provided `T`
+     * (default `unknown`) through the second overload for compatibility
+     * with downstream packages that extend `CapabilityProviderMap` via
+     * declaration merging.
+     *
+     * Hard-typed narrowing via `SingletonCapabilityMap` was introduced in
+     * session 5 Sprint A5 — see audit addendum finding R6.
+     */
+    getSingleton<K extends keyof SingletonCapabilityMap>(capability: K): SingletonCapabilityMap[K] | null;
+    getSingleton<T = unknown>(capability: string): T | null;
+    /** Get the addon ID of the active singleton provider. */
+    getSingletonAddonId(capability: string): string | null;
+    /**
+     * Override the active addon for a singleton capability. Called by the
+     * pipeline-orchestrator binding system so future `getSingleton(cap)`
+     * lookups return the addon the operator explicitly selected. If
+     * `addonId` is `null` or no provider is registered under that id,
+     * falls back to the cap-declared `preferredProvider` (when registered),
+     * otherwise the first-registered provider (legacy behaviour).
+     *
+     * This helper is an internal hook for the UDS-preference race (it does
+     * NOT read `configReader` — the operator's persisted choice is applied
+     * by `registerProvider`/`unregisterProvider`). For consistency with those
+     * paths the fallback still honours `preferredProvider` ahead of
+     * insertion-order first-remaining.
+     *
+     * No-op when the capability isn't declared, isn't a singleton, or the
+     * requested addon hasn't registered a provider for it yet.
+     */
+    setSingletonActiveAddon(capability: string, addonId: string | null): void;
+    /**
+     * Get all active collection providers for a capability.
+     *
+     * Declared capability names resolve to their typed provider via
+     * `CollectionCapabilityMap` — a cap declared as `singleton` in its
+     * `.cap.ts` definition is rejected at the type level. Arbitrary strings
+     * fall back to the caller-provided `T` (default `unknown`) for
+     * compatibility with declaration-merged extensions.
+     */
+    getCollection<K extends keyof CollectionCapabilityMap>(capability: K): readonly CollectionCapabilityMap[K][];
+    getCollection<T = unknown>(capability: string): readonly T[];
+    /**
+     * Like {@link getCollection} but returns `[addonId, provider]` tuples so
+     * callers can attribute work back to the contributing addon.
+     *
+     * Needed by the device-settings aggregator (`device-manager.addon.ts`) —
+     * each contributed field must carry the writer's `addonId` so the
+     * `deviceManager.updateDeviceField` mutation can route the write to the
+     * correct addon-settings store without hardcoding any addon identity.
+     */
+    getCollectionEntries<K extends keyof CollectionCapabilityMap>(capability: K): readonly (readonly [string, CollectionCapabilityMap[K]])[];
+    getCollectionEntries<T = unknown>(capability: string): readonly (readonly [string, T])[];
+    /** Get the full CapabilityDefinition for a declared capability. */
+    getDefinition(capability: string): CapabilityDefinition | undefined;
+    /** Get the mode declared for a capability. */
+    getMode(capability: string): CapabilityMode | undefined;
+    /** Get a specific addon's provider by addon ID. */
+    getProviderByAddonId<K extends keyof CapabilityProviderMap>(capability: K, addonId: string): CapabilityProviderMap[K] | null;
+    getProviderByAddonId<T = unknown>(capability: string, addonId: string): T | null;
+    /** Bare addonId from a registry key (`webrtc-native@dev-agent-0` → `webrtc-native`). */
+    private bareAddonId;
+    /** nodeId a provider key belongs to (bare → 'hub', `@node` → node). */
+    private nodeOfKey;
+    /** capName → (nodeId → bare addonId[]) availability derived from provider keys. */
+    getProvidersByNode(capability: string): Map<string, string[]>;
+    /**
+     * Resolve the BARE addon id a node should use for a singleton cap.
+     * Chain: per-node override → cluster-global default → first available.
+     * Returns null when the node hosts no provider for the cap.
+     */
+    resolveSingletonAddonIdForNode(capability: string, nodeId: string): string | null;
+    /** Resolve the in-process provider object for a node (hub-local only). */
+    getSingletonForNode<T = unknown>(capability: string, nodeId: string): T | null;
+    /** Per-node override accessor (for listCapabilities + tests). */
+    getSingletonNodeOverrides(capability: string): Map<string, string>;
+    /** Set the reader for persisted per-node overrides (boot restore). */
+    setNodeConfigReader(reader: (capability: string, nodeId: string) => string | undefined): void;
+    /** Clear a per-node override (UI "inherit global"). */
+    clearSingletonNodeOverride(capability: string, nodeId: string): void;
+    /**
+     * Set which addon should be the active singleton for a capability.
+     * Pass an optional `nodeId` to set a per-node override instead of the cluster-global default.
+     */
+    setActiveSingleton(capability: string, addonId: string, nodeId?: string): Promise<void>;
+    /**
+     * Check if a specific addon's capability is active system-wide.
+     *
+     * Resolution: 1. explicit system override → 2. autoActivate flag → 3. default true
+     */
+    isActiveForSystem(capability: string, addonId: string): boolean;
+    /** Set system-wide activation for a capability/addon pair. */
+    setSystemActivation(capability: string, addonId: string, active: boolean): void;
+    /**
+     * Check if a specific addon's capability is active for a device.
+     *
+     * Resolution: 1. explicit device override → 2. system activation → 3. autoActivate → 4. default true
+     */
+    isActiveForDevice(capability: string, addonId: string, deviceId: string): boolean;
+    /** Set device activation for a capability/addon pair. */
+    setDeviceActivation(deviceId: string, capability: string, addonId: string, active: boolean): void;
+    /**
+     * Get all addon/capability activations for a device.
+     * Returns every registered provider with its resolved active status.
+     */
+    getDeviceActivations(deviceId: string): ReadonlyArray<{
+        capability: string;
+        addonId: string;
+        active: boolean;
+    }>;
+    /**
+     * Get all addon/capability activations at system level.
+     * Returns every registered provider with its resolved active status.
+     */
+    getSystemActivations(): ReadonlyArray<{
+        capability: string;
+        addonId: string;
+        active: boolean;
+    }>;
+    /** Set a per-device singleton override. */
+    setDeviceOverride(deviceId: string, capability: string, addonId: string): void;
+    /** Clear a per-device singleton override. */
+    clearDeviceOverride(deviceId: string, capability: string): void;
+    /** Get all per-device singleton overrides for a device. */
+    getDeviceOverrides(deviceId: string): Map<string, string>;
+    /**
+     * Resolve a singleton provider for a specific device.
+     * Checks activation (autoActivate + explicit overrides) then per-device override.
+     */
+    resolveForDevice<T = unknown>(capability: string, deviceId: string): T | null;
+    /** Set a per-device collection filter. */
+    setDeviceCollectionFilter(deviceId: string, capability: string, addonIds: string[]): void;
+    /** Clear a per-device collection filter. */
+    clearDeviceCollectionFilter(deviceId: string, capability: string): void;
+    /**
+     * Resolve collection providers for a specific device.
+     * Filters by activation (autoActivate + explicit overrides) and optional collection filter.
+     */
+    resolveCollectionForDevice<T = unknown>(capability: string, deviceId: string): readonly T[];
+    /** Check if all dependencies for a capability are satisfied. */
+    areDependenciesMet(capabilityName: string): boolean;
+    /** Get topologically sorted boot order based on dependsOn. */
+    getBootOrder(): string[];
+    /** Get all auto-mounted routers. Key = capability name. */
+    getMountedRouters(): ReadonlyMap<string, CapabilityRouter>;
+    /** Get a single mounted router by capability name. */
+    getRouter(capabilityName: string): CapabilityRouter | null;
+    /** List all declared capabilities (v1-compatible shape). */
+    listCapabilities(): CapabilityInfo[];
+    /** Check if a capability is declared. */
+    has(capabilityName: string): boolean;
+    /** Check if a capability has at least one provider. */
+    isAvailable(capabilityName: string): boolean;
+    /**
+     * Return every declared device-scoped capability (`scope: 'device'`)
+     * whose `deviceTypes` list includes the given type — or caps that declare
+     * no explicit `deviceTypes` (treat as applies-to-all). Used by the
+     * bindings UI to enumerate which caps the user can wire for a device.
+     */
+    listDeviceScopedCapsForType(deviceType: string): readonly string[];
+    private emitEvent;
+}

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

@@ -0,0 +1,212 @@
+import { AppConfig } from './config-schema.js';
+import { FeatureManifest } from '@camstack/types';
+export interface AddonSettingsView {
+    readAddonStore(): Promise<Record<string, unknown>>;
+    writeAddonStore(patch: Record<string, unknown>): Promise<void>;
+    readDeviceStore(deviceId: number): Promise<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>;
+}
+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;
+}
+export declare class ConfigManager {
+    private readonly configPath;
+    private bootstrapConfig;
+    private settingsStore;
+    private runtimeState;
+    private readonly runtimeStatePath;
+    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;
+    /**
+     * Get a config value by dot-notation path.
+     * Priority: bootstrap config (yaml) → settings-store → RUNTIME_DEFAULTS fallback.
+     *
+     * 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(path: string): unknown;
+    get<T>(path: string): T | undefined;
+    private resolveConfigValue;
+    /**
+     * Write a value to the settings-store.
+     * Throws if the settings store is not yet wired.
+     */
+    set(key: string, value: unknown): 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.
+     */
+    getSection(section: string): Record<string, unknown>;
+    /**
+     * 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. */
+    getAddonConfig(addonId: string): 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.
+     */
+    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;
+    createSettingsView(addonId: string): AddonSettingsView;
+    /** Get all system-wide activation overrides. */
+    getSystemActivation(): Readonly<Record<string, boolean>>;
+    /** Set system-wide activation for a capability/addon pair. */
+    setSystemActivation(capability: string, addonId: string, active: boolean): void;
+    /**
+     * Get activation overrides for a device.
+     * Returns a map of `{capability}/{addonId}` → active boolean.
+     * Missing entries mean "use system activation or autoActivate default".
+     */
+    getDeviceActivation(deviceId: string): Readonly<Record<string, boolean>>;
+    /**
+     * Get all device activation overrides.
+     * Returns deviceId → (`{capability}/{addonId}` → active).
+     */
+    getAllDeviceActivation(): Readonly<Record<string, Record<string, boolean>>>;
+    /**
+     * Set activation for a specific capability/addon on a device.
+     * Persists immediately to runtime-state.json.
+     *
+     * @param deviceId - The device to configure
+     * @param capability - Capability name (e.g., 'motion-detection')
+     * @param addonId - Addon providing the capability (e.g., 'wasm-motion')
+     * @param active - Whether the capability is active on this device
+     */
+    setDeviceActivation(deviceId: string, capability: string, addonId: string, active: boolean): void;
+    /**
+     * Clear all activation overrides for a device (resets to autoActivate defaults).
+     */
+    clearDeviceActivation(deviceId: string): void;
+    /** 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(path: string): unknown;
+    getBootstrap<T>(path: 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.
+     */
+    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.
+     */
+    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;
+    /**
+     * 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 loadRuntimeState;
+    private saveRuntimeState;
+}