Align UK UC claim, child and period definitions

This consolidates the remaining UC consumer-contract questions from #736 and #738, following the benefit-unit corrections in #727 and #813. It supports the UC investigation alongside #879 and #701; SPI generation remains tracked in #840. The evidence below is limited to public repository code and published aggregate source tables.

Reproducible discrepancies

Paid versus all claims. The current contract at eb7ca8a5 counts universal_credit > 0 against all-claim headline/composition rows. The pinned family × payment-indicator source has 90 cells: five family categories × Yes/No × April–December 2025. Summing the five family cells within each month, then averaging the nine months, gives 6,316,227.78 paid and 542,059.89 nil-payment claims. DWP explicitly retains some open claims with no payment. These quantities cannot be treated interchangeably. (Payment indicator definition)
The required joint is unavailable. The pinned feed contains family × payment indicator, family × child entitlement and child count × child entitlement. It does not contain payment indicator × child entitlement, or payment indicator × child count. Therefore pairwise margins cannot identify the paid/child-entitled composition joint. Child Entitlement Yes also does not turn the reported child-count axis into a count of qualifying children. Chronicle #233 and #234 closed the earlier ingestion requests; the remaining consumer alignment is still necessary.
Monthly cash and annual model payments differ in timing. The unresolved bridge is to DWP's monthly payment amount, which includes third-party payments and one-off advances in their issue month. Dividing an annual model award by 12 does not establish that equivalence, especially for rare upper-band cells. (DWP amount definition)
Observation periods need an explicit comparison contract. The public April–December 2025 series has nine monthly observations; the TCL methodology covers open claims during April and a 6 April 2017 birth cutoff. It includes exceptions and distinguishes its dependent/qualifying-child definition from the broader verified under-20 children reported on Stat-Xplore. A source April snapshot, a nine-month average and an annual model state need separate labels and a documented comparison.

Acceptance criteria and ownership

Microcosm: declare and test each target's claim state, benefit-unit/child definition, geography, amount basis and source/model observation periods. Preserve separate all-claim, paid and nil-claim diagnostics; do not blindly rebind all-claim targets to paid margins.
Microcosm: enforce the declared source-month set and record the actual averaging denominator. Retain April snapshot dates separately from annual assignment.
Microcosm: establish the age/cohort anchor across the source year, model year and source observation date; preserve its provenance and test year transitions. If exact birth dates or open-claim state are unavailable, record the approximation and its sensitivity.
Microcosm, with PolicyEngine-UK where model inputs are required: test TCL claimant roles, own qualifying children, exceptions and element denial separately, including nil-payment claims, 18–19-year-olds, multiple benefit units in one dwelling and the birth-date boundary. Claimant PIP and disabled-child elements must refer to the relevant claim's members.
Microcosm: support only identifiable joints. Do not construct a joint from marginal products or rename reported children as qualifying children. Chronicle owns any additional publisher cross export.
Microcosm: reconcile the headline and family cells using a common-vintage published total, unknown-family cells and disclosure tolerances. Chronicle #247/PR #250 owns the published-total/history feed update; the consumer comparison remains a Microcosm responsibility.
Microcosm: audit joint support by reported-child count, own qualifying-child count, birth cohort, family roles and claim/payment state. Trace missing or thin cells through source stages before choosing generation changes; retain original-source lineage in diagnostics.
Microcosm: compare repairs at a fixed optimizer budget and report target-specific original-source support, source contribution and leave-one-source-out sensitivity alongside global concentration and convergence. Do not alter target values or exclusions solely to improve fit.

Consolidating #701 and #738 into this issue as superseded. Their remaining work is tracked here; closing them does not mean UC fit or certified consumer acceptance is complete.

The caseload/composition bindings, paid-source and observation-window repairs, and the retained/fresh candidate comparison have landed in #883, #891 and #892. The merged diagnostics and paid-target contract record both those results and the remaining limitations.

Additional scope carried forward:

UC expenditure comparability — from Certified UK artifact carries less than half of admin UC caseload (3.26m vs ~6.7m; £36.9bn vs £75.8bn) #701. Establish a comparable model-to-OBR UC expenditure measure, including the welfare-cap inclusion/exclusion split, geography, calendar/fiscal period and the distinction between entitlement, deductions and cash payments. The current OBR UC expenditure split remains explicitly excluded because its welfare-cap inclusion is not measured correctly. Correct and validate the measurement contract before activating it; the historical expenditure comparison in Certified UK artifact carries less than half of admin UC caseload (3.26m vs ~6.7m; £36.9bn vs £75.8bn) #701 is not evidence that the current candidate passes.
Certified consumer acceptance — from Certified UK artifact carries less than half of admin UC caseload (3.26m vs ~6.7m; £36.9bn vs £75.8bn) #701. Produce a passing calibrated export and certified replacement, record its code/model/data pins and declared solve configuration, and verify adoption by the intended downstream consumer(s). Report UC counts and comparable expenditure on that consumed artifact. The development comparison and passing software CI do not replace the older certified artifact or satisfy this acceptance step.
Re-measure UC after the remaining repairs — from Re-measure UC composition errors after first calibrated run; element references still unsourced #738. Repeat the controlled comparison once the remaining claim, child, period and support work in this issue is complete. Use common target definitions and a fixed, declared optimizer budget; report headline, family/child composition, TCL and payment-band fit, plus element results as comparable bindings become available. Include original-source support, concentration, convergence and effects on other target families. This is the follow-through measurement for the remaining implementation work.
Carry forward Re-measure UC composition errors after first calibrated run; element references still unsourced #738's outstanding element integration. Housing, LCWRA, carer and childcare count bindings still need comparable source categories, windows and claim/payment states. Chronicle Add opt-in US congressional district fiscal targets #187/Assign US congressional districts from Ledger facts #188 already supplies element series, so the old “still unsourced” description is stale. Available housing facts cover social renting; LCWRA facts cover the Higher category; childcare ends in August 2025; the other three series cover April–December 2025. Validate those scopes, request only missing coverage, and implement/test the corresponding bindings. A paid-by-child-entitlement cross does not establish a paid-by-element cross. No calibration targets for UC elements: childcare runs 2.3x official, housing/LCWRA/carer unbenchmarked policyengine-uk-data#466 remains unchanged as the legacy companion.

The two positive-target, childless-couple payment cells with zero model records remain documented export blockers. Stage/component tracing should establish where that support is lost or absent; remeasurement must continue to report them explicitly. The remaining age/interview provenance and unavailable claim/cohort states also remain open under this issue's existing criteria.

