@object-ui/core 17.6.0 → 17.7.0

package/dist/evaluator/declaredPredicate.js

@@ -6,6 +6,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { toPredicateInput } from './predicateInput.js';
+// A cycle with `fieldRules.ts`, which imports `isBlankPredicateText` from here.
+// Benign by construction: each side reads the other only inside a function
+// body, never while its module is being evaluated.
+import { evalFieldPredicate } from './fieldRules.js';
 /**
  * Is the predicate TEXT blank — in EITHER spelling? (objectui#3960)
  *
@@ -18,13 +22,22 @@ import { toPredicateInput } from './predicateInput.js';
  * `ActionRunner` refused to execute, for a predicate that says nothing).
  *
  * This is not a fourth dialect of "empty": it is the SAME rule core's evaluation
- * entries already apply on the value side — `evaluateCondition`
- * (`if (!trimmed) return true`), `evaluateCelCondition` (`if (!source.trim())
- * return true`), `evalRowPredicate` (`listConditional.ts`) — brought to the one
- * place that answers "is there a condition at all?", so the two halves cannot
- * disagree about the same blank.
+ * entries already apply on the value side — `evaluateCondition` on both of its
+ * routes (which ask THIS function: the CEL route since objectui#8069, the
+ * legacy path since objectui#11262), `evalRowPredicate` (`listConditional.ts`,
+ * whose blank reaches `evalFieldPredicate`, which asks it too) — brought to the
+ * one place that answers "is there a condition at all?", so the two halves
+ * cannot disagree about the same blank.
+ *
+ * Exported since objectui#8069 for its second consumer, `evalFieldPredicate`
+ * (`evaluator/fieldRules.ts`), which is the entry this docblock's list did NOT
+ * name because it did not apply the rule: it trimmed the STRING spelling only,
+ * so `{ dialect: 'cel', source: '   ' }` went to the engine and came back as a
+ * parse fault while `'   '` returned the caller's fallback in silence. Reusing
+ * this definition rather than writing a fourth `trim()` is the whole point of
+ * the paragraph above.
  */
