fix(automation): answer real HTTP status codes on both trigger routes

[os-zhuang]

Part of #9378 — Part of, not Fixes, deliberately: two of the four rows the ruling
decided are NOT implemented here and the card must stay open for them. Which two, and
why, is the second section below.

Both automation trigger doors answered HTTP 200 wrapping an inner {success: false}
for a flow that ran and failed:

HTTP 200
{"success":true,"data":{"success":false,"error":"Node 'create_opportunity' failed: …"}}

That is the double envelope #3962 ruled out for /actions and #8684 closed on the resume
route (PR #9379, merged 2026-08-17). This is the wider half of the same residue: the
trigger route is the door every app dispatches flows through, so a caller that branches on
the HTTP status alone read every failed run as a successful one.

Implemented per the maintainer ruling recorded on the card (2026-08-17), inheriting
#9379's shape in full: producer classifies, route maps, packages/spec untouched, no
sniffing.

What changes

Producer first — packages/services/service-automation/src/engine.ts.execute()
stamps status: 'failed' on the exits where a run DISPATCHED and was rejected — the
ordinary failure exit, the exhausted errorHandling.strategy: 'retry' exit, and
executeWithoutRetry's catch. It is the same lifecycle verdict the exit already writes to
the run log two statements earlier. Its three never-dispatched exits (flow not found, flow
disabled, no start node) carry no status, and that absence is what makes the transport's
arm provable rather than a heuristic.

status and not a new code: AutomationResult.code is a closed union of resume-refusal
members, and the ruling on #9384 (2026-08-17) keeps it closed — the engine classifies with
EXISTING vocabulary. status?: 'completed' | 'paused' | 'failed' is exactly that:
declared on the contract, documented as the run's lifecycle verdict. No packages/spec
edit, measured — tsc --noEmit on service-automation holds at its 3 ledgered TS2341
errors, unchanged.

Route stays a pure mapper — packages/runtime/src/domains/automation.ts. Both doors
answer through one extracted respondToFlowTrigger, the way they already shared one
context builder (#4127) so they could not drift about what a body means.

engine exit	reality	answer
flow not found	never dispatched	404 (registry probe, before dispatch)
ran and failed · retry attempts exhausted	ran, rejected	400FLOW_FAILED
flow disabled · no start node	never dispatched	unchanged 200 — see below

The 404 is the shared existence probe, not a result reading. It is the same
getFlow probe POST /:name/toggle (#7535) and GET /:name use, so no two doors can
disagree about which flows exist, and the engine is never asked to run a name it does not
hold. The line this draws is principled and worth a reviewer's eye: existence is a
question the transport owns (every REST resource route owns its own 404); execution
policy is the producer's. getFlow is optional on IAutomationService, so an
implementation that omits it is unchanged rather than 404'd on a guess.

The consumer contract is carried, not dropped. The ADR-0112 envelope has no data, so
the flow author's own errorMessage travels in error.details.errorMessage — the one
documented location the console reads (objectui flowResponse.ts, PR #4899) — and the
run's per-node summary rides in details for the same reason it was on the 200 body: it
is how a caller finds WHICH node failed. objectui already classifies 400FLOW_FAILED
and 404 on these routes as terminal (objectui#4784 / PR #4899); nothing there is
changed by this PR.

@objectstack/client needed no code change and this is a measured finding, not an
omission: fetch already throws on every non-2xx before any unwrapping, so
client.automation.trigger(), client.automation.execute() and
client.project(id).automation.execute() now reject with err.code === 'FLOW_FAILED',
err.httpStatus and err.details.errorMessage instead of resolving with an inner failure.
All three surfaces document the new contract and all are pinned by tests — trigger()
reads res.json() while execute() reads unwrapResponse(), so both unwrap paths are
pinned separately.

The two rows this does NOT implement, and why they are reported rather than resolved

The ruling's table has four rows. Two of them — flow disabled ⇒ 409 and no start
node ⇒ 422 — cannot be delivered honestly under the constraints the same ruling carries,
and the dispatch's own instruction for that case is to stop on the arm and report back.

Both are never-dispatched exits, so separating them needs the producer to say which is
which, and the closed AutomationResult.code union has no honest member for either:
RUN_NOT_FOUND is documented as "no suspension exists for the run id", RESUME_IN_PROGRESS
is a concurrent-resume refusal, and nothing in it maps to 422 at all. Widening the union is
a packages/spec fragment the ruling on #9384 routes to the spec seat, and it explicitly
forbids minting one mid-PR.

The two workarounds were considered and rejected, not overlooked:

• Match the engine's message text ("is disabled" / "has no start node") — a regex
  on prose, the tolerant-consumer shape PD Add comprehensive test suite for Zod schema validation #12 forbids.
• Probe enable-state at the route via getFlowRuntimeStates() — this would put a
  second copy of the engine's own execution policy in the transport, and it cannot answer
  422 except by elimination, which mis-answers the TOCTOU case: a flow disabled between
  probe and dispatch would be reported as a malformed definition. Wrong for a new reason
  is not better than unchanged.

So those two exits keep TODAY's behaviour, and both are PINNED as unchanged in
automation-trigger-route-status.test.ts rather than left unexamined. Pinning them is also
what proves the 400 arm is not a shape heuristic: both carry success: false exactly like
a failed run — one of them carrying summary and durationMs too — and both stay 200
because they carry no status: 'failed'. When the union question is ruled, those are the
assertions that flip.

For the spec seat, one line: adding 'FLOW_DISABLED' and 'FLOW_NO_START_NODE' to
that union would let the engine name both classes directly and this route gain two more
coded arms. Same measured cost as #9384 recorded for FLOW_FAILED: union members plus
TSDoc, no generated-artifact churn.

Consumer migration — the dogfood gate found a real one (second commit)

Dogfood Regression Gate went red on
packages/qa/dogfood/test/flow-runas.dogfood.test.ts, and it was right to: the
runAs:'user' WRITE leg of the #1888 identity proof triggers a flow whose update_record
node is refused at the record layer, so the run fails and now answers 400FLOW_FAILED
instead of a 200 wrapping the inner failure. Its memberTrigger helper asserted a blanket
< 300.

The semantic that file pins is unchanged and still primary — the run executes AS the
member, so the admin's note stays 'new'. Only the transport expectation moved, and it is
asserted precisely rather than as a widened band: status 400, error.code
FLOW_FAILED, the node-first access-refusal text, and the touch node's failure entry
in error.details.summary. A 403 or 500 there would mean de-elevation broke in a
different way, and this file exists to catch exactly that.

The READ leg is deliberately not migrated — measured, not assumed: an RLS-scoped read
is FILTERED rather than refused, so that run still succeeds with an empty found and keeps
its < 300 expectation. That leg also gains discrimination for free: until now a failed
run and an empty read were indistinguishable there, because both left found falsy under
HTTP 200.

Every other trigger caller in packages/qa/dogfood expects the run to SUCCEED (or
asserts an anonymous 401), so none is touched by this contract — swept rather than assumed,
and all of them were run locally (below). No changeset change: @objectstack/dogfood is
private internal QA and the wire change is already documented in the changeset.

Scope held

• packages/spec untouched, per the ruling.
• objectui untouched — its consumer half is already landed (objectui#4784 / PR ci(release): 解堵 17.0.0-rc.2,并让空 changeset 不再吃掉一整轮发布 (#4898) #4899);
  cited, not changed.
• content/docs/releases/ untouched; the changeset is this PR's only release input.
• Two fixtures in domain-handler-registry.test.ts gained a resolving getFlow stub:
  their subject is body translation and contract-method preference, and a registry that
  claims the flow does not exist never reaches execute now. Disposition per fixture
  triage: declarations added, no assertion weakened.

Verification

Union of gates re-run at 4a37192 — the final commit, tree clean, nothing pushed after it.
Re-derived against the actual changed paths, which is what caught the four spec-liveness
families the dogfood path pulls in (packages/qa/dogfood/** is a CI trigger for
spec-liveness-check.yml, because the liveness ledger reads dogfood usage as evidence):

Local gates for this card (paste into the dispatch prompt):
- pnpm check:changeset-gate-self-tests [lint.yml]
- pnpm check:cross-package-test-inputs [lint.yml]
- pnpm --filter @objectstack/spec run check:empty-state [spec-liveness-check.yml]
- pnpm --filter @objectstack/spec run check:liveness [spec-liveness-check.yml]
- pnpm check:objectui-changeset [lint.yml]
- pnpm check:route-envelope [lint.yml]
- pnpm --filter @objectstack/spec run check:strictness-ledger [spec-liveness-check.yml]
- pnpm check:test-source-alias [lint.yml]
- pnpm check:type-source-resolution [lint.yml]
- pnpm --filter @objectstack/spec run check:variant-docs [spec-liveness-check.yml]
- node scripts/check-adr-0087-registration.mjs [cut-rc.yml, pr-automation.yml]
- node scripts/check-changeset-no-major.mjs [cut-rc.yml, pr-automation.yml]
- node scripts/check-cross-package-test-inputs.mjs [ci.yml]
- node scripts/check-empty-changeset.mjs [cut-rc.yml, pr-automation.yml]
- node scripts/docs-audit/check-affected-docs.mjs [docs-drift-check.yml]
Convention-triggered gates (this change KIND moves them):
adds or edits a test file:
- pnpm check:query-options-erasure
- pnpm check:type-check-coverage
- pnpm check:type-check-debt
- pnpm check:engine-double-contract
- pnpm check:where-matcher

All green at 4a37192, plus check:nul-bytes. check:type-check-debt --re-measure ran on
a fully built workspace closure: 33 ledger entries, 1926 raw errors, none above its
recorded number, surplus none. check:where-matcher: 253 matchers, 0 silently wrong.
check:liveness: every governed-type property classified, README state table current.
check-adr-0087-registration answered not-required (no-migration-prescription) — this
retires no metadata surface, so objectstack migrate meta has nothing to rewrite; the
changeset is the channel that reaches these consumers. check-changeset-no-major refused a
major for the same reason #9379 recorded (one Changesets fixed group ⇒ a single major
promotes the monorepo), so the bump is minor with the BREAKING framing kept in the body.

Tests: @objectstack/runtime 166 files / 2489 tests, @objectstack/service-automation
80 files / 973 tests, @objectstack/client 23 files / 307 tests — all passing.
typecheck green for runtime, client and dogfood; service-automation has no
typecheck script and its 3 ledgered TS2341 errors (in a file this PR does not touch) are
unchanged.

Dogfood, run locally on a built workspace closure (the red gate reproduced first, then
fixed):

flow-runas.dogfood.test.ts 5 passed (was 1 failed)
flow-node · flow-function-effect · flow-durable-suspend ·
showcase-declarative-mcp 17 passed
showcase-anonymous-deny-surfaces · authz-conformance 46 passed

Reverse verification, direction predicted before running, both legs from the committed
state:

• Ablating the engine's status: 'failed' on the ran-and-failed exit ⇒ predicted RED, one
  engine test: expected undefined to be 'failed'. Observed exactly that (1 failed, 3
  passed).
• Ablating the route's FLOW_FAILED arm ⇒ predicted RED on the 400 assertions only, GREEN
  on the 404 probe, the success/paused arms and the two unchanged-200 pins. Observed 10
  failed / 12 passed, the failures being expected 200 to be 400 and the two details
  reads — i.e. the 200 pins held while the 400 pins fell, which is the shape that proves
  they are pinning different facts.

Both ablations restored with a checkout of the committed path, and the tree re-verified
clean.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/client, @objectstack/runtime, @objectstack/service-automation, touching 10 documentable anchor(s).

5 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/api/client-sdk.mdx(via automation.execute (sdk), automation.trigger (sdk))
• content/docs/api/plugin-endpoints.mdx(via /:name/trigger (route), /trigger/:name (route))
• content/docs/automation/flows.mdx(via automation.execute (sdk), /:name/trigger (route))
• content/docs/protocol/kernel/http-protocol.mdx(via /:name/trigger (route))
• content/docs/ui/actions.mdx(via /:name/trigger (route))

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

• content/docs/releases/v17.mdx(via retryExecution (symbol), /: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

• 2 name(s) were too generic to anchor anything (single lowercase words)

Coarse fallback — 31 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 origin/main → packageMentionDocs.

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 origin/main → pass the list as args.docs.

[os-zhuang]

ACCEPT — PM review at 2116dde (dispatching seat, session session_01NYgmGheCzM6NrHZN436Cxf). Reviewed against the full diff, not the report.

The two delivered rows are exactly the ruling's: 404 via the shared existence probe (transport owns existence; engine never asked to run a name it does not hold; getFlow? optionality respected), 400 FLOW_FAILED read off the producer's status: 'failed' — which is the ruling-compliant masterstroke here: existing declared vocabulary (AutomationResult.status, the run log's own verdict), so packages/spec stays untouched per #9384 while the classification is still a producer fact, not a route heuristic. The never-dispatched exits' absence of status is itself pinned, which makes the 400 arm provable.

The stop on 409/422 is the correct execution of the dispatch's stop-and-report clause, and both rejected workarounds are rejected for the right reasons (message regex = PD #12; route-side enable-state probe = policy duplication + TOCTOU misclassification). The two rows are pinned as unchanged-200 with the flip conditions written in place. Part of keeps #9378 open — correct.

Follow-up filed by the PM: the spec-seat card for FLOW_DISABLED / FLOW_NO_START_NODE union members + the two route arms + flipping these pins — that PR carries Fixes #9378. The docs-drift advisory's 5 hand-written pages ride that card's re-verification list (this PR's changeset is the migration note of record meanwhile).

Flipped ready + armed merge-when-ready — lands through the lane; ships in the same release window as the resume flip per the ruling.

---

Generated by Claude Code