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
//! What an INTERFACE answers a query with: [`SqlInterface`], the arm facts a union statement is
//! assembled from.
//!
//! # The binding is on the INTERFACE and the database is its parameter, which is the other way round
//! from a record's
//!
//! [`SqlQuery`](super::SqlQuery) is implemented on the ROW, because a row IS one database — so the
//! dialect stays open and a declaration storing one dialect never has to name it. An interface has
//! no row of its own to be one database; what varies per database is its PROJECTION, which is an
//! associated type here. So the impl names a CONCRETE backend, one per database the declaration is
//! about, and rides that database's conditional-expansion gate — the arrangement the interface's
//! row equations already have, stated one layer up.
//!
//! # FACTS, and no SQL text
//!
//! What a derive can know is the interface's own contract: which members there are, what each of
//! them calls each shared column, and — through the member's own binding — where that member's rows
//! live. What it cannot know is how a statement is assembled out of those, which is the engine's and
//! changes with the engine. So this trait carries the facts and the engine writes the statement:
//!
//! ```text
//! SELECT "title" AS "title", "flags" AS "mask", 'audio' AS "__kind", "id" FROM "audio"
//!         └── InterfaceColumn ──┘               └ InterfaceKind ┘      │     └ address().table()
//!                                                                      └── address().keys()
//! ```
//!
//! # The member's TABLE is asked for, never restated
//!
//! [`address`](SqlInterface::address) reaches `<<M as Record<Db>>::Row as SqlQuery<Db>>::ADDRESS`,
//! which is the member's own declaration answering where its rows live. An interface that carried a
//! copy would be a second spelling of a name `<db>(table = "…")` can move — and it is
//! reachable exactly because [`Record<Db>::Row`](crate::Record::Row) is the per-`(record, database)`
//! pairing that names a target's row: the same projection the row equations read a member's columns
//! through.
//!
//! # ORDERING is not a second trait here, and the tail is why
//!
//! A record splits [`SqlQuery`](super::SqlQuery) from [`SqlOrdering`](super::SqlOrdering), because a
//! record with no order-by type has nothing to write a term with and `.order(…)` should be a missing
//! impl rather than a runtime refusal. An interface has no such state: its total order ENDS in the
//! two synthesized tail terms whatever the client wrote, so every interface has an order and every
//! interface's page resumes. There is nothing for a second trait to be absent for, so the cursor
//! value and the row's projection into one sit here beside the arms.

use core::marker::PhantomData;

use smol_bytes::Utf8BytesMut;

use super::{
  BeginRead, SqlDialect, SqlQueryError,
  snapshot::{close_read, open_read},
};
use crate::{
  ComplexComparison, Cursor, CursorValue, FieldName, InterfaceArm, InterfaceKind, OrderTerm,
  RecordAddress, TermName, Walk,
  comparison::{
    At, Backend,
    sql::{
      Carrier, QueryBuilder, SelectClause, SqlConjunction, SqlKeyset, SqlLoweringError, SqlOrder,
      TermColumns, push_quoted_ident, push_quoted_scope,
    },
  },
  interface::ID,
  query::{DEFAULT_PAGE_SIZE, Edge, MAX_PAGE_SIZE, Page, partition},
};

