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
//! [`Connected`] — the per-call resource bundle every store-handle op receives: a borrow of the
//! shared connection-manager (the `*Store` that was opened once) plus the per-call scope. ONE
//! lifetime by design — see the type doc.
/// The per-call resources a store handle operates against: a borrow of the shared `Connection` (the
/// connection-manager a `*Store` opened once and now hands to every op, so nothing reconnects per
/// call) plus the per-call `scope` — owned here, being whatever the handle's `ReadContext<'_>` /
/// `WriteContext<'_>` GAT resolved to (search knobs, or a borrowed `&mut Transaction`).
///
/// ONE lifetime: `'a` is the connection borrow. Any borrow the scope itself needs rides a lifetime
/// baked INSIDE `X` (the `WriteContext<'s>` / `ReadContext<'s>` GAT), so the scope's borrow is
/// already decoupled from `'a` — a second wrapper lifetime is provably redundant. `C: ?Sized` so an
/// unsized / `dyn` manager can still be borrowed.
/// Written rather than derived, because `#[derive(Clone)]` would bound `C: Clone` — and the
/// connection is BORROWED here, so a shared manager that is not cloneable (which is most of them: a
/// pool, an open index, a cached table set) would lose the impl for a bound nothing spends.
///
/// # What a clone IS, and why the bound sits on the SCOPE alone
///
/// A copy of the connection borrow beside a clone of the per-call scope. That is the whole of it,
/// and it exists for ONE caller: the multi-vector road runs the engine once per query vector, and
/// [`VectorRead::knn`](crate::VectorRead::knn) takes its scope BY VALUE — so `m` calls need `m`
/// scopes, and cloning the knobs is the honest way to get them. Read knobs are what a scope holds on
/// that path (`k`, a probe count, a metric, a prefilter), and they are per-call by nature.
///
/// A read scope that must NOT be duplicated — a lease with an identity, a cursor — simply does not
/// implement [`Clone`], and its engine is then absent from the set road at COMPILE time rather than
/// misused at run time. That is the seam doing its job: the capability is asked for where it is
/// spent, and an engine answers by having it or not having it.