@objectstack/plugin-approvals 17.3.0 → 17.4.0

package/dist/index.mjs

@@ -2324,11 +2324,10 @@ import {
 } from "@objectstack/spec/automation";
 import { ExpressionEngine, collectCelRootIdentifiers } from "@objectstack/formula";
 import { createRecordOrganizationResolver } from "@objectstack/metadata-core";
-import { keysetWalk } from "@objectstack/types";
+import { keysetWalk, strandedDecisionFailure } from "@objectstack/types";
 import {
   ADMIN_FULL_ACCESS,
   ORGANIZATION_ADMIN_GRANTS,
-  BUILTIN_IDENTITY_PLATFORM_ADMIN,
   BUILTIN_IDENTITY_ORG_OWNER,
   BUILTIN_IDENTITY_ORG_ADMIN
 } from "@objectstack/spec/identity";
@@ -2499,10 +2498,22 @@ var TERMINAL_RUN_STATUSES = /* @__PURE__ */ new Set([
   "timed_out"
 ]);
 var STRANDABLE_REQUEST_STATUSES = ["approved", "rejected", "returned"];
+var STRANDED_CONTINUATION_KEY = "__strandedContinuation";
+var CONTINUATIONS_A_STATUS_CAN_ISSUE = {
+  approved: ["approve"],
+  rejected: ["reject"],
+  returned: ["revise", "resubmit"],
+  recalled: ["recall"]
+};
 function classifyStrandedRunState(run) {
   if (!run) return "missing";
   switch (run.status) {
-    // The resume consumed the pause and a downstream node threw. Reported.
+    // A terminal `failed` row. Reported — and, when the engine can be asked,
+    // refined by the third oracle ({@link refineFailedRunState}) into which of
+    // the three `failed` shapes it is. This arm alone cannot tell them apart:
+    // the row reads identically for a resume that consumed the pause and
+    // threw downstream (repairable) and for an ancestor `failAncestors`
+    // cascade-failed (not). `'failed'` here means "reported, undifferentiated".
     case "failed":
       return "failed";
     // ── The negatives, each for its own reason ──────────────────────────────
@@ -2527,6 +2538,28 @@ function classifyStrandedRunState(run) {
       return void 0;
   }
 }
+function refineFailedRunState(verdict) {
+  if (verdict.repairable) return "repairable";
+  switch (verdict.reason) {
+    // The strand happened; the store could not keep the snapshot, and the
+    // engine asked holds no hot copy. Its own class — see the type below.
+    case "SNAPSHOT_DROPPED":
+      return "snapshot_dropped";
+    // Neither witness holds anything: cascade-failed, or never paused.
+    case "NO_CONSUMED_SUSPENSION":
+      return "unrepairable";
+    // Re-armed between the two reads (an operator's restore landed while this
+    // scan was running): the run is alive and resumable, which is what the
+    // first oracle would have said a moment later. Not stranded.
+    case "RUN_SUSPENDED":
+      return void 0;
+    // An answer this build does not know (an engine ahead of this plugin).
+    // Fail-closed exactly as an absent member: reported, undifferentiated —
+    // never condemned on a word this code cannot read.
+    default:
+      return "failed";
+  }
+}
 var ACTION_TOKEN_TTL_MS = 72 * 60 * 60 * 1e3;
 var SYSTEM_CTX2 = { isSystem: true, positions: [], permissions: [] };
 var RECORD_DELETE_CANCEL_LIMIT = 200;
@@ -2840,7 +2873,7 @@ var _ApprovalService = class _ApprovalService {
     const perms = Array.isArray(context.permissions) ? context.permissions : [];
     const positions = Array.isArray(context.positions) ? context.positions : [];
     const posture = context.posture;
-    const isPlatformAdmin = posture === "PLATFORM_ADMIN" || perms.includes(ADMIN_FULL_ACCESS) || positions.includes(BUILTIN_IDENTITY_PLATFORM_ADMIN);
+    const isPlatformAdmin = posture === "PLATFORM_ADMIN" || perms.includes(ADMIN_FULL_ACCESS);
     if (isPlatformAdmin) return true;
     const isTenantAdmin = posture === "TENANT_ADMIN" || ORGANIZATION_ADMIN_GRANTS.some((n) => perms.includes(n)) || positions.includes(BUILTIN_IDENTITY_ORG_OWNER) || positions.includes(BUILTIN_IDENTITY_ORG_ADMIN);
     if (!isTenantAdmin) return false;
@@ -3414,7 +3447,56 @@ var _ApprovalService = class _ApprovalService {
     if (!organizationId) return filter;
     return { ...filter, $or: [{ organization_id: organizationId }, { organization_id: null }] };
   }
-  /** Recursive department — walks `sys_business_unit.parent_business_unit_id`. */
+  /**
+   * Tenant scope for the `sys_business_unit_member` read — a STRICT equality,
+   * deliberately NOT {@link businessUnitOrgScope} (#14946).
+   *
+   * The two screens answer different questions. The UNIT is the anchor the
+   * approver NAMES, and a seeded unit carries `organization_id = null` by
+   * construction (a seed cannot know the id the runtime mints at boot), so
+   * #3807 admits the null there on purpose. The MEMBER rows are the SET BEING
+   * ROUTED TO — enumerated by the platform, never named by anyone — and a
+   * seeded unit id exists identically in every tenant. Before this screen the
+   * member read carried no organization predicate at all, under
+   * {@link SYSTEM_CTX} which carries no tenant either, so tenant A's request
+   * resolved the shared unit and then collected EVERY tenant's membership rows
+   * hanging off it: approval authority over A's record, routed to B's users.
+   *
+   * Why the null arm is NOT copied here — measured on this tree:
+   *   - `sys_business_unit_member` declares no `organization_id`; the column
+   *     is injected (`applySystemFields`) and the tenancy census lists it in;
+   *   - REST / session writes fill it (`SqlDriver.injectTenantOnInsert`);
+   *   - seed replay does NOT (`seed-loader.ts` withholds its `fallbackOrgId`
+   *     from every `sys_` object), and elevated system-context writes do NOT
+   *     (`unclassified` in `PLATFORM_OBJECT_TENANCY`, tracked as #14570).
+   * So a NULL on a member row means UNKNOWN tenancy, not "platform-global",
+   * and unknown tenancy is not a member of this organization. This is the
+   * ruling `plugin-sharing`'s `memberScope` already applies to the same rows
+   * (#14547 / #14949), and the posture this file already takes for
+   * `sys_team_member` and `sys_user_position`.
+   *
+   * The cost is declared, not hidden: an organization whose MEMBERSHIP rows
+   * were seeded or system-written expands to nobody even on a unit it can
+   * see. That is not silent — the graph-type fallback in `expandApprover`
+   * warns `expanded to nobody` (#3807) and `onEmptyApprovers` governs the
+   * request as for any unstaffed target — and the repair is to stamp the
+   * membership rows, never to widen this screen. ⛔ Do not "unify" the two
+   * screens: one method serving both re-opens whichever half it does not
+   * implement.
+   */
+  businessUnitMemberScope(filter, organizationId) {
+    if (!organizationId) return filter;
+    return { ...filter, organization_id: organizationId };
+  }
+  /**
+   * Recursive department — walks `sys_business_unit.parent_business_unit_id`.
+   *
+   * Two tenant screens, and they are different on purpose: the UNIT rows
+   * (seed check and descent) go through the null-inclusive
+   * {@link businessUnitOrgScope}; the MEMBER read goes through the strict
+   * {@link businessUnitMemberScope}. `organizationId` is the DIRECTORY
+   * organization the approver resolves in (ADR-0105 D9), for both.
+   */
   async expandBusinessUnitUsers(businessUnitId, organizationId) {
     if (!businessUnitId) return [];
     try {
@@ -3454,7 +3536,11 @@ var _ApprovalService = class _ApprovalService {
     let rows = [];
     try {
       rows = await this.engine.find("sys_business_unit_member", {
-        where: { business_unit_id: { $in: Array.from(seen) } },
+        // #14946: tenant-screened — {@link businessUnitMemberScope} is STRICT
+        // on purpose and is not {@link businessUnitOrgScope}. The units above
+        // proved their tenancy (or are seeded); these rows have not, and the
+        // shared seeded unit id is exactly where other tenants' rows sit.
+        where: this.businessUnitMemberScope({ business_unit_id: { $in: Array.from(seen) } }, organizationId),
         fields: ["user_id"],
         limit: 1e4,
         context: SYSTEM_CTX2
@@ -4167,6 +4253,7 @@ var _ApprovalService = class _ApprovalService {
         `resume of run '${runId}' failed${reported.code ? ` [${reported.code}]` : ""}: ${reported.error ?? "unknown error"}`
       );
       err.resumeCode = reported.code;
+      err.resumeStatus = reported.status;
       throw err;
     }
   }
@@ -4174,6 +4261,22 @@ var _ApprovalService = class _ApprovalService {
   static resumeCodeOf(err) {
     return err?.resumeCode;
   }
+  /**
+   * The engine's own run-state discriminator behind a {@link serviceResume}
+   * rejection — `AutomationResult.status` — if the engine reported one
+   * (#13807).
+   *
+   * Read as a SIBLING of {@link resumeCodeOf}, never as a substitute: the two
+   * answer different questions and the stranded exit proves they are not
+   * interchangeable. It reports `status: 'stranded'` and **no `code` at all**
+   * (`service-automation` `engine.ts`, the resume catch arm), so a door that
+   * reads only the code sees an unnamed failure and cannot tell a repairable
+   * strand from a dead run — which is how the platform's own repairability
+   * signal had a producer and zero consumers until this call site.
+   */
+  static resumeStatusOf(err) {
+    return err?.resumeStatus;
+  }
   /**
    * Refuse an operation whose whole point is to advance a flow run when that
    * run no longer exists — BEFORE anything is written down (#4420).
@@ -4267,10 +4370,33 @@ var _ApprovalService = class _ApprovalService {
    * which cannot throw without breaking every standalone deployment — it
    * reports through `resumeError` instead.
    *
+   * ## The throw is truthful, not merely loud (#13807)
+   *
+   * Maintainer ruling 2026-09-04 (decision batch #37, option B): this door
+   * KEEPS its status code — the effect landing while the run strands is still
+   * a failure and must still be reported as one — and stops discarding what
+   * the engine said. ⛔ Not "return 200", which the card forbids; ⛔ not
+   * atomic, because rolling a real human decision back is excluded by the
+   * #13937 shape-4 ruling, which binds this door's own writes too (a machine
+   * that re-armed strandings by itself would re-run the node that threw,
+   * forever, with nobody deciding it should).
+   *
+   * So the error carries {@link StrandedDecisionDetails} beside its prose:
+   * `finalized` (the decision stands), `decision`, `runId`, and `repairable`
+   * derived from the engine's `'stranded'` discriminator. Before this a caller
+   * had a 500 and a sentence — and 500 alone reads as "the rejection did not
+   * happen", which is the misreading that makes a caller retry or escalate
+   * against a decision that IS durable.
+   *
    * @param what - how the recorded outcome reads in the error, e.g.
    *   `"the approve decision"`.
+   * @param decision - the outcome label for the machine-readable envelope
+   *   (`'approve'` / `'reject'` / `'revise'` / `'resubmit'`). Passed
+   *   explicitly rather than parsed back out of `what` or the signal: the
+   *   prose is for humans and `output` is the flow's, and neither is a place
+   *   to keep a wire value.
    */
-  async resumeRecordedOutcome(runId, requestId, what, signal) {
+  async resumeRecordedOutcome(runId, requestId, what, signal, decision) {
     const missing = this.missingRunCapability(runId, requestId, what, "resume");
     if (missing) return { resumed: false, resumeError: missing };
     try {
@@ -4286,14 +4412,27 @@ var _ApprovalService = class _ApprovalService {
         });
         return { resumed: false, resumeError: reason };
       }
+      const status = _ApprovalService.resumeStatusOf(err);
+      const repairable = status === "stranded";
       this.logger?.error?.("[approvals] resume failed \u2014 the run is stranded", {
         request: requestId,
         run: runId,
         outcome: what,
-        error: reason
+        error: reason,
+        status,
+        repairable
       });
-      throw new Error(
-        `RESUME_FAILED: ${what} was recorded on request ${requestId}, but its flow run '${runId}' could not be resumed and is now stranded: ${reason}`
+      if (repairable) {
+        await this.journalStrandedContinuation(requestId, {
+          branchLabel: signal.branchLabel,
+          output: signal.output,
+          decision,
+          what
+        });
+      }
+      throw strandedDecisionFailure(
+        `RESUME_FAILED: ${what} was recorded on request ${requestId}, but its flow run '${runId}' could not be resumed and is now stranded: ${reason}`,
+        { finalized: true, decision, runId, repairable }
       );
     }
   }
@@ -4329,7 +4468,8 @@ var _ApprovalService = class _ApprovalService {
           // Reserved keys are spread LAST so no output can shadow them (the
           // whitelist already rejects them; this is defense in depth).
           output: { ...result.outputs ?? {}, decision: result.decision, requestId }
-        }
+        },
+        result.decision
       );
       resumed = outcome.resumed;
       resumeError = outcome.resumeError;
@@ -4344,7 +4484,7 @@ var _ApprovalService = class _ApprovalService {
     };
   }
   /**
-   * Withdraw a pending request (submitter only). Finalises the row as
+   * Withdraw an undecided request. Finalises the row as
    * `recalled`, releases the record lock (keyed on pending status), mirrors
    * the status field when configured, and resumes the owning flow run down
    * the `reject` branch with `output.decision = 'recall'` — leaving the run
@@ -4458,6 +4598,14 @@ var _ApprovalService = class _ApprovalService {
             run: runId,
             error: resumeError
           });
+          if (_ApprovalService.resumeStatusOf(err) === "stranded") {
+            await this.journalStrandedContinuation(requestId, {
+              branchLabel: APPROVAL_BRANCH_LABELS.reject,
+              output: { decision: "recall", requestId },
+              decision: "recall",
+              what: "the recall"
+            });
+          }
         }
       }
     }
@@ -4673,7 +4821,8 @@ var _ApprovalService = class _ApprovalService {
           {
             branchLabel: APPROVAL_BRANCH_LABELS.reject,
             output: { decision: "reject", autoRejected: true, requestId }
-          }
+          },
+          "reject"
         );
         resumed2 = outcome.resumed;
         resumeError2 = outcome.resumeError;
@@ -4721,7 +4870,8 @@ var _ApprovalService = class _ApprovalService {
         {
           branchLabel: APPROVAL_BRANCH_LABELS.revise,
           output: { decision: "revise", requestId }
-        }
+        },
+        "revise"
       );
       resumed = outcome.resumed;
       resumeError = outcome.resumeError;
@@ -4801,7 +4951,8 @@ var _ApprovalService = class _ApprovalService {
         {
           branchLabel: APPROVAL_BRANCH_LABELS.resubmit,
           output: { resubmitted: true, requestId }
-        }
+        },
+        "resubmit"
       );
       resumed = outcome.resumed;
       resumeError = outcome.resumeError;
@@ -5343,8 +5494,25 @@ var _ApprovalService = class _ApprovalService {
    * ⚠️ The widening does NOT reverse the conservatism: `completed`, `cancelled`
    * and `paused` are each still skipped, for reasons named one at a time in
    * `classifyStrandedRunState`, and an unrecognised status is skipped too.
-   * What the widening buys is that a `failed` run is now reported with
-   * `runState: 'failed'` instead of counted as healthy.
+   * What the widening buys is that a `failed` run is now reported instead of
+   * counted as healthy.
+   *
+   * **A THIRD oracle tells the `failed` rows apart (#15358).** `status ===
+   * 'failed'` over-reports in one specific direction: a cascade-failed run
+   * — an ancestor `failAncestors` failed while it was parked at its `subflow`
+   * node, whose pause `failSuspendedRun` consumed and journalled nothing — has
+   * the same terminal row as the #13909 strand, and `restoreConsumedSuspension`
+   * refuses it. The engine's discriminator (the consumed-suspension snapshot)
+   * is deliberately NOT on the object `getRun` answers, so it is asked through
+   * a dedicated read-only member, `inspectConsumedSuspension`, and only for
+   * `failed` rows: the answer splits `'failed'` into `'repairable'`,
+   * `'snapshot_dropped'` and `'unrepairable'` (see {@link StrandedRunState}).
+   * A surface without that member leaves the row `'failed'` — reported,
+   * undifferentiated — because absence of the discriminator is not evidence
+   * of anything. So does a read that THREW or answered a malformed verdict
+   * (#16709): by the time this oracle is asked the row is already known to be
+   * stranded, so a failure to differentiate it is not a reason to drop it from
+   * a report — it is counted `undetermined` as telemetry AND reported.
    *
    * ⚠️ **What this can and cannot size.** It makes the condition *visible* in a
    * deployment; it is not itself a census, and it says nothing about this
@@ -5407,8 +5575,27 @@ var _ApprovalService = class _ApprovalService {
         });
         continue;
       }
-      const runState = classifyStrandedRunState(terminal);
+      let runState = classifyStrandedRunState(terminal);
       if (!runState) continue;
+      if (runState === "failed" && typeof this.automation.inspectConsumedSuspension === "function") {
+        let refined;
+        let differentiated = true;
+        try {
+          refined = refineFailedRunState(await this.automation.inspectConsumedSuspension(runId));
+        } catch (err) {
+          differentiated = false;
+          undetermined++;
+          this.logger?.warn?.("[approvals] stranded-request scan could not read the consumed-suspension state", {
+            request: raw?.id,
+            run: runId,
+            error: err?.message ?? String(err)
+          });
+        }
+        if (differentiated) {
+          if (!refined) continue;
+          runState = refined;
+        }
+      }
       const config = parseJson(
         raw.node_config_json,
         { approvers: [], behavior: "first_response" }
@@ -5449,11 +5636,389 @@ var _ApprovalService = class _ApprovalService {
         undetermined,
         runMissing: stranded.filter((s) => s.runState === "missing").length,
         runFailed: stranded.filter((s) => s.runState === "failed").length,
+        runRepairable: stranded.filter((s) => s.runState === "repairable").length,
+        runSnapshotDropped: stranded.filter((s) => s.runState === "snapshot_dropped").length,
+        runUnrepairable: stranded.filter((s) => s.runState === "unrepairable").length,
         requests: stranded.map((s) => `${s.requestId}@${s.nodeId ?? "?"} \u2192 run ${s.runId} (${s.runState})`)
       });
     }
     return { scanned: rows.length, stranded, undetermined };
   }
+  /**
+   * Stash the continuation a door just failed to deliver, so it can be issued
+   * again after the pause is re-armed (#15389).
+   *
+   * `AutomationEngine.restoreConsumedSuspension` puts a stranded approval run
+   * back on its pause and tells the operator to *re-issue the continuation* —
+   * but for an `approval` node the only issuers are this service's doors, and
+   * every one of them guards on a `pending` request that the stranding call
+   * itself just made terminal. Re-opening the row is excluded (it would let a
+   * decided request be decided again), so what is kept instead is the SIGNAL:
+   * the exact `branchLabel` + `output` the failed resume carried.
+   *
+   * ⚠️ Best-effort by construction, and it must stay that way: the decision is
+   * already durable and its caller is already owed a `RESUME_FAILED` throw. A
+   * failure to write recovery bookkeeping must not replace that throw with a
+   * storage error — {@link ApprovalService.continueRestoredRun} rebuilds the
+   * signal from the row when the stash is absent, so this failing costs
+   * fidelity on one shape, not the repair path.
+   */
+  async journalStrandedContinuation(requestId, signal) {
+    try {
+      const rows = await this.engine.find("sys_approval_request", {
+        where: { id: requestId },
+        limit: 1,
+        context: SYSTEM_CTX2
+      });
+      const raw = Array.isArray(rows) ? rows[0] : null;
+      if (!raw) return;
+      const config = parseJson(raw.node_config_json, {});
+      await this.engine.update("sys_approval_request", {
+        id: requestId,
+        node_config_json: JSON.stringify({ ...config, [STRANDED_CONTINUATION_KEY]: signal })
+      }, { context: SYSTEM_CTX2 });
+    } catch (err) {
+      this.logger?.warn?.(
+        "[approvals] could not journal the stranded continuation \u2014 the repair path falls back to rebuilding it from the row",
+        { request: requestId, error: err?.message ?? String(err) }
+      );
+    }
+  }
+  /**
+   * The continuation to re-issue for a request whose recorded outcome stranded
+   * its run — the journalled one when there is one, otherwise rebuilt from the
+   * row (#15389).
+   *
+   * ## Why a rebuild path exists at all
+   *
+   * The journal only covers runs stranded by a build that HAS it. The card is
+   * explicitly about *"the runs already in this state"*, and one of those can
+   * still be restored whenever the durable run-history row carried its
+   * suspension snapshot — so a repair verb that only served future strands
+   * would miss the population the card was filed for.
+   *
+   * ## Which statuses it rebuilds, which it discriminates, and which it refuses
+   *
+   * ⛔ A status is NOT the same thing as a continuation. Three of the four
+   * terminal statuses have more than one writer or more than one issuer, so
+   * "one status, one signal" is false and is not what this relies on. Each row
+   * below states its own population and its own discriminator:
+   *
+   * | status | writers / issuers | rebuilt as | how it is decided |
+   * |---|---|---|---|
+   * | `approved` | 1 (`decide`; escalation auto-approve routes through it) | `approve` | unambiguous |
+   * | `rejected` | 2 (`decide`; ADR-0044 revision-limit auto-reject) | `reject`, or REFUSED | a `revise` action row means the auto-reject arm is possible |
+   * | `returned` | 1 writer, 2 issuers (`sendBack` → `revise`; a later `resubmit` → `resubmit`, writing no status) | `resubmit` or `revise` | a `resubmit` action row, whose sole writer is `resubmit` |
+   * | `recalled` | 2 writers, 3 behaviours, 2 issuing NO continuation | REFUSED | nothing on the row distinguishes them |
+   *
+   * ⚠️ **Both refusals are deliberate and neither is best-effort.** The failure
+   * mode of a wrong rebuild is a flow advanced down a branch nobody chose —
+   * strictly worse than the dead end this verb exists to open. Where the signal
+   * cannot be proved, this refuses and names what the operator can do instead;
+   * the journal is what makes both shapes recoverable going forward.
+   *
+   * ⛔ `pending` and `cancelled` are refused outright: neither names a recorded
+   * outcome to replay. A `pending` request's continuation is an ordinary
+   * decision through the front door, which is exactly the guard this verb
+   * exists to avoid weakening.
+   */
+  async resolveRecordedContinuation(raw, requestId) {
+    const config = parseJson(raw.node_config_json, {});
+    const status = String(raw.status ?? "");
+    const stashed = config?.[STRANDED_CONTINUATION_KEY];
+    if (stashed && typeof stashed === "object" && typeof stashed.decision === "string") {
+      const issuable = CONTINUATIONS_A_STATUS_CAN_ISSUE[status];
+      const journalled = String(stashed.decision);
+      if (!issuable?.includes(journalled)) {
+        throw new Error(
+          `INVALID_STATE: request ${requestId} is '${status || "unknown"}' and its journalled continuation is the ${journalled}, which a '${status || "unknown"}' request cannot have issued \u2014 ${issuable ? `a '${status}' row is replayable only for ${issuable.map((d) => `'${d}'`).join(" or ")}` : `no continuation is replayable for '${status || "unknown"}'`}. The journal records what the last FAILED resume was carrying, so a later recall (or any other door that moved this row on) leaves a signal behind that the row's own status no longer stands behind, and replaying it would advance a step nobody is waiting on. Refusing to replay it: cancel the run with the engine's cancelRun('${raw.flow_run_id}') if the newer outcome should stand, or resume it by hand with the signal the flow expects.`
+        );
+      }
+      return { signal: stashed, source: "journal" };
+    }
+    const outputs = { ...config?.__decisionOutputs ?? {} };
+    if (status === "approved" || status === "rejected") {
+      if (status === "rejected") {
+        const priorRevise = await this.engine.find("sys_approval_action", {
+          where: { request_id: requestId, action: "revise" },
+          limit: 1,
+          context: SYSTEM_CTX2
+        });
+        if (Array.isArray(priorRevise) && priorRevise.length) {
+          throw new Error(
+            `INVALID_STATE: request ${requestId} is 'rejected' and also carries a 'revise' action, so this service cannot tell a decided rejection from an ADR-0044 revision-limit auto-rejection \u2014 and the two resume the same edge with different flow output (\`autoRejected\`). Refusing to guess: replay it by hand with the signal the flow expects, or cancel the run.`
+          );
+        }
+      }
+      const decision = status === "approved" ? "approve" : "reject";
+      return {
+        source: "reconstructed",
+        signal: {
+          branchLabel: status === "approved" ? APPROVAL_BRANCH_LABELS.approve : APPROVAL_BRANCH_LABELS.reject,
+          output: { ...outputs, decision, requestId },
+          decision,
+          what: `the ${decision} decision`
+        }
+      };
+    }
+    if (status === "returned") {
+      const resubmitted = await this.engine.find("sys_approval_action", {
+        where: { request_id: requestId, action: "resubmit" },
+        limit: 1,
+        context: SYSTEM_CTX2
+      });
+      if (Array.isArray(resubmitted) && resubmitted.length) {
+        return {
+          source: "reconstructed",
+          signal: {
+            branchLabel: APPROVAL_BRANCH_LABELS.resubmit,
+            output: { resubmitted: true, requestId },
+            decision: "resubmit",
+            what: "the resubmit"
+          }
+        };
+      }
+      return {
+        source: "reconstructed",
+        signal: {
+          branchLabel: APPROVAL_BRANCH_LABELS.revise,
+          output: { decision: "revise", requestId },
+          decision: "revise",
+          what: "the send-back"
+        }
+      };
+    }
+    if (status === "recalled") {
+      throw new Error(
+        `INVALID_STATE: request ${requestId} is 'recalled' and carries no journalled continuation, so the signal cannot be rebuilt: a recall reaches this state three ways (resumed down 'reject', terminally cancelled inside a revision window, or swept as a dead run) and two of them issue no continuation at all \u2014 replaying the wrong one would re-open a request that was deliberately withdrawn. Refusing to guess: cancel the run with the engine's cancelRun('${raw.flow_run_id}') if the withdrawal should stand, or resume it by hand with the signal the flow expects.`
+      );
+    }
+    throw new Error(
+      `INVALID_STATE: request is ${status || "unknown"} \u2014 only a request whose recorded outcome already resumed its run can have that continuation re-issued (approved, rejected, returned, recalled)`
+    );
+  }
+  /**
+   * WHERE the pause a recorded continuation was refused on actually sits
+   * (#15389) — the expected node guard 3 compares the run's parked node against.
+   *
+   * ⚠️ This is signal-aware, and that is the whole point of it. "This request's
+   * own node" is the right answer for three of the four signals and the WRONG
+   * answer for the fourth:
+   *
+   * | signal | issued from | why |
+   * |---|---|---|
+   * | `approve` / `reject` | the request's own approval node | the decision is taken at the pause it gates |
+   * | `revise` (send-back) | the request's own approval node | send-back resumes that same pause down the `revise` edge |
+   * | `recall` | the request's own approval node | recall-on-pending resumes that same pause down `reject` |
+   * | `resubmit` | the **revise window** the request's `revise` edge leads to | by construction: a resubmit is only reachable AFTER a send-back moved the run there, and it resumes THAT pause down the `resubmit` back-edge |
+   *
+   * Measured before this existed: a `returned` row whose resubmit stranded was
+   * refused by guard 3 on both the journal and the rebuild paths — the pause
+   * re-armed at the revise window while the row's `flow_node_id` still read the
+   * approval node — and the refusal told the operator the pause was not this
+   * request's when it was exactly this request's. A refusal may ship; a refusal
+   * that names a cause the code did not take may not.
+   *
+   * ⛔ It stays FAIL-CLOSED: the revise window is derived from the flow
+   * definition the same way {@link ApprovalService.assertReviseEdge} derives it
+   * — a `revise` out-edge of this request's node into a node the flow declares
+   * as `{@link APPROVAL_REVISE_NODE_TYPE}`, which is the pause only this service
+   * can continue. No engine, no flow, no such edge, or more than one candidate
+   * ⇒ refuse. It needs no automation surface `assertReviseEdge` did not already
+   * use (`getFlow`), and no engine change.
+   *
+   * ⚠️ It does not widen what guard 3 admits beyond that one signal: for every
+   * other decision the answer is byte-identical to the row's own node.
+   *
+   * ⛔ It is NOT what keeps the recall-in-revise-window shape (row `recalled`,
+   * run at the revise window) refused, and an earlier revision of this comment
+   * claimed it was — on the reasoning that such a row's journalled signal is
+   * `recall` rather than `resubmit`. That is false: a recall taken inside the
+   * revise window calls `cancelRun` and journals NOTHING, so the journal on
+   * such a row is whatever an EARLIER strand left there — a `resubmit`, most
+   * often, since the resubmit is what the window exists to receive. Measured:
+   * with the journal returned before the row's status was looked at, that
+   * stale `resubmit` reached this method, was answered with the revise window,
+   * matched the parked node, and opened a fresh `pending` round on a withdrawn
+   * request. What refuses it is the journal/status compatibility check in
+   * {@link ApprovalService.resolveRecordedContinuation} — see
+   * {@link CONTINUATIONS_A_STATUS_CAN_ISSUE} — which runs BEFORE this method
+   * and never hands it a signal the row's status cannot have issued.
+   */
+  async expectedPauseNode(raw, signal, requestId, runId) {
+    const ownNode = raw.flow_node_id ?? raw.current_step ?? null;
+    if (!ownNode) {
+      throw new Error(
+        `INVALID_STATE: request ${requestId} records no approval node, so the pause on run '${runId}' cannot be proved to be the one ${signal.what} was refused on \u2014 refusing rather than resuming a pause that may belong to another node`
+      );
+    }
+    if (signal.decision !== "resubmit") {
+      return { nodeId: ownNode, describe: `its own approval node '${ownNode}'` };
+    }
+    const processName = String(raw.process_name ?? "");
+    const flowName = processName.startsWith("flow:") ? processName.slice("flow:".length) : "";
+    if (!flowName || typeof this.automation?.getFlow !== "function") {
+      throw new Error(
+        `INVALID_STATE: ${signal.what} on request ${requestId} was issued from the revise window that approval node '${ownNode}' sends back to, and this service cannot read the owning flow definition to say which node that is \u2014 refusing, because continuing a pause it cannot identify advances a step nobody decided`
+      );
+    }
+    const flow = await this.automation.getFlow(flowName);
+    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 : ""])
+    );
+    const windows = Array.from(new Set(
+      (Array.isArray(flow?.edges) ? flow.edges : []).filter((e) => e?.source === ownNode && e?.label === APPROVAL_BRANCH_LABELS.revise).map((e) => typeof e?.target === "string" ? e.target : "").filter((t) => t && nodeTypeById.get(t) === APPROVAL_REVISE_NODE_TYPE)
+    ));
+    if (windows.length !== 1) {
+      throw new Error(
+        `INVALID_STATE: ${signal.what} on request ${requestId} was issued from the revise window that approval node '${ownNode}' sends back to, and flow '${flowName}' declares ${windows.length === 0 ? "no such window" : `${windows.length} of them (${windows.join(", ")})`} \u2014 refusing, because a pause this service cannot identify must not be continued`
+      );
+    }
+    return {
+      nodeId: windows[0],
+      describe: `the revise window '${windows[0]}' that its approval node '${ownNode}' sends back to`
+    };
+  }
+  /**
+   * Re-issue the continuation for a run an operator has re-armed with
+   * `AutomationEngine.restoreConsumedSuspension` — the missing half of that
+   * repair verb, for approvals (#15389).
+   *
+   * ## The dead end this exits
+   *
+   * A decision whose downstream node throws strands the run: the suspension is
+   * consumed, the decision is durable, and the caller gets `RESUME_FAILED`
+   * carrying `repairable: true`. `restoreConsumedSuspension` then genuinely
+   * re-arms the pause — measured `restored: true`, `hasSuspendedRun` back to
+   * `true` — and its own reason string tells the operator to *re-issue the
+   * continuation*. For an `approval` node there was then nobody who could:
+   *
+   *  - `decide` / `recall` / `sendBack` / `resubmit` all guard on a `pending`
+   *    request, and the row is terminal — written by the very call that
+   *    stranded the run;
+   *  - the generic `engine.resume` refuses, because the `approval` node
+   *    declares `resumeAuthority: 'service'` and the #3801 gate turns away any
+   *    resume that is not the tail of a decision this service authorized.
+   *
+   * So the only verb left was `cancelRun`, which discards the branch's
+   * downstream work. Measured on the real engine and the real door: the
+   * restored pause IS resumable, and a `resumeAuthority`-marked resume walks
+   * the reject branch to completion. Nothing was missing in the engine — what
+   * was missing was an ISSUER on this side. This is that issuer.
+   *
+   * ## What it deliberately does NOT do
+   *
+   * ⛔ It does not re-open, re-decide, or rewrite the request row: all four
+   * `pending` guards stay exactly as they are, and no status, mirror field or
+   * audit row is written. A person decided this once; this replays what they
+   * decided onto the pause that was put back, and replays nothing else.
+   * ⛔ It does not relax `resumeAuthority: 'service'` — the resume goes through
+   * {@link ApprovalService.serviceResume} like every other, so the marker is
+   * still stamped in exactly one place.
+   * ⛔ It grants no capability that in-process code did not already have:
+   * `RESUME_AUTHORITY_SERVICE` is importable by anything in the host, so the
+   * raw form of this call was always available. What this adds is the GUARDED
+   * form, and the guards are the substance of it — three, each with its own
+   * reverse-control pin, because the raw marker is not a guard and an
+   * unguarded repair verb advances flows nobody decided:
+   *
+   *  1. {@link assertLatestForRun} — this request is still the newest on its
+   *     run, so a superseded row cannot drive a later round or a later node;
+   *  2. `hasSuspendedRun` — a pause exists at all (strict: an unreadable store
+   *     throws rather than reading as "not suspended");
+   *  3. node identity — that pause is parked where THIS request's recorded
+   *     outcome was issued from: its own approval node for `approve`,
+   *     `reject`, `revise` and `recall`, and — for a `resubmit`, which is only
+   *     reachable from a revise window — the `approval_revise` node its own
+   *     `revise` edge leads to. {@link ApprovalService.expectedPauseNode}
+   *     derives it, fail-closed.
+   *
+   * Guard 3 is not redundant with guard 2: existence is not identity, and a
+   * boolean cannot tell this request's re-armed pause from any other live
+   * pause on the same run.
+   *
+   * ## Posture, and why it takes no `ExecutionContext`
+   *
+   * Deliberately shaped like the engine verb it completes: an in-process
+   * operator repair, reachable from a host or a console script, with no REST
+   * route and no entry in the spec `ApprovalService` contract — exactly as
+   * `restoreConsumedSuspension` is a class method on `AutomationEngine` and
+   * appears in no contract. It authorizes nothing new: the decision it replays
+   * was authorized and recorded when it was made, and re-authorizing it here
+   * against a present-day actor would be a different and wrong question (the
+   * original approver may be long gone). `requestedBy` / `reason` ride the log
+   * for the same reason they do on the restore.
+   *
+   * @returns what was replayed and whether the run moved — never a silent
+   *   `false`. A resume that fails again throws the same `RESUME_FAILED`
+   *   envelope the original decision did, `repairable` and all, so a second
+   *   restore-and-continue is possible.
+   */
+  async continueRestoredRun(requestId, options) {
+    if (!requestId) throw new Error("VALIDATION_FAILED: requestId is required");
+    const rows = await this.engine.find("sys_approval_request", {
+      where: { id: requestId },
+      limit: 1,
+      context: SYSTEM_CTX2
+    });
+    const raw = Array.isArray(rows) ? rows[0] : null;
+    if (!raw) throw new Error(`REQUEST_NOT_FOUND: ${requestId}`);
+    const runId = raw.flow_run_id ?? null;
+    if (!runId) {
+      throw new Error(
+        `INVALID_STATE: request ${requestId} names no flow run \u2014 there is no continuation to re-issue`
+      );
+    }
+    await this.assertLatestForRun(raw);
+    const { signal, source } = await this.resolveRecordedContinuation(raw, requestId);
+    if (typeof this.automation?.hasSuspendedRun === "function") {
+      const parked = await this.automation.hasSuspendedRun(runId);
+      if (!parked) {
+        throw new Error(
+          `INVALID_STATE: run '${runId}' behind request ${requestId} is not suspended, so there is no re-armed pause to continue \u2014 restore it first with the automation engine's restoreConsumedSuspension('${runId}'), which is what re-arms a consumed approval suspension`
+        );
+      }
+    }
+    const expected = await this.expectedPauseNode(raw, signal, requestId, runId);
+    if (typeof this.automation?.listSuspendedRunsDurable !== "function") {
+      throw new Error(
+        `INVALID_STATE: this automation engine cannot report WHERE run '${runId}' is parked (no listSuspendedRunsDurable), so the pause cannot be proved to be the one ${signal.what} on request ${requestId} was refused on \u2014 refusing, because continuing the wrong pause advances a flow with no decision behind it`
+      );
+    }
+    const parkedAt = (await this.automation.listSuspendedRunsDurable()).find((r) => String(r.runId) === String(runId))?.nodeId;
+    if (parkedAt !== expected.nodeId) {
+      throw new Error(
+        `INVALID_STATE: run '${runId}' is parked at ${parkedAt ? `node '${parkedAt}'` : "no node this engine can see"}, but ${signal.what} on request ${requestId} was issued from ${expected.describe} \u2014 so the pause this verb was asked to continue is not the one that outcome was issued at, and continuing it would advance a step nobody decided`
+      );
+    }
+    this.logger?.warn?.(
+      "[approvals] re-issuing the continuation for a restored approval suspension",
+      {
+        request: requestId,
+        run: runId,
+        decision: signal.decision,
+        branchLabel: signal.branchLabel,
+        source,
+        requestedBy: options?.requestedBy ?? "not recorded",
+        reason: options?.reason ?? "not recorded"
+      }
+    );
+    const outcome = await this.resumeRecordedOutcome(
+      runId,
+      requestId,
+      signal.what,
+      { branchLabel: signal.branchLabel, output: signal.output },
+      signal.decision
+    );
+    return {
+      resumed: outcome.resumed,
+      runId,
+      decision: signal.decision,
+      branchLabel: signal.branchLabel,
+      source,
+      ...outcome.resumeError ? { resumeError: outcome.resumeError } : {}
+    };
+  }
   async releaseDeadRunRequests() {
     if (typeof this.automation?.getRun !== "function") return { scanned: 0, released: 0 };
     let rows = [];