-function isBlankPredicateText(value) {
+export function isBlankPredicateText(value) {
     if (typeof value === 'string')
         return value.trim() === '';
     if (value !== null && typeof value === 'object') {
@@ -67,18 +80,55 @@ function isBlankPredicateText(value) {
  *     Neither can be read off the normalizer's answer, so both are named here —
  *     see {@link isBlankPredicateText} for why this is the layer that says it.
  *     Core's other predicate entries already treat both as blank:
- *     `evaluateCondition` (`if (!trimmed) return true`), `evaluateCelCondition`
- *     (`if (!source.trim()) return true`) and `evalRowPredicate`
- *     (`evaluator/listConditional.ts`, `if (!source.trim())`).
+ *     `evaluateCondition` (`isBlankPredicateText`, then `true` — diagnosed on
+ *     the CEL route since objectui#8069 and on the legacy path since
+ *     objectui#11262) and `evalRowPredicate` (`evaluator/listConditional.ts`,
+ *     the caller's fallback, through `evalFieldPredicate`'s `[blank]` report
+ *     since objectui#11262).
  *   - `{ dialect, source: '' }` — the empty ENVELOPE. This is not an exotic
  *     spelling: `@objectstack/spec`'s `ExpressionInputSchema` normalizes every
  *     authored predicate into an envelope, so "author left the predicate empty"
  *     compiles to exactly this, which makes it the likeliest empty shape in real
  *     metadata (objectui#3850).
- *   - anything that is not a predicate at all (`0`, `{}`, an array): a value the
- *     evaluator cannot read must not be the reason a control is disabled or an
- *     action refuses to run. Fail-open on junk, which is the posture
- *     `ActionRunner` already committed to (`catch { isDisabled = false }`).
+ *
+ * The three BLANK shapes above (`''`, whitespace-only text, and an envelope
+ * whose `source` is blank) are still folded to "not declared" — that is the
+ * verdict — but no longer in silence: each is reported once (objectui#8069,
+ * ADR-0137 D4), see {@link reportBlankGate}. `null` / `undefined` (no key) is
+ * not blank TEXT and stays silent: nothing was declared there to report.
+ *
+ * ## What is DECLARED although nothing in it can be evaluated (objectui#11358)
+ *
+ * A value that is present but is not a predicate the client can evaluate — an
+ * envelope with no string `source` (the `ast`-only `{ dialect: 'cel', ast }` an
+ * unmirrored authoring door admits), a number (`0`), an object with no `source`
+ * (`{}`), an array — IS a declared gate. Triage's ruling on objectui#11358:
+ * "declared and faulting", "reported once per predicate", and the action
+ * "hides". It used to be the fifth "nothing to evaluate" shape here, answered
+ * "not declared" in silence, so a bulk action gated that way ran over every
+ * selected record and the toolbars and row menu showed it to everyone.
+ *
+ * This function's CODE did not change for it: the normalizer did.
+ * {@link toPredicateInput} no longer folds such a value into `undefined`; it
+ * returns a `cel` envelope with no `source`, so `toPredicateInput(x) !==
+ * undefined` — the line below — answers "declared", and the derivation this
+ * definition rests on still holds with no second list. The state is told apart
+ * in one place, `isUnevaluablePredicate` (`./unevaluablePredicate.ts`).
+ *
+ * What a reader then DOES with it is the evaluation step's, not this
+ * function's: `ExpressionEvaluator.evaluateCondition` and `evalFieldPredicate`
+ * treat it as a FAULT, so each reader answers with the fail direction its key
+ * already has for a predicate that cannot be evaluated, and reports it there,
+ * once — through `evalFieldPredicate`'s report with the `[unevaluable]` reason,
+ * or through the caller's own fault report. That is why this function reports
+ * nothing for it: a declared gate always goes on to an evaluation, and two
+ * reports for one fault is the noise objectstack-ai/objectstack#5149 removed.
+ * On every action `visible` leg that direction is CLOSED (objectui#11212), on
+ * every `disabled` leg too (objectui#11242), and the hide-polarity `hidden` /
+ * `hiddenOn` legs of `SchemaRenderer` answer "hidden". The keys whose fault
+ * direction is OPEN keep it — a `condition` still lets the action run, a
+ * legacy `enabled` leaves the control enabled, an action param's `visible`
+ * still shows the param — now diagnosed rather than silent.
  *
  * A declared-and-`false` gate is DECLARED (`toPredicateInput` returns the
  * boolean unchanged): `disabled: false` / `visible: false` are verdicts, and
@@ -142,11 +192,62 @@ function isBlankPredicateText(value) {
  * an empty predicate made the node VANISH (objectui#3955), and
  * `ActionEngine.getActionsForLocation`'s `visible` filter, which folded some
  * empty spellings by hand and coerced the rest with `Boolean(raw)`, so
- * `visible: 0` hid an action the renderers showed (objectui#3957). Nothing in the
- * repo now asks "is a gate declared?" anywhere but here.
+ * `visible: 0` hid an action the renderers showed (objectui#3957).
+ *
+ * The last one joined with objectui#11322: plugin-grid's `hasVisibilityGate`,
+ * on the grid's selection bar, asks it through the renderer-side name
+ * `hasDeclaredVisibilityGate`. It decides whether a bulk button whose `visible`
+ * admits no record is hidden, and `partitionBulkRows` asks it before handing a
+ * bulk def's `visible` to `partitionRowsByPredicate`. It had kept the old
+ * `!= null && !== ''` scope after every other member of the family moved here,
+ * so a whitespace-only `visible` counted as declared on that bar, failed closed
+ * for every record, and hid an action the row menu and toolbars showed.
+ *
+ * Nothing in the repo now asks "is a gate declared?" anywhere but here for
+ * the keys this definition serves. What stays outside is a different family,
+ * not a twin: the field-rule `*When` keys (ADR-0137) decide it by rules of
+ * their own. Examples are the built-in Edit / Delete row item's
+ * `visibleWhen != null` (`isBuiltinRowActionVisible`), and the opening test of
+ * the shared partitioner `partitionRowsByPredicate` (`null` / `undefined` /
+ * `''`), which is the answer its built-in Delete `visibleWhen` callers get. The
+ * action family asks here before it calls that partitioner.
+ * ⚠️ Nothing re-derives this paragraph: it was read off a source search when
+ * objectui#11322 landed, and no test or gate repeats that search.
  */
 export function hasDeclaredPredicate(value) {
-    if (isBlankPredicateText(value))
+    if (isBlankPredicateText(value)) {
+        reportBlankGate(value);
         return false;
+    }
     return toPredicateInput(value) !== undefined;
 }
+/**
+ * Say out loud that a DECLARED gate was blank — the one side effect
+ * {@link hasDeclaredPredicate} has (objectui#8069).
+ *
+ * The fold above is objectui#3850 / #3960's ruled verdict and it stands: a
+ * blank gate is "no gate". What ADR-0137 D4 removed is the SILENCE of it — "a
+ * gate predicate that is blank or faulting is diagnosed, never a silent
+ * `true`" — and this fold is where a blank `visible` / `hidden` / `enabled` /
+ * `disabled` / `condition` stopped before it could reach any evaluator that
+ * might have said so.
+ *
+ * Reported through `evalFieldPredicate`'s own `[blank]` report — the channel
+ * every other predicate fault already uses, with its once-per-(text, locator)
+ * dedupe — and not through a warner of its own. It makes no engine call: a
+ * blank predicate never reaches the engine. The `false` it is handed is this
+ * function's answer ("not declared"); nothing reads it back.
+ *
+ * ⚠️ The locator is FIXED, because this question is key-neutral and receives
+ * nothing that names the node. So the dedupe is per blank SPELLING across the
+ * app: `''`, `'   '` and a blank envelope each warn once, and a second node
+ * with the same blank spelling does not warn again. That is weaker than the
+ * field-rule path, which joins the field's locator to a blank's key, and it is
+ * the price of diagnosing at the one definition rather than at each of its
+ * callers.
+ */
+function reportBlankGate(value) {
+    evalFieldPredicate(value, {}, false, undefined, undefined, {
+        context: 'a declared gate, read as no gate',
+    });
+}

package/dist/evaluator/fieldRules.d.ts

@@ -44,12 +44,54 @@ export interface FieldPredicateDiagnostic {
 /**
  * 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
@@ -61,6 +103,45 @@ export interface FieldPredicateDiagnostic {
  *                  is unaffected either way.
  */
 export declare function evalFieldPredicate(pred: FieldRulePredicate | undefined | null, record: Record<string, unknown>, fallback: boolean, previous?: Record<string, unknown>, scope?: Record<string, unknown>, diagnostic?: FieldPredicateDiagnostic): boolean;
+/**
+ * Which of {@link resolveFieldRuleState}'s rules could NOT be evaluated, and
+ * why — keyed by rule, valued by the reason the one-time warning prints after
+ * `Reason:` (`"[kind] message"`). A key is present only for a rule that ran and
+ * faulted (objectui#8069).
+ *
+ * This is the report a SUBMIT path reads — ADR-0137 D2, "at submit time, a
+ * field-rule predicate that cannot be evaluated refuses the write and names the
+ * field and the rule" — so that the refusal is decided by the very evaluation
+ * that drew the verdict, never by a second one with its own record assembly.
+ * Which rules a submit path refuses on is that path's ruling, not this
+ * function's: under objectui#8069's ruling (Q1 = B, one judge per rule) the
+ * client refuses `visibleWhen` only, because no server evaluates it, and leaves
+ * `readonlyWhen` / `requiredWhen` to the server's own D2 refusal. The other two
+ * keys are reported all the same, so the report does not encode that ruling.
+ *
+ * A BLANK predicate IS in it, as the `[blank]` reason. ADR-0137 makes a
+ * declared-but-blank field rule a third state, not a spelling of "no rule":
+ * "A blank predicate takes this path too, wherever one is already stored — D1
+ * keeps new ones from being authored, and D2 is what a stored one meets" (D2),
+ * and its Alternatives refuse "blank means no rule" for this triad by name. So
+ * a stored blank `visibleWhen` is refused at submit like any other fault. The
+ * trap that would otherwise make — an authorable value that no submit can ever
+ * pass — is closed at AUTHORING: the triad's form wire refuses a blank at parse
+ * (`FieldRulePredicateWireSchema` in `@object-ui/types`' `form.zod.ts`, D1).
+ * The render verdict of a blank rule is unchanged (D3: the permissive one).
+ * A blank GATE is a different thing: `hasDeclaredPredicate` still folds it to
+ * "no gate" and only diagnoses it (D4) — it never reaches this function.
+ *
+ * Deliberately NOT in it: a rule the verdict did not need. `readonlyWhen` under
+ * a static `readonly: true`, and `requiredWhen` under `serverOwnedValue` or a
+ * static `required: true`, are short-circuited and never run, so they cannot
+ * fault.
+ */
+export interface FieldRuleFaults {
+    visibleWhen?: string;
+    readonlyWhen?: string;
+    requiredWhen?: string;
+}
 /**
  * Resolve the effective `{ visible, readonly, required }` state for a field
  * given its conditional rules and the live record. Each `*When` rule, when
@@ -90,6 +171,8 @@ export declare function evalFieldPredicate(pred: FieldRulePredicate | undefined
  *                      `"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 declare function resolveFieldRuleState(rules: {
     visibleWhen?: FieldRulePredicate;
@@ -103,4 +186,5 @@ export declare function resolveFieldRuleState(rules: {
     visible: boolean;
     readonly: boolean;
     required: boolean;
+    faults: FieldRuleFaults;
 };

package/dist/evaluator/fieldRules.js

@@ -61,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')
@@ -70,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);
@@ -92,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
@@ -109,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) {
@@ -145,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
@@ -174,18 +337,27 @@ export function evalFieldPredicate(pred, record, fallback, previous, scope, diag
  *                      `"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);
+            ? 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
@@ -195,7 +367,7 @@ export function resolveFieldRuleState(rules, record, statics, previous, scope, f
         ? false
         : statics.required === true ||
             (rules.requiredWhen != null
-                ? evalFieldPredicate(rules.requiredWhen, record, false, previous, scope, diag('requiredWhen'))
-                : false);
-    return { visible, readonly, required };
+                ? 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,7 @@ 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';

package/dist/evaluator/index.js

@@ -10,6 +10,7 @@ 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';