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
//! The entity binding: [`Transformer`], the set of types an entity is reached by and becomes.
//!
//! A unit is an [`Operator`](crate::Operator); an entity is a `Transformer`. The crate already held
//! the first half of that pair at [`operator`](crate::operator), and this is the second — two
//! vocabularies, two modules. `legacy/ingraph` writes the same sentence at `src/transform/mod.rs`,
//! which is the module this item crosses from: the rule for taking something out of that crate is
//! MOVE, NOT REWRITE, and a module is part of what moves.
//!
//! Not in [`record`](crate::record), which answers a different question — what a record contributes
//! to an index, and which index it lands in. An address contributes to no index and lands in none.
//! It is what every family's face is keyed BY, so putting it inside the module describing one
//! family's payload would make three other families borrow it from a neighbour.
//!
//! [`visit`] is the module's one child, and it is the child legacy has under this name: the walk
//! that does something once per declared type. What did not cross with it is legacy's `InGraph` —
//! the per-entity BACK-POINTER naming which graph an entity belongs to — because the ownership is
//! INVERTED here. A graph root lists its own types once, so there is no registry for an entity to
//! point at, no graph identity for [`Transformer`] to carry a bounded slot for, and no wall bought
//! by carrying one.
//!
//! # The set, and the four seams that are not in it
//!
//! [`Transformer`] is an entity's COMPLETE set: one impl block per entity, every member named, and
//! an absent member bound `()` rather than left out. Five are reachable through it — the key, the
//! id, the lineage, the record and the wire face — and a member answering a VOCABULARY answers it
//! through a trait of its own, so a capability is selected at the USE SITE
//! (`T: Transformer<Record: Record<Db>>`) rather than by a bound on the entity.
//!
//! Four of the five are its own members and the id is [`Identifiable`]'s, taken as a SUPERTRAIT.
//! The id is the one of the five a NON-entity also has — the `*Key` addressing a record carries the
//! same last column the record does — so it is the one that had to be nameable without the entity
//! binding around it.
//!
//! # The two query faces, each where it is answered from
//!
//! A query over a record is written in a FILTER and an ORDER, and neither is a member of the set.
//! They sit apart because the conditions that make them exist are different, and each one lives with
//! whatever else answers to its condition.
//!
//! [`GraphqlInput::Filter`] and [`GraphqlInput::OrderBy`] are WIRE types: they exist because a
//! declaration wrote a wire face, and both are reached through the [`Graphql`] slot with the rest of
//! it. [`Record::Comparison`] and [`Record::OrderBy`] are STORAGE types: they are the predicate and
//! the level sequence one database really answers with, and they exist because the record persists.
//! So a persist-only record has a real comparison and a real order and no wire face at all — one
//! absence, not two halves of one.
//!
//! The two AXES are told apart by the parameter rather than by which trait they sit on. Everything
//! per-RECORD is on the wire bundle, everything per-(record × database) is on [`Record<B>`](Record),
//! and a capability trait carrying half an axis is what the retired `Orderable` was: it held one
//! database-free order for both faces, so it had to argue that no database decides anything about an
//! order — true of the WIRE face, and false of the storage one the moment a citizen's single word
//! expands into a dialect's own levels. Absence is [`Record<B>`](Record)'s missing impl now, which
//! is one refusal covering both storage members instead of two predicates kept in step.
//!
//! Its scope is the ENTITY. A pure compute unit is an [`Operator`](crate::Operator) and implements
//! nothing here: the split gives such a unit no table and no id, so there is no address for a
//! `Key = ()` to stand in for, and what a unit does carry — how far it has read — rides the operator
//! vocabulary where the rest of its state does.
//!
//! # The relation half, beside the entity half
//!
//! [`Related<Target>`](Related) is the one fact about a relation no entity trait can conjure: WHICH
//! of a record's fields point at another record. The types are all projections already —
//! `<Target as Identifiable>::Id` is what a referring field carries, an id being a TABLE-WIDE
//! address because every table's is unique — so the emission that has to exist is the one carrying
//! what a projection cannot answer, and it is a per-(source, target) PAIR rather than a registry:
//! two `ref`s at one target are one impl and never `E0119`.
//!
//! Here rather than in a module of its own, because a relation is the entity binding read from the
//! other end. What it names is entities: the source it sits on, the target it points at, and the
//! address the target is reached by — every one of them a member of the set above.
//!
//! # The four READ-side store seams
//!
//! The four legacy's `Transformer` also carries — `Db`, `Vector`, `Fulltext`,
//! `Blob`, which its search layer hydrates a hit through — are not members here and have no slot,
//! not even `()`. They belong to a one-node-one-entity-four-faces premise this crate does not hold:
//! an index over a record and a family of artifacts beside it are each a NODE of their own, reached
//! by a relation, and a store is written OVER a record by the backend that keeps it —
//! [`AsyncBlobEngine<R>`](crate::AsyncBlobEngine), whose `R: Transformer` bound is the whole of what a blob store asks
//! of an entity. An entity never names its backends, so a slot for one would not read as *this
//! entity lacks the capability*, which is what `()` says here; it would read as *this question is
//! still open*.

mod habitat;
mod visit;

pub use habitat::{Habitat, Layout, SlotColumn, SlotSchema, SlotSpec};
pub use visit::{AsyncTypeVisitor, TypeVisitor};

use crate::FieldName;

/// What is reached by ONE id: the address itself, borrowed — and copied where the id's type allows
/// it.
///
/// A trait of its own rather than a member of [`Transformer`], because an entity is not the only
/// thing that has an id. The `*Key` an expansion mints implements this BESIDE the record it
/// addresses — the same last column, read off the key instead of off the record's field — and a key
/// is no entity's binding, so a member of the entity set could never have reached it.
///
/// [`Transformer`] takes it as a SUPERTRAIT, which is what keeps an entity from stating its id
/// twice: `E::Id` projects through the bound for every `E: Transformer`, and there is one place the
/// type is written. A QUALIFIED path still names the trait the member is on — `<E as
/// Identifiable>::Id`, where `<E as Transformer>::Id` is `E0576`, because qualification selects a
/// trait rather than searching one.
///
/// A blanket impl in either direction is refused by the same fact. `impl<T: Transformer>
/// Identifiable for T` would make every implementor an entity, which is exactly what a key is not;
/// and conferring identity from a family face is `E0119` at the SECOND face's impl, before any
/// record exists. So the impls are written one per type.
///
/// # `id` and `id_ref` are the emitted accessor pair
///
/// A `#[ingraph(copy)]` column is handed out as `x_ref(&self) -> &T` with `x(&self) -> T` beside it
/// — the borrow always, the copy in addition — and these two are that pair under the trait's own
/// names. One language on both faces: a caller reaching an id generically writes what it would write
/// reaching it inherently.
///
/// # The `Copy` gate is on the METHOD
///
/// [`id`](Self::id)'s bound is a where clause on the method rather than on [`Id`](Self::Id), so the
/// gate falls where the copy is asked for and nowhere else. A record whose id is a `String`
/// implements this exactly as a `u64`-keyed one does, exposes [`id_ref`](Self::id_ref) alone, and
/// refuses `id()` with `E0277` AT THE CALL.
///
/// That asymmetry is deliberate rather than a shortfall. A text id is an id — it addresses a row as
/// well as any other — and the only thing it cannot do is be handed back by value for free. Binding
/// `Copy` on the associated type would have made the whole capability unavailable to it to spare
/// one method.
///
/// # Examples
///
/// A record and the key that addresses it, both hand-written, both answering the same id:
///
/// ```
/// use ingraph::Identifiable;
///
/// struct Chunk {
///   doc: u64,
///   ordinal: u32,
/// }
///
/// struct ChunkKey {
///   doc: u64,
///   ordinal: u32,
/// }
///
/// impl Identifiable for Chunk {
///   type Id = u32;
///
///   fn id_ref(&self) -> &u32 {
///     &self.ordinal
///   }
/// }
///
/// impl Identifiable for ChunkKey {
///   type Id = u32;
///
///   fn id_ref(&self) -> &u32 {
///     &self.ordinal
///   }
/// }
///
/// fn address_of<T: Identifiable<Id: Copy>>(value: &T) -> T::Id {
///   value.id()
/// }
///
/// let chunk = Chunk { doc: 7, ordinal: 12 };
///
/// assert_eq!(chunk.id_ref(), &12);
/// assert_eq!(address_of(&chunk), 12);
/// assert_eq!(address_of(&ChunkKey { doc: 7, ordinal: 12 }), 12);
/// ```
///
/// A text id implements the trait and borrows; the copy is what it refuses:
///
/// ```compile_fail,E0277
/// use ingraph::Identifiable;
///
/// struct Slug(String);
///
/// impl Identifiable for Slug {
///   type Id = String;
///
///   fn id_ref(&self) -> &String {
///     &self.0
///   }
/// }
///
/// let slug = Slug("a-red-car".to_owned());
/// let _: String = slug.id();
/// ```
///
/// # The sentence a MISSING one carries
///
/// This is the bound a `ref` target is held to, so an unsatisfied one is almost always the same
/// mistake: a field pointing at the VALUE TIER. A FIELD FRAGMENT bears no identity by definition —
/// that is what the tier means — so it can never satisfy this, and the default `E0277` would report
/// a trait the author never wrote and leave them to work out why.
///
/// **The word is `fields`, and it used to be `entity`.** The rename is the LADDER's: `entity` now
/// names the identity-bearing rung one step up — the one that DOES satisfy this bound — so the old
/// sentence sent a reader looking for a value tier at the exact word that answers. `ingraph_derive`'s
/// `fields` module states the ladder from the other end: *the rung above is `entity`, which bears an
/// identity*.
///
/// The note is declared ONCE, here, rather than minted per reference: `on_unimplemented` rides the
/// TRAIT, so every site that bounds it inherits the sentence and nothing has to be emitted to carry
/// one. [`refers_to`]'s `Target: Identifiable<Id = Field>` is the bound a declared `ref` already
/// discharges, so the note reaches the site that needed it without a second audit beside it.
///
/// The note is ONE unbroken line, deliberately: it is rendered verbatim, so a line continuation
/// inside it reaches the reader as the indentation the source was wrapped with. Measured.
#[rustfmt::skip]
#[diagnostic::on_unimplemented(
  message = "`{Self}` has no identity to reference",
  note = "a `ref` target is a node with an id; a field fragment is HELD rather than referenced, so write the field as the plain type and let it be flattened"
)]
pub trait Identifiable {
  /// The ONE column this value is addressed by: a record's own final segment, as against the lineage
  /// its parents supplied, and the same column read off the key that carries it.
  ///
  /// It is not the key, and it is not a one-column key struct: for a `ChunkKey { doc, ordinal }` the
  /// id is `ordinal`'s bare type, never the compound. Naming the key here would nest a parent's
  /// whole address inside its child's where ONE column belongs, which is the flattening the
  /// decomposition exists to keep out.
  ///
  /// It is there to be PROJECTED THROUGH. A child spells its parent's column as
  /// `<Parent as Identifiable>::Id` rather than repeating the scalar, so re-typing one record's id
  /// re-types every key descended from it and the drift is a compile error rather than a convention.
  ///
  /// `()` where a record mints nothing — a key with no columns at all addresses nothing, and has no
  /// last column to name.
  ///
  /// Bound by nothing, `Copy` included: see the gate on [`id`](Self::id).
  type Id;

