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
//! The interpretation → level-sequence map: [`ToDatabaseOrderBy`], the refinement an emitted order
//! CROSSES through ([`ToCrossedOrderBy`]), and the [`OrderLevel`] both are written in.
//!
//! This is the ORDER axis's twin of [`comparison::lower`](crate::comparison::lower), and the
//! geography is deliberately the same: a marker-keyed map per dialect, and a refinement beside it
//! carrying what an emitted expansion actually CALLS. What differs is the answer's kind. A filter's
//! crossing names a TYPE — the comparison it becomes — so its map carries an associated type and
//! pays the four bound walls that type costs at a generic dialect. An order's crossing names a
//! SEQUENCE, which is data, so this map carries a `const` and there is no projection for a `where`
//! clause to normalise.
//!
//! That difference is recorded rather than glossed, because it decides how much of the comparison
//! family's machinery is REAL here. [`ToCrossedComparison`](crate::comparison::ToCrossedComparison)
//! puts its crossing on METHODS to keep a projection off every bound — four measured errors are why.
//! [`ToCrossedOrderBy`] keeps the method SHAPE without the wall behind it: nothing in its signature
//! is a projection, so a caller at a generic `Db` was never going to be asked what the SQL family
//! demands of one. The shape is kept because the day a level sequence becomes a TYPE — a dialect
//! that lowers an order into its own sort document rather than into this crate's terms — the seat is
//! already the one that survives that change, and a caller written against it does not move.
use crate::;
/// ONE level of the order a single wire term runs in: WHICH of the column type's leaves this level
/// sorts by, as an ordinal into that type's own [`SEGMENTS`](crate::ColumnKind::SEGMENTS).
///
/// # An ordinal rather than a name, and the reason is the joining law
///
/// A leaf's COLUMN NAME is never spelled in this crate: `at_nanos` is
/// [`Backend::write_column`](crate::Backend::write_column)'s join of the field's name and the
/// segment's, made once so that a `SELECT`, a `WHERE` and an `ORDER BY` are one join rather than
/// three concatenations free to differ. A level that named its leaf by string would be a second
/// joining rule and the first thing to drift. An ordinal names the same leaf through the walk that
/// already renders it.
///
/// The numbering is the LEAF numbering — the one [`width`](crate::width) counts and
/// [`OrderTerm::width`](crate::OrderTerm::width) iterates — and NOT the segment-list index. A nested
/// composite contributes its own leaves, so `MediaTimestamp`'s three segments are four levels:
/// `pts` is `0`, the timebase's `num` and `den` are `1` and `2`, and the derived `nanos` is `3`.
///
/// # A newtype rather than a bare `usize`
///
/// A leaf ordinal and a level ordinal are two numberings of one term that are equal only by
/// accident, and both are `usize`. Wrapping the one a type DECLARES is what keeps a sequence written
/// in the wrong numbering from compiling — the house rule a [`TermName`](crate::TermName) beside a
/// [`FieldName`](crate::FieldName) already states one seam over.
;
/// An INTERPRETATION mapped to the LEVEL SEQUENCE one wire term over it sorts by, at one backend.
///
/// Implemented for the markers in [`crate::marker`] and for nothing else — [`ToGraphqlFilter`]'s
/// keying, for [`ToGraphqlFilter`]'s reason: a type does not determine its own reading, so a trait
/// keyed on the type would answer once, for the declarer. A declaration reaches this through
/// [`DefaultMarker`](crate::DefaultMarker).
///
/// # The EMPTY sequence is the DECLARATION ORDER, and it is the default for that reason
///
/// Almost every reading sorts by its leaves in the sequence the type declares them, and a scalar —
/// one leaf — cannot sort any other way. So `&[]` is the answer that means *the segments, as
/// declared*, exactly as an empty [`SEGMENTS`](crate::ColumnKind::SEGMENTS) is the answer that means
/// *one column*. A reading that states nothing here is behaviourally identical to what this
/// framework rendered before the map existed, which is what makes the map's arrival a
/// no-op for every existing declaration.
///
/// # Where a NON-default sequence comes from, and why it is not stated here
///
/// The type's own, through [`ColumnKind::ORDER`](crate::ColumnKind::ORDER). A composite citizen
/// declares what it is stored as and, beside it, what ORDER those columns mean — which is one fact
/// about one type, written where the other one is. A row here that named a citizen would be this
/// map deciding a downstream type's semantics, which is the closed surface the framework refuses
/// everywhere else: a downstream citizen teaches its own order by overriding a const in the
/// [`ColumnKind`](crate::ColumnKind) impl it already writes, with no second registration to
/// remember.
///
/// # `Db` is a parameter even where every dialect agrees today
///
/// All three shipped SQL dialects sort a composite's leaves the same way, so every row below ignores
/// its parameter. It is carried all the same, for
/// [`ToDatabaseComparison`](crate::ToDatabaseComparison)'s reason one axis over: what a dialect
/// SORTS BY is a dialect's answer, and a document family that nests a composite rather than
/// flattening it has a genuinely different sequence to give. A map without the parameter would have
/// to grow one the day that row is written, and every caller would move with it.
///
/// [`ToGraphqlFilter`]: crate::ToGraphqlFilter
// The FLAT readings, and every one of them takes the declaration order. A scalar, a string, a byte
// string, an enum, a boolean and a duration are each ONE column, so there is no sequence for a row
// here to permute — the empty answer is not a deferral but the only order one column has.
/// The ONE reading whose sequence can differ from its declaration, and the whole reason this map is
/// not a constant.
///
/// It reads [`ColumnKind::ORDER`] rather than carrying a table of citizens, which is the
/// framework-open half of the design: what a composite MEANS is the composite's, so the type that
/// declares what it is stored as declares what order those columns are in, and a downstream citizen
/// joins by overriding one const in an impl it already writes.
// The three COLLECTION readings. A collection is ONE column of the row whatever it holds — the width
// `impl<T> ColumnKind for Vec<T>` states — so like the flat readings it has no sequence to permute.
// That holds for all three storage forms: a native array is one column, an edge-stored collection is
// no column of this row at all, and a `sortable` one is its companion's single blob.
// The two TRANSPARENT readings, which add no column and therefore no level: an optional or nullable
// composite is stored in exactly the columns the composite is, with the same meaning in the same
// sequence, and what the wrapper changes is whether they may be `NULL` rather than what order they
// run in. So each forwards its inner reading's sequence and states none of its own — the same
// transparency `ToGraphqlFilter` gives the pair one axis over.
/// **The level sequence an emitted order SPENDS on one column, reached without naming a numbering**
/// — the map above refined to the two questions a lowering actually asks it.
///
/// # Why the facts are METHODS, and what is honestly NOT the reason
///
/// [`ToCrossedComparison`](crate::comparison::ToCrossedComparison) puts its crossing on methods to
/// keep a projection off every bound, and its note carries the four measured errors that forced it.
/// **That wall does not bite here**, and saying so is worth more than borrowing the argument: this
/// map's answer is a `const`, not an associated type, so there is no projection for a `where` clause
/// to resolve and nothing for a generic `Db` to be asked about.
///
/// What the methods buy instead is the SPELLING. A caller wants *the `at`-th leaf of this column's
/// order*, and reading it off the const means writing the empty-sequence fallback at every call
/// site — the `if LEVELS.is_empty() { at } else { LEVELS[at].leaf() }` that turns one convention
/// into N copies of it. One method is that convention held in one place, which is the same reason
/// [`OrderTerm::width`](crate::OrderTerm::width) exists beside
/// [`segments`](crate::OrderTerm::segments).
///
/// # Blanket-implemented, deliberately — a downstream joins one level down
///
/// [`ToCrossedComparison`](crate::comparison::ToCrossedComparison)'s arrangement, for its reason:
/// nothing implements this by hand, and a reading joins by having a [`ToDatabaseOrderBy`] row. There
/// is no second registration, and no way for the refinement to disagree with the map it refines.
/// The row itself — see the trait's note for why nothing implements it by hand.