Skip to content

Commit fa5c3fe

Browse files
committed
docs(adr-0055): move the cbp anchors to §1 as amended and cite the ruling
The ADR-0055 invariant in five anchors under scripts/adr-anchors still stated the pre-amendment §1 rule as a Do-NOT instruction. Each now states §1 as amended: the required master, or the only master_detail declared required: false as an optional master, read through the null-master arm by the row's owner and by View All on the detail. The instruction not to restore the retired tiers stays. ADR-0055's amendment named the parse question as open. It now cites the maintainer's ruling record 6687830530 (option A) as the decision the bullet implements. Co-authored-by: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016WV4cxZsyeZedvM4Ea8Ahs
1 parent 469499e commit fa5c3fe

6 files changed

Lines changed: 6 additions & 6 deletions

‎docs/adr/0055-master-detail-controlled-by-parent.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -208,7 +208,7 @@ The ruling names **update**. So the leg does not reach: an **insert** (no row to
208208
### What changes, exactly
209209

210210
- **Spec (§1).** The object's **only** `master_detail`, declared `required: false`, is its master when it declares no required one — an **optional** master. The parse's one-master rule (`packages/spec/src/data/controlled-by-parent-master.ts#controlledByParentMasterRefusal`) judges the master through `controlledByParentMasterOf`, exported beside it, which answers the field and whether it is optional; `isControlledByParentMasterField` keeps meaning the REQUIRED master. `ObjectSchema.create()` keeps an explicit `required: false` on the only `master_detail` as written; beside another `master_detail` it still refuses it, since that field is a second parent, not the master. Every other refusal stands: two masters, a required `lookup` only, and a `readonly` / `system` master (required or optional).
211-
- **An omitted `required` keeps meaning required where the omission is visible.** The builder forces it to `true` and the stored-row conversion `cbp-master-detail-required-defaulted` converts it to `true`, both unchanged. The **parse** cannot see it: `required` defaults to `false` on the parsed field map, so a raw parse (and `defineStack` over a plain object literal) admits an omitted `required` on the only `master_detail` as the optional master. `os lint`'s `relationship/master-detail-required` reports the omission at `error`, naming both spellings. Whether the parse should tell the two spellings apart is the maintainer's open question on #30905 (letters A, B and C); this amendment records option A, the one the code implements, and decides nothing further.
211+
- **An omitted `required` keeps meaning required where the omission is visible.** The builder forces it to `true` and the stored-row conversion `cbp-master-detail-required-defaulted` converts it to `true`, both unchanged. The **parse** cannot see it: `required` defaults to `false` on the parsed field map, so a raw parse (and `defineStack` over a plain object literal) admits an omitted `required` on the only `master_detail` as the optional master. `os lint`'s `relationship/master-detail-required` reports the omission at `error`, naming both spellings. Whether the parse should tell the two spellings apart was ruled by the maintainer on #30905 (record `6687830530`, 2026-11-06): option A, the parse does not tell them apart, and this bullet implements that ruling; option B (refusing the omitted spelling at every door through a new raw-input check) and option C (a separate explicit key) were not chosen.
212212
- **Compatibility.** No accepted stored object changes meaning. A stored row the v18 upgrade listed under `cbp-master-relation-tiers-retired` as `master-not-required` because it declared `required: false` is a valid optional-master detail now and is no longer listed; the semantic migration entry `cbp-optional-master-admitted` records it.
213213
- **Read (§2).** `packages/plugins/plugin-security/src/security-plugin-cbp-read-filter.ts#computeControlledByParentFilter` answers an optional master with `{ $or: [ { fk: { $in: ReadableIds.of(master) } }, nullMasterArm ] }`. The null-master arm is `{ fk: null }` for a holder of View All on the detail (`viewAllRecords` or `modifyAllRecords`, the super-user read bypass on the detail), else `{ $and: [ { fk: null }, { owner_id: <caller> } ] }` when the detail carries the `owner_id` column, else nothing. The function is the one chokepoint: the data middleware, `getReadFilter` (analytics, and the engine's `ReadableIds` composer behind the parent gates of attachments, comments, activity and approvals, and behind a chain's next level) and the delegated read compose it, each with the permission sets of the context it is asked for, so every read door follows. A required master's leaf is byte-identical to before.
214214
- **Explain.** `security/explain` narrates the null-master arm on a record read: which arm returned the row, or, for a row the read door withholds, that it names no master and who reads it instead (`packages/plugins/plugin-security/src/explain-engine.ts`).

‎scripts/adr-anchors/packages__plugins__plugin-security__src__security-plugin-cbp-read-filter.ts.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,5 @@
33
"adrs": [
44
"ADR-0055"
55
],
6-
"invariant": "ADR-0055 §1 — `resolveCbpRelation` derives a `controlled_by_parent` object's master from exactly one `master_detail` field declared `required: true` that names a reference, and from nothing else: zero such fields or two or more resolve `null`, which both halves treat as fail-closed (reads answer RLS_DENY_FILTER, writes throw MasterDetailRelationMissingError, 422 INVALID_METADATA), reported once per object per cache generation. Do NOT restore the retired fallback tiers (any `master_detail`, then a required `lookup`) or a first-by-field-order pick among two: they were never part of ADR-0055 §1, `ObjectSchema` refuses those shapes at parse, and a gate that derives access from a relation the parse refuses is the disagreement the step-18 semantic migration `cbp-master-relation-tiers-retired` closed. The reference-SPELLING tolerance in the same reader is a different, deliberate decision and stays."
6+
"invariant": "ADR-0055 §1 (as amended 2026-11-06, #30905, ruling record 6687830530) — `resolveCbpRelation` derives a `controlled_by_parent` object's master from exactly one `master_detail` field declared `required: true` that names a reference, or, with none, from the object's ONLY `master_detail`, declared `required: false` and naming a reference: an OPTIONAL master (`CbpRelation.optional`), picked by the spec's own `controlledByParentMasterOf` so the parse and this reader cannot name different fields. A detail row that names its master is read through it, and a required master's read leaf is byte-identical to before; a row whose master reference is empty is read through the null-master arm of `computeControlledByParentFilter` alone, by the row's owner (`owner_id`, only where the detail carries that column) and by View All on the detail; the write gate still refuses a write that leaves the reference empty. Anything else resolves `null`, which both halves treat as fail-closed (reads answer RLS_DENY_FILTER, writes throw MasterDetailRelationMissingError, 422 INVALID_METADATA), reported once per object per cache generation: no `master_detail`, two or more required ones, two or more with none required, and one whose `required` is not written at all (this reader tests `required === false`, never its absence, so an object that reached the registry without the parse resolves no master). Do NOT restore the retired fallback tiers (any `master_detail`, then a required `lookup`) or a first-by-field-order pick among two: they were never part of ADR-0055 §1, `ObjectSchema` refuses those shapes at parse, and a gate that derives access from a relation the parse refuses is the disagreement the step-18 semantic migration `cbp-master-relation-tiers-retired` closed. Do NOT widen the null-master arm past rows whose master reference is empty, or let View All on the detail open the master arm. The reference-SPELLING tolerance in the same reader is a different, deliberate decision and stays."
77
}

