@camstack/types 1.2.111 → 1.2.113

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

@@ -102,6 +102,321 @@ declare const SetSiteLocationInputSchema: z.ZodNullable<z.ZodObject<{
     latitude: z.ZodNumber;
     longitude: z.ZodNumber;
 }, z.core.$strip>>;
+/**
+ * One `(procedure, user-agent, ip, principal)` tuple of the HTTP request
+ * census. `principal` is the DERIVED identity (`apocaliss92 (admin)`,
+ * `scoped:1a2b3c4d (scoped-token)`, `anonymous`) that the tRPC error log
+ * already prints - never a token, never an `Authorization` header.
+ */
+declare const RequestCensusGroupSchema: z.ZodObject<{
+    procedure: z.ZodString;
+    userAgent: z.ZodString;
+    ip: z.ZodString;
+    principal: z.ZodString;
+    calls: z.ZodNumber;
+    perMin: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * A procedure's TOTAL over the window, across every caller.
+ *
+ * This block, not the group list, is what answers "did these calls arrive over
+ * HTTP at all". A total far BELOW what a store-side census counted over the
+ * same window excludes the HTTP plane, which is a result, not a failure.
+ */
+declare const RequestCensusProcedureSchema: z.ZodObject<{
+    procedure: z.ZodString;
+    calls: z.ZodNumber;
+    perMin: z.ZodNumber;
+}, z.core.$strip>;
+/** What one armed window measured. Mirrors `HttpRequestCensus.snapshot()`. */
+declare const RequestCensusSnapshotSchema: z.ZodObject<{
+    armed: z.ZodBoolean;
+    elapsedMs: z.ZodNumber;
+    windowMs: z.ZodNumber;
+    armedUntilMs: z.ZodNumber;
+    httpRequests: z.ZodNumber;
+    batchedRequests: z.ZodNumber;
+    procedureCalls: z.ZodNumber;
+    wsConnections: z.ZodNumber;
+    distinctGroups: z.ZodNumber;
+    unattributedCalls: z.ZodNumber;
+    procedures: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        procedure: z.ZodString;
+        calls: z.ZodNumber;
+        perMin: z.ZodNumber;
+    }, z.core.$strip>>>;
+    groups: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        procedure: z.ZodString;
+        userAgent: z.ZodString;
+        ip: z.ZodString;
+        principal: z.ZodString;
+        calls: z.ZodNumber;
+        perMin: z.ZodNumber;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/**
+ * The census as an operator sees it.
+ *
+ * `persisted` is the honest answer to "will this survive the restart I am
+ * about to do": the arm deadline is written to `system-settings` so a window
+ * armed now can measure the NEXT boot, and a write that failed must not look
+ * like one that succeeded.
+ */
+declare const RequestCensusStatusSchema: z.ZodObject<{
+    armed: z.ZodBoolean;
+    elapsedMs: z.ZodNumber;
+    windowMs: z.ZodNumber;
+    armedUntilMs: z.ZodNumber;
+    httpRequests: z.ZodNumber;
+    batchedRequests: z.ZodNumber;
+    procedureCalls: z.ZodNumber;
+    wsConnections: z.ZodNumber;
+    distinctGroups: z.ZodNumber;
+    unattributedCalls: z.ZodNumber;
+    procedures: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        procedure: z.ZodString;
+        calls: z.ZodNumber;
+        perMin: z.ZodNumber;
+    }, z.core.$strip>>>;
+    groups: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        procedure: z.ZodString;
+        userAgent: z.ZodString;
+        ip: z.ZodString;
+        principal: z.ZodString;
+        calls: z.ZodNumber;
+        perMin: z.ZodNumber;
+    }, z.core.$strip>>>;
+    persisted: z.ZodBoolean;
+}, z.core.$strip>;
+/** Severity vocabulary. Mirrors `LogLevel` in `interfaces/logging.ts`. */
+declare const LogLevelSchema: z.ZodEnum<{
+    error: "error";
+    debug: "debug";
+    info: "info";
+    warn: "warn";
+}>;
+/**
+ * The diagnostics that can be ARMED for a window. Exactly one today.
+ *
+ * A diagnostic is anything whose cost is only worth paying while a question is
+ * open. It never persists as a boolean: see {@link DiagnosticWindowSchema}.
+ */
+declare const DiagnosticIdSchema: z.ZodEnum<{
+    "request-census": "request-census";
+}>;
+/**
+ * The layers of the level hierarchy, general → specific. The most specific
+ * layer that carries an explicit value wins.
+ *
+ * `component` is DECLARED and not yet resolvable: the per-component channels
+ * are a later slice of the same plan, and a `levelSource` enum that has to
+ * grow later would force every consumer of this document to change with it.
+ * Nothing returns `component` today.
+ */
+declare const LoggingScopeKindSchema: z.ZodEnum<{
+    node: "node";
+    cluster: "cluster";
+    component: "component";
+}>;
+/** Where an effective level came from. `default` = nothing is set anywhere. */
+declare const LoggingLevelSourceSchema: z.ZodEnum<{
+    default: "default";
+    node: "node";
+    cluster: "cluster";
+    component: "component";
+}>;
+/**
+ * One layer of the hierarchy as it actually STANDS.
+ *
+ * `level: null` is the whole reason this array is returned: it is the
+ * difference between "this node is at `info` because I decided it" and
+ * "...because it inherits". An operator who clears an override believing they
+ * are clearing an inherited value has been handed the same defect as the two
+ * contradicting knobs this document exists to remove, moved one floor up.
+ */
+declare const LoggingLevelLayerSchema: z.ZodObject<{
+    scope: z.ZodEnum<{
+        node: "node";
+        cluster: "cluster";
+        component: "component";
+    }>;
+    nodeId: z.ZodNullable<z.ZodString>;
+    level: z.ZodNullable<z.ZodEnum<{
+        error: "error";
+        debug: "debug";
+        info: "info";
+        warn: "warn";
+    }>>;
+}, z.core.$strip>;
+/** What a line is judged against, and WHICH layer decided it. */
+declare const LoggingEffectiveSchema: z.ZodObject<{
+    level: z.ZodEnum<{
+        error: "error";
+        debug: "debug";
+        info: "info";
+        warn: "warn";
+    }>;
+    levelSource: z.ZodEnum<{
+        default: "default";
+        node: "node";
+        cluster: "cluster";
+        component: "component";
+    }>;
+}, z.core.$strip>;
+/** Every layer, general → specific. Never collapsed into the effective value. */
+declare const LoggingExplicitSchema: z.ZodObject<{
+    layers: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        scope: z.ZodEnum<{
+            node: "node";
+            cluster: "cluster";
+            component: "component";
+        }>;
+        nodeId: z.ZodNullable<z.ZodString>;
+        level: z.ZodNullable<z.ZodEnum<{
+            error: "error";
+            debug: "debug";
+            info: "info";
+            warn: "warn";
+        }>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/**
+ * An armed diagnostic, with its DEADLINE.
+ *
+ * The shape of ADR-0244: what is stored is a deadline and never a flag, so a
+ * diagnostic somebody forgot expires by itself, and a boot-window measurement
+ * survives the restart it exists to measure. `remainingMs` is 0 whenever
+ * `armed` is false — a window is never reported as slightly expired.
+ */
+declare const DiagnosticWindowSchema: z.ZodObject<{
+    id: z.ZodEnum<{
+        "request-census": "request-census";
+    }>;
+    armed: z.ZodBoolean;
+    armedUntilMs: z.ZodNumber;
+    remainingMs: z.ZodNumber;
+    persisted: z.ZodBoolean;
+}, z.core.$strip>;
+/**
+ * `armMs: 0` DISARMS. Any positive value arms for that long, clamped by the
+ * server — there is no maximum here on purpose: a bound repeated in a schema
+ * is a second knob that disagrees with the first the day one of them moves.
+ */
+declare const DiagnosticWindowPatchSchema: z.ZodObject<{
+    id: z.ZodEnum<{
+        "request-census": "request-census";
+    }>;
+    armMs: z.ZodNumber;
+    reportEveryMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * A PATCH, and patches MERGE.
+ *
+ * A field absent from the patch is left exactly as it was — arming a
+ * diagnostic never resets a level, and setting a level never disarms a window.
+ * The provider must not reconstruct the document as `{ ...snapshot, ...patch }`:
+ * `setAll` already merges, and rebuilding the object is how an absent field
+ * turns into an erased one.
+ */
+declare const LoggingSettingsPatchSchema: z.ZodObject<{
+    level: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        error: "error";
+        debug: "debug";
+        info: "info";
+        warn: "warn";
+    }>>>;
+    diagnostics: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        id: z.ZodEnum<{
+            "request-census": "request-census";
+        }>;
+        armMs: z.ZodNumber;
+        reportEveryMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>>;
+}, z.core.$strip>;
+/**
+ * Which LAYER of the hierarchy is addressed. Absent = the cluster layer.
+ *
+ * Deliberately NOT called `nodeId`: that key is reserved on every cap method
+ * input — the generated router strips it and uses it to resolve the PROVIDER
+ * on that node (`resolveProvider(cap, nodeId, …)`). A document about
+ * `agent-1` addressed as `nodeId` would be forwarded to agent-1 and answered
+ * by an agent that holds no cluster document at all. The hub is the single
+ * authority over the whole hierarchy and answers for every layer, so the
+ * layer selector needs a name the transport does not already own.
+ */
+declare const GetLoggingSettingsInputSchema: z.ZodObject<{
+    scopeNodeId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const SetLoggingSettingsInputSchema: z.ZodObject<{
+    scopeNodeId: z.ZodOptional<z.ZodString>;
+    patch: z.ZodObject<{
+        level: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            error: "error";
+            debug: "debug";
+            info: "info";
+            warn: "warn";
+        }>>>;
+        diagnostics: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+            id: z.ZodEnum<{
+                "request-census": "request-census";
+            }>;
+            armMs: z.ZodNumber;
+            reportEveryMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * The whole document, as read and as returned after every write.
+ *
+ * `persisted: false` means the settings store could not be read or written.
+ * The in-memory mirror still governs behaviour and is unchanged by the
+ * failure — a read that fails neither switches a level nor disarms a window
+ * (D49) — but the operator is told that what they are looking at would not
+ * survive a restart.
+ */
+declare const LoggingSettingsStateSchema: z.ZodObject<{
+    scopeNodeId: z.ZodNullable<z.ZodString>;
+    effective: z.ZodObject<{
+        level: z.ZodEnum<{
+            error: "error";
+            debug: "debug";
+            info: "info";
+            warn: "warn";
+        }>;
+        levelSource: z.ZodEnum<{
+            default: "default";
+            node: "node";
+            cluster: "cluster";
+            component: "component";
+        }>;
+    }, z.core.$strip>;
+    explicit: z.ZodObject<{
+        layers: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+            scope: z.ZodEnum<{
+                node: "node";
+                cluster: "cluster";
+                component: "component";
+            }>;
+            nodeId: z.ZodNullable<z.ZodString>;
+            level: z.ZodNullable<z.ZodEnum<{
+                error: "error";
+                debug: "debug";
+                info: "info";
+                warn: "warn";
+            }>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>;
+    activeWindows: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        id: z.ZodEnum<{
+            "request-census": "request-census";
+        }>;
+        armed: z.ZodBoolean;
+        armedUntilMs: z.ZodNumber;
+        remainingMs: z.ZodNumber;
+        persisted: z.ZodBoolean;
+    }, z.core.$strip>>>;
+    persisted: z.ZodBoolean;
+}, z.core.$strip>;
 export declare const systemCapability: {
     readonly name: "system";
     readonly scope: "system";
@@ -204,6 +519,163 @@ export declare const systemCapability: {
             derivationAttemptedAt: z.ZodNullable<z.ZodNumber>;
             derivationError: z.ZodNullable<z.ZodString>;
         }, z.core.$strip>, "mutation">;
+        /**
+         * Read the HTTP request census - which caller, from which address, with
+         * which user-agent, invoked which tRPC procedure, and how often.
+         *
+         * Reading NEVER re-arms: re-arming clears the counts, which would throw
+         * away exactly the numbers being asked for. A closed window may be read as
+         * many times as the operator likes and always describes the same window.
+         *
+         * Admin-only: the rows carry source addresses and principal names.
+         */
+        readonly getRequestCensus: import("./capability-definition.js").CapabilityMethodSchema<z.ZodVoid, z.ZodObject<{
+            armed: z.ZodBoolean;
+            elapsedMs: z.ZodNumber;
+            windowMs: z.ZodNumber;
+            armedUntilMs: z.ZodNumber;
+            httpRequests: z.ZodNumber;
+            batchedRequests: z.ZodNumber;
+            procedureCalls: z.ZodNumber;
+            wsConnections: z.ZodNumber;
+            distinctGroups: z.ZodNumber;
+            unattributedCalls: z.ZodNumber;
+            procedures: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+                procedure: z.ZodString;
+                calls: z.ZodNumber;
+                perMin: z.ZodNumber;
+            }, z.core.$strip>>>;
+            groups: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+                procedure: z.ZodString;
+                userAgent: z.ZodString;
+                ip: z.ZodString;
+                principal: z.ZodString;
+                calls: z.ZodNumber;
+                perMin: z.ZodNumber;
+            }, z.core.$strip>>>;
+            persisted: z.ZodBoolean;
+        }, z.core.$strip>, import("./capability-definition.js").CapabilityMethodKind>;
+        /**
+         * The logging settings document — levels and armed diagnostics — resolved
+         * for `nodeId`, or for the cluster when `nodeId` is absent.
+         *
+         * Returns BOTH `effective` and `explicit`. See
+         * {@link LoggingLevelLayerSchema} for why collapsing them is the defect.
+         */
+        readonly getLoggingSettings: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            scopeNodeId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            scopeNodeId: z.ZodNullable<z.ZodString>;
+            effective: z.ZodObject<{
+                level: z.ZodEnum<{
+                    error: "error";
+                    debug: "debug";
+                    info: "info";
+                    warn: "warn";
+                }>;
+                levelSource: z.ZodEnum<{
+                    default: "default";
+                    node: "node";
+                    cluster: "cluster";
+                    component: "component";
+                }>;
+            }, z.core.$strip>;
+            explicit: z.ZodObject<{
+                layers: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+                    scope: z.ZodEnum<{
+                        node: "node";
+                        cluster: "cluster";
+                        component: "component";
+                    }>;
+                    nodeId: z.ZodNullable<z.ZodString>;
+                    level: z.ZodNullable<z.ZodEnum<{
+                        error: "error";
+                        debug: "debug";
+                        info: "info";
+                        warn: "warn";
+                    }>>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>;
+            activeWindows: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+                id: z.ZodEnum<{
+                    "request-census": "request-census";
+                }>;
+                armed: z.ZodBoolean;
+                armedUntilMs: z.ZodNumber;
+                remainingMs: z.ZodNumber;
+                persisted: z.ZodBoolean;
+            }, z.core.$strip>>>;
+            persisted: z.ZodBoolean;
+        }, z.core.$strip>, import("./capability-definition.js").CapabilityMethodKind>;
+        /**
+         * Write the logging settings document. The ONLY write authority over log
+         * levels and diagnostic windows — arming the request census went through
+         * `system.setRequestCensus` until 2026-08-27 and no longer does, because
+         * two writes that disagree about the same window is exactly the defect
+         * this document exists to remove (D245).
+         *
+         * The patch MERGES: see {@link LoggingSettingsPatchSchema}.
+         */
+        readonly setLoggingSettings: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            scopeNodeId: z.ZodOptional<z.ZodString>;
+            patch: z.ZodObject<{
+                level: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                    error: "error";
+                    debug: "debug";
+                    info: "info";
+                    warn: "warn";
+                }>>>;
+                diagnostics: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+                    id: z.ZodEnum<{
+                        "request-census": "request-census";
+                    }>;
+                    armMs: z.ZodNumber;
+                    reportEveryMs: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>>>>;
+            }, z.core.$strip>;
+        }, z.core.$strip>, z.ZodObject<{
+            scopeNodeId: z.ZodNullable<z.ZodString>;
+            effective: z.ZodObject<{
+                level: z.ZodEnum<{
+                    error: "error";
+                    debug: "debug";
+                    info: "info";
+                    warn: "warn";
+                }>;
+                levelSource: z.ZodEnum<{
+                    default: "default";
+                    node: "node";
+                    cluster: "cluster";
+                    component: "component";
+                }>;
+            }, z.core.$strip>;
+            explicit: z.ZodObject<{
+                layers: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+                    scope: z.ZodEnum<{
+                        node: "node";
+                        cluster: "cluster";
+                        component: "component";
+                    }>;
+                    nodeId: z.ZodNullable<z.ZodString>;
+                    level: z.ZodNullable<z.ZodEnum<{
+                        error: "error";
+                        debug: "debug";
+                        info: "info";
+                        warn: "warn";
+                    }>>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>;
+            activeWindows: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+                id: z.ZodEnum<{
+                    "request-census": "request-census";
+                }>;
+                armed: z.ZodBoolean;
+                armedUntilMs: z.ZodNumber;
+                remainingMs: z.ZodNumber;
+                persisted: z.ZodBoolean;
+            }, z.core.$strip>>>;
+            persisted: z.ZodBoolean;
+        }, z.core.$strip>, "mutation">;
     };
     /** BIG PLAN 2: declarative mount hint — read by `@camstack/system` `buildCapRouters`. */
     readonly mount: {
@@ -211,8 +683,24 @@ export declare const systemCapability: {
     };
 };
 export type ISystemProvider = InferProvider<typeof systemCapability>;
