Name the module that answers a refused store call, not the issue that asked for it

[iderex]

The issue this belongs to

Closes #487

What changed

StorageUnavailable in src/cache/mod.rs stops handing the core's answer to a
refused store call to #42. It names crate::cache::bound as the module holding
it and says what the answer is: a write the store refused is Cached::NotKept,
the call that caused the write does not fail for it, and a run of refusals
suspends writing for a stated interval. A second paragraph records what the
sentence said and which of the two states it was in, in the shape the paragraph
directly below it already uses for its own repair.

Nothing else moves. No behaviour, signature, variant, bound or event.

What failure it prevents

It is wrong in the direction that reads as covered. Somebody reading the one
failure a client's byte store may report is there to find out what the core does
when their implementation returns it, and the answer they got was an issue that
closed as completed on 2026-08-27. The header of the same file says that issue
landed and names writing suspended on a full device among what landed with it, so
one document held both halves and a reader came away with opposite answers
depending on which half they read.

The sentence landed on 2026-08-26, #42 closed the next day, and
src/cache/bound.rs landed two hours after that carrying the answer and
correcting the module header's own half of the same claim. That change had no
reason to open the type's documentation a hundred lines below, so this one went
stale rather than landing refuted.

It was found by reading every issue number this tree names outside
docs/decisions/ against the state of that issue on the tracker.

The means

Doc comments in the Rust source that carries the claim, which is the only means
that puts the correction where the sentence a reader meets is. A record under
docs/decisions/ would leave the false sentence standing in the file somebody
opens to find the answer. No language, runtime or dependency is added, and the
suites that already exist judge the result, because cargo doc resolves the two
links the change adds.

Evidence

The commit being pushed:

git rev-parse HEAD
85d10f660ea025f0d697e22bdc3606d823e3ec06

What the paragraph said, at the parent:

git show 85d10f6^:src/cache/mod.rs | sed -n '123,128p'
/// The one failure a byte store may report.
///
/// 0040 admits exactly one: a full device, a store the platform closed
/// underneath the core, a permission withdrawn while the application was in the
/// background. The core does not tell those apart, because its answer is the
/// same for all of them, and what that answer is belongs to #42.

What the header of the same file said, at the same parent:

git show 85d10f6^:src/cache/mod.rs | sed -n '21,30p'
//! THIS SECTION SAID NOTHING IN THIS TREE CACHES ANYTHING AND THAT THE BOUND AND
//! THE EVICTION WERE #42. The bounds and the eviction are in [`bound`], which is
//! #42 and #54 landed rather than pending, and a client that supplies a store
//! now gets bookkeeping over it: two tiers with their own bounds and their own
//! use orders so that neither can evict the other, bounds counted on bytes the
//! core counted, eviction of the least recently used entry in a tier before a
//! write that would exceed that tier's bound, a read in flight that eviction may
//! not reach, writing suspended rather than the core evicting its own entries
//! when the device is full, and artwork released so that a refused metadata
//! write can be attempted once more.

#42 is closed as completed:

gh issue view 42 --repo Flowfin/core --json number,state,closedAt,title --jq '"\(.number) \(.state) \(.closedAt) \(.title)"'
42 CLOSED 2026-08-27T00:15:11Z Bound the cache and decide what is evicted

The module the header names says a full device is #42's, and carries the answer
as a type in library code:

git show 85d10f6^:src/cache/bound.rs | sed -n '3,4p'
//! Two records and two issues. 0042 and #42 fix the bound, the eviction rule,
//! the read eviction may not reach, and what a full device does. 0054 and #54
git show 85d10f6^:src/cache/bound.rs | sed -n '341,349p'
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Cached {
    /// The bytes are in the store and the core is accounting for them.
    Kept,
    /// They are not. The store refused, or writing is suspended, or no entry in
    /// that tier could be evicted to make room. The cache is an accelerator and
    /// this is the accelerator declining, rather than anything failing.
    NotKept,
}

that a failed write does not fail its caller:

git show 85d10f6^:src/cache/bound.rs | sed -n '333,334p'
/// A FAILED WRITE NEVER FAILS THE CALL THAT CAUSED IT, which is 0040's sentence
/// and neither 0042 nor 0054 changes it. This is not an error type and there is

and the run of refusals that suspends writing:

git show 85d10f6^:src/cache/bound.rs | sed -n '83,86p'
/// How many consecutive refused writes it takes to suspend writing, from 0042.
///
/// Three, because one refusal is a transient and a run of them is a condition.
const REFUSALS_THAT_SUSPEND: u32 = 3;

