[anth-volk]

Fixes #1049

Summary

The Simulation Entrypoint creates economy reports and standalone economy simulations in the Public API's run tables, and starts their calculation on the v2 coordinator and workers by run ID. It replaces the draft #974, which was built on tables that no longer exist.

• POST /reports (permission simulation:submit) takes the body the Public API sends: country, report_type: "economy", label, description, year, region_code, dataset_name (null for the region's default), each side's policy_id and dynamic_id, include_cliffs, and spm only when given. In one transaction it creates each side's new simulation and first simulation run, the report (options in inputs, the reform's policy in policy_id) and its first report run (initial, no budget window); every run is pending with no Modal call ID. It then starts the report run's coordinator by name with a ReportExecutionInput whose evaluation_id is the report run and each side's simulation_execution_id its simulation run, and a context whose report_run names the three runs. No Stage 12 evaluation record is passed. It answers 201 with report_id, report_run_id, the run's status and each side's simulation, run and whether it was reused.
• POST /simulations creates a standalone economy simulation and its first run, and starts that run's simulation function by name with the run's SimulationExecutionInput and a context naming simulation_run_id. It answers 201 with simulation_id, simulation_run_id and the status.
• Only the default version. Both routes run the v2 version manifest's default worker's .py version and name the country's catalog version for it; no request names a version or an ID.
• Reuse. A report side names an existing run instead of a new one when that run is the newest of the same simulation (policy, dynamic, catalog version, dataset, region and year) that succeeded on the same country package and .py versions, its output file is under gs://<V2_SIMULATION_OUTPUT_BUCKET>/, a succeeded report run with the same options used it, and no report run refused to reuse it (an error message starting reused_simulation_). So both of a report run's simulation runs share its dataset and region, and a submission after a refused reuse calculates the simulation again. The two sides never name the same run. Without the bucket setting, nothing is reused.
• Missing rows. Every row is read before writing: a missing catalog version, region, dataset (the region's default unless named), policy or dynamic is refused with 400 and its code before anything is written. A policy or dynamic setting parameters the catalog version lacks, or both setting one, answers 422 (missing_parameters, overlapping_parameters). A foreign-key violation (SQLSTATE 23503) on insert is answered with 400, naming the kind of row by its column.
• Modal calls. The call's ID is recorded once Modal accepts the call. When Modal refuses it, or doesn't confirm it within ten seconds, the run is failed at once (with a report run's new simulation runs), message modal_call_refused: …, and the route answers 503 naming the record. Each update applies only while the run is pending with no call ID, so a run its coordinator already claimed is left alone and answered with 201.
• Answers follow the Public API's client: 201; 400 with unknown_region, unknown_dataset or unknown_dynamic for the caller's own rows, and unknown_catalog_version, unknown_policy, no_economy_worker, dataset_not_in_bundle or missing_reference for the service's state; 422; 503 with Retry-After (not_configured, manifest_unavailable, database_unavailable, or modal_call_refused with report_id/simulation_id); 500 internal_error. No detail holds an exception's text. The OpenAPI document declares every answer, and the regenerated client reads each.
• Status reads. GET /reports/{report_id} and GET /simulations/{simulation_id} (simulation:read) return the record with its newest run's status, versions, error message and times. Results stay the Public API's to read.
• Staging check. Every staging deploy runs staging_economy_check when the household check runs: it creates a small report (current law against current law for country/wales in 2026) through the candidate, follows it and requires its run to succeed within 30 minutes. deployment_ready requires it, so a failure stops the production deploy.
• Persistence. libs/policyengine-simulation-persistence gains read-only models of the catalog's regions and datasets columns, the dynamics table and parameter_values.dynamic_id; a dynamic reader beside the policy reader; the economy records, reuse search and reads; and EconomyRunStore, each step in a transaction of its own. Typed SQLAlchemy Core only; no DDL.
• Refactor. The household routes' failure-log helpers moved unchanged to route_support, which both route modules use.

Builds on, and what merges first

• Contains Coordinate economy runs through the run tables instead of the evaluation records #1051 (tracker C1 · 8), merged in at 56b78135 and again at 3cb8d1fb: the coordinator takes a report run's ID and claims it, each worker claims its own simulation run, and a worker can calculate a standalone simulation run. Coordinate economy runs through the run tables instead of the evaluation records #1051 merges first; this PR then merges main again, and its diff shrinks to its own changes. Before Coordinate economy runs through the run tables instead of the evaluation records #1051 is deployed, a deployed coordinator would refuse these calls (it requires an evaluation record, and its context model refuses simulation_run_id), and each run would be failed by the stuck-run sweep; the staging economy check is what would catch that.
• Calculate stored households as household jobs through /household-calculations #1046 (household calculations: the policy reader and the patterns for creating rows and recording calls), Keep detailed-save simulation output files in their own buckets #1042 (output buckets) and Use a succeeded simulation run's stored output in the v2 coordinator #1040 (the coordinator's reuse of a succeeded run's stored output) have all merged into main, which this branch starts from.

Environment variables and secrets

Name	Provider	Wiring	Verified
V2_SIMULATION_OUTPUT_BUCKET (new for the service)	GitHub Actions environment variable V2_SIMULATION_OUTPUT_BUCKET in beta and prod	deploy_entrypoint job (environment release_environment) → deploy step env: V2_SIMULATION_OUTPUT_BUCKET_VALUE → deploy-cloud-run-simulation-entry.sh validates it and writes it to --env-vars-file	The variable exists in both environments; its value names the bucket C1 · 6 created (not read here).
SIMULATION_SERVICE_DATABASE_URL	Secret Manager, name from the environment variable SIMULATION_SERVICE_DATABASE_URL_SECRET_NAME	unchanged: --set-secrets	Deployed; /ready passes. The role's grants cover every table and column written here (B1 · 1).
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	Not verified here: that the token may call the coordinator and simulation functions.
SIMULATION_V2_MODAL_ENVIRONMENT, SIMULATION_V2_MANIFEST_NAME, APP_ENVIRONMENT	workflow input and literal	unchanged since #1046: env file	Yes
Staging check: SIMULATION_ENTRYPOINT_AUTH_ISSUER, SIMULATION_ENTRYPOINT_AUTH_AUDIENCE, SIMULATION_ENTRYPOINT_TEST_AUTH_CLIENT_ID, SIMULATION_ENTRYPOINT_TEST_AUTH_CLIENT_SECRET	GitHub Actions secrets of beta	staging_economy_check job, environment: release_environment, step env:	The same secrets the staging household check uses. Not verified here: the test client's permissions on POST /reports and GET /reports/{id}.

The coordinator and workers' own settings (policyengine-modal-worker-database, V2_SIMULATION_OUTPUT_BUCKET in the Stage 12 runtime secret) are unchanged.

Tests

Each change was a failing test first, committed with "(failing)" in its subject and seen failing for the expected reason (missing names, routes, jobs or scripts, or assertions), then the change that makes it pass. One commit's test passed before its change too, because the change only derives the caught errors from a type; its message says so.

Run by node ID, only the tests this PR adds or changes:

• libs/policyengine-simulation-persistence: 41 test functions, 59 cases (plus the changed input-tables case in test_tables.py), in test_economy_run_records.py, test_economy_run_reuse.py, test_economy_run_store.py, test_economy_run_reads.py and test_dynamic_reform.py, against a PostgreSQL 17 database built by the Public API's v2 migration chain at master cd513dacc with its privileges applied and verified, acting as the simulation service's role.
• projects/policyengine-simulation-entry: 92 test functions, 168 cases: the new test_economy_*.py and test_staging_economy_check.py files, and the changed cases of test_openapi.py (route table, the old gateway's contract, the new routes' answers), test_config.py and test_deployment_assets.py (the release environment count).
• projects/policyengine-apis-integ: test_economy_generated_client.py, 8 cases, against the client regenerated from this branch with ./scripts/generate-clients.sh. Against a client generated from main it fails to import create_report.

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

Review

Four read-only adversarial rounds (the review-code format):

1. Two bugs: a report's 422 located reasons at policy_id rather than baseline.policy_id/reform.policy_id; a create whose commit failed after its inserts answered a 503 naming nothing, which the Public API reads as nothing created. Both fixed test-first, with the Public API's answer rules: every refusal's detail is written from the request, never from an error's text.
2. One bug from those fixes: a request ID header over 255 characters made submissions answer 500, since a Modal call's context takes at most 255. Fixed: the call gets the request's ID only when it fits the observability runtime's rule (1 to 128 of [A-Za-z0-9._:-]), else a new UUID.
3. No bugs. Its quality findings are fixed: tests at the request-ID limit, one source for the errors a report side wraps, and the staging check asking again after a 429 or any 5xx.
4. The code those fixes added: no bugs. Its two wording notes are fixed.
5. After merging Coordinate economy runs through the run tables instead of the evaluation records #1051 (the standalone context now set through Coordinate economy runs through the run tables instead of the evaluation records #1051's simulation_run_id field, and the deadline message): no bugs; the calls match the merged coordinator and workers exactly.
6. Its two quality findings (the context takes its runs once, so the artifact prefix can't name another run; a test that the deadline message names the latest read): no bugs; its wording notes are fixed.

CI

The first run failed two jobs, fixed test-only in 31c4c7f8: test_tables' list of input tables lacked the three this PR models, and Pyright refused an optional field read in the generated-client test. A later run failed one executor test that #1051 had moved code under; #1051 fixed it, and 3cb8d1fb merges that fix. Every check passes on 3cb8d1fb.

Not done or not verified

• The staging check's region country/wales must be in the staging catalog for the default worker's .py version; not verified.
• UK local-area breakdowns are left out: C1 · 21 decides how they are stored.
• Restarting a run whose call never started is C1 · 19.
• Left as found by the reviews: reuse treats a simulation whose policy or dynamic was deleted (ON DELETE SET NULL) as current law, though the Public API deletes no policies; REFUSED_REUSE_PREFIX copies the coordinator's reused_simulation_ error codes with no test tying the two. The household path (Calculate stored households as household jobs through /household-calculations #1046) still answers a create whose commit failed after its insert with a 503; a separate change.

🤖 Generated with Claude Code