+export type RequestCensusGroup = z.infer<typeof RequestCensusGroupSchema>;
+export type RequestCensusProcedure = z.infer<typeof RequestCensusProcedureSchema>;
+export type RequestCensusSnapshot = z.infer<typeof RequestCensusSnapshotSchema>;
+export type RequestCensusStatus = z.infer<typeof RequestCensusStatusSchema>;
+export type DiagnosticId = z.infer<typeof DiagnosticIdSchema>;
+export type DiagnosticWindow = z.infer<typeof DiagnosticWindowSchema>;
+export type DiagnosticWindowPatch = z.infer<typeof DiagnosticWindowPatchSchema>;
+export type GetLoggingSettingsInput = z.infer<typeof GetLoggingSettingsInputSchema>;
+export type LoggingEffective = z.infer<typeof LoggingEffectiveSchema>;
+export type LoggingExplicit = z.infer<typeof LoggingExplicitSchema>;
+export type LoggingLevelLayer = z.infer<typeof LoggingLevelLayerSchema>;
+export type LoggingLevelSource = z.infer<typeof LoggingLevelSourceSchema>;
+export type LoggingScopeKind = z.infer<typeof LoggingScopeKindSchema>;
+export type LoggingSettingsPatch = z.infer<typeof LoggingSettingsPatchSchema>;
+export type LoggingSettingsState = z.infer<typeof LoggingSettingsStateSchema>;
+export type SetLoggingSettingsInput = z.infer<typeof SetLoggingSettingsInputSchema>;
 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, };
