@camstack/types 1.2.71 → 1.2.73

package/dist/capabilities/scene-monitor.cap.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { type InferNativeProvider } from './capability-definition.js';
 import { DeviceType } from '../device/device-type.js';
+import { type InferNativeProvider } from './capability-definition.js';
 /**
  * scene-monitor — device-scoped reference-region state cap. An operator marks
  * a rect ROI on a camera frame and names one or more states; the engine
@@ -9,14 +9,58 @@ import { DeviceType } from '../device/device-type.js';
  * thing except the comparator: `similarity` (CLIP cosine at the same ROI coords
  * vs condition-tagged references) and `llm` (vision-LLM judgment over the crop).
  *
- * D14 device-config archetype (`deviceConfig.ui.kind:'widget'`) — the framework
- * derives the device-detail contribution; the provider carries NO hand-written
- * settings-contribution methods. `status.kind:'push'` — the engine pushes on
- * every hysteresis flip / availability change; consumers never poll.
+ * **No `deviceConfig`, deliberately.** This shipped as the D14 widget archetype,
+ * which put a "Scenes" tab on one camera's detail page. That is the wrong shape
+ * for the thing: a scene is a standing question about the property ("is the bin
+ * still out"), and the operator's question is "which of my scenes have tripped",
+ * across every camera at once — not "what does camera 617 think". Buried one
+ * camera deep it also could not be found. The surface is now a top-level admin
+ * page (`/scenes`, `pages/Scenes.tsx`) that lists every scene on every camera and
+ * picks the camera inside the create flow, the same shape Events and Faces have.
+ *
+ * The consequence to keep in mind: `host/scene-monitor-editor` is gone from
+ * `HOST_WIDGETS` too. `scripts/check-host-widget-resolves.ts` asserts BOTH
+ * directions, so a registration nobody declares fails exactly as loudly as a
+ * declaration nobody registers. The editor is imported directly by the page.
+ *
+ * `status.kind:'push'` — the engine pushes on every hysteresis flip /
+ * availability change; consumers never poll.
  */
-/** Extensible condition tag. Seeded 'day' | 'night'; open by design so more can
- *  be added without a wire break (matching falls back to any-condition refs). */
+/** Extensible condition tag. Seeded 'day' | 'ir' (the two variants the operator
+ *  captures) plus 'night' | 'dawn' | 'dusk' from the resolver's sun-times band.
+ *  Open by design so more can be added without a wire break.
+ *
+ *  Matching does NOT fall back across conditions: cross-condition cosines are
+ *  not comparable, so "I have never seen this scene in this light" is reported
+ *  as `unknown`, never guessed. A day reference scored against an IR frame
+ *  collapses the cosine and would latch a false alarm every single night. */
 export declare const SceneConditionSchema: z.ZodString;
+/** The conditions the resolver can produce. Seeds for the UI's coverage line;
+ *  the wire type stays an open string. */
+export declare const SCENE_CONDITIONS: readonly ["day", "ir", "night", "dawn", "dusk"];
+/** Reserved, engine-owned state id standing for "the region no longer looks
+ *  like ANY captured reference". Never authored by an operator, never stored in
+ *  `states[]` — it is the synthetic candidate that makes divergence a
+ *  first-class hysteresis input rather than a bare `return`. */
+export declare const SCENE_DIVERGED = "__diverged__";
+/** `matched` = the baseline is what we see; `diverged` = it demonstrably is not;
+ *  `unknown` = we cannot judge (no reference for this condition, encoder model
+ *  changed, view shifted, no snapshot). `unknown` is a real value, not a null,
+ *  and never counts toward hysteresis in either direction. */
+export declare const SceneVerdictSchema: z.ZodEnum<{
+    unknown: "unknown";
+    matched: "matched";
+    diverged: "diverged";
+}>;
+/** Why a scene cannot judge. Named, because this feature's failure mode is
+ *  silence that reads as "nothing has happened". */
+export declare const SceneUnavailableSchema: z.ZodEnum<{
+    "no-reference-for-condition": "no-reference-for-condition";
+    "view-shifted": "view-shifted";
+    "no-vision-profile": "no-vision-profile";
+    "encoder-model-changed": "encoder-model-changed";
+    "no-snapshot": "no-snapshot";
+}>;
 /** One captured reference — condition-tagged, model-version-gated. `embedding`
  *  is `number[]` (Float32Array does NOT survive MsgPack/UDS). */
 export declare const SceneReferenceSchema: z.ZodObject<{
@@ -25,6 +69,7 @@ export declare const SceneReferenceSchema: z.ZodObject<{
     condition: z.ZodString;
     capturedAt: z.ZodNumber;
     thumbnailMediaId: z.ZodOptional<z.ZodString>;
+    anchorEmbedding: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
 }, z.core.$strip>;
 export declare const SceneMonitorStateSchema: z.ZodObject<{
     id: z.ZodString;
@@ -35,6 +80,7 @@ export declare const SceneMonitorStateSchema: z.ZodObject<{
         condition: z.ZodString;
         capturedAt: z.ZodNumber;
         thumbnailMediaId: z.ZodOptional<z.ZodString>;
+        anchorEmbedding: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
     }, z.core.$strip>>;
     textPrompts: z.ZodOptional<z.ZodArray<z.ZodString>>;
     referenceCount: z.ZodNumber;
@@ -52,6 +98,40 @@ export declare const SceneCheckSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     profileId: z.ZodOptional<z.ZodString>;
     hysteresisCount: z.ZodNumber;
 }, z.core.$strip>], "mode">;
