docs: MISSING_REQUIRED_FIELD answers 422 without fields[] on the surviving controlled_by_parent refusals (#8880) (#8963)

`MISSING_REQUIRED_FIELD` is documented as HTTP 400 carrying `fields[]`
(`error-handling.mdx`, `error-catalog.mdx`), but `assertControlledByParentWrite`
answers `422 MISSING_REQUIRED_FIELD` with no `fields[]` on four declarable
shapes, plus a stored-row case on a different path. Documents the exception
where it exists rather than moving the wire.

Measured on this branch's base rather than taken from the card:

  - `resolveCbpRelation` sets `omissionRefusedByValidation` to
    `type === 'master_detail' && required && !readonly && !system`, so only
    that shape hands over to validation's `400 VALIDATION_FAILED`.
  - The four surviving shapes are pinned by
    `controlled-by-parent-sharing.test.ts` (`err.status`/`statusCode` 422).
  - `MasterReferenceMissingError` declares `code`/`status`/`statusCode`;
    `mapDataError`'s 4xx passthrough emits `{ error, code, object }`, and
    `fields[]` is emitted only for the `VALIDATION_FAILED` duck-type — so the
    absent `fields[]` is confirmed at the door, not assumed.

One claim from the card and the #8879 changeset is deliberately NOT repeated:
that a publish-time lint bounds these shapes. #8772 is still open and
`relationship/master-detail-required` is `severity: 'warning'`, with no rule
covering the `readonly`/`system`/fallback-`lookup` shapes — so the docs say
these shapes are authorable today. Filed as #8959.

No runtime change: the refusal is correct (an unconditional hand-over was
measured fail-open) and direction 2 was declined by the maintainer ruling.


Claude-Session: https://claude.ai/code/session_011RB4waLuNbdruCo6X9oobm

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

Author: os-project-manager

content/docs/api/error-catalog.mdx

@@ -86,9 +86,48 @@ substitute. See the [Data API](/docs/api/data-api).
 
 ### `MISSING_REQUIRED_FIELD`
 **Cause:** A required field was not provided in the request body.  
-**Fix:** Include the missing field. Check `fields` for the field name.  
+**Fix:** Include the missing field. Check `fields` for the field name — **except** on the
+`controlled_by_parent` master-reference paths below, where the status is `422` and no
+`fields` array is sent; read the field name out of the message there.  
 **Retry:** `no_retry`
 
+<Callout type="warn">
+**`MISSING_REQUIRED_FIELD` is `400` with one exception: an absent `controlled_by_parent`
+master reference answers `422`, without `fields`.**
+
+An object whose `sharingModel` is `controlled_by_parent` derives its access from a master
+record, so the gate authorizing writes to it resolves that master *before* the executor —
+and the executor is where required-field validation runs. Which of the two refuses first
+depends on how the master reference is declared. A `master_detail` that is `required` and
+neither `readonly` nor `system` reaches validation and answers the documented
+`400 VALIDATION_FAILED` with `fields`. The other four declarable shapes never reach it and
+answer `422 MISSING_REQUIRED_FIELD` with no `fields`:
+
+- a `master_detail` with no `required`
+- a `master_detail` that is `required` + `readonly`
+- a `master_detail` that is `required` + `system`
+- a `required` `lookup`, when the object declares no `master_detail`
+
+The full matrix is on the protocol page:
+[`MISSING_REQUIRED_FIELD`](/docs/protocol/kernel/error-handling#missing_required_field).
+
+An update or delete **by id** whose *stored* master reference is null answers the same
+`422`, whatever the declaration — the caller sent no such field, so nothing could be named
+in `fields` and no payload would fix it.
+
+The refusal itself is correct and is not going to be relaxed: on those four shapes
+required-field validation does not fire (it skips `system` and `readonly` fields before its
+required check, and never fires on a field that is not `required`), so the gate is the only
+thing standing between the request and a detail record with a null master reference — which
+the `controlled_by_parent` read filter (`fk IN (readable masters)`) can never match, leaving
+a record readable by nobody.
+
+These shapes are **authorable today**: lint reports a `master_detail` without `required` as
+a warning only, and does not report the `readonly`, `system`, or fallback-`lookup` shapes at
+all. **Branch on `code`, treat `fields` as optional, and read the status off the response**
+rather than deriving it from the table at the end of this page.
+</Callout>
+
 ### `INVALID_FORMAT`
 **Cause:** Field value does not match the expected format (e.g., invalid email, wrong date format).  
 **Fix:** Ensure the value matches the field's `format` constraint or built-in type validation.  
@@ -632,6 +671,7 @@ async function handleApiCall() {
 | 403 | `authorization` | `PERMISSION_DENIED`, `FIELD_NOT_ACCESSIBLE`, `LICENSE_REQUIRED` |
 | 404 | `not_found` | `RECORD_NOT_FOUND`, `OBJECT_NOT_FOUND`, `ENDPOINT_NOT_FOUND` |
 | 409 | `conflict` | `CONCURRENT_MODIFICATION`, `DUPLICATE_RECORD`, `DELETE_RESTRICTED` |
+| 422 | `validation` | `MISSING_REQUIRED_FIELD` on an absent `controlled_by_parent` master reference (see [above](#missing_required_field)) — this row is an exception to the 400 row, not a second home for the code |
 | 429 | `rate_limit` | `RATE_LIMIT_EXCEEDED`, `QUOTA_EXCEEDED` |
 | 500 | `server` | `INTERNAL_ERROR`, `DATABASE_ERROR`, `TIMEOUT` |
 | 502 | `external` | `EXTERNAL_SERVICE_ERROR`, `INTEGRATION_ERROR` |

content/docs/protocol/kernel/error-handling.mdx

@@ -90,7 +90,7 @@ ObjectStack uses standard HTTP status codes:
 | **403** | Forbidden | Authenticated but insufficient permissions |
 | **404** | Not Found | Resource doesn't exist |
 | **409** | Conflict | Resource already exists or version mismatch |
-| **422** | Unprocessable Entity | Semantic validation failed (e.g. metadata spec validation) |
+| **422** | Unprocessable Entity | Semantic validation failed (e.g. metadata spec validation); also an absent `controlled_by_parent` master reference — see [`MISSING_REQUIRED_FIELD`](#missing_required_field) |
 | **429** | Too Many Requests | Rate limit exceeded |
 | **500** | Internal Server Error | Server-side error |
 | **503** | Service Unavailable | Server overloaded or maintenance |
@@ -244,7 +244,7 @@ if (error.code === 'VALIDATION_ERROR') {
 ```
 
 #### `MISSING_REQUIRED_FIELD`
-**HTTP Status:** 400  
+**HTTP Status:** 400 — with one documented exception, which answers **422** (see below)  
 **Meaning:** Required field is missing
 
 **Example:**
@@ -262,6 +262,45 @@ if (error.code === 'VALIDATION_ERROR') {
 }
 ```
 
+**Exception — an absent `controlled_by_parent` master reference answers 422 with no `fields`.**
+An object whose `sharingModel` is `controlled_by_parent` derives its access from a master
+record, so the gate that authorizes writes to it must resolve that master *before* the
+executor runs — and the executor is where required-field validation lives. When the master
+reference is absent, whichever of the two refuses first decides the envelope, and that
+depends on how the reference is declared:
+
+| Master reference declared as | Refused by | Status | `code` | `fields` |
+|---|---|:---:|---|:---:|
+| `master_detail` + `required`, not `readonly`/`system` | required-field validation | 400 | `VALIDATION_FAILED` | yes |
+| `master_detail` with no `required` | the master-access gate | **422** | `MISSING_REQUIRED_FIELD` | **absent** |
+| `master_detail` + `required` + `readonly` | the master-access gate | **422** | `MISSING_REQUIRED_FIELD` | **absent** |
+| `master_detail` + `required` + `system` | the master-access gate | **422** | `MISSING_REQUIRED_FIELD` | **absent** |
+| a `required` `lookup`, when the object declares no `master_detail` | the master-access gate | **422** | `MISSING_REQUIRED_FIELD` | **absent** |
+
+Only the first row is the documented 400 shape. On the other four, messages are prefixed
+`[Security] Missing master reference:` and name the object and the field, but no `fields`
+array rides along.
+
+The same `422 MISSING_REQUIRED_FIELD` also answers an update or delete **by id** whose
+*stored* master reference is null, whatever the declaration. That is a different path: the
+caller supplied no such field, so there is no request field to name in `fields` and no
+payload that would fix it.
+
+**Why the gate refuses rather than handing over.** Required-field validation skips
+provenance-flagged fields before its required check is reached (`system` and `readonly`
+fields are skipped outright) and never fires on a field that is not `required` at all. On
+those four shapes the gate is the only thing refusing the write, and letting it through was
+measured to create a detail record whose master reference is null — a record the
+`controlled_by_parent` read filter (`fk IN (readable masters)`) can never match, so it is
+readable by nobody and answers 422 on every later write by id. The refusal is correct; only
+its status departs from the rule above.
+
+**These shapes are authorable today.** Publish-time lint reports a `master_detail` without
+`required` as a *warning* (`relationship/master-detail-required`), and does not report the
+`readonly`, `system`, or fallback-`lookup` shapes at all — so a stack can publish clean and
+still reach the 422. Branch on `code`, and read the status off the response rather than
+deriving it from this page.
+
 #### `INVALID_FIELD`
 **HTTP Status:** 400  
 **Meaning:** Field value has wrong type