@objectstack/service-automation 7.4.1 → 7.6.0

package/dist/index.js

@@ -1,7 +1,7 @@
 // src/engine.ts
-import { FlowSchema, FLOW_STRUCTURAL_NODE_TYPES } from "@objectstack/spec/automation";
+import { FlowSchema, FLOW_STRUCTURAL_NODE_TYPES, validateControlFlow, findRegionEntry, defineActionDescriptor } from "@objectstack/spec/automation";
 import { ConnectorSchema } from "@objectstack/spec/integration";
-import { ExpressionEngine } from "@objectstack/formula";
+import { ExpressionEngine, validateExpression } from "@objectstack/formula";
 var FlowSuspendSignal = class {
   constructor(nodeId, correlation, screen) {
     this.nodeId = nodeId;
@@ -14,7 +14,7 @@ function isSuspendSignal(err) {
   return typeof err === "object" && err !== null && err.__flowSuspend === true;
 }
 var AutomationEngine = class {
-  constructor(logger) {
+  constructor(logger, store) {
     this.flows = /* @__PURE__ */ new Map();
     this.flowEnabled = /* @__PURE__ */ new Map();
     this.flowVersionHistory = /* @__PURE__ */ new Map();
@@ -31,10 +31,74 @@ var AutomationEngine = class {
     this.connectors = /* @__PURE__ */ new Map();
     this.executionLogs = [];
     this.maxLogSize = 1e3;
-    this.runCounter = 0;
-    /** Runs paused at a node, keyed by runId (ADR-0019). In-memory, see {@link SuspendedRun}. */
+    /**
+     * Runs paused at a node, keyed by runId (ADR-0019). In-memory hot cache —
+     * mirrored to {@link store} when one is configured, so a pause survives a
+     * process restart. See {@link SuspendedRun}.
+     */
     this.suspendedRuns = /* @__PURE__ */ new Map();
+    /**
+     * Run ids currently mid-resume — an in-process idempotency guard so a
+     * duplicate `resume(runId)` can't re-enter and double-run side effects.
+     */
+    this.resuming = /* @__PURE__ */ new Set();
     this.logger = logger;
+    this.store = store;
+  }
+  /**
+   * Attach (or replace) the durable {@link SuspendedRunStore}. Used by the
+   * service plugin to upgrade the engine to DB-backed persistence once the
+   * ObjectQL engine is available (the engine is constructed earlier, during
+   * `init`, before services are wired).
+   */
+  setSuspendedRunStore(store) {
+    this.store = store;
+  }
+  /**
+   * Generate a process-unique run id. Includes a random component so ids do
+   * not collide with runs persisted by a previous process lifetime (a plain
+   * incrementing counter would reissue `run_1` after a restart, clashing with
+   * a still-suspended durable run).
+   */
+  nextRunId() {
+    const g = globalThis;
+    const rand = g.crypto?.randomUUID ? g.crypto.randomUUID() : `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
+    return `run_${rand}`;
+  }
+  /**
+   * Persist a suspended run to the in-memory cache and (best-effort) the
+   * durable store. A store failure is logged but does not fail the run — the
+   * in-memory copy still allows in-process resume; only cross-restart
+   * durability is lost.
+   */
+  async persistSuspendedRun(run) {
+    this.suspendedRuns.set(run.runId, run);
+    if (this.store) {
+      try {
+        await this.store.save(run);
+      } catch (err) {
+        this.logger.warn(
+          `[automation] failed to persist suspended run '${run.runId}' to durable store (kept in memory only): ${err.message}`
+        );
+      }
+    }
+  }
+  /**
+   * Drop a suspended run from the in-memory cache and (best-effort) the
+   * durable store. Called once the run is claimed for resume or reaches a
+   * terminal state.
+   */
+  async forgetSuspendedRun(runId) {
+    this.suspendedRuns.delete(runId);
+    if (this.store) {
+      try {
+        await this.store.delete(runId);
+      } catch (err) {
+        this.logger.warn(
+          `[automation] failed to delete suspended run '${runId}' from durable store: ${err.message}`
+        );
+      }
+    }
   }
   // ── Plugin Extension API ──────────────────────────────
   /** Register a node executor (called by plugins) */
@@ -54,6 +118,58 @@ var AutomationEngine = class {
     }
     this.logger.info(`Node executor registered: ${executor.type}`);
   }
+  /**
+   * Register a **deprecated alias** of a canonical node type (ADR-0018 M3).
+   *
+   * The alias is a real registered executor, so old saved flows whose nodes
+   * use the alias type keep validating and running with no migration. At
+   * execute time it delegates to the canonical executor (resolved live, so the
+   * canonical may be registered before or after the alias), logging a one-time
+   * deprecation warning. Its published descriptor is flagged `deprecated` +
+   * `aliasOf` so the designer palette can hide or mark it while the canonical
+   * type is the one offered for new authoring.
+   *
+   * This is how ADR-0018 collapses the five outbound verbs onto `http` /
+   * `notify`: `http_request` / `http_call` / `webhook` become aliases of
+   * `http`.
+   */
+  registerNodeAlias(alias, canonicalType, meta) {
+    const engine = this;
+    let warned = false;
+    this.registerNodeExecutor({
+      type: alias,
+      descriptor: defineActionDescriptor({
+        type: alias,
+        version: "1.0.0",
+        name: meta?.name ?? alias,
+        description: `Deprecated alias of '${canonicalType}' (ADR-0018 M3). Author new flows with '${canonicalType}'.`,
+        category: meta?.category ?? "io",
+        source: "builtin",
+        paradigms: meta?.paradigms ?? ["flow", "workflow_rule", "approval"],
+        supportsRetry: true,
+        needsOutbox: meta?.needsOutbox ?? false,
+        deprecated: true,
+        aliasOf: canonicalType
+      }),
+      async execute(node, variables, context) {
+        if (!warned) {
+          warned = true;
+          engine.logger.warn(
+            `Node type '${alias}' is deprecated; use '${canonicalType}' (ADR-0018 M3). Existing flows keep running via the alias.`
+          );
+        }
+        const target = engine.nodeExecutors.get(canonicalType);
+        if (!target) {
+          return {
+            success: false,
+            error: `alias '${alias}' \u2192 '${canonicalType}': canonical executor not registered`
+          };
+        }
+        return target.execute(node, variables, context);
+      }
+    });
+    this.logger.info(`Node alias registered: ${alias} \u2192 ${canonicalType} (deprecated)`);
+  }
   /** Unregister a node executor (hot-unplug) */
   unregisterNodeExecutor(type) {
     const executor = this.nodeExecutors.get(type);
@@ -245,7 +361,9 @@ var AutomationEngine = class {
   registerFlow(name, definition) {
     const parsed = FlowSchema.parse(definition);
     this.detectCycles(parsed);
+    validateControlFlow(parsed);
     this.validateNodeTypes(name, parsed);
+    this.validateFlowExpressions(name, parsed);
     const history = this.flowVersionHistory.get(name) ?? [];
     history.push({
       version: parsed.version,
@@ -340,7 +458,7 @@ var AutomationEngine = class {
     if (context?.previous) {
       variables.set("previous", context.previous);
     }
-    const runId = `run_${++this.runCounter}`;
+    const runId = this.nextRunId();
     variables.set("$runId", runId);
     const startedAt = (/* @__PURE__ */ new Date()).toISOString();
     const steps = [];
@@ -392,7 +510,7 @@ var AutomationEngine = class {
     } catch (err) {
       if (isSuspendSignal(err)) {
         const durationMs2 = Date.now() - startTime;
-        this.suspendedRuns.set(runId, {
+        await this.persistSuspendedRun({
           runId,
           flowName,
           flowVersion: flow.version,
@@ -464,109 +582,131 @@ var AutomationEngine = class {
    * returns `{ status: 'paused', runId }` afresh.
    */
   async resume(runId, signal) {
-    const run = this.suspendedRuns.get(runId);
-    if (!run) {
-      return { success: false, error: `No suspended run '${runId}'` };
-    }
-    const flow = this.flows.get(run.flowName);
-    if (!flow) {
-      return { success: false, error: `Flow '${run.flowName}' not found for run '${runId}'` };
-    }
-    const node = flow.nodes.find((n) => n.id === run.nodeId);
-    if (!node) {
-      return { success: false, error: `Suspended node '${run.nodeId}' no longer exists in flow '${run.flowName}'` };
+    if (this.resuming.has(runId)) {
+      return { success: false, error: `Run '${runId}' is already being resumed` };
     }
-    this.suspendedRuns.delete(runId);
-    const variables = new Map(Object.entries(run.variables));
-    if (signal?.output) {
-      for (const [key, value] of Object.entries(signal.output)) {
-        variables.set(`${run.nodeId}.${key}`, value);
+    this.resuming.add(runId);
+    try {
+      let run = this.suspendedRuns.get(runId) ?? null;
+      if (!run && this.store) {
+        try {
+          run = await this.store.load(runId);
+        } catch (err) {
+          this.logger.warn(
+            `[automation] failed to load suspended run '${runId}' from durable store: ${err.message}`
+          );
+        }
       }
-    }
-    if (signal?.variables) {
-      for (const [key, value] of Object.entries(signal.variables)) {
-        variables.set(key, value);
+      if (!run) {
+        return { success: false, error: `No suspended run '${runId}'` };
       }
-    }
-    const steps = run.steps;
-    const context = run.context;
-    try {
-      await this.traverseNext(node, flow, variables, context, steps, signal?.branchLabel);
-      const output = {};
-      if (flow.variables) {
-        for (const v of flow.variables) {
-          if (v.isOutput) output[v.name] = variables.get(v.name);
+      const flow = this.flows.get(run.flowName);
+      if (!flow) {
+        return { success: false, error: `Flow '${run.flowName}' not found for run '${runId}'` };
+      }
+      const node = flow.nodes.find((n) => n.id === run.nodeId);
+      if (!node) {
+        return { success: false, error: `Suspended node '${run.nodeId}' no longer exists in flow '${run.flowName}'` };
+      }
+      await this.forgetSuspendedRun(runId);
+      const variables = new Map(Object.entries(run.variables));
+      if (signal?.output) {
+        for (const [key, value] of Object.entries(signal.output)) {
+          variables.set(`${run.nodeId}.${key}`, value);
         }
       }
-      const durationMs = Date.now() - run.startTime;
-      this.recordLog({
-        id: runId,
-        flowName: run.flowName,
-        flowVersion: run.flowVersion,
-        status: "completed",
-        startedAt: run.startedAt,
-        completedAt: (/* @__PURE__ */ new Date()).toISOString(),
-        durationMs,
-        trigger: {
-          type: context.event ?? "manual",
-          userId: context.userId,
-          object: context.object
-        },
-        steps,
-        output
-      });
-      return { success: true, output, durationMs };
-    } catch (err) {
-      if (isSuspendSignal(err)) {
-        const durationMs2 = Date.now() - run.startTime;
-        this.suspendedRuns.set(runId, {
-          ...run,
-          nodeId: err.nodeId,
-          variables: Object.fromEntries(variables),
+      if (signal?.variables) {
+        for (const [key, value] of Object.entries(signal.variables)) {
+          variables.set(key, value);
+        }
+      }
+      const steps = run.steps;
+      const context = run.context;
+      try {
+        await this.traverseNext(node, flow, variables, context, steps, signal?.branchLabel);
+        const output = {};
+        if (flow.variables) {
+          for (const v of flow.variables) {
+            if (v.isOutput) output[v.name] = variables.get(v.name);
+          }
+        }
+        const durationMs = Date.now() - run.startTime;
+        this.recordLog({
+          id: runId,
+          flowName: run.flowName,
+          flowVersion: run.flowVersion,
+          status: "completed",
+          startedAt: run.startedAt,
+          completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          durationMs,
+          trigger: {
+            type: context.event ?? "manual",
+            userId: context.userId,
+            object: context.object
+          },
           steps,
-          correlation: err.correlation,
-          screen: err.screen
+          output
         });
+        return { success: true, output, durationMs };
+      } catch (err) {
+        if (isSuspendSignal(err)) {
+          const durationMs2 = Date.now() - run.startTime;
+          await this.persistSuspendedRun({
+            ...run,
+            nodeId: err.nodeId,
+            variables: Object.fromEntries(variables),
+            steps,
+            correlation: err.correlation,
+            screen: err.screen
+          });
+          this.recordLog({
+            id: runId,
+            flowName: run.flowName,
+            flowVersion: run.flowVersion,
+            status: "paused",
+            startedAt: run.startedAt,
+            durationMs: durationMs2,
+            trigger: {
+              type: context.event ?? "manual",
+              userId: context.userId,
+              object: context.object
+            },
+            steps
+          });
+          return { success: true, status: "paused", runId, durationMs: durationMs2, screen: err.screen };
+        }
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        const durationMs = Date.now() - run.startTime;
         this.recordLog({
           id: runId,
           flowName: run.flowName,
           flowVersion: run.flowVersion,
-          status: "paused",
+          status: "failed",
           startedAt: run.startedAt,
-          durationMs: durationMs2,
+          completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          durationMs,
           trigger: {
             type: context.event ?? "manual",
             userId: context.userId,
             object: context.object
           },
-          steps
+          steps,
+          error: errorMessage
         });
-        return { success: true, status: "paused", runId, durationMs: durationMs2, screen: err.screen };
+        return { success: false, error: errorMessage, durationMs };
       }
-      const errorMessage = err instanceof Error ? err.message : String(err);
-      const durationMs = Date.now() - run.startTime;
-      this.recordLog({
-        id: runId,
-        flowName: run.flowName,
-        flowVersion: run.flowVersion,
-        status: "failed",
-        startedAt: run.startedAt,
-        completedAt: (/* @__PURE__ */ new Date()).toISOString(),
-        durationMs,
-        trigger: {
-          type: context.event ?? "manual",
-          userId: context.userId,
-          object: context.object
-        },
-        steps,
-        error: errorMessage
-      });
-      return { success: false, error: errorMessage, durationMs };
+    } finally {
+      this.resuming.delete(runId);
     }
   }
   /**
    * List the runs currently suspended awaiting {@link resume} (ADR-0019).
    * Backs operability surfaces such as a "pending approvals" view.
+   *
+   * Synchronous — reads the in-memory cache only, so after a process restart
+   * runs that suspended in a prior lifetime are not listed here even though
+   * they remain durably stored and resumable by id. Use
+   * {@link listSuspendedRunsDurable} to include those.
    */
   listSuspendedRuns() {
     return [...this.suspendedRuns.values()].map((r) => ({
@@ -576,6 +716,28 @@ var AutomationEngine = class {
       correlation: r.correlation
     }));
   }
+  /**
+   * Like {@link listSuspendedRuns} but includes runs held only in the durable
+   * {@link SuspendedRunStore} (e.g. suspended before a restart). The in-memory
+   * cache takes precedence on id collisions. Falls back to the in-memory list
+   * when no store is configured.
+   */
+  async listSuspendedRunsDurable() {
+    const byId = /* @__PURE__ */ new Map();
+    if (this.store) {
+      try {
+        for (const r of await this.store.list()) {
+          byId.set(r.runId, { runId: r.runId, flowName: r.flowName, nodeId: r.nodeId, correlation: r.correlation });
+        }
+      } catch (err) {
+        this.logger.warn(`[automation] failed to list suspended runs from durable store: ${err.message}`);
+      }
+    }
+    for (const r of this.suspendedRuns.values()) {
+      byId.set(r.runId, { runId: r.runId, flowName: r.flowName, nodeId: r.nodeId, correlation: r.correlation });
+    }
+    return [...byId.values()];
+  }
   /**
    * The screen a paused run is currently waiting on (screen-flow runtime), or
    * `null` if the run isn't suspended / didn't pause at a screen node. Lets a
@@ -614,6 +776,41 @@ var AutomationEngine = class {
       );
     }
   }
+  /**
+   * ADR-0032 §Decision 1a — parse-validate every predicate in the flow at
+   * registration. Predicates are bare CEL; this catches the #1491 class
+   * (`{record.x}` template braces in a condition → CEL parse error) and any
+   * other malformed predicate LOUDLY, with the offending location + source +
+   * a corrective hint, instead of letting it fail silently at run time.
+   *
+   * Only the *predicate* surfaces are checked here (start/node `config.condition`
+   * and `edge.condition`) — node string fields are templates (a different
+   * dialect) and are validated by the template engine, not as CEL.
+   */
+  validateFlowExpressions(flowName, flow) {
+    const failures = [];
+    const check = (where, raw) => {
+      if (raw == null) return;
+      const result = validateExpression("predicate", raw);
+      for (const e of result.errors) {
+        failures.push(`  \u2022 ${where}: ${e.message}
+      source: \`${e.source}\``);
+      }
+    };
+    for (const node of flow.nodes) {
+      const cfg = node.config ?? {};
+      check(`node '${node.id}' (${node.type}) condition`, cfg.condition);
+    }
+    for (const edge of flow.edges) {
+      check(`edge '${edge.id}' (${edge.source}\u2192${edge.target}) condition`, edge.condition);
+    }
+    if (failures.length > 0) {
+      throw new Error(
+        `Flow '${flowName}' has ${failures.length} invalid condition${failures.length > 1 ? "s" : ""} (ADR-0032 \xA71a). Conditions are bare CEL \u2014 do not wrap field references in \`{\u2026}\` template braces:
+${failures.join("\n")}`
+      );
+    }
+  }
   /**
    * Detect cycles in the flow graph (DAG validation).
    * Uses DFS with coloring (white/gray/black) to detect back edges.
@@ -841,6 +1038,45 @@ var AutomationEngine = class {
       await Promise.all(parallelTasks);
     }
   }
+  /**
+   * Execute a structured control-flow **region** (ADR-0031) — the nested
+   * body of a `loop` container (or, later, a `parallel` branch / `try_catch`
+   * region). The region is a self-contained single-entry/single-exit
+   * sub-graph carried in the container's `config`; it runs in the **enclosing
+   * variable scope** (the caller's `variables` map), so the iterator variable
+   * and any body mutations are visible to the surrounding flow — a region is
+   * NOT a separate `subflow` invocation.
+   *
+   * The region executes against a synthetic flow view of its own
+   * nodes/edges, so the main DAG traversal (`traverseNext`) is never aware of
+   * scope markers — keeping the shared traversal untouched.
+   *
+   * Body step logs are kept in a region-local array (not yet merged into the
+   * parent run log); surfacing per-iteration steps is a follow-up.
+   *
+   * Durable pause (`suspend`) inside a region is not supported in this
+   * iteration — it is converted into a clear error (mirrors the `subflow`
+   * nested-pause guard).
+   */
+  async runRegion(region, variables, context) {
+    const entryId = findRegionEntry(region);
+    const entry = region.nodes.find((n) => n.id === entryId);
+    if (!entry) {
+      throw new Error(`region entry node '${entryId}' not found`);
+    }
+    const subFlow = { nodes: region.nodes, edges: region.edges ?? [] };
+    const regionSteps = [];
+    try {
+      await this.executeNode(entry, subFlow, variables, context, regionSteps);
+    } catch (err) {
+      if (isSuspendSignal(err)) {
+        throw new Error(
+          `durable pause inside a structured region (node '${err.nodeId}') is not supported`
+        );
+      }
+      throw err;
+    }
+  }
   /**
    * Execute a promise with timeout using Promise.race.
    */
@@ -883,10 +1119,17 @@ var AutomationEngine = class {
           { dialect: "cel", source: exprStr },
           { extra: { ...vars, vars }, record: vars }
         );
-        if (!result.ok) return false;
+        if (!result.ok) {
+          throw new Error(
+            `condition failed to evaluate as CEL: ${result.error?.message ?? "unknown error"} \u2014 source: \`${exprStr}\`. Conditions are bare CEL (e.g. \`record.rating >= 4\`); do not wrap field references in \`{\u2026}\` template braces.`
+          );
+        }
         return Boolean(result.value);
-      } catch {
-        return false;
+      } catch (err) {
+        const msg = err?.message ?? String(err);
+        throw new Error(
+          msg.includes("source:") ? msg : `condition evaluation error: ${msg} \u2014 source: \`${exprStr}\``
+        );
       }
     }
     let resolved = exprStr;
