Say which events the cache emits, and stop the cache module denying the read it holds

[iderex]

The issue this belongs to

Closes #442

What changed

src/diagnostics/mod.rs's "Which events exist today" section stops answering
"None". It names the cache as the subsystem that emits, says what each of the
three events is emitted for, and hands the reader
git grep -n 'EventName::declared' -- src/ rather than a list, because a list in
this module goes stale against the modules that declare the names.

Its pointer at crate::session for the same sentence is deleted. Nothing of that
shape is in that module, so there is nothing to repair it against.

src/cache/mod.rs stops saying that nothing in this tree fetches bytes out of a
store and hands them anywhere. What is absent is a caller that DEMANDS freshness -
nothing here asks for an entry because it is about to show one to somebody - and
that is the reason the file now gives, with #27 as the transport that would
produce such a caller.

Each correction records what the sentence said, and whether it went stale or
landed refuted, because the two are different states.

What failure it prevents

Both errors run in the direction that makes the tree look emptier than it is, in
the two files a reader opens to ask what either subsystem does today.

A reader asking what the diagnostics interface looks like in practice met "None"
and went away with a shape and no worked example, two files away from three names
with their severities and their fields. The sentence sits directly above the rule
that an event name arrives with the issue that builds the subsystem emitting it,
so the emptiness read as evidence that no such issue had landed.

A reader asking whether the freshness half of #43 is closable met what reads as
an absent mechanism. The mechanism is present and used; the caller is what is
missing. Those are different gaps with different owners.

No negative disclosure is softened. Nothing in this tree runs a core to hand an
event to a sink a client supplied, which is #115 and 0100, and the demand for
freshness and every caller are still absent.

How it was found: a sweep of absence claims in files no check reads, run against
the tree, after #438 and #440 repaired the same class elsewhere under src/.

git grep -n "ls-files '\*\.md'" origin/main -- .github/doc-paths/doc-paths.sh
origin/main:.github/doc-paths/doc-paths.sh:440:  git ls-files '*.md'

Evidence

Readings at the parent commit, 368664219e3e320f630d041cbf7c3fbd65eff3cb, except
where a historical commit is named.

The two sentences as they stood:

git show 3686642:src/diagnostics/mod.rs | sed -n '33,37p'
//! # Which events exist today
//!
//! None. Nothing in this tree emits one, because no subsystem that would is
//! built. That is a statement about this tree rather than about the interface,
//! and the same sentence stands over [`crate::session`] for its own reason.
git show 3686642:src/cache/mod.rs | sed -n '36,40p'
//! still absent from that half is the demand for freshness and every caller.
//! THIS SENTENCE SAID THE DEMAND WAITS ON #37 FOR A FAILURE TO RETURN. That
//! landed; what it waits on now is a transport that can fail to reach a server,
//! which is #27. Nothing in this tree fetches bytes out of a store and hands
//! them anywhere.

Three events are declared:

git grep -n 'EventName::declared' 3686642 -- src/cache/
3686642:src/cache/bound.rs:105:const WRITING_SUSPENDED: EventName = EventName::declared("cache.writing-suspended");
3686642:src/cache/bound.rs:109:const ARTWORK_GAVE_WAY: EventName = EventName::declared("cache.artwork-gave-way");
3686642:src/cache/envelope.rs:174:const ENTRY_DROPPED: EventName = EventName::declared("cache.entry-dropped");

and four sites emit them:

git grep -n 'ARTWORK_GAVE_WAY\|WRITING_SUSPENDED\|ENTRY_DROPPED' 3686642 -- src/ | grep -v 'EventName::declared'
3686642:src/cache/bound.rs:668:            ARTWORK_GAVE_WAY,
3686642:src/cache/bound.rs:785:                WRITING_SUSPENDED,
3686642:src/cache/envelope.rs:420:                ENTRY_DROPPED,
3686642:src/cache/envelope.rs:430:                .emit(Severity::Notice, ENTRY_DROPPED, &[entry, entry_kind, check]);

None of the six is in a test module. Those begin below every one of them:

git show 3686642:src/cache/bound.rs | awk '/#\[cfg\(test\)\]/{print NR; exit}'
966
git show 3686642:src/cache/envelope.rs | awk '/#\[cfg\(test\)\]/{print NR; exit}'
463

The store is read and the bytes are handed on:

git show 3686642:src/cache/bound.rs | sed -n '510,513p'
    pub(crate) fn read(&self, tier: Tier, key: &EntryKey) -> Option<Vec<u8>> {
        let answer = {
            let _in_flight = ReadInFlight::started(self, key);
            self.store.read(key)
git show 3686642:src/cache/envelope.rs | sed -n '378,381p'
    pub fn read(&self, kind: EntryKind, key: &EntryKey) -> Option<Vec<u8>> {
        let held = self.cache.read(Tier::of(kind), key)?;
        match open(kind, &held) {
            Ok(payload) => Some(payload.to_vec()),

The pointer at crate::session resolves to nothing:

git grep -n 'exist today\|no subsystem' 3686642 -- src/session/

exits 1 and prints nothing, which is grep selecting nothing rather than an
error.

One went stale and one landed refuted:

git log 3686642 --format='%h %ad %s' --date=short -S'Nothing in this tree emits one' -- src/diagnostics/mod.rs
6933b04 2026-08-26 Give the core a way to say what happened, without giving it a voice
git log 3686642 --format='%h %ad %s' --date=short -S'WRITING_SUSPENDED' -- src/cache/bound.rs
19be153 2026-08-27 Bound the cache and evict the least recently used entry
git log 3686642 --format='%h %ad %s' --date=short -S'ENTRY_DROPPED' -- src/cache/envelope.rs
a8da1c3 2026-08-28 Wrap every cache entry in an envelope, and drop one that does not check out (#225)
git log 3686642 --format='%h %ad %s' --date=short -S'fetches bytes out of a store and hands' -- src/cache/mod.rs
7616f21 2026-08-28 Answer a cache read with the age that produced the state, on the anchor the server supplies (#221)
git log 3686642 --format='%h %ad %s' --date=short -S'self.store.read(key)' -- src/cache/bound.rs
19be153 2026-08-27 Bound the cache and evict the least recently used entry

The diff:

git diff --stat origin/main...HEAD
 src/cache/mod.rs       | 13 +++++++++++--
 src/diagnostics/mod.rs | 27 ++++++++++++++++++++++++---
 2 files changed, 35 insertions(+), 5 deletions(-)

Neither claim is left:

git grep -n 'Nothing in this tree emits one\|fetches bytes out of a store and hands' -- src/ ; echo "exit=$?"
exit=1

The runs at this commit:

cargo test --locked 2>&1 | grep -c '^test result: ok'
10
bash .github/format/format.sh check >/dev/null ; echo "exit=$?"
exit=0
bash .github/lint/lint.sh check >/dev/null ; echo "exit=$?"
exit=0
bash .github/doc-paths/doc-paths.sh check >/dev/null ; echo "exit=$?"
exit=0
bash .github/invariants/invariants.sh check >/dev/null ; echo "exit=$?"
exit=0

cargo build --locked --all-targets finishes without error at this commit,
cargo clippy --locked --all-targets -- -D warnings exits 0, and
cargo fmt --all -- --check exits 0. Ten result lines, all reading ok; a run
that collected nothing would print a result line too, which is what
.github/test/test.sh refuses on the gate, and that leg was not run here.

What a guard here refuses, and the proof it bites

No guard is added or edited. No event is added, renamed or removed. No type,
field, constant, assertion or test changes. The diff is two doc comments.

What this does not cover

• No event is added, renamed or removed, and no site emits anything new.
• Nothing hands an event to a client. A core that runs is Decide what creating and stopping the core means, including a host that suspends it #115 and the
  interface a client supplies a sink through is 0100, and neither is delivered
  here.
• The freshness demand stays absent. No caller is added, and what would
  produce one is Build the HTTP transport, with timeouts, connection reuse and cancellation #27.
• No check would catch the next one. Nothing in this tree reads a claim
  written into a Rust doc comment. .github/doc-paths/doc-paths.sh reads
  git ls-files '*.md', and widening it is not asked for here, so this class
  stays found by hand.
• The other absence claims in the same files. src/cache/mod.rs carries
  further statements about what is absent - a token to watch, an entry produced
  for a notification - and each needs its own reading of the tree. None is
  touched.
• docs/decisions/. 0100 and 0061 carry sentences of a similar shape. A
  landed record's prose that has gone false because the tree moved is the rule
  question 0001 says no check reads a decision record and pastes five workflow files, and a check over docs/decisions/ has run since 2026-09-02 #380 is open on, and nothing here goes near it.
• .github/shell-analysis/shell-analysis.sh was NOT run. shellcheck is not
  on this machine and the script refuses rather than passing. No shell file is
  touched by this change and the gate runs that leg.
• No cross-toolchain, target, coverage, mutation, codeql or thread-detector leg
  was run here. Those run on the gate.

Who has read it

Nobody other than the author. There is no second reader on this board tonight,
and the evidence above stands in place of one rather than the question being left
open.