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
//! [`Scored`] — what a searching store hands back: the thing it matched, and the score it matched
//! at.
//!
//! At the seam layer rather than inside a family, for the reason [`Connected`](super::Connected) is
//! one file over: it belongs to no single engine. `Connected` is the shape every op RECEIVES, and
//! this is the shape every SEARCH returns — [`VectorRead::knn`](super::VectorRead::knn) and
//! [`FulltextRead::search`](super::FulltextRead::search), because both answer with a KEY rather than
//! with the row it addresses. One type for both is what keeps them from being two that must agree
//! and are free to stop.
/// One search result: what matched, and the score it matched at.
///
/// A named type rather than a `(D, S)`, so a reader takes [`data_ref`](Self::data_ref) and
/// [`score_ref`](Self::score_ref) instead of remembering which half of a pair is which. The tuple
/// is still reachable, at the one point it costs nothing to be one:
/// [`into_components`](Self::into_components), where the hit is being taken apart anyway.
///
/// # The score's SHAPE is a parameter, and NOTHING defaults it
///
/// Every scoring node answers in its own currency: a cosine or L2 DISTANCE (lower is closer), an
/// inner product, a BM25 relevance (unbounded above), a fused rank. `S` has no default, so the
/// currency is SPELLED by whoever produces the hit — a seam names it as an associated type and a
/// backend fills that in with what its engine measures in.
///
/// The default that is not here would have been `f32`, and what it bought is the reason there is
/// none: a signature reading `Vec<Scored<R::Key>>` reads NEUTRAL over the whole family while
/// pinning one engine's arithmetic. `f32` is BM25's shape and the shape a cosine face reports in;
/// it is not the shape a quantised backend, a fused rank or a posterior arrives in, and the first
/// member to answer in another one would have had to move every signature that had been reading as
/// though it did not care. A parameter spelled at every site is the same fact with nowhere left for
/// it to hide.
///
/// Spelling `Scored<D, Score>` is the MARKED form. [`Score`](crate::Score) IS the closed unit
/// interval, so writing it is a claim that something normalised the value, made at the place the
/// normalising happened rather than assumed by a later reader of an `f32`.
///
/// The dividend lands at the layer above: two hit lists at different `S` do not merge, and making
/// them merge is a conversion somebody writes down. Normalisation stops being an undocumented
/// convention about what an `f32` means here and becomes an act with a type.
///
/// # `D` is what matched, which is not always a key
///
/// An index answers with ADDRESSES, which is why [`VectorRead::knn`](super::VectorRead::knn)
/// returns `Scored<Self::Address, Self::Score>` — identity and score, never the payload. A fusion
/// layer ranks
/// whatever it is holding, hydrated records included, so the field is the DATA and
/// `Scored<Record, S>` is spellable without a second type being born to say it.
///
/// # No bound on either parameter
///
/// Ordering is not a property of a hit. It is what a sort or a merge asks for, so the
/// `PartialOrd`-class bound belongs at that call site, spent by the body that needs it — and no
/// such site exists yet.
///
/// # The accessors are the emitted pair, under this type's own names
///
/// A generated column is handed out as `x_ref(&self) -> &T`, with `x(&self) -> T` beside it where
/// the column is `copy` — the borrow always, the copy in addition. Both halves here follow it:
/// [`data_ref`](Self::data_ref) and [`score_ref`](Self::score_ref) are always there, and
/// [`data`](Self::data) and [`score`](Self::score) sit beside them behind a `Copy` gate written on
/// the METHOD.
///
/// On the method rather than on the parameter, which is what keeps a shape that cannot be copied
/// from being locked out of the type: a `String` key or a composite fused score is stored, borrowed
/// and decomposed exactly as an `f32` is, and the only thing it refuses is being handed back by
/// value for free — `E0277` at that call and nowhere else. Binding `Copy` on `D` or `S` would have
/// made the whole type unavailable to them to spare two methods.
/// A search's whole answer: its hits, ordered as the engine ranked them.
///
/// Named rather than spelled `Vec<Scored<D, S>>` at each seam that returns one, which
/// `clippy::type_complexity` refuses inside an RPITIT `Result`. It abbreviates nothing — both
/// parameters ride through it, so the score's currency is as visible at a seam as it is here.
pub type Hits<D, S> = ;