@object-ui/core 17.3.0 → 17.6.0

package/dist/evaluator/listConditional.d.ts

@@ -44,12 +44,37 @@ export interface RowPredicateOptions {
      * row-action `visible`/`disabled`; `false` (no style) for formatting. */
     fallback?: boolean;
     /** Extra top-level scope merged alongside the row — e.g. the global predicate
-     * scope (`features` / `user` / `app`) a host shell provides. */
+     * scope (`features` / `user` / `app`) a host shell provides. The row wins on
+     * collision: a `record` or `data` key here never shadows the row. */
     scope?: Record<string, unknown>;
     /** When true, log a one-time warning if a *present* predicate faults. */
     warnOnError?: boolean;
     /** Label used in warning messages (e.g. an action name or rule index). */
     label?: string;
+    /**
+     * This surface has **no row of its own** — bind NOTHING for the row instead
+     * of binding an empty one, so a `record` / `data` the HOST SCOPE carries
+     * survives to the predicate (objectui#4640).
+     *
+     * The default (`false`) is this function's whole subject rule: the row is
+     * pinned over the scope, on both dialect paths, so `record` / `data` always
+     * name THIS row even when the host scope carries keys of those names
+     * (objectui#3796). That is right for every row surface — and exactly wrong
+     * for a surface that has no row, because the pin then writes an EMPTY
+     * `record` / `data` over the host's real ones and every `record.*` predicate
+     * faults with "No such key". "This surface has no row of its own" and "this
+     * surface's row is empty" are different facts; only the latter is entitled to
+     * shadow the scope. Same distinction, same words, as `usePredicateRecordContext`
+     * in `@object-ui/react` (objectui#4075) — which is the BINDING half of this
+     * rule for the `useCondition` tier; this is the evaluation-entry half.
+     *
+     * Set it where the predicate is scoped to a *dialog / shell / page* rather
+     * than to a record — `ActionParamDialog`'s param `visible` gates are the
+     * first caller (objectui#4640): their scope IS the host predicate scope,
+     * `data` and all. `opts.fields` is meaningless here (there is no row to
+     * collapse relations on) and is ignored.
+     */
+    rowless?: boolean;
     /**
      * The object's field definitions (`objectSchema.fields`). Supplying them lets
      * a relation field be bound as the FOREIGN KEY the server stores, rather than
@@ -63,9 +88,34 @@ export interface RowPredicateOptions {
  * Evaluate a single boolean predicate against a row record on the canonical CEL
  * engine (with a legacy-dialect fallback — see the module note). The row's
  * fields are bound three ways so every authoring convention resolves:
- * `record.status` (spec/canonical), bare `status` (row-action shorthand), and
- * `data.status` (legacy). The optional `scope` (host predicate scope) is bound
- * alongside so `features.*` / `user.*` predicates keep working.
+ * `record.status`, bare `status` (row-action shorthand), and `data.status`.
+ *
+ * ⚠️ Those three are NOT peers, and this doc comment used to read as though
+ * they were. **The canon is `record.*`** (maintainer ruling 2026-08-20 on
+ * objectui#5330, option B); the other two are client tolerances in a
+ * deprecation window, kept because stored metadata carries them and warned
+ * about — from the CEL path below — by `warnNonCanonicalRowSpelling`. The
+ * server accepts `record.*` and NOTHING else: measured on
+ * `@objectstack/formula@17.1.0`, `buildScope({ record })` mounts exactly
+ * `['record']`, so a bare field faults `Unknown variable: status` there and a
+ * `data.*` predicate faults `Unknown variable: data`. See
+ * {@link ./rowPredicateCanon.ts} for the full measurement, for why `data.*` is
+ * the dangerous one (it is silently ACCEPTED by the server's authoring oracle
+ * and still binds nothing at runtime), and for why the deprecation is scoped to
+ * this runtime layer rather than declared platform-wide (`data` is the
+ * canonical root of a metadata-editing form — ADR-0089 D3).
+ *
+ * ⛔ No spelling is removed from the binding, and none may be before a
+ * stored-metadata survey sizes the window — that is part of the same ruling.
+ *
+ * The optional `scope` (host predicate scope) is bound
+ * alongside so `features.*` / `user.*` predicates keep working — but the row is
+ * the subject: `record` and `data` always name THIS row, on both dialect paths,
+ * even when the host scope carries keys of those names (objectui#3796).
+ *
+ * A caller with no row at all passes {@link RowPredicateOptions.rowless}, and
+ * then nothing is bound over the scope — see that option for why an absent row
+ * must not be spelled as an empty one.
  */
 export declare function evalRowPredicate(pred: FieldRulePredicate | undefined | null, row: Record<string, unknown> | null | undefined, opts?: RowPredicateOptions): boolean;
 /** A conditional-formatting rule in any of the three historical shapes. */

package/dist/evaluator/listConditional.js

@@ -36,6 +36,7 @@
 import { evalFieldPredicate } from './fieldRules.js';
 import { ExpressionEvaluator } from './ExpressionEvaluator.js';
 import { toPredicateRecord } from '../utils/predicate-record.js';
+import { warnNonCanonicalRowSpelling } from './rowPredicateCanon.js';
 /**
  * Syntax that only the legacy JS-dialect evaluator understands and that is NOT
  * valid CEL: `${…}` templates, strict (in)equality, JS optional-chaining
@@ -54,27 +55,54 @@ function warnLegacyDialect(source) {
     if (warnedLegacy.has(source))
         return;
     warnedLegacy.add(source);
-    console.warn('[object-ui] A list conditional predicate uses the legacy expression dialect ' +
+    console.warn('[object-ui] A conditional predicate uses the legacy expression dialect ' +
         'and is not portable to the server CEL engine: ' +
         JSON.stringify(source) +
         '. Rewrite it as CEL (use "==" not "===", "x in [..]" for membership, ' +
         '".contains()" not ".includes()", and drop template interpolation).');
 }
 const warnedError = new Set();
-function warnEvalError(source, label) {
+/**
+ * One-time report for a predicate that could not be evaluated.
+ *
+ * The message names the caller's `fallback` as "its safe default" without
+ * asserting a direction, because the direction is the caller's: row surfaces
+ * fail CLOSED (a faulting `visible` hides the action), while a param-collection
+ * dialog fails OPEN (objectui#4640 — a silently hidden required param is the
+ * undiagnosable failure). Both are loud; only silence was ever ruled out
+ * (2026-08-06 on objectui#4051 / objectstack#5149).
+ *
+ * `reason` is the engine's own description of the failure (`"[runtime] No such
+ * key: owner_id"`) — the single most useful line for the author, and precisely
+ * what this path used to discard: the fault-probing CEL route silences the
+ * canonical helper's warning to avoid double-reporting, so before objectui#3792
+ * the more safety-critical the surface, the LESS it said. It is optional
+ * because a caller may genuinely have no reason to pass (nothing fabricates
+ * one).
+ *
+ * The wording is deliberately surface-neutral: this function is not
+ * list-specific and has not been for a long time — row kebabs, the bulk
+ * selection bar, kanban conditional formatting and (since objectui#3521)
+ * `page:header` all report through it, and telling a page-header author that
+ * "a list conditional predicate" failed sends them to the wrong screen.
+ */
+function warnEvalError(source, label, reason) {
     // One-time-warning identity for the (label, source) pair. JSON-encoded rather
     // than joined on a character the two halves "cannot contain" — that separator
     // was a raw U+0000, which made this whole file binary to grep (objectstack#5450).
     // JSON needs no impossible character, so the boundary is unambiguous for any
     // label and any predicate source, and the literal is plain ASCII.
+    // `reason` is deliberately NOT part of the key: one predicate text has one
+    // reason, so keying on it could only ever weaken the warn-once contract.
     const key = JSON.stringify([label ?? '', source]);
     if (warnedError.has(key))
         return;
     warnedError.add(key);
-    console.warn('[object-ui] A list conditional predicate failed to evaluate' +
+    console.warn('[object-ui] A conditional predicate failed to evaluate' +
         (label ? ` (${label})` : '') +
         ' and was treated as its safe default: ' +
         JSON.stringify(source) +
+        (reason ? `. Reason: ${reason}` : '') +
         '. Check the field names and CEL syntax.');
 }
 /**
@@ -91,20 +119,52 @@ function evalCel(pred, record, scope) {
     // verbatim — no second engine — so CEL semantics never drift from B2.
     // `warn: false`: this caller reports the fault itself (the labelled
     // `warnEvalError` in `evalRowPredicate`) — one warning per broken predicate,
-    // not two (#5149).
-    const asTrue = evalFieldPredicate(pred, record, true, undefined, scope, { warn: false });
-    const asFalse = evalFieldPredicate(pred, record, false, undefined, scope, { warn: false });
+    // not two (#5149). `onFault` carries the engine's reason across that silence
+    // so the labelled report can still name it (objectui#3792); both probes fault
+    // identically, so the first reason is the reason.
+    let reason;
+    const onFault = (r) => {
+        reason ?? (reason = r);
+    };
+    const diagnostic = { warn: false, onFault };
+    const asTrue = evalFieldPredicate(pred, record, true, undefined, scope, diagnostic);
+    const asFalse = evalFieldPredicate(pred, record, false, undefined, scope, diagnostic);
     if (asTrue !== asFalse)
-        return { ok: false, value: false };
+        return { ok: false, value: false, reason };
     return { ok: true, value: asTrue };
 }
 /**
  * Evaluate a single boolean predicate against a row record on the canonical CEL
  * engine (with a legacy-dialect fallback — see the module note). The row's
  * fields are bound three ways so every authoring convention resolves:
- * `record.status` (spec/canonical), bare `status` (row-action shorthand), and
- * `data.status` (legacy). The optional `scope` (host predicate scope) is bound
- * alongside so `features.*` / `user.*` predicates keep working.
+ * `record.status`, bare `status` (row-action shorthand), and `data.status`.
+ *
+ * ⚠️ Those three are NOT peers, and this doc comment used to read as though
+ * they were. **The canon is `record.*`** (maintainer ruling 2026-08-20 on
+ * objectui#5330, option B); the other two are client tolerances in a
+ * deprecation window, kept because stored metadata carries them and warned
+ * about — from the CEL path below — by `warnNonCanonicalRowSpelling`. The
+ * server accepts `record.*` and NOTHING else: measured on
+ * `@objectstack/formula@17.1.0`, `buildScope({ record })` mounts exactly
+ * `['record']`, so a bare field faults `Unknown variable: status` there and a
+ * `data.*` predicate faults `Unknown variable: data`. See
+ * {@link ./rowPredicateCanon.ts} for the full measurement, for why `data.*` is
+ * the dangerous one (it is silently ACCEPTED by the server's authoring oracle
+ * and still binds nothing at runtime), and for why the deprecation is scoped to
+ * this runtime layer rather than declared platform-wide (`data` is the
+ * canonical root of a metadata-editing form — ADR-0089 D3).
+ *
+ * ⛔ No spelling is removed from the binding, and none may be before a
+ * stored-metadata survey sizes the window — that is part of the same ruling.
+ *
+ * The optional `scope` (host predicate scope) is bound
+ * alongside so `features.*` / `user.*` predicates keep working — but the row is
+ * the subject: `record` and `data` always name THIS row, on both dialect paths,
+ * even when the host scope carries keys of those names (objectui#3796).
+ *
+ * A caller with no row at all passes {@link RowPredicateOptions.rowless}, and
+ * then nothing is bound over the scope — see that option for why an absent row
+ * must not be spelled as an empty one.
  */
 export function evalRowPredicate(pred, row, opts = {}) {
     const fallback = opts.fallback ?? false;
@@ -116,24 +176,70 @@ export function evalRowPredicate(pred, row, opts = {}) {
     // Relations collapse to the foreign key the server stores, so `record.owner`
     // means one thing whether or not this surface expanded the column
     // (objectui#3501). Returned by reference when there is nothing to collapse.
-    const rowObj = toPredicateRecord(row && typeof row === 'object' ? row : {}, opts.fields);
-    // Bare fields + `data.*` + the host scope, all top-level; `record` is bound
-    // by the engine call itself (evalCel / the legacy evaluator below).
-    const scope = { ...(opts.scope ?? {}), ...rowObj, data: rowObj };
+    // A `rowless` caller has no row to collapse, so `opts.fields` is moot there.
+    const rowObj = opts.rowless
+        ? {}
+        : toPredicateRecord(row && typeof row === 'object' ? row : {}, opts.fields);
+    // Bare fields + `data.*` + `record.*` + the host scope, all top-level.
+    //
+    // `data` AND `record` are pinned AFTER the spread, so a host scope that
+    // happens to carry either key is background and the ROW stays the subject of
+    // this function — on BOTH dialect paths. `data` always had that protection;
+    // `record` did not, and relied instead on each engine's own binding, which
+    // disagreed: the legacy evaluator re-pinned `record` (row won) while the CEL
+    // engine takes `extra` over its `record` binding (host scope won). Same
+    // function, same predicate text, opposite subjects — decided by whether the
+    // string happens to contain `===`/`${…}`, which no author is choosing
+    // deliberately (objectui#3796). Pinning here fixes both paths at the merge,
+    // independently of either engine's precedence.
+    //
+    // …UNLESS the caller has no row (`rowless`), in which case there is nothing
+    // to pin and the host scope keeps its own `record` / `data` — see the option.
+    const scope = opts.rowless
+        ? { ...(opts.scope ?? {}) }
+        : { ...(opts.scope ?? {}), ...rowObj, data: rowObj, record: rowObj };
+    // The predicate TEXT for diagnostics: a bare string is itself, an envelope is
+    // its `source`. Reported separately from `source` above, which is `undefined`
+    // for an envelope *by design* (it drives the dialect routing, and an envelope
+    // is never routed to the legacy engine). Reusing it for the warning is what
+    // made every faulting envelope report as the literal `"(expression)"` — no
+    // predicate text for the author, and, because the one-time key is
+    // (label, source), the FIRST faulting envelope on a given label silenced every
+    // other one under it (objectui#4640: measured on `evalRowPredicate` — a second
+    // envelope with a different, also-broken source warned zero times). The
+    // envelope is not an exotic spelling: `@objectstack/spec`'s
+    // `ExpressionInputSchema` normalizes every authored predicate into one, so it
+    // is the likeliest shape in served metadata and was the least diagnosable.
+    const predicateText = source ??
+        (pred && typeof pred === 'object' && typeof pred.source === 'string'
+            ? pred.source
+            : '(expression)');
     // Legacy-dialect *strings* route to the legacy engine (back-compat). The
     // `{ dialect: 'cel', source }` envelope is never routed here — it is CEL.
     if (source !== undefined && isLegacyDialectSource(source)) {
         warnLegacyDialect(source);
         try {
-            const evaluator = new ExpressionEvaluator({ ...scope, record: rowObj });
+            const evaluator = new ExpressionEvaluator(scope);
             return evaluator.evaluateCondition(source, { throwOnError: true });
         }
-        catch {
-            if (opts.warnOnError)
-                warnEvalError(source, opts.label);
+        catch (err) {
+            // The legacy engine reports by throwing, so its message IS the reason —
+            // the fail-closed report carries it for the same reason the CEL path does.
+            if (opts.warnOnError) {
+                warnEvalError(source, opts.label, `[legacy] ${err instanceof Error ? err.message : String(err)}`);
+            }
             return fallback;
         }
     }
+    // CEL path — everything reaching here is CEL, which is what makes this the
+    // right place for the objectui#5330 spelling warning: in the legacy `${…}`
+    // dialect above, `data.*` is the NORMAL spelling, so reporting it there would
+    // be a false positive on every legacy predicate. `data` names THIS row unless
+    // the caller is `rowless` (then the host scope keeps its own — see the
+    // option), which is exactly the condition the detector needs.
+    if (predicateText !== '(expression)') {
+        warnNonCanonicalRowSpelling(predicateText, rowObj, !opts.rowless, opts.label);
+    }
     // CEL path. The fault-aware `evalCel` costs two evaluations (to tell a fault
     // from a genuine `false`), so only pay it when a caller wants the labelled
     // fail-closed warning — the formatting hot path takes the single-eval fast
@@ -145,7 +251,7 @@ export function evalRowPredicate(pred, row, opts = {}) {
     }
     const verdict = evalCel(pred, rowObj, scope);
     if (!verdict.ok) {
-        warnEvalError(source ?? '(expression)', opts.label);
+        warnEvalError(predicateText, opts.label, verdict.reason);
         return fallback;
     }
     return verdict.value;

package/dist/evaluator/optionRules.d.ts

@@ -97,3 +97,58 @@ export interface CascadingOptions<T extends OptionLike> {
  * purely by `visibleWhen`). Callers format their own hint from `dependsOnFields`.
  */
 export declare function resolveCascadingOptions<T extends OptionLike>(rawOptions: readonly T[] | undefined | null, record: Record<string, unknown>, dependsOn: DependsOnInput, scope?: Record<string, unknown>): CascadingOptions<T>;
+/**
+ * Widget keys whose OFFERED option set is re-resolved against a live record by
+ * {@link resolveCascadingOptions} — i.e. the allow-list of widgets a surface
+ * must thread its live record to (`dependentValues`). Each of their options may
+ * carry a `visibleWhen` predicate read against `record.*`, and the field may
+ * declare a `dependsOn` gate (ADR-0058 / objectui#2284 / objectui#1583).
+ * Without the record a cascading select never sees its controlling field and
+ * stays permanently gated on the "select the parent first" hint.
+ *
+ * ## One definition, three surfaces (objectui#4770)
+ *
+ * Three surfaces feed this one evaluator, and each carried its own private copy
+ * of these four keys until this constant existed — with no gate able to notice
+ * them drifting apart on what "the record" means:
+ *
+ * - the object form — `CASCADE_OPTION_FIELD_TYPES` in
+ *   `components/src/renderers/form/form.tsx` (the original);
+ * - the single-record action dialog — `CASCADE_OPTION_WIDGET_TYPES` in
+ *   `app-shell/src/views/ActionParamDialog.tsx` (objectui#3765 / PR #4756);
+ * - the bulk action dialog — the same name in
+ *   `plugin-grid/src/components/BulkActionDialog.tsx` (objectui#4757 / PR #4763).
+ *
+ * The set lives in `@object-ui/core`, next to the evaluator it describes,
+ * because core is the one package all three already depend on — the form layer
+ * cannot reach `@object-ui/fields` (that dependency runs the other way). Same
+ * shape and same reason as `EXPANDABLE_FIELD_TYPES` in
+ * `core/src/utils/expand-fields.ts`, the in-repo precedent for a form-layer
+ * allow-table more than one surface reads. `@object-ui/fields` re-exports it
+ * next to `resolveFormWidgetType` for discoverability — a re-export, never a
+ * second definition.
+ *
+ * ## An ALLOW-LIST, not a blanket pass-through
+ *
+ * `dependentValues` is also the channel two widget-hint pickers read a specific
+ * SIBLING KEY from (`filter-condition` reads `object_name`, `recipient-picker`
+ * reads `recipient_type`), and the lookup family filters its query by it. All
+ * three surfaces above agree today in NOT feeding those from action / bulk
+ * dialog params, but that is a different wiring question from the one ruled
+ * here and it has never been decided either way. Stated here so the three
+ * copies of the statement become one — the boundary itself stays open:
+ * objectui#4771.
+ *
+ * ## Normalization stays with the consumer
+ *
+ * The members are WIDGET keys — `resolveFormWidgetType` output in the two
+ * dialogs, `normalizeFieldType` output (the `field:` prefix stripped) in the
+ * form — not authored `type` spellings. Each consumer keeps its own
+ * normalization; the two normalizations agree on these four members, which is
+ * what makes one shared set safe to read from both.
+ *
+ * `select` + `multiple: true` is not listed separately: `SelectField` delegates
+ * to `MultiSelectField` with the whole prop object, so the key it resolves
+ * under (`select`) is the one that must carry the record.
+ */
+export declare const CASCADE_OPTION_WIDGET_TYPES: ReadonlySet<string>;

package/dist/evaluator/optionRules.js

@@ -77,3 +77,63 @@ export function resolveCascadingOptions(rawOptions, record, dependsOn, scope) {
     const options = gated ? [] : resolveVisibleOptions(rawOptions, record, scope);
     return { options, gated, dependsOnFields };
 }
+/**
+ * Widget keys whose OFFERED option set is re-resolved against a live record by
+ * {@link resolveCascadingOptions} — i.e. the allow-list of widgets a surface
+ * must thread its live record to (`dependentValues`). Each of their options may
+ * carry a `visibleWhen` predicate read against `record.*`, and the field may
+ * declare a `dependsOn` gate (ADR-0058 / objectui#2284 / objectui#1583).
+ * Without the record a cascading select never sees its controlling field and
+ * stays permanently gated on the "select the parent first" hint.
+ *
+ * ## One definition, three surfaces (objectui#4770)
+ *
+ * Three surfaces feed this one evaluator, and each carried its own private copy
+ * of these four keys until this constant existed — with no gate able to notice
+ * them drifting apart on what "the record" means:
+ *
+ * - the object form — `CASCADE_OPTION_FIELD_TYPES` in
+ *   `components/src/renderers/form/form.tsx` (the original);
+ * - the single-record action dialog — `CASCADE_OPTION_WIDGET_TYPES` in
+ *   `app-shell/src/views/ActionParamDialog.tsx` (objectui#3765 / PR #4756);
+ * - the bulk action dialog — the same name in
+ *   `plugin-grid/src/components/BulkActionDialog.tsx` (objectui#4757 / PR #4763).
+ *
+ * The set lives in `@object-ui/core`, next to the evaluator it describes,
+ * because core is the one package all three already depend on — the form layer
+ * cannot reach `@object-ui/fields` (that dependency runs the other way). Same
+ * shape and same reason as `EXPANDABLE_FIELD_TYPES` in
+ * `core/src/utils/expand-fields.ts`, the in-repo precedent for a form-layer
+ * allow-table more than one surface reads. `@object-ui/fields` re-exports it
+ * next to `resolveFormWidgetType` for discoverability — a re-export, never a
+ * second definition.
+ *
+ * ## An ALLOW-LIST, not a blanket pass-through
+ *
+ * `dependentValues` is also the channel two widget-hint pickers read a specific
+ * SIBLING KEY from (`filter-condition` reads `object_name`, `recipient-picker`
+ * reads `recipient_type`), and the lookup family filters its query by it. All
+ * three surfaces above agree today in NOT feeding those from action / bulk
+ * dialog params, but that is a different wiring question from the one ruled
+ * here and it has never been decided either way. Stated here so the three
+ * copies of the statement become one — the boundary itself stays open:
+ * objectui#4771.
+ *
+ * ## Normalization stays with the consumer
+ *
+ * The members are WIDGET keys — `resolveFormWidgetType` output in the two
+ * dialogs, `normalizeFieldType` output (the `field:` prefix stripped) in the
+ * form — not authored `type` spellings. Each consumer keeps its own
+ * normalization; the two normalizations agree on these four members, which is
+ * what makes one shared set safe to read from both.
+ *
+ * `select` + `multiple: true` is not listed separately: `SelectField` delegates
+ * to `MultiSelectField` with the whole prop object, so the key it resolves
+ * under (`select`) is the one that must carry the record.
+ */
+export const CASCADE_OPTION_WIDGET_TYPES = new Set([
+    'select',
+    'multiselect',
+    'radio',
+    'checkboxes',
+]);

package/dist/evaluator/predicateInput.d.ts

@@ -44,7 +44,9 @@ export type EvaluatorPredicateInput = string | boolean | {
  *
  * Accepts:
  *   - `boolean` → returned as-is (predicate evaluation short-circuits).
- *   - `string`  → wrapped as `${string}` (legacy DX shorthand).
+ *   - `string`  → a BARE expression is wrapped as `${string}` (legacy DX
+ *     shorthand); a string that is already a `${…}` template is ALREADY in the
+ *     normalized shape and is returned untouched (objectui#3871, below).
  *   - `Expression` envelope `{ dialect, source }` (the normalized form
  *     `@objectstack/spec`'s `ExpressionInputSchema` produces for every
  *     authored predicate, including bare strings) → a `cel` dialect keeps
@@ -73,8 +75,54 @@ export type EvaluatorPredicateInput = string | boolean | {
  * site. `@object-ui/react`'s `toPredicateInput` is a re-export of this function
  * (since #3367; it used to be an independent twin held in step by a 14-shape
  * normalization parity table, which is exactly the arrangement the paragraph
- * above describes the failure mode of). What pins that now is the identity
- * assertion in
+ * above describes the failure mode of).
+ *
+ * ## Why an already-`${…}` string is NOT wrapped again (objectui#3871)
+ *
+ * `${…}` is one of the spellings this repo documents for a predicate
+ * (AGENTS.md §4: `hidden?: string; // expression: "${data.role != 'admin'}"`)
+ * AND one of the shapes {@link EvaluatorPredicateInput} lists as a normalized
+ * OUTPUT. Wrapping unconditionally therefore corrupted every value that was
+ * already normalized: `'${x}'` became `'${${x}}'`, which no longer matches
+ * `ExpressionEvaluator`'s single-template fast path (`/^\$\{([^}]+)\}$/` —
+ * `[^}]+` cannot cross the inner `}`), so it fell to the global replace, whose
+ * inner expression `'${x'` does not parse. The verdict then stopped depending
+ * on the predicate at all, in a direction set by the CALLER's error policy:
+ *
+ *   - fail-soft callers (every `disabled` / `enabled` leg, and the `visible`
+ *     legs of `action:group` / `action:icon` / `RelatedList`) got the original
+ *     non-empty string back from the evaluator's `catch { return match }`, so
+ *     `Boolean(…)` was a constant `true` — `disabled` greyed out forever,
+ *     `visible` shown forever, `enabled` never disabling.
+ *   - fail-closed callers (`throwOnError: true` — `action:button` / `action:bar`
+ *     / `action:menu` / `DeclaredActionsBar` `visible`, and
+ *     `ActionEngine.getActionsForLocation`) got a THROW, so the constant was
+ *     the other one: the action was hidden forever, including when its
+ *     predicate held.
+ *
+ * Either way the author's expression was never consulted. The guard is
+ * `includes('${')` — "does this string already carry template syntax", the
+ * same question `evaluateCondition` itself asks before choosing the template
+ * path — not an anchored full match: a multi-part string like `'a ${x} b'` is
+ * not a predicate in any spelling, and wrapping it produced the same constant
+ * verdict, so the narrower guard would buy nothing and would still corrupt a
+ * value the evaluator can read.
+ *
+ * The same guard covers the envelope branch below, where the unwrapped
+ * `source` reaches the identical wrap one line later. It is one defect with two
+ * spellings, and `{ dialect: 'template', source: '${x}' }` is the shape a
+ * producer that compiles an authored template emits. A bare `source` (what
+ * `@objectstack/spec`'s `ExpressionInputSchema` produces today, pinned in
+ * `packages/react/src/hooks/__tests__/useExpression.test.ts`) is unaffected.
+ *
+ * What this does NOT do is decide whether `${…}` SHOULD be authorable on an
+ * action predicate: `@objectstack/spec`'s `PredicateInput` models a bare string
+ * and a dialect envelope, not the template spelling. Rejecting it loudly at
+ * publish time is a spec-side ruling (deferred to the objectstack seat by the
+ * objectui#3871 dispatch); until then this normalizer must not silently invent
+ * a verdict for a spelling both the docs and this file's own output type bless.
+ *
+ * What pins the single implementation is the identity assertion in
  * `packages/react/src/hooks/__tests__/actionPredicate.parity.test.tsx` — the
  * react export must BE this function object — alongside the engine-path vs
  * renderer-path verdict parity suite in the same file, which is a separate

package/dist/evaluator/predicateInput.js

@@ -5,6 +5,15 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/**
+ * Wrap a BARE expression as a `${…}` template, and leave a string that already
+ * carries template syntax alone (objectui#3871 — rationale in
+ * {@link toPredicateInput}'s doc below). One rule, so the two string spellings
+ * inside the normalizer cannot drift apart.
+ */
+function wrapIfBare(expression) {
+    return expression.includes('${') ? expression : `\${${expression}}`;
+}
 /**
  * Normalize a schema-supplied predicate (`visible` / `enabled` / `disabled` /
  * `hidden`) into the form {@link ExpressionEvaluator.evaluateCondition}
@@ -12,7 +21,9 @@
  *
  * Accepts:
  *   - `boolean` → returned as-is (predicate evaluation short-circuits).
- *   - `string`  → wrapped as `${string}` (legacy DX shorthand).
+ *   - `string`  → a BARE expression is wrapped as `${string}` (legacy DX
+ *     shorthand); a string that is already a `${…}` template is ALREADY in the
+ *     normalized shape and is returned untouched (objectui#3871, below).
  *   - `Expression` envelope `{ dialect, source }` (the normalized form
  *     `@objectstack/spec`'s `ExpressionInputSchema` produces for every
  *     authored predicate, including bare strings) → a `cel` dialect keeps
@@ -41,8 +52,54 @@
  * site. `@object-ui/react`'s `toPredicateInput` is a re-export of this function
  * (since #3367; it used to be an independent twin held in step by a 14-shape
  * normalization parity table, which is exactly the arrangement the paragraph
- * above describes the failure mode of). What pins that now is the identity
- * assertion in
+ * above describes the failure mode of).
+ *
+ * ## Why an already-`${…}` string is NOT wrapped again (objectui#3871)
+ *
+ * `${…}` is one of the spellings this repo documents for a predicate
+ * (AGENTS.md §4: `hidden?: string; // expression: "${data.role != 'admin'}"`)
+ * AND one of the shapes {@link EvaluatorPredicateInput} lists as a normalized
+ * OUTPUT. Wrapping unconditionally therefore corrupted every value that was
+ * already normalized: `'${x}'` became `'${${x}}'`, which no longer matches
+ * `ExpressionEvaluator`'s single-template fast path (`/^\$\{([^}]+)\}$/` —
+ * `[^}]+` cannot cross the inner `}`), so it fell to the global replace, whose
+ * inner expression `'${x'` does not parse. The verdict then stopped depending
+ * on the predicate at all, in a direction set by the CALLER's error policy:
+ *
+ *   - fail-soft callers (every `disabled` / `enabled` leg, and the `visible`
+ *     legs of `action:group` / `action:icon` / `RelatedList`) got the original
+ *     non-empty string back from the evaluator's `catch { return match }`, so
+ *     `Boolean(…)` was a constant `true` — `disabled` greyed out forever,
+ *     `visible` shown forever, `enabled` never disabling.
+ *   - fail-closed callers (`throwOnError: true` — `action:button` / `action:bar`
+ *     / `action:menu` / `DeclaredActionsBar` `visible`, and
+ *     `ActionEngine.getActionsForLocation`) got a THROW, so the constant was
+ *     the other one: the action was hidden forever, including when its
+ *     predicate held.
+ *
+ * Either way the author's expression was never consulted. The guard is
+ * `includes('${')` — "does this string already carry template syntax", the
+ * same question `evaluateCondition` itself asks before choosing the template
+ * path — not an anchored full match: a multi-part string like `'a ${x} b'` is
+ * not a predicate in any spelling, and wrapping it produced the same constant
+ * verdict, so the narrower guard would buy nothing and would still corrupt a
+ * value the evaluator can read.
+ *
+ * The same guard covers the envelope branch below, where the unwrapped
+ * `source` reaches the identical wrap one line later. It is one defect with two
+ * spellings, and `{ dialect: 'template', source: '${x}' }` is the shape a
+ * producer that compiles an authored template emits. A bare `source` (what
+ * `@objectstack/spec`'s `ExpressionInputSchema` produces today, pinned in
+ * `packages/react/src/hooks/__tests__/useExpression.test.ts`) is unaffected.
+ *
+ * What this does NOT do is decide whether `${…}` SHOULD be authorable on an
+ * action predicate: `@objectstack/spec`'s `PredicateInput` models a bare string
+ * and a dialect envelope, not the template spelling. Rejecting it loudly at
+ * publish time is a spec-side ruling (deferred to the objectstack seat by the
+ * objectui#3871 dispatch); until then this normalizer must not silently invent
+ * a verdict for a spelling both the docs and this file's own output type bless.
+ *
+ * What pins the single implementation is the identity assertion in
  * `packages/react/src/hooks/__tests__/actionPredicate.parity.test.tsx` — the
  * react export must BE this function object — alongside the engine-path vs
  * renderer-path verdict parity suite in the same file, which is a separate
@@ -55,7 +112,7 @@ export function toPredicateInput(value) {
     if (typeof value === 'boolean')
         return value;
     if (typeof value === 'string')
-        return `\${${value}}`;
+        return wrapIfBare(value);
     if (typeof value === 'object' && typeof value.source === 'string') {
         const src = value.source;
         if (!src)
@@ -66,7 +123,7 @@ export function toPredicateInput(value) {
         if (value.dialect === 'cel')
             return { dialect: 'cel', source: src };
         // Every other dialect (template / unset) keeps the legacy `${…}` behavior.
-        return `\${${src}}`;
+        return wrapIfBare(src);
     }
     return undefined;
 }

package/dist/evaluator/rowPredicateCanon.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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 canonical row-predicate root. */
+export declare const ROW_PREDICATE_CANONICAL_ROOT = "record";
+/** A non-canonical row-predicate spelling, and the edit that fixes it. */
+export type NonCanonicalRowSpelling = {
+    /** Bare shorthand: `status == 'active'` — a field of THIS row, unrooted. */
+    kind: 'bare-shorthand';
+    /** The offending identifier (`status`). */
+    identifier: string;
+    /** What the author should write instead (`record.status`). */
+    canonical: string;
+} | {
+    /** Wrong-layer root: `data.status == 'active'` on a runtime record surface. */
+    kind: 'metadata-layer-root';
+    identifier: string;
+    canonical: string;
+};
+/**
+ * Detect a non-canonical spelling in ONE row predicate, or `null` when the
+ * predicate is already canonical (or is not this module's verdict to give).
+ *
+ * Deliberately conservative in both arms — every condition below can only
+ * REMOVE a finding, never invent one, because a false deprecation warning sends
+ * an author to rewrite a predicate that was correct:
+ *
+ * - **Unparseable source** → `null`. Syntax is another gate's verdict.
+ * - **Bare shorthand** is reported only when the undeclared identifier is an own
+ *   key of THIS row. That is what makes it unambiguously the #4075 shorthand
+ *   rather than a host-scope global this module cannot see (a deployment key
+ *   that is simply not in `SCOPE_ROOTS` would otherwise read as a bare field).
+ * - **`data.*`** is reported only when the caller confirms `data` names the row
+ *   (`dataNamesRow`). A surface whose `data` is the host scope's own — a
+ *   `rowless` dialog, a metadata-editing form — is a legitimate `data.*` site
+ *   and is left alone.
+ *
+ * Only the FIRST finding is returned, and the bare-shorthand arm is checked
+ * first: it is the arm the server refuses outright (`visibility-bare-identifier`
+ * is an `error` there, while a mis-layered root is a `warning`), so when a
+ * predicate manages both it is the one the author must fix to have anything
+ * evaluate at all.
+ *
+ * @param source       The predicate's CEL text. Callers must have already
+ *                     routed legacy `${…}`-dialect strings elsewhere — in that
+ *                     dialect `data.*` is the NORMAL spelling, and reporting it
+ *                     here would be a false positive on every legacy predicate.
+ * @param row          The row the predicate is bound against.
+ * @param dataNamesRow Whether `data` is bound to that same row on this surface.
+ */
+export declare function detectNonCanonicalRowSpelling(source: string, row: Record<string, unknown> | null | undefined, dataNamesRow: boolean): NonCanonicalRowSpelling | null;
+/** Reset the row-predicate spelling warn-once memo. Exported for tests. */
+export declare function resetRowPredicateCanonWarnings(): void;
+/**
+ * Report a non-canonical row-predicate spelling once, in dev.
+ *
+ * Phase 1 of the objectui#5330 window: the binding is UNCHANGED and every
+ * spelling still resolves — this only says so out loud, so the stored
+ * population stops growing and a later survey has something to count. It is a
+ * warning and deliberately not a refusal: turning it into one would move the
+ * accept/reject set, which this card is explicitly not entitled to do.
+ */
+export declare function warnNonCanonicalRowSpelling(source: string, row: Record<string, unknown> | null | undefined, dataNamesRow: boolean, label?: string): void;