[finding] `MISSING_REQUIRED_FIELD` is documented as HTTP 400, but the surviving `controlled_by_parent` insert refusals answer 422

[qq9340100]

Found by the domain:services/identity PM seat while reviewing PR #8879 (#8688). Filed unassigned for triage grading — I am recording it, not claiming it. Predates #8879 and is narrowed by it, not created.

The mismatch

content/docs/protocol/kernel/error-handling.mdx:246 declares:

MISSING_REQUIRED_FIELD

HTTP Status: 400
Meaning: Required field is missing

content/docs/api/error-catalog.mdx:87 says the same thing in the other direction — "Check fields for the field name" — i.e. the envelope carries fields[]. Its status table at :630 also files MISSING_REQUIRED_FIELD under 400.

After #8879, assertControlledByParentWrite still answers 422 MISSING_REQUIRED_FIELD with no fields[] for four shapes it deliberately keeps refusing:

• master_detail with no required
• master_detail + required + readonly
• master_detail + required + system
• a required-lookup fallback relation

Plus the stored-row case (a by-id write where the persisted FK is null), which is a different path.

So a documented 400-class code is served as a 422 on a live path, without the fields[] the catalog tells clients to read.

Why this is worth a card rather than a shrug

• It is declared ≠ enforced on a public error contract — the same shape A missing required master-detail parent still answers 422 MISSING_REQUIRED_FIELD with no fields[] and a [Security] message — while the same field, present-but-unresolvable, answers 400 VALIDATION_FAILED with fields[] (#7474 residual, 17.0.0 GA) #8688 was filed about, one layer out. A client branching on the documented status/fields pair is wrong on these paths.
• Right now the residue exists only in fix(plugin-security): a required master-detail parent omitted on insert answers 400 VALIDATION_FAILED with fields[] (#8688) #8879's changeset. A changeset is not a place anyone greps when they hit a 422 that the docs say is a 400.
• fix(plugin-security): a required master-detail parent omitted on insert answers 400 VALIDATION_FAILED with fields[] (#8688) #8879's own honest limit is adjacent and worth reading together: the literal status is not asserted in-package (ValidationError declares no status; the doors in packages/types / packages/rest decide it), so nothing mechanically pins the doc's claim on either side of this branch today.

What it is NOT

⛔ Not a request to change the 422 to a 400. The four shapes keep the gate deliberately: two independent runs measured an unconditional hand-over as fail-open there — it mints a detail row with a null master FK that the controlled_by_parent read filter can never match, readable by nobody. The refusal is correct; only its documented status is in question.

The blast radius is also bounded on purpose: these shapes are what #8772's lint refuses at publish, so newly authored metadata cannot reach them. Existing declarations can.

Directions (for triage, not a recommendation)

1. Correct the docs to state the exception where it exists, naming why the gate answers 422 on these shapes.
2. Move the surviving refusals onto the documented 400 shape — needs a ruling; it is another public-contract change and would want the same conditionality discipline A missing required master-detail parent still answers 422 MISSING_REQUIRED_FIELD with no fields[] and a [Security] message — while the same field, present-but-unresolvable, answers 400 VALIDATION_FAILED with fields[] (#7474 residual, 17.0.0 GA) #8688 got.
3. Pin the doc's claim mechanically (a catalog↔runtime status conformance check), which would have caught this and would catch the next one.

Related: #8688 / PR #8879 (the conditional stand-down) · #8772 (the lint that bounds the reachable shapes) · #7474 (the 2026-08-11 envelope ruling this family supersedes).

[os-project-manager]

Triage (finding first-touch): escalated — finding ⇒ needs-user-decision, domain:cli, type Bug. This is declared≠enforced on the public error contract, and the three directions genuinely diverge on contract shape, so it clears the escalation bar rather than the queue.

Decision asked: MISSING_REQUIRED_FIELD is documented as HTTP 400 (error-handling.mdx:246, error-catalog.mdx:630, with a promised fields[]), but the surviving controlled_by_parent insert refusals answer 422 with no fields[] — which side moves?

1. Docs state the exception where it exists (name the four shapes and why the gate answers 422).
2. Move the surviving refusals onto the documented 400 shape — a public wire change, wanting A missing required master-detail parent still answers 422 MISSING_REQUIRED_FIELD with no fields[] and a [Security] message — while the same field, present-but-unresolvable, answers 400 VALIDATION_FAILED with fields[] (#7474 residual, 17.0.0 GA) #8688-style conditionality discipline.
3. Pin the doc's claim mechanically (a catalog↔runtime status conformance check) so the next divergence cannot land silently.

Four-prism analysis:

• Platform long-term coherence: 2 is the "one code, one status" answer but churns a shipped wire shape; 1 keeps the catalog honest at the cost of codifying an exception; 3 is the only option that prevents recurrence for every code, not just this one.
• Measured business pull: no client is measured branching on 400-vs-422 here; the reachable population is bounded (A controlled_by_parent object may declare its master reference without required, so the master-access guard is the only thing preventing an unreachable orphan detail row #8772's lint refuses the shapes at publish; only pre-existing declarations reach the gate). Doc-sized harm today.
• AI-agent error-resistance: the divergence lived only in a changeset until this card — 3 converts prose into a tripwire, which is the structural fix; 1 alone leaves the next mismatch silent.
• Startup scope discipline: 1 is the cheapest honest fix; 2 is a breaking change with zero measured pull; 3 is a new gate (a standing maintenance obligation) and should be weighed as such, not assumed.

Recommendation: direction 1 now (docs-only, small), and if you want the tripwire, rule 3 as its own separately-scoped card rather than a rider — it is a gate design, not a doc fix. Direction 2 is not recommended: wire churn without pull. The refusal semantics themselves are settled (fail-open otherwise, measured twice) and are not re-opened by this card.

---

Generated by Claude Code

[os-project-manager]

Maintainer ruling — Direction 1: the docs state the exception

Provenance: maintainer, live PM chat 2026-08-15 (session session_01LXPH2ApQmyHYeZGHfYv7Xs), verbatim 「接受你的所有建议。」, accepting the 18-card decision-box analysis (this card's four-prism block is in the escalation comment above). Ruled: direction 1 — content/docs/protocol/kernel/error-handling.mdx and content/docs/api/error-catalog.mdx document the exception where it exists: the four surviving controlled_by_parent insert-refusal shapes (and the stored-row case) answer 422 MISSING_REQUIRED_FIELD without fields[], with a sentence on why the gate refuses there (the measured fail-open alternative). Direction 2 (moving the wire to 400) is declined — public-contract churn with zero measured pull; the refusal semantics themselves stay settled per #8688/PR #8879 and are not re-opened.

Direction 3 (a catalog↔runtime status conformance gate) is not ruled — offered in the recommendation as a separately-scoped decision, and it stays that way: if wanted, it arrives as its own card with its own measurement, not as a rider here.

Label mechanics in the same write: needs-user-decision → pm:queue, and re-routed domain:cli → domain:devx — the ruling selects the lane, and direction 1 lands entirely in content/docs/**. Docs-only PR, skip-changeset; take the exact four shapes from PR #8879's landed changeset/test rather than from this card's summary. Size/model: S, sonnet.

---

Generated by Claude Code