ingraph 0.1.0

A declaration-driven indexing framework: records and nodes are written as Rust types, and the storage rows, the dataflow between them and the GraphQL query surface are emitted from the declaration.
Documentation
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
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
//! THE ROWS, against two toy engines and one hand-assembled byte string.
//!
//! The round trips run on `store::column`'s [`testkit`](crate::store::column::testkit) sinks —
//! `Fallback`, which implements only the required kinds, and `Native`, which lands a column per
//! width — because a row that reads back off both is a row that speaks the LANGUAGE rather than one
//! engine's storage. Two toys of this file's own carry the two claims the shared pair cannot: a sink
//! that tells [`fixed`](ColumnWriter::fixed) from [`bytes`](ColumnWriter::bytes), which is the only
//! vantage the untagged rows' choice of door is visible from, and one that renders the codec
//! `store::tantivy` ships, which is what the layout parity is asserted against.

// The three pointer rows live in `alloc`, and this file exercises all three.
extern crate alloc;

use core::{
  fmt::Debug,
  net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, SocketAddrV4, SocketAddrV6},
  num::{
    NonZeroI8, NonZeroI16, NonZeroI32, NonZeroI64, NonZeroI128, NonZeroU8, NonZeroU16, NonZeroU32,
    NonZeroU64, NonZeroU128,
  },
};

use smol_bytes::Utf8Bytes;
use uuid::Uuid;

use super::Field;
use crate::store::{
  ColumnError, ColumnReader, ColumnWriter,
  column::testkit::{Col, Fallback, Native, Refusal},
};

/// The entity a typed id addresses. It implements nothing, which is the point: `E` reaches no
/// column.
struct Witness;

/// The uuid every row below carries, so a failure names a value rather than a fresh one.
fn identity() -> Uuid {
  Uuid::from_bytes([
    0x9f, 0x1c, 0x2d, 0x3e, 0x4a, 0x5b, 0x6c, 0x7d, 0x8e, 0x9f, 0xa0, 0xb1, 0xc2, 0xd3, 0xe4, 0xf5,
  ])
}

/// The v6 host the network rows and the layout assertions share.
fn host() -> Ipv6Addr {
  Ipv6Addr::new(0x2001, 0x0db8, 0, 0, 0, 0, 0, 1)
}

/// What one row landed on a sink with NO native widths.
fn landed<T: Field>(value: &T) -> Vec<Col> {
  let mut sink = Fallback::default();
  Field::write(value, &mut sink);
  sink.0
}

/// ONE ROW'S WHOLE ROUND TRIP on a sink with no native widths: written, read back off the columns it
/// wrote, and asked whether the key took all of them.
fn crosses<T: Field + PartialEq + Debug>(value: &T) {
  let mut sink = Fallback::default();
  Field::write(value, &mut sink);

  let mut read = sink.read();
  let back = T::read(&mut read).expect("the row reads back");
  read.finish().expect("the key took every column");
  assert_eq!(&back, value, "a row came back as another value");
}

/// The same round trip on a sink whose widths are NATIVE columns — the other half of *written once,
/// read by every engine*.
fn crosses_native<T: Field + PartialEq + Debug>(value: &T) {
  let mut sink = Native::default();
  Field::write(value, &mut sink);

  let mut read = sink.read();
  let back = T::read(&mut read).expect("the row reads back");
  read.finish().expect("the key took every column");
  assert_eq!(&back, value, "a row came back as another value");
}

/// One row against both engines, which is what every row below is asked.
fn crosses_both<T: Field + PartialEq + Debug>(value: &T) {
  crosses(value);
  crosses_native(value);
}