/// One interface, as the engine queries it in ONE database.
///
/// # What a union needs, and nothing more
///
/// The member vocabulary, the projection its rows decode into, and one ARM per member: which member
/// it reads, and what that member calls each shared column. Everything else the statement renders is
/// asked of the member's own binding through [`address`](Self::address).
///
/// # The arms are a `const`, so nothing builds one per query
///
/// [`InterfaceArm::new`] and [`InterfaceColumn::new`] are `const` and the lists are `&'static`,
/// which is the shape that makes an interface's arms an ITEM — the argument
/// [`RecordAddress`]'s own `'static` key list already carries one layer down.
pub trait SqlInterface<Db: Backend + sqlx::Database>: Sized + 'static {
  /// Which member a row came from.
  ///
  /// One vocabulary per INTERFACE rather than one per (interface, database), which is what makes a
  /// cursor minted against one deployment replayable against another: the word is the member's own
  /// and nothing about storage can move it. See [`InterfaceKind`] for why it is not a table's name.
  type Kind: InterfaceKind;

  /// The interface's OWN projection in this database — what every arm's rows decode into.
  ///
  /// Not any member's row. A member's row is that member's whole table; this is the shared columns
  /// under the interface's names, at the types the interface pinned, plus the discriminant.
  ///
  /// Bound by nothing here, for the reason [`Record::Row`](crate::Record::Row) is: what a projection
  /// must satisfy is the DECODE's question — `FromRow` at this dialect — and it is asked where that
  /// decode is bound.
  type Row: 'static;

  /// The predicate a filter over the interface's own vocabulary crosses into at this database.
  ///
  /// The INTERFACE's rather than any member's, and that is the whole of what the union's wrapper
  /// buys: a shared column is called something else in some member's table, and every arm has
  /// already aliased its own column to the interface's name — so one predicate, over the aliased
  /// projection, answers whichever member the row came from.
  type Comparison: ComplexComparison<Db>;

  /// One slot of a cursor over this interface's page — a shared column's value, or the address.
  ///
  /// A sum for [`SqlOrdering::Value`](super::SqlOrdering::Value)'s reason, at one more width: a
  /// cursor's frame is ONE type across its slots, and an interface's slots are its shared columns
  /// PLUS the two synthesized tail terms. The members need not agree about what an id is, so the
  /// address slot is a sum in its own right.
  type Value: Carrier<Db> + CursorValue + Clone;

  /// One ordering term a client may write over this interface: which SHARED column, and which way
  /// it runs.
  ///
  /// The INTERFACE's vocabulary and never a member's. A client ordering a union has no member to
  /// name a column of — the statement projects the interface's own names — so the terms it may
  /// write are exactly the shared columns, and a member's private column is unorderable here
  /// because it is not part of what the interface promised.
  ///
  /// `Clone` for [`SqlOrdering::Order`](super::SqlOrdering::Order)'s reason at this width and no
  /// more: an interface's term is a column and a direction today, and the engine clones one per
  /// statement rather than per row.
  type Order: Clone;

  /// One arm per member, in DECLARATION order.
  ///
  /// Declaration order rather than sorted order, so an expansion is stable and diffable. Nothing
  /// reads it as an ordering: what a statement sorts by is the projected word, and the arms are the
  /// set of members rather than a sequence with meaning.
  const ARMS: &'static [InterfaceArm<Self::Kind>];

  /// The column every arm projects its DISCRIMINANT under, in this database.
  ///
  /// [`interface::KIND`](crate::interface::KIND) unless the declaration moved it, which
  /// `<db>(alias(prefix = "…"))` is what does — the same knob that moves a record's
  /// row-source names, spent on the words a union statement invents. It is defaulted here because
  /// the default is what nearly every binding states and a hand-written one should not have to.
  ///
  /// PER DATABASE, and the interface's own [`Kind`](Self::Kind) is not: what a cursor freezes is the
  /// member's WORD, which is the same word in every deployment, while this is the column that word
  /// arrives under — see [`total_order`], where the term's rename-proof identity stays put and only
  /// the column moves.
  const KIND: &'static FieldName = crate::interface::KIND;

  /// The name the outer query gives the derived table it selects the union from, in this database.
  ///
  /// [`interface::SOURCE`](crate::interface::SOURCE) unless the same `alias(prefix = "…")` moved it.
  /// A derived table must be named, and the name is synthesized rather than any member's — so it
  /// wears the fence, and a schema that took the fence back moves it too.
  const SOURCE: &'static FieldName = crate::interface::SOURCE;

  /// The derived table as an ADDRESS: the union's own name, keyed by the one output column every arm
  /// projects its member's address under.
  ///
  /// Defaulted over [`SOURCE`](Self::SOURCE), which is the only implementation the item admits. It
  /// names an ALIAS rather than a table — the one use [`RecordAddress`]'s own note admits, *the
  /// table is named as the enclosing `FROM` names it* — and nothing correlates a dependent table off
  /// it, which is what that note warns an alias would break.
  const UNION: RecordAddress = RecordAddress::new(Self::SOURCE, &[ID]);

  /// The discriminant's ORDER TERM, which is the first half of the tail that makes the order total.
  ///
  /// Its identity is `__ig_kind__` WHATEVER the column is called, and that is deliberate: a
  /// [`TermName`] is the rename-proof name a cursor freezes, so a page minted against a deployment
  /// that moved the prefix stays replayable against one that did not. What moves with the prefix is
  /// the column the `ORDER BY` renders.
  const KIND_TERM: OrderTerm = OrderTerm::new(
    TermName::new("__ig_kind__"),
    Self::KIND,
    crate::OrderDirection::Asc,
  );

  /// Where `kind`'s member keeps its rows, and what one of them is addressed by.
  ///
  /// The MEMBER's own answer, reached through its query binding rather than restated here — see the
  /// module note. An interface holds no table of its own to give.
  fn address(kind: Self::Kind) -> RecordAddress;

  /// The table `kind`'s arm selects from.
  ///
  /// Defaulted, and there is no second body to write: it is [`address`](Self::address)'s own table,
  /// and an implementation overriding it would be stating where a member's rows live twice.
  #[inline]
  fn table(kind: Self::Kind) -> &'static FieldName {
    Self::address(kind).table()
  }

  /// The arm reading `kind`'s member, or [`None`] where this binding has none for it.
  ///
  /// Defaulted over [`ARMS`](Self::ARMS), which is the only implementation the item admits.
  /// [`None`] is unreachable through an emitted binding — the vocabulary and the arms are written
  /// from one member list — and it is ANSWERED rather than asserted, because both are a caller's
  /// items in a hand-written one.
  #[inline]
  fn arm(kind: Self::Kind) -> Option<&'static InterfaceArm<Self::Kind>> {
    Self::ARMS.iter().find(|arm| arm.kind() == kind)
  }

  /// The value `row` holds at `term`, or [`None`] where it holds SQL `NULL`.
  ///
  /// # The TAIL is minted from the address, and that is where the one-slot ruling lives
  ///
  /// Two of the terms a page walks are the framework's own: `__ig_kind__` and `id`. Neither is a
  /// column a declaration promised, and both are on the row — the address carries the member's id
  /// and answers WHICH member — so the binding mints both from that one field. A discriminant
  /// carried beside the address rather than read off it is a pair that can disagree, which is the
  /// whole of what folding them into one slot was for.
  ///
  /// # No raw driver row, and no alias
  ///
  /// [`SqlOrdering::value`](super::SqlOrdering::value) takes both, because a record's order may
  /// contain a term whose subject is an EXPRESSION and such a value rides the statement under an
  /// alias the engine wrote. Every term of an interface's order is a COLUMN of the union's own
  /// output — a shared column or one of the tail's two — so the decoded projection answers all of
  /// them and there is nothing for a second reading to be about.
  fn value(row: &Self::Row, term: &OrderTerm) -> Option<Self::Value>;

  /// One written term as the statement renders it: its rename-proof identity, the column the union
  /// projects it under, and the direction it runs in.
  ///
  /// There is no per-database spelling to choose between, which is what makes this one function
  /// rather than one per dialect: an arm has ALREADY aliased its member's column to the interface's
  /// own name, so what the `ORDER BY` names is the interface's name in every database.
  fn term(order: Self::Order) -> OrderTerm;

  /// How many conjuncts `filter`'s COLLECTION columns render for `kind`'s arm.
  ///
  /// Zero by default, and that is what keeps this item free for a binding with no collection: an
  /// interface whose shared columns are all single-valued renders no arm group at all, so the
  /// statement is byte-for-byte what it was before this item existed.
  #[inline]
  fn collection_conjuncts(filter: &Self::Comparison, kind: Self::Kind) -> usize {
    let _ = (filter, kind);
    0
  }

  /// Render `filter`'s COLLECTION columns for `kind`'s arm, at that member's own frame.
  ///
  /// # A collection is the ONE shared column the wrapper cannot lower once
  ///
  /// Every other predicate is written in the interface's vocabulary and applied ONCE above the
  /// union, because every arm has already aliased its member's column to the interface's name. A
  /// collection has no column for an arm to alias — no backend keeps every collection in a column of
  /// the row — so there is nothing in the union's output to compare against, and the predicate has
  /// to reach the member's own EDGE TABLE.
  ///
  /// That table is per member, so the lowering is per arm: the engine walks [`ARMS`](Self::ARMS),
  /// gates each on the discriminant the arm projects, and hands the group here at an [`At::aliased`]
  /// naming the MEMBER's address under the union's own alias. The member's real table is what
  /// `<table>_<field>` derives from, and the union's alias is what the correlation compares against
  /// — the two roles held apart, which is the whole of what that spelling is for.
  ///
  /// # Errors
  ///
  /// Whatever the column's own kind refuses with, carried verbatim.
  #[inline]
  fn collections<'q>(
    filter: &'q Self::Comparison,
    kind: Self::Kind,
    at: At<'_>,
    builder: <Db as Backend>::Builder<'q>,
  ) -> Result<<Db as Backend>::Builder<'q>, <Db as Backend>::Error> {
    let _ = (filter, kind, at);
    Ok(builder)
  }
}

