@object-ui/core 17.5.0 → 17.7.0

package/dist/actions/ActionRunner.js

@@ -5,10 +5,52 @@
  * 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 { hasDeclaredPredicate } from '../evaluator/declaredPredicate';
-import { globalUndoManager } from './UndoManager';
-import { warnOnDeprecatedObjectParams, 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';
+import { toPredicateRecord } from '../utils/predicate-record.js';
+/**
+ * The text the runner writes itself, and so the only text
+ * {@link ActionRunner.setTranslator}'s translator is asked for. In each entry
+ * `key` names the locale-pack entry (`@object-ui/i18n`'s packs define it) and
+ * `defaultValue` is the English source, which is also what shows when no
+ * translator is installed.
+ *
+ * - `completedSuccessfully` — the success toast when the author supplied no
+ *   copy for it: no `outcomeMessages` entry for the answer's `outcome` and no
+ *   `successMessage` (objectui#10900, objectui#11344).
+ * - `failed` — the error toast when the error that reached the toast carries
+ *   no readable message, and a parallel chain's result when its last action
+ *   rejected (objectui#10969).
+ * - `parallelFailed` — a parallel chain's error when no failed action reported
+ *   one of its own (objectui#10969).
+ * - `undo` — the label the runner hands the toast handler for an undoable
+ *   success toast's Undo affordance (objectui#10969).
+ *
+ * An author's `outcomeMessages` / `successMessage` / `errorMessage` and an
+ * action's own error are never in this table: the host localizes authored copy
+ * before dispatch, and the runner only fills in its `${result.*}` tokens.
+ */
+const RUNNER_TEXT = {
+    completedSuccessfully: {
+        key: 'actions.completedSuccessfully',
+        defaultValue: 'Action completed successfully',
+    },
+    failed: {
+        key: 'actions.failed',
+        defaultValue: 'Action failed',
+    },
+    parallelFailed: {
+        key: 'actions.parallelFailed',
+        defaultValue: 'One or more parallel actions failed',
+    },
+    undo: {
+        key: 'actions.undo',
+        defaultValue: 'Undo',
+    },
+};
 /**
  * Bind the server-CEL-parity `os.user` identity alias into an action context
  * (#2358 trap 1). `@objectstack/spec` documents the canonical CEL identity
@@ -79,6 +121,24 @@ function readContextObjectName(context) {
     const name = context.objectName;
     return typeof name === 'string' && name.trim() !== '' ? name.trim() : undefined;
 }
+/**
+ * The field definitions the host published for `objectName`, or `undefined`
+ * (objectui#11122).
+ *
+ * A host publishes `objectFields` BESIDE `objectName` (`useConsoleActionRuntime`
+ * and `RecordDetailView` both do), so the pair names one object and its fields.
+ * They are answered only for THAT object: an action that retargets another
+ * object (a related-list row on the record page carries the child's
+ * `objectName`) gets no field map rather than the host object's, because
+ * reading one object's field types against another object's row would decide
+ * which of its fields are relations by the wrong schema.
+ */
+function readContextObjectFields(context, objectName) {
+    if (readContextObjectName(context) !== objectName)
+        return undefined;
+    const fields = context.objectFields;
+    return fields && typeof fields === 'object' ? fields : undefined;
+}
 /**
  * Whether opening FormView `viewName` from a record of `contextObject` would
  * cross an object boundary (objectui#4292).
@@ -101,6 +161,91 @@ function crossesObjectBoundary(viewName, contextObject) {
         return false;
     return !viewName.startsWith(`${contextObject}.`);
 }
+/**
+ * Is this the declarative single-record field write?
+ *
+ * Asks the AUTHORED key, not `type`: the spec materializes `type: 'script'`
+ * here and refuses every other explicit spelling, so `type` cannot answer the
+ * question — see the dispatch comment in {@link ActionRunner.execute}.
+ *
+ * `'update'` is the only member the spec declares (`'delete'` and `'custom'`
+ * have no row-level form), and an unrecognized spelling is a parse rejection
+ * upstream. This reads the ONE member rather than "any truthy `operation`" so a
+ * future member cannot silently inherit the update write path — the dispatch
+ * table's own guard reasoning, applied to this key.
+ */
+function isUpdateOperationAction(action) {
+    return action.operation === 'update';
+}
+/**
+ * The fields an `operation: 'update'` action writes, and their prior values.
+ *
+ * `undoable` promises to restore EXACTLY the fields the action wrote, so the
+ * captured set is the effective payload — `patch` merged under the collected
+ * `params` — and never `patch` alone: a param-collected field left out of the
+ * capture would make Undo restore SOME of the edit and report a full one, which
+ * is worse than offering no Undo at all.
+ *
+ * Prior values come from the row record the invoking surface stashed under
+ * `params._rowRecord` (the same client-side stash the record-id dance reads).
+ * A field the row carries as `null` is captured as `null`: it was empty, and
+ * clearing it back to empty is what restoring it means on the data plane.
+ *
+ * ⛔ A field the row does not CARRY is never captured as `null`
+ * (objectui#10404). Absent is not empty: a list row is projected by `$select`,
+ * and a written field no column shows is missing from the row while the server
+ * holds a real value for it. Recording `null` there made Undo write `null` over
+ * the value it existed to restore. The list harvest (`listViewPredicates`) now
+ * asks for the written fields of an `undoable` action, so a projected row
+ * carries them; this is the backstop for the ones it cannot ask for (a field
+ * the object does not declare or the principal may not read, a row no harvest
+ * shaped). "Carries" means an own key whose value is not `undefined`: JSON
+ * cannot send `undefined`, so such a value says nothing about what is stored.
+ *
+ * Answers `undefined` when any written field is not carried, and the caller
+ * then offers no Undo at all. Capturing only the carried fields is not an
+ * option, for the reason above: a partial restore reported as a full one is
+ * worse than no Undo.
+ *
+ * ⛔ A relation's prior value is its STORED id, never the record `$expand`
+ * put in its place (objectui#11122). Surfaces read rows with `$expand` on the
+ * relations they show (a grid, its visible and grouping columns; the record
+ * page, every relation the reader may read), and the server replaces the id
+ * in place with the related record. Copied verbatim, that record became the
+ * Undo value and Undo wrote it into the reference slot, which stores an id:
+ * refused under a strict value-shape posture, stored as corruption under the
+ * lenient one. So each carried value goes through `toPredicateRecord`, the one
+ * rule that binds a fetched record the way the server stores it: a field the
+ * object DECLARES relational (`EXPANDABLE_FIELD_TYPES`, the set that decides
+ * what is expanded in the first place) collapses to its id, element-wise for a
+ * `multiple` relation, and every other field is left exactly as the row
+ * carries it. It is read from `fields`, never from the value's shape: a `json`
+ * field may hold an object with an `id`, and that object is its stored value.
+ *
+ * `fields` is the written object's field definitions (`objectSchema.fields`,
+ * either served shape), and it is REQUIRED so that a caller without them has
+ * to say so: `undefined` collapses nothing, because a caller that cannot name
+ * the relations must not guess them.
+ *
+ * Exported (objectui#11082) because it is THE rule, not this runner's: every
+ * surface that builds an `update` Undo snapshot itself calls it rather than
+ * restating it. Today that is the console runtime's `api` handler
+ * (`useConsoleActionRuntime`) and the record page's own `api` handler
+ * (`RecordDetailView`), which reads prior values off the page's loaded record;
+ * that record lacks a written field when field-level security hides it from
+ * the reader. To name the fields that blocked a capture, ask per field:
+ * `captureUpdateUndoData([field], rowRecord, fields) === undefined`.
+ */
+export function captureUpdateUndoData(writtenFields, rowRecord, fields) {
+    if (!writtenFields.every((field) => rowCarries(rowRecord, field)))
+        return undefined;
+    const stored = toPredicateRecord(rowRecord, fields);
+    return Object.fromEntries(writtenFields.map((field) => [field, stored[field]]));
+}
+/** Whether the row CARRIES `field`: an own key whose value is not `undefined`. */
+function rowCarries(rowRecord, field) {
+    return Object.prototype.hasOwnProperty.call(rowRecord, field) && rowRecord[field] !== undefined;
+}
 /*
  * ## The two predicate gates in `execute`, and the one question they ask first
  *
@@ -128,8 +273,10 @@ function crossesObjectBoundary(viewName, contextObject) {
  * 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
+ * empty-`source` envelope are NOT declared; a declared `false` IS) and the
+ * third state objectui#11358 added (a present value with no evaluable `source`
+ * — `0`, `{}`, an array, an `ast`-only envelope — IS declared, and faults).
+ * 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
@@ -163,9 +310,15 @@ function crossesObjectBoundary(viewName, contextObject) {
  * 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.
+ * {@link hasDeclaredPredicate} too (objectui#3957), so the two entries answer
+ * a value that is not a predicate at all the same way. Since objectui#11358
+ * that answer is "declared, and faulting" rather than "no gate": `0` / `{}` /
+ * an `ast`-only envelope reach `evaluateCondition`, which reports them and
+ * answers its fail-soft `true` — so `disabled` refuses the action (its closed
+ * direction, as for any faulting `disabled`) and `condition` lets it run (the
+ * direction a faulting `condition` has always taken), and the engine filter
+ * hides it (`throwOnError`). Pinned in `ActionRunner.disabledGate.test.ts` /
+ * `ActionRunner.conditionGate.test.ts`.
  */
 export class ActionRunner {
     constructor(context = {}) {
@@ -229,6 +382,12 @@ export class ActionRunner {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "translate", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         /**
          * Built-in dispatch, one entry per runnable action type.
          *
@@ -266,6 +425,21 @@ export class ActionRunner {
         this.navigationHandler = null;
         this.paramCollectionHandler = null;
         this.resultDialogHandler = null;
+        this.translate = null;
+    }
+    /**
+     * Set the translator for the text the runner supplies itself — the host's
+     * `t`, injected so this package takes no i18n dependency. That text is the
+     * `RUNNER_TEXT` table in this file: the generic success toast shown when an
+     * action declares neither an `outcomeMessages` entry for the answer nor a
+     * `successMessage`, the error fallbacks when no readable error message
+     * reached the runner, and the Undo label of an undoable success toast. An
+     * author's `outcomeMessages` / `successMessage` / `errorMessage` and an
+     * action's own error never go through this translator: the host localizes
+     * authored copy before dispatch. With no translator the text stays English.
+     */
+    setTranslator(translate) {
+        this.translate = translate;
     }
     /**
      * Set a custom confirmation handler (e.g., Shadcn AlertDialog).
@@ -328,10 +502,10 @@ export class ActionRunner {
         try {
             // `ActionDef` accepts any key of any type, so a typo (`targt`) and a
             // retired key (`execute`) both reach here having type-checked. Neither
-            // 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).
+            // binds a handler, and binding no handler silently is the objectstack-ai/objectstack#2169 "Mark Done
+            // does nothing" shape. Dev-only, warn-once, changes nothing (objectstack-ai/objectstack#4075 step 1).
             warnOnUnknownActionKeys(action);
-            // The compat window for the object-form `params` payload (#5777, maintainer
+            // The compat window for the object-form `params` payload (objectstack-ai/objectstack#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
@@ -375,9 +549,16 @@ export class ActionRunner {
                 // code only evaluated the STRING form and treated any object as truthy,
                 // so an envelope-disabled action was ALWAYS "disabled" — silently
                 // blocking every execution (param dialog never opened, handler never
-                // ran). `evaluateCondition` already handles boolean/string/envelope;
-                // and the renderers are authoritative for the visual disabled state, so
-                // any eval failure here defaults to NOT-disabled (don't false-block).
+                // ran). `evaluateCondition` already handles boolean/string/envelope.
+                //
+                // A predicate that FAULTS — an unbound root, a misspelled field,
+                // `current_user.can(…)` before the permissions payload has loaded — does
+                // NOT reach the `catch` below: `evaluateCondition` handles its own
+                // faults and answers its fail-soft `true`, which on this key means
+                // DISABLED, so the action is refused ("Action is disabled"). That is the
+                // closed direction every `disabled` leg takes (objectui#11212,
+                // objectui#11242). The `catch` only covers a throw from outside that
+                // fault handling, and leaves such an action not disabled.
                 let isDisabled = false;
                 try {
                     isDisabled = this.evaluator.evaluateCondition(action.disabled);
@@ -389,14 +570,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' };
                 }
@@ -425,6 +605,32 @@ export class ActionRunner {
                         action.params._rowRecord = rowRecord;
                 }
             }
+            // ── `operation` is read BEFORE `type`, and this is the only order that
+            // can work ────────────────────────────────────────────────────────────
+            //
+            // `operation: 'update'` is a PARALLEL key beside `type`, not a member of
+            // it: `@objectstack/spec` materializes `type: 'script'` on such an action
+            // (the platform action route is the script type's own route) and refuses
+            // any other explicit `type`. `ActionType` therefore did not gain a
+            // member, which is why `builtinExecutors` — a `Record<RunnableActionType,
+            // …>` — still compiles unchanged across the bump that added this key.
+            //
+            // The cost of that design is paid here: by the time `actionType` is
+            // consulted, an update action is indistinguishable from every other
+            // script action. Dispatched on `type` it would reach the registered
+            // `script` handler with its `patch` never merged into the request — the
+            // route would be POSTed a payload with no field values in it and answer a
+            // green success for having written nothing (objectui#2960). Worse, a row
+            // rehydrated from `sys_metadata` UNPARSED (objectui#3903) carries no
+            // materialized `type` at all, so `actionType` falls back to the action's
+            // NAME, matches no executor, and the action lands in
+            // `executeActionSchema`. Reading `operation` first is what makes both of
+            // those impossible.
+            if (isUpdateOperationAction(action)) {
+                const result = await this.executeUpdateOperation(action);
+                await this.handlePostExecution(action, result);
+                return result;
+            }
             // Check for a registered custom handler first
             if (actionType && this.handlers.has(actionType)) {
                 const handler = this.handlers.get(actionType);
@@ -477,13 +683,13 @@ export class ActionRunner {
                 const firstFail = results.find(r => r.status === 'fulfilled' && !r.value.success);
                 return {
                     success: false,
-                    error: firstFail?.value?.error || 'One or more parallel actions failed',
+                    error: firstFail?.value?.error || this.runnerText(RUNNER_TEXT.parallelFailed),
                 };
             }
             const lastResult = results[results.length - 1];
             return lastResult.status === 'fulfilled'
                 ? lastResult.value
-                : { success: false, error: 'Action failed' };
+                : { success: false, error: this.runnerText(RUNNER_TEXT.failed) };
         }
         // Sequential execution — stop on first failure
         let lastResult = { success: true };
@@ -495,6 +701,61 @@ export class ActionRunner {
         }
         return lastResult;
     }
+    /**
+     * One entry of `RUNNER_TEXT`, in the installed translator's language. An
+     * empty answer from the translator falls back to the English source rather
+     * than raising an empty toast or an empty label.
+     */
+    runnerText({ key, defaultValue }) {
+        return this.translate?.(key, { defaultValue }) || defaultValue;
+    }
+    /**
+     * The success toast's text, by the contract's three rungs
+     * (`ActionSchema.outcomeMessages`, objectui#11344):
+     *
+     * 1. `outcomeMessages[outcome]`, where `outcome` is the top-level `outcome`
+     *    of the handler's return value — the payload `${result.*}` reads, so it
+     *    is the same fact an author writes as `${result.outcome}`;
+     * 2. `successMessage`;
+     * 3. the runner's own default text, in its translator's language.
+     *
+     * Rungs 1 and 2 are the author's copy. Both arrive already localized — the
+     * host's localizer resolves the bundle entry or the inline `I18nLabel` map
+     * before dispatch — and both have their `${result.*}` tokens filled in here,
+     * through the one token grammar and scope `onSuccess.navigate` reads
+     * (`substituteScopeTokens` over `readActionPayload(result.data)`). Only the
+     * sink differs: a toast is text, so a value is inserted as-is, where a URL
+     * position percent-encodes it.
+     *
+     * ⛔ `result.data.message` is not a rung. It used to outrank both rungs of
+     * author copy, which put whatever language the server happened to write in
+     * front of the user's locale; the contract names no server-message rung, and
+     * an author who wants the server's sentence can still write
+     * `${result.message}` as the copy.
+     *
+     * A rung counts only when it is a non-empty string. An `I18nLabel` map that
+     * reached the runner without passing through a localizer has no language to
+     * resolve against here, so it is skipped rather than handed to the toast as
+     * an object — the React #31 crash the error branch below guards against.
+     */
+    composeSuccessMessage(action, result) {
+        const payload = readActionPayload(result.data);
+        const outcome = payload && typeof payload === 'object'
+            ? payload.outcome
+            : undefined;
+        const outcomeMessages = action.outcomeMessages;
+        const outcomeCopy = typeof outcome === 'string'
+            && outcomeMessages && typeof outcomeMessages === 'object'
+            && Object.prototype.hasOwnProperty.call(outcomeMessages, outcome)
+            ? outcomeMessages[outcome]
+            : undefined;
+        for (const copy of [outcomeCopy, action.successMessage]) {
+            if (typeof copy === 'string' && copy.trim() !== '') {
+                return substituteScopeTokens(copy, { result: payload }, (value) => value);
+            }
+        }
+        return this.runnerText(RUNNER_TEXT.completedSuccessfully);
+    }
     /**
      * Post-execution: emit toast notifications, handle chaining, callbacks.
      */
@@ -510,27 +771,25 @@ export class ActionRunner {
             const showToast = action.toast ?? { showOnSuccess: true, showOnError: true };
             const duration = action.toast?.duration;
             if (result.success && !hasResultDialog && !result.silent && showToast.showOnSuccess !== false) {
-                // Prefer a DYNAMIC message the server returned (result.data.message)
-                // over the static action.successMessage. Server-driven actions like
-                // check_app_updates / publish / install compute a real outcome
-                // ("2 app updates available: CRM 1.0.0→1.0.1", "Published v1.2.0")
-                // that the static label can't express; without this the user only ever
-                // sees a generic "Done". Falls back to the static label, then a default.
-                const dyn = (result.data && typeof result.data === 'object'
-                    && typeof result.data.message === 'string')
-                    ? String(result.data.message).trim()
-                    : '';
-                const message = dyn || action.successMessage || 'Action completed successfully';
+                // The server returns FACTS and the console writes the sentence
+                // (ruling A on objectstack-ai/cloud#2315) — see `composeSuccessMessage`.
+                const message = this.composeSuccessMessage(action, result);
                 // Undoable action: register the captured operation on the global
                 // UndoManager and surface an "Undo" affordance on the toast (the
-                // consumer's toast handler wires the button to UndoManager).
+                // consumer's toast handler wires the button to UndoManager). The
+                // button's label is the runner's own text, so it is translated here
+                // rather than left to each handler's English default (objectui#10969).
                 if (result.undo) {
                     try {
                         globalUndoManager.push(result.undo);
                     }
                     catch { /* non-fatal */ }
                 }
-                this.toastHandler(message, { type: 'success', duration, undo: result.undo ? {} : undefined });
+                this.toastHandler(message, {
+                    type: 'success',
+                    duration,
+                    undo: result.undo ? { label: this.runnerText(RUNNER_TEXT.undo) } : undefined,
+                });
             }
             if (!result.success && showToast.showOnError !== false && result.error) {
                 // `result.error` is typed as a string, but a handler bug can leak an
@@ -543,7 +802,7 @@ export class ActionRunner {
                     ? raw
                     : (raw && typeof raw.message === 'string')
                         ? raw.message
-                        : 'Action failed';
+                        : this.runnerText(RUNNER_TEXT.failed);
                 this.toastHandler(message, { type: 'error', duration });
             }
         }
@@ -558,12 +817,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 });
             }
         }
@@ -586,25 +843,204 @@ export class ActionRunner {
             if (chainResult.reload)
                 result.reload = true;
         }
-        // Execute onSuccess/onFailure callbacks
+        // ── ActionSchema.onSuccess — post-success navigation ────────────────────
+        //
+        // `053fdc8f9`, 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.
+        //
+        // That declared meaning is the key's ONLY meaning. The runner's older
+        // chained-callback channel (`onSuccess?: ActionDef | ActionDef[]`,
+        // dispatched through `executeChain`) was retired by objectui#5934
+        // (maintainer ruling 2026-08-31): the spec strict-refuses a callback shape
+        // at parse, so no validated metadata could ever reach it, and the census
+        // found zero producers outside the channel's own pins.
+        //
+        // `readOnSuccessNavigation` stays as the shape guard, not as a
+        // discriminator: stored rows are rehydrated UNPARSED (objectstack-ai/objectstack#3903), so the value
+        // is still read as data, and a shape the spec refuses gets no reading —
+        // no navigation, no callback dispatch, no lenient fallback.
         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);