/// A SINK THAT TELLS THE KINDS APART — what an engine with a native fixed-width column has, and the
/// only vantage from which a row's choice between [`ColumnWriter::fixed`] and [`ColumnWriter::bytes`]
/// is observable at all. On the shipped codec the two land identical bytes.
#[derive(Debug, Default)]
struct Kinded(Vec<(&'static str, Vec<u8>)>);

impl ColumnWriter for Kinded {
  fn i64(&mut self, value: i64) {
    self.0.push(("i64", value.to_be_bytes().to_vec()));
  }

  fn u64(&mut self, value: u64) {
    self.0.push(("u64", value.to_be_bytes().to_vec()));
  }

  fn text(&mut self, value: &str) {
    self.0.push(("text", value.as_bytes().to_vec()));
  }

  fn bytes(&mut self, value: &[u8]) {
    self.0.push(("bytes", value.to_vec()));
  }

  fn uuid(&mut self, value: Uuid) {
    self.0.push(("uuid", value.as_bytes().to_vec()));
  }

  fn fixed<const N: usize>(&mut self, value: &[u8; N]) {
    self.0.push(("fixed", value.to_vec()));
  }
}

/// What one row landed on the kind-telling sink.
fn kinds<T: Field>(value: &T) -> Vec<(&'static str, Vec<u8>)> {
  let mut sink = Kinded::default();
  Field::write(value, &mut sink);
  sink.0
}

/// THE SHIPPED CODEC, rendered: a big-endian `u32` length prefix and then the value's raw bytes, for
/// every kind alike — which is what `store::tantivy`'s address is, and therefore what the bytes a
/// row lands there look like once the engine speaks columns.
///
/// It implements the REQUIRED kinds only, so every other kind arrives through its fallback exactly
/// as it will on that engine, whose storage has no typed column to override one with.
#[derive(Debug, Default)]
struct Rendered(Vec<u8>);

impl Rendered {
  fn framed(&mut self, value: &[u8]) {
    let len = u32::try_from(value.len()).expect("a key column shorter than u32::MAX bytes");
    self.0.extend_from_slice(&len.to_be_bytes());
    self.0.extend_from_slice(value);
  }
}

impl ColumnWriter for Rendered {
  fn i64(&mut self, value: i64) {
    self.framed(&value.to_be_bytes());
  }

  fn u64(&mut self, value: u64) {
    self.framed(&value.to_be_bytes());
  }

  fn text(&mut self, value: &str) {
    self.framed(value.as_bytes());
  }

  fn bytes(&mut self, value: &[u8]) {
    self.framed(value);
  }

  fn uuid(&mut self, value: Uuid) {
    self.framed(value.as_bytes());
  }
}

/// ONE LAYOUT, against **the bytes that are already on disk** for this value.
///
/// # `expected` IS THE COMPATIBILITY CONTRACT, and that is what the flip made of it
///
/// Each byte string below was hand-assembled from the codec `store::tantivy` shipped BEFORE the
/// column language reached it — a `u32` big-endian length and then the value's own bytes — and it is
/// therefore a transcript of what a live index written under the retired per-engine rows holds. It
/// is no longer a restatement of a live impl that could be re-derived if that impl moved: the live
/// impl is gone, and what these strings pin is the LAYOUT ITSELF.
///
/// **Changing one of these numbers breaks every index already written.** A key that renders
/// differently is a key that finds nothing — a stored address is read back by the type that wrote
/// it, so a drifted layout is not a failed decode but a silent miss. If a row's layout genuinely has
/// to move, that is a REINDEX and it is stated as one; it is not a test to bless.
///
/// The parity was a DOUBLE assertion while both codecs lived, and the half that compared against a
/// live `FulltextField<TantivyFulltext>` impl died with those rows. What stands in its place is the
/// half below.
#[cfg(not(feature = "tantivy"))]
fn layout<T: Field>(value: &T, expected: &[u8]) {
  let mut rendered = Rendered::default();
  Field::write(value, &mut rendered);
  assert_eq!(rendered.0, expected, "the row's layout moved");
}

/// The same, with **the shipped engine's own write phase** driven beside the toy one — the NEW path
/// asserted against the OLD contract.
///
/// The toy [`Rendered`] sink says what the row lands in the abstract; this half says what
/// `store::tantivy` actually stores, by running the exact three functions the framework's write walk
/// runs — [`buffer`](crate::FulltextEngine::buffer), the row's own
/// [`write`](Field::write), and [`finalize`](crate::FulltextEngine::finalize) — and comparing the
/// sealed address to the historical bytes. So a change anywhere on that path (the row, the engine's
/// `ColumnWriter`, an overridden [`fixed`](ColumnWriter::fixed)) fails HERE rather than at whatever
/// retrieve first misses a document.
#[cfg(feature = "tantivy")]
fn layout<T: Field>(value: &T, expected: &[u8]) {
  use crate::{FulltextEngine, store::TantivyFulltext};

  let mut rendered = Rendered::default();
  Field::write(value, &mut rendered);
  assert_eq!(rendered.0, expected, "the row's layout moved");

  let mut terms = TantivyFulltext::buffer();
  Field::write(value, &mut terms);
  let address = TantivyFulltext::finalize(terms);
  assert_eq!(
    address.as_slice(),
    expected,
    "the shipped engine's write phase and the stored layout disagree"
  );
}

#[test]
fn every_integer_lands_a_column_of_its_own_width() {
  // The claim is the one the shipped rows make in their own words: at its own width, never widened.
  // An engine with native integer columns is where it is VISIBLE, so this is asserted there.
  let mut sink = Native::default();
  Field::write(&i8::MIN, &mut sink);
  Field::write(&i16::MIN, &mut sink);
  Field::write(&i32::MIN, &mut sink);
  Field::write(&i64::MIN, &mut sink);
  Field::write(&i128::MIN, &mut sink);
  Field::write(&u8::MAX, &mut sink);
  Field::write(&u16::MAX, &mut sink);
  Field::write(&u32::MAX, &mut sink);
  Field::write(&u64::MAX, &mut sink);
  Field::write(&u128::MAX, &mut sink);

  assert_eq!(
    sink.0,
    vec![
      Col::I8(i8::MIN),
      Col::I16(i16::MIN),
      Col::I32(i32::MIN),
      Col::I64(i64::MIN),
      Col::I128(i128::MIN),
      Col::U8(u8::MAX),
      Col::U16(u16::MAX),
      Col::U32(u32::MAX),
      Col::U64(u64::MAX),
      Col::U128(u128::MAX),
    ]
  );
}

#[test]
fn every_integer_crosses_both_engines() {
  crosses_both(&i8::MIN);
  crosses_both(&i8::MAX);
  crosses_both(&i16::MIN);
  crosses_both(&i32::MIN);
  crosses_both(&i64::MIN);
  crosses_both(&i128::MIN);
  crosses_both(&0_i64);
  crosses_both(&u8::MAX);
  crosses_both(&u16::MAX);
  crosses_both(&u32::MAX);
  crosses_both(&u64::MAX);
  crosses_both(&u128::MAX);
  crosses_both(&0_u128);
}

#[test]
fn a_nonzero_lands_the_column_its_integer_lands() {
  // TRANSPARENCY: a wrapper is how a value is HELD, so the two must address one entry.
  assert_eq!(
    landed(&NonZeroU64::new(9).expect("9 is not zero")),
    landed(&9_u64)
  );
  assert_eq!(
    landed(&NonZeroI8::new(-3).expect("-3 is not zero")),
    landed(&-3_i8)
  );
  assert_eq!(
    landed(&NonZeroU128::new(u128::MAX).expect("the maximum is not zero")),
    landed(&u128::MAX)
  );
}

#[test]
fn every_nonzero_crosses_both_engines() {
  crosses_both(&NonZeroI8::new(i8::MIN).expect("the minimum is not zero"));
  crosses_both(&NonZeroI16::new(-2).expect("-2 is not zero"));
  crosses_both(&NonZeroI32::new(-2).expect("-2 is not zero"));
  crosses_both(&NonZeroI64::new(-2).expect("-2 is not zero"));
  crosses_both(&NonZeroI128::new(i128::MIN).expect("the minimum is not zero"));
  crosses_both(&NonZeroU8::new(u8::MAX).expect("the maximum is not zero"));
  crosses_both(&NonZeroU16::new(7).expect("7 is not zero"));
  crosses_both(&NonZeroU32::new(7).expect("7 is not zero"));
  crosses_both(&NonZeroU64::new(7).expect("7 is not zero"));
  crosses_both(&NonZeroU128::new(u128::MAX).expect("the maximum is not zero"));
}

/// A zero landed at each width, taken back by the `NonZero*` that cannot hold it.
macro_rules! refuses_zero {
  ($($nonzero:ty => $int:ty),* $(,)?) => {
    $({
      let zero: $int = 0;
      let mut sink = Fallback::default();
      Field::write(&zero, &mut sink);

      let mut read = sink.read();
      assert_eq!(
        <$nonzero>::read(&mut read).expect_err("zero is not admitted"),
        Refusal::Custom("value 0 outside the type's domain".to_owned()),
        "{} took a zero", stringify!($nonzero)
      );
    })*
  };
}

#[test]
fn a_zero_column_is_the_rows_own_domain_refusal() {
  // The narrowing is on the way OUT — the column is well-formed and the VALUE is inadmissible — and
  // an engine-blind row has only the shape of that refusal to say, which the engine words.
  refuses_zero!(
    NonZeroI8 => i8,
    NonZeroI16 => i16,
    NonZeroI32 => i32,
    NonZeroI64 => i64,
    NonZeroI128 => i128,
    NonZeroU8 => u8,
    NonZeroU16 => u16,
    NonZeroU32 => u32,
    NonZeroU64 => u64,
    NonZeroU128 => u128,
  );
}

#[test]
fn a_uuid_crosses_as_a_uuid_column() {
  assert_eq!(landed(&identity()), vec![Col::Uuid(identity())]);
  crosses_both(&identity());
  crosses_both(&Uuid::nil());
}

#[test]
fn every_text_member_crosses_as_a_text_column() {
  assert_eq!(
    landed(&"a caption".to_owned()),
    vec![Col::Text("a caption".to_owned())]
  );
  assert_eq!(
    landed(&Utf8Bytes::from("a caption".to_owned())),
    vec![Col::Text("a caption".to_owned())]
  );

  crosses_both(&"a caption".to_owned());
  crosses_both(&String::new());
  crosses_both(&Utf8Bytes::from("a caption".to_owned()));

  #[cfg(feature = "smol_str")]
  {
    assert_eq!(
      landed(&smol_str::SmolStr::new("a caption")),
      vec![Col::Text("a caption".to_owned())]
    );
    crosses_both(&smol_str::SmolStr::new("a caption"));
  }
}

#[test]
fn the_network_family_crosses_by_octets() {
  crosses_both(&Ipv4Addr::new(10, 0, 0, 1));
  crosses_both(&host());
  crosses_both(&Ipv6Addr::LOCALHOST);
  crosses_both(&SocketAddrV4::new(Ipv4Addr::new(10, 0, 0, 1), 8080));
  crosses_both(&SocketAddrV6::new(host(), 8080, 0x0a0b_0c0d, 0x0102_0304));
  crosses_both(&IpAddr::V4(Ipv4Addr::new(10, 0, 0, 1)));
  crosses_both(&IpAddr::V6(host()));
  crosses_both(&SocketAddr::V4(SocketAddrV4::new(
    Ipv4Addr::new(10, 0, 0, 1),
    8080,
  )));
  crosses_both(&SocketAddr::V6(SocketAddrV6::new(host(), 8080, 1, 2)));
}

#[test]
fn an_untagged_row_lands_a_variable_column_where_its_arms_land_fixed_ones() {
  // THE HAZARD THIS PINS: `fixed` falls back onto `bytes` on the shipped codec, so the two are the
  // same door there and a different one on any engine with a native fixed width — where an untagged
  // row that wrote through `fixed` would land its arms in two columns its `bytes` read never finds.
  // Same layout, and deliberately not the same kind.
  let socket = SocketAddrV4::new(Ipv4Addr::new(10, 0, 0, 1), 8080);
  let packed = vec![10, 0, 0, 1, 0x1f, 0x90];

  assert_eq!(kinds(&socket), vec![("fixed", packed.clone())]);
  assert_eq!(kinds(&SocketAddr::V4(socket)), vec![("bytes", packed)]);

  let address = Ipv4Addr::new(10, 0, 0, 1);
  assert_eq!(kinds(&address), vec![("fixed", vec![10, 0, 0, 1])]);
  assert_eq!(
    kinds(&IpAddr::V4(address)),
    vec![("bytes", vec![10, 0, 0, 1])]
  );
}

#[test]
fn an_untagged_host_reads_its_arms_apart_by_width() {
  let mut sink = Fallback::default();
  Field::write(&IpAddr::V4(Ipv4Addr::new(10, 0, 0, 1)), &mut sink);
  Field::write(&IpAddr::V6(host()), &mut sink);
  sink.bytes(&[1, 2, 3, 4, 5]);

  let mut read = sink.read();
  assert_eq!(
    IpAddr::read(&mut read).expect("four octets are a v4 host"),
    IpAddr::V4(Ipv4Addr::new(10, 0, 0, 1))
  );
  assert_eq!(
    IpAddr::read(&mut read).expect("sixteen octets are a v6 host"),
    IpAddr::V6(host())
  );
  assert_eq!(
    IpAddr::read(&mut read).expect_err("five octets are no host"),
    Refusal::Custom("width 5, expected one of [4, 16]".to_owned())
  );
}

#[test]
fn an_untagged_socket_reads_its_arms_apart_by_width() {
  let v4 = SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(10, 0, 0, 1), 8080));
  let v6 = SocketAddr::V6(SocketAddrV6::new(host(), 8080, 0x0a0b_0c0d, 0x0102_0304));

  let mut sink = Fallback::default();
  Field::write(&v4, &mut sink);
  Field::write(&v6, &mut sink);
  sink.bytes(&[1, 2, 3, 4, 5, 6, 7]);

  let mut read = sink.read();
  assert_eq!(
    SocketAddr::read(&mut read).expect("six bytes are a v4 socket"),
    v4
  );
  assert_eq!(
    SocketAddr::read(&mut read).expect("twenty-six bytes are a v6 socket"),
    v6
  );
  assert_eq!(
    SocketAddr::read(&mut read).expect_err("seven bytes are no socket"),
    Refusal::Custom("width 7, expected one of [6, 26]".to_owned())
  );
}