  /// This value's id, BORROWED.
  ///
  /// The half every id shape can answer, which is why it is the one an implementor writes: a `String`
  /// id hands back a `&String` as a `u64` id hands back a `&u64`, and nothing about the type has to
  /// be true for it.
  fn id_ref(&self) -> &Self::Id;

  /// This value's id BY VALUE, where the id is `Copy`.
  ///
  /// Defaulted, and there is no second body to write: a `Copy` id read out of a borrow is the
  /// dereference. An implementor overriding it would be stating the same thing again.
  fn id(&self) -> Self::Id
  where
    Self::Id: Copy,
  {
    *self.id_ref()
  }
}

/// An ENTITY's set, bound to the entity type: the id it is REACHED by, on [`Identifiable`] below,
/// the full key and the ancestor half it is HANDED BACK under, and the row form it becomes.
///
/// One set per entity, which is why the members are ASSOCIATED TYPES rather than parameters. Both
/// alternatives were measured: `Transformer<K>` compiles `impl Transformer<u64> for Caption` beside
/// `impl Transformer<String> for Caption`, giving one record two identities with nothing to say
/// which one addresses it; and conferring identity from a family face by blanket impl is `E0119` at
/// the SECOND face's impl, before any record exists, so at most one family could ever confer it.
///
/// Implemented BESIDE a family face rather than beneath it — see [`record`](crate::record)'s module
/// note for the two bounds that arrangement buys.
///
/// # The set is TOTAL, and an absent member binds `()`
///
/// One impl block IS this set — the [`Identifiable`] block beside it is the supertrait's, and the
/// two together are the entity's binding. A member the entity lacks is written `()` rather than
/// left out, so absence is a fact a reader finds where the presences are. `()` answers nothing
/// vacuously, which is the half that keeps it honest — no vocabulary is implemented for it, so a
/// party demanding a capability writes it as a bound on the MEMBER
/// (`T: Transformer<Record: Record<Db>>`) and an entity without one is `E0277` where the capability
/// is asked for.
///
/// A member added later is a member every hand-written impl has to bind, associated types having no
/// defaults. That is the price of totality and it is paid knowingly: the derive absorbs the
/// generated impls, and the hand-written ones are the declarations this crate can see.
///
/// [`Graphql`](Self::Graphql) is what reaches the WIRE half of a query — the filter a client sends
/// and the order it asks for, both under [`Graphql`](crate::Graphql) rather than as members here.
/// The line between a slot and a member of one is who ELSE could implement the face: a wire face has
/// two halves and each half has its own questions, so it is a bundle with a vocabulary, where a
/// single type with nothing asked of it would have been a member. The STORAGE half of a query is
/// [`Record::OrderBy`], beside this trait entirely and under the database that decides it.
///
/// # The three name one decomposition
///
/// A key is `lineage ⊕ id`: the path from the root, root-first, then the record's own final segment.
/// [`Key`](Self::Key) is that whole chain, [`Lineage`](Self::Lineage) its ancestor half and
/// [`Id`](Identifiable::Id) its last column — so the two halves are not extra state, they are the
/// two ends of one type, each nameable on its own.
///
/// Which end does which job is not the same end twice, and the obvious answer is the stale one. A
/// row is REACHED by the id: every table's is unique, so `WHERE id = ?` names at most one and the
/// chain adds nothing to the naming. What the chain is for is the OUTPUT — a hit hands back its
/// ancestry instead of a round-trip for it — and the SCOPE, the lineage being stored beside the id
/// as ordinary columns a filter, an order and a scoped delete all still reach.
///
/// The id is the SUPERTRAIT's, and one source of truth: an entity states it in its
/// [`Identifiable`] impl, `E::Id` projects to it under this bound alone, and the key carrying that
/// same column answers with the same type from an impl of its own.
///
/// # Examples
///
/// A three-column address, decomposed. The bound reaches every part of it, and nothing else:
///
/// ```
/// use ingraph::{Identifiable, Transformer};
///
/// struct Keyframe {
///   media: u64,
///   scene: u32,
///   ordinal: u16,
/// }
///
/// #[derive(Debug, PartialEq)]
/// struct KeyframeKey {
///   media: u64,
///   scene: u32,
///   ordinal: u16,
/// }
///
/// #[derive(Debug, PartialEq)]
/// struct KeyframeLineage {
///   media: u64,
///   scene: u32,
/// }
///
/// impl Identifiable for Keyframe {
///   type Id = u16;
///
///   fn id_ref(&self) -> &u16 {
///     &self.ordinal
///   }
/// }
///
/// impl Transformer for Keyframe {
///   type Key = KeyframeKey;
///   type Lineage = KeyframeLineage;
///   type Record = Self;
///   // Nothing exposes this record on a wire, so there is no face to reach and nothing to filter
///   // through. Its columns are orderable all the same, and that answer is beside this block.
///   type Graphql = ();
///
///   fn key(&self) -> KeyframeKey {
///     KeyframeKey {
///       media: self.media,
///       scene: self.scene,
///       ordinal: self.ordinal,
///     }
///   }
/// }
///
/// fn address_of<T: Transformer>(record: &T) -> T::Key {
///   record.key()
/// }
///
/// // The id projects off this bound alone, the supertrait having put it in reach.
/// fn id_of<T: Transformer>(record: &T) -> T::Id
/// where
///   T::Id: Copy,
/// {
///   record.id()
/// }
///
/// // The wire face projects off it too, which is how a NESTED position reaches a neighbour's
/// // types without repeating them — the member is this trait's own, so the qualified path spells
/// // it. An entity that declares a face binds ITSELF here, as it does for its row form.
/// fn wire_face<T: Transformer>(face: <T as Transformer>::Graphql) -> T::Graphql {
///   face
/// }
///
/// let keyframe = Keyframe {
///   media: 7,
///   scene: 3,
///   ordinal: 12,
/// };
///
/// assert_eq!(
///   address_of(&keyframe),
///   KeyframeKey {
///     media: 7,
///     scene: 3,
///     ordinal: 12
///   }
/// );
/// assert_eq!(id_of(&keyframe), 12);
/// assert_eq!(wire_face::<Keyframe>(()), ());
/// ```
#[rustfmt::skip]
#[diagnostic::on_unimplemented(
  message = "`{Self}` has no key",
  label = "no key type",
  note = "a key is what a declaration's own macro emits, so a value that declares nothing has none; `notify` on a source entry asks for one, and a product without one is received as the message instead"
)]
pub trait Transformer: Identifiable {
  /// The record's key — the whole chain, `lineage ⊕ id`, flat and root-first.
  ///
  /// The OUTPUT address rather than the storage one. A row is reached by
  /// [`Id`](Identifiable::Id), and this is what a hit is handed back UNDER: a
  /// [`Scored`](crate::Scored) hit carries this key, so a keyframe's scene, track and media arrive
  /// with the keyframe and a caller reads the ancestry off the hit rather than paying a hydration
  /// round-trip for it.
  ///
  /// Bound by nothing, and that is not laziness. The reason used to be the ENGINE's fan-in — a
  /// derived index with several upstreams, keyed by an enum over those upstreams' keys — and that
  /// key has moved down to the packet layer, where a fan-in is the fixed-width `(tag, id)` an
  /// engine dedups and replaces on. What still needs the openness is the fan-in's OUTPUT half,
  /// which is a sum however narrow the engine's key became:
  /// `Segment(SegmentKey) | Keyframe(KeyframeKey)`, an enum over WHOLE keys, so any bound
  /// describing a key as a struct of columns would refuse the shape the output layer requires. What
  /// a key must satisfy is asked where it is used: an engine's own record trait, and the codec that
  /// encodes it.
  type Key;

