ingraph 0.1.0

A declaration-driven indexing framework: records and nodes are written as Rust types, and the storage rows, the dataflow between them and the GraphQL query surface are emitted from the declaration.
Documentation
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
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
//! The built-in filter types — encapsulated: `Option` operator slots, constructed via `new()`
//! (`const`, all-`None`) / `Default` (delegates) and reached through the `opt_accessor!`-generated
//! set — a bare-named projecting GETTER plus the `with_*`/`set_*`/`maybe_*`/`update_*` writers.
//! `None` = operator absent, distinct from a set-but-empty value. There are no public FIELDS: the
//! slots are `pub(crate)` because a filter's LOWERINGS live with the backends they emit for rather
//! than here — which is what keeps a database driver out of this module.
//!
//! Three ways out of a filter, and each answers a question the others cannot. A getter INSPECTS,
//! `try_map` TRANSFORMS without exposing, and the crossing into a comparison CONSUMES. A caller that
//! wants to branch on what is set uses the first; one converting operands into their stored form
//! uses the second; the store layer uses the third.
//!
//! A byte column's WIDTH DISCIPLINE used to be such a parameter — `BytesFilter<B, Variable|Fixed<N>>`,
//! ten slots either way, two of them refused at the crossing for one of the two markers. It is two
//! KINDS now: [`BytesFilter`] keeps the substring pair a blob's dialects answer and
//! [`FixedBytesFilter<B, N>`](FixedBytesFilter) simply has no slot for one. A collection's shape went
//! the same way, for the same reason — [`ListFilter`] and [`SetFilter`] — because what a marker
//! decided was an operator SET and not a rendering.
//!
//! [`QuantifiedFilter`] is a THIRD collection kind and splits on a different axis again: not what the
//! column's order means, but whether the ELEMENT has a literal form worth publishing. The two wide
//! kinds hold the element in seven of their slots and so put it on the wire; this one holds it in
//! none, keeps `any` and `count` alone, and asks its element type for nothing at all. A collection of
//! float-bearing pairs is the case — see the kind's own note, where each departing operator is named
//! with the reason it could not be answered honestly.
//!
//! Nullability is the third such fact, and it is carried by a WRAPPER rather than a parameter:
//! [`Nullable<F>`] is `F`'s operators plus the null test, and the null test exists nowhere else. NO
//! kind has one, so `IS NULL` against a `NOT NULL` column is not a query that matches no rows — it is
//! a type that does not exist.
//!
//! The contract they all answer to — [`GraphqlFilter`], the one question every filter answers the
//! same way — is declared here beside them.
//!
//! Which of these kinds a column gets is not this module's to say. A Rust type carries an
//! INTERPRETATION and the interpretation carries the kind — see [`crate::marker`] — which
//! is what makes `ListFilter` and `SetFilter` both reachable for one `Vec<T>`.
//!
//! Behind `async-graphql`, this file carries the two REGISTRATION MACROS a hand-written face is
//! written with, and exactly one spending of them: [`BooleanFilter`]'s. Every other kind's face is
//! written over a PARAMETER in the kind's own file — the enum's over its operand, the two
//! collections' over their element, and the text, scalar and byte kinds' over a READING, which is
//! the [`carrier`](super::carrier) axis a DECLARING crate joins through.
//!
//! What that leaves here is the one kind with nothing to be generic over: a boolean has two values,
//! so it has no operand form to choose and no reading to be a row of. The macros stay public all the
//! same, because a filter kind declared DOWNSTREAM is in exactly that position for its own reasons.

use crate::{
  graphql::lower::ToGraphqlFilter,
  marker::{BytesFilterMarker, BytesMarker, DefaultMarker, DefaultVecMarker, ListMarker},
  primitives::{Confidence, Count, Timestamp},
};

/// Generate one optional field's accessor set inside a filter's inherent impl: the bare-named
/// GETTER, then the quartet that writes it — `with_*`/`set_*` set `Some(value)` (consuming /
/// in-place), `maybe_*`/`update_*` assign the raw `Option` (consuming / in-place). The four writers
/// are NOT `const` — assigning a field drops its old value, and dropping a generic `T` in a
/// `const fn` is disallowed (only `new()`'s fresh all-`None` construction is `const`). The consuming
/// forms are `#[must_use]`.
///
/// # The getter PROJECTS
///
/// It hands out `Option<&T>`, or `Option<&[T]>` for a list slot — the operand, never the
/// `Option<Box<[T]>>` it is stored in. `Box<[T]>` is an allocation decision (see the list arm below)
/// and no part of the vocabulary a caller reasons in; handing out `&Option<Box<[T]>>` would publish
/// it and make every future change to it a breaking one.
///
/// Getters exist because [`try_map`](ScalarFilter::try_map) transforms and does not INSPECT. A
/// downstream that wants to branch on what is set — "only `eq`, take the fast path" — is asking the
/// question [`is_referential`](ScalarFilter::is_referential) answers, and that method had to be
/// written inside this crate precisely because nothing outside could ask it. With the getters a
/// caller answers its own such questions instead of waiting for the framework to anticipate them.
///
/// # `eq` and `ne` shadow [`PartialEq`]'s methods, and that is the cost of the bare names
///
/// Two slots are named `eq` and `ne`, and every filter derives [`PartialEq`]. An inherent method
/// wins method resolution, so `a.eq(&b)` no longer reaches the trait — the inherent `eq` takes no
/// argument, so such a call is a compile error rather than a wrong answer.
///
/// The `==` and `!=` OPERATORS are unaffected, and so is `assert_eq!`: both go to the trait
/// directly rather than through method resolution. Pinned in `graphql::tests`, because the claim is
/// about name resolution rather than about either impl and would otherwise be an assumption.
///
/// # The names carry no suffix
///
/// `eq()` rather than `eq_ref()`. A projected getter is the ordinary shape here, and a suffix would
/// mark every one of them for the sake of the two that collide.
///
/// The four WRITER names are SPELLED at each call site rather than pasted together from the field
/// name. `::paste::paste!` would save the repetition and cost a proc-macro dependency to do it;
/// spelling them keeps every public method findable by the name a reader actually types when they
/// go looking for `with_starts_with_nocase`. The getter needs no such spelling — its name IS the
/// field's, so `$field` reaches it directly and there is nothing for a reader to search for that
/// they are not already looking at.
///
/// `opt_accessor!(field: [T] => …)` is the LIST arm, and the slot it belongs to stores `Box<[T]>` —
/// two words where `Vec<T>` is three. The third word is a capacity no filter reads: a list operator
/// allocates when it is set, and in the common case every one of them is `None`, so the saving costs
/// nothing. It compounds by the COLUMN rather than by the query, since a where struct holds one
/// filter per column and each filter one slot per operator — `Nullable<ScalarFilter<i64>>` 152 → 136
/// bytes, a twenty-column where struct of them 3040 → 2720.
///
/// The list arm's four methods take `impl Into<Box<[T]>>`, never the storage type. Taking `Vec<T>`
/// and converting inside would hide a reallocation from the only party able to avoid it:
/// `Vec::into_boxed_slice` reallocates exactly when capacity exceeds length, so the conversion is
/// free for a `vec![…]` literal or an exact-size `collect` and a copy of the whole list for a `Vec`
/// grown by `push`. `Into` leaves that cost in the caller's own expression, where it is visible.
///
/// The list arm is FIRST because `$ty:ty` matches `[T]` too, and a macro tries its arms in order.
macro_rules! opt_accessor {
  ($field:ident: [$elem:ty] => $with:ident, $set:ident, $maybe:ident, $update:ident) => {
    #[doc = concat!("The `", stringify!($field), "` operands, or `None` while the operator is absent.")]
    #[doc = ""]
    #[doc = "A PRESENT but empty list is not the same as an absent operator: the first asks for no"]
    #[doc = "rows, the second for every row, so `Some(&[])` and `None` say different things."]
    #[inline]
    pub fn $field(&self) -> Option<&[$elem]> {
      self.$field.as_deref()
    }

    #[doc = concat!("Set `", stringify!($field), "` to `Some(value)` (consuming).")]
    #[must_use]
    #[inline]
    pub fn $with(mut self, value: impl Into<Box<[$elem]>>) -> Self {
      self.$field = Some(value.into());
      self
    }

    #[doc = concat!("Set `", stringify!($field), "` to `Some(value)` (in place).")]
    #[inline]
    pub fn $set(&mut self, value: impl Into<Box<[$elem]>>) -> &mut Self {
      self.$field = Some(value.into());
      self
    }

    #[doc = concat!("Assign the `", stringify!($field), "` list option (consuming).")]
    #[must_use]
    #[inline]
    pub fn $maybe(mut self, value: Option<impl Into<Box<[$elem]>>>) -> Self {
      self.$field = value.map(Into::into);
      self
    }

    #[doc = concat!("Assign the `", stringify!($field), "` list option (in place).")]
    #[inline]
    pub fn $update(&mut self, value: Option<impl Into<Box<[$elem]>>>) -> &mut Self {
      self.$field = value.map(Into::into);
      self
    }
  };
  ($field:ident: $ty:ty => $with:ident, $set:ident, $maybe:ident, $update:ident) => {
    #[doc = concat!("The `", stringify!($field), "` operand, or `None` while the operator is absent.")]
    #[inline]
    pub const fn $field(&self) -> Option<&$ty> {
      self.$field.as_ref()
    }

    #[doc = concat!("Set `", stringify!($field), "` to `Some(value)` (consuming).")]
    #[must_use]
    #[inline]
    pub fn $with(mut self, value: $ty) -> Self {
      self.$field = Some(value);
      self
    }

    #[doc = concat!("Set `", stringify!($field), "` to `Some(value)` (in place).")]
    #[inline]
    pub fn $set(&mut self, value: $ty) -> &mut Self {
      self.$field = Some(value);
      self
    }

    #[doc = concat!("Assign the raw `", stringify!($field), "` option (consuming).")]
    #[must_use]
    #[inline]
    pub fn $maybe(mut self, value: Option<$ty>) -> Self {
      self.$field = value;
      self
    }

    #[doc = concat!("Assign the raw `", stringify!($field), "` option (in place).")]
    #[inline]
    pub fn $update(&mut self, value: Option<$ty>) -> &mut Self {
      self.$field = value;
      self
    }
  };
}

// TEXTUAL SCOPE reaches the filter kinds declared below this line and nothing else, and one filter
// outside this module needs the same four writers: `primitives::lang`'s `LanguageIdFilter`, a
// COMPOSED filter written by hand in the house whose types it is over rather than a kind of its own.
// The re-export is what lets an operator slot anywhere in this crate spell that family once.
//
// It WAS gated on the one consumer's own word — `derive`, which `primitives::lang` rides — because a
// `pub(crate) use` nobody names is `unused_imports`, and that note said what would end the gate: *a
// second consumer outside that tier widens the gate rather than removing it*.
//
// `primitives::geometry` is that second consumer, and it is outside every tier — the house admits no
// dependency and needs none, so there is no word to widen the gate WITH. Widening it as far as the
// new consumer sits is therefore removing it, and the original reason cannot come back: an UNGATED
// consumer names this row in every build, so the `unused_imports` the gate existed to prevent has no
// configuration left to fire in.
pub(crate) use opt_accessor;

