action.zod.ts

// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.

import { z } from 'zod';
import { retiredKey } from '../shared/retired-key';
import { FieldType } from '../data/field.zod';
// #6970 — the authoring gate on `defaultValue` runs the SAME value contract the
// dispatcher runs at submit, through the shared `defaultValue` discriminator
// module (#7127 — one module, two consumers; the literal-check core lives
// there). Imported file-directly (never via a barrel): `default-value-shape`
// and `field-value.zod` reach only `shared/` + `data/` + `system/`, and
// `action-params.zod` only `data/` + `api/` + `shared/`, so none can close a
// cycle back to `ui/`.
import { MULTI_CAPABLE_TYPES, isMultiValueField } from '../data/field-value.zod';
import { checkLiteralDefaultValue } from '../data/default-value-shape';
import { isActionParamValuePresent } from './action-params.zod';
// #17319 — the action's `execution` declaration is the bulk def's OWN enum,
// imported rather than re-declared: the maintainer ruling (decision batch #121
// item 3) admits no third spelling of the two dispatch contracts, and sharing
// the schema object is the only form of that which cannot drift. Imported
// file-directly for the reason the neighbours above are: `bulk-action.zod`
// reaches only `shared/` + `data/`, so it cannot close a cycle back to `ui/`.
import { BulkActionExecutionSchema } from './bulk-action.zod';
import { SnakeCaseIdentifierSchema } from '../shared/identifiers.zod';
import { EvaluatedExpressionInputSchema } from '../shared/expression.zod';
import { evaluatedExpressionUnionRefusal } from '../shared/evaluated-slot-union';
import { I18nLabelSchema } from './i18n.zod';
import { HookBodySchema } from '../data/hook-body.zod';
// Imported file-directly (not via the kernel barrel): the module is
// deliberately import-free, so this cannot introduce a cycle.
import { PUBLIC_AUTH_FEATURE_NAMES, lowerRequiresFeature } from '../kernel/public-auth-features';
import { MEMBERSHIP_REACH_NAMES, lowerRequiresMembershipReach } from '../identity/membership-reach';
import { strictUnknownKeyError } from '../shared/suggestions.zod';
import { strictObject } from '../shared/strict-object';
import { MetadataProtectionFields } from '../kernel/metadata-protection.zod';
import { lazySchema } from '../shared/lazy-schema';
import { aiJsonSchemaSlot } from '../shared/ai-json-schema-slot';
import { ACTION_TARGET_ALIASES } from './action-target-aliases';

/**
 * Semantic near-misses — a different **word** for the same intent, usually
 * borrowed from a neighbouring schema where that word is correct. Edit distance
 * cannot reach these (`visibleWhen` → `visible` is 4 apart), so they are named
 * explicitly; plain case/underscore slips (`help_text` → `helpText`) are left to
 * the factory's edit-distance fallback. Mirrors the `FIELD_TYPE_ALIASES`
 * pattern in `shared/suggestions.zod.ts`.
 *
 * Keys are matched case-insensitively with separators removed (see
 * {@link strictUnknownKeyError}).
 */
const ACTION_PARAM_KEY_ALIASES: Readonly<Record<string, string>> = {
  // The objectql/runtime field shape spells a lookup target `reference_to`, and
  // objectui's resolved param calls it `referenceTo`. Dropping either is the
  // exact #3405 failure: a targetless picker degrades to a raw-UUID text box.
  referenceto: 'reference',
  referenceobject: 'reference',
  referencedobject: 'reference',
  targetobject: 'reference',
  // ADR-0089 made `visibleWhen` the canonical predicate on view/page schemas.
  // An author who learned it there would silently lose a param's capability
  // gate here — the param would render unconditionally.
  visiblewhen: 'visible',
  visibleon: 'visible',
  visibility: 'visible',
  description: 'helpText',
  help: 'helpText',
  default: 'defaultValue',
  // The words an author borrows from `FieldSchema` (`readonly`) or widget
  // vocabulary (`disabled`) for "the user must not edit this". On a param the
  // declared contract is `carryOver` (commit 0e4e51b0a): non-editable AND still
  // submitted verbatim — which is the half `readonly`'s field semantics
  // (write-path strip) would get exactly wrong here.
  readonly: 'carryOver',
  disabled: 'carryOver',
};

/**
 * Custom zod `error` for the `.strict()` {@link ActionParamSchema} (#3405 part 3).
 *
 * Before this, the schema was zod-default `.strip`: a key it does not declare was
 * **silently discarded**, and the param went on parsing. That is how a correctly
 * intended `reference: 'sys_user'` became a text box asking a human to paste a
 * UUID, with no error anywhere — the config was eaten and the UI lied about why
 * (ADR-0078 no-silently-inert-metadata, ADR-0049 enforce-or-remove).
 *
 * Built by {@link strictUnknownKeyError} — the shared factory this schema's
 * hand-rolled #3746 map was generalized into (#4001): it names the offending
 * key(s) and, when one is a recognisable spelling of a declared key, points at
 * the canonical one.
 */
/**
 * Guidance for `color` — declared one layer down on `SelectOptionSchema`
 * (`data/field.zod.ts`), and still not a key of THIS shape.
 *
 * `visibleWhen` shared this text until #5016. The two were separated on
 * measurement rather than on symmetry: both are declared on a FIELD's option
 * list, but only one of them has a consumer an ACTION PARAM's option list can
 * reach.
 *
 *  - `visibleWhen` is now declared below, because the reader is on this path.
 *    An inline param's `options` are lowered VERBATIM (objectui
 *    `resolveActionParam`'s inline branch → `paramToField` →
 *    `getLazyFieldWidget`), and every option widget narrows the offered set
 *    through `useCascadingOptions` → `resolveCascadingOptions`, which reads
 *    exactly this key (ADR-0058 / objectui#2284).
 *  - `color` has no reader here. It is consumed only where a STORED value is
 *    displayed — the grid cell / detail badge (`SelectCellRenderer`) and the
 *    state-machine viewer. An action param's option list never reaches those:
 *    the dialog builds an input from it, submits the picked value, and drops
 *    the list. The select / multiselect / radio / checkboxes INPUT widgets read
 *    `label`, `value` and `visibleWhen`, and nothing else.
 *
 * So `color` here is not "not yet, pending #5016" — #5016 measured it and the
 * answer is no. Declaring it would add exactly the key that parses clean and
 * changes nothing (ADR-0078), and would delete the only sentence telling an
 * author where the vocabulary IS real.
 */
const actionParamOptionColorGuidance =
  '`color` is a per-option key of a FIELD\'s option list (`SelectOptionSchema` in '
  + '`data/field.zod.ts`), read where a STORED value is displayed — the grid cell and the '
  + 'detail badge. An action param\'s options are never rendered that way: the dialog builds '
  + 'an INPUT from them, submits the picked value and discards the list, so no renderer would '
  + 'read `color` here even if this shape declared it (measured this). Drop the key — to '
  + 'colour the value once it is stored, declare the option list on the FIELD.';

/**
 * Guidance for per-option keys that no spec shape declares at all.
 *
 * `icon` / `disabled` exist only in objectui's internal `SelectOptionMetadata`
 * interface, which nothing populates from metadata and no widget reads — so
 * unlike `color` / `visibleWhen` there is no "one layer down" to point at, and
 * saying there was would be the false-prescription class this campaign has
 * already shipped four times (ledger finding 18).
 *
 * #5016 re-measured both before deciding whether to converge the spec on
 * objectui's interface (its option C) and found the same thing the batch-14
 * pass did: `SelectOptionMetadata.icon` has no reader anywhere in objectui, and
 * every `disabled` in the four option widgets is the FIELD-level `props.disabled`,
 * never a per-option one. C was therefore not taken.
 */
const actionParamOptionUndeclaredAnywhere = (key: 'icon' | 'disabled'): string =>
  `no option shape in the spec declares \`${key}\` — not this one, and not the field-level `
  + `\`SelectOptionSchema\`. It exists only inside objectui's own `
  + `\`SelectOptionMetadata\` type, which no metadata path populates and no widget reads. An `
  + `action param's options are \`{ label, value, visibleWhen }\`; drop the key.`;

/**
 * Action Parameter Schema
 *
 * Defines inputs required before executing an action.
 *
 * Two declaration modes:
 *
 * 1. **Field-backed** (preferred) — reference an existing object field; the
 *    runtime resolves the field's label (i18n), type, validation rules,
 *    options, placeholder, help text, and widget mapping from object
 *    metadata. Cross-object references use `objectOverride`.
 *
 *    ```ts
 *    params: [
 *      { field: 'email' },                                 // same object
 *      { field: 'role', objectOverride: 'sys_member' },    // different object
 *    ]
 *    ```
 *
 * 2. **Inline** (legacy / bespoke) — declare `name`, `label`, `type` etc.
 *    inline when no matching object field exists. Inline values may also be
 *    used alongside `field` to override individual properties. A `lookup` /
 *    `master_detail` param declared this way MUST name its target object via
 *    `reference` — there is no field to inherit it from:
 *
 *    ```ts
 *    params: [
 *      { name: 'inspector', label: 'Inspector', type: 'lookup', reference: 'sys_user' },
 *    ]
 *    ```
 *
 * `name` is required unless `field` is provided (in which case it defaults
 * to the field name and is used as the request-body key).
 */