  /// The ANCESTOR half of [`Key`](Self::Key): the path from the root, root-first, without the id.
  ///
  /// `()` for a ROOT, whose path is empty. That is what the codegen was measured to emit and not a
  /// form invented for this slot: `RecordModel::lineage` is an `Option`, `RecordModel::emit` writes
  /// no lineage type when it is `None`, and `ingraph-codegen`'s
  /// `tests::a_root_emits_a_key_and_no_lineage_type_at_all` holds it there. A root therefore has no
  /// emitted type to name, and the empty product already has a spelling — an empty struct would be a
  /// second name for what `()` denotes.
  ///
  /// # It is the typed SCOPE SCHEMA
  ///
  /// The chain is not an address and not a spare copy of one. It is the projection a SCOPED question
  /// is written in — *nearest within media X*, *retire this media's derivations* — and the same
  /// fields a secondary entry stores denormalized, so ONE projection feeds the filter going in and
  /// the provenance coming back out. That is what a derived artifact answers *where did this come
  /// from* with, the id alone answering only *which one is it*.
  ///
  /// [`VectorRecord::Filter`](crate::VectorRecord::Filter) is the face that spends it, and the two
  /// are already written as one type where a record declares both — `store::vector`'s own fixture
  /// binds a single `KeyframeLineage` to this member and to that one. What has not arrived is the
  /// emission that makes them one BY CONSTRUCTION, which is the secondary stores' derive.
  ///
  /// No shipped path projects it. It is generated, it is total, and nothing in this crate or its
  /// expansions writes `T::Lineage` — said here rather than left for a reader to discover, because
  /// a member that looks spent and is not is what a later reader deletes.
  ///
  /// Bound by nothing, and for its own reason rather than [`Key`](Self::Key)'s: a scope schema is a
  /// projection of the record's own columns, shaped differently per entity, so what one must SATISFY
  /// is the searched engine's question and is asked where that engine's face is bound — the
  /// arrangement [`VectorRecord::Filter`](crate::VectorRecord::Filter) states in full one family
  /// over.
  type Lineage;

  /// The ROW FORM this entity becomes — `Self` where it becomes one, `()` where it becomes none.
  ///
  /// `= Self` exactly when the declaration persists somewhere. A stored record's projections are one
  /// per database, a row apiece with that database's own column names and conversions, and the type
  /// they are all projections OF is the record — so binding the record names the row form without
  /// electing one database's spelling of it.
  ///
  /// `()` is the absent form, and a real answer rather than a placeholder: an entity that becomes no
  /// row binds the empty product, as a root binds it for [`Lineage`](Self::Lineage). A declaration
  /// with no `persist(…)` block is that entity — `ingraph-derive` says the same thing from the other
  /// side, refusing an empty block with *a record stored nowhere is spelled by omitting the block* —
  /// and so is a referenceable CELL, a value other entities point at that has no row of its own.
  ///
  /// What a row form can do is asked of it through [`Record`], the vocabulary a non-`()` binding
  /// answers, and asked at the use site: `()` implements none of it.
  type Record;

  /// The WIRE FACE — `Self` where the declaration writes a `graphql(…)` block, and `()` where it
  /// writes none.
  ///
  /// `()` means NO GRAPHQL BLOCK WAS DECLARED, so nothing was ever written for a client to send a
  /// filter in or receive a hit through.
  ///
  /// `= Self` is [`Record`](Self::Record)'s rule one member over, and for the matching reason. The
  /// types a client speaks are per RECORD — a schema varying with a deployment's storage choice
  /// would be a schema no client could hold against two deployments — so the record is what names
  /// them, and the [`Graphql`](crate::Graphql) impl beside this block is where they are written.
  /// Naming a bundle type here instead would have put a second name on a face the record already
  /// is.
  ///
  /// # It reaches the FILTER, which is not the comparison
  ///
  /// A comparison is a predicate LOWERED into one database's own types, so a record stored in three
  /// databases has three of them and each lives on [`Record::Comparison`] under that database's
  /// parameter. The filter — `<Self::Graphql as Graphql>::Input`'s
  /// [`Filter`](GraphqlInput::Filter) — is the ONE type a client speaks, per record rather than per
  /// database, and the crossing between the two happens exactly once.
  ///
  /// That split is why a persist-only record binds `()` here and still has comparisons — already the
  /// emitter's truth rather than a rule invented for this slot: a comparison rides beside its row
  /// whether or not anything can be converted into one.
  ///
  /// # It is there to be PROJECTED THROUGH
  ///
  /// A position constraining a neighbour writes
  /// `<<Target as Transformer>::Graphql as Graphql>::Input` and takes that face's own filter, so
  /// re-shaping one record's wire types re-shapes every nested position that reaches it and the
  /// drift is a compile error rather than a convention.
  ///
  /// Bound by nothing here, and the bound is written at the position instead:
  /// `T: Transformer<Graphql: Graphql>` is what a party demanding a wire face writes, and nesting
  /// through an entity that declared none is `E0277` AT THAT BOUND — [`Graphql`](crate::Graphql) is
  /// implemented for no `()`, which is the whole of what keeps the empty product from answering
  /// vacuously.
  type Graphql;

  /// This record's key.
  ///
  /// By value, because a key is built from the record's fields rather than stored whole — there is
  /// no `&Self::Key` to hand back.
  fn key(&self) -> Self::Key;
}