+/** Defaults, as CONSTANTS rather than only as Zod `.default()`. A Zod default
+ *  does NOT run on the addon→addon cap path, so every runtime seam reads these
+ *  as absent-with-a-constant (the `NcConfirmSchema` lesson, three production
+ *  failures in one day). The schema defaults and these values are the same
+ *  numbers on purpose. */
+export declare const SCENE_DEFAULT_QUIET_SECONDS = 60;
+export declare const SCENE_DEFAULT_OBSERVATION_SPACING_SEC = 120;
+export declare const SCENE_DEFAULT_CHECK_INTERVAL_SEC = 60;
+export declare const SCENE_DEFAULT_ANCHOR_THRESHOLD = 0.85;
+export declare const SCENE_CONFIRM_DEFAULT_TIMEOUT_MS = 8000;
+export declare const SCENE_CONFIRM_DEFAULT_MAX_IMAGE_PX = 448;
+/** `resetScene({ recapture })` absent means TRUE — the operator decision. Read
+ *  at the seam, because a Zod `.optional()` carries no default at all. */
+export declare const SCENE_RESET_RECAPTURES = true;
+/**
+ * Vision-model adjudication of a candidate flip. Field names deliberately
+ * mirror `NcConfirmSchema` so an operator meets one vocabulary, not two.
+ *
+ * `onTimeout` defaults to **'hold'**, the OPPOSITE of `NcConfirmGate`'s
+ * fail-open: a notification suppressed is the worse error there, but a vision
+ * model that timed out has not told us the bin is gone, and a latch is a
+ * stateful claim that costs the operator a trip to reset.
+ */
+export declare const SceneConfirmSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    prompt: z.ZodString;
+    profileId: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    maxImagePx: z.ZodDefault<z.ZodNumber>;
+    onTimeout: z.ZodDefault<z.ZodEnum<{
+        flip: "flip";
+        hold: "hold";
+    }>>;
+}, z.core.$strip>;
 export declare const SceneMonitorSchema: z.ZodObject<{
     id: z.ZodString;
     label: z.ZodString;
@@ -88,6 +168,7 @@ export declare const SceneMonitorSchema: z.ZodObject<{
             condition: z.ZodString;
             capturedAt: z.ZodNumber;
             thumbnailMediaId: z.ZodOptional<z.ZodString>;
+            anchorEmbedding: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
         }, z.core.$strip>>;
         textPrompts: z.ZodOptional<z.ZodArray<z.ZodString>>;
         referenceCount: z.ZodNumber;
@@ -102,6 +183,43 @@ export declare const SceneMonitorSchema: z.ZodObject<{
         unavailable: "unavailable";
     }>;
     unavailableReason: z.ZodNullable<z.ZodString>;
+    baselineStateId: z.ZodNullable<z.ZodString>;
+    emit: z.ZodDefault<z.ZodEnum<{
+        live: "live";
+        latched: "latched";
+    }>>;
+    verdict: z.ZodEnum<{
+        unknown: "unknown";
+        matched: "matched";
+        diverged: "diverged";
+    }>;
+    latched: z.ZodBoolean;
+    armedAt: z.ZodNumber;
+    divergedAt: z.ZodNullable<z.ZodNumber>;
+    restoredAt: z.ZodNullable<z.ZodNumber>;
+    quietSeconds: z.ZodDefault<z.ZodNumber>;
+    minObservationSpacingSec: z.ZodDefault<z.ZodNumber>;
+    confirm: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        prompt: z.ZodString;
+        profileId: z.ZodOptional<z.ZodString>;
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+        maxImagePx: z.ZodDefault<z.ZodNumber>;
+        onTimeout: z.ZodDefault<z.ZodEnum<{
+            flip: "flip";
+            hold: "hold";
+        }>>;
+    }, z.core.$strip>>;
+    anchorThreshold: z.ZodDefault<z.ZodNumber>;
+    autoRestore: z.ZodDefault<z.ZodBoolean>;
+    unavailable: z.ZodNullable<z.ZodEnum<{
+        "no-reference-for-condition": "no-reference-for-condition";
+        "view-shifted": "view-shifted";
+        "no-vision-profile": "no-vision-profile";
+        "encoder-model-changed": "encoder-model-changed";
+        "no-snapshot": "no-snapshot";
+    }>>;
+    coveredConditions: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
 export declare const SceneMonitorStatusSchema: z.ZodObject<{
     monitors: z.ZodArray<z.ZodObject<{
@@ -140,6 +258,7 @@ export declare const SceneMonitorStatusSchema: z.ZodObject<{
                 condition: z.ZodString;
                 capturedAt: z.ZodNumber;
                 thumbnailMediaId: z.ZodOptional<z.ZodString>;
+                anchorEmbedding: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
             }, z.core.$strip>>;
             textPrompts: z.ZodOptional<z.ZodArray<z.ZodString>>;
             referenceCount: z.ZodNumber;
@@ -154,10 +273,50 @@ export declare const SceneMonitorStatusSchema: z.ZodObject<{
             unavailable: "unavailable";
         }>;
         unavailableReason: z.ZodNullable<z.ZodString>;
+        baselineStateId: z.ZodNullable<z.ZodString>;
+        emit: z.ZodDefault<z.ZodEnum<{
+            live: "live";
+            latched: "latched";
+        }>>;
+        verdict: z.ZodEnum<{
+            unknown: "unknown";
+            matched: "matched";
+            diverged: "diverged";
+        }>;
+        latched: z.ZodBoolean;
+        armedAt: z.ZodNumber;
+        divergedAt: z.ZodNullable<z.ZodNumber>;
+        restoredAt: z.ZodNullable<z.ZodNumber>;
+        quietSeconds: z.ZodDefault<z.ZodNumber>;
+        minObservationSpacingSec: z.ZodDefault<z.ZodNumber>;
+        confirm: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            prompt: z.ZodString;
+            profileId: z.ZodOptional<z.ZodString>;
+            timeoutMs: z.ZodDefault<z.ZodNumber>;
+            maxImagePx: z.ZodDefault<z.ZodNumber>;
+            onTimeout: z.ZodDefault<z.ZodEnum<{
+                flip: "flip";
+                hold: "hold";
+            }>>;
+        }, z.core.$strip>>;
+        anchorThreshold: z.ZodDefault<z.ZodNumber>;
+        autoRestore: z.ZodDefault<z.ZodBoolean>;
+        unavailable: z.ZodNullable<z.ZodEnum<{
+            "no-reference-for-condition": "no-reference-for-condition";
+            "view-shifted": "view-shifted";
+            "no-vision-profile": "no-vision-profile";
+            "encoder-model-changed": "encoder-model-changed";
+            "no-snapshot": "no-snapshot";
+        }>>;
+        coveredConditions: z.ZodArray<z.ZodString>;
     }, z.core.$strip>>;
     lastFetchedAt: z.ZodNumber;
 }, z.core.$strip>;
 export type SceneCondition = z.infer<typeof SceneConditionSchema>;