/// A ROW FROM A CRATE THIS ONE HAS NEVER HEARD OF, and refusing something NEITHER NAMED SHAPE
/// covers: its two columns must agree, which is a fact about the pair rather than about either
/// column's domain or its width.
///
/// It is not in the id vocabulary, it names no engine, and nothing was added to [`ColumnError`] for
/// it — [`custom`](ColumnError::custom) is the floor, and that this row needs nothing else is the
/// floor being open.
#[derive(Debug, PartialEq, Eq)]
struct Checked(u64);

impl Field for Checked {
  fn write(&self, w: &mut impl ColumnWriter) {
    w.u64(self.0);
    w.u64(!self.0);
  }

  fn read<R: ColumnReader>(r: &mut R) -> Result<Self, R::Error> {
    let value = r.u64()?;
    let check = r.u64()?;
    if check == !value {
      Ok(Self(value))
    } else {
      Err(R::Error::custom("my own reason"))
    }
  }
}

#[test]
fn a_row_with_a_refusal_of_its_own_words_it_through_the_floor() {
  crosses_both(&Checked(9));

  // A pair that does not agree — well-formed columns, both of them, and a value the row still
  // refuses. Neither named shape has anything to say about it, so the words are the row's.
  let mut sink = Fallback::default();
  sink.u64(9);
  sink.u64(9);

  let mut read = sink.read();
  assert_eq!(
    Checked::read(&mut read).expect_err("nine is not the complement of nine"),
    Refusal::Custom("my own reason".to_owned())
  );
}

