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
//! THE HIT: one retrieved result as a client reads it — the score it matched at, where the engine
//! put it, and the thing itself.
//!
//! ```text
//! <someSearch>(…) { <someHydratedSearch>(…) {
//! score score # the ENGINE's own currency, comparable INSIDE one list
//! rank rank # where the engine put it, holes left in
//! node { … } node { … }
//! } }
//! ```
//!
//! # THE ROW WORD IS `node` AT BOTH TIERS, AND WHAT THE NODE *IS* IS THE TIER'S ANSWER
//!
//! Ruled 2026-08-18, closing the family alignment: one word across the whole Match family — tier A's
//! node is the ADDRESS and tier B's is the ENTITY — which is the design this module's Rust half has
//! carried since it was written, [`Match`]'s third field having always been called `node`. It
//! replaces the 2026-08-15 split (`key` at tier A, `entity` at tier B), which had put two spellings
//! on one position and left the wire disagreeing with the type it renders.
//!
//! **`node` is not overloaded by this, and the two other homes it has are why.** The arrangement
//! grammar's `upstream(node = "…")` names a graph node in a DECLARATION, which is a Rust-facing
//! word a client never reads; and [`Connection`](super::Connection)'s edges carry Relay's own `node`,
//! where a page's element is exactly what this row is one shape over. A client that reads a page and
//! a client that reads a ranking now spell the thing itself the same way.
//!
//! # ONE TYPE AT BOTH TIERS, AND `N` IS THE WHOLE OF THE DIFFERENCE
//!
//! Ruled 2026-08-19, retiring the `EntityMatch` newtype the 2026-08-18 alignment had emptied: the
//! two tiers are [`Match<N, S>`](Match) at two INSTANTIATIONS, not two types. The claim the newtype
//! rested on — *an `#[Object]` impl publishes one row TYPE per method, so the entity tier needs a
//! face of its own* — is true about the METHOD and false about the type: `#[Object]` is written once
//! over a generic impl, and `node`'s return type is `&N`, so the row's type is whatever the tier
//! instantiated. `Match<KeyframeKey, f32>` publishes `node: KeyframeKey!` and
//! `Match<Keyframe, f32>` publishes `node: Keyframe!` off the SAME impl, which is the mechanism
//! [`Connection<N, V>`](super::Connection) has always named its own node through.
//!
//! The newtype was observationally identical to what it wrapped, and the [`TypeName`] impl it
//! carried is where that stopped being an opinion: it DELEGATED, `<Match<N, S>>::type_name()`, so
//! both tiers already computed one formula. What the deletion removes is a second constructor, a
//! second crossing, a second `#[Object]` and a third accessor spelling (`entity_ref` beside
//! `node_ref`) — four ways to write the same three fields, each free to drift from the others.
//!
//! Their SDL names still cannot collide, and that is a fact about the DECLARATION rather than about
//! the type: `N` is an address object at one tier and an entity object at the other, and a
//! declaration publishing one type at both positions would already be publishing an entity as its
//! own address.
//!
//! The FIELD is left unnamed above because its name is COMPUTED rather than fixed —
//! `<subject>By<Election>Keys`, off the declaration's own base and the elected field — so no single
//! word could stand at that position. The face itself IS EMITTED: `mediaByTitleKeys` and
//! `mediaByBodyKeys` are two of them, and `ingraph/tests/resource_wire_road.rs` answers a client's
//! own query through one over a real Tantivy corpus, end to end.
//!
//! The blocker this paragraph used to record — *an index declaration carries no engine, so nothing
//! in its expansion can spell the `E` its own retrieve is generic over* — was ANSWERED rather than
//! worked around, by the resource word. `#[ingraph(resource)]` on a graph root's field and
//! `engines(<word> = "path::To::Engine")` on the root itself name a concrete engine at the
//! DECLARATION, so the expansion spells it; and the resolver never has to be generic, because its
//! context lookup is a `TypeId` on the resource's own type — which is exactly the concrete thing it
//! wanted. `ingraph/tests/retrieve_wire.rs` still writes the crossing out BY HAND, which is the
//! Rust surface underneath the emitted face rather than a stand-in for it.
//!
//! # It is [`Ranked`]'s wire face, and it adds nothing to it
//!
//! The Rust item was closed before this module existed: score first because it is the more important
//! of the two numbers, rank second as the ENGINE's own ordinal, node third. This type is those three
//! fields at a wire position, in that order, and the one crossing between them is
//! [`From<Ranked>`](Match::from) — so a face that renders a retrieve cannot pick a number up from
//! anywhere but the answer it is rendering.
//!
//! A SEPARATE type rather than an `#[Object]` on `Ranked` itself, for the reason the whole crate
//! splits declaration from face: `Ranked` is the Rust answer and exists in a build with no GraphQL
//! binding at all, and an inherent `#[Object]` impl would put async-graphql's name in the middle of
//! it. The same split [`Connection`](super::Connection) draws between `query::Page` and what a page
//! becomes on the wire.
//!
//! # The SDL name is the NODE's, plus `Match`
//!
//! `TranscriptKeyMatch`, `SegmentMatch` — computed off `N`'s own published name through async-graphql's
//! [`TypeName`] hook, which is the identical mechanism `Connection<N, V>` already names
//! `<Node>Connection` and `<Node>Edge` through. GraphQL's flat type namespace has no generics, so a
//! generic wire type either names itself off its parameter or is written out once per instantiation;
//! the first is the library's own answer and the one this crate already spends.
//!
//! # THE TWO PARAMETERS ARRIVE DIFFERENTLY, AND THE ASYMMETRY IS THE CURRENCY'S
//!
//! `N` is `OutputType` — already wire-shaped — exactly as `Connection<N, V>` takes an `OutputType`
//! node: a tier's address or entity is a type the DECLARATION already published a face for, and
//! this module has nothing to add to it.
//!
//! `S` is [`WireScore`](super::WireScore), which is the crossing every declared column travels. It
//! was `OutputType` too, and that left the one row on a hit that IS a measurement reaching
//! async-graphql's own float rows — which publish `f32` and `f64` alike as `Float` — beside columns
//! whose widths the SCALAR SUITE had already made honest. So a score now says which width it is
//! measured in, and what stays exactly as it was is COMPARABILITY: the doctrine below is unchanged,
//! and a width is precision rather than permission.
use Cow;
use ;
use WireScore;
use crateRanked;
/// ONE HIT on the wire, at either tier: its score, its engine ordinal, and the NODE that matched —
/// the ADDRESS at tier A, the whole upstream ENTITY at tier B.
///
/// The wire projection of [`Ranked<N, S>`](Ranked), field for field and in the same order. See the
/// module note for why it is a type of its own and for where its SDL name comes from.
///
/// # `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 ranked 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-18 alignment they share the third row's NAME, and
/// since the 2026-08-19 retirement they share the TYPE that carries it: the tier is an
/// instantiation, not a second face. See the module note.
///
/// # The `__async_graphql_` PREFIX on the face below, and the collision that proves the pin
///
/// Every function of the `#[Object]` impl is `__async_graphql_`-prefixed with its wire name written
/// out beside it, which is the law an emitted face already wears — and this type is where the
/// reason stops being hypothetical. `#[Object]` methods ARE inherent methods, so the unprefixed
/// spelling puts a second `rank` on `Match` beside [`Match::rank`], inside an attribute expansion.
///
/// **MEASURED on 2026-08-19 rather than asserted**, by deleting the prefix and reading what rustc
/// said. Three errors, and the note that stood here had the count right and the shape wrong:
///
/// | | |
/// |---|---|
/// | `E0592` *duplicate definitions with name `rank`* | 1, on the inherent fn |
/// | `E0034` *multiple applicable items in scope* | 2 — at the `#[Object]` method's own declaration, and at the `self.rank()` inside it |
///
/// ONE row collides and not three: the borrows are `score_ref` and `node_ref`, so `score` and `node`
/// have nothing to be a second definition OF. The pin is real and it is `rank`'s alone — which is
/// enough, because the prefix is a rule about a NAMESPACE and a rule that held for two rows out of
/// three would be no rule at all. An accessor renamed `score` tomorrow would collide the same way
/// with no edit to this impl, and the prefix is why that stays a non-event.
///
/// The prefix names the BACKEND rather than merely being ugly, per the ruling of 2026-08-13: a
/// second GraphQL binding mounted on `Match` mints `__smear_score` beside `__async_graphql_score`,
/// so the two faces are the two namespaces and the collision this section is about cannot recur one
/// backend later. `ingraph-codegen`'s `method::wire_method` is where an emitted face reads the same
/// shape from.
///
/// # WHERE THE DOCS GO, because async-graphql publishes one of these two
///
/// This type's own note is a Rust reader's; the `#[Object]` impl's note is a CLIENT's, because
/// async-graphql reads the impl block's rustdoc and publishes it as the SDL type's description. So
/// everything a schema explorer should not have to read — this section included — is written here,
/// and the impl carries only what a client is owed.
/// The ONE crossing from the Rust answer to the wire one.
///
/// Written as a conversion rather than as three field reads at each face, for
/// [`Ranked::map_node`]'s own reason one layer down: the two numbers belong to the engine's answer
/// about this hit, and a face that assembled them by hand is a face that can assemble them from the
/// wrong hit.
/// `<Node>Match`, off the node's own published name.
///
/// `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. It is
/// [`WireScore`](super::WireScore) and no longer `OutputType`, which is the whole of the currency
/// correction: the score seat travels the crossing map like every declared column beside it.
/// One result of a search: what matched, how well, and where the engine put it.
///
/// The list this belongs to is ALREADY the ranking — its order is the engine's — so a client that
/// wants the best result takes the first element and needs no comparison of its own.
/// A whole ranked answer, crossed.
///
/// The shape a retrieve face's body ends in, written once here rather than as a `map` at each of
/// them — 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, which is three moves and asks nothing
/// of what it is moving. The answer is a `Vec` because the ranking IS the order — the sequence is
/// the whole of the answer's structure, and no page wraps it HERE: a paged road cuts its stretch
/// off the kept ranking BEFORE this crossing, so what reaches this function is one stretch's rows
/// and the claim on the next rides beside them rather than around them.