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
//! THE FOLD: N root-projected member lists in, one ranked fused list out.
use Reverse;
use ;
/// Fuse the members' lists into one ranked answer.
///
/// # The arithmetic, and the only two numbers it reads
///
/// Each member contributes `1 / (k + rank)` to every root it ranked, and a root's fused score is the
/// SUM of those contributions. `rank` is that member's ENGINE ordinal for the hit and `k` is
/// [`Fusion::Rrf`]'s damping constant; no score of any member enters, which is the property that
/// lets members whose currencies have never been compared be fused at all.
///
/// # The pipeline this is the end of
///
/// ```text
/// each member: engine → floor → dedup → rank → root-project → Vec<Rooted<R, V>>
/// then: fuse(those, fusion) → Vec<Fused<R, V>>
/// ```
///
/// The floor is the ONE semantic gate and it has already run: what arrives here is the survivors,
/// all of them, bounded per member only by the safety ceiling. So this function prunes NOTHING — a
/// root ranked by a single member at a poor ordinal still comes back, ranked below everything more
/// agreed upon, and *raise the floor* is what a caller who wants fewer results does.
///
/// # A member is counted ONCE per root, and the first sighting is the one counted
///
/// A member's list is meant to arrive collapsed at the root grain, so this is the case that should
/// not occur — and where it does, the second sighting is DROPPED WHOLE rather than added. Two
/// reasons, and the first is a defect the addition would create: a member that returned six segments
/// of one video would out-contribute genuine agreement between two members about a different video,
/// and the fused ranking would be measuring transcript density instead of relevance.
///
/// The second is that the drop makes this fold agree with itself across the grain. Root-projecting a
/// SELF-grain list produces exactly those repeats, and dropping all but the first keeps the best
/// segment per root — which is what the root grain would have handed over in the first place, since
/// a descending stream's first sighting is its best. *First occurrence wins* is the dedup stage's own
/// ruled law, applied where the same shape recurs.
///
/// # Ties keep the order they arrived in
///
/// No ruling sets a tie law, and the sort is STABLE, so roots with equal fused scores come back in
/// FIRST-SIGHTING order: the root some member ranked earliest, reading the member lists in the order
/// they were passed. That is deterministic and it is arbitrary, in that order of importance — it is
/// recorded here so a client does not read meaning into it.
///
/// The same stability orders the evidence: two members that contributed equally appear in the order
/// their lists were passed.
///
/// # `J` is the join's mechanism, and it is the LAST parameter for a measured reason
///
/// [`ranked_keys`](crate::ranked_keys) spells its dedup mechanism last and is called
/// `ranked_keys::<_, _, D>(…)`; this mirrors it. What forces the member lists to be `Vec`s rather
/// than `impl IntoIterator` is the same mirroring: a partial turbofish is **`E0107`** — *function
/// takes 5 generic arguments but 3 generic arguments were supplied* — so iterator generics for the
/// two collection layers would have made every call site spell `fuse::<_, _, HashJoin<_>, _, _>`.
/// The lists are built by a `map().collect()` at the projection anyway, so the concrete shape costs
/// the caller nothing it was not already holding.
/// [`fuse`] with a WEIGHT on every member — the edge fact [`Route::weight`] carries, spent.
///
/// # It is the same fold and not a second one
///
/// A member's term becomes `w / (k + rank)`, and everything else is unchanged: no score of any
/// member enters, the ordinal is still the engine's raw one, a member is still counted once per
/// root, and the sort is still stable. At `w = 1` for every member this IS [`fuse`], which is why
/// that function delegates rather than repeating the walk — one arithmetic, one place.
///
/// # The weight rides the MEMBER and not the hit
///
/// A route's weight is what a PARENT believes about that route, so it multiplies every term the
/// route contributes and nothing about which terms those are. A per-hit weight would be a score,
/// and scores do not fuse.
///
/// # The evidence CARRIES the weighted contribution, and is ordered by it
///
/// [`Fused::evidence`] is ordered by contribution, and the contribution a member actually made is
/// the weighted one — so a heavily-weighted member that ranked a root third can lead the evidence
/// over a barely-weighted one that ranked it first, which is what the weight was set to mean.
///
/// The number is KEPT rather than dropped after the sort (#296-L2): each entry is a
/// [`Sighting`](super::Sighting) holding it beside the member's own evidence. The fold already had
/// it in a local — carrying is not computing anything new, and it is the only thing that lets a
/// reader tell a nose from a mile.
///
/// The RANK it was computed from is kept with it (#296-L3). This walk destructures `rank` out of
/// every hit and used to drop it the moment the term was multiplied; the term alone cannot be run
/// backwards — `w / (k + rank)` is two unknowns in one equation and the weight never crosses the
/// wire — so the input to RRF is carried rather than left to be inferred from an output.
/// One member's RRF term for a hit at `rank`, damped by `k`.
///
/// # The denominator floor, and the one input it exists for
///
/// `rank` is the 1-based engine ordinal, so `k + rank` is at least 1 for every input the pipeline
/// produces and the clamp is never reached. It covers the one value that is not an ordinal — a `0`
/// handed in by a caller who passed a list POSITION instead — for which the division would be an
/// infinity, and an infinity in a sum is a root that outranks everything for a reason that is not
/// about the corpus. Clamped and finite is the answer that stays diagnosable.
///
/// `saturating_add` for the other end: `k + rank` cannot wrap into a small denominator and turn the
/// worst hit in a stream into the best one in the answer.