@object-ui/core 17.1.0 → 17.3.0

package/dist/actions/actionKeys.js

@@ -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.
@@ -94,6 +111,29 @@ export const ACTION_DEF_KEYS = [
     'onFailure',
     'opensInNewTab',
     'newTabUrl',
+    // Promoted out of the index signature by objectstack#4075 step 2 — the 18 keys
+    // the spec owns that `ActionDef` had never declared. Their types are derived
+    // from `@objectstack/spec`'s `ActionInput`, so this list is the only
+    // hand-maintained half, and `actionKeys.pin.test.ts` re-derives it from the
+    // interface's AST.
+    '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.
@@ -110,6 +150,17 @@ export const ACTION_DEF_KEYS = [
  * `ActionComponent`. The pin test does the walk and fails the day this drifts.
  */
 export const SPEC_ACTION_KEYS = [
+    // The package-lock / provenance envelope, added to `ActionSchema` in spec
+    // 17.0.0-rc.2. Not authorable action vocabulary — it is stamped on a record
+    // that came from an installed package — but it IS declared by the schema, so
+    // an action carrying it must not be reported as having unknown keys.
+    '_lock',
+    '_lockDocsUrl',
+    '_lockReason',
+    '_lockSource',
+    '_packageId',
+    '_packageVersion',
+    '_provenance',
     'ai',
     'aria',
     'body',

package/dist/actions/actionResponse.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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.
+ */
+export interface ActionResponseOutcome {
+    ok: boolean;
+    /** Human-readable failure text. Always a string when `ok` is false. */
+    error?: string;
+    /**
+     * The ACTION ENVELOPE (`body.data`) — `{ success, data }`. Kept as-is
+     * because `ActionResult.data` has always carried this level and
+     * `resultDialog` field paths in the wild may compensate for it; see the
+     * note in {@link readActionPayload}.
+     */
+    envelope?: unknown;
+    /** What the handler actually returned (`body.data.data`). */
+    payload?: unknown;
+}
+/**
+ * The handler's own return value — one level deeper than the action envelope.
+ *
+ * `body.data` is `{ success, data }`; the handler's value is `body.data.data`.
+ * Reading the shallower level is why an action returning `{ redirectUrl }` was
+ * silently ignored: `body.data.redirectUrl` is never set by anything, because
+ * that level is constructed by the server and only ever holds `success`/`data`.
+ */
+export declare function readActionPayload(envelope: unknown): unknown;
+/** The pre-objectstack#3962 inner envelope, detected narrowly. */
+export declare function isLegacyActionEnvelope(v: unknown): boolean;
+/**
+ * Classify an `/actions` response. `label` names the action for the fallback
+ * message (e.g. `Action "log_call" failed`).
+ *
+ * `json` is the parsed body, or `null` when it could not be parsed.
+ */
+export declare function interpretActionResponse(res: {
+    ok: boolean;
+    status: number;
+}, json: any, label: string): ActionResponseOutcome;

package/dist/actions/actionResponse.js

@@ -0,0 +1,104 @@
+/**
+ * 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.
+ */
+/**
+ * The ONE place a `POST /api/v1/actions/...` response is interpreted.
+ *
+ * This existed twice — `useConsoleActionRuntime.serverActionHandler` and
+ * `RecordDetailView`'s copy of the same handler — and the two drifted, which is
+ * the whole reason objectstack#3913 was filed against the console: one copy
+ * learned to inspect the inner envelope and the other did not, so a failed
+ * action fired a green "completed" toast on every list/page surface. Two copies
+ * of a subtle envelope rule is a bug generator; this is the rule, once.
+ *
+ * Moved from `@object-ui/app-shell` (`utils/actionResponse`) into core by
+ * objectui#2904: `createServerActionHandler` — the dispatch every consumer
+ * registers as its `script` handler — lives here and must apply the rule, so
+ * the rule lives beside it.
+ *
+ * ## The legacy envelope was DOUBLE, and that was the trap (pre-objectstack#3962)
+ *
+ * ```
+ * {                          ← transport envelope
+ *   success: true,
+ *   data: {                  ← action envelope
+ *     success: true,
+ *     data: { … }            ← what the handler actually returned
+ *   }
+ * }
+ * ```
+ *
+ * Unlike `/api/v1/<anything-else>`, which wraps ONCE, `/actions` wraps twice —
+ * the route's own `{success, data}` sits inside the dispatcher's. Reading one
+ * level (the natural instinct, and what the other handlers correctly do) lands
+ * on the action envelope, not the payload.
+ *
+ * ## Failure has three shapes, and `res.ok` alone catches only one
+ *
+ * - **dispatch failure** — 404 no such action, 403 denied, 400 wrong action
+ *   type, 503 unavailable, 500 the handler crashed. `res.ok` is false.
+ * - **business rejection** — the handler ran and said no. HTTP **200** with
+ *   `data.success === false`. `res.ok` is TRUE; only the inner envelope shows
+ *   it. This is the one that got missed.
+ * - **transport-level `success: false`** — the outer envelope reporting a
+ *   failure directly.
+ */
+import { actionErrorDetail } from './actionErrorDetail';
+/**
+ * The handler's own return value — one level deeper than the action envelope.
+ *
+ * `body.data` is `{ success, data }`; the handler's value is `body.data.data`.
+ * Reading the shallower level is why an action returning `{ redirectUrl }` was
+ * silently ignored: `body.data.redirectUrl` is never set by anything, because
+ * that level is constructed by the server and only ever holds `success`/`data`.
+ */
+export function readActionPayload(envelope) {
+    // objectstack#3962 servers single-wrap: `body.data` IS the handler value,
+    // so most of the time this is the identity function. Only the exact LEGACY
+    // action envelope (pre-#3962: a boolean `success` and no keys beyond the
+    // envelope's own) is unwrapped one more level — a handler value that
+    // merely contains a `success` key passes through untouched.
+    if (isLegacyActionEnvelope(envelope)) {
+        return envelope.data;
+    }
+    return envelope;
+}
+const LEGACY_ENVELOPE_KEYS = new Set(['success', 'data', 'error', 'code', 'fields']);
+/** The pre-objectstack#3962 inner envelope, detected narrowly. */
+export function isLegacyActionEnvelope(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v)
+        && typeof v.success === 'boolean'
+        && Object.keys(v).every((k) => LEGACY_ENVELOPE_KEYS.has(k));
+}
+/**
+ * Classify an `/actions` response. `label` names the action for the fallback
+ * message (e.g. `Action "log_call" failed`).
+ *
+ * `json` is the parsed body, or `null` when it could not be parsed.
+ */
+export function interpretActionResponse(res, json, label) {
+    const envelope = json?.data;
+    // Pre-#3962 servers reported a rejection as HTTP 200 with the inner
+    // `{success:false, error}`; current servers answer a real status, which
+    // `res.ok` catches first. Detected narrowly so a handler value that merely
+    // contains `success: false` is not misread as a failure.
+    const innerFailed = isLegacyActionEnvelope(envelope) && envelope.success === false;
+    if (!res.ok || (json && json.success === false) || innerFailed) {
+        // A business rejection carries its message on the INNER envelope; a
+        // dispatch failure carries it on the outer one (as a nested
+        // `{message, code}` object, which `actionErrorDetail` resolves to a
+        // string — handing that object to `toast.error()` as a React child
+        // crashes the page, React #31).
+        return {
+            ok: false,
+            error: innerFailed
+                ? actionErrorDetail(envelope, `${label} failed`)
+                : actionErrorDetail(json, `${label} failed (HTTP ${res.status})`),
+        };
+    }
+    return { ok: true, envelope, payload: readActionPayload(envelope) };
+}

package/dist/actions/index.d.ts

@@ -11,3 +11,6 @@ export * from './actionKeys.js';
 export * from './TransactionManager.js';
 export * from './UndoManager.js';
 export * from './bulkFastPath.js';
+export * from './actionErrorDetail.js';
+export * from './actionResponse.js';
+export * from './serverActionHandler.js';

package/dist/actions/index.js

@@ -11,3 +11,6 @@ export * from './actionKeys.js';
 export * from './TransactionManager.js';
 export * from './UndoManager.js';
 export * from './bulkFastPath.js';
+export * from './actionErrorDetail.js';
+export * from './actionResponse.js';
+export * from './serverActionHandler.js';

package/dist/actions/serverActionHandler.d.ts

@@ -0,0 +1,143 @@
+/**
+ * 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.
+ */
+/**
+ * `createServerActionHandler` — the core server-action dispatcher factory
+ * (objectui#2904, the follow-up #2896 deferred).
+ *
+ * `ActionSchema.body` (HookBodySchema — L1 expression / L2 sandboxed JS) is the
+ * spec's preferred binding for script actions, and bodies execute SERVER-side:
+ * `POST /api/v1/actions/{object}/{action}` → the runtime sandbox. This client
+ * never interprets a body (L2 needs an isolated VM enforcing capabilities /
+ * `timeoutMs` / `memoryMb`, which a browser cannot provide; L1 is formula-engine
+ * CEL, a different dialect from this package's `${…}` evaluator). The client
+ * DISPATCHES; it does not interpret — see the `ActionDef.body` doc and #2896.
+ *
+ * Until this factory existed, only the console could dispatch: app-shell's
+ * `useConsoleActionRuntime` and `RecordDetailView` each hand-rolled the same
+ * POST (and drifted — objectstack#3913, framework#3935), while every other
+ * `@object-ui/core` consumer fell through to the built-in `executeScript` and
+ * hit a dead end. The factory is deliberately opinion-free about the three
+ * things core has no business deciding (#2904):
+ *
+ * - **auth** — inject `fetch` (an authenticated wrapper: Bearer, tenant,
+ *   cookies — whatever the host's transport needs);
+ * - **base URL** — inject `baseUrl` (a string or a thunk; core inherits no
+ *   bundler env convention like `VITE_SERVER_URL`);
+ * - **object scope** — inject `resolveObject` for the fallback when the action
+ *   declares no `objectName` of its own.
+ *
+ * Everything protocol-shaped lives here, once: name-only action identity
+ * (ADR-0110 D1), the record-id resolution dance (`_rowRecord`, `recordIdField`,
+ * aggregate `_selectedIds`, toolbar-selection fallback with its guards), the
+ * re-entrancy guard, the POST body shape `{ recordId, params }`, and the
+ * `/actions` envelope rule (`interpretActionResponse`).
+ *
+ * Standalone usage:
+ *
+ * ```ts
+ * import { createServerActionHandler } from '@object-ui/core';
+ *
+ * const script = createServerActionHandler({
+ *   fetch: myAuthenticatedFetch,
+ *   baseUrl: 'https://api.example.com',
+ *   resolveObject: () => currentObjectName,
+ *   onRefresh: () => notifyDataChanged(),
+ * });
+ * // Register it — registered handlers beat the built-in executeScript:
+ * // <ActionProvider handlers={{ script }} … />  (or runner.registerHandler('script', script))
+ * ```
+ */
+import type { ActionContext, ActionDef, ActionResult } from './ActionRunner';
+/** The response surface the dispatcher needs — satisfied by a WHATWG `Response`. */
+export interface ServerActionFetchResponse {
+    ok: boolean;
+    status: number;
+    json(): Promise<any>;
+}
+/**
+ * The injected transport. Core has no auth opinion: pass an authenticated
+ * wrapper (e.g. app-shell's `createAuthenticatedFetch()`), not the bare global
+ * `fetch`, unless your deployment really needs no credentials.
+ */
+export type ServerActionFetch = (url: string, init: {
+    method: 'POST';
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<ServerActionFetchResponse>;
+/**
+ * What a record-id resolver reports: a record id (absent for object-scoped
+ * dispatches), or a blocking error the handler returns without POSTing.
+ */
+export interface ServerActionRecordIdResolution {
+    recordId?: unknown;
+    error?: string;
+}
+export type ServerActionRecordIdResolver = (action: ActionDef, context: ActionContext | undefined) => ServerActionRecordIdResolution;
+/**
+ * A dispatch handler produced by {@link createServerActionHandler}. Assignable
+ * to `ActionRunnerHandler` — register it under `'script'` (and, where the host
+ * routes them server-side, other action types).
+ */
+export type ServerActionHandler = (action: ActionDef, context?: ActionContext) => Promise<ActionResult>;
+export interface ServerActionHandlerConfig {
+    /** Authenticated transport — see {@link ServerActionFetch}. */
+    fetch: ServerActionFetch;
+    /**
+     * Server origin prefix (`''`/omitted = same-origin). A thunk is read per
+     * dispatch, so hosts with late-bound configuration can inject one.
+     */
+    baseUrl?: string | (() => string);
+    /**
+     * Fallback object scope when the action declares no `objectName` — e.g. the
+     * current view's object. When neither yields a name the dispatch is `global`.
+     */
+    resolveObject?: (action: ActionDef, context: ActionContext | undefined) => string | undefined;
+    /**
+     * Replace the standard record-id dance ({@link resolveServerActionRecordId})
+     * wholesale — e.g. a record page resolves against ITS record, not a grid
+     * selection.
+     */
+    resolveRecordId?: ServerActionRecordIdResolver;
+    /**
+     * Invoked after a successful dispatch that requests a refresh
+     * (`refreshAfter !== false`) — wire your data invalidation here.
+     */
+    onRefresh?: () => void;
+}
+/**
+ * An action that also mounts on list rows (`list_item`) or record pages is
+ * designed to run against a single record. When such an action is launched
+ * from the list toolbar with nothing selected, there is no record context to
+ * resolve — block up front instead of triggering a run that fails at its
+ * first record-bound step (#2210: "Update requires an ID"). Actions declaring
+ * only object-level locations (e.g. `['list_toolbar']`) are left alone: they
+ * legitimately run without a record.
+ */
+export declare function isRecordScopedAction(action: ActionDef): boolean;
+/**
+ * The standard record-id resolution dance, shared by the dispatcher and by
+ * consumers that need the id BEFORE dispatching (e.g. app-shell's zero-roundtrip
+ * `newTabUrl` fast path). Pure — reads the action/context, mutates nothing.
+ *
+ * Order: explicit `params.recordId` → the stashed `_rowRecord`'s
+ * `recordIdField` (list_item invocations) → the grid's checkbox selection from
+ * the runner context (`selectedRecords`, list_toolbar invocations). An
+ * AGGREGATE bulk dispatch (objectui#3139) carries the whole selection as
+ * `params._selectedIds` — the server reads that array, not `recordId`, so the
+ * selection fallback must not touch it (resolving a recordId would mislabel
+ * the run as record-scoped, and the multi-select guard would block exactly the
+ * selection the dispatch exists to carry). Multi-select is ambiguous for a
+ * single-record action — block with a message; so is zero selection when the
+ * action is record-scoped (see {@link isRecordScopedAction}).
+ */
+export declare function resolveServerActionRecordId(action: ActionDef, context: ActionContext | undefined): ServerActionRecordIdResolution;
+/**
+ * Build a server-action dispatch handler. See the module doc for what the
+ * factory owns and what the config injects.
+ */
+export declare function createServerActionHandler(config: ServerActionHandlerConfig): ServerActionHandler;

package/dist/actions/serverActionHandler.js

@@ -0,0 +1,137 @@
+/**
+ * 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.
+ */
+import { interpretActionResponse } from './actionResponse';
+/**
+ * An action that also mounts on list rows (`list_item`) or record pages is
+ * designed to run against a single record. When such an action is launched
+ * from the list toolbar with nothing selected, there is no record context to
+ * resolve — block up front instead of triggering a run that fails at its
+ * first record-bound step (#2210: "Update requires an ID"). Actions declaring
+ * only object-level locations (e.g. `['list_toolbar']`) are left alone: they
+ * legitimately run without a record.
+ */
+export function isRecordScopedAction(action) {
+    const locations = action.locations;
+    if (!Array.isArray(locations))
+        return false;
+    return locations.some((l) => l === 'list_item' || l === 'record_header' || l === 'record_more' || l === 'record_section');
+}
+/**
+ * The standard record-id resolution dance, shared by the dispatcher and by
+ * consumers that need the id BEFORE dispatching (e.g. app-shell's zero-roundtrip
+ * `newTabUrl` fast path). Pure — reads the action/context, mutates nothing.
+ *
+ * Order: explicit `params.recordId` → the stashed `_rowRecord`'s
+ * `recordIdField` (list_item invocations) → the grid's checkbox selection from
+ * the runner context (`selectedRecords`, list_toolbar invocations). An
+ * AGGREGATE bulk dispatch (objectui#3139) carries the whole selection as
+ * `params._selectedIds` — the server reads that array, not `recordId`, so the
+ * selection fallback must not touch it (resolving a recordId would mislabel
+ * the run as record-scoped, and the multi-select guard would block exactly the
+ * selection the dispatch exists to carry). Multi-select is ambiguous for a
+ * single-record action — block with a message; so is zero selection when the
+ * action is record-scoped (see {@link isRecordScopedAction}).
+ */
+export function resolveServerActionRecordId(action, context) {
+    const params = (action.params && !Array.isArray(action.params))
+        ? action.params
+        : {};
+    const rowRecord = params._rowRecord;
+    const recordIdField = action.recordIdField || 'id';
+    let recordId = params.recordId ?? rowRecord?.[recordIdField];
+    const isAggregateDispatch = Array.isArray(params._selectedIds);
+    if (recordId == null && !isAggregateDispatch) {
+        const selected = Array.isArray(context?.selectedRecords) ? context.selectedRecords : [];
+        if (selected.length === 1) {
+            recordId = selected[0]?.[recordIdField];
+        }
+        else if (selected.length > 1) {
+            // The runner's post-execution hook surfaces `error` as a toast.
+            return { error: 'This action runs on a single record — select exactly one row.' };
+        }
+        else if (isRecordScopedAction(action)) {
+            return { error: 'This action runs on a single record — select a row first.' };
+        }
+    }
+    return { recordId: recordId ?? undefined };
+}
+/**
+ * Build a server-action dispatch handler. See the module doc for what the
+ * factory owns and what the config injects.
+ */
+export function createServerActionHandler(config) {
+    const { fetch: dispatchFetch, resolveObject, onRefresh } = config;
+    const resolveRecordId = config.resolveRecordId ?? resolveServerActionRecordId;
+    // Guards against double-firing a server action (slow SSO handoff, etc.).
+    // Handler-instance state: keep the produced handler stable for its guard to
+    // span invocations.
+    const inFlight = new Set();
+    return async function serverActionDispatch(action, context) {
+        // [ADR-0110 D1] The URL identifies the action by its declarative `name`,
+        // never by `target`. `target` is a BINDING EXPRESSION — the handler's
+        // registration key here, but a URL / flow id / FormView name for other
+        // types, `${param.X}`-interpolatable, and legitimately non-unique — so it
+        // cannot identify a declaration. Posting it (the old `target || name`)
+        // meant the server resolved NO declaration for a target-bound action and
+        // silently skipped both the ADR-0066 D4 capability gate and the ADR-0104
+        // param contract (framework#3935). The server derives the handler key from
+        // the declaration it resolves by name.
+        const actionName = action.name;
+        if (!actionName) {
+            return { success: false, error: 'Action has no name — a server action must declare one' };
+        }
+        // The row record is a CLIENT-side stash (list_item invocations park it
+        // under `params._rowRecord` for param defaults and id resolution) — never
+        // part of the server contract, so it is stripped from the POSTed params.
+        const params = (action.params && !Array.isArray(action.params))
+            ? { ...action.params }
+            : {};
+        delete params._rowRecord;
+        const resolution = resolveRecordId(action, context);
+        if (resolution.error) {
+            return { success: false, error: resolution.error };
+        }
+        const recordId = resolution.recordId;
+        // Re-entrancy guard.
+        const inflightKey = `${actionName}:${recordId ?? ''}`;
+        if (inFlight.has(inflightKey)) {
+            return { success: false, error: 'Action already in progress' };
+        }
+        inFlight.add(inflightKey);
+        try {
+            const baseUrl = typeof config.baseUrl === 'function' ? config.baseUrl() : (config.baseUrl ?? '');
+            const objectName = action.objectName || resolveObject?.(action, context) || 'global';
+            const res = await dispatchFetch(`${baseUrl}/api/v1/actions/${encodeURIComponent(objectName)}/${encodeURIComponent(actionName)}`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ recordId, params }),
+            });
+            const json = await res.json().catch(() => null);
+            // The `/actions` envelope rule, once — see ./actionResponse.
+            const outcome = interpretActionResponse(res, json, `Action "${actionName}"`);
+            if (!outcome.ok) {
+                // Don't toast here — the ActionRunner's post-execution hook surfaces
+                // `error` as a toast; a handler-side toast double-fires it.
+                return { success: false, error: outcome.error };
+            }
+            const shouldRefresh = action.refreshAfter !== false;
+            if (shouldRefresh)
+                onRefresh?.();
+            // `data` carries the ACTION ENVELOPE (`{ success, data }`), the level
+            // `ActionResult.data` has always carried; consumers reading the
+            // handler's own return value go through `readActionPayload`.
+            return { success: true, data: outcome.envelope, reload: shouldRefresh };
+        }
+        catch (error) {
+            return { success: false, error: error.message };
+        }
+        finally {
+            inFlight.delete(inflightKey);
+        }
+    };
+}

package/dist/evaluator/ExpressionEvaluator.js

@@ -256,8 +256,10 @@ export class ExpressionEvaluator {
         // Fail-closed callers need to tell a genuine `false` from a fault. The
         // canonical helper fails soft to the fallback, so a value that tracks the
         // fallback in BOTH runs means the predicate faulted — then we throw.
-        const asTrue = evalFieldPredicate(source, record, true, undefined, bag);
-        const asFalse = evalFieldPredicate(source, record, false, undefined, bag);
+        // `warn: false`: the throw below IS this path's diagnostic; without it one
+        // broken predicate would log AND throw (#5149).
+        const asTrue = evalFieldPredicate(source, record, true, undefined, bag, { warn: false });
+        const asFalse = evalFieldPredicate(source, record, false, undefined, bag, { warn: false });
         if (asTrue !== asFalse) {
             throw new Error(`CEL predicate failed to evaluate: ${source}`);
         }

package/dist/evaluator/fieldRules.d.ts

@@ -10,6 +10,21 @@ export type FieldRulePredicate = string | {
     dialect?: string;
     source: string;
 };
+/** Diagnostic options for {@link evalFieldPredicate} evaluation failures. */
+export interface FieldPredicateDiagnostic {
+    /**
+     * Human-readable locator included in the one-time failure warning — e.g.
+     * `"visibleWhen of field 'amount'"`. Pass whatever the call site knows; the
+     * predicate source text and failure reason are always included.
+     */
+    context?: string;
+    /**
+     * Set `false` when the caller deliberately probes for faults (evaluating
+     * twice with both fallbacks) and surfaces its own diagnostic — prevents two
+     * warnings for one broken predicate. Defaults to `true`.
+     */
+    warn?: boolean;
+}
 /**
  * Evaluate a field-rule CEL predicate against a record.
  *
@@ -24,14 +39,23 @@ export type FieldRulePredicate = string | {
  *                  e.g. `{ parent }` so an inline line-item cell can reference
  *                  its header (`parent.status == 'paid'`) as well as its own
  *                  row (`record.quantity`). Bound via the engine's `extra`.
+ * @param diagnostic  Failure-warning options: a `context` locator for the
+ *                  one-time warning, and `warn: false` for callers that probe
+ *                  for faults and report them themselves. The returned value
+ *                  is unaffected either way.
  */
-export declare function evalFieldPredicate(pred: FieldRulePredicate | undefined | null, record: Record<string, unknown>, fallback: boolean, previous?: Record<string, unknown>, scope?: Record<string, unknown>): boolean;
+export declare function evalFieldPredicate(pred: FieldRulePredicate | undefined | null, record: Record<string, unknown>, fallback: boolean, previous?: Record<string, unknown>, scope?: Record<string, unknown>, diagnostic?: FieldPredicateDiagnostic): boolean;
 /**
  * Resolve the effective `{ visible, readonly, required }` state for a field
  * given its conditional rules and the live record. Each `*When` rule, when
  * present, *overrides* the static flag. A static `true` is never weakened by a
  * `false` predicate result for required/readonly — but `visibleWhen` is
  * authoritative when present (so a field can be conditionally shown/hidden).
+ *
+ * @param fieldContext  Optional locator for failure warnings — e.g.
+ *                      `"field 'amount'"`. The warning then reads
+ *                      `visibleWhen of field 'amount' …`; without it, the rule
+ *                      kind alone is reported.
  */
 export declare function resolveFieldRuleState(rules: {
     visibleWhen?: FieldRulePredicate;
@@ -40,7 +64,7 @@ export declare function resolveFieldRuleState(rules: {
 }, record: Record<string, unknown>, statics: {
     required?: boolean;
     readonly?: boolean;
-}, previous?: Record<string, unknown>, scope?: Record<string, unknown>): {
+}, previous?: Record<string, unknown>, scope?: Record<string, unknown>, fieldContext?: string): {
     visible: boolean;
     readonly: boolean;
     required: boolean;