The dates. The sentence is a day older than the issue closing, and the module
holding the answer is two hours younger than that:

git blame -L 128,128 --date=short 85d10f6^ -- src/cache/mod.rs | cat
6ce521d5 (Nils Lehnen 2026-08-26 128) /// same for all of them, and what that answer is belongs to #42.
git log --format='%h %cI %s' --diff-filter=A 85d10f6^ -- src/cache/bound.rs
19be153 2026-08-27T02:06:57+02:00 Bound the cache and evict the least recently used entry
git blame -L 22,23 --date=short 85d10f6^ -- src/cache/mod.rs | cat
4f227f3c (Nils Lehnen 2026-08-27 22) //! THE EVICTION WERE #42. The bounds and the eviction are in [`bound`], which is
4f227f3c (Nils Lehnen 2026-08-27 23) //! #42 and #54 landed rather than pending, and a client that supplies a store

What the paragraph says now:

git show HEAD:src/cache/mod.rs | sed -n '123,138p'
/// The one failure a byte store may report.
///
/// 0040 admits exactly one: a full device, a store the platform closed
/// underneath the core, a permission withdrawn while the application was in the
/// background. The core does not tell those apart, because its answer is the
/// same for all of them. That answer is in [`bound`]: a write the store refused
/// is [`bound::Cached::NotKept`], the call that caused the write does not fail
/// for it, and a run of refusals suspends writing for a stated interval.
///
/// THIS SENTENCE HANDED THAT ANSWER TO #42 AS A THING THAT WOULD ARRIVE. It
/// landed on 2026-08-26, #42 closed as completed the next day, and [`bound`]
/// landed two hours after that with the answer and with the correction of the
/// module header's own half of this. So the sentence went stale rather than
/// landing refuted, which is the milder of the two states and is worth saying in
/// those words. #487 is where it was found.
///

What the change is:

git diff --stat origin/main...HEAD
 src/cache/mod.rs | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)
git diff --name-only origin/main...HEAD
src/cache/mod.rs

The two commands the gate runs, at this commit. The build was run first and
exited 0; its own summary line is not pasted, because this board's hygiene check
reads the word in it as a speed claim:

cargo build --locked --all-targets ; echo "exit=$?"
exit=0
cargo test --locked ; echo "exit=$?"
exit=0
cargo test --locked 2>&1 | grep -c '^test result: ok'
10
cargo test --locked 2>&1 | grep -c 'test result: FAILED'
0

The two links the paragraph adds resolve, which the ordinary build does not
judge:

cargo doc --no-deps --locked ; echo "exit=$?"
exit=0

Four of this board's own legs, run on this machine at this commit:

bash .github/invariants/invariants.sh check | tail -1
Every rule above was applied to its subject and refused nothing.
bash .github/format/format.sh check | tail -1
Every tracked source file above is written the way the formatter would write it.
bash .github/doc-paths/doc-paths.sh check | tail -1
Every path these documents name resolves against the tracked set.
bash .github/lint/lint.sh check | tail -1
Every lint the groups above carry was refused, outside the register printed with it.

What this does not cover

• src/cache/bound.rs. It is read as evidence and not edited. It already
  says what holds.

• The header of src/cache/mod.rs. It is read as evidence and not edited. It
  is the half that was already correct.

• The paragraph below the one repaired. Its own correction about
  crate::failure::Failure::from_cache_store is read and left exactly as it is.

• The index that survives a restart. src/cache/bound.rs states in its own
  words that it writes none and that Decide what a cache written by another version, or half-written, is allowed to do #105 and Decide what creating and stopping the core means, including a host that suspends it #115 are where it arrives. Both are
  open and neither is touched.

• 0040, 0042 and 0054. The records are referred to and none is edited. A
  record is added or superseded rather than edited in place, which
  docs/decisions/0001-decision-records.md fixes.

• Every other reference to a closed issue in this directory. Only #42 at
  this one site is examined, and nothing is claimed about the rest in either
  direction.

• A check that would refuse this. Nothing in this tree reads a doc comment's
  hand-off against the state of the issue it names, and the document check reads
  only .md files. This adds no rule, so the next sentence of this shape is
  caught by a reader or not at all.

• The shell analysis. It was not run on this machine, because the analyser is
  not on this machine's path:

    command -v shellcheck ; echo "exit=$?"
    exit=1
  

  What the run on this pull request reports is the reading, and nothing is
  claimed for it from here. This change touches no shell file.

Who has read it

Nobody other than the author. There is no second reader on this board tonight,
and the readings pasted above stand in place of one rather than a review having
happened.