@object-ui/core 17.3.0 → 17.6.0

package/dist/evaluator/ExpressionEvaluator.d.ts

@@ -129,7 +129,48 @@ export declare class ExpressionEvaluator {
      */
     getFormulas(): FormulaFunctions;
     /**
-     * Register a custom formula function
+     * Register a custom formula function.
+     *
+     * **The name is case-folded: it is stored — and must be called — in UPPER
+     * CASE.** `registerFunction('formatCurrency', fn)` registers
+     * `FORMATCURRENCY`, and an expression has to spell it that way:
+     * `${FORMATCURRENCY(price)}` resolves, `${formatCurrency(price)}` does not.
+     * The fold is deliberate — formula names are spreadsheet-style vocabulary
+     * (`SUM`, `IF`, `UPPER`) and the built-ins go through the very same
+     * {@link FormulaFunctions.register} — but two things keep it from being
+     * self-evident at the call site:
+     *
+     * 1. The registry API stays case-insensitive, so it never surfaces the fold:
+     *    `getFormulas().has('formatCurrency')` is `true` and `.get()` returns the
+     *    function. Only expressions see the stored spelling, because the
+     *    evaluation scope is built from `FormulaFunctions.toObject()` — a plain
+     *    object, whose identifiers expressions match case-sensitively.
+     * 2. A wrong-case call site does not raise. {@link evaluate} catches, warns,
+     *    and returns `defaultValue ?? expression`, so the template renders its own
+     *    `${...}` source as literal text.
+     *    {@link ExpressionEvaluator.evaluateExpression} is the throwing sibling,
+     *    and reports `'formatCurrency' is not a function`.
+     *
+     * To keep a name's exact spelling, supply the function as evaluation context
+     * data instead: context entries are merged over the formulas and stay verbatim.
+     *
+     * @param name Function name; folded to upper case for both storage and lookup.
+     * @param fn Implementation, invoked with the evaluated call arguments.
+     *
+     * @example
+     * ```ts
+     * const evaluator = new ExpressionEvaluator({ price: 1234.5 });
+     * evaluator.registerFunction('formatCurrency', fmt);
+     *
+     * evaluator.evaluate('${FORMATCURRENCY(price)}'); // '$1,234.50'
+     * evaluator.evaluate('${formatCurrency(price)}'); // '${formatCurrency(price)}' — the source, verbatim
+     *
+     * // Case-sensitive alternative — the function travels as context data.
+     * // Note the receiver: the call below is the MODULE-LEVEL export (a context
+     * // bag as its second parameter), not the method used above.
+     * import { evaluateExpression } from '@object-ui/core';
+     * evaluateExpression('${formatCurrency(price)}', { formatCurrency: fmt, price: 1234.5 }); // '$1,234.50'
+     * ```
      */
     registerFunction(name: string, fn: (...args: any[]) => any): void;
 }

package/dist/evaluator/ExpressionEvaluator.js

