populace.data.release: latest.json pointer + contract-gated publishing

[PavelMakarchuk]

Fixes #9. Stacked on #12 (the release contract) — merge that first; GitHub will retarget this to main when the base branch is deleted.

What

Adds populace.data.release — both sides of the latest.json pointer:

• Producer: publish_release(release_dir, repo_id) validates the directory against the release contract (an invalid release uploads nothing), uploads its files, and uploads latest.json last — so a reader never sees the pointer before the release it points at. extra_files= lets a diagnostics artifact (Publish calibration diagnostics (per-target rows, loss trajectory, skipped targets) with each populace-us release #10) ride along.
• Consumer: latest_release(repo_id) downloads the pointer and returns a typed LatestPointer — the one-call answer to "which release is current?" for dashboards and scorers. Refuses pointer schema versions it doesn't understand, loudly.

Pointer payload (schema_version 1):

{
  "schema_version": 1,
  "release_id": "populace-us-2024-9f1260b-20260611",
  "updated_at": "2026-06-11T13:53:15+00:00",
  "paths": {
    "build_manifest": "releases/populace-us-2024-9f1260b-20260611/build_manifest.json",
    "release_manifest": "releases/populace-us-2024-9f1260b-20260611/release_manifest.json",
    "sound_ecps_replacement_comparison": "releases/populace-us-2024-9f1260b-20260611/sound_ecps_replacement_comparison.json"
  }
}

Why

Nothing on the Hub says which release is current. Consumers list the releases/ tree and guess — and because build ids end in a date, two same-day builds (9f1260b vs 5da5a95, both 2026-06-11) have no defined ordering. The calibration-diagnostics dashboard currently picks the lexicographically-last complete release, which is right today only by accident of hex ordering.

Testing

• 8 new behavioral tests against a fake Hub client that records upload order: pointer-last is asserted, invalid-release-uploads-nothing is asserted, publish→resolve round-trips.
• The Hub client is injected (api=), so the suite is network-free and mocks nothing of our own.
• Full workspace suite on this branch: 376 passed, 4 skipped. ruff check clean. Wheel builds.

Follow-up (not here)

Backfilling latest.json for the already-published 9f1260b release is one call once this merges:

from populace.data import publish_release
publish_release("releases/populace-us-2024-9f1260b-20260611", "policyengine/populace-us")

🤖 Generated with Claude Code

[MaxGhenis]

Superseded by #37, which merged the latest.json pointer and contract-gated publishing into main.