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
//! The storage forms a field DECLARATION spells: the local types a column holds a value AS, with no
//! database named in any of them.
//!
//! # Two layers, and this module is the first
//!
//! ```text
//! postgres(type = "BeU64") the DECLARATION: what this field is stored as
//! <BeU64 as Carrier<Postgres>> the SQL family: how that stored type binds in one dialect
//! <BeU64 as MongoCarrier> the MongoDB one: the same question, with no dialect to ask it of
//! ```
//!
//! The second layer is per-family and lives with its family. The first is not — and the reason this
//! module exists is that it used to. Every type here sat inside `comparison::sql`, behind the `sqlx`
//! feature, so a `u64` field was declarable on SQLite and undeclarable on MongoDB **for a reason
//! that had nothing to do with MongoDB**: a big-endian encoding holds no `sqlx::Database` anywhere,
//! and it was gated by where it lived rather than by what it names.
//!
//! The framework does not CHOOSE the first layer. Silently wrapping a `u64` field into a big-endian
//! blob behind the declarer's back is exactly the magic that was removed: an omission is an
//! unsatisfied carrier bound naming the field's type, never a query that binds something plausible.
//!
//! # What is here, and what deciding it is NOT
//!
//! | storage form | what declares it | feature |
//! |---|---|---|
//! | [`BeU64`] | a `u64` on a backend with no unsigned 64-bit column | none |
//! | [`BeU128`], [`BeI128`] | a 128-bit integer, which no backend here has a column for | none |
//! | [`Embedding<E, N, S>`] | an embedding field, whose model fixes the element type, the width and — where it is named — the [SPACE](Anon) | none |
//! | [`Temporal<T>`] | jiff's six registered types, through the `time` type each crosses into — and an `i32` for a zone offset | `jiff` + `time` |
//!
//! Whether a backend can HOLD one of these is that backend's own answer, stated in its carrier
//! table and nowhere here. Being able to NAME the type is what this module supplies, and it is the
//! half that was missing.
//!
//! # [`Count`](crate::Count) IS NOT HERE, and the line it sits the other side of is worth reading
//!
//! It is the framework's cardinality, it crosses into an `i64` on the two dialects with no unsigned
//! 64-bit column, and it still belongs in `primitives` rather than in this table. Every form above
//! is a STORAGE ESCAPE a declaration spells in a `<db>(type = "…")` seat — the second name a field
//! wears because its own type has no column — and every one of their crossings is INFALLIBLE and
//! total, which is what `carrier_from!`'s own note states. A `Count` is neither: it is the field's
//! OWN type, written where the field is declared, and its crossing SPENDS an invariant it carries
//! (*a cardinality counts rows that EXIST*, so it is bounded by the physical store).
//!
//! So the two modules divide by what a name IS rather than by what it crosses into: a value type
//! carrying an invariant its representation cannot state lives with `Confidence` and `Timestamp`,
//! and an encoding a declaration reaches FOR a value type lives here.
//!
//! # One codec, and it belongs to the type
//!
//! [`BeU64::to_blob`] and its five siblings are inherent and public, which is what keeps a shared
//! name from acquiring two meanings. `BeU64` promises one thing — the order-preserving eight-byte
//! big-endian blob — and two families each writing `to_be_bytes` into their own carrier row would
//! be two encodings that agree today and are free to stop. Every row calls the method instead, so a
//! `BeU64` column holds the same bytes whichever backend wrote it, and a downstream family
//! implementing its own trait for these types reaches the same bytes through the same call.
//!
//! Equal-length big-endian blobs compare bytewise exactly as the numbers do, so an index over such
//! a column is an index over the numeric order — SQLite's `BLOB` and Postgres's `BYTEA` both order
//! that way. `i128` offsets through a sign-bit flip so the negative range sorts below the positive
//! one.
use PhantomData;
use Arc;
/// A `u64` stored as its order-preserving 8-byte big-endian blob — SQLite `BLOB`, Postgres `BYTEA`,
/// MongoDB generic `BinData`. MySQL has `BIGINT UNSIGNED`, so it binds `u64` natively and never sees
/// this type.
///
/// # Layout, and the slice-level bind it exists for
///
/// All three carriers are `#[repr(transparent)]` and derive [`bytemuck::TransparentWrapper`], so
/// `&[u64] ⇄ &[BeU64]` is a **zero-copy, safe** conversion — `TransparentWrapper::wrap_slice` /
/// `peel_slice`, with the `unsafe` argument owned by the derive rather than restated here.
///
/// What that buys is one fewer safety argument, not a crate without any. The single hand-written
/// `unsafe` block this crate has is the borrowed names' view — written once and expanded once per
/// name type, over a layout claim of its own — and it says nothing about these three, which is the
/// point of letting the derive make this one.
///
/// The consumer that justifies it is the SQL family's, which is why the two derives ride the `sqlx`
/// feature while the type rides none: a large `IN` list costs ONE BIND PER ELEMENT, and bind counts
/// are a real ceiling — 65535 on Postgres and MySQL, 32766 on SQLite. The slice-level form (Postgres
/// `= ANY($1)`) collapses N binds to one and takes a `&[T]` whose element type is the carrier.
/// MongoDB has no such position: `MongoCarrier` returns an owned `Bson` per element, so a membership
/// list is built by mapping and never by peeling a slice.
///
/// **That path is not built here, and the transparent conversion is not the only thing it needs.**
/// Measured: `push_bind(&[BeU64])` on Postgres is `E0277`, `the trait bound BeU64: PgHasArrayType is
/// not satisfied` — sqlx routes `&[T]` through an ARRAY type, so a carrier joining that path also
/// has to name the Postgres array OID its element blob lives in. On SQLite the path does not exist at
/// all: `[i64]: Encode<Sqlite>` is unimplemented, because SQLite has no array type to bind into.
///
/// # Why [`bytemuck::Pod`] is deliberately NOT derived
///
/// All three shapes structurally qualify, and deriving it would still be wrong. `Pod` advertises a
/// NATIVE-endian byte view: `bytemuck::cast_slice::<BeU64, u8>(&keys)` would compile and hand out
/// `01 00 00 00 00 00 00 00` for `BeU64(1)` on a little-endian host — the exact opposite of the
/// `00 00 00 00 00 00 00 01` this crate stores, and of the byte order the type exists to impose.
/// These carriers exist BECAUSE the stored bytes are big-endian; a `Pod` impl would let a caller
/// contradict that with a cast the compiler blesses.
///
/// The encoding lives in [`to_blob`](Self::to_blob), never in the value's memory layout.
/// [`bytemuck::Zeroable`] IS derived — an all-zero blob is a valid value of each, and it carries no
/// such claim.
// The two derives are the SQL family's, so they ride its feature: `bytemuck` arrives with `sqlx`
// and the slice peel serves a Postgres bind. The type itself is neutral and gated on nothing, which
// is the whole distinction this module was made for — a build with another backend gets the storage
// form and not a dependency it has no position to use.
;
/// A `u128` stored as its order-preserving 16-byte big-endian blob — no backend here has a 128-bit
/// integer column. See [`BeU64`] for the layout contract the three share.
;
/// An `i128` stored as its order-preserving 16-byte big-endian blob, sign-flipped so the negative
/// range sorts below the positive one. See [`BeU64`] for the layout contract the three share.
;
/// The crossing into each carrier is INFALLIBLE and total — every value of the width has a blob —
/// so a field declaring one needs no converter and its comparison's error type is
/// [`Infallible`](core::convert::Infallible).
}
)+
};
}
carrier_from!;
/// The SPACE an embedding is in when nobody named one — the third parameter's default.
///
/// Two [`Embedding<f32, 768>`](Embedding)s are both `Embedding<f32, 768, Anon>`, so they unify and
/// nothing is checked. That is the zero-burden state and the one every declaration written before
/// the space axis existed is in: a graph that never names a space pays nothing for the parameter and
/// reads no differently.
///
/// # The SEALED PRIVATE-UNIT form, and it is the form a declarer copies
///
/// `pub struct Anon(());` rather than `pub struct Anon;`. The private unit field is what makes the
/// type non-constructible outside this module, and both halves of that matter:
///
/// - a space marker is a NAME the compiler compares, never a value anybody holds. A bare unit struct
/// is a value expression its own declarer never meant to hand out, so the `(())` is the type saying
/// what it is for;
/// - it is forward-compatible in the direction that costs nothing. A bare unit struct that later
/// grows a field breaks every `Clip` expression written against it; this one has none to break.
///
/// A declarer mints their own the same way — the canonical example, which is the whole of what
/// declaring a space takes:
///
/// ```
/// use std::sync::Arc;
///
/// use ingraph::Embedding;
///
/// /// The CLIP space: the embeddings one model family produces, told apart from every other
/// /// family's by this type and by nothing else.
/// pub struct Clip(());
///
/// let coordinates: Arc<[f32]> = Arc::from(vec![0.5; 768]);
/// let tagged: Embedding<f32, 768, Clip> = Embedding::new(coordinates).unwrap();
///
/// assert_eq!(tagged.coordinates().len(), 768);
/// ```
///
/// Nothing there implements a trait and nothing registers the marker. A space is a name, the
/// compiler already compares names, and the whole mechanism is that comparison.
);
/// An embedding, at the ELEMENT TYPE and the WIDTH its model produces — and, where one is named, the
/// SPACE it lives in. All three are carried in the type.
///
/// Spelled `Embedding<f32, 768>` where a field declares one, and `Embedding<f32, 768, Clip>` where it
/// names the space too. The element leads and the width follows, which is the order
/// [`BytesFilter<B, K>`](crate::BytesFilter) already reads in — the thing held first, the way it is
/// held second — and the space comes last because it is the part a declaration may leave out.
///
/// # The SPACE is a type, and the three states are the compiler's own arithmetic
///
/// A width already refuses the mismatch it can see: a 768-wide producer cannot feed a 1152-wide
/// column. What a width cannot see is two models of the SAME width whose coordinate systems have
/// nothing to do with each other — a 768-dimensional CLIP vector and a 768-dimensional text vector
/// are the same type today, and a `knn` over the wrong one answers well-formed nonsense. `S` is that
/// distinction written down, and every state of it is a compilation:
///
/// | producer | consumer | what happens |
/// |---|---|---|
/// | `Embedding<f32, 768>` | `Embedding<f32, 768>` | both are [`Anon`] — they unify, nothing is checked, nothing is paid |
/// | `Embedding<f32, 768, Clip>` | `Embedding<f32, 768, Siglip>` | `E0308` at the wiring site, NAMING BOTH SPACES |
/// | `Embedding<f32, 768>` | `Embedding<f32, 768, Clip>` | `E0308` — [`Anon`] is not `Clip` |
///
/// The third row is the law *a named space demands its counterpart name one*, and it needs no rule
/// written anywhere: non-unification IS the demand. That is why there is no attribute word for a
/// space, no registry of spaces, and no row in the launch walk's `validate` — a check the compiler
/// performs is not a check the framework can perform later or better.
///
/// # The parameter DEFAULTS, which is what makes it free
///
/// `S = Anon`, so `Embedding<f32, 768>` is a complete type and every declaration written before this
/// parameter existed means exactly what it meant. A graph adopts the axis one edge at a time: name a
/// space on a tower's output and on the election it feeds, and those two are checked while the rest
/// of the graph goes on unifying with itself.
///
/// # The marker is held as `PhantomData<fn() -> S>`
///
/// The spelling every marker in this crate carries — see [`TypedId`](crate::TypedId), which states
/// the argument in full. What it buys here: the auto traits and the variance of an embedding are
/// facts about its COORDINATES, so a marker that is neither [`Send`] nor [`Sync`] cannot make a
/// perfectly ordinary `Embedding<f32, 768, Clip>` unsendable, and a declarer minting a space never
/// has to think about what their marker derives.
///
/// # The width is a fact the TYPE states
///
/// It is known wherever the type is, so nothing has to be told it and nothing can be told it
/// wrongly. That supersedes, by name, the ruling the reference implementation was built on —
/// `legacy/ingraph/src/store/plan/shape/mod.rs`, *"the dimension is the model's, discovered at
/// wiring"* — under which a width was the ONE part of a vector slot's shape no type could supply,
/// and therefore a value passed in at construction with a runtime refusal standing behind it for
/// the case where nobody passed one.
///
/// What that buys is a check the graph was already making. A producer of `Embedding<f32, 768>`
/// cannot feed a column declared `Embedding<f32, 1152>`, because those are two types: the mismatch
/// is a type error where the two are WIRED, not a store error at the first write.
///
/// # The carrier is a shared slice, and the width does not change it
///
/// `Arc<[E]>`, which is what an embedding is in memory whether or not its width is written down.
/// An `[E; N]` carrier would state the same fact about the same field and cost the LOAD — a decode
/// holding a buffer already could no longer hand it over, only copy it into the array — while
/// buying nothing [`DIM`](Self::DIM) does not.
///
/// A slice's length is a runtime fact, so [`new`](Self::new) is where it meets the type's width.
/// That check happens once, at the boundary; every reader past it has the width without asking.
///
/// # `E` is the element type itself, and it carries no bound
///
/// `f32` rather than a marker standing for it. The reference implementation had a marker per
/// element (`element::F32`, whose `Carrier` was `Arc<[f32]>`) because a free `F32` type would have
/// collided with the primitive's name; naming the primitive removes the collision and the mapping
/// at once, and `Arc<[E]>` is then the carrier spelled rather than projected.
///
/// No bound here, because nothing here needs one: a width, a length and a borrow are answerable for
/// any `E` at all. What an ENGINE can materialize is that engine's own question, asked where its
/// face is bound and not on the vocabulary a declaration writes — the same split the module note
/// draws for every other type in it.
///
/// # No layout claim
///
/// The blob carriers are `#[repr(transparent)]` and the temporal wrapper says why it keeps the
/// attribute without the derive. This type takes neither. Its invariant is that the carrier's
/// length IS the width, and a layout claim is precisely what lets a caller mint one without
/// passing the check that establishes it.
///
/// # Examples
///
/// ```
/// use std::sync::Arc;
///
/// use ingraph::Embedding;
///
/// let coordinates: Arc<[f32]> = Arc::from(vec![0.5; 768]);
/// let embedding: Embedding<f32, 768> = Embedding::new(coordinates).unwrap();
///
/// assert_eq!(Embedding::<f32, 768>::DIM, 768);
/// assert_eq!(embedding.coordinates().len(), 768);
/// ```
///
/// A slice of some other length is not a value of this type:
///
/// ```
/// # use std::sync::Arc;
/// # use ingraph::Embedding;
/// assert!(Embedding::<f32, 768>::new(Arc::from(vec![0.5; 1152])).is_none());
/// ```
///
/// And a space is a third fact of the same kind — one width, one element, two types:
///
/// ```
/// # use std::sync::Arc;
/// # use ingraph::Embedding;
/// pub struct Clip(());
///
/// let coordinates: Arc<[f32]> = Arc::from(vec![0.5; 768]);
/// let anonymous: Embedding<f32, 768> = Embedding::new(Arc::clone(&coordinates)).unwrap();
/// let tagged: Embedding<f32, 768, Clip> = Embedding::new(coordinates).unwrap();
///
/// assert_eq!(anonymous.coordinates(), tagged.coordinates());
/// ```
///
/// which nothing can be talked out of:
///
/// ```compile_fail,E0308
/// # use std::sync::Arc;
/// # use ingraph::Embedding;
/// pub struct Clip(());
///
/// fn clip_only(_: Embedding<f32, 768, Clip>) {}
///
/// clip_only(Embedding::<f32, 768>::new(Arc::from(vec![0.5; 768])).unwrap());
/// ```
>);
/// Written rather than derived, because `#[derive(Clone)]` would bound `E: Clone` and the carrier
/// does not: cloning an embedding is a refcount bump on the shared coordinates, at every element
/// type including one that cannot be cloned itself.
/// The other three are written for the SAME reason one parameter further along — and here the reason
/// is no longer a nicety.
///
/// `#[derive(Debug, PartialEq, Eq)]` bounds every type parameter it sees, so a derived pair would
/// demand `S: Debug` and `S: PartialEq + Eq` of a marker that is a NAME and holds nothing. The
/// sealed form a space wears — `pub struct Clip(());` — derives nothing by default, so the derive
/// would silently take [`Debug`] and equality away from `Embedding<f32, 768, Clip>` while leaving
/// them on `Embedding<f32, 768>`: the axis would cost a declaration two impls for naming a space,
/// which is exactly the burden the defaulted parameter exists to avoid.
///
/// The phantom itself needs no bound at all — std's [`PhantomData`] impls are unconditional — so
/// each of these is the derived body with `S` left out of the bounds.
/// A temporal value in the form a column holds it — the local type the jiff → `time` crossing needs
/// in order to be spelled at all.
///
/// # A coherence result, not a taste
///
/// **sqlx 0.9 ships no `jiff` integration** and BSON has no nanosecond instant, so jiff's registered
/// types reach a column through `time`'s four — and, for a zone offset, through an `i32` — either
/// way. The crossing a comparison uses
/// is `V: TryFrom<D>`, and `impl TryFrom<jiff::Timestamp> for time::OffsetDateTime` is `E0117` here
/// because both types are foreign. Neither escape works, measured in the SQL family where the
/// question first arose:
///
/// - a concrete `impl<Db> TryFromFilter<ScalarFilter<jiff::Timestamp>> for
/// SqlScalarComparison<time::OffsetDateTime, Db>` is **`E0119`** against the generic crossing,
/// *"upstream crates may add a new impl of trait `TryFrom<jiff::Timestamp>` for type
/// `time::OffsetDateTime` in future versions"*;
/// - a blanket `impl<D: TemporalStorage, Db> TryFromFilter<ScalarFilter<D>> for
/// SqlScalarComparison<D::Storage, Db>` is **`E0119`** for the same reason with no note, since the
/// projection unifies with the generic impl's `V`.
///
/// A LOCAL storage type has neither problem, and it needs no new trait and no second crossing: the
/// blanket [`From`] below is legal because the self type is local, and std's own `TryFrom` blanket
/// lifts it with [`Infallible`](core::convert::Infallible) — so the temporal crossing is *provably*
/// unable to fail rather than merely always returning `Ok`, and it travels the existing
/// `V: TryFrom<D>` seam that every other kind travels.
///
/// | field type | stored as | why |
/// |---|---|---|
/// | `jiff::Timestamp` | `Temporal<`[`time::OffsetDateTime`]`>` | the instant, in UTC |
/// | `jiff::Zoned` | `Temporal<`[`time::OffsetDateTime`]`>` | its `timestamp()`; `Ord`/`Eq`/`Hash` all delegate there, so the zone takes no part in any operator this layer renders |
/// | `jiff::civil::Date` | `Temporal<`[`time::Date`]`>` | the same `-9999-01-01 ..= 9999-12-31` span on both sides |
/// | `jiff::civil::Time` | `Temporal<`[`time::Time`]`>` | the same `00:00:00 ..= 23:59:59.999999999` span on both sides |
/// | `jiff::civil::DateTime` | `Temporal<`[`time::PrimitiveDateTime`]`>` | the two civil rows paired — the one `time` type that names no zone |
/// | `jiff::tz::Offset` | `Temporal<i32>` | its SECONDS; sqlx has no `time::UtcOffset` row, and jiff's `±25:59:59` fits an `i32` four orders over |
///
/// All six crossings are TOTAL, measured; see [`TemporalStorage`](crate::TemporalStorage) for the
/// range table. What a BIND then does to a sub-microsecond operand is a different question with a
/// different answer per backend, and each family's carrier table is where it is stated.
///
/// ```
/// # use ingraph::Temporal;
/// let at: jiff::Timestamp = "2024-05-06T07:08:09.123456789Z".parse().unwrap();
/// let stored: Temporal<time::OffsetDateTime> = at.into();
///
/// assert_eq!(stored.get().unix_timestamp_nanos(), at.as_nanosecond());
/// ```
///
/// Nothing there names a converter. The field's type is what selected `time::OffsetDateTime`, and
/// `<db>(into = …)` remains the escape for a column that wants some other form.
///
/// # No public constructor, and that is the point
///
/// The only way to build one is [`From`], which routes through
/// [`TemporalStorage`](crate::TemporalStorage) — the same arrangement `MySqlDuration` uses to make
/// its checked conversion the only reachable one. Here what would be lost to a public field is the
/// UTC normalization: a hand-built `Temporal(offset_date_time_at_plus_nine)` renders the same query,
/// binds the same once, and on SQLite stores RFC 3339 text carrying `+09:00` that sorts against a UTC
/// column wrongly. sqlx's Postgres and MySQL encoders would silently normalize the same value, so two
/// of the three dialects would agree with the caller's intent and one would not.
///
/// # Why [`bytemuck::TransparentWrapper`] is not derived here
///
/// The three blob carriers derive it for the slice-level bind — `&[u64] ⇄ &[BeU64]`, a peel from
/// the element type sqlx knows to the one it does not. A temporal operand needs no peel: sqlx
/// encodes a Postgres array ELEMENT BY ELEMENT through each element's [`Encode`](sqlx::Encode), so
/// `&[Temporal<T>]` binds through that family's own delegating impls and never through a layout
/// claim. `#[repr(transparent)]` stays because it is true and free, and nothing reads it.
// `pub(crate)` and not private: a family's rows delegate by MOVING the stored value into sqlx's
// `Encode`, which `get`'s `&T` cannot supply. What the visibility is defending is the PUBLIC
// surface — a caller who could build one out of an unnormalized value — and a crate-internal row
// is on the other side of that line.
T);
/// The whole built-in crossing, in one impl and with no new trait beside the one that already names
/// the map.
///
/// Legal where a `TryFrom` between the two foreign types is not, because the self type is LOCAL. It
/// does not overlap std's reflexive `impl<T> From<T> for T` either: that would need
/// `Temporal<X>: TemporalStorage`, and both names belong to this crate, so rustc can see no such
/// impl exists and that no downstream may add one.
///
/// [`From`] rather than [`TryFrom`] because every built-in row is total — measured, not assumed —
/// and std's blanket then supplies the fallible spelling at
/// [`Infallible`](core::convert::Infallible). A crossing that CANNOT be `Err` is a stronger
/// statement than one that always returns `Ok`, and this is where the difference is bought.