findings: a registry, because the codes had already drifted

A finding code is the stable half of a result - what a dashboard groups by and
what someone greps a year of archived runs for. That only holds if a code means
exactly one thing forever, which fifteen ad-hoc string literals cannot promise.

By the time this was written the failure had happened twice:

  - Two emitters independently produced connectivity.downstream_loss and
    connectivity.loss_downstream for the same claim. Nothing objected. Anyone
    aggregating either would have silently seen half their data.
  - Two codes sat under nat.* while being declared Category.CONNECTIVITY.
    nat.udp_unreachable is not about NAT, and the prefix decides the category,
    which decides which verdict light the finding rolls up into. Renamed while
    that is still cheap.

Codes are now typed FindingSpecs carrying category and default severity;
emitters reference the spec rather than retyping the string, so a typo is a
compile error and two call sites cannot disagree about a finding's category.

docs/findings-registry.md is the contract and a test reads it, failing when the
document and the code disagree on which codes exist or how severe they are.
Documentation that drifts from its implementation is worse than none, because it
still looks authoritative. The check reads table rows only, so the prose can go
on explaining which codes were retired and why.

Closes open item 1 of measurement-schema.md section 9.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/build-status.md

@@ -819,3 +819,32 @@ prevent. The pre-existing rate test caught that when I first tried the generous
 right to. Second half of the same bug: callers treated *any* refusal as terminal, so `TryAllow` now
 says why — a sender paces through a transient "too fast just now" and still stops dead on a spent
 budget or an expired grant. Both halves are pinned by regression tests.
+
+### Findings registry (2026-08-01)
+Closes open item 1 of measurement-schema.md §9. A finding code is the stable, machine-readable half
+of a result — what a dashboard groups by and what someone greps a year of archived runs for — and
+that only holds if a code means exactly one thing forever. Ad-hoc string literals at fifteen call
+sites cannot promise that, and by the time the registry was written the failure had already
+happened.
+
+**Two emitters had independently produced `connectivity.downstream_loss` and
+`connectivity.loss_downstream` for the same claim**, and nothing anywhere objected. Anyone
+aggregating either one would have silently seen half their data. Merged into
+`connectivity.loss_downstream`, paired with `loss_upstream` so the two directions read as a set.
+
+**Two codes were also renamed out of `nat.*`.** `nat.udp_unreachable` is not about NAT — it means
+no replies came back — but the prefix determines the category, and the category determines which
+verdict light the finding rolls up into (§7.3). A `nat.*` code landing under *connectivity* is not
+a naming quibble; it changes which light turns red. Cheap to fix now, a breaking change later.
+
+Codes are now declared as typed `FindingSpec`s carrying their category and default severity, and
+emitters reference the spec instead of retyping the string — so a typo is a compile error and two
+call sites cannot disagree about a finding's category.
+
+`docs/findings-registry.md` is the contract, and a test reads it: it fails when the document and
+the registry have codes the other lacks, or when a severity differs. Documentation that drifts from
+its implementation is worse than none, because it still looks authoritative. The check scopes
+itself to table rows, so the prose can keep explaining which codes were retired and why.
+
+Six tests: uniqueness, declared-vs-listed, prefix↔category agreement, naming convention, a
+word-order-anagram check (the shape the duplication actually took), and the document agreement.