@camstack/types 1.2.93 → 1.2.95

package/dist/capabilities/index.d.ts

@@ -79,8 +79,8 @@ export { type IOauthIntegrationProvider, type OauthIntegrationDescriptor, OauthI
 export { type AudioEvent, AudioEventSchema, type DetectionSource, DetectionSourceSchema, type EventKind, type EventKindCategory, EventKindCategorySchema, type EventKindDescriptor, EventKindDescriptorSchema, type EventKindIcon, EventKindIconSchema, EventKindSchema, type EventKindsForDevice, EventKindsForDeviceSchema, type EventPruneCounts, type EventStoreDeviceFootprint, type EventStoreFootprint, type IPipelineAnalyticsProvider, type KeyEvent, KeyEventSchema, type LabelAttribution, LabelAttributionSchema, type LabelTier, LabelTierSchema, type MediaFile, type MediaFileInfo, MediaFileInfoSchema, type MediaFileKind, MediaFileSchema, type MotionEvent, MotionEventSchema, type ObjectEvent, ObjectEventSchema, pipelineAnalyticsCapability, type RecentTracksPage, RecentTracksPageSchema, type RecentTracksQuery, RecentTracksQueryInput, type RetrainAnnotation, type RetrainAnnotationDraft, RetrainAnnotationDraftSchema, RetrainAnnotationKindSchema, RetrainAnnotationSchema, RetrainAnnotationSourceSchema, type RetrainAssistResult, RetrainAssistResultSchema, RetrainAssistSubjectSchema, RetrainCopyRefusalSchema, type RetrainFrame, type RetrainFrameCandidate, RetrainFrameCandidateSchema, type RetrainFrameList, RetrainFrameListSchema, RetrainFrameSchema, type RetrainFrameSelection, RetrainFrameSelectionSchema, type RetrainMacroClass, RetrainMacroClassSchema, type RetrainStatus, RetrainStatusSchema, type RetrainTrack, RetrainTrackSchema, type RetrainTransitionResult, RetrainTransitionResultSchema, type ScoredObjectEvent, ScoredObjectEventSchema, type SensorEvent, SensorEventSchema, type Track, type TrackCascadeCounts, TrackCascadeCountsSchema, type TrackEnvelope, TrackEnvelopeSchema, TrackedDetectionSchema, type TrackFlags, type TrackFlagsPatch, TrackFlagsPatchSchema, TrackFlagsSchema, type TrackProjection, TrackProjectionSchema, TrackSchema, type TrackSource, TrackSourceSchema, type TrackState, TrackStateSchema, type TrackZoneFilter, TrackZoneFilterSchema, type TrainingExportDeviceTotals, TrainingExportDeviceTotalsSchema, type TrainingExportSummary, TrainingExportSummarySchema, type ZoneCrossing, type ZoneCrossingDirection, ZoneCrossingDirectionSchema, ZoneCrossingSchema, } from './pipeline-analytics.cap.js';
 export type { NativeCropRef, PipelineStepInputOutput, PipelineValidationIssue, PipelineValidationResult, } from './pipeline-executor.cap.js';
 export { ModelSubstitutionSchema, NativeCropRefSchema, PipelineDefaultStepSchema, PipelineEngineChoiceSchema, PipelineRunResultBridge, PipelineStepInputSchema, PipelineValidationIssueSchema, PipelineValidationResultSchema, pipelineExecutorCapability, } from './pipeline-executor.cap.js';
-export type { CameraAssignmentStatus, CameraAudioStatus, CameraBrokerProfile, CameraBrokerStatus, CameraDecoderShm, CameraDecoderStatus, CameraDetectionPhase, CameraDetectionProvisioning, CameraDetectionProvisioningState, CameraDetectionStatus, CameraMotionStatus, CameraRecordingMode, CameraRecordingStatus, CameraSourceStatus, CameraSourceStream, CameraStatus, CameraStatusDegradation, CameraStatusDegradationReason, CameraStatusStage, DiskReconcileJob, IngestOwner, NodeInferenceDevice, NodeInferenceDevices, } from './pipeline-orchestrator.cap.js';
-export { AgentLoadSummarySchema, CameraAssignmentStatusSchema, CameraAudioStatusSchema, CameraBrokerProfileSchema, CameraBrokerStatusSchema, CameraDecoderShmSchema, CameraDecoderStatusSchema, CameraDetectionPhaseSchema, CameraDetectionProvisioningSchema, CameraDetectionProvisioningStateSchema, CameraDetectionStatusSchema, CameraMotionStatusSchema, CameraRecordingModeSchema, CameraRecordingStatusSchema, CameraSourceStatusSchema, CameraSourceStreamSchema, CameraStatusDegradationReasonSchema, CameraStatusDegradationSchema, CameraStatusSchema, CameraStatusStageSchema, CapabilityBindingsSchema, DiskReconcileJobSchema, GlobalMetricsSchema, IngestOwnerSchema, PipelineAssignmentSchema, pipelineOrchestratorCapability, } from './pipeline-orchestrator.cap.js';
+export type { CameraAssignmentStatus, CameraAudioStatus, CameraBrokerProfile, CameraBrokerStatus, CameraDecoderShm, CameraDecoderStatus, CameraDetectionPhase, CameraDetectionProvisioning, CameraDetectionProvisioningState, CameraDetectionStatus, CameraMotionStatus, CameraRecordingMode, CameraRecordingStatus, CameraSourceStatus, CameraSourceStream, CameraStatus, CameraStatusDegradation, CameraStatusDegradationReason, CameraStatusStage, DiskReconcileJob, InferenceDeviceExclusionReason, IngestOwner, NodeInferenceDevice, NodeInferenceDevices, } from './pipeline-orchestrator.cap.js';
+export { AgentLoadSummarySchema, CameraAssignmentStatusSchema, CameraAudioStatusSchema, CameraBrokerProfileSchema, CameraBrokerStatusSchema, CameraDecoderShmSchema, CameraDecoderStatusSchema, CameraDetectionPhaseSchema, CameraDetectionProvisioningSchema, CameraDetectionProvisioningStateSchema, CameraDetectionStatusSchema, CameraMotionStatusSchema, CameraRecordingModeSchema, CameraRecordingStatusSchema, CameraSourceStatusSchema, CameraSourceStreamSchema, CameraStatusDegradationReasonSchema, CameraStatusDegradationSchema, CameraStatusSchema, CameraStatusStageSchema, CapabilityBindingsSchema, DiskReconcileJobSchema, GlobalMetricsSchema, INFERENCE_DEVICE_EXCLUSION_REASONS, InferenceDeviceExclusionReasonSchema, IngestOwnerSchema, PipelineAssignmentSchema, pipelineOrchestratorCapability, } from './pipeline-orchestrator.cap.js';
 export type { DetailParent, DetailResult, MotionSource, MotionSources, ReportMotionInput, RunDetailSubtreeInput, RunDetailSubtreeResult, RunnerFrameSource, RunnerInferenceDevice, RunStatelessStepInput, RunStatelessStepResult, StatelessStepRefusal, } from './pipeline-runner.cap.js';
 export { MotionSourceEnum, MotionSourcesSchema, type NativeCropBbox, NativeCropBboxSchema, NativeCropResultSchema, pipelineRunnerCapability, ReportMotionInputSchema, RunnerCameraConfigSchema, RunnerCameraDeviceUIFields, RunnerFrameSourceSchema, RunnerInferenceDeviceSchema, RunnerLocalLoadSchema, RunnerLocalMetricsSchema, } from './pipeline-runner.cap.js';
 export { AudioChunkInputSchema, AudioClassificationLabelSchema, AudioLevelSchema, BoundingBoxSchema, FrameInputSchema, SpatialDetectionSchema, } from './schemas/detection-shared.js';
@@ -154,7 +154,7 @@ export { type BacklightMode, BacklightModeSchema, type ExposureMode, ExposureMod
 export { AvailableIntegrationTypeSchema, CreateIntegrationInputSchema, DeleteIntegrationResultSchema, type IIntegrationsProvider, IntegrationLiteSchema, type IntegrationTestConnectionResult, type IntegrationTestConnectionStatus, IntegrationWithStateSchema, integrationsCapability, TestConnectionResultSchema, TestConnectionStatusEnum, UpdateIntegrationInputSchema, } from './integrations.cap.js';
 export { type IIntercomProvider, type IntercomAbility, IntercomAbilitySchema, type IntercomStatus, IntercomStatusSchema, intercomCapability, } from './intercom.cap.js';
 export { type DeviceCodeSeverity, DeviceCodeSeveritySchema, type ILawnMowerControlProvider, type LawnMowerActivity, LawnMowerActivitySchema, type LawnMowerControlStatus, LawnMowerControlStatusSchema, lawnMowerControlCapability, } from './lawn-mower-control.cap.js';
-export { type ConnectionEndpoint, type ILocalNetworkProvider, type LocalInterface, localNetworkCapability, } from './local-network.cap.js';
+export { type AdvertisedLocalPort, type ConnectionEndpoint, type ILocalNetworkProvider, type LocalInterface, localNetworkCapability, } from './local-network.cap.js';
 export { type ILockControlProvider, type LockControlStatus, LockControlStatusSchema, type LockState, LockStateSchema, lockControlCapability, } from './lock-control.cap.js';
 export { type MaskGridDims, MaskGridDimsSchema, type MaskGridShape, MaskGridShapeSchema, type MaskLineShape, MaskLineShapeSchema, type MaskPoint, MaskPointSchema, type MaskPolygonShape, MaskPolygonShapeSchema, type MaskPolygonVertices, MaskPolygonVerticesSchema, type MaskRectShape, MaskRectShapeSchema, type MaskShape, type MaskShapeKind, MaskShapeKindSchema, MaskShapeSchema, } from './mask-shape.js';
 export { type IMediaPlayerProvider, type MediaInfo, type MediaPlayerRepeat, MediaPlayerRepeatSchema, type MediaPlayerState, MediaPlayerStateSchema, type MediaPlayerStatus, MediaPlayerStatusSchema, mediaPlayerCapability, } from './media-player.cap.js';

package/dist/capabilities/local-network.cap.d.ts

@@ -74,6 +74,17 @@ declare const ConnectionEndpointSchema: z.ZodObject<{
     plausibleReason: z.ZodString;
     priority: z.ZodNumber;
 }, z.core.$strip>;
+/** The port every LAN/loopback `baseUrl` in the same result was built with. */
+declare const AdvertisedLocalPortSchema: z.ZodObject<{
+    port: z.ZodNumber;
+    source: z.ZodEnum<{
+        default: "default";
+        "server-config": "server-config";
+        "server-env": "server-env";
+        "caller-hint": "caller-hint";
+    }>;
+}, z.core.$strip>;
+export type AdvertisedLocalPort = z.infer<typeof AdvertisedLocalPortSchema>;
 /**
  * The chosen outbound endpoint for notification artifacts. `baseUrl: null` =
  * AUTO (resolved from the candidate ranking at send time); `resolved` reports
@@ -157,9 +168,29 @@ export declare const localNetworkCapability: {
          * Honours `getAllowedAddresses()` when set — addresses outside
          * the allowlist are dropped (the public tunnel + loopback are
          * always included as escape hatches).
+         *
+         * **The port is the hub's, not the caller's** (D62 — a function's fact
+         * belongs to whoever already owns it). This method used to take a `port`
+         * and echo it onto every LAN and loopback URL it advertised, which made
+         * every client a second authority on a socket only the hub binds. A viewer
+         * configured with a port-less public URL (`https://camstack.example.top`)
+         * infers 443 from the scheme, asks with 443, and was handed
+         * `https://192.168.1.9:443` for a hub listening on 4443. That candidate
+         * cannot ever answer, and losing its race reads in the log exactly like
+         * "the LAN was tried and it was slower" — so an operator sitting on his own
+         * WiFi stayed on the public tunnel for weeks, with the LAN candidate born
+         * dead on every single connect.
+         *
+         * The hub now resolves its own listen port and reports it as `localPort`,
+         * with the SOURCE of the number, so a client can tell a fact from an echo.
+         *
+         * Out of scope on purpose: a LAN URL that is not the hub's own socket (a
+         * reverse proxy in front of it on another port) is not this method's to
+         * invent either — pin it with `setNotificationEndpoint` / a configured
+         * origin, which is an operator statement rather than a guess.
          */
         readonly getConnectionEndpoints: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
-            port: z.ZodNumber;
+            port: z.ZodOptional<z.ZodNumber>;
             includeLoopback: z.ZodOptional<z.ZodBoolean>;
             ipv4Only: z.ZodOptional<z.ZodBoolean>;
             scheme: z.ZodOptional<z.ZodEnum<{
@@ -189,6 +220,15 @@ export declare const localNetworkCapability: {
                 plausibleReason: z.ZodString;
                 priority: z.ZodNumber;
             }, z.core.$strip>>>;
+            localPort: z.ZodObject<{
+                port: z.ZodNumber;
+                source: z.ZodEnum<{
+                    default: "default";
+                    "server-config": "server-config";
+                    "server-env": "server-env";
+                    "caller-hint": "caller-hint";
+                }>;
+            }, z.core.$strip>;
         }, z.core.$strip>, import("./capability-definition.js").CapabilityMethodKind>;
         /**
          * The endpoint OUTBOUND artifacts must be addressed by — notification

package/dist/capabilities/pipeline-analytics.cap.d.ts

@@ -202,7 +202,7 @@ export type TrackEnvelope = z.infer<typeof TrackEnvelopeSchema>;
  * `snapshots[]` references — megabytes across a page of tracks. `slim`
  * keeps every scalar the list surfaces actually render (ids, class(es),
  * label / audioLabels / importance enrichment, firstSeen/lastSeen, state,
- * zonesVisited, bestEventId, envelope, hasFace, hasRider) and returns `positions` /
+ * zonesVisited, bestEventId, envelope, hasFace, hasEmbeddedFace, hasRider) and returns `positions` /
  * `snapshots` as EMPTY arrays — detail views re-fetch the full row via
  * `getTrack`. Mirrors the event-store `projection` convention
  * (`getObjectEvents` et al.).
@@ -435,6 +435,7 @@ declare const TrackSchema: z.ZodObject<{
         maxY: z.ZodNumber;
     }, z.core.$strip>>;
     hasFace: z.ZodOptional<z.ZodBoolean>;
+    hasEmbeddedFace: z.ZodOptional<z.ZodBoolean>;
     hasRider: z.ZodOptional<z.ZodBoolean>;
     label: z.ZodOptional<z.ZodString>;
     labelScore: z.ZodOptional<z.ZodNumber>;
@@ -1087,6 +1088,7 @@ declare const RecentTracksPageSchema: z.ZodObject<{
             maxY: z.ZodNumber;
         }, z.core.$strip>>;
         hasFace: z.ZodOptional<z.ZodBoolean>;
+        hasEmbeddedFace: z.ZodOptional<z.ZodBoolean>;
         hasRider: z.ZodOptional<z.ZodBoolean>;
         label: z.ZodOptional<z.ZodString>;
         labelScore: z.ZodOptional<z.ZodNumber>;
@@ -1348,6 +1350,7 @@ export declare const pipelineAnalyticsCapability: {
                 maxY: z.ZodNumber;
             }, z.core.$strip>>;
             hasFace: z.ZodOptional<z.ZodBoolean>;
+            hasEmbeddedFace: z.ZodOptional<z.ZodBoolean>;
             hasRider: z.ZodOptional<z.ZodBoolean>;
             label: z.ZodOptional<z.ZodString>;
             labelScore: z.ZodOptional<z.ZodNumber>;
@@ -1444,6 +1447,7 @@ export declare const pipelineAnalyticsCapability: {
                 maxY: z.ZodNumber;
             }, z.core.$strip>>;
             hasFace: z.ZodOptional<z.ZodBoolean>;
+            hasEmbeddedFace: z.ZodOptional<z.ZodBoolean>;
             hasRider: z.ZodOptional<z.ZodBoolean>;
             label: z.ZodOptional<z.ZodString>;
             labelScore: z.ZodOptional<z.ZodNumber>;
@@ -1563,6 +1567,7 @@ export declare const pipelineAnalyticsCapability: {
                 maxY: z.ZodNumber;
             }, z.core.$strip>>;
             hasFace: z.ZodOptional<z.ZodBoolean>;
+            hasEmbeddedFace: z.ZodOptional<z.ZodBoolean>;
             hasRider: z.ZodOptional<z.ZodBoolean>;
             label: z.ZodOptional<z.ZodString>;
             labelScore: z.ZodOptional<z.ZodNumber>;
@@ -1678,6 +1683,7 @@ export declare const pipelineAnalyticsCapability: {
                     maxY: z.ZodNumber;
                 }, z.core.$strip>>;
                 hasFace: z.ZodOptional<z.ZodBoolean>;
+                hasEmbeddedFace: z.ZodOptional<z.ZodBoolean>;
                 hasRider: z.ZodOptional<z.ZodBoolean>;
                 label: z.ZodOptional<z.ZodString>;
                 labelScore: z.ZodOptional<z.ZodNumber>;

package/dist/capabilities/pipeline-orchestrator.cap.d.ts

@@ -532,6 +532,24 @@ declare const CameraStatusSchema: z.ZodObject<{
     }, z.core.$strip>>>;
     fetchedAt: z.ZodNumber;
 }, z.core.$strip>;
+/**
+ * Why the dispatcher does NOT consider a device the node HAS for the
+ * camera-root election. The list is the CONTRACT between the orchestrator's
+ * `resolveInferenceDeviceEligibility` (which computes it) and the admin UI
+ * (which renders it) — the orchestrator's `InferenceDeviceExclusionReason`
+ * derives from this tuple so the two can never drift.
+ *
+ * Every one of these drops used to be silent, and an accelerator that is
+ * enabled, available, and never chosen is indistinguishable from one that was
+ * never configured. The reason is the difference.
+ */
+declare const INFERENCE_DEVICE_EXCLUSION_REASONS: readonly ["disabled", "unavailable", "cannot-host-camera-root", "accelerator-preferred"];
+declare const InferenceDeviceExclusionReasonSchema: z.ZodEnum<{
+    disabled: "disabled";
+    unavailable: "unavailable";
+    "cannot-host-camera-root": "cannot-host-camera-root";
+    "accelerator-preferred": "accelerator-preferred";
+}>;
 declare const NodeInferenceDeviceSchema: z.ZodObject<{
     key: z.ZodString;
     backend: z.ZodString;
@@ -554,6 +572,12 @@ declare const NodeInferenceDeviceSchema: z.ZodObject<{
         settings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         jumpDeviceKey: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    exclusion: z.ZodNullable<z.ZodEnum<{
+        disabled: "disabled";
+        unavailable: "unavailable";
+        "cannot-host-camera-root": "cannot-host-camera-root";
+        "accelerator-preferred": "accelerator-preferred";
+    }>>;
 }, z.core.$strip>;
 declare const NodeInferenceDevicesSchema: z.ZodObject<{
     nodeId: z.ZodString;
@@ -580,6 +604,12 @@ declare const NodeInferenceDevicesSchema: z.ZodObject<{
             settings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             jumpDeviceKey: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
+        exclusion: z.ZodNullable<z.ZodEnum<{
+            disabled: "disabled";
+            unavailable: "unavailable";
+            "cannot-host-camera-root": "cannot-host-camera-root";
+            "accelerator-preferred": "accelerator-preferred";
+        }>>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 /**
@@ -1027,6 +1057,12 @@ export declare const pipelineOrchestratorCapability: {
                     settings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
                     jumpDeviceKey: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>>>;
+                exclusion: z.ZodNullable<z.ZodEnum<{
+                    disabled: "disabled";
+                    unavailable: "unavailable";
+                    "cannot-host-camera-root": "cannot-host-camera-root";
+                    "accelerator-preferred": "accelerator-preferred";
+                }>>;
             }, z.core.$strip>>>;
         }, z.core.$strip>, import("./capability-definition.js").CapabilityMethodKind>;
         /**
@@ -1887,4 +1923,5 @@ export type CameraRecordingMode = z.infer<typeof CameraRecordingModeSchema>;
 export type IngestOwner = z.infer<typeof IngestOwnerSchema>;
 export type NodeInferenceDevice = z.infer<typeof NodeInferenceDeviceSchema>;
 export type NodeInferenceDevices = z.infer<typeof NodeInferenceDevicesSchema>;
-export { AgentLoadSummarySchema, CameraAssignmentStatusSchema, CameraAudioStatusSchema, CameraBrokerProfileSchema, CameraBrokerStatusSchema, CameraDecoderShmSchema, CameraDecoderStatusSchema, CameraDetectionPhaseSchema, CameraDetectionProvisioningSchema, CameraDetectionProvisioningStateSchema, CameraDetectionStatusSchema, CameraMotionStatusSchema, CameraPipelineConfigSchema, CameraRecordingModeSchema, CameraRecordingStatusSchema, CameraSourceStatusSchema, CameraSourceStreamSchema, CameraStatusDegradationReasonSchema, CameraStatusDegradationSchema, CameraStatusSchema, CameraStatusStageSchema, CameraStepOverridePatchSchema, CapabilityBindingsSchema, DiskReconcileJobSchema, GlobalMetricsSchema, IngestOwnerSchema, PipelineAssignmentSchema, PipelineTemplateSchema as OrchestratorPipelineTemplateSchema, };
+export type InferenceDeviceExclusionReason = z.infer<typeof InferenceDeviceExclusionReasonSchema>;
+export { AgentLoadSummarySchema, CameraAssignmentStatusSchema, CameraAudioStatusSchema, CameraBrokerProfileSchema, CameraBrokerStatusSchema, CameraDecoderShmSchema, CameraDecoderStatusSchema, CameraDetectionPhaseSchema, CameraDetectionProvisioningSchema, CameraDetectionProvisioningStateSchema, CameraDetectionStatusSchema, CameraMotionStatusSchema, CameraPipelineConfigSchema, CameraRecordingModeSchema, CameraRecordingStatusSchema, CameraSourceStatusSchema, CameraSourceStreamSchema, CameraStatusDegradationReasonSchema, CameraStatusDegradationSchema, CameraStatusSchema, CameraStatusStageSchema, CameraStepOverridePatchSchema, CapabilityBindingsSchema, DiskReconcileJobSchema, GlobalMetricsSchema, INFERENCE_DEVICE_EXCLUSION_REASONS, InferenceDeviceExclusionReasonSchema, IngestOwnerSchema, PipelineAssignmentSchema, PipelineTemplateSchema as OrchestratorPipelineTemplateSchema, };

package/dist/capabilities/pipeline-runner.cap.d.ts

@@ -55,6 +55,7 @@ declare const DetailResultSchema: z.ZodObject<{
     }, z.core.$strip>>;
     embedding: z.ZodOptional<z.ZodString>;
     embeddingMagnitude: z.ZodOptional<z.ZodNumber>;
+    embeddingModelId: z.ZodOptional<z.ZodString>;
     label: z.ZodOptional<z.ZodString>;
     labelTier: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
     labelModelId: z.ZodOptional<z.ZodString>;
@@ -628,6 +629,7 @@ export declare const pipelineRunnerCapability: {
                 }, z.core.$strip>>;
                 embedding: z.ZodOptional<z.ZodString>;
                 embeddingMagnitude: z.ZodOptional<z.ZodNumber>;
+                embeddingModelId: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
                 labelTier: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
                 labelModelId: z.ZodOptional<z.ZodString>;
@@ -707,6 +709,7 @@ export declare const pipelineRunnerCapability: {
                 }, z.core.$strip>>;
                 embedding: z.ZodOptional<z.ZodString>;
                 embeddingMagnitude: z.ZodOptional<z.ZodNumber>;
+                embeddingModelId: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
                 labelTier: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
                 labelModelId: z.ZodOptional<z.ZodString>;

package/dist/device/index.d.ts

@@ -18,8 +18,8 @@ export type { IBatteryOperated, IDoorbellButton, INativeSnapshot, IPanTiltZoom,
 export { getByPath, setByPath } from './path-util.js';
 export type { ReachabilityPollHandle, ReachabilityPollLogger, ReachabilityPollOptions, } from './reachability-poll.js';
 export { REACHABILITY_FAILURES_TO_OFFLINE, REACHABILITY_POLL_INTERVAL_MS, REACHABILITY_PROBE_TIMEOUT_MS, startReachabilityPoll, } from './reachability-poll.js';
-export type { RuntimeStateBridge } from './runtime-state-helpers.js';
-export { createRuntimeStateBridge } from './runtime-state-helpers.js';
+export type { RuntimeStateBridge, RuntimeStateStaleReadPolicy, } from './runtime-state-helpers.js';
+export { createRuntimeStateBridge, OPERATOR_WRITTEN_STALE_MS, RUNTIME_STATE_REFRESH_MISS_COOLDOWN_MS, } from './runtime-state-helpers.js';
 export type { WireableField } from './schema-fields.js';
 export { enumerateItemArrayFields, enumerateSchemaFields } from './schema-fields.js';
 export type { DeviceConfigEntry } from './zod-to-config-ui.js';

package/dist/device/runtime-state-helpers.d.ts

@@ -13,6 +13,45 @@ import type { IDeviceRuntimeState } from './device-runtime-state.js';
  * coming back; per-read is enough to stall the viewer's first paint.
  */
 export declare const RUNTIME_STATE_REFRESH_MISS_COOLDOWN_MS = 60000;
+/**
+ * The freshness window for a cap whose value changes ONLY when WE write it.
+ *
+ * The usual `staleMs: 10_000` is tuned for a reading that moves on its own — a
+ * battery level, a day/night state that flips at dusk. It is the wrong number
+ * for a cap like `privacy-mask`, whose two facts (is the video mask on, is the
+ * microphone on) change when an operator changes them, through a `setMask` /
+ * `setAudioEnabled` that **re-reads the camera and rewrites this very slice**.
+ * A write is therefore its own invalidation: the window never delays an
+ * operator's own change, however long it is.
+ *
+ * What the window really bounds is the ONE case we do not write: somebody
+ * changing the mask in the vendor app or the camera's web UI. Ten minutes is
+ * the trade — that change is visible within ten minutes, and a fleet of 29
+ * cameras behind a page that polls every 5s costs about 3 camera round trips a
+ * minute instead of 696
+ * ([D221](../../../../docs/decisions/adr-0221-a-polled-list-never-dials-a-camera.md)).
+ *
+ * Use it ONLY with {@link RuntimeStateStaleReadPolicy} `'serve-and-revalidate'`.
+ * On the awaiting default a window this long does not remove the stall, it
+ * merely makes it rarer and just as long.
+ */
+export declare const OPERATOR_WRITTEN_STALE_MS: number;
+/**
+ * What a read does when the slice it finds is STALE **and present**.
+ *
+ *  - `'await-refresh'` (default) — the caller waits for the camera. Right for a
+ *    reader that asked BECAUSE it wants the current value: an open settings
+ *    form, a write path reading back what the firmware accepted.
+ *  - `'serve-and-revalidate'` — the caller is answered from the slice
+ *    immediately and the refresh runs behind it, for the next caller. Right for
+ *    a POLLED reader, which by definition will ask again shortly and must never
+ *    put a camera round trip on a request path (D49, D221).
+ *
+ * A COLD slice — one that was never fetched — awaits under both policies. The
+ * first render has to be a real answer rather than a flash of the `empty()`
+ * default, and a default is exactly what "the operator muted this" looks like.
+ */
+export type RuntimeStateStaleReadPolicy = 'await-refresh' | 'serve-and-revalidate';
 /**
  * Minimal logger surface the bridge uses. Declared with METHOD syntax
  * (not a property arrow) so the parameter check is bivariant — a scoped
@@ -69,6 +108,23 @@ export interface RuntimeStateBridgeLogger {
  * helper stays thin so a single provider can host multiple cap-bridged
  * readers without fighting over a shared promise.
  *
+ * ## The freshness window belongs to the READER, not to the cap
+ *
+ * `staleMs` plus {@link RuntimeStateStaleReadPolicy} are what make this the
+ * ONLY cache in front of a cap. Before D221 they were not: `privacy-mask` kept
+ * the 10s window meant for a self-changing reading while a fleet-wide list
+ * polled it every 5s, so the slice was stale on nearly every read and the badge
+ * dialled 29 cameras twelve times a minute. The answer was a SECOND cache in
+ * the consumer — two authorities over one fact, and the write path that did not
+ * route through that consumer (the mask editor, which writes the cap directly)
+ * left it lying.
+ *
+ * So a cap whose value only an operator changes takes
+ * {@link OPERATOR_WRITTEN_STALE_MS} and `'serve-and-revalidate'`, here, once:
+ * the write path already re-reads the camera into this slice, which is a
+ * stronger invalidation than any downstream mirror can offer, and no consumer
+ * needs a cache of its own.
+ *
  * ## A refresh that does not LAND is a miss, and a miss costs the caller
  *
  * Providers swallow their own camera errors (they keep the last slice
@@ -91,8 +147,10 @@ export interface RuntimeStateBridgeLogger {
  */
 export interface RuntimeStateBridge<TStatus> {
     /** Run a stale-check; if the slice is missing or older than
-     *  `staleMs`, await `refresh()`. Idempotent within the freshness
-     *  window — back-to-back calls touch zero camera I/O. */
+     *  `staleMs`, refresh it — awaiting the camera, or behind the caller
+     *  when `staleRead` is `'serve-and-revalidate'` and a slice already
+     *  exists. Idempotent within the freshness window — back-to-back calls
+     *  touch zero camera I/O. */
     readonly ensureFresh: () => Promise<void>;
     /** Drop-in `getStatus` provider method. Includes the cross-device
      *  guard + freshness check + status projection from the slice. */
@@ -113,6 +171,9 @@ export declare function createRuntimeStateBridge<TCap extends CapabilityDefiniti
     readonly empty: () => z.infer<TCap['status']['schema']>;
     /** Override the miss cooldown (tests, or a cap whose fetch is cheap). */
     readonly refreshMissCooldownMs?: number;
+    /** What a stale-but-present slice does. Defaults to `'await-refresh'`,
+     *  which is what every caller did before the policy existed. */
+    readonly staleRead?: RuntimeStateStaleReadPolicy;
     /** Scoped logger so a refresh that never lands is visible per-device. */
     readonly logger?: RuntimeStateBridgeLogger;
 }): RuntimeStateBridge<z.infer<TCap['status']['schema']>>;

package/dist/index.d.ts

@@ -153,8 +153,8 @@ export type { IBatteryOperated, IDoorbellButton, INativeSnapshot, IPanTiltZoom,
 export { getByPath, setByPath } from './device/path-util.js';
 export type { ReachabilityPollHandle, ReachabilityPollLogger, ReachabilityPollOptions, } from './device/reachability-poll.js';
 export { REACHABILITY_FAILURES_TO_OFFLINE, REACHABILITY_POLL_INTERVAL_MS, REACHABILITY_PROBE_TIMEOUT_MS, startReachabilityPoll, } from './device/reachability-poll.js';
-export type { RuntimeStateBridge } from './device/runtime-state-helpers.js';
-export { createRuntimeStateBridge } from './device/runtime-state-helpers.js';
+export type { RuntimeStateBridge, RuntimeStateStaleReadPolicy, } from './device/runtime-state-helpers.js';
+export { createRuntimeStateBridge, OPERATOR_WRITTEN_STALE_MS, RUNTIME_STATE_REFRESH_MISS_COOLDOWN_MS, } from './device/runtime-state-helpers.js';
 export type { WireableField } from './device/schema-fields.js';
 export { enumerateItemArrayFields, enumerateSchemaFields } from './device/schema-fields.js';
 export type { SourceInfo } from './device/source-info.js';
@@ -199,7 +199,8 @@ export { isScheduleActive } from './notification/schedule.js';
 export { NC_SYSTEM_EVENT_FILTER_KEYS, type NcSystemEventFilterKey, systemEventFilterApplies, systemEventFilterAppliesToAnyKind, } from './notification/system-event-filters.js';
 export type { TimelapseCadencePair, TimelapsePreviewMode, TimelapseRule, TimelapseRuleInput, TimelapseRulePatch, TimelapseTemplate, } from './notification/timelapse-rule.js';
 export { assertTimelapseCadences, DEFAULT_TIMELAPSE_PREVIEW_TEXT, readTimelapseGeneratedAt, TIMELAPSE_DENSE_FLOOR_SEC, TimelapseRuleInputSchema, TimelapseRulePatchSchema, TimelapseRuleSchema, TimelapseTemplateSchema, } from './notification/timelapse-rule.js';
-export { DEFAULT_DETAIL_CROP_CONVENTION, DETAIL_CROP_PADDING_FIELD, DETAIL_CROP_PADDING_KEY, DETAIL_CROP_SECTION_ID, DETAIL_CROP_SQUARE_KEY, type DetailCropConvention, DetailCropConventionSchema, type DetailCropRect, deriveDetailCropRect, type HydratedSettingsSection, type HydratedSettingsView, pickDetailCropConvention, readDetailCropConvention, } from './pipeline/detail-crop.js';
+export { CLUSTER_MODEL_SCOPED_STEPS, CLUSTER_MODEL_SECTION_ID, type ClusterModelScopedStep, type ClusterStepModels, clusterModelSettingKey, DEFAULT_CLUSTER_STEP_MODELS, type HydratedClusterSection, type HydratedClusterView, isClusterScopedStep, pickClusterStepModels, readClusterStepModels, resolveClusterStepModelId, type StepModelScope, } from './pipeline/cluster-model-scope.js';
+export { DEFAULT_DETAIL_CROP_CONVENTION, DETAIL_CROP_PADDING_FIELD, DETAIL_CROP_PADDING_KEY, DETAIL_CROP_SECTION_ID, DETAIL_CROP_SQUARE_KEY, FULL_IMAGE_BBOX, type DetailCropConvention, DetailCropConventionSchema, type DetailCropRect, deriveDetailCropRect, type HydratedSettingsSection, type HydratedSettingsView, pickDetailCropConvention, readDetailCropConvention, } from './pipeline/detail-crop.js';
 export { DEFAULT_NATIVE_LEASE_SETTINGS, NATIVE_LEASE_ACTIVITY_FIELD, NATIVE_LEASE_ACTIVITY_KEY, NATIVE_LEASE_ADMISSION_FIELD, NATIVE_LEASE_ADMISSION_KEY, NATIVE_LEASE_BUDGET_FIELD, NATIVE_LEASE_BUDGET_KEY, NATIVE_LEASE_HOLD_FIELD, NATIVE_LEASE_HOLD_KEY, NATIVE_LEASE_SECTION_ID, NATIVE_LEASE_TILE_BUDGET_FIELD, NATIVE_LEASE_TILE_BUDGET_KEY, type NativeLeaseAdmission, NativeLeaseAdmissionSchema, type NativeLeaseKnob, type NativeLeaseNumberKnob, type NativeLeaseSettings, type NativeLeaseSettingsOverride, NativeLeaseSettingsSchema, pickNativeLeaseOverride, readNativeLeaseOverride, } from './pipeline/native-lease.js';
 export { ACCESS_ROLES, type AccessRoleAssignment, type AccessRoleId, type AccessRoleSpec, buildRoleScopes, detectAccessRole, roleSpec, } from './schemas/access-roles.js';
 export { type ApiKeyRecord, ApiKeyRecordSchema, type CapScope, CapScopeSchema, type DeviceSelector, DeviceSelectorSchema, type DeviceTokenScope, type MethodAccess, MethodAccessSchema, type ScopedToken, ScopedTokenSchema, type TokenScope, TokenScopeSchema, type UserRecord, UserRecordSchema, } from './schemas/auth-records.js';