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
//! [`SlotHandle`] — the SLOT BRAND: an engine handle that carries, in its type, which declaration's
//! slot it was opened for.
use ;
use ;
/// An engine handle BRANDED with the SLOT it was opened for.
///
/// # What `T` is, and that it MOVED
///
/// It was the DECLARATION, while a declaration was a slot. Under the engine grammar a slot is
/// `(elected field × declared engine)` and `T` is the marker naming that pair — see
/// [`Slot`](super::Slot), which a derived index emits one of per slot. Nothing here changed to carry
/// it: `T: ?Sized` was already unbounded, so the brand narrowed for free, and a declaration is still
/// what a slot marker names ([`Slot::Of`](super::Slot::Of)).
///
/// # What it stops, and why that is corpus corruption rather than a mix-up
///
/// A slot is the grain of storage isolation, and for the shipped engine it is load-bearing
/// arithmetic: ONE Tantivy index per slot, because BM25's corpus statistics — `docfreq` over
/// `numdocs`, and the average document length the length normalization divides by — are INDEX-wide.
/// A write that lands in another slot's index does not merely put a row in the wrong place;
/// it moves that index's scores, which moves them out from under the MANDATORY FLOOR the retrieve
/// face is calibrated against. The repair is a reindex, not a code change. `store::tantivy`'s own
/// three laws state the same fact from the engine's side.
///
/// The re-keying makes that guarantee FINER rather than different: a title and a body of one
/// declaration are now two corpora, so writing one cannot move the other's scores either.
///
/// The same class exists one engine over — a Lance table inside a shared instance is the same wrong
/// write — so the brand is engine-kind-agnostic and the vector face wears it identically.
///
/// # It PROPAGATES the pairing; it does not PROVE it
///
/// This is the honest sentence and it is the whole contract. [`mint`](Self::mint) is where a lie can
/// enter: nothing in the type system checks that the engine handed to `mint::<_, Transcript>` was
/// opened on `Transcript::SLOT`. What the brand buys is that the fact, once stated, TRAVELS — every
/// site downstream of the mint carries the declaration in its type, so a handle cannot be quietly
/// swapped for another slot's on the way to a write or a read.
///
/// That makes the mint the one place to audit, and production has exactly ONE: the launch walk that
/// opens `options[T::SLOT]`'s path. Tests hand-mint deliberately, which is what lets a fixture
/// build the wrong pairing on purpose and prove it is refused.
///
/// A runtime slot-name assertion is NOT replaced by this and may later join INSIDE `mint` as
/// belt-and-braces — brand against directory — which is a launch-round detail rather than a
/// substitute.
///
/// # It adds ZERO impl rows, which is why it resurrects no wall
///
/// A′'s walls were the per-(record × engine) IMPL FAMILIES an R-generic engine trait forced: the
/// `E0117` orphan wall on a key trait over foreign types, and the `trivial_bounds` `E0277` an
/// expansion could not satisfy. This is a STRUCT, not a trait: engines stay R-free, a key's
/// [`Field`](super::Field) row names no engine at all, and nothing anywhere gains an impl per
/// declaration. A brand is a fact carried through the types, and carrying costs no rows.
///
/// # `PhantomData<fn() -> T>` and not `PhantomData<T>`
///
/// The marker must not make the handle's own auto-traits depend on the declaration. `PhantomData<T>`
/// would make `SlotHandle<E, T>: Send` require `T: Send`, so a declaration that is not `Send` would
/// silently cost the write seam its `+ Send` future — a bound arriving from a type that reaches no
/// byte here. The `fn() -> T` form is `Send + Sync` for every `T`, so the handle's auto-traits are
/// exactly the engine's, and it stays covariant in `T`, which is what a marker should be.
///
/// `T: ?Sized`, because a declaration is only ever NAMED here.
/// Cloning PRESERVES the brand — `T` is unchanged — so it costs the guarantee nothing and it is what
/// a second concurrent reader takes. The bound is on `E` alone, the marker being `Copy` for every
/// `T`.
/// The BRANDED full-text WRITE door — where a declaration's own write crosses into its engine.
///
/// The verb is a thin forward to the engine's own, and the forwarding IS the mechanism: the
/// signature is where the declaration is named, so handing `T`'s write another declaration's handle
/// is `E0308` naming both. The engine seam itself is untouched and stays R-free.
///
/// It takes `&mut self`, which for a write is the act's own law — a keyed replace must not
/// interleave against its own slot.
///
/// # Why the door is TWO impl blocks per family
///
/// The verbs live on their FACES, and the two directions are two traits — so the bound that reaches
/// `upsert` is not the bound that reaches `search`, and a branded door written over one trait would
/// demand the other of every engine it brands. Two blocks is the division the seam already has,
/// carried here: an engine that only writes wears this door and never the read one.
///
/// The face named is the ASYNC one on every block, which is where every caller of these doors stands
/// today. The blocking pair is spellable at the face itself, and a branded blocking door is a
/// mode-selection question rather than a brand question.
///
/// # Why the two kinds' write verbs are spelled apart
///
/// `upsert_document` and [`upsert_vector`](Self::upsert_vector) name their engine kind because two
/// inherent methods of ONE name on one type are `E0592` — duplicate definitions — regardless of the
/// bounds their impl blocks carry, and an engine implementing BOTH faces is perfectly legal. The
/// read verbs need no such care: `search` and `knn` were already two words.
/// The BRANDED full-text READ door — the search, over the face that answers it.
///
/// `&mut self` here is the seam's rather than the act's, the emitted retrieve being spelled
/// `&mut SlotHandle<E, Self>`; a caller wanting two concurrent reads clones the handle, which
/// preserves the brand.
/// The BRANDED vector WRITE door — the same stroke on the other engine kind, for the same reason: a
/// Lance table inside a shared instance is the same wrong-write corpus class as a Tantivy index
/// inside a shared root.
///
/// Two blocks per family, for the reason [`upsert_document`](Self::upsert_document)'s door states.
/// The BRANDED vector READ door — [`knn`](Self::knn) and the by-key read, over the face that
/// answers them.