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
//! The two shapes the fold moves between: [`Rooted`] going in, [`Fused`] coming out.
use ;
/// ONE member's answer about ONE root: where that member put it, and what that member saw.
///
/// This is what a member's ranked list becomes on the way into [`fuse`](super::fuse), and the
/// projection is the EMISSION's act rather than this type's — a key's root is its own root-first
/// prefix, and only the code that can see the key's shape can take it.
///
/// # Three members, and the fold reads two of them
///
/// `root` is what the join happens at. `rank` is the ENGINE ordinal the member's survivor wore, and
/// it is the whole of the fold's arithmetic. `evidence` the fold never opens: it carries it to the
/// [`Fused`] that comes out, ordered by how much it contributed, and asks NOTHING of the type.
///
/// # Why `evidence` is a parameter and not a read through a trait
///
/// The alternative was a trait the emitted evidence enum implements, so the fold could read the rank
/// back out of it. It buys one fewer field and costs every emitted enum an impl — and the rank it
/// would read is a number the caller is holding anyway at the moment it builds this. A bound that
/// recovers what the call site already has is a bound with nothing behind it.
///
/// # The rank is the RAW ordinal, and passing the list position instead is a silent defect
///
/// [`Ranked::rank`](crate::Ranked::rank) is the number, not `position()` in the survivor list. The
/// two agree exactly when nothing was dropped, so a call site that passes the wrong one produces a
/// perfectly ordered answer on every fixture whose floor let everything through — which is why the
/// distinction is written here, where the number is taken.
/// One row of a fused answer: the framework's score, the root it is about, and every member's
/// evidence for it.
///
/// # `R` is the root at two tiers, exactly as [`Ranked`](crate::Ranked)'s node is
///
/// The root KEY where the caller asked for keys, and the whole hydrated root ENTITY where it asked
/// for entities — the second reached through the same address lanes tier B already walks. One
/// parameter covers both because the fold never looks at it beyond joining on it.
///
/// # `V` is the EMITTED evidence, and it is a parameter because it has to be
///
/// The ruling spells this type `Fused<R>` and, in the same clause, names the evidence as *the
/// EMITTED per-root evidence enum (variant per member, carrying that member's `Ranked<Key, Score>`)*
/// — a type minted per graph root, since its variants ARE that root's member table. A framework
/// struct cannot hold a type the emission mints, so the two halves of that clause are simultaneously
/// satisfiable only with the evidence as a second parameter. The emission instantiates
/// `Fused<MediaKey, MediaEvidence>` and the ruled shape is what a reader of the emitted signature
/// sees.
///
/// # `evidence` is a LIST, and its order is the ruling's
///
/// One entry per member that ranked this root — never per member in the catalog, since a member that
/// did not rank it has nothing to say — ordered by CONTRIBUTION DESCENDING. That is the UI's primary
/// jump point first: the entry at index 0 is the member whose ranking moved this root the most, and
/// it is the one to open when a user clicks the result.
///
/// # THE CONTRIBUTION IS CARRIED, and carrying it is merely not stripping it
///
/// The entry is a [`Sighting`] — the member's own evidence beside the WEIGHTED term it added to the
/// score above. Until the #296-L2 ruling the list was a bare `Vec<V>` and this note argued the other
/// way: the number was `1 / (k + rank)`, the rank rode inside the member's own `Ranked`, so a client
/// computed it and a stored copy was a second version that could disagree.
///
/// The wire road ended that argument. A client reading a union variant has no `k`, no weight and no
/// local to recompute from, and the order alone cannot say whether the leading entry led by a nose
/// or by a mile. And the disagreement clause does not survive the carry: a number taken FROM the
/// fold cannot disagree with the fold, because it IS the fold's — what could disagree was the
/// recomputation.