#[test]
fn a_byte_array_crosses_at_the_width_its_type_states() {
  crosses_both(&[0xde_u8, 0xad, 0xbe, 0xef]);
  crosses_both(&[0_u8; 12]);

  // A column of another width is not this value, and the refusal is the ENGINE's: the width was
  // settled where it is checked, so the row had nothing to say about it.
  let mut sink = Fallback::default();
  Field::write(&[0xde_u8, 0xad, 0xbe, 0xef], &mut sink);

  let mut read = sink.read();
  assert_eq!(
    <[u8; 12]>::read(&mut read).expect_err("four bytes are not twelve"),
    Refusal::Octets {
      wanted: 12,
      found: 4,
    }
  );
}

#[test]
fn a_pointer_lands_exactly_what_it_holds() {
  use alloc::{rc::Rc, sync::Arc};

  assert_eq!(landed(&Arc::new(9_u64)), landed(&9_u64));
  assert_eq!(landed(&Rc::new(9_u64)), landed(&9_u64));
  assert_eq!(landed(&Box::new(9_u64)), landed(&9_u64));

  crosses_both(&Arc::new(9_u64));
  crosses_both(&Rc::new("a caption".to_owned()));
  crosses_both(&Box::new(identity()));
  // One level out again: a pointer to a pointer is still the same address.
  crosses_both(&Arc::new(Box::new(9_u64)));
}

