[anth-volk]

What changes

v3's Household tab (on a report or bill page) calculates households through the Public API's v1 household routes and keeps each household only in the page's state. This PR saves each household it calculates to the user, in the background, as a /v2/user-households row that points at the v1 household (legacy_household_id), as v3 already saves its reforms and reports. Nothing in v3 reads or shows these rows yet: they keep each user's households for the Public API's v2 household routes.

• Saved only where saved work goes to the account (useV3SavedWork): signed in, or signed out as the browser's unauthenticated user, in the US or UK, and only in the account's country. With sign-in off, nothing is saved.

• One row per v1 household and user. ApiFlagshipHouseholdStore.saveCalculated looks up the user's row for the v1 household (GET /v2/user-households filtered by legacy_household_id) and creates one only when there is none. The row is named with the household's summary ("Married · 2 children · California"), shortened to the API's 255 characters.

• Once per page. useSaveCalculatedHousehold saves through one query per country and household, kept for the page's life, so a saved household is not looked up again. The key leaves out the session's user: otherwise a signed-in session that ends without a reload would save the household on screen again as the browser's user, and the next sign-in would merge that row into the account beside the first. A failed save changes nothing on the page: it is logged to the console, and tried again the next time the household's result shows, or when the session's user changes while it shows.

• Sign-in notices. The household save creates the browser's unauthenticated user on the Public API, so a browser that saved only households now has work to move at sign-in. Both notices now say "The work you saved on this browser…" instead of naming reforms and reports.

• Corrected comment. runFlagshipHousehold's comment said the API dedupes identical households; it now says the Public API stores a new one on every call.

Not changed: the Account page's delete dialog and signed-out card still name reforms and reports.

Known limits:

• The Public API's POST /{country}/household stores a new v1 household on every call, so the same inputs calculated again (after a reload, or once the run's five-minute cache entry has gone) get a new v1 ID and a second row. Those rows point at the same v2 household, because the Public API's copies to v2 deduplicate identical content, so a view of saved households can group them by household_id.
• The Public API has no uniqueness constraint on a user's row for a household. Two tabs saving the same household at the same moment can create two rows, and a household saved both by the browser's unauthenticated user and by the account becomes two rows when sign-in merges them.

Live as soon as it merges.

Tests

New or changed, all passing, each run by name:

• flagshipHouseholdStore.test.ts (new): a household the user hasn't saved gets one row, after a lookup by legacy_household_id; an existing row means no second one; a long summary is shortened; an ID that isn't a v1 household ID sends nothing.
• useFlagshipHousehold.test.tsx (new): the same household twice on a page is looked up and saved once, and isn't looked up again after six minutes; two different households are each saved; signed out, it's saved as the browser's unauthenticated user; with sign-in off, in another country, or with no calculated household, nothing is sent; a session that ends on the page saves nothing again; a failed save is logged to the console, stays in its own query, and is tried again when the result shows again.
• HouseholdImpactSection.test.tsx: a calculated household is passed on to be saved, with its v1 ID and summary.
• accountUpgrade.test.ts (new): the sign-in notices name no reforms or reports.

Each failed before its code, except three that cover behaviour already in place: the six-minute test (it fails without the session-long cache entry), the two-household test (it fails without the household's ID in the query key) and the retry test.

🤖 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	Nov 2, 2026 2:08pm UTC
policyengine-website	Ready	Preview	Nov 2, 2026 2:08pm UTC

[PavelMakarchuk]

Heads-up from Pavel's side: #1511 reworks the v3 Household tab's layout (a row of household tiles, Results/Inputs per household, Compare all, full-width charts). Saving stays here; #1511 saves nothing.

The two overlap in HouseholdImpactSection.tsx only at this PR's useSaveCalculatedHousehold call. #1511's new HouseholdCard keeps result and requested (with requested.summary), so the call goes back in unchanged after const result = …, whichever PR merges second. Two small differences:

• requested.summary now ends with the household's earnings when it has any ("Married · 2 children · Ohio · $65,000 earnings").
• Households can be renamed in v3 Household tab: a household switcher, results first, full-width charts #1511; the name is label in HouseholdCard, if the saved row should use it instead of the summary.

#1392 also overlaps (HouseholdImpactResult.tsx); the notes for that are in #1511's description under "Overlap and scope split".

🤖 Generated with Claude Code

[PavelMakarchuk]

Review: no blocking issues. The save lookup filters on legacy_household_id server-side, the hook sits before any early return, and a shared fetchQuery keeps a doubled effect (strict mode, or the same household twice) to one request. Three small points:

1. A failed save leaves no trace (inline below).
2. Stale comment, not in this diff: householdRun.ts above runFlagshipHousehold says "the API dedupes identical ones". It does not: two identical POST /us/household calls today returned 58663 and 58664. Since this PR now saves a row per v1 household, worth correcting here so nobody expects one row per household after a reload.
3. Test gap: every hook test uses one CALCULATED_HOUSEHOLD. A test with two household ids expecting two POSTs would catch someone dropping householdId from the query key.

Product note, not a defect: a signed-out visitor who only calculated a household now sees "The work you saved on this browser is now in your account" at sign-in, though they saved nothing visible. The description says this is deliberate; flagging it for Pavel's call.

🤖 Generated with Claude Code

[PavelMakarchuk]

Every failure is dropped silently. If the API refuses all saves (a 422 on the body, a 403 for the browser's user), the rows never appear and nobody can tell. A console.error('[useSaveCalculatedHousehold] Save failed:', error) here changes nothing on the page, like runAccountUpgrade does.

🤖 Generated with Claude Code

[anth-volk]

Done in 81a90cd: a failed save is now logged with console.error('[useSaveCalculatedHousehold] Save failed:', error), as runAccountUpgrade does, and the page stays as it was. A new test checks the log.

[anth-volk]

Thanks. Addressed in 81a90cd:

1. A failed save is logged to the console (see the inline reply).
2. The comment above runFlagshipHousehold now says the Public API stores a new household on every call, even for identical inputs, so each run gets its own household ID.
3. A hook test with two household IDs expects two saves. It fails if householdId is dropped from the save's query key.

Not changed here: the sign-in notice's wording, and the saved row's name (still the household's summary). On #1511: whichever PR merges second keeps the useSaveCalculatedHousehold call after const result = ….