+export type SceneVerdict = z.infer<typeof SceneVerdictSchema>;
+export type SceneUnavailable = z.infer<typeof SceneUnavailableSchema>;
+export type SceneConfirm = z.infer<typeof SceneConfirmSchema>;
 export type SceneReference = z.infer<typeof SceneReferenceSchema>;
 export type SceneMonitorState = z.infer<typeof SceneMonitorStateSchema>;
 export type SceneCheck = z.infer<typeof SceneCheckSchema>;
@@ -170,14 +329,6 @@ export declare const sceneMonitorCapability: {
     readonly kind: "wrapper";
     readonly defaultActive: true;
     readonly deviceTypes: readonly [DeviceType.Camera];
-    readonly deviceConfig: {
-        readonly ui: {
-            readonly kind: "widget";
-            readonly widgetId: "host/scene-monitor-editor";
-            readonly tab: "scenes";
-            readonly label: "Scenes";
-        };
-    };
     readonly methods: {
         readonly listScenes: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             deviceId: z.ZodNumber;
@@ -218,6 +369,7 @@ export declare const sceneMonitorCapability: {
                         condition: z.ZodString;
                         capturedAt: z.ZodNumber;
                         thumbnailMediaId: z.ZodOptional<z.ZodString>;
+                        anchorEmbedding: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
                     }, z.core.$strip>>;
                     textPrompts: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     referenceCount: z.ZodNumber;
@@ -232,6 +384,43 @@ export declare const sceneMonitorCapability: {
                     unavailable: "unavailable";
                 }>;
                 unavailableReason: z.ZodNullable<z.ZodString>;
+                baselineStateId: z.ZodNullable<z.ZodString>;
+                emit: z.ZodDefault<z.ZodEnum<{
+                    live: "live";
+                    latched: "latched";
+                }>>;
+                verdict: z.ZodEnum<{
+                    unknown: "unknown";
+                    matched: "matched";
+                    diverged: "diverged";
+                }>;
+                latched: z.ZodBoolean;
+                armedAt: z.ZodNumber;
+                divergedAt: z.ZodNullable<z.ZodNumber>;
+                restoredAt: z.ZodNullable<z.ZodNumber>;
+                quietSeconds: z.ZodDefault<z.ZodNumber>;
+                minObservationSpacingSec: z.ZodDefault<z.ZodNumber>;
+                confirm: z.ZodOptional<z.ZodObject<{
+                    enabled: z.ZodDefault<z.ZodBoolean>;
+                    prompt: z.ZodString;
+                    profileId: z.ZodOptional<z.ZodString>;
+                    timeoutMs: z.ZodDefault<z.ZodNumber>;
+                    maxImagePx: z.ZodDefault<z.ZodNumber>;
+                    onTimeout: z.ZodDefault<z.ZodEnum<{
+                        flip: "flip";
+                        hold: "hold";
+                    }>>;
+                }, z.core.$strip>>;
+                anchorThreshold: z.ZodDefault<z.ZodNumber>;
+                autoRestore: z.ZodDefault<z.ZodBoolean>;
+                unavailable: z.ZodNullable<z.ZodEnum<{
+                    "no-reference-for-condition": "no-reference-for-condition";
+                    "view-shifted": "view-shifted";
+                    "no-vision-profile": "no-vision-profile";
+                    "encoder-model-changed": "encoder-model-changed";
+                    "no-snapshot": "no-snapshot";
+                }>>;
+                coveredConditions: z.ZodArray<z.ZodString>;
             }, z.core.$strip>>;
             lastFetchedAt: z.ZodNumber;
         }, z.core.$strip>, import("./capability-definition.js").CapabilityMethodKind>;
@@ -297,6 +486,7 @@ export declare const sceneMonitorCapability: {
                     condition: z.ZodString;
                     capturedAt: z.ZodNumber;
                     thumbnailMediaId: z.ZodOptional<z.ZodString>;
+                    anchorEmbedding: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
                 }, z.core.$strip>>;
                 textPrompts: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 referenceCount: z.ZodNumber;