#[test]
fn a_typed_id_lands_its_id_and_nothing_for_the_entity() {
  let id = crate::TypedId::<Uuid, Witness>::new(identity());

  assert_eq!(landed(&id), landed(&identity()));
  crosses_both(&id);
  crosses_both(&crate::TypedId::<u64, Witness>::new(9));
}

#[cfg(feature = "mongo")]
#[test]
fn the_bson_pair_crosses_at_its_own_width() {
  let uuid = bson::Uuid::from_bytes(*identity().as_bytes());
  let oid = bson::oid::ObjectId::from_bytes([
    0x50, 0x7f, 0x1f, 0x77, 0xbc, 0xf8, 0x6c, 0xd7, 0x99, 0x43, 0x90, 0x11,
  ]);

  assert_eq!(
    landed(&uuid),
    vec![Col::Bytes(identity().as_bytes().to_vec())]
  );
  assert_eq!(landed(&oid), vec![Col::Bytes(oid.bytes().to_vec())]);

  crosses_both(&uuid);
  crosses_both(&oid);
}

#[test]
fn a_key_of_several_members_reads_its_columns_back_in_order() {
  let mut sink = Fallback::default();
  Field::write(&7_u32, &mut sink);
  Field::write(&"a caption".to_owned(), &mut sink);
  Field::write(&identity(), &mut sink);
  Field::write(&host(), &mut sink);

  let mut read = sink.read();
  assert_eq!(u32::read(&mut read).expect("the first column"), 7);
  assert_eq!(
    String::read(&mut read).expect("the second column"),
    "a caption"
  );
  assert_eq!(Uuid::read(&mut read).expect("the third column"), identity());
  assert_eq!(
    Ipv6Addr::read(&mut read).expect("the fourth column"),
    host()
  );
  read.finish().expect("the key took every column");
}