‎scripts/adr-anchors/packages__plugins__plugin-security__src__security-plugin-cbp-relation.ts.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,5 @@
33
"adrs": [
44
"ADR-0055"
55
],
6-
"invariant": "ADR-0055 §1 — `resolveCbpRelation` derives a `controlled_by_parent` object's master from exactly one `master_detail` field declared `required: true` that names a reference, and from nothing else: zero such fields or two or more resolve `null`, which both halves treat as fail-closed (reads answer RLS_DENY_FILTER, writes throw MasterDetailRelationMissingError, 422 INVALID_METADATA), reported once per object per cache generation. Do NOT restore the retired fallback tiers (any `master_detail`, then a required `lookup`) or a first-by-field-order pick among two: they were never part of ADR-0055 §1, `ObjectSchema` refuses those shapes at parse, and a gate that derives access from a relation the parse refuses is the disagreement the step-18 semantic migration `cbp-master-relation-tiers-retired` closed. The reference-SPELLING tolerance in the same reader is a different, deliberate decision and stays."
6+
"invariant": "ADR-0055 §1 (as amended 2026-11-06, #30905, ruling record 6687830530) — `resolveCbpRelation` derives a `controlled_by_parent` object's master from exactly one `master_detail` field declared `required: true` that names a reference, or, with none, from the object's ONLY `master_detail`, declared `required: false` and naming a reference: an OPTIONAL master (`CbpRelation.optional`), picked by the spec's own `controlledByParentMasterOf` so the parse and this reader cannot name different fields. A detail row that names its master is read through it, and a required master's read leaf is byte-identical to before; a row whose master reference is empty is read through the null-master arm of `computeControlledByParentFilter` alone, by the row's owner (`owner_id`, only where the detail carries that column) and by View All on the detail; the write gate still refuses a write that leaves the reference empty. Anything else resolves `null`, which both halves treat as fail-closed (reads answer RLS_DENY_FILTER, writes throw MasterDetailRelationMissingError, 422 INVALID_METADATA), reported once per object per cache generation: no `master_detail`, two or more required ones, two or more with none required, and one whose `required` is not written at all (this reader tests `required === false`, never its absence, so an object that reached the registry without the parse resolves no master). Do NOT restore the retired fallback tiers (any `master_detail`, then a required `lookup`) or a first-by-field-order pick among two: they were never part of ADR-0055 §1, `ObjectSchema` refuses those shapes at parse, and a gate that derives access from a relation the parse refuses is the disagreement the step-18 semantic migration `cbp-master-relation-tiers-retired` closed. Do NOT widen the null-master arm past rows whose master reference is empty, or let View All on the detail open the master arm. The reference-SPELLING tolerance in the same reader is a different, deliberate decision and stays."
77
}