@@ -311,6 +501,43 @@ export declare const sceneMonitorCapability: {
                 unavailable: "unavailable";
             }>;
             unavailableReason: z.ZodNullable<z.ZodString>;
+            baselineStateId: z.ZodNullable<z.ZodString>;
+            emit: z.ZodDefault<z.ZodEnum<{
+                live: "live";
+                latched: "latched";
+            }>>;
+            verdict: z.ZodEnum<{
+                unknown: "unknown";
+                matched: "matched";
+                diverged: "diverged";
+            }>;
+            latched: z.ZodBoolean;
+            armedAt: z.ZodNumber;
+            divergedAt: z.ZodNullable<z.ZodNumber>;
+            restoredAt: z.ZodNullable<z.ZodNumber>;
+            quietSeconds: z.ZodDefault<z.ZodNumber>;
+            minObservationSpacingSec: z.ZodDefault<z.ZodNumber>;
+            confirm: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodDefault<z.ZodBoolean>;
+                prompt: z.ZodString;
+                profileId: z.ZodOptional<z.ZodString>;
+                timeoutMs: z.ZodDefault<z.ZodNumber>;
+                maxImagePx: z.ZodDefault<z.ZodNumber>;
+                onTimeout: z.ZodDefault<z.ZodEnum<{
+                    flip: "flip";
+                    hold: "hold";
+                }>>;
+            }, z.core.$strip>>;
+            anchorThreshold: z.ZodDefault<z.ZodNumber>;
+            autoRestore: z.ZodDefault<z.ZodBoolean>;
+            unavailable: z.ZodNullable<z.ZodEnum<{
+                "no-reference-for-condition": "no-reference-for-condition";
+                "view-shifted": "view-shifted";
+                "no-vision-profile": "no-vision-profile";
+                "encoder-model-changed": "encoder-model-changed";
+                "no-snapshot": "no-snapshot";
+            }>>;
+            coveredConditions: z.ZodArray<z.ZodString>;
         }, z.core.$strip>, "mutation">;
         readonly updateScene: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             deviceId: z.ZodNumber;
@@ -341,6 +568,25 @@ export declare const sceneMonitorCapability: {
                     profileId: z.ZodOptional<z.ZodString>;
                     hysteresisCount: z.ZodNumber;
                 }, z.core.$strip>], "mode">>;
+                emit: z.ZodOptional<z.ZodEnum<{
+                    live: "live";
+                    latched: "latched";
+                }>>;
+                quietSeconds: z.ZodOptional<z.ZodNumber>;
+                minObservationSpacingSec: z.ZodOptional<z.ZodNumber>;
+                anchorThreshold: z.ZodOptional<z.ZodNumber>;
+                autoRestore: z.ZodOptional<z.ZodBoolean>;
+                confirm: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                    enabled: z.ZodDefault<z.ZodBoolean>;
+                    prompt: z.ZodString;
+                    profileId: z.ZodOptional<z.ZodString>;
+                    timeoutMs: z.ZodDefault<z.ZodNumber>;
+                    maxImagePx: z.ZodDefault<z.ZodNumber>;
+                    onTimeout: z.ZodDefault<z.ZodEnum<{
+                        flip: "flip";
+                        hold: "hold";
+                    }>>;
+                }, z.core.$strip>>>;
             }, z.core.$strip>;
         }, z.core.$strip>, z.ZodVoid, "mutation">;
         readonly deleteScene: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
