@camstack/types 1.2.453 → 1.2.455

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.455] - 2026-10-31
+
+### Changed
+
+- Notification verdicts carry the subject and reach the retrain listing (new optional verdict fields on retrain frames and tracks)
+- An automation or notification step now names its devices as a target (named devices, or every device that offers an action, optionally in one room), and a stored step is read in that shape
+- Schedules take a time spec: a clock time, a sun event (sunrise, sunset, dawn, dusk) with an offset, or a date; the site now reports its time zone
+
+## [1.2.454] - 2026-10-31
+
+### Changed
+
+- Remote layout groups accept an optional size and hideTitle for dividers
+
 ## [1.2.453] - 2026-10-30
 
 ### Changed

package/dist/automation/action-target.d.ts

@@ -0,0 +1,86 @@
+/**
+ * WHO an action step acts on (D983) — one target shape for every place that
+ * performs an action (automation steps, Action entries, notification
+ * sequences, scheduler points):
+ *
+ *  - `devices` — device ids the operator picked, frozen at save time;
+ *  - `domain`  — every device that offers the step's VOCABULARY action,
+ *    optionally narrowed to one device type and one room, resolved WHEN THE
+ *    STEP RUNS (a device added later is included). The action always comes
+ *    from the vocabulary (`cover.open`), never from a raw cap name, so a
+ *    `domain` target needs an `actionId` (enforced on the step schema);
+ *  - `var`     — a `$var` resolved from the run's scope.
+ *
+ * {@link ActionTargetResolver} turns a target into device ids. It is pure
+ * (a {@link DeviceDirectory} is handed in) so the hub's core-blocks service and
+ * a generated automation block share it.
+ *
+ * A room is the device's `location` label (`DeviceInfo.location`); two labels
+ * name the same room when `locationIconKey` agrees (trimmed, lower-cased).
+ */
+import { z } from 'zod';
+import { DeviceType } from '../device/device-type.js';
+import { EventCategory } from '../enums/event-category.js';
+import type { IScopedLogger } from '../interfaces/logging.js';
+export declare const ActionTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"devices">;
+    ids: z.ZodArray<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"domain">;
+    deviceType: z.ZodOptional<z.ZodEnum<typeof DeviceType>>;
+    roomId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"var">;
+    name: z.ZodString;
+}, z.core.$strip>], "kind">;
+export type ActionTarget = z.infer<typeof ActionTargetSchema>;
+/** What a resolver needs to know about one device. */
+export interface DirectoryDevice {
+    readonly id: number;
+    readonly type: DeviceType;
+    /** The room label, `null` when unset. */
+    readonly location: string | null;
+    readonly disabled: boolean;
+}
+/**
+ * The device registry as the resolver sees it. `listDeviceIdsByCaps` is the
+ * per-binding walk (D12/D13) done where the bindings live; `listDevices`
+ * reads the listed devices' type and room.
+ */
+export interface DeviceDirectory {
+    listDeviceIdsByCaps(capNames: readonly string[]): Promise<readonly number[]>;
+    listDevices(deviceIds: readonly number[]): Promise<readonly DirectoryDevice[]>;
+}
+/** The events after which a cached domain is stale. */
+export declare const ACTION_TARGET_INVALIDATION_EVENTS: readonly EventCategory[];
+/** The result of resolving a target. */
+export interface ResolvedTarget {
+    readonly deviceIds: readonly number[];
+    /** Set when nothing matched — the reason, for the trace. */
+    readonly emptyReason?: string;
+}
+/** Who asked, for the log line of an empty resolution. */
+export interface ResolveOrigin {
+    readonly actionId: string | undefined;
+    /** The automation / action / scheduler the step belongs to. */
+    readonly owner: string | undefined;
+}
+/** The bag `var` targets read from. */
+export type TargetVars = Readonly<Record<string, unknown>>;
+export declare class ActionTargetResolver {
+    private readonly directory;
+    private readonly logger;
+    /** cap name → its devices, until a registry event says otherwise. */
+    private readonly byCap;
+    constructor(directory: DeviceDirectory, logger: IScopedLogger);
+    /** Forget every cached domain (a device was added, removed, moved or re-bound). */
+    invalidate(): void;
+    private devicesOfCap;
+    /**
+     * The devices `target` means for `actionId` right now. An EMPTY answer is
+     * logged and carries its reason — the caller traces it; it is never silent.
+     * Throws when the target cannot be resolved at all (an unknown action, a
+     * `var` that is not a device id).
+     */
+    resolve(target: ActionTarget, actionId: string | undefined, vars: TargetVars, origin: ResolveOrigin): Promise<ResolvedTarget>;
+}

