@camstack/types 1.2.451 → 1.2.453

package/dist/automation/recipe.d.ts

@@ -9,146 +9,23 @@
  * engine, no second store and no second runtime — the block runner is the
  * runtime, `core_blocks` is the store (§2.1).
  *
- * Three vocabularies, each salvaged rather than invented:
+ * Two parts:
  *
- *  - **Triggers** — the only genuinely new surface. Seven 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 three leaf kinds, bounded. The
- *    expression leaf is the bounded engine at `../expression/`, which is where
- *    arithmetic between two device fields lives and the only place it lives.
+ *  - **`when`** — ONE tree (`./when.ts`) of all/any/not over event leaves
+ *    (instants) and state leaves (durations). It replaces the flat trigger list
+ *    plus the separate condition tree; the firing rule is in that file and in
+ *    ADR "one tree".
  *  - **Actions** — `NcRuleActionSchema`'s two steps, plus the `{kind:'code'}`
  *    fragment of §3.2.2. See {@link AutomationActionSchema} for the ONE place
  *    this had to diverge from "verbatim", and why.
  *
- * Bounds are a guard, not a paragraph (§3.2.1): depth ≤ 3, ≤ 32 leaves. They are
- * enforced by {@link validateRecipeBounds} AND by the schema, so a recipe that
- * arrives over the wire cannot skip the check that the editor applies.
+ * A recipe stored in the old shape (`triggers` + `conditions`) still LOADS:
+ * {@link AutomationRecipeSchema} (the parse-anywhere schema) converts it on parse. Nothing writes it.
  */
 import { z } from 'zod';
-import { type ExpressionBindingSource } from '../expression/binding-source.js';
 import { type QuantityValue } from '../units/quantity-input.js';