@@ -367,6 +613,22 @@ export declare const sceneMonitorCapability: {
             deviceId: z.ZodNumber;
             monitorId: z.ZodString;
         }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /**
+         * Clear the latch, re-arm, and — by default — RE-CAPTURE the baseline for
+         * the CURRENT condition. The bin never goes back in exactly the same spot;
+         * "reset" in the operator's head means *this is the new normal*, and
+         * re-capture is what makes the feature self-healing against slow drift
+         * instead of failing silently weeks later.
+         *
+         * Reachable from three surfaces on this one mutation: the scene card, a
+         * notification button (an `onTrigger` sequence with a `kind:'cap'` step —
+         * no new Notification-Center code at all), and tRPC for scripts.
+         */
+        readonly resetScene: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            monitorId: z.ZodString;
+            recapture: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
     };
     readonly status: {
         readonly schema: z.ZodObject<{
@@ -406,6 +668,7 @@ export declare const sceneMonitorCapability: {
                         condition: z.ZodString;
                         capturedAt: z.ZodNumber;
                         thumbnailMediaId: z.ZodOptional<z.ZodString>;
+                        anchorEmbedding: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
                     }, z.core.$strip>>;
                     textPrompts: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     referenceCount: z.ZodNumber;
@@ -420,6 +683,43 @@ export declare const sceneMonitorCapability: {
                     unavailable: "unavailable";
                 }>;
                 unavailableReason: z.ZodNullable<z.ZodString>;
+                baselineStateId: z.ZodNullable<z.ZodString>;
+                emit: z.ZodDefault<z.ZodEnum<{
+                    live: "live";
+                    latched: "latched";
+                }>>;
+                verdict: z.ZodEnum<{
+                    unknown: "unknown";
+                    matched: "matched";
+                    diverged: "diverged";
+                }>;
+                latched: z.ZodBoolean;
+                armedAt: z.ZodNumber;
+                divergedAt: z.ZodNullable<z.ZodNumber>;
+                restoredAt: z.ZodNullable<z.ZodNumber>;
+                quietSeconds: z.ZodDefault<z.ZodNumber>;
+                minObservationSpacingSec: z.ZodDefault<z.ZodNumber>;
+                confirm: z.ZodOptional<z.ZodObject<{
+                    enabled: z.ZodDefault<z.ZodBoolean>;
+                    prompt: z.ZodString;
+                    profileId: z.ZodOptional<z.ZodString>;
+                    timeoutMs: z.ZodDefault<z.ZodNumber>;
+                    maxImagePx: z.ZodDefault<z.ZodNumber>;
+                    onTimeout: z.ZodDefault<z.ZodEnum<{
+                        flip: "flip";
+                        hold: "hold";
+                    }>>;
+                }, z.core.$strip>>;
+                anchorThreshold: z.ZodDefault<z.ZodNumber>;
+                autoRestore: z.ZodDefault<z.ZodBoolean>;
+                unavailable: z.ZodNullable<z.ZodEnum<{
+                    "no-reference-for-condition": "no-reference-for-condition";
+                    "view-shifted": "view-shifted";
+                    "no-vision-profile": "no-vision-profile";
+                    "encoder-model-changed": "encoder-model-changed";
+                    "no-snapshot": "no-snapshot";
+                }>>;
+                coveredConditions: z.ZodArray<z.ZodString>;
             }, z.core.$strip>>;
             lastFetchedAt: z.ZodNumber;
         }, z.core.$strip>;
@@ -462,6 +762,7 @@ export declare const sceneMonitorCapability: {
                     condition: z.ZodString;
                     capturedAt: z.ZodNumber;
                     thumbnailMediaId: z.ZodOptional<z.ZodString>;
+                    anchorEmbedding: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
                 }, z.core.$strip>>;
                 textPrompts: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 referenceCount: z.ZodNumber;
@@ -476,6 +777,43 @@ export declare const sceneMonitorCapability: {
                 unavailable: "unavailable";
             }>;
             unavailableReason: z.ZodNullable<z.ZodString>;