+export { DiagnosticIdSchema, DiagnosticWindowPatchSchema, DiagnosticWindowSchema, FeatureManifestSchema, GetLoggingSettingsInputSchema, HealthStatusSchema, LogLevelSchema, LoggingEffectiveSchema, LoggingExplicitSchema, LoggingLevelLayerSchema, LoggingLevelSourceSchema, LoggingScopeKindSchema, LoggingSettingsPatchSchema, LoggingSettingsStateSchema, NetworkAddressSchema, RequestCensusGroupSchema, RequestCensusProcedureSchema, RequestCensusSnapshotSchema, RequestCensusStatusSchema, SetLoggingSettingsInputSchema, SetSiteLocationInputSchema, SiteLocationSchema, SiteLocationSourceSchema, SiteLocationStatusSchema, };

package/dist/catalogs/index.d.ts

@@ -1,3 +1,4 @@
 export * from './coco-classmap.js';
+export * from './sensor-active-state.js';
 export * from './audio-classmap.js';
 export * from './event-taxonomy.js';

package/dist/catalogs/sensor-active-state.d.ts

@@ -0,0 +1,130 @@
+/**
+ * LA tabella "quale booleano di questo tipo di device conta come ALTO", e il
+ * valutatore puro del suo FRONTE.
+ *
+ * Viveva dentro il builtin virtual-doorbell
+ * (`@camstack/system` — `builtins/doorbell/trigger-engine.ts`) e i suoi
+ * predicati erano privati al modulo. Il recorder ne ha bisogno per il trigger
+ * `RecordingTriggers.sensorDeviceIds`: copiarla avrebbe creato la SECONDA
+ * tabella, che diverge alla prima cap aggiunta e il cui sintomo — "il sensore
+ * fa suonare il campanello ma non registra" — è esattamente D62. Quindi si
+ * SPOSTA qui e il doorbell la ri-esporta.
+ *
+ * ⚠ NON è `DEVICE_STATE_READERS` (`catalogs/device-state-vocabulary.ts`), e le
+ * due non vanno unificate: quella risponde a "qual è la PAROLA di stato per una
+ * regola" (e include `presence`, `cover`, `alarm-panel`), questa a "qual è il
+ * booleano il cui FRONTE conta". Vocabolari deliberatamente diversi.
+ */
+/**
+ * Known binary / switch source caps → the boolean slice field whose
+ * false→true rise counts as ACTIVE. Every entry is "fire on active".
+ * Sensors whose "active" reading is not a plain boolean (presence's string
+ * state, connectivity's connected flag) are deliberately excluded — a
+ * reconnect is not a doorbell press, and it is not a recording either.
+ */
+export declare const SOURCE_CAP_ACTIVE_FIELD: Readonly<Record<string, string>>;
+/**
+ * The same caps → the slice field carrying the ms-epoch timestamp of the
+ * last transition. Every source cap MUST appear here (guarded by a spec):
+ * without a transition timestamp the evaluator cannot tell a genuine rise
+ * from a boot-time hydration when the FIRST slice it ever sees is already
+ * active, and errs towards silence — swallowing the rise.
+ *
+ * These timestamps are UPSTREAM ones, not ingest ones: the Home Assistant
+ * provider derives them from `state.last_changed`, so they survive our own
+ * restarts and correctly read as "hours ago" for a state that has been
+ * active for hours. `motion` names its rise timestamp `lastDetectedAt`.
+ */
+export declare const SOURCE_CAP_CHANGED_AT_FIELD: Readonly<Record<string, string>>;
+/** Cap names whose presence in a device's bindings qualify it as a source. */
+export declare const SOURCE_CAPS: readonly string[];
+/**
+ * Device `type` values (from `DeviceType`) that can host a binary/switch
+ * source cap. Used by the camera's `device-multiselect` picker as the
+ * CLIENT-SIDE filter, alongside `SOURCE_CAPS`.
+ *
+ * Why types and not caps alone: the shared picker filters
+ * `deviceManager.listAll` rows client-side, and those rows carry only the
+ * device's advertised `features` — NOT its registered cap list. On the live
+ * cluster binary sensors and switches advertise EMPTY features (features
+ * mirror only a handful of caps like `motion-trigger`), so a caps-only
+ * filter matched against `features` would list nothing (the very bug this
+ * replaced, which relied on the now-empty `getAllBindings`). Matching by
+ * `type` is the reliable client-side signal; the union with `SOURCE_CAPS`
+ * still captures any device that DOES advertise a source-cap feature.
+ * `sensor` covers contact/motion/flood/gas/smoke/CO/vibration/tamper,
+ * `switch` covers switches, `control` covers generic binary actuators.
+ */
+export declare const SOURCE_DEVICE_TYPES: readonly string[];
+/** True when a cap is a recognised binary/switch source. */
+export declare function isSourceCap(capName: string): boolean;
+/** Extract the "active" boolean a source cap's slice carries, or null when
+ *  the cap is unknown or the field is missing / non-boolean. */
+export declare function sliceActiveValue(capName: string, slice: Readonly<Record<string, unknown>>): boolean | null;
+/** Ms-epoch transition timestamp a source cap's slice carries, or null when
+ *  it is absent, non-numeric or the zero "never observed" sentinel. */
+export declare function sliceChangedAt(capName: string, slice: Readonly<Record<string, unknown>>): number | null;
+/**
+ * Perché una slice non ha portato un fronte alto. Stesso vocabolario che il
+ * virtual-doorbell riporta dal 2026-08-05: UN enum, così "perché non è scattato
+ * niente" ha una risposta sola, chiunque lo chieda.
+ */
+export type SensorEdgeIgnoreReason = 
+/** Not a recognised binary/switch source cap. */
+'unknown-cap'
+/** Recognised cap, but its active field is missing or not a boolean. */
+ | 'non-boolean-value'
+/** First sighting, INACTIVE — nothing can have been lost. */
+ | 'baseline-seeded-inactive'
+/** First sighting, ALREADY ACTIVE, and we could not prove it is a fresh
+ *  transition. A genuine rise MAY have been swallowed here. */
+ | 'baseline-seeded-stale-active'
+/** Re-emission carrying the same binary value. */
+ | 'no-change'
+/** The falling edge — switch-off / contact-close never fires. */
+ | 'falling-edge';
+export interface SensorEdgeInput {
+    readonly capName: string;
+    readonly slice: Readonly<Record<string, unknown>>;
+    /** Ultimo booleano osservato per questa `(device, cap)`; `undefined` = mai vista. */
+    readonly prior: boolean | undefined;
+    /** Quando l'OSSERVATORE ha iniziato a guardare — il pavimento per una prima
+     *  osservazione già attiva. Ogni osservatore ha il suo. */
+    readonly startedAtMs: number;
+    readonly nowMs: number;
+    readonly firstSightingFreshnessMs: number;
+}
+/**
+ * `value` è restituito su ogni cammino in cui la slice PORTAVA un booleano,
+ * anche quando non c'è fronte: il chiamante aggiorna la sua memoria con quello
+ * e non rilegge la slice. Su `unknown-cap` / `non-boolean-value` è `null` e la
+ * memoria non va toccata.
+ */
+export type SensorEdgeVerdict = {
+    readonly edge: 'rising';
+    readonly value: true;
+} | {
+    readonly edge: 'none';
+    readonly value: boolean | null;
+    readonly reason: SensorEdgeIgnoreReason;
+};
+/**
+ * How recent a source's own transition timestamp must be for a FIRST
+ * sighting that is already active to count as a genuine rise rather than a
+ * hydration of long-standing state.
+ */
+export declare const DEFAULT_FIRST_SIGHTING_FRESHNESS_MS = 30000;
+/**
+ * IL fronte. Puro: nessun orologio proprio, nessuna memoria — il chiamante
+ * porta `prior`, `nowMs` e il proprio `startedAtMs`.
+ *
+ * Il caso della PRIMA slice già attiva è trattato esplicitamente e vale come
+ * fronte solo se il timestamp UPSTREAM della transizione è posteriore a
+ * `startedAtMs` **e** entro `firstSightingFreshnessMs`. Entrambe le metà
+ * servono: la sola freschezza scatterebbe su un'idratazione al boot di uno
+ * stato flippato pochi secondi prima del riavvio, e il solo "dopo che abbiamo
+ * iniziato" scatterebbe, su un processo di lunga vita, per una sorgente
+ * adottata oggi il cui stato è cambiato ieri. Il caso ambiguo ERRA VERSO IL
+ * SILENZIO e lo dichiara (`baseline-seeded-stale-active`).
+ */
+export declare function evaluateSensorEdge(input: SensorEdgeInput): SensorEdgeVerdict;