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
//! The lowering every comparison kind implements: [`ComplexComparison`], and where one is applied —
//! [`At`], the [`Path`] of segments naming its column, the [`Frame`] a layer pushes to extend that
//! path, and the [`RecordAddress`] of the row it constrains.
//!
//! Beside it, the three refinements a comparison may carry: [`CompositeComparison`], which a scalar
//! does not implement and which is what refuses `flatten` where it has no meaning;
//! [`CollapsibleComparison`], which an ENTITY's comparison carries and which is what lets a relation
//! predicate over its id become a predicate on the foreign key instead; and
//! [`ReferentialComparison`], which a LEAF kind carries and which is the half of the collapse's law
//! that an entity's generic implementor cannot read for itself.
use Backend;
use crateFieldName;
/// Which ROW a predicate constrains: the table it is stored in, and the key columns that identify
/// one of its rows.
///
/// # What it is for, given that most comparisons never read it
///
/// A leaf's predicate is about its column and nothing else, so eight of this crate's nine SQL kinds
/// take this and ignore it. The one that reads it is
/// [`SqlEdgeComparison`](crate::comparison::sql::SqlEdgeComparison), whose predicate is a
/// CORRELATED subquery: it selects from a second table and joins back to this row, and neither the
/// table it joins to nor the columns it joins on is derivable from a field's name.
///
/// The channel is uniform because it could not be anything else. A collection column is not
/// distinguishable from a scalar one where the addressing would have to be attached — `Vec<String>`
/// behind a type alias is a scalar to anything reading tokens — so a per-kind channel is unwritable
/// and this one arrives for every column.
///
/// # `&'static FieldName`, for the reason a part name is `&'static str`
///
/// These are identifiers, so they reach the SQL TEXT rather than the bind list — the asymmetry
/// [`quote_ident`](crate::comparison::sql::quote_ident) exists to make safe. `'static` is what keeps
/// a caller's runtime string from arriving here, and [`FieldName::new`] is `const`, so the names a
/// schema declares can be built in a constant, which is where they actually are.
///
/// The key list is BORROWED for the same reason and one more: with the whole type `const`, an
/// address is an item rather than an allocation, so the code that emits a schema states its rows'
/// addresses beside the schema and nothing builds one per query.
///
/// # One key list, named once
///
/// A correlated predicate needs this row's key columns and the second table's leading columns, and
/// they are the SAME names — a row hanging off this one carries its key as its leading columns,
/// which is the whole of what makes it a dependent row. Two lists would be two arguments of one
/// type that could be given in the wrong order, both rendering valid SQL of the same shape, which is
/// the defect a [`Path`] closes one level down — a layer PUSHES its own segment rather than being
/// handed a name per column. There is one list, so there is nothing to swap.
///
/// # The table is the REAL one, and an alias lives one type over
///
/// A qualified reference needs the name the enclosing `FROM` gave the row source, and a nested
/// relation gives it an ALIAS — so for a while it looked as though an aliased `FROM` would have to
/// pass that alias here. It must not, and the reason is that this field has a second reader: a
/// dependent table's name is DERIVED from it, by
/// [`edge_table`](crate::comparison::sql::edge_table), and extending an alias would name a table
/// that does not exist.
///
/// So the two roles are SPLIT rather than swapped. This stays the real table and is what every
/// derivation reads; the alias rides on [`At`], which is the scope rather than the row, and
/// [`At::qualifier`] is what every qualified reference reads. That split is also what let the alias
/// arrive at all — it is `&'static str` minted at expansion, so it borrows nothing and both types
/// stay `Copy`.
/// The SEGMENTS naming one column, innermost first — each borrowed from the [`Frame`] the layer
/// above it is holding.
///
/// # A cons list, because a path is built while WALKING
///
/// A layer learns its own segment and nothing below it, so the path grows one segment at a time as
/// the walk descends. A slice cannot be extended without allocating, and the whole cost this shape
/// removes is a name allocated per column per query; a borrowed link costs two pointers on the
/// stack of the layer that pushed it, and it lives exactly as long as the call it was pushed for.
///
/// There is no PUBLIC constructor. The only way a caller obtains one is [`At::frame`], so a path is
/// a record of a walk rather than an argument anyone assembles — which is what keeps a layer from
/// naming a column that is not below it.
///
/// [`under`](Self::under) is the crate's own second way in, and it opens onto the same walk from
/// the other family: a row's [`ColumnShape`](crate::ColumnShape) list is a tree of fields, and the
/// renderer that walks it needs the segments above each column in exactly the form this type holds
/// them. Sharing the type is what makes the two families join a name identically — a filter over
/// `tb.num` and a `SELECT` of the same column both reach `push_segments`, so neither can spell it
/// differently. A second cons list beside this one would have been the place they could.
///
/// # It states no joining convention
///
/// What character runs the segments together, and whether the result is bracketed, is
/// [`Backend::write_column`]'s: the SQL family runs them together with `_` and brackets the whole
/// as one identifier, where a document family nests them along a real path. This type holds the
/// segments and joins nothing, so a family joining differently needs nothing from here.
/// One segment pushed, held on the stack of the layer that pushed it.
///
/// It exists because [`At`] borrows its path rather than owning it: a layer descending into a child
/// binds this to a local, and [`at`](Self::at) is the child address borrowed from it. The borrow is
/// what ties the child's path to the parent's frame, so a path cannot outlive the walk that built
/// it and nothing has to be freed.
///
/// Explicit rather than a scoped closure (`at.under(name, |at| …)`), because generated code is the
/// primary author of these two lines and straight-line output reads and debugs better than nested
/// closures.
/// Where a predicate is being applied: the path naming the column, and the row it constrains.
///
/// # Why the row travels with the column
///
/// [`ComplexComparison::apply`] already takes schema knowledge from its caller, and says why: the
/// name is rendered into the SQL text verbatim, and the caller owns it because the caller is the
/// only party that knows the schema. A row's table and key columns are the same kind of knowledge,
/// so they arrive at the same place — and arriving HERE rather than at the crossing is what keeps
/// [`TryFromFilter`](crate::TryFromFilter) taking a filter and nothing else.
///
/// That is not a tidiness argument. The addressing genuinely is not part of a filter:
/// `tags: { overlaps: […] }` is the same question whichever row it constrains, and only the address
/// differs. A crossing that took the address would be claiming otherwise — and a comparison built
/// from a filter alone can be applied against any row shape the caller names, which is the property
/// that makes a generated comparison reachable from a GraphQL filter at all.
///
/// # The top level is the EMPTY path, and that is the whole reason this is a path
///
/// A generated comparison is the composite case: it is handed one address and each of its columns
/// extends it. Under a single NAME there was no name to hand it that produced the right answer — a
/// top-level `Media` predicate rendered `media_title` where the column is `title`, and applying one
/// to its own row rendered `frames_id` beside a [`RecordAddress`] saying the column identifying
/// that row is `id`. The address and the predicate disagreed about one column inside one call, and
/// no naming convention reconciles them.
///
/// With a path there is nothing to reconcile: [`new`](Self::new) names a row and no column, each
/// layer pushes its own segment, and `title` falls out of the top level rather than being a case.
///
/// # A comparison over a COLUMN applied at the top level addresses none
///
/// The empty path names no column, so what a backend renders for one is the backend's — the SQL
/// family writes nothing, which makes the predicate around it a parse error rather than a name that
/// might resolve.
///
/// Writing nothing settles only the forms that WRITE the column. A CORRELATED comparison has one
/// that does not: its second table is the row's own extended by the column's path, and extended by
/// nothing it IS the row's, so the predicate correlates the row to itself and is well-formed and
/// constant. Those kinds refuse the empty path outright — see
/// [`SqlLoweringError::EdgeWithoutField`](crate::comparison::sql::SqlLoweringError::EdgeWithoutField).
///
/// Either way a column's comparison belongs at a frame, and [`frame`](Self::frame) is the only way
/// to make one.
///
/// # An address is a VALUE, and every receiver here says so
///
/// Two borrowed pointers and `Copy`, so an `&At<'_>` is a pointer to two pointers: the width of
/// what it points at, one indirection more, and the opposite of how the builder travels through the
/// very same signature. [`ComplexComparison::apply`] takes this BY VALUE for that reason, and the
/// three accessors take `self` rather than `&self` for the same one.
///
/// The receiver is measured rather than matched to a habit. The emitter writes its calls
/// qualified — `At::frame(at, …)` on the address its `apply` was handed — which against a `&self`
/// receiver is one `E0308` per emitted column, ten of them across `ingraph-derive`'s fixtures,
/// reported at the `#[derive]` rather than anywhere inside the expansion a reader could look at. So
/// `&self` would cost generated code a `&` at each such site and buy nothing back; nothing anywhere
/// holds an `At` it cannot copy.
/// One comparison's lowering into a predicate, threading the backend's builder.
///
/// # The builder is a value that passes through
///
/// `apply` takes the builder and gives it back rather than writing into a `&mut`, and that is what
/// makes a comparison naming two or more columns expressible: a layer addresses its own children by
/// deriving names from the one it was given and hands each of them the same builder in turn, so
/// nesting is unbounded and no signature has to state an arity.
///
/// Passing it by value carries exclusivity more strongly than a `&mut` would. Two accumulators over
/// one builder would interleave placeholders and arguments; you cannot hold two of these, because
/// you moved the one you had.
///
/// # The address names THIS layer, and a layer that occupies several columns pushes a frame
///
/// A leaf renders at the path it was handed and pushes nothing of its own. A composite pushes one
/// segment per part — `timebase` becoming `timebase_num` and `timebase_den` — so the path arrives
/// from above and each layer extends it by exactly its own name. Nothing here invents a convention
/// or guesses: the caller knows the real column names because it is the code that emitted the
/// schema.
///
/// A kind never renders the column itself. It hands the address to [`Backend::write_column`], which
/// joins the segments and brackets the result as that backend spells one — the one input on this
/// path that is not bound, since an identifier is not a value and no placeholder stands for one.
/// The quoting is the backend's rather than the caller's for the same reason it always was:
/// bracketing is a pure function of the name and the backend, and the backend is `B`, a type every
/// implementor already names. A step at the call site is one a caller can forget, silently.
///
/// The segments are [`FieldName`]s rather than `&str`s because they become TEXT: an operand is text
/// too, and with both spelled the same the compiler could not tell a name from a value here. See
/// the type for what that closes.
///
/// One convention at every depth is the other half. Whether a kind occupies one column or several
/// changes only how many segments it pushes, so a leaf never has to ask what it was handed.
///
/// # The ROW arrives with the column, and most kinds never read it
///
/// A leaf's predicate is about its column alone, so it takes [`At::record`] and ignores it. A
/// CORRELATED predicate cannot: it selects from a second table and joins back to this row, and
/// neither that table nor the columns it joins on is in a field's name. Carrying the row here — for
/// every column, whether or not the kind occupying it reads one — is what keeps the crossing pure
/// and the emitter free of a special case it could not detect anyway. See [`RecordAddress`].
///
/// # `apply` opens conjuncts, never a clause
///
/// It appends to the accumulator it was handed and returns it. Which CLAUSE those conjuncts belong
/// to, and whether one is opened at all, is the accumulator's: it pushes its lead on the first
/// conjunct anything writes, so a comparison that sets no operator leaves a statement with no
/// clause rather than an empty one. Several comparisons can therefore be threaded through one
/// accumulator without any of them asking [`is_empty`](Self::is_empty) about the others, and
/// without the caller asking either.
///
/// That is also what makes a nested sub-comparison legal by construction — it is handed exactly
/// what its parent held — and why recursion needs no state of its own.
///
/// # The comparison outlives the builder
///
/// `&'q self` ties them, and the tie is what keeps the seam open rather than a constraint the SQL
/// family needs. sqlx 0.9's builder OWNS its arguments, so a SQL operand bound out of `&self` need
/// not outlive the accumulator's borrow — but a backend whose builder assembles REFERENCES to the
/// operands has no way to state that it may, and a signature with the two lifetimes unrelated makes
/// such a backend unimplementable. It costs nothing real: a query is rendered FROM a filter the
/// caller is holding, so the comparison outlives the builder in every call there is.
///
/// # `Result`, and why it is not the same layer as the typestate
///
/// An illegal clause transition is a COMPILE error — a missing `ClauseTransition` impl — while this
/// `Result` carries a RUNTIME refusal: an operand that will not convert, an operator this dialect
/// lacks, a ceiling this wire protocol imposes. Two layers, and neither substitutes for the other.
///
/// Pushing every refusal down to the crossing is what makes a SQL lowering infallible, and that
/// argument holds only for a lowering that cannot nest. **A middle layer can refuse**, so the
/// `Result` belongs to the trait. For a backend where nothing refuses, [`Backend::Error`] is
/// uninhabited and the type says so.
/// **An ABSENT predicate** — what a position a client said nothing about lowers to.
///
/// # It is the state a kind with no empty VALUE has instead of one
///
/// Every flat kind has an empty form: `ScalarFilter::default()`'s crossing renders no conjunct, so
/// an unwritten column needs no wrapper. A RELATION position has none — `SqlRefComparison` holds the
/// far side's comparison bare, and an emitted comparison has no `Default` (the reason is written at
/// its emission: the bound would demand of a generic dialect what only a concrete one can give). So
/// *nothing was asked* is carried by the [`Option`] rather than by a value.
///
/// Absence renders NOTHING and counts ZERO, which is what makes it conjoinable with anything: a
/// record's lowering threads its accumulator through every member, and one that says nothing hands
/// the builder straight back.
/// A comparison occupying MORE THAN ONE column beneath the address it is applied at.
///
/// A scalar comparison does not implement it — and that is the whole refusal.
///
/// # What it refuses, and why the refusal is not a taste
///
/// A field declared `flatten` contributes NO segment, so its type's columns land at the parent's
/// level: `timebase: Timebase` renders `timebase_num`/`timebase_den`, and the same field marked
/// `flatten` renders `num`/`den`. A scalar has no such columns to lift — the field's name IS its only
/// segment, and a scalar comparison pushes nothing of its own — so `flatten` on one does not rename
/// its column, it DELETES the column's name, and two flattened scalars land on the same path.
///
/// A no-op was the live alternative and is coherent: read semantically, `flatten` says *this field's
/// TYPE's columns are laid out at my level*, and a type with no columns of its own has nothing to lay
/// out. It loses on the case a reader is most likely to get wrong — a COLLECTION, where *store this
/// in my table rather than in an edge table* is a reading the word supports and a behaviour that
/// really differs per dialect. A no-op makes that misreading silent, and a no-op that later becomes
/// an error is a breaking change.
///
/// # A trait rather than a `const` on [`ComplexComparison`]
///
/// The first shape tried was `const SEGMENTS: &[&str]` on `ComplexComparison` itself, checked in a
/// `const {}` block, and each of its costs is what the split removes:
///
/// - **The error.** A `const` block fails as *evaluation of constant value failed*; an unimplemented
/// trait is `E0277`, which carries the wording above.
/// - **Forgettability.** A `&[]` default makes the declaration optional, so a downstream composite
/// that omits it is silently treated as a scalar. Nothing here can be forgotten: a scalar simply
/// does not implement this.
/// - **Breakage.** Widening `ComplexComparison` changes a surface downstreams implement. This is
/// purely ADDITIVE — only a composite writes the extra impl.
///
/// # [`SEGMENTS`](Self::SEGMENTS) is what a ROW's columns are read out of
///
/// It arrived with `flatten`, which needs only the impl's EXISTENCE, and for a while nothing read
/// the value. Storage is the reader: a composite occupying two columns has to be selected, created,
/// bound and decoded as two, and the names of those two are exactly the segments this comparison
/// pushes. So the column shape a field's type answers with — [`ColumnKind`](crate::ColumnKind) —
/// delegates here, and one list drives both the predicate over `tb.num` and the `SELECT` of
/// `tb_num`. Two lists that agreed today would be two lists that could drift, and the drift is the
/// silent kind: a filter naming a column no statement selected.
///
/// The question that note left open — whether a nested composite's segments are its children's
/// concatenated or one level deep — is answered by that consumer, as it asked. **One level deep**:
/// the entries are [`ColumnShape`](crate::ColumnShape)s, so a composite part carries its own parts
/// and the renderer descends. Concatenation would have needed a joining rule in a `const`, where
/// this crate deliberately has none.
/// A comparison over a ROW that can hand back its constraint on that row's own ID — and hands it
/// back only when the id is the ONLY thing it constrains.
///
/// # What it is for
///
/// A relation predicate over a to-one reference is a semi-join:
/// `fk IN ( SELECT id FROM target WHERE <nested> )`. When the nested predicate constrains nothing
/// but the target's id, that whole subquery answers the same rows as the direct predicate on `fk` —
/// so the relation renders `fk = ?` and no subquery at all. This is the projection that decides it.
///
/// # It is a PROJECTION, not a writer
///
/// The obvious shape is a method that writes the collapsed predicate at an address and reports
/// whether it did — which is what `legacy/ingraph`'s `SqlWhere::collapse_onto` was, under a builder
/// it borrowed. It does not survive the move to [`ComplexComparison`], whose builder is a value that
/// passes THROUGH: a writer would have to hand back both the builder and a `bool`, so *declined*
/// and *rendered nothing* would be two answers of one shape and each caller would re-derive the
/// difference.
///
/// Handing back the id's own comparison removes the question. It is a [`ComplexComparison<B>`] over
/// ONE column, so the relation applies it at the FOREIGN KEY's address and the collapsed predicate
/// is an ordinary rendering — no second spelling of `=`, no second spelling of `IN`, and a
/// multi-operator id (`{ gt: 3, lt: 9 }`) collapses to its own conjuncts rather than to one.
///
/// # The law: sound only under REFERENTIAL INTEGRITY
///
/// `fk IN (SELECT id FROM target WHERE id = v)` is `fk = v` exactly when every `fk` names a row that
/// EXISTS. A dangling reference separates them — the subquery finds no row and answers false, where
/// the direct predicate compares the stored value and answers true — and no rendering here can see
/// whether the constraint holds.
///
/// So an implementor answers [`only_id`](Self::only_id) with `Some` only when BOTH hold:
///
/// - every other field of this comparison is empty, and
/// - the id's own operators survive the substitution in this schema.
///
/// The second half is the implementor's because this trait cannot see an operator: the id's
/// comparison is a type parameter behind a [`ComplexComparison`] bound, which reports a conjunct
/// count and a rendering and names no operator — the same reason
/// [`SqlLoweringError::JsonElementScope`](crate::comparison::sql::SqlLoweringError::JsonElementScope)
/// is a refusal rather than a per-operator branch. `legacy/ingraph` drew the line at plain equality
/// and membership (`is_referential`), leaving the negated, ordering and case-insensitive shapes to
/// the subquery; a stricter implementor answering `None` always is correct and merely slower.
///
/// # An EMPTY comparison may answer `Some`
///
/// It is the same answer either way — an empty id comparison renders nothing, and a relation whose
/// nested predicate is empty renders nothing — so an implementor need not special-case it.
/// **A comparison held BEHIND A POINTER** — what a relation position holds when the two records
/// refer to each other.
///
/// # It is the SIZE cycle, and nothing else
///
/// A `ref` one way and a `derived` the other way is the ordinary shape of a relation, and it makes
/// two comparisons each of which contains the other: `ClipSqliteComparison` holds the semi-join
/// through its `reel_id`, whose nested predicate is a `Reel`'s — which holds the quantifier over its
/// clips, whose nested predicate is a `Clip`'s. Each type is then infinitely large, and the report is
/// `E0275` about `Sized`.
///
/// That is the same recursion the WIRE face already owns: a record whose position names its own kind
/// contains itself, and the holder puts a `Box` in. This row is the storage side of it, so the
/// indirection costs a pointer per POSITION rather than anything per row of data.
///
/// `?Sized`, because a boxed comparison is a value nothing else here constrains — and delegating
/// rather than deref-ing at each call site is what keeps the recursion an implementation detail of
/// the position that owns it.
/// The COLLAPSE travels through the pointer too, so a boxed nested predicate keeps the optimisation
/// the unboxed one had: a forward position whose target constrains its id alone still renders on the
/// foreign key rather than opening a subquery.
/// A comparison that can say whether its constraint is REFERENTIAL — a plain equality or a plain
/// membership, and nothing else.
///
/// # It is the second half of [`CollapsibleComparison`]'s law, made askable
///
/// That trait's law has two halves, and only the first is a question a generic implementor could
/// answer for itself: *every other field of this comparison is empty* reads its own members, where
/// *the id's own operators survive the substitution* is a question about a type it reaches through a
/// projection — an emitted `only_id` is generic in its database, so the id's comparison is opaque
/// and the only thing it can do with one is call a trait method. This is that method.
///
/// # The wire already answers it, and the crossing used to throw the answer away
///
/// [`ScalarFilter::is_referential`](crate::ScalarFilter::is_referential) and its twins on
/// [`EnumFilter`](crate::EnumFilter), [`TextFilter`](crate::TextFilter) and
/// [`BytesFilter`](crate::BytesFilter) answer exactly this question on the client-facing side, and
/// the storage comparison a filter crosses into holds THE SAME OPERATOR SLOTS — measured kind by
/// kind: `SqlScalarComparison`'s `one { eq, ne, gt, gte, lt, lte } many { in_, not_in }` is
/// `ScalarFilter`'s own set, and the enum, text and bytes kinds mirror theirs the same way. So the
/// answer is not carried across the crossing as data; it is asked again at the other end, of a value
/// that holds the same facts. Nothing can drift between the two, because there is no second copy to
/// drift.
///
/// # The ABSENCE of an impl is the refusal, and that is the whole design
///
/// The rejected alternative was a defaulted `fn is_referential(&self) -> bool { false }` on
/// [`ComplexComparison`]: conservative, always sound, and needing no bound anywhere. It was rejected
/// because *declines silently* is the failure mode this seam cannot afford — a comparison that grew
/// a new operator and forgot to revisit the default would keep answering `false`, and the only
/// symptom is a subquery where a column comparison would have done. A missing impl is `E0277` AT THE
/// POSITION that needed it, with the sentence below.
///
/// So the kinds that can answer implement it and the kinds that cannot simply do not, which is the
/// same shape [`Nullable`](crate::Nullable) already takes on the wire: it has no `is_referential` of
/// its own, deliberately, because a null test names no child row and asking the inner filter would
/// smuggle one into a collapse. There is no impl here for a nullable, a collection, a composite or a
/// relation, and each absence means what the wire's means.
///
/// # `B` is a parameter because referentiality is the BACKEND's question
///
/// The collapse rewrites `fk IN (SELECT id FROM target WHERE id = v)` as `fk = v`, so it moves a
/// predicate from the target's id column onto the source's foreign key. That is sound when the two
/// columns compare values the same way, which is a fact about the storage rather than about the
/// operator — a dialect whose text equality is collation-dependent may decline for its text kind
/// while answering for its scalar one, and it can only say so if the backend is part of what is
/// being claimed.