@camstack/types 1.2.41 → 1.2.43

package/dist/interfaces/camera-switches.d.ts

@@ -0,0 +1,375 @@
+/**
+ * Per-camera FUNCTION SWITCHES — the one coherent on/off surface over the
+ * pipeline functions an operator thinks in terms of.
+ *
+ * ## This file adds no state
+ *
+ * Every switch here is a VIEW onto an authority that already existed
+ * ([D62](../../../../docs/decisions/adr-0062.md)). The whole point of the
+ * group is that there is exactly one place each function is turned off, and
+ * the group routes to it:
+ *
+ * | Switch | Authority | Proven "off stops the work" gate |
+ * | --- | --- | --- |
+ * | `stream-broker` | `deviceManager.setDisabled` | `StreamBrokerManager.reconcileAllCatalogs` releases the brokers; `ensureBroker` refuses re-creation |
+ * | `object-detection` | `deviceManager.setWrapperActive('detection-pipeline')` | `PipelineSettingsStore.resolvePipelineForDevice` returns `{ steps: [], audio: null }` |
+ * | `audio-analysis` | `deviceManager.setWrapperActive('audio-analysis')` | `AudioSubscriptionController.subscribeAudioStream` returns `null` before opening the stream |
+ * | `recording` | `recording.setDeviceConfig` → `RecordingConfig.enabled` | `band-decision.shouldRecord` returns false; the controller detaches the device |
+ * | `notifications` | `notificationRules.setDeviceMuted` | `NotificationCenter.evaluateAndEnqueue` returns before any rule is evaluated |
+ * | `privacy-mask` | `privacyMask.setMask({ enabled })` → the CAMERA | the camera blanks the masked regions itself; every stream and recording carries the black boxes |
+ * | `device-audio` | `privacyMask.setAudioEnabled` → the CAMERA | the camera stops encoding an audio track at all; every consumer sees silent video |
+ *
+ * ## The two switches whose authority is not on this server
+ *
+ * `privacy-mask` and `device-audio` write the CAMERA. That is not a loophole
+ * in "the group stores nothing" — it is the purest form of it: the camera
+ * holds the fact, every read is a read-through, and there is no server-side
+ * copy that could drift. Their availability therefore cannot come from
+ * `listBindableCapsForDeviceType` (a device-NATIVE cap carries no wrappers and
+ * is filtered out there); it comes from the cap's own camera-probed
+ * `privacyMask.getOptions()`, which is strictly more honest — it answers for
+ * THIS camera rather than for the device type
+ * ([D74](../../../../docs/decisions/adr-0074.md)).
+ *
+ * ## `privacy-mask` is the one row whose ON is not "the function is working"
+ *
+ * Every other switch means *this camera's function is doing its job*, so
+ * `enabled: false` is a thing an operator took away. `privacy-mask` means **the
+ * MASK is active** — `enabled: true` is video deliberately obscured. The
+ * polarity is not a choice made here: `addon-export-hap`'s privacy `Switch`
+ * (`builders/privacy-switch.ts`) already mirrors `patch.enabled` verbatim, and
+ * a HomeKit toggle that disagreed with the app's toggle for the same camera is
+ * worse than either surface not having one.
+ *
+ * Two consequences follow and both are load-bearing:
+ *
+ * - **It never counts as `switchedOff`.** `countsAsSwitchedOff` is `false` for
+ *   exactly this row. With the polarity above, every camera that has NOT drawn
+ *   a privacy mask would otherwise report `switchedOff: ['privacy-mask']` — the
+ *   normal, healthy state of most cameras rendered as an operator disablement.
+ * - **Its cost line names BOTH directions.** `costWhenOff` is rendered
+ *   unconditionally by both clients, so for this row it has to read correctly
+ *   whichever way the switch is sitting.
+ *
+ * The wrapper-binding pair is not a new idea: `legacy-migrations.ts` already
+ * migrated the legacy `audioEnabled` / `pipelineEnabled` /
+ * `motionDetectionEnabled` booleans ONTO `setWrapperActive`. The group is the
+ * surface that decision never got.
+ *
+ * ## Two rules that are load-bearing
+ *
+ * - **Recording's switch is `enabled`, never the bands.** `bands` is the only
+ *   authored intent and `mode` is derived from it (`deriveRecordingMode`).
+ *   Expressing "off" by clearing bands destroys the operator's schedule and
+ *   turning the camera back on would then silently record nothing.
+ * - **A switch that is off must be reported as off**, not merely produce
+ *   nothing. {@link CameraSwitch.enabled} is what a status surface renders as
+ *   "disabled by an operator" instead of "broken" — see
+ *   `CameraStatus.switchedOff`.
+ */
+import { z } from 'zod';
+/**
+ * The functions the operator named — five on 2026-08-05, plus the camera's own
+ * microphone on 2026-08-07. Deliberately NOT one id per pipeline step: face
+ * recognition and plate/LPR are per-step toggles on
+ * `pipelineOrchestrator.setCameraStepToggle` and belong in the pipeline
+ * editor, not in a safety group.
+ */
+export declare const CameraSwitchIdSchema: z.ZodEnum<{
+    "privacy-mask": "privacy-mask";
+    "audio-analysis": "audio-analysis";
+    recording: "recording";
+    "stream-broker": "stream-broker";
+    notifications: "notifications";
+    "object-detection": "object-detection";
+    "device-audio": "device-audio";
+}>;
+export type CameraSwitchId = z.infer<typeof CameraSwitchIdSchema>;
+/**
+ * Stable render order — broadest blast radius first, and a source before the
+ * thing that consumes it. `device-audio` sits ABOVE `audio-analysis` because
+ * turning the microphone off leaves the analyzer with nothing to analyse; the
+ * reverse is not true.
+ *
+ * `privacy-mask` sits directly ABOVE `device-audio` because they are literal
+ * siblings — one cap, one device plane, video then audio — and NOT above
+ * `object-detection` despite feeding it: a mask blanks REGIONS, so its blast
+ * radius is partial, and the "broadest first" rule does not rank a partial
+ * control above a whole-function one.
+ */
+export declare const CAMERA_SWITCH_ORDER: readonly CameraSwitchId[];
+/**
+ * WHERE the switch's state actually lives. A discriminated union rather than a
+ * string so both the writer (the orchestrator's `setCameraSwitch`) and any
+ * reader can exhaustively narrow — and so "the group added a parallel map" is
+ * a compile error rather than a review comment.
+ */
+export declare const CameraSwitchAuthoritySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"device-disabled">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"wrapper-binding">;
+    capName: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"recording-config">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"notification-mute">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"camera-audio">;
+    capName: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"camera-mask">;
+    capName: z.ZodString;
+}, z.core.$strip>], "kind">;
+export type CameraSwitchAuthority = z.infer<typeof CameraSwitchAuthoritySchema>;
+/**
+ * Why a switch is not offered for this camera. Rendered instead of the
+ * control, never as a dead control — an absent function and a broken one must
+ * not look the same.
+ */
+export declare const CameraSwitchUnavailableReasonSchema: z.ZodEnum<{
+    "no-provider": "no-provider";
+    "source-unreachable": "source-unreachable";
+    "not-configured": "not-configured";
+}>;
+export type CameraSwitchUnavailableReason = z.infer<typeof CameraSwitchUnavailableReasonSchema>;
+/**
+ * One switch, resolved for one camera.
+ *
+ * `label` and `costWhenOff` travel ON THE WIRE rather than being looked up
+ * client-side: the viewer is a separate repository that does not import
+ * `@camstack/types`, and a cost line duplicated in two clients is a cost line
+ * that will disagree with itself. Five rows per camera is nothing.
+ */
+export declare const CameraSwitchSchema: z.ZodObject<{
+    id: z.ZodEnum<{
+        "privacy-mask": "privacy-mask";
+        "audio-analysis": "audio-analysis";
+        recording: "recording";
+        "stream-broker": "stream-broker";
+        notifications: "notifications";
+        "object-detection": "object-detection";
+        "device-audio": "device-audio";
+    }>;
+    label: z.ZodString;
+    costWhenOff: z.ZodString;
+    available: z.ZodBoolean;
+    unavailableReason: z.ZodOptional<z.ZodEnum<{
+        "no-provider": "no-provider";
+        "source-unreachable": "source-unreachable";
+        "not-configured": "not-configured";
+    }>>;
+    enabled: z.ZodBoolean;
+    authority: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"device-disabled">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"wrapper-binding">;
+        capName: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"recording-config">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"notification-mute">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"camera-audio">;
+        capName: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"camera-mask">;
+        capName: z.ZodString;
+    }, z.core.$strip>], "kind">;
+}, z.core.$strip>;
+export type CameraSwitch = z.infer<typeof CameraSwitchSchema>;
+/** The whole group for one camera. */
+export declare const CameraSwitchGroupSchema: z.ZodObject<{
+    deviceId: z.ZodNumber;
+    switches: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        id: z.ZodEnum<{
+            "privacy-mask": "privacy-mask";
+            "audio-analysis": "audio-analysis";
+            recording: "recording";
+            "stream-broker": "stream-broker";
+            notifications: "notifications";
+            "object-detection": "object-detection";
+            "device-audio": "device-audio";
+        }>;
+        label: z.ZodString;
+        costWhenOff: z.ZodString;
+        available: z.ZodBoolean;
+        unavailableReason: z.ZodOptional<z.ZodEnum<{
+            "no-provider": "no-provider";
+            "source-unreachable": "source-unreachable";
+            "not-configured": "not-configured";
+        }>>;
+        enabled: z.ZodBoolean;
+        authority: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"device-disabled">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"wrapper-binding">;
+            capName: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"recording-config">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"notification-mute">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"camera-audio">;
+            capName: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"camera-mask">;
+            capName: z.ZodString;
+        }, z.core.$strip>], "kind">;
+    }, z.core.$strip>>>;
+    fetchedAt: z.ZodNumber;
+}, z.core.$strip>;
+export type CameraSwitchGroup = z.infer<typeof CameraSwitchGroupSchema>;
+/**
+ * The wrapper capability each wrapper-backed switch controls. Named constants
+ * because the same strings appear in `legacy-migrations.ts`, in
+ * `isCapActiveForDevice` call sites and in the fake harness — a typo in any of
+ * them is a switch that silently writes a binding nobody reads.
+ */
+export declare const DETECTION_PIPELINE_CAP_NAME = "detection-pipeline";
+export declare const AUDIO_ANALYSIS_CAP_NAME = "audio-analysis";
+/**
+ * The device-NATIVE cap that owns what the camera does not capture — masked
+ * video regions and, since 2026-08-07, the microphone. Named here because the
+ * `camera-audio` authority, the orchestrator's gather and the fake harness all
+ * have to agree on it.
+ */
+export declare const PRIVACY_MASK_CAP_NAME = "privacy-mask";
+/** Static half of a switch: everything that does not depend on a device. */
+export interface CameraSwitchDescriptor {
+    readonly id: CameraSwitchId;
+    readonly label: string;
+    readonly costWhenOff: string;
+    readonly authority: CameraSwitchAuthority;
+    /**
+     * May `enabled: false` on this row appear in {@link switchedOffIds}?
+     *
+     * `true` for every switch that means "this camera's function is doing its
+     * job", where OFF is something a person took away and a status surface must
+     * render as disabled rather than broken.
+     *
+     * `false` for `privacy-mask` alone, and only because its polarity is
+     * inverted: OFF there means the mask is not obscuring anything, which is the
+     * ordinary state of nearly every camera. Reporting it would put a
+     * `switchedOff` badge on healthy cameras and drown the badge that matters.
+     */
+    readonly countsAsSwitchedOff: boolean;
+}
+/**
+ * THE catalog. One entry per switch; the cost lines are the operator-facing
+ * contract and are written to be true rather than reassuring.
+ */
+export declare const CAMERA_SWITCH_CATALOG: Readonly<Record<CameraSwitchId, CameraSwitchDescriptor>>;
+/**
+ * Everything the pure derivation needs, gathered by the caller. A `null`
+ * sub-state means the owning source did not answer — which produces
+ * `available: false` with `source-unreachable`, NEVER a control defaulted to
+ * "on". Guessing a switch is on when we could not read it is how an operator
+ * learns a function is off a week later.
+ */
+export interface CameraSwitchDerivationInput {
+    readonly deviceId: number;
+    /** `deviceManager` soft-disable flag for this device. */
+    readonly deviceDisabled: boolean;
+    /**
+     * Capability names bindable for this device's TYPE
+     * (`deviceManager.listBindableCapsForDeviceType`). This is what makes the
+     * group derived rather than hardcoded: a deployment with no audio analyzer
+     * has no `audio-analysis` here, so no audio switch is rendered.
+     * `null` = the lookup failed.
+     */
+    readonly bindableCapNames: readonly string[] | null;
+    /**
+     * Capability names currently bound `kind: 'wrapped'` for this device
+     * (`deviceManager.getBindings`). Absence IS how a deactivated wrapper is
+     * represented — there is no `active: false` row.
+     */
+    readonly activeWrapperCapNames: readonly string[] | null;
+    /** `RecordingConfig.enabled`; `null` when the recording cap did not answer. */
+    readonly recordingEnabled: boolean | null;
+    /** `notificationRules` per-camera mute; `null` when the cap did not answer. */
+    readonly notificationsMuted: boolean | null;
+    /**
+     * The camera's own microphone, read through the `privacy-mask` native cap.
+     * `null` = the cap is bound to this camera but did not answer.
+     *
+     * A camera with no `privacy-mask` provider at all is `{ supported: false }`,
+     * not `null` — "this camera has no such control" and "we could not read it"
+     * are different answers and the operator is shown different copy for each.
+     */
+    readonly deviceAudio: DeviceAudioSwitchState | null;
+    /**
+     * The camera's own VIDEO privacy mask, read through the same `privacy-mask`
+     * native cap and the same pair of round trips as {@link deviceAudio} — one
+     * `getOptions` + one `getStatus` answer both, so the second switch is free.
+     *
+     * `null` = the cap is bound to this camera but did not answer.
+     */
+    readonly privacyMask: PrivacyMaskSwitchState | null;
+}
+/** What the camera-probed audio switch reported for one camera. */
+export interface DeviceAudioSwitchState {
+    /**
+     * `privacyMask.getOptions().supportsAudioMute` — camera-probed, never a
+     * device-type guess. A camera that does not expose the control renders no
+     * switch rather than a toggle that silently does nothing.
+     */
+    readonly supported: boolean;
+    /**
+     * `privacyMask.getStatus().audioEnabled` — the camera's current answer.
+     * `null` when unsupported, or when supported but unreadable; the second
+     * case yields `source-unreachable`, never a control defaulted to "on".
+     */
+    readonly enabled: boolean | null;
+}
+/** What the camera-probed VIDEO privacy mask reported for one camera. */
+export interface PrivacyMaskSwitchState {
+    /**
+     * Can this camera store privacy zones at all? Derived from the probed
+     * `getOptions()`: `maxRegions > 0` AND at least one supported shape kind.
+     * Reolink answers `maxNum: 0` / `supportedShapes: []` honestly on models
+     * that cannot, and that must render no control rather than a toggle whose
+     * write the camera discards.
+     */
+    readonly supported: boolean;
+    /**
+     * How many zones are actually drawn on the camera right now
+     * (`getStatus().regions.length`). `null` = supported, but the status could
+     * not be read.
+     *
+     * **Zero is not "off", it is "nothing to switch".** Toggling the master
+     * enable with no zones changes not one pixel — the dead control D62 exists
+     * to remove — so it resolves to `not-configured`, which tells the operator
+     * to go and draw one instead of leaving them pressing a button.
+     */
+    readonly configuredRegions: number | null;
+    /**
+     * `getStatus().enabled` — the camera's master mask flag, `true` when the
+     * zones are being blanked. `null` when unreadable; never defaulted.
+     */
+    readonly enabled: boolean | null;
+}
+/**
+ * Pure derivation of the whole group. No I/O — the orchestrator gathers, this
+ * decides, so the decision is testable without a hub.
+ *
+ * Order is {@link CAMERA_SWITCH_ORDER}; unavailable switches are RETURNED
+ * rather than filtered out, so a client can explain the gap instead of
+ * silently rendering four buttons where another camera shows five.
+ */
+export declare function deriveCameraSwitches(input: CameraSwitchDerivationInput): readonly CameraSwitch[];
+/**
+ * The ids an operator has switched OFF, for a status surface.
+ *
+ * This is the answer to "a disabled function must be visible as DISABLED, not
+ * merely quiet": a camera reporting zero detections with
+ * `switchedOff: ['object-detection']` was turned off; the same camera with an
+ * empty list is broken. Unavailable switches never appear — a function nobody
+ * provides was not switched off by anyone.
+ *
+ * `privacy-mask` never appears either, whichever way it is sitting, because its
+ * ON means "the mask is active" rather than "the function works"
+ * ({@link CameraSwitchDescriptor.countsAsSwitchedOff}). Without that filter the
+ * ordinary state of every camera nobody has masked would carry a
+ * "switched off" badge, and the badge that matters would be lost in it.
+ */
+export declare function switchedOffIds(switches: readonly CameraSwitch[]): readonly CameraSwitchId[];

