Port post-freeze UK childcare/TFC spine inputs and calibration contract

[juaristi22]

Why this is needed

The Microcosm UK stochastic/spine port froze the incumbent at policyengine-uk-data ebf733c / Enhanced FRS 1.56.16. The childcare work that followed for the free-childcare dashboard landed after that freeze:

• uk-data #472: one target registry, corrected the TFC annual child count, removed the ineffective ±100% check, and documented the release-build/smoke-build distinction.
• uk-data #473: added the person-level, year-varying tax_free_childcare_spend_routed_share calibration adjustment derived from HMRC account-active duration.
• uk-data #474: corrected the entitlement caseloads to DfE data and removed non-independent/unsupported spending targets.
• policyengine-uk #1830 and #1834: corrected the TFC contribution base/pro-rating and added the neutral-default routed-share input consumed by Characteristic-varying take-up priors: EITC by qualifying-child count, SSI by age band #473.

The dashboard is pinned to Enhanced FRS 1.57.2, PolicyEngine UK 2.94.0, and revision 7b0a06f0…. Its like-for-like 2024 check is £0.6252bn / £0.6322bn = 0.989x and 1,099,437 / 1,085,020 children = 1.013x. See the final repository audit and current source contract.

Microcosm main at bc43f2f0 does not yet carry that contract:

• fit_uk_childcare_takeup.py still hard-codes all of the superseded targets and fits six parameters, including the now-fixed extended-hours mean and SD.
• take_up_contract.json has the four legacy take-up rates, but the TFC and extended-hours provenance predates the review findings.
• frs_take_up.py emits no tax_free_childcare_spend_routed_share, and the release input-coverage contract does not require it.
• The UK extra is locked to policyengine-uk 2.92.1, before the model/data contract above.
• No TFC or early-years entitlement facts/references appear in the UK Ledger target surface.

Parent migration issue: #145.

Exact target/modeling contract to port

Observed targets

These are the current policyengine-uk-data source of truth. Spending is £bn; caseload is children.

Programme	Spending	Caseload	Observation basis
Tax-Free Childcare	0.6322	1,085,020	HMRC 2024-25 annual top-up and annual-unique children with used accounts
Working-parent entitlement	—	621,500	DfE January 2025: 379,000 aged 3-4 + 242,500 aged 2
Disadvantaged 2-year-old offer	—	115,852	DfE January 2024 registered children
Universal entitlement only	—	416,537	DfE January 2024: 778,327 registered excluding reception minus 361,790 on the working-parent entitlement

Sources: HMRC TFC June 2025, DfE funded early education 2025, and DfE funded early education 2026.

Do not restore the old £2.5bn/£0.6bn/£1.7bn fitter rows as calibration constraints merely because similar figures appear in dashboard comparisons. #474 removed the universal and targeted spending constraints because they were caseload × a constant and therefore double-weighted the same evidence; the extended construction assumed full funded-hours usage and was a ceiling. TFC spending remains because it is an observed outturn and varies with the fee base/award, independently of child count. Dashboard allocation/outturn rows may be added as separate diagnostics only after their programme mapping, period, geography, and price basis are reviewed.

TFC routed-spend adjustment (source/spine stage, not a target row)

Port the full 1-April series from uk-data #473 to a person-level input:

FY	Share
2017-18	0.359
2018-19	0.489
2019-20	0.542
2020-21	0.471
2021-22	0.575
2022-23	0.584
2023-24	0.589
2024-25	0.593
2025-26	0.582

It is derived as sum(monthly children with used accounts) / annual-unique children / 12 from HMRC TFC statistics: March 2026, Table 2, with the HMRC quality report defining a used account.

This is a calibration adjustment, not a measured routed-expenditure share. It uses an account-active-duration statistic as the closest observable proxy. It assumes uniform spend through the year and full routing in active months; HMRC also warns that payment dates need not be care dates. Preserve that wording and assign the published mean as a constant—do not invent or impute a household distribution.

It must be person-level because a TFC account and both childcare_expenses and tax_free_childcare are child/person-level. The model variable has default 1, so a missing source-stage column silently restores the old full-year treatment unless the build/export contract fails loudly.

Pre-existing choices to retain, but describe correctly

• Keep the four existing benefit-unit draw rates: TFC 0.586 then 0.88; extended 0.812; universal 0.563; targeted 0.597.
• Correct the TFC 0.88 provenance: it was a manual bump fitted on Enhanced FRS 2022-23 before the pipeline moved to FRS 2024-25. One scalar rate cannot hit caseload and spending when the award is wrong; annual child caseload is already near target.
• Keep maximum_extended_childcare_hours_usage ~ clip(N(15.019, 4.972), 0, 30), but classify it as a fixed modeling assumption, not a current fit. Without an independent extended-spending observation, the objective cannot identify mean/SD; replacing them needs evidence on hours actually used.
• Keep targeted take-up at 0.597. Do not substitute DfE's January-2024 74.8%: the model already excludes working-parent-eligible 2-year-olds from the targeted scheme from 1 January, while the real 2-year-old working-parent expansion began in April, after the census. Those denominators are not comparable.
• Keep Microcosm's identity-keyed RNG rather than restoring uk-data's sequential stream; that was an intentional signed difference in Port the UK stochastic layer: take-up anchoring, identity-keyed draws, LHA/BRMA, provenance flags #680.
• The raw FRS spine already uses the right person grain and chamt * (cost == 1) * (registrd == 1) construction for childcare_expenses. Microcosm's 365.25/7 annualisation differs slightly from uk-data's 52 but was the explicit uniform-week adjudication in workstream E; keep it and record the resulting ~0.34% signed difference rather than reverting it.