package/dist/automation/action.d.ts

@@ -86,9 +86,21 @@ export declare const ActionEntrySchema: z.ZodObject<{
         seconds: z.ZodNumber;
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"cap">;
-        deviceId: z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>, z.ZodObject<{
+        actionId: z.ZodOptional<z.ZodString>;
+        target: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"devices">;
+            ids: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"domain">;
+            deviceType: z.ZodOptional<z.ZodEnum<typeof import("../index.js").DeviceType>>;
+            roomId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"var">;
+            name: z.ZodString;
+        }, z.core.$strip>], "kind">>;
+        deviceId: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>, z.ZodObject<{
             $var: z.ZodString;
-        }, z.core.$strip>]>;
+        }, z.core.$strip>]>>;
         cap: z.ZodString;
         method: z.ZodString;
         args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -122,9 +134,21 @@ export declare const ActionInputSchema: z.ZodObject<{
         seconds: z.ZodNumber;
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"cap">;
-        deviceId: z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>, z.ZodObject<{
+        actionId: z.ZodOptional<z.ZodString>;
+        target: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"devices">;
+            ids: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"domain">;
+            deviceType: z.ZodOptional<z.ZodEnum<typeof import("../index.js").DeviceType>>;
+            roomId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"var">;
+            name: z.ZodString;
+        }, z.core.$strip>], "kind">>;
+        deviceId: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>, z.ZodObject<{
             $var: z.ZodString;
-        }, z.core.$strip>]>;
+        }, z.core.$strip>]>>;
         cap: z.ZodString;
         method: z.ZodString;
         args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;

package/dist/automation/index.d.ts