/// The address's term, which is the second half — and the last, an id being `UNIQUE` within its own
/// table and the discriminant telling the tables apart.
const ID_TERM: OrderTerm = OrderTerm::new(TermName::new("id"), ID, crate::OrderDirection::Asc);

/// A written order COMPLETED into a total one: the client's terms, then the discriminant, then the
/// address.
///
/// # The tail is two columns and it takes both
///
/// A record's order completes with its address alone, because an id is `UNIQUE` in its table. An
/// interface's rows come from several tables, so an id names at most one row PER MEMBER and the
/// discriminant is what makes the pair unique — which is also why the discriminant comes FIRST: it
/// is what a page's keyset folds on, and an arm renders it as a literal, so a tail ordered the other
/// way would put a constant below a column that varies.
///
/// A client term already naming one of the two MOVES it rather than repeating it, which is the rule
/// [`SqlOrdering::complete`](super::SqlOrdering::complete) states for a record's own tail.
///
/// # It is the INTERFACE's tail, because the discriminant's column is
///
/// The two terms used to be items of this module, and a declaration that moves its synthetic words
/// is what made them the binding's: `I::KIND_TERM` renders whatever column this deployment projects
/// the discriminant under. The term's own IDENTITY does not move with it — see there — so a cursor
/// is portable across two deployments that spell the column differently.
#[must_use]
pub fn total_order<I, Db>(written: &[OrderTerm]) -> Vec<OrderTerm>
where
  I: SqlInterface<Db>,
  Db: Backend + sqlx::Database,
{
  let tail = [I::KIND_TERM, ID_TERM];
  // The pair (column, LEAF), for the reason the capability frame's repetition scan reads the same
  // pair: a level of an expanded citizen is a column of its own, so a field that happened to share
  // the tail's name would still not be the tail's column at any of its leaves.
  let mut order: Vec<OrderTerm> = written
    .iter()
    .filter(|term| {
      !tail
        .iter()
        .any(|held| held.column() == term.column() && held.leaf() == term.leaf())
    })
    .cloned()
    .collect();
  order.extend(tail);
  order
}

