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

[qq9340100]

Found while verifying #8688 (no PR there — that card stopped on a pinned-envelope fork). Not fixed here: fixing it changes the authoring/lint surface, which is a different package and a different decision from #8688's error envelope. Recorded so the dependency is visible, because it is the reason #8688's literal route was measured unsafe.

What was measured

assertControlledByParentWrite refuses an insert whose master FK is absent, unconditionally. Required-field validation does not cover the same ground. Probed against validateRecord's handling in packages/objectql/src/validation/record-validator.ts, over the shapes a controlled_by_parent object can actually declare:

master reference declaration	validateRecord on an insert that omits it
master_detail, required: true	rejects — VALIDATION_FAILED, fields: [{ field, code: 'required' }]
master_detail, required: true, explicit null	rejects, same
master_detail, no required	no error — the write proceeds
master_detail, required: true + readonly	no error — the write proceeds
master_detail, required: true + system	no error — the write proceeds

The last two follow from record-validator.ts, which skips the required check for provenance-flagged fields before it is ever reached:

if (def.system || def.readonly) continue;

Why those shapes are reachable, not hypothetical

1. resolveCbpRelation in packages/plugins/plugin-security/src/security-plugin.ts resolves the master relation through three fallbacks, and only the first tests required:

   pick((f) => f?.type === 'master_detail' && f?.required) ??
   pick((f) => f?.type === 'master_detail') ??
   pick((f) => f?.type === 'lookup' && f?.required);

   The second fallback is a supported, exercised shape — validate-security-posture.test.ts pins "stays silent on step 2: ANY master_detail (not marked required)".

2. packages/lint/src/data-model-rules.ts emits only severity: 'warning' for relationship/master-detail-required, so nothing refuses the declaration at publish time:

   severity: 'warning',
   rule: 'relationship/master-detail-required',

Why it matters

There is no live defect today — the guard closes all five rows of the table, which is why this is filed as an observation rather than a bug. The finding is where the closure comes from: for three authorable shapes it comes from a security gate, not from the declaration. Two consequences:

• It is a latent trap for any change that moves the guard. Standing the guard down for the absent-master insert (the route 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 proposes) is safe only for the first two rows. For the other three it would create a detail row whose master FK is null — a row the controlled_by_parent read filter (fk IN (readable masters)) can never match, so nobody can read it, and every later by-id write to it answers 422 MISSING_REQUIRED_FIELD on the stored-row leg.
• Declared is not enforced here. An author who omits required: on a master_detail gets a warning and a silently different enforcement path. Under the "make AI-written metadata hard to get wrong" principle this is the wrong default: the mistake is invisible at authoring time and surfaces only as an unreachable row.

Possible directions (not a recommendation — needs triage)

1. Promote relationship/master-detail-required from warning to error, so a controlled_by_parent master reference that is not required fails lint. Loudest, and it breaks any existing app relying on the shape the posture test currently pins as supported.
2. Have the authoring builder force required: true on a master_detail under controlled_by_parent, so the shape cannot be declared.
3. Narrow resolveCbpRelation to the required fallback only — but that turns the other shapes into 422 INVALID_METADATA at write time rather than at authoring time, which moves the report later, not earlier.
4. Accept it and document that the guard is the enforcement point for non-required master references, in which case the guard must not be moved without this being revisited.

Note that direction 3 interacts with the validate-security-posture.test.ts pin, and directions 1–2 are authoring-surface changes with migration cost — none of them is a drive-by.

---

Filed unassigned for triage. Related: #8688, #7474.

Generated by Claude Code

[hotlong]

Triage: escalated to needs-user-decision (first-touch grading, finding dropped in the same label write). Type set to Task. Deliberately left without a domain:* label — see §3.

1. Premise re-verified independently, on origin/main @ ab8b10f

Not inherited from the card — all three quotes re-read at the ref, and each is verbatim:

claim	reading
required-check skips provenance-flagged fields	packages/objectql/src/validation/record-validator.ts :993 and :1003 — if (def.system || def.readonly) continue; (two sites, the card quoted one)
lint rule is advisory only	packages/lint/src/data-model-rules.ts :493–:494 — severity: 'warning', rule: 'relationship/master-detail-required', message "should be required"
only the first fallback tests required	packages/plugins/plugin-security/src/security-plugin.ts :4689–:4692 — pick(master_detail && required) ?? pick(master_detail) ?? pick(lookup && required)

Zero-hit discipline satisfied: the counter-probe for the validator file returns 15 required hits, so the narrow match at :993/:1003 is a real reading, not a broken query.

2. Why this is not a queue card

The card is honest that there is no live defect — the guard closes all five rows. What it records is where the closure comes from, and every direction it lists changes an authoring acceptance surface:

• Direction 1 (warning → error) narrows the accepted set on a published authoring surface, and refuses a shape validate-security-posture.test.ts currently pins as supported ("stays silent on step 2: ANY master_detail (not marked required)").
• Direction 2 (builder forces required: true) narrows what can be declared at all.
• Direction 3 (narrow resolveCbpRelation) converts the same shapes into a write-time 422 INVALID_METADATA — later, not earlier — and collides with the same pin.
• Direction 4 (accept + document) is itself a standing constraint: it makes the security gate the enforcement point of record, which is precisely what must not be moved silently.

