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
//! bytes → Key: the engine's own addresses read back into the node's own key type — and, since the
//! by-key read landed, Key → bytes on the way back.
//!
//! ONE READ PER ENGINE FAMILY — [`keyed`] for full-text, [`vector_keyed`] for vector. They are two
//! rather than one because the SEAMS are two: `E::Address` and `E::Error` project through
//! [`FulltextEngine`] in one and [`VectorEngine`] in the other. Collapsing them would take a third
//! trait unifying the two engine faces — a seam invented to save a duplicated `map`, and one every
//! backend would then have to know about.
//!
//! **BOTH now spend the same kind of row, which is the column language landed on both sides.** Each
//! walk asks for [`Field`] — engine-blind, one impl per TYPE — and drives its own engine's
//! `buffer` / `finalize` / `open` phases around it. What is still two is the SEAM each is generic
//! in, and nothing else: the bodies are line-for-line the same walk.
//!
//! [`vector_addressed`] is the WRITE, and there is one rather than two because only one family has
//! a caller: [`VectorRead::get`](crate::VectorRead::get) takes an address a key was written into,
//! and the full-text family's own by-key read has no grammar yet. The only code that builds a
//! full-text address is a backend's own entry builder, which spells the three phases where the
//! engine is concrete.
use crate::;
/// Read every FULL-TEXT hit's ADDRESS back into `K` — the emission's half of the read, written once.
///
/// [`vector_keyed`] is the same walk for the other family; the module note says why they are two.
///
/// # Why it is here and not inside the engine
///
/// [`FulltextEngine`] is R-free: it stores what it is handed and hands it back, and it cannot name a
/// declaration's key type. So the typed half of the read belongs to the code that CAN — the emitted
/// `retrieve_keys`, which knows `K` because it knows its own upstream. This function is that code's
/// one shared line, exactly as [`ranked_keys`](super::ranked_keys) is the pipeline's: the emission
/// names the types and the framework owns the walk.
///
/// Three things happen per hit, in this order and no other:
///
/// 1. [`FulltextEngine::open`] turns the hit's address into a READ PHASE, consuming it;
/// 2. `K` takes its columns off that phase, one [`Field`] row per column, in the order the key's own
/// impl wrote them;
/// 3. [`ColumnReader::finish`] asks whether anything is LEFT — a stored address carrying more
/// columns than the key reads is a drifted column sequence, and it is named rather than silently
/// half-read.
///
/// The key's row names NO ENGINE, which is what the column language bought: one [`Field`] impl per
/// TYPE serves every engine there is, where the retired per-family row had to be written once per
/// (type × engine).
///
/// # It is FAIL-FAST, and that is the conservative reading
///
/// One unreadable address fails the whole answer rather than being dropped from it. A key that will
/// not decode is a corrupt index or a key whose column sequence no longer matches what was indexed
/// — a condition about the INDEX, not about that one hit — so a page silently one shorter would hide
/// exactly the thing worth surfacing.
///
/// # Errors
///
/// The engine's own error, from a column's read or from the completeness check — one type, because
/// [`ReadBuffer`](FulltextEngine::ReadBuffer) is tied to [`Error`](FulltextEngine::Error).
/// Read every VECTOR hit's ADDRESS back into `K` — [`keyed`]'s twin, and the SAME walk one seam
/// over.
///
/// Everything [`keyed`] states holds here unchanged, phase for phase and posture for posture: the
/// same order, the same fail-fast reading, the same engine-blind row, and the same reason the typed
/// half is the emission's rather than the engine's — [`VectorEngine`] is R-free too, so it answers
/// in its own address vocabulary and only the code that knows the upstream knows `K`.
///
/// # Errors
///
/// The engine's own error, from a column's read or from the completeness check — one type, because
/// [`ReadBuffer`](VectorEngine::ReadBuffer) is tied to [`Error`](VectorEngine::Error).
/// Report `key` into a FRESH buffer of `E`'s own and seal it — the walk above run BACKWARDS, and the
/// emission's half of the by-key read.
///
/// [`vector_keyed`] turns an address the engine produced into a key; this turns a key the caller
/// holds into the address [`VectorRead::get`](crate::VectorRead::get) takes. The two are one
/// correspondence read in two directions, which is why [`Field`] is one trait with two methods:
/// `write` reports a value's columns in the key's own order and `read` takes them back off in that
/// same order, so an address built here and an address a hit arrives under are THE SAME BYTES for
/// the same key.
///
/// # The buffer is the engine's, and that is the one thing this walk cannot supply itself
///
/// A row REPORTS and does not create: it is handed a [`ColumnWriter`](crate::ColumnWriter) and lands
/// its columns in it. Where that writer comes from is the engine's business — an arrow builder, a
/// term buffer, a bound-parameter list — so [`VectorEngine::buffer`] is what this calls, and its doc
/// says why a `Default` bound was the wrong shape for it.
///
/// # It is INFALLIBLE, and the asymmetry with [`vector_keyed`] is real rather than an oversight
///
/// Writing a key cannot fail: [`ColumnWriter`](crate::ColumnWriter) has no failing method, a value
/// renders its own columns, and the address is whatever they seal to. Reading one can, because the
/// bytes may be a key's from another era. There is no completeness check to run either — that check
/// asks whether a STORED address carried more than the key read, and this address was just built
/// from the key and carries exactly it.