/// The ARMS, as the derived table's body: one `SELECT` per member, joined by `UNION ALL`.
///
/// # It is TEXT, and that is what the arms are
///
/// Every other statement in this engine is assembled through a builder because it carries BINDS, and
/// a placeholder is the one thing text cannot hold. An arm carries none: what it selects is a list of
/// identifiers, a discriminant literal the DECLARATION wrote, and a table name — so the arms are
/// text end to end and the outer statement is the only party with operands in it.
///
/// Every identifier goes through [`quote_ident`], which is the seam that doubles the dialect's quote
/// character; the discriminant is the one value here and it is escaped the same way a string literal
/// must be, by doubling `'`. It cannot need it — a discriminant is a Rust variant snake-cased — and
/// it is escaped anyway, because a hand-written binding is a caller and the framework does not take a
/// caller's word about what a string contains.
fn arms<I, Db>() -> Utf8BytesMut
where
  I: SqlInterface<Db>,
  Db: SqlDialect,
{
  let mut body = Utf8BytesMut::new();
  for (at, arm) in I::ARMS.iter().enumerate() {
    if at > 0 {
      body.push_str(" UNION ALL ");
    }
    body.push_str("SELECT ");
    for column in arm.columns() {
      push_quoted_ident::<Db>(column.column(), &mut body);
      body.push_str(" AS ");
      push_quoted_ident::<Db>(column.field(), &mut body);
      body.push_str(", ");
    }
    push_literal(arm.kind().as_str(), &mut body);
    body.push_str(" AS ");
    push_quoted_ident::<Db>(I::KIND, &mut body);
    body.push_str(", ");
    let address = I::address(arm.kind());
    push_quoted_ident::<Db>(address_column(&address), &mut body);
    body.push_str(" AS ");
    push_quoted_ident::<Db>(ID, &mut body);
    body.push_str(" FROM ");
    push_quoted_ident::<Db>(address.table(), &mut body);
  }
  body
}

/// The COLLECTION half of a filter, as ONE conjunct: a disjunction over the arms, each gated on the
/// discriminant it projects and each correlating that member's own edge tables back to the union.
///
/// ```sql
/// AND (
///      ( "__ig_union__"."__ig_kind__" = 'reel'
///        AND EXISTS (SELECT 1 FROM "reel_marks"
///                     WHERE "reel_marks"."id" = "__ig_union__"."id" AND "reel_marks"."marks" = ?) )
///   OR ( "__ig_union__"."__ig_kind__" = 'take'
///        AND EXISTS (SELECT 1 FROM "take_cues"
///                     WHERE "take_cues"."reel_no" = "__ig_union__"."id" AND "take_cues"."cues" = ?) )
/// )
/// ```
///
/// # Why this is the one predicate the wrapper renders N times
///
/// The union's own note states the rule it is built on: a predicate over the ALIASED projection
/// speaks one vocabulary whatever member answered it, so it is lowered ONCE and its operands bind
/// once. A collection breaks the premise rather than the rule — there is no aliased column to
/// compare, because no backend keeps every collection in a column of the row and the choice is the
/// MEMBER's. So the operands of a collection predicate DO bind once per arm, and nothing else does.
///
/// # The GATE is what keeps an arm's predicate off another arm's rows
///
/// Without it the disjunction would admit a `take` whose id happens to match some reel's marks: the
/// correlation is on the address alone, and two members' ids are two vocabularies. The discriminant
/// is the column that tells them apart, and it is rendered as the arms render it — a literal, with
/// the one character that could close it doubled.
///
/// An arm whose own group is EMPTY contributes its gate alone, which admits that member's rows
/// unfiltered. That is the honest reading — the client asked nothing this arm can be asked — and it
/// is what keeps `( … AND )` unwritable.
///
/// # Errors
///
/// Whatever a column's own kind refuses with, carried verbatim — and nothing is written before the
/// first arm renders, so a refusal leaves the accumulator as it was found.
fn collections<'q, I, Db>(
  filter: &'q I::Comparison,
  mut conjunction: SqlConjunction<'q, Db>,
) -> Result<SqlConjunction<'q, Db>, SqlLoweringError>
where
  I: SqlInterface<Db>,
  Db: SqlDialect,
{
  if I::ARMS
    .iter()
    .all(|arm| I::collection_conjuncts(filter, arm.kind()) == 0)
  {
    return Ok(conjunction);
  }
  let alias = I::SOURCE.as_str();
  let out = conjunction.open();
  out.push("(");
  for (at, arm) in I::ARMS.iter().enumerate() {
    if at > 0 {
      out.push(" OR ");
    }
    out.push("(");
    let mut gate = Utf8BytesMut::new();
    push_quoted_scope::<Db>(alias, I::KIND, &mut gate);
    gate.push_str(" = ");
    push_literal(arm.kind().as_str(), &mut gate);
    out.push(gate.as_str());

    let address = I::address(arm.kind());
    // The member's REAL address, under the union's alias, with its key columns named as the arms
    // project them. Nothing here is derived from the union's own address: `<table>_<field>` extends
    // the member's table, and a name derived from `__ig_union__` would be a table that does not
    // exist — the hazard `SqlInterface::UNION`'s own note warns of.
    let group = SqlConjunction::with_lead(out, " AND ");
    let group = I::collections(
      filter,
      arm.kind(),
      At::aliased(&address, alias, &[ID]),
      group,
    )?;
    let _ = group;
    out.push(")");
  }
  out.push(")");
  Ok(conjunction)
}

