Give the diagnostic events the address they have in this tree, not one on the tracker (#491)

[iderex]

The issue this belongs to

Closes #491

What changed

Three doc comments in the library stop locating the diagnostics interface at
#100 and name crate::diagnostics, which is the module that holds it. Kind
in src/failure/mod.rs said 0004's reversal condition is read off "the
diagnostic events in #100"; WhyTheAgeIsUnreadable in src/cache/freshness.rs
said a diagnostic "under #100" could report which way a clock is wrong; Refused
in src/artwork/format.rs said a diagnostic event "under #100" would carry which
check refused. Each carries a second paragraph recording what the sentence said
and which of the two states it was in, in the shape those paragraphs already use
for their own corrections.

The conditional stays conditional in two of the three. Neither the cache
freshness module nor the artwork format module emits an event today, so what a
diagnostic COULD report and what one WOULD carry are still the moods to write
those sentences in. Only the address moved, and each correction says so.

src/diagnostics/mod.rs is not touched. It names #100 beside the record 0100
as the issue that decided the module, which is provenance rather than an address.

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 Kind is
there to find out how a failure is counted, and the paragraph told them the
counting is read off diagnostic events and then put those events on the tracker,
so the next thing they open is a closed issue instead of the module beside them.
A reader of a clock failure and a reader of a refused image format were sent to
the same place.

None of the three went stale. #100 closed as completed on 2026-08-26, the
commit that built the interface landed the same evening, and all three sentences
landed on 2026-08-28 - two days after both. So each landed refuted rather than
going stale, which is the harder of the two states to defend, and each correction
says that in those words.

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 three false addresses standing in the three files
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 three links the change adds.

Evidence

The commit being pushed:

git rev-parse HEAD
ae149ed3f1876bdd3cc7cdcc33233a366d6bd4b3

Every site in src/ that names the number, at the parent. Four, and the fourth
is the one left alone:

git grep -n '#100' ae149ed^ -- src/
ae149ed^:src/artwork/format.rs:215:/// a diagnostic event under #100 would carry and what a reader of a refusal
ae149ed^:src/cache/freshness.rs:284:/// forward. Collapsed, a diagnostic under #100 could report that a clock is
ae149ed^:src/diagnostics/mod.rs:6://! issue is #100. What may leave through an event is 0071 and #71.
ae149ed^:src/failure/mod.rs:111:/// reversal condition, read off the diagnostic events in #100 - without every

What the three paragraphs said, at the parent:

git show ae149ed^:src/failure/mod.rs | sed -n '108,112p'
/// Which of the fifteen a failure is, without its payload.
///
/// It exists so that a failure can be counted and grouped - which is 0004's own
/// reversal condition, read off the diagnostic events in #100 - without every
/// counting site matching fifteen variants and reaching into their fields.
git show ae149ed^:src/cache/freshness.rs | sed -n '280,286p'
/// Why an age could not be read as a length of time.
///
/// Two reasons rather than one because 0102 names two devices, and they are not
/// the same device: one that came up believing it is 1970, and one that jumped
/// forward. Collapsed, a diagnostic under #100 could report that a clock is
/// wrong and never which way, which is the half that says whether anything can
/// be done about it.
git show ae149ed^:src/artwork/format.rs | sed -n '213,216p'
/// format is a shape the core recognised and declined on purpose, and the word in
/// the kind says the opposite. What is here is which check refused, which is what
/// a diagnostic event under #100 would carry and what a reader of a refusal
/// wants. THIS SENTENCE SAID THE MAPPING ONTO THE KIND IS NOT MADE ANYWHERE:

#100 is closed as completed:

gh issue view 100 --repo Flowfin/core --json number,state,closedAt,title --jq '"\(.number) \(.state) \(.closedAt) \(.title)"'
100 CLOSED 2026-08-26T19:26:54Z Define the interface through which a client receives the core's diagnostics

The module carrying the interface, with the public names a sentence would use:

git show ae149ed^:src/diagnostics/mod.rs | grep -n '^pub '
71:pub mod redaction;
93:pub enum Severity {
172:pub const fn is_a_well_formed_event_name(name: &str) -> bool {
222:pub struct EventName(&'static str);
290:pub enum FieldValue<'a> {
306:pub struct Field<'a> {
353:pub struct Event<'a> {
403:pub trait DiagnosticsSink: Send + Sync {
418:pub struct Diagnostics<'a> {

and the tree already emitting through it, outside that module:

git grep -n 'EventName::declared(' ae149ed^ -- src/ ':!src/diagnostics/'
ae149ed^:src/cache/bound.rs:105:const WRITING_SUSPENDED: EventName = EventName::declared("cache.writing-suspended");
ae149ed^:src/cache/bound.rs:109:const ARTWORK_GAVE_WAY: EventName = EventName::declared("cache.artwork-gave-way");
ae149ed^:src/cache/envelope.rs:174:const ENTRY_DROPPED: EventName = EventName::declared("cache.entry-dropped");
ae149ed^:src/server/write_queue.rs:98:const AN_ENTRY_WAS_DROPPED: EventName = EventName::declared("write-queue.entry-dropped");
ae149ed^:src/session/mid_playback.rs:86:const REPORTING_SUSPENDED: EventName = EventName::declared("session.reporting-suspended");

The dates. The interface landed nine minutes before the issue closed, and all
three sentences landed two days after both:

git log --format='%h %cI %s' ae149ed^ -- src/diagnostics/mod.rs | tail -3
1aa8170 2026-08-28T17:30:05+02:00 Carry the treatment on the field name, and apply it before the sink (#224)
6933b04 2026-08-26T21:17:55+02:00 Give the core a way to say what happened, without giving it a voice
34b3866 2026-08-25T06:46:03+02:00 Lay the repository out, and give a fresh clone two commands (#13)
git blame -L 111,111 --date=short ae149ed^ -- src/failure/mod.rs | cat
b6db24df (Nils Lehnen 2026-08-28 111) /// reversal condition, read off the diagnostic events in #100 - without every
git blame -L 284,284 --date=short ae149ed^ -- src/cache/freshness.rs | cat
7616f211 (Nils Lehnen 2026-08-28 284) /// forward. Collapsed, a diagnostic under #100 could report that a clock is
git blame -L 215,215 --date=short ae149ed^ -- src/artwork/format.rs | cat
f8aaba7b (Nils Lehnen 2026-08-28 215) /// a diagnostic event under #100 would carry and what a reader of a refusal

What the three paragraphs say now:

git show HEAD:src/failure/mod.rs | sed -n '108,120p'
/// Which of the fifteen a failure is, without its payload.
///
/// It exists so that a failure can be counted and grouped - which is 0004's own
/// reversal condition, read off the diagnostic events [`crate::diagnostics`]
/// carries - without every counting site matching fifteen variants and reaching
/// into their fields.
///
/// THIS SENTENCE GAVE THOSE EVENTS AN ADDRESS ON THE TRACKER AND SAID THEY WERE
/// IN #100. That issue closed as completed on 2026-08-26, the module carrying the
/// interface landed the same evening, and this sentence landed two days after
/// both. So it landed refuted rather than going stale, which is the harder of the
/// two states to defend, and is worth saying in those words. #491 is where it was
/// found.
git show HEAD:src/cache/freshness.rs | sed -n '284,293p'
/// forward. Collapsed, a diagnostic under [`crate::diagnostics`] could report
/// that a clock is wrong and never which way, which is the half that says
/// whether anything can be done about it.
///
/// THE CONDITIONAL IS RIGHT AND THE ADDRESS WAS NOT: THIS SENTENCE SAID #100.
/// Nothing in this module emits an event, so what such a diagnostic COULD report
/// is still the mood to write it in. Where it points is the part that moved:
/// #100 closed as completed on 2026-08-26, the module carrying the interface
/// landed the same evening, and this sentence landed two days after both, so it
/// landed refuted rather than going stale. #491 is where it was found.
git show HEAD:src/artwork/format.rs | sed -n '215,232p'
/// a diagnostic event under [`crate::diagnostics`] would carry and what a reader
/// of a refusal wants. THIS SENTENCE SAID THE MAPPING ONTO THE KIND IS NOT MADE
/// ANYWHERE: the point exists now and is [`crate::failure::Failure`], and no
/// caller in this tree reaches it from here, because nothing in this tree fetches
/// artwork and the transport that would is #27.
///
/// IT HANDED THAT ABSENCE TO #49 UNTIL THIS EDIT. #49 closed as completed on
/// 2026-08-29, the day after the sentence landed, and what it produced is the
/// address in [`crate::artwork::address`] rather than a fetch. The two other
/// files of this directory already name #27 for the same absence. #485 is where
/// it was found.
///
/// IT ALSO GAVE THE DIAGNOSTIC EVENT AN ADDRESS ON THE TRACKER AND SAID #100.
/// Nothing here emits one, so what such an event WOULD carry is still the mood to
/// write it in, and where the events live is [`crate::diagnostics`]. #100 closed
/// as completed on 2026-08-26, the module landed the same evening, and this
/// sentence landed two days after both, so that half landed refuted rather than
/// going stale. #491 is where it was found.

No sentence in src/ gives the interface that address any more. What is left of
the number is the corrections saying what the three used to do, and the one line
that is provenance:

git grep -n '#100' HEAD -- src/
HEAD:src/artwork/format.rs:227:/// IT ALSO GAVE THE DIAGNOSTIC EVENT AN ADDRESS ON THE TRACKER AND SAID #100.
HEAD:src/artwork/format.rs:229:/// write it in, and where the events live is [`crate::diagnostics`]. #100 closed
HEAD:src/cache/freshness.rs:288:/// THE CONDITIONAL IS RIGHT AND THE ADDRESS WAS NOT: THIS SENTENCE SAID #100.
HEAD:src/cache/freshness.rs:291:/// #100 closed as completed on 2026-08-26, the module carrying the interface
HEAD:src/diagnostics/mod.rs:6://! issue is #100. What may leave through an event is 0071 and #71.
HEAD:src/failure/mod.rs:116:/// IN #100. That issue closed as completed on 2026-08-26, the module carrying the

What the change is:

git diff --stat origin/main...HEAD
 src/artwork/format.rs  | 17 ++++++++++++-----
 src/cache/freshness.rs | 13 ++++++++++---
 src/failure/mod.rs     | 12 ++++++++++--
 3 files changed, 32 insertions(+), 10 deletions(-)
git diff --name-only origin/main...HEAD
src/artwork/format.rs
src/cache/freshness.rs
src/failure/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 three links the paragraphs add 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

• docs/decisions/. Every site naming #100 outside src/ is there, and
  the git grep above shows the whole of src/. A record is superseded rather
  than edited in place, which docs/decisions/0001-decision-records.md fixes, so
  none of them is touched and nothing is claimed about them in either direction.

• src/diagnostics/mod.rs and src/diagnostics/redaction.rs. They are read
  as evidence and not edited.

• Whether any of the three modules should emit an event. That is a question
  about behaviour and it is not asked here. This change moves no code, and the
  two conditional sentences stay conditional for that reason.

• Every other reference to a closed issue in src/. Only #100 is examined,
  and nothing is claimed about the rest of the numbers this tree names in either
  direction.

• A check that would refuse this. Nothing in this tree reads a doc comment's
  pointer 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.