@object-ui/core 17.5.0 → 17.7.0

package/dist/evaluator/fieldRules.js

@@ -34,8 +34,7 @@
  * `stripReadonlyWhenFieldsMulti` on the bulk path — DELETES that key from the
  * UPDATE payload. This file keeps the same fault fail-OPEN. For that one class
  * the two ends therefore point in OPPOSITE directions, deliberately: the
- * framework's ADR-0057 D10 — server enforces, client is courtesy (framework
- * numbering; this repo's own ADR-0057 is an unrelated document) — makes the
+ * framework's ADR-0124 D1 — server enforces, client is courtesy — makes the
  * server the authority, so the courtesy layer does not get to guess "locked"
  * and grey out a field the server might have accepted.
  *
@@ -62,8 +61,22 @@
  * logs `treating the field as LOCKED` instead). The *default* stays
  * fail-open on purpose — flipping it is a shipped-behavior change tracked
  * separately in objectstack#5149 (appeal 1, undecided).
+ *
+ * A predicate the author DECLARED and left BLANK is loud too, since
+ * objectui#8069 — and it did not used to be. It is a third state, not a
+ * spelling of either neighbour: the key is present (so it is not "no rule")
+ * and nothing evaluates (so no engine fault is raised), and it used to return
+ * the caller's permissive fallback before any warning could fire. `''` and
+ * `'   '` are authorable — `ExpressionWireSchema` is a bare `z.string()`, and
+ * `resolveFieldRuleState`'s own guard is `!= null` — so the one state an author
+ * reaches by *starting* a rule and not finishing it was the one state that said
+ * nothing at all. Both spellings now report `[blank]` through the same single
+ * site as every other fault; the VERDICT is unchanged for every input.
  */
 import { ExpressionEngine } from '@objectstack/formula';
