@object-ui/core 17.3.0 → 17.6.0

package/dist/actions/ActionRunner.js

@@ -5,9 +5,11 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { ExpressionEvaluator } from '../evaluator/ExpressionEvaluator';
-import { globalUndoManager } from './UndoManager';
-import { warnOnUnknownActionKeys } from './actionKeys';
+import { ExpressionEvaluator } from '../evaluator/ExpressionEvaluator.js';
+import { hasDeclaredPredicate } from '../evaluator/declaredPredicate.js';
+import { globalUndoManager } from './UndoManager.js';
+import { warnOnDeprecatedObjectParams, warnOnUnknownActionKeys } from './actionKeys.js';
+import { readActionPayload } from './actionResponse.js';
 /**
  * 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 +29,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 +332,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,
@@ -220,14 +390,13 @@ export class ActionRunner {
                     return { success: false, error: 'Action is disabled' };
                 }
             }
-            // Confirmation (structured or simple)
-            const confirmMessage = action.confirm?.message || action.confirmText;
-            if (confirmMessage) {
-                const confirmed = await this.confirmHandler(this.evaluator.evaluate(confirmMessage), action.confirm ? {
-                    title: action.confirm.title,
-                    confirmText: action.confirm.confirmText,
-                    cancelText: action.confirm.cancelText,
-                } : undefined);
+            // Confirmation. One spelling: `confirmText` — the only one the
+            // translation bundle can address (`…._actions.{name}.confirmText`). The
+            // structured `confirm.message` read that used to OUTRANK it is retired
+            // (objectui#4314): it had zero producers and no bundle key, so a dialog
+            // authored that way silently lost localization.
+            if (action.confirmText) {
+                const confirmed = await this.confirmHandler(this.evaluator.evaluate(action.confirmText));
                 if (!confirmed) {
                     return { success: false, error: 'Action cancelled by user' };
                 }
@@ -389,12 +558,10 @@ export class ActionRunner {
                 catch (err) {
                     // Acknowledgement failure is non-fatal; the underlying action already
                     // succeeded. Log so consumers can wire it through their error reporter.
-                    // eslint-disable-next-line no-console
                     console.warn('[ActionRunner] resultDialog handler rejected; treating as acknowledged', err);
                 }
             }
             else {
-                // eslint-disable-next-line no-console
                 console.warn('[ActionRunner] action.resultDialog set but no resultDialogHandler registered — the response value will not be shown to the user.', { action: action.name, data: result.data });
             }
         }
@@ -417,16 +584,94 @@ export class ActionRunner {
             if (chainResult.reload)
                 result.reload = true;
         }
-        // Execute onSuccess/onFailure callbacks
+        // ── ActionSchema.onSuccess — post-success navigation ────────────────────
+        //
+        // objectui#5221, the console half of objectstack#9566/#9474. The spec
+        // declares `onSuccess` as a CLOSED STRICT object
+        // `{ navigate: string, openIn: 'self' | 'newTab' }`, refine-scoped to
+        // `type: 'api'` and `type: 'script'` — the two types whose success event
+        // carries a server response for `${result.*}` to read.
+        //
+        // This runner's OWN `ActionDef.onSuccess` predates that key and means
+        // something else entirely: `ActionDef | ActionDef[]`, chained callbacks.
+        // The two are told apart by the spec's own declaration — a non-array object
+        // whose `navigate` is a STRING is the spec block and nothing else can be:
+        // `navigate` on a callback ActionDef is the deprecated nested navigation
+        // ENVELOPE (`executeNavigation` reads `navigate.to`), so a string there has
+        // never been runnable. This is a NARROWING to the declared contract, not a
+        // lenient fallback: a shape the spec refuses gets no new reading here.
+        //
+        // Before this branch existed, the ruled shape fell into the callback path,
+        // dispatched `{ navigate: '<string>' }` as an action, and failed inside
+        // `executeNavigation` with "No URL provided for navigation action" — the
+        // author got a red toast and no hop.
         if (result.success && action.onSuccess) {
-            const callbacks = Array.isArray(action.onSuccess) ? action.onSuccess : [action.onSuccess];
-            await this.executeChain(callbacks, 'sequential');
+            const navigation = readOnSuccessNavigation(action.onSuccess);
+            if (navigation) {
+                this.navigateOnSuccess(navigation, action, result);
+            }
+            else {
+                const callbacks = Array.isArray(action.onSuccess) ? action.onSuccess : [action.onSuccess];
+                await this.executeChain(callbacks, 'sequential');
+            }
         }
         if (!result.success && action.onFailure) {
             const callbacks = Array.isArray(action.onFailure) ? action.onFailure : [action.onFailure];
             await this.executeChain(callbacks, 'sequential');
         }
     }
+    /**
+     * Perform the `ActionSchema.onSuccess` hop for an action that just succeeded.
+     *
+     * **The router is the app's own.** `navigationHandler` is the seam every
+     * navigator in this file already goes through, and the console wires it to
+     * react-router's `navigate` — so `openIn: 'self'` is a real SPA route hop,
+     * in place, immune to popup blocking. No `window.location` / `window.open`
+     * mechanism is introduced here; the no-handler fallback is the same
+     * `result.redirect` hand-off `navigateTo` already uses.
+     *
+     * **No default is written here.** `openIn` is a materialised
+     * `.default('self')` in the spec, so parse output always carries a resolved
+     * member; this reads the ONE member that changes the branch and leaves the
+     * other implicit. A `?? 'self'` would be a second source of truth for a
+     * default the producer already resolved.
+     *
+     * **The two `openIn` spellings never cross.** This reads
+     * `onSuccess.openIn` (`'self' | 'newTab'`) and nothing else — never the
+     * top-level `type: 'url'` switch, which spells its new-tab member
+     * `'new-tab'`. Spec refuses each crossover spelling with a keyed error; a
+     * renderer that accepted either would be a second, looser contract than the
+     * one authors are validated against.
+     */
+    navigateOnSuccess(block, action, result) {
+        // `${result.*}` reads the HANDLER's return value, one level below the
+        // action envelope — the same level `readActionPayload` hands the
+        // `redirectUrl` convention. Reading `result.data` raw would see the
+        // `{ success, data }` envelope on pre-objectstack#3962 servers, which is
+        // the "one level too shallow" bug (#2904) in a new place.
+        const url = this.interpolateTarget(block.navigate, action, readActionPayload(result.data));
+        // `navigate` is author-supplied metadata and lands in a URL position, so
+        // it goes through the same scheme guard as every other navigator here.
+        if (!this.isValidUrl(url)) {
+            console.warn('[ActionRunner] onSuccess.navigate resolved to a URL this runner refuses to open '
+                + '(only http://, https:// and relative URLs are allowed) — no navigation performed.', { action: action.name, navigate: block.navigate, resolved: url });
+            return;
+        }
+        const newTab = block.openIn === 'newTab';
+        // Same external-URL convention `navigateTo` hands the handler; `newTab`
+        // stays the declared choice alone, never `?? isExternal`.
+        const external = url.startsWith('http://') || url.startsWith('https://');
+        if (this.navigationHandler) {
+            this.navigationHandler(url, { external, newTab });
+            return;
+        }
+        if (newTab) {
+            window.open(url, '_blank', 'noopener,noreferrer');
+        }
+        else {
+            result.redirect = url;
+        }
+    }
     /**
      * Execute script action — evaluates client-side expression via ExpressionEvaluator.
      * Supports ${} template expressions referencing data, record, user context.
@@ -452,12 +697,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 +821,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 +945,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 +985,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 +1016,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 +1089,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 +1110,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 };
@@ -813,16 +1174,58 @@ export class ActionRunner {
      * param. Consumers can extend by stuffing extra keys under
      * `context.ctx = {...}` before calling `runner.execute()`.
      */