export const ActionParamSchema = lazySchema(() => strictObject(
  {
    surface: 'this action param',
    aliases: ACTION_PARAM_KEY_ALIASES,
    history:
      'Until this shape was closed, these were dropped silently — the param still parsed, so a mis-spelled ' +
      'config shipped as a control that quietly ignored it.',
  },
  {
  /** Request-body key. Defaults to `field` when `field` is set. */
  name: z.string().optional().meta({ title: 'Name' }),
  /** Reference an existing object field for label/type/validation/options. */
  field: SnakeCaseIdentifierSchema.optional().meta({ title: 'Field' }),
  /** Object that owns the referenced field (defaults to the action's parent object). */
  objectOverride: SnakeCaseIdentifierSchema.optional().meta({ title: 'Object Override' }),
  /** Overrides the resolved field label (or sets it for inline params). */
  label: I18nLabelSchema.optional().meta({ title: 'Label' }),
  /** Overrides the resolved field type (or sets it for inline params). */
  type: FieldType.optional().meta({ title: 'Type' }),
  /**
   * Required override; when omitted defaults to `false`. Consumers that wish
   * to inherit the underlying field's `required` flag should leave this
   * undefined in the source schema and resolve at runtime (the dialog
   * renderers check truthiness, so `false === undefined` for UI purposes).
   */
  required: z.boolean().optional().default(false).meta({ title: 'Required' }),
  /**
   * Select/picklist options override.
   *
   * #4001 批 14 closed the OPTION ENTRY. `ActionParamSchema` has been strict
   * since #3405/#3746 — the file's template — but **strictness does not
   * recurse**, so the entries inside `options` were still zod-default strip:
   * the param was validated, its option list was not, and the shell reported
   * success either way.
   *
   * **`strictObject`, not `.passthrough()` — measured, not inherited from the
   * sibling.** `bulk-action.zod.ts`'s option entry went `.passthrough()`
   * (#4909) and the reasoning there was specific: an authored bulk-action def
   * is "left as-authored", reaches the grid VERBATIM, and objectui's
   * `BulkActionParam` declares an explicit `[key: string]: unknown` catch-all,
   * so `bulkParamToField`'s spread carries extras into a genuinely open widget
   * vocabulary. Neither half of that holds here, and both were re-measured on
   * 2026-08-03 rather than assumed:
   *
   * 1. **This surface has a parsing door, and the door already strips.** An
   *    action is a registered metadata type, so an authored param reaches
   *    objectui through `getMetadataTypeSchema('action')`
   *    (`MetadataManager.validate` / `GET /api/v1/meta` / the Studio form).
   *    Parsing a real action whose option carried
   *    `color` / `icon` / `disabled` / `visibleWhen` returned
   *    `{"label":"Overload","value":"overload"}` — every extra already gone,
   *    silently, before any renderer sees it. `.passthrough()` would therefore
   *    not be preserving a live flow; it would be *opening* one.
   * 2. **The consumer type here is CLOSED, not a catch-all.** The dialog lowers
   *    a param through `paramToField` into field metadata, where the option
   *    vocabulary is objectui's `SelectOptionMetadata` — an enumerable
   *    interface (`label` / `value` / `color` / `icon` / `disabled` /
   *    `visibleWhen`), not an index signature. A closed target vocabulary is
   *    exactly the case where declaring beats tolerating.
   *
   * So the answer legitimately differs from the sibling's. What that left was a
   * real, separable question — *should* an action param's option list speak the
   * per-option vocabulary that a FIELD's `options` (`SelectOptionSchema`,
   * `data/field.zod.ts`) already declares? That was filed as #5016 rather than
   * guessed at here, and #5016 answered it **per key, on measurement**:
   *
   * - **`visibleWhen` — opened.** The reader is on this exact path and it works
   *   today. An inline param's `options` are lowered VERBATIM (objectui
   *   `resolveActionParam`'s inline branch does `options: param.options`;
   *   `ActionParamDialog` re-spreads each entry to localise `label`;
   *   `paramToField` passes the array straight into the widget's field
   *   metadata), and `SelectField` / `MultiSelectField` / `RadioField` /
   *   `CheckboxesField` all narrow the offered set through
   *   `useCascadingOptions` → `resolveCascadingOptions`, which reads this key
   *   and accepts the `{ dialect, source }` envelope
   *   `EvaluatedExpressionInputSchema` emits. The spec door was the ONLY thing between an author and a working
   *   per-option gate.
   * - **`color` / `default` — not opened**, and `icon` / `disabled` not added to
   *   `SelectOptionSchema` either (#5016's option C). None has a reader an
   *   action param's option list can reach; each keeps a `guidance` entry
   *   saying where the vocabulary IS real. Declaring them would be the
   *   parses-clean-changes-nothing key ADR-0078 exists to keep out — and for
   *   `default` it would actively mislead, since a dialog param defaults
   *   through `defaultValue` one level up.
   *
   * **What this does NOT fix**, deliberately, because it is objectui's and not
   * the spec's: a FIELD-BACKED param that inherits its list instead of declaring
   * one still loses the key. `resolveActionParam` reaches
   * `param.options ?? normaliseOptions(field.options, …)`, and `normaliseOptions`
   * rebuilds every inherited entry as `{ label, value }`. That drop predates
   * this change, is invisible to it (an authored `options` array wins over the
   * inherited one), and is tracked in objectui — so the guidance below still
   * refuses to prescribe "make it field-backed and inherit" (ledger finding 18:
   * a confidently wrong prescription is worse than none).
   *
   * The aliases are anchored on `SelectOptionSchema`'s own curated table (the
   * same idea, one layer down) rather than on edit distance, and deliberately
   * carry across ONLY the entries whose target this shape actually declares —
   * `never suggest a key the schema cannot accept` (ledger finding 12).
   */
  options: z.array(strictObject({
    surface: 'this action param option',
    history:
      'Until this shape was closed these were dropped silently — the param still '
      + 'rendered its picker, minus whatever the key was meant to colour, gate or disable.',
    aliases: {
      // Carried over from `SelectOptionSchema`'s table — same idea, and these
      // five point at keys THIS shape declares.
      text: 'label',
      name: 'label',
      title: 'label',
      key: 'value',
      id: 'value',
      // objectql/import-export spell the stored side this way.
      optionValue: 'value',
      optionLabel: 'label',
      displayName: 'label',
      // #5016 declared `visibleWhen` here, so `SelectOptionSchema`'s two
      // spellings for it now point at a key this shape accepts and can carry
      // across under the same finding-12 rule as the five above.
      visible: 'visibleWhen',
      showWhen: 'visibleWhen',
    },
    guidance: {
      // The per-option keys that are real one layer down but have no reader on
      // THIS path, plus the two that no spec shape declares at all. Each says
      // where the vocabulary lives and — critically — does NOT promise that a
      // field-backed param inherits it: `resolveActionParams`' `normaliseOptions`
      // rebuilds each inherited entry as `{ label, value }`, so that promise
      // would be false in exactly the way ledger finding 18 warns about.
      //
      // `visibleWhen` is deliberately absent: it is a declared key now, and
      // `guidance` is consulted only from the `unrecognized_keys` path, so an
      // entry for it would be dead prose (`shared/alias-integrity.test.ts`).
      color: actionParamOptionColorGuidance,
      icon: actionParamOptionUndeclaredAnywhere('icon'),
      disabled: actionParamOptionUndeclaredAnywhere('disabled'),
      default: '`default` on an OPTION is the field-level picklist default (`SelectOptionSchema.default`). A dialog param defaults through `defaultValue` on the PARAM itself, one level up — write `defaultValue: \'<value>\'` there.',
    },
  }, {
    label: I18nLabelSchema,
    value: z.string(),
    /**
     * Per-option visibility predicate (CEL) — the option is offered only when
     * this evaluates TRUE. Omit = always available (#5016).
     *
     * Same key, same engine and same binding environment as
     * `SelectOptionSchema.visibleWhen` one layer down, so one vocabulary covers
     * both surfaces: it expresses dependent options (`record.country == 'cn'`)
     * AND role/context gating (`'admin' in current_user.positions`). In a
     * dialog `record` is the live param bag overlaid on the row, so a param can
     * gate its options on a SIBLING param the user has already filled.
     *
     * ⚠️ Client-side hiding is UX, not authorization. `enforceActionParams`
     * validates the submitted value against this param's option VALUES
     * (ADR-0104 D2) — it does not evaluate per-option `visibleWhen` — so an
     * option gated for access-control reasons must also be refused by the
     * action's own body or a permission check. Hiding it in the dropdown is
     * bypassable.
     */
    visibleWhen: EvaluatedExpressionInputSchema.optional().describe("Per-option visibility predicate (CEL) — option is offered only when TRUE (else omitted). Same env as the field-level per-option visibleWhen (record + current_user). e.g. P`record.tier == 'gold'`"),
  })).optional().meta({ title: 'Options' }),
  /** Placeholder override. */
  placeholder: z.string().optional().meta({ title: 'Placeholder' }),
  /** Help/description override. */
  helpText: z.string().optional().meta({ title: 'Help Text' }),
  /**
   * Default value for the dialog input — prefilled into the control when the
   * dialog opens, and SUBMITTED VERBATIM if the user does not touch the field
   * (objectui `ActionParamDialog` seeds its state with `p.defaultValue` and
   * resolves no tokens against it).
   *
   * Because it is submitted verbatim it must satisfy this param's own value
   * contract — the shape checked below through the SAME `valueSchemaFor` the
   * dispatcher runs at submit. This is a LITERAL, not an expression surface:
   * unlike a FIELD's `defaultValue`, which the ObjectQL engine resolves for
   * runtime tokens (`current_user`, CEL `today()`; ROADMAP §M9.9b), nothing on
   * the action-param path interprets this value.
   */
  defaultValue: z.unknown().optional().meta({ title: 'Default Value' }),
  /**
   * Widget config for inline params (field-backed params inherit these from
   * the referenced field at runtime; inline values override). The param
   * dialog renders every param through the same field-widget renderer the
   * object form uses (objectui ADR-0059), so these mirror the corresponding
   * `FieldSchema` knobs.
   */
  /** Allow multiple values (file/image/lookup/user params → array value). */
  multiple: z.boolean().optional().describe('Allow multiple values (array value shape); mirrors FieldSchema.multiple.').meta({ title: 'Multiple' }),
  /** Accepted upload types (MIME types / extensions) for `file`/`image` params. */
  accept: z.array(z.string()).optional().describe('Accepted upload types (MIME types / extensions) for file/image params.').meta({ title: 'Accepted Types' }),
  /** Max upload size in bytes for `file`/`image` params. */
  maxSize: z.number().int().positive().optional().describe('Max upload size in bytes for file/image params.').meta({ title: 'Max Size (bytes)' }),
  /**
   * Reference target for an inline `lookup` / `master_detail` param — the
   * object whose records the picker searches. Field-backed params inherit it
   * from the referenced field, so it is only needed inline.
   *
   * Without it the dialog cannot query anything and degrades to a plain text
   * input asking for a raw record id, which is unusable for a human — hence
   * the `.refine()` below rejects a targetless lookup param at parse time.
   *
   * Key name deliberately mirrors `FieldSchema.reference` so the same spelling
   * works in both places.
   */
  reference: SnakeCaseIdentifierSchema.optional().describe('Reference target object for inline lookup/master_detail params; mirrors FieldSchema.reference.').meta({ title: 'Reference Object' }),
  /**
   * When true, the param's default value is pulled from the current row record
   * (key = the resolved field name) when the action runs from a list_item
   * context. Useful for edit dialogs that pre-fill from the selected row.
   */
  defaultFromRow: z.boolean().optional().meta({ title: 'Default From Row' }),
  /**
   * Carry-over declaration (maintainer ruling 2026-08-25, commit 0e4e51b0a): the param's value is
   * carried through the dialog rather than collected from the user — seeded
   * from the current row (`defaultFromRow` is required alongside), rendered as
   * a NON-EDITABLE summary, and submitted VERBATIM in the request body.
   *
   * The knob exists because neither neighbour expresses this contract:
   *
   * - `visible: false` omits the param from the dialog AND from the submission
   *   — the measurement commit 0e4e51b0a records; a clone action that hid its facet params this way
   *   would silently stop copying them, which is exactly the defect shape
   *   commit 5cb62d88b fixed in `clone_permission_set`.
   * - Leaving the param editable invites the failure the ruling names: the
   *   clone dialog offered `member_default`'s `row_level_security` — a JSON
   *   array of 17+ policy objects — as a prefilled textarea on the platform's
   *   SANCTIONED clone path, where a hand-mangled-but-valid-JSON edit produces
   *   a clone granting MORE than its base, accepted without a word
   *   (`PermissionSetSchema` validates shape, not intent).
   *
   * "Not editable" is expressed by contract and enforced by the renderer
   * (maintainer ruling 2026-08-25, recommendation A, commit 0e4e51b0a): objectui's
   * `ActionParamDialog` renders a declared carry-over as a read-only summary
   * while keeping the seeded value in its submit state, so what is declared is
   * what is sent. Requiring `defaultFromRow: true` is the declared = enforced
   * half at authoring time — a carry-over with no row seed would render an
   * empty locked control and submit nothing, which is an authoring error, not
   * a rendering decision (ADR-0078).
   */
  carryOver: z.boolean().optional().describe(
    'Carry-over param: seed the value from the current row (requires defaultFromRow: true), '
    + 'render it as a non-editable summary in the dialog, and submit it verbatim in the request '
    + 'body. Unlike `visible: false` (which omits the param from the submission entirely), a '
    + 'carry-over param is always sent.',
  ).meta({ title: 'Carry Over' }),
  /**
   * Visibility predicate (CEL) — same scope as the action-level `visible`
   * (`current_user` / `data` / `features`). When it evaluates false the
   * dialog omits this param entirely. Use it to hide a param that the backend
   * only accepts under an opt-in capability, e.g. the create-user `phoneNumber`
   * param gated on `features.phoneNumber` so the form never offers a field the
   * default backend rejects. Absent = always visible.
   */
  visible: EvaluatedExpressionInputSchema.optional().describe('Param visibility predicate (CEL); omits the param when false.').meta({ title: 'Visible When' }),
  /**
   * Declarative capability gate (#2874): name a public auth feature flag
   * (see `PUBLIC_AUTH_FEATURES` in `@objectstack/spec/kernel`) and the schema
   * lowers it at parse time into the canonical `visible` predicate —
   * `features.X == true` (opt-in flag) or `features.X != false` (default-on),
   * AND-composed with any explicit `visible`. The sugar key is stripped from
   * the parsed output, so renderers/lint only ever see `visible`. Prefer this
   * over a hand-written `features.*` predicate: the flag name is
   * enum-checked and the gate/registry stay in lockstep.
   */
  requiresFeature: z.enum(PUBLIC_AUTH_FEATURE_NAMES).optional().describe('Public auth feature flag gating this param; lowered into `visible` at parse time.').meta({ title: 'Requires Feature' }),
}).refine(
  (p) => Boolean(p.name) || Boolean(p.field),
  { message: 'ActionParam requires either "name" or "field"' },
).refine(
  // An INLINE record-picker param must name its target object. Only inline
  // params are checked: a field-backed one inherits the target from the
  // referenced field's metadata, which is not visible at parse time.
  (p) => !(!p.field && (p.type === 'lookup' || p.type === 'master_detail') && !p.reference),
  {
    path: ['reference'],
    message:
      'ActionParam with type "lookup"/"master_detail" requires "reference" (the target object) when declared inline — without it the param dialog degrades to a raw record-id text input. Set `reference: \'<object>\'`, or use a field-backed param (`{ field: \'<lookup_field>\' }`) to inherit it.',
  },
).refine(
  // A carry-over param must have its row seed declared. The pair is checked at
  // parse time because the failure it prevents is silent at runtime: a
  // `carryOver: true` param with no `defaultFromRow` would render an empty
  // read-only control and submit `undefined` — the silent-drop shape commit 5cb62d88b fixed,
  // reintroduced through the very key added to close it.
  (p) => !p.carryOver || p.defaultFromRow === true,
  {
    path: ['carryOver'],
    message:
      'ActionParam with "carryOver" requires "defaultFromRow: true" — a carry-over param is '
      + 'seeded from the current row, rendered read-only and submitted verbatim; without the row '
      + 'seed it would render an empty locked control and submit nothing. Declare '
      + '`defaultFromRow: true`, or (for a fixed value the user should not see) use the action\'s '
      + '`bodyExtra` instead.',
  },
).superRefine((p, ctx) => {
  // #6970 — an authored `defaultValue` is checked against the param's OWN
  // declared value contract, through the SAME `valueSchemaFor` the dispatcher
  // runs at submit (ADR-0104 D2, `validateActionParams`). One rule set, two
  // moments: whatever the dispatcher would refuse from a user is refused from
  // an AUTHOR, at the moment it is written.
  //
  // The gap this closes: `defaultValue` was `z.unknown()`, so a default that
  // can never satisfy its own param parsed clean, prefilled the control, and
  // 400'd at submit on a field the user never touched — with a message naming
  // the param but not the author's default as the cause. `datetime` is the
  // loudest instance (a human-readable wall clock, `2026-08-10T15:00`, which
  // `datetime-local` happily displays and `InstantValueSchema` refuses) but the
  // hole was every type: `number` + `'abc'`, `select` + a non-member, a
  // `multiple` param + a scalar. That is the "AI writes it wrong in bulk and
  // nothing says so" shape ADR-0078 / ADR-0049 exist to prevent.
  //
  // Checked ONLY where the declaration can answer the question — see the two
  // skips below. An authoring gate that guessed at what a field-backed param
  // inherits would reject valid metadata, which is worse than the silence it
  // replaces.
  if (!isActionParamValuePresent(p.defaultValue)) return;
  // `type` is the param's own override; absent it is inherited from the
  // referenced field at runtime and is not visible here (the same "leaves the
  // value shape open" default `validateActionParams` applies to an
  // unresolvable type).
  if (!p.type) return;

  // The whole present value goes down the LITERAL branch — deliberately no
  // `discriminateDefaultValueShape` here. An action param's default is a pure
  // literal (the dialog seeds it verbatim; `serializeParamValues` resolves
  // nothing), so a runtime-token or envelope SPELLING is judged as the literal
  // it would be at submit — the parity pin at the bottom of
  // `action-param-default-value.test.ts` is the contract. The stance is
  // recorded in `default-value-shape.ts`'s module note (#7127).
  const def = { type: p.type, multiple: p.multiple, options: p.options };
  const verdict = checkLiteralDefaultValue(def, p.defaultValue);
  if (verdict.ok) return;

  // ARITY is knowable only when the param states it. A field-backed param
  // inherits `multiple` from its field, so `{ field: 'owners', type: 'user',
  // defaultValue: ['a','b'] }` is a legal declaration whose array default this
  // gate must not call wrong. When the param is field-backed AND silent on
  // `multiple` AND the type is one whose arity `multiple` decides, accept
  // either arity and check only the ELEMENT shape.
  if (p.field && p.multiple === undefined && MULTI_CAPABLE_TYPES.has(p.type)) {
    if (checkLiteralDefaultValue({ ...def, multiple: !isMultiValueField(def) }, p.defaultValue).ok) return;
  }

  const detail = verdict.detail ?? 'invalid value';
  const key = p.name ?? p.field ?? '<unnamed>';
  ctx.addIssue({
    code: 'custom',
    path: ['defaultValue'],
    message:
      `Action param "${key}" (${p.type}): the default ${JSON.stringify(p.defaultValue)} cannot `
      + `satisfy this param's own value contract — ${detail}. The dialog would PREFILL this value `
      + 'and the submit would then be refused with that same message (ADR-0104 D2), for a field the '
      + 'user never touched — so the 400 names the param but not this default, which is the real '
      + "cause. Write the default in the param's declared value shape, or drop `defaultValue`.",
  });
}).transform((p, ctx) => lowerRequiresFeature(p, ctx)));

/**
 * Action type enum values — the DISPATCH ROUTE of an action.
 *
 * The declarative single-record field write (#14092, maintainer ruling
 * 2026-09-01) is deliberately NOT a member. It is spelled as a parallel key —
 * `operation: 'update'` + `patch` — mirroring the list view's `bulkActionDefs`
 * vocabulary word for word, and it rides the `script` route: the platform
 * action route (`POST /api/v1/actions/<object>/<action>`) is where the write
 * is performed, and `type: 'script'` is that route's name on an action. So
 * `type` answers WHERE the action dispatches and `operation` answers WHAT the
 * platform does there; an `operation: 'update'` action keeps `type` at its
 * default and every other `type` beside it is refused (see
 * {@link refuseDeclarativeUpdateContradictions}).
 *
 * Why not a member: objectui's `ActionRunner` types its dispatch table
 * `Record<RunnableActionType, …>` on purpose, so a member added here stops the
 * console compiling until an executor exists — a coupling the ruling's
 * contract-first split (spec now, executor halves downstream) must not carry —
 * and a member would be a second spelling of the bulk def's `operation`.
 */
export const ActionType = z.enum(['script', 'url', 'modal', 'flow', 'api', 'form']);
export type ActionType = z.input<typeof ActionType>;

/**
 * Action types that require a `target` field.
 * Derived from ActionType, excluding 'script' which allows inline handlers.
 * These types reference an external resource (URL, flow, modal, or API endpoint)
 * and cannot function without a target binding.
 */
const TARGET_REQUIRED_TYPES: ReadonlySet<string> = new Set(
  ActionType.options.filter((t) => t !== 'script'),
);

/**
 * Action Schema
 * 
 * **NAMING CONVENTION:**
 * Action names are machine identifiers used in code and must be lowercase snake_case.
 * 
 * **TARGET BINDING:**
 * The `target` field is the canonical way to bind an action to its handler.
 * - `type: 'script'` — `target` is recommended (references a script/function name).
 * - `type: 'url'`    — `target` is **required** (the URL to navigate to).
 * - `type: 'flow'`   — `target` is **required** (the flow name to invoke).
 * - `type: 'modal'`  — `target` is **required** (the modal/page name to open).
 * - `type: 'api'`    — `target` is **required** (the API endpoint to call).
 * - `type: 'form'`   — `target` is **required** (the FormView name to open, routed to `/_console/forms/:name`).
 * - `operation: 'update'` (on the default `script` route) — `target` is **refused**: the platform writes
 *   `patch` to the current record; there is nothing for a target to name (#14092).
 * 
 * The `execute` alias was **removed in protocol 17** (#3855). `target` is the
 * only handler slot, so no consumer has a second slot to disagree about. An
 * authored `execute` is rejected with the rename prescription rather than
 * silently stripped; `os migrate meta --from 16` lists the edit for you to apply.
 * 
 * @example Good action names
 * - 'on_close_deal'
 * - 'send_welcome_email'
 * - 'approve_contract'
 * - 'export_report'
 * 
 * @example Bad action names (will be rejected)
 * - 'OnCloseDeal' (PascalCase)
 * - 'sendEmail' (camelCase)
 * - 'Send Email' (spaces)
 * 
 * Note: The action name is the configuration ID. JavaScript function names can use camelCase,
 * but the metadata ID must be lowercase snake_case.
 */
// Retired-VALUE prescription. Declared with `//` (never `/** */`) and ABOVE the
// enum's JSDoc deliberately: `build-docs.ts` takes a doc comment adjacent to the
// declaration as the reference entry's blurb, so a `/** */` here would displace
// the location table below. (House style set by the `crypto.hash` /
// `HookBodyCapability` and `array_agg` / `AggregationFunction` enum-value
// retirements — `data/hook-body.zod.ts`, `data/query.zod.ts`.)
const GLOBAL_NAV_RETIRED =
  '`global_nav` was removed from `ACTION_LOCATIONS` in @objectstack/spec 17 (ADR-0049 '
  + 'enforce-or-remove) — no running-app surface ever rendered it. The console command palette '
  + '(`⌘K`) builds its groups from nav items, objects, dashboards, pages, reports, recent items '
  + 'and record search; it reads no action metadata at all, so an action declaring this location '
  + 'never reached a user. The only thing that DID draw it was the Studio designer, which '
  + 'previewed a command-palette frame for a surface the product does not have — an authoring '
  + 'tool teaching authors to write dead metadata (ADR-0078). Place the action on a location a '
  + 'renderer serves (`list_toolbar`, `list_item`, `record_header`, `record_more`, '
  + '`record_related`, `record_section`), or — for an action that deliberately has no UI home, '
  + 'such as an object-less one invoked over REST/MCP/AI — declare it headless with '
  + '`locations: []`, which keeps its capability gate, param contract and audit trail. '
  + 'Run `os migrate meta --from 16` to list the mechanical edits for existing sources; `--write` applies the ones it can prove, and you apply the rest by hand.';