/// Register one type's INTERPRETATIONS: the FAMILY it is read as a value under, the filter that
/// family's trait carries for it, and what a `Vec` of it means. Crate-internal, because only this
/// crate is coherent for the framework's own types.
///
/// # The family is named once, and both impls follow from it
///
/// `$ty as <family>` picks the trait the answer is carried by AND the marker the default resolves
/// to, so a row cannot state a reading in one half and a different one in the other. It could not
/// state them separately even if it tried: [`crate::DefaultMarker`]'s item bound makes
/// `ScalarMarker<T>` well formed only while `T: ScalarFilterMarker`, so halves that disagree are
/// `E0277` at the row that wrote them.
///
/// The word is a literal token per arm rather than one `$family:ident` pasted into
/// `<Family>FilterMarker`, because pasting an identifier needs `::paste::paste!` — a proc-macro
/// dependency, which the accessor macro above already declined to take for the same saving.
///
/// There is no `enum` arm, and its absence is the demand filter rather than an oversight: no type
/// this crate registers is read as an enumeration. [`EnumFilter`] is a kind a DECLARING crate
/// reaches, and such a crate writes the two impls itself — see below, or takes
/// `#[derive(ingraph::Enum)]`, which emits them.
///
/// Its WIRE face is not the declarer's, and that is the one asymmetry worth stating here: the two
/// impls above name the declarer's own type and only it can write them, where
/// `impl InputType for EnumFilter<T>` names this crate's type and is written once, generically, in
/// [`EnumFilter`]'s own file.
///
/// Three impls where there were four, and the two that went are the `Option` ones: `Option<T>` and
/// `Option<Vec<T>>` now come from ONE blanket over every `T` (see [`crate::DefaultMarker`]),
/// because a nullable column has exactly one reading whatever it wraps — its inner interpretation,
/// plus the null test, which is where [`Nullable`] lives.
///
/// That blanket used to be declined, on the argument that enumerating left `Option<T>` free for a
/// future entity-typed impl over it to arrive into. The premise moved with the trait: an entity's
/// interpretation is a MARKER of its own, so such an impl lands on the entity type's
/// `DefaultMarker` row and never on `Option`'s, and the room the enumeration was holding open
/// is room nothing needs. `Vec<T>` is a different case and keeps its per-element row — see the arm
/// below for why it cannot be a blanket at all.
///
/// # What a DOWNSTREAM type writes
///
/// The same rows, minus the ones it has no use for, and it writes them for itself because it always
/// could — every one of them names a type local to that crate. A scalar or enum writes two, and the
/// family it names is the same one this macro's word is short for:
///
/// ```
/// # struct MediaKind;
/// impl ingraph::EnumFilterMarker for MediaKind {
///   type Filter = ingraph::EnumFilter<MediaKind>;
/// }
///
/// impl ingraph::DefaultMarker for MediaKind {
///   type Marker = ingraph::EnumMarker<MediaKind>;
/// }
/// ```
///
/// A filter kind the FRAMEWORK does not ship has no family word to claim, and needs none: the
/// declaring crate owns a marker of its own and implements [`crate::ToGraphqlFilter`] on it
/// directly, which is legal there for the reason every row here is legal — the marker is a local
/// type. `ingraph-derive`'s composite fixture is written that way.
///
/// and an `Option<MediaKind>` column follows from the blanket. A LIST column of it takes one more —
/// `impl DefaultVecMarker for MediaKind { type Marker = ListMarker<Vec<MediaKind>>; }` — and that
/// row is also where such a crate says its `Vec<MediaKind>` columns are SETS instead, by naming
/// [`crate::SetMarker`] there.
///
/// What it no longer does is name a container's filter by hand in a where struct. `impl
/// ToGraphqlFilter for Vec<MediaKind>` was `E0117` — `Vec` is foreign there, the trait is foreign
/// there, and `Vec` is not fundamental — and it is now an impl nobody writes, because the
/// framework's own `impl<T> ListFilterMarker for Vec<T>` already covers every element.
///
/// # The `, vec = …` arm
///
/// Names what a `Vec` of the registered type means, where the plain arm says *an ordered collection
/// of them*. One type asks for it, and that type is `u8`.
///
/// A `Vec<u8>` field is a BLOB — a thumbnail, a fingerprint, a payload — not a list of small
/// integers. Under the plain arm it would resolve to `ListFilter<u8>` and be given element-wise
/// list operators over individual bytes, so `contains: [0x89]` would ask "is `0x89` an element of
/// this list" where the only useful question is "does this blob contain that byte SEQUENCE". The
/// operators would not be missing; they would be the wrong vocabulary, which is worse, because a
/// caller gets an answer.
///
/// polarsync reached the same place, and its evidence is what it OMITS. Comparing its
/// `impl_as_graphql_filter! {base(…)}` invocation against its `impl_as_graphql_filter! {array(…)}`
/// one, both in `polarsync-core`'s `filter/base.rs`: `u8`, `u16`, `u32` and `u64` appear in `base`
/// and are ABSENT from `array`, so no unsigned integer of any width has a list filter there.
/// `Vec<u8>` is in `base` instead, a value filter rather than a list one.
///
/// Cited by INVOCATION and not by line. polarsync is a sibling CHECKOUT rather than a dependency of
/// this crate, so nothing here builds against it and no build would catch a line number going
/// stale; and the same file sits at several checkout paths on a working machine, where the two
/// invocations land on different lines. A line number is wrong for every path but one from the
/// moment it is written, and nothing would say so.
///
/// Naming the blob READING here rather than withholding a row is what the marker layer changed, and
/// it moves the decision to where it is made: `u8`'s row says what a `Vec` of it means, in one
/// place, instead of a `no_collection` token here and a `Vec<u8>` registration further down that a
/// reader has to connect. `Vec<u8>` still registers in its own right — as BYTES, so `Vec<Vec<u8>>`
/// is a LIST of blobs, which matches polarsync too: it carries `Vec<u8>` in `array(…)` as well as
/// in `base(…)`.
///
/// The family traits themselves need no such exception, and that is what the split moved: bytes and
/// list are decided at the MARKER, so `Vec<u8>` implements [`crate::BytesFilterMarker`] and
/// [`crate::ListFilterMarker`] both and nothing has to choose between them. Only the DEFAULT does,
/// and it is `DefaultVecMarker`'s row on `u8` that chooses.
///
/// A blanket for `Vec<T>` with `u8` as its exception is what that row exists INSTEAD of, and it is
/// not a preference: two impls of one trait where one is a special case of the other is `E0119` on
/// stable, whichever level it is written at. So the `Vec` default is a row per ELEMENT type, which
/// is also what lets a downstream element type supply its own.
///
/// # The two `@` arms
///
/// The family arms carry `vec = …` as an OPTIONAL tail and hand it on; the pair below is where the
/// three impls are actually written, once. They lead with `@` so that no registration can reach
/// them by accident — a family arm's first token is a type, and `@` starts none.
///
/// Their ORDER is not load-bearing, and that is worth stating because the arms it replaced carried
/// a note saying it was. Swapping them was measured: `macro_rules` requires an arm to consume the
/// whole invocation, so a `$ty:ty` that matched with `, vec = …` left over makes the arm FAIL and
/// the next one is tried. It does not "choke on the leftover tokens" — there is no parse error to
/// report, and both orders register `Vec<u8>` as a blob.
macro_rules! to_filter {
  (@ $family:ident, $marker:ident, $ty:ty => $filter:ty, vec = $vec:ty) => {
    impl $crate::$family for $ty {
      type Filter = $filter;
    }
    impl $crate::DefaultMarker for $ty {
      type Marker = $crate::$marker<$ty>;
    }
    impl $crate::DefaultVecMarker for $ty {
      type Marker = $vec;
    }
  };
  (@ $family:ident, $marker:ident, $ty:ty => $filter:ty) => {
    to_filter!(@ $family, $marker, $ty => $filter, vec = $crate::ListMarker<::std::vec::Vec<$ty>>);
  };
  ($ty:ty as scalar => $filter:ty $(, vec = $vec:ty)?) => {
    to_filter!(@ ScalarFilterMarker, ScalarMarker, $ty => $filter $(, vec = $vec)?);
  };
  ($ty:ty as string => $filter:ty $(, vec = $vec:ty)?) => {
    to_filter!(@ StringFilterMarker, StringMarker, $ty => $filter $(, vec = $vec)?);
  };
  ($ty:ty as bytes => $filter:ty $(, vec = $vec:ty)?) => {
    to_filter!(@ BytesFilterMarker, BytesMarker, $ty => $filter $(, vec = $vec)?);
  };
  ($ty:ty as bool => $filter:ty $(, vec = $vec:ty)?) => {
    to_filter!(@ BoolFilterMarker, BoolMarker, $ty => $filter $(, vec = $vec)?);
  };
  ($ty:ty as duration => $filter:ty $(, vec = $vec:ty)?) => {
    to_filter!(@ DurationFilterMarker, DurationMarker, $ty => $filter $(, vec = $vec)?);
  };
}

/// The `input_fields` map ONE input object registers, from `$name : $fty` pairs in declaration
/// order. Both faces [`filter_input_object!`] emits build their field list here — the nullable one by
/// passing the same pairs and appending `"isNull"` — so "the nullable face is `F`'s fields plus the
/// null test" is one list read twice rather than two lists kept in step by hand.
#[cfg(feature = "async-graphql")]
#[doc(hidden)]
#[macro_export]
macro_rules! __ingraph_filter_input_fields {
  ($registry:ident, $( $name:literal : $fty:ty ),+ $(,)?) => {{
    let mut fields = $crate::__private::async_graphql::indexmap::IndexMap::new();
    $(
      fields.insert(
        ::std::string::String::from($name),
        $crate::__private::async_graphql::registry::MetaInputValue {
          name: ::std::string::String::from($name),
          description: ::std::option::Option::None,
          ty: <$fty as $crate::__private::async_graphql::InputType>::create_type_info($registry),
          deprecation: $crate::__private::async_graphql::registry::Deprecation::NoDeprecated,
          default_value: ::std::option::Option::None,
          visible: ::std::option::Option::None,
          inaccessible: false,
          tags: ::std::vec::Vec::new(),
          is_secret: false,
          directive_invocations: ::std::vec::Vec::new(),
        },
      );
    )+
    fields
  }};
}

/// The `to_value` object an input object renders, from `$name : $field` pairs read off `$owner`. The
/// bare face passes `self`; the nullable face passes `self.inner` and appends `"isNull"` — the same
/// field list in the same order its registration declares.
#[cfg(feature = "async-graphql")]
#[doc(hidden)]
#[macro_export]
macro_rules! __ingraph_filter_value_map {
  ($owner:expr, $( $name:literal : $field:ident ),+ $(,)?) => {{
    let mut map = $crate::__private::async_graphql::indexmap::IndexMap::new();
    $(
      map.insert(
        $crate::__private::async_graphql::Name::new($name),
        $crate::__private::async_graphql::InputType::to_value(&$owner.$field),
      );
    )+
    map
  }};
}