Implementation work

1. Source/spine parity

• Raise the UK engine requirement/lock to a release containing #1830/#1834 (at least 2.93.0; preferably the dashboard-tested 2.94.0 for the first comparison run).
• Add a cited, versioned routed-share resource and a declarative constant-assignment operation on the person table.
• Add tax_free_childcare_spend_routed_share to source-stage outputs, schema/export contracts, parity/signed-difference evidence, release input coverage, and stage receipts.
• Add a fail-loud engine contract test proving the installed model defines the input and a release-H5 test proving the non-default 2024 value survives export. The frozen 1.56.16 parity reference predates this column, so handle it as an explicit post-freeze addition rather than treating absence from the reference as evidence it is unnecessary.

2. Facts, target references, and materialization

• Land the five observed facts above in Chronicle/Ledger and add UK target references/bindings for:
  • tax_free_childcare weighted spending;
  • is_child_receiving_tax_free_childcare child count;
  • is_child_receiving_{extended,targeted,universal}_childcare child counts.
• Use one declared resource/registry for the fitter, calibration, diagnostics, and release gates so target numbers cannot drift again.
• Preserve the observation basis in metadata. TFC is an annual FY 2024-25 flow/annual-unique count; universal and targeted are January-2024 stocks; extended is a January-2025 end-of-rollout stock. Never compare an annual model count with HMRC's monthly point-in-time family count.
• Resolve the target-period seam before binding. The dashboard and uk-data evaluate these targets at model period 2024. Blindly restamping/materializing them at Microcosm's 2025 calibration period changes the working-parent policy scope (including the September-2025 expansion) and makes the 621,500 comparator materially wrong. If the current compiler cannot separate fact vintage, model materialization period, and calibration year, keep the affected rows as release diagnostics until it can.
• Pin the universal target's formula contract: 416,537 is only valid while the model treats universal and working-parent entitlements as mutually exclusive.

3. Repair the offline fitter

• Remove its private hard-coded target dictionary or generate it from the declared target resource.
• Fit only the four take-up rates. Hold the extended-hours distribution fixed at 15.019/4.972.
• Remove extended/universal/targeted spending terms unless an independent, reviewed outturn is added.
• Make receipts pin the target-resource digest, engine version, input H5 identity, model period, seed, and achieved/target ratios.

4. Release validation

• Treat PR-CI builds as contract/smoke tests, not release certification. Run the target diagnostics on the full private release candidate and publish all five achieved/target ratios.
• Start TFC spend and child-count gates no looser than ±25% (the uk-data initial release threshold), with every material miss explicit. Tighten from measured Microcosm release evidence rather than copying uk-data's reduced-epoch smoke override.
• Add source-contract tests for exact target values, the routed-share launch year and 2024 value, entity grain, target/model periods, and the deliberate absence of unsupported spending targets.

Childcare fee-base follow-up (not a blind port)

The dashboard also finds childcare_expenses for England, under-5s at about £6.36bn against a derived CMA residual near £5.1bn (~1.25x). This is relevant because TFC and the 75% reform both price that base, but it is not ready to become a hard UK/all-age target:

• £5.1bn is derived from an uncertain ~£14bn provider-income estimate less £8.9bn entitlement funding; it is not a published parent-fee total and includes other provider income.
• The comparator must be England + under-5 only and gross of TFC/UC childcare support. There is no published school-age aggregate, so the UK/all-age base must not be rescaled from it.
• Audit whether FRS chamt is gross or already partly net of TFC before binding it.

If carried into Ledger, make it an uncertainty-weighted, filtered research fact/diagnostic first. Promote it to calibration only after the concept bridge and uncertainty are reviewed.

Acceptance criteria

• The Microcosm UK spine contains person-level tax_free_childcare_spend_routed_share == 0.593 for build year 2024, with source identity and a fail-loud model/export contract.
• The current five observed targets are declared once and consumed by fitting, calibration/diagnostics, and release validation; the stale 985/740/130/490 values are gone.
• The fitter optimizes four rates only and cannot reintroduce the three unsupported spending terms.
• Target metadata distinguishes annual flow/annual-unique counts from January/monthly stocks and keeps model period separate from calibration year.
• A full private release-candidate receipt reports all five target ratios under a pinned PolicyEngine UK version containing #1830/#1834.
• TFC target failures cannot pass silently; non-TFC spending rows remain diagnostic-only unless independently sourced and reviewed.
• The intentional Microcosm differences (identity-keyed RNG and uniform WEEKS_IN_YEAR) remain signed rather than accidentally reverted.
• The CMA fee-base item remains filtered/uncertainty-labelled until its FRS concept bridge is resolved.