#[test]
fn a_key_that_reads_fewer_members_is_refused_at_finish() {
  let mut sink = Fallback::default();
  Field::write(&7_u32, &mut sink);
  Field::write(&"a caption".to_owned(), &mut sink);
  Field::write(&identity(), &mut sink);

  // `(7, "a caption")` would otherwise pose as the address of the three-member key.
  let mut read = sink.read();
  assert_eq!(u32::read(&mut read).expect("the first column"), 7);
  assert_eq!(
    String::read(&mut read).expect("the second column"),
    "a caption"
  );
  assert_eq!(read.finish(), Err(Refusal::Trailing(1)));
}

/// THE STORED-ADDRESS COMPATIBILITY CONTRACT — see [`layout`], which is where the whole argument
/// is.
///
/// Every byte string here is a transcript of what a live tantivy index ALREADY HOLDS for the value
/// beside it. Under the `tantivy` feature each is also driven through the shipped engine's own
/// `buffer` → `write` → `finalize`, so the new path is checked against the old bytes rather than
/// against itself.
///
/// # ONE VALUE PER COLUMN KIND, which is what the list is FOR
///
/// The transcripts started at six values and covered four of the five kinds a row can land in
/// (`i64`, `u64`, `uuid`, and `fixed` at two widths). Text and the variable-width byte column were
/// held by argument alone — the impl not overriding [`ColumnWriter::fixed`], and the round-trip
/// suite's own widths — and an argument is not a transcript. The last three below close that: a
/// `String` for [`text`](ColumnWriter::text), an [`IpAddr`](core::net::IpAddr) V4 arm for
/// [`bytes`](ColumnWriter::bytes), and a `[u8; 12]` for a THIRD `fixed` width, so every door a row
/// can go through has a hand-written byte string standing behind it.
///
/// Each was derived from the retired codec the same way the first six were, and the derivation is
/// one line: `push_bytes` framed a `u32` big-endian length and then the octets, `push_text` was
/// `push_bytes(value.as_bytes())`, the `[u8; N]` row was `push_bytes(self)`, and
/// `IpAddr`'s arms were `push_bytes(&host.octets())`.
#[test]
fn the_layouts_are_the_ones_the_shipped_codec_lands() {
  layout(
    &0x0123_4567_89ab_cdef_i64,
    &[0, 0, 0, 8, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef],
  );
  layout(
    &0xfedc_ba98_7654_3210_u64,
    &[0, 0, 0, 8, 0xfe, 0xdc, 0xba, 0x98, 0x76, 0x54, 0x32, 0x10],
  );
  layout(
    &NonZeroU64::new(0xfedc_ba98_7654_3210).expect("the value is not zero"),
    // The `u64` row's bytes, to the byte: transparency is a LAYOUT law before it is anything else.
    &[0, 0, 0, 8, 0xfe, 0xdc, 0xba, 0x98, 0x76, 0x54, 0x32, 0x10],
  );
  layout(
    &identity(),
    &[
      0, 0, 0, 16, 0x9f, 0x1c, 0x2d, 0x3e, 0x4a, 0x5b, 0x6c, 0x7d, 0x8e, 0x9f, 0xa0, 0xb1, 0xc2,
      0xd3, 0xe4, 0xf5,
    ],
  );
  layout(
    &host(),
    &[
      0, 0, 0, 16, 0x20, 0x01, 0x0d, 0xb8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0x01,
    ],
  );
  layout(
    &SocketAddrV6::new(host(), 8080, 0x0a0b_0c0d, 0x0102_0304),
    &[
      0, 0, 0, 26, 0x20, 0x01, 0x0d, 0xb8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0x01, 0x1f, 0x90, 0x0a,
      0x0b, 0x0c, 0x0d, 0x01, 0x02, 0x03, 0x04,
    ],
  );
  // THE TEXT COLUMN. The prefix counts OCTETS and not characters, which is why the value carries a
  // multi-byte one: four characters, five bytes, and a prefix that says five. A codec counting
  // `chars` would render this string one byte short and every text key written before the move
  // would stop being findable.
  layout(
    &"café".to_owned(),
    &[0, 0, 0, 5, 0x63, 0x61, 0x66, 0xc3, 0xa9],
  );
  // THE VARIABLE-WIDTH BYTE COLUMN, at the untagged row whose WIDTH is its discriminant — the V4
  // arm, whose four octets are what tells it from the V6 arm's sixteen.
  layout(
    &IpAddr::V4(Ipv4Addr::new(10, 0, 0, 1)),
    &[0, 0, 0, 4, 10, 0, 0, 1],
  );
  // A THIRD `fixed` WIDTH, and it is the bson id's twelve — the widest evidence there is that the
  // fallback onto `bytes` frames at whatever width the type states rather than at a codec's own.
  layout(
    &[
      0x64_u8, 0x9f, 0x1c, 0x2d, 0x3e, 0x4a, 0x5b, 0x6c, 0x7d, 0x8e, 0x9f, 0xa0,
    ],
    &[
      0, 0, 0, 12, 0x64, 0x9f, 0x1c, 0x2d, 0x3e, 0x4a, 0x5b, 0x6c, 0x7d, 0x8e, 0x9f, 0xa0,
    ],
  );
}