makersclaw 0.7.0 → 0.8.1

package/templates/next/files/check/automation-format.ts

@@ -0,0 +1,2103 @@
+// Copied from claw shared/src/automation.ts @ 33de2374. Never edit; refresh with scripts/sync-automation-format.mjs.
+/**
+ * Automations: the definition format, its one validator, and the small
+ * language steps use to pass data to each other (docs/AUTOMATIONS-PLAN.md,
+ * "The definition" and "Data between steps"; decisions A2, A8, A18).
+ *
+ * An automation is a JSON document, format 1: a trigger and an ordered
+ * list of steps. A condition has `then` and `else` lists; a loop has a
+ * `steps` list. No arrows, no cycles, no joins (A2): a durable run must
+ * resume at "step 4, item 7", a version must merge by step id, and a person
+ * must be able to say what it does in one breath.
+ *
+ *   {
+ *     "format": 1, "key": "morning-read", "name": "Morning read",
+ *     "trigger": { "type": "schedule", "cron": "0 7 * * 1-5", "tz": "team" },
+ *     "inputs": {}, "settings": { "overlap": "skip" },
+ *     "steps": [
+ *       { "id": "mail", "kind": "action", "action": "read_mail", "input": { "since": "{{ trigger.at }}" } },
+ *       { "id": "has", "kind": "condition", "if": "{{ steps.mail.output.result.count > 0 }}",
+ *         "then": [ { "id": "done", "kind": "stop", "message": "Read {{ steps.mail.output.result.count }}" } ] }
+ *     ]
+ *   }
+ *
+ * What is in this file, none of it touching a tenant's code, a clock or a
+ * network:
+ *
+ * 1. The expression language (A8). `{{ ... }}` inside any string of a
+ *    step. A value that is only one expression keeps its type (a list
+ *    stays a list); a string that mixes text and expressions is text. No
+ *    `eval`, no `Function`, no regular expressions from outside: a hand
+ *    written tokenizer and parser, a whitelist of functions, a work budget
+ *    and size caps, so a hostile expression stops with a plain error and
+ *    cannot reach `constructor`, `__proto__` or anything outside its data.
+ * 2. `validateAutomation`: every rule of the format, one list of problems
+ *    each naming its place ("steps[2].input.since"). It runs in the
+ *    template's check, the store's publish, the engine's save and the
+ *    Builder's ship.
+ * 3. The output-schema check (A8): each step kind declares the shape of
+ *    its output; a reference to `steps.mail.output.messages` that no such
+ *    field answers is refused at save, with the step and field named.
+ *
+ * There is no approval step (A18): `ask` and `approval` are refused with
+ * their reason. Layout is view data and never part of a definition.
+ *
+ * Standalone: no imports, no env, no I/O. makersclaw-store and the
+ * template may copy this file as they copy app-actions.ts.
+ */
+
+/* ------------------------------------------------------------------ */
+/* Limits and names                                                     */
+/* ------------------------------------------------------------------ */
+
+/** The numbers the plan calls defaults "to be tuned at build". */
+export const AUTOMATION_LIMITS = {
+  /** Steps in one automation, nested ones included. */
+  steps: 60,
+  /** Nesting: a loop or a condition inside a loop or a condition. */
+  depth: 4,
+  /** Items one loop runs over. */
+  loopItems: 500,
+  /** A step's stored output, as JSON. Larger fails the step. */
+  outputBytes: 256 * 1024,
+  /** One expression's source. */
+  expressionChars: 1000,
+  /** Nodes in one expression's tree. */
+  expressionNodes: 200,
+  /** Nesting inside one expression. */
+  expressionDepth: 24,
+  /** Work one resolve may do before it is stopped. */
+  evalWork: 100_000,
+  /** A text an expression builds. */
+  stringChars: 262_144,
+  /** Nesting inside a step's value (`input`, `values`). */
+  valueDepth: 8,
+  /** Keys in one object of a step's value. */
+  valueKeys: 60,
+  /** A label, name or message. */
+  nameChars: 120,
+  messageChars: 500,
+  doesChars: 300,
+  /** Inputs a manual run asks for. */
+  inputs: 20,
+  /** Retry tries a step may ask for. */
+  retries: 5,
+} as const;
+
+/** A step's id, an input's name, a `set` key: lower case, stable (the
+ *  merge key between a shipped version and a member's edit). */
+export const AUTOMATION_ID = /^[a-z][a-z0-9_]{0,39}$/;
+/** An automation's key: the shipped name an app's update merges by. */
+export const AUTOMATION_KEY = /^[a-z][a-z0-9-]{0,59}$/;
+
+export const AUTOMATION_FORMAT = 1;
+
+/** Every kind a definition may name. Which of them an engine runs is
+ *  `CODE_STEP_KINDS` and what comes after (the plan's phases 2 and 3). */
+export const STEP_KINDS = [
+  "action",
+  "brain.read",
+  "condition",
+  "loop",
+  "set",
+  "wait",
+  "stop",
+  "notify",
+  "tool",
+  "search",
+  "llm",
+  "agent",
+  "zero",
+  "automation",
+] as const;
+export type StepKind = (typeof STEP_KINDS)[number];
+
+/** The kinds an engine runs (phases 2 and 3): the code ones, which spend
+ *  nothing (A3), and the four that call out and are metered: `tool`,
+ *  `search`, `llm` and `agent` (docs/AUTOMATIONS-PLAN.md "Step kinds").
+ *  `automation` (a call to another automation) is a later phase. The name
+ *  is kept from phase 2: the doors and the template check read it. */
+export const CODE_STEP_KINDS: readonly StepKind[] = ["action", "brain.read", "condition", "loop", "set", "wait", "stop", "notify", "tool", "search", "llm", "agent", "zero"];
+
+/** The kinds that cost money to run: each is metered into the run's
+ *  credits, counted against the app's allowance, held by the run's cap and
+ *  priced before the run (`estimate`). */
+export const METERED_STEP_KINDS: readonly StepKind[] = ["tool", "search", "llm", "agent", "zero"];
+
+/** The most one Zero step may pay for a call, in USD: the platform's own
+ *  per-call ceiling (agent-app/src/lib/zero.ts ZERO_MAX_PAY_CEILING_USD;
+ *  keep the two equal). A workspace's own cap may be lower, never higher. */
+export const ZERO_STEP_MAX_PAY_USD = 2;
+/** The methods a Zero step may use (GET puts `input` on the url, the rest
+ *  send it as a JSON body). */
+export const ZERO_STEP_METHODS = ["GET", "POST", "PUT", "PATCH"] as const;
+
+/** Kinds that do not exist, and why (A18): refused by name so a person or
+ *  a model writing one is told the rule, not "unknown kind". */
+export const REFUSED_STEP_KINDS: Readonly<Record<string, string>> = {
+  ask: "automations carry no approval step: nothing in a run waits for a yes (A18). When a yes is truly needed, the fixer asks the automation's owner",
+  approval: "automations carry no approval step: nothing in a run waits for a yes (A18). When a yes is truly needed, the fixer asks the automation's owner",
+};
+
+/** A trigger's type. Phase 2 runs the first two; phase 7 adds the rest:
+ *  `event` (a topic an app fires), `action` (an app's declared action
+ *  finished), `record` (the company brain changed), `webhook` (a secret URL
+ *  of this automation's own) and `automation` (another one finished). */
+export const TRIGGER_TYPES = ["schedule", "manual", "event", "action", "record", "webhook", "automation"] as const;
+export type TriggerType = (typeof TRIGGER_TYPES)[number];
+
+/** Triggers that do not exist yet, and why: refused by name so a person or
+ *  a model writing one is told the rule, not "unknown type". */
+export const REFUSED_TRIGGER_TYPES: Readonly<Record<string, string>> = {
+  connection:
+    "a connection's own events (a new mail, a new row in a sheet) are not offered yet: use a schedule with a tool step, or the webhook trigger that a connection's trigger can post to",
+};
+
+/** An event topic: a short dotted slug ("rows.imported"). The same shape
+ *  the apps' `_claw/events` door takes. */
+export const EVENT_TOPIC = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+/** A company-brain kind's name, as a record trigger lists it. */
+export const BRAIN_KIND_NAME = /^[a-z][a-z0-9_]{0,39}$/;
+/** What a record trigger can hear. */
+export const RECORD_OPS = ["create", "update"] as const;
+/** How an `automation` trigger picks the finish it follows. */
+export const FINISH_WHEN = ["done", "failed", "any"] as const;
+/** Keyed runs an hour per automation unless `settings.max_per_hour` says. */
+export const KEYED_RUNS_PER_HOUR = 20;
+/** The longest chain of automations starting automations. */
+export const TRIGGER_CHAIN_MAX = 5;
+
+export const OVERLAP_MODES = ["skip", "queue", "allow"] as const;
+export const FAILURE_MODES = ["stop", "retry_then_agent", "agent_first"] as const;
+
+/* ------------------------------------------------------------------ */
+/* The definition's types                                               */
+/* ------------------------------------------------------------------ */
+
+/** A JSON value a step carries; strings may hold `{{ expressions }}`. */
+export type StepValue = string | number | boolean | null | StepValue[] | { [key: string]: StepValue };
+
+interface StepBase {
+  id: string;
+  label?: string;
+  /** `stop` (default): a step that failed for good fails the run.
+   *  `continue`: the run goes on, the step's output is empty. */
+  on_error?: "stop" | "continue";
+  /** Retry tries after the first, for a transient failure (default 3). */
+  retry?: { max: number };
+}
+
+export interface ActionStep extends StepBase {
+  kind: "action";
+  /** The app's declared action (shared/src/app-actions.ts). */
+  action: string;
+  /** For a workspace automation: which app's. An app's own: absent. */
+  app?: string;
+  input?: { [key: string]: StepValue };
+}
+export interface BrainReadStep extends StepBase {
+  kind: "brain.read";
+  op: "search" | "get" | "list";
+  input: { [key: string]: StepValue };
+}
+export interface ConditionStep extends StepBase {
+  kind: "condition";
+  if: string;
+  then?: Step[];
+  else?: Step[];
+}
+export interface LoopStep extends StepBase {
+  kind: "loop";
+  over: string;
+  max?: number;
+  /** One at a time in v1. */
+  concurrency?: 1;
+  /** Evaluated after each pass; the values are the step's `collected`. */
+  collect?: string;
+  steps: Step[];
+}
+export interface SetStep extends StepBase {
+  kind: "set";
+  values: { [key: string]: StepValue };
+}
+export interface WaitStep extends StepBase {
+  kind: "wait";
+  /** A duration: `30s`, `10m`, `2h`, `3d`. */
+  for?: string;
+  /** An expression giving a time (ISO). */
+  until?: string;
+}
+export interface StopStep extends StepBase {
+  kind: "stop";
+  message: string;
+  as?: "done" | "failed";
+}
+export interface NotifyStep extends StepBase {
+  kind: "notify";
+  message: string;
+  to?: "owner";
+}
+export interface ToolStep extends StepBase {
+  kind: "tool";
+  needs: { category: string };
+  tool: string;
+  input?: { [key: string]: StepValue };
+  account?: string;
+}
+export interface SearchStep extends StepBase {
+  kind: "search";
+  query: string;
+  limit?: number;
+}
+export interface LlmStep extends StepBase {
+  kind: "llm";
+  prompt: string;
+  system?: string;
+  tier?: "fast" | "smart";
+  schema?: Record<string, unknown>;
+}
+export interface AgentStep extends StepBase {
+  kind: "agent";
+  instructions: string;
+  cap_credits?: number;
+  schema?: Record<string, unknown>;
+}
+/**
+ * A paid capability from Zero's catalog (D31 widened: "zero … use the entire
+ * force of the platform"). Plain code, no model: one call to `url`, paid up
+ * to `max_pay_usd`, with the platform's own guards (the per-call, per-run and
+ * daily caps, the same call never paid for twice). `capability` and `url` are
+ * what the catalog named; `input` is the capability's own request (query
+ * params for GET, a JSON body otherwise).
+ */
+export interface ZeroStep extends StepBase {
+  kind: "zero";
+  /** The catalog's name for it: a z_xxx.N token or a slug. */
+  capability: string;
+  /** The capability's address (https). */
+  url: string;
+  method?: (typeof ZERO_STEP_METHODS)[number];
+  input?: { [key: string]: StepValue };
+  /** The most one call may pay, in USD (at most `ZERO_STEP_MAX_PAY_USD`). */
+  max_pay_usd: number;
+}
+export interface AutomationStep extends StepBase {
+  kind: "automation";
+  key: string;
+  input?: { [key: string]: StepValue };
+}
+
+export type Step =
+  | ActionStep
+  | BrainReadStep
+  | ConditionStep
+  | LoopStep
+  | SetStep
+  | WaitStep
+  | StopStep
+  | NotifyStep
+  | ToolStep
+  | SearchStep
+  | LlmStep
+  | AgentStep
+  | ZeroStep
+  | AutomationStep;
+
+export type Trigger =
+  | { type: "schedule"; cron: string; tz: string }
+  | { type: "manual" }
+  /** An app fired `topic` (`_claw/events`), or the workspace did. `app`
+   *  names the app a workspace automation hears; an app's own hears its own. */
+  | { type: "event"; topic: string; app?: string }
+  /** The app's declared action finished. Never an action an automation ran
+   *  (a loop-proof rule): that is what `automation` is for. */
+  | { type: "action"; action: string; app?: string }
+  /** The company brain changed: records of `kinds` (default: every kind the
+   *  owner may read) were created or updated, by a person or the app's
+   *  agent, never by one of the app's own jobs. */
+  | { type: "record"; kinds?: string[]; ops?: ("create" | "update")[]; app?: string }
+  /** A POST to this automation's secret URL. */
+  | { type: "webhook" }
+  /** The automation `key` (of the same owner) finished. */
+  | { type: "automation"; key: string; when: "done" | "failed" | "any" };
+
+export interface InputSpec {
+  type: "string" | "number" | "boolean" | "date";
+  label?: string;
+  required?: boolean;
+  default?: string | number | boolean;
+  options?: string[];
+}
+
+export interface AutomationSettings {
+  overlap: "skip" | "queue" | "allow";
+  on_failure: "stop" | "retry_then_agent" | "agent_first";
+  only_if_changed: boolean;
+  run_cap_credits?: number;
+  /** Keyed runs an hour (default `KEYED_RUNS_PER_HOUR`): a storm of
+   *  distinct events cannot eat a week's budget in a minute. */
+  max_per_hour?: number;
+}
+
+export interface AutomationDef {
+  format: 1;
+  key: string;
+  name: string;
+  does?: string;
+  trigger: Trigger;
+  inputs: Record<string, InputSpec>;
+  settings: AutomationSettings;
+  steps: Step[];
+}
+
+export interface Problem {
+  /** Where: "steps[2].input.since", "trigger.cron". */
+  path: string;
+  message: string;
+}
+
+/* ------------------------------------------------------------------ */
+/* Small helpers                                                        */
+/* ------------------------------------------------------------------ */
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+const hasOwn = (o: object, k: string): boolean => Object.prototype.hasOwnProperty.call(o, k);
+
+/** Names no path may read or write: the way up to Object.prototype. */
+const BAD_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+/** JSON with sorted keys: the same document always gives the same text,
+ *  so a hash of it says "did the member change it". */
+export function canonicalJson(value: unknown): string {
+  const seen = (v: unknown): unknown => {
+    if (Array.isArray(v)) return v.map(seen);
+    if (isObject(v)) {
+      const out: Record<string, unknown> = {};
+      for (const k of Object.keys(v).sort()) if (v[k] !== undefined) out[k] = seen(v[k]);
+      return out;
+    }
+    return v;
+  };
+  return JSON.stringify(seen(value));
+}
+
+const DURATION = /^(\d{1,6})(s|m|h|d)$/;
+const UNIT_MS: Record<string, number> = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+/** The longest wait: thirty days. */
+export const WAIT_MAX_MS = 30 * 86_400_000;
+
+/** `10m` → milliseconds; null when it is not a duration. */
+export function durationMs(text: unknown): number | null {
+  if (typeof text !== "string") return null;
+  const m = DURATION.exec(text);
+  if (!m) return null;
+  return Number(m[1]) * UNIT_MS[m[2]!]!;
+}
+
+/* ------------------------------------------------------------------ */
+/* The expression language: tokens                                      */
+/* ------------------------------------------------------------------ */
+
+/** A mistake in an expression, in words, with where it is. */
+export class ExprError extends Error {
+  readonly at: number;
+  constructor(message: string, at = 0) {
+    super(message);
+    this.name = "ExprError";
+    this.at = at;
+  }
+}
+
+/** A reference with no value, where the step needed one (strict). */
+export class MappingError extends Error {
+  readonly source: string;
+  constructor(source: string) {
+    super(`${source} has no value`);
+    this.name = "MappingError";
+    this.source = source;
+  }
+}
+
+type Tok =
+  | { t: "num"; v: number; at: number }
+  | { t: "str"; v: string; at: number }
+  | { t: "id"; v: string; at: number }
+  | { t: "op"; v: string; at: number }
+  | { t: "end"; at: number };
+
+const OPS3 = new Set<string>([]);
+const OPS2 = new Set(["&&", "||", "??", "==", "!=", "<=", ">="]);
+const OPS1 = new Set([".", "[", "]", "(", ")", ",", "?", ":", "!", "<", ">", "+", "-", "*", "/", "%"]);
+
+function tokenize(src: string): Tok[] {
+  if (src.length > AUTOMATION_LIMITS.expressionChars) {
+    throw new ExprError(`an expression is at most ${AUTOMATION_LIMITS.expressionChars} characters`);
+  }
+  const out: Tok[] = [];
+  let i = 0;
+  while (i < src.length) {
+    const c = src[i]!;
+    if (c === " " || c === "\t" || c === "\n" || c === "\r") {
+      i++;
+      continue;
+    }
+    if (c >= "0" && c <= "9") {
+      let j = i;
+      while (j < src.length && src[j]! >= "0" && src[j]! <= "9") j++;
+      if (src[j] === "." && src[j + 1]! >= "0" && src[j + 1]! <= "9") {
+        j++;
+        while (j < src.length && src[j]! >= "0" && src[j]! <= "9") j++;
+      }
+      if (j - i > 15) throw new ExprError("that number is too long", i);
+      out.push({ t: "num", v: Number(src.slice(i, j)), at: i });
+      i = j;
+      continue;
+    }
+    if (c === '"' || c === "'") {
+      let j = i + 1;
+      let s = "";
+      for (;;) {
+        if (j >= src.length) throw new ExprError("a quote is not closed", i);
+        const d = src[j]!;
+        if (d === c) break;
+        if (d === "\\") {
+          const e = src[j + 1];
+          if (e === undefined) throw new ExprError("a quote is not closed", i);
+          s += e === "n" ? "\n" : e === "t" ? "\t" : e;
+          j += 2;
+          continue;
+        }
+        s += d;
+        j++;
+      }
+      out.push({ t: "str", v: s, at: i });
+      i = j + 1;
+      continue;
+    }
+    if ((c >= "a" && c <= "z") || (c >= "A" && c <= "Z") || c === "_") {
+      let j = i + 1;
+      while (j < src.length && /[A-Za-z0-9_]/.test(src[j]!)) j++;
+      out.push({ t: "id", v: src.slice(i, j), at: i });
+      i = j;
+      continue;
+    }
+    const three = src.slice(i, i + 3);
+    if (OPS3.has(three)) {
+      out.push({ t: "op", v: three, at: i });
+      i += 3;
+      continue;
+    }
+    const two = src.slice(i, i + 2);
+    if (OPS2.has(two)) {
+      out.push({ t: "op", v: two, at: i });
+      i += 2;
+      continue;
+    }
+    if (OPS1.has(c)) {
+      out.push({ t: "op", v: c, at: i });
+      i++;
+      continue;
+    }
+    throw new ExprError(`"${c}" is not part of the expression language`, i);
+  }
+  out.push({ t: "end", at: src.length });
+  return out;
+}
+
+/* ------------------------------------------------------------------ */
+/* The expression language: the tree and the parser                     */
+/* ------------------------------------------------------------------ */
+
+/** The names an expression may start from. */
+export const EXPR_ROOTS = ["trigger", "steps", "item", "index", "vars", "run", "now", "inputs"] as const;
+type Root = (typeof EXPR_ROOTS)[number];
+
+export type Expr =
+  | { n: "lit"; v: string | number | boolean | null }
+  | { n: "path"; root: Root; segs: PathSeg[] }
+  | { n: "un"; op: "!" | "-"; a: Expr }
+  | { n: "bin"; op: string; a: Expr; b: Expr }
+  | { n: "tern"; c: Expr; a: Expr; b: Expr }
+  | { n: "call"; fn: string; args: Expr[] }
+  /** A call's result read further: `list.first(x).id`, `list.filter(...)[0]`. */
+  | { n: "get"; base: Expr; segs: PathSeg[] };
+
+/** A path segment: a name, or an expression in brackets. */
+export type PathSeg = { k: "name"; v: string } | { k: "idx"; e: Expr };
+
+interface FunctionDef {
+  /** Fewest and most arguments. */
+  min: number;
+  max: number;
+}
+
+/** The whole library (A8): pure, bounded, no loops, no code. */
+export const EXPR_FUNCTIONS: Readonly<Record<string, FunctionDef>> = {
+  "date.add": { min: 3, max: 3 },
+  "date.diff": { min: 3, max: 3 },
+  "text.trim": { min: 1, max: 1 },
+  "text.lower": { min: 1, max: 1 },
+  "text.upper": { min: 1, max: 1 },
+  "text.join": { min: 1, max: 2 },
+  "text.contains": { min: 2, max: 2 },
+  "num.round": { min: 1, max: 2 },
+  "num.min": { min: 2, max: 2 },
+  "num.max": { min: 2, max: 2 },
+  "list.filter": { min: 3, max: 4 },
+  "list.map": { min: 2, max: 2 },
+  "list.count": { min: 1, max: 1 },
+  "list.first": { min: 1, max: 1 },
+  "list.slice": { min: 2, max: 2 },
+  "list.sum": { min: 1, max: 2 },
+};
+
+class Parser {
+  private i = 0;
+  private nodes = 0;
+  private depth = 0;
+  private readonly toks: Tok[];
+  constructor(toks: Tok[]) {
+    this.toks = toks;
+  }
+
+  parse(): Expr {
+    const e = this.ternary();
+    const t = this.peek();
+    if (t.t !== "end") throw new ExprError(`unexpected "${this.show(t)}"`, t.at);
+    return e;
+  }
+
+  private show(t: Tok): string {
+    return t.t === "end" ? "the end" : t.t === "num" || t.t === "str" ? String(t.v) : t.v;
+  }
+  private peek(): Tok {
+    return this.toks[this.i]!;
+  }
+  private take(): Tok {
+    return this.toks[this.i++]!;
+  }
+  private isOp(v: string): boolean {
+    const t = this.peek();
+    return t.t === "op" && t.v === v;
+  }
+  private eat(v: string): boolean {
+    if (!this.isOp(v)) return false;
+    this.i++;
+    return true;
+  }
+  private expect(v: string, why: string): void {
+    if (!this.eat(v)) throw new ExprError(`expected "${v}" ${why}`, this.peek().at);
+  }
+  private node<T extends Expr>(n: T): T {
+    if (++this.nodes > AUTOMATION_LIMITS.expressionNodes) throw new ExprError("that expression is too large");
+    return n;
+  }
+  private enter(): void {
+    if (++this.depth > AUTOMATION_LIMITS.expressionDepth) throw new ExprError("that expression nests too deep");
+  }
+
+  private ternary(): Expr {
+    this.enter();
+    const c = this.binary(0);
+    if (this.eat("?")) {
+      const a = this.ternary();
+      this.expect(":", "in a ? : choice");
+      const b = this.ternary();
+      this.depth--;
+      return this.node({ n: "tern", c, a, b });
+    }
+    this.depth--;
+    return c;
+  }
+
+  /** Lowest to highest. `??` and `||` bind as in JavaScript's habit. */
+  private static LEVELS: string[][] = [["??"], ["||"], ["&&"], ["==", "!="], ["<", "<=", ">", ">="], ["+", "-"], ["*", "/", "%"]];
+
+  private binary(level: number): Expr {
+    if (level >= Parser.LEVELS.length) return this.unary();
+    let left = this.binary(level + 1);
+    for (;;) {
+      const t = this.peek();
+      if (t.t === "op" && Parser.LEVELS[level]!.includes(t.v)) {
+        this.i++;
+        const right = this.binary(level + 1);
+        left = this.node({ n: "bin", op: t.v, a: left, b: right });
+      } else return left;
+    }
+  }
+
+  private unary(): Expr {
+    if (this.isOp("!") || this.isOp("-")) {
+      const op = (this.take() as { v: "!" | "-" }).v;
+      this.enter();
+      const a = this.unary();
+      this.depth--;
+      return this.node({ n: "un", op, a });
+    }
+    return this.primary();
+  }
+
+  private primary(): Expr {
+    const t = this.take();
+    if (t.t === "num") return this.node({ n: "lit", v: t.v });
+    if (t.t === "str") return this.node({ n: "lit", v: t.v });
+    if (t.t === "op" && t.v === "(") {
+      this.enter();
+      const e = this.ternary();
+      this.depth--;
+      this.expect(")", "to close the bracket");
+      return e;
+    }
+    if (t.t !== "id") throw new ExprError(`unexpected "${this.show(t)}"`, t.at);
+    if (t.v === "true") return this.node({ n: "lit", v: true });
+    if (t.v === "false") return this.node({ n: "lit", v: false });
+    if (t.v === "null") return this.node({ n: "lit", v: null });
+    // A function: a dotted name from the library, then arguments.
+    const name = this.dotted(t.v);
+    if (this.isOp("(")) {
+      const def = EXPR_FUNCTIONS[name];
+      if (!def) throw new ExprError(`there is no function "${name}"`, t.at);
+      this.i++;
+      const args: Expr[] = [];
+      if (!this.isOp(")")) {
+        for (;;) {
+          args.push(this.ternary());
+          if (this.eat(",")) continue;
+          break;
+        }
+      }
+      this.expect(")", `to close ${name}(`);
+      if (args.length < def.min || args.length > def.max) {
+        throw new ExprError(`${name} takes ${def.min === def.max ? def.min : `${def.min} to ${def.max}`} arguments, not ${args.length}`, t.at);
+      }
+      const callNode = this.node({ n: "call", fn: name, args }) as Expr;
+      const segs = this.segments(t.at);
+      return segs.length ? this.node({ n: "get", base: callNode, segs }) : callNode;
+    }
+    return this.path(t);
+  }
+
+  /** `.name` and `[expr]` after a value. */
+  private segments(at: number): PathSeg[] {
+    const segs: PathSeg[] = [];
+    for (;;) {
+      if (this.eat(".")) {
+        const t = this.take();
+        if (t.t !== "id") throw new ExprError('expected a name after "."', t.at);
+        if (BAD_KEYS.has(t.v)) throw new ExprError(`"${t.v}" cannot be read`, t.at);
+        segs.push({ k: "name", v: t.v });
+      } else if (this.eat("[")) {
+        this.enter();
+        const e = this.ternary();
+        this.depth--;
+        this.expect("]", "to close the bracket");
+        if (e.n === "lit" && typeof e.v === "string") {
+          if (BAD_KEYS.has(e.v)) throw new ExprError(`"${e.v}" cannot be read`, at);
+          segs.push({ k: "name", v: e.v });
+        } else segs.push({ k: "idx", e });
+      } else return segs;
+    }
+  }
+
+  /** `date.add` read as a name, without consuming a path. */
+  private dotted(first: string): string {
+    let name = first;
+    let j = this.i;
+    while (this.toks[j]?.t === "op" && (this.toks[j] as { v: string }).v === "." && this.toks[j + 1]?.t === "id") {
+      name += "." + (this.toks[j + 1] as { v: string }).v;
+      j += 2;
+    }
+    // Only a call consumes the dots; a path re-reads them.
+    if (this.toks[j]?.t === "op" && (this.toks[j] as { v: string }).v === "(" && name.includes(".")) {
+      this.i = j;
+      return name;
+    }
+    return first;
+  }
+
+  private path(first: Tok & { t: "id" }): Expr {
+    if (!(EXPR_ROOTS as readonly string[]).includes(first.v)) {
+      throw new ExprError(`"${first.v}" is not something an expression can read (use ${EXPR_ROOTS.join(", ")})`, first.at);
+    }
+    const segs = this.segments(first.at);
+    return this.node({ n: "path", root: first.v as Root, segs });
+  }
+}
+
+/** Parse one expression (no braces). Throws ExprError. */
+export function parseExpression(src: string): Expr {
+  return new Parser(tokenize(src)).parse();
+}
+
+/* ------------------------------------------------------------------ */
+/* Templates: text with {{ expressions }}                               */
+/* ------------------------------------------------------------------ */
+
+export type TemplatePart = string | Expr;
+export interface Template {
+  parts: TemplatePart[];
+  /** The text was exactly one expression: its value keeps its type. */
+  single: Expr | null;
+  /** The expression sources, for messages. */
+  sources: string[];
+}
+
+/** Split text at `{{ ... }}`, string-aware so `"}}"` inside quotes holds. */
+export function parseTemplate(text: string): Template {
+  const parts: TemplatePart[] = [];
+  const sources: string[] = [];
+  let i = 0;
+  let lit = "";
+  while (i < text.length) {
+    const open = text.indexOf("{{", i);
+    if (open < 0) {
+      lit += text.slice(i);
+      break;
+    }
+    lit += text.slice(i, open);
+    let j = open + 2;
+    let quote: string | null = null;
+    let close = -1;
+    while (j < text.length) {
+      const c = text[j]!;
+      if (quote) {
+        if (c === "\\") j++;
+        else if (c === quote) quote = null;
+      } else if (c === '"' || c === "'") quote = c;
+      else if (c === "}" && text[j + 1] === "}") {
+        close = j;
+        break;
+      }
+      j++;
+    }
+    if (close < 0) throw new ExprError('"{{" is never closed with "}}"', open);
+    const src = text.slice(open + 2, close).trim();
+    if (!src) throw new ExprError("an empty {{ }}", open);
+    if (lit) parts.push(lit);
+    lit = "";
+    try {
+      parts.push(parseExpression(src));
+    } catch (error) {
+      if (error instanceof ExprError) throw new ExprError(`{{ ${src.slice(0, 60)} }}: ${error.message}`, open + 2 + error.at);
+      throw error;
+    }
+    sources.push(src);
+    i = close + 2;
+  }
+  if (lit) parts.push(lit);
+  const only = parts.length === 1 && typeof parts[0] !== "string" ? (parts[0] as Expr) : null;
+  return { parts, single: only, sources };
+}
+
+/** A template that must be exactly one expression: `if`, `over`. A bare
+ *  expression without braces is accepted and means the same. */
+export function parseSingle(text: string): Expr {
+  const t = text.trim();
+  if (!t.includes("{{")) return parseExpression(t);
+  const tpl = parseTemplate(t);
+  if (!tpl.single) throw new ExprError("this must be one {{ expression }} and nothing else");
+  return tpl.single;
+}
+
+/* ------------------------------------------------------------------ */
+/* The expression language: evaluation                                  */
+/* ------------------------------------------------------------------ */
+
+/** What an expression reads. A step's data lives under `steps.<id>.output`. */
+export interface Scope {
+  trigger?: unknown;
+  steps?: Record<string, { output?: unknown } | undefined>;
+  item?: unknown;
+  index?: number;
+  vars?: unknown;
+  run?: unknown;
+  /** An ISO time: when this step began (stable across a replay). */
+  now?: string;
+  inputs?: unknown;
+}
+
+/** The work an evaluation may still do (AUTOMATION_LIMITS.evalWork). */
+export interface Meter {
+  left: number;
+}
+
+function spend(m: Meter, n = 1): void {
+  m.left -= n;
+  if (m.left < 0) throw new ExprError("that does too much work; make the list or the expression smaller");
+}
+
+export function truthy(v: unknown): boolean {
+  if (v === null || v === undefined || v === false || v === 0 || v === "") return false;
+  if (typeof v === "number" && Number.isNaN(v)) return false;
+  if (Array.isArray(v)) return v.length > 0;
+  if (isObject(v)) return Object.keys(v).length > 0;
+  return true;
+}
+
+/** Text for an interpolation: no "undefined", no "[object Object]". */
+export function toText(v: unknown): string {
+  if (v === null || v === undefined) return "";
+  if (typeof v === "string") return v;
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  const s = JSON.stringify(v);
+  return s === undefined ? "" : s;
+}
+
+function capText(s: string): string {
+  if (s.length > AUTOMATION_LIMITS.stringChars) throw new ExprError("that text is too long");
+  return s;
+}
+
+function getProp(obj: unknown, key: string | number): unknown {
+  if (obj === null || obj === undefined) return undefined;
+  if (typeof key === "number") {
+    return Array.isArray(obj) && Number.isInteger(key) && key >= 0 ? obj[key] : undefined;
+  }
+  if (typeof obj === "string") return key === "length" ? obj.length : undefined;
+  if (Array.isArray(obj)) return key === "length" ? obj.length : undefined;
+  if (typeof obj === "object") {
+    if (BAD_KEYS.has(key)) return undefined;
+    return hasOwn(obj, key) ? (obj as Record<string, unknown>)[key] : undefined;
+  }
+  return undefined;
+}
+
+function deepEqual(a: unknown, b: unknown, m: Meter, depth = 0): boolean {
+  spend(m);
+  if (depth > 64) throw new ExprError("that data nests too deep to compare");
+  if (a === undefined) a = null;
+  if (b === undefined) b = null;
+  if (a === b) return true;
+  if (typeof a !== typeof b || a === null || b === null || typeof a !== "object") return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  const ka = Object.keys(a as object);
+  const kb = Object.keys(b as object);
+  if (ka.length !== kb.length) return false;
+  for (const k of ka) {
+    if (!hasOwn(b as object, k) || !deepEqual((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k], m, depth + 1)) return false;
+  }
+  return true;
+}
+
+function num(v: unknown, what: string): number {
+  if (typeof v !== "number" || !Number.isFinite(v)) throw new ExprError(`${what} needs a number`);
+  return v;
+}
+
+function isoOf(v: unknown, what: string): number {
+  if (typeof v !== "string") throw new ExprError(`${what} needs a date`);
+  const t = Date.parse(v);
+  if (!Number.isFinite(t)) throw new ExprError(`${what}: "${v.slice(0, 40)}" is not a date`);
+  return t;
+}
+
+const DATE_UNITS: Record<string, number> = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 };
+
+function unitMs(v: unknown): number {
+  const u = typeof v === "string" ? DATE_UNITS[v] : undefined;
+  if (!u) throw new ExprError('a unit is "s", "m", "h", "d" or "w"');
+  return u;
+}
+
+function cmp(op: string, a: unknown, b: unknown): boolean {
+  if (a === null || a === undefined || b === null || b === undefined) return false;
+  if (typeof a === "number" && typeof b === "number") {
+    return op === "<" ? a < b : op === "<=" ? a <= b : op === ">" ? a > b : a >= b;
+  }
+  if (typeof a === "string" && typeof b === "string") {
+    return op === "<" ? a < b : op === "<=" ? a <= b : op === ">" ? a > b : a >= b;
+  }
+  return false;
+}
+
+function listOf(v: unknown, what: string): unknown[] {
+  if (v === null || v === undefined) return [];
+  if (!Array.isArray(v)) throw new ExprError(`${what} needs a list`);
+  return v;
+}
+
+function call(fn: string, a: unknown[], m: Meter): unknown {
+  switch (fn) {
+    case "date.add": {
+      const t = isoOf(a[0], "date.add") + num(a[1], "date.add") * unitMs(a[2]);
+      if (!Number.isFinite(t) || Math.abs(t) > 8.64e15) throw new ExprError("date.add: that date is out of range");
+      return new Date(t).toISOString();
+    }
+    case "date.diff":
+      return (isoOf(a[0], "date.diff") - isoOf(a[1], "date.diff")) / unitMs(a[2]);
+    case "text.trim":
+      return toText(a[0]).trim();
+    case "text.lower":
+      return toText(a[0]).toLowerCase();
+    case "text.upper":
+      return toText(a[0]).toUpperCase();
+    case "text.join": {
+      const list = listOf(a[0], "text.join");
+      spend(m, list.length);
+      return capText(list.map(toText).join(a[1] === undefined ? ", " : toText(a[1])));
+    }
+    case "text.contains":
+      return toText(a[0]).includes(toText(a[1]));
+    case "num.round": {
+      const digits = a[1] === undefined ? 0 : Math.max(0, Math.min(10, Math.trunc(num(a[1], "num.round"))));
+      const f = 10 ** digits;
+      return Math.round(num(a[0], "num.round") * f) / f;
+    }
+    case "num.min":
+      return Math.min(num(a[0], "num.min"), num(a[1], "num.min"));
+    case "num.max":
+      return Math.max(num(a[0], "num.max"), num(a[1], "num.max"));
+    case "list.filter": {
+      const list = listOf(a[0], "list.filter");
+      const field = toText(a[1]);
+      const hasOp = a.length === 4;
+      const op = hasOp ? toText(a[2]) : "==";
+      const want = hasOp ? a[3] : a[2];
+      if (!["==", "!=", "<", "<=", ">", ">=", "contains"].includes(op)) throw new ExprError(`list.filter: "${op}" is not a comparison`);
+      spend(m, list.length);
+      return list.filter((x) => {
+        const v = field === "" ? x : getProp(x, field);
+        if (op === "==") return deepEqual(v, want, m);
+        if (op === "!=") return !deepEqual(v, want, m);
+        if (op === "contains") return Array.isArray(v) ? v.some((y) => deepEqual(y, want, m)) : toText(v).includes(toText(want));
+        return cmp(op, v, want);
+      });
+    }
+    case "list.map": {
+      const list = listOf(a[0], "list.map");
+      const field = toText(a[1]);
+      spend(m, list.length);
+      return list.map((x) => (field === "" ? x : getProp(x, field)));
+    }
+    case "list.count":
+      return a[0] === null || a[0] === undefined ? 0 : listOf(a[0], "list.count").length;
+    case "list.first":
+      return listOf(a[0], "list.first")[0];
+    case "list.slice":
+      return listOf(a[0], "list.slice").slice(0, Math.max(0, Math.trunc(num(a[1], "list.slice"))));
+    case "list.sum": {
+      const list = listOf(a[0], "list.sum");
+      const field = a[1] === undefined ? "" : toText(a[1]);
+      spend(m, list.length);
+      let total = 0;
+      for (const x of list) {
+        const v = field === "" ? x : getProp(x, field);
+        if (typeof v === "number" && Number.isFinite(v)) total += v;
+      }
+      return total;
+    }
+  }
+  throw new ExprError(`there is no function "${fn}"`);
+}
+
+function evalNode(e: Expr, scope: Scope, m: Meter): unknown {
+  spend(m);
+  switch (e.n) {
+    case "lit":
+      return e.v;
+    case "path": {
+      let v: unknown = e.root === "now" ? scope.now : (scope as Record<string, unknown>)[e.root];
+      for (const seg of e.segs) {
+        if (v === null || v === undefined) return undefined;
+        if (seg.k === "name") v = getProp(v, seg.v);
+        else {
+          const key = evalNode(seg.e, scope, m);
+          if (typeof key === "string") v = BAD_KEYS.has(key) ? undefined : getProp(v, key);
+          else if (typeof key === "number") v = getProp(v, key);
+          else v = undefined;
+        }
+      }
+      return v;
+    }
+    case "un": {
+      const a = evalNode(e.a, scope, m);
+      return e.op === "!" ? !truthy(a) : -num(a, "a minus sign");
+    }
+    case "tern":
+      return truthy(evalNode(e.c, scope, m)) ? evalNode(e.a, scope, m) : evalNode(e.b, scope, m);
+    case "get": {
+      let v = evalNode(e.base, scope, m);
+      for (const seg of e.segs) {
+        if (v === null || v === undefined) return undefined;
+        const key = seg.k === "name" ? seg.v : evalNode(seg.e, scope, m);
+        v = typeof key === "string" || typeof key === "number" ? getProp(v, key) : undefined;
+      }
+      return v;
+    }
+    case "call":
+      return call(
+        e.fn,
+        e.args.map((x) => evalNode(x, scope, m)),
+        m,
+      );
+    case "bin": {
+      if (e.op === "&&") {
+        const a = evalNode(e.a, scope, m);
+        return truthy(a) ? evalNode(e.b, scope, m) : a;
+      }
+      if (e.op === "||") {
+        const a = evalNode(e.a, scope, m);
+        return truthy(a) ? a : evalNode(e.b, scope, m);
+      }
+      if (e.op === "??") {
+        const a = evalNode(e.a, scope, m);
+        return a === null || a === undefined ? evalNode(e.b, scope, m) : a;
+      }
+      const a = evalNode(e.a, scope, m);
+      const b = evalNode(e.b, scope, m);
+      switch (e.op) {
+        case "==":
+          return deepEqual(a, b, m);
+        case "!=":
+          return !deepEqual(a, b, m);
+        case "<":
+        case "<=":
+        case ">":
+        case ">=":
+          return cmp(e.op, a, b);
+        case "+":
+          if (typeof a === "number" && typeof b === "number") return a + b;
+          if (typeof a === "string" || typeof b === "string") return capText(toText(a) + toText(b));
+          throw new ExprError("+ adds two numbers or joins text");
+        case "-":
+          return num(a, "-") - num(b, "-");
+        case "*":
+          return num(a, "*") * num(b, "*");
+        case "/": {
+          const d = num(b, "/");
+          if (d === 0) throw new ExprError("cannot divide by zero");
+          return num(a, "/") / d;
+        }
+        case "%": {
+          const d = num(b, "%");
+          if (d === 0) throw new ExprError("cannot divide by zero");
+          return num(a, "%") % d;
+        }
+      }
+      throw new ExprError(`unknown operator ${e.op}`);
+    }
+  }
+}
+
+/** Evaluate a parsed expression. Throws ExprError on a mistake. */
+export function evalExpression(e: Expr, scope: Scope, meter: Meter = { left: AUTOMATION_LIMITS.evalWork }): unknown {
+  return evalNode(e, scope, meter);
+}
+
+/** Evaluate a template: one expression keeps its type, a mix is text. */
+export function evalTemplate(t: Template, scope: Scope, meter: Meter = { left: AUTOMATION_LIMITS.evalWork }): unknown {
+  if (t.single) return evalNode(t.single, scope, meter);
+  let out = "";
+  for (const p of t.parts) {
+    out += typeof p === "string" ? p : toText(evalNode(p, scope, meter));
+    capText(out);
+  }
+  return out;
+}
+
+export interface ResolveOptions {
+  /** A whole-value expression with no value is a MappingError. */
+  strict?: boolean;
+  /** Shared across values so a step's work is bounded as a whole. */
+  meter?: Meter;
+}
+
+/** Resolve every `{{ }}` in a step's value (strings, lists, objects).
+ *  Keys are never templates. */
+export function resolveValue(value: unknown, scope: Scope, opts: ResolveOptions = {}): unknown {
+  const meter = opts.meter ?? { left: AUTOMATION_LIMITS.evalWork };
+  const walk = (v: unknown, depth: number): unknown => {
+    spend(meter);
+    if (depth > AUTOMATION_LIMITS.valueDepth + 2) throw new ExprError("that value nests too deep");
+    if (typeof v === "string") {
+      if (!v.includes("{{")) return v;
+      const tpl = parseTemplate(v);
+      const out = evalTemplate(tpl, scope, meter);
+      if (opts.strict && out === undefined) throw new MappingError(tpl.sources[0] ?? "a reference");
+      return out;
+    }
+    if (Array.isArray(v)) return v.map((x) => walk(x, depth + 1));
+    if (isObject(v)) {
+      const out: Record<string, unknown> = {};
+      for (const k of Object.keys(v)) {
+        if (BAD_KEYS.has(k)) continue;
+        out[k] = walk(v[k], depth + 1);
+      }
+      return out;
+    }
+    return v;
+  };
+  return walk(value, 0);
+}
+
+/** One expression of a step (`if`, `over`, `until`, `collect`), evaluated. */
+export function evalSingle(text: string, scope: Scope, opts: ResolveOptions = {}): unknown {
+  const meter = opts.meter ?? { left: AUTOMATION_LIMITS.evalWork };
+  return evalNode(parseSingle(text), scope, meter);
+}
+
+/* ------------------------------------------------------------------ */
+/* References                                                           */
+/* ------------------------------------------------------------------ */
+
+/** What an expression reads, for the save-time check: a root and the
+ *  static names after it (stops at the first computed bracket). */
+export interface Ref {
+  root: Root;
+  names: string[];
+  /** The path had a computed bracket after `names`. */
+  open: boolean;
+  /** The expression as the person wrote it. */
+  source: string;
+}
+
+function refsOfExpr(e: Expr, source: string, out: Ref[]): void {
+  switch (e.n) {
+    case "lit":
+      return;
+    case "path": {
+      const names: string[] = [];
+      let open = false;
+      for (const s of e.segs) {
+        if (s.k === "name") names.push(s.v);
+        else {
+          open = true;
+          refsOfExpr(s.e, source, out);
+          break;
+        }
+      }
+      out.push({ root: e.root, names, open, source });
+      return;
+    }
+    case "un":
+      return refsOfExpr(e.a, source, out);
+    case "get":
+      refsOfExpr(e.base, source, out);
+      for (const s of e.segs) if (s.k === "idx") refsOfExpr(s.e, source, out);
+      return;
+    case "bin":
+      refsOfExpr(e.a, source, out);
+      return refsOfExpr(e.b, source, out);
+    case "tern":
+      refsOfExpr(e.c, source, out);
+      refsOfExpr(e.a, source, out);
+      return refsOfExpr(e.b, source, out);
+    case "call":
+      for (const a of e.args) refsOfExpr(a, source, out);
+  }
+}
+
+/** Every reference in a template string. Throws ExprError. */
+export function refsOfText(text: string): Ref[] {
+  if (!text.includes("{{")) return [];
+  const tpl = parseTemplate(text);
+  const out: Ref[] = [];
+  tpl.parts.forEach((p) => {
+    if (typeof p !== "string") refsOfExpr(p, "{{ … }}", out);
+  });
+  return out;
+}
+
+/* ------------------------------------------------------------------ */
+/* Output shapes (A8: the save-time check)                              */
+/* ------------------------------------------------------------------ */
+
+/** The shape of a step's output, as far as a reference can be checked. */
+export type OutShape =
+  | { type: "any" }
+  | { type: "null" | "string" | "number" | "boolean" }
+  | { type: "array"; items: OutShape }
+  | { type: "object"; props: Record<string, OutShape>; open?: boolean };
+
+const ANY: OutShape = { type: "any" };
+const str: OutShape = { type: "string" };
+const numShape: OutShape = { type: "number" };
+const bool: OutShape = { type: "boolean" };
+const obj = (props: Record<string, OutShape>, open = false): OutShape => ({ type: "object", props, ...(open ? { open: true } : {}) });
+const arr = (items: OutShape = ANY): OutShape => ({ type: "array", items });
+
+/** A JSON Schema (the subset steps declare: type, properties, items) as a
+ *  shape. Anything it does not say is open. */
+export function shapeFromJsonSchema(schema: unknown, depth = 0): OutShape {
+  if (!isObject(schema) || depth > 8) return ANY;
+  const t = schema.type;
+  if (t === "object" || isObject(schema.properties)) {
+    const props: Record<string, OutShape> = {};
+    if (isObject(schema.properties)) {
+      for (const k of Object.keys(schema.properties)) if (!BAD_KEYS.has(k)) props[k] = shapeFromJsonSchema(schema.properties[k], depth + 1);
+    }
+    return obj(props, schema.additionalProperties !== false && Object.keys(props).length === 0 ? true : schema.additionalProperties === true);
+  }
+  if (t === "array") return arr(shapeFromJsonSchema(schema.items, depth + 1));
+  if (t === "string" || t === "number" || t === "boolean" || t === "null") return { type: t };
+  if (t === "integer") return numShape;
+  return ANY;
+}
+
+/** Walk `names` down a shape. Null: fine. Else the words for the miss. */
+export function checkShapePath(shape: OutShape, names: readonly string[]): string | null {
+  let cur: OutShape = shape;
+  for (let i = 0; i < names.length; i++) {
+    const name = names[i]!;
+    if (cur.type === "any") return null;
+    if (cur.type === "object") {
+      if (hasOwn(cur.props, name)) {
+        cur = cur.props[name]!;
+        continue;
+      }
+      if (cur.open) return null;
+      const known = Object.keys(cur.props);
+      return `has no "${name}"${known.length ? ` (it has ${known.slice(0, 8).join(", ")})` : ""}`;
+    }
+    if (cur.type === "array") {
+      if (name === "length") return i === names.length - 1 ? null : "length is a number";
+      return `is a list; use an index like [0] or list.map for "${name}"`;
+    }
+    if (cur.type === "string" && name === "length") return null;
+    return `is ${cur.type === "null" ? "empty" : `a ${cur.type}`}, so it has no "${name}"`;
+  }
+  return null;
+}
+
+/* ------------------------------------------------------------------ */
+/* Validation                                                           */
+/* ------------------------------------------------------------------ */
+
+export interface ValidateOptions {
+  /** The kinds this engine runs. Default: every kind the format names. */
+  kinds?: readonly StepKind[];
+  /** Extra check of a cron expression in a zone: a message, or null.
+   *  (The shape is checked here; cron-parser is the engine's.) */
+  cronCheck?: (cron: string, tz: string) => string | null;
+  /** The app's declared action names: an `action` step must name one.
+   *  Absent: not checked (a workspace automation names other apps). */
+  actionNames?: ReadonlySet<string> | null;
+  /** The output shape of an action by name (from its declaration). */
+  actionShape?: (name: string, app: string | undefined) => OutShape | null;
+}
+
+export type ValidateResult = { ok: true; automation: AutomationDef } | { ok: false; problems: Problem[] };
+
+const CRON_FIELD = /^[0-9*/,\-A-Za-z?LW#]+$/;
+
+/** Checks `tz` is a zone the runtime knows (or "team"). */
+function zoneOk(tz: string): boolean {
+  if (tz === "team") return true;
+  try {
+    new Intl.DateTimeFormat("en", { timeZone: tz });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const STEP_KEYS: Record<StepKind, readonly string[]> = {
+  action: ["action", "app", "input"],
+  "brain.read": ["op", "input"],
+  condition: ["if", "then", "else"],
+  loop: ["over", "max", "concurrency", "collect", "steps"],
+  set: ["values"],
+  wait: ["for", "until"],
+  stop: ["message", "as"],
+  notify: ["message", "to"],
+  tool: ["needs", "tool", "input", "account"],
+  search: ["query", "limit"],
+  llm: ["prompt", "system", "tier", "schema"],
+  agent: ["instructions", "cap_credits", "schema"],
+  zero: ["capability", "url", "method", "input", "max_pay_usd"],
+  automation: ["key", "input"],
+};
+const COMMON_KEYS = ["id", "kind", "label", "on_error", "retry"];
+
+interface Env {
+  /** Steps whose output a reference may read here, in order. */
+  steps: Map<string, OutShape>;
+  /** Inside a loop: item and index exist. */
+  itemShape: OutShape | null;
+  trigger: Trigger;
+  inputs: Record<string, InputSpec>;
+}
+
+class Validator {
+  problems: Problem[] = [];
+  private ids = new Set<string>();
+  private count = 0;
+  private readonly opts: ValidateOptions;
+  /** The key of the automation being validated, once read (a trigger may
+   *  not follow itself). */
+  private selfKey = "";
+
+  constructor(opts: ValidateOptions) {
+    this.opts = opts;
+  }
+
+  add(path: string, message: string): void {
+    if (this.problems.length < 60) this.problems.push({ path, message });
+  }
+
+  run(raw: unknown): AutomationDef | null {
+    if (!isObject(raw)) {
+      this.add("", "an automation is a JSON object");
+      return null;
+    }
+    this.allowKeys(raw, ["format", "key", "name", "does", "trigger", "inputs", "settings", "steps"], "");
+    if (raw.format !== AUTOMATION_FORMAT) this.add("format", `format must be ${AUTOMATION_FORMAT}`);
+    const key = this.text(raw.key, "key", 1, 60, true);
+    if (key && !AUTOMATION_KEY.test(key)) this.add("key", "key is lower case letters, digits and hyphens, starting with a letter");
+    this.selfKey = key ?? "";
+    const name = this.text(raw.name, "name", 1, AUTOMATION_LIMITS.nameChars, true);
+    const does = raw.does === undefined ? undefined : (this.text(raw.does, "does", 0, AUTOMATION_LIMITS.doesChars, false) ?? undefined);
+    const trigger = this.trigger(raw.trigger);
+    const inputs = this.inputs(raw.inputs);
+    // A schedule or a press waits its turn (skip); a trigger that is something
+    // HAPPENING must not lose it while a run is under way, so it queues.
+    const settings = this.settings(raw.settings, trigger && trigger.type !== "schedule" && trigger.type !== "manual" ? "queue" : "skip");
+    if (!Array.isArray(raw.steps) || raw.steps.length === 0) this.add("steps", "steps is a list with at least one step");
+
+    const env: Env = { steps: new Map(), itemShape: null, trigger: trigger ?? { type: "manual" }, inputs };
+    const steps = Array.isArray(raw.steps) ? this.steps(raw.steps, "steps", env, 1) : [];
+    if (this.problems.length || !key || !name || !trigger) return null;
+    return {
+      format: 1,
+      key,
+      name,
+      ...(does ? { does } : {}),
+      trigger,
+      inputs,
+      settings,
+      steps,
+    };
+  }
+
+  private allowKeys(o: Record<string, unknown>, allowed: readonly string[], path: string): void {
+    for (const k of Object.keys(o)) {
+      if (BAD_KEYS.has(k) || !allowed.includes(k)) this.add(path ? `${path}.${k}` : k, `"${k}" is not a field here (${allowed.join(", ")})`);
+    }
+  }
+
+  private text(v: unknown, path: string, min: number, max: number, required: boolean): string | null {
+    if (v === undefined || v === null) {
+      if (required) this.add(path, `${path.split(".").pop()} is required`);
+      return null;
+    }
+    if (typeof v !== "string") {
+      this.add(path, "must be text");
+      return null;
+    }
+    const t = v.trim();
+    if (t.length < min || (required && t.length === 0)) {
+      this.add(path, `${path.split(".").pop()} is required`);
+      return null;
+    }
+    if (t.length > max) {
+      this.add(path, `at most ${max} characters`);
+      return null;
+    }
+    return t;
+  }
+
+  private trigger(raw: unknown): Trigger | null {
+    if (!isObject(raw)) {
+      this.add("trigger", `trigger is required: { type: ${TRIGGER_TYPES.join(" | ")} }`);
+      return null;
+    }
+    const type = raw.type;
+    if (type === "schedule") {
+      this.allowKeys(raw, ["type", "cron", "tz"], "trigger");
+      const cron = this.text(raw.cron, "trigger.cron", 1, 100, true);
+      const tzRaw = raw.tz === undefined ? "team" : raw.tz;
+      let tz = "team";
+      if (typeof tzRaw !== "string" || !zoneOk(tzRaw)) this.add("trigger.tz", 'tz is "team" or a time zone like "Europe/London"');
+      else tz = tzRaw;
+      if (cron) {
+        const fields = cron.split(/\s+/);
+        if (fields.length !== 5 || !fields.every((f) => CRON_FIELD.test(f))) this.add("trigger.cron", "cron is five fields: minute hour day month weekday");
+        else {
+          const extra = this.opts.cronCheck?.(cron, tz);
+          if (extra) this.add("trigger.cron", extra);
+        }
+        return fields.length === 5 ? { type: "schedule", cron: fields.join(" "), tz } : null;
+      }
+      return null;
+    }
+    if (type === "manual") {
+      this.allowKeys(raw, ["type"], "trigger");
+      return { type: "manual" };
+    }
+    if (type === "event") {
+      this.allowKeys(raw, ["type", "topic", "app"], "trigger");
+      const topic = this.text(raw.topic, "trigger.topic", 1, 64, true);
+      if (topic && !EVENT_TOPIC.test(topic)) this.add("trigger.topic", "topic is a short dotted slug, like rows.imported");
+      const app = this.appName(raw.app);
+      return topic && EVENT_TOPIC.test(topic) ? { type: "event", topic, ...(app ? { app } : {}) } : null;
+    }
+    if (type === "action") {
+      this.allowKeys(raw, ["type", "action", "app"], "trigger");
+      const action = this.text(raw.action, "trigger.action", 1, 40, true);
+      if (action && !AUTOMATION_ID.test(action)) this.add("trigger.action", "action is the name of one of the app's declared actions");
+      else if (action && this.opts.actionNames && !this.opts.actionNames.has(action))
+        this.add("trigger.action", `this app declares no action "${action}" (it declares: ${[...this.opts.actionNames].slice(0, 12).join(", ") || "none"})`);
+      const app = this.appName(raw.app);
+      return action && AUTOMATION_ID.test(action) ? { type: "action", action, ...(app ? { app } : {}) } : null;
+    }
+    if (type === "record") {
+      this.allowKeys(raw, ["type", "kinds", "ops", "app"], "trigger");
+      let kinds: string[] | undefined;
+      if (raw.kinds !== undefined) {
+        if (!Array.isArray(raw.kinds) || raw.kinds.length === 0 || raw.kinds.length > 20 || !raw.kinds.every((k) => typeof k === "string" && BRAIN_KIND_NAME.test(k)))
+          this.add("trigger.kinds", "kinds is a list of up to 20 kind names (lower case, like contact), or leave it out for every kind");
+        else kinds = [...new Set(raw.kinds as string[])];
+      }
+      let ops: ("create" | "update")[] | undefined;
+      if (raw.ops !== undefined) {
+        if (!Array.isArray(raw.ops) || raw.ops.length === 0 || !raw.ops.every((o) => (RECORD_OPS as readonly unknown[]).includes(o)))
+          this.add("trigger.ops", `ops is a list of ${RECORD_OPS.join(" and/or ")}, or leave it out for both`);
+        else ops = [...new Set(raw.ops as ("create" | "update")[])];
+      }
+      const app = this.appName(raw.app);
+      return { type: "record", ...(kinds ? { kinds } : {}), ...(ops ? { ops } : {}), ...(app ? { app } : {}) };
+    }
+    if (type === "webhook") {
+      this.allowKeys(raw, ["type"], "trigger");
+      return { type: "webhook" };
+    }
+    if (type === "automation") {
+      this.allowKeys(raw, ["type", "key", "when"], "trigger");
+      const key = this.text(raw.key, "trigger.key", 1, 60, true);
+      if (key && !AUTOMATION_KEY.test(key)) this.add("trigger.key", "key names another automation: lower case letters, digits and hyphens");
+      let when: "done" | "failed" | "any" = "done";
+      if (raw.when !== undefined) {
+        if ((FINISH_WHEN as readonly unknown[]).includes(raw.when)) when = raw.when as typeof when;
+        else this.add("trigger.when", `when is one of ${FINISH_WHEN.join(", ")}`);
+      }
+      if (key && AUTOMATION_KEY.test(key) && this.selfKey && key === this.selfKey) this.add("trigger.key", "an automation cannot start itself: pick another automation to follow");
+      return key && AUTOMATION_KEY.test(key) ? { type: "automation", key, when } : null;
+    }
+    if (typeof type === "string" && hasOwn(REFUSED_TRIGGER_TYPES, type)) {
+      this.add("trigger.type", REFUSED_TRIGGER_TYPES[type]!);
+      return null;
+    }
+    this.add("trigger.type", `trigger type is one of ${TRIGGER_TYPES.join(", ")}`);
+    return null;
+  }
+
+  /** The app a trigger names (a workspace automation says whose events it
+   *  hears): its name or template key. */
+  private appName(raw: unknown): string | undefined {
+    if (raw === undefined) return undefined;
+    return this.text(raw, "trigger.app", 1, 80, false) ?? undefined;
+  }
+
+  private inputs(raw: unknown): Record<string, InputSpec> {
+    const out: Record<string, InputSpec> = {};
+    if (raw === undefined) return out;
+    if (!isObject(raw)) {
+      this.add("inputs", "inputs is an object of named inputs");
+      return out;
+    }
+    const names = Object.keys(raw);
+    if (names.length > AUTOMATION_LIMITS.inputs) this.add("inputs", `at most ${AUTOMATION_LIMITS.inputs} inputs`);
+    for (const n of names) {
+      const p = `inputs.${n}`;
+      if (!AUTOMATION_ID.test(n)) {
+        this.add(p, "an input's name is lower case letters, digits and underscores");
+        continue;
+      }
+      const spec = raw[n];
+      if (!isObject(spec)) {
+        this.add(p, "an input is { type, label?, required?, default?, options? }");
+        continue;
+      }
+      this.allowKeys(spec, ["type", "label", "required", "default", "options"], p);
+      const type = spec.type;
+      if (type !== "string" && type !== "number" && type !== "boolean" && type !== "date") {
+        this.add(`${p}.type`, "type is string, number, boolean or date");
+        continue;
+      }
+      const item: InputSpec = { type };
+      if (spec.label !== undefined) item.label = this.text(spec.label, `${p}.label`, 0, AUTOMATION_LIMITS.nameChars, false) ?? undefined;
+      if (spec.required !== undefined) {
+        if (typeof spec.required !== "boolean") this.add(`${p}.required`, "true or false");
+        else item.required = spec.required;
+      }
+      if (spec.default !== undefined) {
+        const d = spec.default;
+        if (typeof d === "string" || typeof d === "number" || typeof d === "boolean") item.default = d;
+        else this.add(`${p}.default`, "a text, number or true/false");
+      }
+      if (spec.options !== undefined) {
+        if (!Array.isArray(spec.options) || spec.options.length === 0 || spec.options.length > 30 || !spec.options.every((o) => typeof o === "string"))
+          this.add(`${p}.options`, "a list of up to 30 texts");
+        else item.options = spec.options as string[];
+      }
+      out[n] = item;
+    }
+    return out;
+  }
+
+  private settings(raw: unknown, overlap: "skip" | "queue" = "skip"): AutomationSettings {
+    const out: AutomationSettings = { overlap, on_failure: "retry_then_agent", only_if_changed: false };
+    if (raw === undefined) return out;
+    if (!isObject(raw)) {
+      this.add("settings", "settings is an object");
+      return out;
+    }
+    this.allowKeys(raw, ["overlap", "on_failure", "only_if_changed", "run_cap_credits", "max_per_hour"], "settings");
+    if (raw.overlap !== undefined) {
+      if ((OVERLAP_MODES as readonly unknown[]).includes(raw.overlap)) out.overlap = raw.overlap as AutomationSettings["overlap"];
+      else this.add("settings.overlap", `overlap is one of ${OVERLAP_MODES.join(", ")}`);
+    }
+    if (raw.on_failure !== undefined) {
+      if ((FAILURE_MODES as readonly unknown[]).includes(raw.on_failure)) out.on_failure = raw.on_failure as AutomationSettings["on_failure"];
+      else this.add("settings.on_failure", `on_failure is one of ${FAILURE_MODES.join(", ")}`);
+    }
+    if (raw.only_if_changed !== undefined) {
+      if (typeof raw.only_if_changed === "boolean") out.only_if_changed = raw.only_if_changed;
+      else this.add("settings.only_if_changed", "true or false");
+    }
+    if (raw.run_cap_credits !== undefined) {
+      if (typeof raw.run_cap_credits === "number" && Number.isFinite(raw.run_cap_credits) && raw.run_cap_credits >= 0 && raw.run_cap_credits <= 1_000_000)
+        out.run_cap_credits = raw.run_cap_credits;
+      else this.add("settings.run_cap_credits", "credits, from 0 to 1,000,000");
+    }
+    if (raw.max_per_hour !== undefined) {
+      if (typeof raw.max_per_hour === "number" && Number.isInteger(raw.max_per_hour) && raw.max_per_hour >= 1 && raw.max_per_hour <= 600) out.max_per_hour = raw.max_per_hour;
+      else this.add("settings.max_per_hour", "a whole number of runs an hour, from 1 to 600");
+    }
+    return out;
+  }
+
+  private steps(list: unknown[], path: string, env: Env, depth: number): Step[] {
+    const out: Step[] = [];
+    if (depth > AUTOMATION_LIMITS.depth) {
+      this.add(path, `steps nest at most ${AUTOMATION_LIMITS.depth} deep`);
+      return out;
+    }
+    // A step reads what came before it in this list and above; its own
+    // nested lists add nothing visible outside them.
+    const local: Env = { ...env, steps: new Map(env.steps) };
+    list.forEach((raw, i) => {
+      const p = `${path}[${i}]`;
+      const step = this.step(raw, p, local, depth);
+      if (step) out.push(step);
+    });
+    return out;
+  }
+
+  private step(raw: unknown, path: string, env: Env, depth: number): Step | null {
+    if (!isObject(raw)) {
+      this.add(path, "a step is an object");
+      return null;
+    }
+    if (++this.count > AUTOMATION_LIMITS.steps) {
+      if (this.count === AUTOMATION_LIMITS.steps + 1) this.add(path, `at most ${AUTOMATION_LIMITS.steps} steps in one automation`);
+      return null;
+    }
+    const id = typeof raw.id === "string" ? raw.id : "";
+    if (!AUTOMATION_ID.test(id)) this.add(`${path}.id`, "a step's id is lower case letters, digits and underscores, starting with a letter");
+    else if (this.ids.has(id)) this.add(`${path}.id`, `the id "${id}" is used twice; ids are unique in an automation`);
+    else this.ids.add(id);
+
+    const kind = raw.kind;
+    if (typeof kind === "string" && hasOwn(REFUSED_STEP_KINDS, kind)) {
+      this.add(`${path}.kind`, REFUSED_STEP_KINDS[kind]!);
+      return null;
+    }
+    if (typeof kind !== "string" || !(STEP_KINDS as readonly string[]).includes(kind)) {
+      this.add(`${path}.kind`, `kind is one of ${(this.opts.kinds ?? STEP_KINDS).join(", ")}`);
+      return null;
+    }
+    const k = kind as StepKind;
+    if (this.opts.kinds && !this.opts.kinds.includes(k)) {
+      this.add(`${path}.kind`, `${k} steps are not available yet (${this.opts.kinds.join(", ")} are)`);
+      return null;
+    }
+    this.allowKeys(raw, [...COMMON_KEYS, ...STEP_KEYS[k]], path);
+
+    const base: StepBase = { id };
+    if (raw.label !== undefined) {
+      const label = this.text(raw.label, `${path}.label`, 0, AUTOMATION_LIMITS.nameChars, false);
+      if (label) base.label = label;
+    }
+    if (raw.on_error !== undefined) {
+      if (raw.on_error === "stop" || raw.on_error === "continue") base.on_error = raw.on_error;
+      else this.add(`${path}.on_error`, 'on_error is "stop" or "continue"');
+    }
+    if (raw.retry !== undefined) {
+      const r = raw.retry;
+      if (isObject(r) && Object.keys(r).length === 1 && Number.isInteger(r.max) && (r.max as number) >= 0 && (r.max as number) <= AUTOMATION_LIMITS.retries)
+        base.retry = { max: r.max as number };
+      else this.add(`${path}.retry`, `retry is { max: 0 to ${AUTOMATION_LIMITS.retries} }`);
+    }
+
+    let step: Step | null = null;
+    let shape: OutShape = ANY;
+    switch (k) {
+      case "action": {
+        const action = typeof raw.action === "string" ? raw.action : "";
+        if (!/^[a-z][a-z0-9_]{0,39}$/.test(action)) this.add(`${path}.action`, "action names one of the app's declared actions");
+        else if (this.opts.actionNames && raw.app === undefined && !this.opts.actionNames.has(action))
+          this.add(`${path}.action`, `the app declares no action "${action}"${this.opts.actionNames.size ? ` (it declares ${[...this.opts.actionNames].slice(0, 10).join(", ")})` : ""}`);
+        let app: string | undefined;
+        if (raw.app !== undefined) app = this.text(raw.app, `${path}.app`, 1, 60, true) ?? undefined;
+        const input = this.value(raw.input, `${path}.input`, env, true);
+        const given = this.opts.actionShape?.(action, app);
+        shape =
+          given ??
+          obj({ ok: bool, action: str, result: ANY, records: ANY, created: numShape, changed: numShape });
+        step = { ...base, kind: "action", action, ...(app ? { app } : {}), ...(input ? { input: input as { [key: string]: StepValue } } : {}) };
+        break;
+      }
+      case "brain.read": {
+        const op = raw.op;
+        if (op !== "search" && op !== "get" && op !== "list") this.add(`${path}.op`, "op is search, get or list");
+        const input = this.value(raw.input, `${path}.input`, env, false);
+        if (!input || !isObject(input)) this.add(`${path}.input`, "input is an object (search: q; get: id; list: kind)");
+        shape =
+          op === "get"
+            ? obj({ ok: bool, brain: ANY, record: ANY })
+            : op === "list"
+              ? obj({ ok: bool, brain: ANY, records: arr(ANY), next: ANY })
+              : obj({ ok: bool, brain: ANY, meaning: ANY, results: arr(ANY) });
+        step = { ...base, kind: "brain.read", op: op as BrainReadStep["op"], input: (input ?? {}) as { [key: string]: StepValue } };
+        break;
+      }
+      case "condition": {
+        const cond = this.single(raw.if, `${path}.if`, env, true);
+        const hasThen = Array.isArray(raw.then) && raw.then.length > 0;
+        const hasElse = Array.isArray(raw.else) && raw.else.length > 0;
+        if (raw.then !== undefined && !Array.isArray(raw.then)) this.add(`${path}.then`, "then is a list of steps");
+        if (raw.else !== undefined && !Array.isArray(raw.else)) this.add(`${path}.else`, "else is a list of steps");
+        if (!hasThen && !hasElse) this.add(path, "a condition needs steps in then, else or both");
+        const thenSteps = hasThen ? this.steps(raw.then as unknown[], `${path}.then`, env, depth + 1) : undefined;
+        const elseSteps = hasElse ? this.steps(raw.else as unknown[], `${path}.else`, env, depth + 1) : undefined;
+        shape = obj({ taken: str });
+        step = { ...base, kind: "condition", if: cond ?? "", ...(thenSteps ? { then: thenSteps } : {}), ...(elseSteps ? { else: elseSteps } : {}) };
+        break;
+      }
+      case "loop": {
+        const over = this.single(raw.over, `${path}.over`, env, true);
+        let max: number = AUTOMATION_LIMITS.loopItems;
+        if (raw.max !== undefined) {
+          if (Number.isInteger(raw.max) && (raw.max as number) >= 1 && (raw.max as number) <= AUTOMATION_LIMITS.loopItems) max = raw.max as number;
+          else this.add(`${path}.max`, `max is a whole number from 1 to ${AUTOMATION_LIMITS.loopItems}`);
+        }
+        if (raw.concurrency !== undefined && raw.concurrency !== 1) this.add(`${path}.concurrency`, "a loop runs one item at a time (concurrency 1)");
+        // The item's shape: the list's items when `over` names a known list.
+        const itemShape = over ? this.itemShapeOf(over, env) : ANY;
+        const inner: Env = { ...env, itemShape };
+        if (!Array.isArray(raw.steps) || raw.steps.length === 0) this.add(`${path}.steps`, "a loop has steps");
+        const body = Array.isArray(raw.steps) ? this.steps(raw.steps, `${path}.steps`, inner, depth + 1) : [];
+        let collect: string | undefined;
+        if (raw.collect !== undefined) {
+          // Read what the loop's last pass made: the body's steps are visible.
+          const bodyEnv = this.afterBody(inner, body);
+          collect = this.single(raw.collect, `${path}.collect`, bodyEnv, true) ?? undefined;
+        }
+        shape = obj({ count: numShape, collected: arr(ANY) });
+        step = { ...base, kind: "loop", over: over ?? "", max, ...(collect ? { collect } : {}), steps: body };
+        break;
+      }
+      case "set": {
+        const values = this.value(raw.values, `${path}.values`, env, false);
+        const props: Record<string, OutShape> = {};
+        if (!values || !isObject(values) || Object.keys(values).length === 0) this.add(`${path}.values`, "values is an object with at least one value");
+        else {
+          for (const key of Object.keys(values)) {
+            if (!AUTOMATION_ID.test(key)) this.add(`${path}.values.${key}`, "a value's name is lower case letters, digits and underscores");
+            props[key] = ANY;
+          }
+        }
+        shape = obj(props);
+        step = { ...base, kind: "set", values: (values ?? {}) as { [key: string]: StepValue } };
+        break;
+      }
+      case "wait": {
+        const hasFor = raw.for !== undefined;
+        const hasUntil = raw.until !== undefined;
+        if (hasFor === hasUntil) this.add(path, "a wait has either for (a duration like 10m) or until (a time)");
+        let forText: string | undefined;
+        if (hasFor) {
+          const ms = durationMs(raw.for);
+          if (ms === null) this.add(`${path}.for`, "for is a duration: a number and s, m, h or d (30s, 10m, 2h, 3d)");
+          else if (ms > WAIT_MAX_MS) this.add(`${path}.for`, "a wait is at most 30 days");
+          else forText = raw.for as string;
+        }
+        const until = hasUntil ? this.single(raw.until, `${path}.until`, env, true) : null;
+        shape = obj({ waited_until: str });
+        step = { ...base, kind: "wait", ...(forText ? { for: forText } : {}), ...(until ? { until } : {}) };
+        break;
+      }
+      case "stop": {
+        const message = this.templated(raw.message, `${path}.message`, env, true);
+        if (raw.as !== undefined && raw.as !== "done" && raw.as !== "failed") this.add(`${path}.as`, 'as is "done" or "failed"');
+        shape = obj({ message: str, as: str });
+        step = { ...base, kind: "stop", message: message ?? "", ...(raw.as === "failed" ? { as: "failed" as const } : raw.as === "done" ? { as: "done" as const } : {}) };
+        break;
+      }
+      case "notify": {
+        const message = this.templated(raw.message, `${path}.message`, env, true);
+        if (raw.to !== undefined && raw.to !== "owner") this.add(`${path}.to`, 'to is "owner"');
+        shape = obj({ delivered: bool });
+        step = { ...base, kind: "notify", message: message ?? "", ...(raw.to === "owner" ? { to: "owner" as const } : {}) };
+        break;
+      }
+      case "tool": {
+        const needs = raw.needs;
+        const category = isObject(needs) && typeof needs.category === "string" ? needs.category : "";
+        if (!/^[a-z][a-z0-9_-]{0,40}$/.test(category)) this.add(`${path}.needs`, "needs is { category: the kind of account, like mail }");
+        const tool = this.text(raw.tool, `${path}.tool`, 1, 100, true);
+        const input = this.value(raw.input, `${path}.input`, env, true);
+        const account = raw.account === undefined ? undefined : (this.text(raw.account, `${path}.account`, 1, 100, true) ?? undefined);
+        step = { ...base, kind: "tool", needs: { category }, tool: tool ?? "", ...(input ? { input: input as { [key: string]: StepValue } } : {}), ...(account ? { account } : {}) };
+        break;
+      }
+      case "search": {
+        const query = this.templated(raw.query, `${path}.query`, env, true);
+        if (raw.limit !== undefined && !(Number.isInteger(raw.limit) && (raw.limit as number) >= 1 && (raw.limit as number) <= 20)) this.add(`${path}.limit`, "limit is 1 to 20");
+        shape = obj({ results: arr(ANY) });
+        step = { ...base, kind: "search", query: query ?? "", ...(Number.isInteger(raw.limit) ? { limit: raw.limit as number } : {}) };
+        break;
+      }
+      case "llm": {
+        const prompt = this.templated(raw.prompt, `${path}.prompt`, env, true);
+        const system = raw.system === undefined ? undefined : (this.templated(raw.system, `${path}.system`, env, false) ?? undefined);
+        if (raw.tier !== undefined && raw.tier !== "fast" && raw.tier !== "smart") this.add(`${path}.tier`, 'tier is "fast" or "smart"');
+        let schema: Record<string, unknown> | undefined;
+        if (raw.schema !== undefined) {
+          if (!isObject(raw.schema) || canonicalJson(raw.schema).length > 16_000) this.add(`${path}.schema`, "schema is a JSON Schema object, up to 16 KB");
+          else schema = raw.schema;
+        }
+        shape = schema ? obj({ data: shapeFromJsonSchema(schema), text: str }) : obj({ text: str });
+        step = { ...base, kind: "llm", prompt: prompt ?? "", ...(system ? { system } : {}), ...(raw.tier === "fast" || raw.tier === "smart" ? { tier: raw.tier } : {}), ...(schema ? { schema } : {}) };
+        break;
+      }
+      case "agent": {
+        const instructions = this.templated(raw.instructions, `${path}.instructions`, env, true);
+        if (raw.cap_credits !== undefined && !(typeof raw.cap_credits === "number" && raw.cap_credits > 0 && raw.cap_credits <= 100_000)) this.add(`${path}.cap_credits`, "cap_credits is a number of credits, up to 100,000");
+        let schema: Record<string, unknown> | undefined;
+        if (raw.schema !== undefined) {
+          if (!isObject(raw.schema) || canonicalJson(raw.schema).length > 16_000) this.add(`${path}.schema`, "schema is a JSON Schema object, up to 16 KB");
+          else schema = raw.schema;
+        }
+        shape = schema ? shapeFromJsonSchema(schema) : ANY;
+        step = { ...base, kind: "agent", instructions: instructions ?? "", ...(typeof raw.cap_credits === "number" ? { cap_credits: raw.cap_credits } : {}), ...(schema ? { schema } : {}) };
+        break;
+      }
+      case "zero": {
+        const capability = this.text(raw.capability, `${path}.capability`, 1, 200, true);
+        const url = this.templated(raw.url, `${path}.url`, env, true);
+        if (url && !url.trimStart().startsWith("{{") && !/^https:\/\/[^\s/]+/i.test(url.trim())) this.add(`${path}.url`, "url is the capability's own address, starting with https://");
+        if (raw.method !== undefined && !(ZERO_STEP_METHODS as readonly unknown[]).includes(raw.method)) this.add(`${path}.method`, `method is ${ZERO_STEP_METHODS.join(", ")}`);
+        const input = this.value(raw.input, `${path}.input`, env, true);
+        const pay = raw.max_pay_usd;
+        if (!(typeof pay === "number" && Number.isFinite(pay) && pay > 0 && pay <= ZERO_STEP_MAX_PAY_USD)) this.add(`${path}.max_pay_usd`, `max_pay_usd is the most one call may pay, in USD: above 0, at most ${ZERO_STEP_MAX_PAY_USD}`);
+        shape = obj({ ok: bool, paid_usd: numShape, cached: bool, body: ANY });
+        step = {
+          ...base,
+          kind: "zero",
+          capability: capability ?? "",
+          url: url?.trim() ?? "",
+          ...(raw.method === "GET" || raw.method === "POST" || raw.method === "PUT" || raw.method === "PATCH" ? { method: raw.method } : {}),
+          ...(input ? { input: input as { [key: string]: StepValue } } : {}),
+          max_pay_usd: typeof pay === "number" ? pay : 0,
+        };
+        break;
+      }
+      case "automation": {
+        const key = typeof raw.key === "string" ? raw.key : "";
+        if (!AUTOMATION_KEY.test(key)) this.add(`${path}.key`, "key names another automation");
+        const input = this.value(raw.input, `${path}.input`, env, true);
+        step = { ...base, kind: "automation", key, ...(input ? { input: input as { [key: string]: StepValue } } : {}) };
+        break;
+      }
+    }
+    if (AUTOMATION_ID.test(id)) env.steps.set(id, shape);
+    return step;
+  }
+
+  /** The steps a loop's `collect` may read: the loop's body, in order. */
+  private afterBody(env: Env, body: Step[]): Env {
+    const steps = new Map(env.steps);
+    for (const s of body) steps.set(s.id, ANY);
+    return { ...env, steps };
+  }
+
+  private itemShapeOf(over: string, env: Env): OutShape {
+    try {
+      const e = parseSingle(over);
+      if (e.n !== "path") return ANY;
+      const ref: Ref[] = [];
+      refsOfExpr(e, over, ref);
+      const r = ref[0];
+      if (!r || r.open || r.root !== "steps" || r.names.length < 2) return ANY;
+      const shape = env.steps.get(r.names[0]!);
+      if (!shape || r.names[1] !== "output") return ANY;
+      let cur: OutShape = shape;
+      for (const n of r.names.slice(2)) {
+        if (cur.type === "object" && hasOwn(cur.props, n)) cur = cur.props[n]!;
+        else return ANY;
+      }
+      return cur.type === "array" ? cur.items : ANY;
+    } catch {
+      return ANY;
+    }
+  }
+
+  /** A step's expression field: one expression, checked against `env`. */
+  private single(v: unknown, path: string, env: Env, required: boolean): string | null {
+    if (v === undefined || v === null || v === "") {
+      if (required) this.add(path, `${path.split(".").pop()} is required`);
+      return null;
+    }
+    if (typeof v !== "string") {
+      this.add(path, "must be an expression like {{ steps.read.output.items }}");
+      return null;
+    }
+    if (v.length > AUTOMATION_LIMITS.expressionChars + 4) {
+      this.add(path, `an expression is at most ${AUTOMATION_LIMITS.expressionChars} characters`);
+      return null;
+    }
+    try {
+      const e = parseSingle(v);
+      const refs: Ref[] = [];
+      refsOfExpr(e, v, refs);
+      for (const r of refs) this.checkRef(r, path, env);
+    } catch (error) {
+      if (error instanceof ExprError) {
+        this.add(path, error.message);
+        return null;
+      }
+      throw error;
+    }
+    return v.trim();
+  }
+
+  /** A text that may hold {{ expressions }}. */
+  private templated(v: unknown, path: string, env: Env, required: boolean): string | null {
+    if (v === undefined || v === null || v === "") {
+      if (required) this.add(path, `${path.split(".").pop()} is required`);
+      return null;
+    }
+    if (typeof v !== "string") {
+      this.add(path, "must be text");
+      return null;
+    }
+    if (v.length > AUTOMATION_LIMITS.messageChars * 4) {
+      this.add(path, "that text is too long");
+      return null;
+    }
+    this.checkText(v, path, env);
+    return v;
+  }
+
+  private checkText(text: string, path: string, env: Env): void {
+    try {
+      for (const r of refsOfText(text)) this.checkRef(r, path, env);
+    } catch (error) {
+      if (error instanceof ExprError) this.add(path, error.message);
+      else throw error;
+    }
+  }
+
+  /** A step's value (`input`, `values`): JSON, templates checked. */
+  private value(v: unknown, path: string, env: Env, optional: boolean): Record<string, unknown> | null {
+    if (v === undefined) {
+      if (!optional) this.add(path, "required");
+      return null;
+    }
+    if (!isObject(v)) {
+      this.add(path, "must be an object");
+      return null;
+    }
+    const budget = { n: 0 };
+    const clean = this.jsonValue(v, path, env, 0, budget);
+    return isObject(clean) ? clean : null;
+  }
+
+  private jsonValue(v: unknown, path: string, env: Env, depth: number, budget: { n: number }): unknown {
+    if (++budget.n > 2000) {
+      if (budget.n === 2001) this.add(path, "that value is too large");
+      return null;
+    }
+    if (depth > AUTOMATION_LIMITS.valueDepth) {
+      this.add(path, `values nest at most ${AUTOMATION_LIMITS.valueDepth} deep`);
+      return null;
+    }
+    if (v === null || typeof v === "boolean") return v;
+    if (typeof v === "number") {
+      if (!Number.isFinite(v)) this.add(path, "numbers must be finite");
+      return v;
+    }
+    if (typeof v === "string") {
+      if (v.length > 20_000) this.add(path, "that text is too long");
+      else this.checkText(v, path, env);
+      return v;
+    }
+    if (Array.isArray(v)) return v.map((x, i) => this.jsonValue(x, `${path}[${i}]`, env, depth + 1, budget));
+    if (isObject(v)) {
+      const keys = Object.keys(v);
+      if (keys.length > AUTOMATION_LIMITS.valueKeys) this.add(path, `at most ${AUTOMATION_LIMITS.valueKeys} keys in one object`);
+      const out: Record<string, unknown> = {};
+      for (const k of keys.slice(0, AUTOMATION_LIMITS.valueKeys)) {
+        if (BAD_KEYS.has(k)) {
+          this.add(`${path}.${k}`, `"${k}" cannot be a name`);
+          continue;
+        }
+        out[k] = this.jsonValue(v[k], `${path}.${k}`, env, depth + 1, budget);
+      }
+      return out;
+    }
+    this.add(path, "only JSON values (text, numbers, true/false, null, lists, objects)");
+    return null;
+  }
+
+  /** The save-time check of one reference (A8). */
+  private checkRef(r: Ref, path: string, env: Env): void {
+    const say = (message: string) => this.add(path, message);
+    switch (r.root) {
+      case "steps": {
+        const id = r.names[0];
+        if (id === undefined) return say('"steps" needs a step: steps.<id>.output');
+        const shape = env.steps.get(id);
+        if (!shape) {
+          const known = [...env.steps.keys()];
+          return say(`steps.${id} is not a step that comes before this one${known.length ? ` (earlier: ${known.slice(-6).join(", ")})` : ""}. A step inside another branch or loop is not readable outside it`);
+        }
+        if (r.names.length === 1) return say(`steps.${id} needs a field: steps.${id}.output`);
+        if (r.names[1] !== "output") return say(`read a step's data as steps.${id}.output, not steps.${id}.${r.names[1]}`);
+        const miss = checkShapePath(shape, r.names.slice(2));
+        if (miss) say(`steps.${r.names.join(".")}: the output of "${id}" ${miss}`);
+        return;
+      }
+      case "item":
+      case "index":
+        if (!env.itemShape) return say(`"${r.root}" only exists inside a loop`);
+        if (r.root === "item") {
+          const miss = checkShapePath(env.itemShape, r.names);
+          if (miss) say(`item ${miss}`);
+        }
+        return;
+      case "inputs": {
+        const name = r.names[0];
+        if (name !== undefined && !hasOwn(env.inputs, name)) say(`inputs.${name} is not an input of this automation${Object.keys(env.inputs).length ? ` (it has ${Object.keys(env.inputs).join(", ")})` : " (it has none)"}`);
+        return;
+      }
+      case "run": {
+        const name = r.names[0];
+        if (name !== undefined && !["id", "started_at", "tz", "key", "attempt"].includes(name)) say(`run.${name} is not known (run.id, run.started_at, run.tz, run.key)`);
+        return;
+      }
+      default:
+        return;
+    }
+  }
+}
+
+/**
+ * Check a definition against every rule of the format. On success, the
+ * normalised definition (defaults filled, only known fields kept); else
+ * every problem, each naming where.
+ */
+export function validateAutomation(raw: unknown, opts: ValidateOptions = {}): ValidateResult {
+  const v = new Validator(opts);
+  let automation: AutomationDef | null = null;
+  try {
+    automation = v.run(raw);
+  } catch (error) {
+    if (error instanceof ExprError) v.add("", error.message);
+    else throw error;
+  }
+  if (v.problems.length || !automation) return { ok: false, problems: v.problems.length ? v.problems : [{ path: "", message: "not a valid automation" }] };
+  return { ok: true, automation };
+}
+
+/** Problems as one line each, for a refusal's text. */
+export function problemLines(problems: readonly Problem[], max = 8): string[] {
+  return problems.slice(0, max).map((p) => (p.path ? `${p.path}: ${p.message}` : p.message));
+}
+
+/** Every step of a list, nested ones included, with where it sits. */
+export function walkSteps(steps: readonly Step[], visit: (step: Step, parent: Step | null) => void, parent: Step | null = null): void {
+  for (const s of steps) {
+    visit(s, parent);
+    if (s.kind === "condition") {
+      if (s.then) walkSteps(s.then, visit, s);
+      if (s.else) walkSteps(s.else, visit, s);
+    } else if (s.kind === "loop") walkSteps(s.steps, visit, s);
+  }
+}
+
+/** How many steps, nested ones included. */
+export function stepCount(steps: readonly Step[]): number {
+  let n = 0;
+  walkSteps(steps, () => n++);
+  return n;
+}
+
+/* ------------------------------------------------------------------ */
+/* One automation starting another (phase 7)                            */
+/* ------------------------------------------------------------------ */
+
+/** One automation as the cycle check sees it: its key, the automation whose
+ *  finish starts it (its `automation` trigger), and the ones its own
+ *  `automation` steps call. */
+export interface StartsNode {
+  key: string;
+  follows: string | null;
+  calls: readonly string[];
+}
+
+export function startsNodeOf(def: Pick<AutomationDef, "key" | "trigger" | "steps">): StartsNode {
+  const calls: string[] = [];
+  walkSteps(def.steps, (s) => {
+    if (s.kind === "automation" && !calls.includes(s.key)) calls.push(s.key);
+  });
+  return { key: def.key, follows: def.trigger.type === "automation" ? def.trigger.key : null, calls };
+}
+
+/**
+ * A loop in "who starts whom", or null. X starts Y when Y's trigger follows X
+ * or X's steps call Y. Returns the keys round the loop, first key repeated
+ * last (`["a", "b", "a"]`), so the refusal can say it in words. A key no node
+ * has is an automation that is not there (yet): not a loop.
+ */
+export function findStartCycle(nodes: readonly StartsNode[]): string[] | null {
+  const byKey = new Map<string, StartsNode>();
+  for (const n of nodes) byKey.set(n.key, n);
+  const starts = new Map<string, string[]>();
+  const add = (from: string, to: string) => {
+    if (!byKey.has(from) || !byKey.has(to)) return;
+    const list = starts.get(from) ?? [];
+    if (!list.includes(to)) list.push(to);
+    starts.set(from, list);
+  };
+  for (const n of nodes) {
+    if (n.follows) add(n.follows, n.key);
+    for (const c of n.calls) add(n.key, c);
+  }
+  const state = new Map<string, 1 | 2>();
+  const stack: string[] = [];
+  const visit = (k: string): string[] | null => {
+    state.set(k, 1);
+    stack.push(k);
+    for (const next of starts.get(k) ?? []) {
+      if (state.get(next) === 1) return [...stack.slice(stack.indexOf(next)), next];
+      if (!state.has(next)) {
+        const found = visit(next);
+        if (found) return found;
+      }
+    }
+    stack.pop();
+    state.set(k, 2);
+    return null;
+  };
+  for (const n of nodes) if (!state.has(n.key)) {
+    const found = visit(n.key);
+    if (found) return found;
+  }
+  return null;
+}