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.
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
/// 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
pub use subtag_citizen;