[anth-volk]

Fixes #981

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.

Summary

After this deploys, the Simulation Entrypoint calculates budget windows on the v2 economy path itself: one reform compared with its baseline in each year of a window of up to 75 years, each year stored as an ordinary v2 economy report run, and the totals summed from the stored rows when the report is read. No user reaches it yet: the Public API's /v2/reports (a separate PR) is its first caller. The old gateway's budget windows (/simulate/economy/budget-window) are unchanged.

It is stacked on #974 (the v2 economy path), which is stacked on #951, #950, #900 and #898.

Budget-window reports and runs (persistence library, revision 0005)

• simulation.reports gains budget_window_size: an economy report with one compares its two simulations in each of that many years from its year (1 to 75, ending no later than the last year a run may have). Only an economy report may have one, which a check constraint and NewReport both enforce.
• simulation.budget_window_runs (new) holds one row per calculation of a budget-window report on a catalog version: its trigger (initial, manual, system), whether its years calculate their simulations again (force), how many years it calculates at once (max_concurrent_years), its status (running, succeeded, failed) and error, when the safety check next looks at it, and the lease of the caller starting its next years (scheduling_claimed_until). It stores no figures.
• simulation.report_runs gains budget_window_run_id: each year of a budget-window run is one report run of the same report and catalog version (composite foreign key fk_report_runs_budget_window_run through uq_budget_window_runs_id_report_catalog_version), with at most one per year (uq_report_runs_budget_window_run_id_year). RunStore.create_report_run refuses a budget-window report's run that is not a year of its window, and a year of a window on any other report.
• BudgetWindowRunStore creates runs (create_first_run adds one only while the report has none, under a transaction-level advisory lock, as first report runs are), claims and releases a run for scheduling, finishes it once with a conditional write, reads each year's report run with both its simulation runs, and reads each year's budget_impacts row in year order.
• RunStore.create_window_year_run records a year's report run, or returns the one another caller recorded for that year first, so a caller that loses still starts the simulation runs it created that the year compares (as a first open of a single-year report that loses does).
• The default privileges give the runtime role SELECT, INSERT and UPDATE on the new table; it needs no new grant. The new foreign key into the Public API's tax_benefit_model_versions uses the REFERENCES grant revision 0003 already needs.
• The downgrade refuses to run while any budget-window report exists: without the window size and the years' link, each year's report run would read as a run of a single-year report.

Running the years: a few at a time (entrypoint)

• EconomyReports gains prepare_report (create a report and its simulations without running it, optionally with a window), report_setup and run_year: one year's two simulation runs and report run, with exactly the single-year path's reuse, forcing, labour-supply and comparison rules. submit and run_report use them unchanged. The single-year path neither runs nor reads a budget-window report: run_report and the economy report reads answer 404 for one.
• BudgetWindowReports (budget_window_reports) submits a budget-window report and its first run, and runs one again (manual, or system, which returns the report's newest run when it has one, before reading the catalog). A re-run whose catalog version cannot resolve the report's region or dataset is refused with 422 before anything is written, as a single-year re-run is. A run starts its years in year order, at most max_concurrent_years at once: BUDGET_WINDOW_MAX_CONCURRENT_YEARS, five, now in the contract so the entrypoint and the Modal app share it. Its years are the batch's children; there is no Modal batch call: each year's simulation and comparison calls are the v2 economy path's own, each reporting its end as Run and store v2 economy reports in the Simulation Entrypoint #974's calls do.
• A caller starting a run's years first claims the run for a two-minute lease, so two callers do not start the same year; it releases only its own claim (named by the time it lasts until), with the run's next safety-check time (five minutes on), and tries again, at most three times, when a year finished while it held the claim. A caller whose lease ended while it worked meets the next caller at the one-report-run-per-year constraint and shares its report run.
• The next years start when a reported call frees a year's place: YearStartingRecorder wraps the call recorder, after ComparisonStartingRecorder, so a recorded comparison (or a simulation run's end) starts them. Each safety-check pass also starts the years of running runs whose check is due, so a run whose caller stopped carries on.
• The first failed year (a simulation run or the comparison) fails the run with that year's error code and message; a year that cannot start (its region missing from the catalog version, say) fails it as invalid_input. Years already running finish and keep their results. Once every year has succeeded the run has succeeded.

Reading and the totals

