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
//! The MULTI-VECTOR road: [`FoldedQuery`] — what a set-similarity retrieve is asked with — and the
//! two framework functions both physical forms of a stored embedding SET share, [`owner_best`] and
//! [`set_scored`].
//!
//! # WHERE `set` LIVES AND WHERE `Folded` DOES, ruled 2026-08-19
//!
//! Two words on one road, split by GRAIN rather than by taste.
//!
//! **`set` is the DECLARATION's word.** `list(embedding)` elects a set, `streams = N` guards how
//! many query vectors one request may ask a `_with` road with, and what an author reads off either
//! is *this column holds a SET of coordinates*. Nothing there has been folded yet.
//!
//! **`Folded` is the ANSWER's word.** A fold is what turns `m` unordered streams into one order, so
//! every type a client reads is named after the operation that authored it: [`Folded`], the wire
//! `FoldedMatch` it crosses into, and the [`FoldSemantics`](super::FoldSemantics) that decided the
//! number.
//!
//! [`FoldedQuery`] sits on the ANSWER's side, because a query is named for the answer it asks for:
//! two callers holding `m` vectors are told apart by whether a fold runs, and by nothing else. What
//! stays `set` in THIS module is the SHARED CORE both physical forms of a stored set spend —
//! [`set_scored`] walks a stored set, and no fold has happened when it does.
use ;
use ;
use crate::;
/// A SET-SIMILARITY retrieve: the `m` query embeddings, and the minimum score a neighbour must
/// reach.
///
/// [`VectorQuery`](super::VectorQuery)'s multi-vector twin, and every clause of that type holds here
/// unchanged: the width and the space are checked where an [`Embedding`] is BUILT, the floor is
/// MANDATORY and rides the constructor's positional parameter, and the score's currency is the
/// ENGINE's rather than the framework's.
///
/// # The floor is in the ELEMENT's currency, and it cuts before the fold
///
/// It is the same number [`VectorQuery`](super::VectorQuery) carries — the engine's own score for
/// one query vector against one stored vector — and it is spent at the same stage, terminating each
/// per-query walk. It is NOT a floor on the folded set score, which would be a number in a third
/// currency (a [`Sum`](super::Sum) of `m` cosines is not a cosine) that no engine reports and no
/// author could calibrate. So *what counts as a match* stays a fact about one pair of vectors, which
/// is the only grain at which a person has ever seen a score.
///
/// # The EMPTY query set is refused, and the refusal is the constructor
///
/// A set query with no query vectors asks nothing: there is no `bⱼ` to fold, so every fold is an
/// empty product and every entity ties. [`new`](Self::new) hands back [`None`] for it — the same
/// shape [`Embedding::new`] uses for a slice that is not this type's width, and for the same reason:
/// an empty list is not a value of this type. The dividend is one parameter further on:
/// [`asked`](Self::asked) is a [`NonZeroUsize`], so the `m ≥ 1` a
/// [`FoldSemantics`](super::FoldSemantics) is promised is a fact of this type rather than a comment
/// on it.
///
/// # The FLOORLESS form is the same type at a different floor TYPE
///
/// [`of`](Self::of) defers the number and answers `FoldedQuery<E, Deferred, N, Space>`, which no
/// engine-facing door takes — see [`Deferred`](super::Deferred) for why the deferral is structural
/// rather than an `Option` inside the query.
///
/// # `m = 1` is the DEGENERATE form and not a different one
///
/// [`single`](Self::single) builds it and cannot fail. Every fold agrees on a single slot — there is
/// one number and it is the answer — so an `ask` chain that produced one embedding reaches this road
/// unchanged and a caller holding one vector never learns the knob exists.
/// The three are written rather than derived, for [`VectorQuery`](super::VectorQuery)'s own reason:
/// a derive bounds every parameter it sees, and `Space` is a marker holding nothing that a sealed
/// `pub struct Clip(());` derives nothing for.
/// ONE query vector's `bⱼ`: the engine's hits for it, collapsed to **the best score per OWNER**.
///
/// # It is the dedup stage, read one grain up
///
/// The multi-row physical form stores an entity's set as one row per member — owner key, ordinal,
/// element vector — so the engine's raw stream is at the ELEMENT grain and several of its hits can
/// name one entity. The primitive the fold needs is that entity's BEST, which is precisely *first
/// occurrence wins on a score-descending stream*: the pipeline's own dedup, asked about an owner
/// instead of about a key that was already one. So this delegates to
/// [`ranked_keys`](super::ranked_keys) rather than reimplementing the walk, and inherits every
/// property stated there — the floor TERMINATES rather than filters, an incomparable score ends the
/// walk, and the mechanism is the declaration's own.
///
/// The `hits` this takes are therefore already read back into the OWNER's key type: the address the
/// engine hands back carries owner and ordinal, and the row family ([`Field`](crate::Field)) is
/// where a key decides that the ordinal is not part of it.
///
/// # The RANK is KEPT here, and ATTRIBUTED where it lands
///
/// [`ranked_keys`] mints an ordinal over the engine's raw stream, and a set query has `m` such
/// streams. The number is this stream's own truth and stays that: it rides through the fold into the
/// slot belonging to the query vector that produced it, which is what
/// [`Folded::streams`](super::Folded::streams) hands back — beside the score it was measured with.
/// Nothing anywhere mints an ordinal ACROSS the streams — the fold authors the answer's order, and a
/// number invented over that order would be one no engine could be continued from.
///
/// # It is UNBOUNDED, and that is the fold's requirement rather than an oversight
///
/// Every above-floor owner is returned. `k` counts ENTITIES and is applied by [`set_scored`] AFTER
/// the fold, because an entity that places 200th for one query vector and first for the other four
/// is exactly the entity a late-interaction score exists to find — truncating per query vector would
/// cut it before its score existed.
/// [`owner_best`] with ONE OWNER ALREADY SEEN — the collapse a fuse-BY-EXAMPLE runs, where the
/// example must not answer its own question.
///
/// # It is the SET grain's spelling of an exclusion the single-vector doors already had
///
/// [`ranked_keys_excluding`](super::ranked_keys_excluding) is what a
/// `retrieve_similar_by_<field>` walks, and a set-similarity door asks the same question with `m`
/// vectors instead of one — so each of the `m` streams needs the same seed, and the exclusion has
/// to happen HERE rather than after the fold. Filtering the fused answer instead would let the
/// example contribute to its own neighbours' sightings, which is a different ranking wearing the
/// same name.
///
/// UNBOUNDED like the sibling it wraps, and for the same reason: `k` counts entities and is spent
/// by [`set_scored`] after the fold.
/// ONE ENTITY's per-query sightings, as the fold accumulates them — the accumulator's VALUE, and a
/// type a caller of [`set_scored`] names and never builds.
///
/// # Why the accumulated value is not just the score
///
/// A [`FoldSemantics`](super::FoldSemantics) is handed `m` SLOTS, and the answer carries the same
/// `m` sightings. So what one entity accumulates is a sighting per query vector that saw it — which
/// query, at what score, at what ordinal in that query's own stream — and the row is widened to the
/// two `m`-long lists only at the end, where the number of queries asked is finally known.
///
/// SPARSE, one entry per vector that actually saw the entity: an entity matched by one of fifty
/// query vectors carries one sighting rather than fifty slots, and the widening to `m` happens once.
///
/// # Opaque
///
/// It is public because the accumulator's instantiation names it — `HashBests<Key, Sightings<Score>>`
/// is what an emitted set door writes — and it carries no constructor, because the only party that
/// fills one is the fold below.
>);
/// THE FOLD: `m` lists of per-query bests in, one [`Folded`](super::Folded) per ENTITY out, ranked
/// and cut to `limit`.
///
/// The half of the multi-vector road that is identical over both physical forms. A native
/// multi-vector engine hands its per-query singleton MaxSim straight in; an engine on the universal
/// multi-row form hands in what [`owner_best`] collapsed. Neither is named here, which is the
/// delegation law made mechanical: the framework folds a primitive and never learns which side of
/// the delegation produced it.
///
/// # The SEMANTICS is a type, and the arithmetic is entirely its own
///
/// This function walks, slots and sorts. What the `m` numbers MEAN together is
/// [`FoldSemantics::score`](super::FoldSemantics::score)'s, called once per entity with that
/// entity's slots — so a fold nobody here has heard of is reached by the same walk, and no arm in
/// this body knows which one it called.
///
/// # `limit` counts ENTITIES, and it is spent LAST
///
/// After the fold and after the sort. A set score is not known until every query vector has been
/// walked, so a budget spent earlier would be a budget spent on a number that did not exist yet.
///
/// # The order the answer comes back in
///
/// Set score DESCENDING. Two entities whose scores cannot be compared — which takes a currency that
/// produced a `NaN` in the fold — are left in the accumulator's own order rather than being placed
/// against each other on evidence that does not exist; the sort is stable, so that order is the
/// mechanism's and is at least the same twice.
///
/// # `m` is COUNTED here rather than passed
///
/// The slots are `m` long, and `m` is the number of lists this function walks. Taking it as a
/// parameter would let a caller state a different one, and there is no case where a caller knows
/// better than the walk.