Repository navigation
Expand file tree
/
Copy pathengine-referential-integrity.ts
More file actions
530 lines (516 loc) · 28.6 KB
/
Copy pathengine-referential-integrity.ts
File metadata and controls
530 lines (516 loc) · 28.6 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
/**
* [#25522 cut 10] Two referential-integrity bodies of `ObjectQL`, moved out
* of `engine.ts` whole: `assertReferencesResolve` (the write path's #4441
* reference check: a caller-supplied id in a reference field must name a row
* of its target) and `masterDetailHeadersCallerReads` (#22519: which
* master-detail headers the caller's own read door returns), with
* `isEmptyReferenceValue`, the module helper only the first of them calls.
*
* A MOVE, not a redesign. Each exported function below is the body of the
* `ObjectQL` method of the same name as it stood, re-indented one level and
* otherwise unedited: the same system-caller exit, the same `readonly` and
* caller-supplied skips, the same master-detail branch, the same one-`find`
* read door and the same warning when that read fails. Each method's
* docblock stays on the method in `engine.ts`, which is still the contract.
* `isEmptyReferenceValue` moves with its docblock, byte for byte, and is not
* exported. [#28881] Since the move, the system-caller exit keeps the check for
* a flow run's elevated write (the method's docblock, Scope).
*
* What stays in the class: `referenceExists`, `resolveMasterDetailParent` and
* `resolveMasterDetailParents`, which read the private static
* `referenceCheckContext` and hold an erased query-options site; the bodies
* that call a module helper `engine.ts` still needs elsewhere
* (`settleMasterDetailLanding`, `resolvePreviewParents`,
* `resolvePredicateRelated`, `resolveOneHopRelated`); and
* `callerReadableReferenceExists`, `materializeParentHeader` and
* `masterDeclaredFields`, whose bodies are no longer than the host literal
* moving them would cost.
*
* ## How the moved bodies reach the class
*
* The shape #23050 set for `rest-server.ts`, applied per method as
* `engine-compatibility-api.ts` applies it. The class keeps both methods with
* name, modifiers, signature, docblock and position, and each body is one
* literal of exactly the {@link ReferentialIntegrityHost} members that method
* reads, plus a `.call`. The one field a body reads (`logger`) goes as a
* GETTER, so the read happens when the body makes it, as it did. The methods
* they call (`find`, `callerReadableReferenceExists`, `referenceExists`) go as
* late-bound closures over the instance, so a double or spy set on the engine
* is still the one a call reaches.
*
* This module imports the engine only as a TYPE, so there is no module cycle
* at run time, and nothing re-exports it, so the published surface does not
* move.
*
* [#30053 codemod] A PRIVATE method's docblock has since moved here,
* onto its function (`--hand-docs` of `scripts/codemod-split-engine.mjs`),
* and the class keeps none for it; a public or protected method's docblock
* stays on the class, the contract, and its function keeps the placeholder.
*/
import { referenceTargetOf, type EngineQueryOptions } from '@objectstack/spec/data';
import type { ExecutionContext } from '@objectstack/spec/kernel';
import { isUserBanInForce, isVouchedReference, keepsFlowWriteReferenceCheck, USER_BAN_FIELDS } from '@objectstack/core';
import { ValidationError, buildFieldError } from './validation/record-validator.js';
import { servedAsStored } from './engine-top-level.js';
import type { ObjectQL } from './engine.js';
/**
* The `ObjectQL` members the functions below read — every one of them, and no
* other; each function's `this` is the `Pick` of the members IT reads. Each is
* typed AS the class member (an indexed access on the class), so a change to a
* member's type on the class is a change here too, and naming a member the
* class does not have is a compile error. See the module header for which
* member is a getter.
*/
export interface ReferentialIntegrityHost {
readonly logger: ObjectQL['logger'];
find: ObjectQL['find'];
callerReadableReferenceExists: ObjectQL['callerReadableReferenceExists'];
callerReadableReferenceRow: ObjectQL['callerReadableReferenceRow'];
referenceExists: ObjectQL['referenceExists'];
referenceRow: ObjectQL['referenceRow'];
}
/**
* [#4441] "The caller did not name a record here."
*
* `null` / `undefined` / `''` mean NO LINK — exactly what
* `deleteBehavior: 'set_null'` writes — and an empty array is the multi-value
* spelling of the same thing. None of them is an id to resolve.
*/
function isEmptyReferenceValue(v: unknown): boolean {
if (v === null || v === undefined || v === '') return true;
if (Array.isArray(v)) return v.length === 0 || v.every((e) => e === null || e === undefined || e === '');
return false;
}
/**
* [#29029] The reference types whose target a non-system write may name only
* when the caller's own read door returns it: `master_detail` (#22519), and
* `lookup` and `user` with it. A target the caller cannot read answers
* `reference_not_found`, exactly as a target that exists nowhere. `tree`, the
* one other reference type, keeps the elevated existence probe: the rulings
* that tightened this set (records 6573561091 and 6663849489) name `lookup`
* and `user` only.
*/
const CALLER_READ_REFERENCE_TYPES: ReadonlySet<string> = new Set(['master_detail', 'lookup', 'user']);
/**
* [#29029] Whether this write's reference check ({@link assertReferencesResolve})
* runs BEFORE the record's validation rules. A write that is not a system
* write: yes — a reference its caller cannot read answers
* `reference_not_found`, whatever a rule would answer. A system write keeps
* the order it had, the rules first and then the check, so its answer is the
* one it gave before (ruling of record 6663849489). The one predicate every
* write door and the validate preview read, so the order cannot differ
* between them.
*/
export function referencesCheckedBeforeRules(context: unknown): boolean {
return !(context as { isSystem?: unknown } | null | undefined)?.isSystem;
}
/**
* [#4441] Referential integrity on the WRITE path: a `lookup` (or any
* reference-typed field) may not be given an id that exists in no row of the
* object it declares.
*
* The field metadata is unambiguous — `{"type":"lookup","required":true,
* "reference":"sys_permission_set"}` — and the DELETE side already reasons
* about the edge (`deleteBehavior: 'set_null'`). Only the insert side never
* checked, so `POST /data/sys_position_permission_set
* {"permission_set_id":"ps_does_not_exist_at_all"}` created the row.
*
* On the RBAC link tables that is a security-surface record that resolves to
* nothing: an administrator auditing permissions sees a binding whose target
* cannot be inspected, and the audience-anchor gate had to resolve that very
* set to evaluate the grant — so a dangling row was an unevaluable gate input,
* not merely an untidy one. (That gate and `sys_position_permission_set` are
* retired since C3 stage 8; the check stands for the link tables that remain.)
*
* ## Scope, deliberately narrow
*
* - **Caller-supplied keys only.** Server stamps (`owner_id`,
* `organization_id`, `created_by`/`updated_by`) are lookups too; they are
* written by hooks and middleware, not by the request, and re-validating
* them here would turn a platform stamp into a caller-facing rejection.
* - **Non-system writes only**, like every other write-path guard in this
* engine (`stripReadonlyFields` — which since #14147 runs on the create
* path as well as the update one — and `stripRuntimeOwnedFields`). Seed
* replay,
* package install and boot-time provisioning legitimately write rows in an
* order that resolves only once the batch completes; failing them closed
* would turn an ordering detail into a boot failure. This leaves a real
* residual — an `isSystem` caller can still write a dangling reference —
* which is recorded on the issue rather than silently accepted.
* [#28881] ⛔ Except a flow run's elevated write (`runAs: 'system'`):
* its context carries the flow-write mark (`keepsFlowWriteReferenceCheck`,
* `@objectstack/core`, set by `resolveRunDataContext` in
* service-automation) and is checked like a user write. Its elevation is
* for authorization (other people's rows, past RLS and FLS), never for a
* link to a row that does not exist, and it keeps every authorization
* exemption `isSystem` gives it. A write it sets off (a hook's `ctx.api`,
* its `sudo()`, a cascade leg) spreads that context and is checked as
* the flow's own.
* - **Empty values are not references.** `null` / `undefined` / `''` mean
* "no link", which is what `deleteBehavior: 'set_null'` produces.
* - **Already-expanded objects are skipped.** A read round-trip can hand back
* `{id, name, …}` in the slot; that is not an id write.
* - **A value the row already stores is not the write's (#29062).** The
* check judges only the references a write ADDS. An update's `storedRows`
* (the by-id prior row; a predicate update's matched rows) forgive a
* refused value, or a multi-valued member, that every one of those rows
* already holds: an edit form carries the whole record back, and a stored
* id that has since stopped resolving (the delete walk leaves a `user`
* value in place, `DELETE_SEMANTICS_REFERENCE_TYPES`) is not the editor's
* to answer for. A value new to any of the rows is refused as before, and
* an insert has no stored rows, so every value it supplies is judged.
* [#29029] The stored rows are compared as the caller may read them
* ({@link storedReferencesCallerReads}): a column the caller cannot read
* holds no stored value for it, so it forgives nothing, and the answer is
* the same whatever the column holds. A system write compares them as
* stored, as before.
*
* ## Why the existence probe bypasses RLS — and why it keeps the tenant wall
*
* Existence is a fact about the database, not about the caller's ROW-LEVEL
* visibility — the same distinction the #4435 existence probe turns on. So
* the existence probe ({@link referenceExists}) is elevated: `isSystem`
* bypasses RBAC, RLS and FLS. Whether a NON-system caller may name the row is
* the separate question the next section answers, and it is asked first, of
* the caller's own read door, for every reference type but `tree`.
*
* That argument is about visibility, never about TENANCY, and the elevation
* is therefore `sudo()`-shaped — `{ ...context, isSystem: true }`, see
* {@link referenceExists} — not a bare `{ isSystem: true }` (#19808). The
* bare spelling carried no `tenantId`, so the probe spanned every
* organization: an org-bound caller could store a reference to another
* organization's row, and could tell "exists in another organization" (the
* write committed) from "exists nowhere" (refused) — a cross-tenant existence
* oracle. With the caller's context spread first, `buildDriverOptions`
* forwards its `tenantId` to the driver, a row stamped with another
* organization is not found, and both cases answer the same
* `reference_not_found`. The tenancy exemptions stay where they are decided:
* `buildDriverOptions` withholds `tenantId` for a `tenancy.enabled: false`
* (platform-global) object and for a federated one, so a reference to either
* still resolves from an org-bound caller. A row with no organization is no
* tenant's (ADR-0131 D1): the driver's scope is the organization equality,
* with no `IS NULL` arm, so an org-bound caller's probe does not find one.
*
* ## A non-system caller may name only a row its own read door returns (#22519, #29029)
*
* A `master_detail`, `lookup` or `user` value a non-system caller supplies
* must name a row the caller's own read door returns; a write naming a row
* the caller cannot read answers exactly what a write naming a row that
* exists nowhere answers: `reference_not_found`. So for those three types the
* caller's read door is asked first ({@link callerReadableReferenceExists}),
* then the elevated, tenant-kept existence probe for a row it returned. A
* multi-valued field is judged per member: one unreadable member refuses the
* write. Nothing upstream of this check settles it: ADR-0055 §3 gates a
* detail write on its header (master edit) only for a `controlled_by_parent`
* detail, and nothing gates a lookup on its target, so an elevated probe
* alone would let a caller bind its row to a row it has no access to, and
* tell "exists" apart from "exists nowhere". #22519 (ruling A) set the rule
* for `master_detail`; ruling records 6573561091 and 6663849489 extended it
* to `lookup` and `user` as the default, with no field-level opt-out. A
* system caller keeps the exemption above (its read door returns every row),
* and a value the row already stores is not judged again (#29062). `tree`
* keeps the elevated probe alone.
*
* One value is not the caller's choice: a reference a service verb vouches for
* on its own write (`vouchForReference`, `@objectstack/core`), naming a record
* the same call authorized and created — the file-attachments writer's
* `sys_attachment.file_id`, inserted as the caller after its own attach check.
* For exactly that object, field and id the caller's read door is not asked;
* the elevated, tenant-kept existence probe still is. Every other value, field
* and object on the write is judged as above, and the mark comes from no
* request: it is a symbol-keyed context property no body, query or stored row
* can spell.
*
* Fails OPEN when the target cannot be checked (unregistered object, no
* driver, a probe that throws): an integrity check that cannot run must not
* invent a rejection, and the alternative — refusing every write to an object
* whose target lives on an unreachable datasource — converts a connectivity
* problem into data loss. A caller's read door that fails is the exception:
* it did not return the row, so the row is missing for that caller, for a
* `master_detail`, `lookup` or `user` value alike
* (see {@link masterDetailHeadersCallerReads}).
*/
export async function assertReferencesResolve(
this: Pick<ReferentialIntegrityHost, 'logger' | 'find' | 'callerReadableReferenceExists' | 'callerReadableReferenceRow' | 'referenceExists' | 'referenceRow'>,
schema: any,
data: Record<string, unknown> | null | undefined,
supplied: Record<string, unknown> | null | undefined,
context: any,
msgCtx?: { locale?: string; translate?: any; objectName?: string },
storedRows?: StoredReferenceRows,
): Promise<void> {
// [#28881] A system caller is exempt, except a flow run's elevated write:
// its elevation is for authorization, and it keeps this check (see
// `keepsFlowWriteReferenceCheck`, @objectstack/core).
if (context?.isSystem && !keepsFlowWriteReferenceCheck(context)) return;
const fields = schema?.fields;
if (!fields || !data) return;
const refused: Array<{ name: string; def: any; value: unknown; target: string; code?: 'reference_user_banned' }> = [];
for (const name of Object.keys(fields)) {
// [#4441, narrowing kept by #4743] A `readonly` field is never the
// caller's to answer for — BY CONSTRUCTION, not by exemption.
//
// This check answers for exactly one thing: "the reference the CALLER
// named". `stripReadonlyFields` removes a non-system caller's value from
// a readonly field before the write — on BOTH write paths since #14147
// moved the create-side strip into this engine and deleted the boundary
// copy it used to live in. So a value still sitting in one at
// this point was minted by the PLATFORM — outside this check's own stated
// scope, whatever it happens to hold. That argument stands on its own and
// depends on no particular field: deleting the `continue` would start
// rejecting the platform's own writes, which is why it is recorded here
// (AGENTS.md PD #13) rather than left to be re-derived.
//
// Historical note, kept because it is how the narrowing was FOUND (the
// dogfood gate, not reasoning) and because the audit next door re-scoped
// itself on its removal: `sys_metadata_history.recorded_by` is a
// `Field.lookup('sys_user', { readonly: true })` that the metadata
// repository once filled with `actor ?? 'system'` — a SENTINEL STRING,
// not a user id, on a write carrying no `isSystem`; checking it rejected
// ordinary metadata authoring (package create / publish / clone). #4556
// replaced that sentinel with NULL, so no platform write puts a non-id in
// a reference column any more. The narrowing survives it unchanged
// because it never rested on it — but #4551's blanket audit skip did, and
// #4743/#5719 duly re-scoped that one (see `inspectDanglingReferences`).
//
// This does NOT weaken #4441: the fields the issue names —
// `sys_position_permission_set.permission_set_id` and
// `showcase_task.project` — are ordinary author-facing lookups with no
// `readonly`, and both stay enforced (pinned in the unit suite).
if (fields[name]?.readonly === true) continue;
// Only a value the CALLER actually supplied is theirs to answer for.
//
// Key presence is not enough: a form serializes an unpicked control as
// an explicit `null`, and `applyFieldDefaults` then fills it from
// `defaultValue` — including the `current_user` token (#2706). The key is
// in the payload, but the ID that lands is the PLATFORM's, so validating
// it would report a server-derived value as the caller's bad reference
// (and reject a perfectly ordinary insert against a driver that has no
// `sys_user` row for the acting principal).
//
// So the value read for the check comes from the post-normalization
// `data` (multi-value strings are already split by then), while WHETHER
// to check is decided by the caller's own raw value being non-empty.
if (!supplied || isEmptyReferenceValue((supplied as Record<string, unknown>)[name])) continue;
if (!(name in data)) continue;
const def = fields[name];
const target = referenceTargetOf(def);
if (!target) continue;
const raw = (data as Record<string, unknown>)[name];
const values = Array.isArray(raw) ? raw : [raw];
for (const v of values) {
if (v === null || v === undefined || v === '') continue;
if (typeof v === 'object') continue;
// [#22519, #29029] A master-detail header, a lookup target and a user
// must also be one the caller can read — except the one value a service
// verb vouches for on its own write: a record the same call authorized
// and created (`vouchForReference`, @objectstack/core). Its existence is
// still probed; nothing else on the write is admitted by it.
const callerReads = CALLER_READ_REFERENCE_TYPES.has(def?.type)
&& !isVouchedReference(context, schema?.name, name, v);
if (def?.type !== 'master_detail' && target === BAN_CHECKED_USER_OBJECT) {
// [#30205] One probe answers both: the row's existence and its ban.
// [#29029] The caller's read door comes first: a user it does not
// return answers as one that exists nowhere, and its ban is not read.
let row: Awaited<ReturnType<typeof this.referenceRow>>;
try {
row = callerReads
? await this.callerReadableReferenceRow(target, v, context, USER_BAN_FIELDS)
: await this.referenceRow(target, v, context, USER_BAN_FIELDS);
} catch (err) {
// Fails open like the existence probe: a check that cannot run refuses nothing.
this.logger?.warn?.('the reference check could not read the referenced user — neither its existence nor its ban was checked', {
object: target, field: name, error: err instanceof Error ? err.message : String(err),
});
row = null;
}
if (row === false) refused.push({ name, def, value: v, target });
// adr0112-ok: D6 — a field-addressed FieldErrorCode; this entry becomes `{ field, code }` below
else if (row !== null && isUserBanInForce(row)) refused.push({ name, def, value: v, target, code: 'reference_user_banned' });
continue;
}
const resolved = callerReads
? await this.callerReadableReferenceExists(target, v, context)
: await this.referenceExists(target, v, context);
if (resolved === false) refused.push({ name, def, value: v, target });
}
}
if (refused.length === 0) return;
// [#29062] A refused value every row this write lands on already stores
// is not a reference the write ADDS, so it is not this caller's to answer
// for. The stored rows are read only now, once a probe has refused.
// [#29029] …and only as this caller may read them
// ({@link storedReferencesCallerReads}): the update's reference forgiveness
// compares only stored values the caller may read, so a column it cannot
// read forgives nothing, and its value is refused like any other.
const storedAsStored = storedRows ? (await storedRows() ?? []).filter(isRow) : [];
const stored = storedAsStored.length === 0
? storedAsStored
: await storedReferencesCallerReads.call(this, schema?.name, storedAsStored, [...new Set(refused.map((r) => r.name))], context);
const failures = refused
.filter((r) => stored.length === 0 || !stored.every((row) => storedReferenceIds(row[r.name]).has(String(r.value))))
.map((r) => buildFieldError(
{
field: r.name,
code: r.code ?? 'reference_not_found',
def: r.def,
value: String(r.value),
constraint: { target: r.target },
},
msgCtx as any,
));
if (failures.length > 0) throw new ValidationError(failures);
}
/**
* [#30205] The user object whose rows a reference check also asks about a ban.
*
* Banning a user leaves the row in place, so the existence probe resolves a
* banned user like any other, and a write could hand new work to someone who
* cannot sign in to do it (`POST /data/OBJECT` with `assignee` set to the
* banned user answered 201). The check refuses that with
* `reference_user_banned`, on the same terms as `reference_not_found`: only a
* caller-supplied value, only a value the write ADDS (a row that already holds
* the banned user stays editable, and is handed over by the transfer
* instead), never a system write the reference check exempts.
*
* The ban columns ride the existence probe's own read (`referenceRow`), so the
* check costs no read of its own and is read the way the probe reads:
* elevated inside the caller's tenant, because a ban is a fact about the
* user, not about what the caller may read. A probe that cannot run refuses
* nothing, as before, and logs a warning. The caller's read door is asked
* before the probe, as for every `lookup` and `user` value (#29029): a user
* the caller cannot read answers `reference_not_found`, and its ban is not read.
*/
const BAN_CHECKED_USER_OBJECT = 'sys_user';
/**
* [#29062] The rows a write lands on, as stored before it, read on demand by
* {@link assertReferencesResolve}: the by-id update's prior row, or the
* matched rows of a predicate update. Absent (an insert), every value the
* caller supplied is the write's own.
*/
export type StoredReferenceRows = () => Promise<ReadonlyArray<Record<string, unknown> | null | undefined> | null>;
function isRow(row: unknown): row is Record<string, unknown> {
return row !== null && typeof row === 'object';
}
/**
* [#29029] The stored rows an update's reference forgiveness compares against,
* as THIS caller may read them: for each of `rows`, only the `fields` the
* caller's own read door serves for that row exactly as stored
* ({@link servedAsStored}). One `find` for the batch, under the caller's own
* context, so every enforcement layer in the middleware chain (RBAC, RLS,
* sharing, field-level security) answers it, as it answers
* {@link masterDetailHeadersCallerReads}.
*
* A column the caller cannot read — hidden, masked or rewritten for it — is
* absent from the row returned here, so it holds no stored id and forgives
* nothing: the value the write names is judged like any other, and the
* answer does not depend on what the column holds. A row the read door does
* not return, or a read that fails, keeps no column either; ⛔ never the row
* as stored. A caller who can read the column keeps the forgiveness: an
* unchanged stored reference is still accepted.
*
* A SYSTEM caller (a flow run's elevated write, the one system write the
* reference check judges) is answered with `rows` unchanged, as before.
*/
export async function storedReferencesCallerReads(
this: Pick<ReferentialIntegrityHost, 'find' | 'logger'>,
object: unknown,
rows: ReadonlyArray<Record<string, unknown>>,
fields: ReadonlyArray<string>,
context: ExecutionContext | undefined,
): Promise<ReadonlyArray<Record<string, unknown>>> {
if (context?.isSystem) return rows;
const ids = new Map<string, unknown>();
for (const row of rows) {
const id = row.id;
if (typeof id === 'string' || typeof id === 'number') ids.set(String(id), id);
}
const served = new Map<string, Record<string, unknown>>();
if (typeof object === 'string' && object && ids.size > 0) {
const values = [...ids.values()];
try {
const found = await this.find(object, {
where: { id: values.length === 1 ? values[0] : { $in: values } },
fields: ['id', ...fields],
context,
} as EngineQueryOptions) as Array<Record<string, unknown>>;
for (const row of Array.isArray(found) ? found : []) {
if (isRow(row) && row.id != null && ids.has(String(row.id))) served.set(String(row.id), row);
}
} catch (err) {
this.logger?.warn?.('the caller\'s read of the stored record failed — its stored references forgive nothing', {
object, error: err,
});
}
}
return rows.map((row) => {
const view = row.id != null ? served.get(String(row.id)) : undefined;
const kept: Record<string, unknown> = {};
if (!view) return kept;
for (const field of fields) {
if (Object.prototype.hasOwnProperty.call(view, field) && Object.prototype.hasOwnProperty.call(row, field)
&& servedAsStored(view[field], row[field])) {
kept[field] = row[field];
}
}
return kept;
});
}
/** The ids a stored reference value holds: each member of a multi-valued one, or the one scalar. */
function storedReferenceIds(value: unknown): ReadonlySet<string> {
const members = Array.isArray(value) ? value : [value];
const ids = new Set<string>();
for (const m of members) if (typeof m === 'string' || typeof m === 'number') ids.add(String(m));
return ids;
}
/**
* [#22519] Read 1 of the write's master-detail header read: which of `ids`
* the caller's READ DOOR returns — one `find` for the whole batch, under the
* caller's own context, so every enforcement layer in the middleware chain
* (RBAC, RLS, sharing, row scope) answers it, as it answers the preview's
* first read ({@link resolvePreviewParents}). Projected to `id`: what the
* header HOLDS is read 2's question, never this one's.
*
* A header it does not return binds as a header that exists nowhere binds:
* the reference check answers `reference_not_found` for it
* ({@link callerReadableReferenceExists}), and the write's header resolution
* leaves `parent` unbound for it ({@link resolveMasterDetailParent},
* {@link resolveMasterDetailParents}). A read that fails — a refusal of the
* read itself included — returned no header, so every header binds as
* missing, as the preview binds them and as the write's own failed header
* read does; ⛔ never as readable.
*
* A SYSTEM caller (seed replay, boot) has no read door to ask: every id goes
* straight to read 2, and its write resolves exactly as before.
*/
export async function masterDetailHeadersCallerReads(
this: Pick<ReferentialIntegrityHost, 'find' | 'logger'>,
master: string,
ids: ReadonlyArray<unknown>,
context: ExecutionContext | undefined,
): Promise<ReadonlySet<string>> {
const asked = new Map<string, unknown>();
for (const id of ids) if (id != null) asked.set(String(id), id);
if (context?.isSystem || asked.size === 0) return new Set(asked.keys());
// One id is asked by equality, the predicate shape the elevated probe
// already sends; a batch by `$in`, as read 2 of the batch reads it.
const values = [...asked.values()];
try {
const rows = await this.find(master, {
where: { id: values.length === 1 ? values[0] : { $in: values } },
fields: ['id'],
context,
} as EngineQueryOptions) as Array<Record<string, unknown>>;
const served = new Set<string>();
for (const row of Array.isArray(rows) ? rows : []) {
if (row?.id != null && asked.has(String(row.id))) served.add(String(row.id));
}
return served;
} catch (err) {
this.logger?.warn?.('the caller\'s read of the referenced record failed — it answers as a record that does not exist', {
object: master, error: err,
});
return new Set();
}
}