@camstack/addon-pipeline-orchestrator 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,907 @@
+import * as _camstack_types from '@camstack/types';
+import { RunnerLocalLoad, PipelineAssignment, IPipelineOrchestratorProvider, RunnerCameraConfig, BaseAddon, AddonInitResult, CameraMetrics, AgentLoadSummary, PipelineOrchestratorGlobalMetrics, DecoderAssignment, AgentPipelineSettings, AgentAddonConfig, CameraPipelineSettings, CameraStepOverridePatch, CameraPipelineConfig, CameraPipelineTemplate, ConfigUISchemaWithValues, CameraDetectionConfig } from '@camstack/types';
+import { z } from 'zod';
+
+/**
+ * Input to the load balancer: one entry per online runner node.
+ */
+interface BalancerInput {
+    /** Per-node load snapshots fetched from each runner's `getLocalLoad()` cap. */
+    readonly nodes: readonly RunnerLocalLoad[];
+    /** Optional L1 affinity — if set and the node is online, it wins unconditionally. */
+    readonly preferredAgent?: string | null;
+}
+/**
+ * Output of the load balancer: the picked agent nodeId plus the reason the
+ * balancer chose it. `null` when no online runner is available.
+ */
+interface BalancerDecision {
+    readonly agentNodeId: string;
+    readonly reason: 'manual' | 'capacity';
+    readonly score: number;
+}
+/**
+ * Compute the L2 capacity score for a runner node. Lower is better.
+ * The score is a weighted sum of the runner's active workload so the balancer
+ * prefers agents that are serving fewer cameras OR draining queues quickly.
+ *
+ * Rationale:
+ *  - `attachedCameras * avgInferenceFps` approximates the total inference rate
+ *    the agent is currently sustaining (not just how many cameras are assigned).
+ *  - `queueDepthTotal` penalises agents that are falling behind the frame feed.
+ */
+declare function computeCapacityScore(load: RunnerLocalLoad): number;
+/**
+ * Run the two-level camera balancer.
+ *
+ * L1 (manual affinity): if `preferredAgent` names an online node, return it.
+ * L2 (capacity): compute capacity scores and pick the lowest.
+ *
+ * Returns `null` when no runners are online. The orchestrator decides how to
+ * react — typically by logging and deferring the assignment until a runner
+ * comes online.
+ */
+declare function balance(input: BalancerInput): BalancerDecision | null;
+interface DecoderBalancerInput {
+    readonly decoderNodes: readonly RunnerLocalLoad[];
+    readonly pipelineNodeId: string;
+    readonly preferredDecoderNode?: string | null;
+}
+interface DecoderBalancerDecision {
+    readonly decoderNodeId: string;
+    readonly reason: 'manual' | 'capacity' | 'co-located';
+    readonly score: number;
+}
+/**
+ * Choose decoder node. Priority: manual pin → co-located with pipeline → capacity.
+ */
+declare function balanceDecoder(input: DecoderBalancerInput): DecoderBalancerDecision | null;
+
+/**
+ * Custom-action catalog exposed through `api.addons.custom` (Task 9.1 PoC).
+ *
+ * The orchestrator's cap surface is the contract for all runtime traffic
+ * (assignCamera / unassignCamera / rebalance / getGlobalMetrics etc). This
+ * catalog is reserved for read-only diagnostics that are intentionally
+ * outside the cap — they expose internal state (balancer caches, enabledNodes
+ * set, active detection count) that is useful for admin tooling but does not
+ * belong on the capability contract.
+ */
+declare const OrchestratorDiagnosticsSchema: z.ZodObject<{
+    localNodeId: z.ZodString;
+    knownRunnerNodes: z.ZodArray<z.ZodString>;
+    cachedAgentLoadNodeIds: z.ZodArray<z.ZodString>;
+    enabledNodes: z.ZodArray<z.ZodString>;
+    assignedDeviceCount: z.ZodNumber;
+    cameraConfigCount: z.ZodNumber;
+    activeDetectionCount: z.ZodNumber;
+}, z.core.$strip>;
+type OrchestratorDiagnostics = z.infer<typeof OrchestratorDiagnosticsSchema>;
+declare const pipelineOrchestratorActions: {
+    dumpState: _camstack_types.CustomActionSpec<z.ZodVoid, z.ZodObject<{
+        localNodeId: z.ZodString;
+        knownRunnerNodes: z.ZodArray<z.ZodString>;
+        cachedAgentLoadNodeIds: z.ZodArray<z.ZodString>;
+        enabledNodes: z.ZodArray<z.ZodString>;
+        assignedDeviceCount: z.ZodNumber;
+        cameraConfigCount: z.ZodNumber;
+        activeDetectionCount: z.ZodNumber;
+    }, z.core.$strip>, "query", "protected", {
+        readonly kind: "system";
+    }>;
+};
+type PipelineOrchestratorActions = typeof pipelineOrchestratorActions;
+/**
+ * Result of a successful dispatch. Returned by `dispatchCamera` so the
+ * caller (DetectionWiringService) can log / emit follow-up events with
+ * the same rationale the balancer used.
+ */
+interface DispatchResult {
+    readonly success: true;
+    readonly agentNodeId: string;
+    readonly reason: PipelineAssignment["reason"];
+}
+/**
+ * Local-only provider surface resolved via the kernel capability registry.
+ * Extends the cap interface with the in-process dispatch entrypoints that
+ * can't cleanly round-trip through the tRPC serializer because they carry
+ * a full `PipelineConfig` payload attached to the `RunnerCameraConfig`.
+ */
+interface IPipelineOrchestratorLocalProvider extends IPipelineOrchestratorProvider {
+    /**
+     * In-process dispatch entrypoint. Caches the config, runs the load
+     * balancer, dispatches the attach call to the chosen runner.
+     */
+    dispatchCamera(runnerConfig: RunnerCameraConfig): Promise<DispatchResult>;
+    /** In-process release entrypoint — detach + clear cached state. */
+    releaseCamera(input: {
+        deviceId: number;
+    }): Promise<{
+        success: true;
+    }>;
+}
+declare class PipelineOrchestratorAddon extends BaseAddon implements IPipelineOrchestratorLocalProvider {
+    /** This node's Moleculer nodeId (from this.ctx.kernel.localNodeId). */
+    private localNodeId;
+    /** Set of nodeIds known to be running pipeline-runner; maintained via AgentOnline/AgentOffline events. */
+    private readonly knownRunnerNodes;
+    /** EventBus unsubscribes for agent online/offline events. */
+    private unsubAgentOnline;
+    private unsubAgentOffline;
+    /**
+     * Readiness tracker — drives `detection-pipeline` seed on every
+     * provider life cycle. Prefers the kernel-shared singleton via
+     * `ctx.kernel.readinessRegistry`; falls back to a local instance for
+     * test contexts without a kernel.
+     */
+    private readinessRegistry;
+    /** True when this addon owns the registry (local fallback) and should `close()` it on shutdown. */
+    private ownsReadinessRegistry;
+    /** Per-node readiness subscription unsubs — torn down on AgentOffline / shutdown. */
+    private readonly readinessSubsByNode;
+    /** Per-node idempotency guard — re-seed only when the producer's epoch advances. */
+    private readonly lastSeenReadinessEpochByNode;
+    /** Most recent RunnerCameraConfig per device — used by rebalance + re-dispatch. */
+    private readonly cameraConfigs;
+    /**
+     * Per-camera zones CRUD provider. Constructed lazily in `onInitialize`
+     * because it captures `this.ctx` for settings + api access; cleared
+     * to null in `onShutdown` so a soft-restart is observable.
+     */
+    private zonesProvider;
+    /**
+     * Per-camera zone-rules CRUD provider — bulk-replace per stage,
+     * mirrors to dev.state slices `motion-zone-rules` /
+     * `detection-zone-rules` so consumer addons subscribe per stage.
+     */
+    private zoneRulesProvider;
+    /** In-memory assignment map — mirrored into events + per-device settings for the pin. */
+    private readonly assignments;
+    /** Per-device audio node assignment — nodeId of the audio-analyzer handling this device's chunks. */
+    private readonly audioNodeByDevice;
+    /** Assignments with metadata — replaces plain audioNodeByDevice values as the source of truth. */
+    private readonly audioAssignments;
+    /** Nodes known to have a ready audio-analyzer. */
+    private readonly readyAudioNodes;
+    /** Last seen readiness epoch per node for audio-analyzer. */
+    private readonly lastSeenAudioEpochByNode;
+    /** Last observed agent-load snapshot per runner, populated during each dispatch. */
+    private cachedAgentLoad;
+    /**
+     * Cached `PipelineSchema` per engine key (`runtime/backend/format`).
+     * Populated on demand by {@link getCatalogForEngine} via
+     * `pipelineExecutor.getSchema({nodeId})` and invalidated on every
+     * `$node.connected` / `$node.disconnected` — node changes can mean
+     * model downloads arrived, addons enabled, etc. TTL is a soft
+     * guard only (invalidation is the main signal).
+     */
+    private catalogCache;
+    private static readonly CATALOG_CACHE_TTL_MS;
+    /** Runtime failover policy, driven by `getConfigSchema` fields + `onConfigChange`. */
+    private failoverPolicy;
+    /**
+     * Hub-wide allow-list of node ids eligible to run the detection
+     * pipeline. Driven by the `enabledNodes` multiselect in the addon
+     * schema. Hydrated from the schema default (`['hub']`) on first
+     * boot; every other node must be explicitly added by the operator.
+     * The list is a strict whitelist — disabled nodes stay connected
+     * for other capabilities (metrics, logs, cluster-wide events) but
+     * never receive camera assignments.
+     */
+    private enabledNodes;
+    /**
+     * Hub-wide allow-list of node ids eligible to run decoder sessions.
+     * Driven by the `enabledDecoderNodes` multiselect in the addon schema.
+     * Defaults to `['hub']` — the hub always has a decoder available.
+     */
+    private enabledDecoderNodes;
+    /**
+     * Hub-wide allow-list of node ids eligible to run audio-analyzer sessions.
+     * Driven by the `enabledAudioNodes` multiselect in the addon schema.
+     * Defaults to `['hub']`.
+     */
+    private enabledAudioNodes;
+    /**
+     * Full global settings snapshot kept in memory so synchronous cap methods
+     * (e.g. `getGlobalOrchestrationSettings`) can resolve without awaiting the
+     * backing store. Refreshed in `initialize` and `onConfigChange`.
+     */
+    private globalSettings;
+    /** Per-device active detection config — set on startDetection, cleared on stopDetection. */
+    private readonly activeDetections;
+    /** Per-device audio broker unsubscribe callbacks. */
+    private readonly audioSubscriptions;
+    /** Per-device pending lazy-audio teardown timer (closes audio sub
+     *  after motion cooldown when audioMode === 'on-motion'). */
+    private readonly lazyAudioTeardownTimers;
+    /** Event bus subscription lifetimes. */
+    private unsubDeviceRegistered;
+    /** Pending CameraStreams.profileSlotsChanged debounce timers, cancelled on shutdown. */
+    private profileSlotTimers;
+    private unsubDeviceUnregistered;
+    private unsubSettingsChanged;
+    private unsubInferenceResult;
+    private unsubProviderDetection;
+    private unsubCameraUpdated;
+    private unsubBindingsChanged;
+    private unsubCameraMetrics;
+    private unsubLazyAudioMotion;
+    /** Per-camera last-seen actualFps for load management enforcement. */
+    private readonly cameraFpsMap;
+    /**
+     * Load-shed state per camera:
+     *   - `lowSinceTs`: timestamp of the first metrics snapshot that
+     *     dipped below `fpsMinThreshold`, or `null` when fps is healthy.
+     *     Camera pauses when `now - lowSinceTs >= fpsLowWindowMs`.
+     *     Resets to `null` the moment fps recovers above the threshold,
+     *     so transient dips (GC, model swap) don't accumulate.
+     *   - `pausedAt`: timestamp when camera was paused (null = not paused)
+     *   - `resumeAttempts`: number of auto-resume attempts (drives backoff)
+     */
+    private readonly loadShedState;
+    /** Timer for the auto-resume sweep. */
+    private loadShedResumeTimer;
+    private initTimestamp;
+    constructor();
+    protected onInitialize(): Promise<AddonInitResult<PipelineOrchestratorActions>>;
+    /**
+     * One-shot migration from the legacy per-device flags
+     * (`audioEnabled:false` / `pipelineEnabled:false` in the orchestrator's
+     * device-store, `disableInference:true` in the cameraSettings map) to
+     * the new binding system. For each match we call
+     * `device-manager.setWrapperActive(false)` so the equivalent state
+     * sticks after the flags are gone. Guarded by an addon-store flag so
+     * it runs at most once per cluster install.
+     *
+     * Runs in the background after onInitialize — the `ctx.api` usually
+     * lights up after a short delay once the device-manager + capability
+     * registry finish wiring, so we poll briefly and give up with a warn
+     * when the window closes. Failure re-arms on next boot since we only
+     * persist the flag after a successful pass.
+     */
+    private migrateLegacyFlagsToBindings;
+    /**
+     * Build the diagnostic snapshot exposed via the `dumpState` custom action.
+     * Pure read — never mutates state. Extracted from `handleCustomAction` so
+     * tests can assert the snapshot shape directly without going through the
+     * dispatcher.
+     */
+    private dumpDiagnostics;
+    protected onShutdown(): Promise<void>;
+    dispatchCamera(runnerConfig: RunnerCameraConfig): Promise<DispatchResult>;
+    releaseCamera(input: {
+        deviceId: number;
+    }): Promise<{
+        success: true;
+    }>;
+    assignPipeline(input: {
+        deviceId: number;
+        agentNodeId: string;
+    }): Promise<{
+        success: true;
+    }>;
+    unassignPipeline(input: {
+        deviceId: number;
+    }): Promise<{
+        success: true;
+    }>;
+    rebalance(): Promise<{
+        migrated: number;
+    }>;
+    getPipelineAssignments(): readonly PipelineAssignment[];
+    getPipelineAssignment(input: {
+        deviceId: number;
+    }): PipelineAssignment | null;
+    /**
+     * Per-camera live metrics. Centralised entry point for the UI: the
+     * orchestrator owns the device→agent assignment map, so it knows
+     * which runner holds the camera and can route the cap call to the
+     * exact node. Calling `pipelineRunner.getCameraMetrics` directly
+     * from the UI breaks in multi-agent setups because the hub-side cap
+     * router resolves the runner singleton against the registry's first-
+     * registered provider, which races between agents and may not be the
+     * one the orchestrator actually dispatched the camera to.
+     */
+    getCameraMetrics(input: {
+        deviceId: number;
+    }): Promise<CameraMetrics | null>;
+    /**
+     * Live snapshot of every runner's load. Triggers a fresh
+     * `collectAgentLoad()` on each call so the UI's "Live load" panel
+     * always reflects reality — the in-memory cache is only populated
+     * during dispatch / rebalance, so without a refresh here the panel
+     * would stay empty until the next dispatch event (problematic after
+     * a server restart that rehydrates assignments from disk without
+     * re-dispatching).
+     */
+    getAgentLoad(): Promise<readonly AgentLoadSummary[]>;
+    getGlobalMetrics(): Promise<PipelineOrchestratorGlobalMetrics>;
+    /**
+     * Call `attachCamera` on the target runner via this.ctx.api. The generated cap
+     * router extracts `nodeId` from the input and routes to local or remote
+     * runner transparently — no broker reference needed.
+     */
+    private attachOn;
+    private detachOn;
+    private localRunnerNodeId;
+    /**
+     * Enumerate every runner-capable node currently known (populated via
+     * AgentOnline/AgentOffline events). Used to populate the `enabledNodes`
+     * multiselect options at schema-build time.
+     *
+     * Forked child nodeIds (`hub/classifier`, `agent-1/motion-wasm`) are
+     * filtered out — they name isolated-process services, never dispatchable
+     * pipeline runners. The on-write guards in AgentOnline + applyRuntimeSettings
+     * already exclude them, but we filter here too so any legacy seed that
+     * slipped in before those guards existed doesn't leak into the UI picker.
+     */
+    private collectRunnerNodeIds;
+    /**
+     * Enumerate every node currently known as decoder-capable. Reuses
+     * `knownRunnerNodes` since any runner node can potentially host a
+     * decoder session. `hub` is always included. Forked child nodeIds are
+     * filtered out for the same reason as `collectRunnerNodeIds`.
+     */
+    private collectDecoderNodeIds;
+    /**
+     * Enumerate every node currently known as audio-analyzer-capable.
+     * Uses `knownRunnerNodes` as the universe and filters out child
+     * nodeIds (containing '/') the same way the other collectors do.
+     */
+    private collectAudioNodeIds;
+    /**
+     * Resolve which node should run the decoder for a given device.
+     * Reads the per-device `decoderNodeId` pin first (manual override),
+     * then falls back to the `balanceDecoder` algorithm which prefers
+     * co-location with the pipeline node, then capacity.
+     */
+    private resolveDecoderNode;
+    /**
+     * Return `true` when `nodeId` is in the `enabledNodes` whitelist.
+     * A strict list — an empty whitelist means "no node allowed", not
+     * "all nodes allowed". The schema default (`['hub']`) guarantees
+     * fresh installs always have at least the hub enabled.
+     */
+    private isNodeEnabled;
+    /**
+     * Query every online runner in the cluster for its current load, plus the
+     * local runner if co-located. Refreshes the `cachedAgentLoad` snapshot so
+     * `getAgentLoad()` / `getGlobalMetrics()` can return fresh data.
+     *
+     * `{onlyEnabled: true}` applies the `enabledNodes` whitelist filter —
+     * used when the caller is the dispatcher / balancer and must only
+     * see runners eligible for new camera assignments. The default
+     * (unfiltered) collects every known runner, which is what the UI
+     * wants: operators need visibility into every connected node, even
+     * ones currently disabled from the dispatch pool.
+     */
+    private collectAgentLoad;
+    private refreshAgentLoadCache;
+    private readPreferredAgent;
+    private readAudioNodePin;
+    private collectAudioNodeLoad;
+    private recordAudioAssignment;
+    private dispatchAudio;
+    private recordAssignment;
+    private emitUnassigned;
+    /**
+     * Failover handler. When a runner node goes offline, the behaviour is
+     * driven by the persisted failover policy (`failoverPolicy`):
+     *  - `onDisconnect: 'migrate'` → move non-pinned cameras to another runner
+     *  - `onDisconnect: 'leave-unassigned'` → drop all assignments for the node
+     *  - `pinnedOnDisconnect: 'leave-pinned'` → pinned cameras stay unassigned
+     *  - `pinnedOnDisconnect: 'unpin-and-migrate'` → clear the pin + migrate
+     */
+    private handleNodeDisconnect;
+    /**
+     * Reconnect handler. When a runner node comes back online, the behaviour
+     * is driven by the `onReconnect` policy:
+     *  - `restore` → re-attach cameras previously assigned to that node
+     *    (only the ones still known in `cameraConfigs`)
+     *  - `rebalance` → run a full `rebalance()` pass so non-pinned cameras
+     *    can migrate back onto the newly-available runner
+     */
+    private handleNodeConnect;
+    /**
+     * Subscribe to `detection-pipeline` readiness transitions for `nodeId`.
+     * Idempotent: re-subscribing the same node is a no-op. The handler
+     * skips same-epoch replays so repeated `ready` emits don't force
+     * redundant reseeds.
+     */
+    private subscribeToDetectionPipelineReadiness;
+    private unsubscribeDetectionPipelineReadiness;
+    /**
+     * Subscribe to `audio-analyzer` readiness transitions for `nodeId`.
+     * Idempotent — re-subscribing the same node is a no-op (uses its own
+     * key space separate from detection readiness subscriptions).
+     */
+    private subscribeToAudioAnalyzerReadiness;
+    private handleAudioAnalyzerReadiness;
+    /**
+     * Act on a `detection-pipeline` transition: on `ready` with a new
+     * epoch (= producer restart or first-time ready), invalidate the
+     * catalog cache, re-seed that node's `agentAddonDefaults`, and
+     * redispatch every camera currently assigned to it. Everything else
+     * (down, starting, same-epoch keepalive) is skipped.
+     */
+    private handleDetectionPipelineReadiness;
+    /**
+     * Walk every cached RunnerCameraConfig and re-attach any whose stored
+     * `steps` are empty AND whose latest resolve produces a non-empty
+     * pipeline. Catches the "camera dispatched mid-readiness" race where
+     * the initial attach landed BEFORE the catalog was cached but the
+     * subsequent readiness sweep already finished iterating.
+     */
+    private reattachStaleEmpties;
+    getCapabilityBindings(input: {
+        nodeId: string;
+    }): Promise<Readonly<Record<string, string>>>;
+    setCapabilityBinding(input: {
+        nodeId: string;
+        capName: string;
+        addonId: string;
+    }): Promise<{
+        success: true;
+    }>;
+    assignDecoder(input: {
+        readonly deviceId: number;
+        readonly nodeId: string;
+    }): Promise<void>;
+    unassignDecoder(input: {
+        readonly deviceId: number;
+    }): Promise<void>;
+    /**
+     * Per-camera decoder node accessor (Phase 8). Exposes the existing
+     * private `resolveDecoderNode` logic as a cap method so
+     * `stream-broker.createBroker` can filter its decoder provider
+     * selection deterministically. Caller hint: pass `pipelineNodeId` to
+     * bias the balancer toward co-location with the runner; omitted → the
+     * last-known assignment, else 'hub'.
+     */
+    getDecoderAssignment(input: {
+        readonly deviceId: number;
+        readonly pipelineNodeId?: string;
+    }): Promise<DecoderAssignment>;
+    getDecoderAssignments(): Promise<readonly DecoderAssignment[]>;
+    assignAudio(input: {
+        readonly deviceId: number;
+        readonly nodeId: string;
+    }): Promise<{
+        success: true;
+    }>;
+    unassignAudio(input: {
+        readonly deviceId: number;
+    }): Promise<{
+        success: true;
+    }>;
+    getAudioAssignment(input: {
+        readonly deviceId: number;
+    }): Promise<{
+        nodeId: string;
+        pinned: boolean;
+        assignedAt: number;
+    } | null>;
+    getAudioNodeLoad(): Promise<Array<{
+        nodeId: string;
+        deviceCount: number;
+    }>>;
+    getAudioAssignments(): Promise<Array<{
+        deviceId: number;
+        nodeId: string;
+        pinned: boolean;
+        assignedAt: number;
+    }>>;
+    getAgentSettings(input: {
+        readonly agentNodeId: string;
+    }): Promise<AgentPipelineSettings | null>;
+    listAgentSettings(): Promise<readonly {
+        readonly nodeId: string;
+        readonly settings: AgentPipelineSettings;
+    }[]>;
+    setAgentAddonDefaults(input: {
+        readonly agentNodeId: string;
+        readonly defaults: Record<string, AgentAddonConfig>;
+    }): Promise<{
+        success: true;
+    }>;
+    removeAgentSettings(input: {
+        readonly agentNodeId: string;
+    }): Promise<{
+        success: boolean;
+        removed: boolean;
+    }>;
+    getCameraSettings(input: {
+        readonly deviceId: number;
+    }): Promise<CameraPipelineSettings | null>;
+    setCameraStepToggle(input: {
+        readonly deviceId: number;
+        readonly addonId: string;
+        readonly enabled: boolean | null;
+    }): Promise<{
+        success: true;
+    }>;
+    getCameraStepOverrides(input: {
+        readonly deviceId: number;
+    }): Promise<Record<string, Record<string, CameraStepOverridePatch>> | null>;
+    setCameraStepOverride(input: {
+        readonly deviceId: number;
+        readonly agentNodeId: string;
+        readonly addonId: string;
+        readonly patch: CameraStepOverridePatch | null;
+    }): Promise<{
+        success: true;
+    }>;
+    setCameraPipelineForAgent(input: {
+        readonly deviceId: number;
+        readonly agentNodeId: string;
+        readonly pipeline: {
+            steps: CameraPipelineConfig["steps"];
+            audio: {
+                modelId: string;
+                enabled: boolean;
+            } | null;
+        } | null;
+    }): Promise<{
+        success: true;
+    }>;
+    resolvePipeline(input: {
+        readonly deviceId: number;
+        readonly agentNodeId?: string;
+    }): Promise<CameraPipelineConfig>;
+    /** Emit `pipeline.camera-updated` carrying the freshly-resolved config. */
+    private emitResolvedCameraUpdated;
+    /** Re-dispatch every camera currently assigned to `nodeId` — used when agent defaults change. */
+    private redispatchCamerasOnAgent;
+    listTemplates(): Promise<readonly CameraPipelineTemplate[]>;
+    saveTemplate(input: {
+        readonly name: string;
+        readonly description?: string;
+        readonly config: CameraPipelineConfig;
+    }): Promise<CameraPipelineTemplate>;
+    updateTemplate(input: {
+        readonly id: string;
+        readonly name?: string;
+        readonly description?: string;
+        readonly config?: CameraPipelineConfig;
+    }): Promise<CameraPipelineTemplate>;
+    deleteTemplate(input: {
+        readonly id: string;
+    }): Promise<{
+        success: true;
+    }>;
+    /** Read the templates map from the addon store. */
+    private readTemplatesMap;
+    /** Emit the `pipeline.camera-updated` event so the internal subscriber hot-reloads the runner. */
+    private emitCameraUpdated;
+    /** Read the `agentSettings` map (keyed on `nodeId`) from the addon store. */
+    private readAgentSettingsMap;
+    /** Overwrite one agent's settings. Does NOT touch other agents' entries. */
+    private writeAgentSettings;
+    /** Read the `cameraSettings` map (keyed on `deviceId` as string) from the addon store. */
+    private readCameraSettingsMap;
+    /** Overwrite one camera's settings. */
+    private writeCameraSettings;
+    /**
+     * Fetch `pipelineExecutor.getSchema({nodeId})` through the standard cap
+     * router, cached per `(nodeId, engineKey)` with a short TTL. Returns
+     * `null` when the executor can't be reached (no runner yet attached)
+     * — callers fall back to an empty pipeline in that case.
+     */
+    private getCatalogForAgent;
+    /**
+     * Ensure `agentSettings[nodeId]` exists and is up-to-date with the
+     * current catalog. Triggered on orchestrator init (for the hub) and on
+     * every `$node.connected` for remote runners.
+     *
+     * Behaviour:
+     *   - Fetch catalog for the node.
+     *   - Call `seedAgentAddonDefaults(current.addonDefaults, engine, catalog)` — preserves
+     *     operator customisations, adds missing addons, drops orphans.
+     *   - Persist if anything changed.
+     *
+     * Idempotent: a second call with the same catalog is a no-op.
+     */
+    private seedAgentSettingsFromCatalog;
+    /**
+     * Fetch the engine triple (`runtime/backend/device`) from the
+     * `detection-pipeline` addon's global settings on the target node.
+     * This is the authoritative engine source since phase 2f. Returns
+     * `null` when the addon hasn't responded yet or doesn't expose the
+     * fields — callers fall back to `catalog.selectedEngine`.
+     */
+    private readDetectionPipelineEngine;
+    /** Sleep helper used inside readiness retry loops. */
+    private static sleep;
+    /**
+     * Resolve the pipeline for a device. NEVER returns an empty/fallback
+     * config: if the catalog or agent settings aren't available yet, this
+     * blocks (with backoff) until the detection-pipeline cap is registered
+     * and a non-null catalog comes back. Cameras must never be dispatched
+     * with `engine=node/cpu, steps=[]` because the runner then attaches
+     * the camera with no steps and silently never recovers.
+     *
+     * Two legitimate exceptions to "never empty":
+     *   1. The device's `detection-pipeline` binding is INACTIVE — the
+     *      operator explicitly turned inference off for this camera.
+     *   2. `cam.pipelineByAgent[agentNodeId]` carries a saved wholesale
+     *      override with empty steps — also operator intent.
+     *
+     * Everything else (boot ordering, catalog cold-start, transient cap
+     * registration delay) loops with backoff until the catalog responds.
+     */
+    private resolvePipelineForDevice;
+    /**
+     * Block until `pipeline-executor` is ready on `nodeId` AND
+     * `getCatalogForAgent` returns a non-null catalog AND `agentSettings`
+     * for that node has populated `addonDefaults`.
+     *
+     * `acquireCapability` defaults to infinite wait now — a single call
+     * carries the readiness gate. The thin retry below only handles
+     * the secondary case where the cap is "ready" but a derived call
+     * (getSchema) still returns null due to Moleculer service-registry
+     * propagation lag.
+     */
+    private waitForAgentAndCatalog;
+    /**
+     * Block until a real engine choice is available. `acquireCapability`
+     * defaults to infinite wait; the post-acquire loop only handles the
+     * propagation gap where the cap is `ready` but the derived calls
+     * still return null for a tick.
+     */
+    private waitForEngine;
+    /**
+     * Structural runtime check for `CameraPipelineConfig`. Persisted JSON
+     * may be stale or partial across upgrades, so we gate reads on shape
+     * rather than trusting the raw object. False = silently ignore that
+     * entry and fall back to defaults — the orchestrator's job is to
+     * never crash on corrupt store state.
+     */
+    private isCameraPipelineConfig;
+    private isPipelineTemplate;
+    /**
+     * Generate a short template id. Collision risk at N≤1000 templates is
+     * effectively zero (12 hex chars = 48 bits of entropy). Not a UUID
+     * because the persisted shape is a plain map keyed by id and shorter
+     * keys keep the JSON compact.
+     */
+    private generateTemplateId;
+    /** Build the addon-level schema (cluster-wide tunables: balancer + failover). */
+    protected globalSettingsSchema(): _camstack_types.ConfigUISchema;
+    /** Build the device-level schema (per-camera detection wiring). */
+    protected deviceSettingsSchema(): _camstack_types.ConfigUISchema;
+    updateGlobalSettings(patch: Record<string, unknown>): Promise<void>;
+    private writeDeviceOrchestratorSettings;
+    getDeviceSettingsContribution(input: {
+        deviceId: number;
+    }): Promise<ConfigUISchemaWithValues | null>;
+    getDeviceLiveContribution(input: {
+        deviceId: number;
+    }): Promise<ConfigUISchemaWithValues | null>;
+    /**
+     * Best-effort camera-type check used to gate the settings/live
+     * contributions on non-camera devices (Lights, Switches, Sensors,
+     * Buttons). Returns `true` on lookup failure so a transient
+     * device-manager hiccup never silently hides legitimate camera
+     * sections.
+     */
+    private isCameraDevice;
+    applyDeviceSettingsPatch(input: {
+        deviceId: number;
+        patch: Record<string, unknown>;
+    }): Promise<{
+        success: true;
+    }>;
+    /**
+     * Peel the pipeline-config keys out of an inbound patch. The remaining
+     * patch is forwarded to the existing device-level store writer. JSON
+     * textarea values are parsed here — `FormBuilder` serialises JSON
+     * editors as strings on submit, so the cap boundary has to reverse it
+     * before the content lands in the typed pipelines map.
+     */
+    private splitPipelinePatch;
+    /**
+     * Apply a `cameraPipeline` patch emitted by the `pipeline-editor`
+     * ConfigField. Routes the full `CameraPipelineConfig` into the
+     * 3-level `cameraSettings[deviceId].pipelineByAgent[agent]` store.
+     * The target agent is the camera's current assignment (or the local
+     * hub when unassigned). Emits `pipeline.camera-updated` so the
+     * internal subscriber hot-reloads the runner.
+     */
+    private applyPipelinePatch;
+    /** Tolerant JSON parser used to round-trip textarea-isJson fields. */
+    private tryParseJson;
+    /**
+     * Apply the subset of global settings that affect runtime behaviour
+     * (balancer thresholds, broker timeout, failover policy) into the
+     * in-memory state so subsequent `balance()` / `handleNodeDisconnect`
+     * calls use the new values immediately.
+     */
+    private applyRuntimeSettings;
+    private get api();
+    /**
+     * Resolve this addon's own per-device detection settings — combines the
+     * raw device store with the device schema defaults via `hydrateSchema()`,
+     * then narrows to a typed DTO. Replaces the old call to
+     * `this.ctx.settings!.getDevice` which used the deleted multi-level resolver
+     * (the new model has no overlap between addon-level and device-level
+     * keys, so there's no merge across levels — only schema defaults are
+     * applied to fill in keys missing from the device store).
+     */
+    /**
+     * True when `capName` is bound (`kind:'wrapped'`) for `deviceId` via
+     * `device-manager.getBindings`. Single source of truth for the
+     * "binding-gated cap" checks sprinkled around this addon (detection
+     * pipeline, audio analysis, …). Failures log-and-return `true` — the
+     * safe default is "cap on" unless the operator has explicitly toggled
+     * the wrapper off via `device-manager.setWrapperActive`.
+     */
+    private isCapActiveForDevice;
+    private isDetectionPipelineActive;
+    private isAudioAnalysisActive;
+    private isMotionDetectionActive;
+    /**
+     * Resolve the device's feature array. Used by the resolver to pick
+     * the right `DeviceProfile` when computing per-camera scheduling
+     * defaults. Reads via the `device-manager.getDevice` cap because the
+     * orchestrator may run on a different node from the live IDevice;
+     * the live registry isn't available cross-process.
+     */
+    private lookupDeviceFeatures;
+    /**
+     * True when the device has a native `motion` or `native-object-detection`
+     * cap registered by its driver — i.e. the camera does motion detection
+     * itself (Reolink Baichuan onboard PIR, ONVIF event-driven, etc.).
+     * Drives the dynamic `motionSources` default in
+     * `resolveDeviceDetectionSettings`: when the operator hasn't pinned a
+     * value, `['onboard']` is preferred over `['analyzer']` so we don't
+     * burn CPU running a redundant motion pipeline.
+     *
+     * Detection is via `device-manager.getBindings`: any binding entry of
+     * kind `'native'` whose capName is `motion` or
+     * `native-object-detection` qualifies. Failures default to `false` so
+     * we err toward the analyzer (never lose detection coverage when the
+     * binding lookup hiccups).
+     */
+    private deviceHasOnboardMotionCap;
+    private resolveDeviceDetectionSettings;
+    /**
+     * True when the device has registered a native `motion` or
+     * `native-object-detection` cap provider — i.e. the camera's driver
+     * addon does motion detection on the device itself. Drives the
+     * dynamic motionSource default in `resolveDeviceDetectionSettings`.
+     * Each lookup is isolated: a throw for one cap (legitimate "no
+     * provider registered" from the registry) must not mask the presence
+     * of the other cap.
+     */
+    /**
+     * Resolve the requested profile against the set of currently-assigned
+     * profile slots. Returns the profile id itself if the slot is live;
+     * otherwise walks the quality chain so a device missing the requested
+     * profile still gets a detection subscription on the closest assigned
+     * slot. Returns `null` only when nothing is assigned.
+     */
+    private resolveAssignedProfile;
+    /**
+     * Fetch the current profile-slot map for a device from the system
+     * stream-broker cap (`listAllProfileSlots`). Returns a map of
+     * `CamProfile → sourceCamStreamId` so callers can both check which
+     * profiles are live AND resolve a profile to the cam-stream-keyed
+     * brokerId (`${deviceId}/${camStreamId}`) used by the broker.
+     */
+    private fetchAssignedProfiles;
+    /**
+     * Build a `CameraDetectionConfig` from the resolved per-device
+     * orchestrator settings + the device's currently-assigned profile
+     * slots. Returns `null` when the device has no assigned slot or when
+     * settings cannot be resolved.
+     *
+     * `motionStreamId` / `detectionStreamId` hold a `camStreamId` value
+     * (e.g. `'native:main'`, `'rtsp:sub'`). The pipeline-runner
+     * concatenates `${deviceId}/${motionStreamId}` to build the broker
+     * id, matching the cam-stream-keyed brokers published by the
+     * stream-broker. The profile chosen by `motionStreamProfile` /
+     * `detectionStreamProfile` is resolved to the cam-stream backing it
+     * via the slot map fetched from `listAllProfileSlots`.
+     */
+    buildDetectionConfig(deviceId: number): Promise<CameraDetectionConfig | null>;
+    /**
+     * Start detection for a camera: dispatch to runner via the orchestrator
+     * local path and subscribe to the audio broker if audio is enabled.
+     */
+    startDetection(deviceId: number, config: CameraDetectionConfig): Promise<void>;
+    /** Stop detection for a camera: release via releaseCamera + audio cleanup. */
+    stopDetection(deviceId: number): Promise<void>;
+    /** Stop detection and purge all persisted config for a removed device. */
+    private handleDeviceUnregistered;
+    /**
+     * Handle a profile-slot change: build a fresh detection config from
+     * per-device settings and start detection if motion is enabled.
+     * Fires on `camera-streams.onProfileSlotsChanged` — any publish,
+     * retract, or assignment mutation in the stream-broker lands here.
+     */
+    private handleDeviceRegistered;
+    /**
+     * Field-by-field comparison of two `CameraDetectionConfig` records.
+     * `motionSources` is an unordered set; everything else is a primitive.
+     */
+    private static detectionConfigEquals;
+    /**
+     * Handle an orchestration settings update: rebuild the config and restart
+     * detection with the new values.
+     */
+    private handleSettingsChanged;
+    /**
+     * Hot-reload the runner currently hosting `deviceId` with a fresh
+     * pipeline config. Called from the `PipelineCameraUpdated` subscriber —
+     * any mutation to `pipelines[deviceId]` flows through this path so the
+     * operator's edit reaches the next frame without a rebalance or a full
+     * detection restart.
+     *
+     * No-ops (with a debug log) when the camera has no cached
+     * RunnerCameraConfig — means the camera either isn't registered yet or
+     * isn't assigned to a runner. The next DeviceStreamsRegistered cycle
+     * will read the fresh config from the store and dispatch normally.
+     */
+    private handlePipelineCameraUpdated;
+    /**
+     * Re-emit `PipelineInferenceResult` as `DetectionResult` when the
+     * frame carries detections. Kept deliberately thin: refinement
+     * (tracking, zone/state analysis, per-kind event persistence) is now
+     * owned end-to-end by `addon-pipeline-analytics`, which subscribes to
+     * `PipelineInferenceResult` directly. Consumers that want
+     * enriched-event-driven notifications subscribe to
+     * `pipeline-analytics.detection-event` + drive `notificationOutput`
+     * themselves.
+     */
+    /**
+     * Load management enforcement — called on every camera metrics snapshot.
+     *
+     * Time-based window: a camera must stay below `fpsMinThreshold` for
+     * at least `fpsLowWindowMs` (default 60s) before it is paused. The
+     * window resets the moment fps recovers above threshold, so a
+     * transient dip (GC, model swap, brief stall) doesn't accumulate
+     * across recoveries.
+     */
+    private static readonly DEFAULT_FPS_LOW_WINDOW_MS;
+    private enforceLoadManagement;
+    /** Base cooldown before first auto-resume attempt. */
+    private static readonly LOAD_SHED_BASE_COOLDOWN_MS;
+    /** Maximum backoff cap. */
+    private static readonly LOAD_SHED_MAX_COOLDOWN_MS;
+    /** How often the sweep runs. */
+    private static readonly LOAD_SHED_SWEEP_INTERVAL_MS;
+    private ensureLoadShedResumeTimer;
+    private loadShedResumeSweep;
+    /**
+     * Re-dispatch a single camera through the normal assignment pipeline.
+     * Used by auto-resume and settings-change recovery.
+     */
+    private redispatchSingleCamera;
+    private handleInferenceResult;
+    /**
+     * Lazy audio gate handler. Fires on every `MotionOnMotionChanged`
+     * event for a device whose `audioMode === 'on-motion'`.
+     *
+     * - `detected:true` → cancel any pending teardown, open audio sub
+     *   if not already open. Idempotent: re-fires of the same `true`
+     *   while subscribed are no-ops aside from cancelling the timer.
+     * - `detected:false` → schedule teardown after the device's
+     *   motion cooldown window. Mirrors the runner's own `'on-motion'`
+     *   detection-mode behaviour where the camera stays in `active`
+     *   for the cooldown window after the last motion ping.
+     *
+     * Idempotency is critical because `MotionOnMotionChanged` can fire
+     * frequently (every 1-2s while motion is active on Reolink); each
+     * rearm just keeps the audio stream open without restarting it.
+     */
+    private handleLazyAudioMotion;
+    /**
+     * Subscribe to decoded audio chunks for a camera and feed them into the
+     * audio-analyzer. Reads the analyzer's settings via its own
+     * `resolveDeviceSettings(deviceId)` method so the orchestrator does not
+     * touch the audio-analyzer schema field names directly.
+     */
+    private subscribeAudioStream;
+}
+
+export { type BalancerDecision, type BalancerInput, type DecoderBalancerDecision, type DecoderBalancerInput, type DispatchResult, type IPipelineOrchestratorLocalProvider, type OrchestratorDiagnostics, type PipelineOrchestratorActions, balance, balanceDecoder, computeCapacityScore, PipelineOrchestratorAddon as default, pipelineOrchestratorActions };