@@ -1005,7 +1248,7 @@ var AutomationEngine = class {
     if (context?.record) {
       variables.set("$record", context.record);
     }
-    const runId = `run_${++this.runCounter}`;
+    const runId = this.nextRunId();
     const startedAt = (/* @__PURE__ */ new Date()).toISOString();
     const steps = [];
     try {
@@ -1064,12 +1307,249 @@ var AutomationEngine = class {
   }
 };
 
+// src/suspended-run-store.ts
+var TABLE = "sys_automation_run";
+var SYSTEM_CTX = { isSystem: true, roles: [], permissions: [] };
+function jsonClone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+function parseJson(raw, fallback) {
+  if (raw == null || raw === "") return fallback;
+  if (typeof raw === "string") {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return fallback;
+    }
+  }
+  return raw;
+}
+var InMemorySuspendedRunStore = class {
+  constructor() {
+    this.runs = /* @__PURE__ */ new Map();
+  }
+  async save(run) {
+    this.runs.set(run.runId, jsonClone(run));
+  }
+  async load(runId) {
+    const run = this.runs.get(runId);
+    return run ? jsonClone(run) : null;
+  }
+  async delete(runId) {
+    this.runs.delete(runId);
+  }
+  async list() {
+    return [...this.runs.values()].map(jsonClone);
+  }
+};
+var ObjectStoreSuspendedRunStore = class {
+  constructor(engine, logger) {
+    this.engine = engine;
+    this.logger = logger;
+  }
+  async save(run) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const row = this.serialize(run);
+    const existing = await this.engine.find(TABLE, {
+      where: { id: run.runId },
+      limit: 1,
+      context: SYSTEM_CTX
+    });
+    if (Array.isArray(existing) && existing[0]) {
+      await this.engine.update(
+        TABLE,
+        { ...row, updated_at: now },
+        { where: { id: run.runId }, context: SYSTEM_CTX }
+      );
+    } else {
+      await this.engine.insert(
+        TABLE,
+        { ...row, created_at: now, updated_at: now },
+        { context: SYSTEM_CTX }
+      );
+    }
+  }
+  async load(runId) {
+    const rows = await this.engine.find(TABLE, {
+      where: { id: runId },
+      limit: 1,
+      context: SYSTEM_CTX
+    });
+    const row = Array.isArray(rows) ? rows[0] : null;
+    return row ? this.deserialize(row) : null;
+  }
+  async delete(runId) {
+    if (typeof this.engine.delete !== "function") {
+      this.logger?.warn?.(
+        `[automation] ObjectStoreSuspendedRunStore: engine has no delete(); suspended run '${runId}' row not removed`
+      );
+      return;
+    }
+    await this.engine.delete(TABLE, { where: { id: runId }, context: SYSTEM_CTX });
+  }
+  async list() {
+    const rows = await this.engine.find(TABLE, {
+      where: { status: "paused" },
+      limit: 1e3,
+      context: SYSTEM_CTX
+    });
+    return (Array.isArray(rows) ? rows : []).map((r) => this.deserialize(r));
+  }
+  /** Flatten a run into a `sys_automation_run` row (state columns JSON-encoded). */
+  serialize(run) {
+    const ctx = run.context ?? {};
+    const org = ctx.organizationId ?? ctx.tenantId ?? null;
+    return {
+      id: run.runId,
+      organization_id: org,
+      flow_name: run.flowName,
+      flow_version: run.flowVersion ?? null,
+      node_id: run.nodeId,
+      status: "paused",
+      correlation: run.correlation ?? null,
+      user_id: ctx.userId ?? null,
+      variables_json: JSON.stringify(run.variables ?? {}),
+      steps_json: JSON.stringify(run.steps ?? []),
+      context_json: JSON.stringify(run.context ?? {}),
+      screen_json: run.screen ? JSON.stringify(run.screen) : null,
+      started_at: run.startedAt,
+      start_time: run.startTime ?? null
+    };
+  }
+  /** Rebuild a run from a `sys_automation_run` row. */
+  deserialize(row) {
+    const startedAt = row.started_at ?? (/* @__PURE__ */ new Date()).toISOString();
+    return {
+      runId: String(row.id),
+      flowName: String(row.flow_name ?? ""),
+      flowVersion: row.flow_version ?? void 0,
+      nodeId: String(row.node_id ?? ""),
+      variables: parseJson(row.variables_json, {}),
+      steps: parseJson(row.steps_json, []),
+      context: parseJson(row.context_json, {}),
+      startedAt,
+      startTime: typeof row.start_time === "number" ? row.start_time : Date.parse(startedAt) || Date.now(),
+      correlation: row.correlation ?? void 0,
+      screen: parseJson(row.screen_json, void 0)
+    };
+  }
+};
+
+// src/sys-automation-run.object.ts
+import { ObjectSchema, Field } from "@objectstack/spec/data";
+var SysAutomationRun = ObjectSchema.create({
+  name: "sys_automation_run",
+  label: "Automation Run",
+  pluralLabel: "Automation Runs",
+  icon: "pause-circle",
+  isSystem: true,
+  managedBy: "system",
+  description: "Durable state of a suspended automation flow run (ADR-0019)",
+  displayNameField: "id",
+  titleFormat: "{flow_name} \xB7 {node_id}",
+  compactLayout: ["flow_name", "node_id", "status", "correlation", "started_at", "updated_at"],
+  fields: {
+    id: Field.text({ label: "Run ID", required: true, readonly: true, group: "System" }),
+    organization_id: Field.lookup("sys_organization", {
+      label: "Organization",
+      required: false,
+      group: "System",
+      description: "Tenant that owns this run (propagated from the trigger context)"
+    }),
+    flow_name: Field.text({
+      label: "Flow",
+      required: true,
+      maxLength: 255,
+      searchable: true,
+      group: "Identity"
+    }),
+    flow_version: Field.number({ label: "Flow Version", required: false, group: "Identity" }),
+    node_id: Field.text({
+      label: "Paused Node",
+      required: true,
+      maxLength: 255,
+      description: "Node the run is suspended at; resume continues from its out-edges.",
+      group: "State"
+    }),
+    status: Field.select(
+      ["paused"],
+      {
+        label: "Status",
+        required: true,
+        defaultValue: "paused",
+        description: "Only suspended runs are persisted; the row is deleted on terminal completion.",
+        group: "State"
+      }
+    ),
+    correlation: Field.text({
+      label: "Correlation",
+      required: false,
+      maxLength: 255,
+      description: "Correlation key from the pausing node (e.g. approval request id).",
+      group: "State"
+    }),
+    user_id: Field.text({
+      label: "User",
+      required: false,
+      maxLength: 255,
+      description: "User who triggered the run (from context.userId).",
+      group: "State"
+    }),
+    variables_json: Field.textarea({
+      label: "Variables",
+      required: false,
+      description: "JSON snapshot of the flow variable map at suspend time.",
+      group: "State"
+    }),
+    steps_json: Field.textarea({
+      label: "Steps",
+      required: false,
+      description: "JSON snapshot of the executed step logs so far.",
+      group: "State"
+    }),
+    context_json: Field.textarea({
+      label: "Context",
+      required: false,
+      description: "JSON snapshot of the trigger / automation context.",
+      group: "State"
+    }),
+    screen_json: Field.textarea({
+      label: "Screen",
+      required: false,
+      description: "JSON snapshot of the screen spec the run is waiting on (screen-flow runtime).",
+      group: "State"
+    }),
+    started_at: Field.datetime({ label: "Started At", required: true, group: "State" }),
+    start_time: Field.number({
+      label: "Start Time (epoch ms)",
+      required: false,
+      description: "Epoch ms when the run started; used to compute duration on resume.",
+      group: "State"
+    }),
+    created_at: Field.datetime({
+      label: "Created At",
+      required: true,
+      defaultValue: "NOW()",
+      readonly: true,
+      group: "System"
+    }),
+    updated_at: Field.datetime({ label: "Updated At", required: false, group: "System" })
+  },
+  indexes: [
+    // "Which runs are suspended for this flow?" — operability / resume sweeps.
+    { fields: ["flow_name", "status"] },
+    { fields: ["status", "updated_at"] },
+    // Look up a suspended run by the pausing node's correlation key.
+    { fields: ["correlation"] }
+  ]
+});
+
 // src/builtin/logic-nodes.ts