@@ -18,10 +18,10 @@ export type { StationaryChangedInput, StationaryDecision, StationaryTrigger, Sta
 export { evaluateStationaryTrigger } from './stationary-trigger.js';
 export type { CooldownInput, CooldownVerdict, RunGateAdmission } from './run-gate.js';
 export { RunGate } from './run-gate.js';
-export type { AutomationConditionTraceNode, AutomationRunOutcome, AutomationRunTrace, AutomationRunVerdict, AutomationStateDoc, AutomationStepTrace, AutomationTriggerTrace, TraceNodeOutcome, TraceValue, } from './trace.js';
-export { AutomationConditionTraceNodeSchema, EMPTY_AUTOMATION_STATE, mergeSkipTraces, AutomationRunOutcomeSchema, AutomationRunTraceSchema, AutomationRunVerdictSchema, AutomationStateDocSchema, AutomationStepTraceSchema, AutomationTriggerTraceSchema, appendTrace, buildStepArgsTrace, buildTriggerTrace, isSkippedTrace, MAX_TRACE_ARG_LENGTH, MAX_TRACE_ARGS, REDACTED_ARG, skipSignature, TraceNodeOutcomeSchema, TraceValueSchema, } from './trace.js';
-export type { ActionStep, AutomationAction, AutomationCapStep, AutomationRecipe, AutomationRunMode, LegacyAutomationRecipe, } from './recipe.js';
-export { ActionStepSchema, AutomationActionSchema, AutomationCapStepSchema, AutomationWaitStepSchema, AutomationRecipeSchema, AutomationRunModeSchema, CurrentAutomationRecipeSchema, convertLegacyRecipe, DEFAULT_TRACE_KEEP, LegacyAutomationRecipeSchema, MAX_TRACE_KEEP, MAX_CONDITION_DEPTH, MAX_CONDITION_LEAVES, validateRecipeBounds, } from './recipe.js';
+export type { AutomationConditionTraceNode, AutomationRunOutcome, AutomationRunTrace, AutomationRunVerdict, AutomationStateDoc, AutomationStepTrace, AutomationTriggerTrace, StepDeviceTrace, TraceNodeOutcome, TraceValue, } from './trace.js';
+export { AutomationConditionTraceNodeSchema, EMPTY_AUTOMATION_STATE, mergeSkipTraces, AutomationRunOutcomeSchema, AutomationRunTraceSchema, AutomationRunVerdictSchema, AutomationStateDocSchema, AutomationStepTraceSchema, AutomationTriggerTraceSchema, appendTrace, buildStepArgsTrace, buildTriggerTrace, isSkippedTrace, MAX_TRACE_ARG_LENGTH, MAX_STEP_DEVICE_OUTCOMES, MAX_TRACE_ARGS, REDACTED_ARG, skipSignature, StepDeviceTraceSchema, TraceNodeOutcomeSchema, TraceValueSchema, } from './trace.js';
+export type { ActionStep, AutomationAction, AutomationCapStep, AutomationRecipe, AutomationRunMode, LegacyAutomationRecipe, NormalizedCapStep, } from './recipe.js';
+export { ActionStepSchema, AutomationActionSchema, AutomationCapStepSchema, AutomationWaitStepSchema, AutomationRecipeSchema, AutomationRunModeSchema, CurrentAutomationRecipeSchema, convertLegacyRecipe, DEFAULT_TRACE_KEEP, LegacyAutomationRecipeSchema, MAX_TRACE_KEEP, MAX_CONDITION_DEPTH, MAX_CONDITION_LEAVES, normalizeCapStep, normalizeStepTargets, validateRecipeBounds, } from './recipe.js';
 export type { AutomationAll, AutomationAny, AutomationConditionOperator, AutomationEventLeaf, AutomationLeaf, AutomationNot, AutomationStateLeaf, AutomationWhen, DetectionLeaf, DeviceBecomesLeaf, DeviceIsLeaf, ExpressionLeaf, StationaryLeaf, StationaryPresentLeaf, } from './when.js';
 export { AutomationConditionOperatorSchema, AutomationWhenSchema, countWhenLeaves, forEachLeaf, hasEventLeaves, isEventLeaf, isLeaf, MAX_WHEN_DEPTH, MAX_WHEN_LEAVES, validateWhenTree, whenDepth, } from './when.js';
 export type { LegacyCondition, LegacyTrigger, } from './legacy-recipe.js';
@@ -29,6 +29,8 @@ export { convertLegacyCondition, convertLegacyWhen, LegacyConditionSchema, Legac
 export type { DetectionLabelSource, DetectionSubject, IdentityLabel, PlateLabel, SubClassLabel, SubjectObservation, SubjectVerdict, } from './detection-subject.js';
 export { anySubjectMatches, DETECTION_LABEL_SOURCES, DetectionSubjectSchema, describeSubject, StationarySubjectSchema, subClassesOf, subjectFromClassName, subjectMatches, } from './detection-subject.js';
 export * from './action.js';
+export * from './action-target.js';
+export * from './nc-action-target.js';
 export * from './step-runner.js';
 export { UnitWarningSchema, capUnitResolver, normalizeActionUnits, normalizeConditionUnits, normalizeRecipeUnits, } from './normalize-units.js';
 export type { UnitResolver, UnitWarning, UnitsNormalized } from './normalize-units.js';

package/dist/automation/nc-action-target.d.ts

@@ -0,0 +1,21 @@
+/**
+ * D983 for a notification sequence's cap step: the ONE reader of its target.
+ *
+ * A step stored before D983 names one device (`deviceId`); it is read as a
+ * `devices` target, and `actionId` is filled when the cap and method match
+ * exactly one vocabulary action. A step already in the new shape passes
+ * through. Nothing else in the notification centre reads `deviceId`.
+ */
+import type { NcRuleAction } from '../capabilities/notification-rules.cap.js';
+import type { ActionTarget } from './action-target.js';
+type NcCapAction = Extract<NcRuleAction, {
+    kind: 'cap';
+}>;
+export interface NcCapTarget {
+    readonly target: ActionTarget;
+    readonly actionId: string | undefined;
+}
+export declare function normalizeNcCapTarget(action: NcCapAction): NcCapTarget;
+/** The step as it is stored from now on: `target` (and `actionId`) set, no `deviceId`. */
+export declare function normalizeNcAction(action: NcRuleAction): NcRuleAction;
+export {};

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

@@ -24,7 +24,7 @@ import type { CapabilityDefinition } from '../capabilities/capability-definition
 import { type ParamMeta } from '../units/quantity-input.js';
 import type { ReadingQuantity } from '../units/quantity.js';
 import { z } from 'zod';
-import type { AutomationAction, AutomationCapStep, AutomationRecipe } from './recipe.js';
+import { type AutomationAction, type AutomationCapStep, type AutomationRecipe } from './recipe.js';
 import type { AutomationWhen } from './when.js';
 /** What the boundary needs to know about caps. */
 export interface UnitResolver {

package/dist/automation/recipe.d.ts

@@ -24,8 +24,10 @@
  */
 import { z } from 'zod';
 import { type QuantityValue } from '../units/quantity-input.js';
+import { type ActionTarget } from './action-target.js';
 import { type AutomationWhen } from './when.js';
 export type { QuantityValue };
+export type { ActionTarget };
 /**
  * One action step.
  *
@@ -48,17 +50,74 @@ export declare const AutomationWaitStepSchema: z.ZodObject<{
     kind: z.ZodLiteral<"wait">;
     seconds: z.ZodNumber;
 }, z.core.$strip>;
+/**
+ * The fields of a cap step, before the target rules are applied. Exported for
+ * a shape that is "a cap call, narrowed" (a remote-control binding is one
+ * device); a step is {@link AutomationCapStepSchema}.
+ */
+export declare const AutomationCapStepBaseSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"cap">;
+    actionId: z.ZodOptional<z.ZodString>;
+    target: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"devices">;
+        ids: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"domain">;
+        deviceType: z.ZodOptional<z.ZodEnum<typeof import("../index.js").DeviceType>>;
+        roomId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"var">;
+        name: z.ZodString;
+    }, z.core.$strip>], "kind">>;
+    deviceId: z.ZodOptional<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>;
 export declare const AutomationCapStepSchema: z.ZodObject<{
     kind: z.ZodLiteral<"cap">;
-    deviceId: z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>, z.ZodObject<{
+    actionId: z.ZodOptional<z.ZodString>;
+    target: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"devices">;
+        ids: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"domain">;
+        deviceType: z.ZodOptional<z.ZodEnum<typeof import("../index.js").DeviceType>>;
+        roomId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"var">;
+        name: z.ZodString;
+    }, z.core.$strip>], "kind">>;
+    deviceId: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>, z.ZodObject<{
         $var: z.ZodString;
-    }, z.core.$strip>]>;
+    }, 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>;
 export type AutomationCapStep = z.infer<typeof AutomationCapStepSchema>;
