# ADR 0019: An attribution declares whether its work was read Every attribution to a published work carries one line saying whether anybody read that work against this code: `Read: YYYY-MM-DD, primary.`, the same with `secondary.`, or `Not read: .` with a reason that may not be empty. `tests/architecture/test_citations.py` requires exactly one such line per attribution and checks nothing about its content. ADR 0015 made the bibliography fetched rather than written; this records the state the fetch cannot establish. ## The failure this comes from happened here ADR 0016 cited [clauset2004] for the quantity FastGreedy maximizes. The key resolved, the work was real, the sentence read well, and every gate was green. The paper defines modularity with an adjacency entry of 1 or 0, while the code hands igraph a weighted graph; the quantity actually maximized is [newman2004]'s. It was found by reading the paper, and nothing in the repository could have found it. That is the limit this decision accepts rather than tries to beat. A resolved entry proves the work exists. Whether it supports the sentence beside it is a reader's judgement, and the only thing a check can do is make the absence of that judgement visible. ## Three vocabularies for one fact is how it stayed invisible Before this, the same state was written three ways: a delta sentence with a direct quote in `ncd.py`, a bold "None has been read against this code." paragraph in `natural_breaks.py`, and -- in `fastgreedy.py` -- a delta sentence with no statement either way. A fourth form was one commit away, because nothing said which to use. The count made it worse. Thirteen of the twenty attributions in the census were presumed, and finding that out meant reading every docstring; issue #93 counted them by hand. With one spelling the count is derived, and `docs/method/evidence.md` (issue #58) can consume it instead of a second manual tally. ## Why the mark hangs on the attribution and not on the module `natural_breaks.py` names five works. Three of them -- [gronlund2017], [song2020] and [wang2011] -- were read on 2026-11-07, and [fisher1958] and [jenks1977] cannot be obtained at all. A module-level statement has no way to say that, and the one it had was literally false the moment the first of the five was read. The attribution is the unit that makes a claim, so it is the unit that declares. ## Why `primary` and `secondary` are distinguished ADR 0016 was not "nobody read it". Somebody read *about* it. A bit that records only whether reading happened would have been set to true, and the wrong sentence would have shipped with a mark vouching for it. `secondary` is the honest record of having read an account of a work, and it is visible in exactly the way the failure needs it to be. ## Why obtainability is a reason and not a field The first draft of this put the access state in `docs/refs.json`, beside the fetched metadata. It is not there, for three reasons. Open access is time-varying -- [saitou1987] is free to read at the publisher today and machine-unreachable all the same -- so the field would be a snapshot that goes stale silently. Writing it requires a resolver this project does not already call, and ADR 0015's rule is that nothing in that file is typed by hand. And the fact is only ever needed where it changes what a reader should do, which is beside the attribution that cannot be completed: `Not read: closed access, no open copy anywhere.` says it in the place it matters, in a field that already has to be non-empty. ## What this does not do It does not check that a `Read:` date is true, that the work named is the work opened, or that the delta sentence beside it is correct. A date in a docstring is evidence of nothing: `make ref` keeps the fetch script free of a clock by taking `--today` from the shell, and a mark is typed by its author in the same spirit. What the gate removes is the silent third state -- an attribution that neither claims a reading nor admits the lack of one -- which is what left thirteen of them indistinguishable from the four that had been checked.