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

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

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;