+            baselineStateId: z.ZodNullable<z.ZodString>;
+            emit: z.ZodDefault<z.ZodEnum<{
+                live: "live";
+                latched: "latched";
+            }>>;
+            verdict: z.ZodEnum<{
+                unknown: "unknown";
+                matched: "matched";
+                diverged: "diverged";
+            }>;
+            latched: z.ZodBoolean;
+            armedAt: z.ZodNumber;
+            divergedAt: z.ZodNullable<z.ZodNumber>;
+            restoredAt: z.ZodNullable<z.ZodNumber>;
+            quietSeconds: z.ZodDefault<z.ZodNumber>;
+            minObservationSpacingSec: z.ZodDefault<z.ZodNumber>;
+            confirm: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodDefault<z.ZodBoolean>;
+                prompt: z.ZodString;
+                profileId: z.ZodOptional<z.ZodString>;
+                timeoutMs: z.ZodDefault<z.ZodNumber>;
+                maxImagePx: z.ZodDefault<z.ZodNumber>;
+                onTimeout: z.ZodDefault<z.ZodEnum<{
+                    flip: "flip";
+                    hold: "hold";
+                }>>;
+            }, z.core.$strip>>;
+            anchorThreshold: z.ZodDefault<z.ZodNumber>;
+            autoRestore: z.ZodDefault<z.ZodBoolean>;
+            unavailable: z.ZodNullable<z.ZodEnum<{
+                "no-reference-for-condition": "no-reference-for-condition";
+                "view-shifted": "view-shifted";
+                "no-vision-profile": "no-vision-profile";
+                "encoder-model-changed": "encoder-model-changed";
+                "no-snapshot": "no-snapshot";
+            }>>;
+            coveredConditions: z.ZodArray<z.ZodString>;
         }, z.core.$strip>>;
         lastFetchedAt: z.ZodNumber;
     }, z.core.$strip>;

package/dist/capabilities/system.cap.d.ts

@@ -39,6 +39,69 @@ declare const NetworkAddressSchema: z.ZodObject<{
     family: z.ZodString;
     internal: z.ZodBoolean;
 }, z.core.$strip>;
