feat(spec): builder forces required: true on a master_detail reference under controlled_by_parent (#9138)

Direction 2 of the #8772 maintainer ruling (2026-08-16, comment 5306089973):
ObjectSchema.create() now forces required: true on every master_detail
reference of a sharingModel: 'controlled_by_parent' object when the author
omits it, and refuses an explicit required: false there with a located,
prescriptive error. Raw .parse()/.safeParse() stay tolerant — metadata at
rest keeps loading unrewritten; runtime (resolveCbpRelation) and lint
severity are deliberately untouched (they are separate ruled slices).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y26DJEHSBhhAQ6wwfsHNza

Author: claude

packages/spec/src/data/object.test.ts

@@ -8,6 +8,7 @@ import { describe, it, expect, vi, afterEach } from 'vitest';
 // (#5286).
 import { ObjectSchema, ObjectCapabilities, IndexSchema, ObjectFieldGroupSchema, ObjectExternalBindingSchema, ObjectAccessConfigSchema, LifecycleSchema, TenancyConfigSchema, isTenancyDisabled, resolveCrudAffordances, type ServiceObject } from './object.zod';
 import { resolveInjectedSystemColumns } from './injected-system-columns';
+import { Field } from './field.zod';
 import type { StateMachineValidation } from './validation.zod';
 
 describe('ObjectCapabilities', () => {
@@ -1216,6 +1217,134 @@ describe('ObjectSchema.create()', () => {
   });
 });
 
+// ============================================================================
+// controlled_by_parent × master_detail — the builder forces `required: true`
+// (#9138 — #8772 maintainer ruling, Direction 2 / ADR-0055)
+// ============================================================================
+
+describe('ObjectSchema.create() forces a required master_detail under controlled_by_parent (#9138)', () => {
+  it('forces required: true when `required` is omitted on the master reference', () => {
+    const obj = ObjectSchema.create({
+      name: 'cbp_line',
+      sharingModel: 'controlled_by_parent',
+      fields: {
+        parent: { type: 'master_detail', reference: 'cbp_header' },
+        note: { type: 'text' },
+      },
+    });
+    const fields = obj.fields as Record<string, { required?: boolean }>;
+    expect(fields.parent.required).toBe(true);
+    // Scope: only the master reference is forced — sibling fields keep the
+    // ordinary default (required: false).
+    expect(fields.note.required).toBe(false);
+  });
+
+  it('preserves an explicit required: true and the rest of the field config', () => {
+    const obj = ObjectSchema.create({
+      name: 'cbp_line_explicit',
+      sharingModel: 'controlled_by_parent',
+      fields: {
+        parent: Field.masterDetail('cbp_header', {
+          label: 'Header',
+          required: true,
+          deleteBehavior: 'cascade',
+        }),
+      },
+    });
+    const parent = (obj.fields as Record<string, Record<string, unknown>>).parent;
+    expect(parent.required).toBe(true);
+    expect(parent.deleteBehavior).toBe('cascade');
+    expect(parent.label).toBe('Header');
+  });
+
+  it('forces the Field.masterDetail helper shape too (the helper omits required)', () => {
+    const obj = ObjectSchema.create({
+      name: 'cbp_line_helper',
+      sharingModel: 'controlled_by_parent',
+      fields: { parent: Field.masterDetail('cbp_header', { label: 'Header' }) },
+    });
+    expect((obj.fields as Record<string, { required?: boolean }>).parent.required).toBe(true);
+  });
+
+  it('REFUSES an explicit required: false, loudly, naming object + field + the fix', () => {
+    let message = '';
+    try {
+      ObjectSchema.create({
+        name: 'cbp_bad',
+        sharingModel: 'controlled_by_parent',
+        fields: {
+          parent: { type: 'master_detail', reference: 'cbp_header', required: false },
+        },
+      });
+      throw new Error('expected ObjectSchema.create to refuse required: false under controlled_by_parent');
+    } catch (e) {
+      message = (e as Error).message;
+    }
+    expect(message).not.toContain('expected ObjectSchema.create to refuse');
+    expect(message).toContain("ObjectSchema.create('cbp_bad')");
+    expect(message).toContain('`parent`');
+    expect(message).toContain('required: false');
+    expect(message).toContain('controlled_by_parent');
+    // The message carries the prescription, not just the verdict.
+    expect(message).toContain('Remove `required: false`');
+    expect(message).toContain('change its `sharingModel`');
+  });
+
+  it('forces EVERY master_detail reference under the object, not just the first', () => {
+    // The prose contract is "exactly one required master_detail", but nothing
+    // enforces the count today (#7474 owns the zero-reference case at publish);
+    // forcing each declared reference keeps every candidate safe rather than
+    // silently blessing only the first.
+    const obj = ObjectSchema.create({
+      name: 'cbp_multi',
+      sharingModel: 'controlled_by_parent',
+      fields: {
+        a: { type: 'master_detail', reference: 'master_a' },
+        b: { type: 'master_detail', reference: 'master_b' },
+      },
+    });
+    const fields = obj.fields as Record<string, { required?: boolean }>;
+    expect(fields.a.required).toBe(true);
+    expect(fields.b.required).toBe(true);
+  });
+
+  it('leaves master_detail on a NON-controlled_by_parent object alone (scope pin)', () => {
+    const omitted = ObjectSchema.create({
+      name: 'plain_line',
+      fields: { parent: { type: 'master_detail', reference: 'plain_header' } },
+    });
+    expect((omitted.fields as Record<string, { required?: boolean }>).parent.required).toBe(false);
+
+    const explicit = ObjectSchema.create({
+      name: 'plain_line_explicit',
+      sharingModel: 'private',
+      fields: { parent: { type: 'master_detail', reference: 'plain_header', required: false } },
+    });
+    expect((explicit.fields as Record<string, { required?: boolean }>).parent.required).toBe(false);
+  });
+
+  it('raw .parse()/.safeParse() stay TOLERANT of the old shape — metadata at rest keeps loading', () => {
+    // The other half of the #8772 ruling: the narrowing is authoring-time
+    // only. Stored metadata rehydrated through the schema (never through the
+    // builder) must keep loading, UNREWRITTEN — runtime tolerance for existing
+    // installs stays with the security gate, and the lint rule stays `warning`
+    // until the v18 card (#9139) promotes it.
+    const atRest = {
+      name: 'cbp_stored',
+      sharingModel: 'controlled_by_parent',
+      fields: {
+        parent: { type: 'master_detail', reference: 'cbp_header', required: false },
+      },
+    };
+    const result = ObjectSchema.safeParse(atRest);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      const fields = (result.data as { fields: Record<string, { required?: boolean }> }).fields;
+      expect(fields.parent.required).toBe(false);
+    }
+  });
+});
+
 // ============================================================================
 // Namespace removal (D4) — Object identity is single-sourced on `name`.
 // ============================================================================