/**
 * Action Location — where an action is allowed to surface in the UI.
 *
 * Canonical list (single source of truth for the whole platform). Renderers,
 * the ActionEngine, the Studio designer dropdowns, and `objectui` consumers
 * MUST import from this constant rather than re-declaring their own enum —
 * adding a new location should require touching this one file only.
 *
 * Semantics:
 * - `list_toolbar`    — header/toolbar of a list view (bulk actions, "New", export).
 * - `list_item`       — per-row action on a list/grid row (Salesforce row-level menu).
 * - `record_header`   — primary actions in the record-detail title bar.
 * - `record_more`     — overflow menu under the "More" / ⋯ button on a record.
 * - `record_related`  — per-row action on each row of a related list shown inside
 *                       a parent record, in that parent's context only. Unlike
 *                       `list_item` (every row wherever the object is listed), it
 *                       never surfaces on the object's own list views.
 * - `record_section`  — actions surfaced inside a body section/tab of a record
 *                       (e.g. a Security tab grouping change-password, 2FA, etc.).
 *
 * `global_nav` was REMOVED in 17 (#6888, maintainer ruling 2026-08-09). It had
 * been declared here since the vocabulary was written and no product surface
 * ever served it: the console's ⌘K palette composes its groups from nav items,
 * objects, dashboards, pages, reports, recent items and record search, and
 * references no action metadata. Four of the five references to the value in
 * the whole UI repo were the Studio designer — which drew the author a mock
 * "⌘K · Command palette" frame, promising a rendering the product cannot do
 * (the ADR-0078 declares-renders-does-nothing shape, arriving through the
 * location vocabulary rather than through a missing key). Retired rather than
 * implemented: no user has asked for command-palette actions and the only two
 * declarers were our own showcase corpus, so wiring the palette would have been
 * capability expansion with no pull. This is an enum VALUE, not a key, so there
 * is no `retiredKey()` tombstone — the prescription lives on the enum's own
 * error map above, keyed on `issue.input` so that only the spelling which used
 * to be legal is told it "was removed". An object-less action's honest
 * declaration is `locations: []` (headless), not a location nothing renders.
 */
export const ACTION_LOCATIONS = [
  'list_toolbar',
  'list_item',
  'record_header',
  'record_more',
  'record_related',
  'record_section',
] as const;

export const ActionLocationSchema = z.enum(ACTION_LOCATIONS, {
  // Only the spelling that USED to be legal gets the retirement message.
  // Telling the author of `globalnav` that their value "was removed" would
  // misinform, so everything else keeps zod's own enum error, which already
  // lists the legal locations. (`array_agg` / `crypto.hash` precedent.)
  error: (issue) => (issue.input === 'global_nav' ? GLOBAL_NAV_RETIRED : undefined),
});
export type ActionLocation = z.input<typeof ActionLocationSchema>;

/**
 * Tool category values for {@link ActionAiSchema.category}.
 *
 * **Canonical.** This was a hand-copy of `ToolCategorySchema` in
 * `../ai/tool.zod`, kept inline rather than imported to avoid a `ui → ai`
 * cycle, under a comment telling the next author to update both sides. #3896
 * removed `ToolCategorySchema` along with the inert `tool.category` key it
 * typed — which left that instruction pointing at a source that no longer
 * exists, and a reader hunting for a second side there is none of. This enum
 * is now the only declaration of the vocabulary: change it here, nowhere
 * else. (#3786 — comments are not a mechanism, and they rot silently.)
 */
const ActionAiCategorySchema = z.enum([
  'data',
  'action',
  'flow',
  'integration',
  'vector_search',
  'analytics',
  'utility',
]);

/**
 * AI exposure block (ADR-0011 "Actions as AI Tools").
 *
 * **Opt-in, default off.** An action becomes an AI-callable tool only when
 * `exposed: true`. This is a deliberate governance gate: in an AI-authoring
 * world the platform's value is that a human can govern exactly which
 * capabilities the agent fleet is allowed to invoke — a half-finished or
 * unreviewed action must never be silently armed.
 *
 * When exposed, `description` is **required** — it is the LLM-facing contract
 * (when/why to call), authored explicitly rather than derived from the
 * UI `label`. The bridge in `@objectstack/service-ai` translates this block
 * into an `AIToolDefinition`.
 */
/**
 * Shared history for this file (#4001).
 *
 * `ActionParamSchema` has been strict since #3746 — the campaign's own template,
 * where `visibleWhen` → `visible` proved that the most valuable alias entry is
 * rarely a typo but a key that reads as a control and silently is not one. The
 * action AROUND the param stayed open for three more releases.
 */
const ACTION_HISTORY =
  'Until this shape was closed these were dropped silently — the action still registered '
  + 'and still ran, without whatever the key was meant to configure or gate.';

export const ActionAiSchema = strictObject({
  surface: "this action's AI exposure block",
  history: ACTION_HISTORY,
  aliases: {
    enabled: 'exposed', enable: 'exposed', aiEnabled: 'exposed', expose: 'exposed', visible: 'exposed',
    prompt: 'description', toolDescription: 'description', summary: 'description',
    type: 'category', kind: 'category', toolCategory: 'category',
    hints: 'paramHints', parameterHints: 'paramHints', params: 'paramHints',
    returns: 'outputSchema', responseSchema: 'outputSchema', output: 'outputSchema',
    confirm: 'requiresConfirmation', requireConfirmation: 'requiresConfirmation', hitl: 'requiresConfirmation', humanInTheLoop: 'requiresConfirmation',
  },
  guidance: {
    // This block IS the governance gate — the doc above says a half-finished or
    // unreviewed action must never be silently armed. A near-miss here is
    // therefore the worst kind on this surface: the author believes they set a
    // gate, and the gate does not exist. Name the two people reach for.
    permissions:
      'AI invocation is not gated by a key here — an agent reaches this action only if a '
      + "surface-compatible SKILL declares it (ADR-0064), and who may talk to that agent is "
      + "gated by the agent's `access` / `permissions`. "
      + 'For a human-approval step on the call itself, use `requiresConfirmation: true`.',
    approval:
      'there is no approval workflow key here — `requiresConfirmation: true` forces a '
      + 'human-in-the-loop gate on the AI call. A multi-step business approval is an `approval` '
      + 'metadata item, not an action field.',
  },
}, {
  /**
   * Expose this action to AI agents as a callable tool. Default `false`.
   * Setting `true` REQUIRES `description`.
   */
  exposed: z.boolean().default(false).describe('Expose this action to AI agents. Requires `description` when true.'),

  /**
   * LLM-facing description: tells the model when and why to call this action.
   * Distinct from the UI `label`. Plain English, ≥ 40 chars for useful tool
   * selection. Required whenever `exposed` is true.
   */
  description: z.string().min(40).optional().describe('LLM-facing description (≥40 chars). Required when exposed.'),

  /**
   * Override the derived tool category. Defaults to `action` (side-effect).
   * Use `data` for read-only actions, `analytics` for aggregations, etc.
   */
  category: ActionAiCategorySchema.optional().describe('Tool category override (defaults to "action").'),

  /**
   * Per-parameter AI hints, keyed by param name (or the injected `recordId`).
   * Tightens the JSON Schema the LLM sees (e.g. add `enum`, override
   * `description`, supply `examples`) WITHOUT changing the UI-facing field
   * metadata. Keys must match a declared `params[].name` (or `recordId`).
   */
  paramHints: z.record(z.string(), strictObject({
    surface: 'this AI parameter hint',
    history: ACTION_HISTORY,
    aliases: { desc: 'description', hint: 'description', values: 'enum', options: 'enum', choices: 'enum', allowed: 'enum', example: 'examples', sample: 'examples' },
  }, {
    description: z.string().optional(),
    enum: z.array(z.union([z.string(), z.number()])).optional(),
    examples: z.array(z.unknown()).optional(),
  })).optional().describe('Per-parameter AI hints keyed by param name.'),

  /**
   * Output JSON Schema for the action's return value. Enables structured
   * downstream tool chaining (one action's output feeds another's input) and
   * is summarised into the tool description so the model knows what it gets
   * back. Optional — when omitted the return value is treated as freeform.
   *
   * The cloud AI runtime compiles this schema before the action runs, and its
   * schema reader refuses an untyped subschema that carries a type-scoped
   * keyword (`properties`, `items`, `pattern`, `minimum`, …). The slot refuses
   * the same schemas here, at the subschema's path, through the one factory
   * `agent.structuredOutput.schema` shares (`shared/ai-json-schema-slot.ts`).
   */
  outputSchema: aiJsonSchemaSlot('ai.outputSchema').optional().describe(
    'JSON Schema for the action return value. An untyped subschema that carries a type-scoped '
    + 'keyword (properties, items, pattern, minimum, …) is refused at its path, because the AI '
    + 'runtime\'s schema reader does not check it; declare its "type".',
  ),

  /**
   * Override confirmation for AI calls. When unset, the bridge defaults to
   * `true` for actions that look destructive: `mode:'delete'` or
   * `variant:'danger'` (#7828 Option A). `confirmText` is dialog copy, not a
   * destructive signal. Set explicitly to `false` to assert such an action is
   * safe without human approval, or `true` to gate an otherwise-safe one.
   */
  requiresConfirmation: z.boolean().optional().describe('Override HITL confirmation for AI invocations.'),
});

export type ActionAi = z.input<typeof ActionAiSchema>;
/** Post-parse shape of {@link ActionAi} — defaults applied, transforms run (ADR-0122). */
export type ActionAiParsed = z.infer<typeof ActionAiSchema>;

/**
 * The shape both action-level condition keys speak — `visible` and `disabled`.
 *
 * Three arms for one meaning, cheapest first:
 *
 * | arm | example | meaning |
 * |:---|:---|:---|
 * | `boolean` | `visible: false` | the degenerate literal — a condition that is settled at authoring time |
 * | `string` | `disabled: "record.status == 'closed'"` | CEL shorthand, normalized to the envelope at parse time |
 * | `{ dialect, source }` | `{ dialect: 'cel', source: '…', meta: { rationale } }` | the full envelope, for authorship metadata or a non-default dialect |
 *
 * The two keys were asymmetric until commit 97e7e3caa — `visible` had no `boolean` arm, so
 * the very common `visible: true` was a parse error on the spec side while
 * objectui's `ActionDef` accepted it and stored metadata was already written
 * that way. An asymmetry between two keys that mean the same *kind* of thing is
 * a dialect nursery: it teaches each consumer to keep its own widening (the
 * `(action as any).disabled` cast in console's `DeclaredActionsBar` was exactly
 * that), and every one of those is a second de-facto contract (Prime Directive
 * #12). Unifying here is what lets #4075 step 3 derive `ActionDef` from this
 * schema and delete the casts.
 *
 * The boolean arm is deliberately NOT normalized into `{dialect:'cel',
 * source:'true'}`: a literal survives as a literal, so a renderer can branch on
 * it without standing up an evaluator, and `false` stays statically greppable.
 */
const ActionConditionInputSchema = z.union([z.boolean(), EvaluatedExpressionInputSchema], {
  error: (issue) => evaluatedExpressionUnionRefusal(issue.input),
});

/**
 * The object half of {@link ActionSchema}, before its refinements.
 *
 * A factory rather than a schema so `lazySchema`'s deferral still holds — the
 * fields are built on first use of whichever schema derives from them, not at
 * module load.
 *
 * It exists because `.pick()` is a `ZodObject` method and `ActionSchema` is
 * `z.object(…).refine(…).refine(…)`, so nothing can derive a subset from the
 * exported schema. {@link InlineActionSchema} derives from this instead of
 * restating a dozen field definitions and their `describe()` text, which is how
 * a second action vocabulary would start.
 */