• A report reads with its newest run, and a run with every year of its window: started years with their report runs' status, stage and error; years not started yet as pending/queued; years a finished run never started as not_run. A run reads as failed as soon as one year has failed, and as succeeded once every year has; progress is the share of years that succeeded.
• Once it has succeeded, its result is today's budget-window format (the JSON the old gateway answers with), built from each year's stored budget_impacts row. Its models are the v2 path's own (BudgetWindowReportResult, BudgetWindowYearImpact, BudgetWindowTotalImpact), so a change to the old gateway's models never changes this contract; they leave out the old gateway's SPM provenance, which v2 budget windows never have. The totals are summed in decimal arithmetic from each float's shortest form and returned as floats, as the old gateway does (0.1 + 0.2 + 0.3 totals 0.6). The federal figure is the tax revenue change less the state one. A succeeded run missing a year's figures answers a declared 500.

Routes

POST /v2/budget-window-reports (201), GET /v2/budget-window-reports/{report_id}, POST /v2/budget-window-reports/{report_id}/runs (201) and GET /v2/budget-window-reports/{report_id}/runs (budget_window_routes), with simulation:submit for submissions and simulation:read for reads, as the economy routes. They declare the same error answers for the generated client (404 and 503 as EconomyErrorResponse, 422 as EconomyRefusalResponse, and 500 on the report read), and answer 503 without the simulation database or the Modal environment. A window has 1 to 75 years and ends in 2099 or earlier, as the old gateway's do. The generated client gains submit_budget_window_report, get_budget_window_report, run_budget_window_report and list_budget_window_report_runs.

Modal capacity

In the v2 Modal app:

• the economy simulation functions (US and UK) go from 10 to 40 containers: three windows at the cap (two simulations a year) and the 10 they had for other reports;
• the comparison function from 10 to 25: three windows' comparisons and its 10;
• the US segment function from 300 to 1,000: the 20 segments of every US simulation call that may run at once (40 v2 economy simulations and 10 Stage 12 ones), so no segment waits behind the limit, which would count against its caller's time limit. Stage 12 calls use this function too.

test_economy_run_capacity checks these relations. Time limits are unchanged; see "Time limits".

Staging qualification against the old gateway: an operator step

authenticated_tests/test_staging_budget_window_qualification.py is an operator step, not a CI check. An operator runs it once against staging after this is deployed there. It submits the same reform, region and years to the v2 route and to the old gateway's route, and requires each year's figures and the totals to agree within 0.1% or 1,000 (both configurable); its window has seven years against the cap of five, so its last years start only when earlier years report their ends or the safety check passes; and running the report again unforced must read back the same figures. It is an operator step because the v2 report needs a reform saved in the staging Public API database (given as its policy ID, and as its parameter values for the old gateway), which nothing creates in CI without writing to staging, and because both windows cost Modal time for every year, too much for every staging deployment. The module's docstring lists every input.

Decisions, for the reviewer

• No Modal batch call. The "batch with one child per year" is the budget-window run and its years' report runs, scheduled by the entrypoint, because Run and store v2 economy reports in the Simulation Entrypoint #974 starts every simulation and comparison call from the entrypoint and records each call's end. Pre-emption follows the pre-emption decision recorded in Let the v2 report coordinator return a typed result to its caller #896: each year's calls are Run and store v2 economy reports in the Simulation Entrypoint #974's, so a pre-empted US national simulation cancels its segments and Modal runs it again under the same call ID; there is no batch call to pre-empt.
• The cap is sim's, not the caller's: five years at once for every window. The old gateway lets a caller choose up to 20, but its children were never segmented; a US national year here is up to 40 segment calls.
• A window is its own report. A budget-window report is an economy report with a window size, so its years reuse the single-year path; the single-year routes answer 404 for it, and the budget-window routes 404 for a single-year report.
• A failed year fails the window, as the old gateway's batch does; the years already running are not cancelled, because their simulation runs may be shared with other reports.
• Report options must be empty, as for Run and store v2 economy reports in the Simulation Entrypoint #974's economy reports.
• Years start inside the call-report request. Starting a window's next years runs in the request that records a call's end (up to three passes of up to five years, two Modal spawns a year), because no CPU is kept allocated outside requests; the reporter retries a slow answer, which changes nothing the second time.
• Capacity is per window, not overall. Each window is capped at five years at once, and the container limits assume about three windows at once; more windows (or a re-run while a run is still going) queue in Modal rather than failing.
• The lease uses each instance's clock, as Run and store v2 economy reports in the Simulation Entrypoint #974's run transitions do for their own leases.

Overlap

• Revision 0005: Calculate and store households through the v2 household functions #957 (the household path) also adds a revision 0005 on Run and store v2 economy reports in the Simulation Entrypoint #974's chain head. Revisions in this chain merge one at a time; whichever merges second renumbers its revision onto the other's.
• Calculate and store households through the v2 household functions #957 also changes runs.py, run_store.py, app.py, safety_check.py, simulation_database.py and the v2 Modal app. This PR keeps its own code in new modules (budget_window_runs, budget_window_store, budget_window_reports, budget_window_reads, budget_window_routes, budget_window_schemas) and changes those shared modules only where it must; whichever merges second rebases.
• economy_routes makes three helpers public for the budget-window modules (report_run_progress, simulation_response, answer_route), with no change in behaviour.