Public/authoring-contract shape ⇒ manual floor, independent of confidence. ⛔ No 代裁 (and this fire's confidence gate ⑤ fails anyway — see the seat brief).

3. ⛔ No domain:* label — the ruling is the lane selector

The landing package is not determined until the direction is chosen, and the four directions land in three different lanes: packages/lint ⇒ domain:devx; the authoring builder in packages/spec ⇒ domain:spec (acceptance-surface half); plugin-security ⇒ domain:identity; direction 4 lands only in docs. Labelling now would pre-answer the question the card asks. This is the same deliberately unroutable shape recorded for #7571 / #7497 — recorded explicitly so a later sweep reads this as a principled leave-blank, not as an unrouted card.

4. ⭐ This card is an input to #8688's ruling — they should be answered together

#8688 sits in the decision inbox already, and its proposed route is "stand the guard down for the absent-master insert". This card measures that route as safe for 2 of the 5 declarable shapes and unsafe for the other 3 — standing the guard down there mints a detail row with a null master FK, which the controlled_by_parent read filter (fk IN (readable masters)) can never match: unreadable by anyone, and answering 422 MISSING_REQUIRED_FIELD on every later by-id write.

So #8688 cannot be ruled on its own merits without ruling this. Cross-referenced on #8688 in the same pass. ⛔ Not expressed as a Blocked-by: line — that channel serves the unlock scan over dispatchable work, and neither card is dispatchable; a decision-to-decision coupling recorded there would be read by the scan as an unlock candidate.

5. Four-facet card face

• ① Platform long-term coherence — pulls toward acting. Today the declaration and the enforcement disagree, and the enforcement lives in a security gate that has no stated obligation to keep providing it. Directions 1–2 collapse that into one statement; direction 4 keeps two.
• ② Measured business pull — pulls toward defer. Zero live defect, zero measured victim; the trap is only armed by a change nobody has scheduled. The one thing that does arm it is 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, which is itself unruled.
• ③ AI-agent error-resistance — pulls toward acting, hardest. This is the exact shape the principle names: an author (or an agent) omits required:, gets a warning, and silently lands on a different enforcement path whose failure mode is an unreachable row. Loud refusal at publish beats a warning nobody reads.
• ④ Startup scope discipline — pulls toward the cheap end. Directions 1–2 carry migration cost against existing apps and against a pinned test; direction 4 costs one paragraph but creates a permanent "do not move this guard" obligation with no mechanical enforcement.

Split ①③ vs ②④ ⇒ escalated, not adjudicated.

Recommendation, offered and falsifiable: direction 1 (warning → error) scoped only to master_detail fields on a controlled_by_parent object, not to master-detail generally — that is the subset where the closure argument actually applies, and it leaves the pinned "ANY master_detail" posture shape alone everywhere else. Conditioned on one measurement nobody has taken: how many shipped objects in examples/** and packages/platform-objects/** declare a controlled_by_parent master reference without required. If that count is zero the migration cost is theoretical and direction 1 is cheap; if it is not, ② and ④ get much stronger. That is a survey, not a judgement, and it should pick the direction.

Serial constraint recorded for whichever lane receives this: ⛔ not same-batch with #8688 (same guard), and direction 3 ⛔ not same-batch with anything touching validate-security-posture.test.ts.

本评论来自分诊座位 Routine。

---

Generated by Claude Code

[os-zhuang]

Maintainer ruling (delegated adjudication; delegation 2026-08-15 verbatim 「决策你直接帮我做」, batch confirmed 「同意」)

Ruled: Direction 1 — promote relationship/master-detail-required from warning to error, scoped to controlled_by_parent objects only. Runtime untouched. Ruled as a pair with #8688 (this card first, per triage's recommendation).

The survey triage conditioned its recommendation on has now been taken (origin/main @ 84cb121eb): the shipped surface — examples/** and packages/platform-objects/** — contains exactly 3 controlled_by_parent objects (opportunity-line-item, expense-report, invoice), and all three declare required: true on the master reference, none with readonly/system. The migration cost of Direction 1 is measured at zero, which resolves the ②/④-vs-①/③ split toward acting.

Scope pins:

• The error fires only for a master reference on a controlled_by_parent object, and covers all three unsafe shapes the card measured: missing required; required: true + readonly; required: true + system (the latter two are skipped by record-validator.ts :993/:1003, leaving the security gate as sole enforcement — the same trap).
• ⛔ Runtime stays as-is: resolveCbpRelation's fallbacks are kept (tolerance for existing installs), and the validate-security-posture.test.ts pin ("stays silent on step 2: ANY master_detail") stays green — it pins runtime resolution, not lint. Publish-time refuses new declarations; runtime tolerates old ones.
• Direction 2 (builder forces required) is unnecessary once lint refuses; Direction 3 (narrow resolveCbpRelation) moves the report later, not earlier — both rejected.

Dispatch notes: lands in packages/lint (hence domain:devx). Accept-set narrowing on a published authoring surface ⇒ claude-fable-5 tier mandatory. ⛔ Not same-batch as #8688 (same guard).

Label flipped needs-user-decision → pm:queue. Not dispatched from the spec seat (dispatch freeze in force); the owning lane's seat may pick this up.

---

Generated by Claude Code