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
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
//! The vector family's two seams: [`VectorEngine`] (the per-slot handle) and
//! [`AsyncVectorStore`] / [`VectorStore`] (the construction layer that mints the handle, in BOTH
//! modes) — and [`VectorColumn`], the name one slot's several embeddings are told apart by, with
//! [`Elected`] carrying that name in a TYPE.
use Future;
use Utf8Bytes;
use ;
/// WHICH embedding of a slot a call is about — the ELECTION SELECTOR.
///
/// # A slot may hold SEVERAL vector columns, and that survived the slot's re-keying
///
/// A declaration may elect N embeddings, each queryable. The geometry that carries them used to be
/// ONE SLOT with N vector columns, on the law *one declaration, one slot*; the engine grammar re-keyed
/// the slot to `(field × engine)` ([`Slot`](crate::Slot)) and this parameter is what it did NOT
/// change. A slot still holds several columns — one election's own geometry can be more than one —
/// so the subject of a `knn` still has to be said. Engines are native to the shape: a Lance table
/// holds several vector columns and indexes each, so the seam states a fact the backend already has
/// rather than asking it for a new capability.
///
/// # A NEWTYPE over `&'static str`, and both halves of that are the point
///
/// A STRING because a column is a name at the storage boundary: what an engine does with it is build
/// a projection, open a per-column index, or key a map, and every one of those wants the name. A
/// NEWTYPE because a bare `&str` in that position is a magic string — `knn(ctx, "image_embedding", …)`
/// type-checks against a slot that has no such column and against a query text — where a named type
/// makes the parameter's subject readable at the call and unmistakable in a signature.
///
/// `&'static str` rather than an owned or shared string because of where the value COMES FROM: an
/// election is a `#[ingraph(knn)]` marker on a FIELD, so the column's name is that field's own ident
/// — a token of the declaration — and every column an emission addresses is minted `const` from it
/// and outlives everything. A backend needing an owned
/// form takes one off [`as_str`](Self::as_str); nothing here allocates.
;
/// ONE ELECTION of `T`, as a TYPE — the [`VectorColumn`] above lifted out of the value world.
///
/// A declaration electing N embeddings mints N implementors of this, one per `embedding(<field>)`
/// word, each a zero-sized marker the emission names after the field it stands for. Nothing here is
/// hand-written: the same expansion that emits `retrieve_by_<field>` emits the marker beside it, so
/// the elections a type has are exactly the elections the declaration declared.
///
/// # Why the column becomes a type
///
/// It is [`SlotHandle`](crate::SlotHandle)'s medicine applied one grain finer. A slot was made a type
/// fact so that serving out of another declaration's storage is `E0308` rather than a wrong answer;
/// a COLUMN carried as a value has the same failure available to it one level down — a lane
/// constructed with the image column and wired into the door that answers text questions is a
/// program that compiles and answers from the wrong embedding, with no error anywhere. Carried as a
/// type, that wiring is `E0308` NAMING BOTH ELECTIONS, at the line where the two were joined.
///
/// The dividend is a HUMAN's, and deliberately so: the wiring this refuses is wiring somebody writes
/// by hand today and the launch walk writes tomorrow, and both sit under the same compiler.
///
/// # What it does NOT do
///
/// It adds nothing to the ASK. [`VectorAsk`](crate::VectorAsk) still carries a scope and coordinates
/// and no column — a caller cannot spell one, before this or after it. What changed is where the
/// column is written down: at the type of the lane, once, instead of at every call.
/// A vector index (Lance, pgvector, a `vec0` virtual table) — **R-FREE**, exactly as
/// [`FulltextEngine`](crate::FulltextEngine) is, and for the same three reasons: an orphan wall an
/// engine-specific key trait could not avoid, a method-level `where` an expansion could not satisfy,
/// and an inference burden every call carried.
///
/// # It is the BASE, and a base has no verbs
///
/// What lives here is the VOCABULARY an engine speaks — the address it answers in, the currency it
/// scores in, the element it materializes — together with the ADDRESS LIFECYCLE that turns a key
/// into one of its addresses and back. The verbs are on the four faces
/// ([`VectorRead`](crate::VectorRead) / [`AsyncVectorRead`](crate::AsyncVectorRead),
/// [`VectorWrite`](crate::VectorWrite) / [`AsyncVectorWrite`](crate::AsyncVectorWrite)), each naming
/// this trait as a supertrait and each holding the LEASE its own direction spends.
///
/// So a bound asks for exactly the half it uses. A query type that only spells an
/// [`Address`](Self::Address) and a [`Score`](Self::Score) binds THIS and inherits no search; a
/// retrieve binds a read face; a drainer binds a write one; and an engine that only reads — a
/// snapshot, a replica, a served index — is spellable, which it was not while one trait carried
/// every verb.
///
/// **THERE IS NO GAT LEFT HERE.** Both leases moved onto the faces that spend them, so nothing a
/// query type or a walk binds carries borrowing machinery, and the read/write scopes are free to be
/// two different types on the two modes — an async transaction ticket is not a blocking searcher's.
///
/// # THE ADDRESS LIFECYCLE — three functions, and the phase each one ends
///
/// An address is a KEY'S IDENTITY in this engine's own vocabulary, and it is built and read in
/// phases that cannot be confused for one another:
///
/// ```text
/// buffer() ─► WriteBuffer ─(the key reports its columns)─► finalize(buf) ─► Address
/// Address ─► open(address) ─► ReadBuffer ─(the key takes its columns)─► ColumnReader::finish
/// ```
///
/// [`WriteBuffer`](Self::WriteBuffer) is a [`ColumnWriter`] and [`ReadBuffer`](Self::ReadBuffer) is
/// a [`ColumnReader`], so what crosses between a key and an engine is TYPED COLUMNS — never an
/// intermediate encoding both sides then decode. That is what makes a key's row
/// ([`Field`](crate::Field)) engine-blind and costs a new engine no row at all.
///
/// All three are ASSOCIATED FUNCTIONS rather than methods: minting a buffer, sealing it and opening
/// an address ask nothing of a handle, so `E::buffer()` is spellable wherever `E` is — which is what
/// [`vector_addressed`](crate::retrieve::vector_addressed) and
/// [`vector_keyed`](crate::retrieve::vector_keyed), the framework's two walks, need of them.
///
/// # THE SAME-BYTES LAW
///
/// The column sequence a key reports into a [`WriteBuffer`](Self::WriteBuffer) is the sequence it
/// takes back off the [`ReadBuffer`](Self::ReadBuffer) [`open`](Self::open) mints from the finished
/// address. An address built by the write walk and an address a hit arrives under are THE SAME BYTES
/// for the same key, which is the whole correspondence the by-key read stands on.
///
/// # `SearchOptions` and the LEASE are two different seats, and only one of them is here
///
/// [`SearchOptions`](Self::SearchOptions) is the BACKEND's own per-query knobs and stays on the base
/// because a wire face carries it: an emitted engine variant's `options` row is typed on it, so the
/// type must be nameable from a bound that spends no verb. The LEASE is the half a request cannot
/// carry — a snapshot, a transaction handle, a searcher's ticket — and it went with the verbs, onto
/// [`VectorRead::ReadContext`](crate::VectorRead::ReadContext) and its three siblings.
/// Construction for a vector store — per-slot tables opened and cached behind ONE
/// connection-manager.
///
/// A `*Store` IS the [`Connection`](VectorEngine::Connection) its handles borrow: opened once by
/// [`open`](Self::open), its per-slot factory mints a STATELESS handle that reaches back through
/// `ctx.connection()`, so nothing reconnects per call. `open`'s future is `Send` (a multi-threaded
/// runtime); [`vector`](Self::vector) is SYNC and INFALLIBLE — a stateless handle needs no I/O to
/// mint, so any per-slot table open happens lazily behind the shared manager on first use.
/// `: Sized` because `open` returns `Self` by value.
///
/// [`VectorStore`] is the BLOCKING twin, and the pair is [`AsyncBlobStore`](crate::AsyncBlobStore) /
/// [`BlobStore`](crate::BlobStore)'s verbatim one family over: [`vector`](Self::vector) is already
/// synchronous on both faces, so [`open`](Self::open) is the whole of what a mode can change here.
/// Construction for a vector store whose OPENING is a blocking act — [`AsyncVectorStore`]'s twin, and
/// the narrowest shape a store pair takes: it differs in exactly one verb.
///
/// [`vector`](Self::vector) is already synchronous on the async face — a stateless handle needs no
/// I/O to mint — so [`open`](Self::open) is the whole of what a mode can change. Opening an embedded
/// index directory is a syscall that returns; this seam is where such a store stops wrapping that
/// fact in an `async fn`, exactly as [`BlobStore`](crate::BlobStore) is one family over.
///
/// # The two faces are SIBLINGS
///
/// Neither is a supertrait of the other, per [`BlobEngine`](crate::BlobEngine)'s ratified argument: a
/// supertrait either way taxes one kind of store with a face nobody asked it for. What a store CAN
/// answer is what it implements, and a caller's bound is what says which face it needs. A store
/// answering both writes both, and the shipped filesystem blob store is the reference discipline —
/// the blocking face holds the body and the async one delegates to it.
/// The unused vector face.
///
/// FULLY UNBOUNDED, which it was not before — see [`FulltextEngine for ()`](crate::FulltextEngine)
/// for the deletion and its reason. `Element = ()` is a face that materializes nothing, which is
/// what a store that never searches has.
///
/// The whole address lifecycle is the UNIT, in all three phases: the column language's own unused
/// pair ([`ColumnWriter for ()`](ColumnWriter), [`ColumnReader for ()`](ColumnReader)) accepts every
/// column and drops it, and refuses every read for the honest reason that nothing was ever landed.
/// So `Error = NoColumns` rather than [`Infallible`](core::convert::Infallible): the read phase is
/// tied to this member, and a key asking a face that holds nothing for a column has to be answered.
/// The face still cannot fail at a VERB — see the four face impls, every one of which answers.