fix(automation,approvals): 审批决策不能在流程原地不动的情况下"成功" (#4420) (#4460)

* fix(automation,approvals): an approval decision can no longer succeed while its flow stays parked (#4420)

A flow paused at an `approval` node, a deploy, then an approver clicking
Approve: the request row flipped to `approved`, the UI toasted success — and
the flow never moved. No next-stage request, no error, the record's mirrored
status frozen mid-workflow. Approval flows pause for days by design, so a
restart mid-flight is the normal case, not the edge one.

Durable suspended runs (#1518) had shipped and were not the missing piece.
Two other things were.

The wiring could enable a store over a table nobody had created. Object
registration and store activation resolve different services in different
phases — `manifest` at init(), `objectql` at start() — and the plugin declared
no ordering. Composed ahead of ObjectQL, init() found no `manifest`, warned,
and continued; start() attached the DB-backed store anyway. Every suspend then
failed with `no such table: sys_automation_run` into a log line nobody read.
Now: `optionalDependencies: ['com.objectstack.engine.objectql']` (order-if-
present per ADR-0116 — an engine-less kernel must still boot), a missed
registration retried at start() while it still precedes schema sync, no store
attached when registration did not happen (at error level), a boot-time table
probe, and a failed durable write logged at error rather than warn.

A reported resume failure read as success. `AutomationEngine.resume()` answers
a lost run by RETURNING `{ success: false }`, never by throwing; approvals
discarded that value and counted only throws as failure. Resume failures are
now classified — RUN_NOT_FOUND, STORE_UNAVAILABLE, RESUME_IN_PROGRESS —
so a run gone for good is distinguishable from a store merely unreachable,
and the raw resume route maps them to 404 / 503 / 409.

Approvals acts on them. The new `hasSuspendedRun(runId)` — which reads the
suspension store, unlike `getRun()`, and throws rather than answering false
when the store is unreadable — pre-flights decide / sendBack / resubmit BEFORE
their first write, so the zombie half-state is never created rather than
merely reported: RESUME_TARGET_LOST (409), request left actionable. A resume
that fails after the decision is durable throws RESUME_FAILED (500) naming the
stranded run. A concurrent duplicate stays benign via the new `resumeError`
field; recall and revise-window cancellation stay non-fatal but log at error.
Compositions with no automation engine attached are unaffected.

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

* docs(spec): regenerate the API reference for the new resume error codes (#4420)

`check:docs` compares `content/docs/references/` against what
`gen:schema && gen:docs` produces. The five codes this branch registers in the
ADR-0112 ledger — RUN_NOT_FOUND, STORE_UNAVAILABLE, RESUME_IN_PROGRESS,
RESUME_TARGET_LOST, RESUME_FAILED — feed `ErrorCode`, which the generator
inlines into every response-envelope table. Hence eleven files, all of it the
same union widening: the ledger page gains the five entries and every page
that renders an ApiError picks them up.

Generated, not hand-edited:
  pnpm --filter @objectstack/spec gen:schema && pnpm --filter @objectstack/spec gen:docs

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

---------

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

Author: os-zhuang

.changeset/approval-decision-survives-restart.md

@@ -0,0 +1,64 @@
+---
+"@objectstack/spec": minor
+"@objectstack/service-automation": minor
+"@objectstack/plugin-approvals": minor
+"@objectstack/rest": patch
+"@objectstack/runtime": patch
+---
+
+fix(automation,approvals): an approval decision can no longer succeed while its flow stays parked (#4420)
+
+A flow paused at an `approval` node, a deploy, then an approver clicking
+Approve: the request row flipped to `approved`, the UI toasted success — and
+the flow never moved. No next-stage request, no error, the record's mirrored
+status frozen mid-workflow. Approval flows pause for days by design, so a
+restart mid-flight is the normal case: every release could quietly zombify
+every in-flight approval, with the approvers none the wiser.
+
+Durable suspended runs (#1518) had shipped and were not the missing piece. Two
+other things were.
+
+**The wiring could enable a store over a table nobody had created.** Object
+registration and store activation resolve different services in different
+phases — `manifest` at `init()`, `objectql` at `start()` — and the plugin
+declared no ordering. Composed ahead of ObjectQL, `init()` found no `manifest`,
+warned, and continued; `start()` then attached the DB-backed store anyway. Every
+suspend failed with `no such table: sys_automation_run` into a log line nobody
+read, pauses silently stayed in memory, and the next restart lost them all.
+Now: `AutomationServicePlugin` declares `optionalDependencies:
+['com.objectstack.engine.objectql']` (order-if-present, per ADR-0116 — an
+engine-less kernel must still boot); a registration missed at `init()` is
+retried at `start()`, which still lands before ObjectQL's schema sync; the
+store is never attached when registration did not happen, and says so at
+**error** level instead of warning; the table is probed once at boot so a
+broken setup surfaces there rather than one failed write at a time; and a
+failed durable write of a paused run is logged at error — it is data loss in
+waiting, not a warning.
+
+**A reported resume failure read as success.** `AutomationEngine.resume()`
+answers a lost run by *returning* `{ success: false }`, never by throwing.
+`ApprovalService` discarded that return value, and `decide()` counted only a
+thrown error as failure — so a decision against a dead run came back
+`resumed: true`, HTTP 200. Resume failures are now classified
+(`RUN_NOT_FOUND`, `STORE_UNAVAILABLE`, `RESUME_IN_PROGRESS`, joining
+`PERMISSION_DENIED` / `INVALID_SIGNAL`), so a run that is gone for good is
+distinguishable from a store that is merely unreachable, and the raw resume
+route maps them to 404 / 503 / 409.
+
+Approvals acts on them. A new `AutomationEngine.hasSuspendedRun(runId)` — which
+reads the suspension store, unlike `getRun()`, and throws rather than answering
+`false` when the store is unreadable — pre-flights every flow-advancing
+operation (`decide`, `sendBack`, `resubmit`) **before its first write**, so the
+zombie half-state is never created rather than merely reported: the decision
+fails with `RESUME_TARGET_LOST` (HTTP 409) and the request stays actionable. A
+resume that fails after the decision is durable can no longer be undone, but it
+now throws `RESUME_FAILED` (HTTP 500) naming the stranded run instead of
+reporting success. A concurrent duplicate resume stays benign — the engine's
+idempotency guard is doing its job — and reports through the new optional
+`resumeError` field. Recall and revise-window cancellation stay non-fatal by
+design (they abandon the request), but log at error with the reason instead of
+swallowing it. Compositions with no automation engine attached are unaffected.
+
+Existing zombie requests from affected deployments (already `approved`, run
+stranded) are not repaired by this change — `releaseDeadRunRequests` only
+sweeps requests that are still `pending`.

content/docs/references/api/analytics.mdx

@@ -280,13 +280,17 @@ const result = ErrorCode.parse(data);
 * `REQUEST_NOT_FOUND`
 * `RESEED_NO_ROWS`
 * `RESEED_SKIPPED`
+* `RESUME_FAILED`
+* `RESUME_IN_PROGRESS`
+* `RESUME_TARGET_LOST`
 * `ROUTE_NOT_FOUND`
 * `RULE_DEFINE_FAILED`
 * `RULE_DELETE_FAILED`
 * `RULE_EVALUATE_FAILED`
 * `RULE_GET_FAILED`
 * `RULE_LIST_FAILED`
 * `RULE_NOT_FOUND`
+* `RUN_NOT_FOUND`
 * `SAML_REGISTER_FAILED`
 * `SCHEDULES_LIST_FAILED`
 * `SCHEDULE_DELETE_FAILED`
@@ -303,6 +307,7 @@ const result = ErrorCode.parse(data);
 * `SIGN_IN_REQUIRED`
 * `SSO_REGISTER_FAILED`
 * `SSO_REGISTER_FORBIDDEN`
+* `STORE_UNAVAILABLE`
 * `SUGGESTION_CONFIRM_FAILED`
 * `SUGGESTION_DISMISS_FAILED`
 * `SUGGESTION_LIST_FAILED`