+import { subjectPermissionsOf } from './subjectPermissions.js';
+import { isBlankPredicateText } from './declaredPredicate.js';
+import { isUnevaluablePredicate, UNEVALUABLE_PREDICATE_REASON } from './unevaluablePredicate.js';
 /** Normalize a predicate into the `Expression` shape the engine expects. */
 function toExpression(pred) {
     if (typeof pred === 'string')
@@ -71,15 +84,35 @@ function toExpression(pred) {
     return { dialect: (pred.dialect ?? 'cel'), source: pred.source };
 }
 const warnedPredicates = new Set();
+/**
+ * The `reason` reported for a predicate the author DECLARED and left blank.
+ *
+ * Tagged like an engine reason (`[parse]`, `[type]`, `[throw]`) because it
+ * travels the same two channels — the built-in warning and the `onFault`
+ * passback — and a caller that routes on the tag must be able to tell this
+ * apart from a predicate that faulted with text in it: the fix for a blank one
+ * is to finish it or delete the key, never to debug its syntax.
+ */
+const BLANK_PREDICATE_REASON = '[blank] the predicate is declared but empty — nothing to evaluate';
 /**
  * One-time warning for a predicate that could not be evaluated. Deduped per
  * predicate TEXT (dialect + source): a broken predicate is re-evaluated on
  * every render/keystroke, and the point is one loud line, not a scrolling
  * wall. The dedupe key is JSON-encoded — never a control-character separator
  * (objectstack#5450 made a sibling of this file binary to grep that way).
+ *
+ * ⚠️ One class joins the LOCATOR to that key: a BLANK predicate. The text is
+ * what identifies the authoring site for every other fault — it carries the
+ * typo — but every blank predicate in an app shares the key `""`, so text
+ * alone would let the first blank rule silence every other author's. Non-blank
+ * keys are unchanged (objectui#8069).
  */
 function warnPredicateFailure(expr, fallback, reason, context) {
-    const key = JSON.stringify([expr.dialect, expr.source]);
+    // `Expression['source']` is optional in the spec; an absent source is blank
+    // by the same rule as a whitespace-only one, and lands in the same key shape.
+    const key = expr.source?.trim()
+        ? JSON.stringify([expr.dialect, expr.source])
+        : JSON.stringify([expr.dialect, expr.source, context ?? '']);
     if (warnedPredicates.has(key))
         return;
     warnedPredicates.add(key);
@@ -93,12 +126,54 @@ function warnPredicateFailure(expr, fallback, reason, context) {
 /**
  * Evaluate a field-rule CEL predicate against a record.
  *
+ * ## `fallback` is a per-CALL-SITE policy, not a default this helper owns
+ *
+ * The parameter is required and carries no default value, so every call site
+ * states a direction of its own — and the directions in this repo do not
+ * agree. Five distinct fault policies share this one helper today, which is
+ * readable nowhere but here (objectui#8069):
+ *
+ * 1. **Fixed permissive, paired with an equal "no rule" literal.**
+ *    {@link resolveFieldRuleState} (`true` / `false` / `false`) and
+ *    `resolveVisibleOptions` (`evaluator/optionRules.ts`, `true`). A fault
+ *    produces the permissive verdict, indistinguishable from the verdict for
+ *    "the author wrote no rule" — see the `…_FAULTED` / `…_ABSENT` note below.
+ * 2. **Fixed permissive, unguarded — ONE literal answers absent *and*
+ *    faulted.** Every visibility call site outside core: the form renderer
+ *    (`components/renderers/form/form.tsx`), console's `FormPage`, app-shell's
+ *    `ScreenView`, `plugin-form`'s `WizardForm`. All of them pass `true`, and
+ *    none has a separate absent branch at all.
+ * 3. **Caller-parameterised.** `evalRowPredicate`'s single-eval fast route
+ *    (`evaluator/listConditional.ts`) forwards `opts.fallback`, so the
+ *    direction is the mounting surface's to state.
+ * 4. **Divergence probe → fault FLAG.** `evalCel`
+ *    (`evaluator/listConditional.ts`) calls this helper once per direction with
+ *    `warn: false` + `onFault`: a verdict that tracks the fallback in BOTH runs
+ *    is a fault, and the caller emits its own labelled warning and returns its
+ *    own fallback.
+ * 5. **Divergence probe → THROW.** `ExpressionEvaluator.evaluateCelCondition`
+ *    under `throwOnError` runs the same two-call trick and converts the
+ *    disagreement into `throw new Error('CEL predicate failed to evaluate: …')`.
+ *
+ * ⚠️ The last two policies exist **because** `fallback` is free to specify: they
+ * detect a fault by disagreeing with themselves. Fixing a direction *inside*
+ * this helper would remove the mechanism they are built on, which is why
+ * ADR-0137 D5 keeps `fallback` free and declares the direction at the
+ * field-rule and gate layer instead.
+ *
  * @param pred      The `visibleWhen` / `readonlyWhen` / `requiredWhen` predicate.
  * @param record    The live form values (overlays prior persisted record).
- * @param fallback  Value to return when the predicate is absent or fails to
- *                  evaluate. Pick the *safe* default for the caller:
- *                  `false` for readonly/required (don't lock/block on error),
- *                  `true` for visibility (don't hide on error).
+ * @param fallback  Value to return when the predicate is ABSENT (`null` /
+ *                  `undefined`), and — separately — the value returned when a
+ *                  present predicate cannot be evaluated. ⚠️ Those are two
+ *                  questions this one parameter answers with one value; a
+ *                  caller that wants different answers must branch before the
+ *                  call, as {@link resolveFieldRuleState} does. The historic
+ *                  advice is to pick the *safe* default (`false` for
+ *                  readonly/required — don't lock/block on error; `true` for
+ *                  visibility — don't hide on error). ADR-0137 kept those
+ *                  directions for RENDER (D3) and put the answer to a broken
+ *                  field rule at SUBMIT (D2) — see {@link FieldRuleFaults}.
  * @param previous  The prior persisted record, if any (for `previous.*` refs).
  * @param scope     Extra top-level scope variables bound alongside `record` —
  *                  e.g. `{ parent }` so an inline line-item cell can reference
@@ -110,30 +185,63 @@ function warnPredicateFailure(expr, fallback, reason, context) {
  *                  is unaffected either way.
  */
 export function evalFieldPredicate(pred, record, fallback, previous, scope, diagnostic) {
-    if (pred == null || (typeof pred === 'string' && !pred.trim()))
+    if (pred == null)
         return fallback;
     const expr = toExpression(pred);
-    // The two fault sources — a not-ok verdict and a throw that slipped past the
-    // engine's "never throws" contract — converge on one reason string and one
-    // reporting site below, so the built-in warning and the `onFault` passback
-    // can never describe the failure differently.
+    // The fault sources — a blank predicate, a not-ok verdict, and a throw that
+    // slipped past the engine's "never throws" contract — converge on one reason
+    // string and one reporting site below, so the built-in warning and the
+    // `onFault` passback can never describe the failure differently.
     let reason;
     let value = fallback;
-    try {
-        const res = ExpressionEngine.evaluate(expr, {
-            record,
-            previous,
-            ...(scope ? { extra: scope } : {}),
-        });
-        // Parse error, type error, unbound identifier, engine fault … — every
-        // not-ok verdict resolves to the fallback, but never silently (#5149).
-        if (!res.ok)
-            reason = `[${res.error.kind}] ${res.error.message}`;
-        else
-            value = res.value === true;
+    if (isBlankPredicateText(pred)) {
+        // Declared-and-blank, in EITHER spelling. Answered here rather than by the
+        // engine for two reasons: the bare-string spelling never reached the engine
+        // at all (this line used to `return fallback` before any warning could
+        // fire — objectui#8069), and the envelope spelling reached it and came back
+        // with `AST-only evaluation not yet supported; persist \`source\`` for
+        // `{ source: '' }`, a reason that sends the author looking for a
+        // serialization bug. `isBlankPredicateText` is the repo's one definition of
+        // this question (objectui#3960) — a fourth local `trim()` here is exactly
+        // the drift it was consolidated to stop.
+        reason = BLANK_PREDICATE_REASON;
     }
-    catch (err) {
-        reason = `[throw] ${err instanceof Error ? err.message : String(err)}`;
+    else if (isUnevaluablePredicate(pred)) {
+        // Declared, and nothing here can be evaluated: an envelope with no string
+        // `source` (an `ast`-only one), a number, `{}`, an array (objectui#11358).
+        // Answered here, beside the blank, for the blank's reasons: there is no
+        // `source` to hand the engine, and the engine's answer for one —
+        // `AST-only evaluation not yet supported; persist \`source\`` — was what
+        // a `0` reported too, which sends its author looking for a serializer.
+        // One reason, one tag, the same two channels.
+        reason = UNEVALUABLE_PREDICATE_REASON;
+    }
+    else {
+        try {
+            // objectui#4421 — the acting subject's effective object permissions, the
+            // one input `current_user.can(object, verb)` is answered from. They ride
+            // on the subject the scope already carries (`subjectPermissions.ts`),
+            // never under a scope key, because every key of `scope` is a CEL root
+            // and the engine keeps this map out of the variable namespace. A subject
+            // with none passes none, and `can` then refuses loudly: that fault goes
+            // through the caller's `fallback` like any other.
+            const permissions = subjectPermissionsOf(scope?.current_user);
+            const res = ExpressionEngine.evaluate(expr, {
+                record,
+                previous,
+                ...(scope ? { extra: scope } : {}),
+                ...(permissions !== undefined ? { permissions } : {}),
+            });
+            // Parse error, type error, unbound identifier, engine fault … — every
+            // not-ok verdict resolves to the fallback, but never silently (objectstack-ai/objectstack#5149).
+            if (!res.ok)
+                reason = `[${res.error.kind}] ${res.error.message}`;
+            else
+                value = res.value === true;
+        }
+        catch (err) {
+            reason = `[throw] ${err instanceof Error ? err.message : String(err)}`;
+        }
     }
     if (reason !== undefined) {
         if (diagnostic?.warn !== false) {
@@ -146,6 +254,60 @@ export function evalFieldPredicate(pred, record, fallback, previous, scope, diag
     }
     return value;
 }
+/**
+ * The verdict {@link resolveFieldRuleState} applies when a rule's predicate
+ * CANNOT BE EVALUATED — parse error, unbound identifier, engine fault, or a
+ * predicate the author left blank.
+ *
+ * ⚠️ These answer **"what should the form do when this rule is BROKEN?"** —
+ * *not* "what should the form do when the author declared NO rule?" That
+ * second question is answered separately, by the `…_ABSENT` set below. The two
+ * sets hold pairwise EQUAL values today, and that equality is a copy, not an
+ * implication: each `rules.<key> != null` ternary answers the absent case with
+ * its own literal and hands `evalFieldPredicate` the same literal as the fault
+ * fallback beside it, so every permissive value is written twice and the "it
+ * broke" answer was chosen by aligning it with the "it is absent" answer next
+ * to it. Nothing was *inherited* from a shared default — `evalFieldPredicate`'s
+ * `fallback` parameter is required and has none (objectui#8069 measured both
+ * halves).
+ *
+ * All three directions are the PERMISSIVE one, so a single mistyped column in
+ * one authored predicate yields a form that shows more, locks less and demands
+ * less — three faults from one typo, composing rather than cancelling.
+ * ADR-0137 answered that without moving any of the three: they stay the RENDER
+ * direction (D3 — a faulting `visibleWhen` shows the field), and the composite
+ * is closed at SUBMIT instead (D2), from the `faults` report
+ * {@link resolveFieldRuleState} returns beside the verdicts.
+ *
+ * **What the history records** (read on full, unshallowed history — a shallow
+ * clone answers this with one commit and no warning): the direction *was*
+ * reasoned about, once, when the helper landed (objectui#1578). This module's
+ * head and ADR-0036 both record the same rationale — the fallbacks are "chosen
+ * so a fault is *safe*: `true` for visibility (don't hide content on error),
+ * `false` for required/readonly (don't block submit or lock a field on
+ * error)". What no commit records is the COMPOSITION: every recorded argument
+ * is per-key, and the case where all three faults arrive from one typo was
+ * never put. objectstack#5149 then removed the SILENCE and left the direction
+ * explicitly undecided ("appeal 1").
+ *
+ * ⛔ These values are shipped behaviour, declared by ADR-0137 D3. Changing one
+ * is not a refactor — and `6a449fc49` leans on the `visibleWhen` half staying
+ * fail-open (a broken predicate must never silently null a stored column).
+ */
+const VISIBLE_WHEN_FAULTED = true;
+const READONLY_WHEN_FAULTED = false;
+const REQUIRED_WHEN_FAULTED = false;
+/**
+ * The verdict {@link resolveFieldRuleState} applies when the author declared NO
+ * rule for that key at all — the `: <literal>` arm of each `!= null` ternary.
+ *
+ * Spelled apart from the `…_FAULTED` set above because they answer a different
+ * question, not because they differ: changing one of THESE changes what an
+ * unconditional field does, which is a louder and quite separate decision.
+ */
+const VISIBLE_WHEN_ABSENT = true;
+const READONLY_WHEN_ABSENT = false;
+const REQUIRED_WHEN_ABSENT = false;
 /**
  * Resolve the effective `{ visible, readonly, required }` state for a field
  * given its conditional rules and the live record. Each `*When` rule, when
@@ -153,25 +315,59 @@ export function evalFieldPredicate(pred, record, fallback, previous, scope, diag
  * `false` predicate result for required/readonly — but `visibleWhen` is
  * authoritative when present (so a field can be conditionally shown/hidden).
  *
+ * ## `statics.serverOwnedValue` — the one thing that outranks BOTH
+ *
+ * A CREATE form leaves a producer-owned control empty on purpose and omits the
+ * key, so the server resolves the declared runtime default (#4069). Required-
+ * ness is then not the client's question at all, and this is the single place
+ * that answers it: `required` resolves to `false` whatever `statics.required`
+ * says and whatever `requiredWhen` evaluates to.
+ *
+ * Both spellings had to land HERE, not in a gate a layer up. Since
+ * objectui#4201 the submit-time check and the required marker read one live
+ * verdict — this function's — so a suppression applied anywhere else would
+ * show a field without an asterisk and still refuse the submit, which is the
+ * exact two-layer disagreement #4201 removed. #4085 is the conditional half:
+ * `requiredWhen` resolving TRUE on a create form re-required a control the
+ * renderer deliberately left empty, with nothing the user could type to
+ * unblock it. See `isServerOwnedValue` in `../validation/server-owned-value.js`
+ * for who computes the fact and why the mode is the caller's to state.
+ *
  * @param fieldContext  Optional locator for failure warnings — e.g.
  *                      `"field 'amount'"`. The warning then reads
  *                      `visibleWhen of field 'amount' …`; without it, the rule
  *                      kind alone is reported.
+ * @returns The three verdicts, plus `faults` — see {@link FieldRuleFaults} for
+ *          what a submit path reads from it and what it leaves out.
  */
 export function resolveFieldRuleState(rules, record, statics, previous, scope, fieldContext) {
+    const faults = {};
+    // `onFault` fires beside the built-in warning, not instead of it (`warn`
+    // stays on), so recording the report costs no diagnostic and no second
+    // engine call.
     const diag = (rule) => ({
         context: fieldContext ? `${rule} of ${fieldContext}` : rule,
+        onFault: (reason) => {
+            faults[rule] = reason;
+        },
     });
     const visible = rules.visibleWhen != null
-        ? evalFieldPredicate(rules.visibleWhen, record, true, previous, scope, diag('visibleWhen'))
-        : true;
+        ? evalFieldPredicate(rules.visibleWhen, record, VISIBLE_WHEN_FAULTED, previous, scope, diag('visibleWhen'))
+        : VISIBLE_WHEN_ABSENT;
     const readonly = statics.readonly === true ||
         (rules.readonlyWhen != null
-            ? evalFieldPredicate(rules.readonlyWhen, record, false, previous, scope, diag('readonlyWhen'))
-            : false);
-    const required = statics.required === true ||
-        (rules.requiredWhen != null
-            ? evalFieldPredicate(rules.requiredWhen, record, false, previous, scope, diag('requiredWhen'))
-            : false);
-    return { visible, readonly, required };
+            ? evalFieldPredicate(rules.readonlyWhen, record, READONLY_WHEN_FAULTED, previous, scope, diag('readonlyWhen'))
+            : READONLY_WHEN_ABSENT);
+    // Short-circuited, not evaluated-and-discarded: the verdict cannot depend on
+    // the predicate, so running it would only spend an engine call per field per
+    // render. A broken `requiredWhen` still warns wherever it decides something
+    // — the same object's EDIT form, and any create form where the field is not
+    // server-owned.
+    const required = statics.serverOwnedValue === true
+        ? false
+        : statics.required === true ||
+            (rules.requiredWhen != null
+                ? evalFieldPredicate(rules.requiredWhen, record, REQUIRED_WHEN_FAULTED, previous, scope, diag('requiredWhen'))
+                : REQUIRED_WHEN_ABSENT);
+    return { visible, readonly, required, faults };
 }

package/dist/evaluator/index.d.ts

@@ -10,6 +10,8 @@ export * from './ExpressionEvaluator.js';
 export * from './predicateInput.js';
 export * from './declaredPredicate.js';
 export * from './fieldRules.js';
+export * from './subjectPermissions.js';
+export * from './rowPredicateCanon.js';
 export * from './listConditional.js';
 export * from './optionRules.js';
 export * from './optionLint.js';

package/dist/evaluator/index.js

@@ -10,6 +10,8 @@ export * from './ExpressionEvaluator.js';
 export * from './predicateInput.js';
 export * from './declaredPredicate.js';
 export * from './fieldRules.js';
+export * from './subjectPermissions.js';
+export * from './rowPredicateCanon.js';
 export * from './listConditional.js';
 export * from './optionRules.js';
 export * from './optionLint.js';

package/dist/evaluator/listConditional.d.ts

@@ -44,13 +44,39 @@ 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;
     /** 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` 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 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` 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
+     * 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
@@ -62,15 +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` (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 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`). */