[anth-volk]

Fixes #4280

Summary

Adds /v2/reports (economy kind) and /v2/simulations. Reads come from the detailed-save tables, and creates go through the simulation service. Replaces #4108, whose reads through the simulation service, lookup by v1 report number and first-read runs no longer fit the design.

Reads need country_id and no user credential. They never call the simulation service or start a run.

• GET /v2/reports/{report_id} returns the report within its reports.country, with its newest run: the one created last, with the larger ID winning a tie, whatever its status and versions. This deliberately differs from picking the newest succeeded run on the deployed versions, which would hide the out-of-date run a client needs to see.
  • The answer: the definition (label, year, region code, dataset name, each simulation's policy and dynamic, options), status (not_run or the run's), run (status, trigger, both package versions, simulation run IDs, error, times), current_versions and result.
  • result is filled only once the newest run has succeeded.
• GET /v2/reports?report_id=… lists 1 to 25 reports in one SQL statement, in the order named, each once, without results. Unknown reports, other countries' reports and reports of other kinds are left out.
• GET /v2/simulations/{simulation_id} returns the simulation and its newest run, with current_versions. Its country comes from its catalog version's model.

The result rebuild (services/v2/stored_reports/economy_results/) reverses the simulation service's writer part by part into SingleYearMacroOutput:

• budget, programs, income and wealth deciles, and intra-decile shares;
• poverty and inequality for each simulation run;
• labour supply and its deciles;
• congressional districts, and UK constituencies and local authorities with their disclosure fields;
• cliffs, SPM receipts (typed as SPMComparisonProvenance) and the data and model versions.

The UK local-area breakdown is left out until its storage is decided. A golden fixture, tests/fixtures/economy_result_rows_golden.json, was produced by running the simulation service's real writer (scripts/generate_economy_result_golden.py, at the simulation service's commit cb1264a5). It covers the US, the UK, labour supply deciles −1 and 0, at-large districts and a negative budget, and a test rebuilds it exactly.

Creates. POST /v2/reports and POST /v2/simulations take country_id in the query and the body, refuse bodies over 16 KiB, and answer 201 with the record read back from the tables.

• Report body: kind: "economy", label, description, year, region_code, an optional dataset_name, baseline and reform (each an optional policy_id and dynamic_id), include_cliffs and an optional spm.
• Simulation body: kind, year, region_code, an optional dataset_name, policy_id and dynamic_id.
• Checks before calling the simulation service: the country must allow society-wide calculations, and each named policy must be stored in it. No field names a version: the simulation service runs its default worker's.

Answers from the simulation service. No answer that invites a resubmission follows a record the simulation service may have created, unless it says so.

The simulation service	The create answers
201 or 202	201 with the record read back. If the read-back fails, 502 with the created report_id or simulation_id, saying to read it rather than submit again.
422, or a 400 whose code is unknown_region, unknown_dataset or unknown_dynamic	422 with its code and reason
Any other 400	503 with its code and reason
A readable 503 that names the submission's own record	503 with that record's ID and sim's code
A readable 503 that names no record	503 with sim's code: nothing was created
401, 403, 404, 405, 413 or 429, which come before sim's route runs; a connection never made; a gateway token that can't be fetched	503
An answer lost after sending, or a proxy's 502 or 504	502: "The simulation service may have received the request, but its answer was lost (…). Submit the report again; if the first request went through, this creates a second report."
Its own 500, an unreadable 201 or 202, a 503 that can't be read or names another or a malformed record, or any other status	502: "The simulation service may have created the report, but it failed (…). Submit the report again; if the first request went through, this creates a second report."

For sim's 500 and 503, only the status and sim's code reach the caller, never sim's error text.

Saved records. Saved reports and saved simulations accept a detailed-save report_id or simulation_id, one reference per request. A request naming both a v1 number and a detailed-save ID gets 400, as does an update that would leave a row holding both. The reference is checked with a SELECT in the write's own transaction. A foreign-key violation (SQLSTATE 23503) on those keys, from a record deleted after that check, answers 404; the insert and update connectors turn it into the not-found error, so the services import no SQLAlchemy. The shared report answer now includes report_id.

The call to the simulation service sits behind the SimulationServiceClient protocol. The adapter, policyengine_api/libs/simulation_reports.py, reuses SimulationEntrypointClient's HTTP client, so the gateway credentials and the request and observability ID headers come from there. Wiring the released generated client is one change: add policyengine-api-simulation-client>=<the release with these routes>, relock, and replace post_report and post_simulation with the generated create_report.sync_detailed(...) and create_simulation.sync_detailed(...), as their docstrings show.

