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
//! The order a client writes, and the door it comes in through.
//!
//! The wire face is a LIST — `[<T>OrderBy!]` — because sequence IS the semantics and GraphQL has no
//! map type. What the list decodes INTO is a map keyed by the SUBJECT each term names, so the one
//! thing a list can spell that an order cannot hold — the same subject named twice — is refused at
//! the parse rather than carried down to a backend.
//!
//! # Why a repeat is refused and not quietly dropped
//!
//! A second term over a subject an earlier term already ordered by can reorder nothing: inside the
//! first term's tie group that column is CONSTANT, whichever direction the second one runs in. So a
//! repeat is not a different order — it is the same order with a term that means nothing — and the
//! backends do not agree about what that nothing costs. SQL carries it harmlessly and pays for it
//! once per row; a MongoDB sort is a BSON document whose keys are unique, so there the second term
//! REPLACES the first and the order silently runs the other way. Refusing is the only answer that
//! reads the same at every backend, and refusing at the DOOR is what keeps that divergence out of
//! wire semantics rather than merely out of one lowering.
//!
//! A caller's own list is the only place a repeat can come from. The framework's own default cannot
//! collide with a client's term either, and that is `complete`'s doing: it MOVES the key rather than
//! repeating it where a client's order already named it — so a client that orders by the key is
//! writing a legal order, not a repeat.
//!
//! # An EMPTY list is an order, an ABSENT argument is the same order, and the key is what both mean
//!
//! `[]` decodes to the empty order, and an absent `orderBy` normalises to it — [`Orderings::default`]
//! is that one door. What either becomes is decided one layer up by the emitted
//! `<T>OrderBy::complete`, which appends the record's KEY ASCENDING to any order that did not name
//! it: so both spell *the key, ascending*, which is unique and therefore a TOTAL order, and a page
//! over it neither skips nor repeats a row.
//!
//! The two were once different queries — `None` a client that never wrote an order and was refused a
//! page, `Some([])` one that asked for the address order — and the key default collapsed them.
//! Refusing the absent case bought a client nothing: it had to write `[]` to get exactly the order
//! the refusal was telling it about.
//!
//! What still has no default is the ENGINE's unordered lane, and that is a different question rather
//! than the same one answered twice. A Rust query that never calls `.order(…)` gets no `ORDER BY` at
//! all — SQL's own unordered semantics, and a sort nobody asked for is work every row pays for — and
//! a page there is a missing method rather than a defaulted order. The wire has no such lane: every
//! list field it serves is one a client may page.
//!
//! # The wrapper is not a schema name
//!
//! [`Orderings`] renders as the ARRAY and never as a type of its own: its `type_name` is
//! `[<T>OrderBy!]`, which is exactly what a `Vec` of the same term renders as, so the decode is
//! invisible to a client and a schema review sees the list the design ruled. A named wrapper input
//! would have been a second thing for a client to learn about an order that has not changed.
use IndexMap;
use crateTermName;
/// The SUBJECT one ordering term names: the path to a column, root-first, under the names no
/// per-database rename can move.
///
/// # A PATH, because a subject is not always one segment
///
/// `cover.title` and `title` are two subjects, and one order may name both. What makes them two is
/// the WHOLE path rather than its head — `cover.title` and `cover.duration` are two as well — so a
/// uniqueness test comparing first segments would refuse orders that are perfectly well formed.
/// Today every emitted term is one segment, and holding the path is what keeps the day a term
/// reaches through a relation from being a change to this rule.
///
/// # The segments are [`TermName`]s, which is what makes the identity rename-proof
///
/// A [`TermName`] is the RECORD FIELD's own name — the one `<db>(rename)` renames FROM —
/// so two deployments of one schema compute the same subject for the same term. The per-database
/// spelling is a [`FieldName`](crate::FieldName), which is a different type for exactly this
/// reason, and it reaches no part of this identity: an order compared by rendered names would
/// refuse a legal pair the moment one column's rename collided with another column's name, and
/// would admit a repeat wherever two renames crossed.
///
/// This is the identity the emitted `<T>OrderBy::complete` already dedupes the key tail by, one
/// layer up, where it is spelled as a match on the VARIANT. One variant is one column at every
/// database and one path here, so the two readings of "the same subject" are one reading.
///
/// # It is compared by SEGMENTS and rendered for a human
///
/// Equality and hashing walk the segments. The dotted [`Display`](core::fmt::Display) exists so a
/// refusal can name the subject a client wrote, and it is PROSE: nothing parses it, nothing matches
/// on it, and no part of this type's identity passes through it. [`Path`](crate::Path) states no
/// joining convention at all for the neighbouring reason — there the join is a BACKEND's, and the
/// families disagree about it.
;
/// The subject an ordering TERM names — implemented by every emitted `<T>OrderBy`.
///
/// A method rather than an associated constant: a term is a VALUE that has already chosen its
/// variant, and which subject it names is that choice. The direction it carries is the other half
/// and no part of the subject — `title ASC` and `title DESC` are one subject named twice, which is
/// the case the decode refuses.
///
/// It is gated on NOTHING, where [`Orderings`] is gated on the GraphQL binding. Generated code
/// lives in the DECLARING crate and cannot spell a feature of this one, so a trait an expansion
/// names has to exist in every build of it — the same split [`OrderDirection`](crate::OrderDirection)
/// already carries, where the enum is unconditional and only its wire derive rides the feature.
/// An order as it arrived from a client: the terms it wrote, in the sequence it wrote them, each
/// naming a subject no other term names.
///
/// It is built by the [`InputType`](async_graphql::InputType) decode and nowhere else, which is
/// what makes the uniqueness a fact about every value of this type rather than a check somebody
/// remembers to run. The Rust order-builder API is a separate door and keeps taking a plain slice;
/// what guards THAT one is the partition frame, on the other side of the engine.
///
/// # It carries no `PartialEq`, and the absence is the design
///
/// An `IndexMap`'s own equality is a MAP's — order-insensitive — so a derived one here would report
/// two different orders as equal, which is the wrong answer for the one property this type exists
/// to preserve. Comparing orders means comparing sequences: iterate [`terms`](Self::terms).
/// The empty order, which is the KEY DEFAULT — so `order.unwrap_or_default()` is the whole of what
/// a resolver does with an absent `orderBy`.
/// Two terms of one order naming one subject — what the decode refuses with.
///
/// Opaque to construct: the decode is the only party that can mint one, because it is the only
/// party that has seen both positions. What a caught refusal can read is all three facts, and the
/// message renders them.
/// The wire door's own word: a client that named a subject twice is told so under
/// `REPEATED_ORDER_SUBJECT`, whatever the sentence beside it grows into.
/// The DECODE: the list a client wrote, walked once, refusing at the term that repeats a subject.
///
/// Everything except [`parse`](async_graphql::InputType::parse) mirrors what a `Vec<T>` of the same
/// term does, and mirrors it exactly — that is what makes the wrapper invisible in SDL. The name
/// this presents is a LIST TYPE REFERENCE (`[<T>OrderBy!]`) rather than a type name, so nothing is
/// registered for the wrapper itself and only `T` reaches the registry.