-/**
- * Depth of a condition tree, counting the root container as level 1.
- *
- * Three is enough and is not arbitrary: `NOT` over a group is always rewritable
- * by De Morgan (`not(any(a,b))` ≡ `all(not a, not b)`), so the shapes that would
- * need a fourth level have an equivalent at three. An editor that refuses depth
- * 4 should offer that rewrite rather than refusing blankly.
- */
-export declare const MAX_CONDITION_DEPTH = 3;
-/** Leaves per automation. A UI that grows without a bound becomes a language. */
-export declare const MAX_CONDITION_LEAVES = 32;
-/** How a leaf compares a device field to a value. Derived from the field's
- *  `kind` in `deviceManager.getWireableFields`, never hand-maintained. */
-export declare const AutomationConditionOperatorSchema: z.ZodEnum<{
-    contains: "contains";
-    eq: "eq";
-    gt: "gt";
-    gte: "gte";
-    in: "in";
-    lt: "lt";
-    lte: "lte";
-    ne: "ne";
-}>;
-export type AutomationConditionOperator = z.infer<typeof AutomationConditionOperatorSchema>;
-/** A catalog leaf: one device field compared to one value. */
-export interface AutomationConditionLeaf {
-    readonly kind: 'condition';
-    readonly deviceId: number;
-    readonly cap: string;
-    readonly fieldPath: string;
-    readonly operator: AutomationConditionOperator;
-    /**
-     * The value. A number on a quantity field is stored in the field's base unit
-     * (D944); {@link QuantityValue} is the WRITE form — "this number is in this
-     * unit" — which the save boundary replaces with the converted number and
-     * `unit`. A leaf that still carries one is never evaluated (it fails).
-     */
-    readonly value: string | number | boolean | readonly (string | number)[] | QuantityValue;
-    /** The unit the person picked for `value` (display only; `value` is in the base unit). */
-    readonly unit?: string;
-}
-/** The escape hatch: the bounded expression engine over named device bindings. */
-export interface AutomationConditionExpression {
-    readonly kind: 'expression';
-    readonly expr: string;
-    readonly bindings: Readonly<Record<string, ExpressionBindingSource>>;
-}
-/**
- * True when the camera currently has a PARKED object (stationary registry)
- * matching `classes` (macro classes match like the detection trigger) in at
- * least one of `zones`. Reads the zone-analytics snapshot through the same
- * mirror as every other leaf, so a dropped event never decides it (D49).
- */
-export interface AutomationConditionStationaryPresent {
-    readonly kind: 'stationary-present';
-    readonly deviceId: number;
-    readonly classes?: readonly string[];
-    readonly zones?: readonly string[];
-}
-export interface AutomationConditionAll {
-    readonly kind: 'all';
-    readonly children: readonly AutomationCondition[];
-}
-export interface AutomationConditionAny {
-    readonly kind: 'any';
-    readonly children: readonly AutomationCondition[];
-}
-export interface AutomationConditionNot {
-    readonly kind: 'not';
-    readonly child: AutomationCondition;
-}
-export type AutomationCondition = AutomationConditionAll | AutomationConditionAny | AutomationConditionNot | AutomationConditionLeaf | AutomationConditionExpression | AutomationConditionStationaryPresent;
-export declare const AutomationConditionSchema: z.ZodType<AutomationCondition>;
-/**
- * What starts a run.
- *
- * D8 compliance, and it is the reason `device-state` is not merely an event
- * subscription: the trigger evaluates against the **state mirror**, which is
- * reconciled, and an event only WAKES the evaluation. A dropped event therefore
- * DELAYS a trigger; it does not lose it. `schedule` uses `croner` — the one
- * already in the repo — because `setInterval(24h)` drifts and "at 23:30" does
- * not.
- */
-export declare const AutomationTriggerSchema: 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 AutomationTrigger = z.infer<typeof AutomationTriggerSchema>;
+import { type AutomationWhen } from './when.js';
+export type { QuantityValue };
 /**
  * One action step.
  *
@@ -252,7 +129,47 @@ 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<{
+export declare const CurrentAutomationRecipeSchema: z.ZodObject<{
+    when: z.ZodType<AutomationWhen, unknown, z.core.$ZodTypeInternals<AutomationWhen, unknown>>;
+    actions: 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>>;
+        argUnits: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, 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 CurrentAutomationRecipeSchema>;
+/** A recipe as it was stored before the single tree. Read-only: nothing writes this. */
+export declare const LegacyAutomationRecipeSchema: z.ZodObject<{
     triggers: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"device-state">;
         deviceId: z.ZodNumber;
@@ -290,7 +207,7 @@ export declare const AutomationRecipeSchema: 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>>>;
+    conditions: z.ZodOptional<z.ZodType<import("./legacy-recipe.js").LegacyCondition, unknown, z.core.$ZodTypeInternals<import("./legacy-recipe.js").LegacyCondition, unknown>>>;
     actions: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"wait">;
         seconds: z.ZodNumber;
@@ -327,14 +244,241 @@ export declare const AutomationRecipeSchema: z.ZodObject<{
     }, 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. */
-export declare function conditionDepth(cond: AutomationCondition): number;
-/** Leaves only — containers do not count toward the leaf budget. */
-export declare function countConditionLeaves(cond: AutomationCondition): number;
+export type LegacyAutomationRecipe = z.infer<typeof LegacyAutomationRecipeSchema>;
+/** The old shape as the new one, lossless. */
+export declare function convertLegacyRecipe(legacy: LegacyAutomationRecipe): AutomationRecipe;
+/**
+ * Where recipes are PARSED (the core-blocks cap, the MCP tool, the literal a
+ * saved block carries): the new shape as it is, or the old shape converted to
+ * it. The output type is always the new one.
+ */
+export declare const AutomationRecipeSchema: z.ZodUnion<readonly [z.ZodObject<{
+    when: z.ZodType<AutomationWhen, unknown, z.core.$ZodTypeInternals<AutomationWhen, unknown>>;
+    actions: 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>>;
+        argUnits: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, 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>, z.ZodPipe<z.ZodObject<{
+    triggers: z.ZodArray<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">>;
+    conditions: z.ZodOptional<z.ZodType<import("./legacy-recipe.js").LegacyCondition, unknown, z.core.$ZodTypeInternals<import("./legacy-recipe.js").LegacyCondition, unknown>>>;
+    actions: 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>>;
+        argUnits: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, 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>, z.ZodTransform<{
+    when: AutomationWhen;
+    actions: ({
+        kind: "cap";
+        deviceId: number | number[] | {
+            $var: string;
+        };
+        cap: string;
+        method: string;
+        args?: Record<string, unknown> | undefined;
+        argUnits?: Record<string, string> | undefined;
+    } | {
+        kind: "wait";
+        seconds: number;
+    } | {
+        kind: "action";
+        actionId: string;
+        variables?: Record<string, string | number | boolean> | undefined;
+    } | {
+        kind: "code";
+        code: string;
+    })[];
+    runMode?: {
+        mode: "single";
+    } | {
+        mode: "restart";
+    } | {
+        mode: "queued";
+        max: number;
+    } | {
+        mode: "parallel";
+        max: number;
+    } | {
+        mode: "cooldown";
+        minutes: number;
+    } | undefined;
+    keepTraces?: number | undefined;
+}, {
+    triggers: ({
+        kind: "device-state";
+        deviceId: number;
+        cap: string;
+        fieldPath: string;
+        becomes?: string | number | boolean | undefined;
+        edge?: boolean | undefined;
+        forMs?: number | undefined;
+        debounceMs?: number | undefined;
+    } | {
+        kind: "device-event";
+        category: string;
+        deviceId?: number | undefined;
+    } | {
+        kind: "schedule";
+        cron: string;
+    } | {
+        kind: "manual";
+    } | {
+        kind: "detection";
+        classes: string[];
+        deviceIds: number[];
+        zones?: string[] | undefined;
+        minScore?: number | undefined;
+    } | {
+        kind: "stationary";
+        deviceIds: number[];
+        classes?: string[] | undefined;
+        zones?: string[] | undefined;
+        phase: "appeared" | "departed";
+    } | {
+        kind: "interval";
+        minutes: number;
+    })[];
+    conditions?: import("./legacy-recipe.js").LegacyCondition | undefined;
+    actions: ({
+        kind: "cap";
+        deviceId: number | number[] | {
+            $var: string;
+        };
+        cap: string;
+        method: string;
+        args?: Record<string, unknown> | undefined;
+        argUnits?: Record<string, string> | undefined;
+    } | {
+        kind: "wait";
+        seconds: number;
+    } | {
+        kind: "action";
+        actionId: string;
+        variables?: Record<string, string | number | boolean> | undefined;
+    } | {
+        kind: "code";
+        code: string;
+    })[];
+    runMode?: {
+        mode: "single";
+    } | {
+        mode: "restart";
+    } | {
+        mode: "queued";
+        max: number;
+    } | {
+        mode: "parallel";
+        max: number;
+    } | {
+        mode: "cooldown";
+        minutes: number;
+    } | undefined;
+    keepTraces?: number | undefined;
+}>>]>;
+/** Bounds, shared by `when` and the old names the guards still know. */
+export declare const MAX_CONDITION_DEPTH = 4;
+export declare const MAX_CONDITION_LEAVES = 32;
 /**
- * Author-time bounds check. Returns `null` when the recipe is legal, else a
- * message naming the bound it broke — the editor shows it verbatim, so it has
- * to read like something an operator can act on.
+ * Author-time check. Returns `null` when the recipe is legal, else a message
+ * naming what is wrong — the editor shows it verbatim, so it has to read like
+ * something an operator can act on.
  */
 export declare function validateRecipeBounds(recipe: AutomationRecipe): string | null;
+export type { AutomationWhen };

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

@@ -13,10 +13,10 @@
  * misses a fire, and nothing durable depends on it.
  */
 import type { PipelineAnalyticsStationaryChangedPayload } from '../interfaces/event-bus.js';
-import type { AutomationTrigger } from './recipe.js';
-export type StationaryTrigger = Extract<AutomationTrigger, {
-    kind: 'stationary';
-}>;
+import type { LegacyStationaryTrigger } from './legacy-recipe.js';
+import type { StationaryLeaf } from './when.js';
+/** A stationary leaf — or the old trigger a block generated before the single tree still hands over. */
+export type StationaryTrigger = StationaryLeaf | LegacyStationaryTrigger;
 /** The fields of a stationary-changed event the trigger reads (all `unknown`: off the bus). */
 export interface StationaryChangedInput {
     readonly deviceId?: unknown;

package/dist/automation/step-runner.d.ts

@@ -9,7 +9,7 @@
  * after a failure, or after an abort, are `not-run` with the reason.
  */
 import type { ActionStep } from './recipe.js';
-import type { AutomationStepTrace } from './trace.js';
+import { type AutomationStepTrace } from './trace.js';
 /** Static facts about a step, known before it runs. */
 export interface StepMeta {
     readonly kind: string;
@@ -20,6 +20,8 @@ export interface StepMeta {
 /** What a running step can tell the runner (the device a fan-out is on right now). */
 export interface StepScope {
     setDeviceId(deviceId: number): void;
+    /** The parameters the step is sending NOW (substituted), for its trace. */
+    setArgs(args: Readonly<Record<string, unknown>>): void;
 }
 /** One step as the runner sees it: its meta and a closure that does the work. */
 export interface RunnableStep {

package/dist/automation/trace.d.ts

@@ -2,11 +2,12 @@
  * Run traces — what an automation (or, later, an Action run) DID, node by node,
  * so the editor can paint every block green or red with its reason.
  *
- * A trace is data, not a log: it covers the WHOLE tree — the trigger stage,
- * every condition node (containers and leaves, including the ones a
- * short-circuit never reached), the run-mode verdict and every action step —
- * each addressed by a stable path (`conditions.0.1`, `actions.2`, or `steps.N`
- * for an Action run). Skipped
+ * A trace is data, not a log: it covers the WHOLE tree — the event leaf that
+ * fired, every node of the `when` tree (containers and leaves, including the
+ * ones a short-circuit never reached), the run-mode verdict and every action
+ * step — each addressed by a stable path (`when.0.1`, `actions.2`, or `steps.N`
+ * for an Action run). Traces written before the single tree carry
+ * `conditions.*` paths and still parse. Skipped
  * evaluations are traced too, and identical consecutive skips collapse into a
  * repeat count so a trigger that fails every 5 minutes cannot flush real runs.
  *
@@ -36,6 +37,7 @@ export declare const TraceNodeOutcomeSchema: z.ZodEnum<{
 export type TraceNodeOutcome = z.infer<typeof TraceNodeOutcomeSchema>;
 export declare const AutomationTriggerTraceSchema: z.ZodObject<{
     kind: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
     outcome: z.ZodEnum<{
         fail: "fail";
         pass: "pass";
@@ -50,8 +52,16 @@ export declare const AutomationConditionTraceNodeSchema: z.ZodObject<{
         all: "all";
         any: "any";
         condition: "condition";
+        detection: "detection";
+        "device-becomes": "device-becomes";
+        "device-event": "device-event";
+        "device-is": "device-is";
         expression: "expression";
+        interval: "interval";
+        manual: "manual";
         not: "not";
+        schedule: "schedule";
+        stationary: "stationary";
         "stationary-present": "stationary-present";
     }>;
     outcome: z.ZodEnum<{
@@ -103,6 +113,7 @@ export declare const AutomationStepTraceSchema: z.ZodObject<{
     deviceId: z.ZodOptional<z.ZodNumber>;
     startedAt: z.ZodOptional<z.ZodNumber>;
     endedAt: z.ZodOptional<z.ZodNumber>;
+    args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>>>;
     outcome: z.ZodEnum<{
         error: "error";
         "not-run": "not-run";
@@ -117,6 +128,7 @@ export declare const AutomationRunTraceSchema: z.ZodObject<{
     endedAt: z.ZodNumber;
     trigger: z.ZodObject<{
         kind: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
         outcome: z.ZodEnum<{
             fail: "fail";
             pass: "pass";
@@ -130,8 +142,16 @@ export declare const AutomationRunTraceSchema: z.ZodObject<{
             all: "all";
             any: "any";
             condition: "condition";
+            detection: "detection";
+            "device-becomes": "device-becomes";
+            "device-event": "device-event";
+            "device-is": "device-is";
             expression: "expression";
+            interval: "interval";
+            manual: "manual";
             not: "not";
+            schedule: "schedule";
+            stationary: "stationary";
             "stationary-present": "stationary-present";
         }>;
         outcome: z.ZodEnum<{
@@ -180,6 +200,7 @@ export declare const AutomationRunTraceSchema: z.ZodObject<{
         deviceId: z.ZodOptional<z.ZodNumber>;
         startedAt: z.ZodOptional<z.ZodNumber>;
         endedAt: z.ZodOptional<z.ZodNumber>;
+        args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>>>;
         outcome: z.ZodEnum<{
             error: "error";
             "not-run": "not-run";
@@ -213,6 +234,7 @@ export declare const AutomationStateDocSchema: z.ZodObject<{
         endedAt: z.ZodNumber;
         trigger: z.ZodObject<{
             kind: z.ZodString;
+            path: z.ZodOptional<z.ZodString>;
             outcome: z.ZodEnum<{
                 fail: "fail";
                 pass: "pass";
@@ -226,8 +248,16 @@ export declare const AutomationStateDocSchema: z.ZodObject<{
                 all: "all";
                 any: "any";
                 condition: "condition";
+                detection: "detection";
+                "device-becomes": "device-becomes";
+                "device-event": "device-event";
+                "device-is": "device-is";
                 expression: "expression";
+                interval: "interval";
+                manual: "manual";
                 not: "not";
+                schedule: "schedule";
+                stationary: "stationary";
                 "stationary-present": "stationary-present";
             }>;
             outcome: z.ZodEnum<{
@@ -276,6 +306,7 @@ export declare const AutomationStateDocSchema: z.ZodObject<{
             deviceId: z.ZodOptional<z.ZodNumber>;
             startedAt: z.ZodOptional<z.ZodNumber>;
             endedAt: z.ZodOptional<z.ZodNumber>;
+            args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>>>;
             outcome: z.ZodEnum<{
                 error: "error";
                 "not-run": "not-run";
@@ -320,9 +351,23 @@ export declare function mergeSkipTraces(prev: AutomationRunTrace, next: Automati
  *    cannot push the runs the operator is looking for out of the ring.
  */
 export declare function appendTrace(ring: readonly AutomationRunTrace[], trace: AutomationRunTrace, keep: number): AutomationRunTrace[];
+/** What a secret parameter is shown as in a trace. */
+export declare const REDACTED_ARG = "[redacted]";
+/** Parameters kept per step trace; the rest are counted in `…`. */
+export declare const MAX_TRACE_ARGS = 32;
+/** A string value is cut here. */
+export declare const MAX_TRACE_ARG_LENGTH = 200;
+/**
+ * The parameters a step sent, as a trace may show them: primitives and short
+ * lists of them (anything deeper is its JSON text, cut), at most
+ * {@link MAX_TRACE_ARGS} of them. No cap method declares a parameter secret, so
+ * a parameter is redacted by what it is called or by being a keychain marker,
+ * and `secretKeys` names the ones a caller knows about.
+ */
+export declare function buildStepArgsTrace(args: Readonly<Record<string, unknown>>, secretKeys?: readonly string[]): Record<string, TraceValue>;
 /**
  * The trigger stage of a trace from the bag a trigger handed to `run()`:
  * primitives and short lists of them (a device-state `to` that is an object is left out), minus the
- * bookkeeping keys `kind` and `at`.
+ * bookkeeping keys `kind`, `at` and `leaf` (the fired leaf's path, which moves to `path`).
  */
 export declare function buildTriggerTrace(trigger: Readonly<Record<string, unknown>>, outcome: 'pass' | 'fail', reason: string): AutomationTriggerTrace;