const actionObject = () => strictObject({
  surface: 'this action',
  history: ACTION_HISTORY,
  aliases: {
    title: 'label', displayName: 'label', text: 'label',
    object: 'objectName', entity: 'objectName',
    actionType: 'type',
    // The executor-target family lives in ONE table the `action:button` /
    // `action:icon` rows read too (`action-target-aliases.ts`), so the action
    // and the blocks that run it print the same rename (#21005).
    ...ACTION_TARGET_ALIASES,
    parameters: 'params', args: 'params', inputs: 'params', fields: 'params',
    confirm: 'confirmText', confirmation: 'confirmText', confirmMessage: 'confirmText',
    success: 'successMessage', successText: 'successMessage', toast: 'successMessage',
    visibleWhen: 'visible', showWhen: 'visible',
    disabledWhen: 'disabled',
    style: 'variant', color: 'variant', appearance: 'variant',
    placement: 'locations', location: 'locations', position: 'locations',
    verb: 'method', httpMethod: 'method',
    // #14092 — the bulk def's own shorthand for `operation`, and the words an
    // author borrows for "the field values to write" (`values`, `set`, or the
    // verb itself) all rename onto the two declarative-update keys.
    op: 'operation', values: 'patch', set: 'patch', update: 'patch',
    // #17319 — the words an author reaches for when declaring which bulk
    // dispatch contract the body was written for. The card that filed the gap
    // proposed `dispatch`, so that spelling is the one most likely to be
    // typed; the canonical key is `execution`, the bulk def's own.
    // ⛔ NOT `mode`: the def aliases `mode` onto `execution`, but on an ACTION
    // `mode` is a DECLARED key (create/edit/delete/custom), so renaming it here
    // would eat a real declaration.
    dispatch: 'execution', dispatchContract: 'execution',
    bulkExecution: 'execution', bulkDispatch: 'execution',
    // #5013 — `body` is DECLARED on this schema (the `script` action's L1/L2
    // hook body), so an alias filed under it could never run; `payload` is the
    // live spelling that still needs pointing at `bodyExtra`.
    payload: 'bodyExtra',
    llm: 'ai', tool: 'ai',
    dialog: 'resultDialog', result: 'resultDialog',
    refresh: 'refreshAfter', reload: 'refreshAfter',
    // The capability gate on an action IS a declared key — `requiredPermissions`
    // (ADR-0066 D4), enforced with a 403 on the platform action route. So the
    // near-misses of it must RENAME onto it, never be told the gate lives
    // somewhere else.
    permissions: 'requiredPermissions', capabilities: 'requiredPermissions',
    requiresPermissions: 'requiredPermissions', requiredCapabilities: 'requiredPermissions',
    acl: 'requiredPermissions',
  },
  guidance: {
    // `visible` / `disabled` are the trap worth naming on this surface: they
    // look like access control and are not. The real gate is
    // `requiredPermissions`, which is why the near-misses above rename onto it
    // rather than pointing anywhere else.
    hidden:
      '`hidden` is not an action key, and hiding is not gating — `visible` and `disabled` are UI '
      + 'predicates that hide or grey a button, they do not stop a request. To actually gate '
      + 'invocation use `requiredPermissions` (ADR-0066 D4, enforced with a 403 on the platform '
      + 'action route). To declare an action with no UI surface at all, set `locations: []`.',
    // Two AI-block keys authors reach for at the top level. Silently stripping
    // either meant an action was armed for agents, or left ungated, in silence.
    exposed:
      'AI exposure lives under `ai` — write `ai: { exposed: true, description: … }`. The '
      + 'description is the LLM-facing contract and is REQUIRED (≥40 chars) whenever exposed.',
    requiresConfirmation:
      'the AI human-in-the-loop override lives under `ai` — write '
      + '`ai: { requiresConfirmation: true }`. `confirmText` is the separate UI confirm prompt.',
    // The three spellings #9474 measured authors probing for post-success
    // navigation before `onSuccess` existed. Each is a top-level string where
    // the declared shape is a nested object, so an alias rename would produce
    // a second, worse error (`invalid_type` at `onSuccess`) — a guidance
    // pointer carries the whole rewrite instead.
    redirect:
      "post-success navigation is declared under `onSuccess` — write `onSuccess: { navigate: "
      + "'<route/URL template>' }` (interpolates ${param.*}, ${ctx.*} and ${result.*}, the server "
      + "response). Read for `type: 'api'` and `type: 'script'` actions; `openIn: 'self' | 'newTab'` "
      + "picks the tab (default 'self').",
    navigate:
      '`navigate` is not a top-level key — it lives inside `onSuccess`: write '
      + "`onSuccess: { navigate: '<route/URL template>' }`. The template interpolates ${param.*}, "
      + '${ctx.*} and ${result.*} (the server response payload, e.g. ${result.id}).',
    redirectUrl:
      '`redirectUrl` is the HANDLER-RETURN convention (a server handler returns '
      + '`{ redirectUrl, openIn? }`), not an authorable action key. To declare the destination in '
      + "metadata, write `onSuccess: { navigate: '<route/URL template>' }` — ${result.*} "
      + 'interpolates the server response.',
  },
}, {
  /** Machine name of the action */
  name: SnakeCaseIdentifierSchema.describe('Machine name (lowercase snake_case)'),
  
  /** Display label */
  label: I18nLabelSchema.describe('Display label'),

  /**
   * Explanatory line shown in the action's PARAM DIALOG, under the title.
   *
   * The renderer half already exists and predates this key: objectui's
   * `ActionParamDialog` renders it as the dialog's `DialogDescription`
   * (`objectui packages/app-shell/src/views/ActionParamDialog.tsx:215`, falling
   * back to the generic `actionDialog.description` string), fed by
   * `actionDescription(objectName, actionName, action.description)` from two
   * independent handlers — `useConsoleActionRuntime.tsx:206` and
   * `RecordDetailView.tsx:586`. The resolver
   * (`objectui packages/i18n/src/useObjectLabel.ts:463`) reads
   * `objects.{object}._actions.{action}.description`, falls back to
   * `globalActions.{action}.description`, then to this literal. Until #7367 no
   * producer could reach any of it: this shape refused the key.
   *
   * **Use it for the question the dialog is asking.** An action that collects
   * params and ALSO sets `confirmText` shows the user two dialogs for one
   * decision — the confirm, then the param prompt. The maintainer's 2026-08-10
   * ruling on #7278 is to carry the confirm question here instead: one
   * condition, one wording, one dialog, nothing sent until its own Confirm.
   * `confirmText` stays correct for a param-LESS action, where the confirm IS
   * the only dialog. The describe below is Studio form help and says only "one
   * dialog, not two"; the ruling that decided it is recorded here (#22093).
   *
   * **Not `ai.description`.** That one is the LLM-facing tool contract
   * (≥40 chars, required when `ai.exposed`); this one is human-facing dialog
   * copy and is never sent to a model.
   */
  description: I18nLabelSchema.optional().describe('Explanatory line shown under the title in the action\'s param dialog. Carries the confirm question for an action that collects params (one dialog, not two). Not the LLM-facing `ai.description`.'),

  /** Target object this action belongs to (optional, snake_case) */
  objectName: z.string().regex(/^[a-z_][a-z0-9_]*$/).optional().describe('Target object this action belongs to. When set, the action is auto-merged into the object\'s actions array by defineStack().'),
  
  /** Icon name (Lucide) */
  icon: z.string().optional().describe('Icon name'),

  /** Where does this action appear? */
  locations: z.array(ActionLocationSchema).optional().describe('Locations where this action is visible'),

  /** 
   * Visual Component Type
   * Defaults to 'button' or 'menu_item' based on location,
   * but can be overridden.
   */
  component: z.enum([
    'action:button', // Standard Button
    'action:icon',   // Icon only
    'action:menu',   // Dropdown menu
    'action:group'   // Button Group
  ]).optional().describe('Visual component override'),
  
  /**
   * What type of interaction — the dispatch ROUTE. The declarative
   * single-record field write is not a type: it is `operation: 'update'` on
   * the default `script` route (see {@link ActionType}), so the one input
   * that has a declarative answer gets the prescription instead of zod's
   * bare enum list.
   */
  type: z.enum(ActionType.options, {
    error: (issue) => (issue.input === 'update'
      ? "`type: 'update'` is not an action type — the declarative single-record field write is spelled "
        + "`operation: 'update'` with a `patch: { … }` of static field values (the list view's "
        + "`bulkActionDefs` vocabulary, mirrored). Leave `type` at its default `'script'`: that is the "
        + 'platform action route the write is performed on.'
      : undefined),
  }).default('script').describe("Action functionality type — the dispatch route. The declarative single-record field write is not a type: it is `operation: 'update'` + `patch` on the default `script` route."),
  
  /** 
   * Payload / Target — the canonical binding for the action handler.
   * Required for url, flow, modal, and api types.
   * For `script` type: prefer `body` over `target`. `target` is kept only for
   * legacy bundle.functions[name] references.
   *
   * **Interpolation** (renderer responsibility, all action types):
   * `target` MAY contain `${param.X}` and `${ctx.X}` tokens. Renderers
   * resolve them just before invocation:
   * - `${param.X}` — value collected from the action's params dialog.
   * - `${ctx.X}` — values from the action context: `ctx.origin`
   *   (window.origin), `ctx.recordId`, `ctx.user.id`, `ctx.org.id`, etc.
   * Renderers MUST `encodeURIComponent` interpolated values before
   * substituting them into URL query positions.
   */
  target: z.string().optional().describe('URL, Script Name, Flow ID, or API Endpoint. Supports ${param.X} and ${ctx.X} interpolation.'),

  /**
   * For `type:'url'` — where to open `target`. A simple, declarative new-tab
   * control for STATIC urls (no handler, no synchronous pre-open). objectui's
   * ActionRunner.executeUrl reads `openIn` with priority over the legacy
   * `params.newTab`/external-URL heuristic.
   *
   * - `'new-tab'` — opens `target` in a new browser tab.
   * - `'self'`    — navigates in place.
   * - omitted     — external/absolute URLs open in a new tab; relative URLs
   *                 navigate in place.
   *
   * Distinct from `opensInNewTab`/`newTabUrl`, which pre-open an about:blank
   * tab synchronously for ASYNC SSO-redirect handlers — do NOT use `openIn`
   * for those. This is a STATIC execution option: keep it OUT of `params`
   * (which is user-input-collection only).
   */
  openIn: z.enum(['self', 'new-tab']).optional().describe("For type:'url' — where to open `target`. 'new-tab' opens a new browser tab; 'self' navigates in place. When omitted, external/absolute URLs open in a new tab and relative URLs navigate in place. Static execution option — keep it OUT of `params` (which is user-input-collection only)."),

  /**
   * Action Body (L1 expression or L2 sandboxed JS).
   *
   * Only meaningful when `type === 'script'`. When set, the runtime invokes
   * the body inside the sandbox as `(input, ctx) => Promise<output>` and
   * ignores `target`.
   *
   * That condition is ENFORCED at both ends, not merely documented (#4352).
   * Authoring: the refinement on {@link ActionSchema} rejects `body` alongside
   * any other `type` — the publish gate resolves this same schema through
   * `getMetadataTypeSchema('action')`, so the contradiction cannot be stored.
   * Runtime: `actionBodyRunnerFactory` binds no handler unless the type is
   * `script`, which covers metadata published before that gate existed and
   * bundles that never parsed. Until #4352 only the sentence existed: the
   * runtime bound a handler from `body` alone, so flipping `type` from
   * `script` to `url` left the body running with nothing to say so.
   *
   * - `{ language: 'expression', source: '...' }` — pure formula (L1).
   * - `{ language: 'js', source: '...', capabilities: [...] }` — sandboxed JS (L2).
   *
   * Compiled-module bodies are not supported. Outbound IO (HTTP, etc.) goes
   * through Connector recipes (separate spec).
   *
   * `ctx.api.object(...)` is the ONLY way a body persists anything. `ctx.input`
   * is the action's params bag, and `ctx.record` is a snapshot the runtime
   * never writes back — assigning to it is discarded, declared field or not.
   *
   * Both are checked at author time by `validateActionBodyWrites` in
   * `@objectstack/lint`: a literal `ctx.api.object('y').update({ x })` naming a
   * field object `y` never declares warns with a did-you-mean, because nothing
   * downstream catches it — on a SQL driver the stray column fails the whole
   * call with a driver-level error far from the authoring site, and on a
   * schemaless driver it is persisted as an undeclared key (#4271); and a
   * provably dead `ctx.record.<field> = …` warns as discarded (#4345).
   * Advisory only, and blind to everything statically unknowable; see
   * `ScriptBodySchema` for the scope.
   *
   * The sandbox reports the discarded `ctx.record` writes at INVOCATION time as
   * well, covering the computed keys, aliases and Studio/API-authored bodies a
   * parse cannot reach.
   */
  body: HookBodySchema.optional().describe('Action body — expression (L1) or sandboxed JS (L2). Only used when type is `script`.'),

  /**
   * The declarative single-record field write — the row-level counterpart of
   * a list view's `bulkActionDefs` `{ operation: 'update', patch }` (#14092,
   * maintainer ruling 2026-09-01), spelled with the same words on purpose:
   * `operation`, `patch`, `params`, `visible`, `confirmText` mean here exactly
   * what they mean on the def. No second spelling was invented.
   *
   * ONE member, `'update'`, by ruling. The def's other two operations are not
   * admitted on a row: `'delete'` is the object's own delete affordance and
   * was not ruled for the row form, and `'custom'` means "dispatch the action
   * this def NAMES" — on a row the action is already the action, so there is
   * nothing to name. The enum's error map says so rather than listing one
   * member.
   *
   * Beside `operation: 'update'` the action keeps `type` at its default
   * `'script'` — the platform action route, where the write is performed —
   * and carries NO executor binding of its own: `target`, `body`, `method`,
   * `bodyExtra`, `bodyShape`, `recordIdParam`/`recordIdField`, `onSuccess`,
   * `opensInNewTab`/`newTabUrl` and any other explicit `type` are each refused
   * with their own message ({@link refuseDeclarativeUpdateContradictions}).
   * A `list_toolbar` location is refused too: there is no current record
   * there — the selection bar is the bulk def's home.
   *
   * EXECUTOR CONTRACT (the halves that perform the write are downstream cards
   * — both keys are `planned` in the liveness ledger until they land):
   * a single-record data-plane update of the CURRENT record, executed AS THE
   * CALLER and never system-elevated — the direction ruled for hook
   * `runAs: 'user'`, consumed here, not reopened — so the caller's object,
   * row and field permissions, the object's hooks and its validations fire
   * exactly as for a user edit; a caller who cannot read or write the row is
   * refused; the static `patch` is merged UNDER the values `params` collects;
   * `undoable` captures the prior values of exactly the fields written.
   */
  operation: z.enum(['update'], {
    error: (issue) => (issue.input === 'delete' || issue.input === 'custom'
      ? `\`operation: '${issue.input}'\` is a bulk-def operation with no row-level form: `
        + (issue.input === 'delete'
          ? 'a row delete is the object\'s own delete affordance, not a declarative action (and was not ruled for the row form). '
          : "on a bulk def `'custom'` dispatches the action the def NAMES; on a row the action IS the action, so there is nothing to name. ")
        + "The one row-level operation is `'update'` (a static `patch` written to the current record)."
      : undefined),
  }).optional().describe("The declarative single-record field write, mirroring a list view's `bulkActionDefs`: `'update'` applies `patch` (merged under the collected `params`) to the current record on the data plane AS THE CALLER — never system-elevated — so the caller's permissions, the object's hooks and its validations fire as for a user edit. `type` stays at its default `'script'` (the platform action route the write is performed on); `target`/`body`/`method`/`bodyExtra` are refused beside it. `'delete'` and `'custom'` have no row-level form."),

  /**
   * Static field values for `operation: 'update'` — see that key. Merged
   * UNDER the user-supplied `params`, so a fixed value can be declared without
   * exposing it in the dialog; a param of the same name wins. Passed through
   * verbatim: no transform, no field-existence check here (that is a
   * reference diagnostic for `@objectstack/lint`, the `UserFilterFieldSchema`
   * precedent) — the executor validates the values against the object like
   * any user edit.
   */
  patch: z.record(z.string(), z.unknown()).optional().describe("For `operation: 'update'` — static field values written to the current record, merged UNDER the user-supplied `params` so a fixed value can be declared without exposing it in the dialog. Written on the data plane as the caller: object permissions, hooks and validations fire as for a user edit. Refused on an action without `operation: 'update'` (it would be silently dropped)."),

  /**
   * The **bulk dispatch contract this action's body is written for** (#17319,
   * maintainer ruling, decision batch #121 item 3, 2026-09-12).
   *
   * A list view can wire the same declared action two ways, and the two hand
   * the SAME body opposite input:
   *
   *  - `bulkActions: ['<name>']` — the bare-string form. The renderer promotes
   *    the action to a def and dispatches it **once per selected row**; each
   *    call carries that row's `recordId` and **no** `_selectedIds`.
   *  - a `bulkActionDefs` entry with `execution: 'aggregate'` — **one**
   *    dispatch for the whole selection; every id arrives in the builtin
   *    `params._selectedIds` and there is **no** `recordId`.
   *
   * Until this key existed the action declared neither, so both mismatches
   * failed quietly and in opposite directions: an aggregate body wired
   * bare-string reads `_selectedIds` as `undefined`, falls into its
   * single-record branch and reports success for one row out of ten; a
   * per-record body wired aggregate finds no `recordId` and throws its own
   * "nothing selected", which reads like a selection bug. **Nothing caught
   * either**: the ADR-0104 strict params gate cannot, because `_selectedIds`
   * and `recordId` are both `ACTION_PARAM_BUILTIN_KEYS` — admitted
   * without a declaration, and never declarable — so the one key that decides
   * the contract is exactly the key that gate is structurally blind to
   * (pinned in `action-params.test.ts`). The cost was paid in prose: the
   * reference CRM carried the distinction in hand-copied comment blocks, the
   * largest surviving constraint block on its action surface.
   *
   * **The vocabulary is `bulkActionDefs`' own, deliberately — `execution`,
   * `'perRecord' | 'aggregate'`, the very {@link BulkActionExecutionSchema}
   * the def parses with.** Not a second spelling of one idea: an action and a
   * def name the same two dispatches with the same word and the same two
   * values, the way `operation` / `patch` already mirror the def's
   * declarative update. Importing the def's enum rather than re-declaring it
   * is what makes "no third spelling" structural instead of remembered.
   *
   * **Optional, and there is NO silent default** (the ruling's
   * 「创业阶段不渐进」). An action that omits it is *undeclared*, not
   * defaulted to either contract, and `@objectstack/lint` refuses nothing —
   * undeclared is also the honest state of a body written to serve BOTH
   * contracts (it reads `recordId` and `_selectedIds` and copes with either),
   * which is why no third enum member was added for it. Existing actions get
   * their declaration from the ADR-0087 semantic migration entry
   * `action-bulk-dispatch-contract-undeclared`, which derives it from the
   * view wirings where they are unambiguous and hands back a structured TODO
   * where one action is wired both ways.
   *
   * ENFORCEMENT: authoring-time, by `@objectstack/lint`'s
   * `validateActionDispatchContract` (`action-dispatch-contract-mismatch`,
   * severity `error`) — a list view that wires a declared action under the
   * OTHER contract is refused, naming the action, the view and both
   * contracts. The key changes no dispatch by itself; it is the declaration
   * the refusal is measured against.
   */
  execution: BulkActionExecutionSchema.optional().describe("The bulk dispatch contract this action's BODY is written for, in `bulkActionDefs`' own vocabulary: 'perRecord' = one dispatch per selected row carrying that row's `recordId` (the view's `bulkActions: ['<name>']` bare-string form); 'aggregate' = ONE dispatch for the whole selection carrying every id in `params._selectedIds` (a `bulkActionDefs` entry with `execution: 'aggregate'`). Optional with NO default — omit it only when the body genuinely serves both. A list view wiring a declared action under the other contract is refused by `@objectstack/lint` (`action-dispatch-contract-mismatch`)."),

  /**
   * [REMOVED in protocol 17 — #3855] The deprecated alias of `target`.
   * Tombstoned rather than deleted: `ActionSchema` is `strictObject`, so a
   * plain deletion would reject the key — but with a generic unknown-key error
   * that does not name `target`. The prescription is the payload: it carries
   * the rename, so an author who wrote `execute` is told where the handler ref
   * goes instead of only that the key is unknown. It also types the key
   * `never`, so the mistake fails `tsc` before any parse runs.
   */
  execute: retiredKey(
    '`execute` was removed in @objectstack/spec 17 — use `target`. ' +
    'Rename the key; the value (a handler / flow / URL ref) is unchanged. ' +
    'Run `os migrate meta --from 16` to list the mechanical edits for existing sources; `--write` applies the ones it can prove, and you apply the rest by hand.',
  ),
  
  /**
   * User Input Requirements — the **parameter DEFINITION array** rendered as a
   * dialog before the action runs. `ActionParam[]`, never a values map.
   *
   * The distinction is load-bearing and was, until #5777, only implicit. A
   * `type:'api'` author reaches for `params` expecting the REQUEST PAYLOAD —
   * `params: { name: '{{page.inquiryName}}' }` — because "params" reads like
   * "what I send". That is a different concept living under the same name:
   * definitions describe fields to COLLECT, a payload is data to SEND. The
   * static payload key is {@link bodyExtra}, and the two shapes are disjoint
   * (array vs object), which is exactly why the confusion survived — every
   * consumer could tell them apart with `Array.isArray`, so nobody had to.
   *
   * The maintainer's 2026-08-06 ruling on #5777 took direction A (a separate
   * key, no same-name union), so this key keeps ONE meaning and the object form
   * is REFUSED here — with a message that names `bodyExtra` rather than the
   * bare "expected array, received object" an author cannot act on. Sources
   * still carrying the object form are rewritten at load by the
   * `inline-action-api-params-to-body-extra` conversion (ADR-0087 D2).
   *
   * **The api prescription is not universal, which #6828 measured and the
   * maintainer's 2026-08-10 ruling closed.** On a `type:'url'` action the
   * object form meant a THIRD thing again — objectui's `ActionRunner` read a
   * non-array `params` as the `${param.X}` interpolation scope for `target`,
   * and `params.newTab` as a legacy new-tab flag. Sending that author to
   * `bodyExtra` is a wrong instruction: an api request-body key is not an
   * interpolation scope (the same asymmetry is why the conversion above guards
   * on `type === 'api'` — rewriting a url action's object `params` would be
   * lossy, and ADR-0087 D2 requires losslessness). The ruling **retired** the
   * url meaning rather than giving it a key: the scope is already expressible
   * as `target`-string interpolation, and the flag is already {@link openIn}.
   * So the refusal below prescribes per action type — `bodyExtra` for `api`,
   * the sanctioned url spellings for `url` — and nothing new enters the
   * vocabulary. A future authorable interpolation-scope key needs a spec
   * proposal that demonstrates pull, not a third arm of this one.
   *
   * The branch is stated IN THE TEXT rather than selected at runtime because
   * zod cannot see a sibling from a property-level error map: the map receives
   * only `{ code, expected, input, inst, path }` for the offending value, and
   * an object-level `.check()`/`.superRefine()` — which would see `type` — is
   * skipped once a property has already failed (probed on zod 4.4.3). Reading
   * `type` here would mean restructuring `ActionSchema` behind a
   * `z.preprocess`, which erases `z.input<typeof ActionSchema>` (the authoring
   * type `defineAction` publishes) — a far larger change than the guidance
   * defect warrants, and one that moves surfaces this issue must not move.
   */
  params: z.array(ActionParamSchema, {
    error: (iss) => (
      iss.code === 'invalid_type'
        && iss.input !== null
        && typeof iss.input === 'object'
        && !Array.isArray(iss.input)
        ? "`params` is the parameter DEFINITION array (fields collected from the user before the action runs), not a values map. "
          + "For a `type:'api'` action's static request body — including `{{page.<var>}}` tokens — use `bodyExtra: { … }` instead. "
          + "For a `type:'url'` action there is nowhere to move it to, by decision: put static values straight into the `target` string "
          + "(`${param.X}` interpolates a value collected by the params dialog, `${ctx.X}` one from the action context), and open a new tab with "
          + "`openIn: 'new-tab'`. The url-side readings of an object `params` — a static `${param.X}` scope, and `params.newTab` — are RETIRED, not renamed. "
          + 'Expected an array of ActionParam, received an object.'
        : undefined
    ),
  }).optional().describe('Input parameters required from user — an ActionParam[] DEFINITION array, never a payload map (a static request body goes in `bodyExtra`).'),
  
  /** Visual Style */
  variant: z.enum(['primary', 'secondary', 'danger', 'ghost', 'link']).optional().describe('Button visual variant for styling (primary = highlighted, danger = destructive, ghost = transparent)'),

  /**
   * Explicit sort order WITHIN a UI location group (lower = higher / more
   * prominent). Controls where the action lands in each `locations` group
   * instead of relying on cross-file `defineStack({ actions })` registration
   * order — which is fragile and couples unrelated features.
   *
   * In `record_header` the first visible action becomes the primary button, so
   * a low (or negative) `order` promotes an action into the primary slot and a
   * high `order` demotes it toward the `⋯` overflow menu. This is the
   * declarative lever a plugin (e.g. plugin-approvals) or app author uses to
   * make a decision like Approve/Reject stably outrank app actions, rather than
   * hiding the other actions to "make room".
   *
   * Honoured by a STABLE sort in `mergeActionsIntoObjects()` (see stack.zod):
   * actions that leave `order` unset are treated as `0` and keep their original
   * registration order, so setting `order` on nobody is a no-op — fully
   * backward compatible. Renderers MAY additionally prefer a `variant:'primary'`
   * action when two actions tie on `order` (see objectui record-header renderer).
   */
  order: z.number().optional().describe('Sort order within a location group (lower = higher). Promotes/demotes an action toward the record_header primary button; stable, so actions without `order` keep their registration order.'),

  /** UX Behavior */
  // NB this describe() renders into the InlineAction reference table too (both
  // tables derive from this one field factory), and the #7428 refusal lives on
  // `ActionSchema`'s refine chain alone — hence "a registered action" rather
  // than an unqualified claim that would be false on the inline surface.
  confirmText: I18nLabelSchema.optional().describe('Confirmation message before execution. On a registered action, pairing this with a non-empty `params` is refused — that opens a second dialog for one decision; put the question on `description` instead. Correct on a param-LESS action, where the confirm is the only dialog there is.'),
  // `${result.*}` is the scope `onSuccess.navigate` declares (see that key's
  // docblock for its members) — the copy reuses it rather than growing a
  // second interpolation dialect (#21095). The sentence is phrased "on a
  // registered action" for the same reason `confirmText`'s is: this describe()
  // also renders into the InlineAction table, which does not pick
  // `outcomeMessages`.
  successMessage: I18nLabelSchema.optional().describe("Success message shown after the action succeeds. On a `type: 'api'` or `type: 'script'` action it may interpolate ${result.*} — the server response payload, the same scope `onSuccess.navigate` declares (e.g. ${result.id}). On a registered action that declares `outcomeMessages`, the entry named by the response's `outcome` is shown instead, and this message is the fallback."),

  /**
   * Outcome-specific success copy — ruling A on objectstack-ai/cloud#2315,
   * the mechanism half of ruling B there: the server returns FACTS, the
   * console composes the message in the user's locale. Landing order: this
   * key (spec and client, #21095), then the console reader
   * (objectstack-ai/objectui#11344), then cloud's producers.
   *
   * One server-executing action can succeed in more than one way — an
   * environment delete archives, finds it already archived, defers a purge or
   * destroys; an update check finds updates, finds none, or finds nothing
   * installed — and one static `successMessage` cannot say which happened.
   * So the handler answers with a closed `outcome` fact and this map carries
   * the copy for each: keys are the snake_case outcome names the handler
   * returns, values the message shown for that outcome.
   *
   * **Selection** (the console's, after an `api` or `script` action
   * succeeds): the success payload's top-level `outcome` — the payload
   * `${result.*}` reads, i.e. `${result.outcome}` — names the entry; failing
   * a match, `successMessage`; failing that, the runner's default text.
   *
   * **Interpolation**: each message, like `successMessage`, may interpolate
   * `${result.X}` — the scope `onSuccess.navigate` declares
   * (for `type: 'api'` the `target` call's response body, for
   * `type: 'script'` the handler's return value). No second dialect.
   *
   * **Where it is refused** (`refuseInertOutcomeMessages`, and the
   * declarative-update table): on a type with no server response to report
   * an outcome (`url` / `modal` / `flow` / `form`), beside `resultDialog`
   * (which suppresses the success toast this copy is shown in), and beside
   * `operation: 'update'` (no handler, so no outcome). Each would parse clean
   * and never be read — the ADR-0078 shape this file refuses at authoring time.
   *
   * **Translation** rides beside `successMessage`, at the action's one
   * address (`translateAction`): a bound action reads
   * `objects.<object>._actions.<action>.outcomeMessages.<outcome>`, and an
   * object-less action reads `globalActions.<action>.outcomeMessages.<outcome>`.
   *
   * Liveness: the ledger row was `planned` until the console reader landed,
   * and it is `live` from the pin this repo builds against (`.objectui-sha` =
   * `20c6d351a`, re-read there 2026-10-10:
   * `core/src/actions/ActionRunner.ts` changed above the reader only (+29/-35,
   * objectui#6349 batch 4, objectui `d32869883`: `ActionContext` and
   * `ActionResult` declared once and `UndoableOperation` published, every hunk
   * in the import block and those declarations at the top of the file), so
   * `composeSuccessMessage` MOVED `1504` -> `1498` with its body byte-identical,
   * and the four action renderers are byte-identical (`git diff --quiet`). At
   * `47b1f0bb7`, re-read there 2026-10-09:
   * every objectui file this record cites is byte-identical across the hop from
   * `f0268ad78` (`git diff --quiet`), so every anchor held unmoved. At
   * `f0268ad78`, re-read there 2026-10-09:
   * `core/src/actions/ActionRunner.ts` changed above the reader only (+7/-0,
   * objectui#11695: the confirmation handler's `destructive` option and its
   * docblock), so `composeSuccessMessage` MOVED `1497` -> `1504` with its body
   * byte-identical. At `a58626c88`, re-read there 2026-10-06:
   * every objectui file this record cites is byte-identical across the hop from
   * `0abd4f9f8` (`git diff --quiet`), so every anchor held unmoved.
   * At `0abd4f9f8`, re-read there 2026-10-05:
   * every objectui file this record cites is byte-identical across the hop from
   * `9dfaca654` (`git diff --quiet`), so every anchor held unmoved.
   * At `9dfaca654`, re-read 2026-10-05: `core/src/actions/ActionRunner.ts` is
   * byte-identical to `2e818d0b5`, re-read there 2026-10-04, and to
   * `ab1879721`, where it was read 2026-10-03, so the anchor below held
   * unmoved). The reader is objectui#11344 (objectui
   * `c476be0e0`): `ActionRunner.composeSuccessMessage`
   * (`core/src/actions/ActionRunner.ts:1498`) picks `outcomeMessages[outcome]`
   * off the handler's return value, falls back to `successMessage` and then to
   * the runner's default text, and fills `${result.*}` in whichever it shows.
   * The four action renderers forward the key to the runner (`action:bar`
   * spreads a registered action onto `action:button` whole). At `89cad75d5570`
   * no objectui source outside its types named the key.
   */
  outcomeMessages: z.record(SnakeCaseIdentifierSchema, I18nLabelSchema).optional().describe("Success copy per handler outcome, for type:'api' and type:'script' actions: keys are the snake_case `outcome` values the handler returns in its success payload (e.g. archived, already_archived), values the message shown for that outcome. Each message may interpolate ${result.*}, the scope `onSuccess.navigate` declares. An outcome with no entry here falls back to `successMessage`, then to the default text. Not allowed beside `resultDialog` (which suppresses the success toast) or `operation: 'update'` (no handler, so no outcome)."),
  // Runtime (ActionRunner) already honours this — declared here so authors can
  // set a friendly failure toast instead of surfacing the raw error string.
  errorMessage: I18nLabelSchema.optional().describe('Error message to show when the action fails (overrides the raw error).'),
  refreshAfter: z.boolean().default(false).describe('Refresh view after execution'),
  // Single-record update actions only. When true, the runtime captures the
  // record's prior field values and offers an "Undo" affordance on the success
  // toast (backed by the client UndoManager) to restore them. `operation:
  // 'update'` is the DECLARED form of such an action (#14092), and it is the
  // ONE member the operation enum carries — so there is one capture rule, not
  // one per operation. The set is the write bag `{ ...patch, ...params }`
  // (contract point 4, `patch` UNDER `params`), which is what the executor
  // reads back: `executeDeclarativeUpdateAction` keys `undoData` off
  // `Object.keys(data)`, `data` being that merged bag — NOT `patch` alone.
  // Naming `patch` alone here is what let a consumer build a half-restore and
  // report it as a full undo.
  // A SECOND shape is fulfilled, by a different runtime: `type: 'api'`, which
  // the pinned console snapshots — its two readers gate the undo envelope on
  // `action.undoable` alone and never read `action.operation`, and they are the
  // whole recorded evidence for this key's `live` liveness verdict. That is why
  // the published `ReassignLeadAction` example (api + undoable, no `operation`)
  // is legal. Those two are the closed fulfillable set; everything else —
  // `script` / `url` and the dormant `flow` / `modal` / `form` without
  // `operation: 'update'` — has no reader at all and is refused below rather
  // than silently accepted.
  undoable: z.boolean().optional().describe("Offer an Undo affordance after this single-record update action succeeds. `operation: 'update'` is the one declared operation and the declared form of that action: what the undo captures is the prior value of EVERY field the action writes — the merged write bag, `patch` UNDER the collected `params`, not `patch` alone. An action with no `operation` declares no write set here, but `type: 'api'` is fulfilled by the console, which builds the undo envelope from `undoable` alone. Those two shapes — `operation: 'update'` and `type: 'api'` — are the whole fulfillable set; on a registered action `undoable` beside any other shape is refused, because nothing would anchor the capture."),

  /**
   * Result Dialog — describe how to render the API response on success.
   *
   * When set and the action returns successfully, the renderer SHOULD open a
   * dialog showing the selected fields from `result.data` instead of the
   * `successMessage` toast. The dialog has an acknowledge button only — the
   * user must explicitly close it. Used for **one-shot reveals** of values
   * the user must copy now because they cannot be retrieved later:
   *
   * - TOTP enrollment URI + secret (`enable_two_factor`)
   * - Backup recovery codes (`regenerate_backup_codes`)
   * - Freshly minted OAuth `client_secret` (`rotate_client_secret`,
   *   `create_oauth_application`)
   *
   * `fields` selects what to render and how. Each entry's `path` is a dot
   * path into `result.data` (e.g. `'totpURI'`, `'backupCodes'`,
   * `'client.client_secret'`). When `fields` is omitted, the renderer falls
   * back to JSON-printing the whole response under a single block.
   *
   * `format` (dialog-level) is a default for fields that don't carry their
   * own `format`; the per-field `format` always wins.
   *
   * Renderer contract (objectui):
   * - `qrcode` — render the value as a QR code; also render the raw string
   *   underneath with a copy button (so the user can paste into apps that
   *   don't scan).
   * - `code-list` — value must be an array of strings; render each in a
   *   monospace row with per-row copy and a "Copy all" affordance.
   * - `secret` — render a single string masked by default with a reveal
   *   toggle and copy button.
   * - `text` — plain text with copy.
   * - `json` — pretty-printed JSON in a monospace block.
   *
   * The dialog SHOULD set `refreshAfter` to true on close (separate from
   * the existing `refreshAfter` flag, which fires immediately on success).
   */
  resultDialog: strictObject({
    surface: 'this result dialog',
    history: ACTION_HISTORY,
    aliases: { label: 'title', heading: 'title', message: 'description', body: 'description', ok: 'acknowledge', confirm: 'acknowledge', button: 'acknowledge', display: 'format', render: 'format', show: 'fields', reveal: 'fields' },
  }, {
    title: I18nLabelSchema.optional(),
    description: I18nLabelSchema.optional(),
    acknowledge: I18nLabelSchema.optional().describe('Acknowledge button label, e.g. "I have saved this"'),
    format: z.enum(['qrcode', 'code-list', 'secret', 'text', 'json']).optional().describe('Default format for fields without their own format. Defaults to json when omitted.'),
    fields: z.array(strictObject({
      surface: 'this result dialog field',
      history: ACTION_HISTORY,
      aliases: { key: 'path', field: 'path', name: 'path', title: 'label', display: 'format', render: 'format' },
    }, {
      path: z.string().describe('Dot path into result.data (e.g. "totpURI", "client.client_secret").'),
      label: I18nLabelSchema.optional(),
      format: z.enum(['qrcode', 'code-list', 'secret', 'text', 'json']).optional().describe('Per-field format override.'),
    })).optional().describe('Which fields from result.data to render. Omit to dump full JSON.'),
  }).optional().describe('Render API response in a one-shot reveal dialog (suppresses successMessage when set).'),
  
  /** Access */
  /**
   * Whether the action is offered at all. Three arms, one meaning — see
   * {@link ActionConditionInputSchema}: `false` parks the action, `true` is the
   * explicit default, and a predicate gates it per record/user/features.
   *
   * ⚠️ Client-side hiding is UX, not authorization — the button is gone, the
   * route is not. An action gated for access-control reasons must also be
   * refused server-side (`requiredPermissions`, or the action's own body).
   */
  visible: ActionConditionInputSchema.optional().describe('Visibility predicate — `true`/`false` literal, CEL string, or `{dialect, source}` envelope. The action is offered when it evaluates TRUE. Omit = always visible.'),
  /**
   * Declarative capability gate (#2874) — action-level twin of the param
   * `requiresFeature`. Lowered at parse time into `visible` (`== true` for
   * opt-in flags, `!= false` for default-on; AND-composed with an explicit
   * `visible`) and stripped from the output. See `PUBLIC_AUTH_FEATURES` in
   * `@objectstack/spec/kernel`.
   */
  requiresFeature: z.enum(PUBLIC_AUTH_FEATURE_NAMES).optional().describe('Public auth feature flag gating this action; lowered into `visible` at parse time.'),
  /**
   * Declarative membership-grade gate (ADR-0108 D1) — the grade twin of
   * `requiresFeature`. Names a row of `MEMBERSHIP_REACH` (`@objectstack/spec/identity`):
   * the organization endpoint this action calls. Lowered at parse time into
   * `visible` over `current_user.positions` — one term per grade that reaches
   * the endpoint, in the names `mapMembershipRole` projects them to —
   * AND-composed with an explicit `visible`, and stripped from the output.
   * UI courtesy: the endpoint's own door stays the authority.
   */
  requiresMembershipReach: z.enum(MEMBERSHIP_REACH_NAMES).optional().describe('Organization endpoint (a MEMBERSHIP_REACH row) whose membership-grade gate this action follows; lowered into `visible` over current_user.positions at parse time.'),
  /**
   * Whether the action is offered but refused. Same three arms as `visible`
   * ({@link ActionConditionInputSchema}) — a disabled action stays on screen
   * (usually greyed, with the reason in a tooltip) where a non-visible one is
   * gone entirely.
   */
  disabled: ActionConditionInputSchema.optional().describe('Disabled predicate — `true`/`false` literal, CEL string, or `{dialect, source}` envelope. The action is shown but refused when it evaluates TRUE. Omit = never disabled.'),

  /**
   * [ADR-0066 D4] System capabilities required to INVOKE this action — a
   * dual-surface gate from ONE declaration: the PLATFORM ACTION ROUTE rejects
   * the call with 403 when the caller's systemPermissions don't cover these (the
   * source of truth), and the objectui action surfaces hide the button using the
   * same requirement. Independent of `visible` (CEL): this is the RBAC
   * capability contract, mirroring `App.requiredPermissions`.
   *
   * **Server enforcement covers the platform's own invocation paths only** —
   * `POST /api/v1/actions/<object>/<action>` (and the MCP/AI path), which is
   * where `type: 'script' | 'flow' | 'modal'` actions land. A `type: 'api'`
   * action whose `target` is a self-authored endpoint is called by the browser
   * DIRECTLY: the platform never sees the request, so nothing checks this
   * declaration server-side. Such an endpoint MUST re-check the capability
   * itself (framework#3923) — treat the UI gate there as a courtesy, not a
   * boundary.
   */
  requiredPermissions: z.array(z.string()).optional().describe('[ADR-0066 D4] Capabilities required to invoke this action. Enforced with 403 on the platform action route (script/flow/modal + MCP) and mirrored as a UI hide; a `type: api` action pointed at a custom endpoint must re-check it there.'),

  /** Keyboard Shortcut */
  // `shortcut` and `bulkEnabled` REMOVED by the 2026-07 #3896 audit close-out —
  // both were authorable capability claims nothing enforced (ledger: dead,
  // #3686 re-verification): ActionEngine registered them but no keydown path
  // ever dispatched a shortcut, and the multi-select toolbar reads the LIST
  // VIEW's bulkActions, never this flag. Tombstoned with the prescription;
  // `action-inert-keys-removed` strips them from authored sources.
  shortcut: retiredKey(
    '`action.shortcut` was removed in @objectstack/spec 17.0.0 (audit close-out) — ' +
    'it never triggered anything: no keydown listener feeds ActionEngine.getShortcuts(), and ' +
    "objectui's keyboard stack (useKeyboardShortcuts) is hand-registered and never consults " +
    'action metadata. Delete the key. For a real shortcut, register the key in the Console ' +
    'keyboard stack and have its handler invoke the action by name. ' +
    'Run `os migrate meta --from 16` to list the mechanical edits for existing sources; `--write` applies the ones it can prove, and you apply the rest by hand.',
  ),
  bulkEnabled: retiredKey(
    '`action.bulkEnabled` was removed in @objectstack/spec 17.0.0 (audit close-out) — ' +
    'the multi-select toolbar is driven by the LIST VIEW\'s `bulkActions` / `bulkActionDefs`, ' +
    'never by this flag, so setting it changed nothing. Delete the key and declare the action ' +
    "in the view's `bulkActions` instead. " +
    'Run `os migrate meta --from 16` to list the mechanical edits for existing sources; `--write` applies the ones it can prove, and you apply the rest by hand.',
  ),

  /**
   * AI exposure block (ADR-0011). Opt-in, default off: an action is exposed
   * to AI agents only when `ai.exposed === true`, in which case `ai.description`
   * is required. See {@link ActionAiSchema}.
   */
  ai: ActionAiSchema.optional().describe('AI exposure (opt-in). Set ai.exposed=true + ai.description to make this callable by agents.'),

  /**
   * Row-context: when the action runs from a list_item location, this body key
   * receives the row's id (or the field named by `recordIdField`). Defaults to
   * `id` when omitted but `recordIdField` is set; otherwise no injection.
   */
  recordIdParam: z.string().optional().describe('Body key to inject the row id into when running from a list_item context.'),
  /**
   * Row field whose value seeds `recordIdParam`. Defaults to `'id'` when
   * `recordIdParam` is set. Use this when the body key expects a non-id value
   * (e.g. `token` for `revoke-session`).
   */
  recordIdField: z.string().optional().describe('Row field whose value seeds recordIdParam. Defaults to "id".'),
  /**
   * Request-body shape. `'flat'` (default) sends collected params at the top
   * level. `{ wrap: 'data' }` nests the user-collected params under that key
   * (used by better-auth `organization/update`), while `recordIdParam` and
   * other top-level keys stay flat.
   */
  bodyShape: z.union([
    z.literal('flat'),
    strictObject({
      surface: 'this body shape',
      history: ACTION_HISTORY,
      aliases: { key: 'wrap', under: 'wrap', nest: 'wrap', root: 'wrap' },
    }, { wrap: z.string() }),
  ]).optional().describe('Body wrapping: flat (default) or { wrap: key } to nest user-collected params under a key.'),
  /**
   * HTTP method to use when `type: 'api'`. Defaults to `POST`. Use `PATCH` to
   * call data-API update endpoints. The shipped data door is
   * `PATCH {apiBase}/data/:object/:id` — `getApiBasePath()` + `crud.dataPrefix`,
   * i.e. `/api/v1` + `/data` on a default host — so the endpoint for one
   * record is e.g. `/api/v1/data/sys_api_key/${ctx.recordId}` with
   * `bodyExtra: { revoked: true }`. Two things the path depends on: the
   * `/data` segment (omit it and the action renders, is clickable, and 404s
   * at the click), and the `${ctx.X}` / `${param.X}` interpolation
   * {@link target} documents — a bare `{recordId}` placeholder is
   * {@link newTabUrl}'s convention alone and is not substituted here.
   *
   * The full path is host-dependent: under `enableProjectScoping` with
   * `projectResolution: 'required'` only
   * `/api/v1/environments/:environmentId/data/:object/:id` is registered, so
   * an unscoped path 404s on such a host — write `target` against the base
   * the host actually mounts.
   *
   * To write a field on the CURRENT record, prefer the declarative
   * {@link operation} `'update'` with {@link patch}: the platform performs
   * the write, so there is no endpoint, method or id placeholder to spell at
   * all. The `type: 'api'` + `PATCH` form above remains the way to call an
   * explicit endpoint.
   */
  method: z.enum(['POST', 'PATCH', 'PUT', 'DELETE']).optional().describe('HTTP method for type:"api" actions. Defaults to POST.'),
  /**
   * Static body fragment merged into the outgoing request body for `type:'api'`
   * actions. Useful for constants the user shouldn't (or can't) edit, e.g.
   * `bodyExtra: { resend: true }` on a resend-invitation action that reuses
   * better-auth's `invite-member` endpoint. Applied after user-collected
   * params and `recordIdParam` so constants always win.
   *
   * **This is the static-payload key for `type:'api'`, on registered AND inline
   * actions alike** (#5777). `params` is the parameter DEFINITION array and
   * carries no payload; the ruled direction A gave the payload its own key
   * rather than unioning two meanings onto one name. The name is not new and is
   * deliberately not new: `body` is already taken on this schema (the `script`
   * action's L1/L2 hook body, and the #4352 refinement rejects it alongside any
   * other `type`, so it could never carry an api payload), and `payload` is
   * already an ALIAS pointing here — written in the table above by #5013 for
   * exactly that reason. So an author who writes `payload: {…}` is renamed onto
   * this key, and one who writes `body: {…}` on a `type:'api'` action is
   * rejected by the refinement that owns that name.
   *
   * Values are not required to be literals: objectui's console action runtime
   * runs `resolvePageVarTokens` over this record, so `{{page.<var>}}` tokens
   * resolve against the live page-variable snapshot the same way they do for a
   * collected-params body. That is what makes it the correct home for a
   * pure-SDUI form submit (`examples/app-showcase/.../contact-form.page.ts`).
   */
  bodyExtra: z.record(z.string(), z.unknown()).optional().describe('Static request-body fields for a type:"api" action, merged last (overrides user params). `{{page.<var>}}` tokens are resolved by the runtime. This — not `params` — is where a payload goes.'),
  /**
   * Semantic mode hint — UI / runtime can use this to pick confirm copy,
   * default variants, success messaging. Pure metadata; no runtime branching.
   */
  mode: z.enum(['create', 'edit', 'delete', 'custom']).optional().describe('Semantic mode of the action.'),

  /**
   * Open the action's result in a NEW TAB. The renderer pre-opens the tab
   * synchronously on click (preserving the user gesture so popup blockers
   * don't fire), paints a progress page, then drives the tab to the
   * handler's returned `redirectUrl` — or, when `newTabUrl` is set, straight
   * to that URL with no server round trip.
   */
  opensInNewTab: z.boolean().optional().describe('Open the action result in a new tab. The renderer pre-opens the tab synchronously on click (popup-blocker-safe) and navigates it to the handler\'s redirectUrl.'),

  /**
   * Zero-roundtrip new-tab target. A path template the renderer navigates
   * the pre-opened tab to IMMEDIATELY on click, skipping the action POST
   * entirely. Only valid together with `opensInNewTab`. The target endpoint
   * MUST perform all auth/authz itself (e.g. the cloud `/sso-open` endpoint,
   * which re-runs every check the POST half would have done). Supports the
   * `{recordId}` placeholder, URL-encoded on substitution.
   */
  newTabUrl: z.string().optional().describe('Direct new-tab URL template ({recordId} placeholder). When set with opensInNewTab, the renderer navigates the pre-opened tab here immediately — no action POST. The endpoint must enforce auth itself.'),

  /**
   * Post-success navigation (#9566 / #9474, maintainer ruling 2026-08-18) —
   * where to take the user after a server-executing action succeeds. Read for
   * `type: 'api'` and `type: 'script'` only (the refinement below refuses it on
   * other types: a `type:'url'` action already navigates via `target` +
   * `openIn`, and `modal`/`flow`/`form` dispatch on `target` with no success
   * event this key could ride — a declared key those paths never read is the
   * ADR-0078 silently-inert shape).
   *
   * **`navigate`** is a route/URL template. Its interpolation scope is the
   * CONTRACT recorded here; the interpolation ENGINE is the renderer's
   * (objectui `interpolateTarget`) and the scope members are measured from it:
   *
   * - `${param.X}` — value collected by the action's params dialog.
   * - `${ctx.X}` — the action context: `ctx.origin`, `ctx.apiBase`,
   *   `ctx.user.*`, `ctx.org.*`, `ctx.recordId`, `ctx.selection` (the same
   *   scope `target` interpolates today).
   * - `${result.X}` — **NEW with this key**: the action's server response
   *   payload. For a `type:'api'` action, the response body of the `target`
   *   call; for a `type:'script'` action, the handler's return value. This is
   *   what makes "server clones a record → jump to the new record" declarable:
   *   `navigate: '/apps/crm/tasks/${result.id}'`.
   *
   * Renderers MUST `encodeURIComponent` interpolated values in URL query
   * positions (same rule as `target`). A relative template is an SPA route
   * hop (no full page load, immune to popup blocking); an absolute URL is a
   * document navigation.
   *
   * **`openIn`** is a CLOSED two-member enum — `'self'` (default: navigate in
   * place) or `'newTab'` — deliberately not a general navigation DSL.
   * The default is MATERIALIZED (`.default('self')`, the file's convention —
   * `type`, `refreshAfter`, `ai.exposed`): declared navigation is an explicit
   * author choice, so parse output always carries the resolved member and no
   * consumer needs its own fallback. Note the spelling: `'newTab'` here
   * (matching the handler-return convention below), while the top-level
   * `openIn` for `type:'url'` spells it `'new-tab'` — the enum's error map
   * catches the crossover.
   *
   * **Relation to the handler-return convention** (objectui
   * `consoleServerAction.ts`, the `{ redirectUrl, openIn? }` shape fixed by
   * objectui#2967/#2904): that runtime surface keeps its shipped 17.0.0
   * semantics — a handler returning `{ redirectUrl }` WITHOUT `openIn` still
   * opens a NEW TAB (no silent behavior flip for existing handlers); a handler
   * may return `openIn: 'self'` explicitly to opt into the same-tab jump. The
   * defaults are deliberately split by surface: this schema key is a NEW
   * surface and defaults `'self'`; the handler convention is a shipped surface
   * and keeps new-tab.
   *
   * The console consumer is objectui's `ActionRunner` (`handlePostExecution`
   * → `readOnSuccessNavigation` → `navigateOnSuccess`), read at the
   * `.objectui-sha` pin `f8a9d0fb`. After an `api` or `script` action
   * succeeds, it interpolates `navigate` with the `${param.*}`, `${ctx.*}` and
   * `${result.*}` scopes and hands the URL to the console's router. It opens
   * a new tab only on `openIn: 'newTab'`. The liveness ledger's two
   * `onSuccess` rows are `live` and cite this reader.
   *
   * **The doubled channel is refused where the schema can see it** (#11519,
   * maintainer ruling 2026-08-24): a `type: 'script'` action declaring BOTH
   * this block AND `opensInNewTab: true` carries two post-success
   * destinations — `opensInNewTab` is the schema-visible marker of the
   * handler-returned `{ redirectUrl }` channel — and the refinement below
   * rejects the pair at authoring time. A handler that returns `redirectUrl`
   * WITHOUT the marker is runtime-only knowledge; that remainder gets a loud
   * dispatch-seam diagnostic in `@objectstack/runtime` (`action-execution.ts`,
   * `doubledPostSuccessNavigationWarning`), under which the interim renderer
   * precedence (declared `onSuccess` wins, objectui#5933) still decides the
   * navigation. ⛔ No `precedence` field — refusal, not arbitration, by ruling.
   */
  onSuccess: strictObject({
    surface: "this action's onSuccess block",
    history: ACTION_HISTORY,
    aliases: {
      // The handler-return convention's spelling, and the generic reaches.
      redirectUrl: 'navigate', url: 'navigate', to: 'navigate', route: 'navigate',
      path: 'navigate', target: 'navigate', navigateTo: 'navigate', href: 'navigate',
      open: 'openIn', tab: 'openIn',
    },
    guidance: {
      opensInNewTab:
        '`opensInNewTab` is the top-level pre-opened-tab flag for ASYNC redirect handlers, not an '
        + "`onSuccess` key — here the tab choice is `openIn: 'newTab'` (or `'self'`, the default).",
      newTab:
        "the tab choice is the closed enum `openIn: 'self' | 'newTab'` — write `openIn: 'newTab'`.",
    },
  }, {
    navigate: z.string().describe("Route/URL template navigated to after the action succeeds. Interpolates ${param.*} (params-dialog values), ${ctx.*} (origin/apiBase/user/org/recordId/selection) and ${result.*} (the action's server response payload — NEW with this key, e.g. ${result.id}). Relative = SPA route hop; renderers MUST encodeURIComponent values in query positions."),
    openIn: z.enum(['self', 'newTab'], {
      error: (issue) => (issue.input === 'new-tab'
        ? "`onSuccess.openIn` spells the new-tab member `'newTab'` (matching the handler-return "
          + "convention `{ redirectUrl, openIn }`), not `'new-tab'` — that kebab spelling belongs "
          + "to the top-level `openIn` key for `type:'url'` actions. Write `openIn: 'newTab'`."
        : undefined),
    }).default('self').describe("Where to perform the post-success navigation: 'self' (default — in-place SPA navigation, immune to popup blocking) or 'newTab'. Closed enum — no general navigation DSL."),
  }).optional().describe("Post-success navigation for type:'api' and type:'script' actions. `navigate` is a route/URL template interpolating ${param.*}, ${ctx.*} and ${result.*} (the server response); `openIn` defaults 'self'. The handler-return convention ({ redirectUrl } without openIn) keeps its 17.0.0 new-tab behavior."),

  // `aria` REMOVED (ADR-0049 enforce-or-remove; the triage record on the card,
  // comment 5860351140 on #20323, follows the `ChartConfig.aria` retirement
  // `2bf6ef18d`). The ledger graded this key `live` on an uncited "PARTIAL —
  // honored by a few objectui renderers" note, and no reader stood behind it.
  // Measured at this checkout's `.objectui-sha` pin `f8a9d0fb05`: none of the
  // surfaces that render an action — `action:button`, `action:icon`,
  // `action:menu`, `action:group`, `action:bar`, the grid's row and bulk
  // action menus, `record:quick_actions`, the declared-actions bar — reads an
  // action's `aria`. The only `schema.aria` readers there are the PLACING
  // nodes' own blocks (the `record:*` page components, the list view,
  // `element:button`'s props), which never look inside an action.
  //
  // Remove rather than enforce: every one of those surfaces already derives the
  // accessible name from the action's REQUIRED `label` — as the visible button
  // or menu-item text, or as `aria-label` on the icon-only `action:icon` and
  // the overflow-menu trigger — and the region that places the actions carries
  // the node-level `ariaLabel` / `ariaDescribedBy` / `role`. A per-action ARIA
  // block would be a second spelling of both, needing a precedence rule nobody
  // has written. One node, one accessibility vocabulary.
  //
  // `retiredKey()` rather than a bare deletion although this is a
  // `strictObject`: a bare delete is loud only as a generic unrecognized-key
  // report, which cannot carry the prescription (`aria-carrier-tombstones.test.ts`
  // pins the family). `AriaPropsSchema` is untouched — a key retirement, not a
  // def retirement. Sources are stripped by the D2 conversion
  // `action-aria-removed`.
  aria: retiredKey(
    '`action.aria` was removed in @objectstack/spec 17.5.0 (ADR-0049 enforce-or-remove) — no action ' +
    'surface ever applied it: the button, icon, menu, group and bar renderers, the row and bulk ' +
    'action menus and the record quick-actions toolbar all take the accessible name from the ' +
    "action's `label` and never read this block, so ARIA attributes declared here parsed and then " +
    'silently did not reach the DOM. Delete the key. The accessible name that IS applied is the ' +
    "action's required `label` — the visible button or menu-item text, and the `aria-label` of an " +
    'icon-only action — so write the name you meant there. To name the region that PLACES the ' +
    'actions, author `ariaLabel` / `ariaDescribedBy` / `role` in the `aria` block of the placing ' +
    'node: `page.components[].aria` (the component that renders the actions) or the list view ' +
    '`aria`. ' +
    'Run `os migrate meta --from 17` to list the mechanical edits for existing sources; `--write` applies the ones it can prove, and you apply the rest by hand.',
  ),

  // ADR-0010 — runtime protection envelope (internal — set by the loader).
  // `action` is a registered metadata type, so `MetadataPlugin`'s loader stamps
  // `_packageId` / `_provenance` on it. Undeclared, they were dropped on every
  // parse. This is the LAST name on the undeclared-envelope debt list the
  // structural walk opened with eight of.
  ...MetadataProtectionFields,
});