/// Emit the hand-written wire face for ONE concrete filter instantiation: its
/// `async_graphql::InputType` (+ `InputObjectType`) pair, and the [`NullableFace`] row a NULLABLE
/// column of that type reaches its face through. `$filter` is the concrete type (e.g.
/// `ScalarFilter<i64>`), `$gql` its GraphQL input name, and each `$field: $fty => $name` is a struct
/// field, its `InputType` field type, and its GraphQL name.
///
/// Three impls from one invocation, and that is the point. Nullability is a type here, so a
/// registered filter needs a second wire face — the one carrying `isNull` — and the way that face
/// went missing once already is a registration site that could mint one alone. This macro has no arm
/// that does: there is no expansion yielding the bare impls by themselves.
///
/// # The nullable half is a ROW rather than an impl, and that is what opened the surface
///
/// It used to be a second `impl InputType for Nullable<$filter>` written out here per registration,
/// and a table of concrete rows is a table only this crate can extend — the same wall
/// [`TextWire`](crate::TextWire) took `TextFilter` off. `Nullable<F>`'s face is now ONE blanket over
/// [`NullableFace`], which every row here feeds, and a declaring crate joins by implementing that
/// trait on a filter it owns.
///
/// So this macro writes the two pieces a bare face keeps to itself — its field list and its rendered
/// slots — and the blanket assembles the twin: `Nullable` before `$gql`, the fields with `isNull`
/// appended, and a `parse` that hands the SAME object to `$filter`'s own. The bare face reads BOTH
/// pieces back off the row, so the field list is written once per invocation and the two faces cannot
/// come to publish different names in different orders.
///
/// A hand-written impl (not the `InputObject` derive) is required because the derive puts
/// `T: InputType` on the *struct* (it generates generic internal parse methods), which would break
/// the bound-free filter structs and every `to_filter!` registration whose operand has no scalar —
/// `i128`, `u128` and the byte vocabularies among them.
///
/// Neither impl overrides `InputType::federation_fields` (the `InputObject` derive does, emitting the
/// Apollo Federation field set): there is no Apollo Federation usage in-repo, so the trait's `None`
/// default is correct — a future federation adopter overrides it here.
#[cfg(feature = "async-graphql")]
#[macro_export]
macro_rules! filter_input_object {
  (
    $filter:ty : $gql:literal {
      bare $bare:ident : $bfty:ty => $bname:literal
      $(, $field:ident : $fty:ty => $name:literal )* $(,)?
    }
  ) => {
    impl $crate::__private::async_graphql::InputType for $filter {
      type RawValueType = Self;

      #[inline]
      fn type_name() -> ::std::borrow::Cow<'static, str> {
        ::std::borrow::Cow::Borrowed($gql)
      }

      fn create_type_info(
        registry: &mut $crate::__private::async_graphql::registry::Registry,
      ) -> ::std::string::String {
        registry.create_input_type::<Self, _>(
          $crate::__private::async_graphql::registry::MetaTypeId::InputObject,
          |registry| $crate::__private::async_graphql::registry::MetaType::InputObject {
            name: ::std::string::String::from($gql),
            description: ::std::option::Option::None,
            input_fields: <Self as $crate::NullableFace>::bare_fields(registry),
            visible: ::std::option::Option::None,
            inaccessible: false,
            tags: ::std::vec::Vec::new(),
            rust_typename: ::std::option::Option::Some(::std::any::type_name::<Self>()),
            oneof: false,
            directive_invocations: ::std::vec::Vec::new(),
          },
        )
      }

      /// # The SHORTHAND LAW, at its first face
      ///
      /// A bare value is this filter's `eq` — rule ① — and a list is refused, since `in` is an
      /// explicit key. An explicit `null` is the NULL TEST, which this face has not got: a
      /// `NOT NULL` column cannot be asked whether it is null, and refusing here is that fact
      /// rather than a gap. See `Sent`, where the whole law is read.
      fn parse(
        value: ::std::option::Option<$crate::__private::async_graphql::Value>,
      ) -> $crate::__private::async_graphql::InputValueResult<Self> {
        match $crate::sent(value) {
          $crate::Sent::Longhand(obj) => {
            let $bare = <$bfty as $crate::__private::async_graphql::InputType>::parse(obj.get($bname).cloned())
              .map_err($crate::__private::async_graphql::InputValueError::propagate)?;
            $(
              let $field = <$fty as $crate::__private::async_graphql::InputType>::parse(obj.get($name).cloned())
                .map_err($crate::__private::async_graphql::InputValueError::propagate)?;
            )*
            ::std::result::Result::Ok(Self { $bare, $( $field, )* })
          }
          $crate::Sent::Bare(__ingraph_bare) => {
            let $bare = <$bfty as $crate::__private::async_graphql::InputType>::parse(
              ::std::option::Option::Some(__ingraph_bare),
            )
            .map_err($crate::__private::async_graphql::InputValueError::propagate)?;
            ::std::result::Result::Ok(Self {
              $bare,
              ..<Self as ::core::default::Default>::default()
            })
          }
          $crate::Sent::Null => {
            ::std::result::Result::Err($crate::__private::async_graphql::InputValueError::expected_type(
              $crate::__private::async_graphql::Value::Null,
            ))
          }
          $crate::Sent::Refused(__ingraph_sent) => {
            ::std::result::Result::Err($crate::__private::async_graphql::InputValueError::expected_type(
              __ingraph_sent,
            ))
          }
        }
      }

      fn to_value(&self) -> $crate::__private::async_graphql::Value {
        $crate::__private::async_graphql::Value::Object(<Self as $crate::NullableFace>::bare_values(self))
      }

      #[inline]
      fn as_raw_value(&self) -> ::std::option::Option<&Self::RawValueType> {
        ::std::option::Option::Some(self)
      }
    }

    impl $crate::__private::async_graphql::InputObjectType for $filter {}

    impl $crate::NullableFace for $filter {
      fn bare_fields(
        registry: &mut $crate::__private::async_graphql::registry::Registry,
      ) -> $crate::__private::async_graphql::indexmap::IndexMap<
        ::std::string::String,
        $crate::__private::async_graphql::registry::MetaInputValue,
      > {
        $crate::__ingraph_filter_input_fields!(registry, $bname : $bfty $(, $name : $fty )*)
      }

      fn bare_values(
        &self,
      ) -> $crate::__private::async_graphql::indexmap::IndexMap<$crate::__private::async_graphql::Name, $crate::__private::async_graphql::Value> {
        $crate::__ingraph_filter_value_map!(self, $bname : $bare $(, $name : $field )*)
      }
    }
  };
}

/// Emit the `InputType` (+ `InputObjectType`) pair AND the [`NullableFace`] row for one filter whose
/// OPERANDS cross through a WIRE CARRIER — [`filter_input_object!`]'s twin, for the rows that macro
/// cannot serve.
///
/// It cannot serve them because it types every field as the STRUCT's own field type and asks
/// async-graphql to parse THAT, which needs the operand itself to be an `InputType`. Three operands
/// are not, and each for its own reason: `u128` and `i128` have no scalar anywhere (async-graphql's
/// integers stop at 64 bits and the impl is `E0117` for every other crate), and `Vec<u8>` has one
/// that answers the wrong question — `[Int!]`, a list of small integers where the column is a blob.
/// So the operand crosses through a carrier, exactly as `DurationFilter`'s hand-written face already
/// crosses `jiff::SignedDuration` through one.
///
/// # ONE carrier per filter, and the two slot shapes are two GROUPS
///
/// `via $wire` is named once rather than per field, because a filter's operands are all made of the
/// one operand type — that is what `ScalarFilter<T>` and `BytesFilter<B>` ARE. The inline slots come
/// first, then a `;`, then the LIST slots, and the split is what keeps the wire type spellable
/// without nesting a macro inside a type position.
///
/// The two groups preserve DECLARATION ORDER for every row that uses this, because both structs put
/// their list slots last — and the SDL renders fields in the order the registry received them, so
/// the order here is what a client reads.
///
/// # The value is built through `Default` and assigned, never through a struct literal
///
/// `BytesFilter` carries a `PhantomData` reading beside its operator slots, so a literal naming only
/// the operators would not compile — and a macro that had to be told about every non-operator field
/// would be a second place to keep in step with the struct. `Default` is `new()` on every filter
/// kind here, which is all-`None` plus whatever else the struct holds.
#[cfg(feature = "async-graphql")]
#[macro_export]
macro_rules! via_filter_input_object {
  (
    $filter:ty : $gql:literal via $wire:ty {
      $( $field:ident => $name:literal ),+ $(,)?
      ;
      $( $list:ident => $list_name:literal ),* $(,)?
    }
  ) => {
    impl $crate::__private::async_graphql::InputType for $filter {
      type RawValueType = Self;

      #[inline]
      fn type_name() -> ::std::borrow::Cow<'static, str> {
        ::std::borrow::Cow::Borrowed($gql)
      }

      fn create_type_info(
        registry: &mut $crate::__private::async_graphql::registry::Registry,
      ) -> ::std::string::String {
        registry.create_input_type::<Self, _>(
          $crate::__private::async_graphql::registry::MetaTypeId::InputObject,
          |registry| $crate::__private::async_graphql::registry::MetaType::InputObject {
            name: ::std::string::String::from($gql),
            description: ::std::option::Option::None,
            input_fields: <Self as $crate::NullableFace>::bare_fields(registry),
            visible: ::std::option::Option::None,
            inaccessible: false,
            tags: ::std::vec::Vec::new(),
            rust_typename: ::std::option::Option::Some(::std::any::type_name::<Self>()),
            oneof: false,
            directive_invocations: ::std::vec::Vec::new(),
          },
        )
      }

      /// The SHORTHAND LAW at a carried face — the FIRST inline slot is the `eq` a bare value
      /// reaches, and it crosses the wire carrier exactly as the longhand's does.
      fn parse(
        value: ::std::option::Option<$crate::__private::async_graphql::Value>,
      ) -> $crate::__private::async_graphql::InputValueResult<Self> {
        match $crate::sent(value) {
          $crate::Sent::Longhand(object) => {
            let mut filter = <Self as ::core::default::Default>::default();
            $( filter.$field = $crate::__private::graphql::filter::via::read::<$wire, _, Self>(&object, $name)?; )+
            $( filter.$list = $crate::__private::graphql::filter::via::read_list::<$wire, _, Self>(&object, $list_name)?; )*
            ::std::result::Result::Ok(filter)
          }
          $crate::Sent::Bare(__ingraph_bare) => {
            let mut __ingraph_object = $crate::__private::async_graphql::indexmap::IndexMap::new();
            __ingraph_object.insert(
              $crate::__private::async_graphql::Name::new($crate::__ingraph_first!($( $name ),+)),
              __ingraph_bare,
            );
            let mut filter = <Self as ::core::default::Default>::default();
            $( filter.$field =
              $crate::__private::graphql::filter::via::read::<$wire, _, Self>(&__ingraph_object, $name)?; )+
            ::std::result::Result::Ok(filter)
          }
          $crate::Sent::Null => {
            ::std::result::Result::Err($crate::__private::async_graphql::InputValueError::expected_type(
              $crate::__private::async_graphql::Value::Null,
            ))
          }
          $crate::Sent::Refused(__ingraph_sent) => {
            ::std::result::Result::Err($crate::__private::async_graphql::InputValueError::expected_type(
              __ingraph_sent,
            ))
          }
        }
      }

      fn to_value(&self) -> $crate::__private::async_graphql::Value {
        $crate::__private::async_graphql::Value::Object(<Self as $crate::NullableFace>::bare_values(self))
      }

      #[inline]
      fn as_raw_value(&self) -> ::std::option::Option<&Self::RawValueType> {
        ::std::option::Option::Some(self)
      }
    }

    impl $crate::__private::async_graphql::InputObjectType for $filter {}

    impl $crate::NullableFace for $filter {
      fn bare_fields(
        registry: &mut $crate::__private::async_graphql::registry::Registry,
      ) -> $crate::__private::async_graphql::indexmap::IndexMap<
        ::std::string::String,
        $crate::__private::async_graphql::registry::MetaInputValue,
      > {
        $crate::__ingraph_filter_input_fields!(
          registry,
          $( $name : ::core::option::Option<$wire>, )+
          $( $list_name : ::core::option::Option<::std::boxed::Box<[$wire]>> ),*
        )
      }

      fn bare_values(
        &self,
      ) -> $crate::__private::async_graphql::indexmap::IndexMap<$crate::__private::async_graphql::Name, $crate::__private::async_graphql::Value> {
        let mut map = $crate::__private::async_graphql::indexmap::IndexMap::new();
        $(
          map.insert(
            $crate::__private::async_graphql::Name::new($name),
            $crate::__private::graphql::filter::via::write::<$wire, _>(&self.$field),
          );
        )+
        $(
          map.insert(
            $crate::__private::async_graphql::Name::new($list_name),
            $crate::__private::graphql::filter::via::write_list::<$wire, _>(&self.$list),
          );
        )*
        map
      }
    }
  };
}

