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
//! The MULTI-VECTOR fold: [`FoldSemantics`], the contract a set query is asked under, and the three
//! citizens this framework ships as implementations of it.
//!
//! # THE SEMANTIC-KIND NAMING LAW
//!
//! A *semantics* is not one thing. It is a KIND of decision a query makes, and this module holds the
//! first of them — the FOLD, which is how `m` per-query numbers become one. The kind's word
//! conjugates the whole way down, and that is a law rather than a coincidence of this round:
//!
//! ```text
//! semantics(fold = "app::MyFold") the declaration's word — the KEY is the kind
//! FoldSemantics<S> the contract
//! …_with(…, fold: F) the parameter
//! Folded<K, S> the result
//! ```
//!
//! So a second kind arrives spelled the same way and collides with nothing: `semantics(xyz = "…")`
//! reaches `XyzSemantics`, rides as `xyz: F`, and answers in `Xyzed`. The kind is the key of a
//! framework-closed vocabulary and the implementation behind it is open, which is the crossing this
//! whole family is built on.
//!
//! # The vocabulary IS the trait, and the shipped members are CITIZENS
//!
//! There is no `enum Semantics`. The fold a query is asked under is a TYPE implementing
//! [`FoldSemantics`], and [`Sum`], [`Max`] and [`Weighted`] are three of them that happen to ship
//! here. A fourth — framework or downstream — is one ZST and one impl, purely additive: no match
//! site widens, no enum gains an arm, and nothing that compiled before stops compiling. What a
//! closed vocabulary would have bought is a wire enum, and that is emitted PER ELECTION at the face
//! that needs it rather than fixed here.
//!
//! # Every empty type here is SEALED, and that is this crate's law for one
//!
//! `pub struct Sum(());` rather than `pub struct Sum;`. A bare unit struct is constructible by
//! anybody who can name it, so the day a citizen grows a field is the day every downstream literal
//! stops compiling. The private `()` funnels construction through [`Sum::new`] from the first
//! version, and the type can grow without breaking a caller.
use ;
use FoldedQuery;
/// HOW the per-query bests fold into one set score — the query-time contract of the multi-vector
/// round.
///
/// # The primitive it folds over
///
/// A set query is `m` query vectors against an entity holding `n` of its own. The primitive both
/// physical forms produce is the same list of `m` numbers: **per query vector, its best match in the
/// entity's set** — `bⱼ = maxᵢ sim(qⱼ, vᵢ)`. An engine with native multi-vector scoring produces it
/// as a singleton MaxSim; every other engine produces it as an element knn followed by an owner-max,
/// which is the framework's own [`Seen`](super::Seen) stage read one grain up. This trait is what
/// turns those `m` numbers into ONE.
///
/// # THE DELEGATION LAW IS INHERITED BY CONSTRUCTION
///
/// The input is that primitive and nothing else. There is no `m·n` matrix in this signature, and
/// there cannot be one: a native set-scoring engine answers with the per-query best and never
/// exposes the pairs behind it. So all-pairs averaging — `ΣᵢΣⱼ sim(qⱼ, vᵢ) / (m·n)` — is not
/// refused here by a sentence; it is UNREPRESENTABLE, because the numbers it needs are not in the
/// argument. Every implementation anybody writes is therefore realizable on both delegation paths,
/// including the ones this framework has never seen.
///
/// # The SLOTS carry absence, and that is the whole of what a fold has to decide
///
/// `bests[j]` is query vector `j`'s own best, and [`None`] means that vector matched nothing of
/// this entity's ABOVE ITS FLOOR. The slot is there either way, so a fold that wants to know which
/// question went unanswered can see it, and a fold that does not can ignore it — the two readings
/// that split `Mean` in half are both writable, by the party that knows which one it means.
///
/// The slice is `m` long, `m ≥ 1`. Both facts are guaranteed upstream: a
/// [`FoldedQuery`](super::FoldedQuery) refuses the empty set at its constructor, and the walk that fills
/// these slots visits every query vector. They are stated here rather than re-checked, which is what
/// makes a refusal that was paid for once worth having.
///
/// # `Send + Sync`
///
/// The emitted door is `async` and holds the fold across the engine calls, so a fold that could not
/// cross a task boundary would make that future `!Send` and be unusable from every runtime that
/// spawns. It costs the ZST citizens nothing and costs a stateful one exactly what it would have
/// cost at the call site.
/// A BORROWED fold folds — what lets a door taking its fold BY VALUE be handed one that lives
/// somewhere else.
///
/// The emitted set-similarity resolver is the caller this exists for: the fold it runs under is
/// either the one a deployment installed (behind an `Arc` inside a
/// [`FoldDoor`](crate::FoldDoor), so borrowed) or the one the declaration elected (a local, so
/// borrowable), and the door's parameter is `F: FoldSemantics<S>` taken by value. Without this impl
/// the resolver would have to monomorphize the whole door call once per arm of that choice, which
/// is the same body written twice for a decision made once per request.
///
/// `?Sized` so `&dyn FoldSemantics<S>` is one of them: the installed fold is erased, the elected one
/// is not, and both reach the door through this one line. Nothing is added to the fold — `score`
/// and `name` forward, and a borrow cannot disagree with what it borrows.
/// `Σⱼ bⱼ` — standard MaxSim / late-interaction, and the citizen a door falls back to.
///
/// The default because it is what the late-interaction family means by a set score: every query
/// vector contributes its own best, so an entity matching many of them outranks one matching a
/// single vector perfectly.
///
/// # NO ZERO, and no identity anywhere
///
/// The fold starts from the FIRST PRESENT element and adds the rest pairwise. It does not start
/// from a zero, because a currency's zero is a value only that currency can name — a distance-shaped
/// score (lower is closer) has no honest one, and a similarity in `[0, 1]` has one that means
/// *matched nothing*, which is the opposite of an identity.
///
/// [`iter::Sum`](core::iter::Sum) was measured and rejected for exactly this: its empty case
/// MANUFACTURES a value, so a bug that emptied the slots would answer with a zero-scored entity
/// instead of failing. What this does instead is start from a real number, which is available
/// because an entity that matched nothing never entered the accumulator at all.
);
/// `maxⱼ bⱼ` — the best single (query vector, set member) pair.
///
/// For the question *did ANY of my vectors find this entity convincing*, where the sum's reward for
/// answering many questions adequately is not what the caller means.
///
/// # The comparison is written out, and the posture is the walk's own
///
/// A running maximum over [`PartialOrd`] keeps what it holds unless the newcomer is strictly
/// greater, so a tie and an incomparable pair are treated alike: a value that cannot be SHOWN to
/// beat what is held does not replace it. That is the same reading
/// [`ranked_keys`](super::ranked_keys) takes of a score it cannot place, and it is why this citizen
/// asks for no ordering the currency does not already have — floats are not [`Ord`], and demanding
/// that they were would lock out every score shape this framework exists to carry.
///
/// [`Clone`] is the SIGNATURE's price rather than the comparison's: the slots are borrowed and the
/// answer is owned.
);
/// `Σⱼ wⱼ·bⱼ` — the sum with a weight per QUERY VECTOR, for a caller whose questions are not equally
/// important.
///
/// # Why a weight is a FOLD-layer fact
///
/// A non-negative weight does not move a per-query argmax: `w·maxᵢ sim(qⱼ, vᵢ) = maxᵢ w·sim(qⱼ, vᵢ)`.
/// So weighting AFTER the per-query max is the same answer as weighting inside it, which is what
/// makes this citizen correct on both delegation paths — a native set-scoring engine that never
/// exposed its pairs has already produced exactly the numbers this scales.
///
/// Pushing the weights down into an engine that has a native weighted-multi-vector option is an
/// OPTIMIZATION on the same answer, and it belongs to that engine's own options rather than here.
///
/// # The ARITY is checked at CONSTRUCTION, which is the only place it can be
///
/// [`for_query`](Self::for_query) takes the query the weights are for and refuses a list that is not
/// its length. So a mismatched pair is not a value of this type, and [`score`](FoldSemantics::score)
/// has nothing left to re-check — the same shape [`FoldedQuery::new`](super::FoldedQuery::new) uses for
/// the empty question, and for the same reason.
///
/// # An ABSENT answer contributes nothing
///
/// A [`None`] slot adds no term. Not a zero-valued one — that would be a number the currency never
/// produced — and not a shorter question either: the weight for an unanswered vector is simply not
/// spent, so an entity that answered the heavy question wins over one that answered the light one.
;
/// WHAT AN EMITTED WIRE VOCABULARY HANDS ITS FOLD TO — the crossing from a closed set of words back
/// to the open set of types.
///
/// # The problem it exists for
///
/// The vocabulary above is a TRAIT, so a fold is a TYPE. A wire enum is a closed set of WORDS, and
/// the emission mints one per election — variants for the citizens this crate ships and one more for
/// every fold the declaration named. Crossing back is then a `match` whose arms produce DIFFERENT
/// TYPES, which no function returning one type can do and which no `Box<dyn …>` can do without
/// paying a virtual call per entity for a decision made once per query.
///
/// A continuation answers it exactly. The emitted `with_fold` matches, constructs that arm's fold,
/// and hands it here; [`visit`](Self::visit) is generic over the fold, so every arm monomorphizes
/// into its own body and the door below it is the same statically-dispatched door it would have been
/// if the caller had spelled the type. The word never becomes a value that outlives the match.
///
/// # `S` on the trait and `F` on the method, and that is the whole shape
///
/// The currency is the VISITOR's — a caller writes one of these knowing which engine's scores it
/// will fold — and the fold is the WORD's, which the visitor by construction does not know. So `S`
/// is where the implementor states it and `F` is where the emission supplies it, and a visitor
/// written against a currency works for every election scored in it, including the folds it has
/// never heard of.
/// The value a fold STARTS from, or the panic that names WHICH FOLD had nothing to start from and
/// why there was none.
///
/// One sentence for all three citizens, so the invariant is written once and reads the same wherever
/// it fires — and one place to change if a fold that can answer about nothing ever ships.
///
/// The fold's own [`name`](FoldSemantics::name) rides the message, which is the second of the three
/// places that row is spent: a deployment reading this abort in a log knows whether the fold that
/// hit it was the shipped `sum` or the one it installed, and that is exactly the fork it would
/// otherwise have to reproduce to find out. The name is taken as an argument rather than read off a
/// `&dyn` here because the caller is the implementation itself, which knows its own name statically.
///
/// # Panics
///
/// Where the slots hold no answer at all, which this crate's own road cannot produce.