/// The ONE column an arm is addressed by.
///
/// The FIRST of the member's own key columns, which is its id — see `SqlQuery::ADDRESS`, where the
/// address collapsed to one column because every table's id is `UNIQUE`. A member declaring a wider
/// physical address contributes its leading column here and the rest are ordinary columns of its
/// row, exactly as a record's lineage is.
fn address_column(address: &RecordAddress) -> &'static FieldName {
  address.keys().first().copied().unwrap_or(ID)
}

/// A SQL string literal, with the one character that could close it doubled.
fn push_literal(value: &str, out: &mut Utf8BytesMut) {
  out.push('\'');
  for character in value.chars() {
    if character == '\'' {
      out.push('\'');
    }
    out.push(character);
  }
  out.push('\'');
}

/// The union statement: every member's rows under the interface's own names, filtered once, ordered
/// totally, and ceilinged.
///
/// ```sql
/// SELECT * FROM (
///     SELECT "title" AS "title", "mask" AS "mask", 'video' AS "__ig_kind__", "id" AS "id"
///       FROM "video"
///   UNION ALL
///     SELECT "title" AS "title", "flags" AS "mask", 'audio' AS "__ig_kind__", "id" AS "id"
///       FROM "audio"
/// ) AS "__ig_union__"
/// WHERE "title" = ?
/// ORDER BY "title" ASC, "__ig_kind__" ASC, "id" ASC
/// LIMIT ?
/// ```
///
/// The derived table is NAMED and its columns are not qualified by that name, and both halves are
/// deliberate: SQLite tolerates an unnamed one where PostgreSQL and MySQL refuse it, so the alias is
/// what makes one rendering portable — and inside the outer query every column is the union's own
/// output, so a qualification would be a name for a row source there is only one of.
///
/// # The filter is lowered ONCE, over the interface's own names
///
/// A member may call a shared column something else, so a predicate written in the interface's
/// vocabulary does not name the columns any single arm's table has. The arms' SELECT is where that
/// is answered — each aliases its member's column TO the interface's name — so a predicate over the
/// ALIASED projection speaks one vocabulary whatever member answered it.
///
/// ONE wrapper around the whole union rather than one per arm, and that is what "lowered once"
/// means literally: a per-arm wrapper would render the predicate N times and bind its operands N
/// times, where this binds them once. The rename therefore never reaches the comparison layer,
/// which is the alternative this shape exists to avoid.
///
/// # The predicate PUSHES, and that is measured rather than assumed
///
/// The wrapper puts the predicate above the union, so whether it reaches the arms is the planner's
/// decision. Put to SQLite 3.51.0 over the two-member corpus with an index on each member's own
/// spelling of the shared column, `EXPLAIN QUERY PLAN` answers:
///
/// ```text
/// |--CO-ROUTINE __ig_union__
/// |  `--COMPOUND QUERY
/// |     |--LEFT-MOST SUBQUERY
/// |     |  `--SEARCH video USING COVERING INDEX video_title (title=?)
/// |     `--UNION ALL
/// |        `--SEARCH audio USING INDEX audio_label (label=?)
/// |--SCAN __ig_union__
/// `--USE TEMP B-TREE FOR LAST 2 TERMS OF ORDER BY
/// ```
///
/// Both arms SEARCH rather than SCAN, each through its OWN column's index — `title` on one and
/// `label` on the other — so the predicate written once in the interface's vocabulary reaches both
/// members' indexes through the aliases. That is the whole question the wrapper raised, answered.
///
/// The last line is the honest remainder and is the TAIL's rather than the predicate's: the leading
/// term can be served by an index, and the two synthesized tail terms cannot be — a discriminant is
/// a literal per arm and no index spans two tables — so a page sorts them in a temporary B-tree. It
/// is bounded by the page's own `LIMIT` and is what ordering across tables costs.
///
/// PostgreSQL and MySQL are NOT measured here, and their planners are not SQLite's.
///
/// # The KEYSET needs no per-arm folding, and the wrapper is why
///
/// The resume predicate was going to be the awkward half: with a `WHERE` inside each arm, the tail's
/// discriminant is a CONSTANT there, so every arm would have had to fold its own comparison against
/// the cursor's kind — strictly-greater arms dropping the tail, the equal one keeping the id, lesser
/// arms dropping out of the statement.
///
/// The wrapper removes the question rather than answering it. Above the union the discriminant is an
/// ordinary output column that varies row by row, so the general keyset expansion — the same
/// [`SqlKeyset`] every record page renders — is exactly right, over `(…, __ig_kind__, id)` as it is
/// over any other total order. There is no interface-specific comparison, and therefore none to get
/// wrong.
///
/// What the fold would have bought is arm ELIMINATION, and it is the planner's to buy now: an arm
/// whose whole discriminant is below the cursor's contributes no row, and whether a dialect notices
/// that is a plan question rather than a rendering one.
///
/// # Errors
///
/// A lowering refusal carried verbatim, and an order this dialect cannot render.
pub fn union<I, Db>(
  filter: Option<&I::Comparison>,
  order: &SqlOrder<'_, Db>,
  keyset: Option<&SqlKeyset<'_, I::Value, Db>>,
  walk: Walk,
  limit: Option<u32>,
) -> Result<sqlx::QueryBuilder<Db>, SqlQueryError>
where
  I: SqlInterface<Db>,
  Db: SqlDialect,
  i64: sqlx::Type<Db>,
  for<'t> i64: sqlx::Encode<'t, Db>,
{
  let mut source = Utf8BytesMut::new();
  source.push_str("( ");
  source.push_str(arms::<I, Db>().as_str());
  source.push_str(" ) AS ");
  push_quoted_ident::<Db>(I::SOURCE, &mut source);

  let mut builder = QueryBuilder::<SelectClause, Db>::select()
    .push_field("*")
    .from(source.as_str())
    .begin_where();
  {
    // ONE accumulator for both conjuncts, so a resumed page is *the client's filter AND this* and
    // neither has to know what the other was — the arrangement `find::predicates` already makes for
    // a record's lanes.
    let mut conjunction = SqlConjunction::new(builder.inner_mut());
    if let Some(filter) = filter {
      conjunction = filter.apply(At::new(&I::UNION), conjunction)?;
      conjunction = collections::<I, Db>(filter, conjunction)?;
    }
    if let Some(keyset) = keyset {
      conjunction = keyset.apply(At::new(&I::UNION), conjunction)?;
    }
    // The accumulator holds the builder's `&mut` and the clause transition below takes the builder
    // BY VALUE, so the borrow has to end here — the rebinding `find` already writes for the same
    // reason.
    let _ = conjunction;
  }
  let builder = order.push_order_by_with(builder, walk, At::new(&I::UNION), &TermColumns);
  Ok(match limit {
    Some(limit) => builder.limit(u64::from(limit)).finalize(),
    None => builder.finalize(),
  })
}