packages/spec/src/data/object.zod.ts

@@ -2249,6 +2249,76 @@ function assertSystemDataIsWritable(
   );
 }
 
+/**
+ * [#9138 — #8772 maintainer ruling, Direction 2 / ADR-0055] Under
+ * `sharingModel: 'controlled_by_parent'` the builder FORCES `required: true`
+ * on every `master_detail` reference, and REFUSES an explicit
+ * `required: false` there, loudly.
+ *
+ * Why: a `controlled_by_parent` detail's access is *derived* from its master
+ * through that reference (the `sharingModel` docblock above already states
+ * "exactly one required `master_detail` field"). A non-required master
+ * reference arms the worst measured failure shape: an insert may omit the
+ * master FK, the row lands with a null FK, the derived read filter
+ * `masterFK IN (accessible master ids)` can never match null — the row is
+ * invisible to everyone — and every later by-id write answers
+ * `422 MISSING_REQUIRED_FIELD`. Today only the security gate
+ * (`assertControlledByParentWrite`) closes that shape, and #8772 measured that
+ * the declaration and the enforcement disagree. This makes the unsafe shape
+ * impossible to NEWLY declare:
+ *
+ * - omitted `required` → forced to `true` (the lint rule
+ *   `relationship/master-detail-required` already computes exactly this fix);
+ * - explicit `required: false` → refused with a located error — the author
+ *   wrote a contradiction, and silently flipping an explicitly authored value
+ *   would hide it (ADR-0032 "no silent failure").
+ *
+ * Lives at `create()` — the authoring surface (ADR-0077) — beside
+ * {@link assertSystemDataIsWritable}, and deliberately NOT in raw
+ * `.parse()`/`.safeParse()`: metadata already at rest must keep loading.
+ * Runtime tolerance is the other half of the #8772 ruling — the security
+ * gate's fallbacks stay, and the lint rule stays `warning` until v18 — so
+ * publish-time refuses new declarations while runtime tolerates old ones.
+ *
+ * Alias spellings (`isRequired` / `mandatory` / `notNull`) need no handling
+ * here: `FieldSchema` is a `strictObject`, so those keys are refused at parse
+ * with a rename suggestion — they can never land a `required: false` this
+ * check would miss. A non-boolean `required` is left for Zod to report as the
+ * real type error.
+ */
+function forceCbpMasterDetailRequired(
+  objectName: unknown,
+  sharingModel: unknown,
+  fields: unknown,
+): unknown {
+  if (sharingModel !== 'controlled_by_parent') return fields;
+  if (!fields || typeof fields !== 'object' || Array.isArray(fields)) return fields;
+  let out: Record<string, unknown> | undefined;
+  for (const [fieldName, def] of Object.entries(fields as Record<string, unknown>)) {
+    if (!def || typeof def !== 'object' || Array.isArray(def)) continue;
+    const field = def as Record<string, unknown>;
+    if (field.type !== 'master_detail') continue;
+    if (field.required === true) continue;
+    if (field.required === false) {
+      const name = typeof objectName === 'string' && objectName.length > 0 ? objectName : '<unnamed>';
+      throw new Error(
+        `ObjectSchema.create('${name}'): field \`${fieldName}\` declares \`required: false\` on a `
+        + "`master_detail` reference under `sharingModel: 'controlled_by_parent'` — a contradiction "
+        + 'with no honest reading (#8772). A controlled-by-parent detail derives ALL of its record '
+        + 'access from the master this field names (ADR-0055); a row allowed to omit the master FK '
+        + 'is unreadable by everyone (the derived filter `masterFK IN (accessible master ids)` '
+        + 'never matches null) and unwritable thereafter. Remove `required: false` (the builder '
+        + 'declares the reference required by construction), or if this object is not a '
+        + 'master-detail child, change its `sharingModel`.',
+      );
+    }
+    if (field.required !== undefined) continue;
+    out ??= { ...(fields as Record<string, unknown>) };
+    out[fieldName] = { ...field, required: true };
+  }
+  return out ?? fields;
+}
+
 /**
  * [ADR-0079] Back-compat alias normalization: an object authored with the
  * deprecated `displayNameField` key still parses by mapping it onto the
@@ -2368,8 +2438,15 @@ export const ObjectSchema = lazySchema(() => {
     // contradiction with no honest reading — refuse it here, where it is cheap
     // to fix, rather than shipping a bucket whose name lies again.
     assertSystemDataIsWritable(cfg.name, cfg.managedBy, cfg.userActions);
+    // [#9138 — #8772 ruling, Direction 2] A `controlled_by_parent` object's
+    // `master_detail` reference is forced `required: true` (an explicit
+    // `required: false` throws, loudly) so the unsafe shape cannot be newly
+    // declared. Raw `.parse()`/`.safeParse()` stay tolerant for metadata at
+    // rest — see the function's docblock.
+    const forcedFields = forceCbpMasterDetailRequired(cfg.name, cfg.sharingModel, cfg.fields);
     const withDefaults = {
       ...cfg,
+      ...(forcedFields === cfg.fields ? {} : { fields: forcedFields }),
       label: cfg.label ?? snakeCaseToLabel(cfg.name as string),
     };
     // [ADR-0079] `ObjectSchemaBase.parse` here is the alias-normalizing override