+/**
+ * Provenance of the site coordinates, and the whole reason this is not just two
+ * numbers.
+ *
+ *   - `operator-set` — a human typed it, or accepted a detection. Authoritative;
+ *     nothing overwrites it.
+ *   - `derived-from-ip` — the hub geolocated its own public IP once, because a
+ *     default that is right to a few kilometres beats the coarse UTC clock split
+ *     the sun-times consumers otherwise fall back to.
+ *
+ * The UI shows which one it is. An operator who cannot tell a guess from their
+ * own input will eventually trust the guess.
+ */
+declare const SiteLocationSourceSchema: z.ZodEnum<{
+    "operator-set": "operator-set";
+    "derived-from-ip": "derived-from-ip";
+}>;
+/**
+ * Where the installation physically is — a fact of the SITE, not of any addon.
+ *
+ * It used to live in `pipeline-analytics`' global settings, which made a
+ * property of the building a property of one analytics addon. Anything that
+ * needs sun-times (scene condition variants today; anything solar tomorrow)
+ * reads it from here.
+ */
+declare const SiteLocationSchema: z.ZodObject<{
+    latitude: z.ZodNumber;
+    longitude: z.ZodNumber;
+    source: z.ZodEnum<{
+        "operator-set": "operator-set";
+        "derived-from-ip": "derived-from-ip";
+    }>;
+    updatedAt: z.ZodNumber;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * The read shape: the location plus the honest state of the one-shot derivation.
+ *
+ * `derivationAttemptedAt` is what makes the "one call, ever" contract
+ * inspectable. When it is set and `location` is null, the geo-IP lookup ran and
+ * failed; the hub will NOT try again on its own — the fallback is declared
+ * (consumers degrade to their own last resort) and the operator either types the
+ * coordinates or presses detect.
+ */
+declare const SiteLocationStatusSchema: z.ZodObject<{
+    location: z.ZodNullable<z.ZodObject<{
+        latitude: z.ZodNumber;
+        longitude: z.ZodNumber;
+        source: z.ZodEnum<{
+            "operator-set": "operator-set";
+            "derived-from-ip": "derived-from-ip";
+        }>;
+        updatedAt: z.ZodNumber;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    derivationAttemptedAt: z.ZodNullable<z.ZodNumber>;
+    derivationError: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/** `null` clears the location and re-arms nothing — the derivation stays spent. */
+declare const SetSiteLocationInputSchema: z.ZodNullable<z.ZodObject<{
+    latitude: z.ZodNumber;
+    longitude: z.ZodNumber;
+}, z.core.$strip>>;
 export declare const systemCapability: {
     readonly name: "system";
     readonly scope: "system";
@@ -79,6 +142,68 @@ export declare const systemCapability: {
         readonly getRetentionConfig: import("./capability-definition.js").CapabilityMethodSchema<z.ZodVoid, z.ZodNullable<z.ZodUnknown>, import("./capability-definition.js").CapabilityMethodKind>;
         readonly setRetentionConfig: import("./capability-definition.js").CapabilityMethodSchema<z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodNull, "mutation">;
         readonly forceRetentionCleanup: import("./capability-definition.js").CapabilityMethodSchema<z.ZodVoid, z.ZodVoid, "mutation">;
+        /**
+         * The site coordinates, deriving a default from the hub's public IP on the
+         * FIRST read that finds nothing stored.
+         *
+         * The derivation is one-shot and bounded: one outbound request, a few
+         * seconds, its outcome persisted either way. A hub with no internet pays it
+         * once and never again, and neither boot nor any consumer is blocked on it —
+         * the caller gets `location: null` and degrades exactly as it did before this
+         * method existed.
+         */
+        readonly getSiteLocation: import("./capability-definition.js").CapabilityMethodSchema<z.ZodVoid, z.ZodObject<{
+            location: z.ZodNullable<z.ZodObject<{
+                latitude: z.ZodNumber;
+                longitude: z.ZodNumber;
+                source: z.ZodEnum<{
+                    "operator-set": "operator-set";
+                    "derived-from-ip": "derived-from-ip";
+                }>;
+                updatedAt: z.ZodNumber;
+                label: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            derivationAttemptedAt: z.ZodNullable<z.ZodNumber>;
+            derivationError: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>, import("./capability-definition.js").CapabilityMethodKind>;
+        /** Operator input. Always lands as `source: 'operator-set'`. */
+        readonly setSiteLocation: import("./capability-definition.js").CapabilityMethodSchema<z.ZodNullable<z.ZodObject<{
+            latitude: z.ZodNumber;
+            longitude: z.ZodNumber;
+        }, z.core.$strip>>, z.ZodObject<{
+            location: z.ZodNullable<z.ZodObject<{
+                latitude: z.ZodNumber;
+                longitude: z.ZodNumber;
+                source: z.ZodEnum<{
+                    "operator-set": "operator-set";
+                    "derived-from-ip": "derived-from-ip";
+                }>;
+                updatedAt: z.ZodNumber;
+                label: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            derivationAttemptedAt: z.ZodNullable<z.ZodNumber>;
+            derivationError: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>, "mutation">;
+        /**
+         * Re-run the geo-IP derivation now. The ONLY way a spent or failed
+         * derivation is retried — there is no timer, and no read path retries.
+         * Overwrites an existing `derived-from-ip` value; refuses to clobber an
+         * `operator-set` one.
+         */
+        readonly detectSiteLocation: import("./capability-definition.js").CapabilityMethodSchema<z.ZodVoid, z.ZodObject<{
+            location: z.ZodNullable<z.ZodObject<{
+                latitude: z.ZodNumber;
+                longitude: z.ZodNumber;
+                source: z.ZodEnum<{
+                    "operator-set": "operator-set";
+                    "derived-from-ip": "derived-from-ip";
+                }>;
+                updatedAt: z.ZodNumber;
+                label: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            derivationAttemptedAt: z.ZodNullable<z.ZodNumber>;
+            derivationError: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>, "mutation">;
     };
     /** BIG PLAN 2: declarative mount hint — read by `@camstack/system` `buildCapRouters`. */
     readonly mount: {
@@ -86,4 +211,8 @@ export declare const systemCapability: {
     };
 };
 export type ISystemProvider = InferProvider<typeof systemCapability>;
-export { FeatureManifestSchema, HealthStatusSchema, NetworkAddressSchema };
+export type SiteLocation = z.infer<typeof SiteLocationSchema>;
+export type SiteLocationSource = z.infer<typeof SiteLocationSourceSchema>;
+export type SiteLocationStatus = z.infer<typeof SiteLocationStatusSchema>;
+export type SetSiteLocationInput = z.infer<typeof SetSiteLocationInputSchema>;
+export { FeatureManifestSchema, HealthStatusSchema, NetworkAddressSchema, SetSiteLocationInputSchema, SiteLocationSchema, SiteLocationSourceSchema, SiteLocationStatusSchema, };