[anth-volk]

Fixes #1336

What changes

The household section of v3's report (each household the reader describes, run under the report's baseline and reform) already runs UK households in the UK since 15d4b45. This PR finishes US and UK support:

• The country is required, never read as the US. compareHouseholds took the US result rows (the taxes and benefits it lists) for any country without its own; a country without its own rows is now an error. HouseholdImpactResult no longer defaults its currency to us. The unused simple-input run (FlagshipHouseholdInput, buildHouseholdPayload, runFlagshipHousehold, describeHouseholdInput), which always built a US household with a US state, is removed; its run tests now cover runFlagshipHouseholdPayload.
• Calculation provenance is kept. The run called fetchHouseholdCalculation, which drops policyengine_bundle, spm_config and spm_provenance. It now calls fetchHouseholdCalculationWithBundle and keeps them per policy (FlagshipHouseholdRun.provenance). A response without a bundle records null.
• US SPM geography and its footnote. The section no longer passes hideSpmGeography: a US household still starts on national thresholds, and the reader can choose local thresholds by county with a county FIPS code; the household's spm setting and county_fips are sent with it. The SPM methodology footnote shows under the summary and the net income breakdown (from each response's settings and receipt; nothing for a response without one, such as any UK household), and the varying earnings and marginal tax rate views no longer hide their own footnote. SPMMethodologyFootnote now also accepts just a calculation's SPM settings and receipt.
• UK input suggestions. "Related to this reform" came from a parameter dependency map traced only from policyengine-us, so UK reports suggested nothing. app/scripts/build-parameter-dependency-map.py takes --country uk and traces policyengine-uk over 400 generated households (the UK microdata is not public; which parameters a formula reads depends on which formulas run, not on the households, so the population varies ages, couples, children, pensioners, disability, every region, tenure and council tax band, and each income source). loadParameterDependencies(countryId) loads each country's map once, and every caller names its country: the validation surfaces (scorecard matches, calibration matches, reform readers, scorecard comparisons) ask for the US map by name, and a call without a country loads none. Suggestions are limited to inputs that describe a household, so microdata-only inputs no longer use up the list. For a change to Universal Credit's child element, the suggestions now include a child's age, childcare costs and disability.
• UK acceptance checks from Bug in UK household calculation [MOVE TO API] #358 and UAT: UK Household (PR #556) #562 (tests only; see below).

Live as soon as it merges. Calculations stay on the Public API's v1 household routes (create the household, then calculate it under each policy). No environment variable, workflow or deployment configuration is added or changed.

Evidence

• Bug in UK household calculation [MOVE TO API] #358: the issue's household (an adult earning £100, a dependant aged 10 earning £10, one benefit unit, a BRMA, region and local authority that name different places) calculates in policyengine-uk 2.130.1, the version the .py bundle 6.7.5 pins, run locally for 2025 (net income £10,159.73) and 2026. No calculation was sent to production.
• The UK map: policyengine-uk 2.130.1 with policyengine-core 3.33.0; all 1,163 variables calculate with no failures; 688 parameter paths and 989 consumed variables; 195 KB, loaded lazily by the household section of UK reports only.

Tests

New or changed, all passing:

• householdRun.test.ts (26): a country without its own result rows throws; each response's bundle and SPM provenance are kept per policy; one calculation for both policies gives the reform the baseline's provenance; a response without a bundle records null; the run mechanics on runFlagshipHouseholdPayload.
• HouseholdImpactSection.test.tsx (29): the builder stand-in now renders the real SPMGeographyChoice unless hidden. A US household shows the choice on national thresholds; choosing county thresholds and a FIPS code sends both; a response with an SPM receipt shows the methodology under the result, one without shows none; a UK household shows no SPM choice.
• HouseholdBreakdownsSPM.test.tsx (new, 2): varying earnings and marginal tax rates keep their SPM footnote.
• HouseholdImpactSuggestions.test.tsx (new, 2): a UK reform to Universal Credit's child element suggests the inputs it reads, never a microdata-only input.
• parameterDependencies.test.ts (+5) and householdSuggestions.test.ts (+1): each country has its own map; the UK map is traced from policyengine-uk; the US map is the one the validation surfaces ask for; a call without a country loads none (also a type error).
• UKHouseholdAcceptance.test.tsx (new, 4): Bug in UK household calculation [MOVE TO API] #358's household is sent as described and its result shows; UAT: UK Household (PR #556) #562's couple and child share one benefit unit and one household; an input set on the benefit unit is sent on the benefit unit; the household runs under the report's two policies and reads in pounds. These check existing behavior, so they could not fail first: each was confirmed to fail when the section sent a new household instead of the built one, or ran a UK household against the US API.
• ReportViewHousehold.test.tsx and HouseholdImpactAnalytics.test.tsx: their mocks follow the new calculation call.

Full app suite (after rebasing onto main with #1334 and #1335): 5,342 passed, 10 skipped, before the review fixes; with them, the suite on the PR above this one, which contains this branch, passes 5,418 with 10 skipped. Two tests in ScorecardComparisons.test.tsx fail locally on this branch and on main alike (currency formatting, "£1B" against "£1.0B"); they are unrelated, and pass in CI. All CI checks pass on this PR. tsc, ESLint and Prettier are clean; the calculator type check and build pass.

Overlaps

• Draft Send explicit UK claimant roles and stop reading an adult dependant as the partner #1240 (UK claimant roles): not modified. Once it merges, the section should apply withSupportedBuilderClaimantRoles to the household before toV1CreationPayload() in HouseholdImpactSection (calculate), as Send explicit UK claimant roles and stop reading an adult dependant as the partner #1240 does at its other save sites, so v3 UK households send the same roles. This PR does not change Household.ts.
• Add GA4 events for the v3 household, report and Build flows #1334 (GA4 events) merged while this was open; the branch is rebased onto it, and the analytics tests it added now mock the new calculation call.
• Draft Use compact typed SPM provenance contracts #1239 (compact SPM provenance): edits SPMMethodologyFootnote.tsx and the calculation types; a rebase keeps the wider footnote input added here.
• Saved households, UAT: UK Household (PR #556) #562's second item, are in the next PR of this stack (v3 standalone household report and saved households on /v2/households, unreachable until v3 moves to v2 #1339).

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
policyengine-calculator-next	Ready	Preview	Oct 20, 2026 1:10pm UTC
policyengine-website	Ready	Preview	Oct 20, 2026 1:10pm UTC