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
//! The columns these two citizens span, and the six facts that follow from them.
//!
//! ```text
//! TimeRange SEGMENTS start(secs, nanos), end(secs, nanos) — four leaves
//! Carrier ?, ?, ?, ?
//! Assemble the instant's decode, twice, then the PAIR checked
//! CursorValue twenty-four bytes, and the pair checked again
//! MongoCarrier { "start": {…}, "end": {…} }
//! MongoExtract the two keys back through the instant's own door
//!
//! TimeRanged<T> SEGMENTS <the range's four, FLATTENED>, data(T's own)
//! ```
//!
//! # Every leaf is [`Timestamp`](crate::Timestamp)'s, and not one of them is spelled here
//!
//! `secs` and `nanos` appear nowhere in this file. The two seats are `shape::<Timestamp>(…)`, so
//! their inner names are the instant's own `SEGMENTS`; the binds call the instant's [`Carrier`], the
//! decode calls its [`Assemble`], the cursor calls its [`CursorValue`], the document calls its
//! [`MongoCarrier`] and the read calls its [`MongoExtract`]. A rename in that module moves
//! `start_secs`, `"start": {"secs": …}` and the cursor's first eight bytes together, and there is no
//! second list here to drift from.
//!
//! # The RANGE FLATTENS inside a [`TimeRanged`] and the PAYLOAD does not, and that is ONE rule
//!
//! [`ColumnShape::Composite`](crate::ColumnShape) carries an optional field name, and dropping it is
//! worth one path segment per column. The range's is dropped because its own two segments are
//! already `start` and `end` — words that need no prefix to be read, and a `TimeRanged` holds
//! exactly one range, so there is nothing for a `range_` segment to disambiguate. That is
//! [`DetectedLanguage`](crate::DetectedLanguage)'s own `SEGMENTS` argument, unchanged.
//!
//! The payload keeps its name for a reason that type did not have: `T` is a PARAMETER. Its segment
//! names are the payload family's and this crate cannot see them, so a splice would put two
//! independent name sets in one namespace with nothing able to say whether they collide — a payload
//! with a `start` field of its own would silently occupy the range's column. `data` is what makes
//! that unrepresentable, and it costs one segment.
//!
//! So a `TimeRanged<DetectedLanguage>` at `heard` reaches `heard_start_secs`, `heard_start_nanos`,
//! `heard_end_secs`, `heard_end_nanos`, `heard_data_language`, `heard_data_script`,
//! `heard_data_region`, `heard_data_rest` and `heard_data_confidence` — nine leaves, and the range's
//! four are the same four a DIRECT [`TimeRange`] column occupies.
//!
//! # BOTH citizens own the whole roster, and [`TimeRanged`]'s READ rows DELEGATE
//!
//! [`DetectedLanguage`] has no [`Assemble`] and no [`CursorValue`], and its own note says why: a
//! detection is a MEMBER of a `Vec`, so what a row holds is the collection. A timed payload is not
//! only that — `trim: TimeRanged<Trim>` is a column a declaration can hold outright, and a page
//! walking one needs a position — so both rows are written, BOUNDED on the payload.
//!
//! The bound is the honest membership rule and it is [`Confidence<S>`](crate::Confidence)'s shape at
//! a different parameter: a timed payload is decodable exactly where its payload is, and pageable
//! exactly where its payload is. `TimeRanged<DetectedLanguage>` therefore has neither, and the
//! `E0277` names DETECTED LANGUAGE — the half that is actually missing the row — rather than this
//! wrapper. That is the diagnostic a declaration's author can act on.
//!
//! The two WRITE rows carry no such question: a bind and a document form are what one VALUE looks
//! like, which an element has whether or not it is the whole of a field.
//!
//! [`DetectedLanguage`]: crate::DetectedLanguage
//! [`Assemble`]: crate::Assemble
//! [`CursorValue`]: crate::CursorValue
//! [`Carrier`]: crate::Carrier
//! [`MongoCarrier`]: crate::MongoCarrier
//! [`MongoExtract`]: crate::query::mongo::MongoExtract
use crate::;
use ;
/// The first instant's segment — the name a frame pushes and the four columns hang beneath.
///
/// `pub(crate)` rather than `pub(super)`, because the comparison next door addresses these seats
/// directly and reads the names from here rather than respelling them: one authority, at every
/// depth.
pub const START: &FieldName = new;
/// The last instant's segment.
pub const END: &FieldName = new;
/// The payload's segment — the one a [`TimeRanged`] adds to the range's four.
pub const DATA: &FieldName = new;
/// **The two parts a stretch spans**, each of them an INSTANT and therefore two columns of its own.
///
/// [`shape`] rather than [`ColumnShape::Plain`], which is the difference between this composite and
/// every one written before it in this crate: the parts are not leaves. `shape::<Timestamp>` reads
/// the instant's own `SEGMENTS` and nests them under the seat's name, so the four leaves are
/// `start_secs`, `start_nanos`, `end_secs` and `end_nanos` and the join is
/// [`Backend::write_column`](crate::Backend::write_column)'s as it is everywhere.
pub const SEGMENTS: & = &;
/// **The STORAGE half of the width** — four columns under two parts.
/// **One leaf, and it is the value.** A range means its two instants as declared — start then end — which is the order a range IS.
// A stretch is one column value when both its endpoints are — which is what this type's own
// `PartialEq` already says, its two instants being its two columns.
column_eq!
/// **The DECLARED half — FOUR words, which are the INSTANT'S TWO said twice.**
///
/// `secs` and `nanos` appear nowhere here for the reason they appear nowhere in the segments above:
/// the two seats are instants, so their words are [`Timestamp`]'s own row read twice rather than a
/// pair of widths restated. That is what keeps this file free of any claim about how an instant is
/// stored — the same arrangement the binds and the decode already have.
/// **THE ADMISSION.** A stretch is two instants and carries no collection, so it is one element of
/// one — and this row is what says so, exactly as [`Timestamp`]'s does.
///
/// It is the first admitted element whose parts are themselves composite: an edge table of
/// `Vec<TimeRange>` writes `(key…, ordinal, start_secs, start_nanos, end_secs, end_nanos)`, and the
/// descent that reaches those four is the same one a DIRECT column takes.
/// **FOUR BINDS OUT**, and the comma between the two instants is this row's — each instant writes
/// the comma between its own two.
///
/// The parts bind through [`Timestamp`]'s OWN row rather than through its integers, which is what
/// keeps a dialect's decision about an instant the instant's: a range that reached past that row
/// would be a second binding path for the same value.
/// **AND FOUR COLUMNS BACK IN, with the PAIR checked on the way** — the read half, and the third
/// fact a stored stretch states.
///
/// Each seat reads through [`Timestamp`]'s own [`Assemble`](crate::Assemble) row under its own
/// frame, so `start_nanos` past a second is refused by the instant's own sentence naming that
/// column. What THIS row adds is the check nothing beneath it can make: two instants that each
/// decode can still fail to be a range.
///
/// The refusal is [`sqlx::Error::ColumnDecode`] naming the **`end_secs`** column, and the choice is
/// [`Timestamp`]'s own — that row names `nanos`, *the half that cannot stand beside the other*. Here
/// the end is the half that came out too early, and `end_secs` is a name a `SELECT` can be pointed
/// at.
/// **THE KEYSET POSITION: twenty-four bytes, both instants, and the pair CHECKED on the way back.**
///
/// [`Timestamp`]'s twelve, twice, in the order [`SEGMENTS`] states — so the byte order IS the
/// comparison order this type publishes, and a page walking a range column resumes where the last
/// one stopped.
///
/// FIXED WIDTH, so a client's twenty-three bytes are refused rather than zero-extended into a
/// plausible stretch; and the recomposition is [`TimeRange::new`]'s, which makes this the THIRD
/// caller of that one door beside the SQL decode and the MongoDB read. A cursor is a string a CLIENT
/// hands back, so an inverted pair arriving here is refused rather than turned into a range whose
/// type says it cannot exist.
///
/// # **THE ORDER IS A STORAGE ORDER, and this row is where it is stated**
///
/// [`TimeRange`] publishes no [`Ord`] — `mediatime` declines it because *by start, by end and by
/// length are three different answers*, and this crate takes that posture. A KEYSET nonetheless
/// needs a TOTAL order: a page resumes by comparing a client's token against a column, so there has
/// to be one, and it has to be the same one the `ORDER BY` walks.
///
/// So the order lives HERE rather than on the type, and the difference is not bookkeeping. An `Ord`
/// on [`TimeRange`] would answer *which of these two stretches comes first* to any caller that asked
/// — the question with three answers. This row answers a narrower one: *which of these two ROWS
/// pages first*, start then end, which is what the bytes encode. A reader who wants a semantic order
/// still has to choose one and say so.
///
/// It is the order the other two storage faces already read — the SQL row value
/// `("start_secs", "start_nanos", "end_secs", "end_nanos")` compares left to right and BSON compares
/// the sub-document's keys in written order — so the three cannot disagree: all of them read this
/// struct's field order and none of them was matched to another.
/// One instant's cursor width — the eight big-endian bytes of seconds and the four of nanoseconds
/// [`Timestamp`]'s own row writes.
///
/// Derived from the two integer widths rather than spelled as `12`, so a change to either half of
/// that encoding moves this split with it.
const INSTANT_CURSOR_WIDTH: usize = + ;
/// A stretch's cursor width — two instants, and the constant a [`TimeRanged`] splits its own token
/// at.
const RANGE_CURSOR_WIDTH: usize = 2 * INSTANT_CURSOR_WIDTH;
/// **THE DOCUMENT'S FORM: TWO KEYS, EACH A SUB-DOCUMENT** — the instant's own shape, twice, under
/// this type's two seat names.
///
/// ```text
/// { "start": { "secs": 1_756_371_600, "nanos": 0 },
/// "end": { "secs": 1_756_371_660, "nanos": 0 } }
/// ```
///
/// It NESTS where the table flattens, which is the asymmetry [`MongoCarrier`](crate::MongoCarrier)'s
/// own instant row already states and the reason is one rule rather than two: SQL's namespace is
/// flat and BSON's is not. **The SEGMENTS are the same segments** — the four leaves a table joins
/// with `_` are the same four a document reaches as `start.secs`.
///
/// BSON compares two sub-documents field by field in written order, so a range written by this row
/// compares by start and then by end — the SAME order its cursor writes and a SQL row value reads.
/// Three faces, one order, and none of them was matched to another: all three read the field order
/// of the struct.
///
/// **It is a STORAGE order and the type publishes none**, which is the whole of why the sentence
/// above says *this row compares* rather than *a stretch is less than*. See
/// [`CursorValue`](crate::CursorValue)'s row below, where the distinction is argued once for all
/// three faces.
/// The stored pair is not a stretch — the `start` key names an instant no earlier than the `end`
/// one.
///
/// A FIXED sentence, which is what [`MongoTypeError::Range`](crate::query::mongo::MongoTypeError)
/// holds: that variant carries a `&'static str`, so the two instants that failed cannot travel with
/// it. The SQL decode keeps them — [`sqlx::Error::ColumnDecode`] boxes
/// [`InvertedTimeRange`](super::InvertedTimeRange) whole — and the difference between the two
/// families is the vocabulary rather than the check, which is the posture the subtag reads already
/// take.
const INVERTED: &str = "this field holds a `start` and `end` pair whose end is earlier than its start, which is not a \
time range";
/// **THE READ: two sub-documents back into a stretch** — [`MongoCarrier`](crate::MongoCarrier)'s
/// mirror, nesting where that row nests.
///
/// Each seat goes through [`Timestamp`]'s OWN [`MongoExtract`](crate::query::mongo::MongoExtract)
/// row, so a `secs`/`nanos` pair jiff would have normalised is refused here by the instant's own
/// sentence — and the check THIS row adds is the pair's, through [`TimeRange::new`]. One document
/// and one row cannot disagree about which pairs are stretches: the same constructor answers both.
/// **The two parts a TIMED PAYLOAD spans**: the range's four, flattened, then the payload under its
/// own name.
///
/// [`flattened`] lends no name and [`shape`] lends one — see this module's note, where the asymmetry
/// is argued from `T` being a PARAMETER. A SCALAR payload lands on `Plain(data)` and a composite one
/// on `Composite { field: Some(data), … }`, which is [`shape`]'s own branch and is why this row
/// serves both without knowing which it has.
/// A timed payload is one column value when its stretch and its payload both are — the range
/// through its own row, the payload through the bound this wrapper carries.
// **NO `StoredAs` ROW, AND IT IS A LIMIT OF STABLE RUST RATHER THAN AN OMISSION.**
//
// A width is a `ColumnShape` list and composes at any arity — the row above concatenates nothing,
// it nests — but a `StoredAs` row is an ARRAY OF WORDS whose length is fixed when the impl is
// written. This type's would be the range's four followed by `T`'s own, i.e. `4 + <T as
// StoredAs<Db>>::WORDS.len()` entries, and stable Rust refuses that length twice: as an inner
// `const` it is `E0401` (`can't use generic parameters from outer item`), and in the array's own
// length position it is `constant expression depends on a generic parameter`. Both were compiled
// before this comment was written.
//
// So the concatenation belongs to whatever assembles a row's whole column list from its FIELDS,
// where every length is concrete — see `column::stored`, whose note carries the boundary for the
// whole crate. A FIXED-arity composite is unaffected and every other one in this crate is one.
/// **THE ADMISSION**, and it DELEGATES: a timed payload is one element of a collection exactly where
/// its payload is one.
///
/// The range half never refuses — four leaves, no collection — so the whole question is the
/// payload's and the bound is what asks it. `Vec<TimeRanged<DetectedLanguage>>` is admitted because
/// a detection is; `Vec<TimeRanged<Vec<String>>>` is `E0277` naming the inner `Vec`, which is the
/// collection-of-collections refusal reaching THROUGH this type rather than being restated by it.
///
/// It is the deepest admitted element in the crate: the range's `start` is a composite inside a
/// flattened composite inside the element, so the edge table writes `start_secs` and its three
/// siblings beside the payload's own leaves. Nothing here counts columns — the descent is the
/// framework's one leaf walk.
/// **N BINDS OUT** — the range's four placeholders, then the payload's own.
///
/// The range writes its own three commas and the payload writes any of its own, which is the
/// arrangement [`Carrier`](crate::Carrier) documents: how many columns a value spans is the value's
/// answer, so a composite pushes several placeholders with its own separators and the caller counts
/// FIELDS.
/// **AND ITS COLUMNS BACK IN** — the stretch flat under the address it was given, then the payload
/// beneath its own seat.
///
/// [`assembled_flattened`](crate::assembled_flattened) is what makes the first half read at the
/// holder's own level, which is the read side of [`flattened`] and the same pairing every spliced
/// part in this crate has. The PAIR check rides in with the stretch: [`TimeRange`]'s own row refuses
/// a stored end earlier than its start, naming its own column, so this row states no invariant of
/// its own.
/// **THE KEYSET POSITION: the stretch's twenty-four bytes, then the payload's own — and the payload
/// needs NO framing because it is LAST.**
///
/// A cursor slot is already length-delimited by the layer above, which is the framing
/// [`LanguageId`](crate::LanguageId)'s own row is told not to add. Here that argument does the work
/// twice over: the stretch is FIXED at twenty-four bytes so the split point is a constant, and
/// everything after it belongs to the payload whatever width the payload is. So a variable-width
/// payload rides this row unchanged, and no delimiter is invented.
///
/// The ORDER the bytes encode is the stretch first and the payload second, which is the order a
/// `SELECT` walking the columns reads. It is a STORAGE order for [`TimeRange`]'s reason one row up:
/// neither this type nor its stretch half publishes an [`Ord`], and a page's need for *an* order is
/// not a claim about *the* order.
/// **THE DOCUMENT'S FORM: THREE KEYS** — the range's two at this level, and the payload under
/// `data`.
///
/// ```text
/// { "start": {…}, "end": {…}, "data": { … the payload's own shape … } }
/// ```
///
/// The range is SPLICED here for the reason the SQL side splices it: its entry in `SEGMENTS` is
/// [`flattened`], which lends NO NAME, and a key set is built out of names. There is no key to nest
/// under, so its two join this document's own — the same thing the columns do, in the spelling this
/// family has for it. The payload lends a name and therefore takes a key.
/// **THE READ: the range's two keys at this level, then the payload's** —
/// [`MongoCarrier`](crate::MongoCarrier)'s mirror, splicing where that row splices.
///
/// The write builds a timed payload's document by taking the range's OWN document and adding one
/// key. The read takes the same document ONCE and reads three keys out of it: `start` and `end`
/// through [`TimeRange`]'s own row — which is where the pair check lives — and `data` through the
/// payload's own, whatever that payload is. Nothing here re-derives what a key means or what refuses
/// it.
/// **One leaf, and it is the value** — TimeRanged<T> means its columns in the sequence it declares them, so
/// no term over one ever expands and the word is the whole row.