@objectstack/service-automation 9.2.0 → 9.4.0

package/dist/index.cjs

@@ -49,7 +49,7 @@ var FlowSuspendSignal = class {
 function isSuspendSignal(err) {
   return typeof err === "object" && err !== null && err.__flowSuspend === true;
 }
-var AutomationEngine = class {
+var _AutomationEngine = class _AutomationEngine {
   constructor(logger, store) {
     this.flows = /* @__PURE__ */ new Map();
     this.flowEnabled = /* @__PURE__ */ new Map();
@@ -244,7 +244,7 @@ var AutomationEngine = class {
   }
   /**
    * Derive a flow's trigger binding from its `start` node, or `undefined` if
-   * the flow has no auto-trigger (manual / screen / api). The convention —
+   * the flow has no auto-trigger (manual / screen). The convention —
    * established by the showcase flows — is that the start node carries the
    * trigger details in its `config`: `{ objectName, triggerType, condition }`
    * for record-change, or a `schedule` descriptor for time-based flows.
@@ -273,6 +273,12 @@ var AutomationEngine = class {
         binding: { flowName, schedule: config.schedule, condition: config.condition ?? void 0, config }
       };
     }
+    if (flow.type === "api" || triggerType === "api") {
+      return {
+        triggerType: "api",
+        binding: { flowName, condition: config.condition ?? void 0, config }
+      };
+    }
     return void 0;
   }
   /**
@@ -856,6 +862,46 @@ var AutomationEngine = class {
       error
     });
   }
+  /**
+   * Cancel a suspended run (ADR-0044): consume its continuation and record a
+   * terminal `cancelled` log so it stops surfacing as resumable. The
+   * engine-level primitive behind "the submitter abandoned the revision
+   * window" — recalling there leaves the run paused at a wait node with no
+   * reject edge to resume down, so the run must end, not continue. Returns
+   * `false` when no suspended run exists under the id (already terminal /
+   * unknown), which callers treat as idempotent success.
+   */
+  async cancelRun(runId, reason) {
+    let run = this.suspendedRuns.get(runId) ?? null;
+    if (!run && this.store) {
+      try {
+        run = await this.store.load(runId);
+      } catch (err) {
+        this.logger.warn(
+          `[automation] cancelRun: failed to load suspended run '${runId}' from durable store: ${err.message}`
+        );
+      }
+    }
+    if (!run) return false;
+    await this.forgetSuspendedRun(runId);
+    this.recordLog({
+      id: run.runId,
+      flowName: run.flowName,
+      flowVersion: run.flowVersion,
+      status: "cancelled",
+      startedAt: run.startedAt,
+      completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      durationMs: Date.now() - run.startTime,
+      trigger: {
+        type: run.context?.event ?? "manual",
+        userId: run.context?.userId,
+        object: run.context?.object
+      },
+      steps: run.steps,
+      error: reason
+    });
+    return true;
+  }
   /**
    * Walk a failed run's `$parentRunId` chain and fail each suspended
    * ancestor (see {@link failSuspendedRun}). Bounded so a corrupt context
@@ -987,6 +1033,13 @@ ${failures.join("\n")}`
    * Detect cycles in the flow graph (DAG validation).
    * Uses DFS with coloring (white/gray/black) to detect back edges.
    * Throws an error with cycle details if a cycle is found.
+   *
+   * ADR-0044: edges explicitly typed `back` (declared back-edges — e.g. a
+   * revise/rework loop re-entering an approval node) are excluded from the
+   * analysis: the graph **minus `back` edges** must be a DAG. An unmarked
+   * cycle is still rejected — authors opt in edge by edge. At run time a
+   * `back` edge traverses like any default edge; the re-entry runaway guard
+   * lives in {@link executeNode}.
    */
   detectCycles(flow) {
     const WHITE = 0, GRAY = 1, BLACK = 2;
@@ -998,6 +1051,7 @@ ${failures.join("\n")}`
       adj.set(node.id, []);
     }
     for (const edge of flow.edges) {
+      if (edge.type === "back") continue;
       const targets = adj.get(edge.source);
       if (targets) targets.push(edge.target);
     }
@@ -1027,7 +1081,9 @@ ${failures.join("\n")}`
       if (color.get(node.id) === WHITE) {
         const cycle = dfs(node.id);
         if (cycle) {
-          throw new Error(`Flow contains a cycle: ${cycle.join(" \u2192 ")}. Only DAG flows are allowed.`);
+          throw new Error(
+            `Flow contains a cycle: ${cycle.join(" \u2192 ")}. Only DAG flows are allowed \u2014 to author an intentional rework loop, mark the cycle-closing edge with type: 'back' (ADR-0044).`
+          );
         }
       }
     }
@@ -1071,6 +1127,15 @@ ${failures.join("\n")}`
    */
   async executeNode(node, flow, variables, context, steps) {
     if (node.type === "end") return;
+    const priorVisits = steps.reduce(
+      (n, s) => s.nodeId === node.id && s.parentNodeId === void 0 ? n + 1 : n,
+      0
+    );
+    if (priorVisits >= _AutomationEngine.MAX_NODE_REENTRIES) {
+      throw new Error(
+        `Node '${node.id}' was entered ${priorVisits} times in one run \u2014 aborting as a runaway loop (back-edge cycles must terminate; see ADR-0044)`
+      );
+    }
     const stepStart = Date.now();
     const stepStartedAt = (/* @__PURE__ */ new Date()).toISOString();
     const executor = this.nodeExecutors.get(node.type);
@@ -1496,6 +1561,14 @@ ${failures.join("\n")}`
     }
   }
 };
+/**
+ * ADR-0044: maximum times a single node may be (re-)entered at the top
+ * level of one run before the engine aborts it as a runaway back-edge
+ * loop. Generous on purpose — the product guard (`maxRevisions`) sits
+ * orders of magnitude lower.
+ */
+_AutomationEngine.MAX_NODE_REENTRIES = 100;
+var AutomationEngine = _AutomationEngine;
 
 // src/suspended-run-store.ts
 var TABLE = "sys_automation_run";