fix(runtime): /actions answers the #9378 flow-dispatch status table, from one shared definition

[os-zhuang]

Fixes #9446

POST /api/v1/actions/:object/:action with a type: 'flow' action now answers the #9378 flow-dispatch status table, from one definition the trigger door reads too.

The defect

dispatchFlowAction (packages/runtime/src/action-execution.ts) mapped every success: false automation result to one answer — 400 FLOW_FAILED — under a comment asserting "The flow RAN and rejected". That is false for two of the four exits it caught: a DISABLED flow invoked through an action told the caller a run had failed when no node ever executed, and the producer's own result.code was available and ignored.

The ruling this implements

Maintainer, 2026-08-18, verbatim 「同意」 to the triage recommendation: the #9378 table is a property of the flow-dispatch contract, not of the trigger route, converged in stages. Door 2 converges here; door 3 (declared endpoints) is #9462 and is deliberately untouched.

engine exit	before, at /actions	now	trigger door
flow not found	400 FLOW_FAILED	404 RESOURCE_NOT_FOUND	same
flow disabled	400 FLOW_FAILED	409 FLOW_DISABLED	same
flow has no start node	400 FLOW_FAILED	422 FLOW_NO_START_NODE	same
ran and failed	400 FLOW_FAILED	400 FLOW_FAILED	same

Retry semantics changed, and that is the point

The status is a contract with the console, not just a number. All four answers were 400 before, and 400 FLOW_FAILED is terminal to the console — so three refusals that are not terminal-for-the-same-reason were being reported as one. After this change:

• 409 FLOW_DISABLED — reversible operational state. Enable the flow and the identical request succeeds. A caller may legitimately retry after an operator acts.
• 422 FLOW_NO_START_NODE — an authoring defect in the stored definition. Retrying cannot help.
• 404 — the action exists, the flow it targets does not. Retrying cannot help; the metadata needs fixing.
• 400 FLOW_FAILED — unchanged, still terminal, still the only row that says a run happened.

A caller that treats every non-2xx as "the action failed" is unaffected: all four are still refusals, still success: false, still with no inner envelope.

One definition, not a fourth copy

The mapping lives in a new module, packages/runtime/src/flow-dispatch-status.ts, and both doors read it. This is the part that matters more than the mapping: three doors each holding their own reading of one engine result is exactly what let them answer differently in the first place, so a second copy of the rule is a defect by construction. #9462 gets the same module to call.

respondToFlowTrigger (packages/runtime/src/domains/automation.ts) was refactored to delegate — a pure refactor with no behaviour change, pinned by its own untouched suite (automation-trigger-route-status.test.ts, 26 tests) and by the real-engine integration test in @objectstack/verify. Both stayed green throughout.

Declared file-surface expansion, stated rather than smuggled

The dispatch named action-execution.ts plus its test siblings. Two files outside it were touched, both deliberately:

• domains/automation.ts — the delegation above. Without it there are still two definitions of one rule, which is the thing the ruling forbids. The file carries no in-flight claim (verified: automation: the run-resume route still answers HTTP 200 wrapping an inner {success:false} — the route #3962's status-code unification left behind #8684 and automation resume: the request body's OUTER envelope is lenient — an unknown top-level key is silently ignored and the submission is treated as empty #8796 both landed), and packages/runtime is serialised to this card this round.
• content/docs/** — ui/actions.mdx documented the old divergence and cited this very issue; leaving it would ship documentation stating the opposite of the behaviour. automation/flows.mdx gains the cross-door note. protocol/kernel/http-protocol.mdx's declared-endpoint row now points at Declared endpoints (type: 'flow'): converge onto the #9378 status table — the ruled follow-up to #9446's staged execution #9462 rather than at this card — once this lands, a reader following that link from a line describing an unconverged door would conclude the door was fixed. That row's own statement (declared endpoints still answer 200) is unchanged. To be explicit: Declared endpoints (type: 'flow'): converge onto the #9378 status table — the ruled follow-up to #9446's staged execution #9462 is not addressed here.

What deliberately did NOT change

• The 400 message keeps its wording (Flow '...' failed: ...). It has been on the wire since [17.0.0-rc] /actions reports business failures as HTTP 200 inside a double envelope — the only route of 12 that does; unify on real status codes before GA #3962, the ruling is about status and code, and it names the flow — which this door needs because the flow name is in the trigger route's URL and nowhere in this one.
• An unclassified success: false still refuses with 400 FLOW_FAILED here, deliberately not the trigger door's 200. This route settled in [17.0.0-rc] /actions reports business failures as HTTP 200 inside a double envelope — the only route of 12 that does; unify on real status codes before GA #3962 that failures speak HTTP; the alternative residual is the 200 {"success":true,"data":{"success":false}} double envelope that ruling removed. The two doors differ here on purpose and each states why at its own site.
• No packages/spec edit. All three codes are already registered under @objectstack/runtime in ERROR_CODE_LEDGER; nothing needed widening. Their ledger notes still describe only the trigger door as the emitter — a provenance note that is now incomplete rather than wrong, left to the spec seat rather than edited here.
• error.details. The trigger door carries errorMessage / summary there; this door throws, and a throw's structured context is whatever resolveThrownHttpError reads off it. Out of this card's scope, recorded as a finding.

Reverse verification — both directions, predicted before running

A suite that only asserted the new codes would stay green under a regression that collapsed every exit back to one code. Both halves are pinned: each row answers its own status and code, and the rows are asserted as a set so a collapse reddens whatever the surviving answer is.

Then the fix was ablated — the blanket FLOW_FAILED restored at door 2, with the module and the trigger door left alone — and the outcome predicted before the run:

predicted	actual
9 red: rows 1/2/3, the distinguishability set, the classify-off-verdict case, the no-getFlow case, and 3 of the 4 cross-door parity cases	exactly those 9 — expected 200 to be 404, expected 400 to be 409, expected 400 to be 422
4 green: row 4, the success 200, the unclassified-residual guard, the parity case for the row that already agreed	exactly those 4
the trigger door's own suite fully green	26/26 green

The four that stay green do not claim to pin the defect: three are regression guards for behaviour that must not change (including the guard against re-introducing the #3962 double envelope, which the ablation restores identically), and the fourth is the parity row that already agreed before this change.

A second reverse check, on the type side: renaming the compared member to a non-member made tsc refuse it — "types ... and '"FLOW_DISABLED_TYPO"' have no overlap" — which proves the closed AutomationResult.code union is being read from a rebuilt declaration rather than a stale or any one.

Verification

All of the below ran at commit 41ff10ed7 — the final commit — on a tree whose dependency closure was built first. The gate list was re-derived from the actual changed paths (scripts/pm/dispatch-gates.mjs), not taken from the dispatch's initial list, which named four families; the re-derivation named seventeen plus five convention-triggered ones.

Tests

• packages/runtime full suite — 170 files / 2528 tests, all green
• packages/runtime typecheck (tsc --noEmit) — green
• Consumer packages (downstream dependents, --filter '...@objectstack/runtime'): @objectstack/client 23 files / 310 tests green - @objectstack/verify 7 / 32 green (includes the real-AutomationEngine trigger-route integration test) - @objectstack/cloud-connection 23 / 191 green - @objectstack/http-conformance 4 / 72 green - @objectstack/hono 2 / 73 green

Gates

Green: check:nul-bytes - check:cross-package-test-inputs - check:route-envelope - check:dispatcher-error-vocabulary - check:docs-audit-scope - check:docs-redirects - check:role-word - check:changeset-gate-self-tests - check:objectui-changeset - check-adr-0087-registration - check-changeset-no-major - check-empty-changeset - check-affected-docs - check:query-options-erasure - check:engine-double-contract - check:where-matcher - check:type-check-coverage - spec liveness: check:liveness, check:empty-state, check:strictness-ledger, check:variant-docs.

Not completed locally: check:type-check-debt --re-measure timed out under contention for the shared build lock. The thing it would catch was measured directly instead — tsc over packages/runtime including test files (which its own tsconfig excludes) reports 227 pre-existing errors and 0 in the new test file, so this diff cannot push the frozen count up. Its structural half (check:type-check-coverage) is green above. CI runs the ratchet.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/runtime, touching 10 documentable anchor(s).

⛔ 1 release-owned page(s) name something this change touched. These are read-only:

• content/docs/releases/v17.mdx (via /:name/toggle (route))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

Coarse fallback — 23 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 7e202882092bf460b0045f2be9a281797a849462 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from c51a82aff612af37e80ac68e0336716304b055c6 — the merge of head 41ff10ed751228be62eb5fca6b72ce292420ec60 into base 7e202882092bf460b0045f2be9a281797a849462, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin c51a82aff612af37e80ac68e0336716304b055c6 && git checkout c51a82aff612af37e80ac68e0336716304b055c6
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 7e202882092bf460b0045f2be9a281797a849462 41ff10ed751228be62eb5fca6b72ce292420ec60 && git checkout -B drift-repro 7e202882092bf460b0045f2be9a281797a849462 && git merge --no-ff 41ff10ed751228be62eb5fca6b72ce292420ec60

node scripts/docs-audit/affected-docs.mjs --json 7e202882092bf460b0045f2be9a281797a849462

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 7e202882092bf460b0045f2be9a281797a849462 → pass the list as
args.docs, on the commit named under Which tree this was computed on.