@camstack/types 1.2.72 → 1.2.74

package/dist/capabilities/notification-rules.cap.d.ts

@@ -230,28 +230,36 @@ export declare const NC_AUDIO_DBFS_FLOOR = -96;
 /**
  * Audio condition (IMMEDIATE trigger) — a rule on SOUND, not on a picture.
  *
- * Operator-approved vocabulary (2026-08-12, option A — the same one the
- * reference notifier uses, so an operator moving between them re-uses what
- * they already know): a rule matches when, over a sampling window of
- * `samplingSeconds`, at least `hitPercent`% of the audio samples in that
- * window are HITS. A sample is a hit when it satisfies BOTH present filters:
+ * **TWO EXCLUSIVE MODES** (operator decision 2026-08-14, D157). Which one a
+ * rule is in is not a stored field — it is WHICH FILTER the rule carries, so
+ * there is no second switch that can disagree with the first and every rule
+ * authored before the decision migrates for free (`audioModeOf`):
  *
- *  - `dbThreshold` — its level is at or above this many dBFS (see
- *    {@link NC_AUDIO_DBFS_FLOOR}: negative-going, `0` = full scale);
- *  - `labels` — the classifier put at least one of these labels on it.
+ *  - **LABEL mode — `labels` present.** The rule fires on the FIRST frame the
+ *    classifier labels with one of them. No window, no percentage:
+ *    `hitPercent` and `samplingSeconds` are ignored, and the rule's own
+ *    `throttle` cooldown is the only brake. The per-label confidence floor is
+ *    the analyzer's (`classificationMinScore`, per device) — a label only
+ *    reaches this condition if the classifier was already confident enough.
+ *  - **LEVEL mode — `dbThreshold` present, no labels.** The sampling window IS
+ *    the condition: at least `hitPercent`% of the samples over
+ *    `samplingSeconds` must be at or above `dbThreshold` dBFS (see
+ *    {@link NC_AUDIO_DBFS_FLOOR}: negative-going, `0` = full scale). The window
+ *    must be FULL before it can match — a window open for two of its ten
+ *    seconds is 100% of nothing.
  *
- * Both are OPTIONAL and independent, which is the point of the shape: a
- * loudness rule ("something loud at 3am") needs no model to be right, and a
- * label rule ("a dog barked") needs no threshold. **Fail-closed when NEITHER
- * is given** — a window in which every sample is trivially a hit would fire on
- * silence, so the engine refuses such a condition rather than notifying on
- * nothing (the schema cannot express "at least one of" without becoming a
- * ZodEffects the cap path would have to special-case).
+ * **Why label mode has no window.** It had one, and it never fired: the
+ * analyzer emits ~1 audio frame per second but YAMNet only LABELS one to three
+ * of them per episode, even through continuous crying. The measured maximum
+ * `hitPercent` over the whole live history was 40 — under the shipped default
+ * of 60, so a label rule could not fire at all, ever. A percentage of frames is
+ * the wrong question to ask of a sparse classifier.
  *
- * `hitPercent` is over the samples the window actually HOLDS, and the window
- * must be FULL before it can match — a window that has been open for two
- * seconds of its ten is 100% of nothing, and firing on it would make
- * `samplingSeconds` decorative.
+ * **Fail-closed when NEITHER is given** — every sample would be a trivial hit
+ * and the rule would fire on silence. The schema cannot express "exactly one
+ * of" without becoming a ZodEffects the cap path would have to special-case, so
+ * the exclusivity is enforced where every editor writes (`patchAudio`) and a
+ * legacy rule carrying both resolves to LABEL (the mode that fires).
  *
  * Labels are the audio macro classes (`AUDIO_MACRO_LABELS` / the NC taxonomy's
  * `audio-*` ids). Both spellings are accepted — the matcher normalizes the
@@ -468,11 +476,67 @@ export declare const NcDeviceStateConditionSchema: z.ZodObject<{
     states: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
 export type NcDeviceStateCondition = z.infer<typeof NcDeviceStateConditionSchema>;
+/**
+ * "This rule applies only while scene `sceneId` is `matched` / `diverged`."
+ *
+ * A GATE, not a trigger. `occupancy` and `audio` each DISCRIMINATE their rule —
+ * carrying one makes the rule fire on that subject and nothing else. Scene is
+ * the other shape entirely, the `deviceState` shape: it narrows a rule that
+ * already has a trigger ("tell me about a person at the front door, but only
+ * while the bin is still out"). That is why it composes with every delivery
+ * instead of owning one, and why no new `NcDelivery` member and no new subject
+ * kind exist for it — see D159.
+ *
+ * ── Identity ───────────────────────────────────────────────────────────────
+ * `sceneId` is `SceneMonitor.id`, a `randomUUID()` minted by `createScene` —
+ * globally unique, so it needs no device to disambiguate it. `deviceId` is
+ * carried as a HINT for the editor and for the log line, never as part of the
+ * lookup key: a rule whose hint drifted must still gate correctly.
+ *
+ * ── Which boolean ──────────────────────────────────────────────────────────
+ * `latched` ABSENT means "whatever the scene itself says" — `SceneMonitor.emit`
+ * already declares which boolean drives notification rules, and a second knob
+ * that could disagree with it is exactly the D62 failure. Set it only to
+ * override one rule against the scene's own default.
+ *
+ *  - LIVE reading (`emit`/`latched` resolve to live): passes iff
+ *    `verdict === requiredState`. `unknown` — no reference for this light, view
+ *    shifted, no snapshot — passes NEITHER. A scene that cannot judge is not
+ *    evidence, in either direction.
+ *  - LATCHED reading: passes iff `latched === (requiredState === 'diverged')`.
+ *    The latch is a durable fact about the past ("it has diverged since I armed
+ *    it"), so a camera that has gone dark does not clear it — that is the whole
+ *    reason the operator asked for a latch.
+ *
+ * The gate reads an in-memory mirror (`NcSceneStateCache`) refreshed OFF the
+ * event path, never the cap: D49. A mirror that has never loaded, or a scene it
+ * does not carry, reads absent and the rule does NOT fire — fail closed, and
+ * said out loud in the log rather than dropped in silence.
+ */
+export declare const NcSceneConditionSchema: z.ZodObject<{
+    sceneId: z.ZodString;
+    deviceId: z.ZodOptional<z.ZodNumber>;
+    requiredState: z.ZodEnum<{
+        matched: "matched";
+        diverged: "diverged";
+    }>;
+    latched: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type NcSceneCondition = z.infer<typeof NcSceneConditionSchema>;
 export declare const NcConditionsSchema: z.ZodObject<{
     deviceState: z.ZodOptional<z.ZodObject<{
         deviceId: z.ZodNumber;
         states: z.ZodArray<z.ZodString>;
     }, z.core.$strip>>;
+    scene: z.ZodOptional<z.ZodObject<{
+        sceneId: z.ZodString;
+        deviceId: z.ZodOptional<z.ZodNumber>;
+        requiredState: z.ZodEnum<{
+            matched: "matched";
+            diverged: "diverged";
+        }>;
+        latched: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
     devices: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
     classes: z.ZodOptional<z.ZodArray<z.ZodString>>;
     classesExclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -742,6 +806,15 @@ export declare const NcRuleInputSchema: z.ZodObject<{
             deviceId: z.ZodNumber;
             states: z.ZodArray<z.ZodString>;
         }, z.core.$strip>>;
+        scene: z.ZodOptional<z.ZodObject<{
+            sceneId: z.ZodString;
+            deviceId: z.ZodOptional<z.ZodNumber>;
+            requiredState: z.ZodEnum<{
+                matched: "matched";
+                diverged: "diverged";
+            }>;
+            latched: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
         devices: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
         classes: z.ZodOptional<z.ZodArray<z.ZodString>>;
         classesExclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -1075,6 +1148,15 @@ export declare const NcRulePatchSchema: z.ZodObject<{
             deviceId: z.ZodNumber;
             states: z.ZodArray<z.ZodString>;
         }, z.core.$strip>>;
+        scene: z.ZodOptional<z.ZodObject<{
+            sceneId: z.ZodString;
+            deviceId: z.ZodOptional<z.ZodNumber>;
+            requiredState: z.ZodEnum<{
+                matched: "matched";
+                diverged: "diverged";
+            }>;
+            latched: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
         devices: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
         classes: z.ZodOptional<z.ZodArray<z.ZodString>>;
         classesExclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -1225,6 +1307,15 @@ export declare const NcRuleSchema: z.ZodObject<{
             deviceId: z.ZodNumber;
             states: z.ZodArray<z.ZodString>;
         }, z.core.$strip>>;
+        scene: z.ZodOptional<z.ZodObject<{
+            sceneId: z.ZodString;
+            deviceId: z.ZodOptional<z.ZodNumber>;
+            requiredState: z.ZodEnum<{
+                matched: "matched";
+                diverged: "diverged";
+            }>;
+            latched: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
         devices: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
         classes: z.ZodOptional<z.ZodArray<z.ZodString>>;
         classesExclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -1489,6 +1580,7 @@ export declare const NcConditionDescriptorSchema: z.ZodObject<{
         audio: "audio";
         deviceState: "deviceState";
         schedule: "schedule";
+        scene: "scene";
         packagePhase: "packagePhase";
         systemEvent: "systemEvent";
         occupancy: "occupancy";
@@ -1890,6 +1982,15 @@ export declare const notificationRulesCapability: {
                         deviceId: z.ZodNumber;
                         states: z.ZodArray<z.ZodString>;
                     }, z.core.$strip>>;
+                    scene: z.ZodOptional<z.ZodObject<{
+                        sceneId: z.ZodString;
+                        deviceId: z.ZodOptional<z.ZodNumber>;
+                        requiredState: z.ZodEnum<{
+                            matched: "matched";
+                            diverged: "diverged";
+                        }>;
+                        latched: z.ZodOptional<z.ZodBoolean>;
+                    }, z.core.$strip>>;
                     devices: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
                     classes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     classesExclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -2134,6 +2235,15 @@ export declare const notificationRulesCapability: {
                         deviceId: z.ZodNumber;
                         states: z.ZodArray<z.ZodString>;
                     }, z.core.$strip>>;
+                    scene: z.ZodOptional<z.ZodObject<{
+                        sceneId: z.ZodString;
+                        deviceId: z.ZodOptional<z.ZodNumber>;
+                        requiredState: z.ZodEnum<{
+                            matched: "matched";
+                            diverged: "diverged";
+                        }>;
+                        latched: z.ZodOptional<z.ZodBoolean>;
+                    }, z.core.$strip>>;
                     devices: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
                     classes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     classesExclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -2376,6 +2486,15 @@ export declare const notificationRulesCapability: {
                         deviceId: z.ZodNumber;
                         states: z.ZodArray<z.ZodString>;
                     }, z.core.$strip>>;
+                    scene: z.ZodOptional<z.ZodObject<{
+                        sceneId: z.ZodString;
+                        deviceId: z.ZodOptional<z.ZodNumber>;
+                        requiredState: z.ZodEnum<{
+                            matched: "matched";
+                            diverged: "diverged";
+                        }>;
+                        latched: z.ZodOptional<z.ZodBoolean>;
+                    }, z.core.$strip>>;
                     devices: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
                     classes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     classesExclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -2612,6 +2731,15 @@ export declare const notificationRulesCapability: {
                         deviceId: z.ZodNumber;
                         states: z.ZodArray<z.ZodString>;
                     }, z.core.$strip>>;
+                    scene: z.ZodOptional<z.ZodObject<{
+                        sceneId: z.ZodString;
+                        deviceId: z.ZodOptional<z.ZodNumber>;
+                        requiredState: z.ZodEnum<{
+                            matched: "matched";
+                            diverged: "diverged";
+                        }>;
+                        latched: z.ZodOptional<z.ZodBoolean>;
+                    }, z.core.$strip>>;
                     devices: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
                     classes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     classesExclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -2945,6 +3073,15 @@ export declare const notificationRulesCapability: {
                         deviceId: z.ZodNumber;
                         states: z.ZodArray<z.ZodString>;
                     }, z.core.$strip>>;
+                    scene: z.ZodOptional<z.ZodObject<{
+                        sceneId: z.ZodString;
+                        deviceId: z.ZodOptional<z.ZodNumber>;
+                        requiredState: z.ZodEnum<{
+                            matched: "matched";
+                            diverged: "diverged";
+                        }>;
+                        latched: z.ZodOptional<z.ZodBoolean>;
+                    }, z.core.$strip>>;
                     devices: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
                     classes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     classesExclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -3094,6 +3231,15 @@ export declare const notificationRulesCapability: {
                         deviceId: z.ZodNumber;
                         states: z.ZodArray<z.ZodString>;
                     }, z.core.$strip>>;
+                    scene: z.ZodOptional<z.ZodObject<{
+                        sceneId: z.ZodString;
+                        deviceId: z.ZodOptional<z.ZodNumber>;
+                        requiredState: z.ZodEnum<{
+                            matched: "matched";
+                            diverged: "diverged";
+                        }>;
+                        latched: z.ZodOptional<z.ZodBoolean>;
+                    }, z.core.$strip>>;
                     devices: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
                     classes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     classesExclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -3384,6 +3530,15 @@ export declare const notificationRulesCapability: {
                         deviceId: z.ZodNumber;
                         states: z.ZodArray<z.ZodString>;
                     }, z.core.$strip>>;
+                    scene: z.ZodOptional<z.ZodObject<{
+                        sceneId: z.ZodString;
+                        deviceId: z.ZodOptional<z.ZodNumber>;
+                        requiredState: z.ZodEnum<{
+                            matched: "matched";
+                            diverged: "diverged";
+                        }>;
+                        latched: z.ZodOptional<z.ZodBoolean>;
+                    }, z.core.$strip>>;
                     devices: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
                     classes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     classesExclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -3655,6 +3810,7 @@ export declare const notificationRulesCapability: {
                     audio: "audio";
                     deviceState: "deviceState";
                     schedule: "schedule";
+                    scene: "scene";
                     packagePhase: "packagePhase";
                     systemEvent: "systemEvent";
                     occupancy: "occupancy";

package/dist/capabilities/osd-manager.cap.d.ts

@@ -93,6 +93,15 @@ export declare const OsdSlotBindingSchema: z.ZodObject<{
             deviceId: z.ZodNumber;
             states: z.ZodArray<z.ZodString>;
         }, z.core.$strip>>;
+        scene: z.ZodOptional<z.ZodObject<{
+            sceneId: z.ZodString;
+            deviceId: z.ZodOptional<z.ZodNumber>;
+            requiredState: z.ZodEnum<{
+                matched: "matched";
+                diverged: "diverged";
+            }>;
+            latched: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
         devices: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
         classes: z.ZodOptional<z.ZodArray<z.ZodString>>;
         classesExclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -243,6 +252,15 @@ export declare const OsdSlotViewSchema: z.ZodObject<{
                 deviceId: z.ZodNumber;
                 states: z.ZodArray<z.ZodString>;
             }, z.core.$strip>>;
+            scene: z.ZodOptional<z.ZodObject<{
+                sceneId: z.ZodString;
+                deviceId: z.ZodOptional<z.ZodNumber>;
+                requiredState: z.ZodEnum<{
+                    matched: "matched";
+                    diverged: "diverged";
+                }>;
+                latched: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>;
             devices: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
             classes: z.ZodOptional<z.ZodArray<z.ZodString>>;
             classesExclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -465,6 +483,15 @@ export declare const osdManagerCapability: {
                             deviceId: z.ZodNumber;
                             states: z.ZodArray<z.ZodString>;
                         }, z.core.$strip>>;
+                        scene: z.ZodOptional<z.ZodObject<{
+                            sceneId: z.ZodString;
+                            deviceId: z.ZodOptional<z.ZodNumber>;
+                            requiredState: z.ZodEnum<{
+                                matched: "matched";
+                                diverged: "diverged";
+                            }>;
+                            latched: z.ZodOptional<z.ZodBoolean>;
+                        }, z.core.$strip>>;
                         devices: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
                         classes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                         classesExclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -617,6 +644,7 @@ export declare const osdManagerCapability: {
                     audio: "audio";
                     deviceState: "deviceState";
                     schedule: "schedule";
+                    scene: "scene";
                     packagePhase: "packagePhase";
                     systemEvent: "systemEvent";
                     occupancy: "occupancy";
@@ -703,6 +731,15 @@ export declare const osdManagerCapability: {
                         deviceId: z.ZodNumber;
                         states: z.ZodArray<z.ZodString>;
                     }, z.core.$strip>>;
+                    scene: z.ZodOptional<z.ZodObject<{
+                        sceneId: z.ZodString;
+                        deviceId: z.ZodOptional<z.ZodNumber>;
+                        requiredState: z.ZodEnum<{
+                            matched: "matched";
+                            diverged: "diverged";
+                        }>;
+                        latched: z.ZodOptional<z.ZodBoolean>;
+                    }, z.core.$strip>>;
                     devices: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
                     classes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     classesExclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -852,6 +889,15 @@ export declare const osdManagerCapability: {
                             deviceId: z.ZodNumber;
                             states: z.ZodArray<z.ZodString>;
                         }, z.core.$strip>>;
+                        scene: z.ZodOptional<z.ZodObject<{
+                            sceneId: z.ZodString;
+                            deviceId: z.ZodOptional<z.ZodNumber>;
+                            requiredState: z.ZodEnum<{
+                                matched: "matched";
+                                diverged: "diverged";
+                            }>;
+                            latched: z.ZodOptional<z.ZodBoolean>;
+                        }, z.core.$strip>>;
                         devices: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
                         classes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                         classesExclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -1033,6 +1079,15 @@ export declare const osdManagerCapability: {
                         deviceId: z.ZodNumber;
                         states: z.ZodArray<z.ZodString>;
                     }, z.core.$strip>>;
+                    scene: z.ZodOptional<z.ZodObject<{
+                        sceneId: z.ZodString;
+                        deviceId: z.ZodOptional<z.ZodNumber>;
+                        requiredState: z.ZodEnum<{
+                            matched: "matched";
+                            diverged: "diverged";
+                        }>;
+                        latched: z.ZodOptional<z.ZodBoolean>;
+                    }, z.core.$strip>>;
                     devices: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
                     classes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     classesExclude: z.ZodOptional<z.ZodArray<z.ZodString>>;

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

@@ -9,10 +9,22 @@ import { type InferNativeProvider } from './capability-definition.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' | 'ir' (the two variants the operator
  *  captures) plus 'night' | 'dawn' | 'dusk' from the resolver's sun-times band.
@@ -317,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;

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, };

package/dist/generated/addon-api.d.ts

@@ -3354,6 +3354,13 @@ export type AppRouter = TrpcCoreRouter<{
             output: z.infer<typeof llmCapability.methods.generateVision.output>;
             meta: object;
         }>;
+        cancel: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof llmCapability.methods.cancel.input>;
+            output: z.infer<typeof llmCapability.methods.cancel.output>;
+            meta: object;
+        }>;
         listProfileKinds: TRPCQueryProcedure<{
             input: {
                 [x: string]: unknown;
@@ -7494,6 +7501,25 @@ export type AppRouter = TrpcCoreRouter<{
             output: z.infer<typeof systemCapability.methods.forceRetentionCleanup.output>;
             meta: object;
         }>;
+        getSiteLocation: TRPCQueryProcedure<{
+            input: {
+                nodeId?: string | undefined;
+            } | undefined;
+            output: z.infer<typeof systemCapability.methods.getSiteLocation.output>;
+            meta: object;
+        }>;
+        setSiteLocation: TRPCMutationProcedure<{
+            input: z.input<typeof systemCapability.methods.setSiteLocation.input>;
+            output: z.infer<typeof systemCapability.methods.setSiteLocation.output>;
+            meta: object;
+        }>;
+        detectSiteLocation: TRPCMutationProcedure<{
+            input: {
+                nodeId?: string | undefined;
+            } | undefined;
+            output: z.infer<typeof systemCapability.methods.detectSiteLocation.output>;
+            meta: object;
+        }>;
     }>>;
     tamper: TRPCBuiltRouter<{
         ctx: TrpcContext;

package/dist/generated/method-access-map.d.ts

@@ -6,7 +6,7 @@
  * scope+access check inside `protectedProcedure` (see
  * `server/backend/src/api/trpc/trpc.middleware.ts`).
  *
- * Coverage: 934 method paths across 123 capabilities.
+ * Coverage: 938 method paths across 123 capabilities.
  */
 import type { CapabilityMethodAccess } from '../capabilities/capability-definition.js';
 export interface MethodAccessRecord {