@objectstack/service-automation 9.2.0 → 9.3.0

package/dist/index.d.cts

@@ -262,6 +262,13 @@ interface SuspendedRunStore {
     list(): Promise<SuspendedRun[]>;
 }
 declare class AutomationEngine implements IAutomationService {
+    /**
+     * 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.
+     */
+    static readonly MAX_NODE_REENTRIES = 100;
     private flows;
     private flowEnabled;
     private flowVersionHistory;
@@ -355,7 +362,7 @@ declare class AutomationEngine implements IAutomationService {
     unregisterTrigger(type: string): void;
     /**
      * 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.
@@ -476,6 +483,16 @@ declare class AutomationEngine implements IAutomationService {
      * descendant fails — the ancestor awaiting it can never be resumed.
      */
     private failSuspendedRun;
+    /**
+     * 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.
+     */
+    cancelRun(runId: string, reason?: string): Promise<boolean>;
     /**
      * Walk a failed run's `$parentRunId` chain and fail each suspended
      * ancestor (see {@link failSuspendedRun}). Bounded so a corrupt context
@@ -541,6 +558,13 @@ declare class AutomationEngine implements IAutomationService {
      * 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}.
      */
     private detectCycles;
     /**
@@ -1135,6 +1159,37 @@ declare const SysAutomationRun: Omit<{
         }[] | undefined;
         searchableFields?: string[] | undefined;
         filterableFields?: string[] | undefined;
+        userFilters?: {
+            element: "toggle" | "tabs" | "dropdown";
+            fields?: {
+                field: string;
+                label?: string | undefined;
+                type?: "boolean" | "text" | "select" | "multi-select" | "date-range" | undefined;
+                options?: {
+                    value: string | number | boolean;
+                    label: string;
+                    color?: string | undefined;
+                }[] | undefined;
+                showCount?: boolean | undefined;
+                defaultValues?: (string | number | boolean)[] | undefined;
+            }[] | undefined;
+            tabs?: {
+                name: string;
+                pinned: boolean;
+                isDefault: boolean;
+                visible: boolean;
+                label?: string | undefined;
+                icon?: string | undefined;
+                view?: string | undefined;
+                filter?: {
+                    field: string;
+                    operator: string;
+                    value?: string | number | boolean | (string | number)[] | null | undefined;
+                }[] | undefined;
+                order?: number | undefined;
+            }[] | undefined;
+            showAllRecords?: boolean | undefined;
+        } | undefined;
         resizable?: boolean | undefined;
         striped?: boolean | undefined;
         bordered?: boolean | undefined;
@@ -1247,7 +1302,7 @@ declare const SysAutomationRun: Omit<{
         } | undefined;
         appearance?: {
             showDescription: boolean;
-            allowedVisualizations?: ("map" | "grid" | "kanban" | "calendar" | "gantt" | "gallery" | "timeline")[] | undefined;
+            allowedVisualizations?: ("map" | "grid" | "kanban" | "calendar" | "gantt" | "gallery" | "timeline" | "chart")[] | undefined;
         } | undefined;
         tabs?: {
             name: string;
@@ -1441,6 +1496,8 @@ declare const SysAutomationRun: Omit<{
         method?: "POST" | "PATCH" | "PUT" | "DELETE" | undefined;
         bodyExtra?: Record<string, unknown> | undefined;
         mode?: "custom" | "delete" | "edit" | "create" | undefined;
+        opensInNewTab?: boolean | undefined;
+        newTabUrl?: string | undefined;
         timeout?: number | undefined;
         aria?: {
             ariaLabel?: string | undefined;

package/dist/index.d.ts

@@ -262,6 +262,13 @@ interface SuspendedRunStore {
     list(): Promise<SuspendedRun[]>;
 }
 declare class AutomationEngine implements IAutomationService {
+    /**
+     * 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.
+     */
+    static readonly MAX_NODE_REENTRIES = 100;
     private flows;
     private flowEnabled;
     private flowVersionHistory;
@@ -355,7 +362,7 @@ declare class AutomationEngine implements IAutomationService {
     unregisterTrigger(type: string): void;
     /**
      * 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.
@@ -476,6 +483,16 @@ declare class AutomationEngine implements IAutomationService {
      * descendant fails — the ancestor awaiting it can never be resumed.
      */
     private failSuspendedRun;
+    /**
+     * 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.
+     */
+    cancelRun(runId: string, reason?: string): Promise<boolean>;
     /**
      * Walk a failed run's `$parentRunId` chain and fail each suspended
      * ancestor (see {@link failSuspendedRun}). Bounded so a corrupt context
@@ -541,6 +558,13 @@ declare class AutomationEngine implements IAutomationService {
      * 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}.
      */
     private detectCycles;
     /**
@@ -1135,6 +1159,37 @@ declare const SysAutomationRun: Omit<{
         }[] | undefined;
         searchableFields?: string[] | undefined;
         filterableFields?: string[] | undefined;
+        userFilters?: {
+            element: "toggle" | "tabs" | "dropdown";
+            fields?: {
+                field: string;
+                label?: string | undefined;
+                type?: "boolean" | "text" | "select" | "multi-select" | "date-range" | undefined;
+                options?: {
+                    value: string | number | boolean;
+                    label: string;
+                    color?: string | undefined;
+                }[] | undefined;
+                showCount?: boolean | undefined;
+                defaultValues?: (string | number | boolean)[] | undefined;
+            }[] | undefined;
+            tabs?: {
+                name: string;
+                pinned: boolean;
+                isDefault: boolean;
+                visible: boolean;
+                label?: string | undefined;
+                icon?: string | undefined;
+                view?: string | undefined;
+                filter?: {
+                    field: string;
+                    operator: string;
+                    value?: string | number | boolean | (string | number)[] | null | undefined;
+                }[] | undefined;
+                order?: number | undefined;
+            }[] | undefined;
+            showAllRecords?: boolean | undefined;
+        } | undefined;
         resizable?: boolean | undefined;
         striped?: boolean | undefined;
         bordered?: boolean | undefined;
@@ -1247,7 +1302,7 @@ declare const SysAutomationRun: Omit<{
         } | undefined;
         appearance?: {
             showDescription: boolean;
-            allowedVisualizations?: ("map" | "grid" | "kanban" | "calendar" | "gantt" | "gallery" | "timeline")[] | undefined;
+            allowedVisualizations?: ("map" | "grid" | "kanban" | "calendar" | "gantt" | "gallery" | "timeline" | "chart")[] | undefined;
         } | undefined;
         tabs?: {
             name: string;
@@ -1441,6 +1496,8 @@ declare const SysAutomationRun: Omit<{
         method?: "POST" | "PATCH" | "PUT" | "DELETE" | undefined;
         bodyExtra?: Record<string, unknown> | undefined;
         mode?: "custom" | "delete" | "edit" | "create" | undefined;
+        opensInNewTab?: boolean | undefined;
+        newTabUrl?: string | undefined;
         timeout?: number | undefined;
         aria?: {
             ariaLabel?: string | undefined;

package/dist/index.js

@@ -13,7 +13,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();
@@ -208,7 +208,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.
@@ -237,6 +237,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;
   }
   /**
@@ -820,6 +826,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
@@ -951,6 +997,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;
@@ -962,6 +1015,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);
     }
@@ -991,7 +1045,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).`
+          );
         }
       }
     }
@@ -1035,6 +1091,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);
@@ -1460,6 +1525,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";