mod boolean;
mod bytes;
mod confidence;
#[cfg(any(feature = "jiff", feature = "async-graphql"))]
mod duration;
mod r#enum;
/// The FLAGS filter — seven hard words over a bit set, and the sugar that folds into four of them.
#[cfg(feature = "flags")]
mod flags;
/// The SPLICE SEAM a COMPOSED filter's `#[ingraph(flatten)]` field is read through, public for
/// [`via`]'s reason: the emitted face names its table door and lands in a crate that cannot see a
/// `pub(crate)` item here.
#[cfg(feature = "async-graphql")]
#[doc(hidden)]
pub mod flatten;
mod list;
mod nullable;
mod quantified;
mod reference;
mod related;
mod scalar;
mod set;
/// The SLOT SEAM a COMPOSED filter's emitted face resolves each of its fields through.
mod slot;
/// The two temporal CARRIERS async-graphql declines to ship — a wall clock and a zone offset. Gated
/// as `duration` is and for its reason: the carriers are jiff types' wire faces, so a build with
/// neither the vocabulary nor the binding has nothing to give them to.
///
/// `pub(crate)` where its neighbours are private, because the capture-time operand reaches its two
/// GRAMMARS by path: a `pub(crate) use` beside the public one below would be an unused import in
/// every build that has the carriers and not the citizen, which is a real feature set — the
/// workspace's own `xtask` builds one.
#[cfg(any(feature = "jiff", feature = "async-graphql"))]
pub(crate) mod temporal;
#[cfg(test)]
mod tests;
mod text;
/// The carrier crossings a CARRIED face spends, public because
/// [`via_filter_input_object!`](crate::via_filter_input_object) is: an exported macro's expansion
/// names them, and it lands in a crate that cannot see a `pub(crate)` item here. Reached through
/// the shelf and covered by no stability promise, as everything an expansion names is.
#[cfg(feature = "async-graphql")]
#[doc(hidden)]
pub mod via;

pub use boolean::*;
pub use bytes::*;
// The byte crossing's own seam, and a glob does not carry it: `pub use …::*` re-exports what is
// `pub`, and these two are the crate's alone — see [`ByteSlots`] for why one entry point has to
// take both byte kinds.
//
// Each carries the gate of the family that spends it, which is this crate's import rule and not a
// courtesy: `ingraph-derive`'s own test builds take this crate with neither backend, and an import
// whose consumer is compiled out is a warning in exactly those runs.
#[cfg(feature = "mongo")]
pub(crate) use bytes::ByteOperands;
#[cfg(any(feature = "mongo", feature = "sqlx"))]
pub(crate) use bytes::ByteSlots;
pub use confidence::*;
#[cfg(any(feature = "jiff", feature = "async-graphql"))]
pub use duration::*;
pub use r#enum::*;
#[cfg(feature = "flags")]
pub use flags::*;
// The TRAIT alone, where the module's other item is a door only an expansion spells. A component
// face satisfies this one by carrying `NullableFace`, so it is a name a declarer reads about rather
// than one they write.
#[cfg(feature = "async-graphql")]
pub use flatten::FlattenFace;
pub use list::*;
pub use nullable::*;
pub use quantified::*;
pub use reference::*;
pub use related::*;
pub use scalar::*;
pub use set::*;
pub use slot::*;
#[cfg(any(feature = "jiff", feature = "async-graphql"))]
pub use temporal::{JiffCivilDateTime, JiffZoneOffset};
pub use text::*;

/// "Is any operator set" — the one question every filter answers the same way on every backend,
/// asked through a type parameter.
///
/// Each kind ALSO carries an inherent `const fn is_empty` with the same body, and that one wins
/// method resolution, so a concrete call site reads identically either way. This trait exists for
/// the site that cannot reach an inherent method — a wrapper composing its own emptiness from the
/// filter it wraps. Asking through a backend lowering instead would make the caller name a dialect:
/// with two families compiled, `f.is_empty()` through the lowering traits is `E0283`.
///
/// Public because a filter declared downstream implements it as readily as one declared here.
pub trait GraphqlFilter {
  /// True while NO operator slot is set — so a lowering would emit nothing for this field.
  fn is_empty(&self) -> bool;
}

/// A kind's operand map, reached where the KIND ITSELF is a parameter.
///
/// Each kind ALSO carries an inherent `try_map` with the same body, and that one wins method
/// resolution, so a concrete call site reads identically either way — the arrangement
/// [`GraphqlFilter`] already has, for the reason it has it. What this trait adds is the site that
/// cannot reach an inherent method, and there is exactly one: a COLLECTION's crossing, whose nested
/// `any` slot holds a whole filter of a kind that crossing only ever knows as a type parameter.
///
/// # What it is FOR: one declared converter reaching one level down
///
/// A collection's own operands and the operands inside its `any` filter are made of the same
/// ELEMENT, so ONE declared converter is what carries both. The collection kinds' crossings spend it
/// twice — on their own slots through the inherent `try_map`, and on the nested filter's through
/// this bound.
///
/// # The kinds with no row, and why each absence is honest
///
/// [`BooleanFilter`] and [`DurationFilter`](crate::DurationFilter) have no `try_map` to expose:
/// neither carries an operand parameter for one to map, so there is no *this kind over `V`* for
/// [`Mapped`](Self::Mapped) to name. A collection of either with a DECLARED converter is `E0277`
/// naming this trait and the kind, which is the
/// [`PgCollectionStorage`](crate::comparison::sql::PgCollectionStorage) posture one trait over — a
/// missing row refuses at the crossing, naming the row a reader can go and write.
///
/// The two COLLECTION kinds have no row either, and that absence is a storability fact rather than a
/// spelling one: a collection's elements are stored as `V` and no dialect here carries a collection
/// as one, so a collection OF collections has nothing to cross into whatever this trait said.
///
/// Public because a filter kind declared downstream is a collection's element as readily as one
/// declared here.
pub trait TryMapFilter<D, V> {
  /// This kind carrying `V` where `Self` carries `D`.
  type Mapped;

  /// Convert every operand with `f`, keeping the operator set exactly as it stands.
  ///
  /// # Errors
  ///
  /// Whatever `f` refuses an operand with, the first refusal winning — see
  /// [`ScalarFilter::try_map`], whose promises every row here inherits by delegating to its kind's
  /// own `try_map`.
  fn try_map_filter<E, F>(self, f: F) -> Result<Self::Mapped, E>
  where
    F: FnMut(D) -> Result<V, E>;
}

/// The one filter an EXPANSION builds rather than receives: this kind's empty filter with its
/// equality operator set.
///
/// Each kind ALSO carries `new()` and an inherent `with_eq`, and a caller that can SPELL its kind
/// keeps writing `ScalarFilter::new().with_eq(1)`. This is not a second construction face beside
/// that one — it is the same two calls, reached from a site that cannot name the kind. The
/// arrangement is [`GraphqlFilter`]'s and [`TryMapFilter`]'s, for the reason both have it.
///
/// # The site that cannot name the kind, and why it is not hypothetical
///
/// An emitter holds a column's filter as the PROJECTION
/// `<<T as DefaultMarker>::Marker as ToGraphqlFilter>::Filter`, and the projection layer is
/// deliberately type-blind — `type MaybeCover = Option<Uuid7>` is the case that proves a spelling
/// cannot be trusted, so no emitter may branch on one. Two spellings answer that projection,
/// `ScalarFilter<T>` and [`Nullable<ScalarFilter<T>>`](Nullable), and they take an equality operand
/// through DIFFERENT expressions: the wrapper has no `with_eq` of its own, the null test being the
/// only operator it owns. So there is no one line an emitter could write instead, and writing two
/// would mean detecting which — the thing the layer exists to forbid.
///
/// # `equals` rather than `eq`
///
/// `eq` names every kind's equality GETTER, and an inherent method wins method resolution. A trait
/// method spelled `eq` would be shadowed at every concrete call site, reachable only as
/// `<F as EqualsFilter<T>>::eq(v)` — which is the spelling this trait exists so that nobody needs.
///
/// # The kinds with no row, and why the absence is honest
///
/// [`ListFilter`] and [`SetFilter`] have none. Their `eq` slot holds a WHOLE COLLECTION — *this
/// column's elements are exactly these* — so a row would have to read `T = Box<[V]>`, and a caller
/// asking for ONE value would get a one-element collection instead of a refusal. A column whose
/// filter is a collection's is therefore `E0277` naming this trait and the kind, which is
/// [`TryMapFilter`]'s own posture: a missing row refuses where a reader can see which pair refused.
///
/// Public because a filter kind declared downstream guards a lineage column as readily as one
/// declared here.
pub trait EqualsFilter<T> {
  /// The empty filter with its equality operator set to `value` — *this column is exactly this*.
  #[must_use]
  fn equals(value: T) -> Self;
}

/// One named slot, read off a wire object and PROPAGATED into the owning face's refusal type.
///
/// The FIRST of a list of literals — what a carried face's bare value is read as.
///
/// A carried filter's slots are named in one place and this is that place read back: the shorthand
/// puts the bare value under the first inline slot, which is `eq` at every row that uses the macro.
/// A `macro_rules!` cannot index a repetition, so the head is taken by a second arm.
#[doc(hidden)]
#[macro_export]
macro_rules! __ingraph_first {
  ($head:literal $(, $rest:literal )*) => {
    $head
  };
}

