Align Child Benefit claim exports and opt-out draws with the UK model

changelog.d/uk-child-benefit-registered-claims.fixed.md

@@ -0,0 +1 @@
+Preserve registered Child Benefit claims for opt-out-aware UK models and restrict opt-out draws to families whose charge meets the installed payment-suppression threshold, recording any pool shortfall. Keep the original draws and payment flags for older engines, and record the export contract and evaluated threshold in stage receipts.

docs/uk-child-benefit-claim-contract.md

@@ -0,0 +1,66 @@
+# Child Benefit claims and payment opt-outs
+
+The `child_benefit_take_up` stage draws registered claims and payment opt-outs
+separately. Registered claimants include families that opt out of payment.
+`would_claim_child_benefit` must retain that registration for the model to
+restore payment when a reform removes or sufficiently reduces the High Income
+Child Benefit Charge. See [policyengine-uk#2140](https://github.com/PolicyEngine/policyengine-uk/pull/2140)
+and [policyengine-uk#2065](https://github.com/PolicyEngine/policyengine-uk/issues/2065).
+
+The stage supports two installed-engine contracts:
+
+| Installed model | `would_claim_child_benefit` export | Receipt encoding |
+| --- | --- | --- |
+| Exposes `gov.hmrc.child_benefit.opt_out_charge_share` | Registered claims, including payment opt-outs | `registered_claims` |
+| Does not expose that parameter | Claims excluding payment opt-outs, preserving the older model's payment behavior | `legacy_payment` |
+
+The capability and actual `opt_out_charge_share` value are read from the installed
+model's parameter tree alongside the charge thresholds at the build year's
+January 1. The stage receipt's `claim_export` records the selected encoding,
+capability and engine parameter source, including its package version;
+`opt_outs.opt_out_charge_share` records the evaluated share, or `null` for legacy
+models. A present but nonnumeric or nonfinite share is rejected.
+This avoids guessing the version number of the release containing #2140 and
+keeps the currently locked older engine compatible. Both ordinary spine builds
+and graph replay reconstruct the same stage transform and read that boundary.
+
+For opt-out-aware models, the draw selects only claiming nonreporters whose
+charge fraction is positive and at least the installed share. With the default
+share of one, only fully charged families can opt out. If that pool cannot carry
+HMRC's target, `pool_shortfall_families` and `pool_exhausted` record the shortfall;
+the stage does not fill it with families the model would pay. A lower share can
+admit taper families; share zero still excludes incomes at or below the charge
+start, and a share above one leaves the pool empty. Fully charged candidates
+retain priority. Equal or reversed taper endpoints remain unsupported by the
+build boundary (`0 < start < end`); the stage does not infer a cliff rule.
+
+Older models retain the original draw: fully charged families first, then taper
+families for any remainder. Neither contract opts out reporters or nonclaimants,
+and units without eligible children keep their early claim draw. Identity-keyed
+random draws and claim-rate solving remain unchanged.
+
+The stage's `claims`, `opt_outs` and `in_payment` statistics describe the draws
+against HMRC targets. `in_payment` counts claims excluding drawn opt-outs, whose
+selection now matches the installed baseline payment-suppression rule. It does
+not rerun the model to measure cash payments. Synthetic exported-dataset tests
+check paid-family and paid-child counts and payment amounts against the model;
+they do not establish the population fit after this changed draw.
+
+Use a model containing #2140 and regenerate the Child Benefit stage to produce
+the registered-claim contract. Updating model code alone does not migrate old
+Microcosm exports: their false claim flag may mean an opted-out registered
+family. A migration must establish producer provenance and registration first.
+Never infer claims by OR-ing the flags in the UK model: EnhancedFRS draws
+opt-outs independently, so false/true can instead mean a genuine nonclaimant.
+EnhancedFRS remains compatible with the UK model's independent claim gate.
+
+Code CI uses synthetic frames; it does not rebuild or certify population data.
+Existing releases retain their original recorded model/data contract until a
+separately authorized rebuild and publication.
+
+Rollout belongs with the engine-upgrade work in [Microcosm #1095](https://github.com/PolicyEngine/microcosm/issues/1095):
+
+- Upgrade the model and rebuild the Child Benefit stage and exported data.
+- Inspect the explicit opt-out pool shortfall at the build's weights.
+- Compare before/after model-paid families, children and payment amounts.
+- Measure the actual `obr.child_benefit` fit before approving calibration or release.

packages/microcosm-build/src/microcosm/build/uk/release_input_coverage_manifest.json

@@ -468,7 +468,7 @@
    "required_mass_change_reason": "Capital-gains incidence anchor moves the mass of non-liable clone households back to their paired originals until the sub-exempt and loss-making clone mass match the Advani-Summers reporter composition at the redrawn liable mass; every pair's mass and the total household mass are conserved.",
    "rewrites": [],
    "source_manifest": "source_stages.json",
-   "source_manifest_sha256": "a89e2dad9d75768af47a394cab197e3115f18fe3a82efda12d8f22321359438e",
+   "source_manifest_sha256": "c2e14142c3875d31646674bf62fd2c5bb17bd47fc98ea6a1952fed224704f7a7",
    "source_vintages": {
     "source": "Advani and Summers (2020), Capital Gains and UK Inequality, CAGE Working Paper 465",
     "survey": "Family Resources Survey 2024-25, SPI synthetic support, the HMRC Table 3 redrawn gains on the spine and Advani-Summers capital-gains incidence"
@@ -491,7 +491,7 @@
     "capital_gains"
    ],
    "source_manifest": "source_stages.json",
-   "source_manifest_sha256": "a89e2dad9d75768af47a394cab197e3115f18fe3a82efda12d8f22321359438e",
+   "source_manifest_sha256": "c2e14142c3875d31646674bf62fd2c5bb17bd47fc98ea6a1952fed224704f7a7",
    "source_vintages": {
     "source": "Advani and Summers (2020), Capital Gains and UK Inequality, CAGE Working Paper 465",
     "survey": "Family Resources Survey 2024-25, SPI synthetic support, and Advani-Summers capital-gains incidence"
@@ -514,7 +514,7 @@
    "required_mass_change_reason": "Capital-gains residential split divides every household carrying liable gainers into arms weighted by the solved residential probabilities, one arm per subset of residential gainers; every household's mass and the total household mass are conserved.",
    "rewrites": [],
    "source_manifest": "source_stages.json",
-   "source_manifest_sha256": "a89e2dad9d75768af47a394cab197e3115f18fe3a82efda12d8f22321359438e",
+   "source_manifest_sha256": "c2e14142c3875d31646674bf62fd2c5bb17bd47fc98ea6a1952fed224704f7a7",
    "source_vintages": {
     "source": "https://www.gov.uk/government/statistics/capital-gains-tax-statistics",
     "survey": "HMRC Capital Gains Tax statistics 2026 release, Table 8 (UK residential property disposals, 2024-25, administrative) on the amounts the Table 3 redraw placed"
@@ -536,7 +536,7 @@
    "required_mass_change_reason": "Capital-gains support split divides the wealthiest households of each HMRC Table 3 income band into light copies at equal weight; every household's mass and the total household mass are conserved.",
    "rewrites": [],
    "source_manifest": "source_stages.json",
-   "source_manifest_sha256": "a89e2dad9d75768af47a394cab197e3115f18fe3a82efda12d8f22321359438e",
+   "source_manifest_sha256": "c2e14142c3875d31646674bf62fd2c5bb17bd47fc98ea6a1952fed224704f7a7",
    "source_vintages": {
     "source": "HMRC Capital Gains Tax statistics, July 2026 release, Table 3 for 2024-25, via the vendored conditioning facts",
     "survey": "Family Resources Survey 2024-25, SPI synthetic support and HMRC Capital Gains Tax statistics Table 3 (2024-25 individuals by size of gain and taxable income)"
@@ -565,7 +565,7 @@
    "required_mass_change_reason": "ETB public-services imputation on the source spine: household weights pass through unchanged and total household mass is conserved.",
    "rewrites": [],
    "source_manifest": "source_stages.json",
-   "source_manifest_sha256": "a89e2dad9d75768af47a394cab197e3115f18fe3a82efda12d8f22321359438e",
+   "source_manifest_sha256": "c2e14142c3875d31646674bf62fd2c5bb17bd47fc98ea6a1952fed224704f7a7",
    "source_vintages": {
     "source": "UK Data Service SN 8856 Effects of Taxes and Benefits household tab, DfT rail fare index, and public NHS activity/cost table.",
     "survey": "Effects of Taxes and Benefits 1977-2024 and NHS age-gender public table"
@@ -585,7 +585,7 @@
    "required_mass_change_reason": "ETB VAT expenditure-rate imputation on the source spine: household weights pass through unchanged and total household mass is conserved.",
    "rewrites": [],
    "source_manifest": "source_stages.json",
-   "source_manifest_sha256": "a89e2dad9d75768af47a394cab197e3115f18fe3a82efda12d8f22321359438e",
+   "source_manifest_sha256": "c2e14142c3875d31646674bf62fd2c5bb17bd47fc98ea6a1952fed224704f7a7",
    "source_vintages": {
     "source": "UK Data Service SN 8856 Effects of Taxes and Benefits household tab and cited VAT anchor resource.",
     "survey": "Effects of Taxes and Benefits 1977-2024"
@@ -606,7 +606,7 @@
    "required_mass_change_reason": "CGT asset-type assignment on the source spine: household weights pass through unchanged and total household mass is conserved.",
    "rewrites": [],
    "source_manifest": "source_stages.json",
-   "source_manifest_sha256": "a89e2dad9d75768af47a394cab197e3115f18fe3a82efda12d8f22321359438e",
+   "source_manifest_sha256": "c2e14142c3875d31646674bf62fd2c5bb17bd47fc98ea6a1952fed224704f7a7",
    "source_vintages": {
     "source": "https://www.gov.uk/government/statistics/capital-gains-tax-statistics",
     "survey": "HMRC Capital Gains Tax statistics 2026 release, Table 8 (UK residential property disposals, 2024-25, administrative), Table 4.1 (individuals claiming Business Asset Disposal Relief or Investors' Relief by band of qualifying gain, 2024-25, administrative) and Table 7 (disposals, proceeds and gains by asset type, 2023-24, sample-based), vendored from the pinned Chronicle feed"
@@ -630,7 +630,7 @@
     "capital_gains"
    ],
    "source_manifest": "source_stages.json",
-   "source_manifest_sha256": "a89e2dad9d75768af47a394cab197e3115f18fe3a82efda12d8f22321359438e",
+   "source_manifest_sha256": "c2e14142c3875d31646674bf62fd2c5bb17bd47fc98ea6a1952fed224704f7a7",
    "source_vintages": {
     "conditioning_resource": "hmrc_cgt_conditioning_facts.json",
     "conditioning_resource_sha256": "067ba21c12aeb4e95e6a8a16141dbaa075e8787ed875a005f549cab6e91a6b56",
@@ -719,7 +719,7 @@
     "full_frs_tei_band_unavailable"
    ],
    "source_manifest": "source_stages.json",
-   "source_manifest_sha256": "a89e2dad9d75768af47a394cab197e3115f18fe3a82efda12d8f22321359438e",
+   "source_manifest_sha256": "c2e14142c3875d31646674bf62fd2c5bb17bd47fc98ea6a1952fed224704f7a7",
    "source_vintages": {
     "hmrc_surface": "2023-24",
     "mapped_build_period": "2024",
@@ -760,7 +760,7 @@
    "required_mass_change_reason": "LCFS consumption imputation on the source spine: household weights pass through unchanged and total household mass is conserved.",
    "rewrites": [],
    "source_manifest": "source_stages.json",
-   "source_manifest_sha256": "a89e2dad9d75768af47a394cab197e3115f18fe3a82efda12d8f22321359438e",
+   "source_manifest_sha256": "c2e14142c3875d31646674bf62fd2c5bb17bd47fc98ea6a1952fed224704f7a7",
    "source_vintages": {
     "source": "UK Data Service SN 9468 Living Costs and Food Survey 2023-24 household/person tabs and the vendored Chronicle facts for NEED 2023 mean kWh, the FY2024-25 Ofgem cap levels, road-fuel outturn (DESNZ, HMRC, ONS), the DfT VEH1103 licensed-car stock, NTS bus use and the DfT and devolved bus finance tables.",
     "survey": "Living Costs and Food Survey 2023-24"
@@ -786,7 +786,7 @@
    "required_mass_change_reason": "NTS bus-travel imputation on the source spine: household weights pass through unchanged and total household mass is conserved.",
    "rewrites": [],
    "source_manifest": "source_stages.json",
-   "source_manifest_sha256": "a89e2dad9d75768af47a394cab197e3115f18fe3a82efda12d8f22321359438e",
+   "source_manifest_sha256": "c2e14142c3875d31646674bf62fd2c5bb17bd47fc98ea6a1952fed224704f7a7",
    "source_vintages": {
     "source": "Department for Transport National Travel Survey, UK Data Service SN 5340 (End User Licence, 19th edition, November 2025), DOI 10.5255/UKDA-SN-5340-19; local licensed tab files (household, individual, trip); England residents only from 2013.",
     "survey": "National Travel Survey 2002-2024"
@@ -810,7 +810,7 @@
     "non_residential_property_value"
    ],
    "source_manifest": "source_stages.json",
-   "source_manifest_sha256": "a89e2dad9d75768af47a394cab197e3115f18fe3a82efda12d8f22321359438e",
+   "source_manifest_sha256": "c2e14142c3875d31646674bf62fd2c5bb17bd47fc98ea6a1952fed224704f7a7",
    "source_vintages": {
     "source": "MHCLG dwellings and ONS UK House Price Index December 2025 regional average prices.",
     "survey": "Public regional property reference"
@@ -837,7 +837,7 @@
     "employment_income"
    ],
    "source_manifest": "source_stages.json",
-   "source_manifest_sha256": "a89e2dad9d75768af47a394cab197e3115f18fe3a82efda12d8f22321359438e",
+   "source_manifest_sha256": "c2e14142c3875d31646674bf62fd2c5bb17bd47fc98ea6a1952fed224704f7a7",
    "source_vintages": {
     "source": "HMRC, Salary sacrifice reform for pension contributions effective from 6 April 2029",
     "survey": "Family Resources Survey 2024-25 salary-sacrifice respondents and HMRC salary-sacrifice reform analysis"
@@ -870,7 +870,7 @@
     "household_source_id"
    ],
    "source_manifest": "source_stages.json",
-   "source_manifest_sha256": "a89e2dad9d75768af47a394cab197e3115f18fe3a82efda12d8f22321359438e",
+   "source_manifest_sha256": "c2e14142c3875d31646674bf62fd2c5bb17bd47fc98ea6a1952fed224704f7a7",
    "source_vintages": {
     "source": "Reserved SPI support households for the HMRC Table 2.5 total-income bands from GBP 200,000, stacked at the published band taxpayer count over the donors per band (PolicyEngine/chronicle#280 lane).",
     "survey": "Survey of Personal Incomes Public Use Tape 2022-23 and HMRC Income Tax liabilities statistics July 2026 Table 2.5"
@@ -892,7 +892,7 @@
     "student_loan_plan"
    ],
    "source_manifest": "source_stages.json",
-   "source_manifest_sha256": "a89e2dad9d75768af47a394cab197e3115f18fe3a82efda12d8f22321359438e",
+   "source_manifest_sha256": "c2e14142c3875d31646674bf62fd2c5bb17bd47fc98ea6a1952fed224704f7a7",
    "source_vintages": {
     "source": "Explore Education Statistics Table 6a, Higher education total",
     "survey": "Family Resources Survey 2024-25 and Student Loans Company borrower forecasts for England"
@@ -914,7 +914,7 @@
    "required_mass_change_reason": "WAS Lifetime ISA imputation on the source spine: household weights pass through unchanged and total household mass is conserved.",
    "rewrites": [],
    "source_manifest": "source_stages.json",
-   "source_manifest_sha256": "a89e2dad9d75768af47a394cab197e3115f18fe3a82efda12d8f22321359438e",
+   "source_manifest_sha256": "c2e14142c3875d31646674bf62fd2c5bb17bd47fc98ea6a1952fed224704f7a7",
    "source_vintages": {
     "source": "Office for National Statistics Wealth and Assets Survey, UK Data Service SN 7215, DOI 10.5255/UKDA-SN-7215-20; local licensed round-8 person and household tabs (interviews April 2020 to March 2022, Great Britain).",
     "survey": "Wealth and Assets Survey round 8"
@@ -949,7 +949,7 @@
    "required_mass_change_reason": "WAS wealth imputation on the source spine: household weights pass through unchanged and total household mass is conserved.",
    "rewrites": [],
    "source_manifest": "source_stages.json",
-   "source_manifest_sha256": "a89e2dad9d75768af47a394cab197e3115f18fe3a82efda12d8f22321359438e",
+   "source_manifest_sha256": "c2e14142c3875d31646674bf62fd2c5bb17bd47fc98ea6a1952fed224704f7a7",
    "source_vintages": {
     "source": "Office for National Statistics Wealth and Assets Survey, UK Data Service SN 7215, DOI 10.5255/UKDA-SN-7215-20; local licensed 2006-22 household tab.",
     "survey": "Wealth and Assets Survey round 8"