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
//! The write lane: what a LANDING node's own write is, and what one write says about the items it
//! was given.
//!
//! The seam is [`AsyncLands`], and it is deliberately the smallest thing the loop needs — *take these
//! items, tell me which of them reached the store*. Nothing about keys, tables, transactions or
//! backends crosses it: which key a record replaces is the LANE's business, and a lane is what an
//! emission fills in, so this layer never has to name an app's content to make a write durable.
//!
//! # Why the answer is per item
//!
//! One delivery is one write, because a page of 256 rows written as 256 statements is 256 round
//! trips where a store already offers one. A batch that goes as one node can still land as several:
//! a row that violates a constraint, an object whose address is too long, a document one shard
//! refuses. So the answer is a [`Commit`] — a POSITIVE set of positions, exactly as
//! [`Ack::released`](super::Ack) is a positive set of keys, and for the same reason: what a lane
//! does not name stays held, so a lane that reports nothing costs a re-delivery and never a loss.
//!
//! POSITIONS and not keys. The socket hands the lane a slice and reads the answer back against
//! that slice, so the pairing is the delivery's own order and nothing in this layer has to be able
//! to name what a record IS.
//!
//! # Why the seam is async and both engines still drive it
//!
//! Every store face this crate carries — [`AsyncBlobEngine::put`](crate::AsyncBlobEngine),
//! [`VectorEngine`](crate::VectorEngine) — hands back a future, so a lane that wraps one is async
//! whether or not this seam is. Making the
//! seam synchronous would move that fact nowhere: it would put a block inside every lane instead of
//! inside the one engine that needs it.
//!
//! So the seam is async, and the thread engine drives it with [`block_on`] — which is a DRIVER and
//! not a runtime. A resident thread already blocks in `park` and blocks for room on a full edge;
//! blocking it on its own write is the same posture rather than a new one.
use ;
use ;
/// What ONE [`AsyncLands::land`] call did: which of the items it was given reached the store, and —
/// where some did not — why.
///
/// The two constructors that report less than everything both REQUIRE the refusal, and that is the
/// seam's one demand on a lane: an item that is not committed holds the input it descends from, so
/// something has to be able to say what happened, and the alternative is a delivery that stalls with
/// nothing written down.
/// The committed set, as a shape rather than as a set.
///
/// [`All`](Self::All) is the ordinary answer and carries no allocation: a lane that took the whole
/// batch says so in a word, and a page of 256 costs nothing to report.
/// A delivery's write did not commit everything it staged.
///
/// It is the framework's own wrapping of a lane's refusal and it exists to carry the COUNT, which
/// the lane cannot state: the lane knows why one write failed, and the socket is what knows that six
/// of two hundred and fifty-six are held. The lane's own error is kept as the
/// [`source`](core::error::Error::source) rather than rendered into a string, so a tap that knows
/// the concrete type can still walk to it.
/// A node's own write — the socket a landing consumer's durability comes through.
///
/// A [`Resident`](super::Resident) with a lane answers each delivery's oneshot AFTER this call
/// returns, and releases exactly the input items whose writes committed. That ordering is the whole
/// reason the seam exists, and it is the channel half of the layer's one law: a position advances
/// only after the effect it covers is durable.
///
/// # What it does not ask for
///
/// No key, no table, no transaction, no backend. `land` receives the records themselves and answers
/// by POSITION, so the framework never names an app's content — the keyed replace that makes a
/// replay harmless is the lane's, written where the record's type is known. That is the same
/// division [`Skip::about`](crate::Skip::about) states one layer up.
///
/// # ONE WRITE, TWO LAYERS — and never two write verbs at one layer
///
/// This is the SOCKET and [`FulltextWrite::upsert`](crate::FulltextWrite::upsert) /
/// [`VectorWrite::upsert`](crate::VectorWrite::upsert) /
/// [`AsyncBlobEngine::put`](crate::AsyncBlobEngine::put) are
/// the ENGINES. They are not two vocabularies for one act and they are not alternatives: a LANE
/// implements this trait and CALLS an engine verb, and that composition is the only shape in which a
/// node's items reach a store. What each layer answers is what makes the pair irreducible — a socket
/// answers *which of these items are durable*, positionally, over a batch the framework handed it;
/// an engine answers *this entry is written*, over one entry whose identity the emission decided.
/// Neither can be derived from the other, and adding an item verb to an engine or an entry verb here
/// would be the duplication this arrangement exists to refuse.
///
/// **The framework ships no lane, and that is measured rather than an omission.** A generic
/// `FulltextLane<E: FulltextEngine>` cannot be written: `land` takes `&mut self` and writes N items
/// through one write scope, so it must REBORROW `E::WriteContext<'_>` per item — and a GAT
/// projection over an unknown backend has no reborrow. The shipped backend's scope is
/// `&mut SlotWriter` and reborrows as `&mut *writer`; another backend's may be an owned lease, a
/// token, a `Copy` handle. Nothing generic covers the three. So a lane is written where the write
/// scope is CONCRETE, which is the same place the record's type is known and the same place the
/// flatten into the engine's entry lives — one author for the whole crossing. `store::tantivy`'s
/// tests build one end to end.
///
/// **For a SQL backend that concrete scope is a POOL, and the shape is measured rather than
/// preferred**: the lane holds a `&Pool` — the one form an HRTB measurement over sqlx's `Acquire`
/// passed — and acquires PER LAND, the pool reaching it as a shared resource the launch built rather
/// than as a connection this layer hands over. None of it is written here, for the paragraph above's
/// reason; it is recorded so that the first lane written against a pool is written the way the
/// measurement passed.
///
/// The name is the one thing here still open: see the pull request's rename-candidates section.
///
/// # `&mut self`
///
/// [`Positions`](super::Positions)' reason, and it is the same resource: a lane that matters holds a
/// connection, and a keyed replace over a batch is not atomic across two callers. Taking the
/// exclusive borrow makes that serialisation the compiler's rather than a comment, and it costs
/// nothing — a lane belongs to exactly one resident.
///
/// The future is `Send` because a resident is a task on somebody's runtime, and it is spelled as
/// `impl Future + Send` rather than as `async fn` so the bound is part of the contract instead of
/// something each caller has to hope for.
/// [`AsyncLands`]' BLOCKING twin — the write socket a sync body reaches for.
///
/// # It is a FACE of an engine, not a lesser lane
///
/// A `block`, `spawn` or `rayon` poll entry runs a body that has no `.await` to spend, so a store it
/// writes through has to answer without one. Whether a given store CAN is the deployment engine's
/// own fact and nothing about it is decidable from a declaration: a tantivy index writes through an
/// `IndexWriter` and answers here; an sqlx pool is async to its bottom and answers only through
/// [`AsyncLands`]. So the legality of *sync body writes to this store* is settled at the TYPE layer, at
/// the line that reached, and the grammar refuses nothing — which is why the emitted grants contexts
/// forward BOTH families and each forward is conditional on the handle's own impl.
///
/// # The method keeps the bare name
///
/// `land` on both faces, measured rather than assumed: a body that imports one trait calls `land`
/// with no ceremony, and a body that imports BOTH and calls `land` on a handle implementing both is
/// `E0034` — *multiple applicable items in scope* — naming the two candidates and offering the
/// disambiguating spelling. That refusal is a good one: it arises only where a deployment genuinely
/// has two roads to one store and the body has not said which it is on, and it names both. A
/// suffixed second name (`land_blocking`) would buy silence at that one site and charge every other
/// site a word that says nothing the trait's own name does not.
///
/// # `&mut self`
///
/// [`AsyncLands`]' reason verbatim, and it is the same resource: a keyed replace over a batch is not
/// atomic across two callers, so the exclusive borrow is what serialises it.
/// The unused lane, blocking face — [`AsyncLands for ()`](AsyncLands)' twin, and the same absence of a claim.
/// The unused lane — what a resident that declared none carries.
///
/// It is [`AsyncBlobEngine for ()`](crate::AsyncBlobEngine)'s face, one layer up and for the same reason: a resident
/// is generic over its lane, and the absence of one has to be a type. It commits everything, which
/// is not a claim about durability but the absence of a claim — a node with no lane never stages
/// anything through this seam that its own body did not already handle, and what makes its answer
/// true is [`Effect`](super::Effect) rather than this call.
/// Drive `future` to completion on THIS thread — the thread engine's half of a write.
///
/// The two engines already differ in how they park and how they wait for room; a write is the third
/// difference, and this is the thread side of it. It is a DRIVER and not a runtime: one future, no
/// timer, no spawn, no reactor and no dependency — `std::task::Wake` makes the waker and
/// `std::thread::park` is the wait, so an idle poll costs nothing and a wake from another thread is
/// what resumes it.
///
/// The park/unpark race is std's to answer and it does: an `unpark` that arrives before the `park`
/// leaves a token, so the wait returns at once rather than sleeping through its own wake.
pub
/// [`block_on`] with a `deadline` — the same driver, giving up where the caller said to.
///
/// `None` is the expiry. It is what the THREAD engine's PARK spends: a resident's sweep is a
/// timeout, and a node with SEVERAL sources waits in a select that only a future can express, so
/// the deadline has to live in the driver rather than inside a receive call. See
/// [`park_on`](crate::conduit::park_on), which is this with the caller's sweep and is where the
/// public face of the same driver lives.
///
/// The unfinished future is DROPPED at the deadline, and that loses nothing: a receive future that
/// goes away deregisters its waker and passes the wake on, while the message it was waiting for is
/// in the channel's own queue rather than in the future, so the next park sees it.
pub