/**
 * The keys an `operation: 'update'` action must not carry, each with the
 * sentence that names the executor the key belongs to. A table rather than a
 * chain of `.refine()`s so every combination gets ONE issue at ITS key's path
 * — the same shape `BulkActionDefSchema`'s refinements use for the def side.
 */
const DECLARATIVE_UPDATE_REFUSED_KEYS: ReadonlyArray<readonly [key: string, why: string]> = [
  ['target',
    "`target` names a handler, URL, page, flow or endpoint — an `operation: 'update'` action dispatches on "
    + 'none of them: the platform action route writes `patch` to the current record. Drop `target`; to call '
    + "an endpoint of your own instead, use `type: 'api'` without `operation`."],
  ['body',
    "`body` is the inline handler of a `type: 'script'` action — an `operation: 'update'` action has no "
    + 'handler: the write IS the `patch`, performed by the platform as the caller. Drop `body`; to write '
    + 'through a handler of your own (system-elevated `ctx.api`), drop `operation` and `patch` instead.'],
  ['method',
    "`method` is the HTTP verb of a `type: 'api'` request — an `operation: 'update'` action makes no request "
    + 'of its own: the platform performs the write on the data plane. Drop `method`.'],
  ['bodyExtra',
    "`bodyExtra` is the static request body of a `type: 'api'` action — on an `operation: 'update'` action "
    + 'the static field values go in `patch`. Move them there and drop `bodyExtra`.'],
  ['bodyShape',
    "`bodyShape` shapes a `type: 'api'` request body — an `operation: 'update'` action sends no request body "
    + 'of its own. Drop `bodyShape`.'],
  ['recordIdParam',
    "`recordIdParam` injects the row id into a request body — an `operation: 'update'` action binds the "
    + 'current record from the invocation context and has no body to inject into. Drop `recordIdParam`.'],
  ['recordIdField',
    "`recordIdField` seeds `recordIdParam` — an `operation: 'update'` action binds the current record from "
    + 'the invocation context and injects nothing. Drop `recordIdField`.'],
  ['onSuccess',
    "`onSuccess` is not defined for an `operation: 'update'` action yet — its `${result.*}` scope is a "
    + "handler's return value, and a declarative update has no handler. Drop it; post-success navigation "
    + 'for the declarative write is a spec proposal, not a silent key.'],
  ['outcomeMessages',
    "`outcomeMessages` picks success copy by the `outcome` a handler returns — an `operation: 'update'` "
    + 'action has no handler: the platform performs the write and reports no outcome, so no entry could '
    + 'ever be chosen. Drop it; a fixed confirmation for the write is `successMessage`.'],
  ['opensInNewTab',
    "`opensInNewTab` pre-opens a tab for a handler-returned `{ redirectUrl }` — an `operation: 'update'` "
    + 'action has no handler and returns no redirect. Drop it.'],
  ['newTabUrl',
    "`newTabUrl` is the zero-roundtrip target of the pre-opened-tab flow — an `operation: 'update'` action "
    + 'has no such flow. Drop it.'],
];