/// What a client SENT at a filter position — the four readings the SHORTHAND LAW admits.
///
/// # The law, and where it comes from
///
/// polarsync's filters take a bare value where an object is expected and read it as equality, and
/// its `null` is a test rather than an absence. Both are worth having and both are read HERE, once,
/// so that every hand-written filter face answers them the same way rather than each deciding for
/// itself:
///
/// | sent | reading |
/// |---|---|
/// | `{ eq: 42 }` | [`Longhand`](Self::Longhand) — the object, read key by key |
/// | `42` | [`Bare`](Self::Bare) — rule ①, the same as `{ eq: 42 }` |
/// | `null` | [`Null`](Self::Null) — rule ②, the NULL TEST, distinct from absent |
/// | `[1, 2]` | [`Refused`](Self::Refused) — rule ③, faithfully: `in` is an explicit key |
/// | absent | [`Refused`](Self::Refused) — a filter position with no value is not a predicate |
///
/// # Rule ③ is an ABSENCE, and it is faithful rather than conservative
///
/// A list at a bare position could plausibly read as `{ in: […] }`, and polarsync does not do that:
/// its `in` is an explicit key. So a list is refused exactly as it was before this law arrived, and
/// the refusal is the same `expected_type` a client already gets.
///
/// # Rule ② needs somebody who HAS a null test
///
/// [`Null`](Self::Null) is a reading, not an answer: a `NOT NULL` column's filter has no null test to
/// set, so it refuses one — which is the whole content of nullability being a TYPE in this crate. The
/// nullable faces are the ones that act on it, and they reach it through the one blanket
/// [`NullableFace`] carries.
///
/// # Where the READING is delivered from, measured
///
/// Rules ① and ③ arrive through async-graphql; rule ② does not, at either kind of position. A
/// NON-NULL argument has its `null` refused by the validator before any face is asked, and a
/// nullable one is `Option<F>` in Rust, whose own row answers `Ok(None)` without asking the inner
/// face — which is *no predicate written* rather than a question about a column. So the null
/// reading is a property of this type that a different binding may deliver and this one does not;
/// `tests/filter_macros.rs` pins the measurement.
///
/// Public because a filter face declared downstream answers this law as readily as one declared
/// here — that is what the two registration macros carry across the crate boundary.
#[cfg(feature = "async-graphql")]
pub enum Sent {
  /// An OBJECT — the longhand, whose keys each face reads for itself.
  Longhand(async_graphql::indexmap::IndexMap<async_graphql::Name, async_graphql::Value>),
  /// A BARE VALUE at a column-filter position: rule ①, which every face reads as its `eq`.
  Bare(async_graphql::Value),
  /// An explicit `null`: rule ②, the null test — and never the same state as absent.
  Null,
  /// A list, or nothing at all — carrying whatever arrived, for the refusal to name.
  Refused(async_graphql::Value),
}

/// Read what arrived at a filter position under the shorthand law — see [`Sent`].
#[cfg(feature = "async-graphql")]
pub fn sent(value: Option<async_graphql::Value>) -> Sent {
  match value {
    Some(async_graphql::Value::Object(object)) => Sent::Longhand(object),
    Some(async_graphql::Value::Null) => Sent::Null,
    // Rule ③: `in` is an explicit key, so a list here is what it was before — not a predicate.
    Some(list @ async_graphql::Value::List(_)) => Sent::Refused(list),
    Some(bare) => Sent::Bare(bare),
    None => Sent::Refused(async_graphql::Value::Null),
  }
}

/// Rule ①'s LANDING at a composed face: the bare value put under the first field the face publishes,
/// as the object the ordinary reads then run over.
///
/// # The name is read off the published table, not spelled by the emitter
///
/// *The first slot* is the rule, and a composed declaration's own field list stopped being able to
/// state it the moment `#[ingraph(flatten)]` existed: a spliced component's fields are published
/// first and the declaration never writes their names down. Reading the name off `bare_values` is
/// what keeps the shorthand and the registration unable to name different slots — the property the
/// rule was chosen for.
///
/// The default filter and its render are built on the BARE path alone. A longhand document never
/// reaches here.
#[cfg(feature = "async-graphql")]
pub fn shorthand<F>(
  bare: async_graphql::Value,
) -> async_graphql::indexmap::IndexMap<async_graphql::Name, async_graphql::Value>
where
  F: NullableFace,
{
  let mut object = async_graphql::indexmap::IndexMap::new();
  // A face publishing NO field cannot be in a schema — an input object with no field is not valid
  // SDL, which is why the derive refuses an empty declaration — so there is no slot for the value to
  // land in and the reads that follow answer `None`. Dropping it beats panicking on a request path.
  if let Some(first) = F::default().bare_values().into_keys().next() {
    object.insert(first, bare);
  }
  object
}

/// The refusal a COMPOSED face writes where its declaration DECLINED rule ① —
/// `#[ingraph(composed(shorthand = false))]`.
///
/// # What a face declines the shorthand FOR
///
/// Rule ① reads a bare value as the FIRST slot, and that is worth having exactly while the first
/// slot is the one a bare value obviously means. A filter whose vocabulary is a RELATION has no such
/// slot: a range has no `eq` — an interval is not equal to a point in any sense a client asks for —
/// and a length facet's four bounds are four, `"0:00:05"` being as readily *at least* as *at most*.
/// A face that picked one would be answering a question the client did not ask, so the bare value is
/// refused with the operator names instead.
///
/// # The names come off the face's OWN render table
///
/// Read from `bare_values` on a default `F` rather than handed in as literals, so what a refusal
/// offers is what the registration published — including any name a `#[ingraph(flatten)]` spliced in,
/// which the declaration itself cannot spell. The default filter and its render are built for the
/// refusal alone: every path that is not a refusal has already returned.
#[cfg(feature = "async-graphql")]
pub fn refuse_bare<F>(sent: &async_graphql::Value) -> async_graphql::InputValueError<F>
where
  F: NullableFace,
{
  let rendered = F::default().bare_values();
  let names = rendered
    .keys()
    .map(async_graphql::Name::as_str)
    .collect::<std::vec::Vec<_>>();
  let face = <F as async_graphql::InputType>::type_name();
  async_graphql::InputValueError::custom(match names.split_last() {
    // A face with NO slot is unreachable through the derive, which refuses an empty declaration —
    // but the sentence is a total function of what it was handed rather than one with a hole.
    None => std::format!("a `{face}` takes an object — not a bare {sent}"),
    Some((last, [])) => {
      std::format!("a `{face}` names the operator it asks: {last} — not a bare {sent}")
    }
    Some((last, rest)) => std::format!(
      "a `{face}` names the operator it asks: one of {listed} or {last} — not a bare {sent}",
      listed = rest.join(", "),
    ),
  })
}

/// A function rather than the line `filter_input_object!` repeats per field: that macro pastes the
/// read at every call site because it expands into a CONCRETE impl, where the faces written over a
/// PARAMETER — the enum's, the sequence's and the set's — are generic and can call one. `F` is the
/// owner and is spelled `Self` at every call, the same shape [`via::read`] takes and for the same
/// reason: an `InputValueError` carries the type it is about, so a slot's refusal has to be
/// re-pointed at the face that was being parsed.
///
/// The BODY moved to [`via::nested`], which a composed filter's emitted face reaches through the
/// shelf; this name stays because the in-crate faces are written with it and because *the slot the
/// generic faces parse* and *the nested slot an expansion parses* are one operation with two
/// readers, not two operations.
#[cfg(feature = "async-graphql")]
#[inline]
pub(crate) fn parse_slot<V, F>(
  object: &async_graphql::indexmap::IndexMap<async_graphql::Name, async_graphql::Value>,
  name: &str,
) -> Result<V, async_graphql::InputValueError<F>>
where
  V: async_graphql::InputType,
  F: async_graphql::InputType,
{
  via::nested(object, name)
}

/// The wire-vocabulary word an element FILTER is built from: its own schema name with the family
/// suffix taken off — `I64Filter` → `I64`, `TagFilter` → `Tag`.
///
/// # Why the ELEMENT'S FILTER names a collection and the element itself cannot
///
/// A collection face written over a parameter has to derive its schema name from something, and the
/// obvious source is the element's own — which is what [`EnumFilter`]'s face does. Measured, that
/// source is not injective here and cannot be made so: async-graphql publishes EVERY integer width
/// as `Int` (`types/external/integers.rs`, ten `#[Scalar(internal, name = "Int")]` impls), so `i8`,
/// `i64` and `u32` are one word. A sequence face named from the element would put seven Rust types
/// under `IntListFilter` — which is `Registry::create_type`'s own panic — and would rename the four
/// families this crate already publishes.
///
/// The element's FILTER is injective where the element is not, because naming it is precisely the
/// job this crate's own roster does: `ScalarFilter<i8>` is `I8Filter` and `ScalarFilter<i64>` is
/// `I64Filter`. And the scheme those names are written in is the NAMING CONSTITUTION's first law —
/// *`UpperCamel(scalar)`, with one modifier per wrapper* — so taking the suffix off recovers the
/// STEM those names are built on, and putting `ListFilter` on gives the collection's. The stem and
/// the scalar differ in one letter's case since the 2026-08-18 amendment, and it is the stem that
/// composes: the scalar `i64` is the operand's own word and `I64` is what every name over it is
/// written from. See [`roster`](crate::graphql::roster); the rows there are what pin it.
///
/// A name that does not end in the suffix comes back whole. Every filter this crate registers ends
/// in it — that is the convention rather than a coincidence — so the arm is a total function's
/// honest tail and not a case with a behaviour of its own.
#[cfg(feature = "async-graphql")]
pub(crate) fn operand_of(filter: &str) -> &str {
  filter.strip_suffix("Filter").unwrap_or(filter)
}

/// Map one optional operand — the single-slot half of every kind's `try_map`.
///
/// `pub(crate)` rather than private to this module: [`BooleanFilter`] has no `try_map` of its own to
/// hold it (it has no type parameter for one to map), so its crossing calls these two directly and
/// runs the same code every other kind runs.
pub(crate) fn map_operand<T, U, E>(
  slot: Option<T>,
  f: &mut impl FnMut(T) -> Result<U, E>,
) -> Result<Option<U>, E> {
  match slot {
    Some(value) => f(value).map(Some),
    None => Ok(None),
  }
}

/// Map one optional operand LIST, element by element — the list half of every kind's `try_map`.
///
/// The FIRST failure is the answer, and the operands already mapped go with it rather than being
/// reported half-done. An empty list maps to an empty list and never collapses to `None`: `in: []`
/// is the operator present asking for no rows, where an absent `in_` asks for every row.
pub(crate) fn map_operands<T, U, E>(
  slot: Option<Box<[T]>>,
  f: &mut impl FnMut(T) -> Result<U, E>,
) -> Result<Option<Box<[U]>>, E> {
  match slot {
    Some(values) => {
      let mut mapped = Vec::with_capacity(values.len());
      for value in values {
        mapped.push(f(value)?);
      }
      Ok(Some(mapped.into_boxed_slice()))
    }
    None => Ok(None),
  }
}

