@camstack/system 1.2.390 → 1.2.392

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

@@ -1,5 +1,17 @@
-import { CapabilityDeclaration, CapabilityDefinition, CapabilityInfo, CapabilityMode, CapabilityProviderMap, CollectionCapabilityMap, IEventBus, IScopedLogger, SingletonCapabilityMap } from '@camstack/types';
-import { StatusOverlay, StatusOverlayAnswer } from './status-overlay.js';
+/**
+* CapabilityRegistry — auto-mounts tRPC routers from CapabilityDefinitions.
+*
+* Responsibilities:
+*   - Register/unregister providers for capabilities
+*   - Auto-create tRPC routers for each registered capability (via factory function)
+*   - Emit lifecycle events on the EventBus
+*   - Provide typed getProvider() for consumers
+*
+* Does NOT contain tRPC code directly — receives a router factory function
+* from the server layer (which owns @trpc/server).
+*/
+import type { CapabilityDeclaration, CapabilityDefinition, CapabilityInfo, CapabilityMode, CapabilityProviderMap, CollectionCapabilityMap, IEventBus, IScopedLogger, SingletonCapabilityMap } from "@camstack/types";
+import { type StatusOverlay, type StatusOverlayAnswer } from "./status-overlay.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. */
@@ -7,585 +19,585 @@ export type CapabilityRouterFactory = (definition: CapabilityDefinition, getProv
 /** 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.
- */
+* 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;
 /**
- * Proof that an unregister owns the registration it is about to delete.
- *
- * A `(capability, addonId)` key is NOT unique over time: a runner replaced by
- * an update re-registers under the exact same key (`resolveRunnerId` is
- * deterministic), so the dead generation's teardown and the live generation's
- * registration are indistinguishable by key alone. The owner token names the
- * INCARNATION that made a registration — e.g. `hub/recorder#7` — and
- * {@link CapabilityRegistry.unregisterProvider} refuses any unregister that
- * cannot present it. See docs/decisions/adr-0188-an-unregister-carries-proof-of-ownership.md.
- */
+* Proof that an unregister owns the registration it is about to delete.
+*
+* A `(capability, addonId)` key is NOT unique over time: a runner replaced by
+* an update re-registers under the exact same key (`resolveRunnerId` is
+* deterministic), so the dead generation's teardown and the live generation's
+* registration are indistinguishable by key alone. The owner token names the
+* INCARNATION that made a registration — e.g. `hub/recorder#7` — and
+* {@link CapabilityRegistry.unregisterProvider} refuses any unregister that
+* 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;
-    }>;
+	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;
-    private readonly eventBus;
-    private routerFactory;
-    private configReader;
-    private collectionConfigReader;
-    private _ready;
-    /** Boot-time dependency graph: capability → dependsOn names (from CapabilityDeclaration) */
-    private readonly capabilityDeps;
-    /**
-     * capability → addon ids whose MANIFEST declares it.
-     *
-     * Populated by {@link declareFromManifest}, which runs at addon-LOAD time —
-     * before a forked addon's runner has spawned, let alone registered anything.
-     * So this map answers a question `providers` cannot: **which addons still owe
-     * this capability a provider**, i.e. is an absence final or merely early.
-     *
-     * It is not a second registry and nothing waits on it: it stores an argument
-     * `declareFromManifest` was already being handed and dropping, and it is read
-     * synchronously at the moment a caller needs the answer ([D3](../../../../docs/decisions/adr-0003.md)).
-     */
-    private readonly manifestDeclarers;
-    /** 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 SOURCE deactivations: deviceId → (capability → disabled addon ids).
-     *
-     * The in-memory PROJECTION of the persisted wrapper activation
-     * (`deviceBindings[deviceId][capName].disabledSourceAddonIds`, written by
-     * `setWrapperActive`), and never an authority of its own —
-     * [D556](../../../../docs/decisions/adr-0556-a-per-device-source-switch-is-the-wrapper-activation-and-the-registry-holds-only-its-projection.md).
-     * Nothing but `device-source-activation.ts` writes it: the operator's verb
-     * is `deviceManager.setWrapperActive`, and a second writable surface here is
-     * exactly the two-authorities defect D62 exists for.
-     *
-     * A DENY list, not an allow list, and that is the deliberate answer to what
-     * "unset" means: a source nobody has ruled out is a source. An untouched
-     * camera keeps every provider it has today, and a provider that registers
-     * after the operator's last toggle needs no second write to be seen.
-     */
-    /** 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;
-    /** 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`.
-     *
-     * `owner` (optional) stamps the registration with the incarnation that made
-     * it — see {@link ProviderOwnerToken}. Once stamped, only an unregister
-     * presenting the SAME token can delete it. Registration paths whose key is
-     * reused across process generations (the UDS child manifest, the D3
-     * `registerNode` handshake) MUST pass one; ownerless registrations keep the
-     * historical unconditional behaviour.
-     */
-    registerProvider(capabilityName: string, addonId: string, provider: unknown, owner?: ProviderOwnerToken): void;
-    /**
-     * Whether a provider for the exact `(capabilityName, addonId)` pair is
-     * currently registered. Lets a re-registration path (e.g. the agent's
-     * in-place group-runner reload) make {@link registerProvider} idempotent by
-     * dropping a stale prior registration first — `registerProvider` itself
-     * throws on a duplicate pair (a deliberate guard against a duplicate
-     * `registerProvider` call inside one init path), so callers that legitimately
-     * re-register the same pair must unregister first.
-     */
-    hasProvider(capabilityName: string, addonId: string): boolean;
-    /**
-     * Addon ids whose manifest declares `capabilityName`, whether or not they
-     * have registered a provider yet.
-     *
-     * Pair it with {@link hasProvider} to separate "this capability's collection
-     * is still filling up" from "this is everything there will ever be" — the
-     * difference between a 503 a client should retry and a 400 it should not.
-     * Every entry is an addon INSTALLED on this node; an addon that is installed
-     * but disabled therefore stays listed, which is the honest answer (the
-     * capability is owed by something that is not going to supply it, and naming
-     * it is the diagnosis).
-     */
-    getManifestDeclarers(capabilityName: string): readonly string[];
-    /**
-     * The owner token a registration declared, or `null` when the pair is not
-     * registered or was registered without one.
-     */
-    getProviderOwner(capabilityName: string, addonId: string): ProviderOwnerToken | null;
-    /**
-     * Hand an EXISTING registration to a new owner, without touching the provider
-     * instance, the active-singleton selection or any event.
-     *
-     * The takeover case: a replacement runner handshakes with an UNCHANGED cap
-     * set, so the manifest diff correctly leaves the registration alone — but the
-     * registration is still stamped with the dead generation's token, and nothing
-     * the LIVE generation can present would ever match it. Re-stamping keeps the
-     * capability cleanable when the successor eventually dies.
-     *
-     * Returns `false` when the pair is not registered (nothing to hand over) —
-     * the caller decides whether that is a register-instead or a diagnosis.
-     */
-    reassignProviderOwner(capabilityName: string, addonId: string, owner: ProviderOwnerToken): boolean;
-    /**
-     * Unregister a provider. For singleton: clears active. For collection:
-     * removes from list.
-     *
-     * `owner` is the caller's PROOF that it owns the registration it is deleting.
-     * When the registration declared an owner (see {@link ProviderOwnerToken})
-     * and the caller presents a different one — or none at all — this is a
-     * logged no-op: the caller belongs to a generation that no longer holds the
-     * key. This is what stops a dead runner's teardown from erasing its
-     * 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). */
-    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. A CLAIMED
-     * cap's provider is handed back with its `getStatus` overlaid (D663, S3) —
-     * on the in-process branch AND the `nativeFallback` branch, which is the
-     * path the HA feeder's devices take.
-     */
-    getNativeProvider<T = unknown>(capName: string, deviceId: number): T | null;
-    /** The device-manager's view over its mirror; `null` until installed. */
-    private statusOverlay;
-    /** `(cap, device)` pairs whose merged slice currently fails its status schema — one warn per transition. */
-    private readonly overlayParseFailing;
-    /**
-     * Install (or remove, with `null`) the claimed-status overlay. Installed once
-     * by the device-manager at init over its `DeviceStateMirror`; removed on its
-     * shutdown. Wrappers already resolved re-read it at call time, so an
-     * uninstall hands `getStatus` back to the native immediately.
-     */
-    setStatusOverlay(overlay: StatusOverlay | null): void;
-    /**
-     * THE question every `getStatus` awaits before it is answered (the registry's
-     * own wrappers at call time, and the three transport entries through
-     * `answerClaimedGetStatus`). The overlay resolves the device's claims first;
-     * `unknown` survives only when its row cannot be read, and the caller then
-     * answers "not reported", never the native (D315, D49).
-     *
-     * A claimed slice is parsed with the cap's `status.schema` — S4 makes
-     * `status ⊆ runtimeState`, so the merged runtime slice parses and a
-     * runtime-only key such as `lastFetchedAt` is stripped. A slice that does not
-     * parse is `null`, logged once per `(cap, device)` transition with the device
-     * tag; a held claim is `null` without a parse. A cap with no `status` block
-     * passes its merged slice through as is.
-     */
-    resolveClaimedStatus(capName: string, deviceId: number): Promise<StatusOverlayAnswer>;
-    private parseClaimed;
-    /**
-     * Hand `provider` back untouched when `(capName, deviceId)` is KNOWN to be
-     * unclaimed; otherwise wrap it so `getStatus` awaits `resolveClaimedStatus`
-     * (re-read at call time — the parse, and for an unknown device the row read,
-     * happen only when `getStatus` is actually called) and everything else stays
-     * the provider's own. An unclaimed device pays one in-memory lookup; with no
-     * overlay installed it pays nothing.
-     */
-    private withOverlay;
-    /** 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])[];
-    /**
-     * Is `addonId` currently DISABLED as a provider of `capability`?
-     *
-     * Exposed because the disabled set was write-only for `log-destination`:
-     * the orchestrator toggle added the addon here and nothing ever read it, so
-     * console and winston could not be turned off at all while the UI badge said
-     * they were (audit 2026-07-30).
-     */
-    isProviderDisabled(capability: string, addonId: string): boolean;
-    /** 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;
-    /**
-     * Every registry KEY currently registered for `capability`, disabled ones
-     * included — i.e. exactly the ids {@link getProviderByAddonId} can resolve.
-     * Keys are bare (`homeassistant-export`) for hub-local providers and
-     * `<addonId>@<nodeId>` for providers that registered from another node.
-     *
-     * Exists so an unresolvable `{ addonId }` pin can REFUSE with the valid ids
-     * spelled out (the `addons.custom` unknown-id posture) instead of silently
-     * degrading to another provider's answer — a fabricated `addonId` used to
-     * return the first-registered provider's status, indistinguishable from
-     * success (2026-08-09).
-     */
-    getProviderAddonIds(capability: string): readonly string[];
-    /** 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.
-     *
-     * Resolution: the manifest's `autoActivate` flag, else active. There is no
-     * persisted override layer — see D334: an activation map keyed by
-     * `{capability}/{addonId}` is a second authority over a function some addon
-     * already owns, which is what D62 forbids.
-     */
-    isActiveForSystem(capability: string, addonId: string): 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 (the manifest's autoActivate) then the per-device
-     * singleton override — the in-memory provider pin, not a persisted flag.
-     */
-    resolveForDevice<T = unknown>(capability: string, deviceId: string): T | null;
-    /**
-     * Resolve collection providers for a specific device.
-     *
-     * Filters by activation (the manifest's autoActivate) and by nothing else.
-     * The per-device DENY set that used to filter here is gone with the switch
-     * it projected (2026-09-20): *"tutti i providers funzionano sempre"* [all the providers always work]. WHICH
-     * providers a device has is now answered by its BINDINGS
-     * (`device-bindings-store.ts` step 0), which is a different question from
-     * which of them are registered and running — this one.
-     *
-     * `deviceId` is kept in the signature and deliberately unused: the resolution
-     * is per-device by CONTRACT, and a caller that stops passing one is a caller
-     * that has stopped asking about a device.
-     */
-    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;
+	private readonly capabilities;
+	private readonly logger;
+	private readonly eventBus;
+	private routerFactory;
+	private configReader;
+	private collectionConfigReader;
+	private _ready;
+	/** Boot-time dependency graph: capability → dependsOn names (from CapabilityDeclaration) */
+	private readonly capabilityDeps;
+	/**
+	* capability → addon ids whose MANIFEST declares it.
+	*
+	* Populated by {@link declareFromManifest}, which runs at addon-LOAD time —
+	* before a forked addon's runner has spawned, let alone registered anything.
+	* So this map answers a question `providers` cannot: **which addons still owe
+	* this capability a provider**, i.e. is an absence final or merely early.
+	*
+	* It is not a second registry and nothing waits on it: it stores an argument
+	* `declareFromManifest` was already being handed and dropping, and it is read
+	* synchronously at the moment a caller needs the answer ([D3](../../../../docs/decisions/adr-0003.md)).
+	*/
+	private readonly manifestDeclarers;
+	/** 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 SOURCE deactivations: deviceId → (capability → disabled addon ids).
+	*
+	* The in-memory PROJECTION of the persisted wrapper activation
+	* (`deviceBindings[deviceId][capName].disabledSourceAddonIds`, written by
+	* `setWrapperActive`), and never an authority of its own —
+	* [D556](../../../../docs/decisions/adr-0556-a-per-device-source-switch-is-the-wrapper-activation-and-the-registry-holds-only-its-projection.md).
+	* Nothing but `device-source-activation.ts` writes it: the operator's verb
+	* is `deviceManager.setWrapperActive`, and a second writable surface here is
+	* exactly the two-authorities defect D62 exists for.
+	*
+	* A DENY list, not an allow list, and that is the deliberate answer to what
+	* "unset" means: a source nobody has ruled out is a source. An untouched
+	* camera keeps every provider it has today, and a provider that registers
+	* after the operator's last toggle needs no second write to be seen.
+	*/
+	/** 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;
+	/** 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`.
+	*
+	* `owner` (optional) stamps the registration with the incarnation that made
+	* it — see {@link ProviderOwnerToken}. Once stamped, only an unregister
+	* presenting the SAME token can delete it. Registration paths whose key is
+	* reused across process generations (the UDS child manifest, the D3
+	* `registerNode` handshake) MUST pass one; ownerless registrations keep the
+	* historical unconditional behaviour.
+	*/
+	registerProvider(capabilityName: string, addonId: string, provider: unknown, owner?: ProviderOwnerToken): void;
+	/**
+	* Whether a provider for the exact `(capabilityName, addonId)` pair is
+	* currently registered. Lets a re-registration path (e.g. the agent's
+	* in-place group-runner reload) make {@link registerProvider} idempotent by
+	* dropping a stale prior registration first — `registerProvider` itself
+	* throws on a duplicate pair (a deliberate guard against a duplicate
+	* `registerProvider` call inside one init path), so callers that legitimately
+	* re-register the same pair must unregister first.
+	*/
+	hasProvider(capabilityName: string, addonId: string): boolean;
+	/**
+	* Addon ids whose manifest declares `capabilityName`, whether or not they
+	* have registered a provider yet.
+	*
+	* Pair it with {@link hasProvider} to separate "this capability's collection
+	* is still filling up" from "this is everything there will ever be" — the
+	* difference between a 503 a client should retry and a 400 it should not.
+	* Every entry is an addon INSTALLED on this node; an addon that is installed
+	* but disabled therefore stays listed, which is the honest answer (the
+	* capability is owed by something that is not going to supply it, and naming
+	* it is the diagnosis).
+	*/
+	getManifestDeclarers(capabilityName: string): readonly string[];
+	/**
+	* The owner token a registration declared, or `null` when the pair is not
+	* registered or was registered without one.
+	*/
+	getProviderOwner(capabilityName: string, addonId: string): ProviderOwnerToken | null;
+	/**
+	* Hand an EXISTING registration to a new owner, without touching the provider
+	* instance, the active-singleton selection or any event.
+	*
+	* The takeover case: a replacement runner handshakes with an UNCHANGED cap
+	* set, so the manifest diff correctly leaves the registration alone — but the
+	* registration is still stamped with the dead generation's token, and nothing
+	* the LIVE generation can present would ever match it. Re-stamping keeps the
+	* capability cleanable when the successor eventually dies.
+	*
+	* Returns `false` when the pair is not registered (nothing to hand over) —
+	* the caller decides whether that is a register-instead or a diagnosis.
+	*/
+	reassignProviderOwner(capabilityName: string, addonId: string, owner: ProviderOwnerToken): boolean;
+	/**
+	* Unregister a provider. For singleton: clears active. For collection:
+	* removes from list.
+	*
+	* `owner` is the caller's PROOF that it owns the registration it is deleting.
+	* When the registration declared an owner (see {@link ProviderOwnerToken})
+	* and the caller presents a different one — or none at all — this is a
+	* logged no-op: the caller belongs to a generation that no longer holds the
+	* key. This is what stops a dead runner's teardown from erasing its
+	* 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). */
+	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. A CLAIMED
+	* cap's provider is handed back with its `getStatus` overlaid (D663, S3) —
+	* on the in-process branch AND the `nativeFallback` branch, which is the
+	* path the HA feeder's devices take.
+	*/
+	getNativeProvider<T = unknown>(capName: string, deviceId: number): T | null;
+	/** The device-manager's view over its mirror; `null` until installed. */
+	private statusOverlay;
+	/** `(cap, device)` pairs whose merged slice currently fails its status schema — one warn per transition. */
+	private readonly overlayParseFailing;
+	/**
+	* Install (or remove, with `null`) the claimed-status overlay. Installed once
+	* by the device-manager at init over its `DeviceStateMirror`; removed on its
+	* shutdown. Wrappers already resolved re-read it at call time, so an
+	* uninstall hands `getStatus` back to the native immediately.
+	*/
+	setStatusOverlay(overlay: StatusOverlay | null): void;
+	/**
+	* THE question every `getStatus` awaits before it is answered (the registry's
+	* own wrappers at call time, and the three transport entries through
+	* `answerClaimedGetStatus`). The overlay resolves the device's claims first;
+	* `unknown` survives only when its row cannot be read, and the caller then
+	* answers "not reported", never the native (D315, D49).
+	*
+	* A claimed slice is parsed with the cap's `status.schema` — S4 makes
+	* `status ⊆ runtimeState`, so the merged runtime slice parses and a
+	* runtime-only key such as `lastFetchedAt` is stripped. A slice that does not
+	* parse is `null`, logged once per `(cap, device)` transition with the device
+	* tag; a held claim is `null` without a parse. A cap with no `status` block
+	* passes its merged slice through as is.
+	*/
+	resolveClaimedStatus(capName: string, deviceId: number): Promise<StatusOverlayAnswer>;
+	private parseClaimed;
+	/**
+	* Hand `provider` back untouched when `(capName, deviceId)` is KNOWN to be
+	* unclaimed; otherwise wrap it so `getStatus` awaits `resolveClaimedStatus`
+	* (re-read at call time — the parse, and for an unknown device the row read,
+	* happen only when `getStatus` is actually called) and everything else stays
+	* the provider's own. An unclaimed device pays one in-memory lookup; with no
+	* overlay installed it pays nothing.
+	*/
+	private withOverlay;
+	/** 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])[];
+	/**
+	* Is `addonId` currently DISABLED as a provider of `capability`?
+	*
+	* Exposed because the disabled set was write-only for `log-destination`:
+	* the orchestrator toggle added the addon here and nothing ever read it, so
+	* console and winston could not be turned off at all while the UI badge said
+	* they were (audit 2026-07-30).
+	*/
+	isProviderDisabled(capability: string, addonId: string): boolean;
+	/** 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;
+	/**
+	* Every registry KEY currently registered for `capability`, disabled ones
+	* included — i.e. exactly the ids {@link getProviderByAddonId} can resolve.
+	* Keys are bare (`homeassistant-export`) for hub-local providers and
+	* `<addonId>@<nodeId>` for providers that registered from another node.
+	*
+	* Exists so an unresolvable `{ addonId }` pin can REFUSE with the valid ids
+	* spelled out (the `addons.custom` unknown-id posture) instead of silently
+	* degrading to another provider's answer — a fabricated `addonId` used to
+	* return the first-registered provider's status, indistinguishable from
+	* success (2026-08-09).
+	*/
+	getProviderAddonIds(capability: string): readonly string[];
+	/** 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.
+	*
+	* Resolution: the manifest's `autoActivate` flag, else active. There is no
+	* persisted override layer — see D334: an activation map keyed by
+	* `{capability}/{addonId}` is a second authority over a function some addon
+	* already owns, which is what D62 forbids.
+	*/
+	isActiveForSystem(capability: string, addonId: string): 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 (the manifest's autoActivate) then the per-device
+	* singleton override — the in-memory provider pin, not a persisted flag.
+	*/
+	resolveForDevice<T = unknown>(capability: string, deviceId: string): T | null;
+	/**
+	* Resolve collection providers for a specific device.
+	*
+	* Filters by activation (the manifest's autoActivate) and by nothing else.
+	* The per-device DENY set that used to filter here is gone with the switch
+	* it projected (2026-09-20): *"tutti i providers funzionano sempre"* [all the providers always work]. WHICH
+	* providers a device has is now answered by its BINDINGS
+	* (`device-bindings-store.ts` step 0), which is a different question from
+	* which of them are registered and running — this one.
+	*
+	* `deviceId` is kept in the signature and deliberately unused: the resolution
+	* is per-device by CONTRACT, and a caller that stops passing one is a caller
+	* that has stopped asking about a device.
+	*/
+	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;
 }