Make the UK fiscal-event replay select a certified bundle

[MaxGhenis]

Refs #156 (track 1 rerun). This PR is infrastructure only. It lets the UK fiscal-event replay select a certified bundle, so the five track-1 events can be rerun on the next certified pair. That pair is uk-data 1.58.0 with policyengine-uk 2.125.1 and core 3.33.0, certified by PolicyEngine/policyengine.py#555 (merged) and published as policyengine 6.2.6. The PR registers no new bundle and computes no new results, and every existing output byte is unchanged.

What changes

• Bundle registry.

  • data/uk/certified_bundles/index.json maps a key to a pin file. Its only and default entry is populace-uk-2023__pe-uk-2.89.2 → the unchanged data/uk/certified_bundle.json (The pin follows the certified world — one rule, five registries #126).
  • pipeline/register_uk_certified_bundle.py writes a new pin from an installed policyengine.py release's packaged manifest and the cached HF artifact. It checks digest, size and model/core pins, and refuses any mismatch.
  • pipeline/export_uk_bundle_requirements.py exports the exact uk-extra freeze from a policyengine.py tag's uv.lock.

• --bundle KEY on every replay stage:

  • the stages: build, compute (including --dry-run), stage, compare (including --summary), adopt, Modal, model diagnostics and the construction audit;
  • non-default paths: registries go to data/uk/events/bundles/<key>/ and results to results/uk/events/bundles/<key>/;
  • isolation: every receipt binds the key, pin digest, dataset, model, core and loader versions, and year window, and a stage refuses another bundle's inputs.

• policyengine 6.x managed-loader adapter, alongside the 5.0.2 path:

  • resolves the HF model repo type;
  • checks the exact digest of the materialised runtime file before and after each simulation;
  • opens HDF read-only (no writable mirror);
  • falls back to the packaged certification when the network is blocked;
  • projects from the stored data year, which avoids the policyengine.py#557 trap.

  Each fact is checked against installed source in a source-hash-bound offline audit.

• Year windows from the pin. The window runs from the H5's own time_period to the engine's extension end. Earlier OBR cells stay in the accounting once as outside_bundle_window.

• Modal adapter takes its pins, HF cache path, freeze, audit, allowlist, outputs and window from the bundle. It keeps the resource caps, blocked runtime network, no forwarded credentials, and the pre-import and pre/post-simulation hash gates.

• pipeline/compare_uk_engines.py writes results/uk/events/ENGINE_COMPARISON.{md,json,csv}, plus full input-hash provenance.

  • Each row is one event × measure × head × source FY: OBR, PE(base), PE(new), the change, both bins, status, and the new/base ratio of the head's certified aggregate next to the measure's own ratio.
  • Attribution comes only from a hand-authored file with a closed driver vocabulary. Unsized drivers never enter an explained share.

• Paired synthetic diagnostics at both pins reproduce policyengine-uk #2237 / #2238 / #2239, the HICBC opt-out and the NICs threshold-freeze end date.

• Construction adjustment (non-default bundles only). When the engine's CGT rate parameters carry fiscal_year_blend metadata, processed CY2024 already blends in the 30 October 2024 increase. The AB2024 CGT reversal then restores the old rates from 1 January 2024, which turns the 2.89.2 timing gap into a computed part-year row. 2025 onward is unchanged. This is recorded as construction_adjustments in the registry.

Invariants (tested; pytest + Hypothesis)

• Default byte identity. The default bundle reproduces every existing registry, numerical receipt, staging, comparison and summary byte. The PR's validation reran all five registry --check runs, all five dry-runs, staging and comparison, --summary and the AB2025 checks.
• Bundle isolation. No stage accepts another bundle's registry, artifacts, manifests or receipts.
• Accounting across bundles. Per event, the source-row multiset and the exact Decimal net and absolute OBR £ are identical; only classifications and constructions may differ, and each difference is listed.
• Window. There is no computed row outside the pin's window, and each pre-window cell is staged exactly once.
• Engine comparison:
  • swapping base and new negates every change;
  • head changes sum to the measure change;
  • bins are invariant to a common positive scale;
  • no row is dropped or duplicated;
  • output is deterministic;
  • attribution is rejected when it is missing, outside the vocabulary, or sized without a hash-bound computed artifact.
• Existing replay invariants still hold: sign orientation, reversal involution, head sums, inert-construction blocking and determinism.

Validation

• Replay suite: 315 passed, 1 skipped (test_uk_event_*, test_modal_uk_event, test_uk_bundle_*, test_uk_engine_comparison, test_uk_replay_legacy, test_uk_ab2025_pipeline).
• Byte identity: re-ran all five default registry --check runs and default stage/compare/--summary; git status shows no tracked change under data/ or results/.
• Adapter checks on an already-certified bundle, published policyengine 6.2.5 (uk-data 1.56.16, policyengine-uk 2.102.3, core 3.32.10). These are adapter observations, not results.
  • Local: one baseline and one dated reform, run sequentially. The data sha256 was e433e532… before and after, the runtime source was the exact hashed file, and the network was blocked. Timings were 129 s and 95 s.
  • Remote: one Modal --preflight-only run with no simulation, 5.8 s.
• Nothing was computed on any uncertified pairing.

Not in this PR

Registering the 6.2.6 bundle (and the follow-up bundle that will carry policyengine-uk #2240–#2242), the five event reruns, the authored attribution and ENGINE_COMPARISON.md all come in the next PR. This one changes no app or DB build, so merging publishes nothing.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
policyengine-scorecard	Ready	Preview	Oct 10, 2026 1:50pm UTC

[MaxGhenis]

Independent review (GPT-6.1 Sol, read-only) of 61c13e3..93f2200: NEEDS-FIXES, eight findings. All eight are addressed in a858a69..a6d1bb5, plus one bug the review didn't cover. A delta review of the fix commits is running.

#	Finding	Fix
1 (blocking)	Staging CLI validated every registry against the default bundle	a858a69: pass --bundle; CLI-level test
2 (blocking)	An output path outside its own kind's root could overwrite another bundle's registry	f5cd310: every path is checked against both protected trees
3 (blocking)	Diagnostics --report bypassed the namespace guard	f5cd310: --output and --report validated before any work
4 (major)	A hash-correct dry-run artifact from another engine could size attribution	7284ef7: sized evidence must be in a verified run manifest and match that bundle's runtime identity
5 (major)	Overlapping sized drivers were added up	7284ef7: drivers can't cover the same heads of the same measured endpoints
6 (major)	Registering a new bundle changed earlier runs' Modal input commitment	bcd568c: only the selected bundle's index entries are mounted and hashed
7 (minor)	Construction audit asserted 2.89.2 CGT mechanics for 2.125.1	a6d1bb5: derived from engine source and dataset columns for non-default bundles
8 (minor)	Network block covered only socket.connect	3b7e1d3: DNS lookups and datagram sends are blocked too

Also 8c8ca52: the engine comparison read the Modal receipt's bundle identity at the top level, but the wrapper records it under request. Running the first real policyengine 6.2.6 comparison exposed this; the same runs exposed finding 1 independently.

Each fix has a test that fails without it. Full suite at a6d1bb5: 1568 passed, 1 skipped. Regenerating the default bundle's staging, comparisons and summary changes no tracked byte.