feat(spec): refuse the confirmText + params pair on ActionSchema, scoped by schema boundary - #7972

Fixes #7428

An action that declares confirmText beside a non-empty params opens two sequential dialogs for one decision — the console runner awaits the confirm, then the param prompt, so the first dialog already reads as "the action ran" while nothing has been sent. #7278 (PR #7592) and #7309 (PR #7827) repaired the sites that shipped it. Repairing instances does not stop the next one being written; this PR is the structural half.

The guard

A .refine appended to ActionSchema's chain in packages/spec/src/ui/action.zod.ts, refusing confirmText + a non-empty params array at path: ['confirmText'] — the key that has to go, since pointing at params would tell the author to delete the inputs they need. The message names both keys, states the user-visible consequence, points at the remedy (description), warns off the remedy's trap (ai.description), and names the two shapes that stay legal.

Census evidence (the premise, re-measured — not assumed)

Re-ran the card's brace-balanced scan on origin/main @ 8d80e12 before writing a line of the guard, and again on the final merged tree. Predicate per the #7309 notes recorded on the card: object literals declaring both keys at their own depth, with params: [ non-empty — which is what separates real sites from the schema definition files (action.zod.ts, bulk-action.zod.ts, translation.zod.ts declare both keys) and the generated translation bundles (params is a record there, not an array).

So the PM's mechanism premise holds: the ActionSchema census is already 0 after #7592 and #7827, and the refusal breaks nothing that ships today. The only hits anywhere in the repo are the four showcase bulkActionDefs (plus one bulk-action.test.ts fixture), all on the surface the guard is scoped away from.

The census had one blind spot, found after opening this PR — see "Docs" below.

Ruling provenance

The card left three design questions open. They were answered by the PM's claim comment of 2026-08-12T08:24Z and its correction minutes later, which in turn defers to the measured correction of 2026-08-11T17:29Z on the same thread. Quoted rather than paraphrased:

From the 17:29Z measured correction — the finding that scoped this guard:

Measured answer: there is a legitimate shape, and it is the bulk-action surface. The distinction is not "params all optional" as the card guessed — it is which schema renders the pair into how many dialogs. Encode the guard on the schema boundary, not on a heuristic about param optionality.

and its reasoning, which this PR's tests pin verbatim in substance:

(b) They are not the defect. Per the schema's own contract a bulk def renders one dialog: params are "inputs collected once before the run", confirmText is "shown above the affected-record summary", and decisively, a required param "blocks the Confirm button until a value is present." A param cannot block a button in a dialog that has not opened yet

From the PM's correction comment:

• The 4 showcase sites are bulkActionDefs (BulkActionDefSchema) … they are correct, struck from the target set, and MUST NOT be migrated.
• Acceptance is the ActionSchema census returns 0
• Ruling 2 stands in its corrected form … the guard is encoded on the schema boundary — a refusal on ActionSchema's pair that structurally cannot fire on BulkActionDefSchema — plus a pinning test that the bulk pairing stays accepted (so a future "helpful" widening of the guard goes red). Not a param-optionality heuristic.
• Ruling 1 (refuse severity) and 3 (no description requirement) unchanged.

All four are implemented as ruled: refuse severity, schema-boundary scoping with the bulk pinning test, no added description requirement, and no migration of the showcase sites.

Scoping is structural, not conditional

The refusal is on ActionSchema's refine chain. BulkActionDefSchema is a separate strictObject in bulk-action.zod.ts with its own superRefine, so no refinement here can reach it. InlineActionSchema .pick()s from the shared field factory rather than deriving from this chain, so it is out of reach too — and it deliberately does not pick description, so the #7278 remedy has no slot on that surface to move a question into. That is the same argument the 17:29Z correction used to strike the bulk defs, which is why inline is recorded as an open question rather than quietly swept in.

action-confirm-params-guard.test.ts (12 tests) pins both directions:

• Refusal — the pair; the localized-map form of confirmText (a truthiness check written against a string would miss it); the path; and the message substance, asserted phrase by phrase rather than as success === false.
• Non-refusal — a param-LESS action; params: []; params + description (the shape approvals: sys_approval_request.approval_reject / approval_recall declare both confirmText and params, so one decision opens two sequential dialogs #7278 migrated to — if this goes red the guard has swallowed its own remedy); and params with no description, pinning ruling 3.
• Boundary — BulkActionDefSchema still accepts confirmText + non-empty params, with the showcase's own set_labels literal; that the two schemas are independent; and InlineActionSchema's current acceptance, with the reason recorded.

One test changed shape against a measurement. I had assumed aliases (confirm → confirmText, inputs → params) were folded before the refinements, and wrote a test asserting the guard fires on the aliased pair. It does not — this repo rejects a near-miss with a rename arrow rather than folding it (Prime Directive #12), so the aliased pair is refused one layer earlier by key recognition and never reaches the refinement. The test now pins that actual mechanism, since the guard's coverage claim depends on it.

Reverse verification

Guard committed first, then reverted alone (tests kept), per the discipline that a restore point must actually exist.

• Predicted: 5 red — the 4 guard-dependent assertions plus the defineAction throw.
• Measured: 4 red — refuses the pair, says WHY, localized-map form, throws from defineAction. All 8 acceptance/boundary tests stayed green, as they must: they assert success === true, which a schema with no guard satisfies trivially.
• The miss is informative, not noise. The alias test stayed green because the alias rejection is upstream of the guard and does not depend on it — which is exactly the mechanism the corrected test now documents. My prediction had miscounted it as guard-dependent.
• Restored via git checkout <branch> -- <path> from the commit; git diff HEAD empty (byte-identical, not a matching line count), 12/12 green again.

Docs — a stale example the census could not see

The docs-drift bot's list pointed at content/docs/protocol/objectui/actions.mdx, and two of its "Real-World Examples" — disable_oauth_application and rotate_client_secret — declared confirmText beside params. Both were already stale against main: the real actions moved the question to description in #7827. This PR makes the documented shape fail to parse, so a doc that was merely out of date became a doc that teaches metadata the spec refuses.

Fixed in b5b4ff8: the two examples now mirror what sys-oauth-application.object.ts actually ships, and the confirmText bullet above them states the constraint (param-LESS only; question on description; not ai.description; bulk defs unaffected).

Why the census missed them: those examples are YAML, and the card's acceptance scan is brace-balanced — it can only see TS/TS-like object literals. A YAML-aware re-scan across all content/docs/** found exactly these two and nothing else. Worth knowing if the census is ever re-run as a gate: it measures source declarations, not documented ones.

Gates

All run locally, foreground, on the merged tree.

Downstream blast radius, since a refusal is only safe if consumers still parse: platform-objects 342 ✅, plugin-approvals 458 ✅, plugin-security 1001 ✅, example-showcase 193 ✅ — the last being the live proof the four bulk defs still validate.

Two gate results needed a prerequisite rather than a fix, both stale-build-state per the AGENTS.md §9 table, both cleared by building rather than asserted away: check:i18n needed the built CLI, and examples/app-showcase typecheck reported four Cannot find module '@objectstack/connector-*' errors until those packages were built (then clean).

⚠️ Regenerated baseline — this joins the spec serial relay

The diff regenerates content/docs/references/ui/action.mdx (via gen:docs), because the confirmText .describe() now names the constraint so an author meets it in the reference and not only in the error.

Worth a reviewer's eye on the wording: that one field factory renders both the ActionSchema table and the InlineAction table, where the guard does not apply. My first draft said "pairing it with a non-empty params is REFUSED" unqualified, which would have published a documented refusal that does not exist on the inline surface — a declared≠enforced inversion. It reads "on a registered action" for that reason.

No other generated artifact moved; authorable-surface is unchanged (a refinement adds no authorable key), and the anchor was never hand-edited.

Changeset

@objectstack/spec minor — an acceptance narrowing is user-visible. It carries the migration diff, the ai.description trap, and each of the four shapes deliberately left accepted.

Out of scope

packages/metadata-protocol/src/protocol.ts carries a hand-written JSON-Schema mirror of the action shape that declares confirmText and params with no equivalent constraint. Not touched here — a second, independently-maintained contract is a finding of its own rather than a rider on this guard.

Generated by Claude Code