@camstack/types 1.2.429 → 1.2.430

package/CHANGELOG.md

@@ -7,6 +7,13 @@ 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

package/dist/addon.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sleep = require("./sleep-hRhTSDlN.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-BE7IAR2p.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';

package/dist/automation/recipe.d.ts

@@ -11,7 +11,7 @@
  *
  * Three vocabularies, each salvaged rather than invented:
  *
- *  - **Triggers** — the only genuinely new surface. Four members, none of which
+ *  - **Triggers** — the only genuinely new surface. Six members, none of which
  *    touches notification delivery. The NC keeps its four *pipeline* triggers;
  *    these are device/time triggers and the two sets do not overlap.
  *  - **Conditions** — `ALL`/`ANY`/`NOT` over two leaf kinds, bounded. The
@@ -108,6 +108,15 @@ export declare const AutomationTriggerSchema: z.ZodDiscriminatedUnion<[z.ZodObje
     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<"interval">;
+    minutes: z.ZodNumber;
 }, z.core.$strip>], "kind">;
 export type AutomationTrigger = z.infer<typeof AutomationTriggerSchema>;
 /**
@@ -128,6 +137,36 @@ export type AutomationTrigger = z.infer<typeof AutomationTriggerSchema>;
  * is called. The runner still receives a number and is untouched; the
  * resolution is the recipe's job, not the runner's.
  */
+export declare const AutomationWaitStepSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"wait">;
+    seconds: z.ZodNumber;
+}, z.core.$strip>;
+export declare const AutomationCapStepSchema: 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>;
+/**
+ * The steps an internal Action may contain: cap and wait, and nothing that can
+ * call back into an Action — so an Action can never reach itself (no cycles).
+ */
+export declare const ActionStepSchema: 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">;
+export type ActionStep = z.infer<typeof ActionStepSchema>;
 export declare const AutomationActionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"wait">;
     seconds: z.ZodNumber;
@@ -139,11 +178,46 @@ export declare const AutomationActionSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
     cap: z.ZodString;
     method: z.ZodString;
     args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"action">;
+    actionId: z.ZodString;
+    variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
 }, z.core.$strip>, z.ZodObject<{
     kind: z.ZodLiteral<"code">;
     code: z.ZodString;
 }, z.core.$strip>], "kind">;
 export type AutomationAction = z.infer<typeof AutomationActionSchema>;
+/**
+ * How a trigger that arrives while the automation is busy (or cooling down) is
+ * handled. One of the automation's execution modes, never a property of its
+ * actions. Absent means `single`.
+ *
+ *  - `single`   — drop the trigger while a run is in progress (traced + logged).
+ *  - `restart`  — abort the run in progress (at its next step boundary), start fresh.
+ *  - `queued`   — queue up to `max` triggers, drop the rest (traced).
+ *  - `parallel` — up to `max` runs at once, drop the rest (traced).
+ *  - `cooldown` — `single`, and no new run until `minutes` after the last run
+ *    STARTED; persisted across a restart. A manual trigger bypasses only this
+ *    wait, never the single/queued limits.
+ */
+export declare const AutomationRunModeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    mode: z.ZodLiteral<"single">;
+}, z.core.$strip>, z.ZodObject<{
+    mode: z.ZodLiteral<"restart">;
+}, z.core.$strip>, z.ZodObject<{
+    mode: z.ZodLiteral<"queued">;
+    max: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    mode: z.ZodLiteral<"parallel">;
+    max: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    mode: z.ZodLiteral<"cooldown">;
+    minutes: z.ZodNumber;
+}, z.core.$strip>], "mode">;
+export type AutomationRunMode = z.infer<typeof AutomationRunModeSchema>;
+/** Run traces kept per automation when the recipe does not say. */
+export declare const DEFAULT_TRACE_KEEP = 20;
+export declare const MAX_TRACE_KEEP = 100;
 export declare const AutomationRecipeSchema: z.ZodObject<{
     triggers: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"device-state">;
@@ -163,6 +237,15 @@ export declare const AutomationRecipeSchema: z.ZodObject<{
         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<"interval">;
+        minutes: z.ZodNumber;
     }, z.core.$strip>], "kind">>;
     conditions: z.ZodOptional<z.ZodType<AutomationCondition, unknown, z.core.$ZodTypeInternals<AutomationCondition, unknown>>>;
     actions: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -176,10 +259,29 @@ export declare const AutomationRecipeSchema: z.ZodObject<{
         cap: z.ZodString;
         method: z.ZodString;
         args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"action">;
+        actionId: z.ZodString;
+        variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"code">;
         code: z.ZodString;
     }, z.core.$strip>], "kind">>;
+    runMode: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        mode: z.ZodLiteral<"single">;
+    }, z.core.$strip>, z.ZodObject<{
+        mode: z.ZodLiteral<"restart">;
+    }, z.core.$strip>, z.ZodObject<{
+        mode: z.ZodLiteral<"queued">;
+        max: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        mode: z.ZodLiteral<"parallel">;
+        max: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        mode: z.ZodLiteral<"cooldown">;
+        minutes: z.ZodNumber;
+    }, z.core.$strip>], "mode">>;
+    keepTraces: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type AutomationRecipe = z.infer<typeof AutomationRecipeSchema>;
 /** Depth of a tree, root container = 1. A bare leaf is depth 1. */

package/dist/automation/run-gate.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The admission gate of an automation — what its execution mode decides when a
+ * trigger arrives while a run is in progress, and (for `cooldown`) when the
+ * last run is too recent.
+ *
+ * In memory by design (D49): the decision is taken off in-process counters and
+ * never off a read that can fail. Only the cooldown's `lastRunStartedAt` is
+ * persisted (by the block, through `ctx.storage`) so a restart cannot re-fire
+ * inside the window; it is handed in, not read here.
+ *
+ * Usage: `admit()` once per trigger; every admitted run (`run` / `restart`, or
+ * a queued one when it is dequeued) ends with exactly one `release()`, which
+ * says whether a queued trigger now owns the freed slot.
+ */
+import type { AutomationRunMode } from './recipe.js';
+export interface RunGateAdmission {
+    readonly decision: 'run' | 'queued' | 'restart' | 'drop';
+    readonly reason: string;
+}
+export interface CooldownInput {
+    /** A manual trigger is operator intent: it skips the cooldown wait only. */
+    readonly manual: boolean;
+    readonly now: number;
+    readonly lastRunStartedAt: number | null;
+}
+export interface CooldownVerdict {
+    readonly ok: boolean;
+    readonly bypassed: boolean;
+    readonly reason: string;
+}
+export declare class RunGate {
+    private readonly mode;
+    private active;
+    private pending;
+    constructor(mode: AutomationRunMode);
+    get activeRuns(): number;
+    get queuedTriggers(): number;
+    admit(): RunGateAdmission;
+    /** The run holding a slot ended (any outcome). True = a queued trigger took the slot. */
+    release(): boolean;
+    /** Checked AFTER the conditions pass. Always `ok` outside `cooldown` mode. */
+    cooldown(input: CooldownInput): CooldownVerdict;
+}