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

* 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

* chore(spec): register cbp-master-detail-required-forced (protocol 18) + changeset (#9138)

ADR-0087 disposition: registered. The semantic entry carries the FROM -> TO
prescription; spec-changes.json and the upgrade guide project only released
majors, so they are byte-identical until the v18 cut (verified by regenerating
both).

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

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-project-manager

.changeset/cbp-master-detail-required-forced.md

@@ -0,0 +1,59 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): the builder forces `required: true` on a `master_detail` reference under `controlled_by_parent` (#9138 — #8772 maintainer ruling, Direction 2)
+
+**BREAKING** accept-face narrowing on the authoring builder, landing after the
+v17.0.0 cut (the lockstep launch-window convention ships it as `minor`; the
+prescription is registered under protocol major 18, where `os migrate meta`
+users will look).
+
+A `controlled_by_parent` object derives ALL of its record access from the
+master its `master_detail` reference names (ADR-0055). A master reference that
+is not `required` arms the worst measured failure shape: an insert may omit
+the master FK, the row lands with a null FK that the derived read filter
+(`masterFK IN (accessible master ids)`) can never match — unreadable by
+everyone — and every later by-id write answers `422 MISSING_REQUIRED_FIELD`.
+#8772 measured that only the security gate closed that shape while the
+declaration surface accepted it.
+
+`ObjectSchema.create()` now makes the unsafe shape impossible to newly
+declare:
+
+- an **omitted** `required` on a `master_detail` reference under
+  `sharingModel: 'controlled_by_parent'` is **forced to `true`** in the
+  emitted object;
+- an **explicit `required: false`** there is **refused** with a located error
+  naming the object, the field, the consequence and the fix — an explicitly
+  authored contradiction is not silently rewritten (ADR-0032).
+
+## FROM → TO
+
+```ts
+// before — parsed green; the null-FK trap stayed armed behind the security gate
+export const InvoiceLine = ObjectSchema.create({
+  name: 'invoice_line',
+  sharingModel: 'controlled_by_parent',
+  fields: { invoice: { type: 'master_detail', reference: 'invoice', required: false } },
+});
+
+// after — refused at build with the prescription; omitting `required` is fine
+// (the builder emits `required: true` by construction)
+export const InvoiceLine = ObjectSchema.create({
+  name: 'invoice_line',
+  sharingModel: 'controlled_by_parent',
+  fields: { invoice: { type: 'master_detail', reference: 'invoice', required: true } },
+});
+```
+
+**What stays accepted:** everything outside that one shape. Raw
+`ObjectSchema.parse()` / `.safeParse()` — the path metadata at rest rehydrates
+through — still accept the old shape unrewritten, so existing installs keep
+loading; the security gate's derived enforcement stays; the lint rule
+`relationship/master-detail-required` stays `warning` until its own v18
+promotion (#9139). The 2026-08-15 survey measured the shipped first-party
+surface at exactly 3 `controlled_by_parent` objects, all already
+`required: true` — zero first-party migration.
+
+<!-- adr-0087: registered cbp-master-detail-required-forced -->

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

packages/spec/src/migrations/entries/semantic/18.cbp-master-detail-required-forced.ts

@@ -0,0 +1,36 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { SemanticMigration } from '../../types.js';
+
+export const entry: SemanticMigration = {
+  id: 'cbp-master-detail-required-forced',
+  surface: 'object.fields.<master>.required on a `master_detail` reference under '
+    + '`sharingModel: \'controlled_by_parent\'` — authored via `ObjectSchema.create()`',
+  replacement: '`required: true` on the master reference (or nothing at all — the builder now '
+    + 'forces `required: true` when the key is omitted). An explicit `required: false` on that '
+    + 'shape is refused at `ObjectSchema.create()` with a located error carrying this same '
+    + 'prescription. Metadata at rest is untouched: raw `.parse()`/`.safeParse()` still accept '
+    + 'the old shape, the security gate\'s derived enforcement stays, and the lint rule '
+    + '`relationship/master-detail-required` stays `warning` until its own v18 promotion '
+    + '(#8772 Direction 1)',
+  reason:
+    'A `controlled_by_parent` detail derives ALL of its record access from the master that its '
+    + '`master_detail` reference names (ADR-0055). With the reference not `required`, an insert '
+    + 'may omit the master FK: the row lands with a null FK that the derived read filter '
+    + '`masterFK IN (accessible master ids)` can never match — unreadable by everyone — and '
+    + 'every later by-id write answers `422 MISSING_REQUIRED_FIELD`. #8772 measured that only '
+    + 'the security gate closed this shape while the declaration surface still accepted it. '
+    + 'The maintainer ruling (2026-08-16, Direction 2) makes the unsafe shape impossible to '
+    + 'NEWLY declare at the builder; whether to keep `required: false` was never a real choice '
+    + '(the value contradicts the sharing model), so the flip is forced rather than convertible '
+    + '— and an explicitly authored `false` is refused rather than silently rewritten '
+    + '(ADR-0032 "no silent failure").',
+  acceptanceCriteria:
+    'Every `ObjectSchema.create()` call declaring `sharingModel: \'controlled_by_parent\'` '
+    + 'either omits `required` on its `master_detail` reference(s) (now emitted as '
+    + '`required: true`) or declares `required: true` explicitly; the authored app builds and '
+    + 'boots. An explicit `required: false` there fails the build with '
+    + '`ObjectSchema.create(...): field ... declares required: false on a master_detail '
+    + 'reference under sharingModel: controlled_by_parent`. Stored metadata keeps loading '
+    + 'byte-identically (`safeParse` green, `required` unrewritten).',
+};

packages/spec/src/migrations/registry.ts

@@ -4962,6 +4962,38 @@ const step18: MigrationStep = {
         + 'every `/analytics/query` body\'s `timeDimensions[]` items carry only '
         + '`dimension`/`granularity`/`dateRange`. Declared keys parse byte-identically to before.',
     },
+    {
+      id: 'cbp-master-detail-required-forced',
+      surface: 'object.fields.<master>.required on a `master_detail` reference under '
+        + '`sharingModel: \'controlled_by_parent\'` — authored via `ObjectSchema.create()`',
+      replacement: '`required: true` on the master reference (or nothing at all — the builder now '
+        + 'forces `required: true` when the key is omitted). An explicit `required: false` on that '
+        + 'shape is refused at `ObjectSchema.create()` with a located error carrying this same '
+        + 'prescription. Metadata at rest is untouched: raw `.parse()`/`.safeParse()` still accept '
+        + 'the old shape, the security gate\'s derived enforcement stays, and the lint rule '
+        + '`relationship/master-detail-required` stays `warning` until its own v18 promotion '
+        + '(#8772 Direction 1)',
+      reason:
+        'A `controlled_by_parent` detail derives ALL of its record access from the master that its '
+        + '`master_detail` reference names (ADR-0055). With the reference not `required`, an insert '
+        + 'may omit the master FK: the row lands with a null FK that the derived read filter '
+        + '`masterFK IN (accessible master ids)` can never match — unreadable by everyone — and '
+        + 'every later by-id write answers `422 MISSING_REQUIRED_FIELD`. #8772 measured that only '
+        + 'the security gate closed this shape while the declaration surface still accepted it. '
+        + 'The maintainer ruling (2026-08-16, Direction 2) makes the unsafe shape impossible to '
+        + 'NEWLY declare at the builder; whether to keep `required: false` was never a real choice '
+        + '(the value contradicts the sharing model), so the flip is forced rather than convertible '
+        + '— and an explicitly authored `false` is refused rather than silently rewritten '
+        + '(ADR-0032 "no silent failure").',
+      acceptanceCriteria:
+        'Every `ObjectSchema.create()` call declaring `sharingModel: \'controlled_by_parent\'` '
+        + 'either omits `required` on its `master_detail` reference(s) (now emitted as '
+        + '`required: true`) or declares `required: true` explicitly; the authored app builds and '
+        + 'boots. An explicit `required: false` there fails the build with '
+        + '`ObjectSchema.create(...): field ... declares required: false on a master_detail '
+        + 'reference under sharingModel: controlled_by_parent`. Stored metadata keeps loading '
+        + 'byte-identically (`safeParse` green, `required` unrewritten).',
+    },
     {
       id: 'dashboard-header-modal-target-page-only',
       surface: