@object-ui/core 17.1.0 → 17.3.0

package/README.md

@@ -58,6 +58,35 @@ const userName = scope.get('user.name') // 'John'
 const isAdmin = scope.evaluate('${user.role === "admin"}') // true
 ```
 
+### Server Action Dispatch (`createServerActionHandler`)
+
+`ActionSchema.body` (L1 expression / L2 sandboxed JS) executes **server-side**
+— `POST /api/v1/actions/{object}/{action}` → the runtime sandbox. The client
+dispatches; it never interprets a body. Build the dispatch handler with the
+factory and register it — core stays opinion-free about auth, origin and
+object scope, which are injected:
+
+```typescript
+import { createServerActionHandler } from '@object-ui/core'
+
+const script = createServerActionHandler({
+  fetch: myAuthenticatedFetch,          // your auth wrapper (Bearer/cookies/...)
+  baseUrl: 'https://api.example.com',   // '' or omitted = same-origin
+  resolveObject: () => currentObject,   // fallback when the action has no objectName
+  onRefresh: () => refetchData(),       // called per the action's refreshAfter
+})
+
+// Registered handlers beat the built-in executors:
+runner.registerHandler('script', script)
+// (React hosts: <ActionProvider handlers={{ script }} ... />)
+```
+
+The factory owns the protocol so consumers cannot drift on it: name-based
+action identity (ADR-0110), the record-id resolution dance (`_rowRecord`,
+`recordIdField`, selection fallback, aggregate `_selectedIds`), a re-entrancy
+guard, and the `/actions` response-envelope rule (`interpretActionResponse` /
+`readActionPayload`, also exported).
+
 ### System Views (`defineView`)
 
 Schemas authored in source code are part of the product contract and must

package/dist/actions/ActionEngine.d.ts

@@ -78,7 +78,17 @@ export declare class ActionEngine {
         bulkEnabled?: boolean;
         priority?: number;
     }): void;
-    /** Register multiple actions from an ActionSchema array */
+    /**
+     * Register multiple actions from an ActionSchema array.
+     *
+     * Only `locations` is harvested from the metadata. `shortcut` and
+     * `bulkEnabled` used to be read here too, but spec 17 retired both as
+     * `retiredKey()` tombstones — a declaration carrying either one no longer
+     * parses, so harvesting them read a key that cannot exist and made two dead
+     * options look load-bearing. Both remain accepted on the single-action
+     * `registerAction(action, options)` overload, where a HOST passes them
+     * explicitly; they are simply no longer sourced from authored metadata.
+     */
     registerActions(actions: ActionDef[]): void;
     /** Unregister an action by name */
     unregisterAction(name: string): void;
@@ -98,13 +108,18 @@ export declare class ActionEngine {
      *      action behaves identically whether surfaced via the engine or
      *      consumed standalone.
      *
-     *   Predicate normalization matches `@object-ui/react`'s `toPredicateInput`:
+     *   Predicate normalization goes through the shared `toPredicateInput`
+     *   (`@object-ui/core`'s canonical helper — semantically identical to
+     *   `@object-ui/react`'s renderer-side twin, pinned by a parity test):
      *   raw strings (`'record.foo == true'`) are wrapped as `${...}` so they
-     *   evaluate as expressions, not as truthy string literals. Spec-style
-     *   `{ dialect, source }` envelopes are unwrapped to their `source`.
-     *   Without this, every per-action renderer (which already calls
-     *   `toPredicateInput`) and the engine path would disagree on the same
-     *   `visible:` predicate.
+     *   evaluate as expressions, not as truthy string literals, and a spec-style
+     *   `{ dialect: 'cel', source }` envelope is passed through INTACT so
+     *   `evaluateCondition` routes it to the canonical `@objectstack/formula`
+     *   engine (#2661). Unwrapping the envelope here — as this method used to —
+     *   dropped the dialect and silently demoted every CEL predicate to the
+     *   legacy JS evaluator, so the same `visible:` reached a different verdict
+     *   via the engine than via a renderer (#3314): CEL faults on `null < null`
+     *   and fail-closed hides, JS quietly returns `false`.
      */
     getActionsForLocation(location: ActionLocation): ActionDef[];
     /** Get actions that support bulk operations */

package/dist/actions/ActionEngine.js

@@ -16,6 +16,7 @@
  *   ActionSchema[] → ActionEngine → ActionRunner → ActionResult
  */
 import { ActionRunner } from './ActionRunner';
+import { toPredicateInput } from '../evaluator/predicateInput.js';
 export { ACTION_LOCATIONS } from '@object-ui/types';
 /** Normalize a shortcut string for comparison (lowercase, trimmed, sorted parts) */
 function normalizeShortcut(keys) {
@@ -110,13 +111,24 @@ export class ActionEngine {
             this.normalizedShortcutMap.set(normalizeShortcut(options.shortcut), name);
         }
     }
-    /** Register multiple actions from an ActionSchema array */
+    /**
+     * Register multiple actions from an ActionSchema array.
+     *
+     * Only `locations` is harvested from the metadata. `shortcut` and
+     * `bulkEnabled` used to be read here too, but spec 17 retired both as
+     * `retiredKey()` tombstones — a declaration carrying either one no longer
+     * parses, so harvesting them read a key that cannot exist and made two dead
+     * options look load-bearing. Both remain accepted on the single-action
+     * `registerAction(action, options)` overload, where a HOST passes them
+     * explicitly; they are simply no longer sourced from authored metadata.
+     */
     registerActions(actions) {
         for (const action of actions) {
             this.registerAction(action, {
+                // No cast: `locations` is a declared `ActionDef` field as of
+                // objectstack#4075 step 2. The `as any` it replaces existed only
+                // because the key reached this reader through the index signature.
                 locations: action.locations,
-                shortcut: action.shortcut,
-                bulkEnabled: action.bulkEnabled,
             });
         }
     }
@@ -148,13 +160,18 @@ export class ActionEngine {
      *      action behaves identically whether surfaced via the engine or
      *      consumed standalone.
      *
-     *   Predicate normalization matches `@object-ui/react`'s `toPredicateInput`:
+     *   Predicate normalization goes through the shared `toPredicateInput`
+     *   (`@object-ui/core`'s canonical helper — semantically identical to
+     *   `@object-ui/react`'s renderer-side twin, pinned by a parity test):
      *   raw strings (`'record.foo == true'`) are wrapped as `${...}` so they
-     *   evaluate as expressions, not as truthy string literals. Spec-style
-     *   `{ dialect, source }` envelopes are unwrapped to their `source`.
-     *   Without this, every per-action renderer (which already calls
-     *   `toPredicateInput`) and the engine path would disagree on the same
-     *   `visible:` predicate.
+     *   evaluate as expressions, not as truthy string literals, and a spec-style
+     *   `{ dialect: 'cel', source }` envelope is passed through INTACT so
+     *   `evaluateCondition` routes it to the canonical `@objectstack/formula`
+     *   engine (#2661). Unwrapping the envelope here — as this method used to —
+     *   dropped the dialect and silently demoted every CEL predicate to the
+     *   legacy JS evaluator, so the same `visible:` reached a different verdict
+     *   via the engine than via a renderer (#3314): CEL faults on `null < null`
+     *   and fail-closed hides, JS quietly returns `false`.
      */
     getActionsForLocation(location) {
         const evaluator = this.runner.getEvaluator();
@@ -181,18 +198,17 @@ export class ActionEngine {
                 return true;
             if (raw === false)
                 return false;
-            let expr;
-            if (typeof raw === 'string') {
-                expr = `\${${raw}}`;
-            }
-            else if (typeof raw === 'object' && typeof raw.source === 'string') {
-                const src = raw.source;
-                if (!src)
-                    return true;
-                expr = `\${${src}}`;
-            }
-            else {
-                expr = Boolean(raw);
+            // #3314 — one shared normalization, not two. Hand-rolling the envelope
+            // unwrap here is what dropped `dialect: 'cel'` and demoted the
+            // predicate to the legacy JS engine; `toPredicateInput` keeps the
+            // envelope so `evaluateCondition` can route it to `@objectstack/formula`
+            // (the engine the server enforces with), exactly as the renderers do.
+            const expr = toPredicateInput(raw);
+            if (expr === undefined) {
+                // Not an evaluable predicate: an envelope with an empty `source`
+                // (→ nothing declared → visible), or a stray non-predicate value,
+                // which keeps the historical `Boolean(raw)` coercion.
+                return typeof raw === 'object' ? true : Boolean(raw);
             }
             try {
                 // `throwOnError: true` is required for fail-closed semantics: the
@@ -200,7 +216,9 @@ export class ActionEngine {
                 // returns the raw template string, which `Boolean(string)` then
                 // coerces to `true` — silently leaking actions whose preconditions
                 // failed (e.g. `ctx` undefined). Surface the error so our catch
-                // below can hide the action.
+                // below can hide the action. It is equally load-bearing on the CEL
+                // path, where the canonical helper fails SOFT to visible/enabled
+                // unless the caller opts in.
                 return evaluator.evaluateCondition(expr, { throwOnError: true });
             }
             catch (err) {

package/dist/actions/ActionRunner.d.ts

@@ -5,6 +5,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import type { ActionInput as SpecActionInput } from '@objectstack/spec/ui';
 import { ExpressionEvaluator } from '../evaluator/ExpressionEvaluator';
 import { type UndoableOperation } from './UndoManager';
 export interface ActionResult {
@@ -65,7 +66,12 @@ export interface ActionDef {
     /** Action type identifier — a `RunnableActionType` (the spec's six plus the
      *  `navigation` alias of `url`) or a custom type with a registered handler. */
     type?: string;
-    /** Legacy action type field */
+    /**
+     * Legacy action type field.
+     *
+     * @deprecated objectui dialect — use the spec spelling `type`. Both are read,
+     * `type` first (objectstack#4075 step 2).
+     */
     actionType?: string;
     /** Action name (from UIActionSchema) */
     name?: string;
@@ -84,13 +90,36 @@ export interface ActionDef {
     condition?: string;
     /** Disabled expression — if truthy, skip action */
     disabled?: string | boolean;
-    /** API endpoint (string URL or complex config) */
+    /**
+     * API endpoint (string URL or complex config).
+     *
+     * @deprecated objectui dialect — the spec spells an `api` action's endpoint
+     * `target` (with the verb in `method`). `executeAPI` resolves
+     * `api || endpoint || target`, so `target` alone is sufficient. The
+     * `ApiConfig` object form has no spec counterpart and is objectui-only
+     * (objectstack#4075 step 2).
+     */
     api?: string | ApiConfig;
-    /** API endpoint URL (spec v2.0.1 alias) */
+    /**
+     * API endpoint URL.
+     *
+     * @deprecated objectui dialect — this was the "spec v2.0.1 alias", but spec 17
+     * spells it `target`. `executeAPI` resolves `api || endpoint || target`
+     * (objectstack#4075 step 2).
+     */
     endpoint?: string;
     /** HTTP method */
     method?: string;
-    /** Navigation target */
+    /**
+     * Navigation target — a nested envelope carrying the `navigation` alias's own
+     * spelling (`to` / `external` / `newTab` / `replace`).
+     *
+     * @deprecated objectui dialect — the spec has no nested navigation envelope;
+     * it spells a navigation action `{ type: 'url', target, openIn }`.
+     * `executeNavigation` reads `navigate.to || navigate.target || navigate.redirect`,
+     * falling back to the same keys on the action itself, so a flat `target` works
+     * today (objectstack#4075 step 2).
+     */
     navigate?: any;
     /** onClick callback (legacy) */
     onClick?: () => void | Promise<void>;
@@ -147,8 +176,9 @@ export interface ActionDef {
      * would diverge silently rather than fail.
      *
      * Consumers dispatch bodies by registering a `script` handler that POSTs to
-     * `/api/v1/actions/{object}/{action}` (see app-shell's
-     * `useConsoleActionRuntime`); the server runs the body through its sandbox.
+     * `/api/v1/actions/{object}/{action}`; the server runs the body through its
+     * sandbox. Build that handler with `createServerActionHandler` (#2904) —
+     * app-shell's `useConsoleActionRuntime` and `RecordDetailView` both do.
      */
     body?: unknown;
     /** For type: 'url' — where to open `target`. `'new-tab'` forces a new
@@ -177,10 +207,82 @@ export interface ActionDef {
      *  must perform all auth/authz itself (e.g. the cloud `/sso-open` endpoint,
      *  which re-runs every check the POST half would have done). */
     newTabUrl?: string;
+    /** Where this action renders (`record_header`, `list_toolbar`, …). Read by
+     *  `ActionEngine.registerActions` to seed the location filter. */
+    locations?: SpecActionInput['locations'];
+    /**
+     * Visibility predicate, evaluated against the runner's context.
+     *
+     * The `boolean` arm is objectui's own, deliberately wider than the spec:
+     * `ActionSchema.visible` admits only a CEL string or a `{ dialect, source }`
+     * envelope, while `ActionEngine.getActionsForLocation` also honours a literal
+     * `visible: true` / `false` (pinned by `ActionEngine.visibility.test.ts`).
+     * Declared rather than left to the index signature so the tolerance is
+     * auditable instead of invisible — but it IS a dialect, and objectstack#4075
+     * step 3 has to decide whether the spec adopts the boolean or objectui drops
+     * it. Do not widen this further.
+     */
+    visible?: SpecActionInput['visible'] | boolean;
+    /** System permissions the caller must ALL hold for the action to be offered
+     *  (ADR-0066 D4 UI half — the server enforces the source of truth). */
+    requiredPermissions?: SpecActionInput['requiredPermissions'];
+    /** Icon name for the rendered control. */
+    icon?: SpecActionInput['icon'];
+    /** Visual emphasis of the rendered control (`primary`, `danger`, …). */
+    variant?: SpecActionInput['variant'];
+    /** Sort weight among sibling actions. */
+    order?: SpecActionInput['order'];
+    /** Which renderer surfaces the action (`action:button`, `action:menu`, …). */
+    component?: SpecActionInput['component'];
+    /** Object this action is declared against. */
+    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'];
+    /** Execution mode of the action. */
+    mode?: SpecActionInput['mode'];
+    /** Field on the record supplying the record id sent to the endpoint. */
+    recordIdField?: SpecActionInput['recordIdField'];
+    /** Request-parameter name carrying the record id. */
+    recordIdParam?: SpecActionInput['recordIdParam'];
+    /** Auth/tenancy feature the action requires before it is offered. */
+    requiresFeature?: SpecActionInput['requiresFeature'];
+    /**
+     * @deprecated Retired in `@objectstack/spec` 17 as a `retiredKey()` tombstone —
+     * authoring it is a hard parse rejection, so this resolves to `undefined` and
+     * assigning a value is a compile error. A HOST may still pass a shortcut
+     * explicitly via `ActionEngine.registerAction(action, { shortcut })`; it is
+     * only no longer sourced from authored metadata. No replacement key.
+     */
+    shortcut?: SpecActionInput['shortcut'];
+    /**
+     * @deprecated Retired in `@objectstack/spec` 17 as a `retiredKey()` tombstone —
+     * authoring it is a hard parse rejection, so this resolves to `undefined` and
+     * assigning a value is a compile error. Use the list view's `bulkActions` /
+     * `bulkActionDefs` instead; `ActionEngine.registerAction(action, { bulkEnabled })`
+     * remains available to a HOST passing it explicitly.
+     */
+    bulkEnabled?: SpecActionInput['bulkEnabled'];
     /** Any additional properties */
     [key: string]: any;
 }
-export type ActionHandler = (action: ActionDef, context: ActionContext) => Promise<ActionResult> | ActionResult;
+/**
+ * A handler registered with {@link ActionRunner} — the client-side action
+ * dispatch seam: given an authored `ActionDef` and the invocation context,
+ * produce an `ActionResult`.
+ *
+ * NOT the spec's `ActionHandler` (`@objectstack/spec/ui`), whose name this type
+ * carried until objectstack#4115. That one is the SERVER-side objectql action
+ * handler — a different calling convention entirely (`(ctx) => unknown`, with
+ * validated params and a trusted engine facade on `ctx`) and a different
+ * execution site.
+ */
+export type ActionRunnerHandler = (action: ActionDef, context: ActionContext) => Promise<ActionResult> | ActionResult;
 /**
  * Confirmation handler — replaces window.confirm.
  * Consumers can provide an async implementation (e.g., Shadcn AlertDialog).
@@ -252,6 +354,19 @@ export type ResultDialogHandler = (spec: ResultDialogSpec, data: unknown, action
 /**
  * ActionParam definition accepted by the runner.
  * Compatible with @objectstack/spec ActionParam.
+ *
+ * The RESOLVED shape — what `resolveActionParams()` emits and `ActionParamDialog`
+ * reads, after a field-backed param's `{ field }` reference has been inlined.
+ * The AUTHORING counterpart is `@object-ui/types`' `ActionParam` (objectui#3174).
+ *
+ * `validation?: string` used to sit here too, and was removed by objectui#3201:
+ * no producer ever wrote it (it was never a key of `resolveActionParams()`'s
+ * `RawActionParam`, and the runtime field metadata a field-backed param inherits
+ * from carries no `validation` either) and no consumer ever read it —
+ * `paramToField()` did not map it, so it never reached the field widgets, whose
+ * rules `buildValidationRules()` builds from `required` / `minLength` /
+ * `maxLength` / `pattern`. Declaring it on the resolved side only invited the
+ * authoring side to declare it back.
  */
 export interface ActionParamDef {
     name: string;
@@ -265,7 +380,6 @@ export interface ActionParamDef {
     defaultValue?: unknown;
     helpText?: string;
     placeholder?: string;
-    validation?: string;
     /**
      * Visibility predicate (CEL) evaluated against the same scope as action
      * `visible` (`current_user` / `app` / `data` / `features`). When it evaluates
@@ -353,7 +467,7 @@ export declare class ActionRunner {
      * values the user must copy now (2FA codes, OAuth client_secret).
      */
     setResultDialogHandler(handler: ResultDialogHandler): void;
-    registerHandler(actionName: string, handler: ActionHandler): void;
+    registerHandler(actionName: string, handler: ActionRunnerHandler): void;
     unregisterHandler(actionName: string): void;
     /**
      * Register a named script handler. When a `script` action's
@@ -361,7 +475,7 @@ export declare class ActionRunner {
      * instead of the expression evaluator. Lets dashboards/views wire
      * symbolic action names (e.g. 'export_dashboard_pdf') to JS callbacks.
      */
-    registerScript(scriptName: string, handler: ActionHandler): void;
+    registerScript(scriptName: string, handler: ActionRunnerHandler): void;
     unregisterScript(scriptName: string): void;
     execute(action: ActionDef): Promise<ActionResult>;
     /**
@@ -467,9 +581,15 @@ export declare class ActionRunner {
      * fragment.
      *
      * `ctx.origin`, `ctx.user.*`, `ctx.org.*`, `ctx.recordId` are surfaced
-     * implicitly from the runner's ActionContext + window. Consumers can
-     * extend by stuffing extra keys under `context.ctx = {...}` before
-     * calling `runner.execute()`.
+     * implicitly from the runner's ActionContext + window, and
+     * `ctx.selection.ids` / `ctx.selection.count` reflect the grid's current
+     * checkbox selection (`context.selectedRecords`) — `${ctx.selection.ids}`
+     * comma-joins the ids via the standard `String(array)` behaviour, so a
+     * list_toolbar url/api action can carry the selection without any bulk
+     * plumbing (objectui#3139). In an aggregate bulk dispatch,
+     * `${param._selectedIds}` interpolates the same ids from the injected
+     * param. Consumers can extend by stuffing extra keys under
+     * `context.ctx = {...}` before calling `runner.execute()`.
      */
     private interpolateTarget;
     /**

package/dist/actions/ActionRunner.js

@@ -448,7 +448,8 @@ export class ActionRunner {
                     success: false,
                     error: 'Action body must be executed server-side — this client runner does not interpret ' +
                         '`body` (sandboxed JS needs an isolated VM; expression bodies use the formula engine). ' +
-                        'Register a `script` handler that POSTs to /api/v1/actions/{object}/{action}.',
+                        'Register a `script` handler that POSTs to /api/v1/actions/{object}/{action} — ' +
+                        'build one with createServerActionHandler from @object-ui/core.',
                 };
             }
             // ActionDef is open-ended (`[key: string]: any`), so hand-authored
@@ -802,9 +803,15 @@ export class ActionRunner {
      * fragment.
      *
      * `ctx.origin`, `ctx.user.*`, `ctx.org.*`, `ctx.recordId` are surfaced
-     * implicitly from the runner's ActionContext + window. Consumers can
-     * extend by stuffing extra keys under `context.ctx = {...}` before
-     * calling `runner.execute()`.
+     * implicitly from the runner's ActionContext + window, and
+     * `ctx.selection.ids` / `ctx.selection.count` reflect the grid's current
+     * checkbox selection (`context.selectedRecords`) — `${ctx.selection.ids}`
+     * comma-joins the ids via the standard `String(array)` behaviour, so a
+     * list_toolbar url/api action can carry the selection without any bulk
+     * plumbing (objectui#3139). In an aggregate bulk dispatch,
+     * `${param._selectedIds}` interpolates the same ids from the injected
+     * param. Consumers can extend by stuffing extra keys under
+     * `context.ctx = {...}` before calling `runner.execute()`.
      */
     interpolateTarget(target, action) {
         if (typeof target !== 'string' || target.indexOf('${') === -1)
@@ -839,6 +846,22 @@ export class ActionRunner {
             user: this.context.user ?? {},
             org: this.context.org ?? this.context.organization ?? {},
             recordId: this.context.record?.id ?? this.context.recordId,
+            // Current list selection (published by the grid as `selectedRecords`).
+            // `${ctx.selection.ids}` in a url/api target comma-joins the ids —
+            // String(array) — giving toolbar actions selection access without any
+            // bulk-executor involvement (objectui#3139). Empty when nothing is
+            // selected, so authors can treat "" as "no selection".
+            selection: {
+                ids: Array.isArray(this.context.selectedRecords)
+                    ? this.context.selectedRecords
+                        .map((r) => r?.id)
+                        .filter((v) => v != null)
+                        .map(String)
+                    : [],
+                count: Array.isArray(this.context.selectedRecords)
+                    ? this.context.selectedRecords.length
+                    : 0,
+            },
         };
         if (this.context.ctx && typeof this.context.ctx === 'object') {
             Object.assign(ctx, this.context.ctx);

package/dist/actions/actionErrorDetail.d.ts

@@ -0,0 +1,26 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Resolve a human-readable message out of an ObjectStack error payload.
+ *
+ * Always returns a STRING. The envelope nests the message as
+ * `{ error: { code, message } }`, and passing that object through as
+ * `ActionResult.error` reaches `toast.error()` as a React child and crashes the
+ * page (React #31). That shape used to be rare on the `/actions` route —
+ * failures came back as HTTP 200 with a plain-string `error` — but since
+ * objectstack#3913 a failed action answers with a real status and the nested
+ * object, so every `/actions` caller has to go through this.
+ *
+ * Handles, in order: `{error: 'msg'}`, `{error: {message: 'msg'}}`,
+ * `{message: 'msg'}`, else the caller's fallback.
+ *
+ * Moved here from `@object-ui/app-shell` (`utils/actionErrorDetail`) by
+ * objectui#2904 so `createServerActionHandler` — the core dispatch every
+ * consumer registers — can own the rule.
+ */
+export declare function actionErrorDetail(body: unknown, fallback: string): string;

package/dist/actions/actionErrorDetail.js

@@ -0,0 +1,37 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Resolve a human-readable message out of an ObjectStack error payload.
+ *
+ * Always returns a STRING. The envelope nests the message as
+ * `{ error: { code, message } }`, and passing that object through as
+ * `ActionResult.error` reaches `toast.error()` as a React child and crashes the
+ * page (React #31). That shape used to be rare on the `/actions` route —
+ * failures came back as HTTP 200 with a plain-string `error` — but since
+ * objectstack#3913 a failed action answers with a real status and the nested
+ * object, so every `/actions` caller has to go through this.
+ *
+ * Handles, in order: `{error: 'msg'}`, `{error: {message: 'msg'}}`,
+ * `{message: 'msg'}`, else the caller's fallback.
+ *
+ * Moved here from `@object-ui/app-shell` (`utils/actionErrorDetail`) by
+ * objectui#2904 so `createServerActionHandler` — the core dispatch every
+ * consumer registers — can own the rule.
+ */
+export function actionErrorDetail(body, fallback) {
+    const b = body;
+    const err = b?.error;
+    if (typeof err === 'string' && err.length > 0)
+        return err;
+    const nested = err?.message;
+    if (typeof nested === 'string' && nested.length > 0)
+        return nested;
+    if (typeof b?.message === 'string' && b.message.length > 0)
+        return b.message;
+    return fallback;
+}

package/dist/actions/actionKeys.d.ts

@@ -32,25 +32,42 @@
  * interface it mirrors would be the same "declared ≠ enforced" trap this whole
  * thread is about.
  *
- * ── What the inventory found, i.e. step 2's worklist ─────────────────────────
- * `ActionDef` declares 34 keys, the spec's `ActionSchema` declares 36, and they
- * overlap on 17. The two halves of the difference are different problems:
+ * ── What the inventory found, and what step 2 did with it ────────────────────
+ * Step 1 found `ActionDef` declaring 34 keys against the spec `ActionSchema`'s
+ * 36, overlapping on 17. The two halves of the difference were different
+ * problems, and step 2 (objectstack#4075) treated them differently:
  *
  * 18 keys the SPEC owns that `ActionDef` never declared — `ai`, `aria`,
  * `bodyExtra`, `bodyShape`, `bulkEnabled`, `component`, `icon`, `locations`,
  * `mode`, `objectName`, `order`, `recordIdField`, `recordIdParam`,
  * `requiredPermissions`, `requiresFeature`, `shortcut`, `variant`, `visible`.
- * These are authored today and reach readers through the index signature.
- * `ActionEngine` reads two of them (`visible` at the location filter, `locations`
- * at registration) through an `as any` cast — a cast that exists ONLY because the
- * field is undeclared, and that goes away when step 2 promotes them.
+ * These are authored today and used to reach readers through the index
+ * signature. **Step 2 promoted all 18 to explicit optional fields**, typed by
+ * DERIVATION from `@objectstack/spec`'s `ActionInput` rather than by hand-copied
+ * shapes. The `as any` casts `ActionEngine` needed to read `visible`,
+ * `locations` and `requiredPermissions` are gone with them — those casts existed
+ * only because the fields were undeclared.
+ *
+ * Two of the 18 landed as `undefined` rather than as usable types, which is the
+ * correct outcome: spec 17 retired `shortcut` and `bulkEnabled` as `retiredKey()`
+ * tombstones (`z.never()`), so deriving turns "authoring this is a parse
+ * rejection" into a compile error at no cost. Hand-copying would have quietly
+ * re-legitimized two dead keys — which is why the types are derived.
  *
  * 17 keys `ActionDef` declares that the spec does not own — `actionType`, `api`,
  * `chain`, `chainMode`, `close`, `condition`, `confirm`, `endpoint`, `modal`,
  * `navigate`, `onClick`, `onFailure`, `onSuccess`, `redirect`, `reload`, `toast`,
- * `actionParams`. Several are already marked legacy at their declaration. These
- * are objectui's own dialect and need the #4115 treatment: kept and documented as
- * deliberate, or retired — but not silently carried.
+ * `actionParams`. Step 2 marked `@deprecated`, with the spec spelling to use
+ * instead, ONLY the four the runner itself proves are aliases: `actionType` (→
+ * `type`), `api` and `endpoint` (→ `target`; `executeAPI` resolves
+ * `api || endpoint || target`), and `navigate` (→ flat `target`/`openIn`;
+ * `executeNavigation` already falls back to them). The rest are runner mechanics
+ * with no spec counterpart — chaining, toasts, post-execution reload/close — and
+ * deprecating them toward a spelling that does not exist would be worse than
+ * leaving them declared.
+ *
+ * Step 3 remains: remove the index signature, at which point `tsc` catches both
+ * typos and retired keys and the dev-mode warning below can retire with it.
  */
 /**
  * Every property `ActionDef` declares, in declaration order.
@@ -59,7 +76,7 @@
  * `keyof ActionDef` cannot substitute for this list: the index signature widens
  * it to `string | number`, which is precisely the problem being worked around.
  */
-export declare const ACTION_DEF_KEYS: readonly ["type", "actionType", "name", "label", "confirmText", "confirm", "condition", "disabled", "api", "endpoint", "method", "navigate", "onClick", "reload", "close", "redirect", "toast", "successMessage", "errorMessage", "refreshAfter", "undoable", "params", "actionParams", "resultDialog", "target", "body", "openIn", "modal", "chain", "chainMode", "onSuccess", "onFailure", "opensInNewTab", "newTabUrl"];
+export declare const ACTION_DEF_KEYS: readonly ["type", "actionType", "name", "label", "confirmText", "confirm", "condition", "disabled", "api", "endpoint", "method", "navigate", "onClick", "reload", "close", "redirect", "toast", "successMessage", "errorMessage", "refreshAfter", "undoable", "params", "actionParams", "resultDialog", "target", "body", "openIn", "modal", "chain", "chainMode", "onSuccess", "onFailure", "opensInNewTab", "newTabUrl", "locations", "visible", "requiredPermissions", "icon", "variant", "order", "component", "objectName", "ai", "aria", "bodyExtra", "bodyShape", "mode", "recordIdField", "recordIdParam", "requiresFeature", "shortcut", "bulkEnabled"];
 /**
  * Every property `@objectstack/spec`'s `ActionSchema` declares.
  *
@@ -74,7 +91,7 @@ export declare const ACTION_DEF_KEYS: readonly ["type", "actionType", "name", "l
  * test and wrong in shipped code — `@object-ui/types` made the same call for
  * `ActionComponent`. The pin test does the walk and fails the day this drifts.
  */
-export declare const SPEC_ACTION_KEYS: readonly ["ai", "aria", "body", "bodyExtra", "bodyShape", "bulkEnabled", "component", "confirmText", "disabled", "errorMessage", "execute", "icon", "label", "locations", "method", "mode", "name", "newTabUrl", "objectName", "openIn", "opensInNewTab", "order", "params", "recordIdField", "recordIdParam", "refreshAfter", "requiredPermissions", "requiresFeature", "resultDialog", "shortcut", "successMessage", "target", "type", "undoable", "variant", "visible"];
+export declare const SPEC_ACTION_KEYS: readonly ["_lock", "_lockDocsUrl", "_lockReason", "_lockSource", "_packageId", "_packageVersion", "_provenance", "ai", "aria", "body", "bodyExtra", "bodyShape", "bulkEnabled", "component", "confirmText", "disabled", "errorMessage", "execute", "icon", "label", "locations", "method", "mode", "name", "newTabUrl", "objectName", "openIn", "opensInNewTab", "order", "params", "recordIdField", "recordIdParam", "refreshAfter", "requiredPermissions", "requiresFeature", "resultDialog", "shortcut", "successMessage", "target", "type", "undoable", "variant", "visible"];
 /**
  * The `navigation` alias's own spelling of a target, read off the action itself
  * when no nested `navigate` object is present (`ActionRunner.executeNavigation`).