/// A query over an INTERFACE: which of its members' rows, and in what order.
///
/// # Every lane here is a PAGE, and the tail is why
///
/// A record's builder has three lanes, because a record's order is the client's and may be absent —
/// so *the whole set, unordered* is a real question there. An interface's order is never absent: it
/// completes with `(…, __ig_kind__, id)` whatever the client wrote, and those two terms are what
/// make a row of several tables addressable at all. So there is one lane, it is ordered, and it
/// pages.
#[must_use = "a query builder renders nothing until it is fetched"]
pub struct InterfaceFind<'a, I, Db, A>
where
  I: SqlInterface<Db>,
  Db: Backend + sqlx::Database,
{
  executor: A,
  filter: Option<&'a I::Comparison>,
}

/// A query whose order is WRITTEN and completed — the only state a page can be asked for from.
#[must_use = "a query builder renders nothing until it is fetched"]
pub struct InterfaceOrdered<'a, I, Db, A>
where
  I: SqlInterface<Db>,
  Db: Backend + sqlx::Database,
{
  find: InterfaceFind<'a, I, Db, A>,
  /// The client's terms with the tail already on them — completed ONCE here, so the `ORDER BY`, the
  /// resume predicate and the minted cursor are three readings of one list.
  order: Vec<OrderTerm>,
}

/// A page under construction: its size, the way it runs, and the cursor it resumes at.
///
/// `S` is which position is still open, and it is the record lane's own marker set —
/// [`Forward`](super::Forward) admits `after`, [`Backward`](super::Backward) admits `before`, and
/// [`Positioned`](super::Positioned) admits neither. Shared rather than restated, because the rule
/// is one: `last` beside `after` is *the last N of everything after the cursor*, which nobody can
/// answer without reaching the far end first.
#[must_use = "a query builder renders nothing until it is fetched"]
pub struct InterfacePaging<'a, I, Db, A, S>
where
  I: SqlInterface<Db>,
  Db: Backend + sqlx::Database,
{
  ordered: InterfaceOrdered<'a, I, Db, A>,
  size: u32,
  walk: Walk,
  cursor: Option<&'a Cursor<I::Value>>,
  // `fn() -> S` rather than a bare parameter, so the state marker contributes no auto-trait or
  // variance obligation — this crate's convention for every phantom state.
  state: PhantomData<fn() -> S>,
}