/// What a non-`()` [`Record`](Transformer::Record) binding answers, PER BACKEND: the shape a
/// predicate over this row takes in `B`.
///
/// # The backend is the TRAIT's parameter, and one impl names each
///
/// A record's comparison is a NAMED type per database — `MediaSqliteComparison` beside
/// `MediaPostgresComparison`, and whatever a `comparison(rename = "…")` made of either — because a
/// rename is declared per database and the shapes genuinely differ. No single associated type can
/// select among those names: nothing about a database parameter chooses between two structs. So the
/// database is what the trait is parameterised by, and a record stored in three databases gets three
/// impls that cannot collide.
///
/// # Absence IS the refusal
///
/// The impl SET states where a record is stored — one per database it persists in — so a record
/// stored in SQLite alone refuses `<Media as Record<Postgres>>` with `E0277` AT THE BOUND, *this
/// record does not persist there*, rather than with a projection that is well formed and then fails
/// somewhere further along.
///
/// ```compile_fail,E0277
/// use ingraph::Record;
///
/// struct Media;
/// struct Sqlite;
/// struct Postgres;
/// struct MediaSqlite;
/// struct MediaSqliteComparison;
///
/// impl Record<Sqlite> for Media {
///   type Row = MediaSqlite;
///   type Comparison = MediaSqliteComparison;
/// }
///
/// fn stored_in<B, R: Record<B>>() {}
/// stored_in::<Postgres, Media>();
/// ```
///
/// # The name it shares with the attribute, and what really tells them apart
///
/// `Record` the trait and `record` the attribute are one word for one concept, which is worth more
/// than two words keeping a namespace tidy. What separates them is CASE and NAMESPACE — `Record` is
/// a type and `record` is a macro, re-exported side by side at this crate's root — and either alone
/// would have been enough: Rust resolves macros in a namespace of their own, so even one spelling
/// would not have collided.
///
/// It is NOT derive position, which this note used to claim by analogy with `serde::Serialize`. The
/// analogy does not hold, and the difference is not cosmetic: serde's is a `proc_macro_derive`, so
/// its name is written inside a `#[derive(…)]` and the POSITION is what disambiguates. This crate's
/// is a `proc_macro_attribute` — a declaration writes `#[ingraph::record(…)]` — so there is no
/// derive position anywhere for the rule to have been about.
///
/// # What this half of the split holds
///
/// The PER-DATABASE half. [`Row`](Self::Row) is the shape this record takes in one database and
/// `Comparison` a predicate in the types that database keeps, so a record stored in three has three
/// of each and both are reached under that database's parameter; the filter a client sends is
/// [`GraphqlInput::Filter`] and the order it asks for is [`GraphqlInput::OrderBy`], both ONE per
/// record and neither carrying this parameter — where the two members BELOW are per database and
/// both carry it. That a record with no wire face still has comparisons is
/// the emitter's own truth: a comparison rides beside its row whether or not anything can be
/// converted into one, which is the same fact that binding `()` states from the entity's side.
///
/// # The SENTENCE this refuses with came from the retired order capability
///
/// `Orderable` carried a `#[diagnostic::on_unimplemented]` and this trait carried none, so a record
/// stored nowhere was told *no order can be written over it* at the order projection and a bare
/// *trait bound is not satisfied* at every other one. Collapsing the two absences into this one
/// would have taken the better message with it. It is written here instead, widened to the fact
/// both projections are really about: the declaration does not persist in `B`.
#[diagnostic::on_unimplemented(
  message = "`{Self}` is not stored in `{B}`, so it has no row, no comparison and no order there",
  label = "not stored in this database",
  note = "a record earns its storage vocabulary by persisting: `#[ingraph(persist(…))]`, naming \
          this database"
)]
pub trait Record<B> {
  /// The ROW this record becomes in `B` — the concrete type a decode fills and a conversion raises
  /// the record back out of.
  ///
  /// # It is the one fact ANOTHER declaration's expansion cannot reach any other way
  ///
  /// A row's name is per DATABASE and it is RENAMEABLE — `<db>(row(rename = "…"))` — so a
  /// declaration nesting through a `ref` holds the target's path and nothing that names the target's
  /// row. Appending a suffix to that path would be the emitter GUESSING a name, which is the move it
  /// refuses everywhere else: it holds a declaration's TOKENS, and only the declaration that wrote
  /// the row knows what the row is called. `<Target as Record<Sqlite>>::Row` is that name ASKED FOR
  /// rather than rebuilt, and the absence of the impl is still the refusal — a target that persists
  /// elsewhere is `E0277` AT THE BOUND, one step before a projection that would have been well
  /// formed and wrong.
  ///
  /// Here rather than on a vocabulary of its own, because a second per-backend trait would carry the
  /// same parameter, the same one-impl-per-declared-database emission and the same tooth — which is
  /// a vocabulary this trait already is. What answers *what does this record become in `B`* belongs
  /// beside what answers *what does a predicate over it look like in `B`*.
  ///
  /// It is the emitted ROW STRUCT and never the driver's own row. `<B as sqlx::Database>::Row` is
  /// reachable without any member here, says nothing about the entity, and is not what a single
  /// consumer holds: a decode fills the struct, a conversion raises the record out of the struct,
  /// and the query binding is written ON the struct.
  ///
  /// Bound by nothing, for the reason [`Comparison`](Self::Comparison) is: what a row must satisfy
  /// is the DECODE's question — one family's `FromRow`, the other's `Deserialize` — and it is asked
  /// where that decode is bound.
  type Row;

  /// The LOWERED form of a predicate over this record's row in `B`.
  ///
  /// Bound by nothing here. What a comparison must satisfy is asked where it is USED — a party that
  /// renders one writes `ComplexComparison<B>`, whose accumulator is that backend's — and a bound
  /// stated here would be a second copy of a promise the comparison's own emission already keeps.
  type Comparison;

  /// The LOWERED form of an ORDER over this record's rows in `B` — the LEVEL SEQUENCE this database
  /// really sorts by.
  ///
  /// # It is here for [`Comparison`](Self::Comparison)'s reason, and the seat used to be elsewhere
  ///
  /// A predicate and an order are the same shape twice. The client speaks ONE vocabulary per record
  /// — [`GraphqlInput::Filter`] and [`GraphqlInput::OrderBy`], neither carrying a database — and the
  /// storage speaks one per (record × database), because what a column is CALLED and how many
  /// columns a value occupies are that database's answers. So the order's storage half belongs
  /// exactly where the predicate's does: under the parameter that decides it.
  ///
  /// It did not use to. A retired `Orderable` trait carried a single database-free `OrderBy` for
  /// both faces, and its own note argued the parameter away — *an ordering term's variants are the
  /// record's stored columns and the direction each runs in, and a `<db>(rename)` is resolved to a
  /// column NAME at the lowering, so one term type serves every database*. Every clause of that is
  /// true of the WIRE face and none of it is true here, which is what the argument could not see
  /// while one type stood for both: a rename is not the only thing a database decides. How many
  /// LEVELS one citizen's single wire word expands into, and in what sequence, is a dialect's answer
  /// — a family that nests a composite has a different one from a family that flattens it — and no
  /// database-free type can hold two. The argument moved with the face it was about: it is
  /// [`ToGraphqlOrderBy`](crate::ToGraphqlOrderBy)'s note now, where it is entirely correct.
  ///
  /// # Absence is still the refusal, and it is INHERITED rather than restated
  ///
  /// A record stored nowhere has no `Record<B>` impl at all, so it has no order here either — one
  /// absence covering both halves where the capability trait needed its own. That is the whole of
  /// what retiring `Orderable` cost and it is a saving: a record's storability was stated twice, by
  /// two predicates an emitter had to keep in step, and it is stated once now.
  ///
  /// Bound by nothing, for the reason its two siblings are. What an order must satisfy is the
  /// PAGE's question — a completed order, a term per level, a cursor tail — and it is asked where
  /// that engine's face is bound.
  type OrderBy;
}

