docs(spec): FlowSchema terminal messages are every-terminal-run, not screen-flow-only (#9512)

[os-steve]

Fixes#9512

What

FlowSchema.successMessage/errorMessage (packages/spec/src/automation/flow.zod.ts)
still described themselves as screen-flow-only text, but #9414 (merged as PR #9514,
5aadce374) made the engine carry the pair on every terminal flow run, not just resumed
screen flows. This PR rewrites the JSDoc and both describe() strings to state that
reality and to explicitly kill the screen-flow-only reading — that reading is the exact
premise of a route considered and rejected at #9414's triage ("narrow the contract
text to say these are screen-flow / resume-only"), and leaving the text phrased that way
kept the rejected route's premise alive and reachable.

Before / after

packages/spec/src/automation/flow.zod.ts:618-635

 /**
- * Terminal messages for `screen`-flow runs. When the run reaches a terminal- * state, the UI flow-runner shows `successMessage` instead of a generic- * "Done" toast, and `errorMessage` instead of the raw error. Both are- * surfaced on the terminal {@link AutomationResult} (`successMessage` /- * `errorMessage`). Plain strings; `{var}` is NOT interpolated here.+ * Terminal messages for the flow. Since #9414, carried on EVERY terminal+ * run — `execute()`'s exit, both `retryExecution()` exits, and the resume+ * exit — not only on `screen`-flow runs. The pair is set on the terminal+ * {@link AutomationResult} (`successMessage` on success, `errorMessage` on+ * failure) returned by any trigger route (e.g.+ * `POST /api/v1/automation/:name/trigger`), whether or not a UI is+ * listening; a `screen`-flow run additionally has the UI flow-runner show+ * `successMessage` as a toast instead of a generic "Done", and+ * `errorMessage` instead of the raw error. Reading this pair as+ * screen-flow-only was the alternative considered and rejected at #9414's+ * triage — narrowing the text would delete a declared, documented,+ * console-consumed capability to make a bug disappear — so treat the+ * screen-flow toast as one consumer, not the whole contract. Plain+ * strings; `{var}` is NOT interpolated here.
*/
- successMessage: z.string().optional().describe('Toast shown when a screen flow completes (defaults to a generic "Done").'),- errorMessage: z.string().optional().describe('Toast shown when a screen flow fails (defaults to the raw error).'),+ successMessage: z.string().optional().describe('Message carried on AutomationResult for every terminal run (not only screen flows); the screen-flow UI shows it as a toast instead of a generic "Done".'),+ errorMessage: z.string().optional().describe('Message carried on AutomationResult for every terminal run (not only screen flows); the screen-flow UI shows it as a toast instead of the raw error.'),

Wording mirrors the general phrasing contracts/automation-service.ts's AutomationResult
has always used ("successMessage is set on terminal success, errorMessage on
failure") — that file is untouched by this PR.

The two mirrored reference pages were regenerated via pnpm --filter @objectstack/spec gen:docs and committed as the generator produced them, no hand edits:

• content/docs/references/automation/flow.mdx
• content/docs/references/api/automation-api.mdx

Both diffs are the identical two-line describe() text swap (table row for
successMessage / errorMessage), nothing else moved.

Engine-site verification (re-verified on current main, not inherited)

git rev-parse HEAD at worktree creation: 02ebb6f5b (current main, ancestor of the
unlock comment's 5aadce374). grep -n successMessage packages/services/service-automation/src/engine.ts
→ 5 sites, matching the unlock comment's measurement:

• engine.ts:3245 — explanatory comment (execute()'s terminal-success exit)
• engine.ts:3263 — execute()'s terminal-success return: successMessage: flow.successMessage,
• engine.ts:4104 — the resume/bubble-up terminal exit: successMessage: flow.successMessage,
• engine.ts:6350 — explanatory comment (retryExecution()'s success exit)
• engine.ts:6352 — retryExecution()'s success return: successMessage: flow.successMessage, …

Three real assignment sites (execute(), the resume exit, retryExecution()'s success
exit) plus two explanatory comments = the 5 grep hits. Confirms the pair is carried on
every terminal exit, not only the two resumeInternal sites that existed pre-#9414.

authorable-surface re-verification (measured here, not inherited)

Re-ran pnpm --filter @objectstack/spec check:generated after the edit:

✓ check:authorable-surface authorable-surface/ + authorable-defaults/ (+ its .base.json anchor) + JSON schemas

git status --porcelain shows no change under packages/spec/authorable-surface/ or
packages/spec/authorable-surface.base.json — the filer's claim holds: the describe()
text is not part of that generated artifact. This stays a text change, not a spec-surface
change.

Tests / gates

Head verified: e89d5c48b (this PR's tip; the gate run below is on this exact tree).

• pnpm --filter @objectstack/spec build — clean.
• pnpm --filter @objectstack/spec check:generated — 13/13 green (docs regenerated once,
  then clean; authorable-surface untouched — see above).
• pnpm --filter @objectstack/spec test — 409 test files / 10937 tests passed.
• pnpm --filter @objectstack/spec typecheck — clean (tsc --noEmit, check:scripts-typecheck,
  check:test-typecheck).
• node scripts/check-nul-bytes.mjs — OK, 6150 files scanned.
• Named gates from node scripts/pm/dispatch-gates.mjs packages/spec/src/automation/flow.zod.ts,
  all green: check:cross-package-test-inputs, check:doc-formula-expressions,
  check:empty-state, check:liveness, check:merge-driver, check:spec-parsed-alias,
  check:strictness-ledger, check:type-source-resolution, check:variant-docs,
  scripts/check-cross-package-test-inputs.mjs, scripts/docs-audit/check-affected-docs.mjs.
• node scripts/check-dev-prereqs.mjs — not run to green: it requires the full
  monorepo dist/ (64 of 67 packages unbuilt in this fresh worktree), which is unrelated
  to this text-only diff and out of scope for targeted local verification. CI's lint.yml
  pipeline builds the full workspace before this step runs.

Scope

Text only: packages/spec/src/automation/flow.zod.ts's JSDoc + two describe() strings,
the two generated reference pages, and a patch changeset for @objectstack/spec. No
engine edits, no contracts/automation-service.ts edits, no schema/shape change, no
content/docs/releases/ edit.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/automation/flows.mdx(via FlowSchema (symbol), /api/v1/automation/:name/trigger (route))
• content/docs/protocol/kernel/http-protocol.mdx(via /api/v1/automation/:name/trigger (route))
• content/docs/ui/actions.mdx(via /api/v1/automation/:name/trigger (route))

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

• content/docs/releases/v17.mdx(via FlowSchema (symbol))

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

What this run could not see

Coarse fallback — 113 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 b348ac2c24100e26bf88486f704e3064a2e1fee6 → packageMentionDocs.

Which tree this was computed on

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

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