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
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
//! What ONE field contributes to its row's columns: [`ColumnShape`], and the [`Path`] a renderer
//! walks it into.
//!
//! # An entry carries TWO names, and the pair is why a reverse relation can be lowered
//!
//! A column has a name the DECLARATION wrote and a name THIS DATABASE stores it under, and
//! `<db>(rename = "…")` is what makes them two strings. Every entry here is a
//! [`ColumnName`] carrying both, so the list a row publishes is the one place the pairing lives —
//! and since the list is per `SqlQuery<Db>` binding, a record stored in three databases publishes
//! three pairings for one declared field.
//!
//! That is what a REVERSE relation position spends. It is declared at the TARGET, whose expansion
//! cannot see the source's `<db>(rename = …)`, so the stored spelling of the back-reference
//! is asked for rather than rebuilt: [`stored_column`] takes the DECLARED name — the one the reverse
//! declaration wrote — and answers the STORED one, per database.
//!
//! # The list is NESTED because a field's width is its TYPE's answer
//!
//! A row's column list used to be `&[&FieldName]` — one name per field, one field per column — and
//! that shape can only describe a declaration in which no field spans more than one column. A
//! `Timebase` field spans two, and the emitter cannot see that it does: `tb: Timebase` and
//! `title: String` are the same tokens, so a macro asked to flatten one and not the other would be
//! guessing.
//!
//! So the entry is a shape rather than a name, and the shape is answered by the type — see
//! [`ColumnKind`], where a scalar takes the default and says [`Plain`](ColumnShape::Plain) and a
//! composite states its parts and says [`Composite`](ColumnShape::Composite). Nothing in the
//! emitter judges which; it writes one uniform spelling per column and the compiler selects.
//!
//! # The names are JOINED at render time, never in a `const`
//!
//! `tb_num` is not stored anywhere. A renderer walks the tree carrying a [`Path`] of the fields
//! above it, and the join is `push_segments` — the same function a filter's own column rendering
//! already goes through, so a predicate over `tb.num` and a `SELECT` of the same column cannot spell
//! it two ways. Const string concatenation on stable would have needed a second joining rule beside
//! that one, which is the arrangement [`FieldName`] states it does not have.
//!
//! [`FieldName`]: crate::FieldName
use crate::;
/// A column's TWO names: the one its declaration wrote, and the one THIS DATABASE stores it under.
///
/// # It is one value because the two halves are only meaningful together
///
/// `postgres(rename = "reel_fk")` makes one declared field two strings, and which of them a
/// caller wants depends entirely on which side of the boundary it stands on: a RENDERER sends the
/// stored one, since that is the column the engine has, and a DECLARATION — a reverse relation
/// position, a `field = "…"` selector — writes the declared one, since that is the vocabulary its
/// author speaks. Held apart, the two lists are parallel and drift; held together, a lookup by one
/// answers the other and there is nothing to keep in step.
///
/// Which is exactly the fact a reverse relation was missing. The list a row publishes used to carry
/// stored names alone, so `stored_column(…, "reel_id")` answered nothing for a renamed field and the
/// only other publisher of the declared name — a parallel const beside it — carried no database's.
/// The pairing is published here, once, by the row.
///
/// # The DECLARED half is the constant axis
///
/// A field is declared once and stored per database, so the declared half is the same string in
/// every one of a record's `SqlQuery<Db>` bindings and the stored half is the one that moves. That
/// asymmetry is what makes the pair a KEY and a VALUE rather than two coordinates: a lookup is keyed
/// by the half that does not vary.
///
/// # It costs nothing at run time
///
/// Two `&'static FieldName`s, [`Copy`], and every one of them a string literal a declaration wrote —
/// so a row's column list stays an ITEM, which is what
/// [`SqlQuery::COLUMNS`](crate::query::sql::SqlQuery::COLUMNS) being a `const` requires. The
/// un-renamed case holds the same borrow twice rather than an [`Option`], because *no rename* and
/// *renamed to itself* are the same fact and a second state with no second meaning is one a caller
/// can reason wrongly about.
///
/// # Examples
///
/// ```
/// use ingraph::{ColumnName, FieldName};
///
/// const PLAIN: ColumnName = ColumnName::new("title");
/// const RENAMED: ColumnName = ColumnName::renamed("reel_id", "reel_fk");
///
/// const _: () = assert!(PLAIN.declared().is("title") && PLAIN.stored().is("title"));
/// const _: () = assert!(RENAMED.declared().is("reel_id"));
/// const _: () = assert!(RENAMED.stored().is("reel_fk"));
/// # let _: &FieldName = RENAMED.stored();
/// ```
// The READ half, which names a driver row and therefore a dialect family. Gated where the rest of
// this module is not, for the reason the rest is not: a WIDTH names no database, and fetching a
// column by name is `sqlx::Row`'s method.
pub use ;
// The pattern column's own refusal, riding both gates it needs: the read half is `sqlx`'s and the
// value is `regex`'s, so a build with either alone has no such error to name.
pub use PatternColumnError;
// The SAMENESS half, ungated for the reason the width is: whether two stored values are the same
// value names no database and no driver. It is what an emitted row and an emitted page cursor fold,
// in place of the `PartialEq` they used to derive from the declared field types.
pub use ColumnEq;
pub use column_eq;
// The DECLARED half, which is UNGATED where the read half above is not, and the asymmetry is the
// same one the widths themselves have: `Assemble` names `sqlx::Row` and therefore a driver, while a
// WORD names only a dialect — `StoredAs<Db>` puts no bound on `Db` at all, so a backend that is not
// an `sqlx::Database` writes rows through the same door. What IS gated is each dialect's table,
// beside the carrier rows it is the declaration half of.
pub use ;
/// What a field of this TYPE contributes to its row's columns.
///
/// # It is the answer the EMITTER cannot give
///
/// `tb: Timebase` and `title: String` are the same tokens, so a macro asked which of them spans two
/// columns would be guessing. It writes one uniform spelling per column — [`shape`] applied to the
/// field's own type — and the compiler selects: a scalar's row leaves [`SEGMENTS`](Self::SEGMENTS)
/// at its default and answers [`Plain`](ColumnShape::Plain), a composite states its parts and
/// answers [`Composite`](ColumnShape::Composite). There is no case to get wrong.
///
/// # It names NO DATABASE, and that is a measurement rather than a simplification
///
/// The first shape carried the dialect — `ColumnKind<Db>`, with the scalar side a BLANKET over
/// [`Carrier<Db>`](crate::Carrier), which is the ruled shape and is the one every scalar would have
/// joined for free. It does not survive contact with the emitted impls, and the reason is worth
/// keeping: a row's query binding is generic over its dialect, so its `where` clause carries
/// `i64: ColumnKind<DB>` — and with a blanket in scope that predicate is proved through the BLANKET
/// rather than through the clause, so the impl demands `i64: Carrier<DB>` for a `DB` no caller has
/// fixed yet. Measured on `ingraph-derive`'s own corpus: ten `E0277`s naming `Carrier` at fields
/// whose carrier rows all exist, with the where clause stating the bound two lines above.
///
/// Without the parameter the predicate is `i64: ColumnKind`, which is satisfied by a row this crate
/// ships and needs no dialect fixed to prove. What the parameter would have bought — a layout that
/// differs per database — nothing asks for: a composite's parts are its parts in every dialect, and
/// the per-database decision that DOES exist is the `flatten` naming knob, which rides the holder's
/// declaration rather than the type's answer.
///
/// So the two halves of a column sit on two traits: this says HOW MANY COLUMNS a field is, and
/// [`Carrier<Db>`](crate::Carrier) says how its value binds in one dialect. A composite implements
/// both — one width, one bind per dialect — and the pair is what a row's `INSERT` reads at each end.
///
/// # A scalar joins by stating NOTHING
///
/// The default is the scalar answer, so a downstream type that already has a carrier row adds
/// `impl ColumnKind for MyScalar {}` and is done. Every storage type this crate ships has its row
/// below.
/// **The VALUES this type's order levels compare** — the per-leaf vocabulary a citizen publishes
/// beside [`ORDER`](ColumnKind::ORDER), and the third of the three facts a composite states about
/// itself.
///
/// | fact | what it answers |
/// |---|---|
/// | [`SEGMENTS`](ColumnKind::SEGMENTS) | which COLUMNS this type is |
/// | [`ORDER`](ColumnKind::ORDER) | which SEQUENCE those columns mean |
/// | [`Leaf`](Self::Leaf) here | which VALUE one of them compares |
///
/// # It is citizenship machinery and NOT a bind face
///
/// Nothing here binds anything. A leaf is handed back as a VALUE, and what binds it is that value's
/// own [`Carrier`](crate::Carrier) row — `i64` binds as `i64` always has, through the scalar impl it
/// already had. That is the whole point of publishing values rather than pushes: the bind seam stays
/// the two faces [`Carrier`](crate::Carrier) has, and a level's operand is an ordinary scalar
/// operand reached one hop earlier.
///
/// # The numbering is the LEAF numbering
///
/// `at` indexes the leaves [`width`] counts — not the entries [`SEGMENTS`](ColumnKind::SEGMENTS)
/// lists, and not the LEVEL sequence [`ORDER`](ColumnKind::ORDER) is written in. A term's level
/// holds the leaf ordinal its [`OrderLevel`](crate::OrderLevel) named, so the permutation is spent
/// before this is asked and one numbering reaches every reader.
///
/// # A DERIVED leaf is RECOMPUTED here, exactly as the write recomputes it
///
/// [`MediaTimestamp`](crate::MediaTimestamp)'s `nanos` is a function of its value leaves and is
/// carried by nothing — not by the decode, not by the cursor's own
/// [`CursorValue`](crate::CursorValue) row. A cursor level over it recomputes it through the same
/// `to_nanos` the write binds, and answers [`None`] on the same overflow the write writes `NULL`
/// for. That is what keeps the boundary a page resumes at the value the statement sorted by rather
/// than a second reading free to differ.
///
/// # What a NON-reordering composite writes: ONE WORD
///
/// [`DeclaredLeaves`], which is the whole statement — *my columns mean the sequence they are
/// declared in, so one level of me is me*:
///
/// ```
/// use ingraph::{ColumnKind, ColumnName, ColumnShape, DeclaredLeaves, OrderLeaves};
///
/// #[derive(Clone, Copy)]
/// struct Ratio {
/// num: i32,
/// den: i32,
/// }
///
/// impl ColumnKind for Ratio {
/// const SEGMENTS: &'static [ColumnShape] = &[
/// ColumnShape::Plain(ColumnName::new("num")),
/// ColumnShape::Plain(ColumnName::new("den")),
/// ];
/// }
///
/// impl DeclaredLeaves for Ratio {}
///
/// // …and the vocabulary follows, through the blanket that word is the key to.
/// assert!(OrderLeaves::leaf(&Ratio { num: 1, den: 2 }, 0).is_some());
/// ```
///
/// The two words are EXCLUSIVE by construction: a type that writes [`DeclaredLeaves`] reaches this
/// trait through the blanket below, so writing both is `E0119` in the declaring crate. That is the
/// pairing law said at the type level — the half of it a compiler CAN carry.
/// **MY COLUMNS MEAN THE SEQUENCE THEY ARE DECLARED IN** — the ONE WORD a composite that states no
/// [`ORDER`](ColumnKind::ORDER) writes, and the key to the [`OrderLeaves`] row below it.
///
/// # It is a WORD rather than four lines, and the reason is where the `Clone` lands
///
/// The row it stands for is the same sentence for every type that writes it, so writing it out per
/// type would be N copies of one impl — and, worse, each copy would demand [`Clone`] AT THE
/// DECLARATION. Rust checks a concrete impl's `where` clause eagerly, so an
/// `impl OrderLeaves for MyFragment` bounded on `Self: Clone` is `E0277` at the fragment even when
/// nothing ever pages over one. A cursor OWNS its boundary, so the clone itself is real; what is not
/// real is paying for it at a declaration that could never be a boundary.
///
/// The blanket moves the bound to the USE. A type says this word with no bounds at all, and
/// [`Clone`] is asked for exactly where it always was — the first page whose cursor holds one of
/// these — which keeps a fragment that is never a paged column as free as it was.
///
/// # It is the OTHER half of a citizen's choice, and the compiler holds the two apart
///
/// A composite states its order in one of two ways and never both: it declares an
/// [`ORDER`](ColumnKind::ORDER) and publishes an [`OrderLeaves`] vocabulary for the levels that
/// sequence names, or it writes this word and keeps the wide term it always had. Writing both is
/// `E0119` — a hand-written row and the blanket overlap — so the pairing the `ORDER` const's note
/// states in prose is, at this end, a thing the compiler refuses.
///
/// # A downstream joins by writing it, and that is the whole seam
///
/// `impl ingraph::DeclaredLeaves for MyComposite {}`, beside the [`ColumnKind`] it already writes.
/// No registry, no framework table, no second place to remember — the shape
/// [`CollectionElement`](crate::CollectionElement) takes one axis over.
/// The row that word is the key to — *one leaf, and it is the value*.
///
/// [`ColumnKind`] and [`Clone`] are named HERE rather than as supertraits of [`DeclaredLeaves`], and
/// for one reason: a supertrait is checked where the word is written, which is the eager cost the
/// word exists to avoid.
/// The shape a field named `field` and typed `T` contributes — the ONE spelling an emission writes
/// per column.
///
/// `const`, so a row's whole column list stays an ITEM:
/// [`SqlQuery::COLUMNS`](crate::query::sql::SqlQuery::COLUMNS) is a `const` and every entry of it is
/// one of these.
///
/// # A free function rather than a method on [`ColumnKind`]
///
/// The ruled spelling was `<T as ColumnKind>::shape(…)`, which stable Rust cannot evaluate in a
/// `const`: a trait METHOD is not callable there without `const_trait_impl`. An associated CONST is,
/// so the type answers with data and the assembly is this function. Which answer a type gives did
/// not move — the `const` is the type's, and this reads it.
///
/// # Examples
///
/// ```
/// use ingraph::{ColumnKind, ColumnName, ColumnShape, FieldName, shape};
///
/// struct Timebase;
/// impl ColumnKind for Timebase {
/// const SEGMENTS: &'static [ColumnShape] = &[
/// ColumnShape::Plain(ColumnName::new("num")),
/// ColumnShape::Plain(ColumnName::new("den")),
/// ];
/// }
///
/// const TITLE: ColumnShape = shape::<String>(ColumnName::new("title"));
/// const RATE: ColumnShape = shape::<Timebase>(ColumnName::new("tb"));
///
/// const _: () = assert!(TITLE.width() == 1);
/// const _: () = assert!(RATE.width() == 2);
/// ```
pub const Sized>
/// The same field with its NAME dropped — `<db>(flatten)`, which lays a composite's columns
/// out in the holder's own namespace: `num`/`den` where [`shape`] gives `tb_num`/`tb_den`.
///
/// # A SCALAR is refused here, and the segment count is the refusal
///
/// A scalar contributes no segments, so a flattened one would contribute no COLUMNS at all and the
/// field would vanish from the row. That is the fact
/// [`CompositeComparison`](crate::CompositeComparison)'s `E0277` states at the filter, said again
/// where the columns are counted: here it is `E0080` at the row's `COLUMNS`, which is where a
/// declaration that reached this function without a composite can be read.
///
/// ```compile_fail,E0080
/// use ingraph::{ColumnShape, flattened};
///
/// const NOTHING: ColumnShape = flattened::<i64>();
/// ```
pub const Sized>
/// A column the WRITE computes — `record(derived(column = "…", from = "…", type = "…"))`, the
/// mirror image of `record(skip)`.
///
/// `skip` is declared-but-not-stored and the raise fills it; a derived column is
/// stored-but-not-declared and the write computes it. So this reads exactly as [`shape`] does — the
/// entry a field of type `T` contributes, under the name the declaration gave it — and everything
/// about it that differs is on the other two faces: the bind pushes `from(&value)` where a declared
/// field pushes the field, and the read fetches nothing at all, the value being rebuilt from the
/// sources the function read.
///
/// # The function is a PARAMETER so that the two spellings cannot drift
///
/// `T` is the function's return type and the declaration also writes it, because a `where` clause,
/// a filter slot and a comparison member all need the type as TOKENS and stable Rust has no way to
/// name a function's return. Passing the function HERE is what holds the two together: the argument
/// is typed `fn(&S) -> T` with `T` fixed by the caller, so a `from` returning anything else is
/// `E0308` at the path that named it, in a `const` no feature gates away.
///
/// # Examples
///
/// ```
/// use ingraph::{ColumnName, ColumnShape, derived};
///
/// struct Span { pts: i64, hz: i64 }
/// impl Span {
/// fn nanos(&self) -> i64 { self.pts * 1_000_000_000 / self.hz }
/// }
///
/// const NANOS: ColumnShape = derived::<Span, i64>(Span::nanos, ColumnName::new("nanos"));
/// const _: () = assert!(NANOS.width() == 1);
/// ```
pub const Sized, T: ColumnKind>
/// Every ONE-COLUMN storage type this crate ships, each answering the SCALAR shape.
///
/// The qualifier is not decoration: [`Timestamp`](crate::Timestamp) is shipped, is storable, and is
/// NOT here — a composite states its parts, so its row is written out below rather than added to a
/// list whose whole body is the empty default.
///
/// One row per type rather than per (type × dialect): a width is not a dialect's fact, so the list
/// is the union of [`Carrier`](crate::Carrier)'s three tables with the duplicates collapsed. The
/// core of it is UNGATED for the reason the storage forms themselves are — a big-endian encoding
/// names no database — and a type that exists only under a feature keeps that feature's gate here,
/// since a row for a name the build has not got is not a row it could write.
scalar_columns!
// Every ONE-COLUMN storage type this crate ships, each the same as another when `==` says so.
//
// The list is `scalar_columns!`'s, and it is written out beside it rather than folded into it for
// the reason `scalar_elements!`'s is: that macro states a WIDTH and this states a SAMENESS, and the
// day a shipped type has a width whose sameness is not `==` the two lists have to be able to differ.
// `regex::Regex` is already such a type — its row is written out below, as an impl of its own — so
// the two lists differ TODAY rather than one day.
column_eq!
// THE COMPILED PATTERN, one column wide, and the width is the PATTERN's rather than the automaton's.
// What a row holds is the text `Regex::new` was handed; the state machine behind it is a build
// product of that text and is rebuilt on the way back (see `column::assemble`), so there is nothing
// of it for a second column to carry. One column, `TEXT` on every dialect, the road
// `smol_bytes::Utf8Bytes` takes one list up.
scalar_columns!
/// **THE PATTERN'S IDENTITY IS ITS TEXT**, and this row is where that law is spent rather than
/// merely stated.
///
/// A pattern column stores [`Regex::as_str`](regex::Regex::as_str)'s text and reads it back through
/// [`Regex::new`](regex::Regex::new) (see [`assemble`](super::column::assemble)), so the text is the
/// whole of what a store holds. Sameness is therefore the same text, byte for byte: two patterns are
/// one column value exactly when one was written from the other's characters.
///
/// # It CANONICALISES NOTHING, and that is the law rather than a shortfall
///
/// `(?i)a` and `[aA]` accept the same strings and are two values, two rows and two answers here — as
/// `a{2}` and `aa` are. A uuid folds four spellings into one and an IPv6 address folds many into RFC
/// 5952; a pattern has no such normal form, and inventing one would make a column claim an
/// equivalence the engine that matches with it does not have.
///
/// # A `RegexBuilder` FLAG IS OUTSIDE THE IDENTITY, which is the one thing a reader must know
///
/// [`RegexBuilder`](regex::RegexBuilder) sets case-insensitivity, multi-line, `dot_matches_new_line`
/// and the size limits OUTSIDE the pattern text, and `as_str` reports the text alone. So two
/// patterns built from one string with different builder flags are the SAME column value here, match
/// differently at runtime, and round-trip through a store as the flagless one — because the store
/// never held the flags. **A declaration that needs a flag to survive storage writes it INTO the
/// pattern** (`(?i)` and its siblings are inline and are part of `as_str`), which is the spelling
/// that is stored, compared, published and paged as one thing.
///
/// The same text is the same value on every face: the SQL bind, the BSON document, the wire scalar
/// and the page cursor all carry `as_str`, so this row is not a second opinion about a pattern but
/// the one opinion read at the row.
///
/// # Examples
///
/// One text, one value — and a pattern that came back out of a store is the one that went in:
///
/// ```
/// use ingraph::ColumnEq;
///
/// let written = regex::Regex::new(r"^\d{4}-\d{2}$").expect("a pattern");
/// let read_back = regex::Regex::new(written.as_str()).expect("the stored text still compiles");
/// assert!(written.column_eq(&read_back));
/// ```
///
/// Two patterns that accept the same strings are two values, because a pattern canonicalises
/// nothing:
///
/// ```
/// use ingraph::ColumnEq;
///
/// let inline = regex::Regex::new("(?i)a").expect("a pattern");
/// let spelled = regex::Regex::new("[aA]").expect("a pattern");
/// assert!(!inline.column_eq(&spelled));
/// ```
///
/// A `RegexBuilder` flag is outside the identity, so two patterns built from one text are one value
/// here however they were built — and the store holds the text alone:
///
/// ```
/// use ingraph::ColumnEq;
///
/// let plain = regex::Regex::new("a").expect("a pattern");
/// let folded = regex::RegexBuilder::new("a")
/// .case_insensitive(true)
/// .build()
/// .expect("a pattern");
///
/// assert_eq!(plain.as_str(), folded.as_str());
/// assert!(plain.column_eq(&folded));
/// // They do NOT match the same strings — which is why a flag that must survive storage is
/// // written INTO the pattern, where `as_str` reports it.
/// assert!(!plain.is_match("A"));
/// assert!(folded.is_match("A"));
/// ```
// `time`'s three, which are what jiff's instants reach a column THROUGH — so a declaration naming
// one directly and one through `Temporal` both find a width here.
scalar_columns!
column_eq!
// The two checked duration newtypes and the interval a declared converter can still reach. Each is a
// `type = "…"` a declaration may spell, so each needs the row its carrier row implies — and each
// carries the gates that carrier row carries, for that row's reasons.
scalar_columns!
scalar_columns!
scalar_columns!
// The sameness rows for the three above, each on its type's own `PartialEq` and each under the gates
// its width row carries.
column_eq!
column_eq!
column_eq!
// THE SIX ADDRESSES, whose rows are the CURSOR table's rather than the width table's — a network
// address reaches a column as the inner of a `#[derive(ingraph::Id)]` wrapper, whose emitted
// sameness delegates to it, so the obligation lands here even though nothing declares an address
// field directly. Two addresses are one value when they are equal, which for `Ipv6Addr` is a
// comparison of the sixteen bytes and NOT of the two texts: `::1` and `0:0:0:0:0:0:0:1` are one
// address and one stored value, which is exactly the canonicalisation a pattern has none of.
column_eq!
// The house's other text carrier, on `String`'s own terms and under its own word.
column_eq!
// The DOCUMENT tier's two id forms, whose rows are the cursor table's for the addresses' reason.
column_eq!
/// **The framework's own instant is TWO columns, and it is the first shipped type that is.**
///
/// It is stated here rather than listed in [`scalar_columns`](self) above, and the list is the
/// reason: every entry there takes the default and says `Plain`, so a composite added to it would
/// be a row whose body contradicts the macro's own sentence. A composite states its parts, and this
/// is what stating them looks like for a type this crate owns.
///
/// The parts are read from [`Timestamp`](crate::Timestamp)'s own module rather than spelled here,
/// which is the arrangement a DECLARED composite already has — one `const` its predicate, its
/// binds, its reads and its sub-document keys all share. A rename there moves `SELECT "at_secs"`,
/// `WHERE "at_secs" = ?` and the `secs` key of a MongoDB sub-document together, and there is no
/// second list to drift from.
/// **One leaf, and it is the value.** The framework's instant means its two columns in the
/// sequence it writes them, so a term over one stays the wide term it always was.
// Two instants are one column value when both their parts are — which is what the type's own
// `PartialEq` already says, its two columns being its two fields.
column_eq!
/// A borrowed value is as wide as what it borrows, which is what makes the borrowed operand family
/// spellable here at all — the same delegation [`Carrier`](crate::Carrier) makes one layer down.
/// An OPTIONAL field is as wide as its value: nullability decides what a column may HOLD and not how
/// many columns there are. Without this row a nullable composite would be narrower than the same
/// type unwrapped, which no dialect means by `NULL`.
/// The typed id is its id's width — one column, whatever entity it addresses — for the reason its
/// carrier row gives: the marker reaches no column.
/// A typed id is the same as a typed id when the ID is — the marker reaches no column, so it reaches
/// no comparison either. The bound is the id's alone, exactly as the width row's is.
/// A COLLECTION riding a column of the row — a Postgres array, or the `BLOB`/`BYTEA` a `Vec<u8>`
/// binds as — is that ONE column. Where the dialect has no array the elements are an EDGE TABLE and
/// the field appears in no column list at all, so this row is never consulted there.
///
/// One impl over every element rather than a row per element type, which is also what keeps
/// `Vec<u8>` from needing a second one: its width is a vector's, whatever it holds.
/// The temporal wrapper is its inner type's width, delegating exactly as its carrier row does.
/// The temporal wrapper is its inner type's sameness, delegating exactly as its width row does.
/// **A CONFIDENCE IS AS WIDE AS THE WIDTH IT MEASURES IN**, delegating like the three wrappers above
/// it — and here the delegation carries the ADMISSION as well as the width.
///
/// The bound is the membership rule spelled as a bound: `Confidence<S>` is a column exactly where `S`
/// is one. Today that is `f32` and `f64` and not `half::f16` or `rust_decimal::Decimal`, because
/// neither of those widths is a `ColumnKind` — they reach a schema and stop — and the day one is
/// admitted its confidence is admitted with it, without a list here to remember.
///
/// A row apiece would have said the same thing and cost the two goldens that render this trait's
/// implementer list: rustc prints the first eight and a per-width row makes that block's content
/// depend on the vocabulary a build takes. One generic row prints as `Confidence<S>`, which is the
/// same line in every build. See `graphql::carrier`'s confidence row for the measurement.
/// A confidence is the same as a confidence when the WIDTH it is measured in says so — one generic
/// row over the width, for the same reason the width row above is one: a row per carrier would make
/// this trait's rendered implementer list depend on the vocabulary a build takes.
/// A type that may be ONE ELEMENT of a collection.
///
/// # It is what [`ColumnKind`] cannot say, and the gap is exactly one fact
///
/// A width is answered by the type, so an element's COLUMNS are already
/// [`SEGMENTS`](ColumnKind::SEGMENTS) and nothing here restates them: a scalar element is one column
/// and a composite one is its parts, which is the answer an edge table's `CREATE TABLE`, its
/// `INSERT` and its correlated predicate all read. What a width does NOT distinguish is a
/// COLLECTION — `Vec<T>`'s row above says one column, deliberately, because a collection riding a
/// Postgres array or a `BLOB` is one — so a shape alone cannot tell `Vec<String>` from `String`, and
/// an edge table whose element is itself a collection has no rows to be.
///
/// This is that fact, and absence is the whole of it: **no collection type has a row here**, so a
/// collection of collections is `E0277` naming the inner one. It is the standing
/// [`Describe`](crate::Describe) takes one family over — *absence IS the refusal* — and the standing
/// [`CompositeComparison`](crate::CompositeComparison) takes one type over, where a scalar refuses
/// `flatten` by not implementing it.
///
/// # A COMPOSITE element is admitted BY ITS OWN DECLARATION, which is the only party that knows
///
/// A record declaring `Vec<Timebase>` sees two token trees and cannot tell whether `Timebase`
/// carries a collection field; the declaration of `Timebase` can, and it is the party that writes
/// this row. So the refusal ruled for a collection-bearing composite element lands where the
/// information is, and it lands as a missing impl rather than as a rule someone follows — a
/// composite whose own field is a collection simply has no row, and every `Vec` of it is refused at
/// the declaration that spells one.
///
/// # A composite whose own PART is composite is admitted, and the columns are its LEAVES
///
/// The nesting is a naming question rather than an admission one, and the direct table answered it
/// first: `heard: DetectedLanguage` is FIVE columns of the row — the identity's four, flattened, then
/// the confidence — because a part that lends no name splices its own into the holder's namespace. An
/// edge table holding the same element writes the same five, so the element's parts may nest as deep
/// as a declaration nests them and the refusal that used to live here — *only scalar segments may
/// enter a collection element* — has no fact left to state.
///
/// What a nested part still may not do is reach NO column, which
/// [`SqlCompositeEdgeComparison`](crate::comparison::sql::SqlCompositeEdgeComparison) refuses in a
/// `const` where the widths are read.
///
/// # An OPTIONAL element has no row either, and the DDL already says why
///
/// An edge row exists because an element does, so there is no state for a `NULL` to stand for:
/// `Vec<Option<T>>` spells two observables — an absent element and a present one holding nothing —
/// for a table that can hold one. An optional SEGMENT of a composite element is a different
/// question, answered by that element's own descriptor, and for a SET it is
/// [`EdgeTable::composite`](crate::EdgeTable::composite)'s own refusal.
///
/// # Examples
///
/// A downstream composite joins by stating the row, once:
///
/// ```
/// use ingraph::{CollectionElement, ColumnKind, ColumnName, ColumnShape, FieldName};
///
/// struct Timebase;
/// impl ColumnKind for Timebase {
/// const SEGMENTS: &'static [ColumnShape] = &[
/// ColumnShape::Plain(ColumnName::new("num")),
/// ColumnShape::Plain(ColumnName::new("den")),
/// ];
/// }
/// impl CollectionElement for Timebase {}
///
/// const fn stored_as_elements<E: CollectionElement>() -> usize {
/// ingraph::width(E::SEGMENTS)
/// }
///
/// const _: () = assert!(stored_as_elements::<Timebase>() == 2);
/// const _: () = assert!(stored_as_elements::<String>() == 0);
/// ```
///
/// A collection has none, and that is the collection-of-collections refusal:
///
/// ```compile_fail,E0277
/// use ingraph::CollectionElement;
///
/// const fn admitted<E: CollectionElement>() {}
///
/// const _: () = admitted::<Vec<String>>();
/// ```
/// Every ONE-COLUMN storage type this crate ships, each admitted as an element.
///
/// The list is [`scalar_columns`](self)'s, and it is written out beside it rather than folded into
/// it: that macro states a WIDTH and this states an ADMISSION, and the day a shipped type has a
/// width and no admission — a collection form, if this crate ever ships one — the two lists have to
/// be able to differ. `Vec<T>` is already such a type.
scalar_elements!
scalar_elements!
scalar_elements!
scalar_elements!
scalar_elements!
/// A confidence is an element exactly where the width it measures in is one — its
/// [`ColumnKind`] row's bound, one trait up, and the same reason for writing it once.
/// **The framework's own instant is the first COMPOSITE element**, and it carries no collection —
/// its two segments are a whole-seconds integer and a nanosecond one.
///
/// It is the row every composite-element form in this crate is measured against, which is what makes
/// it worth stating here rather than only in the corpus: a `Vec<Timestamp>` reaches an edge table of
/// `(key…, ordinal, at_secs, at_nanos)`, and each of the DDL, the write and the correlated predicate
/// reads those two names off [`ColumnKind`]'s row above.
/// A borrowed element is admitted exactly as what it borrows is — the delegation
/// [`ColumnKind`] and [`Carrier`](crate::Carrier) both make, and what keeps the borrowed operand
/// family spellable.
/// The typed id is admitted as its id is: the marker reaches no column, so it reaches no element
/// either.
/// The temporal wrapper is admitted as its inner type is, delegating exactly as its width does.
/// What one FIELD of a row contributes to its table's columns.
///
/// # A segment is a `ColumnShape` too, and that is the nesting
///
/// [`Composite::segments`](Self::Composite::segments) holds these rather than a flat list of words,
/// so a composite whose own part is composite describes itself without anything having to
/// concatenate: `tb: Timebase` holding `rate: Ratio` is a `Composite` whose segment is a
/// `Composite`, and the renderer's walk produces `tb_rate_num` by descending twice.
///
/// This is the question [`CompositeComparison`](crate::CompositeComparison) left open — *whether a
/// nested composite's segments are its children's concatenated or one level deep* — answered by its
/// first consumer, as that note asked. **One level deep, and the walk descends.** Concatenation
/// would have had to happen in a `const`, where this crate has no joining rule, and it would have
/// put the rendered name in two places.
///
/// # `Copy`, and no owned form
///
/// Every part is `&'static`, so a shape is an ITEM rather than an allocation — the same arrangement
/// [`RecordAddress`](crate::RecordAddress) has, and for the same reason: a row's column list is
/// declared with the schema, once, and nothing builds one per query.
///
/// # THREE KINDS OF LEAF, and the FIRST cut is what a row's VALUE is
///
/// [`Plain`](Self::Plain) is a column the field's value HOLDS. The other two are columns it does
/// not: an INDEX the write computes beside the value, whose whole reason for existing is that the
/// value cannot answer the question it answers. `MediaTimestamp` is the shipped case — `pts` and the
/// timebase are the value, `nanos` is the position on a timeline, and two instants in different
/// timebases are orderable only through the second.
///
/// The SECOND cut is between the two derived words, and it is about the leaf's own arithmetic:
/// [`Nullable`](Self::Nullable) is a computation that can DECLINE — `nanos` past the ±292-year
/// ceiling — and [`Derived`](Self::Derived) is one that cannot — `BoundingBox`'s `area`, which is
/// `width × height` and always there. That cut has exactly one reader, the DDL, and exactly one
/// consequence: `NOT NULL`. Every STRUCTURAL reader below is on the first cut and cannot see the
/// second.
///
/// | | part of the VALUE | may hold `NULL` on its own |
/// |---|---|---|
/// | [`Plain`](Self::Plain) | yes | no |
/// | [`Nullable`](Self::Nullable) | no | yes |
/// | [`Derived`](Self::Derived) | no | no |
///
/// # THE LAW, and the roster that executes it
///
/// **A DERIVED LEAF SERVES THE SEMANTIC ORDER ONLY. Every STRUCTURAL judgment — pagination cursors,
/// row-value equality, tie-breaks, presence — walks VALUE LEAVES ONLY.** Ruled 2026-08-29, and it is
/// one sentence because the readers below each derived their own version of it and two of them got
/// it wrong in the same shape: an index leaf whose `NULL` says *this value has no representable
/// position* was read as *this value is not here*.
///
/// Splitting VALUE from INDEX is one bit — [`holds_value`](Self::holds_value) — and every reader in
/// the crate that has to tell them apart reads THAT bit rather than a rule of its own. The DDL is
/// the one reader that also asks the second question, which is
/// [`self_nullable`](Self::self_nullable)'s:
///
/// | reader | what it reads |
/// |---|---|
/// | the DDL | `self_nullable` — the leaf's own `NULL`, joined to whatever its field is declared |
/// | an optional composite's READ | `None` is *every VALUE leaf `NULL`* — an index leaf is not consulted |
/// | the presence FILTER | `isNull` renders over the value leaves, for the read's reason |
/// | the keyset's NULL TEST | *is this term's value present at this row* is the same question again |
/// | row-value equality and membership | the VALUE tuple; an index leaf would poison it with `NULL` |
/// | the ORDER | the one reader on the other side of the law — see below |
///
/// The structural readers agree BECAUSE they read one bit. A derived leaf that was nullable in the
/// DDL and counted by the `None` test would read a stored instant back as absent, which is the exact
/// misreading the pairing prevents; the same misreading reached pagination as ingraph #454 and
/// element equality as ingraph #455, and both are repaired by pointing them at [`value_width`] and
/// [`holds_value`](Self::holds_value) rather than at the width.
///
/// Note which bit is NOT in that column: nullability. A structural reader that branched on
/// [`self_nullable`](Self::self_nullable) would count [`Derived`](Self::Derived) as part of the
/// value, and that is the shape of the third variant's own hazard — every arm below chooses on
/// `holds_value` unless it is the DDL.
///
/// # The ORDER is the law's OTHER half, and it is EXECUTED
///
/// The semantic clause is true of the ordering itself. A type that means its columns in a sequence
/// other than the one it declares them in says so at [`ColumnKind::ORDER`], and a term over it
/// EXPANDS — [`OrderTerm::levels`] — into one ordinary term per level, each naming one leaf. So
/// `MediaTimestamp` sorts by its derived `at_nanos` first, which is the one unit every stored row
/// shares, and the value leaves follow as the tie-break.
///
/// The four things that had to move together did, because after the expansion they are one thing:
/// the sequence is the level list, the operand is a level's own scalar bind, the `NULL` position is
/// stated per level, and the arm a boundary cut at a beyond-ceiling row needs is the general keyset
/// form's own third row rather than a case anybody writes. See [`OrderTerm::levels`] and ingraph
/// #467, which carries the design.
///
/// The two halves DO NOT collide, and the expansion is why: a level's null test is about that
/// level's own column, so the derived leaf is asked about where it is the subject and never as a
/// proxy for whether a value is there. A row past the ceiling sits in the nanos level's `NULL` group
/// and is separated from a row holding no instant by the level below it.
///
/// [`ColumnKind::ORDER`]: ColumnKind::ORDER
/// [`OrderTerm::levels`]: crate::OrderTerm::levels
/// How many of the columns `shapes` names are part of the VALUE — [`width`] counting only the leaves
/// [`ColumnShape::holds_value`] admits.
///
/// It is what an optional composite's `None` test is measured against, and it is deliberately NOT
/// the width: `MediaTimestamp` is four columns and three of them are the value, so a read that
/// counted four would ask a derived column whether an instant is present and get `NULL` from a row
/// that holds one.
///
/// # Examples
///
/// A citizen shaped as the shipped instants are — a count, the unit it is counted in, and the
/// derived position beside them:
///
/// ```
/// use ingraph::{ColumnName, ColumnShape, value_width, width};
///
/// const SEGMENTS: &[ColumnShape] = &[
/// ColumnShape::Plain(ColumnName::new("pts")),
/// ColumnShape::Composite {
/// field: Some(ColumnName::new("timebase")),
/// segments: &[
/// ColumnShape::Plain(ColumnName::new("num")),
/// ColumnShape::Plain(ColumnName::new("den")),
/// ],
/// },
/// ColumnShape::Nullable(ColumnName::new("nanos")),
/// ];
///
/// // Four columns are written and read; THREE of them are the value.
/// const _: () = assert!(width(SEGMENTS) == 4);
/// const _: () = assert!(value_width(SEGMENTS) == 3);
/// ```
pub const
/// How many columns `shapes` names in total — [`ColumnShape::width`] over a whole list.
///
/// It is what a descriptor's own column count is held against, and what a caller sizing a statement
/// spends; the list's `len` is the number of FIELDS, which for a row with a composite is fewer.
pub const
/// The `leaf`-th LEAF of `shapes`, or [`None`] where the tree has none at that index.
///
/// The same descent [`width`] counts, stopped at one index — a nested composite contributes its own
/// leaves, so this addresses a leaf rather than a part. It answers the ONE question an expanded
/// order level has to ask of the tree it came from: whether that column can hold `NULL`, which
/// decides the level's own null arms.
///
/// `const`, because a term's levels are minted from a `const` segment list and a level's nullability
/// has to be readable there.
///
/// # Examples
///
/// ```
/// use ingraph::{ColumnName, ColumnShape, leaf_shape};
///
/// const SEGMENTS: &[ColumnShape] = &[
/// ColumnShape::Plain(ColumnName::new("pts")),
/// ColumnShape::Composite {
/// field: Some(ColumnName::new("timebase")),
/// segments: &[
/// ColumnShape::Plain(ColumnName::new("num")),
/// ColumnShape::Plain(ColumnName::new("den")),
/// ],
/// },
/// ColumnShape::Nullable(ColumnName::new("nanos")),
/// ];
///
/// // Three segments, FOUR leaves — and the derived one is the last of them.
/// assert!(matches!(leaf_shape(SEGMENTS, 1), Some(ColumnShape::Plain(_))));
/// assert!(matches!(leaf_shape(SEGMENTS, 3), Some(ColumnShape::Nullable(_))));
/// assert!(leaf_shape(SEGMENTS, 4).is_none());
/// ```
pub const
/// [`leaf_shape`]'s recursion, threading how many leaves have been passed.
///
/// The counter travels as a value rather than as an index into a flat list, because there is no flat
/// list: the shapes are a TREE and a nested composite's leaves are counted where they are met. It is
/// [`push_leaf_column`](crate::comparison::sql::push_row_value)'s fold written for a `const` — the
/// same walk, without a buffer to write into.
const
/// The ONE column of `columns` named `field` — the name THIS DATABASE stores it under, read off a
/// row's own published shapes.
///
/// # What it is FOR: the reverse relation position's back-reference
///
/// [`SqlDerivedComparison::new`](crate::comparison::sql::SqlDerivedComparison::new) takes the
/// source's `ref` column as a `&'static FieldName` **in the name this database stores it under**, and
/// a reverse position is declared at the TARGET, whose expansion cannot see the source's
/// `<db>(rename = "…")`. That name is not rebuilt here and never could be — it is ASKED FOR,
/// through the chain the pairing already publishes:
///
/// ```text
/// <<Source as Record<Db>>::Row as SqlQuery<Db>>::COLUMNS
/// ```
///
/// which is per DATABASE, so a source stored in three answers three names for one field. This
/// function is the lookup over that list: `Record::Row`'s own argument, spent one hop further in.
///
/// # A COMPOSITE answers [`None`], and that is the relation's own width refusal one layer up
///
/// A relation joins ONE column to one column, and a composite field's columns are its segments
/// joined beneath it — `tb_num`, a string that exists nowhere as data, since the `const` family here
/// has no joining rule by design (see this module's note). So a field that spans several columns has
/// no single stored name to hand back, and the honest answer is the absent one:
/// [`SqlLoweringError::RelationWidth`](crate::comparison::sql::SqlLoweringError::RelationWidth) is
/// the same refusal, raised where the join is written.
///
/// A FLATTENED composite lends no name, so its segments are columns of the HOLDER's own namespace and
/// the walk descends into them — the arrangement [`distinct`] already walks, and what keeps this
/// function total over the shapes a row may hold rather than correct only for flat ones.
///
/// # It is keyed by the DECLARED name and answers the STORED one
///
/// The two halves of the question are on two sides of a boundary: a reverse position writes the name
/// its author declared, and a statement needs the name this database stores. So the KEY is the
/// declared half — the axis that does not vary with the database — and the answer is the stored one.
/// A `ref` field declared `reel_id` and stored `reel_fk` is found by `reel_id` in every database and
/// answers `reel_fk` in the one that renamed it.
///
/// That is the pairing [`ColumnName`] publishes, and the reason it is one value rather than two
/// parallel lists: this function is the lookup ACROSS the pair, and a lookup across two lists is one
/// that can drift.
///
/// # Examples
///
/// ```
/// use ingraph::{ColumnKind, ColumnName, ColumnShape, FieldName, flattened, shape, stored_column};
///
/// struct Timebase;
/// impl ColumnKind for Timebase {
/// const SEGMENTS: &'static [ColumnShape] = &[
/// ColumnShape::Plain(ColumnName::new("num")),
/// ColumnShape::Plain(ColumnName::new("den")),
/// ];
/// }
///
/// const COLUMNS: &[ColumnShape] = &[
/// ColumnShape::Plain(ColumnName::renamed("reel_id", "reel_fk")),
/// shape::<Timebase>(ColumnName::new("tb")),
/// flattened::<Timebase>(),
/// ];
///
/// // The DECLARED name is the key, and what comes back is what the database stores.
/// const BACK: Option<&FieldName> = stored_column(COLUMNS, "reel_id");
/// const _: () = assert!(matches!(BACK, Some(name) if name.is("reel_fk")));
///
/// // The stored spelling is not a key: one field has one declared name and one lookup.
/// const STORED: Option<&FieldName> = stored_column(COLUMNS, "reel_fk");
/// const _: () = assert!(STORED.is_none());
///
/// // A composite spans two, so it has no single name to be a relation's side of a join.
/// const WIDE: Option<&FieldName> = stored_column(COLUMNS, "tb");
/// const _: () = assert!(WIDE.is_none());
///
/// // A flattened one lends no name, so its segments are the holder's own columns.
/// const FLATTENED: Option<&FieldName> = stored_column(COLUMNS, "den");
/// const _: () = assert!(FLATTENED.is_some());
/// ```
pub const
/// Whether `name` is what `path` joins to — the comparison a `const` audit makes instead of
/// building the joined string.
///
/// # It knows the join, and that is deliberate
///
/// [`joined_byte`] is the `const` side's ONE authority on what the segments run together into, and
/// both compile-time questions read it: this one, against a flat name a person wrote, and
/// [`distinct`]'s, against another path of the same row. The RENDER side's is `push_segments`, and
/// the split between the two is what makes the audit worth having — this side is evaluated against a
/// descriptor at COMPILE time, so a descriptor spelling `tbnum` where the renderer will send
/// `tb_num` is `E0080` at the declaration rather than a `SELECT` the engine answers *no such column*
/// to.
pub const
/// How many bytes the column `path` names occupies — its segments plus one `_` between each pair.
const
/// The `at`th byte of the column `path` names — the `const` family's whole knowledge of the join.
///
/// It walks the cons list per byte rather than building the name, which is what a `const` has
/// instead of a `String`: the list is as deep as a declaration nests and a column name is short, so
/// the quadratic shape costs const-evaluation nothing and buys the two audits one authority to
/// share.
///
/// # Panics
///
/// At const-evaluation time when `at` is past [`joined_len`], which is the caller's own bound to
/// respect — both callers here compare the lengths first.
const
/// Whether `names` is exactly the columns `segments` renders, in order — the audit a FLAT
/// restatement of a composite's parts is held against.
///
/// # What it is FOR: the lists a collection ELEMENT is restated in
///
/// A record's own columns are audited by [`describes`](crate::describes), which walks a descriptor's
/// `[Column]` against the row's shapes. A collection ELEMENT has the same restatement problem and no
/// `Table` to hold it: its parts are written out flat three times over — as
/// [`EdgeTable::composite`](crate::EdgeTable::composite)'s stored columns, as the write plan's
/// [`EdgeWrite::composite`](crate::query::sql::EdgeWrite::composite) leaf names, and as the gather's
/// [`gather_composite`](crate::query::sql::EdgeCollection::gather_composite) — because a `const` on
/// stable cannot filter a `&[ColumnShape]` into a `&'static [&'static FieldName]`, there being no
/// allocation to hold the result.
///
/// So the restatement stays, and this is what makes it CHECKED. A list that has drifted from the
/// element type's own answer is `E0080` at the declaration rather than a statement naming a column
/// the schema never wrote.
///
/// # It compares against the JOINED form without building it
///
/// [`joins`] is the `const` side's one authority on what segments run together into, and this is its
/// second reader after [`describes`](crate::describes)'s walk. A part that lends no name —
/// [`flattened`] — passes the prefix through unchanged, so a detection's identity is audited as
/// `language`/`script`/`region`/`rest` and a part that DOES lend one is audited as `rate_num`. That is
/// the same rule the renderer descends by, stated on the other side of the compile.
///
/// # Examples
///
/// A composite whose part is itself composite and lends no name — the flattening, audited:
///
/// ```
/// use ingraph::{ColumnKind, ColumnName, ColumnShape, FieldName, flattened, leaf_names};
///
/// struct Tag;
/// impl ColumnKind for Tag {
/// const SEGMENTS: &'static [ColumnShape] = &[
/// ColumnShape::Plain(ColumnName::new("language")),
/// ColumnShape::Plain(ColumnName::new("script")),
/// ];
/// }
///
/// struct Detection;
/// impl ColumnKind for Detection {
/// const SEGMENTS: &'static [ColumnShape] = &[
/// flattened::<Tag>(),
/// ColumnShape::Plain(ColumnName::new("confidence")),
/// ];
/// }
///
/// const LEAVES: &[&FieldName] = &[
/// FieldName::new("language"),
/// FieldName::new("script"),
/// FieldName::new("confidence"),
/// ];
///
/// const _: () = assert!(leaf_names(<Detection as ColumnKind>::SEGMENTS, LEAVES));
///
/// // The PARTS are not the columns: three leaves, and naming two of them is a shorter list.
/// const PARTS: &[&FieldName] = &[FieldName::new("language"), FieldName::new("confidence")];
/// const _: () = assert!(!leaf_names(<Detection as ColumnKind>::SEGMENTS, PARTS));
/// ```
///
/// A part that LENDS its name prefixes its leaves, and the audit knows the join:
///
/// ```
/// use ingraph::{ColumnKind, ColumnName, ColumnShape, FieldName, leaf_names, shape};
///
/// struct Ratio;
/// impl ColumnKind for Ratio {
/// const SEGMENTS: &'static [ColumnShape] = &[
/// ColumnShape::Plain(ColumnName::new("num")),
/// ColumnShape::Plain(ColumnName::new("den")),
/// ];
/// }
///
/// const SEGMENTS: &[ColumnShape] = &[shape::<Ratio>(ColumnName::new("rate"))];
///
/// const JOINED: &[&FieldName] = &[FieldName::new("rate_num"), FieldName::new("rate_den")];
/// const _: () = assert!(leaf_names(SEGMENTS, JOINED));
///
/// const BARE: &[&FieldName] = &[FieldName::new("num"), FieldName::new("den")];
/// const _: () = assert!(!leaf_names(SEGMENTS, BARE));
/// ```
pub const
/// [`leaf_names`]'s walk, with [`described`](crate::describes)'s sentinel and for its reason: a
/// `const fn` has no `?`, and a count that has run past the list can only be this value.
const
/// Whether the `at`th FIELD of `shapes` renders its columns under names no other column of the row
/// has already taken.
///
/// # What it closes, and why the same-name refusal cannot
///
/// A declaration's own same-name rule compares the columns a macro can SEE, and a flattened
/// composite's segments are not among them: `<db>(flatten)` on a `Timebase` renders `num`
/// and `den` into the holder's own namespace, and the macro holding `tb: Timebase` cannot tell that
/// type from a `String`. Which is the whole reason the contract is type-answered — so the fence over
/// the RENDERED names has to be type-answered too, and it is this, evaluated where a declaration
/// states its columns.
///
/// A collision left standing is a `CREATE TABLE` with one column named twice: loud at create time,
/// but only for a caller that runs the schema lane, and only after the declaration has compiled.
///
/// # Per FIELD rather than over the whole list, so a refusal can NAME one
///
/// The message a `const` assertion carries is a literal, so nothing it says can be assembled from
/// what collided. Asking the question one field at a time moves that into the ASSERTION's own
/// placement instead: the emission writes one per field and puts the field's name in the sentence,
/// and the one that fires is the field that introduced the collision.
///
/// A field is also checked against ITSELF, which is not the degenerate case: a composite whose own
/// two segments render alike — directly, or through a nested one — occupies one column twice with no
/// second field involved.
///
/// # Examples
///
/// ```
/// use ingraph::{ColumnKind, ColumnName, ColumnShape, FieldName, distinct, flattened, shape};
///
/// struct Timebase;
/// impl ColumnKind for Timebase {
/// const SEGMENTS: &'static [ColumnShape] = &[
/// ColumnShape::Plain(ColumnName::new("num")),
/// ColumnShape::Plain(ColumnName::new("den")),
/// ];
/// }
///
/// // The PREFIXED spelling lends the field's name, so `num` beside it is `tb_num` beside `num`.
/// const PREFIXED: &[ColumnShape] = &[
/// ColumnShape::Plain(ColumnName::new("num")),
/// shape::<Timebase>(ColumnName::new("tb")),
/// ];
/// const _: () = assert!(distinct(PREFIXED, 1));
///
/// // `flatten` drops it, and the two `num`s meet.
/// const FLATTENED: &[ColumnShape] = &[
/// ColumnShape::Plain(ColumnName::new("num")),
/// flattened::<Timebase>(),
/// ];
/// const _: () = assert!(!distinct(FLATTENED, 1));
/// ```
pub const
/// [`distinct`]'s outer walk: every column of `shapes` in turn, checking the ones whose ordinal
/// falls in `from..to` against every column before them.
///
/// It answers the ordinal after the last column walked, or [`usize::MAX`] where one of the checked
/// columns was already named — the sentinel a `const fn` has instead of `?`, which
/// [`crate::describes`]'s own walk uses for the same reason.
const
/// [`scan`]'s inner walk: whether every column of `shapes` before ordinal `before` is named
/// something other than what `name` joins to.
///
/// Same answer shape as [`scan`] — the ordinal after the last column, or [`usize::MAX`] where one of
/// them collided.
const
/// Whether two paths name ONE column — the same question [`joins`] asks, with a path on both sides.
///
/// Segment-wise equality would be the wrong test and the difference is spellable: a field really
/// called `tb_num` beside no segment joins to what `tb` above `num` joins to, so the comparison is
/// over the JOINED bytes and reads them through [`joined_byte`] exactly as [`joins`] does.
const