@object-ui/core 17.5.0 → 17.7.0

package/dist/evaluator/declaredPredicate.d.ts

@@ -5,6 +5,34 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/**
+ * 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` 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.
+ */
+export declare function isBlankPredicateText(value: unknown): boolean;
 /**
  * Is a predicate gate DECLARED on this value — i.e. after normalization, is
  * there still a CONDITION for {@link ExpressionEvaluator.evaluateCondition} to
@@ -38,18 +66,55 @@
  *     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
@@ -113,7 +178,26 @@
  * 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 declare function hasDeclaredPredicate(value: unknown): boolean;

package/dist/evaluator/declaredPredicate.js

@@ -5,7 +5,11 @@
  * 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';
+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';
  * `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
@@ -68,10 +149,30 @@ 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
  *                      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;
@@ -80,8 +181,10 @@ 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;
     required: boolean;
+    faults: FieldRuleFaults;
 };