@object-ui/core 17.5.0 → 17.7.0

package/dist/evaluator/listConditional.js

@@ -62,7 +62,14 @@ function warnLegacyDialect(source) {
 }
 const warnedError = new Set();
 /**
- * One-time fail-closed report for a predicate that could not be evaluated.
+ * 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
@@ -111,7 +118,7 @@ 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). `onFault` carries the engine's reason across that silence
+    // not two (objectstack-ai/objectstack#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;
@@ -127,38 +134,99 @@ function evalCel(pred, record, scope) {
 }
 /**
  * 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 — 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).
+ * engine (with a legacy-dialect fallback — see the module note). The row is
+ * bound ONE way: as `record.*` — **the canon** (maintainer ruling 2026-08-20 on
+ * objectui#5330, option B; Phase 2 executed by `83fe6e741`).
+ *
+ * Until Phase 2 the row was also bound as bare fields (`status`, the row-action
+ * shorthand) and as `data.*`, and Phase 1 (`d1ab06f0f`) warned once per
+ * non-canonical spelling. Both bindings and that warning are gone. A bare-field
+ * or `data.*` predicate on a record surface now FAULTS here exactly as it always
+ * did on the server — measured on `@objectstack/formula@17.1.0`,
+ * `buildScope({ record })` mounts exactly `['record']`, so a bare field faults
+ * `Unknown variable: status` and `data.*` faults `Unknown variable: data` — and
+ * takes this function's EXISTING fault policy: the caller's `fallback`, reported
+ * once by `warnEvalError` (when `warnOnError` is set) or by the canonical
+ * helper's own one-time warning, either of which names the unknown variable.
+ * Nothing detects a retired spelling on this path; it is simply unbound. The
+ * same holds on the legacy `${…}` path below — one scope shape per surface,
+ * both dialects — so `${data.x}` / `${x}` strings on a row surface fault there
+ * too, and land in the same fallback / warning.
+ *
+ * The retirement is scoped to the RUNTIME RECORD layer. `data` is the canonical
+ * root one layer over, in a metadata-editing form (ADR-0089 D3,
+ * `CANONICAL_ROOT_BY_LAYER` = `{ runtime: 'record', metadata: 'data' }`), and
+ * that layer evaluates through its own entry (`app-shell`'s metadata-admin
+ * `predicate.ts`), never through this one. See {@link ./rowPredicateCanon.ts}
+ * for the canon statement, the server measurement and the offline detector.
+ *
+ * The optional `scope` (host predicate scope) is bound alongside so
+ * `features.*` / `user.*` predicates keep working — but the row is the subject:
+ * `record` always names THIS row, on both dialect paths, even when the host
+ * scope carries a key of that name (objectui#3796). Every OTHER host key —
+ * a host's own `data` included — reaches the predicate as the host's own.
+ *
+ * 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;
     if (pred == null)
         return fallback;
+    // A BLANK predicate is not answered here. It used to be, for the bare-string
+    // spelling only: `''` / whitespace returned the fallback on this line, in
+    // silence, while a blank ENVELOPE went on to `evalFieldPredicate`'s `[blank]`
+    // report below (objectui#11262, ADR-0137 D4: a blank gate predicate is
+    // "diagnosed, never a silent `true`"). Both spellings now take that one
+    // route: no legacy marker can match blank text, so a blank string reaches
+    // the CEL path like its envelope twin and gets the same verdict — the
+    // caller's fallback — and the same report, labelled on the fail-closed route
+    // and by the canonical helper on the single-eval one.
     const source = typeof pred === 'string' ? pred : undefined;
-    if (source !== undefined && !source.trim())
-        return fallback;
     // 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.*` + `record.*` + the host scope, all top-level.
+    // 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);
+    // `record.*` + the host scope, all top-level. The row is bound ONE way
+    // (`83fe6e741`, Phase 2 of the objectui#5330 canon): no bare-field spread
+    // and no `data` — a predicate spelled either way is simply unbound here and
+    // faults, on both dialect paths, exactly as it does on the server.
     //
-    // `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,
+    // `record` is pinned AFTER the spread, so a host scope that happens to carry
+    // that key is background and the ROW stays the subject of this function — on
+    // BOTH dialect paths. Before objectui#3796 it 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. Pinning here fixes both paths at the merge,
     // independently of either engine's precedence.
-    const scope = { ...(opts.scope ?? {}), ...rowObj, data: rowObj, record: rowObj };
+    //
+    // …UNLESS the caller has no row (`rowless`), in which case there is nothing
+    // to pin and the host scope keeps its own `record` — see the option.
+    const scope = opts.rowless
+        ? { ...(opts.scope ?? {}) }
+        : { ...(opts.scope ?? {}), 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)) {
@@ -176,10 +244,17 @@ export function evalRowPredicate(pred, row, opts = {}) {
             return fallback;
         }
     }
-    // CEL path. The fault-aware `evalCel` costs two evaluations (to tell a fault
+    // CEL path — everything reaching here is CEL. No spelling detector runs here
+    // (`83fe6e741` removed the Phase-1 warning with the bindings): a retired
+    // bare-field / `data.*` spelling is unbound above and faults in the engine
+    // like any other unknown variable, and the fault report below is what names
+    // it. `detectNonCanonicalRowSpelling` stays exported for OFFLINE sweeps of
+    // authored metadata, not for this hot 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
-    // route. Since #5149 the fast route is no longer silent either: the
+    // route. Since objectstack-ai/objectstack#5149 the fast route is no longer silent either: the
     // canonical helper itself warns once per broken predicate (with `opts.label`
     // as the locator when given).
     if (!opts.warnOnError) {
@@ -187,11 +262,77 @@ export function evalRowPredicate(pred, row, opts = {}) {
     }
     const verdict = evalCel(pred, rowObj, scope);
     if (!verdict.ok) {
-        warnEvalError(source ?? '(expression)', opts.label, verdict.reason);
+        warnEvalError(predicateText, opts.label, verdict.reason);
         return fallback;
     }
     return verdict.value;
 }
+/**
+ * Split a set of records by one per-record predicate — the SET-shaped
+ * counterpart of {@link evalRowPredicate}, and the reason a bulk gate never
+ * needs a hook.
+ *
+ * A bulk affordance spans N records, so its gate is a **loop**, and React
+ * forbids calling `useRowPredicate` (or any hook) per iteration. Every bulk
+ * surface therefore reaches for `evalRowPredicate` directly; this wrapper is
+ * that loop written once, with the three cases each caller was otherwise
+ * re-deriving:
+ *
+ *   - **absent** (`null` / `undefined` / `''`) — nothing is gated, so `rows` is
+ *     returned BY REFERENCE and `skipped` is 0. The common case allocates
+ *     nothing and a caller's downstream memo still holds. Whitespace-only text
+ *     and an envelope whose `source` is blank are NOT absent here: they are
+ *     evaluated, and fail closed like any other predicate that cannot run.
+ *   - **boolean** — a verdict, not an expression, short-circuited exactly as
+ *     `useCondition` / `useRowPredicate` do. Handing `true` to the engine
+ *     produces `{ dialect: 'cel', source: undefined }`, which faults and — on
+ *     this fail-closed path — would disqualify every record, so the most
+ *     explicit way to say "always" would exclude everyone (objectui#3492).
+ *   - **expression** — evaluated once per record with that record in scope,
+ *     **fail-closed**: a predicate that faults must not hand the caller records
+ *     it was written to exclude. `warnOnError` (default `true`) makes the
+ *     resulting exclusion diagnosable once per predicate instead of silent.
+ *
+ * The fail-closed default is what separates this from a lenient record-free
+ * evaluation, and the difference is not mere strictness: evaluated with NO
+ * record bound, `record.status != 'paid'` returns `true` for every row —
+ * including the ones it was written to exclude — so an authored gate is not
+ * weakened, it is inverted for half its inputs (objectui#3067).
+ *
+ * ## Who calls it, and who decides "is a gate declared?" (objectui#11322)
+ *
+ * This is a shared partitioner, and its opening test is not the action
+ * family's "is a gate declared?" question. Its callers:
+ *
+ *   - the bulk ACTION fold, plugin-grid's `partitionBulkRows` (a bulk def's
+ *     `visible`). The action family decides "declared?" BEFORE calling here,
+ *     through `hasDeclaredVisibilityGate`, and hands an undeclared gate over as
+ *     `undefined`. So a whitespace-only `visible` or a blank-`source` envelope
+ *     never reaches the test below from that caller.
+ *   - the built-in Delete's `userActions.delete.visibleWhen`, a field-rule key,
+ *     from plugin-grid's `ObjectGrid` and from plugin-list's `ListView`
+ *     (`bulkDeleteEligibility`). The test below is THEIR answer: a blank one
+ *     that is not `''` is evaluated and excludes every record.
+ *
+ * A caller that needs the action family's answer asks it first; it does not
+ * write a second blank test in front of this one.
+ */
+export function partitionRowsByPredicate(pred, rows, opts = {}) {
+    if (pred == null || pred === '') {
+        return { eligible: rows, skipped: 0 };
+    }
+    if (typeof pred === 'boolean') {
+        return pred
+            ? { eligible: rows, skipped: 0 }
+            : { eligible: [], skipped: rows.length };
+    }
+    const eligible = rows.filter(row => evalRowPredicate(pred, row, {
+        ...opts,
+        warnOnError: opts.warnOnError ?? true,
+        fallback: false,
+    }));
+    return { eligible, skipped: rows.length - eligible.length };
+}
 /** Serialize a JS value as a CEL literal (string / number / bool / list / null). */
 function celLiteral(v) {
     if (v === null || v === undefined)

package/dist/evaluator/optionRules.d.ts

@@ -69,6 +69,68 @@ export declare function isOptionGroupGated(dependsOn: DependsOnInput, record: Re
  * no predicate are always kept; a predicate that errors fails open (kept).
  */
 export declare function resolveVisibleOptions<T extends OptionLike>(options: readonly T[] | undefined | null, record: Record<string, unknown>, scope?: Record<string, unknown>): T[];
+/**
+ * The text an option widget SHOWS for one option: its `label`, or its `value`
+ * when the label is blank (`20b507aff`).
+ *
+ * ## Why a blank label reaches a renderer at all — it is a LEGAL document
+ *
+ * This is deliberately NOT the lenient renderer fallback AGENTS.md #0.1
+ * forbids. That rule governs metadata the contract REFUSES ("if the metadata
+ * is off-spec, fix it at the producer"); an empty label is metadata the
+ * contract ACCEPTS. Measured on the installed `@objectstack/spec` 17.6.0,
+ * `SelectOptionSchema`:
+ *
+ *   { value: 'low', label: 'Low' } -> ACCEPT   (lit control)
+ *   { value: 'low', label: '' }    -> ACCEPT   <- the key reading
+ *   { value: 'low' }               -> REJECT invalid_type at [label]
+ *
+ * `@object-ui/types` mirrors that reading in prose on `SelectOptionBase`:
+ * "An empty string is a valid label; an ABSENT one is not." So the producer
+ * is right to emit `label: ''` — the field designer's `patchOptions` does,
+ * under the ruling `f0f774b0d` landed, and a pin
+ * (`ObjectFieldInspector.optionLabel.test.tsx`) fails if it ever invents
+ * content to fill the hole instead. A document every layer calls legal has to
+ * render as something a person can click.
+ *
+ * ## What the contract does NOT say, and who had already answered it
+ *
+ * The spec states no display default for a legal-but-blank label, so nothing
+ * upstream decides this. objectui had nevertheless already decided it — on
+ * HALF its read sites. Measured across the four option widgets before this
+ * helper existed, with `{ value: 'low', label: '' }` authored and
+ * `{ value: 'high', label: 'High' }` beside it as the lit control:
+ *
+ *   | widget      | readonly path      | interactive path |
+ *   | select      | "low"              | ""               |
+ *   | multiselect | "low"              | ""               |
+ *   | radio       | "low"              | ""               |
+ *   | checkboxes  | "low"              | ""               |
+ *
+ * Four summary paths spelled `opt?.label || value` and fell back; the four
+ * interactive paths spelled `{opt.label}` and rendered nothing. So the same
+ * option read "low" in a read-only form and blank in the editable one — the
+ * bug was never "tolerate or refuse", it was a widget family disagreeing with
+ * itself, and the blank half is the one a person has to click.
+ *
+ * This function is that decision written ONCE, the same "one definition, N
+ * surfaces" move as {@link CASCADE_OPTION_WIDGET_TYPES} below. All eight sites
+ * call it, so the two halves cannot drift apart again.
+ *
+ * ## Boundaries
+ *
+ * - Blank means TRIM-empty, so a whitespace-only label falls back too: it is
+ *   the same invisible row to the person looking at it, and it is the
+ *   spelling the producer's own reader already uses to call an authored
+ *   `value` blank (`classifyOption`, `o.value.trim() === ''`).
+ * - `label` is typed required, but this reads defensively because renderers
+ *   are handed unvalidated runtime metadata: a non-string label must fall back
+ *   rather than throw where `{opt.label}` merely rendered nothing.
+ * - This changes DISPLAY only. It writes nothing, and it is not a licence to
+ *   author blank labels — whether the contract should refuse them outright is
+ *   a `packages/spec` question, not a renderer one.
+ */
+export declare function optionDisplayLabel(option: OptionLike): string;
 /**
  * Whether a scalar field value is still valid given the currently-visible
  * options — used to decide a cascade clear (parent changed, child's old choice
@@ -97,3 +159,67 @@ 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 —
+ * neither of which is an option list, so ⛔ no member is ever added to THIS set
+ * to serve them. Each surface decides that separately, by OR-ing its own rule
+ * beside this one, and they do not agree:
+ *
+ * - the object form has fed both families all along — `needsDataSourceWiring`,
+ *   its own line beside the one that reads this set;
+ * - the single-record action dialog feeds the lookup family since
+ *   objectui#8672 ruling A — `paramNeedsDependentValues()`, same shape;
+ * - the bulk action dialog feeds neither, and nothing has ruled on it.
+ *
+ * ⇒ objectui#4771 is the open boundary for the widget-hint pickers everywhere,
+ * and for the lookup family on the bulk dialog. Stated here so the surfaces'
+ * copies of the statement become one; ⛔ do not read a member of this set as
+ * the answer to "does widget X get the record on surface Y".
+ *
+ * ## 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

@@ -6,6 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { evalFieldPredicate } from './fieldRules.js';
+import { isEmptyValue } from '../utils/emptiness.js';
 /**
  * Normalize a field's `dependsOn` to the list of sibling field names it reacts
  * to. The lookup-only `{field,param}` form contributes just its `field`.
@@ -18,10 +19,12 @@ export function resolveDependsOnFields(dependsOn) {
         .map((d) => (typeof d === 'string' ? d : d && typeof d === 'object' ? d.field : null))
         .filter((f) => typeof f === 'string' && f.length > 0);
 }
-/** A value counts as "empty" (dependency unmet) when nullish, blank, or an empty array. */
-function isEmptyValue(v) {
-    return v === undefined || v === null || v === '' || (Array.isArray(v) && v.length === 0);
-}
+// A dependency counts as UNMET on exactly the shared floor — `null`,
+// `undefined`, the empty string, the empty array — and this module is where
+// those four members were first written down. objectui#8496 promoted them out
+// of here into `utils/emptiness.ts` (byte-for-byte the same four) so the four
+// other surfaces that had each re-spelled them could stop. No extension and no
+// declension: a gated option list asks the floor and nothing more.
 /**
  * True when at least one `dependsOn` field is empty in the record — the option
  * list is gated and the widget should prompt for the parent rather than show an
@@ -45,6 +48,71 @@ export function resolveVisibleOptions(options, record, scope) {
             context: `visibleWhen of option '${String(o.value)}'`,
         }));
 }
+/**
+ * The text an option widget SHOWS for one option: its `label`, or its `value`
+ * when the label is blank (`20b507aff`).
+ *
+ * ## Why a blank label reaches a renderer at all — it is a LEGAL document
+ *
+ * This is deliberately NOT the lenient renderer fallback AGENTS.md #0.1
+ * forbids. That rule governs metadata the contract REFUSES ("if the metadata
+ * is off-spec, fix it at the producer"); an empty label is metadata the
+ * contract ACCEPTS. Measured on the installed `@objectstack/spec` 17.6.0,
+ * `SelectOptionSchema`:
+ *
+ *   { value: 'low', label: 'Low' } -> ACCEPT   (lit control)
+ *   { value: 'low', label: '' }    -> ACCEPT   <- the key reading
+ *   { value: 'low' }               -> REJECT invalid_type at [label]
+ *
+ * `@object-ui/types` mirrors that reading in prose on `SelectOptionBase`:
+ * "An empty string is a valid label; an ABSENT one is not." So the producer
+ * is right to emit `label: ''` — the field designer's `patchOptions` does,
+ * under the ruling `f0f774b0d` landed, and a pin
+ * (`ObjectFieldInspector.optionLabel.test.tsx`) fails if it ever invents
+ * content to fill the hole instead. A document every layer calls legal has to
+ * render as something a person can click.
+ *
+ * ## What the contract does NOT say, and who had already answered it
+ *
+ * The spec states no display default for a legal-but-blank label, so nothing
+ * upstream decides this. objectui had nevertheless already decided it — on
+ * HALF its read sites. Measured across the four option widgets before this
+ * helper existed, with `{ value: 'low', label: '' }` authored and
+ * `{ value: 'high', label: 'High' }` beside it as the lit control:
+ *
+ *   | widget      | readonly path      | interactive path |
+ *   | select      | "low"              | ""               |
+ *   | multiselect | "low"              | ""               |
+ *   | radio       | "low"              | ""               |
+ *   | checkboxes  | "low"              | ""               |
+ *
+ * Four summary paths spelled `opt?.label || value` and fell back; the four
+ * interactive paths spelled `{opt.label}` and rendered nothing. So the same
+ * option read "low" in a read-only form and blank in the editable one — the
+ * bug was never "tolerate or refuse", it was a widget family disagreeing with
+ * itself, and the blank half is the one a person has to click.
+ *
+ * This function is that decision written ONCE, the same "one definition, N
+ * surfaces" move as {@link CASCADE_OPTION_WIDGET_TYPES} below. All eight sites
+ * call it, so the two halves cannot drift apart again.
+ *
+ * ## Boundaries
+ *
+ * - Blank means TRIM-empty, so a whitespace-only label falls back too: it is
+ *   the same invisible row to the person looking at it, and it is the
+ *   spelling the producer's own reader already uses to call an authored
+ *   `value` blank (`classifyOption`, `o.value.trim() === ''`).
+ * - `label` is typed required, but this reads defensively because renderers
+ *   are handed unvalidated runtime metadata: a non-string label must fall back
+ *   rather than throw where `{opt.label}` merely rendered nothing.
+ * - This changes DISPLAY only. It writes nothing, and it is not a licence to
+ *   author blank labels — whether the contract should refuse them outright is
+ *   a `packages/spec` question, not a renderer one.
+ */
+export function optionDisplayLabel(option) {
+    const { label } = option;
+    return typeof label === 'string' && label.trim() !== '' ? label : String(option.value);
+}
 /**
  * Whether a scalar field value is still valid given the currently-visible
  * options — used to decide a cascade clear (parent changed, child's old choice
@@ -77,3 +145,72 @@ 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 —
+ * neither of which is an option list, so ⛔ no member is ever added to THIS set
+ * to serve them. Each surface decides that separately, by OR-ing its own rule
+ * beside this one, and they do not agree:
+ *
+ * - the object form has fed both families all along — `needsDataSourceWiring`,
+ *   its own line beside the one that reads this set;
+ * - the single-record action dialog feeds the lookup family since
+ *   objectui#8672 ruling A — `paramNeedsDependentValues()`, same shape;
+ * - the bulk action dialog feeds neither, and nothing has ruled on it.
+ *
+ * ⇒ objectui#4771 is the open boundary for the widget-hint pickers everywhere,
+ * and for the lookup family on the bulk dialog. Stated here so the surfaces'
+ * copies of the statement become one; ⛔ do not read a member of this set as
+ * the answer to "does widget X get the record on surface Y".
+ *
+ * ## 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

@@ -9,7 +9,9 @@
  * The normalized shape {@link ExpressionEvaluator.evaluateCondition} consumes:
  * a boolean (short-circuits), a `${…}` template string (legacy JS path), a
  * `{ dialect: 'cel', source }` envelope (canonical `@objectstack/formula`
- * path), or `undefined` for "no predicate declared".
+ * path), `undefined` for "no predicate declared", or a `cel` envelope with NO
+ * `source` for a gate that is declared but cannot be evaluated — which the
+ * evaluator treats as a fault, never as "absent" (objectui#11358).
  *
  * ## Why not `PredicateInput` (objectstack#4115 / objectui#3074)
  *
@@ -24,7 +26,8 @@
  * admits `boolean` and the `${…}` template spelling (neither of which the spec
  * models as a predicate), narrows `dialect` to `cel` alone (every other dialect
  * has already been flattened onto the legacy path by `toPredicateInput`),
- * requires a non-empty `source`, and carries no `ast` / `meta`. The two unions
+ * requires a non-empty `source` (or none at all, for the declared-but-
+ * unevaluable state), and carries no `ast` / `meta`. The two unions
  * are not mutually assignable in either direction.
  *
  * The rename is pinned from both sides by the tripwire in
@@ -36,6 +39,9 @@
 export type EvaluatorPredicateInput = string | boolean | {
     dialect: 'cel';
     source: string;
+} | {
+    readonly dialect: 'cel';
+    readonly source?: undefined;
 } | undefined;
 /**
  * Normalize a schema-supplied predicate (`visible` / `enabled` / `disabled` /
@@ -52,8 +58,13 @@ export type EvaluatorPredicateInput = string | boolean | {
  *     authored predicate, including bare strings) → a `cel` dialect keeps
  *     its envelope; every other dialect is unwrapped and wrapped as
  *     `${source}`.
- *   - `null` / `undefined` / empty / anything else → `undefined`
- *     (default visible/enabled).
+ *   - `null` / `undefined` / `''` / an envelope whose `source` is `''` →
+ *     `undefined` (absent: default visible/enabled).
+ *   - anything else that is present — an envelope with no string `source`
+ *     (`{ dialect: 'cel', ast }`), a number, `{}`, an array → the frozen
+ *     `{ dialect: 'cel' }` with no `source`: declared, and a FAULT to the
+ *     evaluator (objectui#11358 — see `DECLARED_UNEVALUABLE` above). This used
+ *     to fold into `undefined` with the absent shapes.
  *
  * ## Why the `cel` envelope must survive normalization (#2661 / #3314)
  *