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
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
//! THE COLUMN LANGUAGE — the vocabulary a key reports itself in, and the one an engine lands.
//!
//! A key is a sequence of columns. [`ColumnWriter`] is how it says so on the way in and
//! [`ColumnReader`] is how it takes itself back on the way out, and the pair exists so that neither
//! direction needs an intermediate representation: a row hands the engine one typed column at a
//! time and the engine lands each in whatever its storage natively has — a tantivy term, an arrow
//! `Int32`, a bound parameter — so nothing is encoded to a shared form and re-encoded to the
//! engine's.
//!
//! Both halves are ENGINE-BLIND from the row's side, which is what the language buys: a row that
//! speaks columns is written once and every engine reads it, where a row that speaks one engine's
//! address type is written once PER ENGINE.
//!
//! # The vocabulary is CLOSED, and it is the census that closed it
//!
//! The kinds here are the ones the shipped rows spend — the id vocabulary of
//! [`Id`](crate::Id) as `store::tantivy`'s `mod vocabulary` lands it, which is the only complete
//! set of key columns this crate has. Every method below names at least one of those rows, and the
//! two kinds a general codec would reflexively carry — a float and a bool — are ABSENT because no
//! key column is one: floats are refused admission to the id vocabulary outright and no member is a
//! bool. This is the framework's own codec alphabet rather than a surface a user extends, so
//! closing it costs a declarer nothing: what stays open is the set of TYPES, since any type at all
//! may land through [`bytes`](ColumnWriter::bytes).
//!
//! # Required kinds, defaulted kinds, and how the set GROWS
//!
//! The required methods are the ones an engine must face itself, and the rest arrive with a
//! fallback onto bytes that an engine OVERRIDES the day it has a native column for that kind. So a
//! new kind is added as a defaulted method and every existing engine goes on compiling — the
//! vocabulary grows additively, which is the whole reason the fallback exists rather than a
//! concession to a lazy backend.
//!
//! An engine that overrides one side of a kind must override the other. The write and the read are
//! one agreement and nothing in a signature can hold two halves together; what holds them is the
//! round-trip walk a conformance suite runs, and that is where a half-overridden kind is caught.
//!
//! # None of the three traits is object-safe, and none of them wants to be
//!
//! [`ColumnReader::fixed`] is const-generic and [`ColumnReader::finish`] takes `self` by value, so
//! the reader is spelled `impl ColumnReader` or as a type parameter and never behind a `dyn`, and
//! [`ColumnError::custom`] is generic over what it is handed, which costs the error type the same
//! thing. The writer follows them for symmetry of use rather than by force. A key's columns are
//! known at compile time, so the seam that spends these is generic anyway and the dispatch is static
//! in both directions.
use Uuid;
/// A KEY REPORTING ITSELF, one typed column at a time.
///
/// The engine's write-phase buffer implements it, and what each method means is *land one column of
/// this kind* — not *encode this value*. A row calls one method per column, in the key's own order,
/// and the sequence it calls is the contract: the same sequence comes back off [`ColumnReader`],
/// which is the one agreement that makes a written key readable by the code that wrote it.
///
/// ONE VALUE PER COLUMN. A row appending two would leave the read count out of step with the key's
/// column count, and a key whose columns drift is a key that addresses the wrong entity.
///
/// # Nothing here can fail
///
/// Every method returns nothing, so a row never branches on the way in and a write phase never has
/// half a key in it. What an engine cannot land is a fact about the engine's own storage and is
/// discovered where that storage is written to, not here — and a row has no repair for it in any
/// case, since its columns are its identity and dropping one is not an option it has.
/// WHAT AN ENGINE'S ERROR MUST BE ABLE TO SAY — the obligation a row's own refusals put on it.
///
/// A row is engine-blind, so it cannot name the type it would have to refuse in; and some refusals
/// are the ROW's to make rather than the engine's, because they are about the reading type's domain
/// rather than about the stored column. This trait is the door between the two, and its shape is
/// `serde::de::Error`'s for serde's own reason: ONE OPEN FLOOR that any row can word its refusal
/// through, and beside it the NAMED refusals the framework reserves — each defaulted onto the floor,
/// so an engine that says nothing gets every one of them and an engine that would rather keep one
/// structured overrides it.
///
/// [`custom`](Self::custom) is the whole obligation, and that is what keeps the set of ROWS open: a
/// row in a crate this one has never heard of, refusing something neither named shape covers, has
/// the floor already and needs nothing added here. A named method arrives the day a row spends one —
/// defaulted, so every engine already written goes on compiling, and a later engine can word it
/// without a byte moving in any row.
///
/// # Not dyn-compatible, and it is not asked to be
///
/// [`custom`](Self::custom) is generic over what it is handed, so an engine's error is spelled as
/// [`ColumnReader::Error`] and never behind a `dyn`. Taking [`core::fmt::Arguments`] instead would
/// buy object safety at the price of putting every caller through `format_args!`, and nothing here
/// holds an engine's error abstractly — the seam that spends it is generic in both directions.
/// A KEY TAKING ITSELF BACK, one typed column at a time.
///
/// The engine's read-phase cursor implements it, and each method lifts the NEXT column into the
/// type asked for. The cursor advances and is never rewound: a key's columns are read once, in the
/// order they were written, by the key that owns them.
///
/// # Whole or refused
///
/// [`finish`](Self::finish) consumes the reader, and what it asks is whether the key took ALL of
/// it. Tolerating a surplus column would let `(7, 42)` pose as the address of `(7, 42, 3)` — a hit
/// carrying the wrong entity, silently — so a key that reads short is refused rather than served.
/// The completeness question is asked once, at the end, by the caller that owns the reader; a row
/// holding `&mut R` cannot ask it and has no business doing so.
///
/// # `Sized`
///
/// Spent by [`finish`](Self::finish), which takes `self` by value.
/// THE UNUSED READER'S REFUSAL — a UNIT, because a phase that landed no column has exactly one thing
/// to say about a read against it.
///
/// It drops the words [`custom`](ColumnError::custom) is handed, and that is honest rather than
/// lossy here: the only reader that raises one holds nothing, so every refusal it can make is the
/// same refusal, and a `String` per read would be a sentence nobody wrote. A real engine keeps its
/// own error and its own words — see [`ColumnError`] for what the floor is FOR.
;
/// The unused WRITE phase — every column accepted and dropped, which is what a face that stores
/// nothing honestly does with one.
///
/// It is the column language's own half of [`VectorEngine for ()`](crate::VectorEngine) and of
/// [`FulltextEngine for ()`](crate::FulltextEngine): a base that mints a buffer needs a buffer to
/// mint, and the trivial one is the unit. FAMILY-FREE, which is what lets one pair serve both bases
/// rather than each family copying it.
/// The unused READ phase — every read past the last column, because there was never a first one.
///
/// [`finish`](ColumnReader::finish) SUCCEEDS, and the two answers together are the consistent
/// reading rather than a contradiction: a phase holding no column has nothing left over, so a key
/// that read nothing off it is whole. Only a key that tried to read is refused.
pub