@objectstack/plugin-approvals 17.0.0-rc.3 → 17.0.0-rc.5

package/dist/index.js

@@ -1334,13 +1334,15 @@ var init_translations = __esm({
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  APPROVAL_REVISE_CORRELATION_PREFIX: () => APPROVAL_REVISE_CORRELATION_PREFIX,
   ApprovalService: () => ApprovalService,
   ApprovalsServicePlugin: () => ApprovalsServicePlugin,
   SysApprovalAction: () => SysApprovalAction,
   SysApprovalApprover: () => SysApprovalApprover,
   SysApprovalDelegation: () => SysApprovalDelegation,
   SysApprovalRequest: () => SysApprovalRequest,
-  registerApprovalNode: () => registerApprovalNode
+  registerApprovalNode: () => registerApprovalNode,
+  registerApprovalReviseNode: () => registerApprovalReviseNode
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -3445,6 +3447,47 @@ var _ApprovalService = class _ApprovalService {
       );
     }
   }
+  /**
+   * The run named by a recorded outcome cannot be advanced at all, because no
+   * automation engine in THIS process implements the capability it needs
+   * (#4420). Returns the reason, or `undefined` when the capability is there
+   * and the caller should proceed.
+   *
+   * **Why this is not simply "not our problem".** Approvals is legitimately
+   * usable with no engine attached, and {@link assertRunResumable} deliberately
+   * stays out of the way for that reason. But "no engine is attached" and "no
+   * run is waiting" are different facts, and only the second is benign: a
+   * `flow_run_id` on the row is the request's OWN declaration that a run is
+   * parked on this decision. Deciding it in a process that cannot resume it
+   * reproduces #4420's reported half-state exactly — a durable decision, a
+   * mirrored status field frozen mid-workflow, a flow parked forever — while
+   * the caller is answered HTTP 200. The engine-less composition is the one
+   * path the #4420 fix left silent, because every guard it added hangs off an
+   * engine that is not there.
+   *
+   * **So the outcome stands, but it is never silent.** Rolling the decision
+   * back is not on the table (a human really did decide, and the row is
+   * already durable), and refusing every such call would break the standalone
+   * compositions the pre-flight protects. What is owed is the report: `error`
+   * level per AGENTS.md's durability rule — persisted state and runtime state
+   * disagree and nothing looks broken from the outside — plus a `resumeError`
+   * on the response, so `resumed: false` carries its reason instead of leaving
+   * the caller to guess whether a resume was even attempted.
+   *
+   * Reuses the registered `RESUME_FAILED` code (ADR-0112 ledger) and
+   * {@link serviceResume}'s message shape: the fact being reported — an
+   * outcome recorded whose run did not advance — is the same one, and this
+   * needs no new vocabulary of its own.
+   */
+  missingRunCapability(runId, requestId, what, capability) {
+    const fn = capability === "resume" ? this.automation?.resume : this.automation?.cancelRun;
+    if (typeof fn === "function") return void 0;
+    this.logger?.error?.(
+      "[approvals] no automation engine to advance the recorded outcome \u2014 the run is stranded",
+      { request: requestId, run: runId, outcome: what, capability }
+    );
+    return `${capability} of run '${runId}' failed [RESUME_FAILED]: ${what} was recorded on request ${requestId}, but no automation engine in this process can ${capability} its flow run \u2014 the run stays parked and the record's mirrored status will not advance. Compose the automation service in this host, or recall the request to release the record.`;
+  }
   /**
    * Resume the run behind an outcome that has ALREADY been written down, and
    * fail loudly when it cannot be (#4420).
@@ -3456,12 +3499,17 @@ var _ApprovalService = class _ApprovalService {
    * everything it catches never reaches a write.
    *
    * `RESUME_IN_PROGRESS` is the exception — a concurrent resume is already
-   * advancing the run, so the outcome stands and only `resumed` is false.
+   * advancing the run, so the outcome stands and only `resumed` is false. So
+   * is a composition with no engine at all ({@link missingRunCapability}),
+   * which cannot throw without breaking every standalone deployment — it
+   * reports through `resumeError` instead.
    *
    * @param what - how the recorded outcome reads in the error, e.g.
    *   `"the approve decision"`.
    */
   async resumeRecordedOutcome(runId, requestId, what, signal) {
+    const missing = this.missingRunCapability(runId, requestId, what, "resume");
+    if (missing) return { resumed: false, resumeError: missing };
     try {
       await this.serviceResume(runId, signal);
       return { resumed: true };
@@ -3504,7 +3552,7 @@ var _ApprovalService = class _ApprovalService {
     const result = await this.decideNode(requestId, input, context);
     let resumed = false;
     let resumeError;
-    if (result.finalized && result.runId && typeof this.automation?.resume === "function") {
+    if (result.finalized && result.runId) {
       const branchLabel = result.decision === "approve" ? import_automation.APPROVAL_BRANCH_LABELS.approve : import_automation.APPROVAL_BRANCH_LABELS.reject;
       const outcome = await this.resumeRecordedOutcome(
         result.runId,
@@ -3541,7 +3589,7 @@ var _ApprovalService = class _ApprovalService {
    *
    * ADR-0044: also valid on the LATEST `returned` request of its run — the
    * submitter abandons the revision window instead of resubmitting. The run
-   * is then paused at the revise wait node (no reject edge), so it is
+   * is then paused at the revise-window node (no reject edge), so it is
    * terminally cancelled via {@link ApprovalResumeSurface.cancelRun} rather
    * than resumed.
    */
@@ -3599,33 +3647,39 @@ var _ApprovalService = class _ApprovalService {
     let resumed = false;
     let resumeError;
     if (inReviseWindow) {
-      if (runId && typeof this.automation?.cancelRun === "function") {
+      if (runId) {
+        resumeError = this.missingRunCapability(runId, requestId, "the recall", "cancelRun");
+        if (!resumeError) {
+          try {
+            await this.automation.cancelRun(runId, `approval request ${requestId} recalled during revision`);
+          } catch (err) {
+            resumeError = err?.message ?? String(err);
+            this.logger?.error?.("[approvals] cancelRun after revise-window recall failed \u2014 the run may be stranded", {
+              request: requestId,
+              run: runId,
+              error: resumeError
+            });
+          }
+        }
+      }
+    } else if (runId) {
+      resumeError = this.missingRunCapability(runId, requestId, "the recall", "resume");
+      if (!resumeError) {
         try {
-          await this.automation.cancelRun(runId, `approval request ${requestId} recalled during revision`);
+          await this.serviceResume(runId, {
+            branchLabel: import_automation.APPROVAL_BRANCH_LABELS.reject,
+            output: { decision: "recall", requestId }
+          });
+          resumed = true;
         } catch (err) {
           resumeError = err?.message ?? String(err);
-          this.logger?.error?.("[approvals] cancelRun after revise-window recall failed \u2014 the run may be stranded", {
+          this.logger?.error?.("[approvals] resume after recall failed \u2014 the run may be stranded", {
             request: requestId,
             run: runId,
             error: resumeError
           });
         }
       }
-    } else if (runId && typeof this.automation?.resume === "function") {
-      try {
-        await this.serviceResume(runId, {
-          branchLabel: import_automation.APPROVAL_BRANCH_LABELS.reject,
-          output: { decision: "recall", requestId }
-        });
-        resumed = true;
-      } catch (err) {
-        resumeError = err?.message ?? String(err);
-        this.logger?.error?.("[approvals] resume after recall failed \u2014 the run may be stranded", {
-          request: requestId,
-          run: runId,
-          error: resumeError
-        });
-      }
     }
     const fresh = await this.readBackRequest(requestId, context);
     return { request: fresh, runId, resumed, ...resumeError ? { resumeError } : {} };
@@ -3635,7 +3689,7 @@ var _ApprovalService = class _ApprovalService {
    * ADR-0044 send back for revision. Finalises the pending request as
    * `returned` (a third terminal state — approver-initiated rework, distinct
    * from submitter-initiated `recalled`) and resumes the owning flow run down
-   * its `revise` edge to a wait point: the record lock (keyed on `pending`)
+   * its `revise` edge to the revise window: the record lock (keyed on `pending`)
    * releases, the submitter reworks the data, then {@link resubmit}s.
    *
    * Requires the approval node to declare a `revise` out-edge — validated
@@ -3710,7 +3764,7 @@ var _ApprovalService = class _ApprovalService {
       }
       let resumed2 = false;
       let resumeError2;
-      if (runId && typeof this.automation?.resume === "function") {
+      if (runId) {
         const outcome = await this.resumeRecordedOutcome(
           runId,
           requestId,
@@ -3758,7 +3812,7 @@ var _ApprovalService = class _ApprovalService {
     }
     let resumed = false;
     let resumeError;
-    if (runId && typeof this.automation?.resume === "function") {
+    if (runId) {
       const outcome = await this.resumeRecordedOutcome(
         runId,
         requestId,
@@ -3790,7 +3844,7 @@ var _ApprovalService = class _ApprovalService {
   /**
    * ADR-0044 resubmit after rework. Valid on the LATEST `returned` request of
    * its run, submitter-only. Audits `resubmit` on the returned (round-N)
-   * request and resumes the run from the revise wait node; traversal walks
+   * request and resumes the run from the revise-window node; traversal walks
    * the declared back-edge into the approval node, whose executor opens the
    * round-N+1 request — fresh approver slate, record re-locks.
    */
@@ -3838,7 +3892,7 @@ var _ApprovalService = class _ApprovalService {
     }, { context: SYSTEM_CTX2 });
     let resumed = false;
     let resumeError;
-    if (runId && typeof this.automation?.resume === "function") {
+    if (runId) {
       const outcome = await this.resumeRecordedOutcome(
         runId,
         requestId,
@@ -3859,6 +3913,21 @@ var _ApprovalService = class _ApprovalService {
    * out-edge before send-back is allowed — the engine's branch-label fallback
    * (no matching label ⇒ ALL out-edges) must never be reachable from a user
    * action.
+   *
+   * Since #3823 it also checks WHAT that edge targets: the revise window must
+   * be an `approval_revise` node, the pause this service owns. ADR-0044 D3
+   * pointed the edge at an ordinary `wait`, which is `resumeAuthority: 'any'`,
+   * so a raw engine resume walked the resubmit back-edge with no submitter
+   * check, no `resubmit` audit row, and — with a pending request colliding on
+   * the record — destroyed the run by consuming the suspension before the
+   * re-entry failed. Refused HERE, before any mutation, for the same reason the
+   * missing-edge check is: a run must never be parked in a revise window that
+   * something other than {@link resubmit} can advance.
+   *
+   * Also refused at authoring time — `flow-approval-revise-target-not-service-owned`
+   * in `@objectstack/lint` gates `os build` / `os validate` / `os lint` and the
+   * runtime metadata publish path — so a flow reaching this check at all is one
+   * published before that gate existed.
    */
   async assertReviseEdge(raw, nodeId) {
     const processName = String(raw.process_name ?? "");
@@ -3867,12 +3936,23 @@ var _ApprovalService = class _ApprovalService {
       throw new Error("VALIDATION_FAILED: send-back requires the owning flow definition (automation engine unavailable)");
     }
     const flow = await this.automation.getFlow(flowName);
-    const hasRevise = Array.isArray(flow?.edges) && flow.edges.some((e) => e?.source === nodeId && e?.label === import_automation.APPROVAL_BRANCH_LABELS.revise);
-    if (!hasRevise) {
+    const reviseEdges = Array.isArray(flow?.edges) ? flow.edges.filter((e) => e?.source === nodeId && e?.label === import_automation.APPROVAL_BRANCH_LABELS.revise) : [];
+    if (reviseEdges.length === 0) {
       throw new Error(
         `VALIDATION_FAILED: approval node '${nodeId}' has no '${import_automation.APPROVAL_BRANCH_LABELS.revise}' out-edge \u2014 the flow does not support send-back for revision`
       );
     }
+    const nodeTypeById = new Map(
+      (Array.isArray(flow?.nodes) ? flow.nodes : []).filter((n) => typeof n?.id === "string").map((n) => [n.id, typeof n.type === "string" ? n.type : ""])
+    );
+    for (const edge of reviseEdges) {
+      const target = typeof edge?.target === "string" ? edge.target : "";
+      const targetType = nodeTypeById.get(target);
+      if (targetType === import_automation.APPROVAL_REVISE_NODE_TYPE) continue;
+      throw new Error(
+        `VALIDATION_FAILED: approval node '${nodeId}' has a '${import_automation.APPROVAL_BRANCH_LABELS.revise}' out-edge into node '${target || "(unknown)"}'` + (targetType === void 0 ? " which the flow does not declare" : ` of type '${targetType || "(untyped)"}'`) + `, but the revise window must be an '${import_automation.APPROVAL_REVISE_NODE_TYPE}' node \u2014 that pause continues only through this service (submitter-only, audited, and refusing a colliding pending request), and any other node type there is resumable by anyone with the run id (amended ADR-0044, #3823). Fix the flow: set node '${target || "<revise target>"}' to type '${import_automation.APPROVAL_REVISE_NODE_TYPE}'.`
+      );
+    }
   }
   /**
    * ADR-0044 guard: a `returned` request is only actionable (resubmit /
@@ -5604,8 +5684,6 @@ function bindApprovalLockHook(engine, logger) {
     const changedFields = Object.keys(data).filter((k) => k !== "id" && k !== "updated_at");
     if (changedFields.length === 0) return;
     if (ctx?.session?.isSystem) return;
-    const roles = ctx?.session?.roles ?? [];
-    if (Array.isArray(roles) && roles.includes("admin")) return;
     const gating = await gatingRequests(engine, ctx, object);
     if (gating.length === 0) return;
     const writerRun = ctx?.provenance?.flowRunId;
@@ -5627,8 +5705,6 @@ function bindDelegationWriteGuard(engine, logger) {
   const makeGuard = (isInsert) => async (ctx) => {
     const session = ctx?.session ?? {};
     if (session.isSystem) return;
-    const roles = session.roles ?? [];
-    if (Array.isArray(roles) && roles.includes("admin")) return;
     const userId = session.userId != null ? String(session.userId) : "";
     const data = ctx?.input?.data;
     const rows = Array.isArray(data) ? data : data && typeof data === "object" ? [data] : [];
@@ -5661,7 +5737,46 @@ function unbindAllHooks(engine) {
 }
 
 // src/approval-node.ts
+var import_automation3 = require("@objectstack/spec/automation");
+
+// src/approval-revise-node.ts
 var import_automation2 = require("@objectstack/spec/automation");
+var APPROVAL_REVISE_CORRELATION_PREFIX = "approval_revise:";
+function registerApprovalReviseNode(automation, logger) {
+  automation.registerNodeExecutor({
+    type: import_automation2.APPROVAL_REVISE_NODE_TYPE,
+    descriptor: (0, import_automation2.defineActionDescriptor)({
+      type: import_automation2.APPROVAL_REVISE_NODE_TYPE,
+      version: "1.0.0",
+      name: "Revise Window",
+      description: "Durable pause an approval send-back parks the run on while the submitter reworks the record. Continues only through the approvals service (resubmit), which re-enters the approval node over the declared back-edge.",
+      icon: "pencil",
+      // Waits on a human — the same category as `approval` and `screen`.
+      category: "human",
+      paradigms: ["flow"],
+      source: "plugin",
+      supportsPause: true,
+      isAsync: true,
+      // #3823 / amended ADR-0044: THE point of this node type. The revise
+      // window is a service-owned continuation, so the #3801 gate must refuse
+      // a raw resume of it — which it does for any node type declaring this.
+      resumeAuthority: "service"
+      // No config: the window is pure position in the graph. Left schemaless
+      // (like `wait` / `subflow` / `decision`) rather than declaring an empty
+      // object, so nothing invents an authorable surface that has no reader.
+    }),
+    async execute(node) {
+      return {
+        success: true,
+        suspend: true,
+        correlation: `${APPROVAL_REVISE_CORRELATION_PREFIX}${node.id}`
+      };
+    }
+  });
+  logger?.info?.("[approvals] approval revise-window node executor registered");
+}
+
+// src/approval-node.ts
 var SYSTEM_CTX4 = { isSystem: true, positions: [], permissions: [] };
 function nestVariables(variables) {
   const vars = {};
@@ -5679,10 +5794,11 @@ function nestVariables(variables) {
   return vars;
 }
 function registerApprovalNode(automation, service, logger) {
+  registerApprovalReviseNode(automation, logger);
   automation.registerNodeExecutor({
-    type: import_automation2.APPROVAL_NODE_TYPE,
-    descriptor: (0, import_automation2.defineActionDescriptor)({
-      type: import_automation2.APPROVAL_NODE_TYPE,
+    type: import_automation3.APPROVAL_NODE_TYPE,
+    descriptor: (0, import_automation3.defineActionDescriptor)({
+      type: import_automation3.APPROVAL_NODE_TYPE,
       version: "1.0.0",
       name: "Approval",
       description: "Route a record for human approval; suspends the flow until a decision, then continues down the approve / reject branch.",
@@ -5705,10 +5821,10 @@ function registerApprovalNode(automation, service, logger) {
       // Publish the node's config contract (ADR-0018 §configSchema) so the
       // Studio flow designer renders the Approval property form from the engine
       // rather than a hardcoded client form — the engine owns the shape.
-      configSchema: (0, import_automation2.getApprovalNodeConfigJsonSchema)()
+      configSchema: (0, import_automation3.getApprovalNodeConfigJsonSchema)()
     }),
     async execute(node, variables, context) {
-      const parsed = import_automation2.ApprovalNodeConfigSchema.safeParse(node.config ?? {});
+      const parsed = import_automation3.ApprovalNodeConfigSchema.safeParse(node.config ?? {});
       if (!parsed.success) {
         const msg = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
         return { success: false, error: `Approval node '${node.id}' has invalid config: ${msg}` };
@@ -6000,12 +6116,14 @@ var ApprovalsServicePlugin = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  APPROVAL_REVISE_CORRELATION_PREFIX,
   ApprovalService,
   ApprovalsServicePlugin,
   SysApprovalAction,
   SysApprovalApprover,
   SysApprovalDelegation,
   SysApprovalRequest,
-  registerApprovalNode
+  registerApprovalNode,
+  registerApprovalReviseNode
 });
 //# sourceMappingURL=index.js.map