refactor(fields): drop the retired conditionalRequired alias (#2952)

`@objectstack/spec` 17 (objectstack#3855) retired `Field.conditionalRequired`,
the deprecated alias of `requiredWhen`. It is tombstoned with `retiredKey()`
(`z.never()`), so authoring it is a `tsc` error AND a hard parse rejection
carrying the rename prescription — verified against 17.0.0-rc.0 at both
`FieldSchema` and `ObjectSchema`. Spec-parsed metadata therefore cannot carry
the key: an object declaring it fails to load rather than loading with the rule
silently dropped.

Keeping a renderer-side `requiredWhen ?? conditionalRequired` would have
re-created the second de-facto contract the tombstone exists to prevent — the
key would keep working in the UI while being rejected everywhere else, hiding
the producer's bug (AGENTS.md #0.1). Backend-agnosticism (#1) does not argue for
keeping it: `conditionalRequired` is an ObjectStack-spec-ism, so the only
producers that emit it are ObjectStack producers on <=16, and the spec ships
them `os migrate meta --from 16`.

Removed from the `FormField` member (types), the `??` fallback and rules-param
member in `resolveFieldRuleState` (core), three form-renderer pass-throughs
(components), `ObjectForm` / `ModalForm` / `sectionFields` / `deriveMasterDetail`
(plugin-form), and the field inspector's legacy read/auto-migrate plus the key's
CEL-lint entry (app-shell).

Studio authors lose nothing: draft validation parses against the spec's own
`ObjectSchema`, so a draft carrying the key now surfaces the tombstone's rename
prescription under the same `fields.<name>.conditionalRequired` path the CEL
lint used to report — a better message than the silent auto-migration, and one
the server agrees with. Pinned by a test.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/drop-conditional-required-alias.md

@@ -0,0 +1,53 @@
+---
+"@object-ui/types": minor
+"@object-ui/core": minor
+"@object-ui/components": minor
+"@object-ui/plugin-form": minor
+"@object-ui/app-shell": minor
+---
+
+refactor(fields): `requiredWhen` is the only required-predicate slot — drop the retired `conditionalRequired` alias
+
+`@objectstack/spec` 17 (objectstack#3855) **retired** `Field.conditionalRequired`,
+the long-deprecated alias of `requiredWhen`. ObjectUI carried a back-compat read
+for it in seven places; all of them are removed.
+
+The removal is safe because the spec did not merely *stop emitting* the key — it
+made authoring it **fail loudly**. `retiredKey()` declares the key as
+`z.never()`, so:
+
+- `z.input` types it as `never` — writing it is a `tsc` error at the authoring site;
+- the parse **rejects** it (verified against `17.0.0-rc.0`), at both `FieldSchema`
+  and `ObjectSchema`, with the prescription as the message:
+
+  > `conditionalRequired` was removed in @objectstack/spec 17 (#3855) — use
+  > `requiredWhen`. Rename the key; the value (a CEL predicate) is unchanged.
+  > Run `os migrate meta --from 16` to rewrite it automatically.
+
+So spec-parsed metadata cannot carry the key — an object declaring it fails to
+load rather than loading with the rule silently dropped. Keeping a renderer-side
+`requiredWhen ?? conditionalRequired` would have re-created exactly the second
+de-facto contract the tombstone exists to prevent: the key would have kept
+working in the UI while being rejected everywhere else, hiding the producer's bug
+(AGENTS.md #0.1). "Backend-agnostic" (#1) does not argue for keeping it either —
+`conditionalRequired` is an ObjectStack-spec-ism, so the only producers that ever
+emit it are ObjectStack producers on ≤16, and the spec ships them a converter.
+
+Removed from:
+
+| package | site |
+| :--- | :--- |
+| `@object-ui/types` | the `conditionalRequired?:` member on `FormField` |
+| `@object-ui/core` | the `??` fallback + rules-param member in `resolveFieldRuleState` |
+| `@object-ui/components` | three pass-throughs in the form renderer |
+| `@object-ui/plugin-form` | `ObjectForm`, `ModalForm`, `sectionFields`, `deriveMasterDetail` (×2) |
+| `@object-ui/app-shell` | the field inspector's legacy read/auto-migrate, and the key's entry in `clientValidation`'s CEL lint list |
+
+**Studio authors lose nothing.** The object designer's draft validation parses
+against the spec's own `ObjectSchema`, so a draft carrying the key now surfaces
+the tombstone's rename prescription under the same `fields.<name>.conditionalRequired`
+path the CEL lint used to report — a better message than the inspector's silent
+auto-migration, and one the server agrees with. That behavior is pinned by a test.
+
+**Migrating:** rename the key to `requiredWhen` (the CEL value is unchanged), or
+run `os migrate meta --from 16`.

content/docs/guide/metadata-diagnostics.md

@@ -139,9 +139,9 @@ field disappears as soon as you start typing in it, then re-validates
 on save.
 
 For **object** drafts the live validation goes beyond the Zod shape check:
-every field conditional rule (`visibleWhen` / `readonlyWhen` / `requiredWhen`,
-plus the deprecated `conditionalRequired` alias) is linted as a CEL predicate
-with the same `@objectstack/formula` validators the server uses. A predicate
+every field conditional rule (`visibleWhen` / `readonlyWhen` / `requiredWhen`)
+is linted as a CEL predicate with the same `@objectstack/formula` validators
+the server uses. A predicate
 that parses but references an unknown field, or references a field bare
 instead of as `record.<field>`, surfaces under its `fields.<field>.<rule>`
 path in the banner. The field inspector's *Conditional rules* editors give

docs/adr/0036-field-conditional-rules.md

@@ -23,7 +23,17 @@ We express them as three optional CEL predicates on `Field`:
 | `readonlyWhen` | the field is read-only                              | **client + server**|
 | `requiredWhen` | the field is required                               | **client + server**|
 
-`conditionalRequired` is a back-compat **alias of `requiredWhen`**.
+> **Amended (2026-07-29) — the `conditionalRequired` alias is gone.**
+> This ADR originally carried `conditionalRequired` as a back-compat **alias of
+> `requiredWhen`**. `@objectstack/spec` 17 (objectstack#3855) *retired* the key:
+> it is tombstoned via `retiredKey()`, so authoring it is both a `tsc` error and
+> a hard parse rejection whose message carries the rename (and
+> `os migrate meta --from 16` rewrites it automatically). Since the producer now
+> rejects the key outright, ObjectUI no longer reads it anywhere — keeping a
+> renderer-side `??` fallback would have re-created the second dialect the
+> tombstone exists to prevent (AGENTS.md #0.1). **`requiredWhen` is the only
+> required-predicate slot.** The paragraphs below are kept as the historical
+> record of the original decision.
 
 ## Why CEL, and why the *same* engine on both ends
 
@@ -47,7 +57,8 @@ import dragged into the bundle.
 - **`requiredWhen`** — `@objectstack/objectql`'s rule-validator evaluates the
   predicate over the *merged* record (`{ ...previous, ...patch }`) and pushes a
   `{ field, code: 'required' }` violation when it is TRUE and the value is
-  missing. `conditionalRequired` is treated identically.
+  missing. (Historical: `conditionalRequired` was treated identically until the
+  spec retired the key — see the amendment above.)
 - **`readonlyWhen`** — `stripReadonlyWhenFields` drops any field from an UPDATE
   payload whose predicate is TRUE for the merged record: the incoming change is
   **ignored** (the persisted value is kept), not rejected. Update paths fetch

packages/app-shell/README.md

@@ -248,9 +248,10 @@ The object designer's field inspector (`ObjectFieldInspector`, Advanced →
   typing `record.` / `previous.` completes the object's own field names.
 - Values round-trip both wire shapes: a bare CEL string or the
   `{ dialect, source }` Expression envelope (envelope extras such as
-  `meta.rationale` are preserved on edit). The deprecated
-  `conditionalRequired` alias is read into the *Required when* editor and
-  migrated to `requiredWhen` on the first edit.
+  `meta.rationale` are preserved on edit). `requiredWhen` is the only
+  required-predicate slot — the `conditionalRequired` alias was removed in
+  `@objectstack/spec` 17 (#3855), so a draft carrying it is rejected by the
+  spec parse itself, with the rename prescription, in the same issue banner.
 - The same lint also runs draft-wide in `clientValidation.ts`
   (`validateMetadataDraft('object', …)`), so an invalid predicate on any
   field — not just the selected one — surfaces in the editor's issue banner

packages/app-shell/src/views/metadata-admin/clientValidation.fieldRules.test.ts

@@ -17,7 +17,7 @@ import { __setCelFormulaLoader } from './celAuthoring';
 
 afterEach(() => __setCelFormulaLoader(undefined));
 
-const RULE_PATH = /^fields\..+\.(visibleWhen|readonlyWhen|requiredWhen|conditionalRequired)$/;
+const RULE_PATH = /^fields\..+\.(visibleWhen|readonlyWhen|requiredWhen)$/;
 
 const draftWith = (fields: unknown) => ({ name: 'account', label: 'Account', fields });
 
@@ -59,12 +59,19 @@ describe('validateMetadataDraft — object field conditional rules (real engine)
     expect(res.issues.filter((i) => RULE_PATH.test(i.path))).toEqual([]);
   });
 
-  it('lints the legacy conditionalRequired alias too', async () => {
+  // `conditionalRequired` is no longer one of OUR lint keys — @objectstack/spec
+  // 17 (#3855) retired it, so the draft is rejected by the spec parse itself,
+  // and the rejection carries the rename prescription. We assert the author
+  // still gets told, and told by the spec (AGENTS.md #0.1 — one contract).
+  it('rejects the retired conditionalRequired alias via the spec tombstone', async () => {
     const res = await validateMetadataDraft(
       'object',
-      draftWith({ status: { type: 'text', conditionalRequired: '{status} == "x"' } }),
+      draftWith({ status: { type: 'text', conditionalRequired: 'record.x == 1' } }),
     );
-    expect(res.issues.some((i) => i.path === 'fields.status.conditionalRequired')).toBe(true);
+    expect(res.ok).toBe(false);
+    const issue = res.issues.find((i) => i.path === 'fields.status.conditionalRequired');
+    expect(issue).toBeTruthy();
+    expect(issue!.message).toMatch(/requiredWhen/);
   });
 
   it('uses index paths for the ARRAY fields shape', async () => {

packages/app-shell/src/views/metadata-admin/clientValidation.ts

@@ -133,7 +133,7 @@ function nodeTypeAt(draft: unknown, index: number): string | undefined {
  * fail-opens at runtime, so we lint the CEL here — the same
  * `@objectstack/formula` verdict the field inspector's editor shows live.
  */
-const FIELD_RULE_KEYS = ['visibleWhen', 'readonlyWhen', 'requiredWhen', 'conditionalRequired'] as const;
+const FIELD_RULE_KEYS = ['visibleWhen', 'readonlyWhen', 'requiredWhen'] as const;
 
 /** Extract a predicate's CEL source from either wire shape (string | envelope). */
 function predicateSource(v: unknown): string | null {

packages/app-shell/src/views/metadata-admin/inspectors/ObjectFieldInspector.test.tsx

@@ -257,17 +257,14 @@ describe('ObjectFieldInspector — conditional rules (CEL editors, #1582)', () =
     expect(onPatch.mock.calls.at(-1)![0].fields.note.visibleWhen).toBeUndefined();
   });
 
-  it('reads legacy conditionalRequired into Required when and migrates it on edit', () => {
+  // The retired `conditionalRequired` alias (@objectstack/spec 17, #3855) is no
+  // longer read into the editor: it is not a required-predicate slot, and a
+  // draft carrying it is rejected by the spec parse with the rename
+  // prescription (see clientValidation.fieldRules.test.ts).
+  it('does not read the retired conditionalRequired alias into Required when', () => {
     stubEngine();
-    const { onPatch } = renderField(
-      { note: { type: 'text', conditionalRequired: 'record.x == 1' } },
-      'note',
-    );
-    expect(controlFor('Required when')).toHaveValue('record.x == 1');
-    fireEvent.change(controlFor('Required when'), { target: { value: 'record.x == 2' } });
-    const field = onPatch.mock.calls.at(-1)![0].fields.note;
-    expect(field.requiredWhen).toBe('record.x == 2');
-    expect(field.conditionalRequired).toBeUndefined();
+    renderField({ note: { type: 'text', conditionalRequired: 'record.x == 1' } }, 'note');
+    expect(controlFor('Required when')).toHaveValue('');
   });
 });
 

packages/app-shell/src/views/metadata-admin/inspectors/ObjectFieldInspector.tsx

@@ -641,15 +641,8 @@ export function ObjectFieldInspector({
           <CelPredicateField
             id={`field-rule-required-${entry.name}`}
             label={tr('designer.field.requiredWhen')}
-            // Legacy alias: `conditionalRequired` (spec @deprecated) reads into
-            // the same editor; the first edit migrates it to `requiredWhen`.
-            value={readPredicate(def.requiredWhen ?? def.conditionalRequired)}
-            onChange={(v) =>
-              patchDef({
-                requiredWhen: writePredicate(def.requiredWhen ?? def.conditionalRequired, v),
-                conditionalRequired: undefined,
-              })
-            }
+            value={readPredicate(def.requiredWhen)}
+            onChange={(v) => patchDef({ requiredWhen: writePredicate(def.requiredWhen, v) })}
             disabled={readOnly}
             placeholder="record.amount > 10000"
             objectName={typeof (draft as any).name === 'string' ? ((draft as any).name as string) : undefined}

packages/components/src/renderers/form/form.tsx

@@ -374,7 +374,6 @@ ComponentRegistry.register('form',
             visibleWhen: (f as any).visibleWhen,
             readonlyWhen: (f as any).readonlyWhen,
             requiredWhen: (f as any).requiredWhen,
-            conditionalRequired: (f as any).conditionalRequired,
           },
           ruleRecord,
           { required: !!f.required, readonly: (f as any).readonly === true },
@@ -733,7 +732,6 @@ ComponentRegistry.register('form',
                   visibleWhen,
                   readonlyWhen,
                   requiredWhen,
-                  conditionalRequired,
                   ...fieldProps
                 } = field;
 
@@ -756,7 +754,7 @@ ComponentRegistry.register('form',
                 // the UX and the persisted verdict agree. A field with no rules
                 // resolves to its static flags unchanged.
                 const ruleState = resolveFieldRuleState(
-                  { visibleWhen, readonlyWhen, requiredWhen, conditionalRequired },
+                  { visibleWhen, readonlyWhen, requiredWhen },
                   ruleRecord,
                   { required: staticRequired, readonly: staticReadonly === true },
                 );

packages/core/src/evaluator/__tests__/fieldRules.test.ts

@@ -106,18 +106,17 @@ describe('resolveFieldRuleState', () => {
     expect(s.required).toBe(true);
   });
 
-  it('honors conditionalRequired as a requiredWhen alias', () => {
-    const s = resolveFieldRuleState({ conditionalRequired: "record.status == 'sent'" }, { status: 'sent' }, {});
-    expect(s.required).toBe(true);
-  });
-
-  it('prefers requiredWhen over conditionalRequired when both present', () => {
-    const s = resolveFieldRuleState(
-      { requiredWhen: "record.status == 'sent'", conditionalRequired: 'record.amount > 0' },
-      { status: 'draft', amount: 5 },
-      {},
-    );
-    // requiredWhen (status=='sent') is FALSE → not required; the alias is ignored.
+  // `conditionalRequired` was the pre-protocol-17 alias of `requiredWhen`.
+  // @objectstack/spec 17 (#3855) tombstoned it with `retiredKey`, so authoring
+  // it is now a `tsc` error AND a hard parse rejection carrying the rename
+  // prescription — it can never reach this evaluator from parsed metadata.
+  // `requiredWhen` is the only required-predicate slot (AGENTS.md #0.1).
+  it('ignores the retired conditionalRequired alias', () => {
+    // Deliberately a shape the parameter type no longer permits.
+    const legacyRules = { conditionalRequired: "record.status == 'sent'" } as unknown as Parameters<
+      typeof resolveFieldRuleState
+    >[0];
+    const s = resolveFieldRuleState(legacyRules, { status: 'sent' }, {});
     expect(s.required).toBe(false);
   });