@object-ui/core 17.5.0 → 17.7.0

package/dist/actions/ActionRunner.d.ts

@@ -21,8 +21,9 @@
  */
 import type { UIActionSchema } from '@object-ui/types';
 import type { Action as SpecActionInput } from '@objectstack/spec/ui';
-import { ExpressionEvaluator } from '../evaluator/ExpressionEvaluator';
-import { type UndoableOperation } from './UndoManager';
+import { ExpressionEvaluator } from '../evaluator/ExpressionEvaluator.js';
+import { type UndoableOperation } from './UndoManager.js';
+import { type FieldContainerLike } from '../utils/predicate-record.js';
 export interface ActionResult {
     success: boolean;
     data?: any;
@@ -134,15 +135,22 @@ export interface ActionDef {
      * it — the two TS2353s the deletion produced repo-wide were both this key.
      */
     description?: UIActionSchema['description'];
-    /** Confirmation text — shows a confirm dialog before executing */
+    /**
+     * Confirmation text — shows a confirm dialog before executing. The ONE
+     * confirm spelling: `@objectstack/spec`'s action surface and the
+     * TranslationBundle key (`{ns}.objects.{obj}._actions.{name}.confirmText`)
+     * both stand on it.
+     */
     confirmText?: string;
-    /** Structured confirmation (from crud.ts) */
-    confirm?: {
-        title?: string;
-        message?: string;
-        confirmText?: string;
-        cancelText?: string;
-    };
+    /**
+     * RETIRED (objectui#4314): the structured confirm object used to sit here
+     * and its `message` OUTRANKED `confirmText` — untranslated, since no bundle
+     * key exists for it. `?: never` so constructing an action with it is a tsc
+     * error rather than a silently-ignored key; the authorable twin
+     * (`@object-ui/types` `crud.ts`) carries the same tombstone.
+     * @deprecated Retired — author `confirmText` instead.
+     */
+    confirm?: never;
     /**
      * Condition predicate — the action executes only while it holds.
      *
@@ -161,8 +169,8 @@ export interface ActionDef {
      * field, because the 2026-08-06 maintainer ruling on objectstack#4075 gave
      * both keys ONE shape: `boolean | string(CEL) | { dialect, source }` —
      * "boolean = 条件的退化形字面量,string = CEL 简写,信封 = 完整形". The
-     * envelope arm arrived in `@objectstack/spec` 17.0.0-rc.6 (objectstack#5970,
-     * PR objectstack#6450); until then this was a hand-written `string | boolean`
+     * envelope arm arrived in `@objectstack/spec` 17.0.0-rc.6 (objectstack
+     * `97e7e3caa`); until then this was a hand-written `string | boolean`
      * that could not describe the envelope, which is why `DeclaredActionsBar`
      * read it through an `(action as any).disabled` cast. Derived, not restated,
      * so the two keys cannot drift apart again.
@@ -226,7 +234,8 @@ export interface ActionDef {
         showOnError?: boolean;
         duration?: number;
     };
-    /** Success message (from UIActionSchema) */
+    /** Success message (from UIActionSchema). The success toast's second rung,
+     *  after {@link outcomeMessages}; may interpolate `${result.*}`. */
     successMessage?: string;
     /** Error message (from UIActionSchema) */
     errorMessage?: string;
@@ -249,9 +258,9 @@ export interface ActionDef {
      * `'url'`, flow name for `'flow'`, modal/page for `'modal'`, endpoint for
      * `'api'`, FormView name for `'form'`.
      *
-     * The `execute` alias was REMOVED in @objectstack/spec 17 (#3855) and is not
-     * read here (#3856) — don't re-add it. Two handler slots is how one action ran
-     * one script server-side and a different one client-side (#3713).
+     * The `execute` alias was REMOVED in @objectstack/spec 17 (objectstack-ai/objectstack#3855) and is not
+     * read here (objectstack-ai/objectstack#3856) — don't re-add it. Two handler slots is how one action ran
+     * one script server-side and a different one client-side (objectstack-ai/objectstack#3713).
      */
     target?: string;
     /**
@@ -284,8 +293,6 @@ export interface ActionDef {
     chain?: ActionDef[];
     /** Chain execution mode */
     chainMode?: 'sequential' | 'parallel';
-    /** Callback on success */
-    onSuccess?: ActionDef | ActionDef[];
     /** Callback on failure */
     onFailure?: ActionDef | ActionDef[];
     /** When true, the runner pre-opens about:blank synchronously on click so the
@@ -316,7 +323,7 @@ export interface ActionDef {
      * spec 采纳 —— `visible` / `disabled` 两键在 spec 侧统一收敛为
      * `boolean | string(CEL) | {dialect, source}`(boolean = 条件的退化形字面量,
      * string = CEL 简写,信封 = 完整形)". `@objectstack/spec` 17.0.0-rc.6 carries
-     * it (objectstack#5970, PR objectstack#6450), so the local `| boolean` is no
+     * it (objectstack `97e7e3caa`), so the local `| boolean` is no
      * longer a tolerance to declare — it is part of the derived type, and adding
      * it back would restate a spec arm rather than widen anything.
      */
@@ -336,12 +343,31 @@ export interface ActionDef {
     objectName?: SpecActionInput['objectName'];
     /** AI affordance metadata (tool exposure, prompts). */
     ai?: SpecActionInput['ai'];
-    /** Accessibility overrides for the rendered control. */
-    aria?: SpecActionInput['aria'];
     /** Extra properties merged into the request body alongside the collected params. */
     bodyExtra?: SpecActionInput['bodyExtra'];
     /** How collected params are shaped into the request body (`flat` or nested). */
     bodyShape?: SpecActionInput['bodyShape'];
+    /**
+     * The declarative single-record field write — a parallel key BESIDE `type`,
+     * never a member of it.
+     *
+     * `ActionType` did not gain a member: the spec materializes `type: 'script'`
+     * on an `operation: 'update'` action, because the write is performed on the
+     * platform action route — `POST /api/v1/actions/{object}/{action}`, the route
+     * the registered `script` dispatch already posts — as the CALLER, so the
+     * caller's permissions, the object's hooks and its validations all fire as
+     * for a user edit. That is why {@link execute} reads this key BEFORE `type`:
+     * by the time `type` is consulted an update action is indistinguishable from
+     * any other script action, and its `patch` would never reach the request.
+     */
+    operation?: SpecActionInput['operation'];
+    /**
+     * For `operation: 'update'` — static field values written to the current
+     * record, merged UNDER the collected `params` so a fixed value can be
+     * declared without exposing it in the dialog. The spec refuses it on an
+     * action without `operation: 'update'`, where it would be silently dropped.
+     */
+    patch?: SpecActionInput['patch'];
     /** Execution mode of the action. */
     mode?: SpecActionInput['mode'];
     /** Field on the record supplying the record id sent to the endpoint. */
@@ -350,6 +376,41 @@ export interface ActionDef {
     recordIdParam?: SpecActionInput['recordIdParam'];
     /** Auth/tenancy feature the action requires before it is offered. */
     requiresFeature?: SpecActionInput['requiresFeature'];
+    /**
+     * Declared post-success navigation — the spec's closed strict
+     * `{ navigate, openIn }` block (`ActionSchema.onSuccess`, authorable since
+     * `@objectstack/spec` 17.1.0, objectui#5328). Read by `handlePostExecution`
+     * → `readOnSuccessNavigation` → `navigateOnSuccess`.
+     *
+     * This key carried a SECOND, older meaning until objectui#5934: the runner's
+     * own chained-callback channel, `ActionDef | ActionDef[]`, dispatched through
+     * `executeChain`. The maintainer retired that channel on 2026-08-31 — the
+     * spec strict-refuses a callback shape here (`{ type: … }` fails parse with
+     * `unrecognized_keys`, so no validated metadata could ever reach it), and the
+     * census found zero producers outside the channel's own pins. `onSuccess`
+     * now means exactly what the contract declares, nothing else; a callback
+     * shape gets NO reading (not a fallback, not an error — the same "a shape
+     * the spec refuses gets no new reading here" rule the discrimination branch
+     * used to apply, now with nothing left to discriminate). `onFailure`, in the
+     * runner-native section above, is untouched: the spec declares no such key,
+     * so it has only ever had its one runner-native meaning.
+     */
+    onSuccess?: SpecActionInput['onSuccess'];
+    /**
+     * Success copy per handler outcome (`ActionSchema.outcomeMessages`, ruling A
+     * on objectstack-ai/cloud#2315): the server answers with a closed `outcome`
+     * fact and this map holds the sentence for each, keyed by the snake_case
+     * outcome name. Read by `handlePostExecution` → `composeSuccessMessage`, the
+     * success toast's FIRST rung: the entry named by the payload's top-level
+     * `outcome` (the payload `${result.*}` reads), then {@link successMessage},
+     * then the runner's own default text.
+     *
+     * Derived, so an entry is an `I18nLabel` — a string or an inline per-locale
+     * map. The runner composes from strings only: the host's localizer
+     * (`useActionTextLocalizer` in `@object-ui/react`) resolves each entry to the
+     * active language before dispatch, because the runner has no language.
+     */
+    outcomeMessages?: SpecActionInput['outcomeMessages'];
     /**
      * @deprecated Retired in `@objectstack/spec` 17 as a `retiredKey()` tombstone —
      * authoring it is a hard parse rejection, so this resolves to `undefined` and
@@ -382,6 +443,29 @@ export type ActionRunnerHandler = (action: ActionDef, context: ActionContext) =>
 /**
  * Confirmation handler — replaces window.confirm.
  * Consumers can provide an async implementation (e.g., Shadcn AlertDialog).
+ *
+ * `options` is LIVE, and its producer is not in this file — searching the
+ * runner alone will tell you otherwise. The only call site here passes one
+ * argument (the structured `confirm` arm that used to forward a bag was
+ * retired, objectui#4314), so a runner-scoped sweep reads this parameter as
+ * declared-but-never-produced and files it for removal. That has already
+ * happened once: objectui#5205, ruled KEEP on 2026-08-22.
+ *
+ * The producer bypasses the runner entirely. `handleDeleteView` in
+ * `packages/app-shell/src/views/ObjectView.tsx` — the admin "delete saved
+ * view" confirmation — invokes a `ConfirmationHandler` with all three fields
+ * populated and localized (`console.objectView.deleteViewTitle` / `.delete` /
+ * `.cancel`), and `app-shell`'s `ActionConfirmDialog.tsx` renders them in
+ * place of its generic `actionConfirm.*` fallbacks. Line numbers are left out
+ * on purpose: #5205's pointer had already drifted by the time it was executed.
+ *
+ * So re-measure across the repo, not this package: grep for two-argument
+ * calls of `ConfirmationHandler`-typed values (`confirmHandler(`, `onConfirm(`)
+ * in `app-shell` as well as here. Dropping `options` costs that dialog its
+ * title and both button labels, and narrows a published `.d.ts` against the
+ * natural `(message, options) => …` spelling — which TypeScript rejects
+ * against a one-parameter target unless the second parameter is written
+ * optional.
  */
 export type ConfirmationHandler = (message: string, options?: {
     title?: string;
@@ -418,10 +502,29 @@ export type NavigationHandler = (url: string, options?: {
  * Returns collected values, or null if cancelled.
  */
 export type ParamCollectionHandler = (params: ActionParamDef[], action?: ActionDef) => Promise<Record<string, any> | null>;
+/**
+ * The contract's own result-dialog block, and one entry of its field list.
+ *
+ * ⭐ The two interfaces below DERIVE their label members from these instead of
+ * restating them, and that is the whole repair of `43c0d1710`: the three
+ * label members were hand-written `string` while the producer declares each as
+ * `I18nLabel` — a plain string **or** an inline per-locale map, both authorized
+ * and neither deprecated — so this mirror refused what the platform accepts
+ * while its own docblock claimed the alignment. A hand copy can drift again the
+ * moment the contract moves; a derived member makes `tsc` re-check the claim on
+ * every build instead of trusting a sentence written once.
+ *
+ * ⛔ Local, deliberately not exported: the two interfaces below stay the only
+ * names this module publishes for the block.
+ */
+type SpecResultDialog = NonNullable<SpecActionInput['resultDialog']>;
+type SpecResultDialogField = NonNullable<SpecResultDialog['fields']>[number];
 /**
  * Result dialog spec — declarative description of how to render a
  * one-shot reveal of an action's API response. Mirrors
- * `Action.resultDialog` in @objectstack/spec.
+ * `Action.resultDialog` in @objectstack/spec — derived from it member by
+ * member for the labels, so the claim in this sentence is enforced rather
+ * than asserted.
  *
  * When set on an action and the action succeeds, the runner suppresses
  * the success toast and awaits a ResultDialogHandler instead. Used for
@@ -430,13 +533,22 @@ export type ParamCollectionHandler = (params: ActionParamDef[], action?: ActionD
  */
 export interface ResultDialogFieldSpec {
     path: string;
-    label?: string;
+    /**
+     * Derived `I18nLabel` — a plain string, or an inline per-locale map. A
+     * renderer must RESOLVE it (`resolveI18nLabel` in `@objectstack/spec/ui`)
+     * before it reaches the DOM; passed through as-is, the map arm is an object
+     * and React refuses an object as a child.
+     */
+    label?: SpecResultDialogField['label'];
     format?: 'qrcode' | 'code-list' | 'secret' | 'text' | 'json';
 }
 export interface ResultDialogSpec {
-    title?: string;
-    description?: string;
-    acknowledge?: string;
+    /** Derived `I18nLabel` — see `ResultDialogFieldSpec.label` on resolving it. */
+    title?: SpecResultDialog['title'];
+    /** Derived `I18nLabel` — see `ResultDialogFieldSpec.label` on resolving it. */
+    description?: SpecResultDialog['description'];
+    /** Derived `I18nLabel` — see `ResultDialogFieldSpec.label` on resolving it. */
+    acknowledge?: SpecResultDialog['acknowledge'];
     format?: 'qrcode' | 'code-list' | 'secret' | 'text' | 'json';
     fields?: ResultDialogFieldSpec[];
 }
@@ -456,7 +568,7 @@ export type ResultDialogHandler = (spec: ResultDialogSpec, data: unknown, action
  * `visibleWhen` (the CEL predicate `resolveVisibleOptions()` filters on —
  * ADR-0058 / #2284), `color`, `icon`, `disabled`.
  *
- * The catch-all is deliberate rather than a closed key list (objectui#3559).
+ * The catch-all is deliberate rather than a closed key list (`fbc23e094`).
  * A field's option vocabulary is owned by the field metadata (`@objectstack/spec`'s
  * `SelectOptionSchema`) and read by the option widgets; a param's option list is
  * only a CONDUIT between the two. When this type restated that vocabulary as
@@ -500,19 +612,36 @@ export interface ActionParamDef {
     placeholder?: string;
     /**
      * Visibility predicate (CEL) evaluated against the same scope as action
-     * `visible` (`current_user` / `app` / `data` / `features`). When it evaluates
+     * `visible` (`current_user` / `data` / `features` — ⛔ not `app`, unbound by
+     * objectui#8155). When it evaluates
      * false the param dialog omits this param — used to hide a param the backend
      * only accepts under an opt-in capability (e.g. `create_user.phoneNumber`
      * gated on `features.phoneNumber`). Absent = always visible.
      */
     visible?: string;
+    /**
+     * Carry-over declaration — `@objectstack/spec`'s `ActionParamSchema.carryOver`
+     * (the 2026-08-25 ruling whose spec half is objectstack `0e4e51b0a`,
+     * objectui#6246), passed through unchanged by
+     * `resolveActionParams()`. The param's value is carried through the dialog
+     * rather than collected from the user: seeded from the row (the spec refuses
+     * the key without `defaultFromRow: true`), rendered by `ActionParamDialog` as
+     * a collapsed read-only summary with no editing affordance, and submitted
+     * verbatim.
+     *
+     * ⛔ Not a styling hint. The permission-set Clone action declares it on its
+     * JSON permission facets because an editable facet lets a hand-edited but
+     * valid blob clone a set that grants MORE than its base; a renderer that
+     * merely greys the control out still offers that edit.
+     */
+    carryOver?: boolean;
     /** Accepted upload types (MIME types / extensions) for `file`/`image` params. */
     accept?: string[];
     /** Max upload size in bytes for `file`/`image` params. */
     maxSize?: number;
     /** Allow multiple values (file/image/lookup/user params → array value). */
     multiple?: boolean;
-    /** Object name the lookup picker queries (`reference_to` on the field). */
+    /** Object name the lookup picker queries (`reference` on the field). */
     referenceTo?: string;
     /** Field on the referenced record used as the human label (default `name`). */
     displayField?: string;
@@ -530,7 +659,87 @@ export interface ActionParamDef {
     lookupPageSize?: number;
     /** Form-field dependencies that gate / parameterise the picker query. */
     dependsOn?: unknown[];
+    /**
+     * Set by `resolveActionParams()` when a FIELD-BACKED param (`{ field }`)
+     * named a field that is not in the object metadata the resolver was given,
+     * carrying `<object>.<field>` — the pair that could not be resolved.
+     *
+     * It exists because the alternative is a SILENT one. Without it the resolver
+     * hands back `type: param.type ?? 'text'`, and every downstream reader of the
+     * degradation is blind to it: the param is a `text` param by then, so
+     * `paramDegradesWithoutTarget()` answers false, `paramToField()` emits no
+     * "no reference target" warning, and the objectstack-ai/objectstack#3405 "paste a record id" hints do
+     * not apply either. A lookup param that should have rendered a record picker
+     * renders an unannotated empty box instead — no options, no dropdown, and no
+     * request for the referenced object on the wire, because no picker was ever
+     * built (`6cc910b6d`).
+     *
+     * ⛔ It is not a widget config key and `paramToField()` deliberately does not
+     * map it: the whole point is that the param's type is UNKNOWN, so there is no
+     * widget to configure. `ActionParamDialog` reads it and refuses.
+     */
+    unresolvedField?: string;
 }
+/**
+ * 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 declare function captureUpdateUndoData(writtenFields: readonly string[], rowRecord: Record<string, unknown>, fields: FieldContainerLike): Record<string, unknown> | undefined;
 export declare class ActionRunner {
     private handlers;
     private scripts;
@@ -542,6 +751,7 @@ export declare class ActionRunner {
     private navigationHandler;
     private paramCollectionHandler;
     private resultDialogHandler;
+    private translate;
     /**
      * Built-in dispatch, one entry per runnable action type.
      *
@@ -558,6 +768,20 @@ export declare class ActionRunner {
      */
     private readonly builtinExecutors;
     constructor(context?: ActionContext);
+    /**
+     * 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: (key: string, options: {
+        defaultValue: string;
+    }) => string): void;
     /**
      * Set a custom confirmation handler (e.g., Shadcn AlertDialog).
      */
@@ -600,10 +824,101 @@ export declare class ActionRunner {
      * Execute multiple actions in sequence or parallel.
      */
     executeChain(actions: ActionDef[], mode?: 'sequential' | 'parallel'): Promise<ActionResult>;
+    /**
+     * 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.
+     */
+    private runnerText;
+    /**
+     * 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.
+     */
+    private composeSuccessMessage;
     /**
      * Post-execution: emit toast notifications, handle chaining, callbacks.
      */
     private handlePostExecution;
+    /**
+     * 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.
+     */
+    private navigateOnSuccess;
+    /**
+     * `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.
+     */
+    private executeUpdateOperation;
     /**
      * Execute script action — evaluates client-side expression via ExpressionEvaluator.
      * Supports ${} template expressions referencing data, record, user context.
@@ -718,7 +1033,7 @@ export declare 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
@@ -787,3 +1102,21 @@ export declare class ActionRunner {
  * Convenience function to execute a single action with a one-off runner.
  */
 export declare function executeAction(action: ActionDef, context?: ActionContext): Promise<ActionResult>;
+/** The `ActionSchema.onSuccess` block, as the pinned spec declares it. */
+export interface OnSuccessNavigation {
+    navigate: string;
+    /** `'self' | 'newTab'` — read as data, so an off-contract value cannot widen the branch. */
+    openIn?: unknown;
+}
+/**
+ * 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 declare function readOnSuccessNavigation(value: unknown): OnSuccessNavigation | null;
+export {};