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
//! [`Folded`] — what a SET retrieve hands back: the folded score, what each query vector's own
//! stream said about the entity, and the thing itself — and [`StreamBest`], one of those slots.
/// ONE QUERY VECTOR'S SIGHTING of an entity: the best score that vector found in the entity's set,
/// and where that vector's own stream put it.
///
/// # It exists because the fold stopped stripping what it computes
///
/// [`set_scored`](super::set_scored) accumulates a score AND an ordinal per query vector, hands the
/// scores to a [`FoldSemantics`](super::FoldSemantics), and used to keep only the ordinals: the
/// answer carried `ranks[j]` and the number the fold actually read — `bests[j]` — was dropped at the
/// push site. That is the same loss [`Sighting`](super::Sighting) was minted to end one family over,
/// and the argument transfers without change: a client reading a set answer has no engine, no floor
/// and no second query to recompute `bⱼ` from, and the ordering alone cannot say whether a stream
/// led by a nose or by a mile.
///
/// The recomputation road is worse here than it was there. A caller CAN re-ask query vector `j` and
/// read the score back, but that is a second engine call against a corpus that may have moved, so
/// the number it returns is a number that can disagree with the one the fold used. What is carried
/// from the fold cannot disagree with the fold, because it IS the fold's.
///
/// # The ordinal is `ordinal` and not `rank`, and the word is the SET family's
///
/// [`Ranked::rank`](super::Ranked::rank) is *where the engine put it* on a road that has ONE stream,
/// so the bare word is unambiguous there. A set retrieve has `m` of them, and a bare `rank` on this
/// slot would read as a position in the answer — which is the one number this whole family refuses
/// to mint, the fold authoring the answer's order. [`Sighting::ordinal`](super::Sighting::ordinal)
/// already spells it this way for the same reason, so the two provenance slots of the two folds say
/// the same word.
///
/// # `Copy` follows `S`, and the accessors are [`Folded`]'s own pair
///
/// The borrow always, the copy behind a `Copy` gate on the METHOD rather than on the parameter — so
/// a composite score is stored, borrowed and decomposed exactly as an `f32` is.
/// One set-similarity result: the score a [`FoldSemantics`](super::FoldSemantics) produced, what
/// each query vector's own stream said about the entity, and the key.
///
/// # It is [`Ranked`](super::Ranked)'s twin, and the plural is the whole difference
///
/// A single-vector retrieve has ONE engine stream, so one score and one rank. A set retrieve runs
/// the engine once per query vector, so it has `m` of each and no order between them — which is why
/// the ruled shape for this answer was a plain score with no number at all, and why this type amends
/// that: the numbers exist, one pair per stream, and they are only unspellable if you insist on ONE.
///
/// # ATTRIBUTION is what makes the numbers lawful
///
/// `streams[j]` is what query vector `j`'s own engine stream said about this entity — see
/// [`StreamBest`] for the pair. The ordinal is **1-based over that stream's raw hits**, the same
/// number [`Ranked::rank`](super::Ranked::rank) carries. Nothing here mints a global ordinal over
/// the `m` streams, because there is nothing to mint one from: the fold authors the answer's ORDER,
/// and an ordinal invented over that order would be a number no engine could be continued from.
/// Every number in this list is one stream's own truth, and it is attributed to the stream that
/// produced it.
///
/// That keeps the rank law intact rather than bending it. What a caller gets is `m` per-stream
/// resume tokens instead of one: re-ask query vector `j` with a wider budget and drop everything at
/// or below `streams[j]`'s ordinal, exactly as the single-vector road's continuation works. The
/// ruled resumption story is therefore reachable from here without a cursor slot and without a
/// second meaning for the word *rank*.
///
/// # `None` is *below that stream's floor*
///
/// `streams[j]` is [`None`] exactly where query vector `j` matched nothing of this entity's — the
/// same slot that is [`None`] in the row a fold receives. The correspondence used to be an invariant
/// between two parallel lists and is now a fact of ONE: the accumulator holds the score and the
/// ordinal in the same slot, and there is no longer a second list for it to disagree with.
///
/// # The SCORES the fold read are HERE, and that is what changed
///
/// A [`FoldSemantics`](super::FoldSemantics) implementor is handed exactly `bests[j]`, and this type
/// used to drop them on the way out. Carrying them was recorded as a widening rather than built,
/// on the argument that nothing asked for the pre-fold numbers; the WIRE asked. A client reading a
/// set answer has neither the engine nor the floor to recompute one from, so the number is carried
/// out of the fold instead of being computable in principle. It costs nothing to carry: the score is
/// MOVED out of the slot the fold borrowed, after the fold has read it.
///
/// # `S` is the engine's own currency, folded
///
/// The score here has been through a fold, so it is in the currency's own units and not necessarily
/// in the range one pair of vectors reports: a sum of `m` cosines is not a cosine. That is the
/// reason the FLOOR is spent one stage earlier, at the element grain, where a person has actually
/// seen a number — and the reason [`StreamBest::score_ref`] is the number that compares against it.
///
/// # The accessors are [`Ranked`](super::Ranked)'s, plus the list
///
/// The borrow always, the copy behind a `Copy` gate on the METHOD rather than on the parameter — so
/// a `String` key or a composite score is stored, borrowed and decomposed exactly as an `f32` is.