feat(spec): name the terminally-failed-but-repairable run 'stranded' on AutomationResult.status (#14384)

[claude]

Fixes#14384

Contract half of the #13937 shape-4 ruling (director seat, comment 5491060439; maintainer 2026-09-01 「其他同意」), quoted verbatim on the card and untranslated here:

2. 命名同批定(service-automation: a resume consumes the pause BEFORE running downstream nodes, so any node that throws leaves the run terminally unresumable — and the only inspector for it reports all clear #13909 交付项 3 在此收口):该条件成为运维要操作的持久状态 ⇒ 平台级名字落 packages/spec/src/contracts/automation-service.ts(AutomationResult.status 现为 'completed' | 'paused' | 'failed')⇒ 触 spec ⇒ 条款②契约复审档位适用。StrandedRunState 保持 plugin 局部报告标签不升格。

What changed — one contract increment

• packages/spec/src/contracts/automation-service.ts — AutomationResult.status is now 'completed' | 'paused' | 'failed' | 'stranded', with a JSDoc paragraph naming the condition: a resume CONSUMED the suspension, a downstream node threw, the run is recorded as failed and can be re-armed only by an explicit operator verb (never by resume, which answers RUN_NOT_FOUND for it, and never automatically). Distinct from 'failed' on purpose: that one says the run ran and was rejected; this one says a recorded continuation stopped mid-flight and an operator has something to repair. The JSDoc also states that plugin-approvals' StrandedRunState is NOT promoted.
• packages/spec/src/api/automation-api.zod.ts — the wire mirror TriggerFlowResponseSchema.data.status carries the same four (the existing TriggerFlowDataMatchesContract pin goes red if only one side moves; see the reverse verification). The .describe() prose names the condition without an issue id: check:doc-authoring refused the first spelling (customer-facing text must not carry #NNNN), so the card references moved to an adjacent line comment.
• packages/spec/src/contracts/automation-result-status.pin.test.ts (new) — pins, each on its own: (1) the union's exact membership at the type level (an Assert over an Eq identity, the automation-api.zod.test.ts form, compiled by check:test-typecheck, plus a satisfies list); (2) wire-to-contract parity at both levels (the Zod enum's .options read at runtime, and its inferred type bound to the contract's); (3) that the doc block above the declaration names the condition (source read); (4) a stranded envelope parses AND is preserved through the strip-mode object; (5) a literal outside the four is refused at data.status with invalid_value.
• content/docs/references/api/automation-api.mdx — regenerated by gen:docs (check:generated --fix; the one artifact it proved stale). api-surface/ is unchanged: the snapshot records that AutomationResult exists, not its members.
• .changeset/automation-result-stranded-status.md — @objectstack/spec: minor, additive (no BREAKING declaration, so no ADR-0087 marker is owed; check:adr-0087-registration exit 0).

Not in this PR, by the card: no engine change, no operator verb, no REST route, no ExecutionStatus widening. Those are #13937 (services half, stays open) and #13953.

The literal — what was measured before choosing

Vocabularies read (packages/spec/src, packages/services/service-automation, packages/plugins/plugin-approvals):

vocabulary	members	shape
AutomationResult.status (this union)	completedpausedfailed	single-word participles
ExecutionStatus (automation/execution.zod.ts, the run-row vocabulary listRuns filters on)	pendingrunningpausedcompletedfailedcancelledtimed_outretrying	single words; snake_case for two words
TaskStatus (system/worker.zod.ts)	pendingqueuedprocessingcompletedfailedcancelledtimeoutdead	dead = moved to the dead-letter queue
JobExecutionStatus (system/job.zod.ts)	runningsuccessfailedtimeoutdegraded
StrandedRunState (plugin-approvals, report-only)	missingfailed	classifies WHY a request's run is unrecoverable
prose lineage	"stranded" / "strands" / "stranding"	#13807, #13909, #13937, PR #13934; inspectStrandedRequests, StrandedApprovalRequest; 8 comment sites in engine.ts

Candidates:

• 'stranded' — chosen. The word the whole measured lineage already uses for exactly this condition (service-automation: a resume consumes the pause BEFORE running downstream nodes, so any node that throws leaves the run terminally unresumable — and the only inspector for it reports all clear #13909 itself: "There is no run state called stranded"); a single-word participle beside its three siblings; it names the operator-facing STATE, which survives a later shape-2 re-ordering, rather than the mechanism. It is not a promotion of StrandedRunState: that type's members are 'missing' | 'failed', it stays plugin-local and report-only, and the JSDoc says so.
• 'dead' — the one in-spec precedent (TaskStatus), but there it means retries exhausted and dead-lettered; here nothing was retried, and "dead" reads as final where the ruling's whole point is re-armable.
• 'failed_resume' / 'resume_failed' — snake_case is the house shape for two words (timed_out), but both name the mechanism (the consumption ordering that [Decision] Workflow resume ordering: a thrown node today leaves the run terminally unresumable — which of three shapes, given that the current order buys exactly-once across a crash? #13937 may still change under shape 2) rather than the state an operator acts on.
• 'unresumable' — false the moment the re-arm verb exists.
• 'suspended' — the spec uses it for admin-suspended tenant / license / environment, and it collides with "suspension", which is the PAUSE.
• 'stalled' / 'stuck' / 'halted' / 'incident' — zero uses in the three trees; incident is a noun (Camunda's shape), not a participle.

Producer and consumer measurements

• AutomationResult.status is a TypeScript interface member, not Zod — verified. Its one Zod mirror in packages/spec/src is TriggerFlowResponseSchema.data.status; both updated, parity pinned.
• Producer today: AutomationEngine.resumeInternal's catch arm records the run ROW failed and returns { success: false, error, durationMs, errorMessage, summary } — no status at all on the resumed-failure envelope (only execute()'s dispatched-and-rejected exit stamps status: 'failed'). So stamping 'stranded' on the result is the services half's, and whether the run ROW (ExecutionStatus) ever carries the word is that half's to measure; this PR does not widen ExecutionStatus.
• Exhaustive switches over AutomationResult.status in packages/{runtime,services,plugins,rest,cli,client}: zero. The only case 'completed' | 'paused' | 'failed' outside spec is plugin-approvals' classifyStrandedRunState, which switches over the run ROW's status string with a deliberately silent default, not over this union. Narrow re-declarations of the three-member union outside spec: zero in code (two in comments, engine.ts:4182 and approval-service.ts:315).
• Sibling repo objectui: app-shell/src/utils/flowResponse.ts:108 types status?: 'completed' | 'paused' | 'failed' | string and branches on success === false — tolerant of the new literal; nothing to change there for this half.
• No consumer needed even a type-only accommodation.

Verification — all readings on head 2c4bc29, exit codes captured before any pipe

@objectstack/spec:

• pnpm --filter @objectstack/spec build — exit 0 (check-dts-emitted: 34/34 declared declaration file(s) present).
• pnpm --filter @objectstack/spec test (whole suite) — Test Files 453 passed | 1 skipped (454) · Tests 12214 passed | 1 skipped (12215) on the committed head. The one skip is scripts/root-entry-type-nameability.pin.test.ts: its inspectDistFreshness predicate saw dist older than src because the reverse verification below touched the contract file's mtime after the build (content byte-identical), and that pin skips by default on a stale dist. After rebuilding the dist that file re-ran on the same head: Test Files 1 passed (1) · Tests 2 passed (2); check:api-surface on the rebuilt dist: exit 0. The earlier full run on the pre-.describe()-edit tree with a fresh dist was 454 passed · 12216 passed, 0 skipped.
• pnpm --filter @objectstack/spec typecheck — exit 0; check:test-typecheck: OK — 54 file(s) / 262 error(s) / 146 pinned signature(s) (ledger unchanged; the new pin file compiles under tsconfig.test.json).
• The pin file with its two neighbours (contracts/automation-service.test.ts, api/automation-api.zod.test.ts) via exec vitest run --maxWorkers=2 — Test Files 3 passed (3) · Tests 61 passed (61).
• check:generated — exit 0 after --fix regenerated the one stale artifact; check:api-surface exit 0; the 15 spec-scoped gates dispatch-gates.mjs derived (api-surface, authorable-surface, browser-reachable-entries, docs, dual-source-exports, empty-state, entry-nameability, export-origins, exported-any, liveness, llms-txt, skill-refs, strictness-ledger, variant-docs, yaml-examples) — every one exit 0.

Root gates, derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack from the merge-base change set (the derivation named this checkout at a5b95ee):

• exit 0: adr-0087-registration, changeset-no-major, empty-changeset, ci-filter-parity, comment-mask-adoption, cross-package-test-inputs (both spellings), keyed-text-bounds, plugin-teardown-shape, shard-attestation, system-context-census, undeclared-dep-imports, docs-audit/check-affected-docs, docs-audit/check-drift-comment, pm/release-rehearsal-clone --self-test, changeset-gate-self-tests, dispatcher-error-vocabulary, engine-double-contract, logger-receiver-detach, merge-driver, objectql-double-limit, objectui-changeset, page-declaration-shape, pm-half-states, published-files, query-options-erasure, slot-lookup, spec-parsed-alias, test-source-alias, type-check-coverage, type-source-resolution, where-matcher, @objectstack/lint check:doc-formula-expressions (exit 0 once the closure was built), pnpm check:doc-authoring (14504 customer-facing string(s) across 710 spec sources clean), pnpm check:nul-bytes (scanned 7981 text file(s) … no raw ASCII control bytes).
• NOT MEASURED, never green: check-test-completeness (exit 3, PREREQUISITE NOT MET), check-dual-build-cjs-loads (exit 3: needs every package's dist), check:type-check-debt (exit 3: --re-measure needs the full ledgered closure), check-dev-prereqs (exit 1: asks for a full pnpm build), pm/check-half-states (timed out at 240 s on the GitHub network leg — a PM-side gate). CI owns these.

Consumers — filter direction is DOWNSTREAM of spec; their dependency closures were built first (turbo run build over the ^... of each, 55 tasks, exit 0):

• @objectstack/runtime — typecheck exit 0; the 6 test files that read AutomationResult (flow-dispatch-status, automation-trigger-route-status, automation-trigger-paused-run, action-activation-dispatch, endpoint-flow-dispatch-status, actions-flow-dispatch-status) — Test Files 5 passed (5) · Tests 81 passed (81) (one pattern matched no file on its own; narrowed to these files, declared).
• @objectstack/service-automation — has no typecheck script (types NOT MEASURED here; the package is ledgered by check:type-check-coverage, exit 0); the 9 test files that read AutomationResult — Test Files 9 passed (9) · Tests 239 passed (239) (narrowed, declared).
• @objectstack/plugin-approvals — typecheck exit 0 (check:test-typecheck: OK); whole test — Test Files 36 passed (36) · Tests 662 passed (662).
• @objectstack/client — typecheck exit 0 (check:test-typecheck: OK); whole test — Test Files 32 passed (32) · Tests 420 passed (420).
• @objectstack/verify — typecheck exit 0; automation-trigger-terminal-messages.test.ts — Test Files 1 passed (1) · Tests 4 passed (4).
• @objectstack/rest — typecheck exit 0 (check:test-typecheck: OK); @objectstack/cli — typecheck exit 0. Neither imports AutomationResult.
• @objectstack/dogfood — NOT MEASURED locally (its closure is the whole app); CI.

Reverse verification — from the committed state

Mutation leg: the contract union narrowed back to three members on disk (confirmed by anchor counts: four-member 0 / three-member 1; git diff --stat 1 file, 1 insertion, 1 deletion), then tsc --noEmit -p packages/spec/tsconfig.test.json: exit 2 with 266 error lines against the ledgered 262 on the restored tree — the 4 new ones name exactly the two pins: src/api/automation-api.zod.test.ts(52,54) (TriggerFlowDataMatchesContract, TS2344) and src/contracts/automation-result-status.pin.test.ts at lines 64 (TS2322, 'stranded' not assignable), 72 and 74 (TS2344). Direction: red, as predicted. Restore leg: git checkout HEAD -- FILE from a trap with an absolute path, proven by git diff HEAD --quiet exit 0 and git hash-object equal to the HEAD blob 85b3d15a….

Review tier

needs:contract-review — clause ②, contract tier, as the ruling says in as many words. Draft; no seat marks it ready or arms auto-merge.

🤖 Generated with Claude Code

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/client-sdk.mdx(via AutomationResult (symbol, a top-level interface))
• content/docs/automation/flows.mdx(via AutomationResult (symbol, a top-level interface))

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

• content/docs/releases/v17.mdx(via AutomationResult (symbol, a top-level interface))

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

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 128 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 d8024f050e1f457117f914d6960a204d1af03966 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from fcdd5f04c1fffa48b2df2a94e9348af681e8c85a — the merge of head 2c4bc2903701f758f1c6c5aa107a3c597888e9de into base d8024f050e1f457117f914d6960a204d1af03966, 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 fcdd5f04c1fffa48b2df2a94e9348af681e8c85a && git checkout fcdd5f04c1fffa48b2df2a94e9348af681e8c85a
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin d8024f050e1f457117f914d6960a204d1af03966 2c4bc2903701f758f1c6c5aa107a3c597888e9de && git checkout -B drift-repro d8024f050e1f457117f914d6960a204d1af03966 && git merge --no-ff 2c4bc2903701f758f1c6c5aa107a3c597888e9de
node scripts/docs-audit/affected-docs.mjs --json d8024f050e1f457117f914d6960a204d1af03966

⚠️ 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 d8024f050e1f457117f914d6960a204d1af03966 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Fixes#14384

Contract half of the #13937 shape-4 ruling (director seat, comment 5491060439; maintainer 2026-09-01 「其他同意」), quoted verbatim on the card and untranslated here:

2. 命名同批定(service-automation: a resume consumes the pause BEFORE running downstream nodes, so any node that throws leaves the run terminally unresumable — and the only inspector for it reports all clear #13909 交付项 3 在此收口):该条件成为运维要操作的持久状态 ⇒ 平台级名字落 packages/spec/src/contracts/automation-service.ts(AutomationResult.status 现为 'completed' | 'paused' | 'failed')⇒ 触 spec ⇒ 条款②契约复审档位适用。StrandedRunState 保持 plugin 局部报告标签不升格。

What changed — one contract increment

• packages/spec/src/contracts/automation-service.ts — AutomationResult.status is now 'completed' | 'paused' | 'failed' | 'stranded', with a JSDoc paragraph naming the condition: a resume CONSUMED the suspension, a downstream node threw, the run is recorded as failed and can be re-armed only by an explicit operator verb (never by resume, which answers RUN_NOT_FOUND for it, and never automatically). Distinct from 'failed' on purpose: that one says the run ran and was rejected; this one says a recorded continuation stopped mid-flight and an operator has something to repair. The JSDoc also states that plugin-approvals' StrandedRunState is NOT promoted.
• packages/spec/src/api/automation-api.zod.ts — the wire mirror TriggerFlowResponseSchema.data.status carries the same four (the existing TriggerFlowDataMatchesContract pin goes red if only one side moves; see the reverse verification). The .describe() prose names the condition without an issue id: check:doc-authoring refused the first spelling (customer-facing text must not carry #NNNN), so the card references moved to an adjacent line comment.
• packages/spec/src/contracts/automation-result-status.pin.test.ts (new) — pins, each on its own: (1) the union's exact membership at the type level (an Assert over an Eq identity, the automation-api.zod.test.ts form, compiled by check:test-typecheck, plus a satisfies list); (2) wire-to-contract parity at both levels (the Zod enum's .options read at runtime, and its inferred type bound to the contract's); (3) that the doc block above the declaration names the condition (source read); (4) a stranded envelope parses AND is preserved through the strip-mode object; (5) a literal outside the four is refused at data.status with invalid_value.
• content/docs/references/api/automation-api.mdx — regenerated by gen:docs (check:generated --fix; the one artifact it proved stale). api-surface/ is unchanged: the snapshot records that AutomationResult exists, not its members.
• .changeset/automation-result-stranded-status.md — @objectstack/spec: minor, additive (no BREAKING declaration, so no ADR-0087 marker is owed; check:adr-0087-registration exit 0).

Not in this PR, by the card: no engine change, no operator verb, no REST route, no ExecutionStatus widening. Those are #13937 (services half, stays open) and #13953.

The literal — what was measured before choosing

Vocabularies read (packages/spec/src, packages/services/service-automation, packages/plugins/plugin-approvals):

vocabulary	members	shape
AutomationResult.status (this union)	completedpausedfailed	single-word participles
ExecutionStatus (automation/execution.zod.ts, the run-row vocabulary listRuns filters on)	pendingrunningpausedcompletedfailedcancelledtimed_outretrying	single words; snake_case for two words
TaskStatus (system/worker.zod.ts)	pendingqueuedprocessingcompletedfailedcancelledtimeoutdead	dead = moved to the dead-letter queue
JobExecutionStatus (system/job.zod.ts)	runningsuccessfailedtimeoutdegraded
StrandedRunState (plugin-approvals, report-only)	missingfailed	classifies WHY a request's run is unrecoverable
prose lineage	"stranded" / "strands" / "stranding"	#13807, #13909, #13937, PR #13934; inspectStrandedRequests, StrandedApprovalRequest; 8 comment sites in engine.ts

Candidates:

• 'stranded' — chosen. The word the whole measured lineage already uses for exactly this condition (service-automation: a resume consumes the pause BEFORE running downstream nodes, so any node that throws leaves the run terminally unresumable — and the only inspector for it reports all clear #13909 itself: "There is no run state called stranded"); a single-word participle beside its three siblings; it names the operator-facing STATE, which survives a later shape-2 re-ordering, rather than the mechanism. It is not a promotion of StrandedRunState: that type's members are 'missing' | 'failed', it stays plugin-local and report-only, and the JSDoc says so.
• 'dead' — the one in-spec precedent (TaskStatus), but there it means retries exhausted and dead-lettered; here nothing was retried, and "dead" reads as final where the ruling's whole point is re-armable.
• 'failed_resume' / 'resume_failed' — snake_case is the house shape for two words (timed_out), but both name the mechanism (the consumption ordering that [Decision] Workflow resume ordering: a thrown node today leaves the run terminally unresumable — which of three shapes, given that the current order buys exactly-once across a crash? #13937 may still change under shape 2) rather than the state an operator acts on.
• 'unresumable' — false the moment the re-arm verb exists.
• 'suspended' — the spec uses it for admin-suspended tenant / license / environment, and it collides with "suspension", which is the PAUSE.
• 'stalled' / 'stuck' / 'halted' / 'incident' — zero uses in the three trees; incident is a noun (Camunda's shape), not a participle.

Producer and consumer measurements

• AutomationResult.status is a TypeScript interface member, not Zod — verified. Its one Zod mirror in packages/spec/src is TriggerFlowResponseSchema.data.status; both updated, parity pinned.
• Producer today: AutomationEngine.resumeInternal's catch arm records the run ROW failed and returns { success: false, error, durationMs, errorMessage, summary } — no status at all on the resumed-failure envelope (only execute()'s dispatched-and-rejected exit stamps status: 'failed'). So stamping 'stranded' on the result is the services half's, and whether the run ROW (ExecutionStatus) ever carries the word is that half's to measure; this PR does not widen ExecutionStatus.
• Exhaustive switches over AutomationResult.status in packages/{runtime,services,plugins,rest,cli,client}: zero. The only case 'completed' | 'paused' | 'failed' outside spec is plugin-approvals' classifyStrandedRunState, which switches over the run ROW's status string with a deliberately silent default, not over this union. Narrow re-declarations of the three-member union outside spec: zero in code (two in comments, engine.ts:4182 and approval-service.ts:315).
• Sibling repo objectui: app-shell/src/utils/flowResponse.ts:108 types status?: 'completed' | 'paused' | 'failed' | string and branches on success === false — tolerant of the new literal; nothing to change there for this half.
• No consumer needed even a type-only accommodation.

Verification — all readings on head 2c4bc29, exit codes captured before any pipe

@objectstack/spec:

• pnpm --filter @objectstack/spec build — exit 0 (check-dts-emitted: 34/34 declared declaration file(s) present).
• pnpm --filter @objectstack/spec test (whole suite) — Test Files 453 passed | 1 skipped (454) · Tests 12214 passed | 1 skipped (12215) on the committed head. The one skip is scripts/root-entry-type-nameability.pin.test.ts: its inspectDistFreshness predicate saw dist older than src because the reverse verification below touched the contract file's mtime after the build (content byte-identical), and that pin skips by default on a stale dist. After rebuilding the dist that file re-ran on the same head: Test Files 1 passed (1) · Tests 2 passed (2); check:api-surface on the rebuilt dist: exit 0. The earlier full run on the pre-.describe()-edit tree with a fresh dist was 454 passed · 12216 passed, 0 skipped.
• pnpm --filter @objectstack/spec typecheck — exit 0; check:test-typecheck: OK — 54 file(s) / 262 error(s) / 146 pinned signature(s) (ledger unchanged; the new pin file compiles under tsconfig.test.json).
• The pin file with its two neighbours (contracts/automation-service.test.ts, api/automation-api.zod.test.ts) via exec vitest run --maxWorkers=2 — Test Files 3 passed (3) · Tests 61 passed (61).
• check:generated — exit 0 after --fix regenerated the one stale artifact; check:api-surface exit 0; the 15 spec-scoped gates dispatch-gates.mjs derived (api-surface, authorable-surface, browser-reachable-entries, docs, dual-source-exports, empty-state, entry-nameability, export-origins, exported-any, liveness, llms-txt, skill-refs, strictness-ledger, variant-docs, yaml-examples) — every one exit 0.

Root gates, derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack from the merge-base change set (the derivation named this checkout at a5b95ee):

• exit 0: adr-0087-registration, changeset-no-major, empty-changeset, ci-filter-parity, comment-mask-adoption, cross-package-test-inputs (both spellings), keyed-text-bounds, plugin-teardown-shape, shard-attestation, system-context-census, undeclared-dep-imports, docs-audit/check-affected-docs, docs-audit/check-drift-comment, pm/release-rehearsal-clone --self-test, changeset-gate-self-tests, dispatcher-error-vocabulary, engine-double-contract, logger-receiver-detach, merge-driver, objectql-double-limit, objectui-changeset, page-declaration-shape, pm-half-states, published-files, query-options-erasure, slot-lookup, spec-parsed-alias, test-source-alias, type-check-coverage, type-source-resolution, where-matcher, @objectstack/lint check:doc-formula-expressions (exit 0 once the closure was built), pnpm check:doc-authoring (14504 customer-facing string(s) across 710 spec sources clean), pnpm check:nul-bytes (scanned 7981 text file(s) … no raw ASCII control bytes).
• NOT MEASURED, never green: check-test-completeness (exit 3, PREREQUISITE NOT MET), check-dual-build-cjs-loads (exit 3: needs every package's dist), check:type-check-debt (exit 3: --re-measure needs the full ledgered closure), check-dev-prereqs (exit 1: asks for a full pnpm build), pm/check-half-states (timed out at 240 s on the GitHub network leg — a PM-side gate). CI owns these.

Consumers — filter direction is DOWNSTREAM of spec; their dependency closures were built first (turbo run build over the ^... of each, 55 tasks, exit 0):

• @objectstack/runtime — typecheck exit 0; the 6 test files that read AutomationResult (flow-dispatch-status, automation-trigger-route-status, automation-trigger-paused-run, action-activation-dispatch, endpoint-flow-dispatch-status, actions-flow-dispatch-status) — Test Files 5 passed (5) · Tests 81 passed (81) (one pattern matched no file on its own; narrowed to these files, declared).
• @objectstack/service-automation — has no typecheck script (types NOT MEASURED here; the package is ledgered by check:type-check-coverage, exit 0); the 9 test files that read AutomationResult — Test Files 9 passed (9) · Tests 239 passed (239) (narrowed, declared).
• @objectstack/plugin-approvals — typecheck exit 0 (check:test-typecheck: OK); whole test — Test Files 36 passed (36) · Tests 662 passed (662).
• @objectstack/client — typecheck exit 0 (check:test-typecheck: OK); whole test — Test Files 32 passed (32) · Tests 420 passed (420).
• @objectstack/verify — typecheck exit 0; automation-trigger-terminal-messages.test.ts — Test Files 1 passed (1) · Tests 4 passed (4).
• @objectstack/rest — typecheck exit 0 (check:test-typecheck: OK); @objectstack/cli — typecheck exit 0. Neither imports AutomationResult.
• @objectstack/dogfood — NOT MEASURED locally (its closure is the whole app); CI.

Reverse verification — from the committed state

Mutation leg: the contract union narrowed back to three members on disk (confirmed by anchor counts: four-member 0 / three-member 1; git diff --stat 1 file, 1 insertion, 1 deletion), then tsc --noEmit -p packages/spec/tsconfig.test.json: exit 2 with 266 error lines against the ledgered 262 on the restored tree — the 4 new ones name exactly the two pins: src/api/automation-api.zod.test.ts(52,54) (TriggerFlowDataMatchesContract, TS2344) and src/contracts/automation-result-status.pin.test.ts at lines 64 (TS2322, 'stranded' not assignable), 72 and 74 (TS2344). Direction: red, as predicted. Restore leg: git checkout HEAD -- FILE from a trap with an absolute path, proven by git diff HEAD --quiet exit 0 and git hash-object equal to the HEAD blob 85b3d15a….

Review tier

needs:contract-review — clause ②, contract tier, as the ruling says in as many words. Draft; no seat marks it ready or arms auto-merge.

🤖 Generated with Claude Code

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/client-sdk.mdx(via AutomationResult (symbol, a top-level interface))
• content/docs/automation/flows.mdx(via AutomationResult (symbol, a top-level interface))

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

• content/docs/releases/v17.mdx(via AutomationResult (symbol, a top-level interface))

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

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 128 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 d8024f050e1f457117f914d6960a204d1af03966 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from fcdd5f04c1fffa48b2df2a94e9348af681e8c85a — the merge of head 2c4bc2903701f758f1c6c5aa107a3c597888e9de into base d8024f050e1f457117f914d6960a204d1af03966, 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 fcdd5f04c1fffa48b2df2a94e9348af681e8c85a && git checkout fcdd5f04c1fffa48b2df2a94e9348af681e8c85a
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin d8024f050e1f457117f914d6960a204d1af03966 2c4bc2903701f758f1c6c5aa107a3c597888e9de && git checkout -B drift-repro d8024f050e1f457117f914d6960a204d1af03966 && git merge --no-ff 2c4bc2903701f758f1c6c5aa107a3c597888e9de
node scripts/docs-audit/affected-docs.mjs --json d8024f050e1f457117f914d6960a204d1af03966

⚠️ 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 d8024f050e1f457117f914d6960a204d1af03966 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Fixes#14384

Contract half of the #13937 shape-4 ruling (director seat, comment 5491060439; maintainer 2026-09-01 「其他同意」), quoted verbatim on the card and untranslated here:

2. 命名同批定(service-automation: a resume consumes the pause BEFORE running downstream nodes, so any node that throws leaves the run terminally unresumable — and the only inspector for it reports all clear #13909 交付项 3 在此收口):该条件成为运维要操作的持久状态 ⇒ 平台级名字落 packages/spec/src/contracts/automation-service.ts(AutomationResult.status 现为 'completed' | 'paused' | 'failed')⇒ 触 spec ⇒ 条款②契约复审档位适用。StrandedRunState 保持 plugin 局部报告标签不升格。

What changed — one contract increment

• packages/spec/src/contracts/automation-service.ts — AutomationResult.status is now 'completed' | 'paused' | 'failed' | 'stranded', with a JSDoc paragraph naming the condition: a resume CONSUMED the suspension, a downstream node threw, the run is recorded as failed and can be re-armed only by an explicit operator verb (never by resume, which answers RUN_NOT_FOUND for it, and never automatically). Distinct from 'failed' on purpose: that one says the run ran and was rejected; this one says a recorded continuation stopped mid-flight and an operator has something to repair. The JSDoc also states that plugin-approvals' StrandedRunState is NOT promoted.
• packages/spec/src/api/automation-api.zod.ts — the wire mirror TriggerFlowResponseSchema.data.status carries the same four (the existing TriggerFlowDataMatchesContract pin goes red if only one side moves; see the reverse verification). The .describe() prose names the condition without an issue id: check:doc-authoring refused the first spelling (customer-facing text must not carry #NNNN), so the card references moved to an adjacent line comment.
• packages/spec/src/contracts/automation-result-status.pin.test.ts (new) — pins, each on its own: (1) the union's exact membership at the type level (an Assert over an Eq identity, the automation-api.zod.test.ts form, compiled by check:test-typecheck, plus a satisfies list); (2) wire-to-contract parity at both levels (the Zod enum's .options read at runtime, and its inferred type bound to the contract's); (3) that the doc block above the declaration names the condition (source read); (4) a stranded envelope parses AND is preserved through the strip-mode object; (5) a literal outside the four is refused at data.status with invalid_value.
• content/docs/references/api/automation-api.mdx — regenerated by gen:docs (check:generated --fix; the one artifact it proved stale). api-surface/ is unchanged: the snapshot records that AutomationResult exists, not its members.
• .changeset/automation-result-stranded-status.md — @objectstack/spec: minor, additive (no BREAKING declaration, so no ADR-0087 marker is owed; check:adr-0087-registration exit 0).

Not in this PR, by the card: no engine change, no operator verb, no REST route, no ExecutionStatus widening. Those are #13937 (services half, stays open) and #13953.

The literal — what was measured before choosing

Vocabularies read (packages/spec/src, packages/services/service-automation, packages/plugins/plugin-approvals):

vocabulary	members	shape
AutomationResult.status (this union)	completedpausedfailed	single-word participles
ExecutionStatus (automation/execution.zod.ts, the run-row vocabulary listRuns filters on)	pendingrunningpausedcompletedfailedcancelledtimed_outretrying	single words; snake_case for two words
TaskStatus (system/worker.zod.ts)	pendingqueuedprocessingcompletedfailedcancelledtimeoutdead	dead = moved to the dead-letter queue
JobExecutionStatus (system/job.zod.ts)	runningsuccessfailedtimeoutdegraded
StrandedRunState (plugin-approvals, report-only)	missingfailed	classifies WHY a request's run is unrecoverable
prose lineage	"stranded" / "strands" / "stranding"	#13807, #13909, #13937, PR #13934; inspectStrandedRequests, StrandedApprovalRequest; 8 comment sites in engine.ts

Candidates:

• 'stranded' — chosen. The word the whole measured lineage already uses for exactly this condition (service-automation: a resume consumes the pause BEFORE running downstream nodes, so any node that throws leaves the run terminally unresumable — and the only inspector for it reports all clear #13909 itself: "There is no run state called stranded"); a single-word participle beside its three siblings; it names the operator-facing STATE, which survives a later shape-2 re-ordering, rather than the mechanism. It is not a promotion of StrandedRunState: that type's members are 'missing' | 'failed', it stays plugin-local and report-only, and the JSDoc says so.
• 'dead' — the one in-spec precedent (TaskStatus), but there it means retries exhausted and dead-lettered; here nothing was retried, and "dead" reads as final where the ruling's whole point is re-armable.
• 'failed_resume' / 'resume_failed' — snake_case is the house shape for two words (timed_out), but both name the mechanism (the consumption ordering that [Decision] Workflow resume ordering: a thrown node today leaves the run terminally unresumable — which of three shapes, given that the current order buys exactly-once across a crash? #13937 may still change under shape 2) rather than the state an operator acts on.
• 'unresumable' — false the moment the re-arm verb exists.
• 'suspended' — the spec uses it for admin-suspended tenant / license / environment, and it collides with "suspension", which is the PAUSE.
• 'stalled' / 'stuck' / 'halted' / 'incident' — zero uses in the three trees; incident is a noun (Camunda's shape), not a participle.

Producer and consumer measurements

• AutomationResult.status is a TypeScript interface member, not Zod — verified. Its one Zod mirror in packages/spec/src is TriggerFlowResponseSchema.data.status; both updated, parity pinned.
• Producer today: AutomationEngine.resumeInternal's catch arm records the run ROW failed and returns { success: false, error, durationMs, errorMessage, summary } — no status at all on the resumed-failure envelope (only execute()'s dispatched-and-rejected exit stamps status: 'failed'). So stamping 'stranded' on the result is the services half's, and whether the run ROW (ExecutionStatus) ever carries the word is that half's to measure; this PR does not widen ExecutionStatus.
• Exhaustive switches over AutomationResult.status in packages/{runtime,services,plugins,rest,cli,client}: zero. The only case 'completed' | 'paused' | 'failed' outside spec is plugin-approvals' classifyStrandedRunState, which switches over the run ROW's status string with a deliberately silent default, not over this union. Narrow re-declarations of the three-member union outside spec: zero in code (two in comments, engine.ts:4182 and approval-service.ts:315).
• Sibling repo objectui: app-shell/src/utils/flowResponse.ts:108 types status?: 'completed' | 'paused' | 'failed' | string and branches on success === false — tolerant of the new literal; nothing to change there for this half.
• No consumer needed even a type-only accommodation.

Verification — all readings on head 2c4bc29, exit codes captured before any pipe

@objectstack/spec:

• pnpm --filter @objectstack/spec build — exit 0 (check-dts-emitted: 34/34 declared declaration file(s) present).
• pnpm --filter @objectstack/spec test (whole suite) — Test Files 453 passed | 1 skipped (454) · Tests 12214 passed | 1 skipped (12215) on the committed head. The one skip is scripts/root-entry-type-nameability.pin.test.ts: its inspectDistFreshness predicate saw dist older than src because the reverse verification below touched the contract file's mtime after the build (content byte-identical), and that pin skips by default on a stale dist. After rebuilding the dist that file re-ran on the same head: Test Files 1 passed (1) · Tests 2 passed (2); check:api-surface on the rebuilt dist: exit 0. The earlier full run on the pre-.describe()-edit tree with a fresh dist was 454 passed · 12216 passed, 0 skipped.
• pnpm --filter @objectstack/spec typecheck — exit 0; check:test-typecheck: OK — 54 file(s) / 262 error(s) / 146 pinned signature(s) (ledger unchanged; the new pin file compiles under tsconfig.test.json).
• The pin file with its two neighbours (contracts/automation-service.test.ts, api/automation-api.zod.test.ts) via exec vitest run --maxWorkers=2 — Test Files 3 passed (3) · Tests 61 passed (61).
• check:generated — exit 0 after --fix regenerated the one stale artifact; check:api-surface exit 0; the 15 spec-scoped gates dispatch-gates.mjs derived (api-surface, authorable-surface, browser-reachable-entries, docs, dual-source-exports, empty-state, entry-nameability, export-origins, exported-any, liveness, llms-txt, skill-refs, strictness-ledger, variant-docs, yaml-examples) — every one exit 0.

Root gates, derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack from the merge-base change set (the derivation named this checkout at a5b95ee):

• exit 0: adr-0087-registration, changeset-no-major, empty-changeset, ci-filter-parity, comment-mask-adoption, cross-package-test-inputs (both spellings), keyed-text-bounds, plugin-teardown-shape, shard-attestation, system-context-census, undeclared-dep-imports, docs-audit/check-affected-docs, docs-audit/check-drift-comment, pm/release-rehearsal-clone --self-test, changeset-gate-self-tests, dispatcher-error-vocabulary, engine-double-contract, logger-receiver-detach, merge-driver, objectql-double-limit, objectui-changeset, page-declaration-shape, pm-half-states, published-files, query-options-erasure, slot-lookup, spec-parsed-alias, test-source-alias, type-check-coverage, type-source-resolution, where-matcher, @objectstack/lint check:doc-formula-expressions (exit 0 once the closure was built), pnpm check:doc-authoring (14504 customer-facing string(s) across 710 spec sources clean), pnpm check:nul-bytes (scanned 7981 text file(s) … no raw ASCII control bytes).
• NOT MEASURED, never green: check-test-completeness (exit 3, PREREQUISITE NOT MET), check-dual-build-cjs-loads (exit 3: needs every package's dist), check:type-check-debt (exit 3: --re-measure needs the full ledgered closure), check-dev-prereqs (exit 1: asks for a full pnpm build), pm/check-half-states (timed out at 240 s on the GitHub network leg — a PM-side gate). CI owns these.

Consumers — filter direction is DOWNSTREAM of spec; their dependency closures were built first (turbo run build over the ^... of each, 55 tasks, exit 0):

• @objectstack/runtime — typecheck exit 0; the 6 test files that read AutomationResult (flow-dispatch-status, automation-trigger-route-status, automation-trigger-paused-run, action-activation-dispatch, endpoint-flow-dispatch-status, actions-flow-dispatch-status) — Test Files 5 passed (5) · Tests 81 passed (81) (one pattern matched no file on its own; narrowed to these files, declared).
• @objectstack/service-automation — has no typecheck script (types NOT MEASURED here; the package is ledgered by check:type-check-coverage, exit 0); the 9 test files that read AutomationResult — Test Files 9 passed (9) · Tests 239 passed (239) (narrowed, declared).
• @objectstack/plugin-approvals — typecheck exit 0 (check:test-typecheck: OK); whole test — Test Files 36 passed (36) · Tests 662 passed (662).
• @objectstack/client — typecheck exit 0 (check:test-typecheck: OK); whole test — Test Files 32 passed (32) · Tests 420 passed (420).
• @objectstack/verify — typecheck exit 0; automation-trigger-terminal-messages.test.ts — Test Files 1 passed (1) · Tests 4 passed (4).
• @objectstack/rest — typecheck exit 0 (check:test-typecheck: OK); @objectstack/cli — typecheck exit 0. Neither imports AutomationResult.
• @objectstack/dogfood — NOT MEASURED locally (its closure is the whole app); CI.

Reverse verification — from the committed state

Mutation leg: the contract union narrowed back to three members on disk (confirmed by anchor counts: four-member 0 / three-member 1; git diff --stat 1 file, 1 insertion, 1 deletion), then tsc --noEmit -p packages/spec/tsconfig.test.json: exit 2 with 266 error lines against the ledgered 262 on the restored tree — the 4 new ones name exactly the two pins: src/api/automation-api.zod.test.ts(52,54) (TriggerFlowDataMatchesContract, TS2344) and src/contracts/automation-result-status.pin.test.ts at lines 64 (TS2322, 'stranded' not assignable), 72 and 74 (TS2344). Direction: red, as predicted. Restore leg: git checkout HEAD -- FILE from a trap with an absolute path, proven by git diff HEAD --quiet exit 0 and git hash-object equal to the HEAD blob 85b3d15a….

Review tier

needs:contract-review — clause ②, contract tier, as the ruling says in as many words. Draft; no seat marks it ready or arms auto-merge.

🤖 Generated with Claude Code

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/client-sdk.mdx(via AutomationResult (symbol, a top-level interface))
• content/docs/automation/flows.mdx(via AutomationResult (symbol, a top-level interface))

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

• content/docs/releases/v17.mdx(via AutomationResult (symbol, a top-level interface))

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

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 128 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 d8024f050e1f457117f914d6960a204d1af03966 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from fcdd5f04c1fffa48b2df2a94e9348af681e8c85a — the merge of head 2c4bc2903701f758f1c6c5aa107a3c597888e9de into base d8024f050e1f457117f914d6960a204d1af03966, 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 fcdd5f04c1fffa48b2df2a94e9348af681e8c85a && git checkout fcdd5f04c1fffa48b2df2a94e9348af681e8c85a
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin d8024f050e1f457117f914d6960a204d1af03966 2c4bc2903701f758f1c6c5aa107a3c597888e9de && git checkout -B drift-repro d8024f050e1f457117f914d6960a204d1af03966 && git merge --no-ff 2c4bc2903701f758f1c6c5aa107a3c597888e9de
node scripts/docs-audit/affected-docs.mjs --json d8024f050e1f457117f914d6960a204d1af03966

⚠️ 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 d8024f050e1f457117f914d6960a204d1af03966 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Fixes#14384

Contract half of the #13937 shape-4 ruling (director seat, comment 5491060439; maintainer 2026-09-01 「其他同意」), quoted verbatim on the card and untranslated here:

2. 命名同批定(service-automation: a resume consumes the pause BEFORE running downstream nodes, so any node that throws leaves the run terminally unresumable — and the only inspector for it reports all clear #13909 交付项 3 在此收口):该条件成为运维要操作的持久状态 ⇒ 平台级名字落 packages/spec/src/contracts/automation-service.ts(AutomationResult.status 现为 'completed' | 'paused' | 'failed')⇒ 触 spec ⇒ 条款②契约复审档位适用。StrandedRunState 保持 plugin 局部报告标签不升格。

What changed — one contract increment

• packages/spec/src/contracts/automation-service.ts — AutomationResult.status is now 'completed' | 'paused' | 'failed' | 'stranded', with a JSDoc paragraph naming the condition: a resume CONSUMED the suspension, a downstream node threw, the run is recorded as failed and can be re-armed only by an explicit operator verb (never by resume, which answers RUN_NOT_FOUND for it, and never automatically). Distinct from 'failed' on purpose: that one says the run ran and was rejected; this one says a recorded continuation stopped mid-flight and an operator has something to repair. The JSDoc also states that plugin-approvals' StrandedRunState is NOT promoted.
• packages/spec/src/api/automation-api.zod.ts — the wire mirror TriggerFlowResponseSchema.data.status carries the same four (the existing TriggerFlowDataMatchesContract pin goes red if only one side moves; see the reverse verification). The .describe() prose names the condition without an issue id: check:doc-authoring refused the first spelling (customer-facing text must not carry #NNNN), so the card references moved to an adjacent line comment.
• packages/spec/src/contracts/automation-result-status.pin.test.ts (new) — pins, each on its own: (1) the union's exact membership at the type level (an Assert over an Eq identity, the automation-api.zod.test.ts form, compiled by check:test-typecheck, plus a satisfies list); (2) wire-to-contract parity at both levels (the Zod enum's .options read at runtime, and its inferred type bound to the contract's); (3) that the doc block above the declaration names the condition (source read); (4) a stranded envelope parses AND is preserved through the strip-mode object; (5) a literal outside the four is refused at data.status with invalid_value.
• content/docs/references/api/automation-api.mdx — regenerated by gen:docs (check:generated --fix; the one artifact it proved stale). api-surface/ is unchanged: the snapshot records that AutomationResult exists, not its members.
• .changeset/automation-result-stranded-status.md — @objectstack/spec: minor, additive (no BREAKING declaration, so no ADR-0087 marker is owed; check:adr-0087-registration exit 0).

Not in this PR, by the card: no engine change, no operator verb, no REST route, no ExecutionStatus widening. Those are #13937 (services half, stays open) and #13953.

The literal — what was measured before choosing

Vocabularies read (packages/spec/src, packages/services/service-automation, packages/plugins/plugin-approvals):

vocabulary	members	shape
AutomationResult.status (this union)	completedpausedfailed	single-word participles
ExecutionStatus (automation/execution.zod.ts, the run-row vocabulary listRuns filters on)	pendingrunningpausedcompletedfailedcancelledtimed_outretrying	single words; snake_case for two words
TaskStatus (system/worker.zod.ts)	pendingqueuedprocessingcompletedfailedcancelledtimeoutdead	dead = moved to the dead-letter queue
JobExecutionStatus (system/job.zod.ts)	runningsuccessfailedtimeoutdegraded
StrandedRunState (plugin-approvals, report-only)	missingfailed	classifies WHY a request's run is unrecoverable
prose lineage	"stranded" / "strands" / "stranding"	#13807, #13909, #13937, PR #13934; inspectStrandedRequests, StrandedApprovalRequest; 8 comment sites in engine.ts

Candidates:

• 'stranded' — chosen. The word the whole measured lineage already uses for exactly this condition (service-automation: a resume consumes the pause BEFORE running downstream nodes, so any node that throws leaves the run terminally unresumable — and the only inspector for it reports all clear #13909 itself: "There is no run state called stranded"); a single-word participle beside its three siblings; it names the operator-facing STATE, which survives a later shape-2 re-ordering, rather than the mechanism. It is not a promotion of StrandedRunState: that type's members are 'missing' | 'failed', it stays plugin-local and report-only, and the JSDoc says so.
• 'dead' — the one in-spec precedent (TaskStatus), but there it means retries exhausted and dead-lettered; here nothing was retried, and "dead" reads as final where the ruling's whole point is re-armable.
• 'failed_resume' / 'resume_failed' — snake_case is the house shape for two words (timed_out), but both name the mechanism (the consumption ordering that [Decision] Workflow resume ordering: a thrown node today leaves the run terminally unresumable — which of three shapes, given that the current order buys exactly-once across a crash? #13937 may still change under shape 2) rather than the state an operator acts on.
• 'unresumable' — false the moment the re-arm verb exists.
• 'suspended' — the spec uses it for admin-suspended tenant / license / environment, and it collides with "suspension", which is the PAUSE.
• 'stalled' / 'stuck' / 'halted' / 'incident' — zero uses in the three trees; incident is a noun (Camunda's shape), not a participle.

Producer and consumer measurements

• AutomationResult.status is a TypeScript interface member, not Zod — verified. Its one Zod mirror in packages/spec/src is TriggerFlowResponseSchema.data.status; both updated, parity pinned.
• Producer today: AutomationEngine.resumeInternal's catch arm records the run ROW failed and returns { success: false, error, durationMs, errorMessage, summary } — no status at all on the resumed-failure envelope (only execute()'s dispatched-and-rejected exit stamps status: 'failed'). So stamping 'stranded' on the result is the services half's, and whether the run ROW (ExecutionStatus) ever carries the word is that half's to measure; this PR does not widen ExecutionStatus.
• Exhaustive switches over AutomationResult.status in packages/{runtime,services,plugins,rest,cli,client}: zero. The only case 'completed' | 'paused' | 'failed' outside spec is plugin-approvals' classifyStrandedRunState, which switches over the run ROW's status string with a deliberately silent default, not over this union. Narrow re-declarations of the three-member union outside spec: zero in code (two in comments, engine.ts:4182 and approval-service.ts:315).
• Sibling repo objectui: app-shell/src/utils/flowResponse.ts:108 types status?: 'completed' | 'paused' | 'failed' | string and branches on success === false — tolerant of the new literal; nothing to change there for this half.
• No consumer needed even a type-only accommodation.

Verification — all readings on head 2c4bc29, exit codes captured before any pipe

@objectstack/spec:

• pnpm --filter @objectstack/spec build — exit 0 (check-dts-emitted: 34/34 declared declaration file(s) present).
• pnpm --filter @objectstack/spec test (whole suite) — Test Files 453 passed | 1 skipped (454) · Tests 12214 passed | 1 skipped (12215) on the committed head. The one skip is scripts/root-entry-type-nameability.pin.test.ts: its inspectDistFreshness predicate saw dist older than src because the reverse verification below touched the contract file's mtime after the build (content byte-identical), and that pin skips by default on a stale dist. After rebuilding the dist that file re-ran on the same head: Test Files 1 passed (1) · Tests 2 passed (2); check:api-surface on the rebuilt dist: exit 0. The earlier full run on the pre-.describe()-edit tree with a fresh dist was 454 passed · 12216 passed, 0 skipped.
• pnpm --filter @objectstack/spec typecheck — exit 0; check:test-typecheck: OK — 54 file(s) / 262 error(s) / 146 pinned signature(s) (ledger unchanged; the new pin file compiles under tsconfig.test.json).
• The pin file with its two neighbours (contracts/automation-service.test.ts, api/automation-api.zod.test.ts) via exec vitest run --maxWorkers=2 — Test Files 3 passed (3) · Tests 61 passed (61).
• check:generated — exit 0 after --fix regenerated the one stale artifact; check:api-surface exit 0; the 15 spec-scoped gates dispatch-gates.mjs derived (api-surface, authorable-surface, browser-reachable-entries, docs, dual-source-exports, empty-state, entry-nameability, export-origins, exported-any, liveness, llms-txt, skill-refs, strictness-ledger, variant-docs, yaml-examples) — every one exit 0.

Root gates, derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack from the merge-base change set (the derivation named this checkout at a5b95ee):

• exit 0: adr-0087-registration, changeset-no-major, empty-changeset, ci-filter-parity, comment-mask-adoption, cross-package-test-inputs (both spellings), keyed-text-bounds, plugin-teardown-shape, shard-attestation, system-context-census, undeclared-dep-imports, docs-audit/check-affected-docs, docs-audit/check-drift-comment, pm/release-rehearsal-clone --self-test, changeset-gate-self-tests, dispatcher-error-vocabulary, engine-double-contract, logger-receiver-detach, merge-driver, objectql-double-limit, objectui-changeset, page-declaration-shape, pm-half-states, published-files, query-options-erasure, slot-lookup, spec-parsed-alias, test-source-alias, type-check-coverage, type-source-resolution, where-matcher, @objectstack/lint check:doc-formula-expressions (exit 0 once the closure was built), pnpm check:doc-authoring (14504 customer-facing string(s) across 710 spec sources clean), pnpm check:nul-bytes (scanned 7981 text file(s) … no raw ASCII control bytes).
• NOT MEASURED, never green: check-test-completeness (exit 3, PREREQUISITE NOT MET), check-dual-build-cjs-loads (exit 3: needs every package's dist), check:type-check-debt (exit 3: --re-measure needs the full ledgered closure), check-dev-prereqs (exit 1: asks for a full pnpm build), pm/check-half-states (timed out at 240 s on the GitHub network leg — a PM-side gate). CI owns these.

Consumers — filter direction is DOWNSTREAM of spec; their dependency closures were built first (turbo run build over the ^... of each, 55 tasks, exit 0):

• @objectstack/runtime — typecheck exit 0; the 6 test files that read AutomationResult (flow-dispatch-status, automation-trigger-route-status, automation-trigger-paused-run, action-activation-dispatch, endpoint-flow-dispatch-status, actions-flow-dispatch-status) — Test Files 5 passed (5) · Tests 81 passed (81) (one pattern matched no file on its own; narrowed to these files, declared).
• @objectstack/service-automation — has no typecheck script (types NOT MEASURED here; the package is ledgered by check:type-check-coverage, exit 0); the 9 test files that read AutomationResult — Test Files 9 passed (9) · Tests 239 passed (239) (narrowed, declared).
• @objectstack/plugin-approvals — typecheck exit 0 (check:test-typecheck: OK); whole test — Test Files 36 passed (36) · Tests 662 passed (662).
• @objectstack/client — typecheck exit 0 (check:test-typecheck: OK); whole test — Test Files 32 passed (32) · Tests 420 passed (420).
• @objectstack/verify — typecheck exit 0; automation-trigger-terminal-messages.test.ts — Test Files 1 passed (1) · Tests 4 passed (4).
• @objectstack/rest — typecheck exit 0 (check:test-typecheck: OK); @objectstack/cli — typecheck exit 0. Neither imports AutomationResult.
• @objectstack/dogfood — NOT MEASURED locally (its closure is the whole app); CI.

Reverse verification — from the committed state

Mutation leg: the contract union narrowed back to three members on disk (confirmed by anchor counts: four-member 0 / three-member 1; git diff --stat 1 file, 1 insertion, 1 deletion), then tsc --noEmit -p packages/spec/tsconfig.test.json: exit 2 with 266 error lines against the ledgered 262 on the restored tree — the 4 new ones name exactly the two pins: src/api/automation-api.zod.test.ts(52,54) (TriggerFlowDataMatchesContract, TS2344) and src/contracts/automation-result-status.pin.test.ts at lines 64 (TS2322, 'stranded' not assignable), 72 and 74 (TS2344). Direction: red, as predicted. Restore leg: git checkout HEAD -- FILE from a trap with an absolute path, proven by git diff HEAD --quiet exit 0 and git hash-object equal to the HEAD blob 85b3d15a….

Review tier

needs:contract-review — clause ②, contract tier, as the ruling says in as many words. Draft; no seat marks it ready or arms auto-merge.

🤖 Generated with Claude Code

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/client-sdk.mdx(via AutomationResult (symbol, a top-level interface))
• content/docs/automation/flows.mdx(via AutomationResult (symbol, a top-level interface))

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

• content/docs/releases/v17.mdx(via AutomationResult (symbol, a top-level interface))

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

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 128 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 d8024f050e1f457117f914d6960a204d1af03966 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from fcdd5f04c1fffa48b2df2a94e9348af681e8c85a — the merge of head 2c4bc2903701f758f1c6c5aa107a3c597888e9de into base d8024f050e1f457117f914d6960a204d1af03966, 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 fcdd5f04c1fffa48b2df2a94e9348af681e8c85a && git checkout fcdd5f04c1fffa48b2df2a94e9348af681e8c85a
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin d8024f050e1f457117f914d6960a204d1af03966 2c4bc2903701f758f1c6c5aa107a3c597888e9de && git checkout -B drift-repro d8024f050e1f457117f914d6960a204d1af03966 && git merge --no-ff 2c4bc2903701f758f1c6c5aa107a3c597888e9de
node scripts/docs-audit/affected-docs.mjs --json d8024f050e1f457117f914d6960a204d1af03966

⚠️ 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 d8024f050e1f457117f914d6960a204d1af03966 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Fixes#14384

Contract half of the #13937 shape-4 ruling (director seat, comment 5491060439; maintainer 2026-09-01 「其他同意」), quoted verbatim on the card and untranslated here:

2. 命名同批定(service-automation: a resume consumes the pause BEFORE running downstream nodes, so any node that throws leaves the run terminally unresumable — and the only inspector for it reports all clear #13909 交付项 3 在此收口):该条件成为运维要操作的持久状态 ⇒ 平台级名字落 packages/spec/src/contracts/automation-service.ts(AutomationResult.status 现为 'completed' | 'paused' | 'failed')⇒ 触 spec ⇒ 条款②契约复审档位适用。StrandedRunState 保持 plugin 局部报告标签不升格。

What changed — one contract increment

• packages/spec/src/contracts/automation-service.ts — AutomationResult.status is now 'completed' | 'paused' | 'failed' | 'stranded', with a JSDoc paragraph naming the condition: a resume CONSUMED the suspension, a downstream node threw, the run is recorded as failed and can be re-armed only by an explicit operator verb (never by resume, which answers RUN_NOT_FOUND for it, and never automatically). Distinct from 'failed' on purpose: that one says the run ran and was rejected; this one says a recorded continuation stopped mid-flight and an operator has something to repair. The JSDoc also states that plugin-approvals' StrandedRunState is NOT promoted.
• packages/spec/src/api/automation-api.zod.ts — the wire mirror TriggerFlowResponseSchema.data.status carries the same four (the existing TriggerFlowDataMatchesContract pin goes red if only one side moves; see the reverse verification). The .describe() prose names the condition without an issue id: check:doc-authoring refused the first spelling (customer-facing text must not carry #NNNN), so the card references moved to an adjacent line comment.
• packages/spec/src/contracts/automation-result-status.pin.test.ts (new) — pins, each on its own: (1) the union's exact membership at the type level (an Assert over an Eq identity, the automation-api.zod.test.ts form, compiled by check:test-typecheck, plus a satisfies list); (2) wire-to-contract parity at both levels (the Zod enum's .options read at runtime, and its inferred type bound to the contract's); (3) that the doc block above the declaration names the condition (source read); (4) a stranded envelope parses AND is preserved through the strip-mode object; (5) a literal outside the four is refused at data.status with invalid_value.
• content/docs/references/api/automation-api.mdx — regenerated by gen:docs (check:generated --fix; the one artifact it proved stale). api-surface/ is unchanged: the snapshot records that AutomationResult exists, not its members.
• .changeset/automation-result-stranded-status.md — @objectstack/spec: minor, additive (no BREAKING declaration, so no ADR-0087 marker is owed; check:adr-0087-registration exit 0).

Not in this PR, by the card: no engine change, no operator verb, no REST route, no ExecutionStatus widening. Those are #13937 (services half, stays open) and #13953.

The literal — what was measured before choosing

Vocabularies read (packages/spec/src, packages/services/service-automation, packages/plugins/plugin-approvals):

vocabulary	members	shape
AutomationResult.status (this union)	completedpausedfailed	single-word participles
ExecutionStatus (automation/execution.zod.ts, the run-row vocabulary listRuns filters on)	pendingrunningpausedcompletedfailedcancelledtimed_outretrying	single words; snake_case for two words
TaskStatus (system/worker.zod.ts)	pendingqueuedprocessingcompletedfailedcancelledtimeoutdead	dead = moved to the dead-letter queue
JobExecutionStatus (system/job.zod.ts)	runningsuccessfailedtimeoutdegraded
StrandedRunState (plugin-approvals, report-only)	missingfailed	classifies WHY a request's run is unrecoverable
prose lineage	"stranded" / "strands" / "stranding"	#13807, #13909, #13937, PR #13934; inspectStrandedRequests, StrandedApprovalRequest; 8 comment sites in engine.ts

Candidates:

• 'stranded' — chosen. The word the whole measured lineage already uses for exactly this condition (service-automation: a resume consumes the pause BEFORE running downstream nodes, so any node that throws leaves the run terminally unresumable — and the only inspector for it reports all clear #13909 itself: "There is no run state called stranded"); a single-word participle beside its three siblings; it names the operator-facing STATE, which survives a later shape-2 re-ordering, rather than the mechanism. It is not a promotion of StrandedRunState: that type's members are 'missing' | 'failed', it stays plugin-local and report-only, and the JSDoc says so.
• 'dead' — the one in-spec precedent (TaskStatus), but there it means retries exhausted and dead-lettered; here nothing was retried, and "dead" reads as final where the ruling's whole point is re-armable.
• 'failed_resume' / 'resume_failed' — snake_case is the house shape for two words (timed_out), but both name the mechanism (the consumption ordering that [Decision] Workflow resume ordering: a thrown node today leaves the run terminally unresumable — which of three shapes, given that the current order buys exactly-once across a crash? #13937 may still change under shape 2) rather than the state an operator acts on.
• 'unresumable' — false the moment the re-arm verb exists.
• 'suspended' — the spec uses it for admin-suspended tenant / license / environment, and it collides with "suspension", which is the PAUSE.
• 'stalled' / 'stuck' / 'halted' / 'incident' — zero uses in the three trees; incident is a noun (Camunda's shape), not a participle.

Producer and consumer measurements

• AutomationResult.status is a TypeScript interface member, not Zod — verified. Its one Zod mirror in packages/spec/src is TriggerFlowResponseSchema.data.status; both updated, parity pinned.
• Producer today: AutomationEngine.resumeInternal's catch arm records the run ROW failed and returns { success: false, error, durationMs, errorMessage, summary } — no status at all on the resumed-failure envelope (only execute()'s dispatched-and-rejected exit stamps status: 'failed'). So stamping 'stranded' on the result is the services half's, and whether the run ROW (ExecutionStatus) ever carries the word is that half's to measure; this PR does not widen ExecutionStatus.
• Exhaustive switches over AutomationResult.status in packages/{runtime,services,plugins,rest,cli,client}: zero. The only case 'completed' | 'paused' | 'failed' outside spec is plugin-approvals' classifyStrandedRunState, which switches over the run ROW's status string with a deliberately silent default, not over this union. Narrow re-declarations of the three-member union outside spec: zero in code (two in comments, engine.ts:4182 and approval-service.ts:315).
• Sibling repo objectui: app-shell/src/utils/flowResponse.ts:108 types status?: 'completed' | 'paused' | 'failed' | string and branches on success === false — tolerant of the new literal; nothing to change there for this half.
• No consumer needed even a type-only accommodation.

Verification — all readings on head 2c4bc29, exit codes captured before any pipe

@objectstack/spec:

• pnpm --filter @objectstack/spec build — exit 0 (check-dts-emitted: 34/34 declared declaration file(s) present).
• pnpm --filter @objectstack/spec test (whole suite) — Test Files 453 passed | 1 skipped (454) · Tests 12214 passed | 1 skipped (12215) on the committed head. The one skip is scripts/root-entry-type-nameability.pin.test.ts: its inspectDistFreshness predicate saw dist older than src because the reverse verification below touched the contract file's mtime after the build (content byte-identical), and that pin skips by default on a stale dist. After rebuilding the dist that file re-ran on the same head: Test Files 1 passed (1) · Tests 2 passed (2); check:api-surface on the rebuilt dist: exit 0. The earlier full run on the pre-.describe()-edit tree with a fresh dist was 454 passed · 12216 passed, 0 skipped.
• pnpm --filter @objectstack/spec typecheck — exit 0; check:test-typecheck: OK — 54 file(s) / 262 error(s) / 146 pinned signature(s) (ledger unchanged; the new pin file compiles under tsconfig.test.json).
• The pin file with its two neighbours (contracts/automation-service.test.ts, api/automation-api.zod.test.ts) via exec vitest run --maxWorkers=2 — Test Files 3 passed (3) · Tests 61 passed (61).
• check:generated — exit 0 after --fix regenerated the one stale artifact; check:api-surface exit 0; the 15 spec-scoped gates dispatch-gates.mjs derived (api-surface, authorable-surface, browser-reachable-entries, docs, dual-source-exports, empty-state, entry-nameability, export-origins, exported-any, liveness, llms-txt, skill-refs, strictness-ledger, variant-docs, yaml-examples) — every one exit 0.

Root gates, derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack from the merge-base change set (the derivation named this checkout at a5b95ee):

• exit 0: adr-0087-registration, changeset-no-major, empty-changeset, ci-filter-parity, comment-mask-adoption, cross-package-test-inputs (both spellings), keyed-text-bounds, plugin-teardown-shape, shard-attestation, system-context-census, undeclared-dep-imports, docs-audit/check-affected-docs, docs-audit/check-drift-comment, pm/release-rehearsal-clone --self-test, changeset-gate-self-tests, dispatcher-error-vocabulary, engine-double-contract, logger-receiver-detach, merge-driver, objectql-double-limit, objectui-changeset, page-declaration-shape, pm-half-states, published-files, query-options-erasure, slot-lookup, spec-parsed-alias, test-source-alias, type-check-coverage, type-source-resolution, where-matcher, @objectstack/lint check:doc-formula-expressions (exit 0 once the closure was built), pnpm check:doc-authoring (14504 customer-facing string(s) across 710 spec sources clean), pnpm check:nul-bytes (scanned 7981 text file(s) … no raw ASCII control bytes).
• NOT MEASURED, never green: check-test-completeness (exit 3, PREREQUISITE NOT MET), check-dual-build-cjs-loads (exit 3: needs every package's dist), check:type-check-debt (exit 3: --re-measure needs the full ledgered closure), check-dev-prereqs (exit 1: asks for a full pnpm build), pm/check-half-states (timed out at 240 s on the GitHub network leg — a PM-side gate). CI owns these.

Consumers — filter direction is DOWNSTREAM of spec; their dependency closures were built first (turbo run build over the ^... of each, 55 tasks, exit 0):

• @objectstack/runtime — typecheck exit 0; the 6 test files that read AutomationResult (flow-dispatch-status, automation-trigger-route-status, automation-trigger-paused-run, action-activation-dispatch, endpoint-flow-dispatch-status, actions-flow-dispatch-status) — Test Files 5 passed (5) · Tests 81 passed (81) (one pattern matched no file on its own; narrowed to these files, declared).
• @objectstack/service-automation — has no typecheck script (types NOT MEASURED here; the package is ledgered by check:type-check-coverage, exit 0); the 9 test files that read AutomationResult — Test Files 9 passed (9) · Tests 239 passed (239) (narrowed, declared).
• @objectstack/plugin-approvals — typecheck exit 0 (check:test-typecheck: OK); whole test — Test Files 36 passed (36) · Tests 662 passed (662).
• @objectstack/client — typecheck exit 0 (check:test-typecheck: OK); whole test — Test Files 32 passed (32) · Tests 420 passed (420).
• @objectstack/verify — typecheck exit 0; automation-trigger-terminal-messages.test.ts — Test Files 1 passed (1) · Tests 4 passed (4).
• @objectstack/rest — typecheck exit 0 (check:test-typecheck: OK); @objectstack/cli — typecheck exit 0. Neither imports AutomationResult.
• @objectstack/dogfood — NOT MEASURED locally (its closure is the whole app); CI.

Reverse verification — from the committed state

Mutation leg: the contract union narrowed back to three members on disk (confirmed by anchor counts: four-member 0 / three-member 1; git diff --stat 1 file, 1 insertion, 1 deletion), then tsc --noEmit -p packages/spec/tsconfig.test.json: exit 2 with 266 error lines against the ledgered 262 on the restored tree — the 4 new ones name exactly the two pins: src/api/automation-api.zod.test.ts(52,54) (TriggerFlowDataMatchesContract, TS2344) and src/contracts/automation-result-status.pin.test.ts at lines 64 (TS2322, 'stranded' not assignable), 72 and 74 (TS2344). Direction: red, as predicted. Restore leg: git checkout HEAD -- FILE from a trap with an absolute path, proven by git diff HEAD --quiet exit 0 and git hash-object equal to the HEAD blob 85b3d15a….

Review tier

needs:contract-review — clause ②, contract tier, as the ruling says in as many words. Draft; no seat marks it ready or arms auto-merge.

🤖 Generated with Claude Code

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/client-sdk.mdx(via AutomationResult (symbol, a top-level interface))
• content/docs/automation/flows.mdx(via AutomationResult (symbol, a top-level interface))

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

• content/docs/releases/v17.mdx(via AutomationResult (symbol, a top-level interface))

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

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 128 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 d8024f050e1f457117f914d6960a204d1af03966 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from fcdd5f04c1fffa48b2df2a94e9348af681e8c85a — the merge of head 2c4bc2903701f758f1c6c5aa107a3c597888e9de into base d8024f050e1f457117f914d6960a204d1af03966, 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 fcdd5f04c1fffa48b2df2a94e9348af681e8c85a && git checkout fcdd5f04c1fffa48b2df2a94e9348af681e8c85a
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin d8024f050e1f457117f914d6960a204d1af03966 2c4bc2903701f758f1c6c5aa107a3c597888e9de && git checkout -B drift-repro d8024f050e1f457117f914d6960a204d1af03966 && git merge --no-ff 2c4bc2903701f758f1c6c5aa107a3c597888e9de
node scripts/docs-audit/affected-docs.mjs --json d8024f050e1f457117f914d6960a204d1af03966

⚠️ 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 d8024f050e1f457117f914d6960a204d1af03966 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Fixes#14384

Contract half of the #13937 shape-4 ruling (director seat, comment 5491060439; maintainer 2026-09-01 「其他同意」), quoted verbatim on the card and untranslated here:

2. 命名同批定(service-automation: a resume consumes the pause BEFORE running downstream nodes, so any node that throws leaves the run terminally unresumable — and the only inspector for it reports all clear #13909 交付项 3 在此收口):该条件成为运维要操作的持久状态 ⇒ 平台级名字落 packages/spec/src/contracts/automation-service.ts(AutomationResult.status 现为 'completed' | 'paused' | 'failed')⇒ 触 spec ⇒ 条款②契约复审档位适用。StrandedRunState 保持 plugin 局部报告标签不升格。

What changed — one contract increment

• packages/spec/src/contracts/automation-service.ts — AutomationResult.status is now 'completed' | 'paused' | 'failed' | 'stranded', with a JSDoc paragraph naming the condition: a resume CONSUMED the suspension, a downstream node threw, the run is recorded as failed and can be re-armed only by an explicit operator verb (never by resume, which answers RUN_NOT_FOUND for it, and never automatically). Distinct from 'failed' on purpose: that one says the run ran and was rejected; this one says a recorded continuation stopped mid-flight and an operator has something to repair. The JSDoc also states that plugin-approvals' StrandedRunState is NOT promoted.
• packages/spec/src/api/automation-api.zod.ts — the wire mirror TriggerFlowResponseSchema.data.status carries the same four (the existing TriggerFlowDataMatchesContract pin goes red if only one side moves; see the reverse verification). The .describe() prose names the condition without an issue id: check:doc-authoring refused the first spelling (customer-facing text must not carry #NNNN), so the card references moved to an adjacent line comment.
• packages/spec/src/contracts/automation-result-status.pin.test.ts (new) — pins, each on its own: (1) the union's exact membership at the type level (an Assert over an Eq identity, the automation-api.zod.test.ts form, compiled by check:test-typecheck, plus a satisfies list); (2) wire-to-contract parity at both levels (the Zod enum's .options read at runtime, and its inferred type bound to the contract's); (3) that the doc block above the declaration names the condition (source read); (4) a stranded envelope parses AND is preserved through the strip-mode object; (5) a literal outside the four is refused at data.status with invalid_value.
• content/docs/references/api/automation-api.mdx — regenerated by gen:docs (check:generated --fix; the one artifact it proved stale). api-surface/ is unchanged: the snapshot records that AutomationResult exists, not its members.
• .changeset/automation-result-stranded-status.md — @objectstack/spec: minor, additive (no BREAKING declaration, so no ADR-0087 marker is owed; check:adr-0087-registration exit 0).

Not in this PR, by the card: no engine change, no operator verb, no REST route, no ExecutionStatus widening. Those are #13937 (services half, stays open) and #13953.

The literal — what was measured before choosing

Vocabularies read (packages/spec/src, packages/services/service-automation, packages/plugins/plugin-approvals):

vocabulary	members	shape
AutomationResult.status (this union)	completedpausedfailed	single-word participles
ExecutionStatus (automation/execution.zod.ts, the run-row vocabulary listRuns filters on)	pendingrunningpausedcompletedfailedcancelledtimed_outretrying	single words; snake_case for two words
TaskStatus (system/worker.zod.ts)	pendingqueuedprocessingcompletedfailedcancelledtimeoutdead	dead = moved to the dead-letter queue
JobExecutionStatus (system/job.zod.ts)	runningsuccessfailedtimeoutdegraded
StrandedRunState (plugin-approvals, report-only)	missingfailed	classifies WHY a request's run is unrecoverable
prose lineage	"stranded" / "strands" / "stranding"	#13807, #13909, #13937, PR #13934; inspectStrandedRequests, StrandedApprovalRequest; 8 comment sites in engine.ts

Candidates:

• 'stranded' — chosen. The word the whole measured lineage already uses for exactly this condition (service-automation: a resume consumes the pause BEFORE running downstream nodes, so any node that throws leaves the run terminally unresumable — and the only inspector for it reports all clear #13909 itself: "There is no run state called stranded"); a single-word participle beside its three siblings; it names the operator-facing STATE, which survives a later shape-2 re-ordering, rather than the mechanism. It is not a promotion of StrandedRunState: that type's members are 'missing' | 'failed', it stays plugin-local and report-only, and the JSDoc says so.
• 'dead' — the one in-spec precedent (TaskStatus), but there it means retries exhausted and dead-lettered; here nothing was retried, and "dead" reads as final where the ruling's whole point is re-armable.
• 'failed_resume' / 'resume_failed' — snake_case is the house shape for two words (timed_out), but both name the mechanism (the consumption ordering that [Decision] Workflow resume ordering: a thrown node today leaves the run terminally unresumable — which of three shapes, given that the current order buys exactly-once across a crash? #13937 may still change under shape 2) rather than the state an operator acts on.
• 'unresumable' — false the moment the re-arm verb exists.
• 'suspended' — the spec uses it for admin-suspended tenant / license / environment, and it collides with "suspension", which is the PAUSE.
• 'stalled' / 'stuck' / 'halted' / 'incident' — zero uses in the three trees; incident is a noun (Camunda's shape), not a participle.

Producer and consumer measurements

• AutomationResult.status is a TypeScript interface member, not Zod — verified. Its one Zod mirror in packages/spec/src is TriggerFlowResponseSchema.data.status; both updated, parity pinned.
• Producer today: AutomationEngine.resumeInternal's catch arm records the run ROW failed and returns { success: false, error, durationMs, errorMessage, summary } — no status at all on the resumed-failure envelope (only execute()'s dispatched-and-rejected exit stamps status: 'failed'). So stamping 'stranded' on the result is the services half's, and whether the run ROW (ExecutionStatus) ever carries the word is that half's to measure; this PR does not widen ExecutionStatus.
• Exhaustive switches over AutomationResult.status in packages/{runtime,services,plugins,rest,cli,client}: zero. The only case 'completed' | 'paused' | 'failed' outside spec is plugin-approvals' classifyStrandedRunState, which switches over the run ROW's status string with a deliberately silent default, not over this union. Narrow re-declarations of the three-member union outside spec: zero in code (two in comments, engine.ts:4182 and approval-service.ts:315).
• Sibling repo objectui: app-shell/src/utils/flowResponse.ts:108 types status?: 'completed' | 'paused' | 'failed' | string and branches on success === false — tolerant of the new literal; nothing to change there for this half.
• No consumer needed even a type-only accommodation.

Verification — all readings on head 2c4bc29, exit codes captured before any pipe

@objectstack/spec:

• pnpm --filter @objectstack/spec build — exit 0 (check-dts-emitted: 34/34 declared declaration file(s) present).
• pnpm --filter @objectstack/spec test (whole suite) — Test Files 453 passed | 1 skipped (454) · Tests 12214 passed | 1 skipped (12215) on the committed head. The one skip is scripts/root-entry-type-nameability.pin.test.ts: its inspectDistFreshness predicate saw dist older than src because the reverse verification below touched the contract file's mtime after the build (content byte-identical), and that pin skips by default on a stale dist. After rebuilding the dist that file re-ran on the same head: Test Files 1 passed (1) · Tests 2 passed (2); check:api-surface on the rebuilt dist: exit 0. The earlier full run on the pre-.describe()-edit tree with a fresh dist was 454 passed · 12216 passed, 0 skipped.
• pnpm --filter @objectstack/spec typecheck — exit 0; check:test-typecheck: OK — 54 file(s) / 262 error(s) / 146 pinned signature(s) (ledger unchanged; the new pin file compiles under tsconfig.test.json).
• The pin file with its two neighbours (contracts/automation-service.test.ts, api/automation-api.zod.test.ts) via exec vitest run --maxWorkers=2 — Test Files 3 passed (3) · Tests 61 passed (61).
• check:generated — exit 0 after --fix regenerated the one stale artifact; check:api-surface exit 0; the 15 spec-scoped gates dispatch-gates.mjs derived (api-surface, authorable-surface, browser-reachable-entries, docs, dual-source-exports, empty-state, entry-nameability, export-origins, exported-any, liveness, llms-txt, skill-refs, strictness-ledger, variant-docs, yaml-examples) — every one exit 0.

Root gates, derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack from the merge-base change set (the derivation named this checkout at a5b95ee):

• exit 0: adr-0087-registration, changeset-no-major, empty-changeset, ci-filter-parity, comment-mask-adoption, cross-package-test-inputs (both spellings), keyed-text-bounds, plugin-teardown-shape, shard-attestation, system-context-census, undeclared-dep-imports, docs-audit/check-affected-docs, docs-audit/check-drift-comment, pm/release-rehearsal-clone --self-test, changeset-gate-self-tests, dispatcher-error-vocabulary, engine-double-contract, logger-receiver-detach, merge-driver, objectql-double-limit, objectui-changeset, page-declaration-shape, pm-half-states, published-files, query-options-erasure, slot-lookup, spec-parsed-alias, test-source-alias, type-check-coverage, type-source-resolution, where-matcher, @objectstack/lint check:doc-formula-expressions (exit 0 once the closure was built), pnpm check:doc-authoring (14504 customer-facing string(s) across 710 spec sources clean), pnpm check:nul-bytes (scanned 7981 text file(s) … no raw ASCII control bytes).
• NOT MEASURED, never green: check-test-completeness (exit 3, PREREQUISITE NOT MET), check-dual-build-cjs-loads (exit 3: needs every package's dist), check:type-check-debt (exit 3: --re-measure needs the full ledgered closure), check-dev-prereqs (exit 1: asks for a full pnpm build), pm/check-half-states (timed out at 240 s on the GitHub network leg — a PM-side gate). CI owns these.

Consumers — filter direction is DOWNSTREAM of spec; their dependency closures were built first (turbo run build over the ^... of each, 55 tasks, exit 0):

• @objectstack/runtime — typecheck exit 0; the 6 test files that read AutomationResult (flow-dispatch-status, automation-trigger-route-status, automation-trigger-paused-run, action-activation-dispatch, endpoint-flow-dispatch-status, actions-flow-dispatch-status) — Test Files 5 passed (5) · Tests 81 passed (81) (one pattern matched no file on its own; narrowed to these files, declared).
• @objectstack/service-automation — has no typecheck script (types NOT MEASURED here; the package is ledgered by check:type-check-coverage, exit 0); the 9 test files that read AutomationResult — Test Files 9 passed (9) · Tests 239 passed (239) (narrowed, declared).
• @objectstack/plugin-approvals — typecheck exit 0 (check:test-typecheck: OK); whole test — Test Files 36 passed (36) · Tests 662 passed (662).
• @objectstack/client — typecheck exit 0 (check:test-typecheck: OK); whole test — Test Files 32 passed (32) · Tests 420 passed (420).
• @objectstack/verify — typecheck exit 0; automation-trigger-terminal-messages.test.ts — Test Files 1 passed (1) · Tests 4 passed (4).
• @objectstack/rest — typecheck exit 0 (check:test-typecheck: OK); @objectstack/cli — typecheck exit 0. Neither imports AutomationResult.
• @objectstack/dogfood — NOT MEASURED locally (its closure is the whole app); CI.

Reverse verification — from the committed state

Mutation leg: the contract union narrowed back to three members on disk (confirmed by anchor counts: four-member 0 / three-member 1; git diff --stat 1 file, 1 insertion, 1 deletion), then tsc --noEmit -p packages/spec/tsconfig.test.json: exit 2 with 266 error lines against the ledgered 262 on the restored tree — the 4 new ones name exactly the two pins: src/api/automation-api.zod.test.ts(52,54) (TriggerFlowDataMatchesContract, TS2344) and src/contracts/automation-result-status.pin.test.ts at lines 64 (TS2322, 'stranded' not assignable), 72 and 74 (TS2344). Direction: red, as predicted. Restore leg: git checkout HEAD -- FILE from a trap with an absolute path, proven by git diff HEAD --quiet exit 0 and git hash-object equal to the HEAD blob 85b3d15a….

Review tier

needs:contract-review — clause ②, contract tier, as the ruling says in as many words. Draft; no seat marks it ready or arms auto-merge.

🤖 Generated with Claude Code

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/client-sdk.mdx(via AutomationResult (symbol, a top-level interface))
• content/docs/automation/flows.mdx(via AutomationResult (symbol, a top-level interface))

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

• content/docs/releases/v17.mdx(via AutomationResult (symbol, a top-level interface))

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

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 128 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 d8024f050e1f457117f914d6960a204d1af03966 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from fcdd5f04c1fffa48b2df2a94e9348af681e8c85a — the merge of head 2c4bc2903701f758f1c6c5aa107a3c597888e9de into base d8024f050e1f457117f914d6960a204d1af03966, 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 fcdd5f04c1fffa48b2df2a94e9348af681e8c85a && git checkout fcdd5f04c1fffa48b2df2a94e9348af681e8c85a
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin d8024f050e1f457117f914d6960a204d1af03966 2c4bc2903701f758f1c6c5aa107a3c597888e9de && git checkout -B drift-repro d8024f050e1f457117f914d6960a204d1af03966 && git merge --no-ff 2c4bc2903701f758f1c6c5aa107a3c597888e9de
node scripts/docs-audit/affected-docs.mjs --json d8024f050e1f457117f914d6960a204d1af03966

⚠️ 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 d8024f050e1f457117f914d6960a204d1af03966 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Fixes#14384

Contract half of the #13937 shape-4 ruling (director seat, comment 5491060439; maintainer 2026-09-01 「其他同意」), quoted verbatim on the card and untranslated here:

2. 命名同批定(service-automation: a resume consumes the pause BEFORE running downstream nodes, so any node that throws leaves the run terminally unresumable — and the only inspector for it reports all clear #13909 交付项 3 在此收口):该条件成为运维要操作的持久状态 ⇒ 平台级名字落 packages/spec/src/contracts/automation-service.ts(AutomationResult.status 现为 'completed' | 'paused' | 'failed')⇒ 触 spec ⇒ 条款②契约复审档位适用。StrandedRunState 保持 plugin 局部报告标签不升格。

What changed — one contract increment

• packages/spec/src/contracts/automation-service.ts — AutomationResult.status is now 'completed' | 'paused' | 'failed' | 'stranded', with a JSDoc paragraph naming the condition: a resume CONSUMED the suspension, a downstream node threw, the run is recorded as failed and can be re-armed only by an explicit operator verb (never by resume, which answers RUN_NOT_FOUND for it, and never automatically). Distinct from 'failed' on purpose: that one says the run ran and was rejected; this one says a recorded continuation stopped mid-flight and an operator has something to repair. The JSDoc also states that plugin-approvals' StrandedRunState is NOT promoted.
• packages/spec/src/api/automation-api.zod.ts — the wire mirror TriggerFlowResponseSchema.data.status carries the same four (the existing TriggerFlowDataMatchesContract pin goes red if only one side moves; see the reverse verification). The .describe() prose names the condition without an issue id: check:doc-authoring refused the first spelling (customer-facing text must not carry #NNNN), so the card references moved to an adjacent line comment.
• packages/spec/src/contracts/automation-result-status.pin.test.ts (new) — pins, each on its own: (1) the union's exact membership at the type level (an Assert over an Eq identity, the automation-api.zod.test.ts form, compiled by check:test-typecheck, plus a satisfies list); (2) wire-to-contract parity at both levels (the Zod enum's .options read at runtime, and its inferred type bound to the contract's); (3) that the doc block above the declaration names the condition (source read); (4) a stranded envelope parses AND is preserved through the strip-mode object; (5) a literal outside the four is refused at data.status with invalid_value.
• content/docs/references/api/automation-api.mdx — regenerated by gen:docs (check:generated --fix; the one artifact it proved stale). api-surface/ is unchanged: the snapshot records that AutomationResult exists, not its members.
• .changeset/automation-result-stranded-status.md — @objectstack/spec: minor, additive (no BREAKING declaration, so no ADR-0087 marker is owed; check:adr-0087-registration exit 0).

Not in this PR, by the card: no engine change, no operator verb, no REST route, no ExecutionStatus widening. Those are #13937 (services half, stays open) and #13953.

The literal — what was measured before choosing

Vocabularies read (packages/spec/src, packages/services/service-automation, packages/plugins/plugin-approvals):

vocabulary	members	shape
AutomationResult.status (this union)	completedpausedfailed	single-word participles
ExecutionStatus (automation/execution.zod.ts, the run-row vocabulary listRuns filters on)	pendingrunningpausedcompletedfailedcancelledtimed_outretrying	single words; snake_case for two words
TaskStatus (system/worker.zod.ts)	pendingqueuedprocessingcompletedfailedcancelledtimeoutdead	dead = moved to the dead-letter queue
JobExecutionStatus (system/job.zod.ts)	runningsuccessfailedtimeoutdegraded
StrandedRunState (plugin-approvals, report-only)	missingfailed	classifies WHY a request's run is unrecoverable
prose lineage	"stranded" / "strands" / "stranding"	#13807, #13909, #13937, PR #13934; inspectStrandedRequests, StrandedApprovalRequest; 8 comment sites in engine.ts

Candidates:

• 'stranded' — chosen. The word the whole measured lineage already uses for exactly this condition (service-automation: a resume consumes the pause BEFORE running downstream nodes, so any node that throws leaves the run terminally unresumable — and the only inspector for it reports all clear #13909 itself: "There is no run state called stranded"); a single-word participle beside its three siblings; it names the operator-facing STATE, which survives a later shape-2 re-ordering, rather than the mechanism. It is not a promotion of StrandedRunState: that type's members are 'missing' | 'failed', it stays plugin-local and report-only, and the JSDoc says so.
• 'dead' — the one in-spec precedent (TaskStatus), but there it means retries exhausted and dead-lettered; here nothing was retried, and "dead" reads as final where the ruling's whole point is re-armable.
• 'failed_resume' / 'resume_failed' — snake_case is the house shape for two words (timed_out), but both name the mechanism (the consumption ordering that [Decision] Workflow resume ordering: a thrown node today leaves the run terminally unresumable — which of three shapes, given that the current order buys exactly-once across a crash? #13937 may still change under shape 2) rather than the state an operator acts on.
• 'unresumable' — false the moment the re-arm verb exists.
• 'suspended' — the spec uses it for admin-suspended tenant / license / environment, and it collides with "suspension", which is the PAUSE.
• 'stalled' / 'stuck' / 'halted' / 'incident' — zero uses in the three trees; incident is a noun (Camunda's shape), not a participle.

Producer and consumer measurements

• AutomationResult.status is a TypeScript interface member, not Zod — verified. Its one Zod mirror in packages/spec/src is TriggerFlowResponseSchema.data.status; both updated, parity pinned.
• Producer today: AutomationEngine.resumeInternal's catch arm records the run ROW failed and returns { success: false, error, durationMs, errorMessage, summary } — no status at all on the resumed-failure envelope (only execute()'s dispatched-and-rejected exit stamps status: 'failed'). So stamping 'stranded' on the result is the services half's, and whether the run ROW (ExecutionStatus) ever carries the word is that half's to measure; this PR does not widen ExecutionStatus.
• Exhaustive switches over AutomationResult.status in packages/{runtime,services,plugins,rest,cli,client}: zero. The only case 'completed' | 'paused' | 'failed' outside spec is plugin-approvals' classifyStrandedRunState, which switches over the run ROW's status string with a deliberately silent default, not over this union. Narrow re-declarations of the three-member union outside spec: zero in code (two in comments, engine.ts:4182 and approval-service.ts:315).
• Sibling repo objectui: app-shell/src/utils/flowResponse.ts:108 types status?: 'completed' | 'paused' | 'failed' | string and branches on success === false — tolerant of the new literal; nothing to change there for this half.
• No consumer needed even a type-only accommodation.

Verification — all readings on head 2c4bc29, exit codes captured before any pipe

@objectstack/spec:

• pnpm --filter @objectstack/spec build — exit 0 (check-dts-emitted: 34/34 declared declaration file(s) present).
• pnpm --filter @objectstack/spec test (whole suite) — Test Files 453 passed | 1 skipped (454) · Tests 12214 passed | 1 skipped (12215) on the committed head. The one skip is scripts/root-entry-type-nameability.pin.test.ts: its inspectDistFreshness predicate saw dist older than src because the reverse verification below touched the contract file's mtime after the build (content byte-identical), and that pin skips by default on a stale dist. After rebuilding the dist that file re-ran on the same head: Test Files 1 passed (1) · Tests 2 passed (2); check:api-surface on the rebuilt dist: exit 0. The earlier full run on the pre-.describe()-edit tree with a fresh dist was 454 passed · 12216 passed, 0 skipped.
• pnpm --filter @objectstack/spec typecheck — exit 0; check:test-typecheck: OK — 54 file(s) / 262 error(s) / 146 pinned signature(s) (ledger unchanged; the new pin file compiles under tsconfig.test.json).
• The pin file with its two neighbours (contracts/automation-service.test.ts, api/automation-api.zod.test.ts) via exec vitest run --maxWorkers=2 — Test Files 3 passed (3) · Tests 61 passed (61).
• check:generated — exit 0 after --fix regenerated the one stale artifact; check:api-surface exit 0; the 15 spec-scoped gates dispatch-gates.mjs derived (api-surface, authorable-surface, browser-reachable-entries, docs, dual-source-exports, empty-state, entry-nameability, export-origins, exported-any, liveness, llms-txt, skill-refs, strictness-ledger, variant-docs, yaml-examples) — every one exit 0.

Root gates, derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack from the merge-base change set (the derivation named this checkout at a5b95ee):

• exit 0: adr-0087-registration, changeset-no-major, empty-changeset, ci-filter-parity, comment-mask-adoption, cross-package-test-inputs (both spellings), keyed-text-bounds, plugin-teardown-shape, shard-attestation, system-context-census, undeclared-dep-imports, docs-audit/check-affected-docs, docs-audit/check-drift-comment, pm/release-rehearsal-clone --self-test, changeset-gate-self-tests, dispatcher-error-vocabulary, engine-double-contract, logger-receiver-detach, merge-driver, objectql-double-limit, objectui-changeset, page-declaration-shape, pm-half-states, published-files, query-options-erasure, slot-lookup, spec-parsed-alias, test-source-alias, type-check-coverage, type-source-resolution, where-matcher, @objectstack/lint check:doc-formula-expressions (exit 0 once the closure was built), pnpm check:doc-authoring (14504 customer-facing string(s) across 710 spec sources clean), pnpm check:nul-bytes (scanned 7981 text file(s) … no raw ASCII control bytes).
• NOT MEASURED, never green: check-test-completeness (exit 3, PREREQUISITE NOT MET), check-dual-build-cjs-loads (exit 3: needs every package's dist), check:type-check-debt (exit 3: --re-measure needs the full ledgered closure), check-dev-prereqs (exit 1: asks for a full pnpm build), pm/check-half-states (timed out at 240 s on the GitHub network leg — a PM-side gate). CI owns these.

Consumers — filter direction is DOWNSTREAM of spec; their dependency closures were built first (turbo run build over the ^... of each, 55 tasks, exit 0):

• @objectstack/runtime — typecheck exit 0; the 6 test files that read AutomationResult (flow-dispatch-status, automation-trigger-route-status, automation-trigger-paused-run, action-activation-dispatch, endpoint-flow-dispatch-status, actions-flow-dispatch-status) — Test Files 5 passed (5) · Tests 81 passed (81) (one pattern matched no file on its own; narrowed to these files, declared).
• @objectstack/service-automation — has no typecheck script (types NOT MEASURED here; the package is ledgered by check:type-check-coverage, exit 0); the 9 test files that read AutomationResult — Test Files 9 passed (9) · Tests 239 passed (239) (narrowed, declared).
• @objectstack/plugin-approvals — typecheck exit 0 (check:test-typecheck: OK); whole test — Test Files 36 passed (36) · Tests 662 passed (662).
• @objectstack/client — typecheck exit 0 (check:test-typecheck: OK); whole test — Test Files 32 passed (32) · Tests 420 passed (420).
• @objectstack/verify — typecheck exit 0; automation-trigger-terminal-messages.test.ts — Test Files 1 passed (1) · Tests 4 passed (4).
• @objectstack/rest — typecheck exit 0 (check:test-typecheck: OK); @objectstack/cli — typecheck exit 0. Neither imports AutomationResult.
• @objectstack/dogfood — NOT MEASURED locally (its closure is the whole app); CI.

Reverse verification — from the committed state

Mutation leg: the contract union narrowed back to three members on disk (confirmed by anchor counts: four-member 0 / three-member 1; git diff --stat 1 file, 1 insertion, 1 deletion), then tsc --noEmit -p packages/spec/tsconfig.test.json: exit 2 with 266 error lines against the ledgered 262 on the restored tree — the 4 new ones name exactly the two pins: src/api/automation-api.zod.test.ts(52,54) (TriggerFlowDataMatchesContract, TS2344) and src/contracts/automation-result-status.pin.test.ts at lines 64 (TS2322, 'stranded' not assignable), 72 and 74 (TS2344). Direction: red, as predicted. Restore leg: git checkout HEAD -- FILE from a trap with an absolute path, proven by git diff HEAD --quiet exit 0 and git hash-object equal to the HEAD blob 85b3d15a….

Review tier

needs:contract-review — clause ②, contract tier, as the ruling says in as many words. Draft; no seat marks it ready or arms auto-merge.

🤖 Generated with Claude Code

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/client-sdk.mdx(via AutomationResult (symbol, a top-level interface))
• content/docs/automation/flows.mdx(via AutomationResult (symbol, a top-level interface))

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

• content/docs/releases/v17.mdx(via AutomationResult (symbol, a top-level interface))

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

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 128 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 d8024f050e1f457117f914d6960a204d1af03966 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from fcdd5f04c1fffa48b2df2a94e9348af681e8c85a — the merge of head 2c4bc2903701f758f1c6c5aa107a3c597888e9de into base d8024f050e1f457117f914d6960a204d1af03966, 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 fcdd5f04c1fffa48b2df2a94e9348af681e8c85a && git checkout fcdd5f04c1fffa48b2df2a94e9348af681e8c85a
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin d8024f050e1f457117f914d6960a204d1af03966 2c4bc2903701f758f1c6c5aa107a3c597888e9de && git checkout -B drift-repro d8024f050e1f457117f914d6960a204d1af03966 && git merge --no-ff 2c4bc2903701f758f1c6c5aa107a3c597888e9de
node scripts/docs-audit/affected-docs.mjs --json d8024f050e1f457117f914d6960a204d1af03966

⚠️ 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 d8024f050e1f457117f914d6960a204d1af03966 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Fixes#14384

Contract half of the #13937 shape-4 ruling (director seat, comment 5491060439; maintainer 2026-09-01 「其他同意」), quoted verbatim on the card and untranslated here:

2. 命名同批定(service-automation: a resume consumes the pause BEFORE running downstream nodes, so any node that throws leaves the run terminally unresumable — and the only inspector for it reports all clear #13909 交付项 3 在此收口):该条件成为运维要操作的持久状态 ⇒ 平台级名字落 packages/spec/src/contracts/automation-service.ts(AutomationResult.status 现为 'completed' | 'paused' | 'failed')⇒ 触 spec ⇒ 条款②契约复审档位适用。StrandedRunState 保持 plugin 局部报告标签不升格。

What changed — one contract increment

• packages/spec/src/contracts/automation-service.ts — AutomationResult.status is now 'completed' | 'paused' | 'failed' | 'stranded', with a JSDoc paragraph naming the condition: a resume CONSUMED the suspension, a downstream node threw, the run is recorded as failed and can be re-armed only by an explicit operator verb (never by resume, which answers RUN_NOT_FOUND for it, and never automatically). Distinct from 'failed' on purpose: that one says the run ran and was rejected; this one says a recorded continuation stopped mid-flight and an operator has something to repair. The JSDoc also states that plugin-approvals' StrandedRunState is NOT promoted.
• packages/spec/src/api/automation-api.zod.ts — the wire mirror TriggerFlowResponseSchema.data.status carries the same four (the existing TriggerFlowDataMatchesContract pin goes red if only one side moves; see the reverse verification). The .describe() prose names the condition without an issue id: check:doc-authoring refused the first spelling (customer-facing text must not carry #NNNN), so the card references moved to an adjacent line comment.
• packages/spec/src/contracts/automation-result-status.pin.test.ts (new) — pins, each on its own: (1) the union's exact membership at the type level (an Assert over an Eq identity, the automation-api.zod.test.ts form, compiled by check:test-typecheck, plus a satisfies list); (2) wire-to-contract parity at both levels (the Zod enum's .options read at runtime, and its inferred type bound to the contract's); (3) that the doc block above the declaration names the condition (source read); (4) a stranded envelope parses AND is preserved through the strip-mode object; (5) a literal outside the four is refused at data.status with invalid_value.
• content/docs/references/api/automation-api.mdx — regenerated by gen:docs (check:generated --fix; the one artifact it proved stale). api-surface/ is unchanged: the snapshot records that AutomationResult exists, not its members.
• .changeset/automation-result-stranded-status.md — @objectstack/spec: minor, additive (no BREAKING declaration, so no ADR-0087 marker is owed; check:adr-0087-registration exit 0).

Not in this PR, by the card: no engine change, no operator verb, no REST route, no ExecutionStatus widening. Those are #13937 (services half, stays open) and #13953.

The literal — what was measured before choosing

Vocabularies read (packages/spec/src, packages/services/service-automation, packages/plugins/plugin-approvals):

vocabulary	members	shape
AutomationResult.status (this union)	completedpausedfailed	single-word participles
ExecutionStatus (automation/execution.zod.ts, the run-row vocabulary listRuns filters on)	pendingrunningpausedcompletedfailedcancelledtimed_outretrying	single words; snake_case for two words
TaskStatus (system/worker.zod.ts)	pendingqueuedprocessingcompletedfailedcancelledtimeoutdead	dead = moved to the dead-letter queue
JobExecutionStatus (system/job.zod.ts)	runningsuccessfailedtimeoutdegraded
StrandedRunState (plugin-approvals, report-only)	missingfailed	classifies WHY a request's run is unrecoverable
prose lineage	"stranded" / "strands" / "stranding"	#13807, #13909, #13937, PR #13934; inspectStrandedRequests, StrandedApprovalRequest; 8 comment sites in engine.ts

Candidates:

• 'stranded' — chosen. The word the whole measured lineage already uses for exactly this condition (service-automation: a resume consumes the pause BEFORE running downstream nodes, so any node that throws leaves the run terminally unresumable — and the only inspector for it reports all clear #13909 itself: "There is no run state called stranded"); a single-word participle beside its three siblings; it names the operator-facing STATE, which survives a later shape-2 re-ordering, rather than the mechanism. It is not a promotion of StrandedRunState: that type's members are 'missing' | 'failed', it stays plugin-local and report-only, and the JSDoc says so.
• 'dead' — the one in-spec precedent (TaskStatus), but there it means retries exhausted and dead-lettered; here nothing was retried, and "dead" reads as final where the ruling's whole point is re-armable.
• 'failed_resume' / 'resume_failed' — snake_case is the house shape for two words (timed_out), but both name the mechanism (the consumption ordering that [Decision] Workflow resume ordering: a thrown node today leaves the run terminally unresumable — which of three shapes, given that the current order buys exactly-once across a crash? #13937 may still change under shape 2) rather than the state an operator acts on.
• 'unresumable' — false the moment the re-arm verb exists.
• 'suspended' — the spec uses it for admin-suspended tenant / license / environment, and it collides with "suspension", which is the PAUSE.
• 'stalled' / 'stuck' / 'halted' / 'incident' — zero uses in the three trees; incident is a noun (Camunda's shape), not a participle.

Producer and consumer measurements

• AutomationResult.status is a TypeScript interface member, not Zod — verified. Its one Zod mirror in packages/spec/src is TriggerFlowResponseSchema.data.status; both updated, parity pinned.
• Producer today: AutomationEngine.resumeInternal's catch arm records the run ROW failed and returns { success: false, error, durationMs, errorMessage, summary } — no status at all on the resumed-failure envelope (only execute()'s dispatched-and-rejected exit stamps status: 'failed'). So stamping 'stranded' on the result is the services half's, and whether the run ROW (ExecutionStatus) ever carries the word is that half's to measure; this PR does not widen ExecutionStatus.
• Exhaustive switches over AutomationResult.status in packages/{runtime,services,plugins,rest,cli,client}: zero. The only case 'completed' | 'paused' | 'failed' outside spec is plugin-approvals' classifyStrandedRunState, which switches over the run ROW's status string with a deliberately silent default, not over this union. Narrow re-declarations of the three-member union outside spec: zero in code (two in comments, engine.ts:4182 and approval-service.ts:315).
• Sibling repo objectui: app-shell/src/utils/flowResponse.ts:108 types status?: 'completed' | 'paused' | 'failed' | string and branches on success === false — tolerant of the new literal; nothing to change there for this half.
• No consumer needed even a type-only accommodation.

Verification — all readings on head 2c4bc29, exit codes captured before any pipe

@objectstack/spec:

• pnpm --filter @objectstack/spec build — exit 0 (check-dts-emitted: 34/34 declared declaration file(s) present).
• pnpm --filter @objectstack/spec test (whole suite) — Test Files 453 passed | 1 skipped (454) · Tests 12214 passed | 1 skipped (12215) on the committed head. The one skip is scripts/root-entry-type-nameability.pin.test.ts: its inspectDistFreshness predicate saw dist older than src because the reverse verification below touched the contract file's mtime after the build (content byte-identical), and that pin skips by default on a stale dist. After rebuilding the dist that file re-ran on the same head: Test Files 1 passed (1) · Tests 2 passed (2); check:api-surface on the rebuilt dist: exit 0. The earlier full run on the pre-.describe()-edit tree with a fresh dist was 454 passed · 12216 passed, 0 skipped.
• pnpm --filter @objectstack/spec typecheck — exit 0; check:test-typecheck: OK — 54 file(s) / 262 error(s) / 146 pinned signature(s) (ledger unchanged; the new pin file compiles under tsconfig.test.json).
• The pin file with its two neighbours (contracts/automation-service.test.ts, api/automation-api.zod.test.ts) via exec vitest run --maxWorkers=2 — Test Files 3 passed (3) · Tests 61 passed (61).
• check:generated — exit 0 after --fix regenerated the one stale artifact; check:api-surface exit 0; the 15 spec-scoped gates dispatch-gates.mjs derived (api-surface, authorable-surface, browser-reachable-entries, docs, dual-source-exports, empty-state, entry-nameability, export-origins, exported-any, liveness, llms-txt, skill-refs, strictness-ledger, variant-docs, yaml-examples) — every one exit 0.

Root gates, derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack from the merge-base change set (the derivation named this checkout at a5b95ee):

• exit 0: adr-0087-registration, changeset-no-major, empty-changeset, ci-filter-parity, comment-mask-adoption, cross-package-test-inputs (both spellings), keyed-text-bounds, plugin-teardown-shape, shard-attestation, system-context-census, undeclared-dep-imports, docs-audit/check-affected-docs, docs-audit/check-drift-comment, pm/release-rehearsal-clone --self-test, changeset-gate-self-tests, dispatcher-error-vocabulary, engine-double-contract, logger-receiver-detach, merge-driver, objectql-double-limit, objectui-changeset, page-declaration-shape, pm-half-states, published-files, query-options-erasure, slot-lookup, spec-parsed-alias, test-source-alias, type-check-coverage, type-source-resolution, where-matcher, @objectstack/lint check:doc-formula-expressions (exit 0 once the closure was built), pnpm check:doc-authoring (14504 customer-facing string(s) across 710 spec sources clean), pnpm check:nul-bytes (scanned 7981 text file(s) … no raw ASCII control bytes).
• NOT MEASURED, never green: check-test-completeness (exit 3, PREREQUISITE NOT MET), check-dual-build-cjs-loads (exit 3: needs every package's dist), check:type-check-debt (exit 3: --re-measure needs the full ledgered closure), check-dev-prereqs (exit 1: asks for a full pnpm build), pm/check-half-states (timed out at 240 s on the GitHub network leg — a PM-side gate). CI owns these.

Consumers — filter direction is DOWNSTREAM of spec; their dependency closures were built first (turbo run build over the ^... of each, 55 tasks, exit 0):

• @objectstack/runtime — typecheck exit 0; the 6 test files that read AutomationResult (flow-dispatch-status, automation-trigger-route-status, automation-trigger-paused-run, action-activation-dispatch, endpoint-flow-dispatch-status, actions-flow-dispatch-status) — Test Files 5 passed (5) · Tests 81 passed (81) (one pattern matched no file on its own; narrowed to these files, declared).
• @objectstack/service-automation — has no typecheck script (types NOT MEASURED here; the package is ledgered by check:type-check-coverage, exit 0); the 9 test files that read AutomationResult — Test Files 9 passed (9) · Tests 239 passed (239) (narrowed, declared).
• @objectstack/plugin-approvals — typecheck exit 0 (check:test-typecheck: OK); whole test — Test Files 36 passed (36) · Tests 662 passed (662).
• @objectstack/client — typecheck exit 0 (check:test-typecheck: OK); whole test — Test Files 32 passed (32) · Tests 420 passed (420).
• @objectstack/verify — typecheck exit 0; automation-trigger-terminal-messages.test.ts — Test Files 1 passed (1) · Tests 4 passed (4).
• @objectstack/rest — typecheck exit 0 (check:test-typecheck: OK); @objectstack/cli — typecheck exit 0. Neither imports AutomationResult.
• @objectstack/dogfood — NOT MEASURED locally (its closure is the whole app); CI.

Reverse verification — from the committed state

Mutation leg: the contract union narrowed back to three members on disk (confirmed by anchor counts: four-member 0 / three-member 1; git diff --stat 1 file, 1 insertion, 1 deletion), then tsc --noEmit -p packages/spec/tsconfig.test.json: exit 2 with 266 error lines against the ledgered 262 on the restored tree — the 4 new ones name exactly the two pins: src/api/automation-api.zod.test.ts(52,54) (TriggerFlowDataMatchesContract, TS2344) and src/contracts/automation-result-status.pin.test.ts at lines 64 (TS2322, 'stranded' not assignable), 72 and 74 (TS2344). Direction: red, as predicted. Restore leg: git checkout HEAD -- FILE from a trap with an absolute path, proven by git diff HEAD --quiet exit 0 and git hash-object equal to the HEAD blob 85b3d15a….

Review tier

needs:contract-review — clause ②, contract tier, as the ruling says in as many words. Draft; no seat marks it ready or arms auto-merge.

🤖 Generated with Claude Code

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/client-sdk.mdx(via AutomationResult (symbol, a top-level interface))
• content/docs/automation/flows.mdx(via AutomationResult (symbol, a top-level interface))

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

• content/docs/releases/v17.mdx(via AutomationResult (symbol, a top-level interface))

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

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 128 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 d8024f050e1f457117f914d6960a204d1af03966 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from fcdd5f04c1fffa48b2df2a94e9348af681e8c85a — the merge of head 2c4bc2903701f758f1c6c5aa107a3c597888e9de into base d8024f050e1f457117f914d6960a204d1af03966, 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 fcdd5f04c1fffa48b2df2a94e9348af681e8c85a && git checkout fcdd5f04c1fffa48b2df2a94e9348af681e8c85a
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin d8024f050e1f457117f914d6960a204d1af03966 2c4bc2903701f758f1c6c5aa107a3c597888e9de && git checkout -B drift-repro d8024f050e1f457117f914d6960a204d1af03966 && git merge --no-ff 2c4bc2903701f758f1c6c5aa107a3c597888e9de
node scripts/docs-audit/affected-docs.mjs --json d8024f050e1f457117f914d6960a204d1af03966

⚠️ 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 d8024f050e1f457117f914d6960a204d1af03966 → pass the list as
args.docs, on the commit named under Which tree this was computed on.