Shared with household calculations (#4274). The adapter and the household calculation client now share policyengine_api/libs/simulation_service_answers.py, so neither keeps its own copy of these:

• the HTTP client's construction;
• the transport-error sorting and the proxy statuses;
• the answer and refusal models;
• the refusal's reason, and the status and code a message gives;
• the lost-answer and failure messages.

The SimulationService*Error types are defined once, in services/v2/simulation_service/types.py. The 422 error is SimulationServiceInvalidRequestError, the household calculations' name. Both routes answer exactly as before.

Merge order

The simulation service's POST /reports and POST /simulations don't exist yet; that work is separate. Until they are deployed, both creates answer 503, while the reads work as soon as this merges. The adapter, policyengine_api/libs/simulation_reports.py, defines the request and answer shapes those routes must use, including the three 400 codes in CALLER_ROW_REFUSAL_CODES.

Tests

• Each test was run individually, by node ID, and seen failing for the expected reason before its change.

• Unit tests: the result rebuild, the golden fixture, newest-run selection with equal creation times, the list query, country checks, the create services, saved-record checks and the route answers. Every simulation-service answer in the table goes through the real HTTP client over a mock transport to the route's JSON.

• Integration tests on PostgreSQL 17, as the runtime role: US and UK rows in all 11 result tables, including UK disclosure fields and their nulls, and the saved-record foreign keys. They run in two existing v2-integration-check.yml steps.

• Checks: alembic -c alembic-v2.ini check (no operations), lint-imports, the rules registry, the quality guards, the migration contract export (regenerated), ruff, ruff format and mypy.

• Review: three rounds, and a follow-up of the fixes.

  • Round 1: a lost answer, and a failed read-back after the record was created, both answered 503, which invites a duplicate.
  • Round 2: every 400 from the simulation service was treated as the caller's error, and its 503 lost its code and created record. The lost-answer message also promised a check no route supports.
  • Round 3: three kinds of 503 could follow a created record.
  • Round 4, of the fixes: an unexpected status, such as a 200, answered the "nothing was created" 503.
  • After merging master with Calculate stored households through /v2/household-calculations #4274, one round on the shared code and two CI fixes. A saved record repointed to a record deleted after the check answered 503: the update connector read its row after the failed flush had expired it.
  • A round on that fix found no bug.

  All are fixed test-first.

Environment variables and secrets

No new ones.

Value	Provider	How it reaches the code
SIMULATION_ENTRYPOINT_URL	GitHub environment secret in staging and production	The deploy job's env: in push.yml, then deploy_cloud_run_candidate.sh, then the Cloud Run revision. Unchanged.
GATEWAY_AUTH_ISSUER, GATEWAY_AUTH_AUDIENCE, GATEWAY_AUTH_CLIENT_ID, GATEWAY_AUTH_CLIENT_SECRET_RESOURCE	Organization secrets; the client secret itself in Secret Manager	The deploy step's env:, then the deploy script and Cloud Run. Unchanged.
V2_RUNTIME_DATABASE_URL_SECRET_RESOURCE	Environment secret	Unchanged.

Not verified:

• that each environment's SIMULATION_ENTRYPOINT_URL names a simulation service with the new routes;
• that the Auth0 client holds permission for those routes;
• that the runtime role's grants on the v2 tables are applied in staging and production.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 96.80625% with 45 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.95%. Comparing base (cd513da) to head (fd4f8d3).

Files with missing lines	Patch %	Lines
policyengine_api/fastapi_routes/dependencies.py	40.00%	12 Missing ⚠️
.../stored_reports/economy_results/transformations.py	92.00%	1 Missing and 11 partials ⚠️
...yengine_api/services/v2/stored_reports/services.py	93.61%	2 Missing and 1 partial ⚠️
..._api/services/v2/stored_reports/transformations.py	90.00%	1 Missing and 2 partials ⚠️
...ngine_api/services/v2/stored_reports/validators.py	89.65%	2 Missing and 1 partial ⚠️
...ine_api/services/v2/stored_simulations/services.py	91.17%	2 Missing and 1 partial ⚠️
...olicyengine_api/libs/simulation_service_answers.py	97.26%	0 Missing and 2 partials ⚠️
...ine_api/services/v2/simulation_service/services.py	91.66%	2 Missing ⚠️
...ngine_api/services/v2/user_simulations/services.py	90.00%	1 Missing and 1 partial ⚠️
...licyengine_api/fastapi_routes/v2/reports/routes.py	98.41%	0 Missing and 1 partial ⚠️
... and 2 more

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #4281      +/-   ##
==========================================
+ Coverage   92.69%   92.95%   +0.26%     
==========================================
  Files         329      356      +27     
  Lines       18783    20097    +1314     
  Branches     3114     3222     +108     
==========================================
+ Hits        17410    18682    +1272     
- Misses        818      844      +26     
- Partials      555      571      +16     

Flag	Coverage Δ
integration	55.77% <76.08%> (+2.00%)	⬆️
unit	90.42% <90.56%> (-0.04%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ 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.