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
//! **`k` IS A CEILING AND NOT AN ALLOCATION HINT** — the seam's law, observed on the engine that is
//! its reference discipline.
//!
//! The law is stated on both engine verbs' `k` docs, and a sentence on a trait binds nobody by
//! itself. What binds this backend is the clamp in `search_slot`: `min(k, num_docs)`,
//! answer-preserving by construction, because a search cannot return more hits than there are live
//! documents. This file is the clamp's own proof.
//!
//! # The number is not hypothetical
//!
//! `NonZeroUsize::MAX` is what the emitted tier-B door asks its own tier A with, and it means *as
//! many as exist* — the fill loop's filter is what decides how many of them fill a page. So an
//! engine that sized a collector by `k` would abort on an ordinary door call rather than on an
//! exotic one: tantivy's `TopNComputer` allocates `k.max(1) * 2` up front, and that multiply
//! overflows long before it allocates.
//!
//! Sibling to [`tests`](super) rather than inside it, on the one-file-per-thing-proved precedent:
//! what is proved here is a DISCIPLINE, and it is the only thing in this backend's suite that would
//! fail by aborting rather than by answering wrongly.
use *;
/// Everything that exists — the honest unbounded ask, in the door family's own currency.
const EVERYTHING: NonZeroUsize = MAX;
/// **AN UNBOUNDED `k` ANSWERS** rather than aborting, and it answers the same hits a small one does.
///
/// Both halves are the claim. Answering at all is the clamp doing its job; answering the SAME thing
/// is what *answer-preserving by construction* means — a ceiling above the corpus removes only
/// capacity that could never have been filled, so the result is the corpus's own and not a truncated
/// view of it.
///
/// MUTATION-CHECKED: hand `TopDocs::with_limit` the raw `k.get()` and this aborts inside tantivy
/// where no caller can catch it — *attempt to multiply with overflow*, at `TopNComputer`'s own
/// `n.max(1) * 2`.
/// **AN EMPTY SLOT STILL RUNS THE QUERY** under the same unbounded ask — the clamp's own floor.
///
/// `min(k, num_docs)` is zero on a never-written corpus and `with_limit` asserts on zero, so the
/// clamp carries a `.max(1)`. What it buys is that *no hits* is an ANSWER here rather than a panic,
/// which is the only honest result for a slot nobody has written to yet.
///
/// MUTATION-CHECKED, and it fires on THIS test alone: drop the `.max(1)` and only this one reds —
/// *Limit must be greater than 0*, tantivy's own assertion — while the test above stays green. The
/// two halves of the clamp are therefore two claims, each with its own pin.