Re-measure UC composition errors after first calibrated run; element references still unsourced

[vahid-ahmadi]

The UK contract carries 30 UC target ids; the national calibration activates 1 of them. 29 are declared, mapped and inert.

uk/uk_national_targets.json — 30 dwp.uc.* ids of 187 total, split evenly:

dwp_universal_credit   15   (households, 4 family types, 5 child counts, payment bands, Scotland)
dwp_two_child_limit    15

uk/target_references.json — 15 references, of which UC is:

dwp.uc.households            period=2025  entity=benunit  measure=dwp/uc/households
obr.universal_credit_in_cap  period=2025  entity=benunit  measure=obr/universal_credit_in_cap

So national_calibration.py calibrates UC on one caseload count and one expenditure aggregate. The family-type and child-count composition is unconstrained, and this is where the error actually sits (policyengine-uk-data, enhanced FRS 2023-24 v1.56.16, 2025):

Target	Model	DWP	Err
dwp.uc.households (activated)	6.395m	6.700m	-4.6%
households_single_no_children	3.210m	2.868m	+11.9%
households_couple_no_children	0.280m	0.231m	+21.1%
households_children_3	0.369m	0.473m	-22.0%
households_children_4	0.136m	0.167m	-18.3%
households_children_5_or_more	0.064m	0.076m	-16.2%

The one activated count is the best-fitting number in the set. Activating the composition rows is what moves the double-digit errors.

Blocker on the two-child limit half: all 15 dwp_two_child_limit ids resolve to targets that are structurally zero from 2026-04-06 (limit abolished, Budget 2025). See PolicyEngine/policyengine-uk-data#465 — activating them before that lands would calibrate against zero.

Not a defect, checked: the payment-distribution many-to-one mapping is correct — dwp.uc.payment_distribution_* carries groupby_dimension: dwp.uc_monthly_award_band, so the per-band uk-data names collapse to one banded id by design.

Next steps

1. Activate the 4 family-type and 5 child-count references at period 2025, alongside the existing dwp.uc.households. Needs the chronicle facts for those ids.
2. Keep the 15 two-child-limit ids deferred until uk-data#465 moves them to 2025.
3. Element-level references (housing, LCWRA, carer, childcare) have no contract ids at all yet — they land here only after uk-data#466 adds the targets upstream.

cc @MaxGhenis @vahid-ahmadi

[juaristi22]

Mapped against #735 (now rebased onto main with the post-chronicle#184 feed): the activation gap this issue measures is closed by that PR — the 15-reference file analyzed here was the #729-era surface, which #735's regeneration replaces with 388 active references.

Per next-step:

1. Family-type + child-count references: done in Complete #622: compile the UK target surface from Ledger facts at the 2024-25 line #735. All nine composition references are active at period 2025 (households_{single,couple}_{no,with}_children, households_children_1..5_or_more) plus Scotland under-1 — the chronicle facts existed (DWP monthlies at 2025-05); only the pre-Complete #622: compile the UK target surface from Ledger facts at the 2024-25 line #735 references file predated them. dwp.uc.households itself now compiles with the adjudicated calendar_year_average over the Add proximal L1 solver path #184 caseload series: 6,758,889 vs DWP's 6,700,000 (+0.9%, signed). The payment bands are 100 active fan-out references (matching the many-to-one check above).
2. Two-child limit: activated at period 2025, where the limit is in force — the uk-data#465 blocker applies at 2026, not 2025. Our references bind the April-2025 publication facts at 2025 (FY 2025-26), so the targets are real and nonzero; it is the incumbent's {2026} pinning that is structurally dead. The 2026 retirement (abolition, Budget 2025) plus a structurally-zero guard test are registered as microcosm#736 item 11.
3. Element-level targets: still open, and now planned — no contract ids exist because no facts exist anywhere upstream. Pipeline: chronicle facts first (requested as UC element-count and monthly composition facts for the microcosm UK target surface chronicle#187 — childcare's published 160k series needs no API key; housing/LCWRA/carer need Stat-Xplore UC_Households), then a contract amendment per the Refresh the UK Universal Credit target contract #727 precedent, then references activate automatically. Registered as microcosm#736 item 12, alongside the monthly split history that makes the family-type values sum-consistent with the caseload average (this issue's vintage-tension note).

What activation alone does NOT fix: the model-vs-DWP error table above comes from a calibrated release — those numbers move only when a calibration run binds the new surface (the #729 stage consumes all 388 references; run-readiness is the narrowed #623). Suggest keeping this issue open to re-measure the composition errors after the first calibrated candidate, with the remaining scope being that re-measurement plus item 3.

[vahid-ahmadi]

Verified against main and agreed — items 1 and 2 are closed by #735. Confirming what I checked:

target_references.json (main): 397 references total
  dwp.uc.*        : 26, all period 2025
  two_child_limit : 15, all period 2025
  composition     : households_{single,couple}_{no,with}_children,
                    households_children_1..5_or_more, scotland_households_child_under_1

You are right on point 2 and I was wrong to call uk-data#465 a blocker here: binding the April-2025 facts at 2025 sidesteps the abolition entirely, so nothing on this side is gated on it. #465 is a standalone defect in the uk-data registry (sources/dwp.py:209-303, still {2026} on main) and I have corrected my cross-link there.

One clarification for anyone reading the table in the issue body: your 6,758,889 vs 6,700,000 (+0.9%) is the compiled target value; the -4.6% in the table is the model estimate against that target. Both are right, they measure different things, and only the second is what a calibration run moves.

Agreed on keeping this open to re-measure after the first calibrated candidate. Narrowing scope to:

Remaining

1. Re-measure the composition errors (+11.9% single-no-children, +21.1% couple-no-children, -22.0% 3 children, -18.3% 4 children, -16.2% 5+) once a run binds the 397-reference surface. Gated on the narrowed Calibrate the UK national build from Ledger-backed targets #623.
2. Element references — chronicle#187 → contract amendment → auto-activation, per WS-C deferred adjudications and the reconciliation layer #736 item 12.

cc @MaxGhenis @vahid-ahmadi