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
//! The [`DetectedLanguage`] pair: what a detector decided a track is in, and how sure it was.
use fmt;
use crate::;
use ;
pub use SqlDetectedLanguageComparison;
/// One detection: which language a track was decided to be in, and how confident the detector was.
///
/// The pair is deliberate, for the reason every DETECTION type's is. A detector emits several
/// candidates per track, each with its own confidence, so a row that recorded only the language
/// would lose the one number that says whether to believe it — and a query narrowing on language and
/// on confidence separately would let a track where German scored `0.2` answer a question about
/// German above `0.8`, on the strength of some other language scoring `0.9`.
///
/// # The carrier is a whole [`LanguageId`], and that is what makes the type outlast its detectors
///
/// Whisper emits a bare two-letter code and nothing else, so today every value here has a
/// `LanguageId` with three empty seats. Carrying the composite anyway costs one word per absent seat
/// and buys the thing a narrower carrier would have to be redesigned for: the day a detector
/// distinguishes simplified from traditional Chinese — which is a REAL detector's real output rather
/// than a hypothetical — its answer lands in the script seat and nothing here, in storage or on the
/// wire, changes shape.
///
/// It is also lossless in the other direction. A bare `zh` from a detector and a `zh-Hans` from a
/// container are two identities, not one identity and a note; the type that holds them is the same
/// type, so nothing has to decide which of the two a column is for.
///
/// # TOP-K is the FIELD's shape, not this type's
///
/// A detector's *k* candidates are a `Vec<DetectedLanguage>`, and that is a decision made where the
/// field is declared rather than here: this type is ONE detection, so nothing about it knows or
/// cares whether it is the best one. What the collection reading buys is stated on this type's
/// [`DefaultVecMarker`] row — `any` over one whole detection and `count` over the collection's
/// length, and none of the seven operators a sequence reading would add.
///
/// # Equality is the PAIR
///
/// The same language detected twice at different confidences is two detections, so the confidence
/// is part of the identity rather than a payload hanging off it. That is every detection type's
/// rule, and it holds here for the same reason.
/// The tag and the confidence, which is the whole of what a detection is.
/// The tag, then the confidence in brackets — `zh-Hans (0.94)`.
///
/// A rendering rather than a round trip, and it is worth saying which: nothing parses this back.
/// [`LanguageId`]'s own [`Display`](fmt::Display) IS an inverse of its parse, and a detection's is
/// not, because the pair has no spelling any standard defines.
/// **The crossing OUT** — a BORROW, resolved by the `#[Object]` this type publishes: the four seats
/// of its identity FLATTENED, and the confidence beside them.
///
/// There is no [`ToGraphqlInput`](crate::ToGraphqlInput) row beside it, and the absence is the
/// filter's shape rather than an omission. A client never SENDS a whole detection: what it sends is a
/// [`DetectedLanguageFilter`], whose operands are a [`LanguageIdOperand`](super::LanguageIdOperand),
/// the three subtags and a confidence threshold. A whole-detection `eq` would be an exact float
/// equality against a number a client typed, which is the question this type's
/// [`DefaultVecMarker`] row already argues cannot be asked honestly.
///
/// So the two directions are deliberately unequal here, where they are equal for every other type in
/// this house — and the row that would have made them equal is the one that would have published a
/// question with no true answer.
/// What guards a [`DetectedLanguage`] column — [`LanguageId`]'s row, and the same reading of it: a
/// detection stores every field it declares, so the two seats name one predicate.
///
/// [`LanguageId`]: super::LanguageId
/// The interpretation a [`DetectedLanguage`] field is read under — [`LanguageId`]'s reading, and
/// this crate no longer mints either: a detection occupies five columns OF ITS OWN, so all five can
/// be absent together, which is exactly the VALUE family [`CompositeMarker`] names.
///
/// [`LanguageId`]: super::LanguageId
/// **A COLLECTION of detections is asked through the QUANTIFIERS alone** — the reading
/// [`QuantifiedMarker`] names, and the one this element could not have had from the wide kinds.
///
/// A detector emits *k* candidates per track, so a `Vec<DetectedLanguage>` is what a row actually
/// holds — and the operators [`ListFilter`](crate::ListFilter) would publish over it are seven
/// questions this pair cannot answer honestly. Each of the seven holds a whole DETECTION as its
/// operand, and a detection carries a float:
///
/// * `hasElement` is exact equality against a confidence a client typed, so it answers *no rows* to
/// the question a caller believed they had asked — *was this language detected at about this
/// confidence*.
/// * `eq` and `ne` are that same falseness per element, multiplied by the collection's length.
/// * `gt`, `gte`, `lt` and `lte` compare two whole collections lexicographically, under an order
/// composed of a TAG's alphabetical one and a float's. This family already documents the first as
/// good for exactly one thing — a cursor — and nothing makes it mean more inside a collection
/// comparison than it does outside one.
///
/// What is left is `any` and `count`, and `any` loses nothing: it carries the whole
/// [`DetectedLanguageFilter`], so every question this family CAN ask about one detection — the
/// identity, the three components and the confidence — is askable of a collection's members.
/// `any: { language: { eq: "zh" }, confidence: { gte: 0.8 } }` is *some Chinese was detected, and
/// confidently*, which is the question `hasElement` was pretending to be able to ask.
///
/// **This is where TOP-K lives.** A ranked list of candidates is a collection, `count` asks how many
/// there were, and `any` asks about each — so the ruling's *k* is the field's `Vec` and the two
/// quantifiers, with nothing about ranking in the element type.
/// The filter that guards a [`DetectedLanguage`] column: the whole IDENTITY axis flattened, and the
/// CONFIDENCE nested beside it.
///
/// | facet | slots | operand | asks about |
/// |---|---|---|---|
/// | IDENTITY | `eq`, `ne`, `in`, `notIn` | [`LanguageIdOperand`](super::LanguageIdOperand) | the whole detected tag |
/// | COMPONENT | `language`, `script`, `region` | the three subtags | one seat of it |
/// | CONFIDENCE | `confidence` | [`Score`] | how sure the detector was |
///
/// # The identity axis FLATTENS and the confidence does not
///
/// A client writes `{ language: { eq: "zh" } }` where it writes `{ confidence: { gte: 0.8 } }`, and
/// the asymmetry is the one every detection filter makes and for its reason. What a detection IS is
/// the language: that is the crossing, and a whole-identity `eq` on a
/// face carrying both would have nothing to disambiguate. The confidence is an ATTRIBUTE of that
/// identity, and a bare `eq` on a face carrying both would have to pick which of them it meant.
///
/// The flattened component is `LanguageIdFilter` WHOLE, so all seven of its slots arrive — the four
/// identity words and the three component filters, `isNull` included. Nothing is restated here and
/// nothing can drift: a slot added to that filter appears on this face with it.
///
/// # The two guard ONE detection, and that is why they share a filter
///
/// A track carries *k* (language, confidence) pairs. Were the two questions asked of the track
/// separately, *German above 0.8* would be answered by a track where German scored `0.2` and English
/// scored `0.9` — each half true of a different detection. Holding both in one filter over one
/// detection makes that unrepresentable rather than merely wrong.
///
/// # `confidence` takes the framework's SIX confidence words
///
/// The facet is [`ConfidenceFilter`] — `eq`, `ne`, `gt`, `gte`, `lt`, `lte` — and every one of them
/// is well-defined, because [`Score`]'s constructor refuses `NaN` and the resulting order is total.
/// `eq` and `ne` earn their place: `eq: 1.0` is a saturated detector and `ne: 0.0` is *was it a
/// candidate at all*, both exactly representable and both genuinely asked.
///
/// `in` and `notIn` are ABSENT FROM THE KIND rather than declined here — a membership list over a
/// continuous measurement resolves each member at a width the client cannot see, so it answers *no
/// rows* to a question the caller believed they had asked. See [`ConfidenceFilter`], where the
/// framework argues it.
///
/// # The wire face is DECLARED, not written
///
/// `#[ingraph(composed)]`, and the identity component carries `#[ingraph(flatten)]`. Declaration
/// order IS publication order, so the confidence is published last, after the seven the splice
/// brings.