[anth-volk]

Fixes #4131

Summary

Adds the household kind of /v2/reports. A household report calculates a household stored through /v2/households under a baseline policy and an optional reform policy, each a /v2/policies policy or current law, for the household's default_year. The simulation service calculates and stores it through its /v2/household-reports routes, as it does economy reports.

• Submit: POST /v2/reports takes a body discriminated on kind. Economy bodies are unchanged. A household body is {"kind": "household", "country_id", "household_id", "baseline": {"policy_id"}, "reform": {"policy_id"} | null, "add_missing_variables": false}, with no year: the simulation service calculates the household's default year. With add_missing_variables, both calculations add every yearly, monthly and eternal variable the household lacks, as /calculate-full does; a re-run keeps the choice. Before asking it, the Public API checks, in the household calculation routes' order, that:

  • the country's countries row has household_enabled (otherwise 422);
  • the household is the country's (otherwise 404);
  • each named policy is the country's (otherwise 404);
  • the household has a default year (otherwise 422).

  A household-only country passes, and still gets 422 for economy reports.

• Read and list: GET /v2/reports/{report_id} and GET /v2/reports?report_id=… look among the country's economy reports first, then among its household reports. A household report carries its newest run with the baseline's and the reform's calculated households, warnings and SPM receipt. Listings leave out the calculations, as they leave out economy results.

• Re-run: POST /v2/reports/{report_id}/runs runs a household report again on the current catalog version, with the manual trigger, reusing calculations unless force is set. A household-only country can re-run its household reports.

• Saved reports: /v2/user-reports accepts a household report ID after checking it with the simulation service. A household report holds no v1 report number, so saving one together with a v1 report is refused as a conflict.

• Unchanged and economy-only: GET /v2/reports/{id}/runs and GET /v2/reports/by-legacy-number/{n}. The simulation service has no household equivalents; the runs list's 404 description says so.

• Errors:

  • The simulation service's 422 (a policy changing a parameter the catalog version lacks, or a stored household or policy value the household functions refuse) answers 422 with its reason.
  • Its 400 means the two services disagree and answers 503. So do its 503, a route it does not serve, any other answer, an answer that does not parse, and a client generated before these routes.
  • Only a not-found answer from one kind leads to a lookup of the other kind. An unavailable simulation service is never taken for a missing report.

Changes to the economy kind:

• Run items gain kind: "economy", so a run answer is either kind.
• The 404 for a report of neither kind names no kind.
• POST /v2/reports declares 404.
• An unknown economy report ID now also asks the simulation service's household report route, so it answers 503 rather than 404 while that route is unavailable.
• The economy service gains find_reports, which list_reports now calls and which also names the reports whose stored result cannot be read back. Those reports are still left out of listings, and never looked for among household reports.

Household-report code is in modules of its own: services/v2/household_reports/, services/v2/report_kinds/ (which sends each operation to the right kind), libs/simulation_household_reports.py and fastapi_routes/v2/reports/household_response_models.py. The household report schemas are named HouseholdReport*, so they do not collide with the household calculation routes' HouseholdCalculation* schemas.

Migration PR checklist:

• Route groups: report (/v2/reports), and user reports (/v2/user-reports).
• Remains on the Flask / v1 path: every v1 report route.
• Newly prepared: household reports on v2, calculated and stored by the simulation service.
• User-visible contract changes: the household kind of /v2/reports, and the economy changes listed above.
• Schema: no Alembic revision.

Waits for before merging

• Serve economy reports at /v2/reports and save v2 report and simulation IDs #4108 (economy reports at /v2/reports), which this branch builds on, and the PRs it waits for.
• Calculate and store households through the v2 household functions policyengine-sim-api#957 merged and deployed, so the simulation service serves /v2/household-reports. The economy routes from Run and store v2 economy reports in the Simulation Entrypoint policyengine-sim-api#974 must be deployed as well.
• A release of policyengine-api-simulation-client that contains both the economy and the household report routes (an operator step). Until then, every household path answers 503 when deployed. The tests here ran against a client generated locally from the two simulation service branches' OpenAPI documents together; no shared path or schema differs between them.
• No migration in the v2 Alembic chain, so this does not queue behind the chain's other open revisions.

This branch does not merge in #4092 (household calculations). Its checks before submitting are reimplemented here, because #4092 sits on a different stack.

Environment variables

No new variables. The new code reads:

• SIMULATION_ENTRYPOINT_URL: GitHub environment secret (staging, production) → job env: of the Cloud Run deploy jobs in push.yml → deploy_cloud_run_candidate.sh → Cloud Run runtime, as the economy report routes do.
• GATEWAY_AUTH_ISSUER, GATEWAY_AUTH_AUDIENCE, GATEWAY_AUTH_CLIENT_ID and GATEWAY_AUTH_CLIENT_SECRET_RESOURCE: organization secrets → the deploy step's env: → the deploy script → Cloud Run runtime. The client secret is read from Secret Manager at runtime. These are the values the economy report adapter already uses.
• The v2 runtime database settings, unchanged. They are used to read the countries row, the stored household and policies, and tax_benefit_model_versions; the runtime role already has SELECT on all of them.

Not verified:

• that the Auth0 client the gateway token comes from holds simulation:submit and simulation:read for the simulation service's audience;
• that the Cloud Run runtime service account can read the Secret Manager secret that GATEWAY_AUTH_CLIENT_SECRET_RESOURCE names;
• that each environment's SIMULATION_ENTRYPOINT_URL serves a revision with the household report routes.

The integration workflow change adds one test module to an existing step. Its database URL and settings are the job's literal disposable values (V2_MIGRATION_DATABASE_URL, V2_ALEMBIC_DISPOSABLE_TEST, DEPLOYMENT_ENVIRONMENT in the job's env:).

Inline suppressions

None added.

Testing

Each commit was built test-first. Three review rounds, then one extra round for the add_missing_variables option, which was added after them.

• Unit:
  • the household report service, routes and dispatch between kinds, against SQLite and fake simulation services;
  • the saved-report check;
  • the default factories when the client is missing or lacks the household routes;
  • the adapter, against a locally generated client through an in-memory transport. These tests skip without a client that has the household routes.
• Integration, against a migrated disposable Postgres database as the runtime role: a household-only country submits, reads and re-runs a household report through the routes, reading the countries row, the stored household and the catalog version, and still refuses economy reports.
• Local runs: only the tests each commit added or changed, each selected on its own; the full suites are left to CI. ruff format, ruff check, mypy, scripts/run_quality_guards.py and scripts/export_migration_contracts.py pass.

Notes for reviewers

• A household report read costs one extra call to the simulation service, the economy lookup that comes first.
• The two simulation service adapters keep their HTTP helpers apart, so this work and the parallel budget-window work do not conflict in the economy adapter. As a result, the process fetches one gateway token for each adapter. Sharing the helpers can follow once both have merged.
• A new run's policyengine_version is the version the Public API sent. A run read back takes its version from the catalog.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 80.88531% with 95 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.66%. Comparing base (e9cfc7e) to head (5c1afd8).

Files with missing lines	Patch %	Lines
policyengine_api/fastapi_routes/dependencies.py	27.27%	16 Missing ⚠️
policyengine_api/services/v2/report_kinds/types.py	46.66%	15 Missing and 1 partial ⚠️
...gine_api/services/v2/household_reports/services.py	81.25%	11 Missing and 4 partials ⚠️
...icyengine_api/services/v2/report_kinds/services.py	80.30%	7 Missing and 6 partials ⚠️
...yengine_api/services/v2/household_reports/types.py	88.76%	9 Missing and 1 partial ⚠️
.../v2/household_reports/database_connectors/reads.py	60.00%	4 Missing and 2 partials ⚠️
...i/services/v2/household_reports/transformations.py	68.75%	3 Missing and 2 partials ⚠️
.../services/v2/household_reports/database_session.py	71.42%	3 Missing and 1 partial ⚠️
...ne_api/services/v2/household_reports/validators.py	82.60%	3 Missing and 1 partial ⚠️
...icyengine_api/services/v2/economy_reports/types.py	66.66%	2 Missing and 1 partial ⚠️
... and 2 more

Additional details and impacted files

@@                         Coverage Diff                          @@
##           v2plan/2a-202-v2-economy-reports    #4132      +/-   ##
====================================================================
- Coverage                             87.38%   85.66%   -1.73%     
====================================================================
  Files                                   286      296      +10     
  Lines                                 17144    17612     +468     
  Branches                               2760     2813      +53     
====================================================================
+ Hits                                  14981    15087     +106     
- Misses                                 1461     1816     +355     
- Partials                                702      709       +7     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.