package/dist/interfaces/inference-engine.d.ts

@@ -16,16 +16,36 @@ import type { RawFrameFormat } from '../types/io.js';
  * raw buffer to JPEG internally rather than throwing — `infer()` must
  * always succeed for either kind.
  */
-export type InferenceInput = {
+/**
+ * Fields every `InferenceInput` variant carries regardless of pixel transport.
+ */
+interface InferenceInputCommon {
+    /**
+     * The camera this frame belongs to — **diagnostic only**. It changes no
+     * dispatch decision, no deadline and no shed rule; it exists so an inference
+     * failure inside a SHARED pool can name the camera that paid for it.
+     *
+     * A `SharedInferencePool` serves every camera on its
+     * `(node, runtime, device)`, so its `inference request timed out` and
+     * `worker saturated` lines could describe the pool and nothing else — and
+     * "why is 617 worse than 615?" is the question those lines always get asked.
+     *
+     * Omitted by callers with no camera (commands, model loads, the benchmark);
+     * the failure line then carries no `deviceId` tag rather than a fabricated
+     * one.
+     */
+    readonly deviceId?: number;
+}
+export type InferenceInput = ({
     readonly kind: 'jpeg';
     readonly data: Buffer;
-} | {
+} & InferenceInputCommon) | ({
     readonly kind: 'raw';
     readonly data: Buffer;
     readonly width: number;
     readonly height: number;
     readonly format: RawFrameFormat;
-};
+} & InferenceInputCommon);
 export interface IInferenceEngine {
     readonly runtime: DetectionRuntime;
     readonly device: DetectionDevice;
@@ -34,3 +54,4 @@ export interface IInferenceEngine {
     run?(input: Float32Array, inputShape: readonly number[]): Promise<Float32Array>;
     dispose(): Promise<void>;
 }
+export {};

package/dist/interfaces/ops-log.d.ts

@@ -23,6 +23,7 @@ export declare const OpsLogOpSchema: z.ZodEnum<{
     rescan: "rescan";
     "retention-run": "retention-run";
     relocate: "relocate";
+    "orphan-audit": "orphan-audit";
 }>;
 export type OpsLogOp = z.infer<typeof OpsLogOpSchema>;
 /** Why the operation ran. */
@@ -31,6 +32,7 @@ export declare const OpsLogReasonSchema: z.ZodEnum<{
     operator: "operator";
     retention: "retention";
     quota: "quota";
+    maintenance: "maintenance";
 }>;
 export type OpsLogReason = z.infer<typeof OpsLogReasonSchema>;
 /** One audit row, shared verbatim by both domains. */
@@ -47,12 +49,14 @@ export declare const OpsLogEntrySchema: z.ZodObject<{
         rescan: "rescan";
         "retention-run": "retention-run";
         relocate: "relocate";
+        "orphan-audit": "orphan-audit";
     }>;
     reason: z.ZodEnum<{
         manual: "manual";
         operator: "operator";
         retention: "retention";
         quota: "quota";
+        maintenance: "maintenance";
     }>;
     deviceId: z.ZodNullable<z.ZodNumber>;
     nodeId: z.ZodString;

package/dist/interfaces/pipeline-runner-capability.d.ts

@@ -1,7 +1,7 @@
-import type { OrchestratorMetrics, CameraMetrics } from './api-shared.js';
 import type { PipelineStepInputOutput } from '../capabilities/pipeline-executor.cap.js';
 import type { Zone } from '../capabilities/zones.cap.js';
 import type { PipelinePhaseMode } from '../device/device-profile.js';
+import type { CameraMetrics, OrchestratorMetrics } from './api-shared.js';
 /**
  * Camera assignment payload sent by the pipeline-orchestrator to a runner
  * via `attachCamera`. Carries everything the runner needs to subscribe to
@@ -204,4 +204,12 @@ export interface IPipelineRunnerProvider {
      * `null` when neither `frameHandle` nor `cropJpeg` resolves to a crop.
      */
     runDetailSubtree(input: import('../capabilities/pipeline-runner.cap.js').RunDetailSubtreeInput): Promise<import('../capabilities/pipeline-runner.cap.js').RunDetailSubtreeResult | null>;
+    /**
+     * Run ONE enrichment step against caller-supplied pixels with NO camera
+     * session — no attach, no handle, no device affinity. See
+     * `pipelineRunnerCapability.runStatelessStep`
+     * (`capabilities/pipeline-runner.cap.ts`) for the full contract, including
+     * why the model pin is refused rather than substituted.
+     */
+    runStatelessStep(input: import('../capabilities/pipeline-runner.cap.js').RunStatelessStepInput): Promise<import('../capabilities/pipeline-runner.cap.js').RunStatelessStepResult>;
 }

package/dist/node.d.ts

@@ -6,3 +6,5 @@ export { FilesystemStorageProvider } from './storage/filesystem-storage-provider
 export { canonicalHash } from './utils/canonical-hash.js';
 export { canonicalDeviceFingerprint, diffExportTargets, resolveExportFingerprint, } from './utils/export-reconciler.js';
 export type { DeviceExportShape, ExportDelta, ExportTargetEntry, } from './utils/export-reconciler.js';
+export { FfmpegProcess } from './ffmpeg/process.js';
+export type { FfmpegProcessOptions, FfmpegExit, FfmpegExitClass } from './ffmpeg/process.js';