impl<'a, I, Db, A> InterfaceFind<'a, I, Db, A>
where
  I: SqlInterface<Db>,
  Db: Backend + sqlx::Database,
{
  /// A query over `executor`, unfiltered.
  ///
  /// There is no `snapshot` flag beside it, and its absence is the transaction law: an interface's
  /// call is bracketed ALWAYS — see [`InterfacePaging::fetch`] — where a record's is opt-in through
  /// `find_<db>_snapshot`.
  #[inline]
  pub const fn new(executor: A) -> Self {
    Self {
      executor,
      filter: None,
    }
  }

  /// Constrain the query by `filter`, in the INTERFACE's own vocabulary.
  #[inline]
  pub fn filter(mut self, filter: &'a I::Comparison) -> Self {
    self.filter = Some(filter);
    self
  }

  /// Order the query by `written`, completed with the tail that makes it total.
  ///
  /// An order of NO terms needs no refusal: it completes into the tail alone, which is a written
  /// order over `(__ig_kind__, id)` — the one order every interface can always be paged in.
  ///
  /// The terms are RENDERED once, here, so the `ORDER BY`, the resume predicate and every minted
  /// cursor are three readings of one list — and EXPANDED once, so a shared column whose citizen
  /// states a semantic sequence runs as its levels here exactly as it does under a record's own
  /// page. [`OrderTerm::levels`] is that expansion, and one written word may therefore render as
  /// several terms.
  #[inline]
  pub fn order(self, written: &[I::Order]) -> InterfaceOrdered<'a, I, Db, A> {
    let terms: Vec<OrderTerm> = written
      .iter()
      .cloned()
      .flat_map(|term| I::term(term).levels())
      .collect();
    InterfaceOrdered {
      order: total_order::<I, Db>(&terms),
      find: self,
    }
  }
}

impl<'a, I, Db, A> InterfaceOrdered<'a, I, Db, A>
where
  I: SqlInterface<Db>,
  Db: Backend + sqlx::Database,
{
  /// The first `first` rows of the order as written.
  #[inline]
  pub fn first(self, first: u32) -> InterfacePaging<'a, I, Db, A, super::Forward> {
    self.page(first, Walk::Forward)
  }

  /// The last `last` rows of the order as written — the same order read from the far end.
  #[inline]
  pub fn last(self, last: u32) -> InterfacePaging<'a, I, Db, A, super::Backward> {
    self.page(last, Walk::Backward)
  }

  /// A default-sized page after `cursor`.
  #[inline]
  pub fn after(
    self,
    cursor: &'a Cursor<I::Value>,
  ) -> InterfacePaging<'a, I, Db, A, super::Positioned> {
    self.first(DEFAULT_PAGE_SIZE).after(cursor)
  }

  /// A default-sized page before `cursor`.
  #[inline]
  pub fn before(
    self,
    cursor: &'a Cursor<I::Value>,
  ) -> InterfacePaging<'a, I, Db, A, super::Positioned> {
    self.last(DEFAULT_PAGE_SIZE).before(cursor)
  }

  /// The page this state opens, with its size clamped to the framework's ceiling.
  fn page<S>(self, size: u32, walk: Walk) -> InterfacePaging<'a, I, Db, A, S> {
    InterfacePaging {
      ordered: self,
      size: size.min(MAX_PAGE_SIZE),
      walk,
      cursor: None,
      state: PhantomData,
    }
  }
}

impl<'a, I, Db, A> InterfacePaging<'a, I, Db, A, super::Forward>
where
  I: SqlInterface<Db>,
  Db: Backend + sqlx::Database,
{
  /// Resume after the row `cursor` was minted at.
  #[inline]
  pub fn after(
    self,
    cursor: &'a Cursor<I::Value>,
  ) -> InterfacePaging<'a, I, Db, A, super::Positioned> {
    self.at(cursor)
  }
}

impl<'a, I, Db, A> InterfacePaging<'a, I, Db, A, super::Backward>
where
  I: SqlInterface<Db>,
  Db: Backend + sqlx::Database,
{
  /// Resume before the row `cursor` was minted at — the backward walk's `after`.
  #[inline]
  pub fn before(
    self,
    cursor: &'a Cursor<I::Value>,
  ) -> InterfacePaging<'a, I, Db, A, super::Positioned> {
    self.at(cursor)
  }
}

