Calibrate the UK national build from Ledger-backed targets

[juaristi22]

Depends on: #622 (compiled registry + parity gate) and a UK national calibration seam, which does not exist yet — the national staging path is gate-only by design. This issue is the convergence point, filed now so the seam work and the target migration land against a shared contract.

Context

Today's UK national build (tools/build_uk_national_dataset.py → build_uk_national_dataset) runs two stages (frs_hmrc_retained_leaves, hmrc_spi_income), enforces coverage/terminal gates, and stages an H5 — explicitly without calibration: the terminal report omits the target-surface/target-fit/parity trio "instead of inventing passes". The June production release's 149-target national calibration ran from code that never reached a pushed branch; its surface is being ported to Ledger (PolicyEngine/chronicle#132, PolicyEngine/chronicle#133) and its compilation to populace (#622).

The local lane already shows the target shape end to end (ladder targets → local_doctrine solve → diagnostics). This issue gives the national build the same property, with Ledger as the only source of target values.

Scope

1. National calibration seam — a stage (or post-stage step) in the UK national build that accepts a compiled TargetRegistry and produces calibrated household weights, advancing household_weight_kind and appending the canonical mass-change record, mirroring the rowwise candidate path's conventions (build_uk_rowwise_candidate.py).
2. Ledger-backed surface only — the seam consumes the registry compiled in Consume Ledger UK facts: uk_target_references, mapping module, and a compile-parity gate #622 (hash-pinned consumer artifact + uk_target_references.json active subset). No target value may enter from any other path; the uk-data package is not a build dependency.
3. Solver doctrine — reuse populace.calibrate (the shared L0/solve stack) under a declared national doctrine analogous to local_doctrine.py: uniform operator, declared caps, no per-target knobs. The doctrine constants land in a reviewed module, not as CLI flags.
4. Evidence becomes real — with a calibration present, the terminal-gate battery gains the previously-omitted trio: target-surface, target-fit (existing UK_MAX_TARGET_ABS_RELATIVE_ERROR = 0.25 fence), and parity evidence; uk_calibration_diagnostics_payload gets wired with the Ledger pin (facts sha256, profile ids) in its provenance block.
5. Acceptance against the incumbent — the US base v2: one CPS+ACS+PUF-detail pool; datasets labeled by exact record count (dense = full pool; exact-k L0 selection) #578 acceptance rule stands: the first Ledger-calibrated candidate must not regress the certified June artifact on battery observables (ESS fraction ≥ 0.01 fence, weight-ratio fence, target-fit). Score against the frozen reference exactly as the terminal gates already encode it.

Explicitly out of scope

• Base-table construction, imputations, or any change to what the input H5 is (separate workstream).
• Ledger authoring or profile changes.
• Retiring uk-data's own calibration pipeline — uk-data remains the production builder until a Ledger-calibrated populace candidate passes the acceptance battery; this issue produces that candidate, not the switchover decision.

Acceptance

• A UK national staging build with the seam armed produces a calibrated H5 whose terminal report carries the full gate battery (no omitted trio), with every target value traceable through ledger_facts_sha256 → consumer artifact → source package → publisher bytes.
• The build fails hard if the compiled registry and the release's pinned Ledger artifact disagree (no mixed-provenance surfaces).
• Candidate-vs-incumbent scoring reproduces the production diagnostics schema (score_vs_enhanced_frs-style block) so the release decision is comparable to June's.