/**
 * The mixing rule between the declarative single-record field write and the
 * rest of the action vocabulary (#14092), designed with the PR that landed it
 * and pinned in `action-row-update.test.ts`:
 *
 *  1. `operation: 'update'` keeps `type` at its default `'script'` — the
 *     platform action route — and any OTHER explicit `type` is refused. An
 *     explicit `type: 'script'` is indistinguishable from the materialized
 *     default at object level (a `.default()` has already run by the time a
 *     refinement sees the object — the #13897 asymmetry) and means the same
 *     thing, so it is accepted.
 *  2. Every key that names or shapes a dispatch the update does not make is
 *     refused at its own path ({@link DECLARATIVE_UPDATE_REFUSED_KEYS}).
 *  3. `patch` without `operation: 'update'` is refused (it would be silently
 *     dropped — ADR-0078); `operation: 'update'` with neither `patch` nor
 *     `params` is refused (nothing to write).
 *  4. `list_toolbar` is refused: no current record there.
 *
 * Deliberately NOT judged here: `objectName`. The same schema parses an
 * action embedded on an object (object implicit) and a standalone one in
 * `stack.actions` (only `objectName` can say), so the standalone form is
 * judged where standalone-ness is knowable — `defineStack`'s cross-reference
 * walk (`stack.zod.ts`, `collectGlobalUpdateActionErrors`).
 */
