[anth-volk]

Fixes #1053

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.

Changelog

• This PR adds changelog fragments: changelog.d/v2-budget-windows.added.md and changelog.d/v2-budget-window-capacity.changed.md.

Summary

Budget-window reports on the detailed-save path. A budget-window report compares a reform with its baseline in each year of a window of 1 to 75 years. Its calculation is one budget_window_runs row with one report run per year; at most five years are under way at once. Each year's coordinator, when its year ends, starts the window's earliest waiting years, and the window is marked succeeded once every year has succeeded, or failed as soon as a year fails. This replaces the draft #982, which was built on the simulation service's own tables and scheduled its years through call reports, both since removed.

Simulation service: POST /reports with report_type: "budget_window"

• Request. The body names budget_window_size (1 to 75, ending by 2200) and otherwise the same fields as an economy report, except include_cliffs, which is refused (422). POST /reports tells the two apart by report_type (a discriminated body). A refused body's 422 locations are exactly what an economy report's were before (ReportRequestRoute removes the type Pydantic adds), because the Public API passes them to its callers.
• Rows. In one transaction: an economy report with budget_window_size set and year the first year; inputs holds {"include_cliffs": false} plus spm when given, the same as a single-year report without cliffs, so reuse (which compares inputs) works both ways between windows and single-year reports. One budget_window_runs row (pending, trigger initial, recalculate false, the default worker's catalog version). For each year, a report run naming the window run and the year, on the same versions. Each year has its own baseline and reform simulations of that year, unless reuse finds succeeded runs of that year (find_reusable_run per year; the two sides never share a run). The report names the first year's simulations.
• Start. The service then advances the window as its own role (BudgetWindowStore.advance_window), which starts the earliest five years under the window run's row lock. The first year's coordinator input is built as a single-year report's (report_run_calculation); each later year's is derived from it (year_calculation): only the year, its three runs, its artifact prefix and its call's creation time differ. The first years share one ten-second wait for Modal, counted from the first start: a later year not confirmed within it is deferred (YearStartDeferred) and waits for a started year's coordinator.
• Answers. 201 with report_id, report_run_id (the first year's run), budget_window_run_id, status and every year's report run and simulation runs. A year Modal refuses, or a first year it doesn't confirm in time, fails the window and its waiting years, and answers 503 modal_call_refused naming report_id. Otherwise the economy report's error rules apply (400 and 422 before any write, 500 internal_error, no exception text in detail). The Public API's adapter reads report_id and budget_window_run_id and ignores the rest (agreed with tracker task C1 · 14).
• Ready check. /ready now requires the service role's UPDATE on budget_window_runs' status, error_message, completed_at and updated_at, which Let the simulation roles update a budget-window run's status policyengine-api#4267 grants.
• GET /reports/{report_id} on a window answers one of its years' runs; the window's own status is in budget_window_runs, which the Public API reads.

Stage 12 side (Modal coordinator, workers and sweep)

• BudgetWindowStore (Stage 12 persistence library): an advance locks the window run's row, then fails the window and its waiting years (and their unstarted simulation runs) when a year failed, marks it succeeded when every year succeeded, or starts the earliest waiting years until five are under way, recording each call while the year is still pending with no call. A start Modal refuses fails that year and the window, unless the year's own call claimed it meanwhile. The Modal worker role and the service role may both advance a window.
• Each year's coordinator. The v2 coordinate_report runs every call through coordinate_window_year: it looks the year's window up once, marks the window running before the coordinator runs, and advances it after the coordinator returns, fails or is cancelled, starting the next years in the same Modal application (ModalYearStarter). A pre-emption advances nothing; the rerun advances when it ends, even when it finds its year already finished. A report run outside any window makes no window writes, and no window write changes a year's own outcome.
• Stuck-run sweep. It leaves a waiting year of an unfinished window to the window, counts a year started later from when its call was recorded, fails the window when it fails one of its years, and settles a window that nothing has changed for ten minutes with no year under way: from its years when all have ended, or as stalled (budget_window_stalled).
• Container limits. The coordinator may run 25 calls at once (three windows at five years, and ten other reports), each simulation worker 50 (both simulations of every coordinator call), and the US segment function 1,000 (20 region groups per US simulation call).
• Contract. year_calculation and report_run_artifact_prefix in stage12_execution, shared by the service and the coordinator; the artifact environment check lives there once.

From #982

Ported: the cap of five, the year order, "the first failed year fails the window", the container-limit test. Dropped: the simulation service's own tables and revision 0005, call reports and their safety-check scheduling, totals summed on read (the Public API's, C1 · 14), and /v2/budget-window-reports.

Builds on, and what merges first

• Coordinate economy runs through the run tables instead of the evaluation records #1051 (tracker C1 · 8, coordination through the run tables) and Create economy reports and simulations through POST /reports and POST /simulations #1052 (C1 · 9, POST /simulations and POST /reports) have merged into main, and this branch has merged main in.
• Let the simulation roles update a budget-window run's status policyengine-api#4267 (C1 · 12) has merged: it grants the roles the budget_window_runs updates. It must be deployed before this merges. Until then, the service's /ready fails, and the coordinator's and sweep's window writes are refused.
• libs/policyengine-simulation-persistence/public-api-commit pins #4267's merge commit, the head of the Public API's master. Its v2 migrations and privilege manifest are the same as at the #4267 head the store and records tests ran against.

Environment variables and secrets

No new variable is read.

Name	Provider	Wiring	Verified
SIMULATION_SERVICE_DATABASE_URL	Secret Manager, named by the GitHub Actions variable SIMULATION_SERVICE_DATABASE_URL_SECRET_NAME	unchanged: the Cloud Run deploy script mounts it (add_runtime_secret); the window store uses the service's existing engine	Wiring traced. Unverified: the role holds #4267's grants in staging and production (not deployed yet).
MODAL_WORKER_DATABASE_URL	Modal secret policyengine-modal-worker-database	attached to coordinate_report (report_run_writer_secrets) and to the sweep's sweep_stuck_runs (secrets=[...]), both with required_keys	The secret exists in staging and main (B1 · 7). Unverified: the role holds #4267's grants.
MODAL_TOKEN_ID, MODAL_TOKEN_SECRET, SIMULATION_V2_MODAL_ENVIRONMENT, SIMULATION_V2_MANIFEST_NAME, V2_SIMULATION_OUTPUT_BUCKET	unchanged from #1052	unchanged	As in #1052.

A coordinator starts the next year's call with modal.Function.from_name(...).spawn, using the credentials Modal's container provides, as it starts its workers.

Testing

• Every test this branch adds or changes was run individually by node ID: the budget-window store (28, against PostgreSQL 17 built from Let the simulation roles update a budget-window run's status policyengine-api#4267's head, as the Modal worker role and the service role), the window records (7, same database), the contract derivation (9), the coordinator scheduling and wrapper (19), the year-start binding to the real coordinator (2), the sweep (6, plus the app test), the capacity limits (3, plus the Modal app test), the service's request, submission and route tests (10, 9, 14), the OpenAPI tests changed (3), the access test (1) and the regenerated client's window tests (3). Failing tests were committed first, with "(failing)" in the subject.
• Sim's checks (Ruff, rules rendering, quality guards, lock checks, Pyright) pass for every changed package.
• The Postgres-backed store tests (REPORT_RUN_TEST_DATABASE_URL) skip in CI, as Coordinate economy runs through the run tables instead of the evaluation records #1051's report-run tests do: no workflow sets that variable.
• Five read-only review rounds (review-code): rounds 1 to 3 and two short rounds on later fixes. Every substantiated bug was fixed test-first; the reports are in the session's notes.

🤖 Generated with Claude Code