HMRC ready reckoner (mode 2): registry, offline compute, full-population triage

[vahid-ahmadi]

What's here

• data/uk/hmrc_reckoner_reforms.json — measure → reform registry covering the entire external reckoner population (75 (program, verbatim label) families from the committed data/externals/hmrc-personal-tax.json; a test pins registry == external vocabulary, so coverage gaps are labelled, never silent). Triage: 24 expressible / 22 partial / 29 not_expressible, each with a note. Registry stores deltas (absolute or relative), never absolute schedules — the reckoner's own construction is baseline-plus-illustrative-change, and the pipeline reads the live baseline value per year.
• Measure keys are program-prefixed (reckoner_202506__vat__change_standard_rate_by_1_percentage_point): HMRC prints the identical label under both VAT and IPT — the same defect class the UK externals → DB ingest path (16,924 claims, five sources) #48 review caught — and the label-only key collided exactly there; a validator defect list plus a duplicate-key test pin it.
• pipeline/compute_uk_reckoner.py — offline compute under the UK counterpart compute pipeline (managed sims, pe_gap-degrading registry) #51/OBR policy costings (mode 2): registry, offline certified compute, staging, descriptive comparison #56 conventions: managed sims on the certified bundle, one baseline per year reused across measures, per-run artifacts, staged JSONL under the campaign ingest contract (external_claim_match with the verbatim label as subgroup), signed PE delta plus the adapter's magnitude_with_direction_in_label orientation annotations (the pipeline never flips the external value). --dry-run validates the registry and, when policyengine-uk is importable, resolves every parameter path — a delta is never applied to a guessed parameter; any missing path demotes the whole measure to pe_gap.
• tests/test_reckoner_registry.py — 12 tests: whole-population join, slug rule, expressible⇒delta, rate deltas are fractions not percentage points, directioned labels carry matching delta signs, delta arithmetic, staged-row contract, engine-free import and dry run. Suite: 175 passed / 4 skipped; ruff clean.

Honest caveats

• Never executed against a managed environment — no certified populace-uk bundle on the authoring machine; the engine boundary is unverified and the docstring says so. The dry-run path gate exists so the first real run cannot silently compute against a wrong parameter.
• paths_verified: true marks only paths resolved by the OBR registry (obr-costings-mode2) against pe-uk 2.89.2 (PA amount, uk/dividends band thresholds); NICs, child benefit and rate-field paths are candidates flagged false and must resolve in --dry-run first. policyengine-uk was not installed at authoring.
• Registry is JSON, not YAML, deliberately: CI runs uv run --with pytest with no PyYAML, which is why OBR policy costings (mode 2): registry, offline certified compute, staging, descriptive comparison #56's pytest job currently fails on import yaml; this lane stays stdlib-parseable.

Builds #60.

🤖 Generated with Claude Code

[DTrim99]

Review — HMRC ready reckoner (mode 2) registry

Verified the core claims directly against the registry and data/externals/hmrc-personal-tax.json, and they all hold:

• Coverage: registry (program, label) set == external set exactly; test_every_external_reckoner_label_is_triaged pins reg == ext and fails loudly on drift. 24 + 22 + 29 = 75 ✓
• VAT/IPT collision resolved: program-prefixed keys are distinct (…__vat__change_standard_rate… vs …__insurance_premium_tax__change_standard_rate…); 0 duplicate measure_keys across all 75 ✓
• Delta-not-schedule: every delta is an increment (max abs 520 for UPL; rate legs 0.01); no absolute schedule or hardcoded baseline anywhere. Sign discipline holds; child-benefit spending sign flip handled at compute:1439 ✓
• Triage honesty: all 22 partial + 29 not_expressible carry a note; 0 expressible rows with a null delta (no over-claim) ✓

Should address (robustness nits, none blocking)