SPI generation (#840), household relationship-to-head (#791), and the broader scorecard (#731) retain their existing scope. The #736/#796 parent checklists record completed increments separately from the work still outstanding here.

Recording the UC measurements on the 10 September rebuild against this issue's acceptance items. This is a measurement record at the current pins, not a certification and not a change to any target or exclusion.

Baseline. Spine-q on main 0afb1235 (after #881, #883, #891, #892, #877, #889), Chronicle feed ec7169b (facts 4a50ee95…), PolicyEngine-UK 2.97.0, joint local+national surface (20,794 rows: 364 national, 20,430 local), doctrine grain_equal, 2,000 epochs, learning rate 0.15, maximum weight ratio 10, target loss cap 10. Two files: Q50f, the 55k L0 candidate with the floored Horvitz–Thompson refit baseline (--baseline-pi-floor 0.001, branch uk-55k-rebuild-2026-09-10, not yet on main), and D2, its dense twin (792,690 rows, same seed). Evaluation page: https://uk-dataset-evaluation.vercel.app/55k-rebuild-2026-09-10/ (receipts in experiments/355-uk-dataset-size-receipts.md on that branch). Numbers below are relative_error from each run's calibration_diagnostics.json unless stated.

Ten broad paid-claim rows (CY2025 targets from #891). Compare the #892 fresh build: headline −4.71 %, lone parents −14.01 %, one child −19.45 %.

row	target	Q50f	D2
`dwp.uc.households`	6,197,311	+2.80 %	+2.99 %
`…single_no_children`	2,990,070	+1.90 %	+1.85 %
`…single_with_children`	2,138,780	+2.08 %	+3.84 %
`…couple_no_children`	241,131	+0.76 %	+2.25 %
`…couple_with_children`	826,161	+8.71 %	+5.26 %
`…children_1`	1,190,124	+0.03 %	+0.03 %
`…children_2`	1,049,896	+8.38 %	+9.23 %
`…children_3`	477,888	+6.13 %	+5.57 %
`…children_4`	170,714	−0.38 %	+0.97 %
`…children_5_or_more`	76,320	−0.67 %	−0.11 %

Other bound UC rows. All 15 two-child-limit rows within 2.03 % on both files (Q50f worst −1.45 %, D2 worst +2.02 %). Scotland child-under-one −0.97 % / −0.41 %. Benefit-cap capped households −0.03 % / +0.08 %. The 82 bound payment bands are all within 4.34 % (Q50f) / 5.08 % (D2). In total 105 of the 108 bound national UC rows are within 5 % on Q50f (D2 104), none past 10 %.

Excluded payment bands (measured by the incumbent-surface evaluator, not fit). The three childless-couple bands from £26,400 upward remain at −100 % on both files: zero model records. Of the 16 bands excluded under uk-data#452, seven are within 25 % on both files: lone-parent £12,000–13,200 (+14.7 % / +10.9 %), £13,200–14,400 (−15.7 % / −3.2 %), £14,400–15,600 (+10.2 % / +3.9 %), £15,600–16,800 (−10.7 % / −12.6 %), £16,800–18,000 (+14.1 % / +11.7 %), single £9,600–10,800 (+13.9 % / +2.1 %), and the HMRC self-employment count at £500k–1m. D2 alone adds lone-parent £18,000–19,200 (−6.9 %) and single £14,400–15,600 (−15.9 %). The rest stay 26–143 % off. No retirement is proposed here.

Local UC rows (constituency and local authority, 3,508 rows). Q50f 99.29 % within 10 %, 100 % within 25 %, worst 15.6 %; D2 99.40 % / 100 % / 12.6 %. The childless bucket (…children_0) is the weakest inside the family (60.6 % within 5 % against 93–95 % for the child buckets).

Expenditure. The OBR in-cap / outside-cap rows stay excluded and measure −96.7 % / +503 % on both files. Their sum (£79.29bn, FY2025/26) against the model's total UC: Q50f £80.38bn (+1.4 %), D2 £80.82bn (+1.9 %); enhanced FRS 1.57.3 £75.85bn (−4.3 %). No total row is bound yet; the feed has no total concept.

Element counts (not bound; measured on Q50f at its calibrated weights, Great Britain, benefit units with universal_credit > 0, against the April–December 2025 means of the DWP all-claims series in the feed).

element	model, paid UC	published mean	gap
LCWRA entitlement (`uc_LCWRA_element > 0`)	2.62m	2.42m	+8 %
deductions (`uc_deductions > 0`)	2.99m (46.6 % of paid)	3.0–3.1m (46–47 %)	≈0 %
housing element, any tenure	4.01m	4.30m	−7 %
housing element, social rented only	2.35m	not in the feed	—
carer element	0.60m	1.13m	−47 %
childcare element	456k (£2.06bn)	184k Jan–Aug 2025 (≈£0.8bn)	+148 %

Two readings that matter for the element bindings: the feed's housing series is labelled Social Rented Sector but its package evidence note and archived query group tenure codes 1+2+3 into one cell, so it is the all-tenure count; and the T4 admin legs on the evaluation page measure elements without conditioning on a UC award, which is why they show LCWRA at +216 % (7.29m unconditioned) and carer at +5 % (1.14m unconditioned). Nil-payment open claims cannot be identified in the model (would-claim ∧ eligible ∧ positive maximum gives 14.3m units), so element rows will need the element × Payment Indicator crosses to bind on paid claims like the ten rows above.

Downstream legs against enhanced FRS 1.57.3. T5 "UC taper to 20 %": Q50f −35.4bn, D2 −34.9bn against an expected −17.2 ± 15 (eFRS −22.6bn), the one reform the whole microcosm family misses. T6 Resolution Foundation UC: 13 ok / 14 flagged, closer on 8 of 10 benchmarks; UC expenditure on the 2029-30 basis £91.1bn against RF's £86bn; mean monthly UC childcare element £636 against RF's £420. T6 childcare: UC childcare element £2.15bn against a £0.81bn benchmark.

Support and concentration. Q50f Kish ESS 16,785 (0.305 of 55,000), max/median weight 57, household mass 29.07m (−0.6 %); D2 Kish ESS 130,504, max/median 296 (fails the reviewed 100 ceiling), mass 29.15m (−0.3 %). Q50f fails the per-area support gate (643 of 650 constituencies under ESS 50); neither file is shippable. Protected non-UC rows on the joint solve: income tax −19.4 % / −19.6 %, NI −3.9 % / −3.9 %, state pension −20.2 % / −13.9 %, child benefit +23.0 % / +21.1 %; the ONS lone-parent-with-dependent-children household row +21.9 % / +19.0 %. Whether the UC rows or the local surface move those cannot be read from these receipts.

Against the acceptance items.

Re-measure after the remaining repairs (from Re-measure UC composition errors after first calibrated run; element references still unsourced #738): this record is that measurement at the current pins; the ten broad rows, TCL and bound bands are within tolerance, the three zero-support bands and the with-children overshoots (+5 to +9 %) remain.
Expenditure comparability (from Certified UK artifact carries less than half of admin UC caseload (3.26m vs ~6.7m; £36.9bn vs £75.8bn) #701): the total is within 2 % of the OBR sum; the welfare-cap split is still not representable; no contract change yet.
Element integration (from Re-measure UC composition errors after first calibrated run; element references still unsourced #738): the series are in the feed and unbound; the sizing above stands in for the diagnostic comparison; binding on paid claims needs the Payment Indicator crosses and a relabel of the housing series (Chronicle issue to follow).
Age/cohort provenance: the FRS birth-date fields in the delivered files are blank; the April-observation approximation documented in the paid-target contract stands.
Certified consumer acceptance (from Certified UK artifact carries less than half of admin UC caseload (3.26m vs ~6.7m; £36.9bn vs £75.8bn) #701): not addressed by either file.

Next: one Chronicle issue for the crosses, the housing relabel and tenure split, a childcare amount series, an earnings indicator and the Housing Benefit caseload; then one microcosm PR carrying the floor-knob commits, the element contracts on the new feed and an OBR total binding.

Bind the UC element targets on paid claims and an OBR UC total on the…

Address review round 1 on #921: hold the any-tenure housing row out o…

Bind the UC element targets on paid claims and an OBR UC total on the…

Merge pull request #921 from PolicyEngine/uk-uc-elements-882

Status after #921 merged (2026-09-15, 4ec72078). The eight acceptance boxes above and two of the four carried-forward items are ticked; here is what each rests on, and what is still open, in clock order.

Ticked, with evidence

Claim state, benefit-unit/child definition, geography, amount basis and periods declared and tested; all-claim, paid and nil diagnostics kept separate — Correct UC measurement contracts and calibration iterate selection #883 and Align national UC targets with paid claims and explicit source windows #891 (docs/uk-uc-paid-target-contract.md, uc_paid_comparison_contract, the 39 paid diagnostic masks, the 11-region GB condition on every DWP row); Bind the UC element targets on paid claims and an OBR UC total on the chronicle 474a0ae feed (#882) #921 extends the same contract to the element rows.
Declared source-month sets with the averaging denominator recorded; April snapshots kept apart — Align national UC targets with paid claims and explicit source windows #891 (uc_source_periods.py; test_uk_uc_source_periods.py pins every shipped window, 118 monthly UC references after Bind the UC element targets on paid claims and an OBR UC total on the chronicle 474a0ae feed (#882) #921).
Age/cohort anchor — recorded as an approximation with its sensitivity, because the delivered FRS carries no birth dates (docs/uk-uc-882-diagnostics.md, the interval sensitivity and the TCL receipt's date/period proxies). Not improvable from source; year-transition tests ride the policy-year rule work (Declare survey- and calibration-year rules for UK FRS parameter reads (#862) #881).
TCL claimant roles, own qualifying children and denied-element flags tested separately; the PIP and disabled-child rows fit within 2 % on Q50f/D2 (test_uk_uc_relationships.py, test_uk_uc_target_measurements.py). Unobservable in the model and documented as such: open nil-payment claims (open_nil_claims_identified: False), TCL exceptions (included by construction), the birth-date boundary.
Identifiable joints only — the ten broad rows bind the family × payment × child-entitlement crosses (Add UK source packages for #251 and #253: UC payment indicator × child entitlement crosses (April 2023 to May 2026) and Scotland's council-area household total on the households spec chronicle#252), the element rows the element × Payment Indicator crosses (Add the UC element, employment, Housing Benefit and childcare packages issue 259 asks for chronicle#260); no constructed joint.
Headline and family cells reconciled on the common-vintage total with unknown-family cells and disclosure tolerances (paid-target contract: 6,197,311 including 1,168.92 unknown-family; child-count totals within 1.17 claims; largest residual 8); UK source package: publish the Stat-Xplore UC_Households family-type Total row as its own monthly fact (April–December 2025 onward) chronicle#247 closed by Add UC family type totals from 2023 chronicle#250.
Joint support audited by child count, qualifying count, cohort, roles and claim state with lineage — Repair UC capital graph inputs and document calibration support gaps #892's diagnostics and tools/diagnose_uk_uc_{matrix,support,lp_evidence}.py; Bind the UC element targets on paid claims and an OBR UC total on the chronicle 474a0ae feed (#882) #921's tools/diagnose_uk_uc_elements.py adds the element side.
Repairs compared at a fixed budget with support, concentration and convergence, no target or exclusion edited to improve fit — Repair UC capital graph inputs and document calibration support gaps #892's six arms; the Q50f/D2 record above; Bind the UC element targets on paid claims and an OBR UC total on the chronicle 474a0ae feed (#882) #921 binds new rows without moving any existing value.

Carried forward: UC expenditure comparability ticked — obr.universal_credit binds the sum of the two OBR cells (+1.4 % Q50f, +1.9 % D2); the welfare-cap split is declared not representable and stays excluded to 2026-11-26. Element integration ticked — housing (any tenure, social, private), LCWRA, carer, childcare and deductions bound on paid claims; carer, childcare and the any-tenure row on the register to 2026-10-15 pending their repairs.

Still open, in clock order

2026-10-03 — the A16 legacy rows (UK spine: housing benefit £2.7bn against OBR £12.1bn — pensioner and supported-accommodation HB missing after the UC migration #867 housing benefit, UK spine: JSA claimants 2.8× the DWP caseload — legacy-benefit reporting after the UC migration #869 JSA). Re-adjudicate before they lapse, with the mechanisms found: the 55 % would_claim_uc draw zeroes half the HB reporters through housing_benefit_eligible; claims_all_entitled_benefits collapses to a scalar; non-head benefit units get rent 0; UC and HB cannot coexist; dwp.jsa_claimants counts contributory JSA only; the stage-6 legacy proxies feed nothing. The new HB caseload facts (dwp.housing_benefit_claimants by client type and tenure, accommodation type from September 2025) can bind as diagnostics in the same PR; the two ESA count rows (−12 % / −16 %, +14 % / +6 %) belong in the same tracking.
2026-10-15 — the element register (Bind the UC element targets on paid claims and an OBR UC total on the chronicle 474a0ae feed (#882) #921). Carer: ingest FRS care hours into the engine's care_hours and a carer condition from 35 hours a week or CA receipt. Childcare: a take-up stage modelled on uc_deduction_attributes, drawing to the published 160–193k. Any-tenure housing: structural (the model has no other/unknown tenure), so a standing diagnostic or a dropped row. LCWRA: decide whether the is_disabled_for_benefits passthrough warrants an engine issue (the row fits at +15 % / +20 %).
2026-11-26 — the OBR split and the uk-data#452 bands. Retire the two split targets now that the total is bound, or renew; rule on the seven excluded bands within 25 % on both files (D2 nine).
2026-12-08 — the three zero childless-couple bands. Stage trace of the 20 high-maximum copies, the amount-concept note (advances, third-party payments), then keep excluded, consolidate the top bands into one open band by a declared sum, or generate support.
With-children overshoots (couple_with_children +8.7 %, children_2 +8.4 %, children_3 +6.1 %) and the ONS lone-parent row (+22 %): UK spine: composition-faithful SPI income draw — bridge predictors and rank-preserving replacement (with-children UC residual) #840 and the post-Add the frs_relationships UK spine stage and rebind the ONS household-composition cells (#791) #903 re-measure.
Claimant income shape (UC taper reform −35bn against −17 to −23): UK spine: composition-faithful SPI income draw — bridge predictors and rank-preserving replacement (with-children UC residual) #840; the new dwp.people_on_universal_credit employment-indicator facts can bind as a diagnostic beside the 51.6 % of paid units with earnings.
Re-measure after the repairs (carried item) and certified consumer acceptance (carried item): the latter needs a shippable candidate (the size work and the area-support floor) and the local grain regenerating on UK local target surface cannot compile since #855: sub-national geographies have no hierarchy label (needs chronicle geography.name) #920 now that Emit geography.name on consumer facts so Microcosm's hierarchy can label sub-national geographies (constituencies, local authorities and regions) chronicle#266 shipped. Align UK UC claim, child and period definitions #882 closes when the consumer adopts the artifact and reproduces the UC readout.

Next steps, as ticke-able items (no separate issues; this list is the record)

Key the UC element register rows by reference name so the calibration…

Re-adjudicate the A16 legacy rows, gate the UC draw by State Pension …

Draw the UC childcare-element take-up by family type in frs_take_up (#…

Join the benefit-cap support count on the engine's float32 household …

Record the control twin and the control-versus-repaired receipts (#882)

Record the U8 population ruling: the rate stays over units with a wor…

Regenerate the H2 fixture after the take-up contract edits; give the …

Fill care_hours and the carer take-up input from the FRS; raise the e…

Re-derive the carer take-up flag from the refilled Carer's Allowance …

Retire the carer and childcare element register rows on the 2.98.0 tw…

Record the repairs against the 10 September baseline; regenerate the …

Record the rebuilt 2.98.0 twin: Carer's Allowance unchanged, carer el…

Regenerate the national references and compile-parity receipts on the…

Regenerate the local references on the df35af7 feed: the Housing Bene…

uk: register adjudications cite the ruling that exists

uk: review round 1 on the #882 repairs

uk: CI fallout of review round 1 on the #882 repairs

Regenerate the derived surfaces on the ec20085 feed after rebasing over

Merge pull request #937 from PolicyEngine/uk-uc-repairs-882

Merge origin/main (d1196af) into the US launch integration branch

Address review: re-pin the approved uv.lock digest, pin the ONS looku…

Navigation Menu

Repository navigation

Align UK UC claim, child and period definitions #882

Reproducible discrepancies

Acceptance criteria and ownership

16 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Align UK UC claim, child and period definitions #882

Description

Reproducible discrepancies

Acceptance criteria and ownership

Activity

juaristi22 commented on Sep 9, 2026

juaristi22 commented on Sep 11, 2026

juaristi22 commented on Sep 16, 2026

16 remaining items

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions