[anth-volk]

Fixes #4294

Summary

Runs a stored economy report or budget window again and lists a report's runs in /v2/reports, with each run's package versions beside the current ones.

• POST /v2/reports/{report_id}/runs?country_id=, body {"force": false} (a JSON boolean; {} is the default, unknown fields refused, 16 KiB limit):

  • reads the report in its country (404 otherwise), and refuses household reports with 422 for now;
  • checks the country's economy flag and the policies of the report's two simulations, baseline first, through SimulationSubmissionService.rerun_report, the same checks as a new report, including Refuse /v2/reports and /v2/simulations submissions whose policies set missing parameters #4286's 422 missing_parameters;
  • has the simulation service create and start the report's new run (POST /reports/{report_id}/runs with {"force": …}), with the database session closed while it is asked;
  • answers 201 with the report read back from the tables, its new run as the newest. Every earlier run is kept.

• GET /v2/reports/{report_id}/runs?country_id= answers {report_id, kind, items, current_versions}, newest first (created last, ties by the larger ID):

  • an economy report (kind: economy): its report runs, each with its status, trigger, country_package_version, policyengine_version, simulation run IDs, error and times;
  • a budget window (kind: budget_window): its budget-window runs, each with recalculate, its versions and its years, as GET /v2/reports/{id} answers a window's newest run.

  current_versions are the versions the Public API runs, as GET /v2/reports/{id} already answers, so v3 can mark a report whose newest run used an older .py version as out of date and offer a re-run.

• How the simulation service's re-run answers are read (policyengine_api/libs/simulation_report_reruns.py):

  • 201 or 202 naming the report: started. One that can't be read, or names another report: 502.
  • 409 (run_in_progress with run_id, or rerun_not_supported): 409 with the service's code and reason and run_id. The service answers 409 only before writing, so one that can't be read is 503.
  • 422, and 400 unknown_region, unknown_dataset or unknown_dynamic for a row the stored report names: 422 with code and reason. Any other 400: 503.
  • 401, 403, 404, 405, 413, 429: 503. The service's 404 is its own state, since the Public API has just read the report.
  • 503 naming no record, or naming this report and the run it failed after Modal refused the call: 503, naming the failed run. A 503 that can't be read or names another record: 502.
  • 500, a lost answer, a proxy's 502 or 504, and any other status: 502. Each message asks the caller to read the report to see whether it has a new run before running it again.
  • A report that can't be read back once its run started: 502 with report_id.

• The status and code sets the create client and the re-run client share move from simulation_reports into simulation_service_answers.

• The migration contract documents gain the two requests, and v2-integration-check.yml runs the new PostgreSQL tests.

Waits for other PRs