/// A record whose rows a HYDRATED read can be served from, and the database one is served out of.
///
/// A capability BESIDE [`Transformer`] as [`Record<B>`](Record) is, and for that trait's reason: a
/// record that becomes no queryable row has no store a hydration could read, so it gets NO IMPL
/// rather than an impl binding `()` — absence is the refusal, one step earlier than an empty product
/// a reader would have to interpret.
///
/// # It exists because two derives are blind to each other
///
/// A derived index's expansion holds the upstream's PATH and its projections and nothing else:
/// `persist` is refused by name on an index declaration, an index model carries no backend, and
/// [`Record<B>`](Record) is parameterised — a record may persist in several databases and no member
/// of the entity set says which of them a READ should go to. So a hydrating resolver had no line to
/// write for `ctx.data::<SqlDoor<…>>`, and both hydrated roads stood hand-mounted
/// (`ingraph/tests/hydrated_road.rs`, `ingraph/tests/similar_hydrated_road.rs`) for exactly that one
/// line. This is that line, moved to the side of the boundary that can answer it: the RECORD's
/// expansion knows its own persist list, and a type-level projection crosses a macro boundary where
/// a token cannot.
///
/// # WHICH database — the record's OWN read face's answer, not a second one computed alike
///
/// [`Db`](Self::Db) is `ingraph-codegen`'s `RecordModel::wire_query_row` verbatim: the FIRST
/// DECLARED database that carries a query face and whose row raises onto the wire. Not a
/// first-declared derived again here, and the difference is the whole reason the two are one
/// function — that emitter's own note states the law it is under, *a client must never see a field
/// that varies with a deployment's storage choice, so a record stored in two databases answers its
/// root fields from one*. A record whose root fields read one store and whose HYDRATION read
/// another would be that variance one road over, and it would want two [`SqlDoor`](crate::SqlDoor)s
/// installed for one record where a schema installs one per store. Hydration reads where the
/// record's own read face reads, by construction rather than by agreement.
///
/// The same function is what decides the impl EXISTS: it is `None` for a record with no `graphql(…)`
/// block, none for a record with no queryable database, and none for a record whose row does not
/// raise — an `entity`, which holds no rows at all, being a case of the second. So there is no condition
/// to keep in step with, and the projection cannot be well formed where the record's own query unit
/// is not.
///
/// # The persist list is a CANDIDATE set, and this is the READ end of it
///
/// The user's ruling of 2026-08-16: a record names every database it is WILLING to be kept in so
/// that a deployment can configure only the one it wants — 目前只保证能多写就行 — and multi-OPEN
/// as a read-routing optimisation is expressly deferred, 先不要考虑. What holds today is therefore
/// narrow and deliberate: multi-WRITE works when every declared database is enabled, and READS —
/// the record's own wire queries and this hydration — follow the first-declared one. There is no
/// picker word here, and a later one would be purely additive.
///
/// **The limitation that is NAMED rather than built**: a deployment that leaves the first-declared
/// database out of its options while mounting a wire read road finds the projected door missing at
/// the request instead of at launch, and the honest teeth for that is a launch refusal naming the
/// database and the mount.
///
/// # The tooth, and what it costs a declaration that wanted addresses alone
///
/// A hydrated road projects `<Upstream as Hydrates>::Db`, so an upstream that is stored nowhere, is
/// dressed nowhere, or is kept only in a store with no query face is `E0277` AT THAT PROJECTION,
/// carrying this trait's own sentence. MEASURED, the caret lands on the whole
/// `#[ingraph::vector(…)]` an author wrote rather than inside an expansion; the projection is
/// written spanned at the `upstream(node = "…")` inside it, so a narrower caret is a span fix and not
/// an edit here.
///
/// **That refusal used to reach the KEYS road too, and the word that ends it is `keys`.** A dressed
/// election mounted both tiers unconditionally, so in a build carrying the SQL family a declaration
/// that only ever wanted addresses back was still held to a storable upstream — where before the
/// hydrated tier existed a wire face cost the upstream one word and no storage. The paragraph here
/// closed *what would remove it is a declaration word choosing the tier, which nothing has ruled*,
/// and the record-family ladder ruled it: `keys` on the election says the upstream is an `entity`,
/// and an entity mounts the keys tier alone. What is left of the old softenings still holds — a
/// build with no SQL family has no hydrated tier, and a FANNED election mounts no hydrated road.
///
/// The word is not a patch on this demand but a TIER FACT beside it, which is why the demand is
/// still written unconditionally where the word is absent: which rung an upstream sits on is not
/// something this expansion can read, and a macro narrowing its own surface to whatever happens to
/// compile would decide a deployment's storage posture from the outside.
///
/// # Examples
///
/// A record and the database its hydration reads — the impl an expansion writes, by hand:
///
/// ```
/// use ingraph::Hydrates;
///
/// struct Frame;
/// struct Sqlite;
///
/// impl Hydrates for Frame {
///   type Db = Sqlite;
/// }
///
/// // The spelling a hydrating resolver writes: the door is keyed on the PROJECTION, so re-declaring
/// // one record's first database re-keys every road that hydrates it.
/// fn door_of<R: Hydrates>(db: R::Db) -> R::Db {
///   db
/// }
///
/// let _: Sqlite = door_of::<Frame>(Sqlite);
/// ```
///
/// A record that is hydrated from nowhere implements nothing here, and the projection is where that
/// is refused:
///
/// ```compile_fail,E0277
/// use ingraph::Hydrates;
///
/// fn hydrates_from<R: Hydrates>() {}
/// hydrates_from::<()>();
/// ```
#[diagnostic::on_unimplemented(
  message = "`{Self}` is hydrated from no database — a hydrated road hands back whole entities, and \
             a record that becomes no queryable row has none to hand back",
  label = "no hydration database",
  note = "a record earns one by being STORED and DRESSED at once: a STORE WORD at the head — \
          `#[ingraph::record(sqlite)]` — at a database whose row raises the record back, and \
          `graphql(…)` beside it, which is the same pair the record's own root fields are served \
          under",
  note = "TWO ROADS, and which one is the repair is yours to say: make the upstream a `record` and \
          name its store, which is what a hydrated tier reads out of; or leave it the `entity` it is \
          and write `keys` on THIS declaration, which mounts the keys tier alone and asks the \
          upstream for nothing but its address. The word is a fact about the upstream's RUNG, so it \
          is not a narrowing you are talked into — a search surface over a node whose messages land \
          in no database anywhere is the pure-engine deployment, and `keys` is its honest home"
)]
pub trait Hydrates {
  /// The database a hydrated read of this record runs against — the one its
  /// [`SqlDoor`](crate::SqlDoor) is keyed by.
  ///
  /// It is there to be PROJECTED THROUGH. A hydrating road writes `<Upstream as Hydrates>::Db`
  /// rather than naming a dialect, so re-declaring one record's first database re-keys every road
  /// that reads it and the drift is a compile error rather than a convention — which is the whole
  /// of what a derived index, which declares no database of its own, can be given.
  ///
  /// Bound by nothing, and by this family's law rather than by oversight: what a database must
  /// satisfy is the READING party's question — `sqlx::Database` where the door is a `SqlDoor`, and
  /// whatever a second store family asks — and a bound written here would put one family's
  /// vocabulary on a member every family projects. It is also what keeps this trait out of the SQL
  /// feature: the member is a name, and only the impl that BINDS one names a driver.
  type Db;
}

/// What a non-`()` [`Graphql`](Transformer::Graphql) binding answers: the entity's wire face, in the
/// two halves a schema has.
///
/// The slot and the vocabulary share the name — one is a type and one is a trait, so they do not
/// collide — and that is the sentence they make together: *this slot answers the `Graphql`
/// questions*. It is the arrangement [`Record`] already uses one member over.
///
/// # Here rather than beside the filter types
///
/// `graphql`'s own module carries the per-FIELD-TYPE vocabulary — the filter kinds, the maps from a
/// field's type to the reading it is guarded under, the direction a term runs in. This is a
/// per-ENTITY fact, and every name in it is a projection of the entity binding, so it lives with
/// the binding as [`Record`] does.
///
/// # Two members are BOUNDED and one is BARE, and the line between them is the BACKEND
///
/// [`Transformer`]'s members are bound by nothing, because what each must satisfy differs per use
/// site and is asked there. [`Input`](Self::Input) and [`Output`](Self::Output) do not: what they
/// must satisfy is [`GraphqlInput`] and [`GraphqlOutput`], two traits of this crate's own that name
/// no library at all — the whole content of those two slots is WHICH TWO FACES, and a face that
/// answered no face questions would be a name with nothing behind it. Bounding them here is also
/// what makes the slot a bundle rather than two more open members — a party writing
/// `T: Transformer<Graphql: Graphql>` reaches the filter in one projection, with no second bound to
/// restate.
///
/// [`Query`](Self::Query) is BARE, and that is the same law read at the one member whose bound
/// would have named a LIBRARY. A query unit is mounted by one GraphQL backend's root, so
/// *`ObjectType` and `Default`* is async-graphql's question rather than this trait's — and a
/// backend-neutral floor that named async-graphql would put a second GraphQL library out of reach
/// of the very seat it has to bind. The requirement is asked at the CONSUMER instead: the emitted
/// root projects `<<E as Transformer>::Graphql as Graphql>::Query` inside its own backend's feature
/// gate, where a unit lacking that backend's citizenship is `E0277` at the projection. A different
/// backend's root builder asks its own traits of the same bare seat.
///
/// # Examples
///
/// A record's wire face, and the two halves reached through it:
///
/// ```
/// use ingraph::{Graphql, GraphqlInput, GraphqlOutput};
///
/// struct Keyframe;
///
/// #[derive(Debug, Default, PartialEq)]
/// struct KeyframeFilter;
/// #[derive(Debug, PartialEq)]
/// enum KeyframeOrderBy {
///   Ordinal,
/// }
/// #[derive(Debug, PartialEq)]
/// struct KeyframeKeyOutput;
///
/// struct KeyframeInput;
/// struct KeyframeOutput;
///
/// impl GraphqlInput for KeyframeInput {
///   type Filter = KeyframeFilter;
///   type OrderBy = KeyframeOrderBy;
/// }
///
/// impl GraphqlOutput for KeyframeOutput {
///   type Key = KeyframeKeyOutput;
/// }
///
/// impl Graphql for Keyframe {
///   type Input = KeyframeInput;
///   type Output = KeyframeOutput;
///   type Query = ();
/// }
///
/// fn sent<T: Graphql>(filter: <T::Input as GraphqlInput>::Filter) -> <T::Input as GraphqlInput>::Filter {
///   filter
/// }
///
/// assert_eq!(sent::<Keyframe>(KeyframeFilter), KeyframeFilter);
/// ```
///
/// An entity that declares no face implements nothing here, and `()` answers nothing in its place:
///
/// ```compile_fail,E0277
/// use ingraph::Graphql;
///
/// fn has_a_face<T: Graphql>() {}
/// has_a_face::<()>();
/// ```
#[diagnostic::on_unimplemented(
  message = "`{Self}` declares no wire face — there is no `graphql(…)` block, so nothing was \
             written for a client to speak to",
  label = "no wire face",
  note = "an entity earns one by declaring it: `#[ingraph(graphql(async_graphql))]`"
)]
pub trait Graphql {
  /// The INPUT half: what a client SENDS.
  type Input: GraphqlInput;

  /// The OUTPUT half: what a client RECEIVES.
  type Output: GraphqlOutput;

