From 2b64f2ef72ab3db51ebe80ff2b37e401055c9258 Mon Sep 17 00:00:00 2001 From: Nils Lehnen <30603423+iderex@users.noreply.github.com> Date: Fri, 18 Sep 2026 04:36:17 +0200 Subject: [PATCH] Say which events the cache emits, and stop the cache module denying the read it holds `src/diagnostics/mod.rs` headed a section "Which events exist today" and answered "None. Nothing in this tree emits one, because no subsystem that would is built." Three exist. `src/cache/bound.rs` declares and emits two, for a full device suspending writing and for artwork giving way to metadata, and `src/cache/envelope.rs` declares and emits a third for an entry dropped after failing its check. None of the six sites is in a test module: those files' test modules begin at lines 966 and 463, below every one of them. That section is now about the cache, and it hands the reader `git grep -n 'EventName::declared' -- src/` rather than a list, because a list in the diagnostics module goes stale against the modules that declare the names. `src/cache/mod.rs` said "Nothing in this tree fetches bytes out of a store and hands them anywhere" as the reason the freshness half of #43 has no caller. `TieredCache::read` reads the supplied store and returns the bytes, and `CheckedEntries::read` calls it and hands what comes back to its own caller. What is actually 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 what the file now says, with #27 as the transport that would produce such a caller. The two are in different states and the text says which is which. The diagnostics sentence landed on 2026-08-26 and was true that day; the cache bound arrived on 2026-08-27 and the envelope on 2026-08-28, neither in a change with a reason to open the diagnostics module, so that one drifted. The cache sentence landed on 2026-08-28 against a read that had been in a sibling module of its own directory since 2026-08-27, so that one was refuted before it was written. The diagnostics paragraph also sent a reader to `crate::session` for the same sentence. `git grep -n 'exist today\|no subsystem' -- src/session/` exits 1 and prints nothing, so the pointer is deleted rather than repaired: what it pointed at cannot be found to repair. What failure it prevents: a reader asking what this interface looks like in practice met "None" and went away with a shape and no worked example, two files from three names with their severities and their fields; and a reader asking whether the freshness half of #43 is closable met an absent mechanism where the mechanism is present and the caller is not. Both errors run in the direction that makes the tree look emptier than it is. 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 its callers are still absent. Both are said in the same place, in words that got sharper rather than weaker. What was wrong, and 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/`. `.github/doc-paths/doc-paths.sh` takes `git ls-files '*.md'` as its subject, so a claim in a Rust doc comment is read by nothing here, and the next sentence of this shape lands as green as these two did. No event is added, renamed or removed. No type, field, constant, assertion or test changes. The diff is two doc comments. `cargo build --locked --all-targets` and `cargo test --locked` are green at this commit: ten suites, 772 passed, 0 failed. `.github/format/format.sh check`, `.github/lint/lint.sh check`, `.github/doc-paths/doc-paths.sh check` and `.github/invariants/invariants.sh check` each exit 0. `.github/shell-analysis/shell-analysis.sh` was NOT run here: `shellcheck` is not on this machine and the script says so rather than passing. No shell file is touched and the gate runs that leg. Closes #442 Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com> --- src/cache/mod.rs | 13 +++++++++++-- src/diagnostics/mod.rs | 27 ++++++++++++++++++++++++--- 2 files changed, 35 insertions(+), 5 deletions(-) diff --git a/src/cache/mod.rs b/src/cache/mod.rs index 458188e..ccfcff6 100644 --- a/src/cache/mod.rs +++ b/src/cache/mod.rs @@ -36,8 +36,17 @@ //! 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. +//! which is #27. What is absent is a caller that DEMANDS freshness: nothing here +//! asks for an entry because it is about to show one to somebody. +//! +//! THAT LAST SENTENCE READ "NOTHING IN THIS TREE FETCHES BYTES OUT OF A STORE AND +//! HANDS THEM ANYWHERE", AND [`bound`] HAD BEEN DOING BOTH FOR A DAY. +//! `TieredCache::read` reads the store the client supplied and returns the bytes, +//! from 2026-08-27, and [`envelope`]'s own read calls it and hands what comes +//! back to its caller. The sentence landed on 2026-08-28, so a sibling module of +//! this directory refuted it before it was written. The read is here; what is +//! missing is a reason to make one, which is the sentence above and is #27. #442 +//! is where it was found. //! //! [`notification`] holds 0116, which is the second of the three ways 0006 says //! an entry stops being trusted and the one [`freshness`] is not: which entries diff --git a/src/diagnostics/mod.rs b/src/diagnostics/mod.rs index 0049e96..9f3600d 100644 --- a/src/diagnostics/mod.rs +++ b/src/diagnostics/mod.rs @@ -32,9 +32,30 @@ //! //! # 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. +//! The cache's, and nobody else's. [`crate::cache::bound`] emits one when a full +//! device suspends writing and one when artwork gives way to metadata, and +//! [`crate::cache::envelope`] emits one when an entry is dropped for failing its +//! check. Which names those are is read out of the tree rather than listed here, +//! because a list in this module goes stale against the modules that declare +//! them: `git grep -n 'EventName::declared' -- src/`. +//! +//! THIS SECTION READ "NONE. NOTHING IN THIS TREE EMITS ONE, BECAUSE NO SUBSYSTEM +//! THAT WOULD IS BUILT." It was true on 2026-08-26, when it landed, and stopped +//! being true the next day: the cache bound arrived on 2026-08-27 with two +//! events and the entry envelope on 2026-08-28 with a third, and neither change +//! had a reason to open this file. So this one went stale rather than landing +//! refuted, which is the milder of the two states and is worth saying in those +//! words. #442 is where it was found. +//! +//! THAT SENTENCE ALSO SENT A READER TO [`crate::session`] FOR THE SAME SENTENCE, +//! AND NOTHING OF THAT SHAPE IS IN THAT MODULE. The pointer is deleted rather +//! than repaired, because what it pointed at cannot be found to repair. +//! +//! What is still absent is a core that runs to hand any of the three to a sink a +//! client supplied. #115 is the core's own lifetime and 0100's interface is how a +//! client supplies one, so today each of the three reaches whatever sink a caller +//! passes in and goes nowhere else. That is a statement about this tree rather +//! than about the interface. pub mod redaction;