feat(service-automation): an operator can put back a suspension a failed resume consumed (#13951)

* wip: #13909 slice 2 operator exit verb

* fix(automation): restore the dropped forgetSuspendedRun call

* feat(service-automation): an operator can put back a suspension a failed resume consumed (#13909)

* fix(service-automation): publish the restore vocabulary at the barrel and true up the sys_automation_run declaration

Contract-review rework (ruling recorded on PR 13951; behaviour unchanged):

- index.ts: export type SuspensionRestoreResult / SuspensionRestoreRefusal in
  the engine.js type block. The verb was already barrel-reachable, so the
  eight refusal values were published de facto while the union was unnameable
  de jure — no exhaustive switch, no annotated result, no typed handler
  parameter. ConsumedSuspension deliberately stays unexported (it appears in
  no barrel-reachable signature).
- consumed-suspension-restore.test.ts: barrel-import pin. The existing suite
  imports from './engine.js', which is why the gap had no witness. The pin
  annotates a real result with the BARREL type and writes the exhaustive
  switch (never-typed default), so removing the export breaks tsc; the
  runtime half pins the verb on the class the barrel itself exports.
- sys-automation-run.object.ts: the declaration asserted invariants this PR
  falsified. One-class corrections only — the node_type description and the
  trigger-attribution comment now carve out the consumed-suspension class of
  terminal row (the same correction shape this PR already applied in
  plugin-approvals' backfill), and variables_json's description names the
  presence-discriminator the store's deserializer keys off.
- engine.ts: the NO_CONSUMED_SUSPENSION docblock no longer claims "exists and
  is terminal" — the arm also answers on a non-terminal logged status, and
  the reason string was already honest about that.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016ZC5rNQj3WEet5HAmmAkMs

* fix(service-automation): keep tracker ids out of the declaration's runtime strings

check:doc-authoring is right: the two descriptions the rework corrected
carried '#13909' inside runtime string prose, which reaches operators who
cannot resolve a tracker id. The carve-out text stays; the ids move to
adjacent comments (the reader who can resolve them reads the source).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016ZC5rNQj3WEet5HAmmAkMs

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

.changeset/automation-consumed-suspension-restore.md

@@ -0,0 +1,48 @@
+---
+"@objectstack/service-automation": minor
+"@objectstack/plugin-approvals": patch
+---
+
+feat(service-automation): an operator can put back a suspension a failed resume consumed (#13909)
+
+A run that was resumed and whose downstream node merely **threw** was
+terminally unresumable, and nothing anywhere could move it. The engine consumes
+the suspension *before* running downstream nodes, so such a node throws with
+the pause already gone and the catch arm records the run `failed`: `resume`
+then answers `RUN_NOT_FOUND`, `cancelRun` is a no-op, and none of the engine's
+other public methods takes the run anywhere. A deployment could enter that
+state and never leave it.
+
+`AutomationEngine.restoreConsumedSuspension(runId, { requestedBy, reason })`
+is the exit. It puts the consumed suspension back — verbatim, as it stood at
+the pause — so the run is resumable again through an ordinary `resume`, with
+the same authority gate, the same screen validation and the same idempotency
+guard as any other.
+
+- **Deliberate, never automatic.** Nothing calls it on its own: no retry, no
+  sweeper. An operator asks for one run, by id.
+- **Safe to refuse, with the reason named.** A run that is still suspended, one
+  whose resume is *in flight*, one that completed, one that was cancelled, one
+  that never suspended, and an unknown id each get their own refusal — as does
+  an unreadable store, which is refused rather than guessed at.
+- **Idempotent.** A suspension is keyed by run id, so however many operators
+  ask there is one resumable pause and no extra traversal — the verb re-arms
+  and stops. Two racing callers in one process get one restore and one refusal.
+- **It leaves a trace.** The restore is logged with the run, flow, node, when
+  the suspension was consumed, who asked and why, and the run is recorded
+  `paused` again so the repair is not invisible. Across a restart the exit
+  still works: the consumed suspension rides the run's own terminal history row
+  (in `sys_automation_run` columns that already existed), and a run that is
+  restored and then finishes clears it.
+
+⚠️ A repair, not a prevention. The failed attempt's side effects are **not**
+undone and the original resume signal is **not** replayed — the continuation
+must be re-issued. Whether the pause should survive a downstream throw at all
+is a separate, unruled decision (#13937); this change leaves the resume
+ordering, `forgetSuspendedRun` and `traverseNext` exactly as they are, mints no
+new run status, and works whichever way that is ruled — the runs already stuck
+today are not released by changing what future resumes do.
+
+`plugin-approvals` carries a comment correction only: its organization backfill
+documented `context_json` as never written on terminal rows, which this change
+makes false for that one class of row. No behaviour change there.

packages/plugins/plugin-approvals/src/backfill-platform-row-organizations.ts

@@ -168,9 +168,12 @@ export const BACKFILL_TARGETS: readonly BackfillTarget[] = [
     subjectObjectField: 'trigger_object',
     subjectIdField: 'trigger_record_id',
     // `context_json` is the serialized AutomationContext; the trigger record
-    // sits at `.record`. Written on paused rows only — `recordTerminal` does
-    // not persist it, so terminal rows resolve from the live subject or not
-    // at all.
+    // sits at `.record`. Written on every paused row, and — since #13909 —
+    // on the one class of TERMINAL row that carries a restorable suspension
+    // (a run whose resume consumed its pause and then failed downstream).
+    // Every other terminal row still has none, so those still resolve from the
+    // live subject or not at all. Nothing here needs to branch on which: a row
+    // that HAS the snapshot uses it, exactly as a paused row does.
     snapshotField: 'context_json',
     snapshotPath: ['record'],
     statusField: 'status',