@camstack/types 1.2.451 → 1.2.453

package/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.453] - 2026-10-30
+
+### Changed
+
+- Terminal instances report nodeInCluster and updateInstance accepts targetNodeId to re-point an instance.
+- Notification targets pick a broker and list their options inside the add/edit form; the page-wide Find devices dialog is gone
+
+## [1.2.452] - 2026-10-30
+
+### Added
+
+- Discovery modes: a device provider can declare how it is found on the network and classify the hits the scan engine returns; candidates can say they set up an integration or sit behind a gateway
+
+### Changed
+
+- An editable-array config field can now hold keychain secrets per row
+- A discovered child device can name the gateway it sits behind (parentStableId)
+- The vendor login proxy can keep a sign-in's vendor cookies server-side (serverCookieJar)
+- Hub: a stale-data audit finds record kinds and settings keys an addon no longer declares, read-only, with an operator-triggered cleanup
+- Automations are one 'when' tree: an event starts a run, states must hold at that instant, and a detection is a macro class with an optional label (dog, a known face, a plate); stored recipes convert on read, and step traces now show the arguments they sent.
+
 ## [1.2.451] - 2026-10-30
 
 ### Changed

package/dist/addon/base-addon.d.ts

@@ -3,6 +3,17 @@ import type { AddonContext, AddonInitResult, CapabilitiesAccess, ProviderRegistr
 import type { ConfigField, ConfigSection, ConfigUISchema, ConfigUISchemaWithValues } from '../interfaces/config-ui.js';
 import { type DurableState } from './durable-state.js';
 import { type UnresolvedSecret } from './secret-settings-view.js';
+export interface DeclaredSettingsKeys {
+    readonly keys: readonly string[];
+}
+export interface UnsetSettingsKeysOutcome {
+    readonly removed: readonly string[];
+    readonly refused: ReadonlyArray<{
+        readonly key: string;
+        readonly reason: string;
+    }>;
+    readonly secretsCleared: number;
+}
 export type { CapabilitiesAccess };
 /**
  * Utility type that constrains a ConfigField's `key` to only accept
@@ -427,6 +438,22 @@ export declare abstract class BaseAddon<TConfig extends object = Record<string,
      * a warning and falls back rather than crashing boot.
      */
     protected state<T>(key: string, schema: ZodType<T>, fallback: T): DurableState<T>;
+    /** Durable-state keys this process registered through {@link state}. */
+    private readonly _declaredStateKeys;
+    /**
+     * Stale-data audit: every global-settings key this addon still declares —
+     * constructor defaults, settings-schema fields (layout containers included),
+     * durable-state keys and the root of each `secretStatePaths` entry. Answered
+     * here, in the addon's own process, so the hub keeps no copy of it.
+     */
+    getDeclaredSettingsKeys(): Promise<DeclaredSettingsKeys>;
+    private declaredKeySet;
+    /**
+     * Stale-data audit: remove stored global-settings keys the addon no longer
+     * declares, and clear the keychain values their markers held — except a value
+     * a surviving key still points at. A declared or absent key is refused.
+     */
+    unsetStoredSettingsKeys(keys: readonly string[]): Promise<UnsetSettingsKeysOutcome>;
     /** Per-device variant of {@link state}, backed by the per-device store. */
     protected deviceState<T>(deviceId: number, key: string, schema: ZodType<T>, fallback: T): DurableState<T>;
     /** The addon store's secret tree: schema fields by TYPE, plus `secretStatePaths`. */

package/dist/addon.js

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sleep = require("./sleep-BSPhInRm.js");
+const require_sleep = require("./sleep-CewR0zRz.js");
 const require_event_category = require("./event-category-E17zaHjN.js");
 const require_err_msg = require("./err-msg-DkPZXb-g.js");
 //#region src/generated/cap-input-defaults.ts
@@ -367,7 +367,7 @@ function materialise(defaults) {
 * barrel (`ALL_CAPABILITY_DEFINITIONS`), which would cost ~144MB RSS per
 * forked runner. See docs/decisions/adr-0028.md.
 *
-* Coverage: 29 collection caps, 49 array methods.
+* Coverage: 29 collection caps, 51 array methods.
 */
 var COLLECTION_ARRAY_METHODS = Object.freeze({
 	"action-source": ["listActions"],
@@ -385,7 +385,12 @@ var COLLECTION_ARRAY_METHODS = Object.freeze({
 		"listSupportedEntityKinds"
 	],
 	"device-extension": ["listSlots", "listSources"],
-	"device-provider": ["discoverDevices", "getDevices"],
+	"device-provider": [
+		"classifyDiscoveryHits",
+		"discoverDevices",
+		"getDevices",
+		"getDiscoveryModes"
+	],
 	"device-removal-hook": ["listDeviceData"],
 	"failure-contribution": ["list"],
 	"llm": [

package/dist/addon.mjs

@@ -1,4 +1,4 @@
-import { $n as RECORD_SECRET_COLLECTION_PREFIX, $r as SECRET_CLEAR, $t as entryBody, A as HF_REPO, An as RECORDS_ERROR_CODES, B as DEVICE_CHILDREN_BATCH_MAX, Bn as asRecordsError, C as addonSliceHandleApi, Cn as BatchTooLargeError, Dn as InvalidRecordError, En as ForeignSecretMarkerError, Fn as RecordsError, Fr as formatSecretScope, G as describeCustomActions, Gn as RECORD_DATABASES, H as withoutCallerStamp, Hn as RECORD_BATCH_MAX, Hr as createEvent, I as deviceOpsCapability, In as RevConflictError, Ir as globalSecretScope, Jn as RECORD_ID_MAX_LENGTH, Kn as RECORD_DEFAULT_MAX_DATA_BYTES, L as viewerUiCapability, Ln as TransactRefusedError, Lr as isSecretRef, M as CAP_ADVANCE_FIELDS, Mn as RecordSecretUnavailableError, Mr as SECRET_REF_SCHEME, Nn as RecordTooLargeError, Nr as arrayItemFieldPath, On as NoCallerError, P as CAP_STATE_LEAVES, Pn as RecordUniqueViolationError, Pr as buildSecretRef, Q as readNodePin, Qn as RECORD_QUERY_MAX, Qt as defineEntryKind, R as PipelineRunResultBridge, Rn as UnindexedFilterError, Rr as normalizeSecretOwner, Sn as isZodSecret, Sr as normalizeAddonInitResult, Tn as FilterRequiredError, U as customAction, Un as RECORD_BATCH_MAX_BYTES, Ur as emitReadiness, V as CALLER_STAMPED_CAPABILITIES, Vn as recordsErrorFromMessage, W as defineCustomActions, Wn as RECORD_CLASSES, Xn as RECORD_MAX_INDEXES, Y as addonPagesSourceCapability, Yn as RECORD_MAX_DATA_BYTES, Z as nodePin, Zn as RECORD_MAX_INDEX_FIELDS, Zt as makeInMemoryRecords, _ as readErrorI18n, _n as recordSecretCollection, _r as DATAPLANE_SECRET_HEADER, ai as makeSecretMarker, an as RecordKindDeclarationSchema, ar as MIN_SCRUBBED_LENGTH, b as isDeviceScopedCap, br as BaseAddon, c as asString, cn as StoredRecordKindDeclarationSchema, cr as knownSecretCount, d as parseJsonUnknown, dn as defineRecordKinds, dr as shortSecretRefHash, ei as classifySecretWrite, en as createRecordsAccess, er as RECORD_SETTINGS_MAX_ROWS, f as hfModelUrl, fn as REMOVE_LEAF, fr as PEER_BYTES_CHUNK_BYTES, g as ErrorI18nPayloadSchema, gn as recordArrayItemPath, gt as ReadinessTimeoutError, hn as parseSecretPath, hr as PEER_BYTES_TICKET_TTL_MS, ht as ReadinessRegistry, ii as isSecretMarkerLike, in as RecordIndexSchema, ir as createSecretsAccess, jn as RecordNotFoundError, kn as PlaintextSecretError, ln as assertValidDeclaration, lr as registerKnownSecret, mn as mapSecretLeaves, mr as PEER_BYTES_STALL_MS, mt as MODEL_FORMATS, ni as isSecretFieldView, nn as EntryDescriptorSchema, nr as resolveSecretViewsIn, o as asJsonObject, oi as toSecretFieldView, on as RecordKindNameSchema, or as clearKnownSecrets, p as BOOT_RECOVERY_BACKOFF_MS, pn as collectSecretLeaves, pr as PEER_BYTES_MAX_OUTSTANDING, q as adminUiCapability, qn as RECORD_DELETE_BATCH, r as maskUrlCredentials, ri as isSecretMarker, rn as RecordFieldPathSchema, rr as REVALIDATE_AFTER_MS, sn as RecordRetentionSchema, sr as forgetKnownSecret, st as expandCapMethods, t as sleep, ti as isSecretClear, tn as assertTransactScope, tr as RECORD_SWEEP_INTERVAL_MS, un as declarationsOf, ur as scrubKnownSecrets, vn as recordSecretRef, w as createEventBusSliceSource, wn as DeclarationRefusedError, x as createDeviceProxy, xn as collectZodSecretPaths, y as DEVICE_SCOPED_CAPS, yn as secretArrayPrefixes, yr as DisposerChain, yt as scopeKey, z as PipelineStepInputSchema, zn as UnknownRecordKindError, zr as parseSecretRef } from "./sleep-63gM_1JR.mjs";
+import { $n as RECORD_SECRET_COLLECTION_PREFIX, $r as SECRET_CLEAR, $t as entryBody, A as HF_REPO, An as RECORDS_ERROR_CODES, B as DEVICE_CHILDREN_BATCH_MAX, Bn as asRecordsError, C as addonSliceHandleApi, Cn as BatchTooLargeError, Dn as InvalidRecordError, En as ForeignSecretMarkerError, Fn as RecordsError, Fr as formatSecretScope, G as describeCustomActions, Gn as RECORD_DATABASES, H as withoutCallerStamp, Hn as RECORD_BATCH_MAX, Hr as createEvent, I as deviceOpsCapability, In as RevConflictError, Ir as globalSecretScope, Jn as RECORD_ID_MAX_LENGTH, Kn as RECORD_DEFAULT_MAX_DATA_BYTES, L as viewerUiCapability, Ln as TransactRefusedError, Lr as isSecretRef, M as CAP_ADVANCE_FIELDS, Mn as RecordSecretUnavailableError, Mr as SECRET_REF_SCHEME, Nn as RecordTooLargeError, Nr as arrayItemFieldPath, On as NoCallerError, P as CAP_STATE_LEAVES, Pn as RecordUniqueViolationError, Pr as buildSecretRef, Q as readNodePin, Qn as RECORD_QUERY_MAX, Qt as defineEntryKind, R as PipelineRunResultBridge, Rn as UnindexedFilterError, Rr as normalizeSecretOwner, Sn as isZodSecret, Sr as normalizeAddonInitResult, Tn as FilterRequiredError, U as customAction, Un as RECORD_BATCH_MAX_BYTES, Ur as emitReadiness, V as CALLER_STAMPED_CAPABILITIES, Vn as recordsErrorFromMessage, W as defineCustomActions, Wn as RECORD_CLASSES, Xn as RECORD_MAX_INDEXES, Y as addonPagesSourceCapability, Yn as RECORD_MAX_DATA_BYTES, Z as nodePin, Zn as RECORD_MAX_INDEX_FIELDS, Zt as makeInMemoryRecords, _ as readErrorI18n, _n as recordSecretCollection, _r as DATAPLANE_SECRET_HEADER, ai as makeSecretMarker, an as RecordKindDeclarationSchema, ar as MIN_SCRUBBED_LENGTH, b as isDeviceScopedCap, br as BaseAddon, c as asString, cn as StoredRecordKindDeclarationSchema, cr as knownSecretCount, d as parseJsonUnknown, dn as defineRecordKinds, dr as shortSecretRefHash, ei as classifySecretWrite, en as createRecordsAccess, er as RECORD_SETTINGS_MAX_ROWS, f as hfModelUrl, fn as REMOVE_LEAF, fr as PEER_BYTES_CHUNK_BYTES, g as ErrorI18nPayloadSchema, gn as recordArrayItemPath, gt as ReadinessTimeoutError, hn as parseSecretPath, hr as PEER_BYTES_TICKET_TTL_MS, ht as ReadinessRegistry, ii as isSecretMarkerLike, in as RecordIndexSchema, ir as createSecretsAccess, jn as RecordNotFoundError, kn as PlaintextSecretError, ln as assertValidDeclaration, lr as registerKnownSecret, mn as mapSecretLeaves, mr as PEER_BYTES_STALL_MS, mt as MODEL_FORMATS, ni as isSecretFieldView, nn as EntryDescriptorSchema, nr as resolveSecretViewsIn, o as asJsonObject, oi as toSecretFieldView, on as RecordKindNameSchema, or as clearKnownSecrets, p as BOOT_RECOVERY_BACKOFF_MS, pn as collectSecretLeaves, pr as PEER_BYTES_MAX_OUTSTANDING, q as adminUiCapability, qn as RECORD_DELETE_BATCH, r as maskUrlCredentials, ri as isSecretMarker, rn as RecordFieldPathSchema, rr as REVALIDATE_AFTER_MS, sn as RecordRetentionSchema, sr as forgetKnownSecret, st as expandCapMethods, t as sleep, ti as isSecretClear, tn as assertTransactScope, tr as RECORD_SWEEP_INTERVAL_MS, un as declarationsOf, ur as scrubKnownSecrets, vn as recordSecretRef, w as createEventBusSliceSource, wn as DeclarationRefusedError, x as createDeviceProxy, xn as collectZodSecretPaths, y as DEVICE_SCOPED_CAPS, yn as secretArrayPrefixes, yr as DisposerChain, yt as scopeKey, z as PipelineStepInputSchema, zn as UnknownRecordKindError, zr as parseSecretRef } from "./sleep-CeyhrcOk.mjs";
 import { t as EventCategory } from "./event-category-DmZDPDf_.mjs";
 import { a as DeviceType, t as errMsg } from "./err-msg-BD5buxvT.mjs";
 //#region src/generated/cap-input-defaults.ts
@@ -366,7 +366,7 @@ function materialise(defaults) {
 * barrel (`ALL_CAPABILITY_DEFINITIONS`), which would cost ~144MB RSS per
 * forked runner. See docs/decisions/adr-0028.md.
 *
-* Coverage: 29 collection caps, 49 array methods.
+* Coverage: 29 collection caps, 51 array methods.
 */
 var COLLECTION_ARRAY_METHODS = Object.freeze({
 	"action-source": ["listActions"],
@@ -384,7 +384,12 @@ var COLLECTION_ARRAY_METHODS = Object.freeze({
 		"listSupportedEntityKinds"
 	],
 	"device-extension": ["listSlots", "listSources"],
-	"device-provider": ["discoverDevices", "getDevices"],
+	"device-provider": [
+		"classifyDiscoveryHits",
+		"discoverDevices",
+		"getDevices",
+		"getDiscoveryModes"
+	],
 	"device-removal-hook": ["listDeviceData"],
 	"failure-contribution": ["list"],
 	"llm": [

package/dist/automation/condition-eval.d.ts

@@ -12,7 +12,8 @@
  * ones a short-circuit never reached) with a stable path and a human reason, so
  * the editor can paint each block.
  */
-import type { AutomationCondition } from './recipe.js';
+import { type LegacyCondition } from './legacy-recipe.js';
+import { type AutomationWhen } from './when.js';
 import type { AutomationConditionTraceNode } from './trace.js';
 /** One device cap whose slice the mirror must hold. */
 export type MirrorSource = {
@@ -24,8 +25,10 @@ export type MirrorSource = {
     readonly stableId: string;
     readonly cap: string;
 };
-/** Every (device, cap) a tree reads, deduplicated. */
-export declare function collectMirrorSources(cond: AutomationCondition | undefined): MirrorSource[];
+/** Every (device, cap) a `when` tree's STATE leaves read, deduplicated. */
+export declare function collectWhenMirrorSources(cond: AutomationWhen | undefined): MirrorSource[];
+/** Legacy name, for blocks generated before the single tree: an old condition tree. */
+export declare function collectMirrorSources(cond: LegacyCondition | undefined): MirrorSource[];
 export interface ConditionReader {
     /** `undefined` = unknown. */
     read(deviceId: number, cap: string, fieldPath: string): unknown;
@@ -57,8 +60,20 @@ export declare class ConditionMirror implements ConditionReader {
 }
 export interface ConditionEvaluation {
     readonly pass: boolean;
+    /** A state leaf could not be read (the mirror held nothing for it). A false
+     *  that comes with this is "not known", and a `not` over it is not to be trusted. */
+    readonly unknown: boolean;
     /** Pre-order: a container, then its children. */
     readonly nodes: readonly AutomationConditionTraceNode[];
 }
-/** No condition tree is a pass with no nodes. */
-export declare function evaluateConditionTree(cond: AutomationCondition | undefined, reader: ConditionReader, now: number): ConditionEvaluation;
+/** Options of one evaluation of a `when` tree. */
+export interface WhenEvaluationOptions {
+    /** The path of the event leaf that occurred (`when.0`); absent for a state-only tree. */
+    readonly firedPath?: string;
+    /** The root path (default `when`; the legacy wrapper keeps `conditions`). */
+    readonly rootPath?: string;
+}
+/** Evaluate a `when` tree: the fired event leaf is true, every other event leaf false. */
+export declare function evaluateWhenTree(when: AutomationWhen, reader: ConditionReader, now: number, options?: WhenEvaluationOptions): ConditionEvaluation;
+/** Legacy name, for blocks generated before the single tree. No tree is a pass with no nodes. */
+export declare function evaluateConditionTree(cond: LegacyCondition | undefined, reader: ConditionReader, now: number): ConditionEvaluation;

package/dist/automation/detection-subject.d.ts

@@ -0,0 +1,154 @@
+/**
+ * WHAT a detection-shaped leaf is about: one MACRO class (person, vehicle,
+ * animal, package) plus an OPTIONAL label that narrows it.
+ *
+ * The taxonomy is `COCO_TO_MACRO` (and `CLASS_MAP_MACRO_TARGETS`) — never a
+ * second list. The label that fits depends on the macro class:
+ *
+ *  - `animal`  → a sub-class (`dog`, `cat`, …);
+ *  - `person`  → a known face (an identity of the `face-gallery`);
+ *  - `vehicle` → a plate (its text) or a sub-class (`car`, `truck`, …);
+ *  - `package` → a sub-class.
+ *
+ * `other` exists only so a class the taxonomy does not know (a custom model's
+ * `forklift`) survives the conversion of a stored recipe without widening.
+ *
+ * A label is decided LATE (D683): face recognition and LPR land after the
+ * detection starts. The track-lifecycle `update` event carries the newly
+ * resolved `label` / `plateText`, which is why a leaf with a label fires when
+ * the subject GETS it — not at the first detection.
+ */
+import { z } from 'zod';
+declare const SubClassLabelSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"sub-class">;
+    className: z.ZodString;
+}, z.core.$strip>;
+declare const IdentityLabelSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"identity">;
+    identityId: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>;
+declare const PlateLabelSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"plate">;
+    text: z.ZodString;
+}, z.core.$strip>;
+export type SubClassLabel = z.infer<typeof SubClassLabelSchema>;
+export type IdentityLabel = z.infer<typeof IdentityLabelSchema>;
+export type PlateLabel = z.infer<typeof PlateLabelSchema>;
+export declare const DetectionSubjectSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    macro: z.ZodLiteral<"animal">;
+    label: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"sub-class">;
+        className: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    macro: z.ZodLiteral<"person">;
+    label: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"identity">;
+        identityId: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    macro: z.ZodLiteral<"vehicle">;
+    label: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"sub-class">;
+        className: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"plate">;
+        text: z.ZodString;
+    }, z.core.$strip>], "kind">>;
+}, z.core.$strip>, z.ZodObject<{
+    macro: z.ZodLiteral<"package">;
+    label: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"sub-class">;
+        className: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    macro: z.ZodLiteral<"other">;
+    className: z.ZodString;
+}, z.core.$strip>], "macro">;
+export type DetectionSubject = z.infer<typeof DetectionSubjectSchema>;
+/**
+ * The subject of a PARKED object. The stationary registry's event carries a
+ * class and a zone, no face and no plate — an identity or plate label there
+ * could never match, so the schema refuses it instead of letting it sit dead.
+ */
+export declare const StationarySubjectSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    macro: z.ZodLiteral<"animal">;
+    label: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"sub-class">;
+        className: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    macro: z.ZodLiteral<"person">;
+    label: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"identity">;
+        identityId: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    macro: z.ZodLiteral<"vehicle">;
+    label: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"sub-class">;
+        className: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"plate">;
+        text: z.ZodString;
+    }, z.core.$strip>], "kind">>;
+}, z.core.$strip>, z.ZodObject<{
+    macro: z.ZodLiteral<"package">;
+    label: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"sub-class">;
+        className: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    macro: z.ZodLiteral<"other">;
+    className: z.ZodString;
+}, z.core.$strip>], "macro">;
+/** What the macro-class picker offers, and where a label's choices come from. */
+export type DetectionLabelSource = {
+    readonly kind: 'sub-class';
+} | {
+    readonly kind: 'cap';
+    readonly cap: string;
+    readonly method: string;
+    readonly label: 'identity' | 'plate';
+};
+/**
+ * Where an editor lists the labels of a macro class. Sub-classes come from the
+ * taxonomy (`subClassesOf`); identities and plates come from the galleries'
+ * own methods, so a picker reads the cap and never a copy of it.
+ */
+export declare const DETECTION_LABEL_SOURCES: Readonly<Record<'animal' | 'person' | 'vehicle' | 'package', readonly DetectionLabelSource[]>>;
+/** The raw classes the taxonomy files under a macro class. */
+export declare function subClassesOf(macro: string): readonly string[];
+/**
+ * A stored class string as a subject: a macro name stays a macro; a raw class
+ * the taxonomy files under a macro becomes that macro plus the sub-class label
+ * (`dog` → animal / dog); anything else is `other`, kept verbatim.
+ */
+export declare function subjectFromClassName(className: string): DetectionSubject;
+/** What an event says about the subject — all optional, off the bus. */
+export interface SubjectObservation {
+    readonly className: string;
+    /** Every class the track was observed as. */
+    readonly classes?: readonly string[];
+    /** The display label (an identity name, a plate text) once resolved. */
+    readonly label?: string;
+    readonly identityId?: string;
+    readonly plateText?: string;
+}
+export type SubjectVerdict = {
+    readonly matches: true;
+    readonly label: string;
+} | {
+    readonly matches: false;
+    readonly reason: string;
+};
+/** A human name for a subject, for a reason line. */
+export declare function describeSubject(subject: DetectionSubject): string;
+/** Does one observation satisfy one subject, and which label did it match? */
+export declare function subjectMatches(subject: DetectionSubject, observed: SubjectObservation): SubjectVerdict;
+/** The first subject an observation satisfies, else why the last one did not. */
+export declare function anySubjectMatches(subjects: readonly DetectionSubject[], observed: SubjectObservation): SubjectVerdict;
+export {};

package/dist/automation/detection-trigger.d.ts

@@ -9,15 +9,17 @@
  * `source`, so the filter reads `data.deviceId`.
  *
  * ONE fire per `(deviceId, trackId)`: a track fires the first time it satisfies
- * the class, score and zone conditions (which may be on an `update`, once its
- * best confidence has risen), and never again. The fired set is bounded and
+ * the subject, score and zone conditions (which may be on an `update`, once its
+ * best confidence has risen, or once its face or plate has been resolved — D683
+ * decides identity late, so a leaf with a label fires on the update that
+ * carries it, never on the first detection), and never again. The fired set is bounded and
  * forgets a track on its `end` or after {@link FIRED_TTL_MS}, so a track whose
  * `end` was dropped (events are telemetry, D8) cannot pin memory.
  */
-import type { AutomationTrigger } from './recipe.js';
-export type DetectionTrigger = Extract<AutomationTrigger, {
-    kind: 'detection';
-}>;
+import type { LegacyDetectionTrigger } from './legacy-recipe.js';
+import type { DetectionLeaf } from './when.js';
+/** A detection leaf — or the old trigger a block generated before the single tree still hands over. */
+export type DetectionTrigger = DetectionLeaf | LegacyDetectionTrigger;
 /** A track that never ended is forgotten after this long. */
 export declare const FIRED_TTL_MS: number;
 /** Hard bound on the fired set. */
@@ -28,6 +30,11 @@ export interface TrackLifecycleInput {
     readonly trackId?: unknown;
     readonly phase?: unknown;
     readonly bestClassName?: unknown;
+    readonly classes?: unknown;
+    /** The display label once resolved: an identity name, a plate text. */
+    readonly label?: unknown;
+    readonly identityId?: unknown;
+    readonly plateText?: unknown;
     readonly bestConfidence?: unknown;
     readonly zonesVisited?: unknown;
 }
@@ -37,6 +44,8 @@ export interface DetectionVars {
     readonly className: string;
     readonly trackId: string;
     readonly score: number;
+    /** The label the subject matched (`dog`, a face name, a plate); empty when the leaf names none. */
+    readonly label: string;
 }
 export type DetectionDecision = 
 /** Not this trigger's business (other device, malformed, an `end`): neither fired nor traced. */
@@ -58,6 +67,7 @@ export declare class DetectionTriggerFilter {
     private readonly trigger;
     /** `${deviceId}|${trackId}` → fired at. Insertion-ordered, so the oldest is first. */
     private readonly fired;
+    private readonly subjects;
     constructor(trigger: DetectionTrigger);
     get firedCount(): number;
     evaluate(event: TrackLifecycleInput, now: number): DetectionDecision;

package/dist/automation/index.d.ts

@@ -11,7 +11,7 @@
 export type { GenerateAutomationBlockInput } from './codegen.js';
 export { generateAutomationBlock } from './codegen.js';
 export type { ConditionEvaluation, ConditionReader, MirrorRefreshFetchers, MirrorRefreshReport, MirrorSource, } from './condition-eval.js';
-export { collectMirrorSources, ConditionMirror, evaluateConditionTree, } from './condition-eval.js';
+export { collectMirrorSources, collectWhenMirrorSources, ConditionMirror, evaluateConditionTree, evaluateWhenTree, } from './condition-eval.js';
 export type { DetectionDecision, DetectionTrigger, DetectionVars, TrackLifecycleInput, } from './detection-trigger.js';
 export { DetectionTriggerFilter, detectionClassMatches, FIRED_MAX, FIRED_TTL_MS, } from './detection-trigger.js';
 export type { StationaryChangedInput, StationaryDecision, StationaryTrigger, StationaryVars, } from './stationary-trigger.js';
@@ -19,9 +19,15 @@ export { evaluateStationaryTrigger } from './stationary-trigger.js';
 export type { CooldownInput, CooldownVerdict, RunGateAdmission } from './run-gate.js';
 export { RunGate } from './run-gate.js';
 export type { AutomationConditionTraceNode, AutomationRunOutcome, AutomationRunTrace, AutomationRunVerdict, AutomationStateDoc, AutomationStepTrace, AutomationTriggerTrace, TraceNodeOutcome, TraceValue, } from './trace.js';
-export { AutomationConditionTraceNodeSchema, EMPTY_AUTOMATION_STATE, mergeSkipTraces, AutomationRunOutcomeSchema, AutomationRunTraceSchema, AutomationRunVerdictSchema, AutomationStateDocSchema, AutomationStepTraceSchema, AutomationTriggerTraceSchema, appendTrace, buildTriggerTrace, isSkippedTrace, skipSignature, TraceNodeOutcomeSchema, TraceValueSchema, } from './trace.js';
-export type { ActionStep, AutomationAction, AutomationCapStep, AutomationCondition, AutomationConditionAll, AutomationConditionAny, AutomationConditionExpression, AutomationConditionLeaf, AutomationConditionNot, AutomationConditionOperator, AutomationConditionStationaryPresent, AutomationRecipe, AutomationRunMode, AutomationTrigger, } from './recipe.js';
-export { ActionStepSchema, AutomationActionSchema, AutomationCapStepSchema, AutomationWaitStepSchema, AutomationConditionOperatorSchema, AutomationConditionSchema, AutomationRecipeSchema, AutomationRunModeSchema, AutomationTriggerSchema, conditionDepth, countConditionLeaves, DEFAULT_TRACE_KEEP, MAX_TRACE_KEEP, MAX_CONDITION_DEPTH, MAX_CONDITION_LEAVES, validateRecipeBounds, } from './recipe.js';
+export { AutomationConditionTraceNodeSchema, EMPTY_AUTOMATION_STATE, mergeSkipTraces, AutomationRunOutcomeSchema, AutomationRunTraceSchema, AutomationRunVerdictSchema, AutomationStateDocSchema, AutomationStepTraceSchema, AutomationTriggerTraceSchema, appendTrace, buildStepArgsTrace, buildTriggerTrace, isSkippedTrace, MAX_TRACE_ARG_LENGTH, MAX_TRACE_ARGS, REDACTED_ARG, skipSignature, TraceNodeOutcomeSchema, TraceValueSchema, } from './trace.js';
+export type { ActionStep, AutomationAction, AutomationCapStep, AutomationRecipe, AutomationRunMode, LegacyAutomationRecipe, } from './recipe.js';
+export { ActionStepSchema, AutomationActionSchema, AutomationCapStepSchema, AutomationWaitStepSchema, AutomationRecipeSchema, AutomationRunModeSchema, CurrentAutomationRecipeSchema, convertLegacyRecipe, DEFAULT_TRACE_KEEP, LegacyAutomationRecipeSchema, MAX_TRACE_KEEP, MAX_CONDITION_DEPTH, MAX_CONDITION_LEAVES, validateRecipeBounds, } from './recipe.js';
+export type { AutomationAll, AutomationAny, AutomationConditionOperator, AutomationEventLeaf, AutomationLeaf, AutomationNot, AutomationStateLeaf, AutomationWhen, DetectionLeaf, DeviceBecomesLeaf, DeviceIsLeaf, ExpressionLeaf, StationaryLeaf, StationaryPresentLeaf, } from './when.js';
+export { AutomationConditionOperatorSchema, AutomationWhenSchema, countWhenLeaves, forEachLeaf, hasEventLeaves, isEventLeaf, isLeaf, MAX_WHEN_DEPTH, MAX_WHEN_LEAVES, validateWhenTree, whenDepth, } from './when.js';
+export type { LegacyCondition, LegacyTrigger, } from './legacy-recipe.js';
+export { convertLegacyCondition, convertLegacyWhen, LegacyConditionSchema, LegacyTriggerSchema, } from './legacy-recipe.js';
+export type { DetectionLabelSource, DetectionSubject, IdentityLabel, PlateLabel, SubClassLabel, SubjectObservation, SubjectVerdict, } from './detection-subject.js';
+export { anySubjectMatches, DETECTION_LABEL_SOURCES, DetectionSubjectSchema, describeSubject, StationarySubjectSchema, subClassesOf, subjectFromClassName, subjectMatches, } from './detection-subject.js';
 export * from './action.js';
 export * from './step-runner.js';
 export { UnitWarningSchema, capUnitResolver, normalizeActionUnits, normalizeConditionUnits, normalizeRecipeUnits, } from './normalize-units.js';

package/dist/automation/legacy-recipe.d.ts

@@ -0,0 +1,130 @@
+/**
+ * The recipe shape before the single `when` tree: a flat list of triggers
+ * (OR'd, each an instant) and an optional condition tree. Stored recipes —
+ * the `AUTOMATION_RECIPE` literal of every block saved so far, and whatever an
+ * older client still posts — are in this shape, so it stays READABLE here, and
+ * {@link convertLegacyRecipe} turns it into the new one, losslessly and one
+ * way. Nothing writes this shape any more.
+ *
+ *   `{ triggers: [t1…tn], conditions?: C }`
+ *      → `when = all(any(t1…tn), C)`, or `any(t1…tn)` without `C`;
+ *        a single trigger is not wrapped in `any`.
+ *   a `condition` leaf → a `device-is` leaf (the "is" verb);
+ *   a `device-state` trigger → a `device-becomes` leaf (the "becomes" verb);
+ *   `classes: ['dog']` → the macro `animal` with the label `dog`.
+ */
+import { z } from 'zod';
+import { type AutomationWhen } from './when.js';
+export declare const LegacyTriggerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"device-state">;
+    deviceId: z.ZodNumber;
+    cap: z.ZodString;
+    fieldPath: z.ZodString;
+    becomes: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    edge: z.ZodOptional<z.ZodBoolean>;
+    forMs: z.ZodOptional<z.ZodNumber>;
+    debounceMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"device-event">;
+    category: z.ZodString;
+    deviceId: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"schedule">;
+    cron: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"manual">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"detection">;
+    classes: z.ZodArray<z.ZodString>;
+    deviceIds: z.ZodArray<z.ZodNumber>;
+    zones: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    minScore: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"stationary">;
+    deviceIds: z.ZodArray<z.ZodNumber>;
+    classes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    zones: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    phase: z.ZodEnum<{
+        appeared: "appeared";
+        departed: "departed";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"interval">;
+    minutes: z.ZodNumber;
+}, z.core.$strip>], "kind">;
+export type LegacyTrigger = z.infer<typeof LegacyTriggerSchema>;
+export type LegacyDetectionTrigger = Extract<LegacyTrigger, {
+    kind: 'detection';
+}>;
+export type LegacyStationaryTrigger = Extract<LegacyTrigger, {
+    kind: 'stationary';
+}>;
+declare const LegacyConditionLeafSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"condition">;
+    deviceId: z.ZodNumber;
+    cap: z.ZodString;
+    fieldPath: z.ZodString;
+    operator: z.ZodEnum<{
+        contains: "contains";
+        eq: "eq";
+        gt: "gt";
+        gte: "gte";
+        in: "in";
+        lt: "lt";
+        lte: "lte";
+        ne: "ne";
+    }>;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>, z.ZodObject<{
+        value: z.ZodNumber;
+        unit: z.ZodString;
+    }, z.core.$strip>]>;
+    unit: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const LegacyStationaryPresentSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"stationary-present">;
+    deviceId: z.ZodNumber;
+    classes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    zones: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+declare const LegacyExpressionSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"expression">;
+    expr: z.ZodString;
+    bindings: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodOptional<z.ZodLiteral<"field">>;
+        sourceKey: z.ZodString;
+        cap: z.ZodString;
+        fieldPath: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"literal">;
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"global">;
+        sourceStableId: z.ZodString;
+        cap: z.ZodString;
+        fieldPath: z.ZodString;
+    }, z.core.$strip>]>>;
+}, z.core.$strip>;
+type LegacyLeaf = z.infer<typeof LegacyConditionLeafSchema> | z.infer<typeof LegacyStationaryPresentSchema> | z.infer<typeof LegacyExpressionSchema>;
+export type LegacyCondition = {
+    readonly kind: 'all';
+    readonly children: readonly LegacyCondition[];
+} | {
+    readonly kind: 'any';
+    readonly children: readonly LegacyCondition[];
+} | {
+    readonly kind: 'not';
+    readonly child: LegacyCondition;
+} | LegacyLeaf;
+export declare const LegacyConditionSchema: z.ZodType<LegacyCondition>;
+/** The recipe without its `actions` / `runMode` / `keepTraces` half, which did not change. */
+export interface LegacyWhenHalf {
+    readonly triggers: readonly LegacyTrigger[];
+    readonly conditions?: LegacyCondition | undefined;
+}
+/** An old condition tree as a `when` subtree: `condition` → "is", classes → subjects. */
+export declare function convertLegacyCondition(condition: LegacyCondition): AutomationWhen;
+/** One legacy trigger as a leaf — kept for readers that hold a single old trigger. */
+export declare function convertLegacyTrigger(trigger: LegacyTrigger): AutomationWhen;
+/** `all(any(t1…tn), C)`, or `any(t1…tn)`; a single trigger is not wrapped in `any`. */
+export declare function convertLegacyWhen(half: LegacyWhenHalf): AutomationWhen;
+export {};

package/dist/automation/normalize-units.d.ts

@@ -24,7 +24,8 @@ import type { CapabilityDefinition } from '../capabilities/capability-definition
 import { type ParamMeta } from '../units/quantity-input.js';
 import type { ReadingQuantity } from '../units/quantity.js';
 import { z } from 'zod';
-import type { AutomationAction, AutomationCapStep, AutomationCondition, AutomationRecipe } from './recipe.js';
+import type { AutomationAction, AutomationCapStep, AutomationRecipe } from './recipe.js';
+import type { AutomationWhen } from './when.js';
 /** What the boundary needs to know about caps. */
 export interface UnitResolver {
     /** The quantity of a status field, or `undefined` when it is not a quantity. */
@@ -49,11 +50,11 @@ export interface UnitsNormalized<T> {
 /** A resolver over capability definitions (the generated registry, or a fake). */
 export declare function capUnitResolver(defs: readonly CapabilityDefinition[]): UnitResolver;
 /** Normalise every leaf of a condition tree. Throws {@link QuantityUnitError}. */
-export declare function normalizeConditionUnits(condition: AutomationCondition, resolver: UnitResolver, path?: string): UnitsNormalized<AutomationCondition>;
+export declare function normalizeConditionUnits(condition: AutomationWhen, resolver: UnitResolver, path?: string): UnitsNormalized<AutomationWhen>;
 /**
  * Normalise the cap steps of an action list (an internal Action's steps, or a
  * recipe's actions). Other step kinds pass through. Throws {@link QuantityUnitError}.
  */
 export declare function normalizeActionUnits<A extends AutomationAction>(actions: readonly A[], resolver: UnitResolver, path?: string): UnitsNormalized<(A | AutomationCapStep)[]>;
-/** Normalise a whole recipe: its condition tree and its actions. */
+/** Normalise a whole recipe: its `when` tree and its actions. */
 export declare function normalizeRecipeUnits(recipe: AutomationRecipe, resolver: UnitResolver): UnitsNormalized<AutomationRecipe>;