+/** A cap step after {@link normalizeCapStep}: `target` always set, no legacy `deviceId`. */
+export type NormalizedCapStep = Omit<AutomationCapStep, 'deviceId' | 'target'> & {
+    readonly target: ActionTarget;
+};
+/**
+ * The ONE reader of a stored cap step. A step written before D983 carries
+ * `deviceId`; it becomes a `target`, and `actionId` is filled when its cap +
+ * method (+ the args it sends) match exactly one vocabulary action. A step in
+ * the new shape passes through (its `deviceId`, if any, is dropped). Nothing
+ * else in the repo reads `deviceId`.
+ */
+export declare function normalizeCapStep(step: AutomationCapStep): NormalizedCapStep;
+/**
+ * {@link normalizeCapStep} over a step list: cap steps are rewritten to the
+ * new target shape, every other step passes through. The one function a store
+ * reads through and a save boundary writes through.
+ */
+export declare function normalizeStepTargets<A extends AutomationAction>(steps: readonly A[]): (A | NormalizedCapStep)[];
 /**
  * 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).
@@ -68,9 +127,21 @@ export declare const ActionStepSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     seconds: z.ZodNumber;
 }, z.core.$strip>, z.ZodObject<{
     kind: z.ZodLiteral<"cap">;
-    deviceId: z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>, z.ZodObject<{
+    actionId: z.ZodOptional<z.ZodString>;
+    target: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"devices">;
+        ids: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"domain">;
+        deviceType: z.ZodOptional<z.ZodEnum<typeof import("../index.js").DeviceType>>;
+        roomId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"var">;
+        name: z.ZodString;
+    }, z.core.$strip>], "kind">>;
+    deviceId: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>, z.ZodObject<{
         $var: z.ZodString;
-    }, z.core.$strip>]>;
+    }, z.core.$strip>]>>;
     cap: z.ZodString;
     method: z.ZodString;
     args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -82,9 +153,21 @@ export declare const AutomationActionSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
     seconds: z.ZodNumber;
 }, z.core.$strip>, z.ZodObject<{
     kind: z.ZodLiteral<"cap">;
-    deviceId: z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>, z.ZodObject<{
+    actionId: z.ZodOptional<z.ZodString>;
+    target: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"devices">;
+        ids: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"domain">;
+        deviceType: z.ZodOptional<z.ZodEnum<typeof import("../index.js").DeviceType>>;
+        roomId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"var">;
+        name: z.ZodString;
+    }, z.core.$strip>], "kind">>;
+    deviceId: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>, z.ZodObject<{
         $var: z.ZodString;
-    }, z.core.$strip>]>;
+    }, z.core.$strip>]>>;
     cap: z.ZodString;
     method: z.ZodString;
     args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -136,9 +219,21 @@ export declare const CurrentAutomationRecipeSchema: z.ZodObject<{
         seconds: z.ZodNumber;
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"cap">;
-        deviceId: z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>, z.ZodObject<{
+        actionId: z.ZodOptional<z.ZodString>;
+        target: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"devices">;
+            ids: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"domain">;
+            deviceType: z.ZodOptional<z.ZodEnum<typeof import("../index.js").DeviceType>>;
+            roomId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"var">;
+            name: z.ZodString;
+        }, z.core.$strip>], "kind">>;
+        deviceId: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>, z.ZodObject<{
             $var: z.ZodString;
-        }, z.core.$strip>]>;
+        }, z.core.$strip>]>>;
         cap: z.ZodString;
         method: z.ZodString;
         args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -213,9 +308,21 @@ export declare const LegacyAutomationRecipeSchema: z.ZodObject<{
         seconds: z.ZodNumber;
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"cap">;
-        deviceId: z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>, z.ZodObject<{
+        actionId: z.ZodOptional<z.ZodString>;
+        target: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"devices">;
+            ids: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"domain">;
+            deviceType: z.ZodOptional<z.ZodEnum<typeof import("../index.js").DeviceType>>;
+            roomId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"var">;
+            name: z.ZodString;
+        }, z.core.$strip>], "kind">>;
+        deviceId: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>, z.ZodObject<{
             $var: z.ZodString;
-        }, z.core.$strip>]>;
+        }, z.core.$strip>]>>;
         cap: z.ZodString;
         method: z.ZodString;
         args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -259,9 +366,21 @@ export declare const AutomationRecipeSchema: z.ZodUnion<readonly [z.ZodObject<{
         seconds: z.ZodNumber;
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"cap">;
-        deviceId: z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>, z.ZodObject<{
+        actionId: z.ZodOptional<z.ZodString>;
+        target: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"devices">;
+            ids: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"domain">;
+            deviceType: z.ZodOptional<z.ZodEnum<typeof import("../index.js").DeviceType>>;
+            roomId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"var">;
+            name: z.ZodString;
+        }, z.core.$strip>], "kind">>;
+        deviceId: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>, z.ZodObject<{
             $var: z.ZodString;
-        }, z.core.$strip>]>;
+        }, z.core.$strip>]>>;
         cap: z.ZodString;
         method: z.ZodString;
         args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -333,9 +452,21 @@ export declare const AutomationRecipeSchema: z.ZodUnion<readonly [z.ZodObject<{
         seconds: z.ZodNumber;
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"cap">;
-        deviceId: z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>, z.ZodObject<{
+        actionId: z.ZodOptional<z.ZodString>;
+        target: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"devices">;
+            ids: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"domain">;
+            deviceType: z.ZodOptional<z.ZodEnum<typeof import("../index.js").DeviceType>>;
+            roomId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"var">;
+            name: z.ZodString;
+        }, z.core.$strip>], "kind">>;
+        deviceId: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>, z.ZodObject<{
             $var: z.ZodString;
-        }, z.core.$strip>]>;
+        }, z.core.$strip>]>>;
         cap: z.ZodString;
         method: z.ZodString;
         args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -367,9 +498,21 @@ export declare const AutomationRecipeSchema: z.ZodUnion<readonly [z.ZodObject<{
     when: AutomationWhen;
     actions: ({
         kind: "cap";
-        deviceId: number | number[] | {
+        actionId?: string | undefined;
+        target?: {
+            kind: "devices";
+            ids: number[];
+        } | {
+            kind: "domain";
+            deviceType?: import("../index.js").DeviceType | undefined;
+            roomId?: string | undefined;
+        } | {
+            kind: "var";
+            name: string;
+        } | undefined;
+        deviceId?: number | number[] | {
             $var: string;
-        };
+        } | undefined;
         cap: string;
         method: string;
         args?: Record<string, unknown> | undefined;
@@ -438,9 +581,21 @@ export declare const AutomationRecipeSchema: z.ZodUnion<readonly [z.ZodObject<{
     conditions?: import("./legacy-recipe.js").LegacyCondition | undefined;
     actions: ({
         kind: "cap";
-        deviceId: number | number[] | {
+        actionId?: string | undefined;
+        target?: {
+            kind: "devices";
+            ids: number[];
+        } | {
+            kind: "domain";
+            deviceType?: import("../index.js").DeviceType | undefined;
+            roomId?: string | undefined;
+        } | {
+            kind: "var";
+            name: string;
+        } | undefined;
+        deviceId?: number | number[] | {
             $var: string;
-        };
+        } | undefined;
         cap: string;
         method: string;
         args?: Record<string, unknown> | undefined;

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

@@ -8,18 +8,25 @@
  * an intent the operator never expressed), and every step is traced — the ones
  * 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 { ActionTarget, ResolvedTarget, ResolveOrigin } from './action-target.js';
+import { type ActionStep } from './recipe.js';
+import { type AutomationStepTrace, type StepDeviceTrace } from './trace.js';
 /** Static facts about a step, known before it runs. */
 export interface StepMeta {
     readonly kind: string;
     readonly cap?: string;
     readonly method?: string;
+    /** The vocabulary action id the step performs, when it names one. */
+    readonly actionId?: string;
     readonly deviceId?: number;
 }
 /** What a running step can tell the runner (the device a fan-out is on right now). */
 export interface StepScope {
     setDeviceId(deviceId: number): void;
+    /** One device of a multi-device step finished — traced per device. */
+    recordDevice(outcome: StepDeviceTrace): void;
+    /** The step's target resolved to no device: traced as `empty`, with the reason. */
+    markEmpty(reason: string): void;
     /** The parameters the step is sending NOW (substituted), for its trace. */
     setArgs(args: Readonly<Record<string, unknown>>): void;
 }
