@@ -0,0 +1,35 @@
+---
+'@objectstack/objectql': minor
+---
+
+fix(objectql)!: a detail write asks the caller's read door for its master-detail header before judging it — a header the caller cannot read answers as a header that exists nowhere (#22519)
+
+Clause-②: no (narrowing)
+
+<!-- adr-0087: not-required (no-migration-prescription) No metadata moves: no spec key, authorable spelling, export or stored shape is removed, renamed or re-shaped, so there is nothing for `objectstack migrate meta` to rewrite. What narrows is one runtime read, in two places: the write's master-detail header read (the `parent` binding) and the write's reference check of a `master_detail` field now ask the caller's read door before their elevated read, so a write naming a header the caller cannot read is answered as a write naming a header that exists nowhere. The other categories are closed on facts: the package publishes (not unpublished); no ADR-0087 id is named or touched (not registered or already-registered); and no exported declaration is removed or narrowed (not runtime-interface-only or type-surface-only). -->
+
+**BREAKING** (an accept-set narrowing), shipped as `minor` under the launch-window convention for breaking changes.
+
+A write of a master-detail DETAIL reads its header for two things: the reference check of the `master_detail` value the caller supplied, and the `parent` that a parent-scoped `requiredWhen` / `readonlyWhen` judges.
+
+**FROM.** Both read the header elevated (row-level access bypassed, the caller's tenant kept), on the premise that the caller's right to write the detail settled its right to see the header. ADR-0055 §3 guarantees that only for a `controlled_by_parent` detail (its master-edit gate). For any other detail, a non-system caller who could write the detail but could not read its header met:
+
+- a reference check that admitted the header id, where a header id that exists nowhere answers `reference_not_found`;
+- a parent-scoped rule judged against the header's stored state, so the write's answer depended on a row the caller cannot read.
+
+**TO.** The header is read in two steps, the shape `validate()`'s preview already uses:
+
+1. The caller's read door, under the caller's own context, so every enforcement layer in the middleware chain answers it. A header it does not return (hidden by row scope, a refused read of the header object, or a failed read) binds as a missing header binds: the reference check answers `reference_not_found` (`400 VALIDATION_FAILED`), and a parent-scoped `requiredWhen` / `readonlyWhen` meets an unbound `parent` (the requirement is refused as unevaluable, the lock holds), exactly as for a header id that exists nowhere.
+2. The elevated, tenant-kept read, only for the headers step 1 returned. A header the caller can read is still judged on its STORED values, a column field-level security hides or masks for the caller included. The preview's per-column masking stays the preview's own.
+
+**Bindings.**
+
+- Every detail, `controlled_by_parent` or not, on every write door: `insert` (single and batch), `insertMany`, update by id (a repoint included) and the predicate (bulk) update.
+- System callers (`isSystem`: seed replay, boot, package install) ask no read door and resolve exactly as before.
+- A plain `lookup`'s reference check keeps its elevated existence probe, unchanged.
+- No new error code and no status change: the answers are the ones a header that exists nowhere already got.
+- Cost: one id-projected read under the caller's context per header resolution (once per batch), and one per supplied `master_detail` value in the reference check.
+
+**Fix, if a write relied on the old answer:** give the writer read access to the header — an object permission or sharing rule on the master, or declare the detail `controlled_by_parent` so the header's access governs it.
+
+**Not measured.** Which deployed configurations let a caller write a detail whose header it cannot read was not measured: the rule only tightens, so it holds whatever that answer is.
@@ -10,7 +10,7 @@ the seed loader replaying package fixtures, a plugin's boot reconciler, a
 service self-write, a migration.
 
 This page is **the authority** for what that flag actually does. It exists
-because the flag is not one concept: it is a single boolean read at **124
+because the flag is not one concept: it is a single boolean read at **125
 distinct sites across 20 packages**, and knowing three of those behaviours gives
 no hint that the other hundred-and-four exist. Every documented app-side bug
 traced to `isSystem` had the same shape — the metadata was complete and correct,
@@ -138,11 +138,12 @@ that silently does not happen.
 | 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `packages/objectql/src/engine.ts#dependentCountIsDisclosable` |
 | 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `packages/objectql/src/engine.ts#recordReferenceCheckElevation` |
 | 29b | A traversing validation rule's related read skips the **caller's bounds** | objectql | Get: no row bound from the caller's own read on a related object no organization wall scopes, and a related read even with no organization under a walled posture (a `tenantId` on the context still scopes it). Every caller that is not system is held to both | `packages/objectql/src/engine.ts#resolvePredicateRelated` |
+| 29c | A detail write's master-detail header read asks **no read door** | objectql | Get: the write binds the header a parent-scoped `requiredWhen` / `readonlyWhen` reads as `parent` from the header's stored row whoever can read it, as before. Every caller that is not system meets its own read door first: a header that read does not return answers as a header that exists nowhere — an unbound `parent`, and `reference_not_found` on the reference check (which a system caller's write skips altogether) | `packages/objectql/src/engine.ts#masterDetailHeadersCallerReads` |
 | 30 | **Bulk data event `organizationId` OMITTED** — the batch is published "not asserted" | plugin-security | Get: nothing — the `data.records.*` event still publishes. Lose: the per-organization attribution: this exit is taken before the security middleware composes any tenant wall, so it records no Layer 0 verdict on the operation (`OperationContext.tenantLayer0Verdict`, #15813), and the engine's bulk producer — which reads that recorded verdict and nothing else — omits the key rather than filling it from the caller's `tenantId`; a tenant-scoped consumer then does not deliver the event inside an organization wall (#15225) | `packages/plugins/plugin-security/src/security-plugin.ts#start` |
 
 ### 3. Sharing (`plugin-sharing`)
 
-The largest single consumer — **17 of the 124 sites**.
+The largest single consumer — **17 of the 125 sites**.
 
 | # | Behaviour when `isSystem` | What you get / what you lose | Anchor |
 |:--|:---|:---|:---|
@@ -285,7 +286,7 @@ Ownership injection, `readonly` bypass and sharing materialisation are
 independent decisions, and a seed loader plausibly wants the first two but not
 the third. The concept is nevertheless **staying as one boolean**:
 
-- **Shipped semantics.** `isSystem` is a published contract with 124 read sites
+- **Shipped semantics.** `isSystem` is a published contract with 125 read sites
   in 20 packages. Splitting it is a breaking contract change across all of them.
   (The ruling was taken when the census read 80 sites in 18 packages; the count
   has grown, which strengthens rather than weakens the argument.)
@@ -359,16 +360,16 @@ still holds equal to the census on every pull request:
 | Appearances of the bare identifier `isSystem` in non-test sources | 813 | — |
 | — parsed as a declaration | 28 | ✅ |
 | — parsed as an object-literal / type key (producers and option objects) | 310 | — |
-| — parsed as a property **read** | 129 | ✅ |
+| — parsed as a property **read** | 130 | ✅ |
 | — parsed in some other syntactic position (a local, a cast, a conditional) | 9 | ✅ |
 | — the remainder: text inside comments and string literals | 358 | — |
 | Of those reads: reads of one of the unrelated metadata fields | 5 | ✅ |
-| Of those reads: reads of `ExecutionContext.isSystem` | **124** | ✅ |
-| — behaviour-bearing (rows 1–61 above) | 121 | ✅ |
+| Of those reads: reads of `ExecutionContext.isSystem` | **125** | ✅ |
+| — behaviour-bearing (rows 1–61 above) | 122 | ✅ |
 | — carry the flag onward only (rows 62–64 above) | 3 | ✅ |
 | Packages containing at least one elevation read | **20** | ✅ |
 | Files containing at least one elevation read | 58 | ✅ |
-| — the distinct symbols those reads live in — what this page anchors | 106 | ✅ |
+| — the distinct symbols those reads live in — what this page anchors | 107 | ✅ |
 | — of those files, the ones holding more than one read in one symbol | 8 | ✅ |
 
 The six rows marked — are a **dated decomposition, not a live claim**: they were
 
@@ -651,10 +651,12 @@ describe('[#19837] the master-detail parent binding is scoped to the caller\'s o
     observed.length = 0;
     const global = await refusalOf(() => insertLine('gh_locked', 'pb_gline'));
     expect(envelopeOf(global)).toEqual({ status: 400, code: 'VALIDATION_FAILED', fields: [{ field: 'note', code: 'required' }] });
-    // Bound because the engine withheld the tenant for this master (ADR-0066).
+    // Bound because the engine withheld the tenant for this master (ADR-0066),
+    // on both of the write's header reads (#22519: the caller's read door, then
+    // the elevated read).
     const read = observed.filter((c) => c.object === 'pb_gheader' && c.method === 'find');
-    expect(read).toHaveLength(1);
-    expect(read[0].options?.tenantId).toBeUndefined();
+    expect(read).toHaveLength(2);
+    for (const r of read) expect(r.options?.tenantId).toBeUndefined();
   });
 
   it('`group` posture: a header inside the caller\'s membership set binds — the union reaches the header read', async () => {
@@ -669,9 +671,11 @@ describe('[#19837] the master-detail parent binding is scoped to the caller\'s o
       engine.insert('pb_line', { id: 'ln_grp', header: 'hy_locked' }, { context: GROUP_MEMBER } as any));
 
     expect(envelopeOf(inside)).toEqual({ status: 400, code: 'VALIDATION_FAILED', fields: [{ field: 'note', code: 'required' }] });
+    // Both of the write's header reads (#22519: the caller's read door, then
+    // the elevated read) reach the union.
     const read = observed.filter((c) => c.object === 'pb_header' && c.method === 'find');
-    expect(read).toHaveLength(1);
-    expect([...(read[0].options?.tenantIds ?? [])].sort()).toEqual([ORG_X, ORG_Y].sort());
+    expect(read).toHaveLength(2);
+    for (const r of read) expect([...(r.options?.tenantIds ?? [])].sort()).toEqual([ORG_X, ORG_Y].sort());
 
     // Lit control: a member whose set is org X alone cannot see the org-Y
     // header, so it binds absent and the write answers as an absent header does
@@ -683,27 +687,36 @@ describe('[#19837] the master-detail parent binding is scoped to the caller\'s o
     expect(envelopeOf(outside)).toEqual({ status: 400, code: 'VALIDATION_FAILED', fields: [{ field: 'note', code: 'rule_violation' }] });
   });
 
-  it('the header read runs ELEVATED and TENANT-SCOPED — the two halves of `{ ...context, isSystem: true }`', async () => {
+  it('the header read asks the caller\'s read door first, then runs ELEVATED and TENANT-SCOPED — the two halves of `{ ...context, isSystem: true }`', async () => {
     const reads: Array<{ operation: string; context: ExecutionContext }> = [];
     engine.registerMiddleware(async (opCtx: any, next: () => Promise<void>) => {
       if (opCtx.object === 'pb_header') reads.push({ operation: opCtx.operation, context: opCtx.context });
       await next();
     });
     storeFor('pb_line').set('ln_x', { id: 'ln_x', header: 'hx_open', note: 'n', organization_id: ORG_X });
 
-    // Insert: `resolveMasterDetailParents` is the batch `find`; the `findOne`
-    // behind it is #19808's reference probe (the payload names the header).
+    // [#22519] Every elevated header read is preceded by the caller's read
+    // door, a `find` under the caller's own context.
+    // Insert: `resolveMasterDetailParents` is the batch `find` pair; the
+    // `find` + `findOne` behind it is #19808's reference probe (the payload
+    // names the header).
     await insertLine('hx_open');
     // Update by id, header not in the payload: no reference probe, so the one
     // `findOne` is `resolveMasterDetailParent` reading the stored row's header.
     await engine.update('pb_line', { note: 'm' }, { where: { id: 'ln_x' }, context: MEMBER_X } as any);
 
-    expect(reads.map((r) => r.operation)).toEqual(['find', 'findOne', 'findOne']);
+    const shape = (r: { operation: string; context: ExecutionContext }) =>
+      `${r.operation}:${r.context?.isSystem === true ? 'elevated' : 'door'}`;
+    expect(reads.map(shape)).toEqual([
+      'find:door', 'find:elevated',
+      'find:door', 'findOne:elevated',
+      'find:door', 'findOne:elevated',
+    ]);
     for (const { context } of reads) {
-      expect(context).toMatchObject({ isSystem: true, tenantId: ORG_X, userId: 'u_x' });
+      expect(context).toMatchObject({ tenantId: ORG_X, userId: 'u_x' });
     }
     // …and the tenant reaches the driver on every one of them.
     const driverReads = observed.filter((c) => c.object === 'pb_header');
-    expect(driverReads.map((c) => c.options?.tenantId)).toEqual([ORG_X, ORG_X, ORG_X]);
+    expect(driverReads.map((c) => c.options?.tenantId)).toEqual([ORG_X, ORG_X, ORG_X, ORG_X, ORG_X, ORG_X]);
   });
 });
@@ -334,20 +334,33 @@ describe('parent-scoped requiredWhen is enforced server-side (#4977)', () => {
     // `resolveMasterDetailParents`), so that is what is counted here — the
     // `findOne`s on the same object belong to the #4441 reference guard and are
     // not this change's cost.
-    const reads: string[] = [];
+    //
+    // [#22519] The resolution is two reads, each ONE batched `find`: the
+    // caller's read door (under the caller's own context), then the elevated
+    // read for the headers it returned. The reference guard asks the read door
+    // too, one single-id `find` per supplied header, ahead of its `findOne`.
+    const reads: Array<{ object: string; ids: unknown; elevated: boolean }> = [];
     const original = (engine as any).find.bind(engine);
     (engine as any).find = async (name: string, q: any, o?: any) => {
-      reads.push(name);
+      const id = q?.where?.id;
+      const ids = Array.isArray(id?.$in) ? id.$in : id === undefined ? undefined : [id];
+      reads.push({ object: name, ids, elevated: q?.context?.isSystem === true });
       return original(name, q, o);
     };
+    const headerReads = () => reads.filter((r) => r.object === 'showcase_invoice');
+    const naming = (n: number) => (r: { ids: unknown }) => Array.isArray(r.ids) && r.ids.length === n;
     // Two rows under the SAME master, and two more under another: N rows, M
-    // masters, ONE query.
+    // masters, ONE query per read.
     await engine.insert('showcase_invoice_line', [
       { invoice: 'INV-SENT', description: 'a', quantity: 1 },
       { invoice: 'INV-SENT', description: 'b', quantity: 1 },
       { invoice: 'INV-DRAFT', quantity: 1 },
     ] as any);
-    expect(reads.filter((r) => r === 'showcase_invoice')).toHaveLength(1);
+    expect(headerReads().filter((r) => r.elevated)).toHaveLength(1);
+    expect(headerReads().filter((r) => !r.elevated && naming(2)(r))).toHaveLength(1);
+    // The rest: the reference guard's read door, one per supplied header.
+    expect(headerReads().filter((r) => !r.elevated && naming(1)(r))).toHaveLength(3);
+    expect(headerReads()).toHaveLength(5);
 
     // An object with only record-scoped requirements pays nothing extra.
     engine.registry.registerObject({
@@ -360,7 +373,9 @@ describe('parent-scoped requiredWhen is enforced server-side (#4977)', () => {
     } as any, 'test-package');
     reads.length = 0;
     await engine.insert('plain_line', { invoice: 'INV-SENT', quantity: 1 });
-    expect(reads.filter((r) => r === 'showcase_invoice')).toHaveLength(0);
+    // No header resolution: the one `find` is the reference guard's read door.
+    expect(headerReads().filter((r) => r.elevated)).toHaveLength(0);
+    expect(headerReads()).toHaveLength(1);
   });
 
   // ── #6457 — the header is TOTAL over the MASTER's declared fields ──────────