Evidence-tier publishing: contract sibling, latest-evidence.json, builder --evidence-release (#506)

[MaxGhenis]

Implements the microcosm#506 design (owner directive: the best available artifact should be publishable at all times WITHOUT weakening certified gating), generalizing the #490/#497 register pattern — adjudicate, record, carry the caveat in the artifact. Leaves #506 open for the owner to close after the first evidence publish (the current best dense artifact).

The tier, structurally

• validate_evidence_release_dir (microcosm-data): a sibling of validate_release_dir, not a relaxation — same required files, same shape/provenance/hash/cross-manifest checks, plus a mandatory non-empty known_failures block: every recorded gate failure verbatim, each with an owner issue ref. Gate-verdict requirements (US critical-target fit, source-coverage gate.passed) are exactly what the tier records instead of enforcing. Dirty-git, hash mismatches, and build-id mismatches still refuse: the tier relaxes verdicts, never auditability.
• Mutual exclusion is structural, both directions. Evidence manifests declare schema_version: "1-evidence" + tier: "evidence"; the certified contract rejects that schema marker no matter which gates failed, and a certified-shape manifest (no tier, no known_failures, schema 1) fails the evidence contract. validate_release_dir itself is untouched.
• Scope: national-default releases only. Local-area roles (Release contract needs dataset-role classes: national-default checks reject valid non-default local-area artifacts #398) and UK exact-k releases (One country-agnostic gate battery: phased evaluation, unconditional reporting, per-country gate selection (#578) #611 gate battery) are refused by name — no evidence semantics have been adjudicated for them.

Publish path

• publish_release(evidence=True) validates via the evidence contract, creates the immutable tag exactly as today, and moves only a new latest-evidence.json pointer (payload mirrors latest_pointer_payload + tier). The certified latest.json path never appears in an evidence commit — pointer isolation is pinned in both directions by tests.
• latest_evidence_release() is the consumer; latest_release() now refuses a pointer payload naming a foreign tier (defense if an evidence payload ever landed in latest.json).
• microcosm-publish-release --evidence; Slack alerts label the tier so they can never read as a certified release announcement.

Builder --evidence-release

• With the flag absent, behavior is bit-identical to main: all conversion points keep the exact certified statements (the batched pre-export raise with the CG tail transfer: field-local donor quarantine + mass-conserving own-tail stratum + E01000 receipt (#567) #568 weight-evidence sidecar, the reform-smoke raise, the take-up-contract raise), and the only refactors are string-identical (list-then-join, extracted _default_release_id).
• With the flag: the Fold SSI take-up gates into the batched terminal gates so failed runs keep their evidence #548 terminal accumulator, reform smoke, and take-up contract convert from raise to record; the run continues through the H5 write and manifests, and _evidence_release_manifest_fields stamps the evidence schema marker + known_failures (raises on an empty record — the flag is structurally incapable of minting a certified-shape manifest). Preflight and mid-build source-stage gates still abort in both modes.
• Owners are mandatory: each recorded failure must match the standing US_EVIDENCE_FAILURE_OWNERS register (the two Evidence-tier publishing: ship the best available artifact at all times, with its failures recorded in the manifest (dense first) #506-adjudicated dense families: SOI Table 1.4 dollar fit → PUF donor uprating overstates mean-reverting distribution series: non_sch_d at 2.39x the SOI concept #487, QRF tail concentration → QRF amount forests lose donor design weights after the n-of-n bootstrap: extreme-tail draws are a seed lottery #481/PUF donor uprating overstates mean-reverting distribution series: non_sch_d at 2.39x the SOI concept #487) or a --evidence-failure-owners per-run JSON — an unowned failure refuses the export, at the earliest conversion point.
• An all-green run under the flag is refused ("rerun without --evidence-release"): the tier exists to carry failures, and a certified-quality artifact must certify.
• Release ids: auto-ids carry the -evidence- segment; certified builds refuse ids that squat it; incompatible with --exact-k (the ladder lane keeps its tag-only contract).

Tests

49 new tests across the three suites (19 contract, 13 release/publish, 2 CLI guard, 11 builder + the #568 AST guard now also covering the evidence branch shape). Full workspace suite green (uv run pytest: exit 0 on this branch), ruff clean.

Notes for the merge gate

• Ported from the pre-rename populace tree (branch evidence-tier-506, commit 9012391d) onto microcosm paths/namespace; the One country-agnostic gate battery: phased evaluation, unconditional reporting, per-country gate selection (#578) #611 schema-4 verifier (Schema-4 gate-battery verification in the release contract (#611 A3) #663) is already in this base.
• gates.calibration in the build manifest stays the battery-only verdict in both modes; the release manifest's known_failures is the authoritative full terminal record (superset).
• A cross-family sol review round on the committed diff is running; findings (if any) will be fixed before this leaves draft.
• Do not merge from this lane: the OWNER session does the final merge gate and the first evidence publish. Evidence artifacts never feed pe.py certification.

🤖 Generated with Claude Code