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
//! [`Ranked`] — what a retrieve hands back: the score the engine gave it, where in the engine's raw
//! stream it stood, and the thing itself.
/// One retrieved result: its score, its rank, and what was retrieved.
///
/// # The three fields, and why the order is the one it is
///
/// `score` is written first because it is the more important of the two numbers. It is the
/// instrument the caller calibrates the MANDATORY floor with — a query cannot be asked without one,
/// and a floor is a number in the engine's own currency, so a caller that cannot see the scores it
/// got back has no way to learn which floor its corpus wants. Field order changes nothing a compiler
/// checks; it records the priority where a reader meets it.
///
/// `rank` is the hit's **1-based position in the engine's RAW hit stream**, and it is NOT the
/// position of this item in the returned list. The two disagree wherever the pipeline dropped a hit
/// — a duplicate key, a row the filter pruned, a row the store no longer has — and the holes are
/// left exactly where they fell. Re-densifying them would throw away the one number a caller can
/// continue from: re-issue the same query with a wider budget, drop everything at or below the last
/// rank seen, and the tail is the continuation. That is what v1 offers instead of a cursor, and it
/// works only while the number means *where the engine put it*.
///
/// `node` is the thing: the KEY at tier A, and the WHOLE upstream domain entity at tier B.
///
/// # `S` is the engine's own currency, and nothing here defaults it
///
/// The score arrives at the type the store face declared — BM25's `f32`, a cosine face's distance,
/// a fused shape — untranslated. [`Scored`](crate::Scored) states the whole argument for the
/// parameter one layer down, and this type is the same fact carried up: two ranked lists at
/// different `S` do not merge, and making them merge is a conversion somebody writes.
///
/// # The accessors are [`Scored`](crate::Scored)'s, plus the number
///
/// The borrow always, the copy in addition behind a `Copy` gate written on the METHOD rather than
/// on the parameter — so a `String` key or a composite fused score is stored, borrowed and
/// decomposed exactly as an `f32` is, and the only thing it declines is being handed back by value
/// for free. [`rank`](Self::rank) takes no gate at all, being a `u64`.