to_filter!(bool as bool => BooleanFilter);
to_filter!(i8 as scalar => ScalarFilter<i8>);
to_filter!(i16 as scalar => ScalarFilter<i16>);
to_filter!(i32 as scalar => ScalarFilter<i32>);
to_filter!(i64 as scalar => ScalarFilter<i64>);
to_filter!(i128 as scalar => ScalarFilter<i128>);
// A `Vec<u8>` is a BLOB and not a list of small integers, which is the one place a `Vec` of a
// registered type does not mean *a collection of them* — see `to_filter!`'s `, vec = …` tail.
to_filter!(u8 as scalar => ScalarFilter<u8>, vec = BytesMarker<Vec<u8>>);
to_filter!(u16 as scalar => ScalarFilter<u16>);
to_filter!(u32 as scalar => ScalarFilter<u32>);
to_filter!(u64 as scalar => ScalarFilter<u64>);
to_filter!(u128 as scalar => ScalarFilter<u128>);
to_filter!(f32 as scalar => ScalarFilter<f32>);
to_filter!(f64 as scalar => ScalarFilter<f64>);
// The `NonZero*` family, ruled 2026-08-22 (findit-studio/ingraph#355): ten rows, following the
// widths above letter for letter. Each is a NUMBER — `gt`, `lt` and their neighbours mean the same
// thing a plain integer's do — so the family word is `scalar`, exactly as it is above; only the
// STORAGE and READ rows differ; see `column::assemble` and `comparison::sql::carrier` for those.
to_filter!(::core::num::NonZeroI8 as scalar => ScalarFilter<::core::num::NonZeroI8>);
to_filter!(::core::num::NonZeroI16 as scalar => ScalarFilter<::core::num::NonZeroI16>);
to_filter!(::core::num::NonZeroI32 as scalar => ScalarFilter<::core::num::NonZeroI32>);
to_filter!(::core::num::NonZeroI64 as scalar => ScalarFilter<::core::num::NonZeroI64>);
to_filter!(::core::num::NonZeroI128 as scalar => ScalarFilter<::core::num::NonZeroI128>);
to_filter!(::core::num::NonZeroU8 as scalar => ScalarFilter<::core::num::NonZeroU8>);
to_filter!(::core::num::NonZeroU16 as scalar => ScalarFilter<::core::num::NonZeroU16>);
to_filter!(::core::num::NonZeroU32 as scalar => ScalarFilter<::core::num::NonZeroU32>);
to_filter!(::core::num::NonZeroU64 as scalar => ScalarFilter<::core::num::NonZeroU64>);
to_filter!(::core::num::NonZeroU128 as scalar => ScalarFilter<::core::num::NonZeroU128>);
// THE NETWORK FAMILY, ruled 2026-08-25 with the rest of the base-type completeness round: six rows,
// following the widths above letter for letter and for the reason the `NonZero` block gives — an
// address is ORDERED, and totally. `Ipv4Addr` and `Ipv6Addr` compare as the integer their octets
// spell, which is what makes `gte`/`lte` a SUBNET question a client can already ask: every address
// under a prefix is a contiguous range, so `10.0.0.0` … `10.0.0.255` is `10.0.0.0/24` written in the
// vocabulary the ordering family already has. A CIDR OPERAND — `inSubnet: "10.0.0.0/24"` — is a
// DOOR and not built: it is a second grammar to parse, it wants prefix arithmetic of its own at each
// width, and the range spelling answers the case that motivated the row.
//
// The two UNTAGGED unions order by VERSION first (`std`'s own `Ord`: every v4 sorts below every v6),
// which is total and is what a mixed column can honestly offer. A column that means to range over
// addresses of one version names that version's own type, where the order is the address's alone.
//
// `SocketAddr*` orders by address and then by port, which is the pair's lexicographic order and the
// one a reader expects of `"host:port"`.
//
// NONE of the six has a STORAGE row — no `Carrier`, no `Assemble`, no comparison lowering — so a
// declared column of one reaches a schema and no dialect. That is a RECORDED DOOR and not an
// oversight: the wire form is text, and which of text, a fixed 4/16-byte column or a dialect's own
// address type a backend should bind is a per-dialect ruling this round does not make. See
// [`roster`](crate::graphql::roster), where the door is written down beside the exclusions.
to_filter!(::std::net::Ipv4Addr as scalar => ScalarFilter<::std::net::Ipv4Addr>);
to_filter!(::std::net::Ipv6Addr as scalar => ScalarFilter<::std::net::Ipv6Addr>);
to_filter!(::std::net::IpAddr as scalar => ScalarFilter<::std::net::IpAddr>);
to_filter!(::std::net::SocketAddrV4 as scalar => ScalarFilter<::std::net::SocketAddrV4>);
to_filter!(::std::net::SocketAddrV6 as scalar => ScalarFilter<::std::net::SocketAddrV6>);
to_filter!(::std::net::SocketAddr as scalar => ScalarFilter<::std::net::SocketAddr>);
// THE UUID, ruled 2026-08-29 with the value-column fill: `as scalar` and not `as bytes`, and the two
// halves of that choice are worth separating.
//
// It is a SCALAR because its wire form is ONE canonical text with one spelling — the same reading
// the six addresses above take — and not the hex a byte household publishes. A `BytesFilter` would
// have brought `contains`/`startsWith`/`endsWith` with it, and a substring of a uuid is not a
// question about anything: the value has no parts a client addresses by position, so the wider kind
// would have published doors that always mean nothing.
//
// It is ORDERED, and totally, which is what makes the eight slots honest rather than six honest ones
// and two that lie. `Uuid`'s own `Ord` is the bytewise order over its sixteen bytes, and every
// backend that stores one compares those same bytes the same way — a native `uuid`, a `binary(16)`,
// a `BLOB`, a subtype-4 `BinData`; see `column::stored`, where the four are held against each other.
// So `gte`/`lte` is a range over the VALUE on every backend, and on a v7 column it is a range over
// TIME, that version's leading 48 bits being a big-endian millisecond.
//
// Unlike the six above, this row HAS a storage road: `Carrier`, `Assemble`, `StoredAs<Db>` and
// `MongoCarrier` all exist for it, so a declared uuid column reaches a schema AND a dialect.
to_filter!(::uuid::Uuid as scalar => ScalarFilter<::uuid::Uuid>);
// THE COMPILED PATTERN, and `as scalar` where its STORAGE is text — the one row in this table whose
// family word does not follow its column's shape, so the reason is written out.
//
// A pattern column stores TEXT and compares as text, so the obvious word is `string` and the obvious
// filter `TextFilter<::regex::Regex>`. That row is UNWRITABLE, and the wall is the orphan rule
// rather than a preference. The text lowering's two `LIKE` dialects take
// `V: Carrier<Db> + AsRef<str>` (`comparison::sql::text::{postgres, mysql}`) and mongo's takes
// `V: MongoCarrier + AsRef<str>` (`comparison::mongo::text`), because each derives a PATTERN from
// the operand's own characters. `regex::Regex` has `as_str` and no `AsRef<str>`, and both the trait
// and the type are foreign here, so `impl AsRef<str> for regex::Regex` is `E0117` in this crate and
// in every other but `regex`'s own. The bound is not partially met: without it
// `SqlTextComparison<Regex, Postgres>: ComplexComparison<Postgres>` does not hold at all, so a text
// filter over a pattern column would have lowered on SQLite and on NO other backend — twelve of its
// twenty slots dead on three of four, and the eight live ones dead with them.
//
// So the word is `scalar`, and what that publishes is the EIGHT operators an ordering family has —
// `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `notIn` — over `V: Carrier<Db> + ColumnKind` and
// `V: MongoCarrier`, which are this crate's own traits and are written for `regex::Regex` beside
// every other row it has. All four backends, or none of them: the same posture `uuid::Uuid` takes
// three rows up, arrived at through a different door.
//
// IT IS ORDERED, and the order is the PATTERN's text order — the collation the column's `TEXT`,
// `text` or `varchar(255)` already has, which is the order a listing of stored patterns sorts in.
// That is a real and useful order and it is NOT an order over what the patterns MATCH: no ordering
// of languages by inclusion exists to be published, and none is claimed. A client reading `gte`
// here should read *whose pattern text sorts at or after this*, which is what a paged listing of
// watches wants and the only question the column can answer.
//
// WHAT IS LOST is the substring and affix family — `contains`, `startsWith`, `endsWith` and their
// nine `not_`/`_nocase` relatives — which a pattern column could honestly have been asked (*which
// watches anchor their pattern with `^`* is a question about pattern text, not about the automaton).
// It is lost to the bound above and to nothing else, and it is a DOOR rather than a refusal: the
// three lowerings could take a trait of this crate's own carrying `fn as_text(&self) -> &str`, with
// a row for every text type that has one, and a pattern column would join the text family the day
// they do. That is a change to a published bound and to a documented downstream seam, so it is a
// ruling and not a row — recorded here, in `graphql::roster`, and in the guide's citizen page.
#[cfg(feature = "regex")]
to_filter!(::regex::Regex as scalar => ScalarFilter<::regex::Regex>);
to_filter!(String as string => TextFilter<String>);
// The blob's own two rows, written out because the macro's third impl would collide with the
// blanket: `Vec<u8>`'s DEFAULT marker comes from `u8`'s `DefaultVecMarker` row above, which is the
// one that decided a `Vec` of bytes is read as bytes, and a second `DefaultMarker for Vec<u8>` here
// would be that decision made twice (`E0119`).
//
// The `DefaultVecMarker` row is a `Vec<Vec<u8>>` column: a list of blobs, which is a list, exactly
// as `Vec<[u8; N]>` is a list of hashes.
impl BytesFilterMarker for Vec<u8> {
  type Filter = BytesFilter<Vec<u8>>;
}

impl DefaultVecMarker for Vec<u8> {
  type Marker = ListMarker<Vec<Vec<u8>>>;
}

// This crate's own primitive, and the row that needed no new COMPARISON: a `Confidence` excludes
// `NaN` at construction whatever it measures in — the decimal has none to exclude — so its `Ord` is
// total at every width, and a total order is what makes `gt`/`gte`/`lt`/`lte` well-defined over it.
// What it needed and now has is a filter KIND, and the reason is the OPERAND rather than the
// operators: see [`ConfidenceFilter`], where one widthless threshold replaces the four `Score*`
// scalars the four widths used to publish.
//
// ALL FOUR WIDTHS NAME ONE FACE, which is what a non-generic filter buys and what the four-name
// arrangement could not: `Registry::create_type` panics on one GraphQL name held by two Rust types,
// so `ScalarFilter<Confidence<f32>>` and `ScalarFilter<Confidence<f64>>` were two names for one
// vocabulary. There is one Rust type here, so there is one name.
//
// ONE row over the WIDTH rather than four, and it is written out rather than passed through
// `to_filter!` because a free type parameter cannot cross that macro's `$ty:ty` — the wall
// `[u8; N]`'s rows a hundred lines up are hand-written against.
//
// Four rows would have compiled the same code and would ALSO have put four lines into rustc's *the
// following other types implement trait `ScalarFilterMarker`* help, TWO OF WHICH RIDE A CARGO
// FEATURE. That block is a list truncated to eight, so four rows make its content vary with the
// vocabulary a build takes, and a golden pinning it is red on one lane and green on another. See
// `graphql::carrier`'s confidence row for the measurement; this is the same fact one trait over.
//
// Ungated, unlike every row below: the type is declared here, so nothing has to be depended on to
// name it — and the two gated WIDTHS need no gate here either, because what rides `half` and
// `rust_decimal` is which INSTANTIATIONS exist rather than which impl does.
impl<S: crate::ConfidenceCarrier> crate::ScalarFilterMarker for Confidence<S> {
  type Filter = ConfidenceFilter;
}

