ingraph 0.1.0

A declaration-driven indexing framework: records and nodes are written as Rust types, and the storage rows, the dataflow between them and the GraphQL query surface are emitted from the declaration.
Documentation
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
//! WHAT LANGUAGE IT IS IN: the identity a track's words carry, and the vendored registries that
//! identity is read against.
//!
//! [`super`]'s law is ONE NAME PER INVARIANT, arriving when a caller asks for it — and this family
//! is that law read at FAMILY SCALE rather than bent to admit five names at once. The invariant
//! here is a STANDARD — BCP 47, and the three ISO registries under it — and a standard does not
//! arrive one type at a time: a language, a script and a region are three subtags of ONE grammar,
//! an identity is the three composed, and a detection is that identity with a confidence beside it.
//! What arrived is ONE invariant with five names, not five inventions; making any of the three
//! subtags a `String` inside a composite would put three folds somewhere a caller cannot see them.
//!
//! # There is NO UPSTREAM TYPE HERE TO WRAP, and this is the only house in [`super`] like that
//!
//! [`Confidence`](crate::Confidence) is a float's invariant, [`Timestamp`](crate::Timestamp) is
//! `jiff::Timestamp`'s and [`Count`](crate::Count) is a `u64`'s — each a value that already exists,
//! given the wire face, the filter and the storage shape that the orphan rule reserves to the crate
//! owning the type. A language is not such a value. It is a published TEXT FILE, and what this
//! house does is turn one into types.
//!
//! # Where it came from, and the one rename the move cost
//!
//! The family arrived from `mediagraph` under #428, whole: the five types, the generated registry
//! table, the generator behind it and all of its tests, with no behaviour changed. What could not
//! come verbatim is one NAME. The arriving type was called `Script`, and
//! [`WritingSystem`](crate::WritingSystem) already holds that word's other meaning here — *which
//! writing system is this codepoint in*, asked of text by [`script_runs`](crate::script_runs). This
//! one asks *which script did this tag DECLARE*, which is a subtag read out of a registry and never
//! off a character, so it is [`ScriptSubtag`] and its scalar and filter are `ScriptSubtag` and
//! `ScriptSubtagFilter` on the wire. Every FIELD spelled `script` is untouched: a seat's name is the
//! question it asks, and that question did not move.
//!
//! # ZERO language knowledge is written here
//!
//! Not a subtag, not a name, not a fold. Two authority files are vendored under `xtask/vendor/` and
//! `cargo xtask gen` turns them into [`registry::table`], which is checked in; `cargo xtask check`
//! regenerates it and refuses if the two disagree — which `cargo test -p xtask` runs as an ordinary
//! test. So the vocabulary this house admits is a function of those files, a registry bump is a
//! diff a reviewer reads, and there is no hand-typed list anywhere for a subtag to be missing
//! from.
//!
//! The rule earns its keep on the case the scene actually presents. A container's language tag is
//! dirty in ways no small hand-written table anticipates — an mkv writes ISO 639-2/B `ger`, an mp4
//! writes 639-2/T `deu`, a muxer writes `iw` for Hebrew forty years after the registry renamed it
//! `he`, and plenty write `und` or nothing at all. Each of those is a row in a published table, and
//! the way to get all of them right is to read the table.
//!
//! # Two files, because one of them cannot answer the question
//!
//! The IANA language-subtag-registry is the BCP 47 authority and feeds everything but ONE column.
//! It cannot fold `ger` or `deu`, because it contains neither word: BCP 47 takes a language's
//! two-letter code where one exists and never registers the three-letter one beside it, so the
//! whole ISO 639-2 alpha-3 space for a major language is absent from it — and that is exactly the
//! space a container writes. The ISO 639-2 registrar's own table is vendored beside it and feeds
//! that column alone. See [`registry`], and the `xtask` crate, where the argument is made in full.
//!
//! # The five types, and which of them a declaration actually holds
//!
//! ```text
//!   Language  ScriptSubtag  Region      one validated subtag each, one column each
//!   LanguageId                    the three composed, plus a lossless tail — four columns
//!   DetectedLanguage              an identity and a confidence — five columns
//! ```
//!
//! A track's DECLARED language is a `LanguageId`, or an `Option<LanguageId>` where the file said
//! nothing. A DETECTOR's answer is a `Vec<DetectedLanguage>` — several candidates, each with its own
//! confidence — and the collection is what carries the ranking, the element knowing nothing about
//! its own.
//!
//! The three subtag types are rarely a column of their own and are declared as types anyway, which
//! is the same decision `mediatime`'s halves get: each has a grammar, a canonical form and a
//! registry column behind it, so making one a `String` inside a composite would put three folds
//! somewhere a caller cannot see them. What a caller does hold directly is the FILTER over one —
//! `{ language: { eq: "zh" } }` reaches a `Language` operand, which is the ruled *all Chinese*.
//!
//! # ONE fold per question, applied at the DOOR
//!
//! Every canonicalisation this house does happens once, when a value is constructed, and nowhere
//! else. That is what makes equality useful and storage exact: two spellings of one identity become
//! one value before anything compares them, so a stored column and a query operand meet without
//! either side knowing the other's spelling.
//!
//! | question | folded by | reading a column of |
//! |---|---|---|
//! | is this the same language? | `alpha3`, then `Preferred-Value` | ISO 639-2, then BCP 47 |
//! | is this the same script? | ASCII case alone | — |
//! | is this the same region? | ASCII case, then `Preferred-Value` | BCP 47 |
//! | is this the same identity? | the three, then `Suppress-Script` | all of them |
//!
//! # The three subtag types are ONE shape, and the shape is where the family words live
//!
//! [`Language`], [`ScriptSubtag`] and [`Region`] each hold a validated [`Utf8Bytes`] in its own
//! canonical case, and every one of them owes the same twelve rows: a rendering, a parse, a wire
//! crossing IN and one OUT, a filter interpretation, a column, a bind, a decode, a cursor, a
//! document form, a document READ and a KEY. Not one of those twelve differs between the three by
//! anything but the type's name, so they are emitted by [`subtag_citizen`] rather than written out
//! three times — the same bargain `opt_accessor!` takes for a filter's operator slots one level up.
//!
//! # The three subtags are KEYS and the two composites are not, and that is one sentence
//!
//! A key is a value the framework can ADDRESS a row by, and [`Id`](crate::Id) admits one on
//! transparency: a subtag holds a [`Utf8Bytes`] and adds nothing a key can see, so it says so once —
//! `unsafe impl DelegatesId` — and stands at a record's `#[ingraph(id)]` or an aggregate's
//! `#[ingraph(group)]`. *How many tracks are in each language* is that row spent: the group column is
//! a [`Language`], the mounted census row is keyed by it, and `ger` and `de` fold into one row before
//! anything counts them.
//!
//! [`LanguageId`] and [`DetectedLanguage`] make NO such claim and cannot. Each holds SEVERAL values —
//! four seats and five — so there is no single member to be transparent to, and the vocabulary's
//! third law is transparency rather than composition. A declaration wanting to key by a whole
//! identity keys by its rendering, which is the tag [`Display`](core::fmt::Display) writes and
//! [`FromStr`](core::str::FromStr) reads back.
//!
//! What is NOT in the macro is everything a reader comes here to check: the structural grammar each
//! type admits, the case it folds onto, which registry columns it folds THROUGH, and the sentences
//! its door refuses with. Those are the type's subject and each one spells them out.

