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

package/dist/index.mjs

@@ -245,6 +245,10 @@ var init_en_objects_generated = __esm({
           comment: {
             label: "Comment"
           },
+          via_override: {
+            label: "Via Admin Override",
+            help: "True when the actor was admitted to this action only by the privileged-override path (#3424) \u2014 they held no slot in the request\u2019s pending-approver slate."
+          },
           reassign_from: {
             label: "Reassigned From",
             help: "User whose pending-approver slot was handed over (reassign actions only)"
@@ -562,6 +566,10 @@ var init_zh_CN_objects_generated = __esm({
           comment: {
             label: "\u8BC4\u8BBA"
           },
+          via_override: {
+            label: "\u7BA1\u7406\u5458\u8D8A\u6743\u64CD\u4F5C",
+            help: "\u4E3A\u771F\u8868\u793A\u8BE5\u64CD\u4F5C\u8005\u53EA\u662F\u51ED\u7279\u6743\u8D8A\u6743\u8DEF\u5F84\uFF08#3424\uFF09\u88AB\u653E\u884C\u2014\u2014\u4ED6\u4EEC\u5E76\u4E0D\u5728\u8BE5\u8BF7\u6C42\u7684\u5F85\u5BA1\u6279\u4EBA\u540D\u5355\u4E2D\u3002"
+          },
           reassign_from: {
             label: "\u8F6C\u51FA\u4EBA",
             help: "\u88AB\u79FB\u4EA4\u5F85\u5BA1\u6279\u69FD\u4F4D\u7684\u7528\u6237\uFF08\u4EC5\u8F6C\u7B7E\u64CD\u4F5C\uFF09"
@@ -879,6 +887,10 @@ var init_ja_JP_objects_generated = __esm({
           comment: {
             label: "\u30B3\u30E1\u30F3\u30C8"
           },
+          via_override: {
+            label: "\u7BA1\u7406\u8005\u30AA\u30FC\u30D0\u30FC\u30E9\u30A4\u30C9\u7D4C\u7531",
+            help: "true \u306E\u5834\u5408\u3001\u5B9F\u884C\u8005\u306F\u7279\u6A29\u30AA\u30FC\u30D0\u30FC\u30E9\u30A4\u30C9\u7D4C\u8DEF\uFF08#3424\uFF09\u306B\u3088\u3063\u3066\u306E\u307F\u8A31\u53EF\u3055\u308C\u305F\u3053\u3068\u3092\u793A\u3057\u307E\u3059 \u2014 \u5F53\u8A72\u30EA\u30AF\u30A8\u30B9\u30C8\u306E\u627F\u8A8D\u5F85\u3061\u30EA\u30B9\u30C8\u306B\u306F\u542B\u307E\u308C\u3066\u3044\u307E\u305B\u3093\u3002"
+          },
           reassign_from: {
             label: "\u5F15\u304D\u7D99\u304E\u5143",
             help: "\u627F\u8A8D\u5F85\u3061\u30B9\u30ED\u30C3\u30C8\u3092\u5F15\u304D\u6E21\u3057\u305F\u30E6\u30FC\u30B6\u30FC\uFF08\u5F15\u304D\u7D99\u304E\u64CD\u4F5C\u306E\u307F\uFF09"
@@ -1196,6 +1208,10 @@ var init_es_ES_objects_generated = __esm({
           comment: {
             label: "Comentario"
           },
+          via_override: {
+            label: "Mediante anulaci\xF3n de administrador",
+            help: "Verdadero cuando el actor fue admitido en esta acci\xF3n \xFAnicamente por la v\xEDa de anulaci\xF3n privilegiada (#3424): no ocupaba ning\xFAn puesto en la lista de aprobadores pendientes de la solicitud."
+          },
           reassign_from: {
             label: "Reasignado de",
             help: "Usuario cuyo turno de aprobaci\xF3n pendiente fue traspasado (solo acciones de reasignaci\xF3n)"
@@ -1689,7 +1705,7 @@ var SysApprovalAction = ObjectSchema2.create({
   nameField: "id",
   // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: "{action} \xB7 {step_name}",
-  highlightFields: ["request_id", "step_name", "action", "actor_id", "created_at"],
+  highlightFields: ["request_id", "step_name", "action", "actor_id", "via_override", "created_at"],
   // ADR-0104 D3 wave 2. `attachments` is a media field, so the files it holds
   // are OWNED by this row — and the storage service would otherwise authorize
   // their download by testing whether the caller can READ this row. It cannot:
@@ -1704,7 +1720,7 @@ var SysApprovalAction = ObjectSchema2.create({
       name: "recent",
       label: "Recent",
       data: { provider: "object", object: "sys_approval_action" },
-      columns: ["created_at", "request_id", "step_name", "action", "actor_id", "comment"],
+      columns: ["created_at", "request_id", "step_name", "action", "actor_id", "via_override", "comment"],
       sort: [{ field: "created_at", order: "desc" }],
       pagination: { pageSize: 50 },
       emptyState: { title: "No approval actions yet", message: "Actions are logged automatically when approvals progress." }
@@ -1724,7 +1740,7 @@ var SysApprovalAction = ObjectSchema2.create({
       name: "all_actions",
       label: "All",
       data: { provider: "object", object: "sys_approval_action" },
-      columns: ["created_at", "request_id", "step_name", "action", "actor_id", "comment"],
+      columns: ["created_at", "request_id", "step_name", "action", "actor_id", "via_override", "comment"],
       sort: [{ field: "created_at", order: "desc" }],
       pagination: { pageSize: 100 }
     }
@@ -1772,6 +1788,29 @@ var SysApprovalAction = ObjectSchema2.create({
       group: "Action"
     }),
     comment: Field2.textarea({ label: "Comment", required: false, group: "Action" }),
+    // #4466 — the one bit of "who really decided this" that was still dropped.
+    // A privileged admin may act on a request whose staffed approver slate they
+    // hold no slot in (the #3424 override path); before this column, that
+    // decision was byte-for-byte identical to the designated approver's own
+    // approval. A reader of the timeline saw `approve` by the admin and could
+    // not tell whether the admin WAS an approver or OVERRODE the ones who were,
+    // and the bypassed approver's later `409 INVALID_STATE` was the only trace
+    // — existing only if they happened to try.
+    //
+    // The platform KNOWS at decision time: it took the `isOverrideActor` branch
+    // to admit the call at all. This is dropped information, not unavailable
+    // information.
+    //
+    // Set on exactly the decisions that were admitted BY that branch — an admin
+    // who is also a genuine slot holder is approving normally and is recorded
+    // as such. Nullable and additive: rows written before this column exists
+    // carry `null`, which reads as "not recorded", never as "not an override".
+    via_override: Field2.boolean({
+      label: "Via Admin Override",
+      required: false,
+      group: "Action",
+      description: "True when the actor was admitted to this action only by the privileged-override path (#3424) \u2014 they held no slot in the request\u2019s pending-approver slate."
+    }),
     // Structured hand-off parties for `action: 'reassign'` (#4365). Before
     // these existed the pair lived only inside a default free-text comment
     // ("<from_id> → <to_id>"), which no client could parse or render readably.
@@ -1879,12 +1918,11 @@ var SysApprovalDelegation = ObjectSchema4.create({
   pluralLabel: "Approval Delegations",
   icon: "user-clock",
   isSystem: true,
-  managedBy: "system",
-  // [ADR-0103] Admin/user-writable DATA on a platform-defined schema: a user
-  // authors their own out-of-office delegation. Affordance only (matches the
-  // full-CRUD apiMethods below) — RLS/permission sets are the authz; opening it
-  // keeps the system write guard from rejecting the self-service write.
-  userActions: { create: true, edit: true, delete: true },
+  // [ADR-0103, #3355] Admin/user-writable DATA on a platform-defined schema: a
+  // user authors their own out-of-office delegation. The bucket default is full
+  // CRUD (matching the full-CRUD apiMethods below), so no `userActions` block is
+  // needed — RLS/permission sets are the authz.
+  managedBy: "system-data",
   description: "Self-service out-of-office rule: route this user's approver slots to a delegate within a time window (#1322 M1).",
   titleFormat: "{delegator_id} \u2192 {delegate_id}",
   highlightFields: ["delegator_id", "delegate_id", "valid_from", "valid_until"],
@@ -2120,6 +2158,7 @@ var TERMINAL_RUN_STATUSES = /* @__PURE__ */ new Set([
   "cancelled",
   "timed_out"
 ]);
+var STRANDABLE_REQUEST_STATUSES = ["approved", "rejected", "returned"];
 var ACTION_TOKEN_TTL_MS = 72 * 60 * 60 * 1e3;
 var SYSTEM_CTX2 = { isSystem: true, positions: [], permissions: [] };
 function actingUserId(context) {
@@ -2259,6 +2298,11 @@ function rowFromAction(row) {
     // Structured reassign hand-off parties (#4365).
     reassign_from: row.reassign_from ?? void 0,
     reassign_to: row.reassign_to ?? void 0,
+    // #4466 — surfaced so a timeline can SAY "overridden the approver slate"
+    // rather than render an override identically to an ordinary approval.
+    // `null` (a row written before the column existed) stays `undefined`:
+    // "not recorded" is not the same claim as "not an override".
+    via_override: row.via_override == null ? void 0 : row.via_override === true,
     // Decision attachments (#3266): rich descriptors carrying the display name +
     // download URL, so consumers label/open them without reading `sys_file`.
     attachments: attachments.length ? attachments : void 0,
@@ -3190,6 +3234,7 @@ var _ApprovalService = class _ApprovalService {
     if (!isSlotHolder && !isOverride) {
       throw new Error(`FORBIDDEN: actor '${actorId}' is not a pending approver`);
     }
+    const viaOverride = isOverride && !isSlotHolder;
     const config = parseJson(raw.node_config_json, { approvers: [], behavior: "first_response" });
     const org = raw.organization_id ?? null;
     const nodeId = raw.flow_node_id ?? raw.current_step ?? null;
@@ -3227,6 +3272,7 @@ var _ApprovalService = class _ApprovalService {
         );
       }
     }
+    await this.assertRunResumable(runId, requestId);
     await this.engine.insert("sys_approval_action", {
       id: uid("aact"),
       request_id: requestId,
@@ -3236,6 +3282,10 @@ var _ApprovalService = class _ApprovalService {
       action: input.decision,
       actor_id: actorId,
       comment: input.comment ?? null,
+      // #4466: the override is recorded on the DECISION, not inferred later.
+      // Written as an explicit `false` for an ordinary decision so a reader can
+      // tell "checked, and it was not an override" from a legacy row's `null`.
+      via_override: viaOverride,
       attachments: input.attachments?.length ? input.attachments : null,
       created_at: now
     }, { context: SYSTEM_CTX2 });
@@ -3322,22 +3372,131 @@ var _ApprovalService = class _ApprovalService {
    * Callers still guard on `typeof this.automation?.resume === 'function'`
    * (approvals runs fine with no automation attached) and keep their own
    * try/catch, because what a failed resume means differs per path.
+   *
+   * Throws when the engine REPORTS failure, not only when it throws one. The
+   * engine answers a lost run with `{ success: false, code: 'RUN_NOT_FOUND' }`
+   * — a plain return value that every caller here used to discard, which is
+   * how an approval could be recorded, reported as resumed, and leave its flow
+   * stranded forever (#4420). The thrown error carries {@link resumeCodeOf}'s
+   * `resumeCode` so callers can tell a benign duplicate from a dead run.
    */
   async serviceResume(runId, signal) {
-    await this.automation.resume(runId, { ...signal, [RESUME_AUTHORITY_SERVICE]: true });
+    const result = await this.automation.resume(runId, { ...signal, [RESUME_AUTHORITY_SERVICE]: true });
+    const reported = result;
+    if (reported && typeof reported === "object" && reported.success === false) {
+      const err = new Error(
+        `resume of run '${runId}' failed${reported.code ? ` [${reported.code}]` : ""}: ${reported.error ?? "unknown error"}`
+      );
+      err.resumeCode = reported.code;
+      throw err;
+    }
+  }
+  /** The engine failure code behind a {@link serviceResume} rejection, if any. */
+  static resumeCodeOf(err) {
+    return err?.resumeCode;
+  }
+  /**
+   * Refuse an operation whose whole point is to advance a flow run when that
+   * run no longer exists — BEFORE anything is written down (#4420).
+   *
+   * The half-state this prevents is the one the issue reported: a request
+   * flipped to `approved`, a success toast, and a flow that never moves. Once
+   * the decision row is written there is nothing left to fail cleanly.
+   *
+   * Deliberately permissive at the edges:
+   *  - no automation attached, or an engine without `hasSuspendedRun` → no
+   *    pre-flight at all (standalone approvals compositions are unaffected);
+   *  - the store cannot be READ → fail OPEN. A transient outage must not block
+   *    every decision in the tenant; the post-resume check still catches a real
+   *    failure and reports it loudly.
+   */
+  async assertRunResumable(runId, requestId) {
+    if (!runId) return;
+    if (typeof this.automation?.resume !== "function") return;
+    if (typeof this.automation?.hasSuspendedRun !== "function") return;
+    let alive;
+    try {
+      alive = await this.automation.hasSuspendedRun(runId);
+    } catch (err) {
+      this.logger?.warn?.("[approvals] could not verify the flow run is resumable \u2014 proceeding", {
+        request: requestId,
+        run: runId,
+        error: err?.message ?? String(err)
+      });
+      return;
+    }
+    if (!alive) {
+      throw new Error(
+        `RESUME_TARGET_LOST: the flow run '${runId}' behind request ${requestId} no longer exists (it was cancelled, or it paused in a process that did not persist suspended runs). Nothing was recorded. An administrator can 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).
+   *
+   * For the operations whose product is the resume — a finalised decision, a
+   * send-back, a resubmit. Their rows are durable by the time this runs, so a
+   * failure here cannot be undone; the one thing left worth doing is refusing
+   * to call it success. {@link assertRunResumable} is what keeps this rare:
+   * 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.
+   *
+   * @param what - how the recorded outcome reads in the error, e.g.
+   *   `"the approve decision"`.
+   */
+  async resumeRecordedOutcome(runId, requestId, what, signal) {
+    try {
+      await this.serviceResume(runId, signal);
+      return { resumed: true };
+    } catch (err) {
+      const reason = err?.message ?? String(err);
+      if (_ApprovalService.resumeCodeOf(err) === "RESUME_IN_PROGRESS") {
+        this.logger?.warn?.("[approvals] resume skipped \u2014 already in progress", {
+          request: requestId,
+          run: runId,
+          outcome: what
+        });
+        return { resumed: false, resumeError: reason };
+      }
+      this.logger?.error?.("[approvals] resume failed \u2014 the run is stranded", {
+        request: requestId,
+        run: runId,
+        outcome: what,
+        error: reason
+      });
+      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}`
+      );
+    }
   }
   /**
    * Public contract entrypoint (ADR-0019). Records a decision on a node-driven
    * request via {@link ApprovalService.decideNode} and, when it finalizes,
    * resumes the owning flow run down the matching `approve` / `reject` edge.
+   *
+   * A finalising decision whose run cannot be resumed FAILS (#4420). The
+   * decision is already durable by then, so the failure cannot be rolled back
+   * — but it must not be reported as success either: this used to answer HTTP
+   * 200 with `resumed: true` while the flow stayed parked forever, which left
+   * the approver with no signal and the record mirroring a stage it never
+   * reached. `decideNode`'s pre-flight means the common case (the run died
+   * before the decision) never gets this far; what survives here is a genuine
+   * race, and it names the stranded run.
    */
   async decide(requestId, input, context) {
     const result = await this.decideNode(requestId, input, context);
     let resumed = false;
+    let resumeError;
     if (result.finalized && result.runId && typeof this.automation?.resume === "function") {
       const branchLabel = result.decision === "approve" ? APPROVAL_BRANCH_LABELS.approve : APPROVAL_BRANCH_LABELS.reject;
-      try {
-        await this.serviceResume(result.runId, {
+      const outcome = await this.resumeRecordedOutcome(
+        result.runId,
+        requestId,
+        `the ${result.decision} decision`,
+        {
           branchLabel,
           // #3447 P2: accepted decision outputs ride the resume envelope and
           // land as `<nodeId>.<key>` flow variables — a later approval node's
@@ -3345,22 +3504,18 @@ 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 }
-        });
-        resumed = true;
-      } catch (err) {
-        this.logger?.warn?.("[approvals] resume after decision failed", {
-          request: requestId,
-          run: result.runId,
-          error: err?.message ?? String(err)
-        });
-      }
+        }
+      );
+      resumed = outcome.resumed;
+      resumeError = outcome.resumeError;
     }
     return {
       request: result.request,
       finalized: result.finalized,
       decision: result.decision,
       runId: result.runId,
-      resumed
+      resumed,
+      ...resumeError ? { resumeError } : {}
     };
   }
   /**
@@ -3428,15 +3583,17 @@ var _ApprovalService = class _ApprovalService {
       );
     }
     let resumed = false;
+    let resumeError;
     if (inReviseWindow) {
       if (runId && typeof this.automation?.cancelRun === "function") {
         try {
           await this.automation.cancelRun(runId, `approval request ${requestId} recalled during revision`);
         } catch (err) {
-          this.logger?.warn?.("[approvals] cancelRun after revise-window recall failed", {
+          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: err?.message ?? String(err)
+            error: resumeError
           });
         }
       }
@@ -3448,15 +3605,16 @@ var _ApprovalService = class _ApprovalService {
         });
         resumed = true;
       } catch (err) {
-        this.logger?.warn?.("[approvals] resume after recall failed", {
+        resumeError = err?.message ?? String(err);
+        this.logger?.error?.("[approvals] resume after recall failed \u2014 the run may be stranded", {
           request: requestId,
           run: runId,
-          error: err?.message ?? String(err)
+          error: resumeError
         });
       }
     }
     const fresh = await this.readBackRequest(requestId, context);
-    return { request: fresh, runId, resumed };
+    return { request: fresh, runId, resumed, ...resumeError ? { resumeError } : {} };
   }
   // ── Send back for revision / resubmit (ADR-0044) ─────────────
   /**
@@ -3484,6 +3642,7 @@ var _ApprovalService = class _ApprovalService {
     const nodeId = raw.flow_node_id ?? raw.current_step ?? null;
     const runId = raw.flow_run_id ?? null;
     await this.assertReviseEdge(raw, nodeId);
+    await this.assertRunResumable(runId, requestId);
     const now = this.clock.now().toISOString();
     const maxRevisions = typeof config.maxRevisions === "number" ? config.maxRevisions : 3;
     let priorSendBacks = 0;
@@ -3536,20 +3695,19 @@ var _ApprovalService = class _ApprovalService {
         );
       }
       let resumed2 = false;
+      let resumeError2;
       if (runId && typeof this.automation?.resume === "function") {
-        try {
-          await this.serviceResume(runId, {
+        const outcome = await this.resumeRecordedOutcome(
+          runId,
+          requestId,
+          "the auto-rejection",
+          {
             branchLabel: APPROVAL_BRANCH_LABELS.reject,
             output: { decision: "reject", autoRejected: true, requestId }
-          });
-          resumed2 = true;
-        } catch (err) {
-          this.logger?.warn?.("[approvals] resume after auto-reject failed", {
-            request: requestId,
-            run: runId,
-            error: err?.message ?? String(err)
-          });
-        }
+          }
+        );
+        resumed2 = outcome.resumed;
+        resumeError2 = outcome.resumeError;
       }
       if (raw.submitter_id) {
         await this.notify({
@@ -3565,7 +3723,7 @@ var _ApprovalService = class _ApprovalService {
         });
       }
       const fresh2 = await this.readBackRequest(requestId, context);
-      return { request: fresh2, runId, resumed: resumed2, autoRejected: true };
+      return { request: fresh2, runId, resumed: resumed2, autoRejected: true, ...resumeError2 ? { resumeError: resumeError2 } : {} };
     }
     await this.engine.update("sys_approval_request", {
       id: requestId,
@@ -3585,20 +3743,19 @@ var _ApprovalService = class _ApprovalService {
       );
     }
     let resumed = false;
+    let resumeError;
     if (runId && typeof this.automation?.resume === "function") {
-      try {
-        await this.serviceResume(runId, {
+      const outcome = await this.resumeRecordedOutcome(
+        runId,
+        requestId,
+        "the send-back",
+        {
           branchLabel: APPROVAL_BRANCH_LABELS.revise,
           output: { decision: "revise", requestId }
-        });
-        resumed = true;
-      } catch (err) {
-        this.logger?.warn?.("[approvals] resume after send-back failed", {
-          request: requestId,
-          run: runId,
-          error: err?.message ?? String(err)
-        });
-      }
+        }
+      );
+      resumed = outcome.resumed;
+      resumeError = outcome.resumeError;
     }
     if (raw.submitter_id) {
       await this.notify({
@@ -3614,7 +3771,7 @@ var _ApprovalService = class _ApprovalService {
       });
     }
     const fresh = await this.readBackRequest(requestId, context);
-    return { request: fresh, runId, resumed };
+    return { request: fresh, runId, resumed, ...resumeError ? { resumeError } : {} };
   }
   /**
    * ADR-0044 resubmit after rework. Valid on the LATEST `returned` request of
@@ -3653,6 +3810,7 @@ var _ApprovalService = class _ApprovalService {
     const nodeId = raw.flow_node_id ?? raw.current_step ?? null;
     const runId = raw.flow_run_id ?? null;
     const now = this.clock.now().toISOString();
+    await this.assertRunResumable(runId, requestId);
     await this.engine.insert("sys_approval_action", {
       id: uid("aact"),
       request_id: requestId,
@@ -3665,23 +3823,22 @@ var _ApprovalService = class _ApprovalService {
       created_at: now
     }, { context: SYSTEM_CTX2 });
     let resumed = false;
+    let resumeError;
     if (runId && typeof this.automation?.resume === "function") {
-      try {
-        await this.serviceResume(runId, {
+      const outcome = await this.resumeRecordedOutcome(
+        runId,
+        requestId,
+        "the resubmit",
+        {
           branchLabel: APPROVAL_BRANCH_LABELS.resubmit,
           output: { resubmitted: true, requestId }
-        });
-        resumed = true;
-      } catch (err) {
-        this.logger?.warn?.("[approvals] resume after resubmit failed", {
-          request: requestId,
-          run: runId,
-          error: err?.message ?? String(err)
-        });
-      }
+        }
+      );
+      resumed = outcome.resumed;
+      resumeError = outcome.resumeError;
     }
     const fresh = await this.readBackRequest(requestId, context);
-    return { request: fresh, runId, resumed };
+    return { request: fresh, runId, resumed, ...resumeError ? { resumeError } : {} };
   }
   /**
    * ADR-0044 guard: the flow's approval node must declare a `revise`
@@ -3742,6 +3899,7 @@ var _ApprovalService = class _ApprovalService {
     }
     const isOverride = this.isOverrideActor(context, raw.organization_id ?? null);
     const from = String(input.from ?? actorId).trim();
+    const viaOverride = isOverride && !pending.includes(actorId);
     let next;
     if (pending.includes(from)) {
       if (!context.isSystem && !isOverride && actorId !== from && !pending.includes(actorId)) {
@@ -3767,6 +3925,7 @@ var _ApprovalService = class _ApprovalService {
       actor_id: actorId,
       reassign_from: from,
       reassign_to: to,
+      via_override: viaOverride,
       comment: input.comment ?? null,
       created_at: now
     }, { context: SYSTEM_CTX2 });
@@ -4131,6 +4290,137 @@ var _ApprovalService = class _ApprovalService {
    * the real cause and {@link DEAD_RUN_ACTOR_ID} the real actor, so a dead-run
    * release is never mistaken for a submitter's withdrawal.
    */
+  /**
+   * Read-only inspection for the OTHER dead-run shape: a request that is
+   * already TERMINAL while its `flow_run_id` points at nothing (#4469).
+   *
+   * #4460 stopped new ones being produced; nothing found the ones already
+   * stuck. The failure mode (#4420) is a request row flipped to `approved` /
+   * `rejected` / `returned` whose owning run no longer exists — the decision
+   * landed, the flow never moved. Any deployment on 17.0.0-rc.1 that hit the
+   * wiring hole and crossed a restart mid-approval can be carrying these rows.
+   *
+   * {@link releaseDeadRunRequests} cannot see them, for a reason worth naming:
+   * it scans `status: 'pending'`, and the very step that zombified the request
+   * is the one that took it OUT of `pending`. The act of breaking it removed it
+   * from the only sweeper's field of view — which is a large part of why this
+   * class of failure stayed silent.
+   *
+   * It also could not have answered the question even if it looked: its
+   * liveness oracle is `getRun`, which reads the execution LOG, and after a
+   * restart that returns `null` for a perfectly ALIVE suspended run. It treats
+   * `null` as alive (conservative, correct) — but that means it has no way to
+   * say "this run is really gone".
+   *
+   * So this uses BOTH oracles, and a row must fail both to be reported:
+   *
+   *  - `hasSuspendedRun(runId) === false` — the suspension store itself says no
+   *    live pause exists. It THROWS when the store cannot be read, and that
+   *    case is SKIPPED, never counted as dead: an unreadable store means
+   *    "unknown", and a storage outage must not be published as a lost run.
+   *  - `getRun(runId) == null` — no terminal history row either (the `run_`
+   *    prefixed rows in `sys_automation_run`). A run that merely finished is
+   *    not stranded; a request whose run neither waits nor ever completed is.
+   *
+   * **Reports; never rewrites.** No status is changed and no run is cancelled.
+   * The decision genuinely happened — a human approved or rejected — and
+   * silently rolling it back would make the audit trail disagree with the
+   * facts. What an operator needs first is visibility: which requests are stuck
+   * at which step, and what the mirrored status field on the business record
+   * still says. Whether to re-run the downstream actions or re-open the
+   * approval is a judgement call this cannot make.
+   */
+  async inspectStrandedRequests(options) {
+    const empty = { scanned: 0, stranded: [], undetermined: 0 };
+    if (typeof this.automation?.hasSuspendedRun !== "function") return empty;
+    if (typeof this.automation?.getRun !== "function") return empty;
+    const limit = options?.limit ?? 500;
+    let rows = [];
+    try {
+      rows = await this.engine.find("sys_approval_request", {
+        where: { status: { $in: [...STRANDABLE_REQUEST_STATUSES] } },
+        limit,
+        context: SYSTEM_CTX2
+      }) ?? [];
+    } catch (err) {
+      this.logger?.warn?.("[approvals] stranded-request scan failed to list requests", {
+        error: err?.message ?? String(err)
+      });
+      return empty;
+    }
+    const stranded = [];
+    let undetermined = 0;
+    for (const raw of rows) {
+      const runId = raw?.flow_run_id ? String(raw.flow_run_id) : "";
+      if (!runId) continue;
+      let suspended;
+      try {
+        suspended = await this.automation.hasSuspendedRun(runId);
+      } catch (err) {
+        undetermined++;
+        this.logger?.warn?.("[approvals] stranded-request scan could not read the suspension store", {
+          request: raw?.id,
+          run: runId,
+          error: err?.message ?? String(err)
+        });
+        continue;
+      }
+      if (suspended) continue;
+      let terminal = null;
+      try {
+        terminal = await this.automation.getRun(runId);
+      } catch (err) {
+        undetermined++;
+        this.logger?.warn?.("[approvals] stranded-request scan could not read the run history", {
+          request: raw?.id,
+          run: runId,
+          error: err?.message ?? String(err)
+        });
+        continue;
+      }
+      if (terminal) continue;
+      const config = parseJson(
+        raw.node_config_json,
+        { approvers: [], behavior: "first_response" }
+      );
+      const mirrorField = config.approvalStatusField;
+      let mirroredStatus;
+      if (mirrorField) {
+        try {
+          const recs = await this.engine.find(raw.object_name, {
+            where: { id: raw.record_id },
+            limit: 1,
+            context: SYSTEM_CTX2
+          });
+          const rec = Array.isArray(recs) ? recs[0] : null;
+          if (rec) mirroredStatus = rec[mirrorField] ?? void 0;
+        } catch {
+        }
+      }
+      stranded.push({
+        requestId: String(raw.id),
+        status: raw.status,
+        runId,
+        flowName: typeof raw.process_name === "string" ? raw.process_name.replace(/^flow:/, "") : void 0,
+        nodeId: raw.flow_node_id ?? raw.current_step ?? void 0,
+        objectName: raw.object_name,
+        recordId: raw.record_id,
+        organizationId: raw.organization_id ?? null,
+        completedAt: raw.completed_at ?? void 0,
+        mirrorField,
+        mirroredStatus
+      });
+    }
+    if (stranded.length || undetermined) {
+      this.logger?.warn?.("[approvals] stranded terminal requests (decision recorded, flow run gone)", {
+        scanned: rows.length,
+        stranded: stranded.length,
+        undetermined,
+        requests: stranded.map((s) => `${s.requestId}@${s.nodeId ?? "?"} \u2192 run ${s.runId}`)
+      });
+    }
+    return { scanned: rows.length, stranded, undetermined };
+  }
   async releaseDeadRunRequests() {
     if (typeof this.automation?.getRun !== "function") return { scanned: 0, released: 0 };
     let rows = [];
@@ -5191,21 +5481,109 @@ function parseJson2(raw, fallback) {
   }
   return raw;
 }
+var PENDING_LOCK_LIMIT = 1e3;
+var SYSTEM_CTX3 = { isSystem: true, positions: [], permissions: [] };
+function lockedError(message) {
+  const err = new Error(`RECORD_LOCKED: ${message}`);
+  err.code = "RECORD_LOCKED";
+  err.statusCode = 409;
+  throw err;
+}
+function asIdList(id) {
+  if (typeof id === "number") return [id];
+  if (typeof id === "string") return id === "" ? null : [id];
+  if (id && typeof id === "object" && Array.isArray(id.$in)) {
+    const raw = id.$in;
+    const scalars = raw.filter((v) => typeof v === "string" || typeof v === "number");
+    return scalars.length === raw.length ? scalars : null;
+  }
+  return null;
+}
 async function pendingRequestFor(engine, objectName, recordId) {
   try {
     const rows = await engine.find("sys_approval_request", {
       where: { object_name: objectName, record_id: String(recordId), status: "pending" },
-      limit: 1
+      limit: 1,
+      context: { ...SYSTEM_CTX3 }
     });
     return Array.isArray(rows) && rows[0] ? rows[0] : null;
   } catch {
     return null;
   }
 }
+async function pendingRequestsForRecords(engine, objectName, recordIds) {
+  if (recordIds.length === 0) return [];
+  if (recordIds.length > PENDING_LOCK_LIMIT) {
+    lockedError(
+      `refusing to authorize an update naming more than ${PENDING_LOCK_LIMIT} records of '${objectName}' \u2014 the approval lock cannot check them row by row; scope the write`
+    );
+  }
+  if (recordIds.length === 1) {
+    const one = await pendingRequestFor(engine, objectName, String(recordIds[0]));
+    return one ? [one] : [];
+  }
+  try {
+    const rows = await engine.find("sys_approval_request", {
+      where: { object_name: objectName, record_id: { $in: recordIds.map(String) }, status: "pending" },
+      limit: PENDING_LOCK_LIMIT + 1,
+      context: { ...SYSTEM_CTX3 }
+    });
+    return Array.isArray(rows) ? rows : [];
+  } catch {
+    return [];
+  }
+}
+async function pendingRequestsForObject(engine, objectName) {
+  try {
+    const rows = await engine.find("sys_approval_request", {
+      where: { object_name: objectName, status: "pending" },
+      limit: PENDING_LOCK_LIMIT + 1,
+      context: { ...SYSTEM_CTX3 }
+    });
+    return Array.isArray(rows) ? rows : [];
+  } catch {
+    return null;
+  }
+}
+async function narrowToMatchedRecords(engine, objectName, where, candidates) {
+  const lockedIds = candidates.map((c) => String(c?.record_id ?? ""));
+  let rows;
+  try {
+    rows = await engine.find(objectName, {
+      where: { $and: [where, { id: { $in: lockedIds } }] },
+      fields: ["id"],
+      limit: lockedIds.length,
+      context: { ...SYSTEM_CTX3 }
+    });
+  } catch (err) {
+    lockedError(
+      `cannot determine which rows a predicate update on '${objectName}' would touch (${err?.message ?? String(err)}); ${candidates.length} record(s) of it carry a pending approval, so the write is refused`
+    );
+  }
+  const matched = new Set((Array.isArray(rows) ? rows : []).map((r) => String(r?.id)));
+  return candidates.filter((c) => matched.has(String(c?.record_id ?? "")));
+}
+async function gatingRequests(engine, ctx, objectName) {
+  const byId = asIdList(ctx?.input?.id);
+  if (byId) return pendingRequestsForRecords(engine, objectName, byId);
+  const rawWhere = ctx?.input?.options?.where;
+  const hasWhere = rawWhere !== void 0 && rawWhere !== null;
+  const whereObj = hasWhere && typeof rawWhere === "object" && !Array.isArray(rawWhere) ? rawWhere : null;
+  const namedIds = whereObj ? asIdList(whereObj.id) : null;
+  const candidates = namedIds ? await pendingRequestsForRecords(engine, objectName, namedIds) : await pendingRequestsForObject(engine, objectName);
+  if (candidates === null) return [];
+  if (candidates.length === 0) return [];
+  if (candidates.length > PENDING_LOCK_LIMIT) {
+    lockedError(
+      `refusing a predicate update on '${objectName}': more than ${PENDING_LOCK_LIMIT} of its records carry a pending approval, so the lock cannot decide row by row; scope the write to the rows you mean`
+    );
+  }
+  if (!hasWhere) return candidates;
+  if (namedIds && whereObj && Object.keys(whereObj).every((k) => k === "id")) return candidates;
+  return narrowToMatchedRecords(engine, objectName, rawWhere, candidates);
+}
 function bindApprovalLockHook(engine, logger) {
   engine.registerHook("beforeUpdate", async (ctx) => {
-    const id = String(ctx?.input?.id ?? "");
-    if (!id) return;
     const object = ctx?.object ?? ctx?.objectName;
     if (!object || String(object).startsWith("sys_approval")) return;
     const data = ctx?.input?.data ?? {};
@@ -5214,18 +5592,19 @@ function bindApprovalLockHook(engine, logger) {
     if (ctx?.session?.isSystem) return;
     const roles = ctx?.session?.roles ?? [];
     if (Array.isArray(roles) && roles.includes("admin")) return;
-    const pending = await pendingRequestFor(engine, object, id);
-    if (!pending) return;
+    const gating = await gatingRequests(engine, ctx, object);
+    if (gating.length === 0) return;
     const writerRun = ctx?.provenance?.flowRunId;
-    if (writerRun && pending.flow_run_id && String(writerRun) === String(pending.flow_run_id)) return;
-    const config = parseJson2(pending.node_config_json, {});
-    if (config?.lockRecord === false) return;
-    const mirror = config?.approvalStatusField;
-    if (typeof mirror === "string" && mirror && changedFields.every((f) => f === mirror)) return;
-    const err = new Error("RECORD_LOCKED: record is locked while an approval is in progress");
-    err.code = "RECORD_LOCKED";
-    err.statusCode = 409;
-    throw err;
+    for (const pending of gating) {
+      if (writerRun && pending?.flow_run_id && String(writerRun) === String(pending.flow_run_id)) continue;
+      const config = parseJson2(pending?.node_config_json, {});
+      if (config?.lockRecord === false) continue;
+      const mirror = config?.approvalStatusField;
+      if (typeof mirror === "string" && mirror && changedFields.every((f) => f === mirror)) continue;
+      lockedError(
+        `record '${String(pending?.record_id ?? "")}' of '${object}' is locked while an approval is in progress`
+      );
+    }
   }, { packageId: APPROVALS_HOOK_PACKAGE, priority: 50 });
   logger?.info?.("[approvals] record-lock hook bound");
 }
@@ -5274,7 +5653,7 @@ import {
   getApprovalNodeConfigJsonSchema,
   APPROVAL_NODE_TYPE
 } from "@objectstack/spec/automation";
-var SYSTEM_CTX3 = { isSystem: true, positions: [], permissions: [] };
+var SYSTEM_CTX4 = { isSystem: true, positions: [], permissions: [] };
 function nestVariables(variables) {
   const vars = {};
   for (const [key, value] of variables) {
@@ -5353,7 +5732,7 @@ function registerApprovalNode(automation, service, logger) {
           // their `trigger.*` snapshot root.
           variables: nestVariables(variables)
         }, {
-          ...SYSTEM_CTX3,
+          ...SYSTEM_CTX4,
           userId: context?.userId,
           organizationId: context?.organizationId,
           tenantId: context?.tenantId
@@ -5497,7 +5876,13 @@ var ApprovalsServicePlugin = class {
         const sweep = async () => {
           const results = await Promise.allSettled([
             svc.runEscalations(),
-            svc.releaseDeadRunRequests()
+            svc.releaseDeadRunRequests(),
+            // #4469 — the other half of the dead-run picture, and the one no
+            // sweeper could see: a request already TERMINAL whose run is gone.
+            // Read-only by design (it reports; it never rewrites a decision
+            // that really happened), so it rides the same clock purely to make
+            // the finding surface without an operator knowing to go looking.
+            svc.inspectStrandedRequests()
           ]);
           for (const r of results) {
             if (r.status === "rejected") {
@@ -5572,14 +5957,19 @@ var ApprovalsServicePlugin = class {
       await mountActionPages();
       await backfillApproverIndex();
     }
+    let automation;
     try {
-      const automation = ctx.getService("automation");
-      if (automation && typeof automation.registerNodeExecutor === "function") {
-        this.service.attachAutomation(automation);
-        registerApprovalNode(automation, this.service, ctx.logger);
-      }
+      automation = ctx.getService("automation");
     } catch {
-      ctx.logger.info("ApprovalsServicePlugin: no automation engine \u2014 approval node not registered");
+      automation = void 0;
+    }
+    if (automation && typeof automation.registerNodeExecutor === "function") {
+      this.service.attachAutomation(automation);
+      registerApprovalNode(automation, this.service, ctx.logger);
+    } else {
+      ctx.logger.warn(
+        "ApprovalsServicePlugin: no automation engine \u2014 the `approval` flow node is NOT registered. Every ADR-0019 approval flow in this deployment fails at execution time with NO_EXECUTOR. Add @objectstack/service-automation to the stack to enable them."
+      );
     }
   }
   async stop(ctx) {