impl<S: crate::ConfidenceCarrier> DefaultMarker for Confidence<S> {
  type Marker = crate::ScalarMarker<Confidence<S>>;
}

impl<S: crate::ConfidenceCarrier> DefaultVecMarker for Confidence<S> {
  type Marker = ListMarker<Vec<Confidence<S>>>;
}

// The crate's SECOND primitive, joining the temporal family and needing no filter kind of its own
// either. An instant is totally ordered — `Timestamp`'s `Ord` is the derive over jiff's, and jiff's
// is a comparison of one duration since the epoch — so `gt`/`gte`/`lt`/`lte` mean what they say, and
// `ScalarFilter` is what jiff's own `Timestamp` is already registered at four rows below.
//
// Ungated, and this is the row where the promotion is visible: `jiff::Timestamp`'s registration
// costs a feature because the TYPE is a vocabulary a declaration opts into, and this one costs
// nothing because the type is the framework's. The two rows are not duplicates — they register two
// different Rust types, and a declaration picks which by which type its field names.
to_filter!(Timestamp as scalar => ScalarFilter<Timestamp>);

// The crate's THIRD primitive, and the same answer for the same reason: a cardinality is totally
// ordered, so `gt`/`gte`/`lt`/`lte` mean what they say and `ScalarFilter` is the whole of what it
// needs. Ungated with the type.
//
// **THE NAME IT PUBLISHES UNDER IS `CardinalityFilter` AND NOT `CountFilter`**, which is the one
// place a named type of this crate's does not wear its own name — see `graphql::carrier`'s row for
// the collision that decides it: `CountFilter` is already the PROTOCOL's, over `usize`, at the
// `count` slot of `ListFilter` and `SetFilter`. A schema holding both a collection column and a
// `Count` column would otherwise put one GraphQL name on two Rust types, which
// `Registry::create_type` answers with a panic.
to_filter!(Count as scalar => ScalarFilter<Count>);

// The gated vocabularies. Each is a foreign byte, string or temporal type a declaration wants to
// name as a field type, each goes through the full arm and so gets its four container shapes, and
// each costs the dependency it is named from — which is why each is off by default (see
// `Cargo.toml`). `jiff`'s rows cost a feature and no longer cost a dependency, the crate having
// become structural; what the feature buys there is the right to DECLARE a field of jiff's own
// types.
//
// `smol_str::SmolStr`, `bytes::Bytes` and `jiff::Timestamp` are `legacy/ingraph`'s own
// registrations, moved; every other row below is new here. No count, deliberately: `to_filter!`'s
// doc carried one in this position ("the other thirteen") until the list outgrew it in silence.

#[cfg(feature = "smol_str")]
to_filter!(smol_str::SmolStr as string => TextFilter<smol_str::SmolStr>);

// UNGATED, where every other vocabulary row here carries a word: `bytes::Bytes` is the roster's own
// `bytes` row since the default byte household swapped, and a DEFAULT roster row cannot sit behind a
// feature — a build declining the word would have a roster with a hole in it and emitters that
// derive every name from that table.
to_filter!(::bytes::Bytes as bytes => BytesFilter<::bytes::Bytes>);

// `bytes::BytesMut` has NO ROW, and the absence is the 2026-08-19 ruling rather than an oversight: a
// `BytesMut` is what you build a value IN and a column holds the value, and no declaration in this
// workspace names one as a field type. What the row published was a filter no schema could reach.
// The two `smol_bytes` mutable types left on the same argument.

// `smol_bytes` is registered at a CONCRETE strategy alias rather than as one impl over the generic
// core, and that is forced rather than chosen: `RawBytes<S>` and `Utf8Bytes<S>` are `pub(crate)`
// inside `smol_bytes` (`src/bytes.rs`: `pub(crate) use raw::{RawBytes, Repr}`), so a generic impl
// cannot be written at all — naming the type outside the crate is `E0425`.
//
// ONE ALIAS OF THE TWO, and it is the crate's own canonical spelling: `smol_bytes::Bytes` and
// `smol_bytes::Utf8Bytes` are the root re-exports of the `shared::` pair, which `smol-bytes`
// documents as its default strategy. `compact::` has no row — see `carrier`'s byte household, where
// the whole of that ruling is, including what a declaration that wants the compact half does.
//
// These rows carry NO feature, where every other vocabulary here does, and it is the dependency
// rather than the registrations that decides: `smol-bytes` supplies `Backend::Buffer` for the SQL
// dialects, so it is in every build and there is nothing left for a feature to gate. What a row
// costs a build that never names the type is nothing — an `impl ToGraphqlFilter`, which no schema
// walk reaches.
to_filter!(smol_bytes::Bytes as bytes => BytesFilter<smol_bytes::Bytes>);

// The UTF-8 household takes `TextFilter`, not `BytesFilter`. The guarantee is real rather than a
// convenience `AsRef<str>`: `Utf8Bytes` documents "Guarantees valid UTF-8" and reads itself back
// through `str::from_utf8_unchecked`, so the invariant is one the type maintains with `unsafe`
// rather than one a caller can violate. What that buys is the substring / affix family — a
// `starts_with` over characters is a question about a string, and byte comparison is not.
to_filter!(smol_bytes::Utf8Bytes as string => TextFilter<smol_bytes::Utf8Bytes>);

// The temporal vocabulary: seven registrations over jiff's value types and its zone offset. Six are
// an instant, a civil field set or a displacement with a total order, so each takes the ordering
// filter; the seventh is the ELAPSED one and takes the kind written for it. `jiff::Timestamp` is `legacy/ingraph`'s row; the rest are new. `Date` and
// `Time` live in `jiff::civil` and have no root spelling — only `Timestamp`, `Zoned`,
// `SignedDuration` and `Span` are re-exported from the crate root.
#[cfg(feature = "jiff")]
to_filter!(jiff::Timestamp as scalar => ScalarFilter<jiff::Timestamp>);
#[cfg(feature = "jiff")]
to_filter!(jiff::civil::Date as scalar => ScalarFilter<jiff::civil::Date>);
#[cfg(feature = "jiff")]
to_filter!(jiff::civil::Time as scalar => ScalarFilter<jiff::civil::Time>);
// `Zoned` compares by INSTANT, and the zone takes no part in it: `impl PartialEq for Zoned` and
// `impl Ord for Zoned` (jiff `src/zoned.rs`) both delegate to `self.timestamp()`, as does its `Hash`.
// So `eq: "2026-01-01T00:00:00-05:00[America/New_York]"` also matches a row stored as
// `2026-01-01T05:00:00+00:00[UTC]`. That is the answer a `timestamptz` column gives too, and it is
// right — but the bracketed zone in the wire syntax reads like part of the comparand, and it is not.
#[cfg(feature = "jiff")]
to_filter!(jiff::Zoned as scalar => ScalarFilter<jiff::Zoned>);

// The WALL CLOCK and the DISPLACEMENT — the two the temporal vocabulary was missing, and the pair
// EXIF writes a capture time as. Both have a total order and take the ordering filter with the four
// above; what neither has is an async-graphql scalar, so each crosses through a carrier of this
// crate's (`filter::temporal`) rather than facing itself.
//
// `civil::DateTime` is the one type in jiff's civil trio the crate root does not re-export either,
// so it is spelled through the module exactly as `Date` and `Time` are.
#[cfg(feature = "jiff")]
to_filter!(jiff::civil::DateTime as scalar => ScalarFilter<jiff::civil::DateTime>);
// `tz::Offset` is not a jiff VALUE type in the sense the five above are — it is a zone's
// displacement rather than a position — and it takes a row because a stored one is a column a client
// asks about: *everything shot in a zone east of UTC* is `gt: "+00"`, which is an ordering question
// over an integer of seconds.
#[cfg(feature = "jiff")]
to_filter!(jiff::tz::Offset as scalar => ScalarFilter<jiff::tz::Offset>);

// The ELAPSED type, and the one row here that mints a whole filter KIND rather than an
// instantiation of a uniform one — see [`DurationFilter`] for what an independent type buys and why
// `ScalarFilter<SignedDuration>` could not have served. The full arm all the same: a
// `Vec<SignedDuration>` is a list of durations, and nothing here makes it anything else.
#[cfg(feature = "jiff")]
to_filter!(jiff::SignedDuration as duration => DurationFilter);

// `jiff::Span` is the sixth type and has NO row, which is the type's own doing rather than a gap:
// it is `#[derive(Clone, Copy, Default)]` (jiff `src/span.rs`, `pub struct Span`) — no `PartialEq`,
// no `Ord`. jiff withholds both deliberately and ships `SpanFieldwise(pub Span)` beside it for the
// comparison it CAN define, whose own doc sets `120.minutes().fieldwise() != 2.hours().fieldwise()`
// against `120.minutes().compare(2.hours())? == Ordering::Equal`. A span carries calendar units, and
// "1 month" against "30 days" has no answer without a reference date — `Span::compare` errors for a
// non-zero unit bigger than hours unless it is given one.
//
// So the refusal is total: no `ScalarFilter` for want of an order, and not even an `EnumFilter` for
// want of an equality. The operators would all be constructible — the filter structs are bound-free,
// so `ScalarFilter<Span>` is a type that compiles — and every answer they produced would be one of
// jiff's two incompatible readings, chosen by this crate rather than by the caller.
//
// A duration column that wants operators names `jiff::SignedDuration` with `DurationFilter`, which
// is the row directly above and escapes the whole argument: a `SignedDuration` is a signed count of
// seconds and nanoseconds with NO calendar units in it, so there is no "1 month" for a reference
// date to be missing from, and jiff gives it the `Eq` and `Ord` it withholds from `Span`. The other
// spelling is `i64` nanoseconds with `ScalarFilter<i64>`. Both have one meaning.
//
// That is a claim about the TYPE and not about the text a client may write. `DurationFilter`'s
// parser does accept `1month`, through a fallback that resolves it to a fixed average before it ever
// becomes an operand — see `parse_operand`. The value in the slot still carries no calendar unit,
// which is what keeps the order total; what the caller gave up is the exactness, once, at the
// parser, rather than the comparison being ambiguous for ever after.

