@camstack/types 1.2.428 → 1.2.430

package/CHANGELOG.md

@@ -7,11 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.430] - 2026-10-27
+
+### Added
+
+- Actions: declared list entries (action-source, actions caps), an action step for automations, and run traces kept in the hub ledger
+- Automations gain detection and interval triggers, per-automation run modes (single, restart, queued, parallel, cooldown), condition reads from an in-memory mirror, and a ring of run traces
+
+## [1.2.429] - 2026-10-27
+
+### Added
+
+- pet-feeder reports bowlFood, eating and supportsMarkRefilled
+
 ## [1.2.428] - 2026-10-27
 
 ### Added
 
 - The published package now includes its README and CHANGELOG.
+- Cloud integrations raise one alert when their session is lost and clear it when it is back
 
 ## [1.2.427] - 2026-10-27
 

package/dist/addon/session-health.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Session health — the STANDARD "cloud connection lost" alert (D-session-health).
+ *
+ * Every addon that keeps a cloud session for an integration (an account login, a
+ * refresh token, a long-lived socket) reports two facts and nothing else:
+ *
+ *   - `lost(integrationId, …)`  the session was refused / kicked / dropped;
+ *   - `restored(integrationId)` a call went through again.
+ *
+ * The tracker owns everything between: a debounce (a transient reconnect never
+ * alerts), ONE alert per integration instance (never one per device, never one
+ * per failed poll), the wording (provider, integration, reason), an action the
+ * operator can follow, and the automatic resolve when the session is back.
+ *
+ * Alerts are durable state that the next run of the addon cannot see, so the
+ * first `restored()` of a process resolves whatever a previous run left active.
+ */
+import type { Alert, AlertSeverity } from '../capabilities/alerts.cap.js';
+import type { IScopedLogger } from '../interfaces/logging.js';
+/** Why the session ended. `kicked` = the same account signed in elsewhere. */
+export type SessionLossReason = 'kicked' | 'auth-rejected' | 'token-expired' | 'connection-lost';
+/** What an alert's action looks like (the `Alert.action` shape). */
+export interface SessionAlertAction {
+    readonly label: string;
+    readonly href?: string;
+    readonly navigation?: 'app' | 'server';
+}
+/** The slice of `ctx.api.alerts` the tracker needs. Structural, so `ctx.api.alerts` fits. */
+export interface SessionHealthAlertsPort {
+    readonly emit?: {
+        mutate(alert: Alert): Promise<unknown>;
+    };
+    readonly update?: {
+        mutate(input: {
+            readonly alertId: string;
+            readonly patch: Partial<Alert>;
+        }): Promise<unknown>;
+    };
+}
+export declare const SESSION_LOST_ALERT_CATEGORY = "integration.session-lost";
+/** A transient reconnect is quiet for this long before it is worth an alert. */
+export declare const DEFAULT_SESSION_LOST_DEBOUNCE_MS: number;
+export declare function sessionLostAlertId(kind: string, integrationId: string): string;
+export interface BuildSessionLostAlertInput {
+    /** Stable provider key, e.g. `petkit` — part of the alert id and source. */
+    readonly kind: string;
+    /** Display name, e.g. `PetKit`. */
+    readonly providerName: string;
+    readonly integrationId: string;
+    readonly integrationName: string;
+    readonly reason: SessionLossReason;
+    /** Defaults to "Open integration" (the admin integration page). */
+    readonly action?: SessionAlertAction;
+    readonly severity?: AlertSeverity;
+    readonly now?: number;
+}
+/** Pure builder, exported so an addon with its own flow can still emit the standard shape. */
+export declare function buildSessionLostAlert(input: BuildSessionLostAlertInput): Alert;
+export interface SessionHealthTrackerOptions {
+    readonly kind: string;
+    readonly providerName: string;
+    readonly logger: IScopedLogger;
+    /** Read lazily: `ctx.api.alerts` may be absent early in boot. */
+    readonly getAlerts: () => SessionHealthAlertsPort | undefined;
+    readonly debounceMs?: number;
+}
+export interface SessionLostInfo {
+    readonly integrationName: string;
+    readonly reason: SessionLossReason;
+    /** Re-auth route when the addon has one; otherwise "Open integration". */
+    readonly action?: SessionAlertAction;
+}
+export declare class SessionHealthTracker {
+    #private;
+    constructor(opts: SessionHealthTrackerOptions);
+    /** The session is gone. Idempotent: call it on every failed poll. */
+    lost(integrationId: string, info: SessionLostInfo): void;
+    /** A call went through. Idempotent: call it on every successful poll. */
+    restored(integrationId: string): Promise<void>;
+    /** The integration is gone (deleted / disabled): drop its state and its alert. */
+    forget(integrationId: string): Promise<void>;
+    /** Stop every pending timer (addon shutdown). */
+    dispose(): void;
+}
+export interface IntegrationSessionBinding {
+    readonly logger: IScopedLogger;
+    readonly getAlerts: () => SessionHealthAlertsPort | undefined;
+    readonly debounceMs?: number;
+}
+export interface IntegrationSessionReporterOptions {
+    readonly kind: string;
+    readonly providerName: string;
+    /**
+     * Is `err` the cloud ending OUR session (kicked, token refused, sign-in
+     * rejected)? `null` for anything else — a network blip or a per-device error
+     * must never read as a lost session.
+     */
+    readonly classify: (err: unknown) => SessionLossReason | null;
+    /** Re-auth route when the addon has one; otherwise "Open integration". */
+    readonly action?: (integrationId: string) => SessionAlertAction | undefined;
+}
+/**
+ * The addon-facing face of {@link SessionHealthTracker}: a process-wide object an
+ * integration manager AND its device classes can reach (the kernel builds a
+ * device from a `DeviceContext` alone, so neither can be handed a tracker).
+ * The addon `bind()`s it in `onInitialize`, `unbind()`s it on shutdown and
+ * `forget()`s an integration that vanished; everything before `bind` is a no-op.
+ */
+export declare class IntegrationSessionReporter {
+    #private;
+    constructor(opts: IntegrationSessionReporterOptions);
+    bind(binding: IntegrationSessionBinding): void;
+    unbind(): void;
+    /** The manager tells us the display name once, so a device can report by id alone. */
+    register(integrationId: string, integrationName: string): void;
+    /** A call failed. Only a session-ending failure counts; anything else is ignored. */
+    failure(integrationId: string, err: unknown): void;
+    /** A call went through. */
+    ok(integrationId: string): Promise<void>;
+    /** The integration was removed. */
+    forget(integrationId: string): Promise<void>;
+}
+/** What a manager / device depends on to report. */
+export type IntegrationSessionSink = Pick<IntegrationSessionReporter, 'register' | 'failure' | 'ok'>;