mod detected;
#[cfg(feature = "async-graphql")]
mod graphql;
mod id;
mod language;
mod region;
pub mod registry;
mod script;
mod subtag;

#[cfg(test)]
mod tests;

pub use detected::{DetectedLanguage, DetectedLanguageFilter};
pub use id::{
  LanguageId, LanguageIdColumnError, LanguageIdFilter, LanguageIdOperand, ParseLanguageIdError,
};
pub use language::{Language, LanguageWire, ParseLanguageError};
pub use region::{ParseRegionError, Region, RegionWire};
pub use script::{ParseScriptSubtagError, ScriptSubtag, ScriptSubtagWire};
#[cfg(feature = "sqlx")]
pub use {
  detected::SqlDetectedLanguageComparison,
  id::{LanguageIdCrossingError, SqlLanguageIdComparison},
};

/// Generate one subtag type's CITIZENSHIP — the rows that are the same row for all three, and the
/// reason this house has a macro at all.
///
/// | row | what it says |
/// |---|---|
/// | [`Display`](fmt::Display), [`Debug`](fmt::Debug) | the canonical subtag, and nothing around it |
/// | [`FromStr`] | the parse, forwarded to the type's own door |
/// | [`AsRef<str>`], [`From`] × 2 | the text out, borrowed and owned |
/// | [`ToGraphqlInput`] / [`ToGraphqlOutput`](crate::ToGraphqlOutput) | the wire crossing, both directions — the IDENTITY, the type being its own scalar |
/// | [`ScalarWire`] | what a filter over it is NAMED, and the eight operators' carrier |
/// | [`CompositeFilterMarker`] / [`DefaultMarker`] | the interpretation a column is read under: the framework's COMPOSITE reading |
/// | [`ColumnKind`](crate::ColumnKind) | ONE column — the default, stated rather than inherited |
/// | [`Carrier`](crate::Carrier) / [`Assemble`](crate::Assemble) / [`CursorValue`](crate::CursorValue) | the bind, the decode and the keyset position |
/// | [`MongoCarrier`](crate::MongoCarrier) | the same canonical text, as the BSON a document holds |
/// | [`MongoExtract`](crate::query::mongo::MongoExtract) | the same canonical text, READ back — [`MongoCarrier`]'s mirror, and [`Assemble`](crate::Assemble)'s twin on the other backend |
/// | [`DelegatesId`](crate::DelegatesId) | **the KEY row** — the transparency assertion, over the [`Utf8Bytes`] the type holds |
///
/// # The decode, the cursor AND THE MONGO READ all RE-VALIDATE, and that is not belt and braces
///
/// A column is `TEXT`, a cursor is a client's bytes, and a BSON field is a document some other
/// writer produced, so none of the three can promise the invariant this type carries: nothing stops
/// a `TEXT` column holding `!!!`, nothing stops a page token being edited, and nothing stops a
/// document holding a `string` that names no subtag. All three therefore go through the type's own
/// door, and a value that does not name a subtag is a decode error — or a [`MongoTypeError::Range`]
/// — rather than a `Language` whose type says it cannot exist.
///
/// **A decode CANONICALISES, which is the one place that is worth saying twice.** The door folds,
/// so a column — or a document — holding `ger` reads back as `de`, which is what a row written
/// before a registry bump, or by a writer that is not this crate, actually needs. It also means a
/// read-back value can differ from the stored bytes, and the write path is what keeps that from
/// mattering: a value bound or carried out is already canonical, so a row this crate wrote reads
/// back byte for byte.
///
/// # The MONGO READ's refusal is a FIXED sentence per type, and that is a narrower answer than
/// the SQL decode gives
///
/// [`sqlx::Error::Decode`] boxes the door's own [`Result::Err`] verbatim, so a caller reading a SQL
/// row sees the exact rule that broke — `ParseLanguageError::NotAlphabetic`, carrying the offending
/// character. [`MongoTypeError`] is a closed vocabulary of three variants and its
/// [`Range`](MongoTypeError::Range) arm holds a `&'static str`, which cannot carry one: the vocabulary
/// was ruled shut over a leaf where BSON is self-describing and there is normally no parse to fail.
/// A subtag's read is the first row in this vocabulary where there IS one, and the answer takes the
/// same shape the narrowing-integer and fixed-width-blob rows in `query::mongo::extract` already
/// do for their own domain checks: one fixed sentence for the type, naming the FIELD rather than
/// the character. What is never lost is which BSON type arrived — a wrong-typed value still gets
/// [`MongoTypeError::Type`], naming what [`alias`](crate::query::mongo::alias) read off it, since
/// that half of the refusal costs nothing to keep precise.
///
/// [`sqlx::Error::Decode`]: https://docs.rs/sqlx/latest/sqlx/enum.Error.html#variant.Decode
/// [`MongoTypeError`]: crate::query::mongo::MongoTypeError
macro_rules! subtag_citizen {
  ($subtag:ident, $wire:ident, $error:ident, $filter:literal) => {
    /// The canonical subtag, and nothing else — no quotes, no wrapper, no type name.
    impl ::core::fmt::Display for $subtag {
      #[inline]
      fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
        f.write_str(self.as_str())
      }
    }

    /// Written out rather than derived, so an assertion message reads `Language("de")` rather than
    /// the [`Utf8Bytes`] representation's own three-field shape.
    impl ::core::fmt::Debug for $subtag {
      fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
        write!(f, concat!(stringify!($subtag), "({:?})"), self.as_str())
      }
    }

    impl ::core::str::FromStr for $subtag {
      type Err = $error;

      /// The type's own door — see its `new`, where the grammar and the folds are.
      #[inline]
      fn from_str(text: &str) -> ::core::result::Result<Self, Self::Err> {
        Self::new(text)
      }
    }

    impl ::core::convert::AsRef<str> for $subtag {
      #[inline]
      fn as_ref(&self) -> &str {
        self.as_str()
      }
    }

    impl ::core::convert::From<$subtag> for ::smol_bytes::Utf8Bytes {
      #[inline]
      fn from(subtag: $subtag) -> Self {
        subtag.into_inner()
      }
    }

    /// What gives `String: TryFrom<`[`$subtag`](
    #[doc = stringify!($subtag)]
    /// `)>` through std's blanket, which is the crossing a storage comparison over a `TEXT` column
    /// makes — and it makes it with `Error = Infallible`, a canonical subtag being valid text by
    /// construction.
    impl ::core::convert::From<$subtag> for ::std::string::String {
      #[inline]
      fn from(subtag: $subtag) -> Self {
        Self::from(subtag.as_str())
      }
    }

    /// The crossing is the IDENTITY: this type is its own GraphQL scalar, so an operand needs no
    /// second spelling. Every refusal happens at that scalar's door, which is the one route a wire
    /// value takes in.
    impl crate::ToGraphqlInput for $subtag {
      type Input = Self;
      type Error = ::core::convert::Infallible;

      #[inline]
      fn cross(input: Self::Input) -> ::core::result::Result<Self, Self::Error> {
        Ok(input)
      }

      #[inline]
      fn carry(operand: &Self) -> Self::Input {
        operand.clone()
      }
    }

    /// **The crossing OUT**, and it is the identity the crossing IN is: this type IS its own GraphQL
    /// scalar, so what a wire face returns is a BORROW of the value the row already holds.
    ///
    /// The row above says what a client may SEND and this one what a client is GIVEN, and the pair
    /// is what makes a subtag column a whole field type rather than half of one — a filter face with
    /// no return is what [`ToGraphqlOutput`](crate::ToGraphqlOutput)'s own note calls half a field
    /// type. An emitted record's face returns
    /// `<`
    #[doc = stringify!($subtag)]
    /// ` as ToGraphqlOutput>::Output<'_>`, so a declaration storing one could publish NOTHING
    /// without this row: `E0277` at the emitted face, naming the member.
    ///
    /// `&'a Self` and never a clone, which is `String`'s own row's bargain: the scalar door's
    /// `to_value` is what builds the JSON, and it takes a borrow.
    ///
    /// The seat is BARE — no `OutputType` bound is written here — so the row stands in a build with
    /// no GraphQL binding at all, and the library that renders it demands what it needs where it
    /// spends the form. That is the map's own law rather than a choice made in this house.
    impl crate::ToGraphqlOutput for $subtag {
      type Output<'a> = &'a Self;

      #[inline]
      fn to_graphql_output(marked: &Self) -> &Self {
        marked
      }
    }

    /// How this subtag crosses when the framework's own ordering filter holds it — the reading that
    /// gives `ScalarFilter<`
    #[doc = stringify!($subtag)]
    /// `, `
    #[doc = stringify!($wire)]
    /// `>` a face.
    ///
    /// A marker carrying the wire NAME beside the operand, which is the shape every registered
    /// filter here takes: `ScalarFilter<T, W>`'s second parameter is what its input object is
    /// called, so a filter over
    #[doc = stringify!($subtag)]
    /// is named by a type rather than by a table only this crate could extend. The row was written
    /// this way while the family lived in a DECLARING crate, where
    /// `impl InputType for ScalarFilter<`
    #[doc = stringify!($subtag)]
    /// `>` is `E0117` outright; it is kept as it stands because the marker is the surface a
    /// declaring crate still joins through, and the family is the framework's own worked example
    /// of doing so.
    ///
    /// What it buys is that the filter's words are the FRAMEWORK's roster rather than four fields
    /// restated by hand — see the type's own docs, where the eight are read one by one against what
    /// a subtag can honestly be asked.
    pub enum $wire {}

    impl crate::ScalarWire<$subtag> for $wire {
      const NAME: &'static str = $filter;

      type Carrier = $subtag;
      type Error = ::core::convert::Infallible;

      #[inline]
      fn cross(carrier: Self::Carrier) -> ::core::result::Result<$subtag, Self::Error> {
        Ok(carrier)
      }

      #[inline]
      fn carry(operand: &$subtag) -> Self::Carrier {
        operand.clone()
      }
    }

    #[doc = concat!(
      "What guards a [`", stringify!($subtag), "`] column, and it is the same predicate at both \
      host kinds."
    )]
    ///
    /// A subtag stores every field it declares — there is only the one — so the two seats name one
    /// predicate: `ScalarFilter` under the reading this crate declares.
    impl crate::CompositeFilterMarker for $subtag {
      type Filter = crate::ScalarFilter<$subtag, $wire>;
      type ColumnFilter = crate::ScalarFilter<$subtag, $wire>;
    }

    #[doc = concat!(
      "The interpretation a [`", stringify!($subtag),
      "`] field is read under: the framework's COMPOSITE reading, which is the VALUE family's \
      member for one value occupying a column of its own."
    )]
    ///
    /// This crate used to MINT the marker here — a local marker type with its own
    /// [`Marker`](crate::Marker) row — because none of the framework's family words named this
    /// filter, the filter being `ScalarFilter` under a reading this crate declares.
    /// [`CompositeMarker`](crate::CompositeMarker) is the family that was missing, and the row
    /// above is the answer the mint existed to supply.
    ///
    /// Its [`Marker::UnderOption`](crate::Marker::UnderOption) is
    /// [`NullableMarker`](crate::NullableMarker) and not the collection reading: a subtag occupies
    /// a column OF ITS OWN, so it can be `NULL` and the null state is a real observable — a track
    /// whose language nobody recorded is not a track whose language is `und`.
    impl crate::DefaultMarker for $subtag {
      type Marker = crate::CompositeMarker<$subtag>;
    }

    /// ONE column, which is the default — stated rather than inherited, because a reader auditing
    /// this house against [`LanguageId`]'s four columns should find the answer here rather than the
    /// absence of one.
    impl crate::ColumnKind for $subtag {}

    /// **One leaf, and it is the value** — ONE column, so there is no sequence to permute.
    impl crate::DeclaredLeaves for $subtag {}

    /// A subtag is the same as a subtag when its canonical text is — one column, one comparison.
    impl crate::ColumnEq for $subtag {
      #[inline]
      fn column_eq(&self, other: &Self) -> bool {
        self == other
      }
    }

    /// The DECLARATION: whatever this dialect calls text, since the bind below is a `String`.
    ///
    /// The word is delegated rather than named for the reason the bind is: a subtag IS its canonical
    /// text, so the column is a text column and the dialect's own word for one is the only answer.
    /// The delegation carries the ADMISSION with it — a subtag is declarable exactly where text is,
    /// which is everywhere.
    impl<Db> crate::StoredAs<Db> for $subtag
    where
      ::std::string::String: crate::StoredAs<Db>,
    {
      const WORDS: &'static [&'static str] =
        <::std::string::String as crate::StoredAs<Db>>::WORDS;
    }

    /// The bind: the canonical subtag as text.
    ///
    /// An OWNED [`String`] rather than the borrowed `&str` the slot already holds, and the reason
    /// is [`sqlx::QueryBuilder`]'s own lifetime rather than a preference. `push_bind` requires its
    /// value to outlive the builder's `'args`, which this trait's signature leaves unrelated to
    /// `&self` — so a borrow of `self` cannot satisfy it, and the copy is what a bind of borrowed
    /// text costs at this seat. It is at most eight bytes.
    #[cfg(feature = "sqlx")]
    impl<Db> crate::Carrier<Db> for $subtag
    where
      Db: sqlx::Database,
      ::std::string::String: crate::Carrier<Db>,
    {
      #[inline]
      fn push_bind(&self, qb: &mut sqlx::QueryBuilder<Db>) {
        <::std::string::String as crate::Carrier<Db>>::push_bind(
          &::std::string::String::from(self.as_str()),
          qb,
        );
      }
    }

    /// The decode — one `TEXT` column back through this type's own door.
    ///
    /// Generic over the ROW where the bind is generic over the DIALECT, which is the two traits'
    /// parameters rather than a choice made here.
    #[cfg(feature = "sqlx")]
    impl<'a, R: ::sqlx::Row> crate::Assemble<'a, R> for $subtag
    where
      ::std::string::String: crate::Assemble<'a, R>,
    {
      fn assemble(row: &'a R, under: Option<&crate::Path<'_>>) -> ::sqlx::Result<Self> {
        let stored: ::std::string::String = crate::Assemble::assemble(row, under)?;

        Self::new(&stored).map_err(|refused| ::sqlx::Error::Decode(::std::boxed::Box::new(refused)))
      }
    }

    /// **The KEYSET position**: the canonical subtag's UTF-8 bytes, which is what
    /// [`Utf8Bytes`]' own row writes and therefore what a column declared as either pages past.
    ///
    /// The read RE-VALIDATES, because a cursor is a string a CLIENT hands back — so a forged
    /// position is refused rather than turned into a value whose type says it cannot exist.
    impl crate::CursorValue for $subtag {
      #[inline]
      fn write_cursor(&self, out: &mut ::std::vec::Vec<u8>) {
        out.extend_from_slice(self.as_str().as_bytes());
      }

      #[inline]
      fn read_cursor(bytes: &[u8]) -> Option<Self> {
        Self::new(::core::str::from_utf8(bytes).ok()?).ok()
      }
    }

    /// **THE DOCUMENT'S FORM: a BSON `String` holding the canonical subtag** — the same text the
    /// `TEXT` column above binds, at the one BSON type that holds it.
    ///
    /// A subtag is ONE WORD, so there is nothing here of [`LanguageId`]'s composite question: no
    /// sub-document, no key set, no field order. What the row states is that the two families store
    /// one value — a `de` row written by SQLite and a `de` document written by MongoDB carry the same
    /// eight bytes at most — which is what lets one canonicalisation serve both.
    ///
    /// **BSON's `String` order is bytewise over UTF-8**, so `$gt` and `$lt` over such a field walk the
    /// same alphabetical order the type's derived [`Ord`] walks and the cursor above writes. That is
    /// read from MongoDB's documented BSON order rather than measured against a live server here,
    /// which is the posture the register takes for its `BinData` rows.
    ///
    /// # What a DOCUMENT can hold is the narrower question, and the answer is [`Timestamp`]'s
    ///
    /// This row is the FILTER OPERAND's. The document's WRITE is serde's, and no storage type this
    /// crate ships carries a serde row — so a declaration naming a bare
    #[doc = concat!("[`", stringify!($subtag), "`]")]
    /// column under `mongo(…)` is `E0277` at the declaration, and the escape is the one
    /// [`Timestamp`](crate::Timestamp)'s row names: a `type = "…"` with its own conversions, which
    /// for a subtag is the `String` it already converts to and from.
    ///
    /// [`Timestamp`]: crate::Timestamp
    #[cfg(feature = "mongo")]
    impl crate::MongoCarrier for $subtag {
      #[inline]
      fn to_bson(&self) -> ::bson::Bson {
        ::bson::Bson::String(::std::string::String::from(self.as_str()))
      }
    }

    /// **THE READ: the same canonical word, back through the door** — [`MongoCarrier`]'s mirror,
    /// row for row the way `query::mongo`'s own carrier and extract tables are.
    ///
    /// A `string` field is exactly as untrusted as the `TEXT` column [`Assemble`](crate::Assemble)
    /// above reads: nothing stops a document holding `!!!`, one written before a registry bump, or
    /// one written by hand for a test. So the read goes through
    #[doc = concat!("[`", stringify!($subtag), "::new`]")]
    /// rather than wrapping the bytes, which is what makes it CANONICALISE rather than merely
    /// validate — a document holding `GER` reads back as `de`, the value the SQL decode's own
    /// re-validation produces from the same three letters. See the macro's own doc for the shape of
    /// what the refusal carries and does not.
    #[cfg(feature = "mongo")]
    impl crate::query::mongo::MongoExtract for $subtag {
      const BSON: &'static str = "string";

      fn extract(
        value: ::core::option::Option<&::bson::Bson>,
      ) -> ::core::result::Result<Self, crate::query::mongo::MongoTypeError> {
        match value {
          ::core::option::Option::Some(::bson::Bson::String(text)) => {
            Self::new(text).map_err(|_refused| {
              crate::query::mongo::MongoTypeError::Range(concat!(
                "this field holds a string that is not a valid `",
                stringify!($subtag),
                "` subtag"
              ))
            })
          }
          ::core::option::Option::Some(other) => {
            ::core::result::Result::Err(crate::query::mongo::MongoTypeError::wrong_type(
              "string",
              crate::query::mongo::alias(other),
            ))
          }
          ::core::option::Option::None => {
            ::core::result::Result::Err(crate::query::mongo::MongoTypeError::Absent)
          }
        }
      }
    }

    /// **THE KEY ROW**: this subtag stands at a key position — a record's `#[ingraph(id)]`, an
    /// aggregate's `#[ingraph(group)]` — as the [`Utf8Bytes`] it holds.
    ///
    /// [`Id`](crate::Id) is SEALED, so `impl Id` is not a road for a named type even in this crate:
    /// its members are admitted by MEASUREMENT, and the one door beside that is the transparency
    /// assertion below. `Utf8Bytes` is a measured member — text, with the filesystem escape a text
    /// segment takes — and this type is that text under a grammar.
    ///
    /// # The obligation, checked against what this type actually WRITES
    ///
    /// The assertion is that every id duty reading a
    #[doc = stringify!($subtag)]
    /// reads its [`Utf8Bytes`], and the three duties are the segment, the identity and the order:
    ///
    /// * **The filesystem segment** is `store::fs`'s delegation row, which renders the delegate — so
    ///   a subtag addresses exactly the file its text addresses. There is no second rendering
    ///   anywhere in this house to disagree with it: [`CursorValue::write_cursor`](crate::CursorValue)
    ///   above writes `self.as_str().as_bytes()`, which is byte for byte what `Utf8Bytes`' own cursor
    ///   row writes, and [`Carrier::push_bind`](crate::Carrier) binds `self.as_str()` as text.
    /// * **The identity** is the derived [`PartialEq`](core::cmp::PartialEq)/[`Eq`](core::cmp::Eq)/
    ///   [`Hash`](core::hash::Hash), each of which reads the one field and nothing else — two subtags
    ///   are equal exactly when their `Utf8Bytes` are.
    /// * **The order** is the derived [`Ord`](core::cmp::Ord), through the same field, which is the
    ///   alphabetical order the type documents.
    ///
    /// And the type carries NO second field, tag or width: it is a `#[repr(Rust)]` newtype over one
    /// `Utf8Bytes`.
    ///
    /// # The FOLD is the door's, and it strengthens this rather than qualifying it
    ///
    /// `ger`, `GER` and `de` are ONE value here, because the fold happens once at construction and
    /// the value that exists afterwards holds `de`. So the delegate is the FOLDED text, and two
    /// spellings of one identity address one file, key one row and walk one position — which is what
    /// a key needs and what a type folding at comparison time could not give it.
    ///
    /// SAFETY: this type is a newtype holding one [`Utf8Bytes`] and nothing else — no second field,
    /// no tag, no width of its own. Its equality, hash and order are all derived through that one
    /// field, so two values are equal exactly when their delegates are; [`delegate`] is a field
    /// borrow, so it is pure and answers the same inner every time; and every id duty that reads one
    /// reads that text, the segment through the framework's own delegation row and nothing else
    /// through anything.
    ///
    /// [`delegate`]: crate::DelegatesId::delegate
    unsafe impl crate::DelegatesId for $subtag {
      type Inner = ::smol_bytes::Utf8Bytes;

      #[inline]
      fn delegate(&self) -> &::smol_bytes::Utf8Bytes {
        &self.0
      }
    }
  };
}

pub(crate) use subtag_citizen;