UK national calibration run-readiness: doctrine, live parity trio, US-format diagnostics, scorer, staging posture (#623)

[juaristi22]

Part of #623 under #665 (WS-D). Registry #736 item 10 asked to close-or-narrow #623 after #729 delivered the seam core; this PR is the narrowing, per the adjudicated plan (María, 2026-08-21): all calibration tooling lands now — solve doctrine, honest gate evidence, US-format diagnostics, candidate-vs-incumbent scoring, run posture — and the licensed armed run itself stays held until the WS-E spine completes E8 (#684) + E10 (#686), or María names a different base. Builds on merged #735 (the 2025 Ledger surface) and #733 (the FRS 2024-25 line).

What lands

1. National solve doctrine — new uk_runtime/national_doctrine.py mirroring local_doctrine.py: every solver option the seam previously inherited silently (epochs 256, lr 0.02, max_weight_ratio 10.0, seed 0, loss cap 10.0, l0 0.0, free mass, uniform target weights) is a declared, tamper-tested constant. Doctrine v1 deliberately lifts Add the UK national calibration step over ledger-backed target references #729's values; first-run evidence is the revision path (adjudication 3).
2. Single compile path + writer-safe materialization — UKNationalCalibrationStage consumes the driver's compiled registry at load_uk_frs_release().calibration_year (2025) and materializes bindings through the shared interpreter via a lifecycle subclass of the shared UKFrameTargetAdapter: prepared scratch columns are restored away post-solve, so the staged frame survives the real HDFStore writer (closes Add the UK national calibration step over ledger-backed target references #729 dispositions finding 4, per adjudication 2 — materializer-owned lifecycle). The materialization period is passed explicitly — never the input frame's base-year time_period, which lags the calibration year.
3. Canonical weight/mass conventions — national_calibration_mass_reason() names the bound families; a post-solve fence requires the CALIBRATED kind and exactly one appended mass record; the stage manifest carries the rowwise-convention weights block (household_weight_kind_chain, calibration_mass_change, solve block, doctrine echo).
4. The parity trio evaluates for real on armed builds — _stage_parity_evidence builds the uk_export_surface/uk_target_surface/uk_target_fit evidence from independently sourced sides: candidate from the staged frame and solve diagnostics, reference from the frozen eFRS parity instrument (parity_reference parameter, driver passes the committed instrument) and the declared registry at name@period grain. A copied reference can never fabricate a pass; unarmed builds keep the honest evidence_absent, pinned in both postures.
5. US-format-identical diagnostics + chronicle provenance — the driver's bespoke diagnostics blob is replaced by uk_calibration_diagnostics_payload/write_uk_calibration_diagnostics — the same shared producer the US release path imports (schema v6, per-epoch loss_trajectory, per-target rows, loss attribution), so the calibration dashboard consumes UK and US files identically. A hermetic format-parity pin asserts the UK payload's shared layer equals the shared producer's output with uk_diagnostics strictly additive. The build block carries the chronicle artifact provenance (facts sha256, manifest sha256, profile ids), build id, code pins, and input posture — every target value traceable through ledger_facts_sha256 (Publish Chronicle package IDs in calibration diagnostics targets #661).
6. Candidate-vs-incumbent scorer (US base v2: one CPS+ACS+PUF-detail pool; datasets labeled by exact record count (dense = full pool; exact-k L0 selection) #578 rule 1) — new tools/score_uk_national_candidate.py: both artifacts rescored on the same frozen register with relative_error_loss (cap 10.0), emitting the June-schema score_vs_enhanced_frs block ({candidate,incumbent}×{train,holdout,full}_loss + target_wins) with per-family wins. Signed differences: holdout_basis: "none_declared" (June's holdout split lives only in the archived pipeline); the diagnostics build block reserves score_vs_enhanced_frs: null until the licensed run merges the real receipt.
7. Run readiness, runs held — a declared non-certified staging-candidate input posture (--staging-candidate-input-sha256: sha-gated with a mid-read race guard, labeled tier in the build record, refused for release candidates) so the armed run is push-button on any pre-clone spine; docs/uk-national-calibration-runbook-623.md records the exact command, the evidence-dir layout, and the two unblock conditions. Grain basis (adjudication 1): the incumbent's published enhanced_frs_2024_25.h5 is itself pre-clone (52,846 households; clone_and_assign feeds only its local-weights product), so pre-clone scoring is apples-to-apples — with one signed method difference to carry into the score receipt: incumbent national weights are a collapsed local solve, ours is a direct national solve under doctrine.

Explicitly out of scope

• The licensed armed run and its acceptance evidence (held per adjudication 5; the runbook is the contract).
• The four post-calibration aggregate scalers — ruling stays open on Calibrate the UK national build from Ledger-backed targets #623 / WS-C deferred adjudications and the reconciliation layer #736 (Max, 2026-08-20).
• Candidate-side labels/manifest/threshold arming (Assemble the microcosm-built UK spine: whole-spine parity and swap acceptance #686); the switchover decision (Assemble the microcosm-built UK spine: whole-spine parity and swap acceptance #686/UK dataset build: full migration from policyengine-uk-data (master epic) #665 P4–P5).

Verification

Hermetic: doctrine pinned tests; single-compile-path + writer regression through the real write_uk_national_frame; armed/unarmed parity-trio postures; mass-record fences; US↔UK diagnostics format-parity pin; scorer unit tests on synthetic twins; staging-posture flag matrix (adversarial refusals). Synthetic end-to-end in CI: armed synthetic build → real writer → full battery, US-format diagnostics, Logbook row with ledger_facts bound in input_pins_digest. Full three-shard suite + ruff green locally on the merged tip.

🤖 Generated with Claude Code