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
//! The READ half of a column shape: [`Assemble`], and the two entry points a decode writes per
//! field.
//!
//! # A composite has no single column to `try_get`, which is what this exists for
//!
//! A row's decode used to be one `try_get` per field under one name, and that shape can only read a
//! declaration in which nothing spans more than one column. `tb: Timebase` spans two, under names —
//! `tb_num`, `tb_den` — that nothing holds: they are joined while a statement is written, from the
//! nested list [`ColumnShape`](crate::ColumnShape) carries. So the read is joined the same way, from
//! the same [`Path`], and the type that knows how many columns it is is the type that reads them
//! back.
//!
//! # Three traits, one column
//!
//! [`ColumnKind`](crate::ColumnKind) says HOW MANY columns a field is,
//! [`Carrier<Db>`](crate::Carrier) says how its value BINDS in one dialect, and this says how its
//! value READS BACK. A composite implements all three, and the three have to agree: a type whose
//! shape says two columns, whose bind pushes two placeholders and whose read fetches one is a row
//! that writes what it cannot read.
//!
//! # A row per type rather than a blanket, and that is a measurement
//!
//! The obvious surface is `impl<T: Decode + Type> Assemble for T`, which every scalar would join for
//! free. It cannot stand beside a composite's own row — `Timebase` is a downstream type, so nothing
//! proves it does not also decode — and the same shape was measured one trait over:
//! [`ColumnKind`](crate::ColumnKind)'s note records ten `E0277`s from a blanket that a generic-over-
//! dialect `where` clause proved through instead of through the clause. [`Carrier`](crate::Carrier)
//! is the shape that works, and this follows it: one row per storage type, stated.
//!
//! What that costs a downstream scalar is one impl beside the two it already writes, and the body is
//! the same three lines every row below has.
use Cow;
use crate::;
/// How a value is read back out of the columns it spans.
///
/// # The parameter is the ROW, not the dialect
///
/// [`Carrier<Db>`](crate::Carrier) names the dialect because a bind is a dialect's fact — a cast,
/// a function call, a placeholder syntax. A read is the ROW's: `try_get` is
/// [`sqlx::Row`]'s method, the emitted decode is generic over the row exactly as
/// [`sqlx::FromRow`] is, and a row already names its own `Database`. Naming the dialect instead
/// would have put `R::Database` in every bound and left the one type a read actually needs
/// unspellable.
///
/// # `under` is the path, and an FLATTENED field is the path unchanged
///
/// The segments above this value are what a renderer descends through, and they arrive here in the
/// same cons list — so a `SELECT` of `tb_num` and a decode of `tb_num` are one join rather than two
/// rules that agree today. A field that lends its name pushes a segment ([`assembled`]); one that
/// does not passes the path along ([`assembled_flattened`]), which is the whole of what
/// `<db>(flatten)` means on this side too.
///
/// # Errors
///
/// Whatever [`sqlx::Row::try_get`] answers, unchanged and unwrapped: a column the statement did not
/// select is `ColumnNotFound` naming it, and one that will not decode is `ColumnDecode`. Nothing
/// here constructs an error, so a composite's failure names the SEGMENT's column — `tb_den` and not
/// `tb` — which is the name the engine was actually asked for.
/// The value a field named `field` holds — the ONE spelling a decode writes per field, and the read
/// half of [`shape`](crate::shape).
///
/// The field lends its name to whatever is below it, so a scalar reads `field` and a composite reads
/// `field_<segment>` for each of its own. Nothing here judges which: the type answers, exactly as it
/// answers its width.
///
/// # Errors
///
/// See [`Assemble`]: the contract is [`sqlx::Row::try_get`]'s.
/// The same field with its NAME dropped — `<db>(flatten)`, the read half of
/// [`flattened`](crate::flattened).
///
/// The segments arrive at the holder's own level, so `tb: Timebase` reads `num` and `den` where
/// [`assembled`] would have read `tb_num` and `tb_den`.
///
/// # Errors
///
/// See [`Assemble`]: the contract is [`sqlx::Row::try_get`]'s.
/// ONE column, fetched by name — the SCALAR answer, and the body every plain row shares.
///
/// Public because a row is what a downstream scalar writes and this is the whole of one:
///
/// ```
/// use ingraph::{Assemble, Path, plain_column};
///
/// struct Rating(i64);
///
/// impl<'a, R: sqlx::Row> Assemble<'a, R> for Rating
/// where
/// Rating: sqlx::Decode<'a, R::Database> + sqlx::Type<R::Database>,
/// for<'name> &'name str: sqlx::ColumnIndex<R>,
/// {
/// fn assemble(row: &'a R, under: Option<&Path<'_>>) -> sqlx::Result<Self> {
/// plain_column(row, under)
/// }
/// }
/// ```
///
/// A path of `None` cannot arrive from a declaration: it would mean a flattened field whose type
/// spans one column, and [`flattened`](crate::flattened) is `E0080` on exactly that at the row's own
/// `COLUMNS`. What it does here is answer as `try_get` would for a column nothing selected, which is
/// what keeps this total without a second error vocabulary for a state a declaration cannot reach.
///
/// # Errors
///
/// See [`Assemble`]: the contract is [`sqlx::Row::try_get`]'s.
/// Every ONE-COLUMN storage type this crate ships that a row can HOLD, each reading one column.
///
/// The list is [`scalar_columns`](super)' minus the unsized ones: `str` is one column wide and is
/// not a value a row owns, so it answers a width here and nothing else. The gates are the carrier
/// rows' own, for the carrier rows' reasons.
///
/// [`Timestamp`](crate::Timestamp) is absent for the reason it is absent there: it reads TWO
/// columns and recomposes them, which is a body no one-column macro can carry.
plain_columns!
plain_columns!
plain_columns!
plain_columns!
plain_columns!
/// Why a stored `0` is not a `NonZero*` value — the `NonZero*` family's own read-path refusal.
///
/// Every `NonZero*` column this crate WRITES carries [`NonZero::get`](core::num::NonZero::get)'s
/// value, which cannot be `0` by construction — see the [`Carrier`](crate::Carrier) row beside this
/// one's. So a stored `0` is not a value this code wrote: a hand-edited row, a column shared with
/// something else, a bit flip. The read refuses it BY NAME rather than mint a `NonZero` around the
/// hole through `new_unchecked`, or panic through `new(…).unwrap()` — see [`Assemble`]'s row below,
/// which is the ONE place a decoded `0` can still be caught, the underlying integer's own decode
/// having already succeeded.
;
/// **A `NonZero*` COLUMN READS ITS UNDERLYING INTEGER AND THEN ASKS [`NonZero::new`], WHICH IS THE
/// ONLY PLACE A STORED `0` CAN STILL REFUSE.**
///
/// The width itself decodes through its OWN row above — `NonZeroI32` asks `i32`'s, exactly as its
/// [`Carrier`](crate::Carrier) row binds through `i32`'s — so what this adds is the ONE check that
/// row cannot make: whether the decoded integer is the one value a `NonZero` cannot hold. A `0`
/// refuses as [`sqlx::Error::ColumnDecode`] naming the column, carrying [`NonZeroColumnError`] —
/// the same shape [`crate::Timestamp`]'s own unnormalised-pair refusal takes, and for the same
/// reason: loudly, at the row that holds it, never a panic and never a value quietly minted around
/// the invariant.
nonzero_columns!
/// **A CONFIDENCE COLUMN READS ITS WIDTH AND THEN ASKS [`Confidence::new`](crate::Confidence::new)**,
/// which is the only place a stored number outside the interval can still refuse.
///
/// It is the `NonZero*` row's shape one house over and for the same reason: the WIDTH decodes
/// through its own row above, and what is left is the one thing that row cannot check — whether the
/// number it produced is a confidence. A stored `1.5`, a restored dump, a column shared with
/// something else: each refuses as [`ColumnDecode`](sqlx::Error::ColumnDecode) naming the column and
/// carrying [`OutsideTheInterval`](crate::OutsideTheInterval) — the same sentence a WIRE operand
/// past the interval meets, so the two doors into this type give one answer.
///
/// # It was MISSING, and a family consuming this seat is what found it
///
/// [`Confidence<S>`](crate::Confidence) had every other row a value citizen has — a width, a stored
/// word, a bind, a document form, an admission and both wire directions — and no READ. That made it
/// a type a declaration could write and could not select back: a record naming one earned `E0277` on
/// its own `FromRow`, naming this trait. The gap was invisible for as long as no shipped composite
/// held a confidence in a column a declaration could name —
/// [`DetectedLanguage`](crate::primitives::lang::DetectedLanguage) has no `Assemble` row of its own
/// and says so — and [`Detection`](crate::Detection) is the first that does.
///
/// The bound is the membership rule spelled as a bound, exactly as the width, carrier and admission
/// rows spell theirs: a confidence reads back wherever the width it measures in does.
/// Why a stored pattern that no longer COMPILES is a refusal and not a panic — the pattern column's
/// own read-path refusal.
///
/// Every pattern column this crate WRITES carries [`Regex::as_str`](regex::Regex::as_str)'s text,
/// which compiled once by construction. So a stored pattern that does not compile is not a value
/// this code wrote, or is one this build cannot read: a hand-edited row, a column shared with
/// something else, a pattern written by a build whose `regex` had a syntax or a size limit this one
/// does not. It refuses BY NAME — carrying the engine's own sentence, which is the only thing that
/// says *what* is wrong with the text — rather than `unwrap` the compile or mint a `Regex` around
/// the hole, neither of which this type even offers.
///
/// It carries [`regex::Error`] rather than restating it, because that error already names the
/// offending span and the rule it broke, and a second sentence written here could only be vaguer.
/// `Eq` is absent where [`NonZeroColumnError`]'s row has it, and that is the carried error's own
/// shape rather than a choice made here: [`regex::Error`] is `#[non_exhaustive]` and derives
/// `PartialEq` and no `Eq`, so the total relation is not one this type could claim without claiming
/// it for the engine's error first.
;
/// **A PATTERN COLUMN READS ITS TEXT AND THEN ASKS [`Regex::new`](regex::Regex::new), WHICH IS THE
/// ONLY PLACE A STORED PATTERN CAN STILL REFUSE.**
///
/// It is the `NonZero*` and [`Confidence`](crate::Confidence) rows' shape a third time: the STORED
/// FORM decodes through its own row above — `String`'s, this column being `TEXT` on every dialect —
/// and what this adds is the one thing that row cannot do, which is turn the text back into the
/// value the column is declared to hold. A pattern that no longer compiles refuses as
/// [`ColumnDecode`](sqlx::Error::ColumnDecode) naming the column and carrying
/// [`PatternColumnError`], loudly and at the row that holds it — never a panic, and never a value
/// quietly minted around the failure.
///
/// # The DECODE is the compile, and that is the whole asymmetry of this citizen
///
/// A uuid reads back as the sixteen bytes it wrote. A pattern reads back by being RE-COMPILED, so
/// the read does real work and can fail where the write could not: `Regex::new` is the inverse of
/// [`Regex::as_str`](regex::Regex::as_str) only over the texts this build's `regex` admits. That is
/// stated rather than hidden because it is the one operational fact a schema owner needs — a stored
/// column survives a dependency bump exactly as far as the engine's grammar and its size limits do.
/// **AND TWO COLUMNS BACK IN, with the teeth on the way** — the read half of the framework's own
/// composite, and the third of the three facts a stored one states.
///
/// Each part reads through [`assembled`], so `under` carries the holder's segment for a field that
/// lends its name and nothing extra for one marked `flatten`, and this one body serves both without
/// knowing which it is reading. A missing or undecodable part is `try_get`'s own error naming
/// `at_nanos` rather than `at`, exactly as the trait's note promises.
///
/// # It is the ONE row here that CONSTRUCTS an error, and the reason is the recomposition
///
/// Every other row hands `try_get`'s answer straight back, because a column that decodes into its
/// Rust type is the whole of what a scalar has to check. Two columns that each decode can still
/// fail to be an instant — a `nanos` past a second, a pair whose halves disagree in sign — and
/// nothing beneath this can see the pair. So the refusal is built here, as
/// [`ColumnDecode`](sqlx::Error::ColumnDecode) naming the **`nanos`** column: it is the half that
/// cannot stand beside the other, and it is a name a `SELECT` can be pointed at.
///
/// What is refused rather than resolved is [`from_parts`](crate::Timestamp::from_parts)'s, stated
/// once for both families — the MongoDB row makes the same call and gives the same answer in its
/// own vocabulary.
/// **A composite column whose VALUE columns disagree about being there.**
///
/// The absence of an optional composite is *every one of its value columns is `NULL`*, and its
/// presence is *none of them is*. A row in neither state was written by nothing this crate does:
/// the bind pushes the whole value or the whole width of `NULL` — see
/// [`Carrier`](crate::Carrier)'s own `Option<T>` row — so a half-null value is a hand migration, a
/// second writer, a restored dump, or a column list two statements disagree about.
///
/// It is REFUSED rather than resolved, and that is the same standing every other recomposition on
/// this page takes: a `nanos` past a second and a zero denominator are refused here too, because a
/// value quietly minted around a hole is the one outcome a caller cannot detect. Reading a mixed
/// row as [`None`] would DELETE a stored value, and reading it as [`Some`] would need a default for
/// the missing half that no type here has.
///
/// # What it can and cannot name
///
/// Both columns: the one that holds a value and the one that does not. Between them they say which
/// field is broken and in which direction, which is what a `SELECT` can be pointed at.
///
/// It does NOT name the ROW. Nothing at this layer holds a key — [`Assemble`] is handed a row and a
/// path, and the record's identity is a column like any other — so the refusal names the columns and
/// leaves the row to the query that produced it. That is stated rather than worked around: minting
/// a key here would mean this page knowing which of a row's columns is the address.
/// **A NULLABLE COLUMN IS ITS VALUE COLUMNS' `NULL`S**, read through the value's own decode — one
/// rule for a scalar and for a composite, because a scalar is the case where there is one value
/// column and it is the field itself.
///
/// ```text
/// every VALUE column NULL → None
/// no VALUE column NULL → Some(T::assemble(…))
/// SOME of them NULL → PartialCompositeError, naming both
/// ```
///
/// # The DERIVED columns are not consulted, and that is the interlock
///
/// A composite's DERIVED leaves — [`Nullable`](crate::ColumnShape::Nullable) and
/// [`Derived`](crate::ColumnShape::Derived) alike — are an INDEX beside the value. `at_nanos` holds
/// the position of an instant and is `NULL` for one past the ±292-year ceiling, which is a fact
/// about ORDERING and says nothing about whether the field is there; counting it would read a
/// stored instant back as absent, which is the exact misreading the leaf grain exists to prevent.
///
/// The bit this walk reads is [`holds_value`](crate::ColumnShape::holds_value), and it is
/// deliberately NOT the DDL's. `BoundingBox`'s `area` takes `NOT NULL` and is passed over here all
/// the same, because *outside the value* and *may be `NULL`* are two questions and this one asks
/// only the first. While a derived leaf could only be spelled nullable those were one bit, and this
/// note used to say so.
///
/// # It went from sqlx's `Decode` to the value's own `Assemble`, and that is what admitted composites
///
/// The row this replaces was `plain_column::<Option<T>>` and demanded `Option<T>: Decode + Type` —
/// which a MULTI-COLUMN value can never satisfy, there being no single column for sqlx to decode.
/// So an optional composite rendered correct DDL, bound correct `NULL`s, and was `E0277` the moment
/// its row was read.
///
/// Asking `T`'s own [`Assemble`] instead costs nothing and needs nothing new: `T: Assemble` and
/// `T: ColumnKind` are the two rows a NON-optional field of the same type already writes, so no
/// type gains an obligation by becoming optional — and several gain a face they did not have, the
/// `NonZero*` family among them, whose `Option` had no `Decode` either.
///
/// # A SCALAR reads exactly what it read before
///
/// Empty [`SEGMENTS`](crate::ColumnKind::SEGMENTS) means the field IS its one value column, so the
/// test is that column's own `NULL` and the mixed state is unreachable — one column cannot disagree
/// with itself. What it costs is one `try_get_raw` beside the `try_get`, which is a `ValueRef` off a
/// row already in hand.
/// What the VALUE columns beneath one field say about the field being there.
/// Whether the VALUE columns of a `T` at `under` hold anything.
///
/// The probe is [`try_get_raw`](sqlx::Row::try_get_raw) rather than a typed read, and the reason is
/// that this asks a question no type answers: whether a column is `NULL` is the driver's fact, and
/// asking it typed would mean decoding a value in order to discover there is not one. A column the
/// statement did not select still refuses here, by its own name, exactly as a typed read would.
/// A COLLECTION riding a column of the row — a Postgres array, or the `BLOB`/`BYTEA` a `Vec<u8>`
/// decodes from — is that ONE column, which is the width its shape already answers. Where a dialect
/// keeps the elements in an edge table the field is decoded by nobody: the emitted read binds the
/// empty collection and the materialization fills it.
/// The typed id is one column whatever entity it addresses, exactly as its width and its carrier row
/// both say — the marker reaches no column, so it reaches no read either.
/// The temporal wrapper reads as one column, through the `Decode` its own module supplies — the same
/// delegation its carrier row makes, one direction over.