S8 (#189) — a correction procedure for the delivery that exists

[Polichinel]

Closes #189. Closes #15. Closes register C-22 — with one step explicitly awaiting an operator decision. Part of epic #181.

Why this was overdue

C-22's trigger fired on 2026-07-27. Run-0 put 64,742 cells × 36 months into the UN FAO's store, live and being served. The written procedure — #15, from June — began "clear stale disk cache" and "re-run with corrected shapefiles". Both were deleted with the runtime mapper.

There was data in a partner's store and no usable way to correct it.

What the document establishes

Identification. run_id and lookup_version, both present by construction. This is why S8 waited on S5: until C-60, lookup_version could silently be the string "unknown", and a procedure whose first step rests on a field that can become a placeholder is not a procedure.

Confirmation, offline. 26 fidelity tests against committed artifacts. Re-running the pipeline to investigate changes the thing being investigated.

And where the fault is not ours. If those pass and a value is still wrong, it is upstream — views-datafactory#387. C-43's scope split, restated where an operator meets it at 22:00 rather than buried in a register entry.

Supersession, not retraction

The contract has no retraction primitive, and the document says so instead of inventing one. Manifest-last commit ordering means a run is replaced by publishing a new complete run.

It also states the thing a reader would otherwise discover the hard way:

views-faoapi resolves the newest manifest matching a broad filter. A corrected run is picked up because it is newer, not because it is correct.

Two consequences spelled out: publishing is the switch-over, and do not publish a test or partial correction to the production bucket — the consumer cannot tell it from the real one. That is C-73, cited rather than re-solved, with #133 named as the fix that would let a consumer select on intent.

Plus the one that would turn a correction into an outage: do not delete the superseded run's files while its manifest still stands — a run that resolves and then fails to load is worse than a wrong value.

The step that is written but not decided

Steps 1–3 and 5 are executable today. Step 4 is not, and it is the one that reaches the partner. Stated verbatim in the document, with an instruction to stop and ask rather than improvise:

1. Who contacts the UN FAO when a delivery is found wrong, through what channel, and how quickly?
No named person, no address, no timing expectation — so it would be improvised by whoever noticed, under time pressure, which is the worst moment to invent a process.

2. Does FAO expect us to retract or to supersede?
Supersession is what the contract does. Retraction has no wire mechanism, and adding one would need an ADR-013 amendment plus agreement from views-faoapi. It is a question for them, not a decision for us.

C-22 closes because the procedure exists and says exactly where it stops. What remains is a decision, not engineering; leaving the entry open would read as unfinished work rather than as a question awaiting an answer.

Carried forward

docs/CLONING.md now warns a clone to answer its partner's correction questions before first delivery. This repo shipped run-0 with that step undecided and it still is — views-crafdapi and views-productionapi should not inherit it.

README.md points at the procedure from the operational surface.

Pinned

Three checks in tests/test_doc_accuracy.py: the document exists and names the identification fields; it describes ADR-013 mechanisms and none of the deleted ones (it is also inside _BANNED's scan); and it still flags its undecided step — so if step 4 is ever answered, the marker has to be replaced with the decision rather than quietly dropped.

Verification

ruff check .                                     # clean
pytest -q                                        # 305 passed, 3 skipped, 41 xfailed, 5 known pyarrow
pytest -q tests/test_doc_accuracy.py             # 13 passed
git diff --stat origin/main -- tests/fixtures/   # empty

Register: 74 concerns, 15 open, 59 resolved.

🤖 Generated with Claude Code