  /// The QUERY UNIT — this record's own root fields, as one mountable value.
  ///
  /// The trio a record answers at the root of a schema: one row by its id, a page of them, and the
  /// walk under one ancestry. They are emitted TOGETHER, on one type, because a root assembles
  /// UNITS rather than fields — the fold that builds a graph's root query names one type per
  /// member, and a member per resolver would make the root's arity the schema's field count.
  ///
  /// `()` where the declaration has no root fields to offer — a record with a wire face and no
  /// stored query lane receives it, exactly as [`Transformer::Record`] receives it for a record
  /// stored nowhere. It is an answer rather than a placeholder, and it is the one a root's own
  /// membership is measured against: the empty product mounts on no schema, so a graph that
  /// projected it would be refused at the projection rather than served an object with no fields.
  ///
  /// # Bound by NOTHING, and the seat is backend-neutral for it
  ///
  /// See the trait's own note. What a query unit must satisfy — `ObjectType`, `Default`, whatever a
  /// second library asks — is a fact about the ROOT that mounts it, so it is written at the root
  /// and not here.
  type Query;
}

/// The input half of a wire face — the types a client writes a query's arguments in.
///
/// Two members today and additive after: a page-argument bundle and whatever else the wire round
/// asks for arrive here rather than on [`Graphql`], because they are arguments and not faces.
pub trait GraphqlInput {
  /// The PREDICATE a client sends against this record, and the type a neighbour's NESTED position
  /// takes when it constrains this one.
  ///
  /// One per RECORD rather than one per database, because a schema varying with a deployment's
  /// storage choice would be a schema no client could hold against two deployments. Its resolution
  /// IS per database — it crosses into each [`Record::Comparison`] — and that crossing is the single
  /// place storage enters.
  type Filter;

  /// The ORDER a client asks for — the WIRE order, one word per citizen.
  ///
  /// One per RECORD rather than one per database, for [`Filter`](Self::Filter)'s reason and with the
  /// same consequence: a schema varying with a deployment's storage choice would be a schema no
  /// client could hold against two deployments. Its resolution IS per database — it crosses into
  /// each [`Record::OrderBy`] — and that crossing is the single place storage enters.
  ///
  /// # This member used to bind the STORAGE term too, and the door that repealed it is below
  ///
  /// The law here read *the two faces bind one type*, and its argument was pushability: an order
  /// that participates in PAGINATION must live entirely in the statement, so every variant a client
  /// can name has to be one the engine can push — a wire variant honoured in memory would put a sort
  /// between the database's `LIMIT` and the page's delivery, which loses rows silently. **That
  /// argument still holds and is not what changed.** Every variant a client can name is still
  /// pushable, and a variant that were not would still be refused.
  ///
  /// What changed is that ONE TYPE was never what pushability required. The old law's own escape
  /// clause said so: *should a wire-only variant ever be wanted, it arrives as a type of its own with
  /// a conversion INTO the storage term*. A CITIZEN is that case, arriving from the other direction.
  /// `at: MediaTimestamp` is one word on the wire and FOUR columns in a statement, in a sequence the
  /// citizen decides — so the wire term and the storage order were already two different things, and
  /// binding them to one type meant the wire published the storage's shape or the storage was held to
  /// the wire's. The conversion the clause reserved is [`FromGraphqlOrderBy`](crate::FromGraphqlOrderBy),
  /// and this member is the wire half of the pair it now crosses.
  ///
  /// So the promise this member makes is narrower and truer than the one it made: every variant here
  /// is a word the engine can push, and WHAT it pushes is [`Record::OrderBy`]'s answer.
  type OrderBy;
}

/// The output half of a wire face — the types a client receives a result in.
///
/// One member today. The row object a client receives for the record's own fields is authored
/// per-field and has no asker here yet; the ADDRESS does, because the search envelopes derive their
/// wire shape from it.
pub trait GraphqlOutput {
  /// The record's ADDRESS on the wire — what a search or knn hit renders into.
  ///
  /// A projection of the key's columns rather than the key itself: a key holds the declaration's own
  /// types, and this holds what a schema can name.
  type Key;
}

/// **THE EMPTY PRODUCT IS A FACE WITH NO REQUEST SIDE**, and it is an ANSWER rather than a
/// placeholder — the same statement `Graphql::Query = ()` and `GraphqlOutput::Key = ()` already
/// make at their own members.
///
/// A RETRIEVING declaration is the case it exists for. A `vector` or `fulltext` node is not asked by
/// predicate and not ordered by column: its whole request surface is the question and options
/// packages its own fusion tree mints, and its whole answer surface is the hits its doors hand back.
/// So the two halves a RECORD's face is built around have nothing to name here, and the member that
/// carries this kind's citizenship is [`Graphql::Query`] alone.
///
/// Written at the framework rather than minted per declaration, because a type whose only content is
/// *there is nothing here* would be one more name in every declaring scope, one more row in every
/// rename roster, and one more collision for an author to hit — for a fact the empty product already
/// states.
impl GraphqlInput for () {
  type Filter = ();
  type OrderBy = ();
}

/// The output half of the same statement — see [`GraphqlInput for ()`](GraphqlInput#impl-GraphqlInput-for-()).
impl GraphqlOutput for () {
  type Key = ();
}

/// WHICH of `Self`'s fields point at `Target` — the one relation fact no projection can answer.
///
/// A record's `#[ingraph(ref = "…")]` fields carry `<Target as Identifiable>::Id` — an id being a
/// TABLE-WIDE address, because every table's is unique — so the TYPES of a relation are already
/// reachable from the entity binding: what is not reachable is which columns hold them, because
/// nothing about `Target` knows who points at it. That is what this carries, and it carries nothing
/// else.
///
/// # ONE impl per (source, target) PAIR
///
/// A record referring to `Target` through two fields gets ONE impl whose [`Fields`](Self::Fields)
/// has two members — not two impls, which would be `E0119`. The pair is the unit of the fact
/// because it is the unit of the QUESTION: a reverse position names a source and a target and asks
/// how they meet, and *through several fields* is an answer rather than a conflict.
///
/// Two DECLARED spellings of one type — `media::Video` beside a `use`d `Video` — are two impls of
/// one pair, and that one IS `E0119`. A declaration writes the target once, and the emitter has
/// tokens rather than types, so nothing here can see that the two spellings meet.
///
/// # What the reverse side reads
///
/// A reverse position — `derived(tracks = "media::VideoTrack")` on the target — is declared in a
/// derive that cannot see the source's declaration, so the audits it emits read this impl instead:
/// the shorthand requires [`Fields`](Self::Fields) to be a [`OneReference`], and the full form's
/// `field = "…"` is checked against [`COLUMNS`](Self::COLUMNS). Absence of the impl is the first
/// refusal of both, and it says the source names no `ref` at this record.
#[diagnostic::on_unimplemented(
  message = "`{Self}` declares no `ref` field naming `{Target}` — a reverse position names a record \
             whose own declaration points back at this one",
  label = "nothing in `{Self}` refers to `{Target}`",
  note = "the forward half is `#[ingraph(ref = \"…\")]` on the field of `{Self}` that carries \
          `{Target}`'s id"
)]
pub trait Related<Target> {
  /// The referring fields as a type-level LIST — one [`Reference`] per `ref` field, in the order
  /// the declaration wrote them.
  ///
  /// A TUPLE, because the one question asked of it is an ARITY question and a tuple answers that in
  /// the type system: `(F,)` is a [`OneReference`] and `(F, G)` is not, so a reverse shorthand's
  /// refusal is a trait bound rather than a count somebody has to carry. A slice-shaped const could
  /// hold the same list and could not be bounded.
  ///
  /// The members are minted BY THE EMISSION, one per field, and named after the field — so the
  /// tuple prints as the refusal's own evidence.
  type Fields;

  /// WHICH of the source's fields refer to the target, by the names its declaration wrote, in
  /// [`Fields`](Self::Fields)' order.
  ///
  /// Beside the type-level list rather than instead of it, because the two answer different
  /// questions: the list answers *how many*, which is a bound, and this answers *which*, which is a
  /// string a declaration wrote — `derived(tracks(type = "…", field = "video_id"))` selects by name,
  /// and a name is not a type on stable Rust.
  ///
  /// # It is MEMBERSHIP evidence and no longer a naming authority
  ///
  /// It used to be the only publisher of a `ref` field's declared name, standing parallel to a row's
  /// stored one — two lists for one field, and no way across between them. The crossing is published
  /// now, by the row: [`ColumnName`](crate::ColumnName) carries both halves and
  /// [`stored_column`](crate::stored_column) is the lookup, per database. So nothing reads this const
  /// for a name to RENDER, and a lowering that wants the column this database stores asks the row.
  ///
  /// What is left here is the fact the row cannot state: a row's columns are all of them, and this is
  /// the SUBSET that points at `Target`. That is what the full form's audit spends — `field = "title"`
  /// names a real column and refers to nothing — so the list stays, narrowed to the one question no
  /// other publisher answers.
  const COLUMNS: &'static [&'static FieldName];
}