Time limits

Unchanged, as decided: the US economy simulation call 3,900 s, the UK one 3,000 s, each segment call 3,600 s, the comparison 1,800 s. A US national simulation call's limit includes waiting for its segment calls, and is only 300 s longer than a segment's own, so segment calls queued behind a container limit count against it. The new segment limit covers every US simulation call the functions allow at once; whether the Modal workspace can run that many 8-CPU, 32 GiB containers at once is not known here, and if it cannot, segments queue and a slow year could time out, which fails its window.

Environment variables

No new variable. The changed code reads:

• SIMULATION_DATABASE_URL (entrypoint and safety-check job): unchanged wiring from Give the Simulation Entrypoint its own simulation schema, migration chain and database connection #898 and Record simulation runs and report runs, and their outcomes when Modal reports a call ended #950: Secret Manager, named by the beta/prod variable SIMULATION_DATABASE_URL_SECRET_NAME, mounted by deploy-cloud-run-simulation-entry.sh and copied into the safety-check job. The budget-window path uses it as the economy path does. Revision 0005 needs no new grant. Not verified in a deployment.
• MODAL_TOKEN_ID, MODAL_TOKEN_SECRET (entrypoint and safety-check job; they start each year's calls): unchanged from Record simulation runs and report runs, and their outcomes when Modal reports a call ended #950 and Run and store v2 economy reports in the Simulation Entrypoint #974: Secret Manager, named by MODAL_TOKEN_ID_SECRET_NAME and MODAL_TOKEN_SECRET_SECRET_NAME. Not verified in a deployment.
• SIMULATION_CALL_REPORT_MODAL_ENVIRONMENT and APP_ENVIRONMENT: unchanged from Run and store v2 economy reports in the Simulation Entrypoint #974; the budget-window path is built only where the economy path is, in the same Modal environment and artifact environment.
• Modal functions: only max_containers changes; their secrets and variables are Run and store v2 economy reports in the Simulation Entrypoint #974's.
• The qualification (operator step): SIMULATION_ENTRYPOINT_TEST_BASE_URL, SIMULATION_ENTRYPOINT_TEST_AUTH_ISSUER, _AUDIENCE, _CLIENT_ID, _CLIENT_SECRET, SIMULATION_STAGING_BUDGET_WINDOW_QUALIFICATION and the SIMULATION_QUALIFICATION_* inputs come from the operator's shell; the auth values are the beta environment's test-client secrets the deployed-auth checks use. No workflow passes them.

Waits for

• Run and store v2 economy reports in the Simulation Entrypoint #974 and the PRs below it (Store every simulation result as rows and rebuild today's result format from them #951, 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, Give the Simulation Entrypoint its own simulation schema, migration chain and database connection #898), and everything they wait for, including the operator steps for sim's database roles and grants, MODAL_WORKSPACE_ID and the safety-check schedule.
• One-at-a-time merging of revision 0005 with Calculate and store households through the v2 household functions #957's.
• The Public API's /v2/reports budget-window support (a separate PR) needs a published release of the simulation client containing these routes; publishing follows the production deployment.
• After deployment to staging: the qualification above (an operator step).

Testing

Locally, each commit was written test-first: each new or changed test was seen failing for the expected reason, then passing. Each commit also ran ruff 0.15.22 (format and check), Pyright on each changed package (python -m scripts.rules pyright), and scripts/run_quality_guards.py; every commit in the branch was checked with ruff and the guards again in a clean worktree.

Tests run (only the tests this branch adds or changes; CI runs the rest):

• persistence, against PostgreSQL 17: tests/test_budget_window_runs.py (new: the revision's upgrade, alembic check, downgrade to 0004 and upgrade again, the refused downgrade, the store's claims and releases, simultaneous claims, first runs and year inserts) and the changed test in tests/test_schema.py;
• entrypoint: tests/test_economy_report_years.py, test_budget_window_reports.py, test_budget_window_reads.py, test_budget_window_routes.py, test_budget_window_safety_check.py, test_budget_window_qualification.py (all new), and the new or changed tests in tests/test_openapi.py;
• executor: tests/test_economy_run_capacity.py (new) and the changed test in tests/test_stage12_modal_app.py.

The OpenAPI document was generated from this branch and the Python client from it with scripts/generate-clients.sh. Driven against the app with in-memory stores, the client parses each new route's answers: 201 and 200 bodies, 404, 422 and 503.

Not run: the whole test suites, and anything against a deployed service, Modal app or database, including the qualification.

🤖 Generated with Claude Code