function refuseDeclarativeUpdateContradictions(
  data: {
    type?: string;
    operation?: string;
    patch?: unknown;
    params?: unknown;
    locations?: unknown;
  } & Record<string, unknown>,
  ctx: z.core.$RefinementCtx,
): void {
  if (data.operation !== 'update') {
    if (data.patch !== undefined) {
      ctx.addIssue({
        code: 'custom',
        path: ['patch'],
        message:
          "`patch` only applies to `operation: 'update'` — without it the action never writes fields, so "
          + "these values would be silently dropped. Add `operation: 'update'`, or for the static request "
          + "body of a `type: 'api'` action use `bodyExtra`.",
      });
    }
    return;
  }

  if (data.type !== undefined && data.type !== 'script') {
    ctx.addIssue({
      code: 'custom',
      path: ['type'],
      message:
        "`operation: 'update'` is performed by the platform action route — the route a `type: 'script'` "
        + "action posts to — so `type` stays at its default `'script'`; leave it off. A `type: '"
        + `${data.type}'\` action dispatches on \`target\` (\`api\` makes the browser call the endpoint itself) `
        + 'and never performs the write.',
    });
  }

  for (const [key, why] of DECLARATIVE_UPDATE_REFUSED_KEYS) {
    if (data[key] !== undefined) {
      ctx.addIssue({ code: 'custom', path: [key], message: why });
    }
  }

  const collectsParams = Array.isArray(data.params) && data.params.length > 0;
  if (data.patch === undefined && !collectsParams) {
    ctx.addIssue({
      code: 'custom',
      path: ['patch'],
      message:
        "An `operation: 'update'` action has nothing to write: declare a static `patch` (`{ status: 'done' }`), "
        + 'or `params` so the dialog collects the values, or both — the patch is merged UNDER the collected params.',
    });
  }

  if (Array.isArray(data.locations)) {
    data.locations.forEach((location, index) => {
      if (location !== 'list_toolbar') return;
      ctx.addIssue({
        code: 'custom',
        path: ['locations', index],
        message:
          "`list_toolbar` has no current record — an `operation: 'update'` action writes ONE record, the one it "
          + 'runs on. Use a record location (`list_item`, `record_header`, `record_more`, `record_section`) or, '
          + "for the selection bar, a `bulkActionDefs` entry on the list view (`{ operation: 'update', patch }`).",
      });
    });
  }
}

/**
 * The two places `outcomeMessages` (#21095) would parse clean and never be
 * read — refused at the key's own path, each with the rewrite. The third,
 * `operation: 'update'`, lives in {@link DECLARATIVE_UPDATE_REFUSED_KEYS}
 * beside `onSuccess`, the sibling key it is refused for the same reason as.
 *
 *  1. A type with no server response. Only `type: 'api'` (the `target` call's
 *     response body) and `type: 'script'` (the handler's return value) hand
 *     the console a success payload that can carry an `outcome` — the same
 *     two-type scope as `onSuccess`, whose `${result.*}` the copy interpolates.
 *  2. Beside `resultDialog`. A result dialog SUPPRESSES the success toast
 *     (the one-shot reveal opens an acknowledge-only dialog instead), and the
 *     toast is the only place outcome copy is shown.
 *
 * `type` has already been defaulted to `'script'` when this runs (the
 * #13897 asymmetry), so an action that never wrote `type` is in scope.
 */
function refuseInertOutcomeMessages(
  data: { type?: string; outcomeMessages?: unknown; resultDialog?: unknown },
  ctx: z.core.$RefinementCtx,
): void {
  if (data.outcomeMessages === undefined) return;

  if (data.type !== 'api' && data.type !== 'script') {
    ctx.addIssue({
      code: 'custom',
      path: ['outcomeMessages'],
      message:
        '`outcomeMessages` holds the success copy for each `outcome` a server handler reports, and only '
        + "`type: 'api'` and `type: 'script'` actions have a server response that can report one — on a "
        + `\`type: '${data.type}'\` action the map would parse clean and never be read. For one fixed `
        + 'confirmation use `successMessage`; to report distinct outcomes, run the work in a '
        + "`type: 'script'` handler (or a `type: 'api'` endpoint) whose success payload carries "
        + "`{ outcome: '<key>' }`.",
    });
  }

  if (data.resultDialog !== undefined) {
    ctx.addIssue({
      code: 'custom',
      path: ['outcomeMessages'],
      message:
        '`outcomeMessages` is success-TOAST copy, and `resultDialog` suppresses that toast: the one-shot '
        + 'reveal opens an acknowledge-only dialog instead, so no outcome message would ever be shown. '
        + 'Drop `outcomeMessages`, or drop `resultDialog` if the response holds nothing the user must '
        + 'copy now.',
    });
  }
}