@@ -305,7 +305,48 @@ export class ExpressionEvaluator {
         return this.formulas;
     }
     /**
-     * Register a custom formula function
+     * Register a custom formula function.
+     *
+     * **The name is case-folded: it is stored — and must be called — in UPPER
+     * CASE.** `registerFunction('formatCurrency', fn)` registers
+     * `FORMATCURRENCY`, and an expression has to spell it that way:
+     * `${FORMATCURRENCY(price)}` resolves, `${formatCurrency(price)}` does not.
+     * The fold is deliberate — formula names are spreadsheet-style vocabulary
+     * (`SUM`, `IF`, `UPPER`) and the built-ins go through the very same
+     * {@link FormulaFunctions.register} — but two things keep it from being
+     * self-evident at the call site:
+     *
+     * 1. The registry API stays case-insensitive, so it never surfaces the fold:
+     *    `getFormulas().has('formatCurrency')` is `true` and `.get()` returns the
+     *    function. Only expressions see the stored spelling, because the
+     *    evaluation scope is built from `FormulaFunctions.toObject()` — a plain
+     *    object, whose identifiers expressions match case-sensitively.
+     * 2. A wrong-case call site does not raise. {@link evaluate} catches, warns,
+     *    and returns `defaultValue ?? expression`, so the template renders its own
+     *    `${...}` source as literal text.
+     *    {@link ExpressionEvaluator.evaluateExpression} is the throwing sibling,
+     *    and reports `'formatCurrency' is not a function`.
+     *
+     * To keep a name's exact spelling, supply the function as evaluation context
+     * data instead: context entries are merged over the formulas and stay verbatim.
+     *
+     * @param name Function name; folded to upper case for both storage and lookup.
+     * @param fn Implementation, invoked with the evaluated call arguments.
+     *
+     * @example
+     * ```ts
+     * const evaluator = new ExpressionEvaluator({ price: 1234.5 });
+     * evaluator.registerFunction('formatCurrency', fmt);
+     *
+     * evaluator.evaluate('${FORMATCURRENCY(price)}'); // '$1,234.50'
+     * evaluator.evaluate('${formatCurrency(price)}'); // '${formatCurrency(price)}' — the source, verbatim
+     *
+     * // Case-sensitive alternative — the function travels as context data.
+     * // Note the receiver: the call below is the MODULE-LEVEL export (a context
+     * // bag as its second parameter), not the method used above.
+     * import { evaluateExpression } from '@object-ui/core';
+     * evaluateExpression('${formatCurrency(price)}', { formatCurrency: fmt, price: 1234.5 }); // '$1,234.50'
+     * ```
      */
     registerFunction(name, fn) {
         this.formulas.register(name, fn);

package/dist/evaluator/SafeExpressionParser.js

@@ -296,7 +296,6 @@ export class SafeExpressionParser {
     parseEquality() {
         let left = this.parseAddition();
         this.skipWhitespace();
-        // eslint-disable-next-line no-constant-condition
         while (true) {
             // Every branch below either assigns `op` or `break`s out of the loop, so
             // `op` is always set by the time the switch reads it (no null initializer
@@ -346,11 +345,9 @@ export class SafeExpressionParser {
                 case '!==':
                     left = left !== right;
                     break;
-                // eslint-disable-next-line eqeqeq
                 case '==':
                     left = left == right;
                     break;
-                // eslint-disable-next-line eqeqeq
                 case '!=':
                     left = left != right;
                     break;
@@ -438,7 +435,6 @@ export class SafeExpressionParser {
     /** Level 9 — Member access, method calls, function calls */
     parseMember() {
         let obj = this.parsePrimary();
-        // eslint-disable-next-line no-constant-condition
         while (true) {
             this.skipWhitespace();
             const isOptionalDot = this.peek() === '?' && this.peek(1) === '.';

package/dist/evaluator/declaredPredicate.d.ts

@@ -0,0 +1,119 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Is a predicate gate DECLARED on this value — i.e. after normalization, is
+ * there still a CONDITION for {@link ExpressionEvaluator.evaluateCondition} to
+ * reach a verdict on? (objectui#3850's ruling, key-neutral: `visible` /
+ * `hidden` / `enabled` / `disabled` / `condition` all ask it.)
+ *
+ * This is the ONE definition of that question in the repo, and it lives here —
+ * one layer under every consumer, beside {@link toPredicateInput}, whose answer
+ * it is derived from. It has to be asked separately from the verdict because
+ * `evaluateCondition` documents and implements exactly one default for "there
+ * is nothing here to evaluate": it returns `true`, meaning *visible/enabled*.
+ * That default is right on `visible` / `enabled` and INVERTED on `disabled`,
+ * where `true` means "greyed out" — so a gate that hands an empty predicate to
+ * the evaluator gets the strongest possible "yes, disable it" for a value the
+ * metadata never used to say anything. Truthiness cannot answer it either, and
+ * asking it that way was objectui#3812: `if (action.visible && !isVisible)`
+ * read `visible: false` — the most explicit "never show this" an author can
+ * write — as *ungated*, and rendered the action for everyone.
+ *
+ * ## What counts as "nothing to evaluate"
+ *
+ * Exactly the shapes {@link toPredicateInput} folds to `undefined`, plus the two
+ * BLANK spellings it wraps or passes through instead of folding:
+ *
+ *   - `null` / `undefined` — no key at all.
+ *   - `''` — an empty predicate (objectui#3492 / objectui#3842).
+ *   - blank predicate TEXT, in either spelling — a whitespace-only string
+ *     (`'   '`, which the normalizer wraps into `'${   }'`) and an envelope whose
+ *     `source` is whitespace-only (`{ dialect: 'cel', source: '   ' }`, which the
+ *     normalizer passes through because it only folds a `source` of `''`).
+ *     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())`).
+ *   - `{ 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 }`).
+ *
+ * A declared-and-`false` gate is DECLARED (`toPredicateInput` returns the
+ * boolean unchanged): `disabled: false` / `visible: false` are verdicts, and
+ * routing them to the evaluator — which short-circuits booleans — is the point
+ * of asking "declared?" rather than "truthy?".
+ *
+ * ## Why blankness is decided HERE and not in the normalizer (objectui#3960)
+ *
+ * The blank-`source` envelope arrived one release late: objectui#3850's ruling
+ * enumerated three empty spellings, `toPredicateInput` folds a `source` of `''`
+ * and does not trim, so `{ dialect: 'cel', source: '   ' }` stayed "declared"
+ * while core's own CEL entry called that exact value "no predicate" — `disabled`
+ * greyed out and `ActionRunner` refused to execute for a predicate that says
+ * nothing (objectui#3960). The asymmetry was that this definition trimmed the
+ * STRING spelling of a blank predicate and not the ENVELOPE spelling of the same
+ * blank.
+ *
+ * Fixing it at the normalizer instead (`if (!src.trim()) return undefined`) would
+ * have aligned every `evaluateCondition(toPredicateInput(x))` consumer at once,
+ * and that is precisely why it is the wider, wrong lever: it changes what
+ * normalization MEANS, which is a shape question ("what does the evaluator
+ * accept"), to answer a declaredness question ("is there a condition"). Those are
+ * different concepts on purpose — a blank `source` is a shape the evaluator
+ * accepts and answers `true` for, by its own documented rule. The blast radius is
+ * the concrete difference: at the normalizer, a NON-cel blank envelope
+ * (`{ source: '   ' }` → `'${   }'` → falsy) flips verdict for every
+ * `useCondition(toPredicateInput(…))` call site including the container-level
+ * `visible` reads in `action-bar` / `action-group` / `action-menu` /
+ * `RelatedList` / `record-alert`, none of which ask this question at all; here it
+ * flips only for the consumers that DO ask it, and only on the inverted-polarity
+ * keys where "declared" is what turns a control off.
+ *
+ * ## Why the callers still evaluate the RAW value
+ *
+ * Every consumer normalizes to decide DECLAREDNESS and then evaluates whatever
+ * it was given, `evaluateCondition(raw)` or `evaluateCondition(toPredicateInput(
+ * raw))` as it did before. Both agree since objectui#3871 made the normalizer
+ * idempotent for an already-`${…}` string; before that they did not, and a
+ * template-spelled predicate normalized twice came back as a constant. Nothing
+ * here changes a verdict for a value that HAS one — this gate only decides
+ * whether there is one to reach.
+ *
+ * ## Scope history (objectui#3850)
+ *
+ * The question used to be answered three times with three different scopes: the
+ * renderer-side `hasDeclaredVisibilityGate` (`!= null && !== ''`, so every
+ * object counted — including the empty envelope), `SchemaRenderer`'s inline
+ * `!== undefined` (wider still: `disabled: null` greyed the control out,
+ * objectui#3862), and `ActionRunner`'s module-private helper (this scope, which
+ * arrived first with objectui#3848 and is what the ruling adopted). One
+ * definition with one scope replaces all three:
+ * `components/renderers/action/visibility-gate.ts` re-exports this function
+ * under its historic name `hasDeclaredVisibilityGate` (the five member-action
+ * renderer call sites are unchanged), `SchemaRenderer`'s `disabled` /
+ * `disabledOn` chain reads it, and `ActionRunner`'s two gates read it instead of
+ * a private twin.
+ *
+ * Two more consumers joined afterwards, and with them the last two places that
+ * answered this question with a range of their own:
+ * `SchemaRenderer`'s `hidden` / `hiddenOn` legs, whose verdict is NOT negated so
+ * 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.
+ */
+export declare function hasDeclaredPredicate(value: unknown): boolean;

package/dist/evaluator/declaredPredicate.js

@@ -0,0 +1,152 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { toPredicateInput } from './predicateInput.js';
+/**
+ * Is the predicate TEXT blank — in EITHER spelling? (objectui#3960)
+ *
+ * `'   '` and `{ dialect: 'cel', source: '   ' }` are the same author mistake
+ * written two ways, and {@link toPredicateInput} folds neither: it wraps a
+ * whitespace-only string into `'${   }'`, and it only folds an envelope whose
+ * `source` is exactly `''`. So blankness cannot be derived from the normalizer's
+ * answer and has to be stated once, here, for both spellings — trimming one and
+ * not the other is the asymmetry objectui#3960 measured (`disabled` greyed out,
+ * `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.
+ */
+function isBlankPredicateText(value) {
+    if (typeof value === 'string')
+        return value.trim() === '';
+    if (value !== null && typeof value === 'object') {
+        const source = value.source;
+        if (typeof source === 'string')
+            return source.trim() === '';
+    }
+    return false;
+}
+/**
+ * Is a predicate gate DECLARED on this value — i.e. after normalization, is
+ * there still a CONDITION for {@link ExpressionEvaluator.evaluateCondition} to
+ * reach a verdict on? (objectui#3850's ruling, key-neutral: `visible` /
+ * `hidden` / `enabled` / `disabled` / `condition` all ask it.)
+ *
+ * This is the ONE definition of that question in the repo, and it lives here —
+ * one layer under every consumer, beside {@link toPredicateInput}, whose answer
+ * it is derived from. It has to be asked separately from the verdict because
+ * `evaluateCondition` documents and implements exactly one default for "there
+ * is nothing here to evaluate": it returns `true`, meaning *visible/enabled*.
+ * That default is right on `visible` / `enabled` and INVERTED on `disabled`,
+ * where `true` means "greyed out" — so a gate that hands an empty predicate to
+ * the evaluator gets the strongest possible "yes, disable it" for a value the
+ * metadata never used to say anything. Truthiness cannot answer it either, and
+ * asking it that way was objectui#3812: `if (action.visible && !isVisible)`
+ * read `visible: false` — the most explicit "never show this" an author can
+ * write — as *ungated*, and rendered the action for everyone.
+ *
+ * ## What counts as "nothing to evaluate"
+ *
+ * Exactly the shapes {@link toPredicateInput} folds to `undefined`, plus the two
+ * BLANK spellings it wraps or passes through instead of folding:
+ *
+ *   - `null` / `undefined` — no key at all.
+ *   - `''` — an empty predicate (objectui#3492 / objectui#3842).
+ *   - blank predicate TEXT, in either spelling — a whitespace-only string
+ *     (`'   '`, which the normalizer wraps into `'${   }'`) and an envelope whose
+ *     `source` is whitespace-only (`{ dialect: 'cel', source: '   ' }`, which the
+ *     normalizer passes through because it only folds a `source` of `''`).
+ *     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())`).
+ *   - `{ 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 }`).
+ *
+ * A declared-and-`false` gate is DECLARED (`toPredicateInput` returns the
+ * boolean unchanged): `disabled: false` / `visible: false` are verdicts, and
+ * routing them to the evaluator — which short-circuits booleans — is the point
+ * of asking "declared?" rather than "truthy?".
+ *
+ * ## Why blankness is decided HERE and not in the normalizer (objectui#3960)
+ *
+ * The blank-`source` envelope arrived one release late: objectui#3850's ruling
+ * enumerated three empty spellings, `toPredicateInput` folds a `source` of `''`
+ * and does not trim, so `{ dialect: 'cel', source: '   ' }` stayed "declared"
+ * while core's own CEL entry called that exact value "no predicate" — `disabled`
+ * greyed out and `ActionRunner` refused to execute for a predicate that says
+ * nothing (objectui#3960). The asymmetry was that this definition trimmed the
+ * STRING spelling of a blank predicate and not the ENVELOPE spelling of the same
+ * blank.
+ *
+ * Fixing it at the normalizer instead (`if (!src.trim()) return undefined`) would
+ * have aligned every `evaluateCondition(toPredicateInput(x))` consumer at once,
+ * and that is precisely why it is the wider, wrong lever: it changes what
+ * normalization MEANS, which is a shape question ("what does the evaluator
+ * accept"), to answer a declaredness question ("is there a condition"). Those are
+ * different concepts on purpose — a blank `source` is a shape the evaluator
+ * accepts and answers `true` for, by its own documented rule. The blast radius is
+ * the concrete difference: at the normalizer, a NON-cel blank envelope
+ * (`{ source: '   ' }` → `'${   }'` → falsy) flips verdict for every
+ * `useCondition(toPredicateInput(…))` call site including the container-level
+ * `visible` reads in `action-bar` / `action-group` / `action-menu` /
+ * `RelatedList` / `record-alert`, none of which ask this question at all; here it
+ * flips only for the consumers that DO ask it, and only on the inverted-polarity
+ * keys where "declared" is what turns a control off.
+ *
+ * ## Why the callers still evaluate the RAW value
+ *
+ * Every consumer normalizes to decide DECLAREDNESS and then evaluates whatever
+ * it was given, `evaluateCondition(raw)` or `evaluateCondition(toPredicateInput(
+ * raw))` as it did before. Both agree since objectui#3871 made the normalizer
+ * idempotent for an already-`${…}` string; before that they did not, and a
+ * template-spelled predicate normalized twice came back as a constant. Nothing
+ * here changes a verdict for a value that HAS one — this gate only decides
+ * whether there is one to reach.
+ *
+ * ## Scope history (objectui#3850)
+ *
+ * The question used to be answered three times with three different scopes: the
+ * renderer-side `hasDeclaredVisibilityGate` (`!= null && !== ''`, so every
+ * object counted — including the empty envelope), `SchemaRenderer`'s inline
+ * `!== undefined` (wider still: `disabled: null` greyed the control out,
+ * objectui#3862), and `ActionRunner`'s module-private helper (this scope, which
+ * arrived first with objectui#3848 and is what the ruling adopted). One
+ * definition with one scope replaces all three:
+ * `components/renderers/action/visibility-gate.ts` re-exports this function
+ * under its historic name `hasDeclaredVisibilityGate` (the five member-action
+ * renderer call sites are unchanged), `SchemaRenderer`'s `disabled` /
+ * `disabledOn` chain reads it, and `ActionRunner`'s two gates read it instead of
+ * a private twin.
+ *
+ * Two more consumers joined afterwards, and with them the last two places that
+ * answered this question with a range of their own:
+ * `SchemaRenderer`'s `hidden` / `hiddenOn` legs, whose verdict is NOT negated so
+ * 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.
+ */
+export function hasDeclaredPredicate(value) {
+    if (isBlankPredicateText(value))
+        return false;
+    return toPredicateInput(value) !== undefined;
+}

package/dist/evaluator/fieldRules.d.ts

@@ -24,6 +24,22 @@ export interface FieldPredicateDiagnostic {
      * warnings for one broken predicate. Defaults to `true`.
      */
     warn?: boolean;
+    /**
+     * Called with the engine's failure reason (`"[kind] message"`, the exact text
+     * the built-in warning prints after `Reason:`) when the predicate cannot be
+     * evaluated. This is the passback for callers that set `warn: false` and
+     * report the fault themselves — without it, silencing the built-in warning
+     * also discards the only description of *why* the predicate failed, which is
+     * how the fail-closed row-predicate path ended up the least debuggable one
+     * (objectui#3792).
+     *
+     * Independent of `warn` and of the one-time-warning dedupe: it fires on every
+     * fault, so a caller doing its own warn-once bookkeeping keeps control of it.
+     * The returned verdict is unaffected. Must not throw — it is invoked outside
+     * the engine guard, so an exception here propagates to the caller rather than
+     * being reported as an engine fault.
+     */
+    onFault?: (reason: string) => void;
 }
 /**
  * Evaluate a field-rule CEL predicate against a record.
@@ -52,6 +68,24 @@ export declare function evalFieldPredicate(pred: FieldRulePredicate | undefined
  * `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
@@ -64,6 +98,7 @@ export declare function resolveFieldRuleState(rules: {
 }, record: Record<string, unknown>, statics: {
     required?: boolean;
     readonly?: boolean;
+    serverOwnedValue?: boolean;
 }, previous?: Record<string, unknown>, scope?: Record<string, unknown>, fieldContext?: string): {
     visible: boolean;
     readonly: boolean;

package/dist/evaluator/fieldRules.js

@@ -22,8 +22,32 @@
  * CEL (mirrors the server's `toExpression`). Evaluation is *fail-open* for
  * visibility/required (a broken predicate must not hide a field or wrongly
  * block submit) and *fail-open* for readonly (a broken predicate leaves the
- * field editable) — matching the server, which logs and allows the change
- * through.
+ * field editable).
+ *
+ * Fail-open agrees with the server for MOST faults — but not for all, and the
+ * exception is the half worth knowing. Since objectstack#4889 a `readonlyWhen`
+ * predicate that faults because it names a scope ROOT the write never bound —
+ * `parent.status == 'paid'` with no master-detail header in hand — is
+ * fail-CLOSED on the server: `isReadonlyWhenLocked` warns and then returns
+ * TRUE, i.e. LOCKED (a declared lock is not waived merely because it could not
+ * be evaluated), and `stripReadonlyWhenFields` — plus
+ * `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-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.
+ *
+ * The caller-visible consequence, spelled out because the symptom is silent:
+ * the form renders the field EDITABLE, the user edits it, the save reports
+ * SUCCESS, and the new value never lands — the server dropped the key and kept
+ * the persisted one. Debug that toward the SERVER-side lock (its `… treating
+ * the field as LOCKED` warning, and the write response's `droppedFields`), not
+ * toward the client predicate, which did exactly what it was asked to. The
+ * other two halves carry no such carve-out: `requiredWhen` binds the same
+ * `parent` scope but deliberately kept fail-open semantics (objectstack#4977),
+ * so an unevaluable requirement is skipped on BOTH ends, and field-level
+ * `visibleWhen` is not a server concept at all.
  *
  * Fail-open is **loud**, not silent (objectstack#5149): a predicate that
  * cannot be evaluated — parse error, unbound identifier, engine fault — logs
@@ -31,8 +55,10 @@
  * reason, then still returns the caller's fallback. Without the warning a
  * broken predicate is indistinguishable from an absent one, so
  * conditional-visibility bugs survive inspection indefinitely. This is the
- * client half of the server's "log and allow" convention (`readonlyWhen for
- * 'x' failed to evaluate — change allowed through`). The *default* stays
+ * client half of the server's "log and allow" convention for the faults where
+ * the two ends DO agree (`readonlyWhen for 'x' failed to evaluate — change
+ * allowed through` — the GENERIC-fault message; the unbound-root fault above
+ * 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).
  */
@@ -86,30 +112,38 @@ export function evalFieldPredicate(pred, record, fallback, previous, scope, diag
     if (pred == null || (typeof pred === 'string' && !pred.trim()))
         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.
+    let reason;
+    let value = fallback;
     try {
         const res = ExpressionEngine.evaluate(expr, {
             record,
             previous,
             ...(scope ? { extra: scope } : {}),
         });
-        if (!res.ok) {
-            // Parse error, type error, unbound identifier, engine fault … — every
-            // not-ok verdict resolves to the fallback, but never silently (#5149).
-            if (diagnostic?.warn !== false) {
-                warnPredicateFailure(expr, fallback, `[${res.error.kind}] ${res.error.message}`, diagnostic?.context);
-            }
-            return fallback;
-        }
-        return res.value === true;
+        // 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;
     }
     catch (err) {
-        // The engine contract is "never throws"; this guard is for anything that
-        // slips past it. Same loud fail-open as the not-ok branch.
+        reason = `[throw] ${err instanceof Error ? err.message : String(err)}`;
+    }
+    if (reason !== undefined) {
         if (diagnostic?.warn !== false) {
-            warnPredicateFailure(expr, fallback, `[throw] ${err instanceof Error ? err.message : String(err)}`, diagnostic?.context);
+            warnPredicateFailure(expr, fallback, reason, diagnostic?.context);
         }
+        // Outside the try on purpose: a throwing callback is a caller bug and must
+        // surface as one, not be swallowed and re-reported as an engine fault.
+        diagnostic?.onFault?.(reason);
         return fallback;
     }
+    return value;
 }
 /**
  * Resolve the effective `{ visible, readonly, required }` state for a field
@@ -118,6 +152,24 @@ 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
@@ -134,9 +186,16 @@ export function resolveFieldRuleState(rules, record, statics, previous, scope, f
         (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);
+    // 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, false, previous, scope, diag('requiredWhen'))
+                : false);
     return { visible, readonly, required };
 }

package/dist/evaluator/index.d.ts

@@ -8,7 +8,9 @@
 export * from './ExpressionContext.js';
 export * from './ExpressionEvaluator.js';
 export * from './predicateInput.js';
+export * from './declaredPredicate.js';
 export * from './fieldRules.js';
+export * from './rowPredicateCanon.js';
 export * from './listConditional.js';
 export * from './optionRules.js';
 export * from './optionLint.js';

package/dist/evaluator/index.js

@@ -8,7 +8,9 @@
 export * from './ExpressionContext.js';
 export * from './ExpressionEvaluator.js';
 export * from './predicateInput.js';
+export * from './declaredPredicate.js';
 export * from './fieldRules.js';
+export * from './rowPredicateCanon.js';
 export * from './listConditional.js';
 export * from './optionRules.js';
 export * from './optionLint.js';