[anth-volk]

Fixes #1055

Same-Repository Draft PR Check

• This PR is a draft.
• This PR is from a branch in PolicyEngine/policyengine-sim-api, not a personal fork.

Changelog

• This PR adds a changelog fragment, changelog.d/c1-15-household-reports.added.md (added).

Summary

The Simulation Entrypoint creates household reports and their household simulations in the Public API's run tables. One household function call per report run calculates them and writes each simulation run's household_result. The Public API's /v2/reports will create household reports through this route.

POST /reports takes household reports

• The body is told apart from an economy report by report_type: "household". Permission simulation:submit.
• Its fields:
  • country, label, description;
  • household_id, a household the Public API stores;
  • baseline: {policy_id};
  • reform: {policy_id}, null or omitted for a report of the baseline alone.
• What it names: each policy_id is null for current law. The report is for the household's default_year. The request names no year, region, dataset, dynamic, .py version or record ID, and has no options. The household's saved SPM selection applies to both sides.
• Every variable is calculated: each side adds every variable the household lacks, as the Public API's stored-household route does for v3's household report page today, so the report holds every value.
• Refused fields are located without the type, as for an economy report, by a copy of Calculate budget windows on the detailed-save path, five years at a time #1054's report_request_errors.py. A dynamic_id on a side, or any unknown field, is refused with 422.

What the service does (household_report_submissions.py)

1. Finds the household function: the v2 version manifest's default worker's household function for the country.

2. Reads the inputs in one transaction: the catalog version for that worker's .py version, the model, the household and each side's policy values.

3. Refuses, before writing anything, what is missing or can't be calculated:

   • 400 unknown_catalog_version, unknown_household, unknown_policy (naming the side), no_household_function;
   • 422 missing_parameters, one reason per parameter at body.<side>.policy_id.<name>;
   • 422 household_not_calculable: the household has no default year or can't be read, or the household contract refuses what would be calculated. Each refusal is located at the field it traces to.

4. Creates the rows in one transaction:

   • a household simulation and a pending simulation run for each side, never reused;
   • the report (type = 'household', household_id, year, the reform's policy, inputs = {});
   • its pending report run, trigger initial.

   No row has a Modal call ID. A foreign-key refusal on insert answers 400 (unknown_household for the household).

5. Starts one call of the household function, by name, with the new keyword household_report_run_id and a HouseholdReportRunCalculation. That is each side's HouseholdExecutionRequest, whose calculation_id is the side's simulation run.

6. Records or fails: it records the call's ID on the report run while it is pending with none. If Modal refuses the call or doesn't confirm it within 10 s, it fails the report run and its simulation runs and answers 503 modal_call_refused with report_id; a run the function claimed meanwhile is answered as it stands.

7. Builds the payload with one public builder, household_report_calculation(household=, year=, baseline=, reform=, worker=). It builds the payload from a report's stored inputs, so a restart of a call that never started (C1 · 19) or a re-run (C1 · 17) uses the same code.

8. Answers 201: report_id, report_run_id, status, year, and each side's simulation and simulation run (the reform's null for a baseline-only report).

Every other answer is an economy report's: 503 not_configured, manifest_unavailable or database_unavailable before any write, and 500 internal_error.

What the household function does (stage12_runtime/household_report_recording.py)

As the Modal worker role, under its own Modal call ID, the call:

1. claims the report run with C1 · 8's claim_report_run;
2. reads which simulation runs the report run names, validates the payload, and refuses one naming other runs;
3. claims each side's simulation run, calculates it, and writes the HouseholdExecutionResult, or the HouseholdExecutionFailure and a one-line summary, to household_result and error_message;
4. completes the report run only if every side's run succeeded; otherwise fails it with the first such side's reason.

How it handles each other case:

• Both sides are always calculated, so each run has its own outcome.
• A report run another call holds, or one already finished, isn't calculated again.
• A restarted call keeps a side it already recorded.
• A pre-emption writes nothing.
• Any other error, a refused payload included, fails the report run and each of its simulation runs left unfinished, then propagates.
• The Modal-side writes are in HouseholdReportRunStore, a ReportRunStore, in libs/policyengine-stage12-persistence. Its simulation_runs mapping gains household_result.
• The stuck-run sweep is unchanged. A household report run has a recorded call, and its simulation runs are judged once it has finished, as an economy report's are. /ready and the roles' grants are unchanged: the Modal worker role already updates simulation_runs.household_result and the report run's status columns.

No add_missing_variables option

By the user's decision, household reports always add the household's missing variables and take no option for it. Their one caller, v3's household report page, needs every value. /v2/household-calculations keeps its own switch for the callers of /calculate, who get only the values they ask for.

Builds on, and what merges first

• Builds on Create economy reports and simulations through POST /reports and POST /simulations #1052 (tracker C1 · 9, POST /reports for economy reports). This branch was built stacked on it; Create economy reports and simulations through POST /reports and POST /simulations #1052 merged into main as faa0f298, and main is merged in here (e25c235d), so this PR targets main and its diff is its own changes.

• Calculate budget windows on the detailed-save path, five years at a time #1054 (C1 · 13, budget windows), also built on Create economy reports and simulations through POST /reports and POST /simulations #1052, also makes the POST /reports body a union. Whichever of the two merges second:

  • keeps one report_request_errors.py;
  • makes ReportRequest the three-type union;
  • updates the create_report dispatch and its response_model;
  • updates Calculate budget windows on the detailed-save path, five years at a time #1054's four tests that use "household" as an unknown type.

  The two helpers this PR makes public in economy_run_records.py (references_checked, insert_simulation_with_run) are renamed exactly as Calculate budget windows on the detailed-save path, five years at a time #1054 renames them, so those hunks merge cleanly.

