[anth-volk]

Fixes #956

What this changes

The Simulation Entrypoint now calculates and stores households on v2, through the v2 Modal household functions, and checks a household calculation end to end on every staging deployment. Nothing calls these routes yet; the Public API's /v2/household-calculations (PolicyEngine/policyengine-api#4092, a draft that waits for this) and household reports will.

• Household calculations. POST /v2/household-calculations records a calculation (one stored household under one policy, with its options such as axes, for a catalog version and year) as a simulation run and starts the household function's Modal call. GET /v2/household-calculations/{calculation_id} returns its status and, once it ended, the calculated household with its warnings, the SPM selection it applied (spm_config), its SPM receipt (spm_provenance) and the bundle, or its error. The same calculation submitted again reuses its run while it is unfinished or for 28 days after it succeeded, unless forced.
• Household reports. POST /v2/household-reports creates a report (a baseline and an optional reform) and starts its first run; POST /v2/household-reports/{report_id}/runs starts another run of it; GET /v2/household-reports/{report_id} returns the newest run with both calculations. One Modal call computes the runs still pending, so a new report's two simulation runs share the call. A report's runs start before the report is created, so a refused reference leaves no report behind.
• Inputs. The runtime database role cannot read the Public API's tables, so the Public API sends the household in the situation shape with its saved SPM choice (spm; a saved null is no choice) and each policy's parameter values. The database checks that the household, policy and catalog version exist (400 otherwise). The household function and bundle come from the v2 version manifest for the calculation's PolicyEngine.py version, before anything is written (400 when there is none, 503 when the manifest cannot be read).
• Recording. Each household function takes the runs a call computes as its second argument, and its last step starts report_call_ended with them, whether the calculation returned or raised; a pre-empted call reports nothing, and Modal runs it again under the same call ID. A household result recorder stores each run's household with the call's success. A household function's typed failure (such as an input the country model does not know) fails the runs with household_calculation_failed, with the household error document as the runs' error detail; an outcome missing one of its runs fails them as invalid_result. The safety check covers calls that never report and runs left dispatching.
• Storage (revision 0005). simulations.options; the household output's warnings, spm_config, spm_provenance and bundle; and error_detail on failed simulation runs and comparison steps.
• Staging test. After a staging deployment promotes its revision, with the v2 application deployed, the new staging_household_test job stores a one-person US household through the staging Public API, reads its catalog version, submits a forced calculation to the staging stable URL, polls until it succeeds or fails, and reads the result back, within ten minutes. It retries a 503 after its Retry-After wait within that limit. A failure fails the deployment run, so production does not deploy.

Tests

Run locally on the branch head, after rebuilding the branch on the rebased #951 (now on main):

• entry project: uv run --frozen pytest tests/ — 1047 passed (new: household recorder, service, routes, reports, workers, staging job wiring; cases for a successful call, a failed Modal call, a typed household failure, an outcome missing a run, and a calculation left dispatching that the safety check fails and a resubmission runs again);
• persistence library against PostgreSQL 17: SIMULATION_TEST_DATABASE_URL=... uv run --frozen pytest tests/ — 210 passed, including the migration cycle with alembic check;
• executor: 2000 passed, 22 skipped, including the household functions' call reports; contract library: 395 passed;
• ruff (0.15.22), Pyright for the entry, persistence, contract and executor packages, and the quality guards (including the file-length rule) pass; the simulation client generates with all five household endpoints;
• each of the branch's own commits, checked out in turn: ruff, the quality guards and the suites of the packages it changes pass.

The staging test itself runs only in the deployed staging job.

Environment variables

New:

• PUBLIC_API_URL (read by the staging_household_test job as SIMULATION_STAGING_TEST_PUBLIC_API_URL): a new GitHub environment variable in beta, the staging Public API's stable URL. It reaches the job through the job's environment: beta; both staging callers of the reusable workflow pass secrets: inherit. Not set yet: an operator step.
• The job's other values: SIMULATION_STAGING_TEST_BASE_URL from deploy_entrypoint.outputs.stable_url; SIMULATION_STAGING_TEST_POLICYENGINE_VERSION from prepare.outputs.policyengine_version; SIMULATION_ENTRYPOINT_TEST_AUTH_ISSUER and _AUDIENCE from the beta secrets SIMULATION_ENTRYPOINT_AUTH_ISSUER and _AUDIENCE; SIMULATION_ENTRYPOINT_TEST_AUTH_CLIENT_ID and _CLIENT_SECRET from the beta secrets of the same names (all present, and used by the existing deployed authentication tests); SIMULATION_STAGING_HOUSEHOLD_TEST is a literal 1 in the job.

Reused, no new runtime variable:

• SIMULATION_CALL_REPORT_MODAL_ENVIRONMENT: from the workflow input modal_environment, written into the Cloud Run environment by the deploy script; the household routes start calls and read the v2 version manifest in that Modal environment.
• SIMULATION_DATABASE_URL, MODAL_TOKEN_ID, MODAL_TOKEN_SECRET: Google Secret Manager secrets mounted with --set-secrets, named by the beta/prod variables SIMULATION_DATABASE_URL_SECRET_NAME, MODAL_TOKEN_ID_SECRET_NAME and MODAL_TOKEN_SECRET_SECRET_NAME. SIMULATION_DATABASE_URL_SECRET_NAME is not set in either environment yet (an operator step of the earlier pull requests in this chain). Without the database or the Modal environment, the household routes answer 503.
• SIMULATION_ENTRY_URL and MODAL_IDENTITY_TOKEN in report_call_ended: wired by the call-report change below this one; the household functions read nothing new.

Not verified: that sim's Modal token can spawn the v2 household functions and read the version manifest Dict in each Modal environment; that the deployed-test Auth0 client holds simulation:submit and simulation:read once permissions are enforced (SIMULATION_ENTRYPOINT_ENFORCE_PERMISSIONS is unset in beta, so today missing permissions are only logged); and that the staging Public API writes to the same database as staging sim, which the foreign keys need.

Waits for

• Store every simulation result as rows and rebuild today's result format from them #951, the base (result tables), and the pull requests below it: Record simulation runs and report runs, and their outcomes when Modal reports a call ended #950, Add simulation and report definitions to the simulation schema #900 and Give the Simulation Entrypoint its own simulation schema, migration chain and database connection #898.
• Calculate a household under several policies in one call with v2 Modal household functions #903 (the v2 household functions and their contract), merged into this branch with a plain merge commit. Calculate a household under several policies in one call with v2 Modal household functions #903 is based on an older main, so the merge also changes its household function's span to runtime.span(...), as main did for every other use of the removed policyengine_simulation_observability.scopes module.
• Promote each staging deployment's tested Simulation Entrypoint revision #894 (staging promotes each tested build), merged into this branch with a plain merge commit; without it, staging never promotes and the staging household job never runs. Promote each staging deployment's tested Simulation Entrypoint revision #894 is based on an older main, so the merge moves its deployment test changes into main's split test modules: the staging promotion check and its rule proof are in test_deployment_assets_promotion.py, and the rules registry names them there.
• The operator steps above: PUBLIC_API_URL in beta, and the database and Modal settings of the pull requests below this one.
• Revision 0005 is in the simulation schema's one Alembic chain. Migration pull requests in this chain merge one at a time; another open revision 0005 (such as the economy path's) is renumbered onto the new head by whichever merges second.

A v2 application deployed before the household functions took run IDs (for an older PolicyEngine.py version) refuses them until it is redeployed; its calls fail as worker errors, recorded by the safety check.

CI: the PR description check passed on 2f0406e; no other run had finished when this was last updated.

🤖 Generated with Claude Code