‎scripts/adr-anchors/packages__plugins__plugin-security__src__security-plugin-cbp-write-gate.ts.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,5 @@
33
"adrs": [
44
"ADR-0055"
55
],
6-
"invariant": "ADR-0055 §1 — `resolveCbpRelation` derives a `controlled_by_parent` object's master from exactly one `master_detail` field declared `required: true` that names a reference, and from nothing else: zero such fields or two or more resolve `null`, which both halves treat as fail-closed (reads answer RLS_DENY_FILTER, writes throw MasterDetailRelationMissingError, 422 INVALID_METADATA), reported once per object per cache generation. Do NOT restore the retired fallback tiers (any `master_detail`, then a required `lookup`) or a first-by-field-order pick among two: they were never part of ADR-0055 §1, `ObjectSchema` refuses those shapes at parse, and a gate that derives access from a relation the parse refuses is the disagreement the step-18 semantic migration `cbp-master-relation-tiers-retired` closed. The reference-SPELLING tolerance in the same reader is a different, deliberate decision and stays."
6+
"invariant": "ADR-0055 §1 (as amended 2026-11-06, #30905, ruling record 6687830530) — `resolveCbpRelation` derives a `controlled_by_parent` object's master from exactly one `master_detail` field declared `required: true` that names a reference, or, with none, from the object's ONLY `master_detail`, declared `required: false` and naming a reference: an OPTIONAL master (`CbpRelation.optional`), picked by the spec's own `controlledByParentMasterOf` so the parse and this reader cannot name different fields. A detail row that names its master is read through it, and a required master's read leaf is byte-identical to before; a row whose master reference is empty is read through the null-master arm of `computeControlledByParentFilter` alone, by the row's owner (`owner_id`, only where the detail carries that column) and by View All on the detail; the write gate still refuses a write that leaves the reference empty. Anything else resolves `null`, which both halves treat as fail-closed (reads answer RLS_DENY_FILTER, writes throw MasterDetailRelationMissingError, 422 INVALID_METADATA), reported once per object per cache generation: no `master_detail`, two or more required ones, two or more with none required, and one whose `required` is not written at all (this reader tests `required === false`, never its absence, so an object that reached the registry without the parse resolves no master). Do NOT restore the retired fallback tiers (any `master_detail`, then a required `lookup`) or a first-by-field-order pick among two: they were never part of ADR-0055 §1, `ObjectSchema` refuses those shapes at parse, and a gate that derives access from a relation the parse refuses is the disagreement the step-18 semantic migration `cbp-master-relation-tiers-retired` closed. Do NOT widen the null-master arm past rows whose master reference is empty, or let View All on the detail open the master arm. The reference-SPELLING tolerance in the same reader is a different, deliberate decision and stays."
77
}

0 commit comments

Comments
 (0)