package/dist/addon.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sleep = require("./sleep-edKiOXLo.js");
-const require_event_category = require("./event-category-Ave2VSxY.js");
+const require_sleep = require("./sleep-5zRztaHa.js");
+const require_event_category = require("./event-category-BhzwWQCH.js");
 const require_err_msg = require("./err-msg-U7lLUMNz.js");
 //#region src/generated/cap-input-defaults.ts
 /**
@@ -362,9 +362,10 @@ function materialise(defaults) {
 * barrel (`ALL_CAPABILITY_DEFINITIONS`), which would cost ~144MB RSS per
 * forked runner. See docs/decisions/adr-0028.md.
 *
-* Coverage: 26 collection caps, 44 array methods.
+* Coverage: 27 collection caps, 45 array methods.
 */
 var COLLECTION_ARRAY_METHODS = Object.freeze({
+	"action-source": ["listActions"],
 	"addon-pages-source": ["listPages"],
 	"addon-routes": ["getRoutes"],
 	"addon-widgets-source": ["listWidgets"],

package/dist/addon.mjs

@@ -1,5 +1,5 @@
-import { $ as expandCapMethods, $n as REVALIDATE_AFTER_MS, $r as isSecretMarker, $t as RecordFieldPathSchema, A as HF_REPO, An as RecordUniqueViolationError, Ar as buildSecretRef, B as withoutCallerStamp, Bn as RECORD_CLASSES, C as addonSliceHandleApi, Cn as InvalidRecordError, Dn as RecordNotFoundError, En as RECORDS_ERROR_CODES, Fn as UnknownRecordKindError, Fr as parseSecretRef, G as adminUiCapability, Gn as RECORD_MAX_DATA_BYTES, Hn as RECORD_DEFAULT_MAX_DATA_BYTES, I as deviceOpsCapability, In as asRecordsError, Jn as RECORD_QUERY_MAX, Jt as defineEntryKind, Kn as RECORD_MAX_INDEXES, L as viewerUiCapability, Ln as recordsErrorFromMessage, M as CAP_ADVANCE_FIELDS, Mn as RevConflictError, Mr as globalSecretScope, Nn as TransactRefusedError, Nr as isSecretRef, On as RecordSecretUnavailableError, Or as SECRET_REF_SCHEME, P as CAP_STATE_LEAVES, Pn as UnindexedFilterError, Pr as normalizeSecretOwner, Qn as resolveSecretViewsIn, Qr as isSecretFieldView, Qt as EntryDescriptorSchema, R as DEVICE_CHILDREN_BATCH_MAX, Rn as RECORD_BATCH_MAX, Rr as createEvent, Sn as ForeignSecretMarkerError, Tn as PlaintextSecretError, U as describeCustomActions, Un as RECORD_DELETE_BATCH, Vn as RECORD_DATABASES, Wn as RECORD_ID_MAX_LENGTH, Xn as RECORD_SETTINGS_MAX_ROWS, Xr as classifySecretWrite, Xt as createRecordsAccess, Yn as RECORD_SECRET_COLLECTION_PREFIX, Yr as SECRET_CLEAR, Yt as entryBody, Zn as RECORD_SWEEP_INTERVAL_MS, Zr as isSecretClear, Zt as assertTransactScope, _ as readErrorI18n, _n as collectZodSecretPaths, an as assertValidDeclaration, ar as registerKnownSecret, b as isDeviceScopedCap, bn as DeclarationRefusedError, c as asString, cn as REMOVE_LEAF, cr as PEER_BYTES_CHUNK_BYTES, ct as readNodePin, d as parseJsonUnknown, dn as parseSecretPath, dr as PEER_BYTES_TICKET_TTL_MS, dt as ReadinessRegistry, ei as isSecretMarkerLike, en as RecordIndexSchema, er as createSecretsAccess, f as hfModelUrl, fn as recordArrayItemPath, ft as ReadinessTimeoutError, g as ErrorI18nPayloadSchema, gr as BaseAddon, hn as secretArrayPrefixes, hr as DisposerChain, ht as scopeKey, in as StoredRecordKindDeclarationSchema, ir as knownSecretCount, jn as RecordsError, jr as formatSecretScope, kn as RecordTooLargeError, kr as arrayItemFieldPath, ln as collectSecretLeaves, lr as PEER_BYTES_MAX_OUTSTANDING, mn as recordSecretRef, ni as toSecretFieldView, nn as RecordKindNameSchema, nr as clearKnownSecrets, o as asJsonObject, on as declarationsOf, or as scrubKnownSecrets, p as BOOT_RECOVERY_BACKOFF_MS, pn as recordSecretCollection, pr as DATAPLANE_SECRET_HEADER, qn as RECORD_MAX_INDEX_FIELDS, qt as makeInMemoryRecords, r as maskUrlCredentials, rn as RecordRetentionSchema, rr as forgetKnownSecret, sn as defineRecordKinds, sr as shortSecretRefHash, st as nodePin, t as sleep, ti as makeSecretMarker, tn as RecordKindDeclarationSchema, tr as MIN_SCRUBBED_LENGTH, un as mapSecretLeaves, ur as PEER_BYTES_STALL_MS, ut as MODEL_FORMATS, vn as isZodSecret, vr as normalizeAddonInitResult, w as createEventBusSliceSource, wn as NoCallerError, x as createDeviceProxy, xn as FilterRequiredError, y as DEVICE_SCOPED_CAPS, yn as BatchTooLargeError, z as CALLER_STAMPED_CAPABILITIES, zn as RECORD_BATCH_MAX_BYTES, zr as emitReadiness } from "./sleep--jXS9hWo.mjs";
-import { t as EventCategory } from "./event-category-CT-hz5Rb.mjs";
+import { $ as expandCapMethods, $n as REVALIDATE_AFTER_MS, $r as isSecretMarker, $t as RecordFieldPathSchema, A as HF_REPO, An as RecordUniqueViolationError, Ar as buildSecretRef, B as withoutCallerStamp, Bn as RECORD_CLASSES, C as addonSliceHandleApi, Cn as InvalidRecordError, Dn as RecordNotFoundError, En as RECORDS_ERROR_CODES, Fn as UnknownRecordKindError, Fr as parseSecretRef, G as adminUiCapability, Gn as RECORD_MAX_DATA_BYTES, Hn as RECORD_DEFAULT_MAX_DATA_BYTES, I as deviceOpsCapability, In as asRecordsError, Jn as RECORD_QUERY_MAX, Jt as defineEntryKind, Kn as RECORD_MAX_INDEXES, L as viewerUiCapability, Ln as recordsErrorFromMessage, M as CAP_ADVANCE_FIELDS, Mn as RevConflictError, Mr as globalSecretScope, Nn as TransactRefusedError, Nr as isSecretRef, On as RecordSecretUnavailableError, Or as SECRET_REF_SCHEME, P as CAP_STATE_LEAVES, Pn as UnindexedFilterError, Pr as normalizeSecretOwner, Qn as resolveSecretViewsIn, Qr as isSecretFieldView, Qt as EntryDescriptorSchema, R as DEVICE_CHILDREN_BATCH_MAX, Rn as RECORD_BATCH_MAX, Rr as createEvent, Sn as ForeignSecretMarkerError, Tn as PlaintextSecretError, U as describeCustomActions, Un as RECORD_DELETE_BATCH, Vn as RECORD_DATABASES, Wn as RECORD_ID_MAX_LENGTH, Xn as RECORD_SETTINGS_MAX_ROWS, Xr as classifySecretWrite, Xt as createRecordsAccess, Yn as RECORD_SECRET_COLLECTION_PREFIX, Yr as SECRET_CLEAR, Yt as entryBody, Zn as RECORD_SWEEP_INTERVAL_MS, Zr as isSecretClear, Zt as assertTransactScope, _ as readErrorI18n, _n as collectZodSecretPaths, an as assertValidDeclaration, ar as registerKnownSecret, b as isDeviceScopedCap, bn as DeclarationRefusedError, c as asString, cn as REMOVE_LEAF, cr as PEER_BYTES_CHUNK_BYTES, ct as readNodePin, d as parseJsonUnknown, dn as parseSecretPath, dr as PEER_BYTES_TICKET_TTL_MS, dt as ReadinessRegistry, ei as isSecretMarkerLike, en as RecordIndexSchema, er as createSecretsAccess, f as hfModelUrl, fn as recordArrayItemPath, ft as ReadinessTimeoutError, g as ErrorI18nPayloadSchema, gr as BaseAddon, hn as secretArrayPrefixes, hr as DisposerChain, ht as scopeKey, in as StoredRecordKindDeclarationSchema, ir as knownSecretCount, jn as RecordsError, jr as formatSecretScope, kn as RecordTooLargeError, kr as arrayItemFieldPath, ln as collectSecretLeaves, lr as PEER_BYTES_MAX_OUTSTANDING, mn as recordSecretRef, ni as toSecretFieldView, nn as RecordKindNameSchema, nr as clearKnownSecrets, o as asJsonObject, on as declarationsOf, or as scrubKnownSecrets, p as BOOT_RECOVERY_BACKOFF_MS, pn as recordSecretCollection, pr as DATAPLANE_SECRET_HEADER, qn as RECORD_MAX_INDEX_FIELDS, qt as makeInMemoryRecords, r as maskUrlCredentials, rn as RecordRetentionSchema, rr as forgetKnownSecret, sn as defineRecordKinds, sr as shortSecretRefHash, st as nodePin, t as sleep, ti as makeSecretMarker, tn as RecordKindDeclarationSchema, tr as MIN_SCRUBBED_LENGTH, un as mapSecretLeaves, ur as PEER_BYTES_STALL_MS, ut as MODEL_FORMATS, vn as isZodSecret, vr as normalizeAddonInitResult, w as createEventBusSliceSource, wn as NoCallerError, x as createDeviceProxy, xn as FilterRequiredError, y as DEVICE_SCOPED_CAPS, yn as BatchTooLargeError, z as CALLER_STAMPED_CAPABILITIES, zn as RECORD_BATCH_MAX_BYTES, zr as emitReadiness } from "./sleep-BHjNez61.mjs";
+import { t as EventCategory } from "./event-category-hdMR7CTW.mjs";
 import { a as DeviceType, t as errMsg } from "./err-msg-DIorGYeC.mjs";
 //#region src/generated/cap-input-defaults.ts
 /**
@@ -361,9 +361,10 @@ function materialise(defaults) {
 * barrel (`ALL_CAPABILITY_DEFINITIONS`), which would cost ~144MB RSS per
 * forked runner. See docs/decisions/adr-0028.md.
 *
-* Coverage: 26 collection caps, 44 array methods.
+* Coverage: 27 collection caps, 45 array methods.
 */
 var COLLECTION_ARRAY_METHODS = Object.freeze({
+	"action-source": ["listActions"],
 	"addon-pages-source": ["listPages"],
 	"addon-routes": ["getRoutes"],
 	"addon-widgets-source": ["listWidgets"],

package/dist/automation/action.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Actions — named, runnable things an operator (or an automation) can start,
+ * declared as LIST ENTRIES, never as devices.
+ *
+ * An entry is either **internal** (a short list of cap/wait steps kept in the
+ * hub's `actions` record kind) or declared by an addon through the
+ * `action-source` collection (a Home Assistant script, a scene …). The one
+ * surface the UI and automations talk to is the `actions` cap; it keeps no
+ * catalog of its own (D3) — every `list` asks the providers live.
+ *
+ * This file is the data half: the entry schema, the variables an entry may
+ * declare, and the pure resolution of the values a run was given. It holds no
+ * runtime.
+ */
+import { z } from 'zod';
+/** What a variable's value is. `select` takes one of `options`. */
+export declare const ActionVariableTypeSchema: z.ZodEnum<{
+    boolean: "boolean";
+    number: "number";
+    select: "select";
+    string: "string";
+}>;
+export type ActionVariableType = z.infer<typeof ActionVariableTypeSchema>;
+export declare const ActionVariableValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+export type ActionVariableValue = z.infer<typeof ActionVariableValueSchema>;
+/**
+ * One declared variable. Steps reference it as `{ $var: 'name' }` (the whole
+ * value) or `{{vars.name}}` (inside a string) in their args.
+ */
+export declare const ActionVariableSchema: z.ZodObject<{
+    name: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    type: z.ZodEnum<{
+        boolean: "boolean";
+        number: "number";
+        select: "select";
+        string: "string";
+    }>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type ActionVariable = z.infer<typeof ActionVariableSchema>;
+export type ResolvedActionVariables = {
+    readonly ok: true;
+    readonly values: Readonly<Record<string, ActionVariableValue>>;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * The values a run starts with: what the caller gave, checked against the
+ * declaration, with defaults filled. A value the entry did not declare is
+ * REFUSED — a typo in a variable name must not silently run with the default.
+ */
+export declare function resolveActionVariables(declared: readonly ActionVariable[] | undefined, given: Readonly<Record<string, ActionVariableValue>> | undefined): ResolvedActionVariables;
+export declare const ActionSourceKindSchema: z.ZodEnum<{
+    addon: "addon";
+    internal: "internal";
+}>;
+export type ActionSourceKind = z.infer<typeof ActionSourceKindSchema>;
+/** Prefix of an internal action's id. */
+export declare const INTERNAL_ACTION_PREFIX = "internal:";
+export declare function internalActionId(uuid: string): string;
+export declare function isInternalActionId(actionId: string): boolean;
+/** The addon behind a `<addonId>:<localId>` id, or null for anything else (internal included). */
+export declare function addonIdOfActionId(actionId: string): string | null;
+export declare const ActionStatusSchema: z.ZodObject<{
+    isRunning: z.ZodBoolean;
+    lastRunAt: z.ZodNullable<z.ZodNumber>;
+    lastError: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ActionStatus = z.infer<typeof ActionStatusSchema>;
+export declare const IDLE_ACTION_STATUS: ActionStatus;
+export declare const ActionEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    addonId: z.ZodString;
+    source: z.ZodEnum<{
+        addon: "addon";
+        internal: "internal";
+    }>;
+    readOnly: z.ZodBoolean;
+    steps: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"wait">;
+        seconds: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"cap">;
+        deviceId: z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>, z.ZodObject<{
+            $var: z.ZodString;
+        }, z.core.$strip>]>;
+        cap: z.ZodString;
+        method: z.ZodString;
+        args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>], "kind">>>;
+    variables: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        type: z.ZodEnum<{
+            boolean: "boolean";
+            number: "number";
+            select: "select";
+            string: "string";
+        }>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    status: z.ZodObject<{
+        isRunning: z.ZodBoolean;
+        lastRunAt: z.ZodNullable<z.ZodNumber>;
+        lastError: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ActionEntry = z.infer<typeof ActionEntrySchema>;
+/** What an operator writes for an internal action. */
+export declare const ActionInputSchema: z.ZodObject<{
+    name: z.ZodString;
+    steps: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"wait">;
+        seconds: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"cap">;
+        deviceId: z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>, z.ZodObject<{
+            $var: z.ZodString;
+        }, z.core.$strip>]>;
+        cap: z.ZodString;
+        method: z.ZodString;
+        args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>], "kind">>;
+    variables: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        type: z.ZodEnum<{
+            boolean: "boolean";
+            number: "number";
+            select: "select";
+            string: "string";
+        }>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ActionInput = z.infer<typeof ActionInputSchema>;
+/** Who started a run. Absent = the operator pressed it. */
+export declare const ActionRunOriginSchema: z.ZodObject<{
+    blockId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ActionRunOrigin = z.infer<typeof ActionRunOriginSchema>;
+/** `started` = the caller did not ask to wait. */
+export declare const ActionRunOutcomeSchema: z.ZodUnion<readonly [z.ZodEnum<{
+    aborted: "aborted";
+    failed: "failed";
+    ran: "ran";
+    "skipped-conditions": "skipped-conditions";
+    "skipped-cooldown": "skipped-cooldown";
+    "skipped-overlap": "skipped-overlap";
+    "skipped-trigger": "skipped-trigger";
+}>, z.ZodLiteral<"started">]>;
+export type ActionRunOutcome = z.infer<typeof ActionRunOutcomeSchema>;
+export declare const ActionRunResultSchema: z.ZodObject<{
+    runId: z.ZodString;
+    outcome: z.ZodUnion<readonly [z.ZodEnum<{
+        aborted: "aborted";
+        failed: "failed";
+        ran: "ran";
+        "skipped-conditions": "skipped-conditions";
+        "skipped-cooldown": "skipped-cooldown";
+        "skipped-overlap": "skipped-overlap";
+        "skipped-trigger": "skipped-trigger";
+    }>, z.ZodLiteral<"started">]>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ActionRunResult = z.infer<typeof ActionRunResultSchema>;
+export declare const ActionErrorCodeSchema: z.ZodEnum<{
+    busy: "busy";
+    "invalid-steps": "invalid-steps";
+    "invalid-variables": "invalid-variables";
+    "not-found": "not-found";
+    "not-linked": "not-linked";
+    "read-only": "read-only";
+}>;
+export type ActionErrorCode = z.infer<typeof ActionErrorCodeSchema>;
+/**
+ * A refusal with a reason a caller can branch on. The code leads the message
+ * (`[read-only] …`) because a cap call flattens an error to its text.
+ */
+export declare class ActionError extends Error {
+    readonly code: ActionErrorCode;
+    constructor(code: ActionErrorCode, message: string);
+}
+/** The run-state change `actions.onRunChanged` carries. */
+export declare const ActionRunChangedSchema: z.ZodObject<{
+    actionId: z.ZodString;
+    runId: z.ZodString;
+    isRunning: z.ZodBoolean;
+    outcome: z.ZodOptional<z.ZodEnum<{
+        aborted: "aborted";
+        failed: "failed";
+        ran: "ran";
+        "skipped-conditions": "skipped-conditions";
+        "skipped-cooldown": "skipped-cooldown";
+        "skipped-overlap": "skipped-overlap";
+        "skipped-trigger": "skipped-trigger";
+    }>>;
+    lastRunAt: z.ZodNullable<z.ZodNumber>;
+    lastError: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ActionRunChanged = z.infer<typeof ActionRunChangedSchema>;

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

@@ -0,0 +1,64 @@
+/**
+ * Evaluating an automation's condition tree against the ConditionMirror.
+ *
+ * D49: a trigger is a one-shot event, so its gate must never hang on a read
+ * that can fail. Every field a condition leaf names is therefore kept in
+ * memory — filled at start, updated off device state-changed events, reconciled
+ * on a timer — and evaluation reads that memory ONLY. A value the mirror does
+ * not hold is UNKNOWN, which is `fail` with a reason, never a throw and never a
+ * `pass`. A failed refresh changes nothing: the previous value stays.
+ *
+ * The evaluator returns a node per tree position (containers, leaves, and the
+ * 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 { AutomationConditionTraceNode } from './trace.js';
+/** One device cap whose slice the mirror must hold. */
+export type MirrorSource = {
+    readonly kind: 'device';
+    readonly deviceId: number;
+    readonly cap: string;
+} | {
+    readonly kind: 'stable';
+    readonly stableId: string;
+    readonly cap: string;
+};
+/** Every (device, cap) a tree reads, deduplicated. */
+export declare function collectMirrorSources(cond: AutomationCondition | undefined): MirrorSource[];
+export interface ConditionReader {
+    /** `undefined` = unknown. */
+    read(deviceId: number, cap: string, fieldPath: string): unknown;
+    readStable(stableId: string, cap: string, fieldPath: string): unknown;
+}
+export interface MirrorRefreshReport {
+    readonly updated: number;
+    /** Sources whose read failed or answered nothing — their old value stays. */
+    readonly kept: number;
+}
+export interface MirrorRefreshFetchers {
+    readonly fetchSlice: (deviceId: number, cap: string) => Promise<unknown>;
+    /** stableId → device id. A rejection leaves the previous map. */
+    readonly fetchStableIds: () => Promise<ReadonlyMap<string, number>>;
+}
+export declare class ConditionMirror implements ConditionReader {
+    private readonly sources;
+    private readonly slices;
+    private stableIds;
+    private readonly watched;
+    constructor(sources: readonly MirrorSource[]);
+    /** A `device.state-changed` event. Slices nobody reads are ignored. */
+    apply(deviceId: number, cap: string, slice: unknown): void;
+    private isStableTarget;
+    read(deviceId: number, cap: string, fieldPath: string): unknown;
+    readStable(stableId: string, cap: string, fieldPath: string): unknown;
+    /** Fill / reconcile. A read that fails or answers nothing keeps the old value. */
+    refresh(fetchers: MirrorRefreshFetchers): Promise<MirrorRefreshReport>;
+}
+export interface ConditionEvaluation {
+    readonly pass: 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;

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

@@ -0,0 +1,66 @@
+/**
+ * The `detection` trigger's per-event decision: does this track-lifecycle
+ * event start a run, and if not, WHY not.
+ *
+ * Source: `EventCategory.PipelineAnalyticsTrackLifecycle` — payload
+ * {@link PipelineAnalyticsTrackLifecyclePayload} (`deviceId`, `trackId`,
+ * `phase` start|update|end, `bestClassName`, `bestConfidence`,
+ * `zonesVisited`). The event carries the device in its DATA, not on its
+ * `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
+ * 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';
+}>;
+/** A track that never ended is forgotten after this long. */
+export declare const FIRED_TTL_MS: number;
+/** Hard bound on the fired set. */
+export declare const FIRED_MAX = 512;
+/** The fields of a track-lifecycle event the trigger reads. */
+export interface TrackLifecycleInput {
+    readonly deviceId?: unknown;
+    readonly trackId?: unknown;
+    readonly phase?: unknown;
+    readonly bestClassName?: unknown;
+    readonly bestConfidence?: unknown;
+    readonly zonesVisited?: unknown;
+}
+/** What a detection run exposes to conditions and actions. */
+export interface DetectionVars {
+    readonly deviceId: number;
+    readonly className: string;
+    readonly trackId: string;
+    readonly score: number;
+}
+export type DetectionDecision = 
+/** Not this trigger's business (other device, malformed, an `end`): neither fired nor traced. */
+{
+    readonly kind: 'ignore';
+    readonly why: string;
+} | {
+    readonly kind: 'reject';
+    readonly reason: string;
+    readonly vars: DetectionVars;
+} | {
+    readonly kind: 'fire';
+    readonly reason: string;
+    readonly vars: DetectionVars;
+};
+/** `animal` matches a dog; `dog` matches only a dog (a cat is also an animal). */
+export declare function detectionClassMatches(wanted: string, actual: string): boolean;
+export declare class DetectionTriggerFilter {
+    private readonly trigger;
+    /** `${deviceId}|${trackId}` → fired at. Insertion-ordered, so the oldest is first. */
+    private readonly fired;
+    constructor(trigger: DetectionTrigger);
+    get firedCount(): number;
+    evaluate(event: TrackLifecycleInput, now: number): DetectionDecision;
+    private remember;
+    private expire;
+}

package/dist/automation/index.d.ts

@@ -10,5 +10,15 @@
  */
 export type { GenerateAutomationBlockInput } from './codegen.js';
 export { generateAutomationBlock } from './codegen.js';
-export type { AutomationAction, AutomationCondition, AutomationConditionAll, AutomationConditionAny, AutomationConditionExpression, AutomationConditionLeaf, AutomationConditionNot, AutomationConditionOperator, AutomationRecipe, AutomationTrigger, } from './recipe.js';
-export { AutomationActionSchema, AutomationConditionOperatorSchema, AutomationConditionSchema, AutomationRecipeSchema, AutomationTriggerSchema, conditionDepth, countConditionLeaves, MAX_CONDITION_DEPTH, MAX_CONDITION_LEAVES, validateRecipeBounds, } from './recipe.js';
+export type { ConditionEvaluation, ConditionReader, MirrorRefreshFetchers, MirrorRefreshReport, MirrorSource, } from './condition-eval.js';
+export { collectMirrorSources, ConditionMirror, evaluateConditionTree, } 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 { 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, AutomationCondition, AutomationConditionAll, AutomationConditionAny, AutomationConditionExpression, AutomationConditionLeaf, AutomationConditionNot, AutomationConditionOperator, 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 * from './action.js';
+export * from './step-runner.js';