// `[u8; N]`'s const generic can't pass through `to_filter!`'s `$ty:ty` with `N` free, so its rows
// are written by hand — the same three the macro generates. Its `Option` columns need none: the
// blanket reaches a const-generic type exactly as it reaches every other. `[u8; N]` is the FIXED
// byte KIND (a hash / fixed id): its filter is `FixedBytesFilter` at the array's OWN width, so the
// two substring operators are absent from the type rather than refused at a crossing, and the width
// reaches the wire name through the same one parameter.
impl<const N: usize> BytesFilterMarker for [u8; N] {
  type Filter = FixedBytesFilter<[u8; N], N>;
}

impl<const N: usize> DefaultMarker for [u8; N] {
  type Marker = BytesMarker<[u8; N]>;
}

impl<const N: usize> DefaultVecMarker for [u8; N] {
  type Marker = ListMarker<Vec<[u8; N]>>;
}

// THE SCALAR NAMES ARE NOT HERE ANY MORE, and the table that held them is the reason the CARRIER
// AXIS grew its second and third readings. Every `impl InputType for ScalarFilter<…>` this file
// carried — the twelve plain numerics, the eight `NonZero` widths, the confidence, `Timestamp`, the
// cardinality and jiff's four instants — is a `Builtin` row now, and each row's own naming argument
// went with it. The twelve widths went one step further when the NAMING CONSTITUTION landed: their
// names DERIVE from [`roster`](crate::graphql::roster)'s scalar names rather than being spelled at
// all, and what is left in [`carrier`](crate::graphql::carrier) is the Pascal half — the named
// vocabularies.
//
// What moving them bought is what moving the two text rows bought one kind over: a DECLARING crate
// can reach `ScalarFilter` at all. A concrete registration per operand is a table only this crate
// can extend — `impl InputType for ScalarFilter<Rate>` written downstream is `E0117`, and a generic
// row written here would have overlapped every concrete one (`E0119`) — so a declarer's own
// single-column scalar had to MINT a filter of its own through the element mode. That road is still
// open; it is no longer the only one.
//
// **THE UUID NOTE THAT STOOD HERE IS SPENT**, and what it recorded is worth keeping as a record of
// how a row enters. It read: *`uuid::Uuid` is in `legacy/ingraph`'s lists and in none of ours, and
// it is left there: it is a dependency this crate has not taken, and taking one to render a filter
// for a field type nothing declares would be the reverse of how anything else enters here. `jiff`
// stood beside it until something asked.*
//
// Two things happened to it. The premise went STALE — the id vocabulary took `uuid` as a MANDATORY,
// ungated dependency, so the sentence outlived the fact it rested on and said the crate had not
// taken a dependency it had. And then something asked, exactly as `jiff`'s clause predicted: the
// 2026-08-29 ruling that a uuid is stored in each backend's own native form needed a wire face to go
// with the four column faces, and the row above is it. Its gate is nothing at all, which is where a
// mandatory dependency's rows differ from the vocabulary rows `jiff` moved into.

// THE FOUR CONFIDENCE SCALARS ARE RETIRED, and what stood here was their whole machinery: a
// `read_confidence` shared by three `#[Scalar]` citizenships over `Confidence<f32>`,
// `Confidence<f64>` and `Confidence<half::f16>` — published as `Score`, `ScoreF64` and `ScoreF16` —
// plus a fourth written out for `Confidence<rust_decimal::Decimal>` under `ScoreF128`, whose wire
// form was decimal text rather than a JSON number.
//
// **A NAMED SCALAR HAS TO SAY SOMETHING THE ROSTER DOES NOT, and these four did not.** What each
// carried over its width's own roster row was the INTERVAL — and an interval is a constructor's
// promise rather than a grammar, so the scalar could state it only in prose a client had to read and
// could not enforce anything with. Meanwhile the four names cost a real thing: a `Score` column and
// an `f32` column published two SDL scalars over one wire form, so a schema reader met two words for
// *a single-precision number between nothing and nothing* and had to learn which was which.
//
// A confidence RETURNS under its width's roster name now — `f32`, `f64`, `f16`, `f128` — and the
// interval lives where it was always kept: at `Confidence::new`, which every crossing in either
// direction goes through, stated to a reader in the FIELD's own documentation. The INPUT side went
// the other way and gained a name the roster has not got: `ConfidenceOperand`, the wide door, whose
// two legs are exactly what a threshold needs and whose refusals a client can act on. See
// [`ConfidenceFilter`] and [`ConfidenceWire`](crate::ConfidenceWire).

/// An instant on the UTC timeline as RFC 3339 text — `2026-08-09T21:14:03.123456789Z` — to the
/// NANOSECOND, and never a bare integer.
///
/// An offset is accepted and normalised: `2026-08-09T21:14:03+09:00` is the same instant as
/// `2026-08-09T12:14:03Z` and comes back in the second form. A string with no offset is REFUSED,
/// because a civil datetime is not an instant and the missing fact is not one a server may invent.
///
/// The range is ±9999 years, so a client is not writing against a 2262 ceiling.
// A scalar of this crate's own rather than a bare `Int` of seconds, milliseconds or nanoseconds, and
// the ruling's own sentence for it is what a client can READ: an integer says nothing about its own
// unit, so the two ends agree by convention and disagree by a factor of a thousand in silence. The
// name is SPELLED rather than derived from the Rust one, as `ConfidenceOperand`'s and
// `JiffDuration`'s are: a wire name is a schema commitment and a Rust rename is not a schema change.
#[cfg(feature = "async-graphql")]
#[async_graphql::Scalar(
  name = "Timestamp",
  specified_by_url = "https://datatracker.ietf.org/doc/html/rfc3339"
)]
impl async_graphql::ScalarType for Timestamp {
  fn parse(value: async_graphql::Value) -> async_graphql::InputValueResult<Self> {
    match &value {
      // jiff's own refusal text, not a re-wording of it: it names the component it refused and where
      // in the input, which is the reason `JiffDuration::parse` keeps its error too.
      async_graphql::Value::String(text) => {
        text.parse().map_err(async_graphql::InputValueError::custom)
      }
      _ => Err(async_graphql::InputValueError::expected_type(value)),
    }
  }

  /// The SAME parser `parse` runs, which is what makes a document that validates a document that
  /// parses. async-graphql's default `is_valid` answers `true` for every value, so a scalar that
  /// narrows in `parse` alone ships a validator admitting what its own parser rejects — the reason
  /// [`ConfidenceOperand`]'s two halves read through one pair of constructors, applied here to a
  /// grammar rather than to a range.
  #[inline]
  fn is_valid(value: &async_graphql::Value) -> bool {
    matches!(value, async_graphql::Value::String(text) if text.parse::<Timestamp>().is_ok())
  }

  fn to_value(&self) -> async_graphql::Value {
    async_graphql::Value::String(self.to_string())
  }
}

// The boolean kind's wire face, and the ONE registration this file still writes out: it is not a
// `ScalarFilter`, so it has no reading to be a row of and its four slots are its own. `legacy/ingraph`
// renders `BooleanFilter` from a scalar registration, giving a two-valued column the full eight
// operators; here the input object behind the name has four fields. The narrowing is
// `gt`/`gte`/`lt`/`lte` and is exactly those four — the whole of what the dedicated kind takes off
// the wire.
//
// It stays a `filter_input_object!` spending rather than moving onto a reading, and that is the
// vocabulary being honest rather than an exception: a boolean has no operand form to choose, so a
// `BoolWire` would be a reading with one row in it and nothing for a declarer to say. What that
// macro is FOR is the same thing it now serves downstream — a filter kind whose slots are its own,
// registered by the crate that owns it.
//
// THE NAME IS THE STANDARD ONE AND SO ARE THE OPERANDS, which is the 2026-08-18 amendment at the
// one line that carries it. `bool` is NOT a roster row: the lowercase roster exists to say what
// GraphQL's own vocabulary leaves silent — a width, a byte shape — and `Boolean` is the spec's name
// for exactly this operand, so a lowercase `bool` beside it would be a second spelling of one fact.
// The round that gave the row a lowercase name is retired whole, and the literal is back where it
// started.
//
// It also could not have been more than a name. This is the one kind with no carrier axis — no type
// parameter for an operand form to be selected through — so a lowercase operand means giving the
// KIND one, which is a change to the kind rather than to a name.
//
// The literal is spelled rather than derived for the same reason: the derivation runs through a
// `#[Scalar(name = …)]`, and a kind with no carrier has no such attribute to hold one.
//
// ONE NAME PER OPERAND is what the amendment leaves, and it is why law two's boolean row is this
// one. [`EnumFilter<bool>`](crate::EnumFilter) derives its name from the operand's own schema name,
// and `bool`'s is `Boolean` — so `EnumFilter<bool>` publishes exactly this name over exactly these
// four operators, and the two cannot stand in one schema. They do not have to: a field that wants
// GraphQL's `BooleanFilter` gets it by saying nothing. See [`Std`](crate::Std) for the table of five
// and `tests/half_roster.rs` for the merge asserted.
#[cfg(feature = "async-graphql")]
filter_input_object!(BooleanFilter : "BooleanFilter" {
  bare eq: ::core::option::Option<bool> => "eq",
  ne: ::core::option::Option<bool> => "ne",
  in_: ::core::option::Option<::std::boxed::Box<[bool]>> => "in",
  not_in: ::core::option::Option<::std::boxed::Box<[bool]>> => "notIn",
});

// NO OPERAND TABLE IS LEFT IN THIS FILE, and the two that were are the reason the CARRIER AXIS
// exists. Every one of them lives in [`carrier`](crate::graphql::carrier) now as a `Builtin` row —
// [`TextWire`](crate::TextWire) for the two text operands, [`ScalarWire`](crate::ScalarWire) for the
// twenty-seven ordering ones, [`BytesWire`](crate::BytesWire) for the blob. The names they published
// here survived that move whole; what renamed the roster's share of them, one round later, was the
// NAMING CONSTITUTION and not the axis.
//
// What moving them bought is that a DECLARING crate can reach these kinds at all. A concrete
// registration per operand is a table only this crate can extend: `impl InputType for
// TextFilter<Tag>` written downstream is `E0117`, and a generic row written here would have
// overlapped every concrete one (`E0119`). One generic row over the axis has neither problem.
//
// What is left here is the two `to_filter!` blocks above — the INTERPRETATION each Rust type
// carries, which is a different question from what its operands cross as — and the boolean face,
// the one kind with no reading to be a row of.
//
// THE ABSENCES ARE CLAIMED. Every `to_filter!` row above that reached no schema now has a reading
// in [`carrier`](super::carrier) and a return in [`output`](super::output): `smol_bytes::Utf8Bytes`
// under `TextWire`, and `bytes::Bytes`, `smol_bytes::Bytes`, `Vec<u8>` and `[u8; N]` under
// `BytesWire`. What had stopped every one of them was the operand having no
// `async_graphql::InputType`; a carrier answers that, and each row costs one line.
//
// The name is the OPERAND'S CRATE AND RUST NAME in wire spelling — `SmolBytesFilter`,
// `SmolUtf8BytesFilter` — and the crate is the only prefix any of them carries. The two allocation
// strategies `smol_bytes` spells one type under are NOT two names, because they are not two wire
// forms; the mutable buffers have no name at all, because a buffer is not a column. Both absences
// are the 2026-08-19 ruling and both are written out in [`carrier`](super::carrier), beside the rows
// they removed.