impl<'a, I, Db, A, S> InterfacePaging<'a, I, Db, A, S>
where
  I: SqlInterface<Db>,
  Db: Backend + sqlx::Database,
{
  /// How many rows this page holds — the ask, clamped to the framework's ceiling.
  #[inline]
  #[must_use]
  pub const fn size(&self) -> u32 {
    self.size
  }

  /// How many rows the STATEMENT asks for: the page, plus the one that answers *is there more*.
  #[inline]
  const fn window(&self) -> u32 {
    self.size.saturating_add(1)
  }

  /// The same page with its position fixed — the one move out of an open state.
  fn at(self, cursor: &'a Cursor<I::Value>) -> InterfacePaging<'a, I, Db, A, super::Positioned> {
    InterfacePaging {
      ordered: self.ordered,
      size: self.size,
      walk: self.walk,
      cursor: Some(cursor),
      state: PhantomData,
    }
  }
}

/// One page's rows, trimmed, and whether the row after them was there.
///
/// The cursor at each row is minted from the row itself — the values the page actually sorted at,
/// read at the same terms the `ORDER BY` ran — which is the frozen-boundary rule a record's edges
/// already hold.
async fn edges<I, Db>(
  conn: &mut Db::Connection,
  statement: &mut sqlx::QueryBuilder<Db>,
  terms: &[OrderTerm],
  size: usize,
) -> Result<(Vec<Edge<I::Row, I::Value>>, bool), SqlQueryError>
where
  I: SqlInterface<Db>,
  I::Row: for<'r> sqlx::FromRow<'r, Db::Row>,
  Db: SqlDialect,
  for<'e> &'e mut Db::Connection: sqlx::Executor<'e, Database = Db>,
  Db::Arguments: sqlx::IntoArguments<Db>,
{
  let mut raw = sqlx::Executor::fetch_all(&mut *conn, statement.build()).await?;
  // The row PAST the page is the whole of what the extra row is for, and it is reported rather than
  // carried: the statement asked for one more than the page holds.
  let more = raw.len() > size;
  raw.truncate(size);
  let mut edges = Vec::with_capacity(raw.len());
  for row in &raw {
    let decoded = <I::Row as sqlx::FromRow<'_, Db::Row>>::from_row(row)?;
    let values: Vec<Option<I::Value>> = terms.iter().map(|term| I::value(&decoded, term)).collect();
    // `Cursor::at` is the framework's UNCHECKED mint, and this is the position it is for: both
    // halves are in hand, read off one row under one order. What is CHECKED is the other end.
    edges.push(Edge::new(decoded, Cursor::at(terms, values)));
  }
  Ok((edges, more))
}

impl<'a, I, Db, A, S> InterfacePaging<'a, I, Db, A, S>
where
  I: SqlInterface<Db>,
  I::Row: for<'r> sqlx::FromRow<'r, Db::Row>,
  Db: SqlDialect,
  i64: sqlx::Type<Db>,
  for<'t> i64: sqlx::Encode<'t, Db>,
  for<'e> &'e mut Db::Connection: sqlx::Executor<'e, Database = Db>,
  Db::Arguments: sqlx::IntoArguments<Db>,
{
  /// The page, in DISPLAY order, with what is known about either side of it.
  ///
  /// # THE TRANSACTION LAW: the call is bracketed, and a caller's own read is passed THROUGH
  ///
  /// The call opens the dialect's read transaction — `BEGIN DEFERRED`, `REPEATABLE READ READ ONLY`,
  /// `WITH CONSISTENT SNAPSHOT`, each stated once on [`ReadSnapshot`](super::ReadSnapshot) — and
  /// closes it, ALWAYS, where a record's lane makes the same bracket opt-in. The asymmetry is the
  /// shape of the two calls rather than a preference: a record's page is one statement and is atomic
  /// without help, and an interface's page is answered by a union whose rows are then HYDRATED from
  /// the members' own tables, one gather per member. Those statements have to see one state of the
  /// database or the gather misses a row the union just returned.
  ///
  /// Handed a surface that already holds a transaction, it opens nothing and closes nothing — see
  /// [`BeginRead`](super::BeginRead), where the passthrough is stated. That is what lets a caller put
  /// the page and the hydration after it inside ONE read: both pass through, and neither has to know
  /// the other ran.
  ///
  /// # Errors
  ///
  /// A lowering refusal carried verbatim, a driver error, an order this dialect cannot render, and a
  /// cursor that is not this order's.
  pub async fn fetch<'c>(self) -> Result<Page<I::Row, I::Value>, SqlQueryError>
  where
    A: sqlx::Acquire<'c, Database = Db> + BeginRead,
  {
    let window = self.window();
    // The degrade law's SECOND row, read before the statement is built — the record lane's own
    // sentence, and this lane mints cursors too: a page's order lives entirely in the statement, and
    // a boundary it could not be resumed at is refused by name rather than served as a sequence the
    // next page cannot continue.
    let written = self.ordered.order;
    let terms = partition::<Db>(&written).paging::<Db>()?;
    let order = SqlOrder::<Db>::new(terms)?;
    let keyset = self
      .cursor
      .map(|cursor| SqlKeyset::resume(order, cursor, self.walk))
      .transpose()?;
    let mut statement = union::<I, Db>(
      self.ordered.find.filter,
      &order,
      keyset.as_ref(),
      self.walk,
      Some(window),
    )?;

    let mut held = self.ordered.find.executor.acquire().await?;
    let conn = &mut *held;
    let opened = open_read::<Db, A>(conn).await?;
    let fetched = edges::<I, Db>(conn, &mut statement, terms, self.size as usize).await;
    close_read::<Db>(conn, opened, fetched.is_ok()).await?;

    let (mut edges, more) = fetched?;
    let resumed = self.cursor.is_some();
    // A backward page is scanned from the far end and RE-REVERSED here, so what comes out is the
    // order as written whichever way the walk ran.
    if matches!(self.walk, Walk::Backward) {
      edges.reverse();
    }
    Ok(match self.walk {
      Walk::Forward => Page::new(edges, more, resumed),
      Walk::Backward => Page::new(edges, resumed, more),
    })
  }
}

#[cfg(test)]
mod tests;