[anth-volk]

Fixes #1337

Stacked on #1338.

What changes

v2 household documents (models/household/v2DocumentCodec.ts, types/v2Households.ts). The app writes a household as the Public API's /v2/households document exactly as the Public API translates a v1 household (translate_legacy_household): people and groups take ids in name order, v1 names are kept as source_name, group members become each person's memberships, the SPM settings move onto the document, and no label is sent. So a household v3 saves deduplicates with the dual-write copy of the same v1 household. It reads a stored household back into the app's model.

Saved households (api/savedHouseholdStore.ts, hooks/useSavedHouseholds.ts), with accounts on, signed in or signed out as the browser's unauthenticated user:

• save: POST /v2/households (which returns the existing household for identical content), then POST /v2/user-households with the label and the v2 household_id;
• list (most recently updated first; a row naming only a v1 household, or whose household fails to load, is listed as unavailable rather than failing the list), open, rename (PATCH of the name), delete (the row only; households are shared);
• edit: a new v2 household, and the saved household pointed at it, through replaceHouseholdBaseForAssociation, which now takes the saved-household type and an optional createHouseholdId (without it, it still creates a v1 household, so the legacy builder is unchanged).

Without accounts there are no saved households: the interface says so, and nothing is saved in the browser.

Saved household interface (components/flagship/household/): a "Household label" field with Save (a new household, an edit as a new household pointed to by the saved one, or a rename alone; a household counts as edited only when its content differs as POST /v2/households takes it, haveSameStoredContent in the codec, as a stored household reads back with its groups in name order); a saved-household picker; and SavedHouseholds.page ("Your households") with Rename and Delete (which asks first).

Standalone household report (pages/flagship/HouseholdReport.page.tsx), for one household under a baseline and, optionally, a reform:

• the net income headline: the change in net income with a reform (the report section's HouseholdImpactResult), or net income alone for a baseline-only household (HouseholdNetIncomeResult), calculated once;
• the net income breakdown tree, varying earnings and marginal tax rates (HouseholdBreakdowns);
• the household's inputs (HouseholdSubPage), the policy summary (PolicySubPage) and Reproduce in Python (HouseholdReproducibility), each block pinned to the .py bundle its own calculation reported;
• a year the reader chooses from the model's tax years (Add user-selectable year to standalone household creation #498); the household's inputs move to it with the report builder's copyHouseholdToYear;
• varying earnings also offers the amounts the household sets, such as tip income (App does not display all possible variables in "Varying your earnings" #1096; EarningsVariationSubPage's new alsoOfferInputs, passed only by this report);
• Reproduce in Python offers a pandas DataFrame (Add dataframe-generating code to Reproduce in Python segment #1095; HouseholdReproducibility's new offerDataFrame, passed only by this report). Generated for a UK household and run against policyengine-uk 2.130.1, the point block prints a four-row table and the earnings variation block a 401-row one;
• the household builder as v3 configures it, with the US SPM geography choice, the saved-household picker and the save form.

It calculates through the Public API's v1 household routes, as the report section does. Plan item 3B-2 moves it to /v2/household-calculations.

The legacy household report, the report section and the legacy builder behave as before: the new options default off, and only the new report passes them.

Unreachable until v3 moves to v2

No runtime flag or environment variable. Everything that works only on v2 is gathered in app/src/pages/flagship/householdEntryPoints.ts, which nothing routed imports. householdEntryPoints.test.tsx checks that Build's "A household" option cannot be chosen, and that no file in the app or the calculator imports the household modules, by an @/ specifier or a relative path, except those modules themselves (confirmed to fail when Report.page imports one either way). The household-report branch of the report page stays covered by ReportLoadStates.test.tsx.

What the switch PR (plan item 4A-1) changes to reach them:

1. Build's population picker (components/flagship/reform/PopulationPicker.tsx) lists "A household" as a disabled option marked "Soon". 4A-1 enables it: choosing it offers SavedHouseholdPicker or a new household, and Build's run opens HouseholdReportPage with that household, the draft reform, and the run bar's year and baseline.
2. The report page (pages/flagship/Report.page.tsx) shows ReportNotSocietyWide ("This report cannot open here") in its householdReport branch. 4A-1 renders HouseholdReportPage there for household reports saved through /v2/reports and /v2/user-reports (3B-2).
3. Saved households have no route. 4A-1 adds calculator-app/src/app/[countryId]/(workspace)/households/page.tsx rendering SavedHouseholdsPage, a "households" screen in workspaceRoutes.ts and libs/flagship/shellRoutes.ts, and a link in the workspace navigation.

Needs a decision: the Public API cannot repoint a saved household

PATCH /v2/user-households/{id} accepts only legacy_household_id, name and description (UserHouseholdUpdateInput, which forbids other fields). It cannot point a saved household at another v2 household. So an edit here replaces the row: a new row with the same name points at the new household, then the earlier row is deleted. The saved household's id changes (nothing in v3 refers to it), identical content changes nothing, and if deleting the earlier row fails the reader is told both are now saved. If the Public API's PATCH accepts household_id, the store's repoint becomes one PATCH that keeps the id; that change belongs in the Public API, not this PR.

Tests

New or changed, all passing:

• v2DocumentCodec.test.ts (8): US and UK households match the Public API's translation exactly; the label is never sent; a person outside a collection fails, naming it; a stored household reads back unchanged, with its id and year; ids name people and groups stored without v1 names.
• savedHouseholdStore.test.ts (13): save, list (order, unavailable rows), open, rename, delete; an edit stores a new household and repoints, keeping the name; identical content changes no row; failures after storing the household or after the new row say what was kept.
• replaceHouseholdBaseForAssociation.test.ts (+1): a given createHouseholdId is used instead of the v1 route.
• useSavedHouseholds.test.tsx (5), SaveHouseholdForm.test.tsx (7, including a household read back from the Public API comparing equal to the builder's), SavedHouseholdPicker.test.tsx (5), SavedHouseholds.page.test.tsx (4): the hooks and the interface through the real store against routed Public API responses, including no accounts.
• reproducibilityCode.test.ts (+3) and HouseholdReproducibility.test.tsx (+2): the DataFrame code for a point calculation and an earnings variation; none unless asked for; the switch only with offerDataFrame.
• EarningsVariationInputs.test.tsx (new, 2), householdReport.test.ts (new, 1), HouseholdBreakdownsSPM.test.tsx (+2): the household's own amounts are offered only when passed.
• HouseholdReport.page.test.tsx (new, 19): a reform's change and a baseline-only household's net income; baseline-only breakdowns; the inputs, policy and Reproduce in Python sections, pinned to each calculation's bundle, each block with its own policy (by id, so a policy that fails to load is never given to the other block); trying again after a failed calculation; a year change moves the inputs before the run, and a household or saved household from another year opens in the report's year; the result keeps describing the household calculated after the builder changes; tip income offered in varying earnings; the SPM choice; a UK household in pounds; opening a saved household, the report opened from one, saving a new household ("Saved", then nothing left to save), an edit whose earlier row cannot be deleted (the reader is told both are saved), and no accounts.
• householdEntryPoints.test.tsx (new, 3): see above.

Full app suite on this branch (rebased onto main with #1334 and #1335, with the review fixes): 5,418 passed, 10 skipped; the same two ScorecardComparisons.test.tsx tests fail locally here and on main (currency formatting), unrelated; they pass in CI. The PR checks workflow runs only for PRs into main, so it runs here once #1338 merges and this PR's base becomes main. tsc, ESLint and Prettier are clean; the calculator type check and build pass.

Overlaps and order

• Merges after v3 household section: US and UK households with SPM geography, calculation provenance and UK input suggestions #1338.
• Group 1E (v3 saved reforms on /v2/policies) also adds v2 client code to this repository. The household wire types here are in their own types/v2Households.ts and use the existing V2UserClient and AccountAssociationRoutes, so the overlap is limited; if 1E introduces a generated TypeScript client, these types can move to it.
• Group 1F (removing Canada, Nigeria and Israel) may change the country lists; the household document codec accepts only us and uk through isAssociationCountry.

🤖 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:25pm UTC
policyengine-website	Ready	Preview	Oct 20, 2026 1:25pm UTC