-import { defineActionDescriptor } from "@objectstack/spec/automation";
+import { defineActionDescriptor as defineActionDescriptor2 } from "@objectstack/spec/automation";
 function registerLogicNodes(engine, ctx) {
   engine.registerNodeExecutor({
     type: "decision",
-    descriptor: defineActionDescriptor({
+    descriptor: defineActionDescriptor2({
       type: "decision",
       version: "1.0.0",
       name: "Decision",
@@ -1091,7 +1571,7 @@ function registerLogicNodes(engine, ctx) {
   });
   engine.registerNodeExecutor({
     type: "assignment",
-    descriptor: defineActionDescriptor({
+    descriptor: defineActionDescriptor2({
       type: "assignment",
       version: "1.0.0",
       name: "Assignment",
@@ -1108,35 +1588,11 @@ function registerLogicNodes(engine, ctx) {
       return { success: true };
     }
   });
-  engine.registerNodeExecutor({
-    type: "loop",
-    descriptor: defineActionDescriptor({
-      type: "loop",
-      version: "1.0.0",
-      name: "Loop",
-      description: "Iterate over a collection.",
-      icon: "repeat",
-      category: "logic",
-      source: "builtin"
-    }),
-    async execute(node, variables, _context) {
-      const config = node.config;
-      const collectionName = config?.collection;
-      if (collectionName) {
-        const collection = variables.get(collectionName);
-        if (Array.isArray(collection)) {
-          variables.set("$loopItems", collection);
-          variables.set("$loopIndex", 0);
-        }
-      }
-      return { success: true };
-    }
-  });
-  ctx.logger.info("[Logic Nodes] 3 built-in node executors registered");
+  ctx.logger.info("[Logic Nodes] 2 built-in node executors registered");
 }
 
-// src/builtin/crud-nodes.ts
-import { defineActionDescriptor as defineActionDescriptor2 } from "@objectstack/spec/automation";
+// src/builtin/loop-node.ts
+import { defineActionDescriptor as defineActionDescriptor3, LOOP_MAX_ITERATIONS_CEILING } from "@objectstack/spec/automation";
 
 // src/builtin/template.ts
 function resolvePath(base, path) {
@@ -1235,7 +1691,232 @@ function interpolate(value, variables, context) {
   return value;
 }
 
+// src/builtin/loop-node.ts
+function registerLoopNode(engine, ctx) {
+  engine.registerNodeExecutor({
+    type: "loop",
+    descriptor: defineActionDescriptor3({
+      type: "loop",
+      version: "2.0.0",
+      name: "Loop",
+      description: "Iterate a body region over a collection (bounded, structured container).",
+      icon: "repeat",
+      category: "logic",
+      source: "builtin",
+      configSchema: {
+        type: "object",
+        properties: {
+          collection: { type: "string", description: "Template/variable resolving to the array to iterate" },
+          iteratorVariable: { type: "string", description: "Loop variable holding the current item" },
+          indexVariable: { type: "string", description: "Optional loop variable holding the current index" },
+          maxIterations: { type: "integer", minimum: 1, maximum: LOOP_MAX_ITERATIONS_CEILING },
+          body: {
+            type: "object",
+            description: "Loop body region (single-entry/single-exit sub-graph)",
+            properties: { nodes: { type: "array" }, edges: { type: "array" } }
+          }
+        },
+        required: ["collection"]
+      }
+    }),
+    async execute(node, variables, context) {
+      const cfg = node.config ?? {};
+      const body = cfg.body;
+      if (body == null) {
+        const collectionName = typeof cfg.collection === "string" ? cfg.collection : void 0;
+        if (collectionName) {
+          const legacy = variables.get(collectionName);
+          if (Array.isArray(legacy)) {
+            variables.set("$loopItems", legacy);
+            variables.set("$loopIndex", 0);
+          }
+        }
+        return { success: true };
+      }
+      const iteratorVariable = typeof cfg.iteratorVariable === "string" && cfg.iteratorVariable ? cfg.iteratorVariable : "item";
+      const indexVariable = typeof cfg.indexVariable === "string" && cfg.indexVariable ? cfg.indexVariable : void 0;
+      const rawCollection = cfg.collection;
+      let collection;
+      if (Array.isArray(rawCollection)) {
+        collection = rawCollection;
+      } else if (typeof rawCollection === "string") {
+        collection = interpolate(rawCollection, variables, context ?? {});
+        if (collection == null && variables.has(rawCollection)) {
+          collection = variables.get(rawCollection);
+        }
+      }
+      if (!Array.isArray(collection)) {
+        return {
+          success: false,
+          error: `loop '${node.id}': collection '${String(rawCollection)}' did not resolve to an array`
+        };
+      }
+      const requested = typeof cfg.maxIterations === "number" ? cfg.maxIterations : LOOP_MAX_ITERATIONS_CEILING;
+      const maxIterations = Math.min(requested, LOOP_MAX_ITERATIONS_CEILING);
+      if (collection.length > maxIterations) {
+        return {
+          success: false,
+          error: `loop '${node.id}': collection length ${collection.length} exceeds maxIterations ${maxIterations}`
+        };
+      }
+      let iterations = 0;
+      for (let i = 0; i < collection.length; i++) {
+        variables.set(iteratorVariable, collection[i]);
+        if (indexVariable) variables.set(indexVariable, i);
+        await engine.runRegion(body, variables, context ?? {});
+        iterations++;
+      }
+      return { success: true, output: { iterations } };
+    }
+  });
+  ctx.logger.info("[Loop Node] 1 built-in node executor registered");
+}
+
+// src/builtin/parallel-node.ts
+import { defineActionDescriptor as defineActionDescriptor4 } from "@objectstack/spec/automation";
+function registerParallelNode(engine, ctx) {
+  engine.registerNodeExecutor({
+    type: "parallel",
+    descriptor: defineActionDescriptor4({
+      type: "parallel",
+      version: "1.0.0",
+      name: "Parallel",
+      description: "Run N branch regions concurrently and join implicitly when all complete.",
+      icon: "git-fork",
+      category: "logic",
+      source: "builtin",
+      configSchema: {
+        type: "object",
+        properties: {
+          branches: {
+            type: "array",
+            minItems: 2,
+            description: "Branch regions executed concurrently; implicit join at block end",
+            items: {
+              type: "object",
+              properties: {
+                name: { type: "string" },
+                nodes: { type: "array" },
+                edges: { type: "array" }
+              }
+            }
+          }
+        },
+        required: ["branches"]
+      }
+    }),
+    async execute(node, variables, context) {
+      const cfg = node.config ?? {};
+      const branches = cfg.branches;
+      if (!Array.isArray(branches) || branches.length < 2) {
+        return {
+          success: false,
+          error: `parallel '${node.id}': config.branches must declare at least 2 branch regions`
+        };
+      }
+      try {
+        await Promise.all(
+          branches.map((branch) => engine.runRegion(branch, variables, context ?? {}))
+        );
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { success: false, error: `parallel '${node.id}': branch failed \u2014 ${message}` };
+      }
+      return { success: true, output: { branches: branches.length } };
+    }
+  });
+  ctx.logger.info("[Parallel Node] 1 built-in node executor registered");
+}
+
+// src/builtin/try-catch-node.ts
+import { defineActionDescriptor as defineActionDescriptor5 } from "@objectstack/spec/automation";
+function registerTryCatchNode(engine, ctx) {
+  engine.registerNodeExecutor({
+    type: "try_catch",
+    descriptor: defineActionDescriptor5({
+      type: "try_catch",
+      version: "1.0.0",
+      name: "Try / Catch",
+      description: "Run a protected region with optional retry and a catch handler (structured error handling).",
+      icon: "shield-alert",
+      category: "logic",
+      source: "builtin",
+      supportsRetry: true,
+      configSchema: {
+        type: "object",
+        properties: {
+          try: {
+            type: "object",
+            description: "Protected region (single-entry/single-exit sub-graph)",
+            properties: { nodes: { type: "array" }, edges: { type: "array" } }
+          },
+          catch: {
+            type: "object",
+            description: "Handler region run when the try region fails",
+            properties: { nodes: { type: "array" }, edges: { type: "array" } }
+          },
+          errorVariable: { type: "string", description: "Variable holding the caught error in the catch region" },
+          retry: {
+            type: "object",
+            properties: {
+              maxRetries: { type: "integer", minimum: 0, maximum: 10 },
+              retryDelayMs: { type: "integer", minimum: 0 },
+              backoffMultiplier: { type: "number", minimum: 1 },
+              maxRetryDelayMs: { type: "integer", minimum: 0 },
+              jitter: { type: "boolean" }
+            }
+          }
+        },
+        required: ["try"]
+      }
+    }),
+    async execute(node, variables, context) {
+      const cfg = node.config ?? {};
+      const tryRegion = cfg.try;
+      const catchRegion = cfg.catch;
+      const errorVariable = typeof cfg.errorVariable === "string" && cfg.errorVariable ? cfg.errorVariable : "$error";
+      const retry = cfg.retry ?? {};
+      if (tryRegion == null) {
+        return { success: false, error: `try_catch '${node.id}': config.try region is required` };
+      }
+      const ctxOrEmpty = context ?? {};
+      const maxRetries = typeof retry.maxRetries === "number" ? retry.maxRetries : 0;
+      const baseDelay = typeof retry.retryDelayMs === "number" ? retry.retryDelayMs : 0;
+      const multiplier = typeof retry.backoffMultiplier === "number" ? retry.backoffMultiplier : 1;
+      const maxDelay = typeof retry.maxRetryDelayMs === "number" ? retry.maxRetryDelayMs : 3e4;
+      const useJitter = retry.jitter === true;
+      let lastError = "unknown error";
+      for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        if (attempt > 0) {
+          let delay = Math.min(baseDelay * Math.pow(multiplier, attempt - 1), maxDelay);
+          if (useJitter) delay = delay * (0.5 + Math.random() * 0.5);
+          if (delay > 0) await new Promise((r) => setTimeout(r, delay));
+        }
+        try {
+          await engine.runRegion(tryRegion, variables, ctxOrEmpty);
+          return { success: true, output: { attempts: attempt + 1, caught: false } };
+        } catch (err) {
+          lastError = err instanceof Error ? err.message : String(err);
+        }
+      }
+      if (catchRegion != null) {
+        variables.set(errorVariable, { nodeId: node.id, message: lastError });
+        try {
+          await engine.runRegion(catchRegion, variables, ctxOrEmpty);
+          return { success: true, output: { attempts: maxRetries + 1, caught: true, error: lastError } };
+        } catch (catchErr) {
+          const catchMsg = catchErr instanceof Error ? catchErr.message : String(catchErr);
+          return { success: false, error: `try_catch '${node.id}': catch region failed \u2014 ${catchMsg}` };
+        }
+      }
+      return { success: false, error: `try_catch '${node.id}': try region failed \u2014 ${lastError}` };
+    }
+  });
+  ctx.logger.info("[TryCatch Node] 1 built-in node executor registered");
+}
+
 // src/builtin/crud-nodes.ts
+import { defineActionDescriptor as defineActionDescriptor6 } from "@objectstack/spec/automation";
 function registerCrudNodes(engine, ctx) {
   const getData = () => {
     try {
@@ -1246,7 +1927,7 @@ function registerCrudNodes(engine, ctx) {
   };
   engine.registerNodeExecutor({
     type: "get_record",
-    descriptor: defineActionDescriptor2({
+    descriptor: defineActionDescriptor6({
       type: "get_record",
       version: "1.0.0",
       name: "Get Records",
@@ -1284,7 +1965,7 @@ function registerCrudNodes(engine, ctx) {
   });
   engine.registerNodeExecutor({
     type: "create_record",
-    descriptor: defineActionDescriptor2({
+    descriptor: defineActionDescriptor6({
       type: "create_record",
       version: "1.0.0",
       name: "Create Record",
@@ -1317,7 +1998,7 @@ function registerCrudNodes(engine, ctx) {
   });
   engine.registerNodeExecutor({
     type: "update_record",
-    descriptor: defineActionDescriptor2({
+    descriptor: defineActionDescriptor6({
       type: "update_record",
       version: "1.0.0",
       name: "Update Records",
@@ -1347,7 +2028,7 @@ function registerCrudNodes(engine, ctx) {
   });
   engine.registerNodeExecutor({
     type: "delete_record",
-    descriptor: defineActionDescriptor2({
+    descriptor: defineActionDescriptor6({
       type: "delete_record",
       version: "1.0.0",
       name: "Delete Records",
@@ -1375,11 +2056,11 @@ function registerCrudNodes(engine, ctx) {
 }
 
 // src/builtin/screen-nodes.ts
-import { defineActionDescriptor as defineActionDescriptor3 } from "@objectstack/spec/automation";
+import { defineActionDescriptor as defineActionDescriptor7 } from "@objectstack/spec/automation";
 function registerScreenNodes(engine, ctx) {
   engine.registerNodeExecutor({
     type: "screen",
-    descriptor: defineActionDescriptor3({
+    descriptor: defineActionDescriptor7({
       type: "screen",
       version: "1.0.0",
       name: "Screen",
@@ -1422,7 +2103,7 @@ function registerScreenNodes(engine, ctx) {
   });
   engine.registerNodeExecutor({
     type: "script",
-    descriptor: defineActionDescriptor3({
+    descriptor: defineActionDescriptor7({
       type: "script",
       version: "1.0.0",
       name: "Script",
@@ -1455,55 +2136,133 @@ function registerScreenNodes(engine, ctx) {
 }
 
 // src/builtin/http-nodes.ts
-import { defineActionDescriptor as defineActionDescriptor4 } from "@objectstack/spec/automation";
+import { defineActionDescriptor as defineActionDescriptor8 } from "@objectstack/spec/automation";
+import { randomUUID } from "crypto";
+var HTTP_TYPE = "http";
 function registerHttpNodes(engine, ctx) {
+  const getMessaging = () => {
+    try {
+      return ctx.getService("messaging");
+    } catch {
+      return void 0;
+    }
+  };
   engine.registerNodeExecutor({
-    type: "http_request",
-    descriptor: defineActionDescriptor4({
-      type: "http_request",
+    type: HTTP_TYPE,
+    descriptor: defineActionDescriptor8({
+      type: HTTP_TYPE,
       version: "1.0.0",
-      name: "HTTP Request",
-      description: "Call an external HTTP endpoint. (ADR-0018: migrates to outbox-backed `http`.)",
+      name: "HTTP",
+      description: "Call an external HTTP endpoint. With `durable: true`, the call is enqueued on the messaging outbox with retry / dead-letter; otherwise it runs inline and returns the response.",
       icon: "globe",
       category: "io",
       source: "builtin",
-      // ADR-0018 §M3 target: route via service-messaging outbox for
-      // retry/idempotency/dead-letter. Today this is a bare fetch().
-      needsOutbox: false,
+      // Capable of outbox-backed durable delivery (used when durable:true
+      // and the messaging HTTP outbox is wired).
+      needsOutbox: true,
       supportsRetry: true,
-      paradigms: ["flow", "workflow_rule", "approval"]
+      paradigms: ["flow", "workflow_rule", "approval"],
+      configSchema: {
+        type: "object",
+        required: ["url"],
+        properties: {
+          url: { type: "string", description: "Target URL" },
+          method: { type: "string", description: "HTTP method (default GET; POST when durable)" },
+          headers: { type: "object", description: "Request headers" },
+          body: { description: "Request body (JSON-serialised)" },
+          durable: {
+            type: "boolean",
+            description: "Fire-and-forget via the durable outbox (retry/dead-letter) instead of inline request/response"
+          },
+          timeoutMs: { type: "number", description: "Per-request timeout (ms)" },
+          signingSecret: { type: "string", description: "HMAC-SHA256 secret \u2192 X-Objectstack-Signature" }
+        }
+      }
     }),
-    async execute(node, _variables, _context) {
-      const config = node.config;
-      const url = config?.url;
-      const method = config?.method ?? "GET";
-      const headers = config?.headers;
-      const body = config?.body;
-      if (!url) {
-        return { success: false, error: "http_request: url is required" };
-      }
-      const response = await fetch(url, {
-        method,
-        headers,
-        body: body ? JSON.stringify(body) : void 0
-      });
-      const data = await response.json();
-      return {
-        success: response.ok,
-        output: { response: data, status: response.status },
-        error: response.ok ? void 0 : `HTTP ${response.status}`
-      };
+    async execute(node, variables, context) {
+      const raw = node.config ?? {};
+      const cfg = interpolate(raw, variables, context);
+      const url = cfg.url;
+      if (!url) return { success: false, error: "http: url is required" };
+      const durable = cfg.durable === true;
+      const headers = cfg.headers;
+      const body = cfg.body;
+      const timeoutMs = typeof cfg.timeoutMs === "number" ? cfg.timeoutMs : void 0;
+      const signingSecret = cfg.signingSecret;
+      if (durable) {
+        const messaging = getMessaging();
+        if (messaging?.isHttpDeliveryReady?.() && messaging.enqueueHttp) {
+          try {
+            const deliveryId = await messaging.enqueueHttp({
+              source: "flow",
+              refId: node.id,
+              dedupKey: randomUUID(),
+              label: `flow:${node.id}`,
+              url,
+              method: cfg.method ?? "POST",
+              headers,
+              signingSecret,
+              timeoutMs,
+              payload: body ?? {}
+            });
+            return { success: true, output: { deliveryId, enqueued: true } };
+          } catch (err) {
+            return { success: false, error: `http (durable) failed to enqueue: ${err.message}` };
+          }
+        }
+        ctx.logger.warn(
+          `[http] node '${node.id}' requested durable delivery but no messaging HTTP outbox is wired; falling back to inline fetch`
+        );
+      }
+      const method = cfg.method ?? "GET";
+      const controller = new AbortController();
+      const timer = timeoutMs ? setTimeout(() => controller.abort(), timeoutMs) : void 0;
+      try {
+        const response = await fetch(url, {
+          method,
+          headers,
+          body: body !== void 0 && body !== null ? JSON.stringify(body) : void 0,
+          signal: controller.signal
+        });
+        const data = await readBody(response);
+        return {
+          success: response.ok,
+          output: { response: data, status: response.status },
+          error: response.ok ? void 0 : `HTTP ${response.status}`
+        };
+      } catch (err) {
+        const e = err;
+        const msg = e?.name === "AbortError" ? `timeout after ${timeoutMs}ms` : e?.message ?? String(err);
+        return { success: false, error: `http: ${msg}` };
+      } finally {
+        if (timer) clearTimeout(timer);
+      }
     }
   });
-  ctx.logger.info("[HTTP] 1 built-in node executor registered (http_request)");
+  engine.registerNodeAlias("http_request", HTTP_TYPE, { name: "HTTP Request", needsOutbox: true });
+  engine.registerNodeAlias("http_call", HTTP_TYPE, { name: "HTTP Call", needsOutbox: true });
+  engine.registerNodeAlias("webhook", HTTP_TYPE, { name: "Webhook", needsOutbox: true });
+  ctx.logger.info("[HTTP] http executor registered (+ deprecated aliases: http_request, http_call, webhook)");
+}
+async function readBody(response) {
+  try {
+    return await response.json();
+  } catch {
+    try {
+      const text = await response.text();
+      return text || null;
+    } catch {
+      return null;
+    }
+  }
 }
 
 // src/builtin/connector-nodes.ts
-import { defineActionDescriptor as defineActionDescriptor5 } from "@objectstack/spec/automation";
+import { defineActionDescriptor as defineActionDescriptor9 } from "@objectstack/spec/automation";
 function registerConnectorNodes(engine, ctx) {
   engine.registerNodeExecutor({
     type: "connector_action",
-    descriptor: defineActionDescriptor5({
+    descriptor: defineActionDescriptor9({
       type: "connector_action",
       version: "1.0.0",
       name: "Connector Action",
@@ -1560,7 +2319,7 @@ function registerConnectorNodes(engine, ctx) {
 }
 
 // src/builtin/notify-node.ts
-import { defineActionDescriptor as defineActionDescriptor6 } from "@objectstack/spec/automation";
+import { defineActionDescriptor as defineActionDescriptor10 } from "@objectstack/spec/automation";
 function toStringList(value) {
   if (Array.isArray(value)) return value.map((v) => String(v)).filter(Boolean);
   if (typeof value === "string" && value.trim()) return [value.trim()];
@@ -1576,7 +2335,7 @@ function registerNotifyNode(engine, ctx) {
   };
   engine.registerNodeExecutor({
     type: "notify",
-    descriptor: defineActionDescriptor6({
+    descriptor: defineActionDescriptor10({
       type: "notify",
       version: "1.0.0",
       name: "Notify",
@@ -1585,6 +2344,9 @@ function registerNotifyNode(engine, ctx) {
       category: "io",
       source: "builtin",
       supportsRetry: true,
+      // Delivery is outbox-backed inside the messaging service (ADR-0030
+      // emit → sys_notification_delivery), so it inherits retry/dead-letter.
+      needsOutbox: true,
       paradigms: ["flow", "workflow_rule", "approval"]
     }),
     async execute(node, variables, context) {
@@ -1635,14 +2397,155 @@ function registerNotifyNode(engine, ctx) {
   ctx.logger.info("[Notify] 1 built-in node executor registered (notify)");
 }
 
+// src/builtin/wait-node.ts
+import { defineActionDescriptor as defineActionDescriptor11 } from "@objectstack/spec/automation";
+function registerWaitNode(engine, ctx) {
+  const getJobService = () => {
+    try {
+      return ctx.getService("job");
+    } catch {
+      return void 0;
+    }
+  };
+  engine.registerNodeExecutor({
+    type: "wait",
+    descriptor: defineActionDescriptor11({
+      type: "wait",
+      version: "1.0.0",
+      name: "Wait",
+      description: "Pause the flow until a timer elapses or a named signal arrives.",
+      icon: "timer-reset",
+      category: "logic",
+      source: "builtin",
+      // Durable pause — the run suspends and resumes later (timer/signal).
+      supportsPause: true,
+      isAsync: true
+    }),
+    async execute(node, variables, _context) {
+      const loose = node.config ?? {};
+      const wec = node.waitEventConfig ?? {};
+      const eventType = String(wec.eventType ?? loose.eventType ?? "timer");
+      const runId = variables.get("$runId");
+      if (eventType === "timer") {
+        const durationMs = parseIsoDuration(wec.timerDuration ?? loose.timerDuration ?? loose.duration) ?? (typeof wec.timeoutMs === "number" ? wec.timeoutMs : void 0) ?? (typeof loose.timeoutMs === "number" ? loose.timeoutMs : void 0);
+        const job = getJobService();
+        if (job && runId != null && durationMs && durationMs > 0) {
+          const jobName = `flow-wait:${String(runId)}:${node.id}`;
+          const at = new Date(Date.now() + durationMs).toISOString();
+          try {
+            await job.schedule(jobName, { type: "once", at }, async () => {
+              try {
+                await engine.resume(String(runId));
+              } finally {
+                try {
+                  await job.cancel?.(jobName);
+                } catch {
+                }
+              }
+            });
+            return { success: true, suspend: true, correlation: jobName };
+          } catch (err) {
+            ctx.logger.warn(
+              `[wait] node '${node.id}': failed to schedule timer resume (${err?.message ?? err}); suspending without auto-resume (resume it via resume(runId))`
+            );
+          }
+        } else if (!job) {
+          ctx.logger.warn(
+            `[wait] node '${node.id}': no job service registered \u2014 suspending without an auto-resume timer (resume it via resume(runId), or install the job service for durable timers)`
+          );
+        }
+        return { success: true, suspend: true, correlation: `timer:${node.id}` };
+      }
+      const signal = String(wec.signalName ?? loose.signalName ?? loose.signal ?? `wait:${node.id}`);
+      return { success: true, suspend: true, correlation: signal };
+    }
+  });
+  ctx.logger.info("[Wait Node] 1 built-in node executor registered");
+}
+function parseIsoDuration(input) {
+  if (typeof input === "number" && Number.isFinite(input)) return input > 0 ? input : void 0;
+  if (typeof input !== "string") return void 0;
+  const s = input.trim();
+  if (!s) return void 0;
+  if (/^\d+(?:\.\d+)?$/.test(s)) {
+    const n = Number(s);
+    return n > 0 ? n : void 0;
+  }
+  const m = /^P(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$/.exec(s);
+  if (!m) return void 0;
+  const [, w, d, h, min, sec] = m;
+  if (!w && !d && !h && !min && !sec) return void 0;
+  const totalSec = Number(w ?? 0) * 7 * 86400 + Number(d ?? 0) * 86400 + Number(h ?? 0) * 3600 + Number(min ?? 0) * 60 + Number(sec ?? 0);
+  const ms = totalSec * 1e3;
+  return ms > 0 ? ms : void 0;
+}
+
+// src/builtin/subflow-node.ts
+import { defineActionDescriptor as defineActionDescriptor12 } from "@objectstack/spec/automation";
+var MAX_SUBFLOW_DEPTH = 16;
+function registerSubflowNode(engine, ctx) {
+  engine.registerNodeExecutor({
+    type: "subflow",
+    descriptor: defineActionDescriptor12({
+      type: "subflow",
+      version: "1.0.0",
+      name: "Subflow",
+      description: "Invoke another flow as a reusable step and capture its output.",
+      icon: "workflow",
+      category: "logic",
+      source: "builtin"
+    }),
+    async execute(node, variables, context) {
+      const cfg = node.config ?? {};
+      const flowName = typeof cfg.flowName === "string" ? cfg.flowName : typeof cfg.flow === "string" ? cfg.flow : void 0;
+      if (!flowName) {
+        return { success: false, error: `subflow '${node.id}': config.flowName is required` };
+      }
+      const depth = Number(context?.$subflowDepth ?? 0);
+      if (depth >= MAX_SUBFLOW_DEPTH) {
+        return {
+          success: false,
+          error: `subflow '${flowName}': max nesting depth (${MAX_SUBFLOW_DEPTH}) exceeded \u2014 recursive subflow?`
+        };
+      }
+      const rawInput = cfg.input && typeof cfg.input === "object" ? cfg.input : {};
+      const params = interpolate(rawInput, variables, context ?? {});
+      const childContext = {
+        ...context ?? {},
+        $subflowDepth: depth + 1,
+        params
+      };
+      const child = await engine.execute(flowName, childContext);
+      if (child.status === "paused") {
+        return {
+          success: false,
+          error: `subflow '${flowName}' suspended at a pausing node \u2014 a nested approval/screen/wait pause from a subflow is not yet supported`
+        };
+      }
+      if (!child.success) {
+        return { success: false, error: `subflow '${flowName}' failed: ${child.error ?? "unknown error"}` };
+      }
+      const outVar = typeof cfg.outputVariable === "string" && cfg.outputVariable ? cfg.outputVariable : void 0;
+      if (outVar) variables.set(outVar, child.output ?? null);
+      return { success: true, output: { output: child.output ?? null } };
+    }
+  });
+  ctx.logger.info("[Subflow Node] 1 built-in node executor registered");
+}
+
 // src/builtin/index.ts
 function installBuiltinNodes(engine, ctx) {
   registerLogicNodes(engine, ctx);
+  registerLoopNode(engine, ctx);
+  registerParallelNode(engine, ctx);
+  registerTryCatchNode(engine, ctx);
   registerCrudNodes(engine, ctx);
   registerScreenNodes(engine, ctx);
   registerHttpNodes(engine, ctx);
   registerConnectorNodes(engine, ctx);
   registerNotifyNode(engine, ctx);
+  registerWaitNode(engine, ctx);
+  registerSubflowNode(engine, ctx);
   const types = engine.getRegisteredNodeTypes();
   ctx.logger.info(
     `[Automation] ${types.length} built-in node executors installed: ${types.join(", ")}`
@@ -1664,6 +2567,24 @@ var AutomationServicePlugin = class {
   async init(ctx) {
     this.engine = new AutomationEngine(ctx.logger);
     ctx.registerService("automation", this.engine);
+    if ((this.options.suspendedRunStore ?? "auto") !== "memory") {
+      try {
+        ctx.getService("manifest").register({
+          id: "com.objectstack.service-automation",
+          name: "Automation Service",
+          version: "1.0.0",
+          type: "plugin",
+          scope: "system",
+          defaultDatasource: "cloud",
+          namespace: "sys",
+          objects: [SysAutomationRun]
+        });
+      } catch (err) {
+        ctx.logger.warn(
+          `[Automation] manifest service unavailable; sys_automation_run not registered (suspended runs stay in-memory): ${err.message}`
+        );
+      }
+    }
     installBuiltinNodes(this.engine, ctx);
     if (this.options.debug) {
       ctx.hook("automation:beforeExecute", async (flowName) => {
@@ -1683,6 +2604,23 @@ var AutomationServicePlugin = class {
     ctx.logger.info(
       `[Automation] Engine started with ${nodeTypes.length} node types: ${nodeTypes.join(", ") || "(none)"}`
     );
+    if ((this.options.suspendedRunStore ?? "auto") !== "memory") {
+      let dataEngine = null;
+      try {
+        dataEngine = ctx.getService("objectql");
+      } catch {
+        try {
+          dataEngine = ctx.getService("data");
+        } catch {
+        }
+      }
+      if (dataEngine && typeof dataEngine.find === "function" && typeof dataEngine.insert === "function") {
+        this.engine.setSuspendedRunStore(new ObjectStoreSuspendedRunStore(dataEngine, ctx.logger));
+        ctx.logger.info("[Automation] Suspended-run persistence enabled (sys_automation_run)");
+      } else {
+        ctx.logger.info("[Automation] No ObjectQL engine \u2014 suspended runs kept in-memory only");
+      }
+    }
     try {
       const ql = ctx.getService("objectql");
       if (!ql) {
@@ -1721,6 +2659,9 @@ var AutomationServicePlugin = class {
 export {
   AutomationEngine,
   AutomationServicePlugin,
+  InMemorySuspendedRunStore,
+  ObjectStoreSuspendedRunStore,
+  SysAutomationRun,
   installBuiltinNodes,
   registerConnectorNodes,
   registerCrudNodes,