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
//! THE SET HIT: one entity of a SET-similarity answer as a client reads it — the folded score, what
//! each query vector's own stream said, and the thing itself.
//!
//! ```text
//! <someSetSearch>(…) { <someHydratedSetSearch>(…) {
//! score score # the FOLD's answer, in the engine's own currency
//! streams { streams { # one nullable slot per query vector, in ASKED order
//! score score # that vector's own best — the PRE-FOLD number
//! ordinal ordinal # where that vector's own stream put the entity
//! } }
//! node { … } node { … }
//! } }
//! ```
//!
//! # It is [`Match`](super::Match)'s family, and the plural is the whole difference
//!
//! A single-vector answer has one score and one rank, so [`Match`](super::Match) carries `score` and
//! `rank` beside its address. A set answer has `m` engine streams and **no order between them**, so
//! there is no one rank to carry: the fold authors the answer's order, and no cross-stream ordinal
//! is ever minted. What replaces the row is the LIST — `streams`, positional over the query vectors
//! in the order they were asked, each slot carrying that stream's own two numbers.
//!
//! The rows follow the family's ruled words: since the 2026-08-18 alignment BOTH tiers spell the
//! third row `node` — tier A's node is the address and tier B's is the entity — and the SDL name is
//! the node's own plus `FoldedMatch`. [`Match`](super::Match)'s module note carries the ruling whole.
//!
//! # `From<Folded>` IS THE ONLY CROSSING, and that is the provenance lock
//!
//! [`Match::from`](super::Match::from) states it for the single-vector road and every word transfers:
//! a face that assembled these fields by hand is a face that can assemble them from the wrong
//! answer. The fold produced the score, the walk produced each slot, and this type is those values
//! at a wire position. There is no constructor beside the conversion, at either tier.
//!
//! # The score is the ENGINE's currency at BOTH grains, and it crosses at that currency's WIDTH
//!
//! [`FoldSemantics`](crate::FoldSemantics) is `S → S`: it takes the per-stream bests in the engine's
//! own currency and answers in that same currency. So the top-level `score` and each slot's `score`
//! are the same type, and both reach the wire through [`WireScore`](super::WireScore) — the crossing
//! every declared column already travels — so an `f32` cosine publishes `F32!` and an `f64` one
//! `F64!`. Coercing either to a framework `Float` would be this module having an opinion about an
//! arithmetic that belongs to the fold, and publishing the two widths under ONE name was that
//! opinion taken by omission.
//!
//! What the two grains do NOT share is comparability. A slot's score is a PRE-FOLD number about one
//! pair of vectors — the grain the query's floor is stated at, and the only grain a person has seen
//! a number in. The top-level score has been through a fold, so it is in the currency's units
//! without being in its range: a sum of `m` cosines is not a cosine. Both are comparable INSIDE
//! this one answer and nowhere else, which is the existing currency doctrine read at two grains.
//!
//! # WHICH fold ran is not published here, and the reason is the schema's clock
//!
//! The fold is a POLICY the deployment installs at launch (see [`FoldDoor`](super::FoldDoor)), and
//! SDL descriptions are built at compile time — so a row naming the installed fold would be a
//! string the schema cannot know. The name a [`FoldSemantics`](crate::FoldSemantics) carries is
//! spent where a runtime value can be read instead: the door's own span, its refusals, and the
//! emitted field's documentation of what a deployment may install.
use PhantomData;
use Cow;
use ;
use WireScore;
use crate;
/// ONE QUERY VECTOR'S SIGHTING on the wire: its own best score in the entity's set, and where its
/// own stream put the entity.
///
/// The wire projection of [`StreamBest<S>`], field for field and in the same order. `null` in the
/// `streams` list it sits in means that query vector matched nothing of this entity's above the
/// floor — the slot is there either way, so the POSITION stays the query vector's ordinal and a
/// client can read *question three went unanswered* rather than counting a shorter list.
///
/// # `N` carries no data and names the type, and the alternative was MEASURED
///
/// Nothing in this shape depends on the node: the two rows are the score and the ordinal, so the
/// obvious spelling is `StreamSighting<S>` naming itself off the currency. That spelling COLLIDES.
/// async-graphql publishes both `f32` and `f64` as `Float`, so two declarations scoring in the two
/// widths would mint two Rust types under one SDL name, in one registry, silently. Carrying the node
/// puts this type on the same naming axis as the [`FoldedMatch`] that owns it — `<Node>StreamSighting`
/// beside `<Node>FoldedMatch` — so a slot's name moves with its owner and two owners never share a name
/// they could disagree about.
///
/// The cost is stated rather than hidden: the keys tier and the hydrated tier publish two slot types
/// of identical shape, `KeyframeKeyStreamSighting` and `KeyframeStreamSighting`. That is the same
/// pair [`Match`](super::Match) publishes at its own two instantiations, and for the same reason —
/// the tier's node is what the two answers differ in.
///
/// # THE SILENT COLLISION CLASS IS EXTINCT AT BOTH ENDS NOW, AND THE NODE AXIS STILL STANDS
///
/// The paragraph above describes the collision as it WAS, and both halves of it are now gone. The
/// SCALAR SUITE ([`scalar`](super::scalar)) gave every Rust width its own SDL name, so `f32` and
/// `f64` are two schema types; and the currency reroute put THIS SEAT on the crossing that publishes
/// them — `S` is bound [`WireScore`](super::WireScore) rather than `OutputType`, so an `f32` score
/// renders `f32!` and an `f64` one `f64!` at every grain of this family. The note that stood here
/// recorded the second half as still open, and it is closed: `graphql::folded_matches`'s own tests read
/// `score: f32!` off a schema whose currency is an `f32`.
///
/// **The node is still carried, and its reason is no longer the collision.** What the parameter buys
/// now is that a slot's name moves with its OWNER — `<Node>StreamSighting` beside `<Node>FoldedMatch` —
/// so a client reading a set answer holds one naming axis rather than two, and a declaration that
/// renames its family renames the slot with it. Naming the slot off the currency instead would put
/// `F32StreamSighting` in a schema beside `KeyframeFoldedMatch`, which is a name a reader has to
/// assemble from two unrelated facts.
///
/// The rest of the posture is unchanged and belongs to the family rather than to this type: two
/// declarations whose slot types are IDENTICAL share one, and two whose currencies DIVERGE under
/// one name are a LOUD REFUSAL rather than a second silent registration. That refusal is
/// async-graphql's own and it is a panic at schema build — `Registry::create_type` refuses one
/// GraphQL name held by two Rust types with a `rust_typename`, which is the mechanism
/// [`EnumFilter`](crate::EnumFilter)'s note already names one module over.
///
/// `PhantomData<fn() -> N>` is this crate's own marker spelling: it holds nothing, is variance-safe,
/// and leaves every derive and every auto trait independent of `N`.
/// The ONE crossing, from the slot the fold filled — [`FoldedMatch`]'s own lock, one grain down.
/// `<Node>StreamSighting`, off the node's own published name — see the type's note for why the node
/// is here at all.
/// What ONE of the query vectors said about this result.
///
/// Its position in the `streams` list is the query vector's own ordinal, counted in the order the
/// vectors were asked.
/// ONE FOLDED hit on the wire, at either tier: the folded score, every query vector's own sighting,
/// and the NODE that matched — the ADDRESS at tier A, the whole upstream ENTITY at tier B.
///
/// The wire projection of [`Folded<N, S>`](Folded), field for field and in the same order. See the
/// module note for why it is a type of its own, for where its SDL name comes from, and for the two
/// grains its two scores live at.
///
/// # `N` is what a TIER decided, not what this type did
///
/// Tier A retrieves KEYS and tier B retrieves the WHOLE upstream entity, and both are folded lists
/// of the same shape — so `N` is the tier's answer and the two tiers share one wire vocabulary
/// rather than growing one each. Since the 2026-08-19 retirement they share this TYPE too: the tier
/// is an INSTANTIATION of it, `FoldedMatch<FrameKey, f32>` at one road and
/// `FoldedMatch<Frame, f32>` at the other, and [`Match`](super::Match)'s own module note carries the
/// whole of why one generic `#[Object]` publishes both.
///
/// # The `__async_graphql_` PREFIX on the face below
///
/// [`Match`](super::Match)'s own measurement, and its correction with it: `#[Object]` methods ARE
/// inherent methods, so an unprefixed method collides with an inherent one of the SAME NAME. At THIS
/// type no row collides today — the borrows are `score_ref`, `streams` and `node_ref`, and `streams`
/// is the one that WOULD, being spelled identically on both sides. The prefix is what keeps the two
/// namespaces apart before any of that is a question, and it names the BACKEND rather than merely
/// being ugly, so a second GraphQL binding mounted here is a second namespace.
/// The ONE crossing from the Rust answer to the wire one.
///
/// [`Match::from`](super::Match::from)'s reason, at the set grain: the folded score and every slot
/// belong to the fold's answer about this entity, and a face that assembled them by hand is a face
/// that can assemble them from the wrong one. The slots cross through
/// [`StreamSighting::from`](StreamSighting#impl-From<StreamBest<S>>-for-StreamSighting<N,+S>) so the
/// per-stream numbers have exactly one road too.
/// `<Node>FoldedMatch`, off the node's own published name — [`Match`](super::Match)'s rule, unchanged.
///
/// `N`'s bound is `OutputType` because that is what carries a published name; `S` is bounded here too
/// so the two halves of the face demand the same thing and a missing row is `E0277` at ONE place
/// rather than at whichever of them the compiler reached first.
/// One result of a SET search: what matched, how well the whole set answered, and what each of the
/// asked vectors said on its own.
///
/// The list this belongs to is ALREADY the ranking — its order is the fold's — so a client that
/// wants the best result takes the first element and needs no comparison of its own.
/// A whole folded answer, crossed.
///
/// [`matches`](super::matches)' reason at the set grain: a face has one line for the crossing and no
/// opportunity to write the loop differently from its neighbour. NO bound on either parameter — the
/// crossing is [`From`]'s.