A retrieval that goes stale fails the build

[ChelseaKR]

Closes the DG-01 and DG-04 gaps the Data Governance row recorded. Adds ADR-0009. Stacked on #30; base is docs/the-manifest-entry-exists.

What was missing

Every figure these pages publish is a count of a file downloaded on one day. The pages say the date, PROVENANCE.md says the version and the hash, and none of that is the same thing as noticing. DINS carries no version string and is appended to as inspections complete, so it differs from the acquired file the day after the acquisition and increasingly every season after.

Nothing here raised its hand, and nothing could: no code in this repository had ever asked what today is.

The README's Data Governance row had recorded the gap: "no refresh cadence, staleness SLA or stated tier".

What this adds

DG-01, a data card per source. docs/data/frap-perimeters.md and docs/data/dins.md, carrying the seven rows the standard's section 1 names. PROVENANCE.md already carried five of them; the two it did not are the tier (L1 for both) and the refresh cadence with its SLA. tests/test_data_cards.py enumerates the cards against the declared source list rather than against what is on disk, so adding a source without a card fails rather than passing a directory listing.

DG-04, the staleness alarm, as an AUTO-GATE.

Source	SLA	Why that number	Fires on
FRAP perimeters	400 days	one annual release cycle plus about five weeks, so a retrieval does not go stale on the eve of the version that would replace it	2027-09-11
CAL FIRE DINS	180 days	about one fire season; no version string, appended to as inspections complete, so there is no release to wait for	2027-02-03

This gate is built to fire, and firing is it working. The message says what to do: re-acquire and rebuild site/, or move the SLA in the card with a reason. What it must not become is a number quietly raised to get a green build, which is the move CONTRIBUTING.md already forbids for a marker set.

The SLA is this project's declaration, and every card says so in those words, held by a test. Neither CAL FIRE nor FRAP promises a publication schedule and neither is asked to.

Where the clock is allowed to be

The obvious implementation is the one the standard's wording suggests: flag it in the report. That is exactly what must not happen here.

README.md promises the same inputs produce byte-identical output, tools/determinism.sh is the gate behind that promise, and test_no_wall_clock_leaks_into_an_artifact already asserts it. A page computing its own staleness would read the wall clock at build time, two builds a day apart would differ, and of the two claims in conflict the one that would quietly lose is determinism, because its failure is invisible.

So the artifacts publish retrieved and staleness_sla_days and compute nothing from them. A consumer holding both does the subtraction against its own clock and gets the same answer this build would, whenever it asks. One function reads date.today(), one caller passes it, and both sides of the SLA boundary are tested against fixed dates. ADR-0009 records that trade and names what it does not solve: ADR-0003's worry that a published marker basis can go stale when a publisher revises a domain is a different check, and a file-level SLA only bounds the window.

Proof each new check can fail

Against the pre-change source with docs/data/ absent, all 25 tests in the new file fail:

FAILED tests/test_data_cards.py::test_the_card_says_the_sla_is_this_projects_declaration[frap_perimeters]
FAILED tests/test_data_cards.py::test_the_cards_carry_no_em_dashes - Attribut...
FAILED tests/test_data_cards.py::test_no_published_retrieval_is_older_than_the_sla_its_card_states
FAILED tests/test_data_cards.py::test_the_staleness_gate_fires_once_the_sla_is_past
FAILED tests/test_data_cards.py::test_the_staleness_gate_fires_the_day_after_the_sla_and_not_the_day_of[dins_postfire]
25 failed in 0.14s

The staleness gate is a pure function of a date, so it is separately run against dates it must reject:

• test_the_staleness_gate_fires_once_the_sla_is_past runs it at 2099-01-01 and requires every source flagged
• test_the_staleness_gate_fires_the_day_after_the_sla_and_not_the_day_of pins both sides of the boundary per source, so an off-by-one is a failure rather than a gate that fires early or late

Positive control, passing identically before and after: tests/test_provenance.py, 14 tests, which reads the same sources.py and is unaffected.

The gate stacked underneath also earned its keep again: adding the policy fields without rebuilding site/ failed test_the_published_artifacts_carry_the_reviewed_provenance on both artifacts.

Gate output

$ make verify
...
Required test coverage of 90% reached. Total coverage: 100.00%
============================= 606 passed in 15.64s =============================
...
  8 passed (3.1s)
determinism: build/run-one and build/run-two are byte-identical (5 files)
MAKE_VERIFY_EXIT=0

Exit code read from $?.

site/ is rebuilt from the acquired files: four lines added to each artifact, all of them the policy fields. No measured number moves.

🤖 Generated with Claude Code