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
//! THE BY-KEY VOCABULARY — what the emitted `get_<field>` and `retrieve_similar_by_<field>` doors
//! report when the KEY's own stored vector is the problem.
//!
//! `get_<field>` reads that vector back through [`VectorRead::get`](crate::VectorRead::get) and
//! checks it against what the declaration says it is. `retrieve_similar_by_<field>` is sugar over
//! the raw pair and adds no query machine: it takes its example FROM that door, hands it to the
//! same `knn` the raw door calls, and excludes the example from the answer.
//!
//! What both can say that the raw pair cannot is that the key's own vector was unusable — and those
//! refusals are here, because none of them is an engine failure and answering an empty page for any
//! of them would be indistinguishable from *nothing was near enough*.
//!
//! # ONE type for TWO doors, and that is the delegation's own requirement
//!
//! The three judgments are made in `get_<field>` and reported by both doors. A second vocabulary
//! for the second door would mean translating one into the other at the delegation — and a
//! re-worded refusal is a refusal a caller cannot match against the original, which is the whole
//! failure a shared type removes.
//!
//! # The file is still called `similar`, and the type is not
//!
//! What else lives here is [`tests`] — half of which is about `ranked_keys_excluding`, the
//! EXCLUSION, which belongs to the similar door and to nothing else. The type moved to a name that
//! covers both doors; the module kept the name that covers what it holds.
use fmt;
/// What an OWN READ reports: the engine refused, or the entity's own stored vector did.
///
/// The *own read* is the act both by-key doors begin with — `get_<field>` IS it, and
/// `retrieve_similar_by_<field>` reaches its example through that door — so the name is the act
/// rather than either caller. The shape is the family's: one type for the whole call, arms for the
/// things that are not the engine's fault, and the engine's own error carried whole rather than
/// translated.
///
/// # The three non-engine arms are all *the stored vector is not what the declaration says it is*
///
/// An own read has an input the caller never supplies: the vector the engine holds for that key.
/// Every arm below is a way that vector failed to be one, and each is NAMED rather than answered
/// with an empty page — because an empty page already means *nothing cleared the floor*, and a door
/// with two silent meanings for one answer is a door whose caller cannot debug it.
///
/// # ONE type for TWO doors, and the delegation is why
///
/// `get_<field>` makes all three findings; `retrieve_similar_by_<field>` reports them without
/// touching them. A second vocabulary for the second door would mean translating one into the other
/// at the delegation, and a re-worded refusal is one a caller cannot match against the original.
/// Every sentence below is therefore written about what was FOUND rather than about what the caller
/// wanted it for.