• test_rate_deltas_are_fractions (test_reckoner_registry.py:1533) relies on and binding tighter than or (path.endswith(".rate") or ".rates." in path and path.endswith((...))). It classifies today's paths correctly, but a future .rates.*.threshold leg ending in "main" would be miscaught — add parentheses.
• head_var dict (compute_uk_reckoner.py:1426) covers only income_tax / NI / child_benefit. All 24 expressible measures fall in those 3 programs today, but a future expressible measure elsewhere crashes with a bare KeyError rather than a pe_gap demotion — .get() + gap fallback would be safer.
• Baseline instant vs full-year window: baseline is read at {year}-06-01 (compute:1319/1433) while the reform is applied over {year}-01-01..{year}-12-31. Harmless for flat-year params, but relative deltas scale the mid-year read — worth a note.

Note

18 of 24 "expressible" measures have paths_verified: false — the --dry-run whole-measure resolution gate is the real backstop and is well-designed, but most expressible paths are still unverified guesses.

Reviewed with Claude Code assistance.

[vahid-ahmadi]

All three robustness nits fixed in the latest commit:

• Operator precedence — parenthesized: path.endswith(".rate") or (".rates." in path and path.endswith((...))); a future .rates.*.threshold leg ending in "main" is no longer miscaught.
• head_var bare KeyError — now .get() with a pe_gap demotion and a comment: a future expressible measure outside income_tax/NI/child_benefit stages a gap row instead of crashing the run.
• Baseline instant vs window — documented at the read site: identical for flat-year parameters (every current registry path), flagged for revisit if a step-mid-year path enters the registry.

On the note: agreed the --dry-run resolution gate is the real backstop for the 18 paths_verified: false measures — first action on a managed machine is the dry run, and any non-resolving path demotes its measure before a sim is attempted.

Suite: 175 passed / 4 skipped; ruff clean.

[DTrim99]

Re-review — all addressed ✅

• Rate-delta test precedence — the and clause is now parenthesised (.rate or (".rates." in path and endswith(...))).
• head_var KeyError — now .get(program) with an is None → pe_gap staged-row + continue, so a future expressible measure outside the three programs demotes instead of crashing.
• Baseline mid-year read — documented (identical for flat-year params; a relative delta on a mid-year-stepping param would scale only the 06-01 value — "revisit if such a path enters").

Coverage 75, VAT/IPT split, and deltas-not-schedules all still hold. Good to go.

[DTrim99]

Re-reviewed — all findings addressed (test precedence parens, head_var .get()+gap fallback, mid-year read documented). Approving.

[MaxGhenis]

Gate round 1 — the declarative triage is right; six findings, five blocking

The closed 24/50 declaration over the 74 distinct labels (VAT/IPT duplicate deliberate) is correct and matches the merged registry. The findings are in what happens at runtime:

1. Blocking — no safe disposition of the existing 14. As shipped the PR is inert (nothing in build_db), but wired in, all 14 FY2026-27 claim keys overlap the campaign attaches on main: 11 would shadow them via latest-result selection and 3 — savings allowance, dividend allowance, savings starting-rate limit — would regress to pe_gap despite exact executed paths already on main. Superseding staged campaign results is the exact Two-country catalog: UK seven-source harvest, campaign PE results, baselines registry (#13), descriptive register (#9) #32-class doctrine violation; this needs an explicit retained-vs-new reconciliation manifest with tests, preserving the 14.

2. Blocking — the compute is neither committed nor reproducible. The module notes it has never run in the managed environment; there are no artifacts, staged JSONL, manifest, hashes, or builder step, and the dry-run passed under ambient PolicyEngine-UK 2.75.3 while the registry prose references 2.89.2. Unpinned defaults on both simulations; only nullable baseline-side provenance is stamped.

3. Blocking — baseline honesty not encoded. The run executes current law while claims key hmrc_indexed_baseline_spring_2025, yet neither rows nor artifacts stamp baseline_key=current_law, and successes emit invalid status ok instead of constructed — the guard can't verify the executed world. (The merged campaign rows model this correctly: result current_law vs claim indexed, effective status constructed.)

4. Blocking — runtime contradicts the declared triage. Three acknowledged partial, missing-leg reforms carry deltas and pass the compute gate → 27 ok / 48 gap per year, not the declared 24/51. And both employer-NIC measures sum through national_insurance where the committed campaign artifacts establish ni_employer as the relevant head.

5. High — cited-gap and magnitude semantics missing. All non-expressible rows lack action links (the App design: public scoreboard + mission control, four views #9 gate), staging drops even the free-text note, and annotations omit the established abs(PE)/abs(HMRC) ratio and use a mapping where the ingest contract is string[].

6. Blocking — the staging shape can't ingest. Records use hmrc-personal-tax/revenue_effect/string-FY where DB claims are uk_hmrc/revenue_change/FY-end integers with exact conditions; computed_at and data_bundle are absent; and the campaign ingester rejects family reckoner. The registry validator is also year-blind, so missing or duplicated FY claims pass.

The path of least rework: treat the existing 14 as the anchor set, extend with the producer/claim_id-direct pattern (#72) for the new measures and years, and stage through the campaign contract rather than a parallel shape.

🤖 Generated with Claude Code

[vahid-ahmadi]

All six addressed in 63184b6, taking the path of least rework you suggested — the existing 14 as the anchor set, claim_id-direct through the campaign contract.

1. The existing 14. They are now the anchor set. Every (measure, year) resolves to exactly one ingested claim and is reconciled against them before anything is emitted: an anchored claim is retained and this lane emits nothing for it, and the reconciliation REFUSES to run if any of the 14 is unreachable. You were right about the three — savings allowance, dividend allowance, savings starting-rate limit — that would have regressed to pe_gap rather than merely being shadowed. The manifest records retained vs new and is testable.

2. Reproducibility. The registry pins policyengine-uk 2.89.2 and the run refuses any other version, on the import AND on the managed sim's own reported version — the dry-run passing under the ambient 2.75.3 proved nothing about the run's engine, agreed. The run writes per-measure artifacts plus a manifest carrying a sha256 over every artifact and the staged file. The run itself is still UK compute campaign, run 2: reckoner full-population compute (24 expressible measures × 3 forecast years) #77; what is fixed is that it can no longer be reproducible-in-prose.

3. Baseline honesty. Both keys are stamped, on the staged row and the artifact, so the guard can verify the two worlds differ, and successes emit constructed — ok is not a valid ComparisonStatus at all. Modelled on the merged campaign rows as you pointed out.

4. Triage. The three partial, missing-leg reforms no longer carry deltas — a partial multi-leg reform is a different reform from the one the label states — so the runtime is 24/51 as declared, the validator rejects a partial that carries one, and the declared triage is checked against the number of measures that actually carry a delta. Both employer-NIC measures read ni_employer via a registry field rather than a dict inside the runtime.

5. Gap and magnitude semantics. All 29 not_expressible measures carry an action_link, the registry's free-text note travels onto the staged row instead of being dropped, and annotations are a list of strings carrying the established abs(PE)/abs(HMRC) ratio, the sign convention, the CY/FY proxy and the basis mismatch.

6. Staging shape. claim_id-direct through the campaign contract, which needs no family normalizer; computed_at and data_bundle present. The validator is year-aware now: a missing or duplicated FY claim fails instead of passing.

Suite 272 passed, build deterministic, ruff format clean.

[vahid-ahmadi]

Follow-up on the engine pin, because I found a defect in my own fix and it is worth being explicit about.

I installed a real policyengine-uk 2.89.2 rather than reasoning about it, and the pin check I added was broken in the direction that matters least visibly: policyengine_uk exposes no __version__ attribute at all, so getattr(policyengine_uk, "__version__", None) read None, compared it to "2.89.2", and would have refused to run on the correct engine. A gate that always fires is not strict, it is unusable — and it would have looked like the pin working. Fixed in a2cde64: the version comes from importlib.metadata.version("policyengine-uk"), with __version__ kept as a fallback if a future release adds one.

With that fixed the dry-run actually runs against the pinned engine, which is the thing this PR could previously only claim:

[    0.0s] registry valid: 75 measures
[    1.0s] dry run complete: no sims, no output

• all 24 delta-carrying measures' parameter paths resolve against the live tree — no unresolved paths;
• the pin gate is confirmed live: bumping the registry pin to a fake version refuses with the installed version named;
• reform values are plausible against real parameters (employer NI rate 0.15, personal allowance £12,570 at 2026) — no sign flips, no runaway relative deltas, nothing going negative;
• both employer measures read ni_employer.

So finding 2's "reproducible" claim is now evidenced up to the engine boundary. The managed run itself is still #77.