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

[vahid-ahmadi]

Automated review pass (Claude Code, high effort, diff only — no verification runs). Posting on the draft since two of these bear on whether the calibration gate means anything; the other two are dead code.

Substantive

1. packages/microcosm-build/src/microcosm/build/uk_runtime/hmrc_restoration.py:851 — the certified-pin check is skipped for the staging tier. _validate_certified_candidate_identity returns early for any identity whose tier == "staging_candidate", verifying only that revision equals a hard-coded constant; the sha256/size comparison against the certified pin never runs. Any UKCertifiedCandidateIdentity constructed with that tier — not only one produced by verify_staging_candidate_uk_input — passes the HMRC replay-base gate with an unverified file. The SHA binding currently lives only in the CLI path, which makes it a convention rather than an invariant; a second caller constructing the identity directly gets no binding at all.

2. tools/score_uk_national_candidate.py:60 — the rule-1 holdout comparison is vacuous by construction. The score block sets candidate_train_loss, candidate_holdout_loss and candidate_full_loss all to the same candidate.final_loss (and likewise for the incumbent), with holdout_basis: "none_declared". Since the candidate was calibrated on this very registry, there is no held-out quantity in the comparison and rule 1 can only ever be won by the candidate — any overfit divergence is silently absorbed. This is the same failure shape as the E7 receipt on #747: a green result that reflects the absence of a check rather than the presence of agreement. Given this is the component deciding whether a calibration run succeeded, it seems worth either declaring a real holdout basis or having the rule refuse when holdout_basis == "none_declared" rather than scoring.

Dead code

3. tools/build_uk_frs_spine.py:871 — the new except ValueError as error: clause is inserted ahead of the pre-existing except Exception as error: whose body branches on isinstance(error, ValueError). That branch is now unreachable, and any ValueError special-casing it performed beyond the rung-abort signature is silently lost. Worth a look given this is the same handler restructured for the #733 review — it may be that the merge of the two paths dropped something.

4. tools/build_uk_national_dataset.py:1202 — source_vintages["frs"] = load_uk_frs_release().vintage is added two lines above an identical pre-existing assignment; the new line is dead and load_uk_frs_release() is now called twice.

Findings 3 and 4 are trivial. 1 and 2 are the ones I would want resolved before this leaves draft — in both cases a gate reports success without having tested the thing it names.