export const ActionSchema = lazySchema(() => actionObject().refine((data) => {
  // Require `target` for types that reference an external resource
  if (TARGET_REQUIRED_TYPES.has(data.type) && !data.target) {
    return false;
  }
  return true;
}, {
  message: "Action 'target' is required when type is 'url', 'flow', 'modal', 'api', or 'form'.",
  path: ['target'],
}).refine((data) => {
  // A `script` action must be *executable*: it needs either an inline `body`
  // (the runtime invokes it in the sandbox) or a `target` naming a registered
  // bundle function. With neither, AppPlugin registers no engine handler and
  // the action fails at runtime with `Action '<name>' on object '*' not found`
  // (the #2169 Mark Done bug) — a soft failure invisible to build & shape
  // tests. Reject it at author/compile time instead.
  //
  // `operation: 'update'` (#14092) rides this same route with NEITHER: the
  // platform performs the write from the declaration, so there is no handler
  // to bind — and the block below refuses a `body`/`target` beside it.
  if (data.type === 'script' && data.operation !== 'update' && !data.body && !data.target) {
    return false;
  }
  return true;
}, {
  message:
    "A 'script' action requires either an inline `body` (sandboxed L1/L2 handler) or a `target` (a registered bundle function name).",
  path: ['body'],
}).refine((data) => {
  // The mirror image of the rule above: a `body` on a NON-script action never
  // runs. `type: 'modal' | 'url' | 'flow' | 'api' | 'form'` all dispatch on
  // `target` (the page to open, the URL, the flow, the endpoint), so the
  // renderer has no point at which it would invoke a body — the action opens
  // its target and the body is silently skipped.
  //
  // This is the same invisible-failure shape as #2169: it passes build, passes
  // shape tests, and only shows up as "the modal opened but nothing was
  // written" (#3530, where `type: 'modal'` + `params` + `body` was authored
  // expecting the body to run on submit). Reject it at author time and name the
  // fix — `type: 'script'` collects the same `params` and DOES run the body.
  if (data.type !== 'script' && data.body) {
    return false;
  }
  return true;
}, {
  message:
    "`body` only runs for `type: 'script'` — a non-script action dispatches on `target` and silently ignores its body. " +
    "To collect `params` and then run the body, use `type: 'script'`; to open a page/modal, drop the `body` and keep `type: 'modal'` with `target` naming the page.",
  path: ['body'],
}).refine((data) => {
  // ADR-0011: an exposed action must carry an LLM-facing description.
  if (data.ai?.exposed === true && !data.ai.description) {
    return false;
  }
  return true;
}, {
  message: 'ai.description is required (≥40 chars) when ai.exposed is true.',
  path: ['ai', 'description'],
}).refine((data) => {
  // ADR-0011: paramHints keys must reference a declared param (or the
  // auto-injected `recordId`), so a typo can't silently no-op.
  const hints = data.ai?.paramHints;
  if (!hints) return true;
  const known = new Set<string>(['recordId']);
  for (const p of data.params ?? []) {
    const key = p.name ?? p.field;
    if (key) known.add(key);
  }
  return Object.keys(hints).every((k) => known.has(k));
}, {
  message: 'ai.paramHints keys must match a declared param name (or "recordId").',
  path: ['ai', 'paramHints'],
}).refine((data) => {
  // #7428 — the structural half of #7278/#7309. `confirmText` beside a
  // non-empty `params` opens TWO sequential dialogs for ONE decision: the
  // console action runner awaits the confirm, THEN the param prompt
  // (objectui `packages/core/src/actions/ActionRunner.ts`), so the first
  // dialog already reads as "the action ran" while nothing has been sent.
  //
  // The two migrations repaired the 16 sites that shipped this (#7592 for
  // plugin-approvals, #7827 for the 14 in platform-objects); neither stops
  // the next one being written, which is what this refusal is for. Refuse
  // rather than warn: the in-repo census is 0, so nothing legal breaks, and
  // a warning that fires on every build of an untouched project is a check
  // nobody reads.
  //
  // **Scoped by SCHEMA BOUNDARY, deliberately — not by a param-optionality
  // heuristic.** The pair is CORRECT on a view's `bulkActionDefs`, where
  // `BulkActionDefSchema`'s own contract renders it as ONE dialog: params are
  // "inputs collected once before the run", `confirmText` sits "above the
  // affected-record summary", and 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. That schema is a separate `strictObject` with
  // its own refinements, so this refusal is structurally incapable of
  // reaching it; `action-confirm-params-guard.test.ts` pins that both ways.
  // The same holds for {@link InlineActionSchema}, which `.pick()`s from the
  // field factory rather than deriving from this chain — and which does not
  // pick `description`, so the remedy below has no slot there to move into.
  if (data.confirmText != null && Array.isArray(data.params) && data.params.length > 0) {
    return false;
  }
  return true;
}, {
  message:
    'An action that declares `confirmText` beside a non-empty `params` shows the user TWO dialogs '
    + 'for one decision — the confirm, then the param prompt, with nothing sent until the second. '
    + "Carry the confirm question in the action's top-level `description` instead (it renders under "
    + 'the param dialog\'s title) and drop `confirmText`: one condition, one wording, one dialog. '
    + 'Not `ai.description` — that is the LLM-facing tool contract. `confirmText` stays '
    + 'correct for a param-LESS action, where the confirm IS the only dialog, and for a view\'s '
    + '`bulkActionDefs`, where the pair renders one dialog by that schema\'s own contract.',
  path: ['confirmText'],
}).refine((data) => {
  // #9566/#9474 — `onSuccess` is scoped to the two action types that HAVE a
  // success event carrying a server response for `${result.*}` to read:
  // `api` (the `target` call's response body) and `script` (the handler's
  // return value). Same enforcement shape as the `body`-on-non-script
  // refinement above (#4352): a declared key the dispatch path never reads is
  // the invisible-failure class this file rejects at author time.
  if (data.onSuccess && data.type !== 'api' && data.type !== 'script') {
    return false;
  }
  return true;
}, {
  message:
    "`onSuccess` declares POST-SUCCESS navigation for a server-executing action, and only "
    + "`type: 'api'` and `type: 'script'` have a success event (a server response) it can ride — "
    + "on any other type the key would parse clean and never run (ADR-0078). For a `type:'url'` "
    + "action the navigation IS the action: put the destination in `target` and pick the tab with "
    + "the top-level `openIn`. For `modal`/`flow`/`form`, the action dispatches on `target` and no "
    + 'renderer reads a post-success hop today — if that capability is needed, it is a spec '
    + 'proposal, not a silent key.',
  path: ['onSuccess'],
}).refine((data) => {
  // #11519 (maintainer ruling 2026-08-24) — refuse the DOUBLED post-success
  // navigation channel where the schema can see it. Two channels can name a
  // destination for one `type: 'script'` action: the declared `onSuccess`
  // block, and the handler-returned `{ redirectUrl }`. The handler's return
  // value is runtime-only in general (`target` names an opaque registry
  // entry; `HookBodySchema` declares no return contract) — but
  // `opensInNewTab: true` IS a schema-visible declaration of the
  // handler-redirect channel: its whole contract is "pre-open a tab, then
  // drive it to the handler's returned `redirectUrl`". Declaring it beside
  // `onSuccess` states two destinations for one success; a renderer can only
  // perform one, so the other declaration is silently dead — the
  // declared-≠-enforced shape this file rejects at author time (#4352 /
  // ADR-0078). The runtime-only remainder (no marker, handler returns
  // `redirectUrl` anyway) is diagnosed loudly at the dispatch seam instead
  // (`@objectstack/runtime` `doubledPostSuccessNavigationWarning`).
  //
  // Scoped to `type: 'script'` — the ruled sentence. `opensInNewTab: false`
  // is not the marker (it declares the channel is NOT in use). The corpus was
  // measured at zero doubled producers (#11519), so nothing legal breaks.
  //
  // Internal anchor for the "interim precedence" the message names: objectui#5933
  // is where the renderer-side precedence was ruled. It lives here rather than in
  // the message, which is printed to a customer who has neither repo's tracker.
  if (data.type === 'script' && data.onSuccess && data.opensInNewTab === true) {
    return false;
  }
  return true;
}, {
  message:
    "A `type: 'script'` action declaring BOTH `onSuccess` and `opensInNewTab: true` carries two "
    + 'post-success destinations for one success: `opensInNewTab` pre-opens a tab for the '
    + 'HANDLER-RETURNED `{ redirectUrl }`, while `onSuccess.navigate` declares the hop in '
    + 'metadata. A renderer can perform only one — under the interim precedence '
    + "the declared `onSuccess` wins and the handler's `redirectUrl` is silently ignored — so the "
    + 'doubled declaration is refused at authoring time. Keep `onSuccess` and drop '
    + '`opensInNewTab` (and stop returning `redirectUrl` from the handler), or keep '
    + '`opensInNewTab` + the handler redirect and drop `onSuccess`. There is no `precedence` '
    + 'field, by ruling: one destination, declared in one place.',
  path: ['onSuccess'],
}).refine((data) => {
  // #11842 — enforce the documented co-constraint on `newTabUrl`. The field's
  // own doc has always said "Only valid together with `opensInNewTab`", and
  // every renderer read point agrees: objectui's pre-opened-tab wrapper
  // (`consoleServerAction.ts`) reads `newTabUrl` only behind
  // `action.opensInNewTab && newTabUrl`, and no other path reads the key at
  // all. So a lone `newTabUrl` parsed clean and did nothing — the
  // declared-≠-enforced shape this file rejects at author time (#4352 /
  // ADR-0078), arriving through a documented co-constraint rather than a
  // missing key.
  //
  // `opensInNewTab: false` is refused too, deliberately: unlike the #11519
  // rule above (where `false` declares the handler-redirect channel out of
  // use and the pair carries ONE destination), `newTabUrl` has no meaning
  // OUTSIDE the pre-opened-tab flow — a declared-off channel makes the key
  // exactly as dead as an undeclared one. The corpus was measured at zero
  // lone producers (this repo's examples/platform metadata, objectui
  // fixtures, and the cloud SSO producers all declare the pair), so nothing
  // legal breaks.
  if (data.newTabUrl !== undefined && data.opensInNewTab !== true) {
    return false;
  }
  return true;
}, {
  message:
    '`newTabUrl` is the zero-roundtrip target of the pre-opened-tab flow and is only valid '
    + 'together with `opensInNewTab: true` — the renderer pre-opens the tab synchronously on '
    + 'click and only THAT flow ever navigates to `newTabUrl`; no render path reads the key '
    + 'otherwise, so without the flag it would parse clean and never run (ADR-0078). If a '
    + 'pre-opened tab is intended, add `opensInNewTab: true`; otherwise drop `newTabUrl` '
    + '(behavior is unchanged — the lone key was never read). For a STATIC url action, new-tab '
    + 'behavior is `openIn: "new-tab"`, not this pair.',
  path: ['newTabUrl'],
}).refine((data) => {
  // `undoable` is fulfilled by TWO runtimes, not one, and only on two shapes:
  // `operation: 'update'`, where the framework runtime snapshots the merged
  // write bag (contract point 5 on that key), and `type: 'api'`, where the
  // pinned console snapshots — its readers gate the undo envelope on
  // `action.undoable` alone and never read `action.operation`, and they are
  // the whole recorded evidence for this key's `live` liveness verdict.
  // Every other combination — `script` / `url` and the dormant `flow` /
  // `modal` / `form` without `operation: 'update'` — has no reader at all:
  // the flag parses clean and no Undo ever appears, the declared-but-inert
  // shape this file rejects at author time (ADR-0078).
  //
  // A BLANKET requirement of `operation: 'update'` is deliberately NOT the
  // rule: it would refuse the published `ReassignLeadAction` example
  // (`type: 'api'` + `undoable`, no `operation`) at import time and every
  // console api action with undo. Writing "`type: 'api'` is fulfilled by the
  // console" into the contract is the point — the spec is the contract for
  // every runtime including the console, and a closed table of fulfillable
  // combinations is what the declared-is-delivered rule asks for.
  //
  // `type` has already been defaulted to `'script'` by the time a refinement
  // sees the object (the #13897 asymmetry), so the default route needs no
  // `undefined` arm here. The rule lives on `ActionSchema`'s chain alone, as
  // the #7428 refusal beside it does — an inline action is not a registered
  // action and has no console reader to speak for.
  if (data.undoable === true && data.operation !== 'update' && data.type !== 'api') {
    return false;
  }
  return true;
}, {
  message:
    '`undoable: true` has no runtime that can fulfil it on this action. An Undo is captured on '
    + "exactly two shapes: `operation: 'update'`, where the framework runtime snapshots the prior "
    + "value of every field the write bag touches, and `type: 'api'`, which the console snapshots. "
    + 'On any other action the flag parses clean and no Undo ever appears. Add '
    + "`operation: 'update'` with a `patch` for a declarative single-record write, or make this a "
    + "`type: 'api'` action calling an endpoint of your own — otherwise drop `undoable`.",
  path: ['undoable'],
}).superRefine(refuseDeclarativeUpdateContradictions)
  .superRefine(refuseInertOutcomeMessages)
  // Grade gate first, feature gate last: `requiresFeature` composes onto
  // whatever `visible` it finds, so this order keeps `features.*` the final
  // term — the convention the platform-objects feature-gate guard reads. One
  // transform, not two: a second pipe stage would move every refinement this
  // chain carries one level deeper in the emitted schema graph.
  .transform((data, ctx) => lowerRequiresFeature(lowerRequiresMembershipReach(data, ctx), ctx)));

export type Action = z.input<typeof ActionSchema>;
/** Post-parse shape of {@link Action} — defaults applied, transforms run (ADR-0122). */
export type ActionParsed = z.infer<typeof ActionSchema>;
export type ActionParam = z.input<typeof ActionParamSchema>;
/** Post-parse shape of {@link ActionParam} — defaults applied, transforms run (ADR-0122). */
export type ActionParamParsed = z.infer<typeof ActionParamSchema>;

/**
 * Legacy spellings an inline action may carry, folded to canonical on parse.
 *
 * `navigation` is a `type` no spec enum ever declared, and `to` a `target` no
 * spec schema ever declared — yet both are what cloud's tenant pages actually
 * write on an `element:button` (`{ type: 'navigation', to: PRICING_ROUTE }`,
 * five sites across the billing and pricing funnel). They reached a real
 * dispatcher: objectui's `ActionRunner` has a `navigation` case reading
 * `nav.to ?? nav.target`.
 *
 * `url` + `target` is the canonical pair, and it is also the *better* one — the
 * runner's `url` path adds `${param.X}` / `${ctx.X}` interpolation, `apiBase`
 * promotion for `/api/…` paths, and popup-blocker-safe `openIn` handling, none
 * of which the `navigation` path has. So this is a bridge with an end state, not
 * a second vocabulary: authored `navigation`/`to` keep validating, parse output
 * is always `url`/`target`, and the aliases get a `retiredKey` tombstone once
 * the producers are migrated.
 *
 * Exported so a producer can normalize before writing, rather than inventing its
 * own fold. objectstack-ai/objectui#2997.
 */
export function normalizeInlineAction(value: unknown): unknown {
  if (!value || typeof value !== 'object' || Array.isArray(value)) return value;
  const v = value as Record<string, unknown>;
  const needsType = v.type === 'navigation';
  const needsTarget = v.target === undefined && typeof v.to === 'string';
  if (!needsType && !needsTarget && !('to' in v)) return value;
  const out: Record<string, unknown> = { ...v };
  if (needsType) out.type = 'url';
  if (needsTarget) out.target = v.to;
  delete out.to;
  return out;
}

/**
 * An action declared **inline** on a UI surface, rather than registered by name.
 *
 * The execution half of {@link ActionSchema} — `.pick()`ed from the same field
 * definitions, so the `describe()` text, the operator vocabulary and the
 * `target`-required rule are shared rather than restated — minus everything that
 * only means something for a *registered* action: `objectName`, `locations`,
 * `order`, `ai` exposure, `requiredPermissions`, `visible`/`disabled`
 * predicates, `resultDialog`.
 *
 * `name` and `label` are optional here, which is the substantive difference.
 * `ActionSchema` requires both because a registry entry needs an identity and a
 * menu label; an inline action has neither — the host supplies the label (an
 * `element:button` has its own `label` prop, and requiring `action.label` too
 * would mean writing it twice).
 *
 * Scoped deliberately to what a host actually honours. `element:button`'s
 * renderer forwards exactly these fields to the `ActionRunner`; `icon` and
 * `variant` are excluded because the button has its own, and `body` because a
 * page button running an inline sandboxed script is a separate decision. Widen
 * this when a renderer widens, not before — a declared field no renderer reads
 * is the failure this schema exists to stop.
 *
 * **`bodyExtra` is the one field picked AHEAD of its renderer, knowingly**
 * (#5777, maintainer ruling 2026-08-06). It is the only authorized way for an
 * inline `type:'api'` action to carry a static request payload: `params` is the
 * parameter DEFINITION array and the ruling refused a same-name union, so
 * without this pick the inline shape has no payload key at all — the cost the
 * issue's option C names. The pick is therefore what makes the ruled direction
 * A reachable from a page, and it is deliberately taken before objectui's half.
 *
 * The divergence that buys, stated rather than hidden: objectui's
 * `element:button` renderer builds an explicit forward list
 * (`packages/components/src/renderers/basic/elements.tsx`) that does not yet
 * include `bodyExtra`, so between this landing and that follow-up an inline
 * `bodyExtra` validates, publishes, and is dropped one hop before the runner.
 * The runner and the console `apiHandler` below it already read the key — the
 * missing hop is the forward list alone. Direction of the window: spec accepts
 * ahead of the renderer, never the reverse. Tracked as the objectui card the
 * ruling splits out under `Blocked-by:` this change; the general rule above is
 * unchanged for every other field.
 */
export const InlineActionSchema = lazySchema(() => z.preprocess(
  normalizeInlineAction,
  actionObject().pick({
    type: true,
    name: true,
    label: true,
    target: true,
    openIn: true,
    method: true,
    params: true,
    bodyExtra: true,
    confirmText: true,
    successMessage: true,
    errorMessage: true,
    refreshAfter: true,
    opensInNewTab: true,
  }).partial({
    name: true,
    label: true,
  }).refine((data) => {
    // The same rule ActionSchema's first refinement applies, for the same
    // reason: a `url`/`flow`/`modal`/`api`/`form` action with no `target` has
    // nothing to dispatch to and fails silently at click time.
    if (TARGET_REQUIRED_TYPES.has(data.type) && !data.target) return false;
    return true;
  }, {
    message: "Inline action 'target' is required when type is 'url', 'flow', 'modal', 'api', or 'form' (`to` is accepted as a legacy spelling).",
    path: ['target'],
  }),
));

/**
 * An inline action as an author writes it: the INPUT type of the object {@link InlineActionSchema}
 * hands its body to, read off the pipe's `out` member.
 *
 * [#19920] Deliberately NOT `z.input<typeof InlineActionSchema>`. That schema is a `z.preprocess`,
 * whose input type is the preprocess function's parameter — `unknown` for
 * {@link normalizeInlineAction} — so this name used to type-check any value at all. The pipe's
 * `out` member is the `.pick()`ed object itself, so the type now carries the shape its fields
 * declare. `inline-action-type.test.ts` pins both halves.
 *
 * A static type, not the door's verdict, in both directions: the door accepts bodies this type
 * refuses (the legacy `type: 'navigation'` and `to` spellings, which the preprocess folds onto
 * `url` / `target`, are canonical-only here on purpose), and refuses bodies it admits (the
 * `target`-required refinement is not a type). `InlineActionSchema` remains the only judge.
 */
export type InlineAction = z.input<(typeof InlineActionSchema)['out']>;
/** Post-parse shape of {@link InlineAction} — defaults applied, transforms run (ADR-0122). */
export type InlineActionParsed = z.infer<typeof InlineActionSchema>;

/**
 * Action Factory Helper
 */
export const Action = {
  create: (config: z.input<typeof ActionSchema>): Action => ActionSchema.parse(config),
} as const;

/**
 * Type-safe factory for a global or object action. Validates at authoring time via
 * `.parse()` and accepts input-shape config (optional defaults, CEL
 * shorthand) — preferred over a bare `: Action` literal.
 */
export function defineAction(config: z.input<typeof ActionSchema>): ActionParsed {
  return ActionSchema.parse(config);
}