• Deployment order: promote_entrypoint doesn't wait for deploy_stage12_v2. A new entrypoint revision can therefore send household_report_run_id to a household function deployed before this change. That call fails, and the stuck-run sweep fails its report run. Create economy reports and simulations through POST /reports and POST /simulations #1052's run-ID calls to the coordinator have the same window, and nothing uses household reports until the Public API's C1 · 16.

Environment variables and secrets

No new variable or secret.

Name	Provider	Wiring	Verified
MODAL_WORKER_DATABASE_URL (read by the household functions' new report run writes)	Modal secret policyengine-modal-worker-database	Unchanged since #903: modal.Secret.from_name(..., required_keys=["MODAL_WORKER_DATABASE_URL"]), attached with secrets=[modal_worker_database_secret] to calculate_household_us and calculate_household_uk; read by household_report_run_store()	The attachment, in v2_app.py. Not verified here: that the secret exists in the staging and main Modal environments, and that its role holds the grants there. B1 · 7 and B1 · 2 recorded both.
SIMULATION_SERVICE_DATABASE_URL	Secret Manager, name from SIMULATION_SERVICE_DATABASE_URL_SECRET_NAME	Unchanged: --set-secrets on every deploy	The service writes only the tables and columns #1052 already writes.
MODAL_TOKEN_ID, MODAL_TOKEN_SECRET	Secret Manager, names from MODAL_TOKEN_ID_SECRET_NAME, MODAL_TOKEN_SECRET_SECRET_NAME	Unchanged since #1046: --set-secrets on every deploy	Household reports call the same household functions /household-calculations calls.
SIMULATION_V2_MODAL_ENVIRONMENT, SIMULATION_V2_MANIFEST_NAME	Workflow input and literal	Unchanged since #1046: env file	Yes. Household reports are configured when household calculations are.

Tests

Each change started as a failing test, committed with "(failing)" in its subject and seen failing for the expected reason, then the change that makes it pass. Run by node ID, only the tests this PR adds or changes:

• libs/policyengine-stage12-persistence: test_household_report_run_store.py, 6 cases.
  • These run against a PostgreSQL 17 database built by the Public API's v2 migration chain at master c4419dcea, with its privileges applied and verified, connected as the Modal worker role.
  • No CI job sets REPORT_RUN_TEST_DATABASE_URL, so they skip in CI, as the other report run store tests do.
• libs/policyengine-simulation-contract: test_household_report_execution.py, 9 cases.
• projects/policyengine-simulation-executor: test_stage12_household_reports.py, 22 cases, and 3 new cases in test_stage12_modal_app.py.
• libs/policyengine-simulation-persistence: test_household_report_store.py, 8 cases, against the same database acting as the simulation service's role.
• projects/policyengine-simulation-entry:
  • test_household_report_submissions.py, 25 cases;
  • test_household_report_routes.py, 16 cases;
  • 2 new cases in test_household_workers.py;
  • in test_openapi.py: the changed test_economy_routes_declare_every_answer, the new test_a_report_request_is_an_economy_or_a_household_report, and test_normalized_contract_matches_old_gateway, whose schema list changed.
• projects/policyengine-apis-integ: test_household_report_generated_client.py, 6 cases, against the client regenerated from this branch. Against a client generated from Create economy reports and simulations through POST /reports and POST /simulations #1052's branch, it fails to import HouseholdReportCreated.

Before each commit: CI's pinned Ruff (format and lint), the rules registry render, the quality guards, uv lock --check, and Pyright for the changed packages. No other tests were run here; CI runs the rest.

Review

Read-only adversarial rounds, in the review-code format:

1. Two bugs:

   • a side whose record changed nothing, or one found failed with no recorded failure, could let the report run succeed;
   • a payload the contract refused, or a claim that raised, wrote nothing and was left to the sweep.

   Both fixed test-first. Its quality findings fixed: the persistence record renamed HouseholdReportSimulation, and the household_not_calculable locations documented.

2. One bug: that second fix still left the report's simulation runs pending. Fixed: the call reads the report run's own runs once it holds it, and fails them on any later error. Quality findings fixed: the answer for a report run another writer finished, a side's reason always set when it didn't succeed, and the migration doc and docstrings.

3. One bug: a side whose claim raised and rolled back stayed pending. Fixed: unfinished runs are failed while still active, whoever holds them; household simulation runs are never shared. Documentation findings fixed.

4. The code round 3's fix added: no bugs. Its quality findings (docs, and tests of existing behaviour) are fixed, with no production code change.

5. The public payload builder, added after round 4 for C1 · 19: no bugs. Its quality findings are fixed test-first:

   • separate baseline/reform parameters;
   • the country taken from the household;
   • policy_values as the side field's name;
   • duplicate run IDs raise HouseholdReportBuildError.

6. Removing the add_missing_variables option (the user's decision): no bugs. Its quality findings are fixed:

   • a contract refusal of the option is the service's own error;
   • the Modal-side test fixture stores {};
   • the module docstring is corrected.

Deferred quality findings: some duplication between household_report_submissions and household_calculations (contract error locating, SPM fields), and no Postgres sweep test seeding a household report run.

CI

This PR targets main, so the full pr.yml run applies. The first run, on e25c235d, failed in test_every_model_is_runtime_evaluated_for_ruff: the new contract model's base wasn't in ruff.toml's runtime-evaluated-base-classes. That is fixed in 9b14bf2c.

🤖 Generated with Claude Code