@@ -71,11 +78,23 @@ export interface CapCall {
     readonly method: string;
     readonly args: Readonly<Record<string, unknown>>;
 }
+/** How many devices of one step are driven at once. */
+export declare const STEP_DEVICE_CONCURRENCY = 4;
 export interface ActionStepDeps {
     invokeCap(call: CapCall): Promise<void>;
     sleep(ms: number): Promise<void>;
     onMissingVar(name: string): void;
+    /** Turn a step's target into device ids (an empty answer is logged by the resolver). */
+    resolveTarget(target: ActionTarget, actionId: string | undefined, vars: StepVars, origin: ResolveOrigin): Promise<ResolvedTarget>;
+    /** The action / automation the steps belong to, for the log line of an empty target. */
+    readonly owner?: string;
 }
+/**
+ * Run `work` for every device, `concurrency` at a time. EVERY device is tried
+ * (one refusing device must not leave the others undone); each outcome goes to
+ * the step's trace, in device order, and the step fails afterwards if any did.
+ */
+export declare function runForDevices(deviceIds: readonly number[], scope: StepScope, work: (deviceId: number) => Promise<void>, concurrency?: number): Promise<void>;
 /**
  * The runnable form of an internal Action's steps, bound to one run's
  * variables. Variables are substituted per step, at the moment it runs, so a

package/dist/automation/trace.d.ts

@@ -105,16 +105,38 @@ export declare const AutomationRunVerdictSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type AutomationRunVerdict = z.infer<typeof AutomationRunVerdictSchema>;
 /** One executed (or not-run) step — shared by automations and Action runs. */
+/** How many per-device outcomes one step trace keeps. */
+export declare const MAX_STEP_DEVICE_OUTCOMES = 200;
+/** One device of a multi-device step: did the call land. */
+export declare const StepDeviceTraceSchema: z.ZodObject<{
+    deviceId: z.ZodNumber;
+    outcome: z.ZodEnum<{
+        error: "error";
+        ok: "ok";
+    }>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type StepDeviceTrace = z.infer<typeof StepDeviceTraceSchema>;
 export declare const AutomationStepTraceSchema: z.ZodObject<{
     path: z.ZodString;
     kind: z.ZodString;
     cap: z.ZodOptional<z.ZodString>;
     method: z.ZodOptional<z.ZodString>;
+    actionId: z.ZodOptional<z.ZodString>;
     deviceId: z.ZodOptional<z.ZodNumber>;
+    devices: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        deviceId: z.ZodNumber;
+        outcome: z.ZodEnum<{
+            error: "error";
+            ok: "ok";
+        }>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
     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<{
+        empty: "empty";
         error: "error";
         "not-run": "not-run";
         ok: "ok";
@@ -197,11 +219,21 @@ export declare const AutomationRunTraceSchema: z.ZodObject<{
         kind: z.ZodString;
         cap: z.ZodOptional<z.ZodString>;
         method: z.ZodOptional<z.ZodString>;
+        actionId: z.ZodOptional<z.ZodString>;
         deviceId: z.ZodOptional<z.ZodNumber>;
+        devices: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            outcome: z.ZodEnum<{
+                error: "error";
+                ok: "ok";
+            }>;
+            message: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
         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<{
+            empty: "empty";
             error: "error";
             "not-run": "not-run";
             ok: "ok";
@@ -303,11 +335,21 @@ export declare const AutomationStateDocSchema: z.ZodObject<{
             kind: z.ZodString;
             cap: z.ZodOptional<z.ZodString>;
             method: z.ZodOptional<z.ZodString>;
+            actionId: z.ZodOptional<z.ZodString>;
             deviceId: z.ZodOptional<z.ZodNumber>;
+            devices: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                deviceId: z.ZodNumber;
+                outcome: z.ZodEnum<{
+                    error: "error";
+                    ok: "ok";
+                }>;
+                message: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
             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<{
+                empty: "empty";
                 error: "error";
                 "not-run": "not-run";
                 ok: "ok";