@object-ui/core 17.6.0 → 17.7.0

package/dist/evaluator/listConditional.d.ts

@@ -44,8 +44,10 @@ 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. The row wins on
-     * collision: a `record` or `data` key here never shadows the row. */
+     * scope (`features` / `user`) a host shell provides. The row wins on
+     * collision: a `record` key here never shadows the row. Every OTHER key —
+     * a host's own `data` included — reaches the predicate as the host's own
+     * (`83fe6e741`: `data` no longer names the row on a record surface). */
     scope?: Record<string, unknown>;
     /** When true, log a one-time warning if a *present* predicate faults. */
     warnOnError?: boolean;
@@ -53,16 +55,16 @@ export interface RowPredicateOptions {
     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).
+     * of binding an empty one, so a `record` 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
+     * pinned over the scope as `record`, on both dialect paths, so `record`
+     * always names THIS row even when the host scope carries a key of that name
      * (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
+     * `record` over the host's real one 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
@@ -86,38 +88,105 @@ 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`, 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).
+ * 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 declare function evalRowPredicate(pred: FieldRulePredicate | undefined | null, row: Record<string, unknown> | null | undefined, opts?: RowPredicateOptions): boolean;
+/** The two halves of a {@link partitionRowsByPredicate} verdict over a selection. */
+export interface RowPartition<TRow> {
+    /** Records whose predicate passed — the ones an operation may act on. */
+    eligible: TRow[];
+    /**
+     * How many records were filtered out. A caller that shrinks a user's
+     * selection owes them this number: a run over fewer records than they picked
+     * must say so rather than quietly shrinking.
+     */
+    skipped: number;
+}
+/**
+ * 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 declare function partitionRowsByPredicate<TRow extends Record<string, unknown>>(pred: FieldRulePredicate | boolean | undefined | null, rows: readonly TRow[], opts?: Omit<RowPredicateOptions, 'fallback' | 'rowless'>): RowPartition<TRow>;
 /** A conditional-formatting rule in any of the three historical shapes. */
 export type ConditionalFormattingRuleLike = {
     /** Spec shape: a CEL predicate (`ExpressionInputSchema`). */

package/dist/evaluator/listConditional.js

@@ -36,7 +36,6 @@
 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
@@ -119,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;
@@ -135,32 +134,37 @@ 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`, bare `status` (row-action shorthand), and `data.status`.
+ * 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`).
  *
- * ⚠️ 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).
+ * 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.
  *
- * ⛔ 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 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` and `data` always name THIS row, on both dialect paths,
- * even when the host scope carries keys of those names (objectui#3796).
+ * 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
@@ -170,9 +174,16 @@ 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.
@@ -180,24 +191,26 @@ export function evalRowPredicate(pred, row, opts = {}) {
     const rowObj = opts.rowless
         ? {}
         : toPredicateRecord(row && typeof row === 'object' ? row : {}, opts.fields);
-    // Bare fields + `data.*` + `record.*` + the host scope, all top-level.
+    // `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.
     //
     // …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.
+    // to pin and the host scope keeps its own `record` — see the option.
     const scope = opts.rowless
         ? { ...(opts.scope ?? {}) }
-        : { ...(opts.scope ?? {}), ...rowObj, data: rowObj, record: rowObj };
+        : { ...(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
@@ -231,19 +244,17 @@ export function evalRowPredicate(pred, row, opts = {}) {
             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
+    // 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) {
@@ -256,6 +267,72 @@ export function evalRowPredicate(pred, row, opts = {}) {
     }
     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
@@ -132,12 +194,21 @@ export declare function resolveCascadingOptions<T extends OptionLike>(rawOptions
  *
  * `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.
+ * 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
  *