/// ONE `ref` field, as a type — a member of [`Related::Fields`].
///
/// A marker, and its whole content is that it stands for a field a declaration wrote. There is
/// nothing on it because nothing asks yet: the names are on [`Related::COLUMNS`], the target's types
/// are [`Transformer`]'s, and this crate takes an item when something live asks rather than when
/// something plausibly will.
///
/// It is a TYPE rather than a const so that what does arrive can hang off it.
///
/// # The stored name per database is NOT one of the things that will arrive here
///
/// This note used to say a relation's lowering *will want each field's stored name per database*,
/// and name that as a seam this marker would grow. It is not one: the name is already published, one
/// hop past where the search for it used to stop.
///
/// ```text
/// <<Source as Record<Db>>::Row as SqlQuery<Db>>::COLUMNS
/// ```
///
/// [`Record::Row`] is the pairing — a row name ASKED FOR rather than rebuilt — and its
/// [`COLUMNS`](crate::query::sql::SqlQuery::COLUMNS) are per DATABASE, so a source stored in three
/// answers three names for one field. [`stored_column`](crate::stored_column) is the lookup over
/// them, and what it hands back is exactly what
/// [`SqlDerivedComparison::new`](crate::comparison::sql::SqlDerivedComparison::new) takes. So the
/// evidence a reverse position spends is the pairing's, not this marker's, and a per-field const here
/// would be a second copy of a fact the row already states per database.
///
/// **That last hop is closed too, and the key was where it was open**: the list used to be keyed by
/// the name the DATABASE sees, so a reverse declaration holding the name its author WROTE could not
/// probe it. Each entry now carries both — [`ColumnName`](crate::ColumnName) — and
/// [`stored_column`](crate::stored_column) takes the declared half and answers the stored one, per
/// database. A source stored in two dialects under two spellings is one lookup either way.
///
/// Whether the position is one-valued or many-valued is still a per-field fact with no publisher, and
/// adding one here is additive where widening a const would not be.
///
/// The bound [`OneReference`] states over it is what the marker is FOR today: a `Fields` that is a
/// one-tuple of something else is not a relation with one field, and the audit says so.
pub trait Reference {}

/// A [`Related::Fields`] with exactly ONE member — what a reverse position's shorthand requires.
///
/// `derived(tracks = "media::VideoTrack")` names a source and no field, so it is answerable only
/// when the source points back through one field. Two `ref`s at one record make the shorthand
/// ambiguous, and the ambiguity is refused HERE — at the reverse declaration, where the shorthand
/// was written — rather than resolved by an order nobody declared.
///
/// # Examples
///
/// One field is one reference:
///
/// ```
/// use ingraph::{OneReference, Reference};
///
/// struct VideoTrackVideoRef;
/// impl Reference for VideoTrackVideoRef {}
///
/// fn shorthand_reaches<F: OneReference>() {}
/// shorthand_reaches::<(VideoTrackVideoRef,)>();
/// ```
///
/// Two are not, and the refusal names them:
///
/// ```compile_fail,E0277
/// use ingraph::{OneReference, Reference};
///
/// struct VideoTrackVideoRef;
/// struct VideoTrackCoverRef;
/// impl Reference for VideoTrackVideoRef {}
/// impl Reference for VideoTrackCoverRef {}
///
/// fn shorthand_reaches<F: OneReference>() {}
/// shorthand_reaches::<(VideoTrackVideoRef, VideoTrackCoverRef)>();
/// ```
#[diagnostic::on_unimplemented(
  message = "a reverse position's shorthand takes the ONE field that points back, and several \
             point here: `{Self}`",
  label = "name the field: `derived(<name>(type = \"…\", field = \"…\"))`",
  note = "each member of this list is one `ref` field of the source, named after it"
)]
pub trait OneReference {}

/// A list of one is one reference. The member's own bound is what keeps the answer about
/// RELATIONS: a one-tuple of anything else is a one-tuple and not a relation with one field.
impl<F: Reference> OneReference for (F,) {}

/// The forward id equation, as a bound an expansion instantiates: a `ref` field carries the
/// target's ID.
///
/// The ID rather than the key, because a field is ONE COLUMN and a key need not be one: a
/// lineage-bearing record's key is the whole ancestry path, so no single column could hold it. What
/// makes the id enough to address by is the storage law beside this one — every table's id is
/// UNIQUE, so an id names one row of its table and not one row per parent.
///
/// Emitted rather than written — `ingraph-derive` names it once per `ref` field, with the field's
/// type (through the collection or optional projection where the declaration puts the field in one)
/// and the target the declaration named. What a reader gets when the two disagree is `E0271` naming
/// both, at the `ref` that claimed them equal.
///
/// A free function rather than a trait, because the equation IS an equation: a trait would need a
/// blanket impl whose own where clause carried the same projection equality, which is the error
/// rustc would report anyway — one indirection for no sentence.
///
/// The bound names [`Identifiable`] and not [`Transformer`], because the id is the whole of what the
/// equation spends: a target's key, lineage and row form say nothing about the column pointing at
/// it. What a reader gets from the smaller bound is a refusal naming the capability that failed
/// rather than the entity binding that carries it.
///
/// # Examples
///
/// A field holding the target's id satisfies it:
///
/// ```
/// use ingraph::{Identifiable, refers_to};
///
/// struct Media(u64);
///
/// impl Identifiable for Media {
///   type Id = u64;
///
///   fn id_ref(&self) -> &u64 {
///     &self.0
///   }
/// }
///
/// refers_to::<u64, Media>();
/// ```
///
/// A field holding the target's KEY does not — one column cannot hold an ancestry path:
///
/// ```compile_fail,E0271
/// use ingraph::{Identifiable, refers_to};
///
/// struct Media(u64);
/// struct MediaKey(u64);
///
/// impl Identifiable for Media {
///   type Id = u64;
///
///   fn id_ref(&self) -> &u64 {
///     &self.0
///   }
/// }
///
/// refers_to::<MediaKey, Media>();
/// ```
pub fn refers_to<Field, Target>()
where
  Target: Identifiable<Id = Field>,
{
}

/// THE FIVE BOUNDS AN ID OWES, as a bound an expansion instantiates: an id can be a KEY.
///
/// The user's ruling of 2026-08-12, on whether the batching seam should ask for these or a
/// declaration should owe them: *强制* — *id有这些属性应该是必须的*. So they are owed, and owed at
/// the DECLARATION rather than at whichever consumer first needs one.
///
/// # Why an id is a key, and why that is not a fact about batching
///
/// [`Identifiable::Id`] is *the ONE column this value is addressed by*, and an address is what
/// parties correlate on: a batch dedups keys before asking and fans one answer back to each asker,
/// a hydration re-associates rows with what it asked for, a cache indexes by it, and a spawned
/// flush carries it across a thread. `Hash + Eq` is being correlatable, `Clone` is being duplicable
/// to the askers that shared a batch, and `Send + Sync` is crossing the boundary an injected
/// spawner puts in the middle. An address that could do none of those would still address a row —
/// and could not be used by anything holding more than one at a time.
///
/// # It is demanded HERE so that it is not demanded LATER
///
/// A record whose id lacked these would compile, publish a schema, answer documents, and refuse at
/// the line an application wrote to install a batch door over it — with the bound named in the
/// application's file rather than at the declaration that owes it. Instantiating the obligation at
/// the expansion moves that refusal to the `id` field, which is where it can be acted on.
///
/// Measured before it was mandated: the sealed [`Id`](crate::Id) vocabulary — text, the integer
/// widths, `uuid::Uuid` and [`TypedId`](crate::TypedId) over any of them — satisfies all five, so
/// the mandate costs the corpus nothing and pins the future.
///
/// # `'static` is NOT among them
///
/// Five bounds were ruled and five are asked for. A coalescing engine wants a sixth, its spawned
/// flush owning the keys it carries; that one is demanded at the binding's own impl, which is the
/// position that spends it. A declaration cannot carry a borrowed id in any case — the derive
/// refuses a generic declaration outright — so the difference is where a refusal reads rather than
/// what compiles.
///
/// # Examples
///
/// ```
/// use ingraph::ids_are_keys;
///
/// ids_are_keys::<u64>();
/// ids_are_keys::<String>();
/// ids_are_keys::<uuid::Uuid>();
/// ```
///
/// A type nothing can correlate on is refused:
///
/// ```compile_fail,E0277
/// use ingraph::ids_are_keys;
///
/// ids_are_keys::<f64>();
/// ```
pub fn ids_are_keys<Id>()
where
  Id: core::hash::Hash + Eq + Clone + Send + Sync,
{
}