• Simulation service: POST /reports/{report_id}/runs is built against the shapes of draft Re-run a stored economy or budget-window report, or a simulation, on the current .py version policyengine-sim-api#1059, with test doubles for its answers. Until a release with that route deploys, re-runs answer 503 (the service's 404 for a route it doesn't have). Once it merges, this PR is checked against what shipped.
• Budget windows (Serve budget windows through /v2/reports #4290, merged): both routes take them. Re-run a stored economy or budget-window report, or a simulation, on the current .py version policyengine-sim-api#1059 re-runs a window through the same route, answering 201 with the window's report_id, which is all the re-run client reads; the window is then answered as read back.
• Household reports (Serve household reports through /v2/reports #4293): both routes answer 422 for them here. After Serve household reports through /v2/reports #4293 merges, this branch merges master and adds them: a household report's re-run checks the household country, as its create does, rather than the economy flag, and its run list is its report runs.
• Wiring the generated simulation client (tracker D7 · 1): post_report_rerun is the only code that sends the re-run, and its docstring names the generated operation.

Known limit: current_versions are the versions the Public API runs, as GET /v2/reports/{id} already answers, while a re-run records the simulation service's default worker's versions. During a release, while the two differ, a report run again a moment ago can still compare as out of date until both deploy the same .py version.

Environment variables and secrets

No new ones. The re-run uses the create's client and configuration:

• SIMULATION_ENTRYPOINT_URL: GitHub environment secret (staging, production) → push.yml job env: → deploy_cloud_run_candidate.sh → Cloud Run. Unverified: that it names a simulation service revision with the re-run route (not yet released).
• GATEWAY_AUTH_ISSUER, GATEWAY_AUTH_AUDIENCE, GATEWAY_AUTH_CLIENT_ID, GATEWAY_AUTH_CLIENT_SECRET_RESOURCE: organization secrets → the deploy step's env: → the deploy script → Cloud Run, the secret read from Secret Manager at runtime. Unverified: the Auth0 client's simulation:submit permission on the new route (the same permission as POST /reports).
• V2_RUNTIME_DATABASE_URL_SECRET_RESOURCE: existing wiring; the runtime role already has SELECT on reports and report_runs.
• CI: the new test file joins an existing step of v2-integration-check.yml, which uses the job's literal throwaway database values.

Testing

• Red-green throughout: each change's tests were committed first and seen failing for the expected reason.

• New tests, each run by node ID (58 node IDs, 113 cases, all passing):

  • the re-run client's request and every answer of the simulation service (tests/unit/libs/test_simulation_report_reruns.py);
  • the checks before a re-run (tests/unit/v2/test_report_rerun_submissions.py);
  • both routes over a stand-in service: bodies, queries, the 409, 413, 422 and 502 answers, error mapping and the OpenAPI document (tests/unit/v2/test_report_run_routes.py);
  • the report service with a database that can't be opened (tests/unit/v2/test_report_rerun_service.py);
  • PostgreSQL 17 as the runtime role (tests/integration/test_v2_report_runs.py): run lists newest first with versions, other reports' runs left out, another country's report or an unknown one (404), household reports and budget windows (422), a re-run with and without force answered with its new run, no report session open while the simulation service is asked, the service's 409 and 503 answered as its own, and a report that can't be read back (502).

• Modified tests: the OpenAPI path list, the contract request count (99), the integration workflow's file list and the contract registry check.

• Checks: alembic -c alembic-v2.ini check on a fresh PostgreSQL 17 database (no operations), lint-imports, python -m scripts.rules validate, python scripts/run_quality_guards.py, ruff, ruff format, mypy, and mypy on the changed libs modules. The migration contract documents are regenerated.

• Review: three adversarial review rounds on the economy routes, one on the budget-window extension after Serve budget windows through /v2/reports #4290 merged, and one on its fixes; none found a bug. Their quality findings are fixed:

  • the run routes refuse other kinds through their own check, which refuses any kind it doesn't take by default;
  • an unreachable 409 mapping is removed;
  • the 503 description lists every 503;
  • docstrings are updated;
  • tests are added for the service with a database that can't be opened, for the sessions open during the call, for household reports and for a window run with no year;
  • the run list matches on the run routes' kinds with no default, so a kind added later fails mypy until its list is written.

• Left as they are, with reasons:

  • The run ID in the simulation service's 201 isn't compared with the run read back. No other run can start while the new one is pending or running, so the newest run read back is the new one.
  • The re-run client keeps its own answer-reading helpers. Serve budget windows through /v2/reports #4290 and Serve household reports through /v2/reports #4293 both change the create client's module, so its private helpers stay unshared until both merge.
  • The 503 after Modal refused the call names the failed run only in its message. That run is also the report's newest run.
  • The read route's kind names and a household-report test helper are not merged with the run routes' copies yet. Serve budget windows through /v2/reports #4290 changes both.

  All of these are revisited after Serve budget windows through /v2/reports #4290 and Serve household reports through /v2/reports #4293 merge.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 98.07692% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.35%. Comparing base (2eae02a) to head (ac5a551).
⚠️ Report is 33 commits behind head on master.

Files with missing lines	Patch %	Lines
...engine_api/fastapi_routes/v2/reports/run_models.py	95.00%	0 Missing and 2 partials ⚠️
...yengine_api/services/v2/stored_reports/services.py	93.93%	0 Missing and 2 partials ⚠️
...ces/v2/stored_reports/database_connectors/reads.py	50.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #4298      +/-   ##
==========================================
+ Coverage   93.22%   93.35%   +0.13%     
==========================================
  Files         357      363       +6     
  Lines       20526    21114     +588     
  Branches     3338     3418      +80     
==========================================
+ Hits        19136    19712     +576     
- Misses        818      823       +5     
- Partials      572      579       +7     

Flag	Coverage Δ
integration	56.43% <57.69%> (+0.56%)	⬆️
unit	90.70% <88.46%> (-0.05%)	⬇️

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.