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
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
//! THE CONFORMANCE WALK — the round-trip theorem an engine has to satisfy, as a function anybody
//! can run.
//!
//! A key crosses into an engine and comes back: [`buffer`](crate::VectorEngine::buffer) →
//! [`Field::write`] → [`finalize`](crate::VectorEngine::finalize) →
//! [`open`](crate::VectorEngine::open) → [`Field::read`] → [`ColumnReader::finish`]. What comes out
//! must be what went in, value for value. That is the whole of what an address IS, and it is the
//! only property every engine and every row have to agree about — so it is stated here once, as a
//! function, rather than restated per backend as a test.
//!
//! THIS IS A DELIVERABLE, not a test helper. It is `pub`, it takes no fixture and it names nothing
//! of this crate's — an engine written in a crate that has never heard of `ingraph` runs
//! [`round_trip_vector`] or [`round_trip_fulltext`] over its own key types and finds out whether it
//! implemented the column language or only compiled against it.
//!
//! # TWO LEGS, and the second one sees what no engine can
//!
//! Each entry runs the key through TWO round trips:
//!
//! 1. **The KIND LAW**, against a framework-private engine that records the kind of every column a
//! row lands and checks it against the kind the row asks back for. Engine-blind, so it holds for
//! every row on every backend.
//! 2. **The ENGINE**, against the real one, through its own three phases.
//!
//! Leg 1 is not redundant, and the reason is the shape of the language: [`ColumnWriter::fixed`]
//! falls back onto [`bytes`](ColumnWriter::bytes) until a backend has a native fixed-width column,
//! so a row that WRITES through `fixed` and READS through `bytes` is invisible on the shipped codec
//! — the two land identical bytes there — and is a wrong-column read on the first engine that
//! overrides one. Leg 2 passes such a row on tantivy. Leg 1 fails it, NAMING the column's index and
//! both kinds.
//!
//! That law is `store::field`'s own — *a row's WRITE kind and its READ kind must be the same kind* —
//! and it was found by hand, in the shipped [`SocketAddr`](core::net::SocketAddr) row, where the
//! arms delegated to two rows that write `fixed` while the enum itself reads `bytes`. This module
//! is that finding turned into something a compiler-of-rows cannot skip: every row run through
//! conformance is checked, including rows written after the finding was forgotten.
//!
//! # TWO ENTRIES, one body — and why there is no third trait
//!
//! The two bases are ISOMORPHIC at the address lifecycle: same three functions, same four members,
//! same tie between [`ReadBuffer`](crate::VectorEngine::ReadBuffer) and
//! [`Error`](crate::VectorEngine::Error). The walk is therefore written ONCE, over the three
//! functions passed as arguments, and each entry supplies its own family's.
//!
//! A private helper trait unifying the three seats was the drafted shape and it does not fit, which
//! was MEASURED rather than assumed: the natural pair of blanket impls — `impl<E: VectorEngine> …
//! for E` beside `impl<E: FulltextEngine> … for E` — is `E0119`, *conflicting implementations of
//! trait*, and no negative bound would close it either, because `()` implements BOTH bases and the
//! overlap is inhabited. Repairing it takes a marker type per family, which is two more types
//! standing in front of a twelve-line body. Passing the three functions states the same isomorphism
//! with no type at all, and it states it at the CALL: a base that grew a fourth phase, or moved one,
//! fails at the entry that names the three.
//!
//! # What it does NOT do
//!
//! It does not touch storage. Nothing here indexes a document, commits a segment or opens a
//! directory — the address lifecycle is a pure function of a key, and conformance is the pure part
//! stated purely. An engine's live behaviour is its own suite's; `store::tantivy`'s
//! `pipeline_tests` is what that looks like one layer out, where a key goes through a real segment
//! and comes back off a real search.
use fmt;
use Uuid;
use ;
/// THE COLUMN-KIND TABLE — the ten doors that differ only in a name, written ONCE and handed to
/// every emitter that has to agree about them.
///
/// Three places name this same set: [`ColumnDoor`]'s variants, [`KindLog`]'s write overrides and
/// [`KindColumns`]'s read overrides. They were three separate lists, and a line missing from one of
/// them was SILENT in the worst possible way — a variant with no override does not fail to compile,
/// it INHERITS the column trait's default, lands through [`fixed`](ColumnWriter::fixed), and every
/// row using that width then reports a split it never wrote. That is a conformance walk accusing
/// correct rows, which is worse than one that misses. So the list lives here and each emitter asks
/// for it; adding a width is one line and the line reaches all three at once.
///
/// The mechanism is the X-macro: this expands to `$emit! { <the table> }`, so an emitter is a
/// `macro_rules!` taking the table's shape and writing whatever it writes. That keeps each emission
/// beside the type it belongs to instead of collecting the enum and both impls at one point in the
/// file.
///
/// # What it does NOT close, stated because the gap is the same shape as the one it does
///
/// The four remaining doors — `text`, `bytes`, `uuid`, `fixed` — are not on the table: each has a
/// body of its own rather than a width, so each emitter writes those out beside the expansion. A new
/// door of THAT kind still costs three edits. And a new method added to [`ColumnWriter`] /
/// [`ColumnReader`] and named nowhere here is still silent, for the reason above — nothing in the
/// language enumerates which defaulted methods a sink overrode. What the table closes is the ten,
/// which is where the drift risk actually was.
/// [`ColumnDoor`] and its [`Display`](fmt::Display), off [`word_doors`]' table plus the four doors
/// that carry a body rather than a width.
};
}
word_doors!;
/// WHAT CONFORMANCE FOUND — one arm per way the round trip can fail, and each one names the party
/// at fault.
///
/// Three of the seven are the ROW's alone ([`KindSplit`](Self::KindSplit), [`Short`](Self::Short),
/// [`Surplus`](Self::Surplus)): the engine-blind leg raises them, so each is the same refusal
/// whichever backend was under test. Two are the ENGINE's ([`Read`](Self::Read),
/// [`Unfinished`](Self::Unfinished)) and carry its own error unwrapped, so a backend author reads a
/// diagnosis in their own vocabulary. [`Row`](Self::Row) is the open floor a row worded for itself,
/// and [`Mismatch`](Self::Mismatch) is the one arm EITHER leg can raise — a row that does not
/// restore fails everywhere, and an engine that loses a value fails only at itself.
///
/// Generic in the ENGINE's error alone. The key type is rendered to a string where a mismatch is
/// found, so this type stays one parameter wide and a caller holding several keys' results holds one
/// type.
/// THE KIND ENGINE'S REFUSAL — the three ways its cursor can disagree with its log, plus the floor.
///
/// Private, and it exists rather than reusing [`ConformanceError`] directly because a
/// [`ColumnReader::Error`] cannot carry the engine parameter this leg has no engine for. The
/// conversion below is the whole of the difference.
/// ONE LANDED COLUMN of the kind engine: what door it went through, and the octets it carried.
///
/// The bytes are kept so the read can hand the row its own value back. A leg that returned a
/// PLACEHOLDER would turn every row with a domain — the ten `NonZero*` — into a false refusal, and a
/// leg that returned nothing could not check the value survived at all.
/// THE KIND-RECORDING WRITE PHASE — every column's door, remembered.
///
/// It overrides EVERY method, including the ten that are defaulted, and that is the one thing that
/// makes it work. A defaulted [`i8`](ColumnWriter::i8) lands through
/// [`fixed`](ColumnWriter::fixed) and a defaulted `fixed` lands through
/// [`bytes`](ColumnWriter::bytes), so a sink that inherits either records the door the DEFAULT
/// chose rather than the one the row asked for — and the row's own choice is the thing under test.
;
/// One landed column per table line — the widths, which differ only in the door they name.
;
}
/// THE KIND-CHECKING READ PHASE — every column's door, compared against the one that wrote it.
///
/// [`KindLog`]'s mirror, overriding every method for the same reason: a defaulted
/// [`i8`](ColumnReader::i8) would ask for `fixed<1>` where the row asked for `i8`, and the leg would
/// report a split the row never wrote.
/// One arm-typed read per table line — the write side's mirror, off the same table.
)*
};
}
/// THE KIND LAW, run over one key — engine-blind, and the leg no backend can perform for itself.
///
/// `E` is free: this leg raises none of the engine's arms, and carrying the parameter is what lets
/// both entries `?` its result straight into their own return type.
/// THE ROUND TRIP, over an engine's three phases — the shared body both entries spend.
///
/// The three functions arrive as arguments rather than through a trait, and the module doc says why:
/// `()` implements both bases, so a private trait unifying them cannot be reached by a pair of
/// blanket impls. What is left is the isomorphism itself, and it is stated here as a signature.
///
/// The order is the lifecycle's, not the assertion's: `read` then `finish` then the comparison, so
/// an address that is not whole is reported as not whole rather than as a value that differs.
/// CONFORMANCE FOR A VECTOR ENGINE — one key, both legs.
///
/// Run it over every key type a backend will be asked to address, and over the members of
/// [`Id`](crate::Id) if the backend means to serve declarations generally. A green run says two
/// things: this engine's address lifecycle restores this key, and this key's row asks back for the
/// columns it landed.
///
/// # THE UNIT ENGINE, and why nothing is special-cased for it
///
/// [`VectorEngine for ()`](VectorEngine) stores nothing, so it is the one backend where the walk's
/// answer is decided before it starts, and both answers are the honest one:
///
/// - a key WITH columns is refused as [`Read`](ConformanceError::Read) carrying
/// [`NoColumns`](crate::NoColumns) — *this face landed no columns*, which is exactly true and is
/// the engine's own word for it;
/// - a key with NO columns passes, because a phase holding nothing has nothing left over and a key
/// that read nothing off it is whole.
///
/// That is [`ColumnReader for ()`](ColumnReader)'s stated reading arriving here unchanged. A
/// short-circuit written into this function would be the same two answers with a second author.
///
/// # Errors
///
/// [`ConformanceError`], whose arms say which party the walk found at fault — the row's four, the
/// engine's two, and the floor a row worded for itself.
/// CONFORMANCE FOR A FULL-TEXT ENGINE — [`round_trip_vector`]'s twin, and the same walk one seam
/// over.
///
/// Everything that entry states holds here unchanged, including the unit engine's two answers:
/// nothing in either body names a family, and what differs is only which base's three functions are
/// handed to the walk.
///
/// # Errors
///
/// [`round_trip_vector`]'s.