@object-ui/core 17.3.0 → 17.5.0

package/dist/actions/ActionRunner.js

@@ -6,8 +6,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { ExpressionEvaluator } from '../evaluator/ExpressionEvaluator';
+import { hasDeclaredPredicate } from '../evaluator/declaredPredicate';
 import { globalUndoManager } from './UndoManager';
-import { warnOnUnknownActionKeys } from './actionKeys';
+import { warnOnDeprecatedObjectParams, warnOnUnknownActionKeys } from './actionKeys';
 /**
  * Bind the server-CEL-parity `os.user` identity alias into an action context
  * (#2358 trap 1). `@objectstack/spec` documents the canonical CEL identity
@@ -27,6 +28,145 @@ function withIdentityAlias(context) {
         return context;
     return { ...context, os: { ...(os && typeof os === 'object' ? os : {}), user } };
 }
+/**
+ * The query param naming the record a form route opens (`?recordId=<id>`).
+ *
+ * The console's reserved-param registry (`@object-ui/app-shell`,
+ * `src/urlParams.ts` → `RECORD_DRAWER_PARAM`) owns this spelling and
+ * `apps/console`'s `FormPage` re-declares it as `FORM_RECORD_ID_PARAM`. It is a
+ * literal in all three places because `@object-ui/core` sits BELOW both in the
+ * dependency graph and cannot import either; the console's `FormPage.test.ts`
+ * pins the spellings equal so they cannot drift apart in silence.
+ */
+const FORM_RECORD_ID_PARAM = 'recordId';
+/**
+ * The query param carrying the OBJECT the forwarded {@link FORM_RECORD_ID_PARAM}
+ * belongs to (objectui#4292).
+ *
+ * It is an ASSERTION, never an override: the form's object always comes from the
+ * FormView metadata, and this param exists solely so the consumer can refuse
+ * when the two disagree. (The registry's `formObject` is the other thing — it
+ * SELECTS which object the record-form overlay edits. Same `<param>Object`
+ * naming, deliberately opposite powers, which is why they are separate names on
+ * separate surfaces.) Widening it into a selector would hand any hand-authored
+ * URL the ability to point a form at an arbitrary object — the hole this closes,
+ * re-opened from the other side.
+ */
+const FORM_RECORD_OBJECT_PARAM = 'recordObject';
+/**
+ * The object the firing context's record belongs to, or `undefined` when the
+ * host did not say (objectui#4292).
+ *
+ * `context.objectName` is MEASURED to be this repo's one spelling of that fact,
+ * not a new convention invented here:
+ *
+ *  - `@object-ui/react`'s `ActionProvider` documents the flat trio `record`,
+ *    `user`, `objectName` and mirrors it into the canonical `ctx.*` scope;
+ *  - `useConsoleActionRuntime` seeds `context: { ...(objectName ? { objectName }
+ *    : {}), … }` — so every console surface that fires a record action
+ *    (`DeclaredActionsBar`, `ObjectView`, `RecordDetailView`) already publishes
+ *    it, and `RecordDetailView` passes it explicitly a second time;
+ *  - `app-shell`'s `recordFormNavigation` resolver already reads exactly this
+ *    key as its last precedence step for `navigate_create` / `navigate_edit`.
+ *
+ * `action.objectName` is deliberately NOT consulted. It declares which object an
+ * ACTION belongs to, which is a statement about the action's placement, not
+ * about the record the id was read from — and trusting metadata about the action
+ * to describe the record is precisely the conflation that made this defect
+ * possible.
+ */
+function readContextObjectName(context) {
+    const name = context.objectName;
+    return typeof name === 'string' && name.trim() !== '' ? name.trim() : undefined;
+}
+/**
+ * Whether opening FormView `viewName` from a record of `contextObject` would
+ * cross an object boundary (objectui#4292).
+ *
+ * View identity is `<object>.<key>` (ADR-0017; `viewEnvelope` builds exactly
+ * that, `defaultListViewId` compares exactly this way), so the question is
+ * answered as a PREFIX match against the object we already hold rather than by
+ * parsing an object name out of the view name — the target's object is a fact
+ * the metadata owns, and this runner only asks whether it is the one in hand.
+ *
+ * Answers `false` — "not comparable, carry on" — whenever either end is missing:
+ * no `contextObject` (host published none), or an unqualified `viewName` (no
+ * dot, so it names no object). Only a qualified name under a DIFFERENT object
+ * is a boundary crossing.
+ */
+function crossesObjectBoundary(viewName, contextObject) {
+    if (!contextObject)
+        return false;
+    if (!viewName.includes('.'))
+        return false;
+    return !viewName.startsWith(`${contextObject}.`);
+}
+/*
+ * ## The two predicate gates in `execute`, and the one question they ask first
+ *
+ * `execute` gates on `condition` and on `disabled`, and both need ONE question
+ * answered before evaluating — "is a gate DECLARED here, i.e. is there a
+ * condition to reach a verdict on?" — for OPPOSITE reasons, which is exactly why
+ * the question has to be asked separately from the verdict:
+ *
+ *   - `disabled` (objectui#3848): an EMPTY predicate must not be handed to
+ *     `evaluateCondition`, whose answer for "no condition" is `true` = BLOCKED.
+ *     Measured consequence of asking `!= null && !== false` instead:
+ *     `disabled: ''` returned `{ success: false, error: 'Action is disabled' }`
+ *     and the handler never ran.
+ *   - `condition` (objectui#3872): a DECLARED-FALSE predicate must not be
+ *     skipped by a truthiness test. `if (action.condition)` never asked whether
+ *     a gate was declared, so `condition: false` — the most explicit "never
+ *     execute" an author can write — landed on `if (false)`, the evaluator was
+ *     never consulted, and the action RAN. Measured on `origin/main` @
+ *     `2937bcf7d`: `condition: false` → `{"success":true}`, handler ran, while
+ *     the semantically identical `{ dialect: 'cel', source: 'false' }` was
+ *     refused. Asking "declared?" routes `false` to `evaluateCondition`, which
+ *     short-circuits booleans (`if (typeof condition === 'boolean') return
+ *     condition`) and blocks.
+ *
+ * Both read {@link hasDeclaredPredicate} — the repo's one definition of that
+ * question, in `evaluator/declaredPredicate.ts` beside the normalizer it is
+ * derived from, with the scope objectui#3850 ruled on (`''` / whitespace-only /
+ * empty-`source` envelope / non-predicate junk are NOT declared; a declared
+ * `false` IS). This gate arrived here first as a module-private helper with a
+ * scope note saying it stayed private until that ruling landed; it has, so the
+ * definition moved down a layer and the renderer side reads the same one
+ * (`components/renderers/action/visibility-gate.ts` re-exports it as
+ * `hasDeclaredVisibilityGate`, `SchemaRenderer`'s `disabled` chain calls it).
+ *
+ * ## Why the gates normalize to DECIDE but evaluate the RAW value
+ *
+ * Historically the two were not interchangeable for a string already spelled as
+ * a `${…}` template: `toPredicateInput` assumed a bare expression and wrapped
+ * unconditionally, so `'${x}'` became `'${${x}}'`, which no longer matched the
+ * single-template fast path and did not parse — leaving a constant verdict whose
+ * direction was set by the caller's error policy (fail-soft got the unparsed
+ * string back, `Boolean(…)` = `true`; fail-closed got a throw). On `disabled`
+ * that meant "always blocked", on `condition` the opposite ("always execute").
+ * That defect was objectui#3871, fixed at the normalizer: an already-`${…}`
+ * string is returned untouched, the normalizer is idempotent, and
+ * `evaluateCondition(toPredicateInput(raw))` agrees with
+ * `evaluateCondition(raw)` on every shape these gates accept.
+ *
+ * The gates still read the raw value. Nothing forces the change now that the two
+ * agree, and it would be churn on the execution path rather than a fix — but the
+ * reason has shifted from "must" to "no reason to", so the equality is pinned
+ * next to each gate's suite (`ActionRunner.disabledGate.test.ts` /
+ * `ActionRunner.conditionGate.test.ts`, the two cases that replaced the
+ * objectui#3871 tripwires) instead of being assumed. Every non-empty shape —
+ * boolean, bare CEL, `${…}` template, `{ dialect, source }` envelope — keeps the
+ * verdict it reaches today.
+ *
+ * The `visible`-filter template in `ActionEngine.getActionsForLocation` used to
+ * be the one place this scope was NOT shared: its non-predicate branch kept a
+ * historical `Boolean(raw)` coercion, so `0` there meant "hidden" — fail-CLOSED
+ * on junk, the opposite of what this module committed to for `disabled`
+ * (`catch { isDisabled = false }`). That filter now reads
+ * {@link hasDeclaredPredicate} too (objectui#3957), so a value that is not a
+ * predicate at all decides nothing on either key, at either entry: `0` / `{}` are
+ * "no gate" here, in the engine filter, and in the shared definition.
+ */
 export class ActionRunner {
     constructor(context = {}) {
         Object.defineProperty(this, "handlers", {
@@ -191,16 +331,45 @@ export class ActionRunner {
             // binds a handler, and binding no handler silently is the #2169 "Mark Done
             // does nothing" shape. Dev-only, warn-once, changes nothing (#4075 step 1).
             warnOnUnknownActionKeys(action);
+            // The compat window for the object-form `params` payload (#5777, maintainer
+            // ruling 2026-08-06 direction A). Checked HERE, before the param-collection
+            // block below rewrites `action.params` into a values map — after that point
+            // an action that authored a legitimate ActionParam[] DEFINITION array also
+            // carries an object under `params`, and the warning could no longer tell the
+            // two apart. Dev-only, warn-once, changes nothing.
+            warnOnDeprecatedObjectParams(action);
             // Resolve the action type
             const actionType = action.type || action.actionType || action.name || '';
-            // Conditional execution
-            if (action.condition) {
+            // Conditional execution. Ask "is a `condition` gate DECLARED?" — not "is
+            // the raw value truthy?" (objectui#3872). Truthiness cannot answer that
+            // question, and on this key it answered it in the OVER-PERMISSIVE
+            // direction: `condition: false` (the most explicit "never execute" an
+            // author can write, and what a template that switches an action off
+            // emits) fell on `if (false)`, so the evaluator was never consulted and
+            // the action executed anyway — while the semantically identical
+            // `{ dialect: 'cel', source: 'false' }` was refused. `evaluateCondition`
+            // short-circuits booleans, so once the gate asks the right question the
+            // verdict needs no boolean branch of its own. See `hasDeclaredPredicate`
+            // for the shared "declared?" scope (objectui#3850) and for why the verdict
+            // still reads the RAW value (`toPredicateInput` used to double-wrap an
+            // already-`${…}` string into a constant verdict — objectui#3871, fixed at
+            // the normalizer; on THIS key that constant meant "always execute").
+            if (hasDeclaredPredicate(action.condition)) {
                 const shouldExecute = this.evaluator.evaluateCondition(action.condition);
                 if (!shouldExecute) {
                     return { success: false, error: 'Action condition not met' };
                 }
             }
-            if (action.disabled != null && action.disabled !== false) {
+            // Ask "is a `disabled` gate DECLARED?" — not "is the key present and not
+            // `false`?" (objectui#3848). The old test let every EMPTY predicate reach
+            // `evaluateCondition`, whose answer for "no condition" is `true`, which on
+            // this key means BLOCKED: `disabled: ''` / `'   '` /
+            // `{ dialect: 'cel', source: '' }` all returned `Action is disabled` with
+            // the handler never invoked. See `hasDeclaredPredicate` above for why the
+            // gate normalizes to decide while the verdict below reads the RAW value
+            // (historically load-bearing: `toPredicateInput` double-wrapped an
+            // already-`${…}` string — objectui#3871, now fixed, so the two agree).
+            if (hasDeclaredPredicate(action.disabled)) {
                 // `disabled` may be a boolean, a CEL string, or the normalized envelope
                 // `{ dialect, source }` (what `objectstack build` emits). The previous
                 // code only evaluated the STRING form and treated any object as truthy,
@@ -452,12 +621,25 @@ export class ActionRunner {
                         'build one with createServerActionHandler from @object-ui/core.',
                 };
             }
-            // ActionDef is open-ended (`[key: string]: any`), so hand-authored
-            // metadata that never passed through the spec parser still compiles with
-            // the retired key. Carry the same prescription the spec's tombstone does,
-            // for the same reason: a bare "no script provided" reads as "you forgot a
-            // field" to an author who did write one.
-            if (typeof action.execute === 'string') {
+            // Read off an UNTYPED view of the action on purpose, and this branch
+            // survives step 3 on purpose (objectstack#4075).
+            //
+            // `ActionDef` no longer declares `execute` — nor any open index signature
+            // — so `tsc` now catches the retired key at every site that AUTHORS an
+            // action literal in code. That is the half of the problem the type can
+            // reach. It is not this half: #3903 established that stored
+            // `sys_metadata` rows are rehydrated UNPARSED, so metadata written before
+            // spec 17 arrives here as a plain object the compiler never saw, still
+            // carrying `execute`. Declaring the key to make this read compile would
+            // re-legitimize a tombstone (#3855 removed it; the spec keeps it only to
+            // reject it BY NAME), and deleting the branch would send those rows back
+            // to a bare "no script provided" — which reads as "you forgot a field" to
+            // an author who did write one, the objectstack#2169 shape.
+            //
+            // So: the cast is the honest spelling of "a key this type deliberately
+            // does not have, read from a row this type never validated".
+            const retiredExecute = action.execute;
+            if (typeof retiredExecute === 'string') {
                 return {
                     success: false,
                     error: '`execute` was removed in @objectstack/spec 17 — rename the key to `target`. ' +
@@ -563,12 +745,24 @@ export class ActionRunner {
             return { success: true };
         }
         // `openIn` is the first-class, declarative switch (ActionSchema.openIn);
-        // it wins over the legacy `navigate.newTab` / `params.newTab` escape
-        // hatches and the external-URL heuristic.
+        // it wins over the legacy `navigate.newTab` escape hatch and the
+        // external-URL heuristic.
+        //
+        // `params.newTab` used to sit between them and is RETIRED (objectui#4097,
+        // executing the objectstack#6828 maintainer ruling of 2026-08-10). It could
+        // only ever fire on an OBJECT-form `params`, which the spec has always
+        // refused on an action (`params` is `z.array(ActionParamSchema)`), so no
+        // validated stack could reach it; and no internal caller synthesizes a
+        // navigation directive into that bag — the runtime value bags carry
+        // collected dialog values, `_selectedIds` and `_rowRecord`, never `newTab`.
+        // Removing it also closes the collision hazard where a params dialog
+        // declaring a field literally named `newTab` would have had the user's own
+        // input silently steer navigation. The spec's refusal message names the
+        // sanctioned spelling: `openIn: 'new-tab'`.
         const openIn = source.openIn ?? action.openIn;
         const newTab = openIn === 'new-tab' ? true
             : openIn === 'self' ? false
-                : (source.newTab ?? action.params?.newTab ?? isExternal);
+                : (source.newTab ?? isExternal);
         // History semantics, the one thing the `navigation` shape carries that
         // `ActionSchema` has no field for. Omitted from the handler call when
         // unset so hosts see the same options object they always did.
@@ -675,6 +869,37 @@ export class ActionRunner {
      * through to `executeActionSchema` and silently no-opped (the "Log Time does
      * nothing" report). The current record id is forwarded as `?recordId=` for
      * hosts that support it; the form route ignores unknown query params.
+     *
+     * ## An id never travels without its object (objectui#4292)
+     *
+     * `?recordId=` names an id and nothing else, so the consumer has to pick an
+     * object to resolve it against, and the only one it can pick is the FormView's
+     * own target object (`/forms/:name` does exactly that since objectui#4278).
+     * That is right whenever the action fired from a record OF that object, and
+     * nothing here used to check that it did: `target: 'showcase_task.edit'` on an
+     * Account record header is publishable metadata, and with per-table integer
+     * keys `GET /data/showcase_task/42` cheerfully answers for Account 42. Before
+     * #4278 the damage stopped at a duplicate insert; now that the route honours
+     * the param, the same mis-scoped action PATCHes a different object's record
+     * with no error anywhere. So the id is forwarded only when the two objects
+     * MATCH, and the object identity rides along as the consumer's second half of
+     * the check ({@link FORM_RECORD_OBJECT_PARAM}).
+     *
+     * The three outcomes, and why the third preserves rather than refuses:
+     *
+     *  - **match** — forward `?recordId=&recordObject=`. The #4278 edit path,
+     *    plus the identity the consumer re-checks against its own view metadata;
+     *  - **mismatch** — forward NEITHER, i.e. the bare `/forms/:name`. A "log
+     *    time" action fired from a Task at another object's create view is not a
+     *    broken edit, it is a CREATE that happens to be launched from a record —
+     *    which is exactly what this route did before #4278 taught it to read the
+     *    param. Refusing here would break a shape that works;
+     *  - **not comparable** — either end unknown ⇒ forward as before. A host that
+     *    publishes no `objectName`, or an unqualified target name, gives this
+     *    runner nothing to compare; tightening on absent information would turn
+     *    working edit flows into creates on every such host. The guard only ever
+     *    fires on information it actually has, and the consumer half applies the
+     *    same rule to a missing `recordObject`.
      */
     async executeForm(action) {
         const name = this.evaluator.evaluate(action.target);
@@ -684,7 +909,13 @@ export class ActionRunner {
         const recordId = (this.context.record && this.context.record.id) ??
             (this.context.data && this.context.data.id);
         const base = `/forms/${name}`;
-        const to = recordId != null ? `${base}?recordId=${encodeURIComponent(String(recordId))}` : base;
+        const contextObject = readContextObjectName(this.context);
+        const to = recordId == null || crossesObjectBoundary(name, contextObject)
+            ? base
+            : `${base}?${FORM_RECORD_ID_PARAM}=${encodeURIComponent(String(recordId))}` +
+                (contextObject
+                    ? `&${FORM_RECORD_OBJECT_PARAM}=${encodeURIComponent(contextObject)}`
+                    : '');
         if (this.navigationHandler) {
             this.navigationHandler(to, { external: false });
             return { success: true };
@@ -709,6 +940,60 @@ export class ActionRunner {
         }
         return this.navigateTo(action, rawUrl, nav);
     }
+    /**
+     * Assemble the request body for the runner's OWN `executeAPI` — the path taken
+     * when no host registered an `api` handler.
+     *
+     * `bodyExtra` is merged LAST, which is the spec's documented semantics for the
+     * key ("Static request-body fields for a `type:'api'` action, merged last
+     * (overrides user params)") and what the console's `apiHandler` already does on
+     * both of its branches. Before objectstack#6837 this path read `action.params`
+     * alone and never looked at `bodyExtra` at all, so an action whose payload lives
+     * entirely in `bodyExtra` — the shape the ADR-0087 conversion produces from an
+     * old object-form `params` page — POSTed an empty body here.
+     *
+     * `params` contributes only in its DEPRECATED non-array form (the compat window
+     * #5777 opened; see `warnOnDeprecatedObjectParams`). An ARRAY `params` is a
+     * parameter DEFINITION list, not a payload: it reaches this method unconsumed
+     * only when no `paramCollectionHandler` is mounted, and POSTing the definitions
+     * as the request body was never a payload any endpoint wanted. It now falls
+     * through to the context record like an absent `params` does.
+     *
+     * `bodyShape` then decides how that payload is WRAPPED, and the wrap covers the
+     * collected payload ONLY — `bodyExtra` stays at the top level. That is the
+     * spec's own wording for the key ("`{ wrap: 'data' }` nests the user-collected
+     * params under that key, while `recordIdParam` and other top-level keys stay
+     * flat") and what both console read-sites already do, so the key means one
+     * thing on every path that honours it. Until objectstack#6938 this path did not
+     * read it at all: the console `apiHandler` wrapped and the runner's own fallback
+     * did not, so the same action changed body shape with the host it ran under.
+     */
+    buildApiRequestBody(action) {
+        const asRecord = (value) => (value && typeof value === 'object' && !Array.isArray(value)
+            ? value
+            : undefined);
+        const bodyExtra = asRecord(action.bodyExtra);
+        const base = asRecord(action.params) ?? this.context.data;
+        // `'flat'` (and an absent//malformed value) means no wrapping — the same
+        // predicate the console read-sites use, so an off-spec `bodyShape` degrades
+        // to the documented default here too instead of producing a `{ undefined: … }`
+        // key on the wire.
+        const shape = action.bodyShape;
+        const wrap = shape && typeof shape === 'object' && typeof shape.wrap === 'string' && shape.wrap
+            ? shape.wrap
+            : undefined;
+        if (wrap) {
+            // The payload nests; `bodyExtra` rides flat beside it. No key collision to
+            // resolve in this branch — that is the point of the wrap — so "merged last"
+            // is preserved by construction.
+            return { [wrap]: base ?? {}, ...bodyExtra };
+        }
+        // Nothing to merge: hand back the historical value as-is, so a host passing a
+        // non-object `context.data` still serializes exactly what it used to.
+        if (!bodyExtra)
+            return base ?? {};
+        return { ...asRecord(base), ...bodyExtra };
+    }
     /**
      * Execute API action — supports both simple string endpoint and complex ApiConfig.
      */
@@ -728,7 +1013,7 @@ export class ActionRunner {
                 // Simple string endpoint
                 url = this.interpolateTarget(apiConfig, action);
                 method = action.method || 'POST';
-                body = JSON.stringify(action.params || this.context.data || {});
+                body = JSON.stringify(this.buildApiRequestBody(action));
             }
             else {
                 // Complex ApiConfig
@@ -749,7 +1034,7 @@ export class ActionRunner {
                         : JSON.stringify(config.body);
                 }
                 else if (method !== 'GET' && method !== 'HEAD') {
-                    body = JSON.stringify(action.params || this.context.data || {});
+                    body = JSON.stringify(this.buildApiRequestBody(action));
                 }
             }
             const fetchInit = { method, headers };
@@ -816,6 +1101,37 @@ export class ActionRunner {
     interpolateTarget(target, action) {
         if (typeof target !== 'string' || target.indexOf('${') === -1)
             return target;
+        // ── The `${param.X}` scope is an INTERNAL runtime value bag, not an
+        //    authoring surface (objectui#4097 ruling B, 2026-08-11) ──────────────
+        //
+        // A non-array `params` reaches this line from ONE direction only: a host
+        // synthesizing a value bag on its way into `runner.execute()` — the
+        // collected values a param dialog just gathered, `_selectedIds` from an
+        // aggregate bulk dispatch, `_rowRecord` from a row surface. Eight internal
+        // producers, measured. No AUTHOR can put a value here: `ActionSchema.params`
+        // is `z.array(ActionParamSchema)`, so the object form is refused at parse,
+        // and the refusal message names the sanctioned spellings.
+        //
+        // That refusal is why this branch survived objectui#4097 while its two
+        // siblings did not. The objectstack#6828 maintainer ruling targeted the
+        // AUTHORING vocabulary — "a key with three meanings and no authorized
+        // spelling for the third" — and both authored meanings are now handled
+        // upstream at parse; PR objectui#4262 removed the third runtime read
+        // (`params.newTab`). What is left here is a channel no author can reach or
+        // observe, so removing it would spend a four-package runtime-contract
+        // migration on an already-unreachable shape. Option A was declined for
+        // exactly that reason: "plumbing expansion with zero pull".
+        //
+        // ⚠️ The hazard the ruling flagged, recorded here so the next reader sees
+        // it at the code rather than in a closed thread: this line's safety rests
+        // ENTIRELY on the producer refusing an authored object-form `params`. If a
+        // future spec loosening ever admits one, an authored scope silently becomes
+        // reachable again — and it would arrive as an interpolation source for URLs
+        // and api targets, which is the shape a params dialog field named for a
+        // navigation directive could steer. The guards are the upstream refusal pin
+        // and the two local pins (`ActionRunner.resultDialog.test.ts`,
+        // `ActionRunner.test.ts`); a spec change that turns them red is the signal,
+        // not a nuisance.
         const params = (action.params && typeof action.params === 'object' && !Array.isArray(action.params))
             ? action.params
             : {};

package/dist/actions/actionKeys.d.ts

@@ -6,26 +6,46 @@
  * LICENSE file in the root directory of this source tree.
  */
 /**
- * What an action is allowed to carry — objectstack#4075 step 1.
+ * What an action is allowed to carry — objectstack#4075, all three steps.
  *
- * `ActionDef` ends with `[key: string]: any`, so it accepts any key of any type.
- * Concretely (objectui#2990): deleting `ActionDef.execute` produced ZERO compile
- * errors even though the field had just been removed, and stale metadata still
- * authoring `execute: 'markDone'` type-checks today. The same deletion against
- * `@object-ui/types`' `ActionSchema` — which has no index signature — correctly
- * produced `TS2353` at the authoring site. One of the two readers can catch a
- * retired key; the other is structurally incapable.
+ * `ActionDef` used to end with `[key: string]: any`, so it accepted any key of
+ * any type. Concretely (objectui#2990): deleting `ActionDef.execute` produced
+ * ZERO compile errors even though the field had just been removed, and stale
+ * metadata authoring `execute: 'markDone'` type-checked. The same deletion
+ * against `@object-ui/types`' `ActionSchema` — which has no index signature —
+ * correctly produced `TS2353` at the authoring site. One of the two readers
+ * could catch a retired key; the other was structurally incapable.
  *
- * That asymmetry is the issue. An open key set on a DECLARED METADATA CONTRACT
+ * That asymmetry was the issue. An open key set on a DECLARED METADATA CONTRACT
  * is what lets a typo (`targt`, `exectue`) and a tombstoned key (`execute`) both
  * sail through to a runner that then silently does nothing — the #2169 "Mark
  * Done does nothing" shape.
  *
- * This module is step 1 of the staged narrowing: it makes the key set VISIBLE
- * and warns on anything outside it, without changing a single type. Nothing
- * breaks, and an invisible failure becomes an audible one. Steps 2 and 3 —
- * promoting the legitimate keys to explicit optional fields, then removing the
- * index signature — are what finally let `tsc` catch typos and retired keys.
+ * This module was step 1 of the staged narrowing: make the key set VISIBLE and
+ * warn on anything outside it, without changing a single type. Step 2 promoted
+ * the legitimate keys to explicit optional fields; **step 3 removed the index
+ * signature**, so `tsc` now rejects a typo or a retired key outright.
+ *
+ * ── Why this module SURVIVES step 3 ──────────────────────────────────────────
+ * Step 1 wrote that the dev-mode warning "can retire" once the index signature
+ * came down. Step 3 measured that and kept it, because the two mechanisms cover
+ * DISJOINT populations rather than the same one twice:
+ *
+ *   - `tsc` sees action literals AUTHORED IN CODE. It rejects an unknown key at
+ *     the construction site, which is the strongest possible signal — but only
+ *     for actions that exist as TypeScript.
+ *   - the warning below sees actions that arrive as DATA. objectstack#3903
+ *     established that stored `sys_metadata` rows are rehydrated UNPARSED, so
+ *     authored metadata reaches `runner.execute()` as a plain object no
+ *     compiler ever looked at. That is the population `execute: 'markDone'`
+ *     actually lives in, and no type can reach it.
+ *
+ * Retiring the warning would therefore have re-opened the runtime half of the
+ * gap while closing the compile-time half — which is why `executeScript`'s
+ * rename-prescription branch also survives, for the same rows and the same
+ * reason. What DID retire with the index signature is the inverted pin in
+ * `actionKeys.pin.test.ts` that asserted the signature was still there; it now
+ * asserts the opposite, which was always its stated completion condition.
  *
  * The lists are pinned by `__tests__/actionKeys.pin.test.ts`, which re-derives
  * each one from its actual source. A hand-maintained list that drifts from the
@@ -66,8 +86,22 @@
  * deprecating them toward a spelling that does not exist would be worse than
  * leaving them declared.
  *
- * Step 3 remains: remove the index signature, at which point `tsc` catches both
- * typos and retired keys and the dev-mode warning below can retire with it.
+ * ── What step 3 found the first two steps had missed ─────────────────────────
+ * Deleting the index signature is the only thing that can name the keys still
+ * hiding behind it, and it named five, in two groups:
+ *
+ * `to` / `external` / `newTab` / `replace` — the `navigation` alias's own
+ * spelling. Step 1 had already ruled these legitimate and listed them below in
+ * {@link NAVIGATION_ALIAS_KEYS}, but step 2's scope was the SPEC-owned keys, so
+ * they were declared as data and never as fields; `executeNavigation` read them
+ * through the index signature. Promoted, and deliberately not `@deprecated` —
+ * step 2's acceptance ruled on exactly that point.
+ *
+ * `description` — objectui vocabulary from `@object-ui/types`' renderer view of
+ * an action, forwarded by all four action renderers (`check:action-forward-parity`
+ * requires it) and read by the param-collection dialog for its subtitle
+ * (objectui#4192). Authorable, forwarded, read — and undeclared. These were the
+ * only two `TS2353`s the deletion produced across the whole workspace.
  */
 /**
  * Every property `ActionDef` declares, in declaration order.
@@ -76,7 +110,7 @@
  * `keyof ActionDef` cannot substitute for this list: the index signature widens
  * it to `string | number`, which is precisely the problem being worked around.
  */
-export declare const ACTION_DEF_KEYS: readonly ["type", "actionType", "name", "label", "confirmText", "confirm", "condition", "disabled", "api", "endpoint", "method", "navigate", "onClick", "reload", "close", "redirect", "toast", "successMessage", "errorMessage", "refreshAfter", "undoable", "params", "actionParams", "resultDialog", "target", "body", "openIn", "modal", "chain", "chainMode", "onSuccess", "onFailure", "opensInNewTab", "newTabUrl", "locations", "visible", "requiredPermissions", "icon", "variant", "order", "component", "objectName", "ai", "aria", "bodyExtra", "bodyShape", "mode", "recordIdField", "recordIdParam", "requiresFeature", "shortcut", "bulkEnabled"];
+export declare const ACTION_DEF_KEYS: readonly ["type", "actionType", "name", "label", "description", "confirmText", "confirm", "condition", "disabled", "api", "endpoint", "method", "navigate", "to", "external", "newTab", "replace", "onClick", "reload", "close", "redirect", "toast", "successMessage", "errorMessage", "refreshAfter", "undoable", "params", "actionParams", "resultDialog", "target", "body", "openIn", "modal", "chain", "chainMode", "onSuccess", "onFailure", "opensInNewTab", "newTabUrl", "locations", "visible", "requiredPermissions", "icon", "variant", "order", "component", "objectName", "ai", "aria", "bodyExtra", "bodyShape", "mode", "recordIdField", "recordIdParam", "requiresFeature", "shortcut", "bulkEnabled"];
 /**
  * Every property `@objectstack/spec`'s `ActionSchema` declares.
  *
@@ -91,7 +125,7 @@ export declare const ACTION_DEF_KEYS: readonly ["type", "actionType", "name", "l
  * test and wrong in shipped code — `@object-ui/types` made the same call for
  * `ActionComponent`. The pin test does the walk and fails the day this drifts.
  */
-export declare const SPEC_ACTION_KEYS: readonly ["_lock", "_lockDocsUrl", "_lockReason", "_lockSource", "_packageId", "_packageVersion", "_provenance", "ai", "aria", "body", "bodyExtra", "bodyShape", "bulkEnabled", "component", "confirmText", "disabled", "errorMessage", "execute", "icon", "label", "locations", "method", "mode", "name", "newTabUrl", "objectName", "openIn", "opensInNewTab", "order", "params", "recordIdField", "recordIdParam", "refreshAfter", "requiredPermissions", "requiresFeature", "resultDialog", "shortcut", "successMessage", "target", "type", "undoable", "variant", "visible"];
+export declare const SPEC_ACTION_KEYS: readonly ["_lock", "_lockDocsUrl", "_lockReason", "_lockSource", "_packageId", "_packageVersion", "_provenance", "ai", "aria", "body", "bodyExtra", "bodyShape", "bulkEnabled", "component", "confirmText", "description", "disabled", "errorMessage", "execute", "icon", "label", "locations", "method", "mode", "name", "newTabUrl", "objectName", "openIn", "opensInNewTab", "order", "params", "recordIdField", "recordIdParam", "refreshAfter", "requiredPermissions", "requiresFeature", "resultDialog", "shortcut", "successMessage", "target", "type", "undoable", "variant", "visible"];
 /**
  * The `navigation` alias's own spelling of a target, read off the action itself
  * when no nested `navigate` object is present (`ActionRunner.executeNavigation`).
@@ -111,8 +145,15 @@ export declare const NAVIGATION_ALIAS_KEYS: readonly ["to", "external", "newTab"
  * Warned about separately from unknown keys, and more loudly: an unknown key is
  * probably a typo, while a retired key is metadata that used to work. That
  * distinction is why `executeScript` carries a runtime branch returning the
- * rename prescription — a branch that exists solely to compensate for the index
- * signature, and that can retire with it in step 3.
+ * rename prescription.
+ *
+ * Step 1 expected that branch to retire with the index signature. It does not,
+ * and the reason is the one in this module's header: `tsc` closed the
+ * code-authored half of the gap, while `execute: 'markDone'` lives in stored
+ * rows that reach the runner UNPARSED (objectstack#3903). The branch reads the
+ * key off an untyped view of the action precisely so that `ActionDef` can go on
+ * NOT declaring it — declaring it to make the read compile would re-legitimize
+ * a tombstone the spec keeps only in order to reject it by name.
  */
 export declare const RETIRED_ACTION_KEYS: Readonly<Record<string, string>>;
 /** Every key an action may legitimately carry today. */
@@ -133,3 +174,38 @@ export declare function resetActionKeyWarnings(): void;
  * down, this is the audible half.
  */
 export declare function warnOnUnknownActionKeys(action: object | null | undefined, where?: string): void;
+/**
+ * Does this action carry the DEPRECATED object-form `params` — a static request
+ * payload written under the key that means "parameter definitions"?
+ *
+ * The discriminator is `Array.isArray` and the type guard is `api`, mirroring
+ * `@objectstack/spec`'s `inline-action-api-params-to-body-extra` conversion
+ * (ADR-0087 D2) key for key. Contract parity with the producer is the point: the
+ * conversion rewrites exactly this shape to `bodyExtra` at load, so the runner
+ * must recognize exactly the same shape as "the thing that got rewritten".
+ *
+ * The `api` guard is also what keeps the deprecation out of objectstack#6828's
+ * territory — object-form `params` on a `type: 'url'` action is a THIRD meaning
+ * (`interpolateTarget`'s `${param.X}` scope, `executeUrl`'s `params.newTab`) and
+ * `bodyExtra` is NOT its replacement. Do not widen this guard without that
+ * ruling.
+ */
+export declare function hasDeprecatedObjectParams(action: object | null | undefined): boolean;
+/**
+ * Dev-mode only: name the object-form `params` that `@objectstack/spec` 17 already
+ * refuses at the authoring door, and prescribe `bodyExtra`.
+ *
+ * This is the audible half of the compat window the maintainer's 2026-08-06
+ * ruling on objectstack#5777 ordered (direction A — a separate key, no same-name
+ * union): the runner keeps READING a non-array `params` as the static payload for
+ * one version window, says so, and the arm is deleted at 18. The loud half lives
+ * at the producer, where it belongs — spec's `params` field refuses the object
+ * form outright with a message naming `bodyExtra`, and the ADR-0087 conversion
+ * rewrites sources that still carry it. So a warning is the correct severity
+ * HERE: by the time metadata reaches this runner the producer has already had its
+ * say, and what is left to catch is a host composing an ActionDef in code.
+ *
+ * Dev-only and warn-once, matching {@link warnOnUnknownActionKeys} — a warning
+ * that floods a production console is a warning that gets muted.
+ */
+export declare function warnOnDeprecatedObjectParams(action: object | null | undefined, where?: string): void;