@object-ui/core 17.2.0 → 17.3.0

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;

package/dist/evaluator/fieldRules.js

@@ -24,6 +24,17 @@
  * block submit) and *fail-open* for readonly (a broken predicate leaves the
  * field editable) — matching the server, which logs and allows the change
  * through.
+ *
+ * Fail-open is **loud**, not silent (objectstack#5149): a predicate that
+ * cannot be evaluated — parse error, unbound identifier, engine fault — logs
+ * one `console.warn` per predicate text with the source and the failure
+ * reason, then still returns the caller's fallback. Without the warning a
+ * broken predicate is indistinguishable from an absent one, so
+ * conditional-visibility bugs survive inspection indefinitely. This is the
+ * client half of the server's "log and allow" convention (`readonlyWhen for
+ * 'x' failed to evaluate — change allowed through`). The *default* stays
+ * fail-open on purpose — flipping it is a shipped-behavior change tracked
+ * separately in objectstack#5149 (appeal 1, undecided).
  */
 import { ExpressionEngine } from '@objectstack/formula';
 /** Normalize a predicate into the `Expression` shape the engine expects. */
@@ -32,6 +43,26 @@ function toExpression(pred) {
         return { dialect: 'cel', source: pred };
     return { dialect: (pred.dialect ?? 'cel'), source: pred.source };
 }
+const warnedPredicates = new Set();
+/**
+ * One-time warning for a predicate that could not be evaluated. Deduped per
+ * predicate TEXT (dialect + source): a broken predicate is re-evaluated on
+ * every render/keystroke, and the point is one loud line, not a scrolling
+ * wall. The dedupe key is JSON-encoded — never a control-character separator
+ * (objectstack#5450 made a sibling of this file binary to grep that way).
+ */
+function warnPredicateFailure(expr, fallback, reason, context) {
+    const key = JSON.stringify([expr.dialect, expr.source]);
+    if (warnedPredicates.has(key))
+        return;
+    warnedPredicates.add(key);
+    console.warn('[object-ui] A conditional predicate failed to evaluate' +
+        (context ? ` (${context})` : '') +
+        ` and was treated as its safe default (${String(fallback)}): ` +
+        JSON.stringify(expr.source) +
+        `. Reason: ${reason}. ` +
+        "Values are bound under 'record.' (e.g. record.status) — check the field names and CEL syntax.");
+}
 /**
  * Evaluate a field-rule CEL predicate against a record.
  *
@@ -46,21 +77,37 @@ function toExpression(pred) {
  *                  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 function evalFieldPredicate(pred, record, fallback, previous, scope) {
+export function evalFieldPredicate(pred, record, fallback, previous, scope, diagnostic) {
     if (pred == null || (typeof pred === 'string' && !pred.trim()))
         return fallback;
+    const expr = toExpression(pred);
     try {
-        const res = ExpressionEngine.evaluate(toExpression(pred), {
+        const res = ExpressionEngine.evaluate(expr, {
             record,
             previous,
             ...(scope ? { extra: scope } : {}),
         });
-        if (!res.ok)
+        if (!res.ok) {
+            // Parse error, type error, unbound identifier, engine fault … — every
+            // not-ok verdict resolves to the fallback, but never silently (#5149).
+            if (diagnostic?.warn !== false) {
+                warnPredicateFailure(expr, fallback, `[${res.error.kind}] ${res.error.message}`, diagnostic?.context);
+            }
             return fallback;
+        }
         return res.value === true;
     }
-    catch {
+    catch (err) {
+        // The engine contract is "never throws"; this guard is for anything that
+        // slips past it. Same loud fail-open as the not-ok branch.
+        if (diagnostic?.warn !== false) {
+            warnPredicateFailure(expr, fallback, `[throw] ${err instanceof Error ? err.message : String(err)}`, diagnostic?.context);
+        }
         return fallback;
     }
 }
@@ -70,18 +117,26 @@ export function evalFieldPredicate(pred, record, fallback, previous, scope) {
  * 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 function resolveFieldRuleState(rules, record, statics, previous, scope) {
+export function resolveFieldRuleState(rules, record, statics, previous, scope, fieldContext) {
+    const diag = (rule) => ({
+        context: fieldContext ? `${rule} of ${fieldContext}` : rule,
+    });
     const visible = rules.visibleWhen != null
-        ? evalFieldPredicate(rules.visibleWhen, record, true, previous, scope)
+        ? evalFieldPredicate(rules.visibleWhen, record, true, previous, scope, diag('visibleWhen'))
         : true;
     const readonly = statics.readonly === true ||
         (rules.readonlyWhen != null
-            ? evalFieldPredicate(rules.readonlyWhen, record, false, previous, scope)
+            ? evalFieldPredicate(rules.readonlyWhen, record, false, previous, scope, diag('readonlyWhen'))
             : false);
     const required = statics.required === true ||
         (rules.requiredWhen != null
-            ? evalFieldPredicate(rules.requiredWhen, record, false, previous, scope)
+            ? evalFieldPredicate(rules.requiredWhen, record, false, previous, scope, diag('requiredWhen'))
             : false);
     return { visible, readonly, required };
 }

package/dist/evaluator/index.d.ts

@@ -7,6 +7,7 @@
  */
 export * from './ExpressionContext.js';
 export * from './ExpressionEvaluator.js';
+export * from './predicateInput.js';
 export * from './fieldRules.js';
 export * from './listConditional.js';
 export * from './optionRules.js';

package/dist/evaluator/index.js

@@ -7,6 +7,7 @@
  */
 export * from './ExpressionContext.js';
 export * from './ExpressionEvaluator.js';
+export * from './predicateInput.js';
 export * from './fieldRules.js';
 export * from './listConditional.js';
 export * from './optionRules.js';

package/dist/evaluator/listConditional.d.ts

@@ -34,6 +34,7 @@
  * (or nothing) to the server's CEL engine.
  */
 import { type FieldRulePredicate } from './fieldRules.js';
+import { type FieldContainerLike } from '../utils/predicate-record.js';
 /** True when a *string* predicate uses legacy-only (non-CEL) syntax. */
 export declare function isLegacyDialectSource(source: string): boolean;
 /** Options for {@link evalRowPredicate}. */
@@ -49,6 +50,14 @@ export interface RowPredicateOptions {
     warnOnError?: boolean;
     /** Label used in warning messages (e.g. an action name or rule index). */
     label?: string;
+    /**
+     * The object's field definitions (`objectSchema.fields`). Supplying them lets
+     * a relation field be bound as the FOREIGN KEY the server stores, rather than
+     * as whatever `$expand` happened to substitute for it on this surface — see
+     * {@link toPredicateRecord}. Omitting them keeps the payload verbatim, so a
+     * caller with no schema at hand never guesses which fields are relations.
+     */
+    fields?: FieldContainerLike;
 }
 /**
  * Evaluate a single boolean predicate against a row record on the canonical CEL
@@ -89,5 +98,8 @@ export type ConditionalFormattingRuleLike = {
  *
  * @param scope  Extra top-level scope (host predicate scope) bound alongside
  *               the row, so `features.*` predicates keep resolving.
+ * @param fields The object's field definitions, so a rule comparing a relation
+ *               field sees the stored foreign key rather than the expanded
+ *               record (see {@link RowPredicateOptions.fields}).
  */
-export declare function resolveConditionalFormatting(record: Record<string, unknown> | null | undefined, rules?: readonly ConditionalFormattingRuleLike[] | null, scope?: Record<string, unknown>): Record<string, string>;
+export declare function resolveConditionalFormatting(record: Record<string, unknown> | null | undefined, rules?: readonly ConditionalFormattingRuleLike[] | null, scope?: Record<string, unknown>, fields?: FieldContainerLike): Record<string, string>;

package/dist/evaluator/optionRules.js

@@ -39,7 +39,11 @@ export function isOptionGroupGated(dependsOn, record) {
 export function resolveVisibleOptions(options, record, scope) {
     if (!options || options.length === 0)
         return [];
-    return options.filter((o) => o?.visibleWhen == null ? true : evalFieldPredicate(o.visibleWhen, record, true, undefined, scope));
+    return options.filter((o) => o?.visibleWhen == null
+        ? true
+        : evalFieldPredicate(o.visibleWhen, record, true, undefined, scope, {
+            context: `visibleWhen of option '${String(o.value)}'`,
+        }));
 }
 /**
  * Whether a scalar field value is still valid given the currently-visible