+            }
         }
         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;
+        }
+    }
+    /**
+     * `operation: 'update'` — the declarative single-record field write.
+     *
+     * ## The write is the ROUTE's, never this client's
+     *
+     * This method composes a request and hands it to the registered `script`
+     * dispatch; it does not touch a `DataSource`. That is a security boundary,
+     * not an implementation preference. `POST /api/v1/actions/{object}/{action}`
+     * runs the write AS THE CALLER — the caller's permissions, the object's hooks
+     * and its validations all fire as for a user edit — while a client-side
+     * `dataSource.update()` reaches the data plane having consulted none of them.
+     * The spec says the same thing from its end by refusing `target`, `body`,
+     * `method` and `bodyExtra` beside this key and pinning `type` to `'script'`:
+     * there is exactly one execution surface for an update action, and it is the
+     * route.
+     *
+     * Consequently, a consumer that has registered NO server-action dispatch gets
+     * a loud refusal naming the remedy. The two silent alternatives were both
+     * available and both wrong: falling through to `executeScript` ends at "No
+     * script provided" (an update action declares no `target` — the author is
+     * sent hunting for a field they were right not to write), and falling through
+     * to `executeActionSchema` reports on an action that never ran.
+     *
+     * ## `patch` rides UNDER the collected params
+     *
+     * The spec's words: static field values "merged UNDER the user-supplied
+     * `params` so a fixed value can be declared without exposing it in the
+     * dialog". So a collected param of the same name WINS — the author declared a
+     * default, and the user answered it.
+     */
+    async executeUpdateOperation(action) {
+        const dispatch = this.handlers.get('script');
+        if (!dispatch) {
+            return {
+                success: false,
+                error: 'An `operation: "update"` action is written by the platform action route, which this ' +
+                    'client runner cannot reach: no `script` handler is registered. The write is never ' +
+                    'performed client-side — a direct data-plane update bypasses the route\'s permission ' +
+                    'floor, the object\'s hooks and its validations. Register a handler that POSTs to ' +
+                    '/api/v1/actions/{object}/{action} — build one with createServerActionHandler from ' +
+                    '@object-ui/core.',
+            };
+        }
+        const collected = (action.params && !Array.isArray(action.params))
+            ? { ...action.params }
+            : {};
+        const patch = (action.patch && typeof action.patch === 'object' && !Array.isArray(action.patch))
+            ? { ...action.patch }
+            : {};
+        // `patch` UNDER the collected params — see the doc above.
+        const params = { ...patch, ...collected };
+        // The row stash and the record selector are transport mechanics, not
+        // written fields: the dispatch strips `_rowRecord` before POSTing and reads
+        // `recordId` as the record's address.
+        const rowRecord = (collected._rowRecord && typeof collected._rowRecord === 'object')
+            ? collected._rowRecord
+            : undefined;
+        const writtenFields = Object.keys(params).filter((k) => k !== '_rowRecord' && k !== 'recordId');
+        const result = await dispatch({ ...action, params }, this.context);
+        // A refusal is returned exactly as the dispatch reported it. The route's
+        // envelope rule (`interpretActionResponse`) has already turned a 4xx/5xx
+        // AND a 200-with-`success:false` business rejection into `error`, and
+        // `handlePostExecution` surfaces that as the failure toast. Re-labelling it
+        // here, or answering success because the POST itself completed, is the
+        // objectui#2960 shape this branch exists to prevent.
+        if (!result.success)
+            return result;
+        // Undo: prior values of exactly the fields this action wrote. Needs a row
+        // record to read them from — without one there is nothing to restore, so
+        // the affordance is correctly not offered rather than offered empty. The
+        // same holds when the row lacks a written field (objectui#10404): no Undo,
+        // never one that writes `null` over the stored value. A relation the row
+        // carries expanded is captured as its stored id, read against the field
+        // map the host published for this object (objectui#11122).
+        if (action.undoable && rowRecord && writtenFields.length > 0) {
+            const objectName = action.objectName || readContextObjectName(this.context);
+            const recordId = collected.recordId ?? rowRecord.id;
+            if (objectName && recordId != null) {
+                const undoData = captureUpdateUndoData(writtenFields, rowRecord, readContextObjectFields(this.context, objectName));
+                if (undoData) {
+                    result.undo = {
+                        id: `undo-${objectName}-${String(recordId)}-${Date.now()}`,
+                        type: 'update',
+                        objectName,
+                        recordId: String(recordId),
+                        timestamp: Date.now(),
+                        // objectui#11080 — no English verb here. The toast that reports the
+                        // Undo / Redo already says which one it is, from a pack key, so an
+                        // action that declared no label is named by the object it acted on.
+                        description: action.label || objectName,
+                        undoData,
+                        redoData: Object.fromEntries(writtenFields.map((k) => [k, params[k]])),
+                    };
+                }
+                else {
+                    // The success toast then carries no Undo button, which is how the
+                    // user learns this one cannot be undone; this names the cause for
+                    // the author.
+                    console.warn('[ActionRunner] `undoable` update succeeded but offers no Undo: the row it ran on does not '
+                        + 'carry every field it wrote, so their prior values are unknown and an Undo would overwrite '
+                        + 'stored data. A list row carries a written field when the object declares it and the '
+                        + 'principal may read it.', { action: action.name, missing: writtenFields.filter((k) => !rowCarries(rowRecord, k)) });
+                }
+            }
+        }
+        return result;
+    }
     /**
      * Execute script action — evaluates client-side expression via ExpressionEvaluator.
      * Supports ${} template expressions referencing data, record, user context.
      */
     async executeScript(action) {
         // `target` is the only handler slot. The `execute` alias was removed in
-        // @objectstack/spec 17 (#3855), which rejects an authored `execute` at parse
+        // @objectstack/spec 17 (objectstack-ai/objectstack#3855), which rejects an authored `execute` at parse
         // with the rename prescription — so parsed metadata cannot carry it and a
-        // `target || execute` fallback could only ever evaluate to `target` (#3856).
+        // `target || execute` fallback could only ever evaluate to `target` (objectstack-ai/objectstack#3856).
         const script = action.target;
         if (!script) {
             // A spec `body` IS a script — this runner just cannot run one (see the
@@ -627,11 +1063,11 @@ export class ActionRunner {
             // `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
+            // reach. It is not this half: objectstack-ai/objectstack#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
+            // re-legitimize a tombstone (objectstack-ai/objectstack#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.
@@ -953,7 +1389,7 @@ export class ActionRunner {
      * 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
+     * objectstack-ai/objectstack#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
@@ -1098,7 +1534,7 @@ 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
@@ -1135,14 +1571,24 @@ export class ActionRunner {
         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);
-            if (value == null)
-                return '';
-            return encodeURIComponent(String(value));
-        });
+        // 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.
+        //
+        // The success toast's copy is the one other caller of the grammar, through
+        // `substituteScopeTokens` directly (`composeSuccessMessage`): `result` only,
+        // because that is the one scope the contract declares for the copy, and no
+        // encoding, because a toast is text.
+        const scopes = { param: params, ctx: this.buildInterpolationContext() };
+        if (resultScope !== undefined)
+            scopes.result = resultScope;
+        return substituteScopeTokens(target, scopes, encodeURIComponent);
     }
     /**
      * Assemble the `ctx` namespace exposed to target interpolation.
@@ -1207,6 +1653,46 @@ export async function executeAction(action, context = {}) {
     const runner = new ActionRunner(context);
     return await runner.execute(action);
 }
+/**
+ * Is this `onSuccess` the spec's navigation block?
+ *
+ * The test IS the spec's declaration: a non-array object carrying a STRING
+ * `navigate`. Stored rows are rehydrated UNPARSED (objectstack-ai/objectstack#3903), so the runner reads
+ * the value as data and anything else gets NO reading — since objectui#5934
+ * retired the legacy chained-callback channel (`ActionDef | ActionDef[]`),
+ * there is no other channel for an off-contract shape to fall into. This is a
+ * shape GUARD on unparsed data, not a discriminator between two meanings.
+ */
+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;
+}
+/**
+ * The runner's ONE `${scope.path}` token grammar — the substitution behind
+ * `interpolateTarget` (url / api targets and the `onSuccess.navigate` hop) and
+ * behind the success toast's `${result.*}` copy (`composeSuccessMessage`).
+ *
+ * The scope MAP defines the vocabulary: the pattern is built from its keys, so
+ * a token naming a scope the caller did not pass is left in the text exactly as
+ * written. A path that resolves to nothing becomes `''`. `encode` is the only
+ * thing a caller varies, and it belongs to the SINK, not to the dialect: a URL
+ * position percent-encodes each value, a toast inserts it as text.
+ */
+function substituteScopeTokens(template, scopes, encode) {
+    if (typeof template !== 'string' || template.indexOf('${') === -1)
+        return template;
+    const pattern = new RegExp(`\\$\\{(${Object.keys(scopes).join('|')})\\.([\\w.]+)\\}`, 'g');
+    return template.replace(pattern, (_match, scope, path) => {
+        const value = readPath(scopes[scope], path);
+        if (value == null)
+            return '';
+        return encode(String(value));
+    });
+}
 /**
  * Dot-path read used by target interpolation. Plain reduce — kept inline
  * to avoid pulling lodash for a 3-line helper.