Repository navigation
Expand file tree
/
Copy pathengine-top-level.ts
More file actions
4987 lines (4840 loc) · 256 KB
/
Copy pathengine-top-level.ts
File metadata and controls
4987 lines (4840 loc) · 256 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
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
// [#29986 codemod] The top-level declarations ahead of `ObjectQL` in
// `engine.ts` that moved out whole by `scripts/codemod-split-engine.mjs` (lever
// (b) of ruling 6591753301).
//
// A MOVE, not a redesign: each declaration below is its `engine.ts` text
// exactly, with the comments above it, in the order it stood there. A LEAF:
// it imports neither `engine.ts` nor any `engine-*` module, so it is
// evaluated before the class and forms no cycle with it. `engine.ts`
// re-exports, by name, every declaration here it exported before, so every
// importer of `./engine.js` reads what it read.
import { AUDIT_PROVENANCE_FIELDS, ENGINE_UPDATE_UPSERT_REMOVED, FILE_REFERENCE_TYPES, FullTextSearchSchema, QUERY_CURSOR_REMOVED, QUERY_DISTINCT_REMOVED, REFERENCE_VALUE_TYPES, RPC_QUERY_ALIAS_SLOTS, VALID_AST_OPERATORS, foldQueryAliasSlots, isFilterAST, isMultiValueField, lowerFilterCondition, normalizeFilterComparandTypes, parseFilterAST, readAutonumberCounter, referenceCarrierOf, referenceTargetOf, resolveInjectedColumnProvenance } from '@objectstack/spec/data';
import type { DroppedFieldsEvent, FilterCondition, FilterLoweringOptions, HookContext, QueryAST, QueryAliasSlot, RecycleBinClearedReference, ServiceObject } from '@objectstack/spec/data';
import type { EngineFilterJudgement, ISecurityService } from '@objectstack/spec/contracts';
import { assertFilterIsMaterializable, assertListComparandShapes, collectComposableReadableIds, invalidFilterError } from './filter-comparand-shape.js';
import { assertResolvedTemporalTokensInRange, assertTemporalComparandsInterpretable } from './temporal-comparand-door.js';
import type { ResolvedTokenJudge } from './temporal-comparand-door.js';
import { assertTextOperatorTargetsAreStringCapable } from './text-operator-declared-type-door.js';
import { mapRelationConditions, narrowNumberComparands } from './number-comparand-declared-type-door.js';
import { lowerRelationSite } from './relation-filter-lowering.js';
import type { RelationFilterSite } from './relation-filter-lowering.js';
import { SystemFieldName } from '@objectstack/spec/system';
import { judgeCollectionItemOwnerStamp } from '@objectstack/spec/kernel';
import type { ExecutionContext } from '@objectstack/spec/kernel';
import type { FlowFunctionEffect } from '@objectstack/spec/automation';
import { filterTokenContextFrom, resolveFilterTokens } from '@objectstack/core';
import type { IDataDriver } from '@objectstack/core';
import { ORGANIZATION_OBJECT } from './tenancy/system-write-organization.js';
import { judgePermissionSetOwnerBinding } from '@objectstack/spec/security';
import type { TenantLayer0Verdict } from '@objectstack/spec/security';
import { applyProtection, pluralToSingular } from '@objectstack/spec/shared';
import type { SchemaRegistry } from './registry.js';
import { SEARCHABLE_ENUM_TYPES, SEARCHABLE_TEXTUAL_TYPES } from './search-filter.js';
import { ExpressionEngine, analyzeRelationshipTraversals, isUnparseableDate } from '@objectstack/formula';
import type { EvalError, EvalOptionLabels, EvalPermissions } from '@objectstack/formula';
import { declaredOptionLabels } from './formula-option-labels.js';
import { ASSEMBLED_VIEW_ITEMS_KEY, AssembledViewArtifactSchema, isAggregatedViewContainer, isViewContainerShaped } from '@objectstack/spec';
import type { Expression } from '@objectstack/spec';
import { deriveViewContainerObject } from '@objectstack/metadata/view-container';
import { viewContainerNameRefusal } from './view-container-name-refusal.js';
import { ValidationError } from './validation/record-validator.js';
import type { FieldValidationError } from './validation/record-validator.js';
import { collectReferenceTraversals, referenceTraversalConflicts, staticReadonlyInsertSubject, stripReadonlyFields } from './validation/rule-validator.js';
import type { RelatedFieldBinding, RelatedRecordBinding } from './validation/rule-validator.js';
import { declaredColumnSet } from './declared-read-columns.js';
/**
* One read of a `sys_migration` flag row: the verdict, plus whether the ledger
* could actually be consulted to reach it (#4769). Both negatives keep the
* gate closed; only the conclusive one is worth remembering.
*/
export interface MigrationFlagRead {
verified: boolean;
conclusive: boolean;
/**
* [#15989] Have the file-family COLUMNS on this deployment moved to the
* bare-id encoding — `hasMovedFileColumns` over the same row?
*
* Carried on the SAME read rather than fetched by a second one, because it
* is a second question about one row and two reads could answer them out of
* one another's date. It is `false` on every row that lacks the stamp, on an
* unverified row, and on every way of not having read a row at all.
*/
columnsMoved: boolean;
}
/**
* What this boot has ADMITTED against one ADR-0104 migration's contract —
* the counterexample that forbids attesting it (#4769). `count` is a lower
* bound (every admitted value is counted, but a revocation records the total
* known at the moment it wrote); `first` is the one an operator is shown,
* because a prescription needs a place to start, not a census.
*/
export interface AdmittedValueShapeViolationTally {
count: number;
first: { object: string; field: string; type: string; detail: string };
}
/**
* The lifecycle events the engine actually dispatches via `triggerHooks`. This
* is the single source of truth for what a hook can subscribe to — kept in
* lockstep with the `triggerHooks(...)` call sites and with `HookEvent` in the
* spec. `beforeFind`/`afterFind` cover both `find` and `findOne`; the write
* events cover both single-id and bulk (`multi: true`) writes (#3195). A hook
* subscribing to anything outside this set would silently never fire, so
* `registerHook` refuses it where the name is one of the engine's own
* ({@link UNDISPATCHED_LIFECYCLE_HOOK_EVENTS}, #17713) and warns otherwise.
*
* ## WHEN `after*` fires, relative to the commit (#7477)
*
* `afterInsert`/`afterUpdate`/`afterDelete` are dispatched INSIDE the unit of
* work, before the enclosing transaction (if any) commits. The declared
* meaning is **"the write has been requested and will happen unless this unit
* of work is undone"** — not "the write happened". This is the ruled semantics
* (#7477, 2026-08-11), not an accident of the current call sites: an `after*`
* dispatch is deliberately NOT deferred to commit, because deferring it would
* push a handler's own `ctx.api` writes outside the transaction the write ran
* in, and an in-engine audit hook depends on landing inside it.
*
* Four ordinary paths open such a unit around the dispatch:
* - the write door itself, when the object has a metadata-bound `after*`
* hook that can abort — blocking with `onError` `abort`, or carrying a
* `condition` — so that abort rolls the row back as `HookSchema.onError`
* says (#22782, #22856, `opensAfterAbortUnit`);
* - a by-id {@link ObjectQL.delete} whose cascade is `'atomic'` — each
* dependent's own `afterDelete` fires inside the wrap the parent opened,
* and the parent's row removal can still refuse afterwards (#7413). The
* PARENT's `afterDelete` is outside that wrap by construction (inside the
* door's own unit when the first path opened one); the cascaded
* CHILDREN's are not;
* - `runAtomicBatch` in `@objectstack/metadata-protocol` —
* `batchData`/`deleteManyData` with `atomic: true` runs every member's
* `after*` inside one transaction that aborts on the first failure
* (#4620);
* - any caller that opened `transaction()` / `ctx.api.transaction()` around
* the write itself.
*
* A rollback on any of those leaves a hook that fired for a row that still
* exists. Effects routed back through this engine roll back with it and are
* therefore safe; effects that leave the engine — webhooks, notifications,
* external index updates, file deletion — are the HANDLER's responsibility to
* make rollback-tolerant (idempotent and reconcilable, or re-checked against
* the row by a worker rather than trusted from the event alone). Documented
* for authors on `HookEvent` in `@objectstack/spec/data` and in
* `content/docs/automation/hooks.mdx`.
*/
const DISPATCHABLE_HOOK_EVENTS: ReadonlySet<string> = new Set([
'beforeFind', 'afterFind',
'beforeInsert', 'afterInsert',
'beforeUpdate', 'afterUpdate',
'beforeDelete', 'afterDelete',
]);
/**
* [#17713] Every verb the engine can put on an {@link OperationContext}, as
* DATA rather than as a second hand-written list.
*
* The type annotation is the weld: `Record<Union, true>` is exhaustive in both
* directions, so a new engine method that widens `OperationContext['operation']`
* fails to compile here until the verb is added, and a verb dropped from the
* union makes its entry an excess property. `pnpm typecheck` compiles this file
* (it is `src`, not the test layer), so the weld is enforced by the package's
* own type check and not only by a test.
*
* It exists so {@link UNDISPATCHED_LIFECYCLE_HOOK_EVENTS} below is DERIVED. A
* hand-written list of "the events we refuse" would be this card's own defect
* one layer up: it would go stale the moment a verb is added, and silently.
*/
const ENGINE_OPERATION_VERBS: Record<OperationContext['operation'], true> = {
find: true,
findOne: true,
insert: true,
update: true,
delete: true,
count: true,
aggregate: true,
};
/**
* [#17713] The engine's own lifecycle-event NAMESPACE — `before`/`after` × every
* verb in {@link ENGINE_OPERATION_VERBS}. Fourteen names, of which
* {@link DISPATCHABLE_HOOK_EVENTS} is the eight the engine actually dispatches.
*/
const ENGINE_LIFECYCLE_HOOK_EVENTS: ReadonlySet<string> = new Set(
Object.keys(ENGINE_OPERATION_VERBS).flatMap((verb) => {
const suffix = `${verb.charAt(0).toUpperCase()}${verb.slice(1)}`;
return [`before${suffix}`, `after${suffix}`];
}),
);
/**
* [#17713] The GAP: a name inside the engine's own lifecycle namespace that the
* engine never dispatches. Derived, never typed out — the difference of the two
* sets above.
*
* Today it is exactly six: `beforeFindOne` / `afterFindOne`, `beforeCount` /
* `afterCount`, `beforeAggregate` / `afterAggregate`. Registering one of them is
* REFUSED at the door ({@link assertDispatchableHookEvent}) rather than warned
* about, because each is a name an author reaches for while believing they are
* subscribing to an engine lifecycle event — and what they get back is an inert
* declaration (ADR-0078: no silently inert declaration), which on a read filter
* means a guardrail that was never armed.
*
* ⚠️ The refusal is deliberately scoped to THIS set, not to "anything outside
* `DISPATCHABLE_HOOK_EVENTS`". A name outside the namespace entirely
* (`'myPlugin:flush'`) is a plugin dispatching its own event through the public
* {@link ObjectQL.triggerHooks} — the legitimate reading that made this branch a
* warn in the first place (#3195). That reading survives untouched; what stops
* being accepted is a near-miss spelling of the engine's OWN vocabulary, where
* no such reading exists.
*/
const UNDISPATCHED_LIFECYCLE_HOOK_EVENTS: ReadonlySet<string> = new Set(
[...ENGINE_LIFECYCLE_HOOK_EVENTS].filter((event) => !DISPATCHABLE_HOOK_EVENTS.has(event)),
);
/**
* [#17713] Test-visible view of the three sets the refusal is computed from, so
* a pin can drive its population FROM THE ENGINE instead of restating it — the
* acceptance criterion this card wrote ("a test per event name the engine
* exposes but never dispatches") is only meaningful if the population is read,
* not typed.
*
* Module-level export, deliberately NOT added to the package barrel
* (`src/index.ts` names its exports one by one), so this widens no published
* surface.
*/
export const HOOK_EVENT_DISPATCH_VOCABULARY = {
dispatchable: DISPATCHABLE_HOOK_EVENTS,
lifecycleNamespace: ENGINE_LIFECYCLE_HOOK_EVENTS,
undispatchedLifecycle: UNDISPATCHED_LIFECYCLE_HOOK_EVENTS,
} as const;
/**
* [#4346] The alias slots the ENGINE option bags still admit, cut from the
* spec's own table (#3795) so the engine never re-declares a mapping.
*
* The deprecated `DataEngine{Query,Update,Delete,Count,Aggregate}Options`
* contracts declare `filter` on every read AND write method, but only `find`
* folded it — `findOne`/`count`/`update`/`delete`/`aggregate` passed the bag
* through with `where === undefined`, which every driver reads as "no
* predicate": a caller filtering with `{ filter }` silently matched EVERY row
* (an over-grant on the reads, an unbounded write on `update`/`delete`).
*
* `where` is the slot every method folds; `limit` additionally applies to the
* find-shaped bags, which declare `top` (OData) as its alias. The other four
* pairs in the table are wire spellings folded at parse by
* `QueryWithTransportSchema` / the protocol normalizer — their values need shape
* lowering (`sort` records, `populate` lists) that belongs to those layers, so
* the engine deliberately does not fold them.
*/
export const ENGINE_WHERE_SLOTS: readonly QueryAliasSlot[] =
RPC_QUERY_ALIAS_SLOTS.filter((slot) => slot.canonical === 'where');
const ENGINE_QUERY_SLOTS: readonly QueryAliasSlot[] =
RPC_QUERY_ALIAS_SLOTS.filter((slot) => slot.canonical === 'where' || slot.canonical === 'limit');
/**
* [#4371] The slots the engine does NOT fold — the wire-only pairs
* (`select`→`fields`, `sort`→`orderBy`, `skip`→`offset`, `populate`→`expand`),
* derived as the complement of {@link ENGINE_QUERY_SLOTS} so a seventh pair
* added to the spec table lands on exactly one side of the split.
*
* Their values need shape lowering (`sort`'s `{field: 'asc'}` record form,
* `populate`'s name list) that belongs to the RPC/protocol layers, so folding
* here would re-implement the lowering per reader — the #3795 condition. But a
* DIRECT engine call never crosses those layers: the alias key used to ride
* the AST verbatim, drivers read only the canonical name, and the parameter
* was silently dropped — three shipped "latest N in arbitrary order" bugs
* (#4370) plus the engine's own `seedAutonumber`. Declared ≠ enforced
* (AGENTS.md PD #10): the find-shaped entry points now REJECT these spellings,
* naming the canonical key and shape, so the mistake throws at the call site
* instead of degrading the result.
*
* Deliberately NOT applied to the where-only methods
* (`update`/`delete`/`count`/`aggregate`): their contracts honour no
* sort/projection/pagination at all, so "pass `orderBy` instead" would
* redirect the caller to a key those methods silently ignore too. Unknown-key
* enforcement for those bags is #4371's option (2), scoped separately.
*/
const ENGINE_WIRE_ONLY_SLOTS: readonly QueryAliasSlot[] =
RPC_QUERY_ALIAS_SLOTS.filter((slot) => !ENGINE_QUERY_SLOTS.includes(slot));
/**
* Canonical shape each wire-only slot's value must be rewritten into — quoted
* by the rejection so the error carries the full migration, not just the key
* rename (the value shapes differ; that is WHY the engine cannot fold them).
*/
const WIRE_ONLY_CANONICAL_SHAPES: Record<string, string> = {
fields: "a string[] of field names",
orderBy: "SortNode[]: [{ field, order: 'asc' | 'desc' }]",
offset: 'a number of rows to skip',
expand: 'a record of { relationName: QueryAST }',
};
/**
* [#4371 option 2] The driver-option keys the engine forwards verbatim: on
* `find`/`findOne`/`update`/`delete` the bag's DECLARED driver-option keys
* are the base of the driver options (`buildDriverOptions(object, ctx, bag)`
* keeps those and nothing else of the bag — `pickDeclaredDriverOptions`),
* which is how a caller's explicit `tenantId` / `bypassTenantAudit` reaches
* the driver (pinned in engine.test.ts). `count`/`aggregate` never forward the bag, so these keys
* are deliberately NOT legal there — accepting them would be the exact
* silently-ignored contract this gate exists to close.
*/
const ENGINE_DRIVER_PASSTHROUGH_KEYS = [
'transaction', 'tenantId', 'tenantIds', 'timezone', 'bypassTenantAudit', 'preserveAudit',
] as const;
/**
* [#4371 option 2] Per-method legal option keys. An option bag key outside
* the method's set is REJECTED at the entry point: the engine executes none
* of them, so the call would otherwise succeed with the option silently
* ignored — the `declared ≠ enforced` shape (PD #10) one layer below the
* wire-alias rejection above.
*
* Sources, in order: the method's `Engine*OptionsSchema` declared keys (minus
* the `retiredKey` tombstones `cursor`/`distinct`/`upsert` (#8057), which get
* their tombstone quoted instead of a generic rejection — the schema keeps them
* ONLY to carry that message, and this runtime path never parses); `searchFields` (read by
* `find` and `aggregate` at the `$search` expansion, sent by the protocol layer);
* `onFieldsDropped` and `strictReadonlyWrites` (`WriteObservabilityOptions` —
* contract-declared, deliberately outside the serializable Zod schema: the
* first because a function is unrepresentable in JSON Schema, the second
* because #5126 ruled that a write-refusal switch must not be settable from a
* wire body); and the driver pass-through keys above. The alias spellings
* (`filter`/`top`) are folded and deleted BEFORE this check runs, so they
* never reach it.
*
* A drift pin in engine-unknown-option.test.ts asserts each set equals its
* schema's shape (minus tombstones, plus the documented extras) so a key
* added to the spec cannot be silently rejected here.
*/
const ENGINE_FIND_OPTION_KEYS: ReadonlySet<string> = new Set([
'context', 'where', 'fields', 'orderBy', 'limit', 'offset',
'search', 'searchFields', 'expand',
...ENGINE_DRIVER_PASSTHROUGH_KEYS,
]);
const ENGINE_UPDATE_OPTION_KEYS: ReadonlySet<string> = new Set([
'context', 'where', 'multi', 'returning', 'onFieldsDropped', 'onValidationAdvisory', 'onMentionsWithheld', 'onNotice', 'strictReadonlyWrites',
...ENGINE_DRIVER_PASSTHROUGH_KEYS,
]);
const ENGINE_DELETE_OPTION_KEYS: ReadonlySet<string> = new Set([
'context', 'where', 'multi',
...ENGINE_DRIVER_PASSTHROUGH_KEYS,
]);
// `search` / `searchFields` are READ by `count` and `aggregate` through the
// same ADR-0061 expander `find` uses ({@link ObjectQL.expandSearchOnOptions}),
// so a count or a grouped answer under a search is over the searched rows.
// Before their schemas declared them they were refused here, and the wire paths
// left them out: the unsearched groups answered, and a paged list's `total`
// under a search was a page-local estimate (#22790).
export const ENGINE_COUNT_OPTION_KEYS: ReadonlySet<string> = new Set(['context', 'where', 'search', 'searchFields']);
const ENGINE_AGGREGATE_OPTION_KEYS: ReadonlySet<string> = new Set([
'context', 'where', 'groupBy', 'aggregations', 'having', 'timezone',
'search', 'searchFields',
]);
/**
* [#27732] A search-field override — `searchFields`, or the object-form
* `search.fields` — that names no field is refused `400 VALIDATION_ERROR`:
* an empty list, or a comma string with no name in it (the `GET` door's
* transport spelling, which reaches the engine as sent). Absent (or `null`)
* still searches the object's default search fields.
*
* `resolveSearchFields` reads an empty override as absent, so the search
* widened to the whole default set: the caller wrote the key to narrow and was
* not told. The door refuses this set (`assertSearchFieldsAreSearchable`,
* #27484) and `QuerySchema.searchFields` / `FullTextSearchSchema.fields`
* declare the same refusal (#27683); the words are read off that declaration
* rather than copied, and the status and code are the door's, so
* `mapDataError` answers an in-process caller and a REST caller alike. Any
* other value is left to the expansion's existing tolerance.
*/
function refuseSearchOverrideNamingNoField(object: string, requested: unknown, param: string): void {
const names = typeof requested === 'string'
? requested.split(',').map((s) => s.trim()).filter(Boolean)
: Array.isArray(requested) ? requested : undefined;
if (names === undefined || names.length > 0) return;
const declared = FullTextSearchSchema.shape.fields.safeParse([]).error?.issues[0]?.message;
const err: any = new Error(
`ObjectQL search on '${object}' names no field in '${param}': got ${JSON.stringify(requested)}. The query was not run: `
+ "an empty search-field list was read as no narrowing, which scans the object's default search fields. "
+ `${declared}.`,
);
err.status = 400;
err.code = 'VALIDATION_ERROR';
err.param = param;
err.object = object;
throw err;
}
/**
* [#28120] …and an override that names no field the search can scan is refused
* `400 INVALID_FIELD`, the code the door answers the same value with
* (`assertSearchFieldsAreSearchable`, #4254): every name unknown, unsearchable,
* or withheld from the scan (`internal: true`, credential types), or no entry a
* field name at all.
*
* `resolveSearchFields` drops the names outside the allowed set and, when none
* is left, falls back to the whole set — the typo or the renamed field the
* caller wrote to narrow the search ran over the object's default fields
* instead, untold. Judged on the set the expansion resolves over (`allowed`),
* so this refuses exactly the overrides that fallback would have widened. An
* override naming at least one allowed field is left to the intersection (the
* engine's tolerance for the other names stands), and an empty `allowed` is
* left to the expansion's own refusal (#24284), which names that cause.
*/
function refuseSearchOverrideNamingNoSearchableField(
object: string,
requested: unknown,
param: string,
allowed: readonly string[],
): void {
const entries = typeof requested === 'string'
? requested.split(',').map((s) => s.trim()).filter(Boolean)
: Array.isArray(requested) ? requested : undefined;
if (entries === undefined || entries.length === 0 || allowed.length === 0) return;
const allowSet = new Set(allowed);
if (entries.some((f) => typeof f === 'string' && allowSet.has(f))) return;
const names = entries.filter((f): f is string => typeof f === 'string');
const err: any = new Error(
`ObjectQL search on '${object}' names no searchable field in '${param}': got ${JSON.stringify(requested)}. `
+ 'The query was not run: an override naming none of the fields the search scans was dropped, which '
+ "scans the object's default search fields. Name a searchable field, or leave the override out to "
+ 'search the default fields.',
);
err.status = 400;
err.httpStatus = 400;
err.code = 'INVALID_FIELD';
if (names.length > 0) {
err.field = names[0];
err.fields = names;
}
err.param = param;
err.object = object;
throw err;
}
/**
* Rows per page for the autonumber seeding scan (#6249). This is a PAGE size,
* not a cap: the walk pages until the scope is exhausted. The number is the one
* the old single-shot `limit: 5000` used, kept so the per-read cost against a
* driver is unchanged — what changed is that reaching it no longer ends the
* scan and truncates the max.
*/
const AUTONUMBER_SEED_PAGE_SIZE = 5000;
/**
* How many times one insert may re-seed and re-issue after a unique-constraint
* collision on an engine-issued autonumber (#6806) before it refuses.
*
* Bounded on purpose. The FIRST re-issue is the one that matters: the collision
* proves the in-memory counter sits below the store's real max, and the re-seed
* that follows reads that max back, so attempt 2 is issued from the truth. A
* further collision means another writer took the number in between — real
* concurrency, which more spinning does not resolve (each attempt costs a full
* scope scan). Two spare attempts absorb a burst; past that the write fails
* loudly rather than looping against a live competitor.
*/
const AUTONUMBER_COLLISION_ATTEMPTS = 3;
/**
* One autonumber the ENGINE issued on a row, paired with the counter it came
* from (#6806). Only engine-issued values are listed: a value an exempt writer
* supplied is the caller's, and a collision on it is the caller's to see.
*/
interface IssuedAutonumber {
/** Field the value was written to. */
readonly field: string;
/** `object.field.<scope>` key in {@link ObjectQL.autonumberCounters}. */
readonly counterKey: string;
}
/**
* [#17052] The write doors' failure META, assembled at the call site because
* the level moved off `error`.
*
* ## Why the level moved
*
* `insert` / `update` / `delete` each end in a `catch` whose next statement is
* `throw e`. AGENTS.md → *Degradation log levels* calls that shape out by name:
* "a failure handed to the CALLER is not a degradation at all … Do not bolt a
* `logger.error` onto such a site". The requester IS told — the throw is the
* answer — so an `error` line is a second, louder report of a fact the caller
* already has, and nothing downstream can tell it apart from a real one. The
* measured cost was a healthy first boot of every fresh project printing
* `ERROR Insert operation failed` while `@better-auth/oauth-provider` seeded
* `sys_oauth_resource` and treated the UNIQUE collision as the no-op its own
* docblock declares it to be.
*
* ## Why the diagnosis needs this helper to survive the move
*
* The `Logger` contract (`packages/spec/src/contracts/logger.ts`) gives an
* `Error` slot to `error` and `fatal` ONLY: `warn(message, meta?)` has two
* parameters, not three. Handing the redacted driver error to `warn` as `meta`
* does not merely lose the slot — `Error.message` and `Error.stack` are
* NON-ENUMERABLE, so every logger that renders meta by spreading it would
* serialize `{}` and the entry would arrive carrying nothing at all. That is
* exactly the loss #14095 refused (the failing column, MySQL's index name, the
* driver's own frames) arriving one level down.
*
* So the two shaped-by-ruling properties are preserved by building the meta the
* way `ObjectLogger.write()` builds it from the slot — `{ …meta, error: {
* message, stack } }` — rather than by handing over the Error:
*
* - **#8682** the value redaction still runs: callers pass
* `redactBoundStatement(...)`, and it is that result's `message`/`stack`
* that are read here.
* - **#14095** the log still takes the driver's error (the envelope's
* `cause`), not the envelope: callers still choose which value to hand in.
*
* The non-Error branch mirrors `ObjectLogger.writeErrorLike()`'s own fallback
* (`{ ...errorOrMeta, ...meta }`, the later argument winning), so a thrown
* non-Error — or a `DuplicateRecordError` with no `cause` — renders as it did.
*
* @param logged The value to report — already redacted by the caller.
* @param meta The entry's own meta (`object`, and `developerMessage` on the
* delete door).
*/
export function writeFailureLogMeta(
logged: unknown,
meta: Record<string, unknown>,
): Record<string, unknown> {
return logged instanceof Error
? { ...meta, error: { message: logged.message, stack: logged.stack } }
: { ...(logged as Record<string, unknown> | undefined), ...meta };
}
/**
* [#24948] The refusal of a predicate (`multi`) delete of `sys_organization`:
* the standard `DELETE_RESTRICTED`, saying to delete by id. An organization is
* deleted one at a time, through plugin-auth's organization delete: its
* refusal of an organization that still owns records and its
* `beforeDeleteOrganization` clean-up of the organization's teams, team members
* and admin grants run there, once per organization. A delete matching
* organizations by a filter runs neither, and no caller needs one.
*/
function organizationPredicateDeleteRefusal(): Error {
const err: any = new Error(
'Organizations are deleted one at a time, by id: a delete matching organizations by a filter is refused. ' +
'Delete each organization by its id.',
);
err.developerMessage =
`A predicate delete of ${ORGANIZATION_OBJECT} is refused: organizations are deleted one at a time, because ` +
"plugin-auth's organization delete refuses an organization that still owns records and removes its teams, " +
'team members and admin grants per organization, and a predicate delete runs neither. Delete each organization ' +
`by id (engine.delete('${ORGANIZATION_OBJECT}', { where: { id } })).`;
err.code = 'DELETE_RESTRICTED';
err.status = 409;
err.httpStatus = 409;
err.object = ORGANIZATION_OBJECT;
return err;
}
/**
* Read the counter out of ONE stored autonumber value, under #6468's anchoring
* rules. Shared by the seeding scan and by the adopt-on-exempt-write resync
* (#6806) so both readings can never drift apart — a divergence here is a
* duplicate record number, which is the harm the whole family is about.
*
* The ANCHORED reading itself is NOT this package's (#6560): it is the inverse
* of `renderAutonumber`'s composition, so it lives beside it as spec's
* {@link readAutonumberCounter}, which the SQL driver's `scanMaxNumericTail`
* calls over the same two strings. This function adds only the piece the two
* sides genuinely do not share:
*
* - **Either `prefix` or `suffix` declared ⇒ ANCHORED**: spec answers, and its
* TSDoc carries the rationale (counter after the prefix, suffix stripped
* when it matches and never required to match, out-of-scope values read as
* `undefined`).
* - **Neither declared ⇒ UNANCHORED**: this engine's own legacy reading — the
* LAST digit run of the whole value — kept byte-for-byte by PR #6553. The
* SQL driver's legacy reading of the same case is deliberately DIFFERENT (it
* concatenates every digit), which is exactly why spec refuses to answer for
* an unanchored slot instead of picking one of the two.
*
* # The unanchored arm is IMPLEMENTATION DETAIL, outside the declared contract (#7287)
*
* Spec's refusal above is no longer just an absence of agreement: the #7287
* ruling (2026-08-10, 「宣告边界」) DECLARES that a stored value carrying
* non-digit content on an unanchored format is out of contract for counter
* readback, and that `readAutonumberCounter`'s `undefined` for that slot is the
* contract rather than a gap. The boundary and its rationale live in that
* function's TSDoc in `packages/spec/src/data/autonumber-format.ts`; the pins
* are `packages/spec/src/data/autonumber-unanchored-boundary.test.ts`.
*
* So the last-digit-run reading below is THIS ENGINE'S behavior, not a promise
* the platform makes. On the inputs the contract admits — pure-digit values,
* which is what `renderAutonumber` emits for an unanchored format — it answers
* the same number the SQL driver does. On mixed-content values it may answer
* differently (`'SO-2024-0007'` → `7` here, `20240007` there), and that
* difference is out of contract on both sides, not a defect on either.
*
* Consequently the ruling moves nothing here: neither this reading nor the
* driver's was hoisted into the shared helper, precisely because doing so would
* move live behavior on the other side over record numbers already issued.
*
* The unanchored branch uses the linear `/\d+/g` — a backtracking lookahead here
* is a polynomial-ReDoS sink on stored values full of zeros (CodeQL
* js/polynomial-redos).
*/
function readStoredAutonumberCounter(value: string, prefix: string, suffix: string): number | undefined {
if (prefix !== '' || suffix !== '') return readAutonumberCounter(value, prefix, suffix);
const runs = value.match(/\d+/g);
const digits = runs ? runs[runs.length - 1] : undefined;
if (!digits) return undefined;
const n = parseInt(digits, 10);
return Number.isFinite(n) ? n : undefined;
}
/** Tombstoned option keys: rejected with the spec's own removal notice. */
const ENGINE_RETIRED_OPTION_MESSAGES: Record<string, string> = {
cursor: QUERY_CURSOR_REMOVED,
distinct: QUERY_DISTINCT_REMOVED,
// [#8057] `update.options.upsert` — declared-but-unenforced (ADR-0049): the
// key sat on the update allowlist while nothing read it, so `{ upsert: true }`
// was accepted and silently dropped. Removed rather than implemented; the
// spec's tombstone carries the create-if-absent prescription (#7867's
// not-found gate is the semantics a caller must reconcile with).
upsert: ENGINE_UPDATE_UPSERT_REMOVED,
};
/**
* The per-method legal key sets, exported for the drift pin ONLY
* (engine-unknown-option.test.ts asserts each set against its schema's shape,
* so a key added to the spec cannot be silently rejected here). Not a public
* API surface — consumers pass options, they do not read this table.
*/
export const ENGINE_OPTION_KEY_SETS: Readonly<Record<string, ReadonlySet<string>>> = {
find: ENGINE_FIND_OPTION_KEYS,
findOne: ENGINE_FIND_OPTION_KEYS,
update: ENGINE_UPDATE_OPTION_KEYS,
delete: ENGINE_DELETE_OPTION_KEYS,
count: ENGINE_COUNT_OPTION_KEYS,
aggregate: ENGINE_AGGREGATE_OPTION_KEYS,
};
/**
* Reject option-bag keys the engine does not execute (#4371 option 2).
*
* Runs AFTER `foldEngineOptionAliases`, so alias spellings are already folded
* away (or thrown on). `null`-valued keys pass — a `null` is a withdrawal
* carrying no intent a drop could lose, same rule as the fold. Retired keys
* (`cursor`/`distinct`) quote their tombstone. Everything else gets the legal
* key set, so the error carries the fix.
*/
export function rejectUnknownEngineOptions(
object: string,
operation: string,
bag: object | undefined,
legal: ReadonlySet<string>,
): void {
if (!bag) return;
let unknown: string[] | undefined;
for (const [key, value] of Object.entries(bag)) {
if (value == null || legal.has(key)) continue;
(unknown ??= []).push(key);
}
if (!unknown) return;
const details = unknown.map((k) =>
ENGINE_RETIRED_OPTION_MESSAGES[k] ? `'${k}': ${ENGINE_RETIRED_OPTION_MESSAGES[k]}` : `'${k}'`,
);
throw new Error(
`${operation}('${object}') does not recognise option${unknown.length > 1 ? 's' : ''} ` +
`${details.join('; ')}. The engine executes none of ${unknown.length > 1 ? 'them' : 'it'}, ` +
`so the call would succeed with the option silently ignored. ` +
`Legal keys for ${operation}: ${[...legal].sort().join(', ')}.`,
);
}
/**
* Fold the deprecated alias spellings of an engine option bag into their
* canonical QueryAST keys, under the #3795/#4181 rule: an alias alone moves to
* the canonical key, redundant identical spellings collapse, DIFFERENT values
* for one slot are irreconcilable and throw (picking a winner IS the silent
* drop), and an explicit `null` alias is a withdrawal.
*
* `rejectSlots` ({@link ENGINE_WIRE_ONLY_SLOTS}) names the slots whose alias
* spellings the engine can neither fold nor honour: a non-null value under one
* throws, quoting the canonical key and shape (#4371). `null` stays a
* withdrawal here too — it carries no intent a drop could lose — and rides
* through for drivers to ignore, exactly as before.
*
* Returns the SAME reference when no alias spelling is present (the common
* path allocates nothing — `withResolvedWhere` discipline); otherwise folds a
* shallow copy, because the bag belongs to the caller and may be reused (view
* metadata, flow node config).
*/
export function foldEngineOptionAliases<T extends object | undefined>(
object: string,
operation: string,
bag: T,
slots: readonly QueryAliasSlot[],
rejectSlots?: readonly QueryAliasSlot[],
): T {
if (!bag) return bag;
if (rejectSlots) {
const refused = rejectSlots.flatMap((slot) =>
slot.aliases
.filter((alias) => (bag as Record<string, unknown>)[alias] != null)
.map((alias) => ({ alias, canonical: slot.canonical })),
);
if (refused.length > 0) {
throw new Error(
`${operation}('${object}') does not accept ` +
`${refused.map((r) => `'${r.alias}'`).join(', ')}: ` +
refused
.map(
(r) =>
`'${r.alias}' is a wire spelling of '${r.canonical}', folded by the RPC/protocol ` +
`layer — a direct engine call bypasses that fold, so the value would be silently ` +
`dropped, not applied. Pass '${r.canonical}' ` +
`(${WIRE_ONLY_CANONICAL_SHAPES[r.canonical] ?? 'the canonical QueryAST shape'}) instead.`,
)
.join(' '),
);
}
}
if (!slots.some((slot) => slot.aliases.some((alias) => alias in bag))) return bag;
const folded: Record<string, unknown> = { ...bag };
foldQueryAliasSlots(folded, slots, (conflict) => {
throw new Error(
`Conflicting options on ${operation}('${object}'): ` +
`${conflict.spellings.map((s) => `'${s}'`).join(', ')} are spellings of the same ` +
`parameter (canonical '${conflict.canonical}') and were given different values. ` +
'Send exactly one.',
);
});
return folded as T;
}
/**
* [#20121] Is this non-array `where` a filter OBJECT — the one non-array shape
* a driver reads as a predicate?
*
* The test is the object's built-in tag (`[object Object]`), not its
* prototype, and each edge shape lands where its measured answer puts it —
* nothing that answered correctly before this gate is refused by it:
*
* - a literal `{…}` and `{}` (match-all, a REAL query — the unscoped-write
* detector reads it that way too) → accepted;
* - `Object.create(null)` and an instance of an author's class with the filter
* on its own keys → accepted: both filtered correctly on `driver-memory` and
* `SqlDriver`, because a driver reads a filter's own enumerable keys;
* - `Map`, `Set`, `Date`, a boxed primitive, a `Promise` (an un-awaited filter
* builder) → refused: each carries its tag, has no own keys, and was
* silently read as "no filter".
*
* `undefined` and `null` never reach this test — the caller skips them, and
* both keep meaning "no filter" (`findOne`'s no-predicate guard and the
* unscoped-write detector both read `null` as absent).
*/
function isWhereFilterObject(where: unknown): where is Record<string, unknown> {
return (
typeof where === 'object'
&& where !== null
&& !Array.isArray(where)
&& Object.prototype.toString.call(where) === '[object Object]'
);
}
/**
* [#20121] How a refused non-filter `where` is named in the refusal: the
* primitive's `typeof` plus its value (bounded), or the object's built-in tag.
* The `typeof` spelling is the wire door's (`received number`); the value is
* added because a direct caller has no request to look at.
*/
function describeNonFilterWhere(where: unknown): string {
if (typeof where === 'object' && where !== null) {
return Object.prototype.toString.call(where).slice('[object '.length, -1);
}
if (typeof where === 'function') return 'function';
const text = typeof where === 'string' ? JSON.stringify(where) : String(where);
const bounded = text.length > 80 ? `${text.slice(0, 77)}...` : text;
return `${typeof where} ${bounded}`;
}
/**
* [#20121] What a dropped `where` would have done, per verb. The read wording is
* the wire door's verbatim; a write has no result set, and "every row in
* scope" is what an unapplied predicate on `multi: true` rewrote or removed.
*/
const UNAPPLIED_WHERE_CONSEQUENCE: Readonly<Record<string, string>> = {
find: 'returned the unfiltered result set',
findOne: 'returned the unfiltered result set',
count: 'returned the unfiltered result set',
aggregate: 'returned the unfiltered result set',
update: 'updated every row in scope',
delete: 'deleted every row in scope',
};
/**
* **Door 2** — lower an arriving {@link FilterArray} on `where` to the
* `FilterCondition` the AST actually declares (#5158, maintainer ruling C).
*
* `FilterArray` — `['stage', '=', 'won']`, `['and', […], […]]`, `[[…], […]]` —
* is authoring sugar, and since #5285 the spec says so in as many words: it is
* declared INPUT-ONLY (`data/filter.zod.ts`), and `QuerySchema.where` is a
* `FilterCondition` that deliberately excludes it. There were two doors into
* the runtime and only one of them read the contract that way:
*
* - **Door 1**, the protocol/HTTP face (`metadata-protocol` `protocol.ts`),
* has always run `isFilterAST` → `parseFilterAST` and answered `400
* INVALID_FILTER` for an array it could not lower. Nothing array-shaped
* survives it.
* - **Door 2**, a direct in-process engine call, passed the array through
* verbatim, and four drivers grew a second filter compiler to meet it —
* an INFIX dialect (`[condA, 'or', condB]`) that the spec never declared,
* that `parseFilterAST` cannot even express, and that cloud's
* `RemoteTransport.buildWhereSQL` refuses outright. Same query, two
* answers, decided by whether the caller went over the wire.
*
* This is that second door, closed: every entry point lowers through the SAME
* `parseFilterAST` sink Door 1 uses, so a driver sees exactly one filter
* dialect regardless of how the query arrived. The authoring ergonomics are
* untouched — `FilterBuilder` tuples, React block `filters` props and the five
* showcase call sites all still work, because lowering is what those shapes
* were always for.
*
* Three arrivals, three answers, matching Door 1 exactly:
*
* 1. `[]` — "no filter". The key is DELETED rather than lowered, which is the
* same reading every layer already gives it (`parseFilterAST([])` is
* `undefined`; `SqlDriver.applyFilters` returns early). Note this is now
* visible to `findOne`'s #4419 guard, which is the point: `findOne({where:
* []})` used to slip past the guard as "an expression tree the driver will
* interpret" and come back with an ARBITRARY row.
* 2. A well-formed AST — lowered. `isFilterAST` gates first so the operator
* vocabulary is checked before `parseFilterAST`'s lenient `$${op}` fallback
* can turn a misspelling into a `$sounds_like` condition nothing executes.
* 3. Anything else array-shaped — REFUSED, loudly, at the call site. Today
* those reach a driver and are refused there (#3948) with driver-internal
* wording, or — for the infix dialect — silently compiled by a second
* implementation. Failing here names the caller's own value.
*
* [#20121] A `where` that is not an array has to be a filter OBJECT, and that
* is checked FIRST, before any door below: a string, a number, a boolean, a
* `Map`, a `Date` — anything that is neither absent, a filter object nor an
* array — is refused with the same `INVALID_FILTER` / 400 envelope the array
* refusal (3) now carries. See {@link isWhereFilterObject} for the accept set
* and why each edge shape lands where it does.
*
* Returns the SAME reference when `where` is not an array (the overwhelmingly
* common path allocates nothing), otherwise a shallow copy: the bag belongs to
* the caller and may be reused (view metadata, flow node config).
*/
export function lowerWhereFilterArray<T extends object | undefined>(
object: string,
operation: string,
bag: T,
schema?: unknown,
schemaOf?: (name: string) => unknown,
): T {
if (!bag) return bag;
const where = (bag as Record<string, unknown>).where;
// [#20121] The SHAPE gate, first on this seam and so first on all six verbs
// that call it (`find`, `findOne`, `count`, `aggregate`, `update`,
// `delete`) — each calls this before it resolves a driver, so a refusal
// here means no driver call is made at all.
//
// Before it, a string / number / `Map` `where` fell into the object branch
// below, every door there stepped around it (they walk the keys of a filter
// object, and it has none), and the driver ignored it: the READ answered the
// unfiltered set, and a `multi: true` UPDATE or DELETE rewrote or removed
// every row of the table (measured on `driver-memory` and `SqlDriver`
// without `SecurityPlugin`, and with it under a system context; with an
// RLS-scoped caller the RLS `$and` composition put the value where the
// driver's node gate refuses it). It also stepped past the unscoped-write
// guard (`dispatchUnscopedMultiWriteHooks`), which reads only an absent or
// `null` `where` as unscoped.
//
// The words are the wire door's (`metadata-protocol`'s normalizer answers
// `?filter=5` with "must be a filter object or condition array, received
// number … It was not applied"); the consequence is spelled per verb,
// because for a write it is not a result set.
if (where !== undefined && where !== null && !Array.isArray(where) && !isWhereFilterObject(where)) {
throw invalidFilterError(
`${operation}('${object}'): 'where' must be a filter object or condition array, ` +
`received ${describeNonFilterWhere(where)}. It was not applied, and an unapplied filter ` +
`would have ${UNAPPLIED_WHERE_CONSEQUENCE[operation] ?? UNAPPLIED_WHERE_CONSEQUENCE.find}.`,
);
}
if (!Array.isArray(where)) {
// [#5869] Door 1 lands HERE, not below: the protocol face runs its own
// `isFilterAST` → `parseFilterAST` and hands the engine an already-lowered
// `FilterCondition` object, so a gate on the array branch alone would miss
// every query that arrived over the wire. The comparand check is the same
// one either way — it reads the lowered condition, which is what both doors
// produce.
assertListComparandShapes(object, operation, where);
// [#8296] The unmaterializable-FIELD door, on the same object form. It sits
// beside the shape gate because the two answer different questions about
// the same predicate — "can this comparand run" vs "is there a column to
// run it against" — and because this seam is the one place EVERY
// caller-supplied `where` passes through, whichever verb it arrived by.
assertFilterIsMaterializable(object, operation, schema, where);
// [#15661] The DECLARED-TYPE door for the text operators, third on this
// seam and third question about the same predicate: the shape gate asks
// "can this comparand run", the materializable gate asks "is there a column
// to run it against", and this asks "can that column's declared type ever
// hold a string". It runs BEFORE the temporal gate below deliberately — a
// `$startsWith` over a `date` field is refused by that gate today, with the
// same `INVALID_FILTER` / 400 envelope but a message about the COMPARAND,
// which sends the author to fix a value that could never have made the
// filter runnable. Same wire envelope, the ruling's message.
assertTextOperatorTargetsAreStringCapable(object, operation, schema, where);
// [#8690] The TEMPORAL-comparand door, fourth on the same seam (#15661's
// declared-type door was inserted above it) and fourth question about the
// same predicate: the shape gate asks "can this comparand run", the
// materializable gate asks "is there a column to run it against", the
// declared-type gate asks "can that column ever hold a string", and this
// asks "can that column's storage rule READ this value".
// It must run BEFORE `resolveWhereTokens` (which is downstream of every
// caller of this function) because the refusal has to precede the driver —
// hence the door steps around `{placeholder}` strings rather than judging
// them; the token resolver refuses the unknown ones a moment later, loudly.
assertTemporalComparandsInterpretable(object, operation, schema, where);
// [#20351] The NUMBER-comparand declared-type door, fifth on the same seam
// and fifth question about the same predicate: is this string a number the
// declared numeric column can be compared with. It refuses a non-numeric
// string (`INVALID_FILTER` / 400) and narrows a numeric one to its number,
// copy-on-write, by `@objectstack/spec/data`'s grammar and verdict. Before
// the token resolver, like the temporal door: a `{placeholder}` resolves to
// an id or a date, never a number, so it is refused here unresolved.
// [#20546] Its walk carries a second arm, asked first at every field: a
// plain object with no `$` key where a scalar column's value belongs
// (`{ amount: { a: 1 } }`) is refused `INVALID_FILTER` / 400. Memory
// answered it with no rows (every row under `$not`), SQL with its own 400.
// [#20745] …and beneath a relation column (the nested-relation form no
// driver serves), a structured-JSON column (a whole-value match the
// drivers share no meaning for) and an undeclared `id`, in words per kind.
// [#20802] …except the nested-relation form, which this position SERVES:
// beneath a relation column it is admitted against the related object's
// declarations (`schemaOf`, the registry) and kept as written — the engine
// lowers it once it can read (`ObjectQL.lowerRelationConditions`) — or
// refused in words of its own (a key the related object does not declare,
// a second level, a related object that is not registered).
// [#21333] …and the walk's BOOLEAN arm: against a declared boolean field
// `"true"` / `"false"`, `1` / `0` and `"1"` / `"0"` narrow to their
// boolean and any other string is refused `INVALID_FILTER` / 400 — the one
// place a bare query parameter's `"true"` becomes `true`.
const numeric = narrowNumberComparands(object, operation, schema, where, 'where', { schemaOf });
// [#7872] The comparand-type door, on the OBJECT form. `parseFilterAST`
// runs the same walk on everything it lowers or passes through, but
// NEITHER door routes an object-form filter through it — Door 1 gates on
// `isFilterAST` first and Door 2 is this very branch — so without this
// call the dominant form would bypass the door entirely (the #7956
// divergence matrix arrived through it). Shape gate first (#5869 keeps
// its pinned wording for the list-operator shapes), type door second;
// the walk is copy-on-write, so the common path allocates nothing and a
// narrowed bigint replaces the bag rather than editing the caller's.
const normalized = normalizeFilterComparandTypes(numeric, `${operation}('${object}')`);
if (normalized !== where) {
return { ...(bag as Record<string, unknown>), where: normalized } as T;
}
return bag;
}
const lowered: Record<string, unknown> = { ...bag };
// (1) `[]` is "no filter", not a failed filter.
if (where.length === 0) {
delete lowered.where;
return lowered as T;
}
// (3) Not a shape `parseFilterAST` can express.
// [#20121] Through `invalidFilterError`, so this refusal carries the
// `INVALID_FILTER` / 400 envelope the wire door answers the same array with
// (`malformedFilterArrayError`) — it used to be a bare `Error`, `code` and
// `status` both `undefined`, a 400-class author error that read as a 500.
if (!isFilterAST(where)) {
throw invalidFilterError(
`${operation}('${object}') received a 'where' array that is not a filter: ` +
`${JSON.stringify(where)}. A filter array is a comparison [field, operator, value], ` +
`a logical node ["and"|"or", ...conditions], or a list of those — it is INPUT-ONLY ` +
`sugar (spec 'FilterArray'), lowered to a FilterCondition here before any driver sees ` +
`it. This value cannot be lowered, and an unapplied filter would have returned ` +
`the UNFILTERED result set. Recognised operators: ` +
`${[...VALID_AST_OPERATORS].sort().join(', ')}. Infix joins ([condA, "or", condB]) are ` +
`NOT one of the shapes — write the prefix form ["or", condA, condB].`,
);
}
// (2) The declared path.
// [#9228] The context prefix is passed because `parseFilterAST` now runs the
// #5869 shape gate itself, one step before this branch could: a scalar `$nin`
// is refused DURING lowering. Handing it `${operation}('${object}')` is what
// keeps this branch's pinned `find('deal'): ` prefix on that refusal — and on
// the #7872 type door's, which `parseFilterAST` has always run and which used
// to answer this branch unprefixed.
const condition = parseFilterAST(where, `${operation}('${object}')`);
if (condition === undefined) {
// Unreachable by construction — `isFilterAST` accepted the shape, so
// `parseFilterAST` has a lowering for it. Loud rather than silent because
// the failure mode of the two spec functions disagreeing is a dropped
// predicate, i.e. every row (#3948).
throw new Error(
`${operation}('${object}'): filter array ${JSON.stringify(where)} passed isFilterAST() ` +
`but parseFilterAST() lowered it to nothing. Refusing rather than running the query ` +
`unfiltered.`,
);
}
// [#5869] Door 2's half of the same check USED to be a second
// `assertListComparandShapes(object, operation, condition)` call here.
// [#9228] moved the rule into `parseFilterAST` itself, which this branch
// calls three lines up with the same context — so the call became provably
// unreachable (nothing between the two can introduce a list operator) and is
// deleted rather than kept as a gate that reads live and never fires. The
// OBJECT branch above keeps its call: that `where` never passes
// `parseFilterAST` at all, which is the whole reason both branches exist.
// [ADR-0139 D1] The object branch's `ReadableIds` rule, on the LOWERED
// condition: `parseFilterAST` admits no leaf as a `$in` comparand (it does
// not opt in, so that spelling is its 400), but a leaf it lowers by
// reference into any other position is refused here by name, as the object
// branch refuses it — first, before the doors below read it as a value.
collectComposableReadableIds(object, operation, condition, 'where');
// [#8296] Same door as the object branch above, on the LOWERED condition —
// the array sugar (`[['is_open','=',true]]`) names fields too, and a gate on
// one branch would answer one mistake two ways depending on the spelling.