/// The reverse shorthand's audit, as a bound an expansion instantiates: `Source` points back at
/// `Target` through exactly one field.
///
/// TWO bounds in one entry point rather than two entry points, because they are one question asked
/// in order and only one of them can be answered at a time: a source that refers to nothing has no
/// [`Related::Fields`] to count, so the first refusal is the only one a reader is shown.
///
/// # Examples
///
/// ```
/// use ingraph::{FieldName, OneReference, Reference, Related, one_field_points_back};
///
/// struct Video;
/// struct VideoTrack;
/// struct VideoTrackVideoRef;
///
/// impl Reference for VideoTrackVideoRef {}
///
/// impl Related<Video> for VideoTrack {
///   type Fields = (VideoTrackVideoRef,);
///   const COLUMNS: &'static [&'static FieldName] = &[FieldName::new("video_id")];
/// }
///
/// one_field_points_back::<VideoTrack, Video>();
/// ```
///
/// A source that names this record nowhere is refused, and so is one that names it twice:
///
/// ```compile_fail,E0277
/// use ingraph::one_field_points_back;
///
/// struct Video;
/// struct Caption;
///
/// one_field_points_back::<Caption, Video>();
/// ```
pub fn one_field_points_back<Source, Target>()
where
  Source: Related<Target>,
  Source::Fields: OneReference,
{
}

/// Whether `columns` holds `field` — the reverse FULL form's audit, in a `const`.
///
/// `derived(tracks(type = "…", field = "video_id"))` selects a referring field BY NAME, and a name
/// is not a type: there is no bound to write, so the check is a constant evaluation over
/// [`Related::COLUMNS`] and its refusal is `E0080` carrying the emitter's own sentence. That is the
/// same position [`SlotName::new`](crate::SlotName::new)'s refusal already occupies — a fact known
/// at compile time, checked where it is declared.
///
/// # Examples
///
/// ```
/// use ingraph::{FieldName, refers_through};
///
/// const COLUMNS: &[&FieldName] = &[FieldName::new("video_id"), FieldName::new("cover_id")];
///
/// const _: () = assert!(refers_through(COLUMNS, "cover_id"));
/// const _: () = assert!(!refers_through(COLUMNS, "media_id"));
/// ```
#[must_use]
pub const fn refers_through(columns: &[&FieldName], field: &str) -> bool {
  let mut at = 0;
  while at < columns.len() {
    if same(columns[at].as_str(), field) {
      return true;
    }
    at += 1;
  }
  false
}

/// Two strings, compared in a `const`. `str`'s own [`PartialEq`] is not one, and the audit above
/// runs nowhere else.
const fn same(one: &str, other: &str) -> bool {
  let (one, other) = (one.as_bytes(), other.as_bytes());
  if one.len() != other.len() {
    return false;
  }
  let mut at = 0;
  while at < one.len() {
    if one[at] != other[at] {
      return false;
    }
    at += 1;
  }
  true
}

/// The MEMBERSHIP evidence: `Member` is one of `Interface`'s members.
///
/// # It is DECLARED at the member, and it has to be
///
/// An interface's declaration names its members, and that alone is not evidence: the two derives
/// cannot see each other, so an interface asserting `Video: Implements<Media>` over a `Video` whose
/// own declaration never agreed would be an interface claiming a promise on somebody else's behalf.
/// The record says `implements(Media)` and this impl is what the word emits; the interface asserts
/// the bound. Absence of the impl is the refusal, and it lands at the interface — naming the member
/// that did not agree.
///
/// The same two-derives-one-fact shape [`Related`] already carries, one direction shorter: a
/// relation needs the referring FIELDS crossing the boundary, and a membership needs only the fact.
/// So there is nothing on this trait — no associated type, no const — and that is a measurement
/// rather than a stub: what an interface asks of a member beyond membership is the member's own
/// ROW, which is `Record<Db>`'s and is asked there.
///
/// A trait rather than a free equation, because it is a FACT a declaration states rather than a
/// projection two types have to agree on. [`refers_to`] is the other shape, and the difference is
/// that nothing about `Video` could ever imply its membership: only the declaration knows.
#[diagnostic::on_unimplemented(
  message = "`{Self}` is not a member of `{Interface}` — a member is a record whose OWN declaration \
             says so",
  label = "`{Self}` declares no `implements({Interface})`",
  note = "the member half is `#[ingraph(implements(…))]` on the record, naming this interface"
)]
pub trait Implements<Interface> {}

/// The membership tie, as a bound an expansion instantiates: `Member` really is one.
///
/// Emitted rather than written — an interface names it once per member — and what a reader gets
/// when a record was never told is `E0277` carrying [`Implements`]' own sentence, at the interface
/// that claimed it.
///
/// # Examples
///
/// ```
/// use ingraph::{Implements, implements};
///
/// struct Media;
/// struct Video;
///
/// impl Implements<Media> for Video {}
///
/// implements::<Video, Media>();
/// ```
///
/// A record that never agreed is refused:
///
/// ```compile_fail,E0277
/// use ingraph::implements;
///
/// struct Media;
/// struct Caption;
///
/// implements::<Caption, Media>();
/// ```
pub fn implements<Member, Interface>()
where
  Member: Implements<Interface>,
{
}

/// The v1 MEMBERSHIP FENCE, as a bound an expansion instantiates: a member is a STORED record.
///
/// An interface's contract is a promise about ROWS — every member carries these columns, at these
/// types — so a member that becomes no row has nothing for the promise to be about.
/// [`Transformer::Record`] is `Self` exactly where a declaration persists and `()` where it does
/// not, so the equality is the whole test.
///
/// It is a FENCE rather than a law. A vector index and a full-text index are member-shaped too —
/// they subscribe to a record and share its key — and an interface over those is the FUSION layer's
/// question: what a hit from one and a hit from the other have in common is a score and an address
/// rather than a column. Nothing in this round answers it, so nothing in this round admits one, and
/// the refusal says which round does.
///
/// Emitted BEFORE the contract's own impls, so a member that is not a record is told that rather
/// than being told about a field it does not have.
///
/// # Examples
///
/// ```
/// use ingraph::{Identifiable, Transformer, stores_rows};
///
/// struct Video(u64);
///
/// impl Identifiable for Video {
///   type Id = u64;
///
///   fn id_ref(&self) -> &u64 {
///     &self.0
///   }
/// }
///
/// impl Transformer for Video {
///   type Key = u64;
///   type Lineage = ();
///   type Record = Self;
///   type Graphql = ();
///
///   fn key(&self) -> u64 {
///     self.0
///   }
/// }
///
/// stores_rows::<Video>();
/// ```
///
/// An entity that persists nowhere binds `()` and is refused:
///
/// ```compile_fail,E0271
/// use ingraph::{Identifiable, Transformer, stores_rows};
///
/// struct Caption(u64);
///
/// impl Identifiable for Caption {
///   type Id = u64;
///
///   fn id_ref(&self) -> &u64 {
///     &self.0
///   }
/// }
///
/// impl Transformer for Caption {
///   type Key = u64;
///   type Lineage = ();
///   type Record = ();
///   type Graphql = ();
///
///   fn key(&self) -> u64 {
///     self.0
///   }
/// }
///
/// stores_rows::<Caption>();
/// ```
pub fn stores_rows<Member>()
where
  Member: Transformer<Record = Member>,
{
}

/// The WIRE-FACE tie, as a bound an expansion instantiates: a member has one.
///
/// An interface's own output is what wraps its members' outputs, and a member's derivations are
/// declared over that output rather than over the domain type — so a member rendering nothing has
/// no face for either to reach. [`Transformer::Graphql`] is `()` where a declaration writes no
/// `graphql(…)` block, and `()` implements [`Graphql`] for nobody, which is what makes the absence
/// a refusal rather than a projection that is well formed and fails later.
///
/// The bound is written as the PROJECTION and never as a name: `<M as Transformer>::Graphql` is how
/// a member's wire face is reached, and a convention-built `<M>GraphqlOutput` would be a second
/// spelling of a name the member's own declaration may have moved.
///
/// # Examples
///
/// ```compile_fail,E0277
/// use ingraph::{Identifiable, Transformer, has_a_wire_face};
///
/// struct Caption(u64);
///
/// impl Identifiable for Caption {
///   type Id = u64;
///
///   fn id_ref(&self) -> &u64 {
///     &self.0
///   }
/// }
///
/// impl Transformer for Caption {
///   type Key = u64;
///   type Lineage = ();
///   type Record = Self;
///   type Graphql = ();
///
///   fn key(&self) -> u64 {
///     self.0
///   }
/// }
///
/// has_a_wire_face::<Caption>();
/// ```
pub fn has_a_wire_face<Member>()
where
  Member: Transformer<Graphql: Graphql>,
{
}