-    interpolateTarget(target, action) {
+    interpolateTarget(target, action, resultScope) {
         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
             : {};
-        const ctx = this.buildInterpolationContext();
-        return target.replace(/\$\{(param|ctx)\.([\w.]+)\}/g, (_match, scope, path) => {
-            const root = scope === 'param' ? params : ctx;
-            const value = readPath(root, path);
+        // The scope MAP defines the vocabulary — the pattern is built from its
+        // keys, so a scope that is not in play is not a scope this call recognizes.
+        //
+        // `result` (the handler's own return value) is passed by exactly one caller:
+        // the `ActionSchema.onSuccess` post-success hop, where a response exists.
+        // Every other caller — `executeUrl`, `executeAPI` — interpolates a target
+        // BEFORE the request, so there is no result to read; admitting `${result.*}`
+        // there would widen the authorable surface with nothing behind it and
+        // silently blank the token instead of leaving the author's mistake visible.
+        const scopes = { param: params, ctx: this.buildInterpolationContext() };
+        if (resultScope !== undefined)
+            scopes.result = resultScope;
+        const pattern = new RegExp(`\\$\\{(${Object.keys(scopes).join('|')})\\.([\\w.]+)\\}`, 'g');
+        return target.replace(pattern, (_match, scope, path) => {
+            const value = readPath(scopes[scope], path);
             if (value == null)
                 return '';
             return encodeURIComponent(String(value));
@@ -891,6 +1294,25 @@ export async function executeAction(action, context = {}) {
     const runner = new ActionRunner(context);
     return await runner.execute(action);
 }
+/**
+ * Is this `onSuccess` the SPEC's navigation block, or this runner's older
+ * chained-callback channel (`ActionDef | ActionDef[]`)?
+ *
+ * The test IS the spec's declaration: a non-array object carrying a STRING
+ * `navigate`. Nothing else can produce that shape — the spec object is strict
+ * with `navigate: z.string()` required, and on a callback `ActionDef`,
+ * `navigate` is the deprecated nested navigation ENVELOPE that
+ * `executeNavigation` reads `to`/`target`/`redirect` off, so a bare string
+ * there has never been runnable.
+ */
+export function readOnSuccessNavigation(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const navigate = value.navigate;
+    if (typeof navigate !== 'string' || navigate === '')
+        return null;
+    return value;
+}
 /**
  * Dot-path read used by target interpolation. Plain reduce — kept inline
  * to avoid pulling lodash for a 3-line helper.