diff --git a/.github/scripts/deploy-cloud-run-simulation-entry.sh b/.github/scripts/deploy-cloud-run-simulation-entry.sh index 6f0108438..cbe60559e 100755 --- a/.github/scripts/deploy-cloud-run-simulation-entry.sh +++ b/.github/scripts/deploy-cloud-run-simulation-entry.sh @@ -102,7 +102,6 @@ required_variables=( SIMULATION_SERVICE_DATABASE_URL_SECRET_NAME MODAL_TOKEN_ID_SECRET_NAME MODAL_TOKEN_SECRET_SECRET_NAME - V2_SIMULATION_OUTPUT_BUCKET_VALUE OBSERVABILITY_SERVICE_NAMESPACE OBSERVABILITY_TRACE_PROJECT_ID OTEL_EXPORTER_OTLP_ENDPOINT @@ -129,11 +128,6 @@ esac || fail "TAG is invalid" [[ "${ENTRYPOINT_RUNTIME_SERVICE_ACCOUNT}" =~ ^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.gserviceaccount\.com$ ]] \ || fail "ENTRYPOINT_RUNTIME_SERVICE_ACCOUNT is invalid" -# The bucket that keeps v2 simulation output files for good: a report -# reuses only a succeeded run whose file is in it. The service compares -# output URIs with it and never reads it. -[[ "${V2_SIMULATION_OUTPUT_BUCKET_VALUE}" =~ ^[a-z0-9][a-z0-9._-]{1,61}[a-z0-9]$ ]] \ - || fail "V2_SIMULATION_OUTPUT_BUCKET_VALUE is invalid" [[ "${ENTRYPOINT_MIN_INSTANCES}" =~ ^[0-9]+$ ]] \ || fail "ENTRYPOINT_MIN_INSTANCES must be a non-negative integer" [[ "${ENTRYPOINT_MAX_INSTANCES}" =~ ^[0-9]+$ ]] \ @@ -201,7 +195,6 @@ jq -n ' POLICYENGINE_OTEL_GOOGLE_AUDIENCE: env.POLICYENGINE_OTEL_GOOGLE_AUDIENCE, SIMULATION_V2_MODAL_ENVIRONMENT: env.MODAL_ENVIRONMENT, SIMULATION_V2_MANIFEST_NAME: "simulation-api-v2-version-manifest", - V2_SIMULATION_OUTPUT_BUCKET: env.V2_SIMULATION_OUTPUT_BUCKET_VALUE, STAGE12_ENABLED: ( if env.DEPLOY_STAGE12_V2 == "true" then env.STAGE12_ENABLED_VALUE else "0" end ) diff --git a/.github/scripts/simulation-staging-economy-check.sh b/.github/scripts/simulation-staging-economy-check.sh index ae24e8673..6f420c2fb 100755 --- a/.github/scripts/simulation-staging-economy-check.sh +++ b/.github/scripts/simulation-staging-economy-check.sh @@ -1,7 +1,11 @@ #!/bin/bash -# Create a small economy report through a deployed Simulation Entrypoint, and -# require its run to succeed: current law against current law for Wales in -# 2026, which needs no stored policy. +# Send a small economy report request through a deployed Simulation +# Entrypoint, force a new run of the report, and require that run to succeed: +# current law against current law for Wales in 2026, which needs no stored +# policy. The request reuses the simulation runs an earlier check on the same +# versions calculated (and, once reports are found by key, ends on that +# check's report run), so only a forced run, which nothing joins or reuses, +# calculates both simulations on every deploy. # Usage: simulation-staging-economy-check.sh # Required env vars: the test client's SIMULATION_TEST_AUTH_ISSUER, # SIMULATION_TEST_AUTH_AUDIENCE, SIMULATION_TEST_AUTH_CLIENT_ID and @@ -9,9 +13,9 @@ # Optional: ECONOMY_CHECK_DEADLINE_SECONDS (1800) and # ECONOMY_CHECK_POLL_SECONDS (15). # The access token is sent from a file and the client secret on standard -# input, so neither appears on a command line. The submission, which isn't -# asked again, may take 60 seconds, Cloud Run's own limit; every other -# request 30. A read that gets no answer, a 429 or any 5xx is asked again +# input, so neither appears on a command line. The submission and the forced +# re-run, neither asked again, may each take 60 seconds, Cloud Run's own +# limit; every other request 30. A read that gets no answer, a 429 or any 5xx is asked again # until the deadline. set -euo pipefail @@ -86,12 +90,23 @@ submission_status="$( || fail "POST /reports answered ${submission_status}: $(cat "${work_directory}/submission.json")" submission="${work_directory}/submission.json" report_id="$(jq -r '.report_id // empty' "${submission}")" -report_run_id="$(jq -r '.report_run_id // empty' "${submission}")" +found_run_id="$(jq -r '.report_run_id // empty' "${submission}")" [[ "${report_id}" =~ ${uuid_pattern} ]] || fail "the submission named no report" -[[ "${report_run_id}" =~ ${uuid_pattern} ]] || fail "the submission named no report run" -printf 'Created report %s, run %s (baseline reused: %s, reform reused: %s)\n' \ - "${report_id}" "${report_run_id}" \ - "$(jq -r '.baseline_reused' "${submission}")" "$(jq -r '.reform_reused' "${submission}")" +[[ "${found_run_id}" =~ ${uuid_pattern} ]] || fail "the submission named no report run" +printf 'Report request answered report %s, run %s (%s)\n' \ + "${report_id}" "${found_run_id}" "$(jq -r '.status' "${submission}")" + +rerun_url="${base_url}/reports/${report_id}/runs" +rerun_status="$( + jq -n '{force: true}' \ + | send rerun "${submission_timeout_seconds}" --request POST --header "@${authorization_header}" \ + --header 'Content-Type: application/json' --data @- "${rerun_url}" +)" || fail "POST /reports/${report_id}/runs got no answer; it may have created a run" +[[ "${rerun_status}" == "201" ]] \ + || fail "POST /reports/${report_id}/runs answered ${rerun_status}: $(cat "${work_directory}/rerun.json")" +report_run_id="$(jq -r '.report_run_id // empty' "${work_directory}/rerun.json")" +[[ "${report_run_id}" =~ ${uuid_pattern} ]] || fail "the forced re-run named no report run" +printf 'Started forced run %s of report %s\n' "${report_run_id}" "${report_id}" started_at="${SECONDS}" # What the last read found, for the deadline's failure message. @@ -107,7 +122,7 @@ while true; do elif [[ "${read_status}" == "200" ]]; then newest_run_id="$(jq -r '.run.run_id // empty' "${report_body}")" [[ "${newest_run_id}" == "${report_run_id}" ]] \ - || fail "report ${report_id}'s newest run is ${newest_run_id:-missing}, not the created run ${report_run_id}" + || fail "report ${report_id}'s newest run is ${newest_run_id:-missing}, not the forced run ${report_run_id}" run_status="$(jq -r '.run.status' "${report_body}")" last_read="the run was ${run_status}" case "${run_status}" in diff --git a/.github/workflows/simulation-deploy.reusable.yml b/.github/workflows/simulation-deploy.reusable.yml index 7cc03a07f..309092f45 100644 --- a/.github/workflows/simulation-deploy.reusable.yml +++ b/.github/workflows/simulation-deploy.reusable.yml @@ -247,7 +247,6 @@ jobs: STAGE12_DATABASE_URL_SECRET_NAME: ${{ vars.STAGE12_DATABASE_URL_SECRET_NAME }} MODAL_TOKEN_ID_SECRET_NAME: ${{ vars.MODAL_TOKEN_ID_SECRET_NAME }} MODAL_TOKEN_SECRET_SECRET_NAME: ${{ vars.MODAL_TOKEN_SECRET_SECRET_NAME }} - V2_SIMULATION_OUTPUT_BUCKET_VALUE: ${{ vars.V2_SIMULATION_OUTPUT_BUCKET }} run: .github/scripts/deploy-cloud-run-simulation-entry.sh - name: Resolve exact candidate metadata diff --git a/changelog.d/1073.changed.md b/changelog.d/1073.changed.md new file mode 100644 index 000000000..ece83ac3f --- /dev/null +++ b/changelog.d/1073.changed.md @@ -0,0 +1 @@ +Identical simulation, report and budget-window requests now end on the same rows, sent together or apart. `POST /reports` (economy, budget-window and household reports), `POST /simulations` and the re-run routes find or create each simulation and report by a key of its definition and join its run on the default worker's versions when one hasn't failed and wasn't forced, so the service starts a Modal calculation only for a run its own request created; a budget-window year and a single-year report of that year share their simulation runs. A re-run with `force`, and every re-run of a report created before keys, calculates an extra run marked forced that nothing joins. No re-run answers 409 `run_in_progress` any more. The service stores no report label, description or user and no run trigger on these shared rows: `label` and `description` are accepted, optional, and not stored. diff --git a/changelog.d/1073.removed.md b/changelog.d/1073.removed.md new file mode 100644 index 000000000..d61de2bd3 --- /dev/null +++ b/changelog.d/1073.removed.md @@ -0,0 +1 @@ +`POST /reports` refuses `include_cliffs: true` with 422 `cliffs_not_available`, and so does a re-run of a stored report that asked for cliffs, until cliff impacts are calculated for each simulation run. diff --git a/changelog.d/1081.removed.md b/changelog.d/1081.removed.md new file mode 100644 index 000000000..27063045c --- /dev/null +++ b/changelog.d/1081.removed.md @@ -0,0 +1 @@ +The Simulation Entrypoint's deployment no longer sets `V2_SIMULATION_OUTPUT_BUCKET` on its Cloud Run service or requires the `beta` and `prod` GitHub variable of that name for the entrypoint's deploy step; the service never used it. The Stage 12 deployment steps still pass it to the Modal coordinator and workers, which write simulation output files to that bucket. The simulation persistence library drops the create functions that use no definition keys, the search for an earlier succeeded simulation run to reuse, and the `reuse` parameters of the economy store's input reads, none of which the service has called since reports, simulations and runs are found or created by key. Requests and answers are unchanged. diff --git a/docs/migration/stage-12-modal-worker-foundation.md b/docs/migration/stage-12-modal-worker-foundation.md index 457cdd6b7..9113dcb74 100644 --- a/docs/migration/stage-12-modal-worker-foundation.md +++ b/docs/migration/stage-12-modal-worker-foundation.md @@ -288,12 +288,15 @@ creates or claims a `stage12_evaluation_*` record. Only comparison-path calls, which pass an evaluation record, write those, until the comparison path is removed. The household functions work the same way on `household_jobs`. -**A report run.** The simulation service creates, in one transaction, the -`simulations` and `reports` rows, a `simulation_runs` row for the baseline and -one for the reform (pending, with no `modal_call_id`; or a run that already -succeeded, to reuse it), and the `report_runs` row naming both (pending, with no -`modal_call_id`). It then starts the manifest's `report_coordinator_callable` -(`coordinate_report`) with two arguments and no evaluation record: +**A report run.** The simulation service finds or creates by definition key, +in one transaction, the `simulations` and `reports` rows, a `simulation_runs` +row for the baseline and one for the reform (pending, with no `modal_call_id`; +or a run of the same simulation on the same versions that it joins, which may +have succeeded already), and the `report_runs` row naming both (pending, with +no `modal_call_id`, or a run on the same versions that it joins). For a report +run it created, it then starts the manifest's `report_coordinator_callable` +(`coordinate_report`) with two arguments and no evaluation record; a joined +report run gets no call: - the report input, a `ReportExecutionInput` whose `evaluation_id` is the report run's ID and whose baseline and reform `simulation_execution_id`s are their @@ -313,7 +316,7 @@ run row naming other simulation runs, fails the report run with `report_run_input_mismatch`. If a worker it starts finds its run held by another call, the coordinator waits for that run instead (see "Shared simulation runs" below). It uses the stored output of each simulation run -that already succeeded (see the reuse of succeeded runs above), fails the +that already succeeded (see the joined runs above), fails the report run with the run's own recorded failure if a run it must calculate already failed (`simulation_run_failed` if it recorded none), and starts a worker for each other one with a context naming only that @@ -327,8 +330,10 @@ once. It returns `{"report_run_id", "status"}`, or the same marked `deduplicated` without running when another call holds the report run or it has finished. -**A simulation run on its own.** The service creates the `simulations` row and -its `simulation_runs` row (pending, no call), starts the country's +**A simulation run on its own.** The service finds or creates by definition +key the `simulations` row and its `simulation_runs` row (pending, no call, or +a run on the same versions that it joins, which gets no call). For a run it +created, it starts the country's `single_simulation_callable` with a `SimulationExecutionInput` (role `standalone`, no output plan, `evaluation_id` and `simulation_execution_id` both the run's ID) and a context naming the run in `simulation_run_id`, with @@ -338,15 +343,20 @@ call as for a report run. A prefix without it fails the run. The worker plans th outputs with its stored plan, as a report run's coordinator does (below). **A re-run.** The service re-runs a stored report or simulation with the same -two calls, by run ID. It creates the record's new run (a report run with -trigger `manual`) and, for a report, a new `simulation_runs` row of each side's -own simulation, or names that simulation's run that already succeeded on the -same versions, unless the re-run is forced. The new runs record the catalog -version, dataset and region of the current .py version's catalog; the -`simulations` and `reports` rows are unchanged. A budget-window report's -re-run is a new `budget_window_runs` row (trigger `manual`) with a report run -per year, each on its year's own simulations, started as a new window's -first years are. The coordinator and workers claim and calculate them as +two calls, by run ID. A simulation's re-run, which takes no `force`, joins +the simulation's run on the current versions, catalog version and year that +hasn't failed and wasn't forced, which gets no call, or else creates one. A +report's re-run, for a report created by key and unless forced, joins the +report's run on the current versions the same way, or else creates the +report's new run naming each side's simulation run on those versions, found +or inserted (C1 · 24's answers 3 and 8); a forced re-run, and every re-run +of a report created before keys, creates an extra run on a new run of each +side, all marked forced. No new run names a trigger (answer 6). The new runs record the +catalog version, dataset and region of the current .py version's catalog; +the `simulations` and `reports` rows are unchanged. A budget-window report's +re-run joins or creates a `budget_window_runs` row with a report run per +year, each on its year's own simulations, a new one started as a new +window's first years are. The coordinator and workers claim and calculate them as they would a new record's: nothing on the Modal side tells a re-run apart. **Each worker** claims its simulation run under its own Modal call ID: a pending @@ -435,9 +445,11 @@ window of 1 to 75 consecutive years. It is an economy report whose the year, with its own simulation runs of that year, so a year can reuse a single-year report's runs, and the reverse. -- **Creating and starting.** The simulation service creates every year's runs - in one transaction, all pending with no call, then starts the earliest - years within one ten-second wait for Modal, counted from the first start; +- **Creating and starting.** The simulation service finds or creates the + window and its window run by key, in one transaction; a window run it + creates names every year's report run, each on its year's simulation runs, + found or created, and every run it creates is pending with no call. For a + window run it created, it then starts the earliest years within 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. The contract's `year_calculation` derives each year's coordinator @@ -921,11 +933,12 @@ pre-emption records nothing. An error in the report run's claim, or in the read of its simulation runs, fails the report run if the claim applied before the error, and leaves its simulation runs to the stuck-run sweep. -A household report's re-run (`POST /reports/{report_id}/runs`) is a new -report run, trigger `manual`, naming a new run of each side's own household -simulation on the current catalog version, in the report's year. The -service starts one call for it, as for a new household report, and the -function claims and calculates it as it would a new report's run. +A household report's re-run (`POST /reports/{report_id}/runs`) joins or +creates its report run as an economy report's does, each side's run of its +own household simulation on the current catalog version, in the report's +year. The service starts one call for a run it created, as for a new +household report, and the function claims and calculates it as it would a +new report's run. The stuck-run sweep (`src/modal/run_sweep_app.py`) fails household jobs nothing will finish by the rule it applies to report runs and simulation diff --git a/libs/policyengine-simulation-persistence/README.md b/libs/policyengine-simulation-persistence/README.md index b3ca22046..46106b720 100644 --- a/libs/policyengine-simulation-persistence/README.md +++ b/libs/policyengine-simulation-persistence/README.md @@ -83,28 +83,16 @@ runs too long and the limit never stays on a pooled connection. ## Economy simulations and reports -`economy_run_records.py` holds the simulation service's reads and writes for -an economy report, or a standalone economy simulation. It reads the -country's model (`read_model_id`) and a catalog version's region by code -(`read_region`) and dataset by name or ID (`read_dataset`, -`read_dataset_by_id`). `insert_economy_report` creates, in the caller's -transaction, each side's new simulation and first run, the report naming -both simulations and the reform's policy with its options in `inputs`, and -its first report run, trigger `initial`; every run is `pending` with no -Modal call ID. A side may instead name a run that already succeeded -(`ReportSimulation.reused`), for which nothing is created. -`insert_economy_simulation` creates a standalone simulation and its first -run. A row naming one that does not exist is refused by its foreign key with -SQLSTATE `23503`; `EconomyRecordReferenceError` names the table and column. - -`find_reusable_run` returns the run a new report's side may reuse: the -newest, by completion, of the same economy simulation (policy, dynamic, -catalog version, dataset, region and year) that succeeded on the same -country package and .py versions, whose output file is under the output -bucket's `gs:///`, that a succeeded report run with the same options -used, and that no report run refused to reuse (an error message starting -`reused_simulation_`). So a submission after a refused reuse calculates the -simulation again. +`economy_run_records.py` holds the simulation service's catalog reads and +run writes for an economy report, or a standalone economy simulation. It +reads the country's model (`read_model_id`) and a catalog version's region +by code (`read_region`) and dataset by name or ID (`read_dataset`, +`read_dataset_by_id`), and builds a simulation run `pending` with no Modal +call ID (`simulation_run_row`, `insert_simulation_run`). The Simulation +Entrypoint creates every simulation, report and run by key ("Shared +simulations, reports and runs" below). A row naming one that does not exist +is refused by its foreign key with SQLSTATE `23503`; +`EconomyRecordReferenceError` names the table and column. `record_report_run_call` and `record_simulation_run_call` record a Modal call's ID, and `fail_unstarted_report_run` and @@ -115,9 +103,9 @@ with its newest run's state. `EconomyRunStore` runs them as the Simulation Entrypoint does, each step in a transaction of its own: `read_report_inputs` reads the catalog version, -model, region and dataset, each side's policy and dynamic values, and each -side's reusable run together, never giving both sides the same run; -`read_simulation_inputs` does the same for one simulation; the writes and +model, region and dataset, and each side's policy and dynamic values +together; `read_simulation_inputs` does the same for one simulation, and +`read_budget_window_inputs` for a budget window's two sides; the writes and reads each take their own. A missing region or dataset raises `UnknownRegionError` or `UnknownDatasetError`, and a report side's refused policy or dynamic raises `ReportSideError`, naming the side. A create whose @@ -125,25 +113,84 @@ commit fails after its rows were inserted raises `EconomyRecordOutcomeUnknownError`: PostgreSQL may have applied the commit, so the rows may exist. +## Shared simulations, reports and runs + +Identical requests, together or a minute apart, end on the same simulation, +report and run rows (C1 · 24). These modules do it: + +- `definition_keys.py` builds each record's key: the lowercase SHA-256 of + a definition's canonical JSON (keys sorted, no spaces, UTF-8, UUIDs as + lowercase strings, missing values null), with `KEY_VERSION` 1 inside the + object and in its own column. `EconomySimulationDefinition` keys a + simulation by its country, policy, dynamic, dataset name, region code, + year, a null filter and the SPM selection; `EconomyReportDefinition` keys + a report by both sides' policies and dynamics, the dataset, region, year + and SPM selection they share, and its budget window size, with no other + option, and gives its `dataset_independent_key` (the same without the + dataset) and each side's simulation definition. `HouseholdSimulationDefinition` + keys a household simulation by its country, policy, dynamic, stored + household and year, and `HouseholdReportDefinition` a household report by + its sides (the reform null for the baseline alone), household and year. + Names and codes, not + catalog IDs, so a record keeps its key across releases. +- `shared_rows.py` finds a row by its definition or version set, or inserts + it: one `INSERT … ON CONFLICT DO NOTHING` against the Public API's unique + index (a simulation's or report's `(key_version, definition_key)`; a + simulation run's simulation, year, catalog version and versions, or a + report run's report and versions, among runs that haven't failed and + weren't forced, outside budget windows), then a read of the row that + won, retried when that run fails in between (`SharedRowNotSettledError` + after three tries). A forced run is inserted directly and never looked + up or joined. +- `keyed_economy_records.py` runs a report's find-or-create in one + transaction: each side's simulation by key, in key order; the report by + key; the report's joinable run on the current versions, joined with the + simulation runs it names; or else, inside a savepoint, each distinct + simulation's joinable run (whatever report first calculated it), found + or inserted, and the report run naming them, a competing report run + joined with the savepoint rolled back (`find_or_insert_report_run_on_sides`, + which the keyed re-runs share). + `find_or_create_household_report` (`keyed_household_records.py`) does + the same for a household report, its simulations keyed by household, and + `find_or_create_economy_simulation` for one + simulation. The answers say what the request inserted, so only it starts + a Modal call. `EconomyRunStore.find_or_create_report` and + `find_or_create_simulation` run them in a transaction of their own. +- `keyed_window_records.py` does it for a budget window + (`find_or_create_budget_window`): each year's simulations by that year's + key, in key order across every year, so a window year and a single-year + report of that year share them; the report by its key (window size and + first year in it); its window run on the current catalog and .py versions + that hasn't failed and isn't a recalculation, joined with its year runs; + or else the window run first (`find_or_insert_window_run`, against the + Public API's window run index, so a concurrent identical request waits + for it and joins it), recording its .py version, then every year's side + runs, found or inserted in simulation ID order, and each year's report + run (`insert_window_years`, which the window re-runs share). + `EconomyRunStore.find_or_create_budget_window` runs it in a transaction + of its own. No keyed create writes a label, description, user or trigger + (C1 · 24's answer 6): each user's saved report and report-run record hold + them, in the Public API. + ## Household reports -`household_report_records.py` holds the simulation service's writes for a -household report: one stored household, for one year, under a baseline and, -optionally, a reform. `insert_household_report` creates, in the caller's -transaction, a household simulation (no dataset or region) and its first -run for each side, never reusing one; the report, of type `household`, -naming the household, both simulations and the reform's policy, with its -options in `inputs`; and its first report run, trigger `initial`, naming no -reform run for a report of the baseline alone. Every run is `pending` with -no Modal call ID, and a row naming one that does not exist is refused as -`EconomyRecordReferenceError`. +A household report calculates one stored household, for one year, under a +baseline and, optionally, a reform. Its report has type `household` +(`HOUSEHOLD_REPORT_TYPE`) and names the household, and each side is a +household simulation (no dataset or region) naming the side's policy. +`keyed_household_records.py` finds or creates the report, its simulations +and its run by key, as an economy report's are (C1 · 24's answer 8); +`household_report_records.py` builds each side's run, `pending` with no +Modal call ID (`household_simulation_run_row`, +`insert_household_simulation_run`). A row naming one that does not exist +is refused as `EconomyRecordReferenceError`. `HouseholdReportStore` runs the steps in transactions of their own: `read_inputs` reads the catalog version for the .py version, the country's model, the stored household and each side's policy values together, raising `UnknownCatalogVersionError`, `UnknownHouseholdError` or `ReportSideError` for the side whose policy is missing or sets parameters -the catalog version lacks; `create_report` raises +the catalog version lacks; `find_or_create_report` raises `EconomyRecordOutcomeUnknownError` when the commit fails after the rows were inserted; and `record_report_call` and `fail_unstarted_report` use the economy report run writes. @@ -160,44 +207,54 @@ version, dataset and region it calculates on. record calculates: its kind (`economy`, `budget_window`, `household` or `unsupported`), country, year, its region's code and dataset's name, and each simulation's policy and dynamic. -- `find_reusable_run_of` searches one simulation's runs, by its ID, under - `find_reusable_run`'s conditions on a run (versions, the run's own catalog - version, dataset, region and year, the output file, a succeeded report run - with the same options, no refused reuse); it doesn't compare the - simulation row, which keeps the catalog rows it was created on. -- `insert_report_rerun` creates a report's new run, trigger `manual`, and a - new run of each side's simulation that reuses none; - `insert_simulation_rerun` creates a simulation's new run. Each refuses with - `RunInProgressError`, naming the run, while the record has a run `pending` - or `running` (for a report, a report run; for a simulation, any of its - runs), and first takes `lock_reruns_of`, a transaction-level - advisory lock on the record's ID, so concurrent re-runs of one record - wait for each other. When the database refuses the new run's key to the +- `insert_report_rerun` joins the report's run on the re-run's versions + that hasn't failed and wasn't forced (pending, running or succeeded), + creating nothing, or else creates the report's new run, naming no + trigger (answer 6), each side joining its simulation's run on those versions that hasn't + failed and wasn't forced, in any state, or inserting one + (`find_or_insert_side_runs`, as a keyed create does). A report run another + request inserts after the lookup is joined, and a savepoint takes back + this call's simulation runs. An unforced one first takes `lock_reruns_of`, + a transaction-level advisory lock on the report's ID, so concurrent + re-runs of one report wait for each other and end on one run. No re-run + is refused while a run is under way. A forced one (`NewReportRerun.forced`) takes no lock, always + creates a new run of each side, marked `forced`, and joins none. + `insert_simulation_rerun` joins or creates the + simulation's run on the re-run's versions, catalog version and year + through `shared_rows`, with no lock. Each returns the run, its status and + whether it created it. When the database refuses the new run's key to the record itself, the record was deleted after it was read: `RerunRecordDeletedError`. A budget window's definition also names its newest budget-window run's years (`WindowYearDefinition`): each year's sides are the simulations of the -runs that year's report run names. `insert_window_rerun` creates the -window's new budget-window run (trigger `manual`, `recalculate` set), a -report run per year and each year's new runs of its own simulations. Every -report re-run is refused while a budget-window run or a report run of the -report is `pending` or `running`. +runs that year's report run names. `insert_window_rerun` joins or creates +the window's run as the window's create does: unforced (a keyed window's +re-run), it takes the re-run lock and joins the report's window run on the +re-run's versions that hasn't failed and isn't a recalculation, with its +year runs, or else inserts the window run and each year's report run on +its sides' runs, found or inserted. One that recalculates is a forced +re-run, never refused, an extra window run whose year runs and simulation +runs are marked `forced`. Either records the window run's .py version and +no trigger, and `EconomyRunStore.create_window_rerun` returns the window +run and years it ended on. A household report's definition also names its household (`household_id`). -`insert_household_report_rerun` creates its new report run (trigger -`manual`) and a new run of each side's own household simulation (no dataset -or region), recording the current catalog version and the report's year: -household runs are never reused. It takes the same lock and makes the same -check for a run under way, and shares `insert_household_simulation_run` with -`insert_household_report`. `HouseholdReportStore.create_report_rerun` runs it -in a transaction of its own; the store's `read_inputs` reads the re-run's -household and policies as it does a new report's. +`insert_household_report_rerun` joins or creates its run as +`insert_report_rerun` does (C1 · 24's answer 8): unforced, as a keyed +report's re-run is, it takes the same lock and joins the report's run on +the re-run's versions, or else each side joins its own household +simulation's run on those versions (no dataset or region, the report's +year) or inserts one, under a new report run (no trigger). A forced +one, as every re-run of a household report without keys is (interim answer +B), takes no lock, is never refused, and marks its report run and a new run +of each side `forced`. `HouseholdReportStore.create_report_rerun` runs it +in a transaction of its own and returns the run; the store's `read_inputs` +reads the re-run's household and policies as it does a new report's. `EconomyRunStore.read_report_rerun_inputs` reads a re-run's catalog rows by -the stored region code and dataset name, and each side's values and -reusable run of its own simulation, never giving both sides the same run. -`read_window_rerun_inputs` does the same for each year of a window. +the stored region code and dataset name, and each side's values. +`read_window_rerun_inputs` does the same for a window's two sides. `create_report_rerun`, `create_window_rerun` and `create_simulation_rerun` run the inserts in a transaction of their own. diff --git a/libs/policyengine-simulation-persistence/public-api-commit b/libs/policyengine-simulation-persistence/public-api-commit index 0954d35d2..06cd4409c 100644 --- a/libs/policyengine-simulation-persistence/public-api-commit +++ b/libs/policyengine-simulation-persistence/public-api-commit @@ -1 +1 @@ -ca4d396ebb13d655e139eb1c6b07e8c4fe20e224 +63cce8273e6a2c3659392d7b1f9dfeb917672645 diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py index 5af229675..8a688c3c8 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py @@ -7,11 +7,17 @@ read_missing_table_privileges, ) from policyengine_simulation_persistence.budget_window_records import ( - BudgetWindowYear, - NewBudgetWindowReport, WindowSide, WindowYearRuns, - insert_budget_window_report, +) +from policyengine_simulation_persistence.definition_keys import ( + KEY_VERSION, + EconomyReportDefinition, + EconomySimulationDefinition, + HouseholdReportDefinition, + HouseholdSimulationDefinition, + canonical_json, + definition_key, ) from policyengine_simulation_persistence.economy_rerun_records import ( HouseholdRerunSide, @@ -23,7 +29,6 @@ ReportDefinition, RerunRecordDeletedError, RerunSide, - RunInProgressError, SideDefinition, SimulationDefinition, WindowRerunYear, @@ -49,18 +54,10 @@ CatalogRegion, EconomyPopulation, EconomyRecordReferenceError, - NewEconomyReport, - NewEconomySimulation, - ReportSimulation, - ReusableRun, RunVersions, SimulationChoice, fail_unstarted_report_run, fail_unstarted_simulation_run, - find_reusable_run, - find_reusable_run_of, - insert_economy_report, - insert_economy_simulation, read_dataset, read_dataset_by_id, read_model_id, @@ -78,7 +75,6 @@ EconomySimulationInputs, ReportSide, ReportSideError, - RunReuse, SideRefusal, SimulationInputs, UnknownDatasetError, @@ -109,15 +105,34 @@ ) from policyengine_simulation_persistence.household_report_records import ( HOUSEHOLD_REPORT_TYPE, - HouseholdReportSimulation, - NewHouseholdReport, - insert_household_report, ) from policyengine_simulation_persistence.household_report_store import ( HouseholdReportInputs, HouseholdReportStore, ) from policyengine_simulation_persistence.input_tables import input_metadata +from policyengine_simulation_persistence.keyed_economy_records import ( + FoundEconomyReport, + FoundEconomySimulation, + FoundSide, + KeyedEconomyReport, + KeyedEconomySimulation, + ProposedSide, + find_or_create_economy_report, + find_or_create_economy_simulation, +) +from policyengine_simulation_persistence.keyed_household_records import ( + FoundHouseholdReport, + KeyedHouseholdReport, + find_or_create_household_report, +) +from policyengine_simulation_persistence.keyed_window_records import ( + FoundBudgetWindow, + FoundWindowYear, + KeyedBudgetWindow, + KeyedWindowYear, + find_or_create_budget_window, +) from policyengine_simulation_persistence.policy_reform import ( MissingPolicyParametersError, OverlappingReformError, @@ -128,6 +143,19 @@ read_dynamic_reform, read_policy_reform, ) +from policyengine_simulation_persistence.shared_rows import ( + FoundReportRun, + FoundRow, + FoundSimulationRun, + FoundWindowRun, + SharedRowNotSettledError, + find_joinable_report_run, + find_or_insert_report, + find_or_insert_report_run, + find_or_insert_simulation, + find_or_insert_simulation_run, + find_or_insert_simulation_runs, +) from policyengine_simulation_persistence.tables import ( LATEST_YEAR, MAX_BUDGET_WINDOW_YEARS, @@ -148,45 +176,60 @@ __all__ = [ "HOUSEHOLD_REPORT_TYPE", + "KEY_VERSION", "LATEST_YEAR", "MAX_BUDGET_WINDOW_YEARS", "SERVICE_TABLE_PRIVILEGES", "SERVICE_UPDATABLE_COLUMNS", "BudgetWindowInputs", - "BudgetWindowYear", "CatalogDataset", "CatalogRegion", "EconomyCatalogRows", "EconomyPopulation", "EconomyRecordOutcomeUnknownError", "EconomyRecordReferenceError", + "EconomyReportDefinition", "EconomyReportInputs", "EconomyReportState", "EconomyRequest", "EconomyRunStore", + "EconomySimulationDefinition", "EconomySimulationInputs", "EconomySimulationState", + "FoundBudgetWindow", + "FoundEconomyReport", + "FoundEconomySimulation", + "FoundHouseholdReport", + "FoundReportRun", + "FoundRow", + "FoundSide", + "FoundSimulationRun", + "FoundWindowRun", + "FoundWindowYear", "HouseholdCalculationInputs", "HouseholdJobRecord", "HouseholdJobReferenceError", "HouseholdJobStatus", "HouseholdJobStore", + "HouseholdReportDefinition", "HouseholdReportInputs", - "HouseholdReportSimulation", "HouseholdReportStore", "HouseholdRerunSide", + "HouseholdSimulationDefinition", + "KeyedBudgetWindow", + "KeyedEconomyReport", + "KeyedEconomySimulation", + "KeyedHouseholdReport", + "KeyedWindowYear", "MissingPolicyParametersError", - "NewBudgetWindowReport", - "NewEconomyReport", - "NewEconomySimulation", "NewHouseholdJob", - "NewHouseholdReport", "NewHouseholdReportRerun", "NewReportRerun", "NewSimulationRerun", "NewWindowRerun", "OverlappingReformError", "PolicyReform", + "ProposedSide", "RecordKind", "ReportDefinition", "ReportRunState", @@ -194,13 +237,10 @@ "ReportRunTrigger", "ReportSide", "ReportSideError", - "ReportSimulation", "RerunRecordDeletedError", "RerunSide", - "ReusableRun", - "RunInProgressError", - "RunReuse", "RunVersions", + "SharedRowNotSettledError", "SideDefinition", "SideRefusal", "SimulationChoice", @@ -222,20 +262,26 @@ "WindowYearRuns", "bounded_transaction", "budget_window_runs", + "canonical_json", "combine_reforms", "create_simulation_engine", + "definition_key", "fail_unstarted_household_job", "fail_unstarted_report_run", "fail_unstarted_simulation_run", - "find_reusable_run", - "find_reusable_run_of", + "find_joinable_report_run", + "find_or_create_budget_window", + "find_or_create_economy_report", + "find_or_create_economy_simulation", + "find_or_create_household_report", + "find_or_insert_report", + "find_or_insert_report_run", + "find_or_insert_simulation", + "find_or_insert_simulation_run", + "find_or_insert_simulation_runs", "household_jobs", "input_metadata", - "insert_budget_window_report", - "insert_economy_report", - "insert_economy_simulation", "insert_household_job", - "insert_household_report", "insert_household_report_rerun", "insert_report_rerun", "insert_simulation_rerun", diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/budget_window_records.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/budget_window_records.py index 9f40b6c40..9bcfd1cd5 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/budget_window_records.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/budget_window_records.py @@ -1,50 +1,33 @@ -"""The rows of a budget-window report: one report run per year of its window. +"""What every budget-window record shares: its years and each year's runs. A budget-window report compares the same baseline and reform in each year of a window of 1 to 75 consecutive years. It is stored as an economy report whose ``budget_window_size`` is the window's length, with one -``budget_window_runs`` row for its calculation and, for each year, a report +``budget_window_runs`` row for each calculation and, for each year, a report run naming that row and the year. Each year has its own baseline and reform -simulations, of that year, unless it reuses a run that already succeeded, -so a year's run can be reused by a single-year report, and the reverse. The -report names its first year's simulations. - -The simulation service creates every row pending with no Modal call, then -starts the first years; each year's coordinator starts the next ones (see -``policyengine_stage12_persistence.BudgetWindowStore``). +simulations, of that year. The report names its first year's simulations. + +The simulation service finds or creates a window by key +(``keyed_window_records``) and re-runs a stored one +(``economy_rerun_records``). ``check_window_years`` refuses years that +aren't such a window's. ``WindowYearRuns`` is a year's report run and each +side's simulation run, as a found window's years and a re-run's years both +hold them. """ from __future__ import annotations -from dataclasses import dataclass, replace -from typing import TYPE_CHECKING, Any, Protocol - -from sqlalchemy import insert +from typing import TYPE_CHECKING, Protocol -from policyengine_simulation_persistence.economy_run_records import ( - ECONOMY_REPORT_TYPE, - EconomyPopulation, - ReportSimulation, - RunVersions, - insert_simulation_with_run, - references_checked, -) from policyengine_simulation_persistence.tables import ( LATEST_YEAR, MAX_BUDGET_WINDOW_YEARS, - ReportRunStatus, - ReportRunTrigger, - budget_window_runs, - report_runs, - reports, ) if TYPE_CHECKING: from collections.abc import Sequence from uuid import UUID - from sqlalchemy import Connection - class WindowSide(Protocol): """A window year's side: its simulation and the run the year names.""" @@ -59,17 +42,12 @@ def simulation_run_id(self) -> UUID: """The run of it the year names.""" ... - @property - def reused(self) -> bool: - """Whether the run already succeeded, rather than being created.""" - ... - class WindowYearRuns(Protocol): """A year of a window run: its year, its report run and each side. - A new window's ``BudgetWindowYear`` and a re-run's ``WindowRerunYear`` - are both one. + A found or created window's ``FoundWindowYear`` and a re-run's + ``WindowRerunYear`` are both one. """ @property @@ -93,51 +71,6 @@ def reform(self) -> WindowSide: ... -@dataclass(frozen=True) -class BudgetWindowYear: - """One year of a window: its report run and its two sides' runs.""" - - year: int - report_run_id: UUID - baseline: ReportSimulation - reform: ReportSimulation - - -@dataclass(frozen=True) -class NewBudgetWindowReport: - """A budget-window report to create, with its first calculation's runs. - - ``population`` is the first year's; each year's simulations use the same - catalog version, region and dataset in their own year. ``inputs`` holds - the report's options as the Public API reads them. ``years`` runs from - the first year, one year at a time, earliest first. - """ - - id: UUID - window_run_id: UUID - country: str - label: str - description: str | None - tax_benefit_model_id: UUID - population: EconomyPopulation - versions: RunVersions - inputs: dict[str, Any] - years: tuple[BudgetWindowYear, ...] - - def __post_init__(self) -> None: - """Refuse years that aren't 1 to 75 consecutive ones from the first.""" - check_window_years(self.population.year, [year.year for year in self.years]) - - @property - def first_year(self) -> BudgetWindowYear: - """The window's first year, whose simulations the report names.""" - return self.years[0] - - def population_in(self, year: int) -> EconomyPopulation: - """Return what the window's simulations of ``year`` calculate on.""" - return replace(self.population, year=year) - - def check_window_years(first_year: int, years: Sequence[int]) -> None: """Raise ValueError unless ``years`` are 1 to 75 in a row from ``first_year``. @@ -156,100 +89,3 @@ def check_window_years(first_year: int, years: Sequence[int]) -> None: f"ending by {LATEST_YEAR}" ) raise ValueError(msg) - - -def insert_budget_window_report( - connection: Connection, report: NewBudgetWindowReport -) -> None: - """Create the report, its budget-window run, and each year's runs, all pending. - - Each year's sides that reuse no run get a new simulation and run of that - year. Raise EconomyRecordReferenceError when the database refuses a row - it names. The refusal ends the caller's transaction, or its savepoint. - """ - with references_checked(): - for window_year in report.years: - population = report.population_in(window_year.year) - for side in (window_year.baseline, window_year.reform): - if not side.reused: - insert_simulation_with_run( - connection, - simulation_id=side.simulation_id, - run_id=side.simulation_run_id, - choice=side.choice, - population=population, - versions=report.versions, - ) - first_year = report.first_year - population = report.population - connection.execute( - insert(reports).values( - id=report.id, - label=report.label, - description=report.description, - country=report.country, - type=ECONOMY_REPORT_TYPE, - user_id=None, - tax_benefit_model_id=report.tax_benefit_model_id, - policy_id=first_year.reform.choice.policy_id, - baseline_simulation_id=first_year.baseline.simulation_id, - reform_simulation_id=first_year.reform.simulation_id, - household_id=None, - dataset_id=population.dataset_id, - region_id=population.region_id, - year=population.year, - budget_window_size=len(report.years), - inputs=report.inputs, - ) - ) - connection.execute( - insert(budget_window_runs).values( - id=report.window_run_id, - report_id=report.id, - tax_benefit_model_version_id=population.tax_benefit_model_version_id, - trigger=ReportRunTrigger.INITIAL, - recalculate=False, - status=ReportRunStatus.PENDING, - ) - ) - connection.execute( - insert(report_runs), - [ - year_run_row( - window_year, - report_id=report.id, - window_run_id=report.window_run_id, - versions=report.versions, - trigger=ReportRunTrigger.INITIAL, - ) - for window_year in report.years - ], - ) - - -def year_run_row( - window_year: WindowYearRuns, - *, - report_id: UUID, - window_run_id: UUID, - versions: RunVersions, - trigger: ReportRunTrigger, -) -> dict[str, Any]: - """Return a year's report run in a window run, pending with no call, as inserted. - - ``window_year`` is a new window's year or a re-run's; ``trigger`` says - which. - """ - return { - "id": window_year.report_run_id, - "report_id": report_id, - "baseline_simulation_run_id": window_year.baseline.simulation_run_id, - "reform_simulation_run_id": window_year.reform.simulation_run_id, - "budget_window_run_id": window_run_id, - "year": window_year.year, - "country_package_version": versions.country_package_version, - "policyengine_version": versions.policyengine_version, - "status": ReportRunStatus.PENDING, - "trigger": trigger, - "modal_call_id": None, - } diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/definition_keys.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/definition_keys.py new file mode 100644 index 000000000..5583fe336 --- /dev/null +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/definition_keys.py @@ -0,0 +1,291 @@ +"""Definition keys: what identifies a simulation or a report, so it is found again. + +Identical requests end on the same simulation and report rows because the +service finds each by a key of its definition (C1 · 24's answer 1a), stored +beside the row's random ID in ``definition_key``. A key is the SHA-256, in +lowercase hexadecimal, of an object's canonical JSON: keys sorted, no +spaces, UTF-8, UUIDs as lowercase strings, missing values null. The object +names ``key_version``, stored in its own column too, so a later change of +format never matches an older key, and ``record``, what it keys. + +Only the service computes keys; the Public API compares the stored columns. +A definition names catalog rows by dataset name and region code, never by +ID, because each catalog version has its own rows: one report spans +releases, and each release's calculation is a new run of it. A simulation's +key holds everything that changes its numbers, the SPM selection included; +a report's holds its two sides and window size and no options (C1 · 24's +answer 4). A report also stores a ``dataset_independent_key``: its key +object without the dataset (revised answer 1a), which a national report +and its local-area report share. A household simulation names its stored +household in place of a dataset and region, and a household report its +household (answer 8). +""" + +from __future__ import annotations + +import hashlib +import json +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any, Final, Literal +from uuid import UUID + +if TYPE_CHECKING: + from collections.abc import Mapping + + from policyengine_simulation_persistence.economy_run_records import ( + SimulationChoice, + ) + +# The format of every key this module builds. +KEY_VERSION: Final = 1 +# A report's or simulation's type, as the key and the Public API name it. +_ECONOMY: Final = "economy" +_HOUSEHOLD: Final = "household" + + +def canonical_json(definition: Mapping[str, object]) -> str: + """Return the definition's canonical JSON text. + + Raise ValueError for a number JSON can't write exactly (NaN or an + infinity) and TypeError for a value it has no form for. + """ + return json.dumps( + definition, + sort_keys=True, + separators=(",", ":"), + ensure_ascii=False, + allow_nan=False, + default=_json_value, + ) + + +def _json_value(value: object) -> str: + """Write a UUID as its lowercase string; refuse anything else JSON lacks.""" + if isinstance(value, UUID): + return str(value) + msg = f"a definition can't hold a {type(value).__name__}" + raise TypeError(msg) + + +def definition_key(definition: Mapping[str, object]) -> str: + """Return the SHA-256 of the definition's canonical JSON, in lowercase hex.""" + return hashlib.sha256(canonical_json(definition).encode("utf-8")).hexdigest() + + +def _side(choice: SimulationChoice) -> dict[str, object]: + return {"policy_id": choice.policy_id, "dynamic_id": choice.dynamic_id} + + +def _selection(spm: Mapping[str, Any] | None) -> dict[str, Any] | None: + """Return the SPM selection as given, or None when the request gave none.""" + return None if spm is None else dict(spm) + + +@dataclass(frozen=True) +class EconomySimulationDefinition: + """What identifies an economy simulation: everything that changes its numbers. + + Its stored policy and dynamic (dynamics by ID, answer 1b), dataset name, + region code and year (answer 1a), and the SPM selection as the request + gave it, or None when it gave none (answer 4c). The service never + filters a simulation, so its filter is null. Never a version. + """ + + country: str + choice: SimulationChoice + dataset_name: str + region_code: str + year: int + spm: Mapping[str, Any] | None + + def key_object(self) -> dict[str, object]: + """Return the object whose canonical JSON the simulation's key hashes.""" + return { + "record": "simulation", + "key_version": KEY_VERSION, + "simulation_type": _ECONOMY, + "country": self.country, + **_side(self.choice), + "dataset": self.dataset_name, + "region": self.region_code, + "year": self.year, + "filter": None, + "spm": _selection(self.spm), + } + + @property + def definition_key(self) -> str: + """The simulation's ``definition_key``.""" + return definition_key(self.key_object()) + + +@dataclass(frozen=True) +class EconomyReportDefinition: + """What identifies an economy report or a budget window (answers 1a and 4). + + A report is its two simulations and its window's size (None for a single + year), with no options of its own: each side's stored policy and dynamic, + and the dataset name, region code, year and SPM selection both sides + share, named once. Never a version: versions belong to runs. + """ + + country: str + baseline: SimulationChoice + reform: SimulationChoice + dataset_name: str + region_code: str + year: int + budget_window_size: int | None + spm: Mapping[str, Any] | None + + def key_object(self) -> dict[str, object]: + """Return the object whose canonical JSON the report's key hashes.""" + return { + "record": "report", + "key_version": KEY_VERSION, + "report_type": _ECONOMY, + "country": self.country, + "baseline": _side(self.baseline), + "reform": _side(self.reform), + "dataset": self.dataset_name, + "region": self.region_code, + "year": self.year, + "budget_window_size": self.budget_window_size, + "spm": _selection(self.spm), + } + + @property + def definition_key(self) -> str: + """The report's ``definition_key``.""" + return definition_key(self.key_object()) + + def dataset_independent_key_object(self) -> dict[str, object]: + """Return the key object without the dataset, under its own record name.""" + key_object = self.key_object() + del key_object["dataset"] + key_object["record"] = "report_dataset_independent" + return key_object + + @property + def dataset_independent_key(self) -> str: + """The report's ``dataset_independent_key``.""" + return definition_key(self.dataset_independent_key_object()) + + def simulation( + self, side: Literal["baseline", "reform"], *, year: int | None = None + ) -> EconomySimulationDefinition: + """Return the simulation ``side`` names, in ``year`` (the report's own). + + A budget window's years each name their own year's simulations. + """ + return EconomySimulationDefinition( + country=self.country, + choice=self.baseline if side == "baseline" else self.reform, + dataset_name=self.dataset_name, + region_code=self.region_code, + year=self.year if year is None else year, + spm=self.spm, + ) + + +@dataclass(frozen=True) +class HouseholdSimulationDefinition: + """What identifies a household simulation (answers 1a and 8). + + Its stored policy and dynamic, the stored household's ID in place of a + dataset and region, and the year. The household's saved SPM selection + is part of the stored household, which the Public API's runtime never + changes, so its ID names it. The service never filters a simulation, so + its filter is null. Never a version. + """ + + country: str + choice: SimulationChoice + household_id: UUID + year: int + + def key_object(self) -> dict[str, object]: + """Return the object whose canonical JSON the simulation's key hashes.""" + return { + "record": "simulation", + "key_version": KEY_VERSION, + "simulation_type": _HOUSEHOLD, + "country": self.country, + **_side(self.choice), + "household_id": self.household_id, + "year": self.year, + "filter": None, + } + + @property + def definition_key(self) -> str: + """The simulation's ``definition_key``.""" + return definition_key(self.key_object()) + + +@dataclass(frozen=True) +class HouseholdReportDefinition: + """What identifies a household report: its sides, household and year. + + Each side's stored policy and dynamic, the reform None for a report of + the baseline alone, the stored household both sides calculate, and the + year, with no options. Never a version. + """ + + country: str + baseline: SimulationChoice + reform: SimulationChoice | None + household_id: UUID + year: int + + @property + def sides(self) -> tuple[Literal["baseline", "reform"], ...]: + """Return each side the report calculates, the baseline's first.""" + return ("baseline",) if self.reform is None else ("baseline", "reform") + + def key_object(self) -> dict[str, object]: + """Return the object whose canonical JSON the report's key hashes.""" + return { + "record": "report", + "key_version": KEY_VERSION, + "report_type": _HOUSEHOLD, + "country": self.country, + "baseline": _side(self.baseline), + "reform": None if self.reform is None else _side(self.reform), + "household_id": self.household_id, + "year": self.year, + "budget_window_size": None, + } + + @property + def definition_key(self) -> str: + """The report's ``definition_key``.""" + return definition_key(self.key_object()) + + def dataset_independent_key_object(self) -> dict[str, object]: + """Return the key object under its own record name. + + A household report has no dataset to leave out; the Public API + requires the key with the other two. + """ + return {**self.key_object(), "record": "report_dataset_independent"} + + @property + def dataset_independent_key(self) -> str: + """The report's ``dataset_independent_key``.""" + return definition_key(self.dataset_independent_key_object()) + + def simulation( + self, side: Literal["baseline", "reform"] + ) -> HouseholdSimulationDefinition: + """Return the simulation ``side`` names; raise ValueError for no reform.""" + choice = self.baseline if side == "baseline" else self.reform + if choice is None: + msg = "a household report of the baseline alone has no reform" + raise ValueError(msg) + return HouseholdSimulationDefinition( + country=self.country, + choice=choice, + household_id=self.household_id, + year=self.year, + ) diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_inputs.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_inputs.py new file mode 100644 index 000000000..4d0ad395e --- /dev/null +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_inputs.py @@ -0,0 +1,290 @@ +"""What an economy request is read from: its catalog rows and its sides' values. + +A request names a region code, a dataset name (or the region's default) and +a year, for the .py version of the default worker, and each side's stored +policy and dynamic. ``read_catalog_rows`` reads the catalog version's model, +region and dataset; ``read_report_sides`` and ``read_window_sides`` read +each side's values on that catalog version. ``EconomyRunStore`` runs these +in its transactions. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import TYPE_CHECKING, Literal, get_args + +from policyengine_simulation_persistence.economy_run_records import ( + CatalogDataset, + CatalogRegion, + EconomyPopulation, + SimulationChoice, + read_dataset, + read_dataset_by_id, + read_model_id, + read_region, +) +from policyengine_simulation_persistence.household_job_records import ( + read_catalog_version_id, +) +from policyengine_simulation_persistence.household_job_store import ( + UnknownCatalogVersionError, +) +from policyengine_simulation_persistence.policy_reform import ( + MissingPolicyParametersError, + OverlappingReformError, + UnknownDynamicError, + UnknownPolicyError, + combine_reforms, + read_dynamic_reform, + read_policy_reform, +) + +if TYPE_CHECKING: + from uuid import UUID + + from sqlalchemy import Connection + + from policyengine_simulation_persistence.policy_reform import PolicyReform + +# Which of a report's simulations a value belongs to. +type ReportSide = Literal["baseline", "reform"] +# The errors a simulation's own policy or dynamic can raise. +type SideRefusal = ( + UnknownPolicyError + | UnknownDynamicError + | MissingPolicyParametersError + | OverlappingReformError +) +# Caught by the type itself, so the two never name different errors. +SIDE_ERRORS: tuple[type[SideRefusal], ...] = get_args(SideRefusal.__value__) + + +class UnknownRegionError(LookupError): + """The catalog version has no region with the requested code.""" + + +class UnknownDatasetError(LookupError): + """The catalog version has no dataset with the requested name.""" + + +class ReportSideError(Exception): + """A report side's policy or dynamic is refused. + + ``side`` names the side, and ``error`` is the policy reader's refusal: + UnknownPolicyError, UnknownDynamicError, MissingPolicyParametersError or + OverlappingReformError. + """ + + def __init__(self, side: ReportSide, error: SideRefusal) -> None: + """Keep the side and the refusal.""" + super().__init__(f"the report's {side}: {error}") + self.side: ReportSide = side + self.error = error + + +@dataclass(frozen=True) +class EconomyRequest: + """What an economy simulation or report request names, apart from policies. + + ``policyengine_version`` is the .py version the calculation runs on, + which chooses the country's catalog version. ``dataset_name`` None means + the region's default dataset. + """ + + country: str + policyengine_version: str + region_code: str + dataset_name: str | None + year: int + + +@dataclass(frozen=True) +class EconomyCatalogRows: + """The catalog rows a request is calculated on.""" + + catalog_version_id: UUID + model_id: UUID + region: CatalogRegion + dataset: CatalogDataset + + def population(self, year: int) -> EconomyPopulation: + """Return what every simulation of the request calculates on.""" + return EconomyPopulation( + tax_benefit_model_version_id=self.catalog_version_id, + region_id=self.region.id, + dataset_id=self.dataset.id, + year=year, + ) + + +@dataclass(frozen=True) +class SimulationInputs: + """One simulation's policy and dynamic, and the values they set together.""" + + choice: SimulationChoice + reform: PolicyReform + + +@dataclass(frozen=True) +class EconomySimulationInputs: + """What a standalone economy simulation is read from.""" + + catalog: EconomyCatalogRows + simulation: SimulationInputs + + +@dataclass(frozen=True) +class EconomyReportInputs: + """What an economy report is read from: the catalog rows and both sides.""" + + catalog: EconomyCatalogRows + baseline: SimulationInputs + reform: SimulationInputs + + +@dataclass(frozen=True) +class BudgetWindowInputs: + """What a budget-window report is read from: the catalog rows and both sides. + + ``baseline`` and ``reform`` hold each side's values, the same in every + year. + """ + + catalog: EconomyCatalogRows + baseline: SimulationInputs + reform: SimulationInputs + + +def read_catalog_rows( + connection: Connection, request: EconomyRequest +) -> EconomyCatalogRows: + """Read the catalog version, model, region and dataset a request names. + + Raise UnknownCatalogVersionError, UnknownRegionError or + UnknownDatasetError. + """ + country = request.country + catalog_version_id = read_catalog_version_id( + connection, + country=country, + policyengine_version=request.policyengine_version, + ) + model_id = read_model_id(connection, country=country) + if catalog_version_id is None or model_id is None: + msg = f"{country} has no catalog version for .py {request.policyengine_version}" + raise UnknownCatalogVersionError(msg) + region = read_region( + connection, + catalog_version_id=catalog_version_id, + region_code=request.region_code, + ) + if region is None: + msg = ( + f"{country}'s catalog version for .py {request.policyengine_version} " + f"has no region {request.region_code}" + ) + raise UnknownRegionError(msg) + dataset = ( + read_dataset_by_id( + connection, + catalog_version_id=catalog_version_id, + dataset_id=region.default_dataset_id, + ) + if request.dataset_name is None + else read_dataset( + connection, + catalog_version_id=catalog_version_id, + name=request.dataset_name, + ) + ) + if dataset is None: + msg = ( + f"{country}'s catalog version for .py {request.policyengine_version} " + f"has no dataset {request.dataset_name}" + ) + raise UnknownDatasetError(msg) + return EconomyCatalogRows( + catalog_version_id=catalog_version_id, + model_id=model_id, + region=region, + dataset=dataset, + ) + + +def read_simulation_values( + connection: Connection, + country: str, + catalog_version_id: UUID, + choice: SimulationChoice, +) -> SimulationInputs: + """Read one simulation's policy and dynamic values, combined.""" + policy_reform = ( + {} + if choice.policy_id is None + else read_policy_reform( + connection, + country=country, + policy_id=choice.policy_id, + catalog_version_id=catalog_version_id, + ) + ) + dynamic_reform = ( + {} + if choice.dynamic_id is None + else read_dynamic_reform( + connection, + dynamic_id=choice.dynamic_id, + catalog_version_id=catalog_version_id, + ) + ) + return SimulationInputs( + choice=choice, reform=combine_reforms(policy_reform, dynamic_reform) + ) + + +def read_side_values( + connection: Connection, + request: EconomyRequest, + catalog: EconomyCatalogRows, + side: ReportSide, + choice: SimulationChoice, +) -> SimulationInputs: + """Read one report side's values; raise ReportSideError naming a refused side.""" + try: + return read_simulation_values( + connection, request.country, catalog.catalog_version_id, choice + ) + except SIDE_ERRORS as error: + raise ReportSideError(side, error) from error + + +def read_report_sides( + connection: Connection, + request: EconomyRequest, + catalog: EconomyCatalogRows, + *, + baseline: SimulationChoice, + reform: SimulationChoice, +) -> EconomyReportInputs: + """Read both sides' values, the baseline's first.""" + return EconomyReportInputs( + catalog=catalog, + baseline=read_side_values(connection, request, catalog, "baseline", baseline), + reform=read_side_values(connection, request, catalog, "reform", reform), + ) + + +def read_window_sides( + connection: Connection, + request: EconomyRequest, + catalog: EconomyCatalogRows, + *, + baseline: SimulationChoice, + reform: SimulationChoice, +) -> BudgetWindowInputs: + """Read both sides' values, the baseline's first, for every year of a window.""" + return BudgetWindowInputs( + catalog=catalog, + baseline=read_side_values(connection, request, catalog, "baseline", baseline), + reform=read_side_values(connection, request, catalog, "reform", reform), + ) diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_rerun_records.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_rerun_records.py index b2be0d6a5..b1bdee38f 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_rerun_records.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_rerun_records.py @@ -7,23 +7,36 @@ ``read_simulation_definition``): its country, year, region code, dataset name and each simulation's policy and dynamic, so the current catalog version's rows with the same code and name can be found; -- creates, in one transaction, the new run and, for each report side not - reusing a run of its own simulation, a new ``simulation_runs`` row of that - simulation, all ``pending`` with no Modal call ID. A report's new run has - trigger ``manual``. A budget window's new run is a ``budget_window_runs`` +- creates, in one transaction, the new run and each report side's run of + its own simulation, all ``pending`` with no Modal call ID; an unforced + economy or household report re-run's side joins its simulation's run on + the current versions instead, when there is one. No new run names a + trigger (answer 6): each user's report-run record holds it. A budget + window's new run is a ``budget_window_runs`` row with a report run per year, each year on the simulations its report - run in the report's newest window run names. A household report's new run - gives each side a new run of its own household simulation: household runs - are never reused. + run in the report's newest window run names. A household report's new + run names runs of its own household simulations. The record itself is never changed: the service may not update ``reports`` or ``simulations``, so a report keeps naming the simulations it was created with, and each new run records the catalog version, dataset and region it -calculates on. Nothing is created while the record has a run that is -``pending`` or ``running`` (for a report, a budget-window run or a report -run of it); a transaction-level advisory lock on the -record's ID makes concurrent re-runs of one record wait for each other, as -a row lock on ``reports`` would need ``UPDATE`` on it. +calculates on. A simulation's re-run, and an unforced economy or household +report's, joins the record's run that hasn't failed and wasn't forced on +the current versions, pending, running or succeeded, rather than create +one (C1 · 24's answers 2, 3 and 8; ``shared_rows``): the simulation's run +on those versions, catalog version and year, or the report's run on those +versions. An unforced report re-run (economy, budget window or household) +takes a transaction-level advisory lock on the report's ID first, which +makes concurrent re-runs of one report wait for each other, as a row lock +on ``reports`` would need ``UPDATE`` on it; an unforced budget window's +re-run joins the window run on its versions the same way. A simulation's +re-run takes no lock. + +A forced re-run (C1 · 24's answer 3) is an extra run instead: its report +run, or each year's report run of a budget window, and the simulation runs +it calculates are marked ``forced``, which the Public API's one-unfailed-run +indexes leave out, so it is created beside any run on the same versions, +even one under way, and nothing ever joins it. The service then starts and records the new run's call as it does a new record's (``economy_run_records``). @@ -33,149 +46,94 @@ from contextlib import contextmanager from dataclasses import dataclass, replace -from typing import TYPE_CHECKING, Any, Final, Literal +from typing import TYPE_CHECKING, Any from sqlalchemy import func, insert, literal, select from policyengine_simulation_persistence.budget_window_records import ( check_window_years, - year_run_row, ) from policyengine_simulation_persistence.economy_run_records import ( - ECONOMY_REPORT_TYPE, EconomyRecordReferenceError, - SimulationChoice, insert_simulation_run, references_checked, + simulation_run_row, ) from policyengine_simulation_persistence.household_report_records import ( - HOUSEHOLD_REPORT_TYPE, + household_simulation_run_row, insert_household_simulation_run, ) -from policyengine_simulation_persistence.input_tables import ( - MODEL_NAME_PREFIX, - datasets, - regions, - tax_benefit_model_versions, - tax_benefit_models, +from policyengine_simulation_persistence.keyed_economy_records import ( + find_or_insert_report_run_on_sides, +) +from policyengine_simulation_persistence.keyed_window_records import ( + FoundBudgetWindow, + WindowYearToInsert, + insert_window_years, + stored_window_years, + window_run_row, +) +from policyengine_simulation_persistence.rerun_definitions import ( + RecordKind, + ReportDefinition, + SideDefinition, + SimulationDefinition, + WindowYearDefinition, + read_report_definition, + read_simulation_definition, +) +from policyengine_simulation_persistence.shared_rows import ( + FoundReportRun, + FoundWindowRun, + find_joinable_report_run, + find_joinable_window_run, + find_or_insert_simulation_run, + find_or_insert_window_run, ) from policyengine_simulation_persistence.tables import ( ReportRunStatus, - ReportRunTrigger, - SimulationStatus, - SimulationType, budget_window_runs, report_runs, - reports, simulation_runs, - simulations, ) if TYPE_CHECKING: - from collections.abc import Iterator + from collections.abc import Iterator, Mapping from uuid import UUID - from sqlalchemy import Column, ColumnElement, Connection, RowMapping, Table + from sqlalchemy import Column, Connection from policyengine_simulation_persistence.economy_run_records import ( EconomyPopulation, RunVersions, ) - -# What a stored report or simulation calculates, as a re-run tells them apart: -# a single-year economy report or simulation, a budget window, a household -# report or simulation, or anything else, such as a simulation of a filtered -# population. -type RecordKind = Literal["economy", "budget_window", "household", "unsupported"] -# Every run table's statuses (simulation, report and budget-window runs) use -# these values for a run under way. -_UNDER_WAY: Final = (SimulationStatus.PENDING.value, SimulationStatus.RUNNING.value) - - -@dataclass(frozen=True) -class SideDefinition: - """A report side's stored simulation, and its policy and dynamic.""" - - simulation_id: UUID - choice: SimulationChoice - - -@dataclass(frozen=True) -class WindowYearDefinition: - """One year of a budget window's newest calculation, and its sides' simulations. - - They are the simulations of the runs that year's report run names: a - year that reused a run names that run's simulation, which may be another - report's. - """ - - year: int - baseline_simulation_id: UUID - reform_simulation_id: UUID - - -@dataclass(frozen=True) -class ReportDefinition: - """What a stored report calculates, as a re-run reads it. - - ``region_code`` and ``dataset_name`` are the code and name of the - report's region and dataset, or None when the report names none (or a - row it named was deleted). ``baseline`` and ``reform`` are None when the - report names no such simulation; a budget window's are its first - year's. A budget window's ``window_years`` are the years of its newest - budget-window run whose report run names both sides, earliest first, - empty when it has none. ``household_id`` is a household report's stored - household, None for any other report. - """ - - id: UUID - country: str - kind: RecordKind - year: int | None - region_code: str | None - dataset_name: str | None - inputs: dict[str, Any] - baseline: SideDefinition | None - reform: SideDefinition | None - budget_window_size: int | None = None - window_years: tuple[WindowYearDefinition, ...] = () - household_id: UUID | None = None - - -@dataclass(frozen=True) -class SimulationDefinition: - """What a stored simulation calculates, as a re-run reads it. - - ``country`` comes from the simulation's catalog version's model; it is - None for a model the service does not name ``policyengine-``. - """ - - id: UUID - country: str | None - kind: RecordKind - year: int | None - region_code: str | None - dataset_name: str | None - choice: SimulationChoice + from policyengine_simulation_persistence.keyed_economy_records import Side + from policyengine_simulation_persistence.shared_rows import FoundSimulationRun @dataclass(frozen=True) class RerunSide: - """The simulation run one side of a report's re-run names. + """The simulation run one side of a report's or a window year's re-run names. - The simulation is always the report's own. With ``reused``, the run is - one of its runs that succeeded on the current versions, and nothing is - created for the side; otherwise the run is created, pending. + The simulation is always the report's own. ``simulation_run_id`` is the + run a forced re-run creates, pending, or the ID an unforced re-run's + side proposes, used only if it inserts the run. """ simulation_id: UUID simulation_run_id: UUID - reused: bool @dataclass(frozen=True) class NewReportRerun: - """A stored report's new run, on the current versions and catalog rows.""" + """A stored report's new run, on the current versions and catalog rows. + + Unforced, each side joins its simulation's run on the re-run's versions + that hasn't failed and wasn't forced, or inserts one; a side's + ``simulation_run_id`` is the ID it proposes, used only if it inserts the + run. ``forced`` makes it a forced re-run's extra run, which inserts a + new run of each side, marked forced. + """ report_id: UUID run_id: UUID @@ -183,15 +141,16 @@ class NewReportRerun: versions: RunVersions baseline: RerunSide reform: RerunSide + forced: bool = False @property def new_simulation_run_ids(self) -> tuple[UUID, ...]: - """Return the IDs of the simulation runs created for the re-run.""" - return tuple( - side.simulation_run_id - for side in (self.baseline, self.reform) - if not side.reused - ) + """Return the IDs of the simulation runs a forced re-run creates. + + An unforced re-run's sides propose these IDs; each is used only for + a run the re-run inserts. + """ + return (self.baseline.simulation_run_id, self.reform.simulation_run_id) @dataclass(frozen=True) @@ -210,7 +169,11 @@ class NewWindowRerun: ``population`` is the first year's, on the current catalog version; each year calculates on the same catalog version, region and dataset in - its own year. ``recalculate`` records whether the re-run was forced. + its own year. ``recalculate`` records whether the re-run was forced: an + extra window run on new runs of every year. Unforced, a keyed window's + re-run joins its window run on the versions, or each year's sides join + their simulations' runs; a side's ``simulation_run_id`` is the ID it + proposes. """ report_id: UUID @@ -221,7 +184,7 @@ class NewWindowRerun: years: tuple[WindowRerunYear, ...] def __post_init__(self) -> None: - """Refuse years that aren't 1 to 75 consecutive ones from the first.""" + """Refuse years that aren't 1 to 75 in a row from the first.""" check_window_years(self.population.year, [year.year for year in self.years]) def population_in(self, year: int) -> EconomyPopulation: @@ -241,8 +204,11 @@ class HouseholdRerunSide: class NewHouseholdReportRerun: """A stored household report's new run, on the current catalog version. - Each side gets a new run of its own household simulation, in the - report's ``year``; ``reform`` is None for a report of the baseline alone. + Unforced (a keyed report's re-run), each side joins its own household + simulation's run in the report's ``year`` on the re-run's versions, or + inserts one with the ID it proposes. ``forced`` makes it an extra run, + on a new run of each side, all marked forced. ``reform`` is None for a + report of the baseline alone. """ report_id: UUID @@ -252,6 +218,15 @@ class NewHouseholdReportRerun: versions: RunVersions baseline: HouseholdRerunSide reform: HouseholdRerunSide | None + forced: bool = False + + @property + def named_sides(self) -> dict[Side, HouseholdRerunSide]: + """Return each side the re-run calculates, by its name.""" + sides: dict[Side, HouseholdRerunSide] = {"baseline": self.baseline} + if self.reform is not None: + sides["reform"] = self.reform + return sides @property def sides(self) -> tuple[HouseholdRerunSide, ...]: @@ -260,7 +235,11 @@ def sides(self) -> tuple[HouseholdRerunSide, ...]: @property def simulation_run_ids(self) -> tuple[UUID, ...]: - """Return the IDs of the simulation runs created for the re-run.""" + """Return the IDs the re-run's sides propose for their simulation runs. + + A forced re-run creates them all; an unforced one only those it + inserts. + """ return tuple(side.simulation_run_id for side in self.sides) @@ -282,207 +261,16 @@ class RerunRecordDeletedError(LookupError): """ -class RunInProgressError(Exception): - """The record has a run that is pending or running, so no re-run is created. - - ``run_id`` names that run: the newest such one. - """ - - def __init__(self, run_id: UUID) -> None: - """Keep the run under way.""" - super().__init__(f"run {run_id} is pending or running") - self.run_id = run_id - - -def read_report_definition( - connection: Connection, report_id: UUID -) -> ReportDefinition | None: - """Return what the stored report calculates, or None when there is none.""" - region = regions.alias("report_region") - dataset = datasets.alias("report_dataset") - baseline = simulations.alias("baseline_simulation") - reform = simulations.alias("reform_simulation") - row = ( - connection.execute( - select( - reports.c.id, - reports.c.country, - reports.c.type, - reports.c.household_id, - reports.c.budget_window_size, - reports.c.year, - reports.c.inputs, - region.c.code.label("region_code"), - dataset.c.name.label("dataset_name"), - baseline.c.id.label("baseline_id"), - baseline.c.policy_id.label("baseline_policy_id"), - baseline.c.dynamic_id.label("baseline_dynamic_id"), - reform.c.id.label("reform_id"), - reform.c.policy_id.label("reform_policy_id"), - reform.c.dynamic_id.label("reform_dynamic_id"), - ) - .select_from(reports) - .outerjoin(region, region.c.id == reports.c.region_id) - .outerjoin(dataset, dataset.c.id == reports.c.dataset_id) - .outerjoin(baseline, baseline.c.id == reports.c.baseline_simulation_id) - .outerjoin(reform, reform.c.id == reports.c.reform_simulation_id) - .where(reports.c.id == report_id) - ) - .mappings() - .one_or_none() - ) - if row is None: - return None - kind = _report_kind(row["type"], row["household_id"], row["budget_window_size"]) - return ReportDefinition( - id=row["id"], - country=row["country"], - kind=kind, - year=row["year"], - region_code=row["region_code"], - dataset_name=row["dataset_name"], - inputs=row["inputs"], - baseline=_side(row, "baseline"), - reform=_side(row, "reform"), - budget_window_size=row["budget_window_size"], - window_years=( - _window_years(connection, report_id) if kind == "budget_window" else () - ), - household_id=row["household_id"], - ) - - -def _window_years( - connection: Connection, report_id: UUID -) -> tuple[WindowYearDefinition, ...]: - """Return the years of the report's newest budget-window run, earliest first. - - A year whose report run names no reform is left out. - """ - newest_window_run = ( - select(budget_window_runs.c.id) - .where(budget_window_runs.c.report_id == report_id) - .order_by( - budget_window_runs.c.created_at.desc(), budget_window_runs.c.id.desc() - ) - .limit(1) - .scalar_subquery() - ) - baseline_run = simulation_runs.alias("baseline_run") - reform_run = simulation_runs.alias("reform_run") - rows = connection.execute( - select( - report_runs.c.year, - baseline_run.c.simulation_id.label("baseline_simulation_id"), - reform_run.c.simulation_id.label("reform_simulation_id"), - ) - .join( - baseline_run, baseline_run.c.id == report_runs.c.baseline_simulation_run_id - ) - .join(reform_run, reform_run.c.id == report_runs.c.reform_simulation_run_id) - .where(report_runs.c.budget_window_run_id == newest_window_run) - .order_by(report_runs.c.year) - ) - return tuple( - WindowYearDefinition( - year=row.year, - baseline_simulation_id=row.baseline_simulation_id, - reform_simulation_id=row.reform_simulation_id, - ) - for row in rows - ) - - -def _report_kind( - report_type: str | None, household_id: UUID | None, budget_window_size: int | None -) -> RecordKind: - if household_id is not None or report_type == HOUSEHOLD_REPORT_TYPE: - return "household" - if report_type != ECONOMY_REPORT_TYPE: - return "unsupported" - return "economy" if budget_window_size is None else "budget_window" - - -def _side( - row: RowMapping, side: Literal["baseline", "reform"] -) -> SideDefinition | None: - simulation_id = row[f"{side}_id"] - if simulation_id is None: - return None - return SideDefinition( - simulation_id=simulation_id, - choice=SimulationChoice( - policy_id=row[f"{side}_policy_id"], dynamic_id=row[f"{side}_dynamic_id"] - ), - ) - - -def read_simulation_definition( - connection: Connection, simulation_id: UUID -) -> SimulationDefinition | None: - """Return what the stored simulation calculates, or None when there is none.""" - row = ( - connection.execute( - select( - simulations.c.id, - simulations.c.simulation_type, - simulations.c.filter_field, - simulations.c.year, - simulations.c.policy_id, - simulations.c.dynamic_id, - tax_benefit_models.c.name.label("model_name"), - regions.c.code.label("region_code"), - datasets.c.name.label("dataset_name"), - ) - .select_from(simulations) - .join( - tax_benefit_model_versions, - tax_benefit_model_versions.c.id - == simulations.c.tax_benefit_model_version_id, - ) - .join( - tax_benefit_models, - tax_benefit_models.c.id == tax_benefit_model_versions.c.model_id, - ) - .outerjoin(regions, regions.c.id == simulations.c.region_id) - .outerjoin(datasets, datasets.c.id == simulations.c.dataset_id) - .where(simulations.c.id == simulation_id) - ) - .mappings() - .one_or_none() - ) - if row is None: - return None - model_name: str = row["model_name"] - simulation_type = SimulationType(row["simulation_type"]) - kind: RecordKind = ( - "household" - if simulation_type is SimulationType.HOUSEHOLD - else "economy" - if row["filter_field"] is None - else "unsupported" - ) - return SimulationDefinition( - id=row["id"], - country=model_name.removeprefix(MODEL_NAME_PREFIX) - if model_name.startswith(MODEL_NAME_PREFIX) - else None, - kind=kind, - year=row["year"], - region_code=row["region_code"], - dataset_name=row["dataset_name"], - choice=SimulationChoice( - policy_id=row["policy_id"], dynamic_id=row["dynamic_id"] - ), - ) - - def lock_reruns_of(connection: Connection, record_id: UUID) -> None: """Wait for, then hold until the transaction ends, the record's re-run lock. It is a transaction-level advisory lock keyed on the record's ID, which - any role may take: a second re-run of the same report or simulation - waits here until the first one's transaction ends, then sees its run. + any role may take: a second re-run of the same report waits here until + the first one's transaction ends, then sees its run, which an economy + or household report's re-run, or a budget window's, joins. A + simulation's re-run takes none, as the Public API's index on runs + lets one joinable run exist, and neither does a forced re-run, which + nothing joins. """ connection.execute( select( @@ -493,186 +281,306 @@ def lock_reruns_of(connection: Connection, record_id: UUID) -> None: ) -def _run_under_way( - connection: Connection, table: Table, condition: ColumnElement[bool] -) -> UUID | None: - """Return the newest pending or running run meeting ``condition``, or None.""" - return connection.execute( - select(table.c.id) - .where(condition, table.c.status.in_(_UNDER_WAY)) - .order_by(table.c.created_at.desc(), table.c.id.desc()) - .limit(1) - ).scalar_one_or_none() - - -def insert_report_rerun(connection: Connection, rerun: NewReportRerun) -> None: - """Create the report's new run and its sides' new simulation runs, pending. - - Take the report's re-run lock first. Raise RunInProgressError, creating - nothing, when the report has a run pending or running. Raise - RerunRecordDeletedError when the database refuses the new run's key to - the report, which no longer exists, and EconomyRecordReferenceError when - it refuses another row the new runs name, such as a side's simulation; - either refusal ends the caller's transaction, or its savepoint. +def insert_report_rerun( + connection: Connection, rerun: NewReportRerun +) -> FoundReportRun: + """Join the report's run on the re-run's versions, or create it, pending. + + A single-year report's re-run (the service re-runs a budget window with + ``insert_window_rerun``). Unless the re-run is forced, take the + report's re-run lock and join the report's run on the re-run's versions + that hasn't failed and wasn't forced, when there is one. Otherwise each + side joins its simulation's run on those versions, or inserts one + (``find_or_insert_side_runs``), and the report run naming them is + inserted, unless another request inserted one after the lookup: that + run is joined, and this call's simulation runs are taken back. A forced + re-run inserts its runs, marked forced, and is never joined. Return the + run and whether this call created it, which only then needs its Modal + call. + + Raise RerunRecordDeletedError when the database refuses the new run's + key to the report, which no longer exists, and + EconomyRecordReferenceError when it refuses another row the new runs + name, such as a side's simulation; either refusal ends the caller's + transaction, or its savepoint. """ - lock_reruns_of(connection, rerun.report_id) - _refuse_while_report_runs(connection, rerun.report_id) + versions = rerun.versions + if not rerun.forced: + lock_reruns_of(connection, rerun.report_id) + joined = find_joinable_report_run( + connection, + report_id=rerun.report_id, + country_package_version=versions.country_package_version, + policyengine_version=versions.policyengine_version, + ) + if joined is not None: + return joined + row = _rerun_report_run_row( + run_id=rerun.run_id, report_id=rerun.report_id, versions=versions + ) + sides: dict[Side, RerunSide] = {"baseline": rerun.baseline, "reform": rerun.reform} with _record_checked(report_runs.c.report_id), references_checked(): - for side in (rerun.baseline, rerun.reform): - if not side.reused: + if rerun.forced: + for side in sides.values(): insert_simulation_run( connection, run_id=side.simulation_run_id, simulation_id=side.simulation_id, population=rerun.population, - versions=rerun.versions, + versions=versions, + forced=True, ) - connection.execute( - insert(report_runs).values( - id=rerun.run_id, - report_id=rerun.report_id, - baseline_simulation_run_id=rerun.baseline.simulation_run_id, - reform_simulation_run_id=rerun.reform.simulation_run_id, - budget_window_run_id=None, - year=None, - country_package_version=rerun.versions.country_package_version, - policyengine_version=rerun.versions.policyengine_version, - status=ReportRunStatus.PENDING, - trigger=ReportRunTrigger.MANUAL, - modal_call_id=None, - ) + return _insert_forced_report_run(connection, row, sides) + found, _ = find_or_insert_report_run_on_sides( + connection, + row, + { + name: simulation_run_row( + run_id=side.simulation_run_id, + simulation_id=side.simulation_id, + population=rerun.population, + versions=versions, + ) + for name, side in sides.items() + }, ) + return found -def insert_window_rerun(connection: Connection, rerun: NewWindowRerun) -> None: - """Create the budget window's new run, each year's report run and new runs. +def _rerun_report_run_row( + *, run_id: UUID, report_id: UUID, versions: RunVersions +) -> dict[str, Any]: + """Return a re-run's report run as inserted, without its sides' runs. - The budget-window run has trigger ``manual`` and records ``recalculate``; - each year's report run names it and its year, and each side reusing no - run gets a new run of its year's simulation. All are pending with no - Modal call; the service then starts the first years. Raise as - ``insert_report_rerun`` does. + It names no trigger: each user's report-run record holds it (answer 6). """ - lock_reruns_of(connection, rerun.report_id) - _refuse_while_report_runs(connection, rerun.report_id) - population = rerun.population + return { + "id": run_id, + "report_id": report_id, + "budget_window_run_id": None, + "year": None, + "country_package_version": versions.country_package_version, + "policyengine_version": versions.policyengine_version, + "status": ReportRunStatus.PENDING, + "modal_call_id": None, + } + + +def _insert_forced_report_run( + connection: Connection, + row: dict[str, Any], + side_runs: Mapping[Side, RerunSide | HouseholdRerunSide], +) -> FoundReportRun: + """Insert a forced re-run's report run, naming its sides' new runs.""" + reform = side_runs.get("reform") + baseline_run_id = side_runs["baseline"].simulation_run_id + reform_run_id = None if reform is None else reform.simulation_run_id + connection.execute( + insert(report_runs).values( + { + **row, + "baseline_simulation_run_id": baseline_run_id, + "reform_simulation_run_id": reform_run_id, + "forced": True, + } + ) + ) + return FoundReportRun( + id=row["id"], + inserted=True, + status=ReportRunStatus.PENDING, + baseline_simulation_run_id=baseline_run_id, + reform_simulation_run_id=reform_run_id, + ) + + +def insert_window_rerun( + connection: Connection, rerun: NewWindowRerun +) -> FoundBudgetWindow: + """Join the window's run on the re-run's versions, or create it, pending. + + Unforced (a keyed window's re-run), take the report's re-run lock and + join the report's window run on the re-run's catalog and .py versions + that hasn't failed and isn't a recalculation, with its year runs; + otherwise insert the window run (``find_or_insert_window_run``, so a + concurrent one is joined) and each year's report run on its sides' + simulation runs, found or inserted (``insert_window_years``), as the + window's create does (C1 · 24's answer 8). A forced re-run + (``recalculate``) takes no lock, is never refused, and inserts an extra + window run on new runs of every year, all marked forced. Every new run + is pending with no Modal call; the window run records its .py version + and no trigger (answer 6). Return the window run and its years, which + only when this call inserted the window run need their first years + started. Raise as ``insert_report_rerun`` does. + """ + versions = rerun.versions + years = tuple( + WindowYearToInsert( + year=window_year.year, + report_run_id=window_year.report_run_id, + simulation_ids={ + "baseline": window_year.baseline.simulation_id, + "reform": window_year.reform.simulation_id, + }, + proposed_run_ids={ + "baseline": window_year.baseline.simulation_run_id, + "reform": window_year.reform.simulation_run_id, + }, + ) + for window_year in rerun.years + ) + row = window_run_row( + run_id=rerun.window_run_id, + report_id=rerun.report_id, + population=rerun.population, + versions=versions, + recalculate=rerun.recalculate, + ) with ( _record_checked(budget_window_runs.c.report_id, report_runs.c.report_id), references_checked(), ): - # First, so a report deleted after its reads is told apart from a - # year's simulation deleted with it. - connection.execute( - insert(budget_window_runs).values( - id=rerun.window_run_id, + if rerun.recalculate: + # First, so a report deleted after its reads is told apart from + # a year's simulation deleted with it. + connection.execute(insert(budget_window_runs).values(row)) + window_run = FoundWindowRun( + id=rerun.window_run_id, inserted=True, status=ReportRunStatus.PENDING + ) + else: + lock_reruns_of(connection, rerun.report_id) + joined = find_joinable_window_run( + connection, report_id=rerun.report_id, - tax_benefit_model_version_id=population.tax_benefit_model_version_id, - trigger=ReportRunTrigger.MANUAL, - recalculate=rerun.recalculate, - status=ReportRunStatus.PENDING, + tax_benefit_model_version_id=( + rerun.population.tax_benefit_model_version_id + ), + policyengine_version=versions.policyengine_version, ) - ) - for window_year in rerun.years: - for side in (window_year.baseline, window_year.reform): - if not side.reused: - insert_simulation_run( - connection, - run_id=side.simulation_run_id, - simulation_id=side.simulation_id, - population=rerun.population_in(window_year.year), - versions=rerun.versions, - ) - connection.execute( - insert(report_runs), - [ - year_run_row( - window_year, + window_run = ( + joined + if joined is not None + else find_or_insert_window_run(connection, row) + ) + if not window_run.inserted: + return FoundBudgetWindow( report_id=rerun.report_id, - window_run_id=rerun.window_run_id, - versions=rerun.versions, - trigger=ReportRunTrigger.MANUAL, + report_inserted=False, + window_run=window_run, + years=stored_window_years( + connection, + window_run.id, + { + (year.year, side): year.simulation_ids[side] + for year in years + for side in ("baseline", "reform") + }, + ), ) - for window_year in rerun.years - ], + found_years = insert_window_years( + connection, + years, + report_id=rerun.report_id, + window_run_id=rerun.window_run_id, + population=rerun.population, + versions=versions, + forced=rerun.recalculate, ) + return FoundBudgetWindow( + report_id=rerun.report_id, + report_inserted=False, + window_run=window_run, + years=found_years, + ) def insert_household_report_rerun( connection: Connection, rerun: NewHouseholdReportRerun -) -> None: - """Create the household report's new run and a new run of each side, pending. +) -> FoundReportRun: + """Join the household report's run on the re-run's versions, or create it. - The report run has trigger ``manual`` and names no budget-window run; + The report run names no budget-window run and no trigger (answer 6); each side's run is of the report's own household simulation, with no - Modal call: the service then starts one household function call for the - report run. Raise as ``insert_report_rerun`` does. + Modal call: the service then starts one household function call for a + report run it created. Unforced (a keyed report's re-run), take the + report's re-run lock and join the report's run on the re-run's versions + that hasn't failed and wasn't forced, when there is one; otherwise each + side joins its simulation's run on those versions, or inserts one, under + a new report run (``find_or_insert_report_run_on_sides``), as an + economy report's re-run does (C1 · 24's answer 8). A forced re-run, as + every re-run of a household report without keys is (interim answer B), + takes no lock and is never refused: its report run and a new run of + each side are marked forced, which nothing joins and the + one-unfailed-run indexes leave out. Return the run and whether this call + created it, which only then needs its call. Raise as + ``insert_report_rerun`` does. """ - lock_reruns_of(connection, rerun.report_id) - _refuse_while_report_runs(connection, rerun.report_id) + versions = rerun.versions + row = _rerun_report_run_row( + run_id=rerun.run_id, report_id=rerun.report_id, versions=versions + ) + sides = rerun.named_sides + if not rerun.forced: + lock_reruns_of(connection, rerun.report_id) + joined = find_joinable_report_run( + connection, + report_id=rerun.report_id, + country_package_version=versions.country_package_version, + policyengine_version=versions.policyengine_version, + ) + if joined is not None: + return joined with _record_checked(report_runs.c.report_id), references_checked(): - for side in rerun.sides: - insert_household_simulation_run( - connection, - run_id=side.simulation_run_id, - simulation_id=side.simulation_id, - year=rerun.year, - tax_benefit_model_version_id=rerun.tax_benefit_model_version_id, - versions=rerun.versions, - ) - connection.execute( - insert(report_runs).values( - id=rerun.run_id, - report_id=rerun.report_id, - baseline_simulation_run_id=rerun.baseline.simulation_run_id, - reform_simulation_run_id=( - None if rerun.reform is None else rerun.reform.simulation_run_id - ), - budget_window_run_id=None, - year=None, - country_package_version=rerun.versions.country_package_version, - policyengine_version=rerun.versions.policyengine_version, - status=ReportRunStatus.PENDING, - trigger=ReportRunTrigger.MANUAL, - modal_call_id=None, - ) + if rerun.forced: + for side in sides.values(): + insert_household_simulation_run( + connection, + run_id=side.simulation_run_id, + simulation_id=side.simulation_id, + year=rerun.year, + tax_benefit_model_version_id=rerun.tax_benefit_model_version_id, + versions=versions, + forced=True, + ) + return _insert_forced_report_run(connection, row, sides) + found, _ = find_or_insert_report_run_on_sides( + connection, + row, + { + name: household_simulation_run_row( + run_id=side.simulation_run_id, + simulation_id=side.simulation_id, + year=rerun.year, + tax_benefit_model_version_id=rerun.tax_benefit_model_version_id, + versions=versions, + ) + for name, side in sides.items() + }, ) + return found -def _refuse_while_report_runs(connection: Connection, report_id: UUID) -> None: - """Raise RunInProgressError while the report has a run pending or running. - - A budget-window run under way is named first, then a report run. - """ - under_way = _run_under_way( - connection, budget_window_runs, budget_window_runs.c.report_id == report_id - ) or _run_under_way(connection, report_runs, report_runs.c.report_id == report_id) - if under_way is not None: - raise RunInProgressError(under_way) - +def insert_simulation_rerun( + connection: Connection, rerun: NewSimulationRerun +) -> FoundSimulationRun: + """Join the simulation's run on the re-run's versions, or create it, pending. -def insert_simulation_rerun(connection: Connection, rerun: NewSimulationRerun) -> None: - """Create the simulation's new run, pending with no call. - - Take the simulation's re-run lock first. Raise RunInProgressError, - creating nothing, when the simulation has a run pending or running, and - RerunRecordDeletedError or EconomyRecordReferenceError as + The run joined is the simulation's that hasn't failed and wasn't forced, + on the same year, catalog version, country package and .py versions; + otherwise ``rerun.run_id`` is created with no call. Return the run and + whether this call created it, which only then needs its Modal call. + Raise RerunRecordDeletedError or EconomyRecordReferenceError as ``insert_report_rerun`` does. """ - lock_reruns_of(connection, rerun.simulation_id) - under_way = _run_under_way( - connection, - simulation_runs, - simulation_runs.c.simulation_id == rerun.simulation_id, - ) - if under_way is not None: - raise RunInProgressError(under_way) with _record_checked(simulation_runs.c.simulation_id), references_checked(): - insert_simulation_run( + return find_or_insert_simulation_run( connection, - run_id=rerun.run_id, - simulation_id=rerun.simulation_id, - population=rerun.population, - versions=rerun.versions, + simulation_run_row( + run_id=rerun.run_id, + simulation_id=rerun.simulation_id, + population=rerun.population, + versions=rerun.versions, + ), ) @@ -690,3 +598,28 @@ def _record_checked(*own_keys: Column[Any]) -> Iterator[None]: if refused in {(key.table.name, key.key) for key in own_keys}: raise RerunRecordDeletedError from None raise + + +# The definition reads moved to rerun_definitions; their names stay importable here. +__all__ = [ + "HouseholdRerunSide", + "NewHouseholdReportRerun", + "NewReportRerun", + "NewSimulationRerun", + "NewWindowRerun", + "RecordKind", + "ReportDefinition", + "RerunRecordDeletedError", + "RerunSide", + "SideDefinition", + "SimulationDefinition", + "WindowRerunYear", + "WindowYearDefinition", + "insert_household_report_rerun", + "insert_report_rerun", + "insert_simulation_rerun", + "insert_window_rerun", + "lock_reruns_of", + "read_report_definition", + "read_simulation_definition", +] diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_records.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_records.py index b842d2b00..01059a24e 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_records.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_records.py @@ -1,22 +1,14 @@ -"""The simulation service's reads and writes for economy simulations and reports. +"""The simulation service's catalog reads and run writes for economy records. An economy report compares a baseline and a reform simulation of one -region's data for one year. The service reads the catalog rows the request -names from the Public API's tables, then creates in one transaction: - -- for each side, a new ``simulations`` row and its first ``simulation_runs`` - row, ``pending`` with no Modal call ID; or, when a run of the same - simulation already succeeded and may be reused (``find_reusable_run``), - nothing: the report names that run and its simulation instead; -- the ``reports`` row, naming both simulations and the reform's policy, with - the report's options in ``inputs``; -- its first ``report_runs`` row, ``pending`` with no Modal call ID and - trigger ``initial``, naming both simulation runs. - -A standalone economy simulation is one ``simulations`` row and its first -run, created the same way. - -The service then starts the Modal call that calculates the run it created, +region's data for one year. The service reads the catalog rows a request +names from the Public API's tables (``read_model_id``, ``read_region``, +``read_dataset``), then finds or creates, by definition key, each +simulation, the report and their runs (``keyed_economy_records``). A run +it creates is ``pending`` with no Modal call ID; this module builds and +inserts such runs (``simulation_run_row``, ``insert_simulation_run``). + +The service then starts the Modal call that calculates a run it created, and records the call's ID on that run, or fails it at once when Modal refuses the call. Both updates apply only while the run is still ``pending`` with no call ID: the coordinator or worker may already have @@ -28,7 +20,8 @@ Every function takes a connection, so the caller chooses the transactions. Each update sets only the columns the service's role may update, with ``updated_at``, whose automatic update the Public API's models make on their -own side only. +own side only. ``references_checked`` turns the database's refusal of a row +naming one that does not exist into ``EconomyRecordReferenceError``. """ from __future__ import annotations @@ -37,16 +30,7 @@ from dataclasses import dataclass from typing import TYPE_CHECKING, Any, Final -from sqlalchemy import ( - cast, - func, - insert, - literal, - or_, - select, - update, -) -from sqlalchemy.dialects.postgresql import JSONB +from sqlalchemy import func, insert, select, update from sqlalchemy.exc import IntegrityError from policyengine_simulation_persistence.input_tables import ( @@ -57,9 +41,7 @@ ) from policyengine_simulation_persistence.tables import ( ReportRunStatus, - ReportRunTrigger, SimulationStatus, - SimulationType, budget_window_runs, report_runs, reports, @@ -71,15 +53,12 @@ from collections.abc import Iterator, Sequence from uuid import UUID - from sqlalchemy import ColumnElement, Connection, FromClause, Table + from sqlalchemy import ColumnElement, Connection, Table # PostgreSQL's SQLSTATE for a row naming one that does not exist. FOREIGN_KEY_VIOLATION: Final = "23503" # A report's type, as the Public API reads it. ECONOMY_REPORT_TYPE: Final = "economy" -# The start of the error message of a report run whose coordinator refused a -# reused simulation run's output (``reused_simulation_: ``). -REFUSED_REUSE_PREFIX: Final = "reused_simulation_" # Both run tables' statuses use these values. _PENDING: Final = SimulationStatus.PENDING.value _FAILED: Final = SimulationStatus.FAILED.value @@ -145,68 +124,6 @@ class SimulationChoice: dynamic_id: UUID | None -@dataclass(frozen=True) -class ReusableRun: - """A succeeded simulation run a new report may name, and its simulation.""" - - simulation_id: UUID - simulation_run_id: UUID - - -@dataclass(frozen=True) -class ReportSimulation: - """The simulation and run one side of a report names. - - With ``reused``, both exist already and the run has succeeded, so nothing - is created for the side. Otherwise both are created, the run pending. - """ - - simulation_id: UUID - simulation_run_id: UUID - choice: SimulationChoice - reused: bool - - -@dataclass(frozen=True) -class NewEconomyReport: - """An economy report to create, with its first run. - - ``inputs`` holds the report's options as the Public API reads them. - """ - - id: UUID - run_id: UUID - country: str - label: str - description: str | None - tax_benefit_model_id: UUID - population: EconomyPopulation - versions: RunVersions - inputs: dict[str, Any] - baseline: ReportSimulation - reform: ReportSimulation - - @property - def new_simulation_run_ids(self) -> tuple[UUID, ...]: - """Return the IDs of the simulation runs created for the report.""" - return tuple( - side.simulation_run_id - for side in (self.baseline, self.reform) - if not side.reused - ) - - -@dataclass(frozen=True) -class NewEconomySimulation: - """A standalone economy simulation to create, with its first run.""" - - id: UUID - run_id: UUID - choice: SimulationChoice - population: EconomyPopulation - versions: RunVersions - - class EconomyRecordReferenceError(LookupError): """The database refused a row naming one that does not exist. @@ -276,307 +193,56 @@ def _dataset( return None if row is None else CatalogDataset(id=row.id, name=row.name) -def find_reusable_run( # noqa: PLR0913 # each keyword is one part of the match - connection: Connection, - *, - choice: SimulationChoice, - population: EconomyPopulation, - versions: RunVersions, - inputs: dict[str, Any], - output_uri_prefix: str, - excluded_run_id: UUID | None = None, -) -> ReusableRun | None: - """Return the succeeded run a new report's simulation may name, or None. - - The run is the newest, by completion, of a run: - - - of an economy simulation with the same policy, dynamic, catalog - version, dataset, region and year; - - that succeeded on the same country package and .py versions, for that - catalog version, year, dataset and region; - - whose output file is under ``output_uri_prefix``, the output bucket, - which never deletes a file; - - that a succeeded report run used, in a report with the same ``inputs`` - (options), so its file holds the outputs a report with those options - planned; - - that no report run has refused to reuse (an error message starting - ``reused_simulation_``), so a submission after a refused reuse - calculates the simulation again; and - - that is not ``excluded_run_id``, the other side's run. - - The coordinator may still refuse it, when the new report plans outputs - that report did not, as for a reform that turns on labour supply - responses: the refusal fails that report run, and the run is not offered - again. - """ - return _newest_reusable_run( - connection, - ( - simulations.c.simulation_type == SimulationType.ECONOMY, - simulations.c.policy_id.is_not_distinct_from(choice.policy_id), - simulations.c.dynamic_id.is_not_distinct_from(choice.dynamic_id), - simulations.c.tax_benefit_model_version_id - == population.tax_benefit_model_version_id, - simulations.c.dataset_id == population.dataset_id, - simulations.c.region_id == population.region_id, - simulations.c.year == population.year, - simulations.c.filter_field.is_(None), - ), - _WantedRun( - population=population, - versions=versions, - inputs=inputs, - output_uri_prefix=output_uri_prefix, - excluded_run_id=excluded_run_id, - ), - ) - - -def find_reusable_run_of( # noqa: PLR0913 # the simulation, then each part of the match +def insert_simulation_run( # noqa: PLR0913 # the run, what it calculates on, and its marker connection: Connection, *, + run_id: UUID, simulation_id: UUID, population: EconomyPopulation, versions: RunVersions, - inputs: dict[str, Any], - output_uri_prefix: str, - excluded_run_id: UUID | None = None, -) -> ReusableRun | None: - """Return the succeeded run of one simulation a re-run of its report may name. - - The run is the newest, by completion, of the simulation's runs that meets - every condition ``find_reusable_run`` sets on a run, or None. Its catalog - version, dataset and region are compared on the run itself: a re-run on - a later .py version calculates the simulation on that version's catalog - rows, while the simulation keeps the ones it was created on. - """ - return _newest_reusable_run( - connection, - (simulation_runs.c.simulation_id == simulation_id,), - _WantedRun( - population=population, - versions=versions, - inputs=inputs, - output_uri_prefix=output_uri_prefix, - excluded_run_id=excluded_run_id, - ), - ) - - -@dataclass(frozen=True) -class _WantedRun: - """What a reusable run must have calculated, and the run it must not be.""" - - population: EconomyPopulation - versions: RunVersions - inputs: dict[str, Any] - output_uri_prefix: str - excluded_run_id: UUID | None - - -def _newest_reusable_run( - connection: Connection, - simulation_conditions: tuple[ColumnElement[bool], ...], - wanted: _WantedRun, -) -> ReusableRun | None: - """Return the newest run meeting the conditions and every run condition.""" - used_by = report_runs.alias("used_by_report_run") - refused_by = report_runs.alias("refused_by_report_run") - used_with_same_options = ( - select(used_by.c.id) - .join(reports, reports.c.id == used_by.c.report_id) - .where( - used_by.c.status == ReportRunStatus.SUCCEEDED, - _names_run(used_by), - cast(reports.c.inputs, JSONB) == literal(wanted.inputs, JSONB), - ) - .exists() - ) - refused = ( - select(refused_by.c.id) - .where( - refused_by.c.status == ReportRunStatus.FAILED, - _names_run(refused_by), - refused_by.c.error_message.startswith( - REFUSED_REUSE_PREFIX, autoescape=True - ), - ) - .exists() - ) - population = wanted.population - versions = wanted.versions - conditions = [ - *simulation_conditions, - simulation_runs.c.status == SimulationStatus.SUCCEEDED, - simulation_runs.c.year == population.year, - simulation_runs.c.tax_benefit_model_version_id - == population.tax_benefit_model_version_id, - simulation_runs.c.country_package_version == versions.country_package_version, - simulation_runs.c.policyengine_version == versions.policyengine_version, - simulation_runs.c.dataset_id == population.dataset_id, - simulation_runs.c.region_id == population.region_id, - simulation_runs.c.output_uri.startswith( - wanted.output_uri_prefix, autoescape=True - ), - simulation_runs.c.output_sha256.is_not(None), - used_with_same_options, - ~refused, - ] - if wanted.excluded_run_id is not None: - conditions.append(simulation_runs.c.id != wanted.excluded_run_id) - row = connection.execute( - select(simulation_runs.c.id, simulation_runs.c.simulation_id) - .join(simulations, simulations.c.id == simulation_runs.c.simulation_id) - .where(*conditions) - .order_by(simulation_runs.c.completed_at.desc(), simulation_runs.c.id.desc()) - .limit(1) - ).one_or_none() - if row is None: - return None - return ReusableRun(simulation_id=row.simulation_id, simulation_run_id=row.id) - - -def _names_run(report_run: FromClause) -> ColumnElement[bool]: - """Return whether ``report_run`` names the outer query's simulation run.""" - return or_( - report_run.c.baseline_simulation_run_id == simulation_runs.c.id, - report_run.c.reform_simulation_run_id == simulation_runs.c.id, - ) - - -def insert_economy_report(connection: Connection, report: NewEconomyReport) -> None: - """Create the report, its first run and each side's new simulation and run. - - Raise EconomyRecordReferenceError when the database refuses a row it - names. The refusal ends the caller's transaction, or its savepoint. - """ - with references_checked(): - for side in (report.baseline, report.reform): - if not side.reused: - insert_simulation_with_run( - connection, - simulation_id=side.simulation_id, - run_id=side.simulation_run_id, - choice=side.choice, - population=report.population, - versions=report.versions, - ) - population = report.population - connection.execute( - insert(reports).values( - id=report.id, - label=report.label, - description=report.description, - country=report.country, - type=ECONOMY_REPORT_TYPE, - user_id=None, - tax_benefit_model_id=report.tax_benefit_model_id, - policy_id=report.reform.choice.policy_id, - baseline_simulation_id=report.baseline.simulation_id, - reform_simulation_id=report.reform.simulation_id, - household_id=None, - dataset_id=population.dataset_id, - region_id=population.region_id, - year=population.year, - budget_window_size=None, - inputs=report.inputs, - ) - ) - connection.execute( - insert(report_runs).values( - id=report.run_id, - report_id=report.id, - baseline_simulation_run_id=report.baseline.simulation_run_id, - reform_simulation_run_id=report.reform.simulation_run_id, - budget_window_run_id=None, - year=None, - country_package_version=report.versions.country_package_version, - policyengine_version=report.versions.policyengine_version, - status=ReportRunStatus.PENDING, - trigger=ReportRunTrigger.INITIAL, - modal_call_id=None, - ) - ) - - -def insert_economy_simulation( - connection: Connection, simulation: NewEconomySimulation + forced: bool = False, ) -> None: - """Create the standalone simulation and its first run, pending. + """Create a run of a stored simulation on ``population``, pending with no call. - Raise EconomyRecordReferenceError when the database refuses a row it - names. The refusal ends the caller's transaction, or its savepoint. + The run records the catalog version, dataset and region it calculates + on, which a re-run's may differ from its simulation's. ``forced`` marks + a forced re-run's run, which nothing joins. """ - with references_checked(): - insert_simulation_with_run( - connection, - simulation_id=simulation.id, - run_id=simulation.run_id, - choice=simulation.choice, - population=simulation.population, - versions=simulation.versions, - ) - - -def insert_simulation_with_run( # noqa: PLR0913 # the simulation's and its run's parts - connection: Connection, - *, - simulation_id: UUID, - run_id: UUID, - choice: SimulationChoice, - population: EconomyPopulation, - versions: RunVersions, -) -> None: - """Create an economy simulation and its first run, pending with no call.""" connection.execute( - insert(simulations).values( - id=simulation_id, - simulation_type=SimulationType.ECONOMY, - dataset_id=population.dataset_id, - household_id=None, - policy_id=choice.policy_id, - dynamic_id=choice.dynamic_id, - tax_benefit_model_version_id=population.tax_benefit_model_version_id, - region_id=population.region_id, - year=population.year, + insert(simulation_runs).values( + simulation_run_row( + run_id=run_id, + simulation_id=simulation_id, + population=population, + versions=versions, + forced=forced, + ) ) ) - insert_simulation_run( - connection, - run_id=run_id, - simulation_id=simulation_id, - population=population, - versions=versions, - ) -def insert_simulation_run( - connection: Connection, +def simulation_run_row( *, run_id: UUID, simulation_id: UUID, population: EconomyPopulation, versions: RunVersions, -) -> None: - """Create a run of a stored simulation on ``population``, pending with no call. - - The run records the catalog version, dataset and region it calculates - on, which a re-run's may differ from its simulation's. - """ - connection.execute( - insert(simulation_runs).values( - id=run_id, - simulation_id=simulation_id, - year=population.year, - tax_benefit_model_version_id=population.tax_benefit_model_version_id, - country_package_version=versions.country_package_version, - policyengine_version=versions.policyengine_version, - dataset_id=population.dataset_id, - region_id=population.region_id, - status=SimulationStatus.PENDING, - modal_call_id=None, - ) - ) + forced: bool = False, +) -> dict[str, Any]: + """Return an economy simulation run, pending with no call, as inserted.""" + return { + "id": run_id, + "simulation_id": simulation_id, + "year": population.year, + "tax_benefit_model_version_id": population.tax_benefit_model_version_id, + "country_package_version": versions.country_package_version, + "policyengine_version": versions.policyengine_version, + "dataset_id": population.dataset_id, + "region_id": population.region_id, + "status": SimulationStatus.PENDING, + "modal_call_id": None, + "forced": forced, + } @contextmanager diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_store.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_store.py index 4666ed427..79cbb2782 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_store.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_store.py @@ -2,20 +2,36 @@ The Simulation Entrypoint creates an economy report, or a standalone economy simulation, in three steps, each its own transaction, with the Modal call -started between them: it reads the request's inputs, creates the rows, then -records the call or fails the run it started. ``EconomyRunStore`` runs the -reads and writes of ``economy_run_records`` and ``policy_reform`` that way. +started between them: it reads the request's inputs, finds or creates the +rows by key, then records the call on a run it created or fails that run. +A stored record's re-run takes the same steps, joining or creating its new +runs instead. ``EconomyRunStore`` runs the reads and writes of +``economy_inputs``, ``keyed_economy_records``, ``keyed_window_records``, +``economy_rerun_records`` and ``economy_run_records`` that way. """ from __future__ import annotations -from dataclasses import dataclass, replace -from typing import TYPE_CHECKING, Any, Literal, get_args +from typing import TYPE_CHECKING from sqlalchemy.exc import SQLAlchemyError -from policyengine_simulation_persistence.budget_window_records import ( - insert_budget_window_report, +from policyengine_simulation_persistence.economy_inputs import ( + BudgetWindowInputs, + EconomyCatalogRows, + EconomyReportInputs, + EconomyRequest, + EconomySimulationInputs, + ReportSide, + ReportSideError, + SideRefusal, + SimulationInputs, + UnknownDatasetError, + UnknownRegionError, + read_catalog_rows, + read_report_sides, + read_simulation_values, + read_window_sides, ) from policyengine_simulation_persistence.economy_rerun_records import ( insert_report_rerun, @@ -29,52 +45,28 @@ read_economy_simulation, ) from policyengine_simulation_persistence.economy_run_records import ( - CatalogDataset, - CatalogRegion, - EconomyPopulation, - ReusableRun, - RunVersions, SimulationChoice, fail_unstarted_report_run, fail_unstarted_simulation_run, - find_reusable_run, - find_reusable_run_of, - insert_economy_report, - insert_economy_simulation, - read_dataset, - read_dataset_by_id, - read_model_id, - read_region, record_report_run_call, record_simulation_run_call, ) from policyengine_simulation_persistence.engine import bounded_transaction -from policyengine_simulation_persistence.household_job_records import ( - read_catalog_version_id, +from policyengine_simulation_persistence.keyed_economy_records import ( + find_or_create_economy_report, + find_or_create_economy_simulation, ) -from policyengine_simulation_persistence.household_job_store import ( - UnknownCatalogVersionError, -) -from policyengine_simulation_persistence.policy_reform import ( - MissingPolicyParametersError, - OverlappingReformError, - UnknownDynamicError, - UnknownPolicyError, - combine_reforms, - read_dynamic_reform, - read_policy_reform, +from policyengine_simulation_persistence.keyed_window_records import ( + find_or_create_budget_window, ) if TYPE_CHECKING: - from collections.abc import Callable, Iterable, Sequence + from collections.abc import Callable, Sequence from contextlib import AbstractContextManager from uuid import UUID from sqlalchemy import Connection, Engine - from policyengine_simulation_persistence.budget_window_records import ( - NewBudgetWindowReport, - ) from policyengine_simulation_persistence.economy_rerun_records import ( NewReportRerun, NewSimulationRerun, @@ -82,62 +74,31 @@ ReportDefinition, SideDefinition, SimulationDefinition, - WindowYearDefinition, ) from policyengine_simulation_persistence.economy_run_reads import ( EconomyReportState, EconomySimulationState, ) - from policyengine_simulation_persistence.economy_run_records import ( - NewEconomyReport, - NewEconomySimulation, + from policyengine_simulation_persistence.keyed_economy_records import ( + FoundEconomyReport, + FoundEconomySimulation, + KeyedEconomyReport, + KeyedEconomySimulation, + ) + from policyengine_simulation_persistence.keyed_window_records import ( + FoundBudgetWindow, + KeyedBudgetWindow, + ) + from policyengine_simulation_persistence.shared_rows import ( + FoundReportRun, + FoundSimulationRun, ) - from policyengine_simulation_persistence.policy_reform import PolicyReform from policyengine_simulation_persistence.tables import ( ReportRunStatus, SimulationStatus, ) type TransactionFactory = Callable[[], AbstractContextManager[Connection]] -# Which of a report's simulations a value belongs to. -type ReportSide = Literal["baseline", "reform"] -# Finds a report side's reusable run, given the side, its policy and dynamic, -# and the run the other side reuses, which it must not. -type ReusableRunSearch = Callable[ - [ReportSide, SimulationChoice, UUID | None], ReusableRun | None -] -# The errors a simulation's own policy or dynamic can raise. -type SideRefusal = ( - UnknownPolicyError - | UnknownDynamicError - | MissingPolicyParametersError - | OverlappingReformError -) -# Caught by the type itself, so the two never name different errors. -_SIDE_ERRORS: tuple[type[SideRefusal], ...] = get_args(SideRefusal.__value__) - - -class UnknownRegionError(LookupError): - """The catalog version has no region with the requested code.""" - - -class UnknownDatasetError(LookupError): - """The catalog version has no dataset with the requested name.""" - - -class ReportSideError(Exception): - """A report side's policy or dynamic is refused. - - ``side`` names the side, and ``error`` is the policy reader's refusal: - UnknownPolicyError, UnknownDynamicError, MissingPolicyParametersError or - OverlappingReformError. - """ - - def __init__(self, side: ReportSide, error: SideRefusal) -> None: - """Keep the side and the refusal.""" - super().__init__(f"the report's {side}: {error}") - self.side: ReportSide = side - self.error = error class EconomyRecordOutcomeUnknownError(RuntimeError): @@ -148,100 +109,6 @@ class EconomyRecordOutcomeUnknownError(RuntimeError): """ -@dataclass(frozen=True) -class EconomyRequest: - """What an economy simulation or report request names, apart from policies. - - ``policyengine_version`` is the .py version the calculation runs on, - which chooses the country's catalog version. ``dataset_name`` None means - the region's default dataset. - """ - - country: str - policyengine_version: str - region_code: str - dataset_name: str | None - year: int - - -@dataclass(frozen=True) -class RunReuse: - """How a report looks for simulation runs to reuse (``find_reusable_run``). - - ``versions`` are those the new runs would calculate on, ``inputs`` the - report's options, and ``output_uri_prefix`` the output bucket's - ``gs:///``. - """ - - versions: RunVersions - inputs: dict[str, Any] - output_uri_prefix: str - - -@dataclass(frozen=True) -class EconomyCatalogRows: - """The catalog rows a request is calculated on.""" - - catalog_version_id: UUID - model_id: UUID - region: CatalogRegion - dataset: CatalogDataset - - def population(self, year: int) -> EconomyPopulation: - """Return what every simulation of the request calculates on.""" - return EconomyPopulation( - tax_benefit_model_version_id=self.catalog_version_id, - region_id=self.region.id, - dataset_id=self.dataset.id, - year=year, - ) - - -@dataclass(frozen=True) -class SimulationInputs: - """One simulation's policy and dynamic, and the values they set together. - - ``reusable_run`` names a succeeded run the simulation may use instead of - a new one, when the request looked for one and one exists. - """ - - choice: SimulationChoice - reform: PolicyReform - reusable_run: ReusableRun | None = None - - -@dataclass(frozen=True) -class EconomySimulationInputs: - """What a standalone economy simulation is read from.""" - - catalog: EconomyCatalogRows - simulation: SimulationInputs - - -@dataclass(frozen=True) -class EconomyReportInputs: - """What an economy report is read from: the catalog rows and both sides.""" - - catalog: EconomyCatalogRows - baseline: SimulationInputs - reform: SimulationInputs - - -@dataclass(frozen=True) -class BudgetWindowInputs: - """What a budget-window report is read from, and each year's reusable runs. - - ``baseline`` and ``reform`` hold each side's values, the same in every - year. ``reusable_runs`` gives, by year, the baseline's and the reform's - reusable run, each None when there is none. - """ - - catalog: EconomyCatalogRows - baseline: SimulationInputs - reform: SimulationInputs - reusable_runs: dict[int, tuple[ReusableRun | None, ReusableRun | None]] - - class EconomyRunStore: """Read and write economy simulations and reports, each in its own transaction.""" @@ -273,8 +140,8 @@ def read_simulation_inputs( OverlappingReformError. """ with self._transaction() as connection: - catalog = _catalog_rows(connection, request) - simulation = _simulation_inputs( + catalog = read_catalog_rows(connection, request) + simulation = read_simulation_values( connection, request.country, catalog.catalog_version_id, choice ) return EconomySimulationInputs(catalog=catalog, simulation=simulation) @@ -285,31 +152,17 @@ def read_report_inputs( *, baseline: SimulationChoice, reform: SimulationChoice, - reuse: RunReuse | None, ) -> EconomyReportInputs: - """Read a report's catalog rows, both sides' values and reusable runs. + """Read a report's catalog rows and both sides' values together. - With ``reuse``, each side gets the run ``find_reusable_run`` finds, - and the reform never gets the baseline's. Raise - UnknownCatalogVersionError, UnknownRegionError or UnknownDatasetError, - or ReportSideError naming the side whose policy or dynamic is refused. + Raise UnknownCatalogVersionError, UnknownRegionError or + UnknownDatasetError, or ReportSideError naming the side whose policy + or dynamic is refused. """ with self._transaction() as connection: - catalog = _catalog_rows(connection, request) - search = ( - None - if reuse is None - else _search_by_definition( - connection, catalog.population(request.year), reuse - ) - ) - return _report_inputs( - connection, - request, - catalog, - baseline=baseline, - reform=reform, - search=search, + catalog = read_catalog_rows(connection, request) + return read_report_sides( + connection, request, catalog, baseline=baseline, reform=reform ) def read_report_definition(self, report_id: UUID) -> ReportDefinition | None: @@ -330,38 +183,21 @@ def read_report_rerun_inputs( *, baseline: SideDefinition, reform: SideDefinition, - reuse: RunReuse | None, ) -> EconomyReportInputs: - """Read a report re-run's catalog rows, both sides' values and reusable runs. + """Read a report re-run's catalog rows and both sides' values. ``request`` names the stored report's region code and dataset name, - found in the catalog version of the current .py version. With - ``reuse``, each side gets the run ``find_reusable_run_of`` finds among - its own simulation's runs, and the reform never gets the baseline's. - Raise the errors ``read_report_inputs`` raises. + found in the catalog version of the current .py version. Raise the + errors ``read_report_inputs`` raises. """ with self._transaction() as connection: - catalog = _catalog_rows(connection, request) - search = ( - None - if reuse is None - else _search_own_runs( - connection, - catalog.population(request.year), - reuse, - { - "baseline": baseline.simulation_id, - "reform": reform.simulation_id, - }, - ) - ) - return _report_inputs( + catalog = read_catalog_rows(connection, request) + return read_report_sides( connection, request, catalog, baseline=baseline.choice, reform=reform.choice, - search=search, ) def read_window_rerun_inputs( @@ -370,64 +206,43 @@ def read_window_rerun_inputs( *, baseline: SimulationChoice, reform: SimulationChoice, - years: Sequence[WindowYearDefinition], - reuse: RunReuse | None, ) -> BudgetWindowInputs: - """Read a window re-run's catalog rows, both sides' values and each year's runs. + """Read a window re-run's catalog rows and both sides' values. - ``request.year`` is the window's first year. With ``reuse``, each - year's sides get the runs ``find_reusable_run_of`` finds among that - year's own simulations' runs, and the reform never gets the - baseline's. Raise the errors ``read_report_inputs`` raises. + ``request.year`` is the window's first year, and ``request`` names + the stored report's region code and dataset name, found in the + catalog version of the current .py version. Raise the errors + ``read_report_inputs`` raises. """ with self._transaction() as connection: - catalog = _catalog_rows(connection, request) - return _window_inputs( - connection, - request, - catalog, - baseline=baseline, - reform=reform, - searches=( - ( - window_year.year, - None - if reuse is None - else _search_own_runs( - connection, - catalog.population(window_year.year), - reuse, - { - "baseline": window_year.baseline_simulation_id, - "reform": window_year.reform_simulation_id, - }, - ), - ) - for window_year in years - ), + catalog = read_catalog_rows(connection, request) + return read_window_sides( + connection, request, catalog, baseline=baseline, reform=reform ) - def create_window_rerun(self, rerun: NewWindowRerun) -> None: - """Create the window's new run and its years' runs; see ``insert_window_rerun``. + def create_window_rerun(self, rerun: NewWindowRerun) -> FoundBudgetWindow: + """Join or create the window's run and its years; see ``insert_window_rerun``. - Raise EconomyRecordOutcomeUnknownError as ``create_report`` does. + Raise EconomyRecordOutcomeUnknownError as ``find_or_create_report`` does. """ - self._create(lambda connection: insert_window_rerun(connection, rerun)) + return self._create(lambda connection: insert_window_rerun(connection, rerun)) - def create_report_rerun(self, rerun: NewReportRerun) -> None: - """Create the report's new run and its sides' new simulation runs. + def create_report_rerun(self, rerun: NewReportRerun) -> FoundReportRun: + """Join or create the report's run; see ``insert_report_rerun``. Raise ``insert_report_rerun``'s errors, and - EconomyRecordOutcomeUnknownError as ``create_report`` does. + EconomyRecordOutcomeUnknownError as ``find_or_create_report`` does. """ - self._create(lambda connection: insert_report_rerun(connection, rerun)) + return self._create(lambda connection: insert_report_rerun(connection, rerun)) - def create_simulation_rerun(self, rerun: NewSimulationRerun) -> None: - """Create the simulation's new run; see ``insert_simulation_rerun``. + def create_simulation_rerun(self, rerun: NewSimulationRerun) -> FoundSimulationRun: + """Join or create the simulation's run; see ``insert_simulation_rerun``. - Raise EconomyRecordOutcomeUnknownError as ``create_report`` does. + Raise EconomyRecordOutcomeUnknownError as ``find_or_create_report`` does. """ - self._create(lambda connection: insert_simulation_rerun(connection, rerun)) + return self._create( + lambda connection: insert_simulation_rerun(connection, rerun) + ) def read_budget_window_inputs( self, @@ -435,81 +250,71 @@ def read_budget_window_inputs( *, baseline: SimulationChoice, reform: SimulationChoice, - reuse: RunReuse | None, - years: Sequence[int], ) -> BudgetWindowInputs: - """Read a window's catalog rows and both sides' values, then each year's runs. + """Read a window's catalog rows and both sides' values together. - ``request.year`` is the window's first year. With ``reuse``, each - year's sides get the runs ``find_reusable_run`` finds for that year, - and the reform never gets the baseline's. Raise the errors + ``request.year`` is the window's first year. Raise the errors ``read_report_inputs`` raises. """ with self._transaction() as connection: - catalog = _catalog_rows(connection, request) - return _window_inputs( - connection, - request, - catalog, - baseline=baseline, - reform=reform, - searches=( - ( - year, - None - if reuse is None - else _search_by_definition( - connection, catalog.population(year), reuse - ), - ) - for year in years - ), + catalog = read_catalog_rows(connection, request) + return read_window_sides( + connection, request, catalog, baseline=baseline, reform=reform ) - def create_budget_window_report(self, report: NewBudgetWindowReport) -> None: - """Create the window's report, its budget-window run and each year's runs. + def find_or_create_report(self, report: KeyedEconomyReport) -> FoundEconomyReport: + """Find the report by key, with its run, or create them. - Raise ``insert_budget_window_report``'s errors, and + See ``find_or_create_economy_report``; raise its errors, and EconomyRecordOutcomeUnknownError when the commit fails after the rows were inserted. """ - self._create(lambda connection: insert_budget_window_report(connection, report)) + return self._create( + lambda connection: find_or_create_economy_report(connection, report) + ) - def create_report(self, report: NewEconomyReport) -> None: - """Create the report, its new simulations and its runs. + def find_or_create_budget_window( + self, window: KeyedBudgetWindow + ) -> FoundBudgetWindow: + """Find the window by key, with its window run, or create them. - Raise ``insert_economy_report``'s errors, and - EconomyRecordOutcomeUnknownError when the commit fails after the - rows were inserted. + See ``find_or_create_budget_window``; raise as + ``find_or_create_report`` does. """ - self._create(lambda connection: insert_economy_report(connection, report)) + return self._create( + lambda connection: find_or_create_budget_window(connection, window) + ) - def create_simulation(self, simulation: NewEconomySimulation) -> None: - """Create the simulation and its run; see ``insert_economy_simulation``. + def find_or_create_simulation( + self, simulation: KeyedEconomySimulation + ) -> FoundEconomySimulation: + """Find the simulation by key, with its run, or create them. - Raise EconomyRecordOutcomeUnknownError as ``create_report`` does. + Raise as ``find_or_create_report`` does. """ - self._create( - lambda connection: insert_economy_simulation(connection, simulation) + return self._create( + lambda connection: find_or_create_economy_simulation(connection, simulation) ) - def _create(self, insert: Callable[[Connection], None]) -> None: + def _create[Created](self, insert: Callable[[Connection], Created]) -> Created: """Run ``insert`` in a transaction, telling a failed commit apart. - An error from ``insert`` leaves nothing written and propagates. An - error once it has run is the commit's, after which the rows may - exist: EconomyRecordOutcomeUnknownError. + Return what ``insert`` returns. An error from ``insert`` leaves + nothing written and propagates. An error once it has run is the + commit's, after which the rows may exist: + EconomyRecordOutcomeUnknownError. """ inserted = False try: with self._transaction() as connection: - insert(connection) + created = insert(connection) inserted = True except SQLAlchemyError as error: if not inserted: raise msg = "the create's commit failed after its rows were inserted" raise EconomyRecordOutcomeUnknownError(msg) from error + return created def record_report_call( self, report_run_id: UUID, modal_call_id: str @@ -568,213 +373,19 @@ def read_simulation(self, simulation_id: UUID) -> EconomySimulationState | None: return read_economy_simulation(connection, simulation_id) -def _catalog_rows( - connection: Connection, request: EconomyRequest -) -> EconomyCatalogRows: - """Read the catalog version, model, region and dataset a request names. - - Raise UnknownCatalogVersionError, UnknownRegionError or - UnknownDatasetError. - """ - country = request.country - catalog_version_id = read_catalog_version_id( - connection, - country=country, - policyengine_version=request.policyengine_version, - ) - model_id = read_model_id(connection, country=country) - if catalog_version_id is None or model_id is None: - msg = f"{country} has no catalog version for .py {request.policyengine_version}" - raise UnknownCatalogVersionError(msg) - region = read_region( - connection, - catalog_version_id=catalog_version_id, - region_code=request.region_code, - ) - if region is None: - msg = ( - f"{country}'s catalog version for .py {request.policyengine_version} " - f"has no region {request.region_code}" - ) - raise UnknownRegionError(msg) - dataset = ( - read_dataset_by_id( - connection, - catalog_version_id=catalog_version_id, - dataset_id=region.default_dataset_id, - ) - if request.dataset_name is None - else read_dataset( - connection, - catalog_version_id=catalog_version_id, - name=request.dataset_name, - ) - ) - if dataset is None: - msg = ( - f"{country}'s catalog version for .py {request.policyengine_version} " - f"has no dataset {request.dataset_name}" - ) - raise UnknownDatasetError(msg) - return EconomyCatalogRows( - catalog_version_id=catalog_version_id, - model_id=model_id, - region=region, - dataset=dataset, - ) - - -def _simulation_inputs( - connection: Connection, - country: str, - catalog_version_id: UUID, - choice: SimulationChoice, -) -> SimulationInputs: - """Read one simulation's policy and dynamic values, combined.""" - policy_reform = ( - {} - if choice.policy_id is None - else read_policy_reform( - connection, - country=country, - policy_id=choice.policy_id, - catalog_version_id=catalog_version_id, - ) - ) - dynamic_reform = ( - {} - if choice.dynamic_id is None - else read_dynamic_reform( - connection, - dynamic_id=choice.dynamic_id, - catalog_version_id=catalog_version_id, - ) - ) - return SimulationInputs( - choice=choice, reform=combine_reforms(policy_reform, dynamic_reform) - ) - - -def _side_inputs( - connection: Connection, - request: EconomyRequest, - catalog: EconomyCatalogRows, - side: ReportSide, - choice: SimulationChoice, -) -> SimulationInputs: - """Read one report side's values; raise ReportSideError naming a refused side.""" - try: - return _simulation_inputs( - connection, request.country, catalog.catalog_version_id, choice - ) - except _SIDE_ERRORS as error: - raise ReportSideError(side, error) from error - - -def _report_inputs( # noqa: PLR0913 # the request's rows, both sides and the search - connection: Connection, - request: EconomyRequest, - catalog: EconomyCatalogRows, - *, - baseline: SimulationChoice, - reform: SimulationChoice, - search: ReusableRunSearch | None, -) -> EconomyReportInputs: - """Read both sides' values and, with ``search``, each side's reusable run. - - The reform never gets the run the baseline reuses. - """ - sides: list[SimulationInputs] = [] - excluded_run_id: UUID | None = None - requested: tuple[tuple[ReportSide, SimulationChoice], ...] = ( - ("baseline", baseline), - ("reform", reform), - ) - for side, choice in requested: - inputs = _side_inputs(connection, request, catalog, side, choice) - reusable_run = None if search is None else search(side, choice, excluded_run_id) - if reusable_run is not None: - excluded_run_id = reusable_run.simulation_run_id - inputs = replace(inputs, reusable_run=reusable_run) - sides.append(inputs) - return EconomyReportInputs(catalog=catalog, baseline=sides[0], reform=sides[1]) - - -def _window_inputs( # noqa: PLR0913 # the request's rows, both sides and each year's search - connection: Connection, - request: EconomyRequest, - catalog: EconomyCatalogRows, - *, - baseline: SimulationChoice, - reform: SimulationChoice, - searches: Iterable[tuple[int, ReusableRunSearch | None]], -) -> BudgetWindowInputs: - """Read both sides' values, and each year's reusable runs with its search. - - A year without a search reuses nothing; in each year the reform never - gets the run the baseline reuses. - """ - baseline_inputs = _side_inputs(connection, request, catalog, "baseline", baseline) - reform_inputs = _side_inputs(connection, request, catalog, "reform", reform) - reusable_runs: dict[int, tuple[ReusableRun | None, ReusableRun | None]] = {} - for year, search in searches: - baseline_run = reform_run = None - if search is not None: - baseline_run = search("baseline", baseline, None) - reform_run = search( - "reform", - reform, - None if baseline_run is None else baseline_run.simulation_run_id, - ) - reusable_runs[year] = (baseline_run, reform_run) - return BudgetWindowInputs( - catalog=catalog, - baseline=baseline_inputs, - reform=reform_inputs, - reusable_runs=reusable_runs, - ) - - -def _search_by_definition( - connection: Connection, population: EconomyPopulation, reuse: RunReuse -) -> ReusableRunSearch: - """Search any simulation with the side's definition (a new report's sides).""" - - def search( - _side: ReportSide, choice: SimulationChoice, excluded_run_id: UUID | None - ) -> ReusableRun | None: - return find_reusable_run( - connection, - choice=choice, - population=population, - versions=reuse.versions, - inputs=reuse.inputs, - output_uri_prefix=reuse.output_uri_prefix, - excluded_run_id=excluded_run_id, - ) - - return search - - -def _search_own_runs( - connection: Connection, - population: EconomyPopulation, - reuse: RunReuse, - simulation_ids: dict[ReportSide, UUID], -) -> ReusableRunSearch: - """Search only each side's own simulation's runs (a stored report's re-run).""" - - def search( - side: ReportSide, _choice: SimulationChoice, excluded_run_id: UUID | None - ) -> ReusableRun | None: - return find_reusable_run_of( - connection, - simulation_id=simulation_ids[side], - population=population, - versions=reuse.versions, - inputs=reuse.inputs, - output_uri_prefix=reuse.output_uri_prefix, - excluded_run_id=excluded_run_id, - ) - - return search +__all__ = [ + "BudgetWindowInputs", + "EconomyCatalogRows", + "EconomyRecordOutcomeUnknownError", + "EconomyReportInputs", + "EconomyRequest", + "EconomyRunStore", + "EconomySimulationInputs", + "ReportSide", + "ReportSideError", + "SideRefusal", + "SimulationInputs", + "TransactionFactory", + "UnknownDatasetError", + "UnknownRegionError", +] diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/household_report_records.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/household_report_records.py index 3650d9c8d..c4df16170 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/household_report_records.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/household_report_records.py @@ -1,47 +1,31 @@ -"""The simulation service's writes for household reports. +"""The simulation service's household report type and household run rows. A household report calculates one stored household, for one year, under a -baseline policy and, optionally, a reform. The service creates in one -transaction: - -- for each side, a new household ``simulations`` row naming the household - and the side's policy, and its first ``simulation_runs`` row, ``pending`` - with no Modal call ID. Household runs are never reused: each report gets - its own; -- the ``reports`` row, of type ``household``, naming the household, both - simulations and the reform's policy, with the report's options in - ``inputs``; -- its first ``report_runs`` row, ``pending`` with no Modal call ID and - trigger ``initial``, naming both simulation runs, or the baseline's - alone. +baseline policy and, optionally, a reform. Its ``reports`` row has type +``household`` (``HOUSEHOLD_REPORT_TYPE``) and names the household; each side +is a household ``simulations`` row naming the household and the side's +policy. The service finds or creates the report, its simulations and its +first run by definition key (``keyed_household_records``), and re-runs a +stored one (``economy_rerun_records``). Either creates each side's run +``pending`` with no Modal call ID, from ``household_simulation_run_row``; +a forced re-run inserts it with ``insert_household_simulation_run``. The service then starts one household function call for the report run and records the call's ID on it, or fails it and its simulation runs at once, with ``economy_run_records``' report run writes. The household function writes the rest: each run's ``household_result``, and every status after -``pending``. A re-run (``economy_rerun_records``) adds a run to each of a -stored report's household simulations with ``insert_household_simulation_run``. +``pending``. """ from __future__ import annotations -from dataclasses import dataclass from typing import TYPE_CHECKING, Any, Final from sqlalchemy import insert -from policyengine_simulation_persistence.economy_run_records import ( - references_checked, -) from policyengine_simulation_persistence.tables import ( - ReportRunStatus, - ReportRunTrigger, SimulationStatus, - SimulationType, - report_runs, - reports, simulation_runs, - simulations, ) if TYPE_CHECKING: @@ -55,127 +39,6 @@ HOUSEHOLD_REPORT_TYPE: Final = "household" -@dataclass(frozen=True) -class HouseholdReportSimulation: - """The new household simulation and run one side of a report creates. - - ``policy_id`` is the side's stored policy, or None for current law. - """ - - simulation_id: UUID - simulation_run_id: UUID - policy_id: UUID | None - - -@dataclass(frozen=True) -class NewHouseholdReport: - """A household report to create, with its first run. - - ``reform`` is None for a report of the baseline alone. ``inputs`` holds - the report's options as the Public API reads them. - """ - - id: UUID - run_id: UUID - country: str - label: str - description: str | None - tax_benefit_model_id: UUID - tax_benefit_model_version_id: UUID - household_id: UUID - year: int - versions: RunVersions - inputs: dict[str, Any] - baseline: HouseholdReportSimulation - reform: HouseholdReportSimulation | None - - @property - def sides(self) -> tuple[HouseholdReportSimulation, ...]: - """Return each side the report calculates, the baseline's first.""" - return (self.baseline,) if self.reform is None else (self.baseline, self.reform) - - @property - def simulation_run_ids(self) -> tuple[UUID, ...]: - """Return the IDs of the simulation runs created for the report.""" - return tuple(side.simulation_run_id for side in self.sides) - - -def insert_household_report(connection: Connection, report: NewHouseholdReport) -> None: - """Create the report, its first run and each side's simulation and run. - - Raise EconomyRecordReferenceError when the database refuses a row it - names. The refusal ends the caller's transaction, or its savepoint. - """ - with references_checked(): - for side in report.sides: - _insert_household_simulation(connection, report, side) - reform = report.reform - connection.execute( - insert(reports).values( - id=report.id, - label=report.label, - description=report.description, - country=report.country, - type=HOUSEHOLD_REPORT_TYPE, - user_id=None, - tax_benefit_model_id=report.tax_benefit_model_id, - policy_id=None if reform is None else reform.policy_id, - baseline_simulation_id=report.baseline.simulation_id, - reform_simulation_id=None if reform is None else reform.simulation_id, - household_id=report.household_id, - dataset_id=None, - region_id=None, - year=report.year, - budget_window_size=None, - inputs=report.inputs, - ) - ) - connection.execute( - insert(report_runs).values( - id=report.run_id, - report_id=report.id, - baseline_simulation_run_id=report.baseline.simulation_run_id, - reform_simulation_run_id=( - None if reform is None else reform.simulation_run_id - ), - budget_window_run_id=None, - year=None, - country_package_version=report.versions.country_package_version, - policyengine_version=report.versions.policyengine_version, - status=ReportRunStatus.PENDING, - trigger=ReportRunTrigger.INITIAL, - modal_call_id=None, - ) - ) - - -def _insert_household_simulation( - connection: Connection, report: NewHouseholdReport, side: HouseholdReportSimulation -) -> None: - """Create one side's household simulation and its first run, pending.""" - connection.execute( - insert(simulations).values( - id=side.simulation_id, - simulation_type=SimulationType.HOUSEHOLD, - dataset_id=None, - household_id=report.household_id, - policy_id=side.policy_id, - dynamic_id=None, - tax_benefit_model_version_id=report.tax_benefit_model_version_id, - region_id=None, - year=report.year, - ) - ) - insert_household_simulation_run( - connection, - run_id=side.simulation_run_id, - simulation_id=side.simulation_id, - year=report.year, - tax_benefit_model_version_id=report.tax_benefit_model_version_id, - versions=report.versions, - ) - - def insert_household_simulation_run( # noqa: PLR0913 # the run and what it calculates on connection: Connection, *, @@ -184,23 +47,51 @@ def insert_household_simulation_run( # noqa: PLR0913 # the run and what it cal year: int, tax_benefit_model_version_id: UUID, versions: RunVersions, + forced: bool = False, ) -> None: """Create a run of a household simulation, pending with no Modal call ID. It records the year, catalog version and versions it calculates on; a - household run names no dataset or region. + household run names no dataset or region. A ``forced`` run is an extra + run that nothing joins. """ connection.execute( insert(simulation_runs).values( - id=run_id, - simulation_id=simulation_id, - year=year, - tax_benefit_model_version_id=tax_benefit_model_version_id, - country_package_version=versions.country_package_version, - policyengine_version=versions.policyengine_version, - dataset_id=None, - region_id=None, - status=SimulationStatus.PENDING, - modal_call_id=None, + { + **household_simulation_run_row( + run_id=run_id, + simulation_id=simulation_id, + year=year, + tax_benefit_model_version_id=tax_benefit_model_version_id, + versions=versions, + ), + "forced": forced, + } ) ) + + +def household_simulation_run_row( + *, + run_id: UUID, + simulation_id: UUID, + year: int, + tax_benefit_model_version_id: UUID, + versions: RunVersions, +) -> dict[str, Any]: + """Return a household simulation's new run, pending with no Modal call ID. + + Unforced: ``insert_household_simulation_run`` adds ``forced`` to it. + """ + return { + "id": run_id, + "simulation_id": simulation_id, + "year": year, + "tax_benefit_model_version_id": tax_benefit_model_version_id, + "country_package_version": versions.country_package_version, + "policyengine_version": versions.policyengine_version, + "dataset_id": None, + "region_id": None, + "status": SimulationStatus.PENDING, + "modal_call_id": None, + } diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/household_report_store.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/household_report_store.py index 2d5490c25..e33d29231 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/household_report_store.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/household_report_store.py @@ -2,13 +2,13 @@ The Simulation Entrypoint creates a household report in three steps, each its own transaction, with the household function's call started between -them: it reads the report's inputs, creates the rows, then records the call -on the report run or fails the run. A stored report's re-run takes the same -steps, creating the report's new runs instead. ``HouseholdReportStore`` runs -the reads and writes of ``household_report_records``, -``household_job_records``, ``policy_reform``, ``economy_rerun_records``' -household report re-run and ``economy_run_records``' report run writes that -way. +them: it reads the report's inputs, finds or creates the rows by key, then +records the call on a report run it created or fails the run. A stored +report's re-run takes the same steps, joining or creating the report's new +runs instead. ``HouseholdReportStore`` runs the reads and writes of +``keyed_household_records``, ``household_job_records``, ``policy_reform``, +``economy_rerun_records``' household report re-run and +``economy_run_records``' report run writes that way. """ from __future__ import annotations @@ -39,8 +39,8 @@ UnknownCatalogVersionError, UnknownHouseholdError, ) -from policyengine_simulation_persistence.household_report_records import ( - insert_household_report, +from policyengine_simulation_persistence.keyed_household_records import ( + find_or_create_household_report, ) from policyengine_simulation_persistence.policy_reform import ( MissingPolicyParametersError, @@ -62,10 +62,12 @@ from policyengine_simulation_persistence.household_job_records import ( StoredHousehold, ) - from policyengine_simulation_persistence.household_report_records import ( - NewHouseholdReport, + from policyengine_simulation_persistence.keyed_household_records import ( + FoundHouseholdReport, + KeyedHouseholdReport, ) from policyengine_simulation_persistence.policy_reform import PolicyReform + from policyengine_simulation_persistence.shared_rows import FoundReportRun from policyengine_simulation_persistence.tables import ReportRunStatus type TransactionFactory = Callable[[], AbstractContextManager[Connection]] @@ -176,37 +178,45 @@ def read_inputs( reforms=reforms, ) - def create_report(self, report: NewHouseholdReport) -> None: - """Create the report, its simulations and its runs. + def find_or_create_report( + self, report: KeyedHouseholdReport + ) -> FoundHouseholdReport: + """Find the report by key, with its run, or create them. - Raise ``insert_household_report``'s errors, and + See ``find_or_create_household_report``; raise its errors, and EconomyRecordOutcomeUnknownError when the commit fails after the - rows were inserted: they may exist. + rows were inserted. """ - self._create(lambda connection: insert_household_report(connection, report)) + return self._create( + lambda connection: find_or_create_household_report(connection, report) + ) - def create_report_rerun(self, rerun: NewHouseholdReportRerun) -> None: - """Create a stored report's new run and each side's new simulation run. + def create_report_rerun(self, rerun: NewHouseholdReportRerun) -> FoundReportRun: + """Join a stored report's run on the re-run's versions, or create it. - Raise ``insert_household_report_rerun``'s errors, and - EconomyRecordOutcomeUnknownError as ``create_report`` does. + See ``insert_household_report_rerun``; raise its errors, and + EconomyRecordOutcomeUnknownError as ``find_or_create_report`` does. """ - self._create( + return self._create( lambda connection: insert_household_report_rerun(connection, rerun) ) - def _create(self, insert_rows: Callable[[Connection], None]) -> None: - """Insert the rows in a transaction; tell a lost commit from a refusal.""" + def _create[Created](self, insert_rows: Callable[[Connection], Created]) -> Created: + """Insert the rows in a transaction; tell a lost commit from a refusal. + + Return what ``insert_rows`` returns. + """ inserted = False try: with self._transaction() as connection: - insert_rows(connection) + created = insert_rows(connection) inserted = True except SQLAlchemyError as error: if not inserted: raise msg = "the create's commit failed after its rows were inserted" raise EconomyRecordOutcomeUnknownError(msg) from error + return created def record_report_call( self, report_run_id: UUID, modal_call_id: str diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/keyed_economy_records.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/keyed_economy_records.py new file mode 100644 index 000000000..e5691ad30 --- /dev/null +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/keyed_economy_records.py @@ -0,0 +1,416 @@ +"""Find an economy report or simulation by key, with its run, or create them. + +Identical requests, together or apart, end on the same simulation, report +and run rows (C1 · 24), and only the request that inserted a run starts its +Modal call. A report's create runs, in one transaction: + +1. each side's simulation by its key (``definition_keys``), in key order, + so two transactions never wait for each other in opposite orders; two + sides with one key name one simulation; +2. the report by its key; +3. the report's run on the current versions that hasn't failed and wasn't + forced, pending, running or succeeded: when there is one, the request + joins it, with the simulation runs it names, and inserts nothing more; +4. otherwise, inside a savepoint, each distinct simulation's run on those + versions, catalog version and year that hasn't failed and wasn't forced, + found or inserted in simulation ID order, then the report run naming + them. A report run another request inserted after step 3 is joined, and + the savepoint takes back this request's simulation runs. + +Every simulation run counts whatever report first calculated it, pending, +running or succeeded: its stored plan no longer depends on the report +(answer 4), and a coordinator waits for a run another report run is +calculating (answer 5). Each lookup is ``shared_rows``'. A standalone +simulation is found or created by its key, with its run, the same way. +Rows keep random IDs (answer 1c): the IDs a request proposes are used only +for the rows it inserts. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any, Final, Literal + +from policyengine_simulation_persistence.definition_keys import KEY_VERSION +from policyengine_simulation_persistence.economy_run_records import ( + ECONOMY_REPORT_TYPE, + references_checked, + simulation_run_row, +) +from policyengine_simulation_persistence.shared_rows import ( + FoundReportRun, + FoundSimulationRun, + find_joinable_report_run, + find_or_insert_report, + find_or_insert_report_run, + find_or_insert_simulation, + find_or_insert_simulation_run, + find_or_insert_simulation_runs, +) +from policyengine_simulation_persistence.tables import ( + ReportRunStatus, + SimulationType, +) + +if TYPE_CHECKING: + from collections.abc import Mapping + from uuid import UUID + + from sqlalchemy import Connection + + from policyengine_simulation_persistence.definition_keys import ( + EconomyReportDefinition, + EconomySimulationDefinition, + ) + from policyengine_simulation_persistence.economy_run_records import ( + EconomyPopulation, + RunVersions, + ) + +# A report's two sides, the baseline first. +type Side = Literal["baseline", "reform"] +_SIDES: Final[tuple[Side, Side]] = ("baseline", "reform") + + +@dataclass(frozen=True) +class ProposedSide: + """The IDs a side's simulation and run get if this request inserts them.""" + + simulation_id: UUID + simulation_run_id: UUID + + +@dataclass(frozen=True) +class KeyedEconomyReport: + """An economy report a request names, found by key or created with its run. + + ``population`` is what its simulations' runs calculate on now: the + current catalog version's rows with the definition's dataset name and + region code. ``inputs`` is what ``reports.inputs`` stores: the SPM + selection when the request gave one, and no other option (answer 4). + No label, description, user or trigger is stored on the shared rows + (answer 6): each user's saved report and report-run record hold them. + """ + + definition: EconomyReportDefinition + report_id: UUID + run_id: UUID + baseline: ProposedSide + reform: ProposedSide + tax_benefit_model_id: UUID + population: EconomyPopulation + versions: RunVersions + inputs: dict[str, Any] + + +@dataclass(frozen=True) +class FoundSide: + """A report run's side: its simulation and run, and who inserted the run.""" + + simulation_id: UUID + simulation_run_id: UUID + run_inserted: bool + + @property + def reused(self) -> bool: + """Whether the run is one this request didn't insert, as answers say.""" + return not self.run_inserted + + +@dataclass(frozen=True) +class FoundEconomyReport: + """The report and run a request ended on, and what it inserted itself.""" + + report_id: UUID + report_inserted: bool + run: FoundReportRun + baseline: FoundSide + reform: FoundSide + + +@dataclass(frozen=True) +class KeyedEconomySimulation: + """A standalone economy simulation, found by key or created with its run.""" + + definition: EconomySimulationDefinition + simulation_id: UUID + run_id: UUID + population: EconomyPopulation + versions: RunVersions + + +@dataclass(frozen=True) +class FoundEconomySimulation: + """The simulation and run a request ended on, and what it inserted.""" + + simulation_id: UUID + simulation_inserted: bool + run: FoundSimulationRun + + +def find_or_create_economy_report( + connection: Connection, request: KeyedEconomyReport +) -> FoundEconomyReport: + """Find the report the request names, and its run, or create them. + + Raise EconomyRecordReferenceError when the database refuses a row an + insert names, and SharedRowNotSettledError when a run keeps failing + between a lookup's insert and its read; either ends the caller's + transaction, or its savepoint. + """ + with references_checked(): + simulation_ids = _find_or_insert_simulations(connection, request) + report = find_or_insert_report( + connection, + economy_report_row( + request.definition, + report_id=request.report_id, + tax_benefit_model_id=request.tax_benefit_model_id, + population=request.population, + inputs=request.inputs, + simulation_ids=simulation_ids, + ), + ) + versions = request.versions + joined = find_joinable_report_run( + connection, + report_id=report.id, + country_package_version=versions.country_package_version, + policyengine_version=versions.policyengine_version, + ) + if joined is not None: + return _found(report.id, report.inserted, joined, simulation_ids, set()) + proposed = {"baseline": request.baseline, "reform": request.reform} + run, runs = find_or_insert_report_run_on_sides( + connection, + _report_run_row(request, report.id), + { + side: simulation_run_row( + run_id=proposed[side].simulation_run_id, + simulation_id=simulation_ids[side], + population=request.population, + versions=request.versions, + ) + for side in _SIDES + }, + ) + inserted = {found.id for found in runs.values() if found.inserted} + return _found(report.id, report.inserted, run, simulation_ids, inserted) + + +def find_or_create_economy_simulation( + connection: Connection, request: KeyedEconomySimulation +) -> FoundEconomySimulation: + """Find the simulation the request names, and its run, or create them. + + Raise as ``find_or_create_economy_report`` does. + """ + with references_checked(): + simulation = find_or_insert_simulation( + connection, + economy_simulation_row( + request.definition, request.simulation_id, request.population + ), + ) + run = find_or_insert_simulation_run( + connection, + simulation_run_row( + run_id=request.run_id, + simulation_id=simulation.id, + population=request.population, + versions=request.versions, + ), + ) + return FoundEconomySimulation( + simulation_id=simulation.id, + simulation_inserted=simulation.inserted, + run=run, + ) + + +def _find_or_insert_simulations( + connection: Connection, request: KeyedEconomyReport +) -> dict[Side, UUID]: + """Return each side's simulation ID, found by key or inserted, in key order.""" + proposed = {"baseline": request.baseline, "reform": request.reform} + by_key: dict[str, list[Side]] = {} + for side in _SIDES: + key = request.definition.simulation(side).definition_key + by_key.setdefault(key, []).append(side) + simulation_ids: dict[Side, UUID] = {} + for key in sorted(by_key): + sides = by_key[key] + found = find_or_insert_simulation( + connection, + economy_simulation_row( + request.definition.simulation(sides[0]), + proposed[sides[0]].simulation_id, + request.population, + ), + ) + for side in sides: + simulation_ids[side] = found.id + return simulation_ids + + +def find_or_insert_report_run_on_sides( + connection: Connection, + report_run_row: Mapping[str, Any], + side_rows: Mapping[Side, Mapping[str, Any]], +) -> tuple[FoundReportRun, dict[Side, FoundSimulationRun]]: + """Find or insert each side's run, then the report run naming them. + + ``report_run_row`` is the report run as inserted, without its sides' + runs, and ``side_rows`` each side's run (``find_or_insert_side_runs``). + It runs in a savepoint: a report run another request inserted after the + caller looked for one is joined instead, and the savepoint takes back + this call's simulation runs. Return the report run, and each side's run + with whether this call inserted it; after a lost race nothing this call + inserted is kept, so no side run is returned (the joined report run + names its own). + """ + savepoint = connection.begin_nested() + try: + runs = find_or_insert_side_runs(connection, side_rows) + reform = runs.get("reform") + run = find_or_insert_report_run( + connection, + { + **report_run_row, + "baseline_simulation_run_id": runs["baseline"].id, + "reform_simulation_run_id": None if reform is None else reform.id, + }, + ) + except BaseException: + savepoint.rollback() + raise + if not run.inserted: + savepoint.rollback() + return run, {} + savepoint.commit() + return run, runs + + +def find_or_insert_side_runs( + connection: Connection, side_rows: Mapping[Side, Mapping[str, Any]] +) -> dict[Side, FoundSimulationRun]: + """Return each side's run of its simulation, found or inserted. + + ``side_rows`` holds each side's run as it would be inserted, with the + ID the side proposes: an economy run (``simulation_run_row``) or a + household one (``household_simulation_run_row``); a household report + of the baseline alone has no reform. Each distinct simulation's run on + the row's year, catalog version and versions that hasn't failed and + wasn't forced is found, or inserted, in simulation ID order + (``find_or_insert_simulation_runs``). One simulation on both sides gets + one run, with the baseline's proposed ID. Keyed reports' creates and + unforced re-runs name their sides' runs this way. + """ + rows = { + side_rows[side]["simulation_id"]: side_rows[side] + # The reform first, so one simulation on both sides keeps the + # baseline's proposed ID. + for side in reversed(_SIDES) + if side in side_rows + } + found = find_or_insert_simulation_runs(connection, rows) + return {side: found[row["simulation_id"]] for side, row in side_rows.items()} + + +def economy_simulation_row( + definition: EconomySimulationDefinition, + simulation_id: UUID, + population: EconomyPopulation, +) -> dict[str, Any]: + """Return a keyed economy simulation as inserted, on ``population``'s rows.""" + return { + "id": simulation_id, + "simulation_type": SimulationType.ECONOMY, + "dataset_id": population.dataset_id, + "household_id": None, + "policy_id": definition.choice.policy_id, + "dynamic_id": definition.choice.dynamic_id, + "tax_benefit_model_version_id": population.tax_benefit_model_version_id, + "region_id": population.region_id, + "year": definition.year, + "key_version": KEY_VERSION, + "definition_key": definition.definition_key, + } + + +def economy_report_row( # noqa: PLR0913 # the definition, then each column it doesn't name + definition: EconomyReportDefinition, + *, + report_id: UUID, + tax_benefit_model_id: UUID, + population: EconomyPopulation, + inputs: dict[str, Any], + simulation_ids: Mapping[Side, UUID], +) -> dict[str, Any]: + """Return a keyed economy report or budget window as inserted. + + It names its sides' simulations (a window's first year's), on + ``population``'s catalog rows (a window's first year's). + """ + return { + "id": report_id, + "country": definition.country, + "type": ECONOMY_REPORT_TYPE, + "tax_benefit_model_id": tax_benefit_model_id, + "policy_id": definition.reform.policy_id, + "baseline_simulation_id": simulation_ids["baseline"], + "reform_simulation_id": simulation_ids["reform"], + "household_id": None, + "dataset_id": population.dataset_id, + "region_id": population.region_id, + "year": definition.year, + "budget_window_size": definition.budget_window_size, + "inputs": inputs, + "key_version": KEY_VERSION, + "definition_key": definition.definition_key, + "dataset_independent_key": definition.dataset_independent_key, + } + + +def _report_run_row(request: KeyedEconomyReport, report_id: UUID) -> dict[str, Any]: + """Return the report's first run on these versions, without its sides' runs.""" + return { + "id": request.run_id, + "report_id": report_id, + "budget_window_run_id": None, + "year": None, + "country_package_version": request.versions.country_package_version, + "policyengine_version": request.versions.policyengine_version, + "status": ReportRunStatus.PENDING, + "modal_call_id": None, + } + + +def _found( + report_id: UUID, + report_inserted: bool, # noqa: FBT001 # the lookup's own flag, passed on + run: FoundReportRun, + simulation_ids: dict[Side, UUID], + inserted_run_ids: set[UUID], +) -> FoundEconomyReport: + """Return what the request ended on, with each side's simulation and run.""" + reform_run_id = run.reform_simulation_run_id + if reform_run_id is None: + msg = f"report run {run.id} of an economy report names no reform run" + raise ValueError(msg) + run_ids = {"baseline": run.baseline_simulation_run_id, "reform": reform_run_id} + sides = { + side: FoundSide( + simulation_id=simulation_ids[side], + simulation_run_id=run_ids[side], + run_inserted=run_ids[side] in inserted_run_ids, + ) + for side in _SIDES + } + return FoundEconomyReport( + report_id=report_id, + report_inserted=report_inserted, + run=run, + baseline=sides["baseline"], + reform=sides["reform"], + ) diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/keyed_household_records.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/keyed_household_records.py new file mode 100644 index 000000000..f8ec4bc4b --- /dev/null +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/keyed_household_records.py @@ -0,0 +1,269 @@ +"""Find a household report by key, with its run, or create them (answer 8). + +Identical household report requests, together or apart, end on the same +simulation, report and run rows, as economy ones do +(``keyed_economy_records``), and only the request that inserted a report +run starts its household function call. A report's create runs, in one +transaction: + +1. each side's household simulation by its key (``definition_keys``), in + key order; two sides with one key name one simulation; +2. the report by its key; +3. the report's run on the current versions that hasn't failed and wasn't + forced, pending, running or succeeded: when there is one, the request + joins it, with the simulation runs it names, and inserts nothing more; +4. otherwise, inside a savepoint, each distinct simulation's run on those + versions, catalog version and year that hasn't failed and wasn't forced, + found or inserted, then the report run naming them + (``find_or_insert_report_run_on_sides``). A report run another request + inserted after step 3 is joined, and the savepoint takes back this + request's simulation runs. + +A household simulation run may be another report run's, pending, running +or succeeded: the household function waits for a run another call holds +(C1 · 26). A report of the baseline alone has no reform side. Rows keep +random IDs: the IDs a request proposes are used only for the rows it +inserts. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any + +from policyengine_simulation_persistence.definition_keys import KEY_VERSION +from policyengine_simulation_persistence.economy_run_records import ( + references_checked, +) +from policyengine_simulation_persistence.household_report_records import ( + HOUSEHOLD_REPORT_TYPE, + household_simulation_run_row, +) +from policyengine_simulation_persistence.keyed_economy_records import ( + FoundSide, + ProposedSide, + Side, + find_or_insert_report_run_on_sides, +) +from policyengine_simulation_persistence.shared_rows import ( + FoundReportRun, + find_joinable_report_run, + find_or_insert_report, + find_or_insert_simulation, +) +from policyengine_simulation_persistence.tables import ( + ReportRunStatus, + SimulationType, +) + +if TYPE_CHECKING: + from uuid import UUID + + from sqlalchemy import Connection + + from policyengine_simulation_persistence.definition_keys import ( + HouseholdReportDefinition, + ) + from policyengine_simulation_persistence.economy_run_records import RunVersions + + +@dataclass(frozen=True) +class KeyedHouseholdReport: + """A household report a request names, found by key or created with its run. + + ``reform`` is None exactly when the definition has no reform (a report + of the baseline alone). The runs calculate on the catalog version + ``tax_benefit_model_version_id``. No label, description, user or + trigger is stored on the shared rows (answer 6). + """ + + definition: HouseholdReportDefinition + report_id: UUID + run_id: UUID + baseline: ProposedSide + reform: ProposedSide | None + tax_benefit_model_id: UUID + tax_benefit_model_version_id: UUID + versions: RunVersions + + def __post_init__(self) -> None: + """Refuse a reform side for a report without a reform, or none for one.""" + if (self.reform is None) != (self.definition.reform is None): + msg = "a household report proposes a reform side exactly when it has one" + raise ValueError(msg) + + @property + def proposed_sides(self) -> dict[Side, ProposedSide]: + """Return each side the report calculates and the IDs it proposes.""" + sides: dict[Side, ProposedSide] = {"baseline": self.baseline} + if self.reform is not None: + sides["reform"] = self.reform + return sides + + +@dataclass(frozen=True) +class FoundHouseholdReport: + """The household report and run a request ended on, and what it inserted. + + ``reform`` is None for a report of the baseline alone. + """ + + report_id: UUID + report_inserted: bool + run: FoundReportRun + baseline: FoundSide + reform: FoundSide | None + + +def find_or_create_household_report( + connection: Connection, request: KeyedHouseholdReport +) -> FoundHouseholdReport: + """Find the household report the request names, and its run, or create them. + + Raise EconomyRecordReferenceError when the database refuses a row an + insert names, and SharedRowNotSettledError when a run keeps failing + between a lookup's insert and its read; either ends the caller's + transaction, or its savepoint. + """ + with references_checked(): + simulation_ids = _find_or_insert_simulations(connection, request) + report = find_or_insert_report(connection, _report_row(request, simulation_ids)) + versions = request.versions + joined = find_joinable_report_run( + connection, + report_id=report.id, + country_package_version=versions.country_package_version, + policyengine_version=versions.policyengine_version, + ) + if joined is not None: + return _found(report.id, report.inserted, joined, simulation_ids, set()) + run, runs = find_or_insert_report_run_on_sides( + connection, + _report_run_row(request, report.id), + { + side: household_simulation_run_row( + run_id=proposed.simulation_run_id, + simulation_id=simulation_ids[side], + year=request.definition.year, + tax_benefit_model_version_id=request.tax_benefit_model_version_id, + versions=versions, + ) + for side, proposed in request.proposed_sides.items() + }, + ) + inserted = {found.id for found in runs.values() if found.inserted} + return _found(report.id, report.inserted, run, simulation_ids, inserted) + + +def _find_or_insert_simulations( + connection: Connection, request: KeyedHouseholdReport +) -> dict[Side, UUID]: + """Return each side's simulation ID, found by key or inserted, in key order.""" + definition = request.definition + proposed = request.proposed_sides + by_key: dict[str, list[Side]] = {} + for side in proposed: + by_key.setdefault(definition.simulation(side).definition_key, []).append(side) + simulation_ids: dict[Side, UUID] = {} + for key in sorted(by_key): + sides = by_key[key] + found = find_or_insert_simulation( + connection, + _simulation_row(request, sides[0], proposed[sides[0]].simulation_id), + ) + for side in sides: + simulation_ids[side] = found.id + return simulation_ids + + +def _simulation_row( + request: KeyedHouseholdReport, side: Side, simulation_id: UUID +) -> dict[str, Any]: + """Return a side's keyed household simulation as inserted.""" + simulation = request.definition.simulation(side) + return { + "id": simulation_id, + "simulation_type": SimulationType.HOUSEHOLD, + "dataset_id": None, + "household_id": simulation.household_id, + "policy_id": simulation.choice.policy_id, + "dynamic_id": simulation.choice.dynamic_id, + "tax_benefit_model_version_id": request.tax_benefit_model_version_id, + "region_id": None, + "year": simulation.year, + "key_version": KEY_VERSION, + "definition_key": simulation.definition_key, + } + + +def _report_row( + request: KeyedHouseholdReport, simulation_ids: dict[Side, UUID] +) -> dict[str, Any]: + """Return a keyed household report as inserted, naming its sides' simulations.""" + definition = request.definition + reform = definition.reform + return { + "id": request.report_id, + "country": definition.country, + "type": HOUSEHOLD_REPORT_TYPE, + "tax_benefit_model_id": request.tax_benefit_model_id, + "policy_id": None if reform is None else reform.policy_id, + "baseline_simulation_id": simulation_ids["baseline"], + "reform_simulation_id": simulation_ids.get("reform"), + "household_id": definition.household_id, + "dataset_id": None, + "region_id": None, + "year": definition.year, + "budget_window_size": None, + # A household report has no options; the column holds an object. + "inputs": {}, + "key_version": KEY_VERSION, + "definition_key": definition.definition_key, + "dataset_independent_key": definition.dataset_independent_key, + } + + +def _report_run_row(request: KeyedHouseholdReport, report_id: UUID) -> dict[str, Any]: + """Return the report's first run on these versions, without its sides' runs.""" + return { + "id": request.run_id, + "report_id": report_id, + "budget_window_run_id": None, + "year": None, + "country_package_version": request.versions.country_package_version, + "policyengine_version": request.versions.policyengine_version, + "status": ReportRunStatus.PENDING, + "modal_call_id": None, + } + + +def _found( + report_id: UUID, + report_inserted: bool, # noqa: FBT001 # the lookup's own flag, passed on + run: FoundReportRun, + simulation_ids: dict[Side, UUID], + inserted_run_ids: set[UUID], +) -> FoundHouseholdReport: + """Return what the request ended on, with each side's simulation and run.""" + run_ids: dict[Side, UUID | None] = { + "baseline": run.baseline_simulation_run_id, + "reform": run.reform_simulation_run_id, + } + sides: dict[Side, FoundSide] = {} + for side, simulation_id in simulation_ids.items(): + run_id = run_ids[side] + if run_id is None: + msg = f"report run {run.id} of a household report names no {side} run" + raise ValueError(msg) + sides[side] = FoundSide( + simulation_id=simulation_id, + simulation_run_id=run_id, + run_inserted=run_id in inserted_run_ids, + ) + return FoundHouseholdReport( + report_id=report_id, + report_inserted=report_inserted, + run=run, + baseline=sides["baseline"], + reform=sides.get("reform"), + ) diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/keyed_window_records.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/keyed_window_records.py new file mode 100644 index 000000000..9fbf98711 --- /dev/null +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/keyed_window_records.py @@ -0,0 +1,501 @@ +"""Find a budget window by key, with its window run, or create them (answer 8). + +A budget window compares the same baseline and reform in each year of a +window of 1 to 75 consecutive years. Identical window requests, together or +apart, end on the same report, simulations, window run and year runs, as +economy reports do (``keyed_economy_records``), and only the request that +inserted the window run starts its first years. A window's create runs, in +one transaction: + +1. each year's simulations by their keys (``definition_keys``, each of its + own year), in key order across every year; two sides with one key name + one simulation; +2. the report by its key, which holds the window's first year and size, + naming the first year's simulations; +3. the report's window run on the current catalog version and .py version + that hasn't failed and isn't a recalculation: when there is one, the + request joins it, with its year runs, and inserts nothing more; +4. otherwise the window run, recording its .py version, against the Public + API's window run index (``find_or_insert_window_run``), so a request + inserting one another request has inserted waits for it and joins it; + then each distinct simulation's run on those versions, catalog version + and year that hasn't failed and wasn't forced, found or inserted in + simulation ID order, and each year's report run naming them. + +A year's simulation run may be a single-year report's, or another window's, +pending, running or succeeded (answers 4 and 5). Rows keep random IDs: the +IDs a request proposes are used only for the rows it inserts. No per-user +column is written (answer 6). +""" + +from __future__ import annotations + +from dataclasses import dataclass, replace +from typing import TYPE_CHECKING, Any + +from sqlalchemy import insert, select + +from policyengine_simulation_persistence.budget_window_records import ( + check_window_years, +) +from policyengine_simulation_persistence.economy_run_records import ( + insert_simulation_run, + references_checked, + simulation_run_row, +) +from policyengine_simulation_persistence.keyed_economy_records import ( + FoundSide, + ProposedSide, + Side, + economy_report_row, + economy_simulation_row, +) +from policyengine_simulation_persistence.shared_rows import ( + FoundWindowRun, + find_joinable_window_run, + find_or_insert_report, + find_or_insert_simulation, + find_or_insert_simulation_runs, + find_or_insert_window_run, +) +from policyengine_simulation_persistence.tables import ( + ReportRunStatus, + report_runs, +) + +if TYPE_CHECKING: + from collections.abc import Sequence + from uuid import UUID + + from sqlalchemy import Connection + + from policyengine_simulation_persistence.definition_keys import ( + EconomyReportDefinition, + ) + from policyengine_simulation_persistence.economy_run_records import ( + EconomyPopulation, + RunVersions, + ) + +# A window year's side: its year and the side's name. +type YearSide = tuple[int, Side] +_SIDE_NAMES: tuple[Side, Side] = ("baseline", "reform") + + +@dataclass(frozen=True) +class WindowYearToInsert: + """A window year to insert: its report run and each side's simulation. + + ``proposed_run_ids`` are the IDs each side's run gets if it is inserted. + """ + + year: int + report_run_id: UUID + simulation_ids: dict[Side, UUID] + proposed_run_ids: dict[Side, UUID] + + +@dataclass(frozen=True) +class KeyedWindowYear: + """A year a window request names: the IDs its rows get if it inserts them.""" + + year: int + report_run_id: UUID + baseline: ProposedSide + reform: ProposedSide + + +@dataclass(frozen=True) +class KeyedBudgetWindow: + """A budget window a request names, found by key or created with its run. + + ``definition`` is the window's report: its first year, its size and the + sides and options every year shares. ``population`` is the first + year's, on the current catalog version; each year calculates on the + same catalog version, region and dataset in its own year. ``inputs`` is + what ``reports.inputs`` stores (the SPM selection, answer 4). ``years`` + runs from the first year, one at a time. + """ + + definition: EconomyReportDefinition + report_id: UUID + window_run_id: UUID + tax_benefit_model_id: UUID + population: EconomyPopulation + versions: RunVersions + inputs: dict[str, Any] + years: tuple[KeyedWindowYear, ...] + + def __post_init__(self) -> None: + """Refuse years that aren't the definition's, 1 to 75 from its first.""" + check_window_years(self.population.year, [year.year for year in self.years]) + if (self.definition.year, self.definition.budget_window_size) != ( + self.population.year, + len(self.years), + ): + msg = "a window's definition names its first year and its length" + raise ValueError(msg) + + def population_in(self, year: int) -> EconomyPopulation: + """Return what the window's simulations of ``year`` calculate on.""" + return replace(self.population, year=year) + + +@dataclass(frozen=True) +class FoundWindowYear: + """A year of the window run a request ended on: its report run and sides. + + Each side's ``run_inserted`` says whether this request inserted the + run; a joined window's years inserted none. + """ + + year: int + report_run_id: UUID + baseline: FoundSide + reform: FoundSide + + +@dataclass(frozen=True) +class FoundBudgetWindow: + """The window report and window run a request ended on, and its years.""" + + report_id: UUID + report_inserted: bool + window_run: FoundWindowRun + years: tuple[FoundWindowYear, ...] + + +def find_or_create_budget_window( + connection: Connection, request: KeyedBudgetWindow +) -> FoundBudgetWindow: + """Find the window the request names, and its window run, or create them. + + Raise EconomyRecordReferenceError when the database refuses a row an + insert names, and SharedRowNotSettledError when a run keeps failing + between a lookup's insert and its read; either ends the caller's + transaction, or its savepoint. + """ + with references_checked(): + simulation_ids = _find_or_insert_simulations(connection, request) + first_year = request.years[0].year + report = find_or_insert_report( + connection, + economy_report_row( + request.definition, + report_id=request.report_id, + tax_benefit_model_id=request.tax_benefit_model_id, + population=request.population, + inputs=request.inputs, + simulation_ids={ + side: simulation_ids[first_year, side] + for side in ("baseline", "reform") + }, + ), + ) + versions = request.versions + joined = find_joinable_window_run( + connection, + report_id=report.id, + tax_benefit_model_version_id=request.population.tax_benefit_model_version_id, + policyengine_version=versions.policyengine_version, + ) + if joined is None: + # The window run first: a request inserting one another request + # has inserted waits for it, then joins it with its year runs. + window_run = find_or_insert_window_run( + connection, + window_run_row( + run_id=request.window_run_id, + report_id=report.id, + population=request.population, + versions=versions, + recalculate=False, + ), + ) + if window_run.inserted: + years = insert_window_years( + connection, + _years_to_insert(request, simulation_ids), + report_id=report.id, + window_run_id=request.window_run_id, + population=request.population, + versions=versions, + forced=False, + ) + return FoundBudgetWindow( + report_id=report.id, + report_inserted=report.inserted, + window_run=window_run, + years=years, + ) + joined = window_run + return FoundBudgetWindow( + report_id=report.id, + report_inserted=report.inserted, + window_run=joined, + years=stored_window_years(connection, joined.id, simulation_ids), + ) + + +def window_run_row( + *, + run_id: UUID, + report_id: UUID, + population: EconomyPopulation, + versions: RunVersions, + recalculate: bool, +) -> dict[str, Any]: + """Return a window's new run as inserted, pending, with its .py version. + + ``recalculate`` marks a forced re-run's, which nothing joins. It names + no trigger: each user's report-run record holds it (answer 6). + """ + return { + "id": run_id, + "report_id": report_id, + "tax_benefit_model_version_id": population.tax_benefit_model_version_id, + "policyengine_version": versions.policyengine_version, + "recalculate": recalculate, + "status": ReportRunStatus.PENDING, + } + + +def window_year_run_row( # noqa: PLR0913 # the year's run, then what it calculates on + *, + run_id: UUID, + report_id: UUID, + window_run_id: UUID, + year: int, + side_runs: dict[Side, UUID], + versions: RunVersions, + forced: bool, +) -> dict[str, Any]: + """Return a window year's report run as inserted, pending with no call.""" + return { + "id": run_id, + "report_id": report_id, + "baseline_simulation_run_id": side_runs["baseline"], + "reform_simulation_run_id": side_runs["reform"], + "budget_window_run_id": window_run_id, + "year": year, + "country_package_version": versions.country_package_version, + "policyengine_version": versions.policyengine_version, + "status": ReportRunStatus.PENDING, + "modal_call_id": None, + "forced": forced, + } + + +def _find_or_insert_simulations( + connection: Connection, request: KeyedBudgetWindow +) -> dict[YearSide, UUID]: + """Return each year's sides' simulation IDs, found by key or inserted. + + In key order across every year, so two transactions never wait for each + other in opposite orders; two sides with one key name one simulation. + """ + proposed: dict[YearSide, ProposedSide] = {} + by_key: dict[str, list[YearSide]] = {} + for window_year in request.years: + for side, side_ids in _sides(window_year, reform_first=False): + year_side: YearSide = (window_year.year, side) + proposed[year_side] = side_ids + key = request.definition.simulation(side, year=window_year.year) + by_key.setdefault(key.definition_key, []).append(year_side) + simulation_ids: dict[YearSide, UUID] = {} + for key in sorted(by_key): + year_sides = by_key[key] + year, side = year_sides[0] + found = find_or_insert_simulation( + connection, + economy_simulation_row( + request.definition.simulation(side, year=year), + proposed[year, side].simulation_id, + request.population_in(year), + ), + ) + for year_side in year_sides: + simulation_ids[year_side] = found.id + return simulation_ids + + +def insert_window_years( # noqa: PLR0913 # the years, then the window they belong to + connection: Connection, + years: Sequence[WindowYearToInsert], + *, + report_id: UUID, + window_run_id: UUID, + population: EconomyPopulation, + versions: RunVersions, + forced: bool, +) -> tuple[FoundWindowYear, ...]: + """Name each year's side runs, then insert each year's report run, pending. + + Unforced, each distinct simulation's run on ``versions`` and its year's + catalog rows (``population`` is the first year's) that hasn't failed + and wasn't forced is found, or inserted with its side's proposed ID, in + simulation ID order; one simulation on both sides of a year gets one + run. Forced, each side gets a new run, marked forced like the year's + report run. A keyed window's create and every window re-run share this. + """ + if forced: + for window_year in years: + for side in _SIDE_NAMES: + insert_simulation_run( + connection, + run_id=window_year.proposed_run_ids[side], + simulation_id=window_year.simulation_ids[side], + population=replace(population, year=window_year.year), + versions=versions, + forced=True, + ) + found_years = tuple( + _found_year( + window_year, + { + side: (window_year.proposed_run_ids[side], True) + for side in _SIDE_NAMES + }, + ) + for window_year in years + ) + else: + rows: dict[UUID, dict[str, Any]] = {} + for window_year in years: + # The reform first, so one simulation on both sides keeps the + # baseline's proposed ID. + for side in reversed(_SIDE_NAMES): + simulation_id = window_year.simulation_ids[side] + rows[simulation_id] = simulation_run_row( + run_id=window_year.proposed_run_ids[side], + simulation_id=simulation_id, + population=replace(population, year=window_year.year), + versions=versions, + ) + runs = find_or_insert_simulation_runs(connection, rows) + found_years = tuple( + _found_year( + window_year, + { + side: ( + runs[window_year.simulation_ids[side]].id, + runs[window_year.simulation_ids[side]].inserted, + ) + for side in _SIDE_NAMES + }, + ) + for window_year in years + ) + connection.execute( + insert(report_runs), + [ + window_year_run_row( + run_id=year.report_run_id, + report_id=report_id, + window_run_id=window_run_id, + year=year.year, + side_runs={ + "baseline": year.baseline.simulation_run_id, + "reform": year.reform.simulation_run_id, + }, + versions=versions, + forced=forced, + ) + for year in found_years + ], + ) + return found_years + + +def _found_year( + window_year: WindowYearToInsert, side_runs: dict[Side, tuple[UUID, bool]] +) -> FoundWindowYear: + """Return a year as inserted, naming each side's run and who inserted it.""" + sides = { + side: FoundSide( + simulation_id=window_year.simulation_ids[side], + simulation_run_id=side_runs[side][0], + run_inserted=side_runs[side][1], + ) + for side in _SIDE_NAMES + } + return FoundWindowYear( + year=window_year.year, + report_run_id=window_year.report_run_id, + baseline=sides["baseline"], + reform=sides["reform"], + ) + + +def _sides( + window_year: KeyedWindowYear, *, reform_first: bool +) -> tuple[tuple[Side, ProposedSide], ...]: + """Return the year's sides by name, the baseline's first unless asked.""" + sides: tuple[tuple[Side, ProposedSide], ...] = ( + ("baseline", window_year.baseline), + ("reform", window_year.reform), + ) + return sides[::-1] if reform_first else sides + + +def _years_to_insert( + request: KeyedBudgetWindow, simulation_ids: dict[YearSide, UUID] +) -> tuple[WindowYearToInsert, ...]: + """Return the request's years on the simulations their keys found.""" + return tuple( + WindowYearToInsert( + year=window_year.year, + report_run_id=window_year.report_run_id, + simulation_ids={ + side: simulation_ids[window_year.year, side] for side in _SIDE_NAMES + }, + proposed_run_ids={ + side: side_ids.simulation_run_id + for side, side_ids in _sides(window_year, reform_first=False) + }, + ) + for window_year in request.years + ) + + +def stored_window_years( + connection: Connection, + window_run_id: UUID, + simulation_ids: dict[YearSide, UUID], +) -> tuple[FoundWindowYear, ...]: + """Return a window run's years, as its year runs name them, none inserted now. + + Raise ValueError when its years aren't the request's: a window run of + one report always has them. + """ + rows = connection.execute( + select( + report_runs.c.id, + report_runs.c.year, + report_runs.c.baseline_simulation_run_id, + report_runs.c.reform_simulation_run_id, + ) + .where(report_runs.c.budget_window_run_id == window_run_id) + .order_by(report_runs.c.year) + ).all() + requested = sorted({year for year, _ in simulation_ids}) + if [row.year for row in rows] != requested: + msg = f"window run {window_run_id} has other years than its report's" + raise ValueError(msg) + return tuple( + FoundWindowYear( + year=row.year, + report_run_id=row.id, + baseline=FoundSide( + simulation_id=simulation_ids[row.year, "baseline"], + simulation_run_id=row.baseline_simulation_run_id, + run_inserted=False, + ), + reform=FoundSide( + simulation_id=simulation_ids[row.year, "reform"], + simulation_run_id=row.reform_simulation_run_id, + run_inserted=False, + ), + ) + for row in rows + ) diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/rerun_definitions.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/rerun_definitions.py new file mode 100644 index 000000000..af0f332c4 --- /dev/null +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/rerun_definitions.py @@ -0,0 +1,302 @@ +"""What a stored report or simulation calculates, as a re-run reads it. + +A re-run (``economy_rerun_records``) first reads the stored record's kind, +country, year, region code, dataset name and each simulation's policy and +dynamic, so the current catalog version's rows with the same code and name +can be found, and, for a budget window, its newest calculation's years. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any, Literal + +from sqlalchemy import select + +from policyengine_simulation_persistence.economy_run_records import ( + ECONOMY_REPORT_TYPE, + SimulationChoice, +) +from policyengine_simulation_persistence.household_report_records import ( + HOUSEHOLD_REPORT_TYPE, +) +from policyengine_simulation_persistence.input_tables import ( + MODEL_NAME_PREFIX, + datasets, + regions, + tax_benefit_model_versions, + tax_benefit_models, +) +from policyengine_simulation_persistence.tables import ( + SimulationType, + budget_window_runs, + report_runs, + reports, + simulation_runs, + simulations, +) + +if TYPE_CHECKING: + from uuid import UUID + + from sqlalchemy import Connection, RowMapping + +# What a stored report or simulation calculates, as a re-run tells them apart: +# a single-year economy report or simulation, a budget window, a household +# report or simulation, or anything else, such as a simulation of a filtered +# population. +type RecordKind = Literal["economy", "budget_window", "household", "unsupported"] + + +@dataclass(frozen=True) +class SideDefinition: + """A report side's stored simulation, and its policy and dynamic.""" + + simulation_id: UUID + choice: SimulationChoice + + +@dataclass(frozen=True) +class WindowYearDefinition: + """One year of a budget window's newest calculation, and its sides' simulations. + + They are the simulations of the runs that year's report run names: a + year that joined another report's run names that run's simulation. + """ + + year: int + baseline_simulation_id: UUID + reform_simulation_id: UUID + + +@dataclass(frozen=True) +class ReportDefinition: + """What a stored report calculates, as a re-run reads it. + + ``region_code`` and ``dataset_name`` are the code and name of the + report's region and dataset, or None when the report names none (or a + row it named was deleted). ``baseline`` and ``reform`` are None when the + report names no such simulation; a budget window's are its first + year's. A budget window's ``window_years`` are the years of its newest + budget-window run whose report run names both sides, earliest first, + empty when it has none. ``household_id`` is a household report's stored + household, None for any other report. + """ + + id: UUID + country: str + kind: RecordKind + year: int | None + region_code: str | None + dataset_name: str | None + inputs: dict[str, Any] + baseline: SideDefinition | None + reform: SideDefinition | None + budget_window_size: int | None = None + window_years: tuple[WindowYearDefinition, ...] = () + household_id: UUID | None = None + # Whether the report was created by key (C1 · 27): its simulations' runs + # are then shared, whatever report first calculated them. + keyed: bool = False + + +@dataclass(frozen=True) +class SimulationDefinition: + """What a stored simulation calculates, as a re-run reads it. + + ``country`` comes from the simulation's catalog version's model; it is + None for a model the service does not name ``policyengine-``. + """ + + id: UUID + country: str | None + kind: RecordKind + year: int | None + region_code: str | None + dataset_name: str | None + choice: SimulationChoice + + +def read_report_definition( + connection: Connection, report_id: UUID +) -> ReportDefinition | None: + """Return what the stored report calculates, or None when there is none.""" + region = regions.alias("report_region") + dataset = datasets.alias("report_dataset") + baseline = simulations.alias("baseline_simulation") + reform = simulations.alias("reform_simulation") + row = ( + connection.execute( + select( + reports.c.id, + reports.c.country, + reports.c.type, + reports.c.household_id, + reports.c.budget_window_size, + reports.c.year, + reports.c.inputs, + reports.c.key_version, + region.c.code.label("region_code"), + dataset.c.name.label("dataset_name"), + baseline.c.id.label("baseline_id"), + baseline.c.policy_id.label("baseline_policy_id"), + baseline.c.dynamic_id.label("baseline_dynamic_id"), + reform.c.id.label("reform_id"), + reform.c.policy_id.label("reform_policy_id"), + reform.c.dynamic_id.label("reform_dynamic_id"), + ) + .select_from(reports) + .outerjoin(region, region.c.id == reports.c.region_id) + .outerjoin(dataset, dataset.c.id == reports.c.dataset_id) + .outerjoin(baseline, baseline.c.id == reports.c.baseline_simulation_id) + .outerjoin(reform, reform.c.id == reports.c.reform_simulation_id) + .where(reports.c.id == report_id) + ) + .mappings() + .one_or_none() + ) + if row is None: + return None + kind = _report_kind(row["type"], row["household_id"], row["budget_window_size"]) + return ReportDefinition( + id=row["id"], + country=row["country"], + kind=kind, + year=row["year"], + region_code=row["region_code"], + dataset_name=row["dataset_name"], + inputs=row["inputs"], + baseline=_side(row, "baseline"), + reform=_side(row, "reform"), + budget_window_size=row["budget_window_size"], + window_years=( + _window_years(connection, report_id) if kind == "budget_window" else () + ), + household_id=row["household_id"], + keyed=row["key_version"] is not None, + ) + + +def _window_years( + connection: Connection, report_id: UUID +) -> tuple[WindowYearDefinition, ...]: + """Return the years of the report's newest budget-window run, earliest first. + + A year whose report run names no reform is left out. + """ + newest_window_run = ( + select(budget_window_runs.c.id) + .where(budget_window_runs.c.report_id == report_id) + .order_by( + budget_window_runs.c.created_at.desc(), budget_window_runs.c.id.desc() + ) + .limit(1) + .scalar_subquery() + ) + baseline_run = simulation_runs.alias("baseline_run") + reform_run = simulation_runs.alias("reform_run") + rows = connection.execute( + select( + report_runs.c.year, + baseline_run.c.simulation_id.label("baseline_simulation_id"), + reform_run.c.simulation_id.label("reform_simulation_id"), + ) + .join( + baseline_run, baseline_run.c.id == report_runs.c.baseline_simulation_run_id + ) + .join(reform_run, reform_run.c.id == report_runs.c.reform_simulation_run_id) + .where(report_runs.c.budget_window_run_id == newest_window_run) + .order_by(report_runs.c.year) + ) + return tuple( + WindowYearDefinition( + year=row.year, + baseline_simulation_id=row.baseline_simulation_id, + reform_simulation_id=row.reform_simulation_id, + ) + for row in rows + ) + + +def _report_kind( + report_type: str | None, household_id: UUID | None, budget_window_size: int | None +) -> RecordKind: + if household_id is not None or report_type == HOUSEHOLD_REPORT_TYPE: + return "household" + if report_type != ECONOMY_REPORT_TYPE: + return "unsupported" + return "economy" if budget_window_size is None else "budget_window" + + +def _side( + row: RowMapping, side: Literal["baseline", "reform"] +) -> SideDefinition | None: + simulation_id = row[f"{side}_id"] + if simulation_id is None: + return None + return SideDefinition( + simulation_id=simulation_id, + choice=SimulationChoice( + policy_id=row[f"{side}_policy_id"], dynamic_id=row[f"{side}_dynamic_id"] + ), + ) + + +def read_simulation_definition( + connection: Connection, simulation_id: UUID +) -> SimulationDefinition | None: + """Return what the stored simulation calculates, or None when there is none.""" + row = ( + connection.execute( + select( + simulations.c.id, + simulations.c.simulation_type, + simulations.c.filter_field, + simulations.c.year, + simulations.c.policy_id, + simulations.c.dynamic_id, + tax_benefit_models.c.name.label("model_name"), + regions.c.code.label("region_code"), + datasets.c.name.label("dataset_name"), + ) + .select_from(simulations) + .join( + tax_benefit_model_versions, + tax_benefit_model_versions.c.id + == simulations.c.tax_benefit_model_version_id, + ) + .join( + tax_benefit_models, + tax_benefit_models.c.id == tax_benefit_model_versions.c.model_id, + ) + .outerjoin(regions, regions.c.id == simulations.c.region_id) + .outerjoin(datasets, datasets.c.id == simulations.c.dataset_id) + .where(simulations.c.id == simulation_id) + ) + .mappings() + .one_or_none() + ) + if row is None: + return None + model_name: str = row["model_name"] + simulation_type = SimulationType(row["simulation_type"]) + kind: RecordKind = ( + "household" + if simulation_type is SimulationType.HOUSEHOLD + else "economy" + if row["filter_field"] is None + else "unsupported" + ) + return SimulationDefinition( + id=row["id"], + country=model_name.removeprefix(MODEL_NAME_PREFIX) + if model_name.startswith(MODEL_NAME_PREFIX) + else None, + kind=kind, + year=row["year"], + region_code=row["region_code"], + dataset_name=row["dataset_name"], + choice=SimulationChoice( + policy_id=row["policy_id"], dynamic_id=row["dynamic_id"] + ), + ) diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/shared_rows.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/shared_rows.py new file mode 100644 index 000000000..7cf2ff7da --- /dev/null +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/shared_rows.py @@ -0,0 +1,380 @@ +"""Find a shared simulation, report or run, or insert it: one lookup each. + +Identical requests share simulations, reports and runs (C1 · 24). Each +lookup here is one ``INSERT … ON CONFLICT DO NOTHING`` against the Public +API's unique index for the row's definition or version set, followed, when +the insert did nothing, by a read of the row that won: + +- a simulation or a report by ``(key_version, definition_key)``; +- a simulation run by simulation, year, catalog version, country package + version and .py version, among runs that haven't failed and weren't forced; +- a report run by report, country package version and .py version, the + same way, outside budget windows, whose year runs no index covers; +- a budget-window run by report, catalog version and .py version, among + window runs that haven't failed and aren't recalculations (answer 8). + +Under READ COMMITTED an insert that conflicts with another transaction's +uncommitted row waits until that transaction ends. Once it commits, the +insert does nothing and the read, which takes a new snapshot, sees the row, +so concurrent identical requests end on one row. A run read as missing +after its insert did nothing has failed in between, which makes it a run +nobody joins (answer 2), so the insert is tried again. + +A forced re-run's runs are inserted directly, marked ``forced``: no index +covers them, so they never conflict, never join and are never joined +(answer 3). Callers choose the transactions, and insert rows in one order +(definitions by key, runs by simulation ID), so two transactions never wait +for each other in opposite orders. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any, Final + +from sqlalchemy import select +from sqlalchemy.dialects.postgresql import insert as postgresql_insert + +from policyengine_simulation_persistence.tables import ( + ReportRunStatus, + SimulationStatus, + budget_window_runs, + report_runs, + reports, + simulation_runs, + simulations, +) + +if TYPE_CHECKING: + from collections.abc import Mapping, Sequence + from uuid import UUID + + from sqlalchemy import ColumnElement, Connection, Row, Table + +# How many times a lookup inserts before giving up on a row that keeps +# failing between its insert and its read. +INSERT_ATTEMPTS: Final = 3 +_DEFINITION_COLUMNS: Final = ("key_version", "definition_key") + + +class SharedRowNotSettledError(RuntimeError): + """A run kept failing between a lookup's insert and its read. + + Nothing was inserted; the caller's transaction may go on or end. + """ + + +@dataclass(frozen=True) +class FoundRow: + """A row a lookup found, or inserted itself (``inserted``).""" + + id: UUID + inserted: bool + + +@dataclass(frozen=True) +class FoundSimulationRun: + """A simulation run a lookup found or inserted, with its status.""" + + id: UUID + inserted: bool + status: SimulationStatus + + +@dataclass(frozen=True) +class FoundReportRun: + """A report run a lookup found or inserted, with its status and pair.""" + + id: UUID + inserted: bool + status: ReportRunStatus + baseline_simulation_run_id: UUID + reform_simulation_run_id: UUID | None + + +@dataclass(frozen=True) +class FoundWindowRun: + """A budget-window run a lookup found or inserted, with its status.""" + + id: UUID + inserted: bool + status: ReportRunStatus + + +@dataclass(frozen=True) +class _UniqueIndex: + """A unique index a lookup inserts against: its columns and condition.""" + + table: Table + columns: tuple[str, ...] + # The partial index's predicate, as the model declares it; None for a + # unique constraint over the whole table. + where: ColumnElement[bool] | None + # The same predicate in SQLAlchemy terms, for the read. + read_conditions: tuple[ColumnElement[bool], ...] + + +def _partial_index( + table: Table, name: str, read_conditions: tuple[ColumnElement[bool], ...] +) -> _UniqueIndex: + """Return the model's partial unique index ``name``, with its own predicate.""" + (index,) = (index for index in table.indexes if index.name == name) + return _UniqueIndex( + table=table, + columns=tuple(column.name for column in index.columns), + where=index.dialect_options["postgresql"]["where"], + read_conditions=read_conditions, + ) + + +_SIMULATION_DEFINITION: Final = _UniqueIndex( + table=simulations, columns=_DEFINITION_COLUMNS, where=None, read_conditions=() +) +_REPORT_DEFINITION: Final = _UniqueIndex( + table=reports, columns=_DEFINITION_COLUMNS, where=None, read_conditions=() +) +_JOINABLE_SIMULATION_RUN: Final = _partial_index( + simulation_runs, + "uq_simulation_runs_unfailed_unforced_versions", + ( + simulation_runs.c.status != SimulationStatus.FAILED, + simulation_runs.c.forced.is_(False), + ), +) +_JOINABLE_REPORT_RUN: Final = _partial_index( + report_runs, + "uq_report_runs_unfailed_unforced_versions", + ( + report_runs.c.budget_window_run_id.is_(None), + report_runs.c.status != ReportRunStatus.FAILED, + report_runs.c.forced.is_(False), + ), +) + + +def find_or_insert_simulation( + connection: Connection, values: Mapping[str, Any] +) -> FoundRow: + """Return the simulation with ``values``' key, inserting ``values`` if none. + + ``values`` is the whole row, its ``key_version`` and ``definition_key`` + included. + """ + row, inserted = _find_or_insert(connection, _SIMULATION_DEFINITION, values, ()) + return FoundRow(id=row.id, inserted=inserted) + + +def find_or_insert_report( + connection: Connection, values: Mapping[str, Any] +) -> FoundRow: + """Return the report with ``values``' key, inserting ``values`` if none. + + ``values`` is the whole row, its three key columns included. + """ + row, inserted = _find_or_insert(connection, _REPORT_DEFINITION, values, ()) + return FoundRow(id=row.id, inserted=inserted) + + +def find_or_insert_simulation_run( + connection: Connection, values: Mapping[str, Any] +) -> FoundSimulationRun: + """Return the simulation's joinable run on ``values``' versions, or insert it. + + A joinable run hasn't failed and wasn't forced. ``values`` is the whole + row; a forced run is never looked up (ValueError): insert it directly. + """ + _refuse_forced(values) + row, inserted = _find_or_insert( + connection, _JOINABLE_SIMULATION_RUN, values, (simulation_runs.c.status,) + ) + return FoundSimulationRun( + id=row.id, inserted=inserted, status=SimulationStatus(row.status) + ) + + +def find_or_insert_simulation_runs( + connection: Connection, rows: Mapping[UUID, Mapping[str, Any]] +) -> dict[UUID, FoundSimulationRun]: + """Return each simulation's joinable run, by simulation ID, or insert ``rows``. + + ``rows`` maps each simulation's ID to its run as it would be inserted. + The lookups go in simulation ID order, so two transactions never wait + for each other in opposite orders. + """ + return { + simulation_id: find_or_insert_simulation_run(connection, rows[simulation_id]) + for simulation_id in sorted(rows) + } + + +_JOINABLE_WINDOW_RUN: Final = _partial_index( + budget_window_runs, + "uq_budget_window_runs_unfailed_unforced_versions", + ( + budget_window_runs.c.status != ReportRunStatus.FAILED, + budget_window_runs.c.recalculate.is_(False), + ), +) + + +def find_or_insert_window_run( + connection: Connection, values: Mapping[str, Any] +) -> FoundWindowRun: + """Return the report's joinable window run on ``values``' versions, or insert it. + + A joinable window run hasn't failed and isn't a recalculation, a forced + re-run's, which is never looked up (ValueError). ``values`` is the + whole row, its ``policyengine_version`` included. + """ + if values.get("recalculate"): + msg = "a recalculating window run is inserted directly: nothing joins it" + raise ValueError(msg) + row, inserted = _find_or_insert( + connection, _JOINABLE_WINDOW_RUN, values, (budget_window_runs.c.status,) + ) + return FoundWindowRun( + id=row.id, inserted=inserted, status=ReportRunStatus(row.status) + ) + + +def find_joinable_window_run( + connection: Connection, + *, + report_id: UUID, + tax_benefit_model_version_id: UUID, + policyengine_version: str, +) -> FoundWindowRun | None: + """Return the report's joinable window run on these versions, or None. + + The one ``find_or_insert_window_run`` would join. A window run created + before C1 · 27 records no .py version, so it is never joined. + """ + row = connection.execute( + select(budget_window_runs.c.id, budget_window_runs.c.status).where( + budget_window_runs.c.report_id == report_id, + budget_window_runs.c.tax_benefit_model_version_id + == tax_benefit_model_version_id, + budget_window_runs.c.policyengine_version == policyengine_version, + *_JOINABLE_WINDOW_RUN.read_conditions, + ) + ).one_or_none() + if row is None: + return None + return FoundWindowRun(id=row.id, inserted=False, status=ReportRunStatus(row.status)) + + +def find_or_insert_report_run( + connection: Connection, values: Mapping[str, Any] +) -> FoundReportRun: + """Return the report's joinable run on ``values``' versions, or insert it. + + A joinable run hasn't failed and wasn't forced. ``values`` is the whole + row. A forced run, or a budget window's year run, which no index covers, + is never looked up (ValueError). + """ + _refuse_forced(values) + if values.get("budget_window_run_id") is not None: + msg = "a budget window's year runs are never looked up by versions" + raise ValueError(msg) + row, inserted = _find_or_insert( + connection, + _JOINABLE_REPORT_RUN, + values, + ( + report_runs.c.status, + report_runs.c.baseline_simulation_run_id, + report_runs.c.reform_simulation_run_id, + ), + ) + return FoundReportRun( + id=row.id, + inserted=inserted, + status=ReportRunStatus(row.status), + baseline_simulation_run_id=row.baseline_simulation_run_id, + reform_simulation_run_id=row.reform_simulation_run_id, + ) + + +def find_joinable_report_run( + connection: Connection, + *, + report_id: UUID, + country_package_version: str, + policyengine_version: str, +) -> FoundReportRun | None: + """Return the report's joinable run on these versions, or None. + + The run hasn't failed, wasn't forced, and is no budget window's year + run: the one ``find_or_insert_report_run`` would join. + """ + row = connection.execute( + select( + report_runs.c.id, + report_runs.c.status, + report_runs.c.baseline_simulation_run_id, + report_runs.c.reform_simulation_run_id, + ).where( + report_runs.c.report_id == report_id, + report_runs.c.country_package_version == country_package_version, + report_runs.c.policyengine_version == policyengine_version, + *_JOINABLE_REPORT_RUN.read_conditions, + ) + ).one_or_none() + if row is None: + return None + return FoundReportRun( + id=row.id, + inserted=False, + status=ReportRunStatus(row.status), + baseline_simulation_run_id=row.baseline_simulation_run_id, + reform_simulation_run_id=row.reform_simulation_run_id, + ) + + +def _refuse_forced(values: Mapping[str, Any]) -> None: + if values.get("forced"): + msg = "a forced run is inserted directly: it never joins or is joined" + raise ValueError(msg) + + +def _find_or_insert( + connection: Connection, + index: _UniqueIndex, + values: Mapping[str, Any], + returned: Sequence[ColumnElement[Any]], +) -> tuple[Row[Any], bool]: + """Insert ``values`` unless ``index`` holds a row like it; return the row. + + Return the row (its ID, then ``returned``) and whether this call + inserted it. Raise ValueError when ``values`` lacks a column of the + index, and SharedRowNotSettledError when the row that won keeps failing + before it is read. + """ + missing = [name for name in index.columns if values.get(name) is None] + if missing: + msg = f"the row names no {', '.join(missing)}, which find it" + raise ValueError(msg) + table = index.table + columns = (table.c.id, *returned) + statement = ( + postgresql_insert(table) + .values(dict(values)) + .on_conflict_do_nothing(index_elements=index.columns, index_where=index.where) + .returning(*columns) + ) + winner = select(*columns).where( + *(table.c[name] == values[name] for name in index.columns), + *index.read_conditions, + ) + for _attempt in range(INSERT_ATTEMPTS): + inserted = connection.execute(statement).one_or_none() + if inserted is not None: + return inserted, True + found = connection.execute(winner).one_or_none() + if found is not None: + return found, False + msg = ( + f"the {table.name} row that won kept failing before it was read, " + f"{INSERT_ATTEMPTS} times" + ) + raise SharedRowNotSettledError(msg) diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/tables.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/tables.py index ac6caf05f..7e5822411 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/tables.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/tables.py @@ -38,6 +38,7 @@ Text, UniqueConstraint, Uuid, + false, text, ) from sqlalchemy.dialects.postgresql import JSONB @@ -53,6 +54,8 @@ MODAL_CALL_ID_LENGTH: Final = 255 OUTPUT_URI_LENGTH: Final = 2048 SHA256_LENGTH: Final = 64 +# A definition key is a SHA-256 in lowercase hexadecimal. +DEFINITION_KEY_LENGTH: Final = 64 class SimulationType(StrEnum): @@ -135,6 +138,42 @@ def _terminal_completion(table_name: str) -> CheckConstraint: ) +def _key_columns(*names: str) -> tuple[Column[int] | Column[str], ...]: + """Return ``key_version`` and each named key column, nullable. + + A row created before the keys existed has none of them, and is never + found by key. + """ + return ( + Column("key_version", Integer, nullable=True), + *(Column(name, String(DEFINITION_KEY_LENGTH), nullable=True) for name in names), + ) + + +def _key_checks(table_name: str, *names: str) -> tuple[CheckConstraint, ...]: + """Require a positive key version, and each key in lowercase hexadecimal. + + The checks are the Public API's, under its names; ``names`` are the key + columns. + """ + return ( + CheckConstraint("key_version > 0", name=f"ck_{table_name}_key_version"), + *( + CheckConstraint( + f"length({name}) = {DEFINITION_KEY_LENGTH} AND " + f"ltrim({name}, '0123456789abcdef') = ''", + name=f"ck_{table_name}_{name}", + ) + for name in names + ), + ) + + +def _forced_column() -> Column[bool]: + """Return the marker of a forced re-run's run, which nothing joins.""" + return Column("forced", Boolean, nullable=False, server_default=false()) + + def _year_between(table_name: str, *, nullable: bool) -> CheckConstraint: condition = f"year BETWEEN 1900 AND {LATEST_YEAR}" if nullable: @@ -207,6 +246,7 @@ def _public_api_key( Column("filter_value", String(255), nullable=True), Column("filter_strategy", String(64), nullable=True), Column("year", Integer, nullable=True), + *_key_columns("definition_key"), PrimaryKeyConstraint("id", name="pk_simulations"), _public_api_key( "dataset_id", @@ -256,6 +296,17 @@ def _public_api_key( name="ck_simulations_type_input", ), _year_between("simulations", nullable=True), + *_key_checks("simulations", "definition_key"), + CheckConstraint( + "(key_version IS NULL) = (definition_key IS NULL)", + name="ck_simulations_keys_complete", + ), + # Find-or-create's conflict target: one simulation per definition. + UniqueConstraint( + "key_version", + "definition_key", + name="uq_simulations_key_version_definition_key", + ), Index( "ix_simulations_tax_benefit_model_version_id", "tax_benefit_model_version_id", @@ -268,7 +319,9 @@ def _public_api_key( _identifier(), _timestamp("created_at", server_now=True), _timestamp("updated_at", server_now=True), - Column("label", String(255), nullable=False), + # Per-user columns the service no longer writes (C1 · 24's answer 6): a + # report's name and description live on each user's saved report. + Column("label", String(255), nullable=True), Column("description", String, nullable=True), Column("country", String(16), nullable=False), Column("type", String(128), nullable=True), @@ -284,6 +337,7 @@ def _public_api_key( Column("inputs", JSON, nullable=False), # The number of years from ``year`` an economy report's window covers. Column("budget_window_size", Integer, nullable=True), + *_key_columns("definition_key", "dataset_independent_key"), PrimaryKeyConstraint("id", name="pk_reports"), _public_api_key( "user_id", "users", ondelete="SET NULL", name="fk_reports_user_id_users" @@ -337,6 +391,21 @@ def _public_api_key( name="ck_reports_budget_window_size", ), _year_between("reports", nullable=True), + *_key_checks("reports", "definition_key", "dataset_independent_key"), + CheckConstraint( + "(key_version IS NULL) = (definition_key IS NULL) AND " + "(key_version IS NULL) = (dataset_independent_key IS NULL)", + name="ck_reports_keys_complete", + ), + # Find-or-create's conflict target: one report per definition. + UniqueConstraint( + "key_version", + "definition_key", + name="uq_reports_key_version_definition_key", + ), + # Reports that differ only in their dataset share this key, by which + # the app finds one from the other. + Index("ix_reports_dataset_independent_key", "dataset_independent_key"), Index("ix_reports_country_type_created_at", "country", "type", "created_at"), Index("ix_reports_tax_benefit_model_id", "tax_benefit_model_id"), # Deleting a user sets its reports' user_id to null. @@ -369,6 +438,7 @@ def _public_api_key( Column("household_result", JSON, nullable=True), Column("output_uri", String(OUTPUT_URI_LENGTH), nullable=True), Column("output_sha256", String(SHA256_LENGTH), nullable=True), + _forced_column(), PrimaryKeyConstraint("id", name="pk_simulation_runs"), _public_api_key( "tax_benefit_model_version_id", @@ -415,6 +485,19 @@ def _public_api_key( "id", ), Index("ix_simulation_runs_status_started_at", "status", "started_at"), + # One run that hasn't failed per simulation, year, catalog version and + # versions, apart from forced re-runs' runs: find-or-create's conflict + # target, so identical requests join one run. + Index( + "uq_simulation_runs_unfailed_unforced_versions", + "simulation_id", + "year", + "tax_benefit_model_version_id", + "country_package_version", + "policyengine_version", + unique=True, + postgresql_where=text("status <> 'failed' AND NOT forced"), + ), Index( "ix_simulation_runs_tax_benefit_model_version_id", "tax_benefit_model_version_id", @@ -430,11 +513,16 @@ def _public_api_key( _timestamp("updated_at", server_now=True), Column("report_id", Uuid, nullable=False), Column("tax_benefit_model_version_id", Uuid, nullable=False), + # The .py version the window calculates on, so a window run is found by + # its report and version set (answer 8); null on runs before C1 · 27. + Column("policyengine_version", String(128), nullable=True), + # Per-request, so the service no longer writes it (answer 6). Column( "trigger", _enum_type(ReportRunTrigger, "v2_report_run_trigger"), - nullable=False, + nullable=True, ), + # The window's forced marker: a recalculating run is never joined. Column("recalculate", Boolean, nullable=False), Column( "status", @@ -470,6 +558,16 @@ def _public_api_key( "ix_budget_window_runs_tax_benefit_model_version_id", "tax_benefit_model_version_id", ), + # One window run that hasn't failed and wasn't forced per report and + # version set: find-or-create's conflict target for a window (answer 8). + Index( + "uq_budget_window_runs_unfailed_unforced_versions", + "report_id", + "tax_benefit_model_version_id", + "policyengine_version", + unique=True, + postgresql_where=text("status <> 'failed' AND NOT recalculate"), + ), ) report_runs = Table( @@ -486,10 +584,11 @@ def _public_api_key( _enum_type(ReportRunStatus, "v2_report_run_status"), nullable=False, ), + # Per-request, so the service no longer writes it (answer 6). Column( "trigger", _enum_type(ReportRunTrigger, "v2_report_run_trigger"), - nullable=False, + nullable=True, ), Column("idempotency_key", Uuid, nullable=True), _timestamp("started_at"), @@ -511,6 +610,7 @@ def _public_api_key( Column("reform_cliff_share", Float, nullable=True), Column("spm_provenance", JSONB, nullable=True), Column("data_version", String(VERSION_LENGTH), nullable=True), + _forced_column(), PrimaryKeyConstraint("id", name="pk_report_runs"), ForeignKeyConstraint( ["report_id"], @@ -573,6 +673,19 @@ def _public_api_key( "id", ), Index("ix_report_runs_status_started_at", "status", "started_at"), + # One run that hasn't failed per report and versions, apart from forced + # re-runs' runs and a budget window's years: find-or-create's conflict + # target. + Index( + "uq_report_runs_unfailed_unforced_versions", + "report_id", + "country_package_version", + "policyengine_version", + unique=True, + postgresql_where=text( + "budget_window_run_id IS NULL AND status <> 'failed' AND NOT forced" + ), + ), Index( "ix_report_runs_baseline_simulation_run_id", "baseline_simulation_run_id", diff --git a/libs/policyengine-simulation-persistence/tests/committed_rows.py b/libs/policyengine-simulation-persistence/tests/committed_rows.py new file mode 100644 index 000000000..7efca4731 --- /dev/null +++ b/libs/policyengine-simulation-persistence/tests/committed_rows.py @@ -0,0 +1,110 @@ +"""Rows and threads for a test of two transactions. + +Most tests run in one transaction rolled back afterwards. A test of two +transactions needs rows each can see, so ``conftest``'s ``committed_catalog`` +commits a catalog of a country no other test uses, and deletes it here, with +every row naming it, afterwards. Such a test runs each transaction in a +thread (``run_together``) and lets the first go on only once the second +waits for its rows (``wait_until_another_backend_waits_for``). +""" + +from __future__ import annotations + +import threading +import time +from typing import TYPE_CHECKING + +from sqlalchemy import text + +if TYPE_CHECKING: + from collections.abc import Callable + + from economy_rows import EconomyCatalog + from sqlalchemy import Connection, Engine + + +def delete_catalog_rows(connection: Connection, economy: EconomyCatalog) -> None: + """Delete every row of the catalog and the rows naming it, as the superuser.""" + parameters = { + "model_id": economy.catalog.model_id, + "version_id": economy.catalog.version_id, + } + for statement in ( + "DELETE FROM public.report_runs WHERE report_id IN " + "(SELECT id FROM public.reports WHERE tax_benefit_model_id = :model_id)", + "DELETE FROM public.budget_window_runs WHERE report_id IN " + "(SELECT id FROM public.reports WHERE tax_benefit_model_id = :model_id)", + "DELETE FROM public.reports WHERE tax_benefit_model_id = :model_id", + "DELETE FROM public.simulation_runs " + "WHERE tax_benefit_model_version_id = :version_id", + "DELETE FROM public.simulations " + "WHERE tax_benefit_model_version_id = :version_id", + "DELETE FROM public.regions WHERE tax_benefit_model_version_id = :version_id", + "DELETE FROM public.datasets WHERE tax_benefit_model_version_id = :version_id", + "DELETE FROM public.tax_benefit_model_versions WHERE id = :version_id", + "DELETE FROM public.tax_benefit_models WHERE id = :model_id", + ): + connection.execute(text(statement), parameters) + + +# How long a test waits for another transaction's lock or thread. +LOCK_WAIT_TIMEOUT_SECONDS = 10.0 + + +def wait_until_another_backend_waits_for(engine: Engine, holder_pid: int) -> str: + """Return, once a backend waits for a lock ``holder_pid`` holds, its statement. + + The statement is read in a transaction of its own once a waiting + backend's pid is found: the view's copy of every backend's status is + taken when the first read starts, a moment before ``pg_blocking_pids`` + runs. + """ + deadline = time.monotonic() + LOCK_WAIT_TIMEOUT_SECONDS + with engine.connect() as connection: + while time.monotonic() < deadline: + waiting_pid = connection.execute( + text( + "SELECT pid FROM pg_stat_activity " + "WHERE :holder_pid = ANY(pg_blocking_pids(pid)) LIMIT 1" + ), + {"holder_pid": holder_pid}, + ).scalar_one_or_none() + connection.rollback() + if waiting_pid is not None: + statement = connection.execute( + text("SELECT query FROM pg_stat_activity WHERE pid = :pid"), + {"pid": waiting_pid}, + ).scalar_one() + connection.rollback() + return statement + time.sleep(0.05) + msg = "the second request never waited for the first one's rows" + raise AssertionError(msg) + + +def run_together( + works: tuple[Callable[[], None], ...], *, released: threading.Event +) -> None: + """Run each in its own thread, wait for all, and re-raise the first error. + + A failing one sets ``released``, so no other waits on it for long. + """ + errors: list[BaseException] = [] + + def recording_errors(work: Callable[[], None]) -> Callable[[], None]: + def run() -> None: + try: + work() + except BaseException as error: # noqa: BLE001 # re-raised below + errors.append(error) + released.set() + + return run + + threads = [threading.Thread(target=recording_errors(work)) for work in works] + for thread in threads: + thread.start() + for thread in threads: + thread.join(LOCK_WAIT_TIMEOUT_SECONDS * 2) + if errors: + raise errors[0] diff --git a/libs/policyengine-simulation-persistence/tests/conftest.py b/libs/policyengine-simulation-persistence/tests/conftest.py index 328c731b3..5a0fd71da 100644 --- a/libs/policyengine-simulation-persistence/tests/conftest.py +++ b/libs/policyengine-simulation-persistence/tests/conftest.py @@ -24,6 +24,8 @@ from uuid import uuid4 import pytest +from committed_rows import delete_catalog_rows +from economy_rows import insert_economy_catalog from policyengine_simulation_persistence import create_simulation_engine from sqlalchemy import create_engine, text from sqlalchemy.engine import URL, make_url @@ -31,7 +33,8 @@ if TYPE_CHECKING: from collections.abc import Iterator - from sqlalchemy import Connection + from economy_rows import EconomyCatalog + from sqlalchemy import Connection, Engine DATABASE_URL_VARIABLE = "SIMULATION_TEST_DATABASE_URL" REQUIRE_DATABASE_VARIABLE = "SIMULATION_REQUIRE_DATABASE_TESTS" @@ -146,3 +149,25 @@ def connection_as_the_service(database_url: str) -> Iterator[Connection]: with rolled_back_transaction(database_url) as connection: act_as_the_service(connection) yield connection + + +@pytest.fixture +def committed_engine(public_api_database_url) -> Iterator[Engine]: + """Return an engine on the Public API's database, disposed afterwards.""" + engine = create_simulation_engine(public_api_database_url) + try: + yield engine + finally: + engine.dispose() + + +@pytest.fixture +def committed_catalog(committed_engine) -> Iterator[EconomyCatalog]: + """Commit a catalog of a country no other test uses; delete its rows after.""" + with committed_engine.begin() as connection: + economy = insert_economy_catalog(connection, country=f"zz{uuid4().hex[:8]}") + try: + yield economy + finally: + with committed_engine.begin() as connection: + delete_catalog_rows(connection, economy) diff --git a/libs/policyengine-simulation-persistence/tests/economy_rows.py b/libs/policyengine-simulation-persistence/tests/economy_rows.py index b203b6aea..517487ebf 100644 --- a/libs/policyengine-simulation-persistence/tests/economy_rows.py +++ b/libs/policyengine-simulation-persistence/tests/economy_rows.py @@ -1,9 +1,10 @@ """Rows for the economy simulation and report tests. The catalog rows a request names are the Public API's, inserted as the -superuser. A run that already succeeded, and the report run that used it, are -written as the superuser too, through the service tables' models: the -service's role can neither mark a run succeeded nor record its output. +superuser. A stored simulation, report and their runs are written as the +superuser too, through the service tables' models: the service's role can +neither mark a run succeeded nor record its output. None of them has a +definition key, as a record the service created before keys has none. """ from __future__ import annotations @@ -146,15 +147,14 @@ class StoredRun: class RunShape: """What a stored economy simulation and its run hold. - A succeeded run records an output file in the output bucket unless - ``output_uri`` names another. + A succeeded run records an output file in the output bucket. ``forced`` + marks a forced re-run's run. """ choice: SimulationChoice = CURRENT_LAW status: SimulationStatus = SimulationStatus.SUCCEEDED versions: RunVersions = VERSIONS - output_uri: str | None = None - completed_at: datetime = COMPLETED_AT + forced: bool = False def insert_simulation_run( @@ -205,13 +205,12 @@ def insert_run_of( dataset_id=population.dataset_id, region_id=population.region_id, status=shape.status, - completed_at=shape.completed_at if finished else None, + completed_at=COMPLETED_AT if finished else None, output_uri=( - (shape.output_uri or f"{OUTPUT_BUCKET_PREFIX}outputs/{run_id}.parquet") - if succeeded - else None + f"{OUTPUT_BUCKET_PREFIX}outputs/{run_id}.parquet" if succeeded else None ), output_sha256="d" * 64 if succeeded else None, + forced=shape.forced, ) ) return StoredRun(simulation_id=simulation_id, simulation_run_id=run_id) @@ -219,11 +218,13 @@ def insert_run_of( @dataclass(frozen=True) class ReportRunOutcome: - """How a stored report run ended, and the options its report has.""" + """How a stored report run ended, its versions and trigger, and its options.""" status: ReportRunStatus = ReportRunStatus.SUCCEEDED inputs: dict[str, Any] | None = None error_message: str | None = None + versions: RunVersions = VERSIONS + trigger: ReportRunTrigger = ReportRunTrigger.INITIAL def insert_report_run_naming( @@ -298,10 +299,10 @@ def insert_report_run_of( report_id=report_id, baseline_simulation_run_id=baseline.simulation_run_id, reform_simulation_run_id=reform.simulation_run_id, - country_package_version=COUNTRY_PACKAGE_VERSION, - policyengine_version=POLICYENGINE_VERSION, + country_package_version=outcome.versions.country_package_version, + policyengine_version=outcome.versions.policyengine_version, status=outcome.status, - trigger=ReportRunTrigger.INITIAL, + trigger=outcome.trigger, completed_at=COMPLETED_AT if finished else None, error_message=outcome.error_message, ) @@ -309,23 +310,43 @@ def insert_report_run_of( return run_id -def insert_reusable_run( - connection: Connection, - economy: EconomyCatalog, - shape: RunShape | None = None, - *, - inputs: dict[str, Any] | None = None, -) -> StoredRun: - """Insert a run shaped ``shape`` that a succeeded report run used, with ``inputs``. +@dataclass(frozen=True) +class PendingReport: + """A stored report whose first run, and both its new simulation runs, wait. - The report run's other simulation run failed, so it is never reusable. + Every run is ``pending`` with no Modal call ID, as the service left a + report it had just created. """ + + report_id: UUID + report_run_id: UUID + baseline: StoredRun + reform: StoredRun + + @property + def simulation_run_ids(self) -> tuple[UUID, UUID]: + """Return the baseline's simulation run, then the reform's.""" + return (self.baseline.simulation_run_id, self.reform.simulation_run_id) + + +def insert_pending_report( + connection: Connection, economy: EconomyCatalog +) -> PendingReport: + """Insert a current-law report and its first run, all runs pending.""" population = economy.population() - reused = insert_simulation_run(connection, population, shape) - other_side = insert_simulation_run( - connection, population, RunShape(status=SimulationStatus.FAILED) + pending = RunShape(status=SimulationStatus.PENDING) + baseline = insert_simulation_run(connection, population, pending) + reform = insert_simulation_run(connection, population, pending) + report_id = insert_report_of(connection, economy, (baseline, reform)) + report_run_id = insert_report_run_of( + connection, + report_id, + (baseline, reform), + ReportRunOutcome(status=ReportRunStatus.PENDING), ) - insert_report_run_naming( - connection, economy, (reused, other_side), ReportRunOutcome(inputs=inputs) + return PendingReport( + report_id=report_id, + report_run_id=report_run_id, + baseline=baseline, + reform=reform, ) - return reused diff --git a/libs/policyengine-simulation-persistence/tests/household_report_rows.py b/libs/policyengine-simulation-persistence/tests/household_report_rows.py new file mode 100644 index 000000000..1ceb62eb5 --- /dev/null +++ b/libs/policyengine-simulation-persistence/tests/household_report_rows.py @@ -0,0 +1,189 @@ +"""Household reports stored as the simulation service created them before keys. + +The service now finds or creates a household report by definition key +(``keyed_household_records``). A report it created before then has no key: +each side is a household simulation of its own with one run, the report +names the household, both simulations and the reform's policy, and its +first run has trigger ``initial``. Every run is ``pending`` with no Modal +call ID. ``insert_household_report_rows`` inserts such a report directly, +as whatever role the connection acts as. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any +from uuid import uuid4 + +from policyengine_simulation_persistence import ( + HOUSEHOLD_REPORT_TYPE, + ReportRunStatus, + ReportRunTrigger, + SimulationStatus, + SimulationType, + report_runs, + reports, + simulation_runs, + simulations, +) +from sqlalchemy import insert + +if TYPE_CHECKING: + from uuid import UUID + + from policyengine_simulation_persistence import RunVersions + from public_api_rows import CatalogVersion + from sqlalchemy import Connection + + +@dataclass(frozen=True) +class StoredHouseholdSide: + """One side of a stored household report: its simulation, run and policy. + + ``policy_id`` is the side's stored policy, or None for current law. + """ + + simulation_id: UUID + simulation_run_id: UUID + policy_id: UUID | None + + +@dataclass(frozen=True) +class StoredHouseholdReport: + """A stored household report and its first run. + + ``reform`` is None for a report of the baseline alone. + """ + + id: UUID + run_id: UUID + household_id: UUID + year: int + baseline: StoredHouseholdSide + reform: StoredHouseholdSide | None + + @property + def sides(self) -> tuple[StoredHouseholdSide, ...]: + """Return each side the report calculates, the baseline's first.""" + return (self.baseline,) if self.reform is None else (self.baseline, self.reform) + + @property + def simulation_run_ids(self) -> tuple[UUID, ...]: + """Return the IDs of the report's first simulation runs.""" + return tuple(side.simulation_run_id for side in self.sides) + + +def insert_household_report_rows( # noqa: PLR0913 # the report's catalog, household and sides + connection: Connection, + catalog: CatalogVersion, + *, + household_id: UUID, + year: int, + versions: RunVersions, + reform_policy_id: UUID | None = None, + with_reform: bool = True, +) -> StoredHouseholdReport: + """Insert a household report with no key, its simulations and its runs. + + The baseline is current law; with ``with_reform``, the reform has + ``reform_policy_id``, current law when it is None. + """ + report = StoredHouseholdReport( + id=uuid4(), + run_id=uuid4(), + household_id=household_id, + year=year, + baseline=StoredHouseholdSide( + simulation_id=uuid4(), simulation_run_id=uuid4(), policy_id=None + ), + reform=( + StoredHouseholdSide( + simulation_id=uuid4(), + simulation_run_id=uuid4(), + policy_id=reform_policy_id, + ) + if with_reform + else None + ), + ) + for side in report.sides: + connection.execute( + insert(simulations).values( + id=side.simulation_id, + simulation_type=SimulationType.HOUSEHOLD, + dataset_id=None, + household_id=household_id, + policy_id=side.policy_id, + dynamic_id=None, + tax_benefit_model_version_id=catalog.version_id, + region_id=None, + year=year, + ) + ) + connection.execute( + insert(simulation_runs).values( + _pending_run(side, catalog=catalog, year=year, versions=versions) + ) + ) + reform = report.reform + connection.execute( + insert(reports).values( + id=report.id, + label="A larger child tax credit", + description="For one family", + country=catalog.country, + type=HOUSEHOLD_REPORT_TYPE, + user_id=None, + tax_benefit_model_id=catalog.model_id, + policy_id=None if reform is None else reform.policy_id, + baseline_simulation_id=report.baseline.simulation_id, + reform_simulation_id=None if reform is None else reform.simulation_id, + household_id=household_id, + dataset_id=None, + region_id=None, + year=year, + budget_window_size=None, + inputs={}, + ) + ) + connection.execute( + insert(report_runs).values( + id=report.run_id, + report_id=report.id, + baseline_simulation_run_id=report.baseline.simulation_run_id, + reform_simulation_run_id=( + None if reform is None else reform.simulation_run_id + ), + budget_window_run_id=None, + year=None, + country_package_version=versions.country_package_version, + policyengine_version=versions.policyengine_version, + status=ReportRunStatus.PENDING, + trigger=ReportRunTrigger.INITIAL, + modal_call_id=None, + ) + ) + return report + + +def _pending_run( + side: StoredHouseholdSide, + *, + catalog: CatalogVersion, + year: int, + versions: RunVersions, +) -> dict[str, Any]: + """Return a side's household simulation run, pending with no Modal call ID.""" + return { + "id": side.simulation_run_id, + "simulation_id": side.simulation_id, + "year": year, + "tax_benefit_model_version_id": catalog.version_id, + "country_package_version": versions.country_package_version, + "policyengine_version": versions.policyengine_version, + "dataset_id": None, + "region_id": None, + "status": SimulationStatus.PENDING, + "modal_call_id": None, + "forced": False, + } diff --git a/libs/policyengine-simulation-persistence/tests/test_budget_window_records.py b/libs/policyengine-simulation-persistence/tests/test_budget_window_records.py index a08d4766f..43f912a5a 100644 --- a/libs/policyengine-simulation-persistence/tests/test_budget_window_records.py +++ b/libs/policyengine-simulation-persistence/tests/test_budget_window_records.py @@ -1,9 +1,8 @@ -"""A budget-window report's inputs and rows: one report run per year. +"""A budget-window report's inputs: its catalog rows and both sides' values. A budget window compares the same baseline and reform in each year of its -window. Each year has its own simulations, with that year, so a year can -reuse a single-year report's run, and the reverse. These run against a -database the Public API's own v2 migration chain built +window, so both sides' values are read once for every year. These run +against a database the Public API's own v2 migration chain built (``PUBLIC_API_SCHEMA_DATABASE_URL``), acting as the simulation service's role in a transaction the test rolls back. """ @@ -11,44 +10,22 @@ from __future__ import annotations from contextlib import contextmanager -from dataclasses import replace from datetime import UTC, datetime from typing import TYPE_CHECKING -from uuid import uuid4 import pytest from conftest import act_as_the_service, rolled_back_transaction -from economy_rows import ( - CURRENT_LAW, - OPTIONS, - OUTPUT_BUCKET_PREFIX, - POLICYENGINE_VERSION, - VERSIONS, - RunShape, - insert_economy_catalog, - insert_report_run_naming, - insert_simulation_run, -) +from economy_rows import CURRENT_LAW, POLICYENGINE_VERSION, insert_economy_catalog from policyengine_simulation_persistence import ( - BudgetWindowYear, - EconomyPopulation, - EconomyRecordReferenceError, EconomyRequest, EconomyRunStore, - NewBudgetWindowReport, - ReportSimulation, - ReusableRun, - RunReuse, SimulationChoice, - SimulationStatus, ) from public_api_rows import StoredValue, insert_policy -from sqlalchemy import text if TYPE_CHECKING: from collections.abc import Iterator - from economy_rows import EconomyCatalog from sqlalchemy import Connection pytestmark = pytest.mark.public_api_schema @@ -62,10 +39,6 @@ dataset_name=None, year=2026, ) -REUSE = RunReuse( - versions=VERSIONS, inputs=OPTIONS, output_uri_prefix=OUTPUT_BUCKET_PREFIX -) -WINDOW_YEARS = (2026, 2027, 2028) def _store_on(connection: Connection) -> EconomyRunStore: @@ -79,283 +52,22 @@ def savepoint() -> Iterator[Connection]: return EconomyRunStore(savepoint) -def _reusable_run_in(connection: Connection, economy: EconomyCatalog, year: int): - """Insert a succeeded current-law run of ``year`` that a report run used.""" - population = economy.population(year=year) - reused = insert_simulation_run(connection, population) - other_side = insert_simulation_run( - connection, population, RunShape(status=SimulationStatus.FAILED) - ) - insert_report_run_naming(connection, economy, (reused, other_side)) - return reused - - -def test_a_window_reads_each_year_s_reusable_runs(public_api_database_url) -> None: +def test_a_windows_catalog_rows_and_both_sides_values_are_read( + public_api_database_url, +) -> None: with rolled_back_transaction(public_api_database_url) as connection: economy = insert_economy_catalog(connection, parameter_names=(CTC_AMOUNT,)) policy_id = insert_policy( connection, economy.catalog, [StoredValue(CTC_AMOUNT, 3_000, START)] ) - reused_in_2027 = _reusable_run_in(connection, economy, 2027) act_as_the_service(connection) reform_choice = SimulationChoice(policy_id=policy_id, dynamic_id=None) inputs = _store_on(connection).read_budget_window_inputs( - REQUEST, - baseline=CURRENT_LAW, - reform=reform_choice, - reuse=REUSE, - years=WINDOW_YEARS, + REQUEST, baseline=CURRENT_LAW, reform=reform_choice ) assert inputs.catalog.catalog_version_id == economy.catalog.version_id assert (inputs.baseline.choice, inputs.baseline.reform) == (CURRENT_LAW, {}) assert inputs.reform.choice == reform_choice - assert inputs.reusable_runs == { - 2026: (None, None), - 2027: ( - ReusableRun( - simulation_id=reused_in_2027.simulation_id, - simulation_run_id=reused_in_2027.simulation_run_id, - ), - None, - ), - 2028: (None, None), - } - - -def test_a_window_reads_no_reusable_run_without_reuse(public_api_database_url) -> None: - with rolled_back_transaction(public_api_database_url) as connection: - economy = insert_economy_catalog(connection) - _reusable_run_in(connection, economy, 2027) - act_as_the_service(connection) - - inputs = _store_on(connection).read_budget_window_inputs( - REQUEST, - baseline=CURRENT_LAW, - reform=CURRENT_LAW, - reuse=None, - years=WINDOW_YEARS, - ) - - assert set(inputs.reusable_runs.values()) == {(None, None)} - - -def _new_side(choice: SimulationChoice = CURRENT_LAW) -> ReportSimulation: - return ReportSimulation( - simulation_id=uuid4(), simulation_run_id=uuid4(), choice=choice, reused=False - ) - - -def _window(economy: EconomyCatalog, reused_in_2027) -> NewBudgetWindowReport: - years = [] - for year in WINDOW_YEARS: - baseline = ( - ReportSimulation( - simulation_id=reused_in_2027.simulation_id, - simulation_run_id=reused_in_2027.simulation_run_id, - choice=CURRENT_LAW, - reused=True, - ) - if year == 2027 - else _new_side() - ) - years.append( - BudgetWindowYear( - year=year, - report_run_id=uuid4(), - baseline=baseline, - reform=_new_side(), - ) - ) - return NewBudgetWindowReport( - id=uuid4(), - window_run_id=uuid4(), - country="us", - label="Ten-year budget window", - description=None, - tax_benefit_model_id=economy.catalog.model_id, - population=economy.population(year=2026), - versions=VERSIONS, - inputs=OPTIONS, - years=tuple(years), - ) - - -def _rows(connection: Connection, table_name: str, **filters): - rows = connection.execute( - text( - f"SELECT * FROM {table_name} WHERE " # noqa: S608 # test-only names - + " AND ".join(f"{name} = :{name}" for name in filters) - ), - filters, - ) - return [dict(row._mapping) for row in rows] - - -def test_a_window_is_created_with_a_report_run_per_year( - public_api_database_url, -) -> None: - with rolled_back_transaction(public_api_database_url) as connection: - economy = insert_economy_catalog(connection) - reused_in_2027 = _reusable_run_in(connection, economy, 2027) - window = _window(economy, reused_in_2027) - act_as_the_service(connection) - - _store_on(connection).create_budget_window_report(window) - - connection.execute(text("RESET ROLE")) - (report,) = _rows(connection, "reports", id=window.id) - (window_run,) = _rows(connection, "budget_window_runs", id=window.window_run_id) - year_runs = { - row["year"]: row - for row in _rows( - connection, "report_runs", budget_window_run_id=window.window_run_id - ) - } - simulations = { - run_id: ( - _rows(connection, "simulation_runs", id=run_id)[0], - _rows( - connection, - "simulations", - id=_rows(connection, "simulation_runs", id=run_id)[0][ - "simulation_id" - ], - )[0], - ) - for year in window.years - for run_id in ( - year.baseline.simulation_run_id, - year.reform.simulation_run_id, - ) - } - - first_year = window.years[0] - assert ( - report["type"], - report["year"], - report["budget_window_size"], - report["inputs"], - report["baseline_simulation_id"], - report["reform_simulation_id"], - report["household_id"], - ) == ( - "economy", - 2026, - 3, - OPTIONS, - first_year.baseline.simulation_id, - first_year.reform.simulation_id, - None, - ) - assert ( - window_run["report_id"], - window_run["status"], - window_run["trigger"], - window_run["recalculate"], - window_run["tax_benefit_model_version_id"], - ) == (window.id, "pending", "initial", False, economy.catalog.version_id) - for year in window.years: - year_run = year_runs[year.year] - assert ( - year_run["id"], - year_run["report_id"], - year_run["status"], - year_run["trigger"], - year_run["modal_call_id"], - year_run["baseline_simulation_run_id"], - year_run["reform_simulation_run_id"], - year_run["country_package_version"], - year_run["policyengine_version"], - ) == ( - year.report_run_id, - window.id, - "pending", - "initial", - None, - year.baseline.simulation_run_id, - year.reform.simulation_run_id, - VERSIONS.country_package_version, - VERSIONS.policyengine_version, - ) - for side in (year.baseline, year.reform): - simulation_run, simulation = simulations[side.simulation_run_id] - # Each year has its own simulations, of that year. - assert (simulation["year"], simulation_run["year"]) == ( - year.year, - year.year, - ) - assert simulation_run["status"] == ( - "succeeded" if side.reused else "pending" - ) - - -def test_a_window_naming_a_missing_policy_is_refused_and_writes_nothing( - public_api_database_url, -) -> None: - with rolled_back_transaction(public_api_database_url) as connection: - economy = insert_economy_catalog(connection) - reused_in_2027 = _reusable_run_in(connection, economy, 2027) - window = _window(economy, reused_in_2027) - missing_policy = SimulationChoice(policy_id=uuid4(), dynamic_id=None) - last_year = window.years[-1] - window = replace( - window, - years=( - *window.years[:-1], - replace( - last_year, reform=replace(last_year.reform, choice=missing_policy) - ), - ), - ) - act_as_the_service(connection) - - with pytest.raises(EconomyRecordReferenceError) as refused: - _store_on(connection).create_budget_window_report(window) - - connection.execute(text("RESET ROLE")) - written = connection.execute( - text("SELECT count(*) FROM reports WHERE id = :id"), {"id": window.id} - ).scalar_one() - - assert (refused.value.table_name, refused.value.column_name) == ( - "simulations", - "policy_id", - ) - assert written == 0 - - -@pytest.mark.parametrize( - "years", - [(), (2026, 2028), tuple(range(2026, 2102))], - ids=["no-years", "a-gap", "76-years"], -) -def test_a_window_s_years_must_be_consecutive_from_its_first(years) -> None: - population = EconomyPopulation( - tax_benefit_model_version_id=uuid4(), - region_id=uuid4(), - dataset_id=uuid4(), - year=years[0] if years else 2026, - ) - with pytest.raises(ValueError, match="budget window"): - NewBudgetWindowReport( - id=uuid4(), - window_run_id=uuid4(), - country="us", - label="Window", - description=None, - tax_benefit_model_id=uuid4(), - population=population, - versions=VERSIONS, - inputs=OPTIONS, - years=tuple( - BudgetWindowYear( - year=year, - report_run_id=uuid4(), - baseline=_new_side(), - reform=_new_side(), - ) - for year in years - ), - ) + assert inputs.reform.reform == {CTC_AMOUNT: {"2026-01-01.2200-12-31": 3_000}} diff --git a/libs/policyengine-simulation-persistence/tests/test_definition_keys.py b/libs/policyengine-simulation-persistence/tests/test_definition_keys.py new file mode 100644 index 000000000..3382a3851 --- /dev/null +++ b/libs/policyengine-simulation-persistence/tests/test_definition_keys.py @@ -0,0 +1,331 @@ +"""Definition keys: the canonical JSON of what identifies a record, hashed.""" + +from __future__ import annotations + +import hashlib +from dataclasses import replace +from typing import Any +from uuid import UUID + +import pytest +from policyengine_simulation_persistence import ( + KEY_VERSION, + EconomyReportDefinition, + EconomySimulationDefinition, + HouseholdReportDefinition, + HouseholdSimulationDefinition, + SimulationChoice, + canonical_json, + definition_key, +) + +REFORM_POLICY_ID = UUID("11111111-2222-3333-4444-555555555555") +DYNAMIC_ID = UUID("99999999-8888-7777-6666-555555555555") +CURRENT_LAW = SimulationChoice(policy_id=None, dynamic_id=None) +REFORM_P = SimulationChoice(policy_id=REFORM_POLICY_ID, dynamic_id=None) +NATIONAL_DATASET = "microcosm_uk_2024_25" +LOCAL_AREA_DATASET = "microcosm_uk_2024_25_dense" +NATIONAL_SPM = {"geography_kind": "national"} + + +def _report_n(**changes: Any) -> EconomyReportDefinition: + """Return the proposal's report N: current law against reform P, UK, 2026.""" + report = EconomyReportDefinition( + country="uk", + baseline=CURRENT_LAW, + reform=REFORM_P, + dataset_name=NATIONAL_DATASET, + region_code="uk", + year=2026, + budget_window_size=None, + spm=None, + ) + return replace(report, **changes) + + +def _reform_p(**changes: Any) -> EconomySimulationDefinition: + """Return report N's reform simulation.""" + simulation = EconomySimulationDefinition( + country="uk", + choice=REFORM_P, + dataset_name=NATIONAL_DATASET, + region_code="uk", + year=2026, + spm=None, + ) + return replace(simulation, **changes) + + +def test_the_canonical_json_sorts_keys_with_no_spaces_and_keeps_utf_8() -> None: + definition = { + "region": "country/wales", + "label": "Région", + "policy_id": UUID("AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE"), + "missing": None, + "nested": {"b": 2, "a": [1, True]}, + } + + assert canonical_json(definition) == ( + '{"label":"Région","missing":null,"nested":{"a":[1,true],"b":2},' + '"policy_id":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee","region":"country/wales"}' + ) + + +def test_a_key_is_the_lowercase_sha_256_of_the_canonical_json() -> None: + definition = {"record": "report", "label": "Région"} + expected = hashlib.sha256(canonical_json(definition).encode("utf-8")).hexdigest() + + key = definition_key(definition) + + assert key == expected + assert len(key) == 64 + assert key == key.lower() + + +def test_a_number_json_cannot_write_exactly_is_refused() -> None: + with pytest.raises(ValueError, match="Out of range float"): + canonical_json({"value": float("nan")}) + + +def test_a_value_json_has_no_form_for_is_refused() -> None: + with pytest.raises(TypeError, match="set"): + canonical_json({"value": {1, 2}}) + + +def test_a_simulation_key_object_holds_everything_that_changes_its_numbers() -> None: + """Answer 1a, and 4c: the SPM selection, as given or absent, is in it.""" + assert KEY_VERSION == 1 + assert _reform_p().key_object() == { + "country": "uk", + "dataset": NATIONAL_DATASET, + "dynamic_id": None, + "filter": None, + "key_version": 1, + "policy_id": REFORM_POLICY_ID, + "record": "simulation", + "region": "uk", + "simulation_type": "economy", + "spm": None, + "year": 2026, + } + assert _reform_p().definition_key[:16] == "b989f3178d09e525" + + +def test_each_part_of_a_simulation_definition_changes_its_key() -> None: + variants = [ + _reform_p(), + _reform_p(country="us"), + _reform_p(choice=CURRENT_LAW), + _reform_p( + choice=SimulationChoice(policy_id=REFORM_POLICY_ID, dynamic_id=DYNAMIC_ID) + ), + _reform_p(dataset_name=LOCAL_AREA_DATASET), + _reform_p(region_code="country/wales"), + _reform_p(year=2027), + _reform_p(spm=NATIONAL_SPM), + _reform_p(spm={}), + ] + + assert len({variant.definition_key for variant in variants}) == len(variants) + + +def test_a_report_key_object_names_its_sides_and_what_they_share() -> None: + """Answer 4: a report has no options; the SPM selection is named once.""" + assert _report_n().key_object() == { + "baseline": {"dynamic_id": None, "policy_id": None}, + "budget_window_size": None, + "country": "uk", + "dataset": NATIONAL_DATASET, + "key_version": 1, + "record": "report", + "reform": {"dynamic_id": None, "policy_id": REFORM_POLICY_ID}, + "region": "uk", + "report_type": "economy", + "spm": None, + "year": 2026, + } + assert _report_n().definition_key[:16] == "1072f5d1cc18140f" + + +def test_each_part_of_a_report_definition_changes_its_key() -> None: + variants = [ + _report_n(), + _report_n(country="us"), + _report_n(dataset_name=LOCAL_AREA_DATASET), + _report_n(region_code="country/wales"), + _report_n(year=2027), + _report_n(budget_window_size=10), + _report_n(spm=NATIONAL_SPM), + _report_n(baseline=REFORM_P, reform=CURRENT_LAW), + _report_n( + reform=SimulationChoice(policy_id=REFORM_POLICY_ID, dynamic_id=DYNAMIC_ID) + ), + _report_n(baseline=SimulationChoice(policy_id=None, dynamic_id=DYNAMIC_ID)), + ] + + assert len({variant.definition_key for variant in variants}) == len(variants) + + +def test_a_reports_sides_are_the_simulations_its_definition_names() -> None: + """Each side shares the report's dataset, region, year and SPM selection.""" + report = _report_n(spm=NATIONAL_SPM) + + assert report.simulation("reform") == _reform_p(spm=NATIONAL_SPM) + assert report.simulation("baseline") == _reform_p( + choice=CURRENT_LAW, spm=NATIONAL_SPM + ) + # Current law against current law names one simulation on both sides. + same_policy = _report_n(reform=CURRENT_LAW) + assert ( + same_policy.simulation("baseline").definition_key + == same_policy.simulation("reform").definition_key + ) + + +def test_a_budget_window_years_simulations_are_of_that_year() -> None: + window = _report_n(budget_window_size=3) + + assert window.simulation("reform", year=2027) == _reform_p(year=2027) + + +def test_the_dataset_independent_key_is_the_report_key_without_its_dataset() -> None: + """Revised answer 1a and answer 4: the report key holds no options.""" + report_n = _report_n() + expected = { + name: value + for name, value in report_n.key_object().items() + if name != "dataset" + } + expected["record"] = "report_dataset_independent" + + assert report_n.dataset_independent_key_object() == expected + assert report_n.dataset_independent_key == definition_key(expected) + assert report_n.dataset_independent_key[:16] == "b2d140ad0201ada4" + + +def test_reports_differing_only_in_their_dataset_share_that_key() -> None: + national = _report_n() + local_area = _report_n(dataset_name=LOCAL_AREA_DATASET) + other_spm = _report_n(dataset_name=LOCAL_AREA_DATASET, spm=NATIONAL_SPM) + other_region = _report_n( + dataset_name=LOCAL_AREA_DATASET, region_code="country/wales" + ) + + assert national.dataset_independent_key == local_area.dataset_independent_key + assert national.definition_key != local_area.definition_key + assert other_spm.dataset_independent_key != national.dataset_independent_key + assert other_region.dataset_independent_key != national.dataset_independent_key + + +HOUSEHOLD_ID = UUID("33333333-4444-5555-6666-777777777777") + + +def _household_report(**changes: Any) -> HouseholdReportDefinition: + """Return a household report: current law against reform P, US, 2026.""" + report = HouseholdReportDefinition( + country="us", + baseline=CURRENT_LAW, + reform=REFORM_P, + household_id=HOUSEHOLD_ID, + year=2026, + ) + return replace(report, **changes) + + +def _household_reform(**changes: Any) -> HouseholdSimulationDefinition: + """Return that household report's reform simulation.""" + simulation = HouseholdSimulationDefinition( + country="us", choice=REFORM_P, household_id=HOUSEHOLD_ID, year=2026 + ) + return replace(simulation, **changes) + + +def test_a_household_simulation_key_names_its_household_for_dataset_and_region() -> ( + None +): + """Answers 1a and 8: a household simulation is keyed by its household's ID.""" + assert _household_reform().key_object() == { + "country": "us", + "dynamic_id": None, + "filter": None, + "household_id": HOUSEHOLD_ID, + "key_version": 1, + "policy_id": REFORM_POLICY_ID, + "record": "simulation", + "simulation_type": "household", + "year": 2026, + } + assert _household_reform().definition_key[:16] == "18d9f70b8310de76" + + +def test_each_part_of_a_household_simulation_definition_changes_its_key() -> None: + variants = [ + _household_reform(), + _household_reform(country="uk"), + _household_reform(choice=CURRENT_LAW), + _household_reform( + choice=SimulationChoice(policy_id=REFORM_POLICY_ID, dynamic_id=DYNAMIC_ID) + ), + _household_reform(household_id=UUID(int=1)), + _household_reform(year=2027), + ] + + assert len({variant.definition_key for variant in variants}) == len(variants) + + +def test_a_household_report_key_names_its_sides_household_and_year() -> None: + """A report of the baseline alone names no reform.""" + assert _household_report().key_object() == { + "baseline": {"dynamic_id": None, "policy_id": None}, + "budget_window_size": None, + "country": "us", + "household_id": HOUSEHOLD_ID, + "key_version": 1, + "record": "report", + "reform": {"dynamic_id": None, "policy_id": REFORM_POLICY_ID}, + "report_type": "household", + "year": 2026, + } + assert _household_report(reform=None).key_object()["reform"] is None + assert _household_report().definition_key[:16] == "4b769456e6d9b01a" + + +def test_each_part_of_a_household_report_definition_changes_its_key() -> None: + variants = [ + _household_report(), + _household_report(country="uk"), + _household_report(baseline=REFORM_P, reform=CURRENT_LAW), + _household_report(reform=None), + _household_report(reform=CURRENT_LAW), + _household_report(household_id=UUID(int=1)), + _household_report(year=2027), + ] + + assert len({variant.definition_key for variant in variants}) == len(variants) + + +def test_a_household_reports_dataset_independent_key_has_its_own_record_name() -> None: + """A household report has no dataset, so only the record name differs.""" + report = _household_report() + expected = {**report.key_object(), "record": "report_dataset_independent"} + + assert report.dataset_independent_key_object() == expected + assert report.dataset_independent_key == definition_key(expected) + assert report.dataset_independent_key != report.definition_key + + +def test_a_household_reports_sides_are_the_simulations_it_names() -> None: + report = _household_report() + + assert report.sides == ("baseline", "reform") + assert report.simulation("reform") == _household_reform() + assert report.simulation("baseline") == _household_reform(choice=CURRENT_LAW) + assert _household_report(reform=None).sides == ("baseline",) + with pytest.raises(ValueError, match="no reform"): + _household_report(reform=None).simulation("reform") + # A policy compared with itself names one simulation on both sides. + same_policy = _household_report(reform=CURRENT_LAW) + assert ( + same_policy.simulation("baseline").definition_key + == same_policy.simulation("reform").definition_key + ) diff --git a/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py b/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py index 53babd5aa..83214bea3 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py @@ -1,9 +1,9 @@ """Re-running a stored economy report or simulation on a later catalog version. -A re-run reads what the stored report or simulation calculates, creates a new -run of it on the current versions, and keeps every earlier run. A report's -side may reuse a run of its own simulation that succeeded on those versions; -nothing is created while the record has a run pending or running. +A re-run reads what the stored report or simulation calculates, joins or +creates its run on the current versions, and keeps every earlier run. A +report's side joins its own simulation's run on those versions, or creates +one; a forced re-run creates an extra run beside any run under way. These run against a database the Public API's own v2 migration chain built (``PUBLIC_API_SCHEMA_DATABASE_URL``), as the simulation service's role, each @@ -25,7 +25,6 @@ LATER_POLICYENGINE_VERSION, LATER_VERSIONS, OPTIONS, - OUTPUT_BUCKET_PREFIX, VERSIONS, EconomyCatalog, ReportRunOutcome, @@ -42,6 +41,7 @@ EconomyRecordReferenceError, EconomyRequest, EconomyRunStore, + FoundReportRun, MissingPolicyParametersError, NewReportRerun, NewSimulationRerun, @@ -51,9 +51,6 @@ ReportSideError, RerunRecordDeletedError, RerunSide, - ReusableRun, - RunInProgressError, - RunReuse, SideDefinition, SimulationChoice, SimulationDefinition, @@ -61,8 +58,6 @@ SimulationType, UnknownDatasetError, UnknownRegionError, - find_reusable_run, - find_reusable_run_of, insert_report_rerun, insert_simulation_rerun, lock_reruns_of, @@ -78,7 +73,7 @@ insert_policy, insert_region, ) -from sqlalchemy import insert, text +from sqlalchemy import bindparam, event, insert, text from sqlalchemy.exc import OperationalError if TYPE_CHECKING: @@ -99,9 +94,6 @@ dataset_name="populace_us_2024", year=2026, ) -LATER_REUSE = RunReuse( - versions=LATER_VERSIONS, inputs=OPTIONS, output_uri_prefix=OUTPUT_BUCKET_PREFIX -) @dataclass(frozen=True) @@ -253,135 +245,71 @@ def test_a_stored_economy_simulations_definition_is_read( ) -def _find_later_run_of( +def _used_on_later_catalog( connection: Connection, - simulation_id: UUID, + stored: StoredReport, + economy: EconomyCatalog, later: EconomyCatalog, - *, - excluded_run_id: UUID | None = None, -) -> ReusableRun | None: - return find_reusable_run_of( - connection, - simulation_id=simulation_id, - population=later.population(), - versions=LATER_VERSIONS, - inputs=OPTIONS, - output_uri_prefix=OUTPUT_BUCKET_PREFIX, - excluded_run_id=excluded_run_id, - ) - - -def _used_on_later_catalog( - connection: Connection, stored: StoredReport, later: EconomyCatalog ) -> StoredRun: - """Insert a succeeded later run of the baseline that a succeeded re-run used.""" + """Insert a succeeded later run of the baseline that another report used. + + The other report, created on ``economy`` beside the stored one, compares + the stored report's baseline simulation (naming its run) with a reform + simulation of its own; its initial run succeeded, and its manual re-run + on the later catalog created both sides' later runs and succeeded. The + stored report has no run on the later versions, so a re-run of it has + none to join, and its reform simulation has no later run. + """ + other_reform = insert_simulation_run(connection, economy.population()) + other_report_id = insert_report_of( + connection, economy, (stored.baseline, other_reform) + ) + insert_report_run_of(connection, other_report_id, (stored.baseline, other_reform)) later_shape = RunShape(versions=LATER_VERSIONS) - later_baseline = insert_run_of( - connection, stored.baseline.simulation_id, later.population(), later_shape + later_baseline, later_other_reform = ( + insert_run_of(connection, simulation_id, later.population(), later_shape) + for simulation_id in (stored.baseline.simulation_id, other_reform.simulation_id) ) - later_reform = insert_run_of( + insert_report_run_of( connection, - stored.reform.simulation_id, - later.population(), - replace(later_shape, status=SimulationStatus.FAILED), + other_report_id, + (later_baseline, later_other_reform), + ReportRunOutcome(versions=LATER_VERSIONS, trigger=ReportRunTrigger.MANUAL), ) - insert_report_run_of(connection, stored.report_id, (later_baseline, later_reform)) return later_baseline -def test_a_simulations_own_run_on_a_later_catalog_version_is_reused( - public_api_database_url, -) -> None: - with rolled_back_transaction(public_api_database_url) as connection: - economy = insert_economy_catalog(connection) - later = insert_later_catalog(connection, economy) - stored = _stored_report(connection, economy) - later_baseline = _used_on_later_catalog(connection, stored, later) - act_as_the_service(connection) - - found = _find_later_run_of(connection, stored.baseline.simulation_id, later) - excluded = _find_later_run_of( - connection, - stored.baseline.simulation_id, - later, - excluded_run_id=later_baseline.simulation_run_id, - ) - # The run on the earlier catalog version is not on the current versions. - earlier = find_reusable_run_of( - connection, - simulation_id=stored.baseline.simulation_id, - population=economy.population(), - versions=LATER_VERSIONS, - inputs=OPTIONS, - output_uri_prefix=OUTPUT_BUCKET_PREFIX, - ) - - assert found == ReusableRun( - simulation_id=stored.baseline.simulation_id, - simulation_run_id=later_baseline.simulation_run_id, - ) - assert excluded is None - assert earlier is None - - -def test_another_simulations_run_is_not_reused_for_a_simulations_rerun( - public_api_database_url, -) -> None: - with rolled_back_transaction(public_api_database_url) as connection: - economy = insert_economy_catalog(connection) - later = insert_later_catalog(connection, economy) - stored = _stored_report(connection, economy) - _used_on_later_catalog(connection, stored, later) - other = _stored_report(connection, economy) - act_as_the_service(connection) - - found = _find_later_run_of(connection, other.baseline.simulation_id, later) - - assert found is None - - -def _rerun_of( - stored: StoredReport, - later: EconomyCatalog, - *, - baseline_reused: StoredRun | None = None, -) -> NewReportRerun: - baseline = ( - RerunSide( - simulation_id=stored.baseline.simulation_id, - simulation_run_id=uuid4(), - reused=False, - ) - if baseline_reused is None - else RerunSide( - simulation_id=baseline_reused.simulation_id, - simulation_run_id=baseline_reused.simulation_run_id, - reused=True, - ) - ) +def _rerun_of(stored: StoredReport, later: EconomyCatalog) -> NewReportRerun: + """Return an unforced re-run of ``stored`` on the later catalog's versions.""" return NewReportRerun( report_id=stored.report_id, run_id=uuid4(), population=later.population(), versions=LATER_VERSIONS, - baseline=baseline, + baseline=RerunSide( + simulation_id=stored.baseline.simulation_id, + simulation_run_id=uuid4(), + ), reform=RerunSide( simulation_id=stored.reform.simulation_id, simulation_run_id=uuid4(), - reused=False, ), ) -def test_a_report_rerun_creates_runs_of_the_reports_own_simulations( +def test_a_report_rerun_joins_or_creates_runs_of_the_reports_own_simulations( public_api_database_url, ) -> None: + """Answers 4 and 5: a side joins its simulation's run on the versions. + + The baseline's later run is another report's; the reform has none. + """ with rolled_back_transaction(public_api_database_url) as connection: economy = insert_economy_catalog(connection) later = insert_later_catalog(connection, economy) stored = _stored_report(connection, economy) - reused = _used_on_later_catalog(connection, stored, later) - rerun = _rerun_of(stored, later, baseline_reused=reused) + joined = _used_on_later_catalog(connection, stored, economy, later) + rerun = _rerun_of(stored, later) act_as_the_service(connection) insert_report_rerun(connection, rerun) @@ -390,7 +318,6 @@ def test_a_report_rerun_creates_runs_of_the_reports_own_simulations( earlier_run = _row(connection, "report_runs", stored.report_run_id) baseline_runs = _count_runs_of(connection, stored.baseline.simulation_id) - assert rerun.new_simulation_run_ids == (rerun.reform.simulation_run_id,) assert { key: report_run[key] for key in ( @@ -407,12 +334,13 @@ def test_a_report_rerun_creates_runs_of_the_reports_own_simulations( ) } == { "report_id": stored.report_id, - "baseline_simulation_run_id": reused.simulation_run_id, + "baseline_simulation_run_id": joined.simulation_run_id, "reform_simulation_run_id": rerun.reform.simulation_run_id, "country_package_version": LATER_VERSIONS.country_package_version, "policyengine_version": LATER_VERSIONS.policyengine_version, "status": ReportRunStatus.PENDING, - "trigger": ReportRunTrigger.MANUAL, + # Answer 6: the trigger is each user's record's, not the shared run's. + "trigger": None, "modal_call_id": None, "budget_window_run_id": None, "year": None, @@ -441,31 +369,75 @@ def test_a_report_rerun_creates_runs_of_the_reports_own_simulations( "status": SimulationStatus.PENDING, "modal_call_id": None, } - # The earlier run is kept, and the reused side gets no new run. + # The earlier run is kept, and the joining side gets no new run. assert earlier_run["status"] == ReportRunStatus.SUCCEEDED assert baseline_runs == 2 + assert reform_run["forced"] is False -@pytest.mark.parametrize("status", [ReportRunStatus.PENDING, ReportRunStatus.RUNNING]) -def test_a_report_rerun_is_refused_while_a_run_is_pending_or_running( +def _unforced_rerun_on_unchanged_versions( + stored: StoredReport, economy: EconomyCatalog +) -> NewReportRerun: + """Return a re-run of ``stored`` on the versions it already ran on.""" + return replace(_forced_rerun_of(stored, economy), run_id=uuid4(), forced=False) + + +@pytest.mark.parametrize( + "status", + [ReportRunStatus.PENDING, ReportRunStatus.RUNNING, ReportRunStatus.SUCCEEDED], +) +def test_a_report_rerun_joins_the_reports_run_on_its_versions( public_api_database_url, status: ReportRunStatus ) -> None: + """Answer 3: a re-run joins a run under way, so #1059's 409 goes.""" with rolled_back_transaction(public_api_database_url) as connection: economy = insert_economy_catalog(connection) - later = insert_later_catalog(connection, economy) stored = _stored_report(connection, economy, run_status=status) - rerun = _rerun_of(stored, later) + rerun = _unforced_rerun_on_unchanged_versions(stored, economy) act_as_the_service(connection) - with pytest.raises(RunInProgressError) as refused: - insert_report_rerun(connection, rerun) - created = connection.execute( + joined = insert_report_rerun(connection, rerun) + created_report_runs = connection.execute( text("SELECT count(*) FROM public.report_runs WHERE id = :id"), {"id": rerun.run_id}, ).scalar_one() + created_simulation_runs = connection.execute( + text( + "SELECT count(*) FROM public.simulation_runs WHERE id IN :ids" + ).bindparams(bindparam("ids", expanding=True)), + {"ids": list(rerun.new_simulation_run_ids)}, + ).scalar_one() - assert refused.value.run_id == stored.report_run_id - assert created == 0 + assert joined == FoundReportRun( + id=stored.report_run_id, + inserted=False, + status=status, + baseline_simulation_run_id=stored.baseline.simulation_run_id, + reform_simulation_run_id=stored.reform.simulation_run_id, + ) + assert (created_report_runs, created_simulation_runs) == (0, 0) + + +def test_a_report_rerun_beside_a_run_under_way_on_older_versions_creates_its_own( + public_api_database_url, +) -> None: + """A run on other versions is no run to join; the re-run is for the current ones.""" + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + later = insert_later_catalog(connection, economy) + stored = _stored_report(connection, economy, run_status=ReportRunStatus.RUNNING) + rerun = _rerun_of(stored, later) + act_as_the_service(connection) + + created = insert_report_rerun(connection, rerun) + report_run = _row(connection, "report_runs", rerun.run_id) + + assert (created.id, created.inserted, created.status) == ( + rerun.run_id, + True, + ReportRunStatus.PENDING, + ) + assert report_run["policyengine_version"] == LATER_POLICYENGINE_VERSION def test_a_report_whose_runs_have_ended_is_rerun_again(public_api_database_url) -> None: @@ -476,15 +448,20 @@ def test_a_report_whose_runs_have_ended_is_rerun_again(public_api_database_url) first = _rerun_of(stored, later) act_as_the_service(connection) insert_report_rerun(connection, first) - # The first re-run's run fails before a second re-run. + # The first re-run's run, and the simulation runs it created, fail + # before a second re-run. connection.execute(text("RESET ROLE")) - connection.execute( - text( - "UPDATE public.report_runs SET status = 'failed', " - "completed_at = now() WHERE id = :id" - ), - {"id": first.run_id}, - ) + for table_name, run_ids in ( + ("report_runs", [first.run_id]), + ("simulation_runs", list(first.new_simulation_run_ids)), + ): + connection.execute( + text( + f"UPDATE public.{table_name} SET status = 'failed', " # noqa: S608 # fixed table names + "completed_at = now() WHERE id IN :ids" + ).bindparams(bindparam("ids", expanding=True)), + {"ids": run_ids}, + ) second = _rerun_of(stored, later) act_as_the_service(connection) @@ -495,9 +472,10 @@ def test_a_report_whose_runs_have_ended_is_rerun_again(public_api_database_url) ) -def test_a_simulation_rerun_creates_a_run_and_is_refused_while_one_is_under_way( +def test_a_simulation_rerun_joins_its_run_on_the_current_versions_until_it_fails( public_api_database_url, ) -> None: + """Answer 3: a re-run joins a run under way or succeeded; 2: never a failed one.""" with rolled_back_transaction(public_api_database_url) as connection: economy = insert_economy_catalog(connection) later = insert_later_catalog(connection, economy) @@ -510,25 +488,61 @@ def test_a_simulation_rerun_creates_a_run_and_is_refused_while_one_is_under_way( ) act_as_the_service(connection) - insert_simulation_rerun(connection, rerun) + inserted = insert_simulation_rerun(connection, rerun) created = _row(connection, "simulation_runs", rerun.run_id) - with pytest.raises(RunInProgressError) as refused: - insert_simulation_rerun(connection, replace(rerun, run_id=uuid4())) - earlier = _row(connection, "simulation_runs", stored.simulation_run_id) + joined_under_way = insert_simulation_rerun( + connection, replace(rerun, run_id=uuid4()) + ) + joined_succeeded = insert_simulation_rerun( + connection, + NewSimulationRerun( + simulation_id=stored.simulation_id, + run_id=uuid4(), + population=economy.population(), + versions=VERSIONS, + ), + ) + connection.execute(text("RESET ROLE")) + connection.execute( + text( + "UPDATE public.simulation_runs SET status = 'failed', " + "completed_at = now() WHERE id = :id" + ), + {"id": rerun.run_id}, + ) + act_as_the_service(connection) + after_failure = insert_simulation_rerun( + connection, replace(rerun, run_id=uuid4()) + ) + runs_of_the_simulation = _count_runs_of(connection, stored.simulation_id) + assert (inserted.id, inserted.inserted, inserted.status) == ( + rerun.run_id, + True, + SimulationStatus.PENDING, + ) assert ( created["simulation_id"], created["tax_benefit_model_version_id"], created["policyengine_version"], created["status"], + created["forced"], ) == ( stored.simulation_id, later.catalog.version_id, LATER_POLICYENGINE_VERSION, SimulationStatus.PENDING, + False, ) - assert refused.value.run_id == rerun.run_id - assert earlier["status"] == SimulationStatus.SUCCEEDED + assert (joined_under_way.id, joined_under_way.inserted) == (rerun.run_id, False) + assert ( + joined_succeeded.id, + joined_succeeded.inserted, + joined_succeeded.status, + ) == (stored.simulation_run_id, False, SimulationStatus.SUCCEEDED) + assert after_failure.inserted is True + assert after_failure.id not in {rerun.run_id, stored.simulation_run_id} + assert runs_of_the_simulation == 3 def test_a_rerun_holds_its_records_lock_until_its_transaction_ends( @@ -561,53 +575,21 @@ def test_a_report_reruns_inputs_are_read_on_the_current_catalog_version( ) reform_choice = SimulationChoice(policy_id=policy_id, dynamic_id=None) stored = _stored_report(connection, economy, reform_choice=reform_choice) - reused = _used_on_later_catalog(connection, stored, later) act_as_the_service(connection) - store = _store_on(connection) - sides = { - "baseline": SideDefinition(stored.baseline.simulation_id, CURRENT_LAW), - "reform": SideDefinition(stored.reform.simulation_id, reform_choice), - } - inputs = store.read_report_rerun_inputs( - LATER_REQUEST, **sides, reuse=LATER_REUSE + inputs = _store_on(connection).read_report_rerun_inputs( + LATER_REQUEST, + baseline=SideDefinition(stored.baseline.simulation_id, CURRENT_LAW), + reform=SideDefinition(stored.reform.simulation_id, reform_choice), ) - forced = store.read_report_rerun_inputs(LATER_REQUEST, **sides, reuse=None) assert (inputs.catalog.catalog_version_id, inputs.catalog.region.id) == ( later.catalog.version_id, later.region_id, ) assert inputs.catalog.dataset.id == later.dataset_id - assert inputs.baseline.reusable_run == ReusableRun( - simulation_id=stored.baseline.simulation_id, - simulation_run_id=reused.simulation_run_id, - ) - assert inputs.reform.reusable_run is None + assert inputs.baseline.reform == {} assert inputs.reform.reform == {CTC_AMOUNT: {"2026-01-01.2200-12-31": 3_000}} - assert forced.baseline.reusable_run is None - - -def test_both_sides_of_one_simulation_never_reuse_the_same_run( - public_api_database_url, -) -> None: - with rolled_back_transaction(public_api_database_url) as connection: - economy = insert_economy_catalog(connection) - later = insert_later_catalog(connection, economy) - stored = _stored_report(connection, economy) - reused = _used_on_later_catalog(connection, stored, later) - act_as_the_service(connection) - side = SideDefinition(stored.baseline.simulation_id, CURRENT_LAW) - - inputs = _store_on(connection).read_report_rerun_inputs( - LATER_REQUEST, baseline=side, reform=side, reuse=LATER_REUSE - ) - - assert inputs.baseline.reusable_run == ReusableRun( - simulation_id=stored.baseline.simulation_id, - simulation_run_id=reused.simulation_run_id, - ) - assert inputs.reform.reusable_run is None def test_a_rerun_names_the_side_whose_policy_the_current_catalog_cannot_set( @@ -628,7 +610,6 @@ def test_a_rerun_names_the_side_whose_policy_the_current_catalog_cannot_set( LATER_REQUEST, baseline=SideDefinition(stored.baseline.simulation_id, CURRENT_LAW), reform=SideDefinition(stored.reform.simulation_id, reform_choice), - reuse=None, ) assert refused.value.side == "reform" @@ -667,7 +648,6 @@ def test_a_rerun_is_refused_when_the_current_catalog_lacks_its_region_or_dataset request, baseline=SideDefinition(stored.baseline.simulation_id, CURRENT_LAW), reform=SideDefinition(stored.reform.simulation_id, CURRENT_LAW), - reuse=None, ) @@ -714,12 +694,11 @@ def test_a_rerun_and_its_runs_are_created_through_the_store( store.create_simulation_rerun(simulation_rerun) definition = store.read_report_definition(stored.report_id) simulation = store.read_simulation_definition(simulation_rerun.simulation_id) - with pytest.raises(RunInProgressError): - store.create_report_rerun(_rerun_of(stored, later)) + # A second re-run joins the first's run, which is still pending. + joined = store.create_report_rerun(_rerun_of(stored, later)) + assert (joined.id, joined.inserted) == (rerun.run_id, False) - assert _row(connection, "report_runs", rerun.run_id)["trigger"] == ( - ReportRunTrigger.MANUAL - ) + assert _row(connection, "report_runs", rerun.run_id)["trigger"] is None assert _row(connection, "simulation_runs", simulation_rerun.run_id)[ "status" ] == (SimulationStatus.PENDING) @@ -729,47 +708,6 @@ def test_a_rerun_and_its_runs_are_created_through_the_store( assert simulation.id == simulation_rerun.simulation_id -def test_a_run_on_another_catalog_version_is_not_reused_by_a_new_report( - public_api_database_url, -) -> None: - """Only the run's own catalog version differs from the request's. - - It is also the newest run, so it would be found without that condition. - """ - with rolled_back_transaction(public_api_database_url) as connection: - economy = insert_economy_catalog(connection) - later = insert_later_catalog(connection, economy) - stored = _stored_report(connection, economy) - connection.execute( - text( - "UPDATE public.simulation_runs " - "SET tax_benefit_model_version_id = :later, " - "completed_at = completed_at + interval '1 day' WHERE id = :id" - ), - { - "later": later.catalog.version_id, - "id": stored.baseline.simulation_run_id, - }, - ) - act_as_the_service(connection) - - found = find_reusable_run( - connection, - choice=CURRENT_LAW, - population=economy.population(), - versions=VERSIONS, - inputs=OPTIONS, - output_uri_prefix=OUTPUT_BUCKET_PREFIX, - ) - - # The reform's run, the same simulation definition on the right catalog - # version, is the only one left to reuse. - assert found == ReusableRun( - simulation_id=stored.reform.simulation_id, - simulation_run_id=stored.reform.simulation_run_id, - ) - - def test_a_household_or_filtered_simulation_and_another_model_are_read_as_such( public_api_database_url, ) -> None: @@ -886,9 +824,7 @@ def test_a_rerun_of_a_deleted_report_or_simulation_says_the_record_is_gone( # A report whose side simulation is gone names that simulation instead. gone_side = replace( _rerun_of(stored, later), - reform=RerunSide( - simulation_id=uuid4(), simulation_run_id=uuid4(), reused=False - ), + reform=RerunSide(simulation_id=uuid4(), simulation_run_id=uuid4()), ) with ( pytest.raises(EconomyRecordReferenceError) as refused, @@ -900,3 +836,112 @@ def test_a_rerun_of_a_deleted_report_or_simulation_says_the_record_is_gone( "simulation_runs", "simulation_id", ) + + +def _forced_rerun_of(stored: StoredReport, economy: EconomyCatalog) -> NewReportRerun: + """Return a forced re-run of ``stored`` on the versions it already ran on.""" + return NewReportRerun( + report_id=stored.report_id, + run_id=uuid4(), + population=economy.population(), + versions=VERSIONS, + baseline=RerunSide( + simulation_id=stored.baseline.simulation_id, + simulation_run_id=uuid4(), + ), + reform=RerunSide( + simulation_id=stored.reform.simulation_id, + simulation_run_id=uuid4(), + ), + forced=True, + ) + + +@pytest.mark.parametrize( + "status", + [ReportRunStatus.PENDING, ReportRunStatus.RUNNING, ReportRunStatus.SUCCEEDED], +) +def test_a_forced_report_rerun_is_an_extra_run_beside_any_run_on_its_versions( + public_api_database_url, status: ReportRunStatus +) -> None: + """Answer 3: forced runs are marked, never refused and never conflict.""" + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + stored = _stored_report(connection, economy, run_status=status) + rerun = _forced_rerun_of(stored, economy) + act_as_the_service(connection) + + insert_report_rerun(connection, rerun) + report_run = _row(connection, "report_runs", rerun.run_id) + simulation_runs = [ + _row(connection, "simulation_runs", run_id) + for run_id in rerun.new_simulation_run_ids + ] + earlier_run = _row(connection, "report_runs", stored.report_run_id) + + assert (report_run["forced"], report_run["trigger"], report_run["status"]) == ( + True, + None, + ReportRunStatus.PENDING, + ) + assert len(simulation_runs) == 2 + assert all(run["forced"] for run in simulation_runs) + assert all(run["status"] == SimulationStatus.PENDING for run in simulation_runs) + assert earlier_run["status"] == status + assert earlier_run["forced"] is False + + +def test_a_report_rerun_losing_to_a_run_created_after_its_lookup_joins_it( + committed_engine, committed_catalog +) -> None: + """It joins that run and takes back the simulation runs it had inserted.""" + economy = committed_catalog + failed = RunShape(status=SimulationStatus.FAILED) + with committed_engine.begin() as connection: + baseline = insert_simulation_run(connection, economy.population(), failed) + reform = insert_simulation_run(connection, economy.population(), failed) + report_id = insert_report_of(connection, economy, (baseline, reform)) + stored = StoredReport( + report_id=report_id, + baseline=baseline, + reform=reform, + report_run_id=uuid4(), + ) + rerun = _unforced_rerun_on_unchanged_versions(stored, economy) + competing_run_ids: list[UUID] = [] + + def create_a_competing_run_first( + _connection, _cursor, statement, _parameters, _context, _executemany + ) -> None: + if competing_run_ids or not statement.lstrip().startswith( + "INSERT INTO public.report_runs" + ): + return + with committed_engine.begin() as other: + competing_run_ids.append( + insert_report_run_of( + other, + report_id, + (baseline, reform), + ReportRunOutcome(status=ReportRunStatus.PENDING), + ) + ) + + with committed_engine.begin() as connection: + act_as_the_service(connection) + event.listen(connection, "before_cursor_execute", create_a_competing_run_first) + try: + joined = insert_report_rerun(connection, rerun) + finally: + event.remove( + connection, "before_cursor_execute", create_a_competing_run_first + ) + kept = connection.execute( + text( + "SELECT count(*) FROM public.simulation_runs WHERE id IN :ids" + ).bindparams(bindparam("ids", expanding=True)), + {"ids": list(rerun.new_simulation_run_ids)}, + ).scalar_one() + + assert (joined.id, joined.inserted) == (competing_run_ids[0], False) + assert kept == 0 diff --git a/libs/policyengine-simulation-persistence/tests/test_economy_run_reads.py b/libs/policyengine-simulation-persistence/tests/test_economy_run_reads.py index 836b63c23..5e11ee4b1 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_run_reads.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_run_reads.py @@ -21,6 +21,7 @@ RunShape, insert_economy_catalog, insert_report_run_naming, + insert_run_of, insert_simulation_run, ) from policyengine_simulation_persistence import ( @@ -39,7 +40,13 @@ def _report_with_runs(connection, economy: EconomyCatalog) -> tuple[UUID, list[UUID]]: - """Insert a report and three runs of it; return the report and its runs.""" + """Insert a report and three runs of it; return the report and its runs. + + The first failed; the two after it are forced re-runs' runs, still + pending, as only forced runs share one report's versions with another + run that hasn't failed. Each forced run names forced simulation runs of + its own, as a forced re-run creates them. + """ population = economy.population() baseline = insert_simulation_run(connection, population) reform = insert_simulation_run( @@ -58,18 +65,24 @@ def _report_with_runs(connection, economy: EconomyCatalog) -> tuple[UUID, list[U .one() .report_id ) + forced_shape = RunShape(status=SimulationStatus.PENDING, forced=True) for _ in range(2): run_id = uuid4() + forced_baseline, forced_reform = ( + insert_run_of(connection, side.simulation_id, population, forced_shape) + for side in (baseline, reform) + ) connection.execute( report_runs.insert().values( id=run_id, report_id=report_id, - baseline_simulation_run_id=baseline.simulation_run_id, - reform_simulation_run_id=reform.simulation_run_id, + baseline_simulation_run_id=forced_baseline.simulation_run_id, + reform_simulation_run_id=forced_reform.simulation_run_id, country_package_version=COUNTRY_PACKAGE_VERSION, policyengine_version=POLICYENGINE_VERSION, status=ReportRunStatus.PENDING, trigger="manual", + forced=True, ) ) run_ids.append(run_id) diff --git a/libs/policyengine-simulation-persistence/tests/test_economy_run_records.py b/libs/policyengine-simulation-persistence/tests/test_economy_run_records.py index 1ddf50262..886a590f4 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_run_records.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_run_records.py @@ -1,38 +1,31 @@ -"""The simulation service's reads and writes for economy simulations and reports. +"""The simulation service's catalog reads and run writes for economy records. These run against a database the Public API's own v2 migration chain built (``PUBLIC_API_SCHEMA_DATABASE_URL``), as the simulation service's role, each -in a transaction rolled back afterwards. The Public API's rows a request names -are inserted first, as the superuser. +in a transaction rolled back afterwards. The Public API's rows a request +names, and any stored report or simulation, are inserted first, as the +superuser. """ from __future__ import annotations -from dataclasses import replace from typing import TYPE_CHECKING from uuid import UUID, uuid4 import pytest from conftest import act_as_the_service, rolled_back_transaction from economy_rows import ( - CURRENT_LAW, - VERSIONS, - EconomyCatalog, + PendingReport, + RunShape, insert_economy_catalog, - insert_reusable_run, + insert_pending_report, + insert_simulation_run, ) from policyengine_simulation_persistence import ( - EconomyRecordReferenceError, - NewEconomyReport, - NewEconomySimulation, ReportRunStatus, - ReportSimulation, - SimulationChoice, SimulationStatus, fail_unstarted_report_run, fail_unstarted_simulation_run, - insert_economy_report, - insert_economy_simulation, read_dataset, read_dataset_by_id, read_model_id, @@ -42,7 +35,7 @@ report_runs, simulation_runs, ) -from public_api_rows import insert_dataset, insert_policy, insert_region +from public_api_rows import insert_dataset, insert_region from sqlalchemy import select, text, update if TYPE_CHECKING: @@ -50,38 +43,6 @@ pytestmark = pytest.mark.public_api_schema -REPORT_OPTIONS = {"include_cliffs": True, "spm": {"geography_kind": "national"}} - - -def _new_side(choice: SimulationChoice = CURRENT_LAW) -> ReportSimulation: - return ReportSimulation( - simulation_id=uuid4(), - simulation_run_id=uuid4(), - choice=choice, - reused=False, - ) - - -def _new_report( - economy: EconomyCatalog, - *, - baseline: ReportSimulation | None = None, - reform: ReportSimulation | None = None, -) -> NewEconomyReport: - return NewEconomyReport( - id=uuid4(), - run_id=uuid4(), - country=economy.catalog.country, - label="Child tax credit", - description="A larger credit", - tax_benefit_model_id=economy.catalog.model_id, - population=economy.population(), - versions=VERSIONS, - inputs=REPORT_OPTIONS, - baseline=baseline or _new_side(), - reform=reform or _new_side(), - ) - def _row(connection: Connection, table_name: str, row_id: UUID) -> dict: row = connection.execute( @@ -91,12 +52,6 @@ def _row(connection: Connection, table_name: str, row_id: UUID) -> dict: return dict(row.one()) -def _count(connection: Connection, table_name: str) -> int: - return connection.execute( - text(f"SELECT count(*) FROM public.{table_name}") # noqa: S608 # fixed table names - ).scalar_one() - - def test_the_countrys_model_is_found_by_its_name(public_api_database_url) -> None: with rolled_back_transaction(public_api_database_url) as connection: economy = insert_economy_catalog(connection) @@ -179,260 +134,10 @@ def test_a_dataset_is_found_by_name_or_id_in_its_catalog_version_only( assert (by_id.id, by_id.name) == (economy.dataset_id, "populace_us_2024") -def test_a_report_its_simulations_and_runs_are_created_pending( - public_api_database_url, -) -> None: - with rolled_back_transaction(public_api_database_url) as connection: - economy = insert_economy_catalog(connection) - policy_id = insert_policy(connection, economy.catalog) - report = _new_report( - economy, reform=_new_side(SimulationChoice(policy_id, dynamic_id=None)) - ) - act_as_the_service(connection) - - insert_economy_report(connection, report) - stored_report = _row(connection, "reports", report.id) - stored_run = _row(connection, "report_runs", report.run_id) - baseline = _row(connection, "simulations", report.baseline.simulation_id) - reform = _row(connection, "simulations", report.reform.simulation_id) - baseline_run = _row( - connection, "simulation_runs", report.baseline.simulation_run_id - ) - reform_run = _row( - connection, "simulation_runs", report.reform.simulation_run_id - ) - - population = economy.population() - assert { - key: stored_report[key] - for key in ( - "label", - "description", - "country", - "type", - "user_id", - "tax_benefit_model_id", - "policy_id", - "baseline_simulation_id", - "reform_simulation_id", - "household_id", - "dataset_id", - "region_id", - "year", - "inputs", - "budget_window_size", - ) - } == { - "label": "Child tax credit", - "description": "A larger credit", - "country": "us", - "type": "economy", - "user_id": None, - "tax_benefit_model_id": economy.catalog.model_id, - "policy_id": policy_id, - "baseline_simulation_id": report.baseline.simulation_id, - "reform_simulation_id": report.reform.simulation_id, - "household_id": None, - "dataset_id": economy.dataset_id, - "region_id": economy.region_id, - "year": 2026, - "inputs": REPORT_OPTIONS, - "budget_window_size": None, - } - assert { - key: stored_run[key] - for key in ( - "report_id", - "baseline_simulation_run_id", - "reform_simulation_run_id", - "budget_window_run_id", - "year", - "country_package_version", - "policyengine_version", - "status", - "trigger", - "modal_call_id", - "started_at", - "completed_at", - ) - } == { - "report_id": report.id, - "baseline_simulation_run_id": report.baseline.simulation_run_id, - "reform_simulation_run_id": report.reform.simulation_run_id, - "budget_window_run_id": None, - "year": None, - "country_package_version": VERSIONS.country_package_version, - "policyengine_version": VERSIONS.policyengine_version, - "status": "pending", - "trigger": "initial", - "modal_call_id": None, - "started_at": None, - "completed_at": None, - } - for simulation, run, expected_policy in ( - (baseline, baseline_run, None), - (reform, reform_run, policy_id), - ): - assert ( - simulation["simulation_type"], - simulation["policy_id"], - simulation["dynamic_id"], - simulation["household_id"], - simulation["dataset_id"], - simulation["region_id"], - simulation["tax_benefit_model_version_id"], - simulation["year"], - simulation["filter_field"], - ) == ( - "economy", - expected_policy, - None, - None, - population.dataset_id, - population.region_id, - population.tax_benefit_model_version_id, - 2026, - None, - ) - assert ( - run["simulation_id"], - run["year"], - run["tax_benefit_model_version_id"], - run["country_package_version"], - run["policyengine_version"], - run["dataset_id"], - run["region_id"], - run["status"], - run["modal_call_id"], - run["output_uri"], - ) == ( - simulation["id"], - 2026, - population.tax_benefit_model_version_id, - VERSIONS.country_package_version, - VERSIONS.policyengine_version, - population.dataset_id, - population.region_id, - "pending", - None, - None, - ) - - -def test_a_side_reusing_a_succeeded_run_creates_nothing_for_that_side( - public_api_database_url, -) -> None: - with rolled_back_transaction(public_api_database_url) as connection: - economy = insert_economy_catalog(connection) - reused = insert_reusable_run(connection, economy) - report = _new_report( - economy, - baseline=ReportSimulation( - simulation_id=reused.simulation_id, - simulation_run_id=reused.simulation_run_id, - choice=CURRENT_LAW, - reused=True, - ), - ) - simulations_before = _count(connection, "simulations") - runs_before = _count(connection, "simulation_runs") - act_as_the_service(connection) - - insert_economy_report(connection, report) - stored_report = _row(connection, "reports", report.id) - stored_run = _row(connection, "report_runs", report.run_id) - simulations_after = _count(connection, "simulations") - runs_after = _count(connection, "simulation_runs") - - assert stored_report["baseline_simulation_id"] == reused.simulation_id - assert stored_run["baseline_simulation_run_id"] == reused.simulation_run_id - assert stored_run["reform_simulation_run_id"] == report.reform.simulation_run_id - assert (simulations_after, runs_after) == ( - simulations_before + 1, - runs_before + 1, - ) - - -@pytest.mark.parametrize( - ("missing_column", "table_name"), - [("region_id", "simulations"), ("dataset_id", "simulations")], -) -def test_a_report_naming_a_missing_row_names_the_column_that_refused_it( - public_api_database_url, missing_column: str, table_name: str -) -> None: - with rolled_back_transaction(public_api_database_url) as connection: - economy = insert_economy_catalog(connection) - report = _new_report(economy) - population = replace(report.population, **{missing_column: uuid4()}) - act_as_the_service(connection) - - with pytest.raises(EconomyRecordReferenceError) as refusal: - insert_economy_report(connection, replace(report, population=population)) - - assert (refusal.value.table_name, refusal.value.column_name) == ( - table_name, - missing_column, - ) - - -def test_a_report_naming_a_missing_dynamic_names_its_column( - public_api_database_url, -) -> None: - with rolled_back_transaction(public_api_database_url) as connection: - economy = insert_economy_catalog(connection) - report = _new_report( - economy, reform=_new_side(SimulationChoice(None, dynamic_id=uuid4())) - ) - act_as_the_service(connection) - - with pytest.raises(EconomyRecordReferenceError) as refusal: - insert_economy_report(connection, report) - - assert (refusal.value.table_name, refusal.value.column_name) == ( - "simulations", - "dynamic_id", - ) - - -def test_a_simulation_and_its_run_are_created_pending(public_api_database_url) -> None: - with rolled_back_transaction(public_api_database_url) as connection: - economy = insert_economy_catalog(connection) - policy_id = insert_policy(connection, economy.catalog) - simulation = NewEconomySimulation( - id=uuid4(), - run_id=uuid4(), - choice=SimulationChoice(policy_id, dynamic_id=None), - population=economy.population(year=2027), - versions=VERSIONS, - ) - act_as_the_service(connection) - - insert_economy_simulation(connection, simulation) - stored = _row(connection, "simulations", simulation.id) - run = _row(connection, "simulation_runs", simulation.run_id) - - assert ( - stored["simulation_type"], - stored["policy_id"], - stored["dynamic_id"], - stored["dataset_id"], - stored["region_id"], - stored["year"], - ) == ("economy", policy_id, None, economy.dataset_id, economy.region_id, 2027) - assert ( - run["simulation_id"], - run["year"], - run["status"], - run["modal_call_id"], - run["policyengine_version"], - ) == (simulation.id, 2027, "pending", None, VERSIONS.policyengine_version) - - -def _created_report(connection: Connection) -> NewEconomyReport: - economy = insert_economy_catalog(connection) - report = _new_report(economy) +def _created_report(connection: Connection) -> PendingReport: + """Insert a pending report and its runs, then act as the service.""" + report = insert_pending_report(connection, insert_economy_catalog(connection)) act_as_the_service(connection) - insert_economy_report(connection, report) return report @@ -443,15 +148,15 @@ def test_a_report_runs_call_is_recorded_once_while_it_is_pending_without_one( report = _created_report(connection) first = record_report_run_call( - connection, report_run_id=report.run_id, modal_call_id="fc-first" + connection, report_run_id=report.report_run_id, modal_call_id="fc-first" ) second = record_report_run_call( - connection, report_run_id=report.run_id, modal_call_id="fc-second" + connection, report_run_id=report.report_run_id, modal_call_id="fc-second" ) unknown = record_report_run_call( connection, report_run_id=uuid4(), modal_call_id="fc-other" ) - call_id = _row(connection, "report_runs", report.run_id)["modal_call_id"] + call_id = _row(connection, "report_runs", report.report_run_id)["modal_call_id"] assert (first, second, unknown) == ( ReportRunStatus.PENDING, @@ -467,21 +172,21 @@ def test_a_claimed_report_run_keeps_its_claim(public_api_database_url) -> None: connection.execute(text("RESET ROLE")) connection.execute( update(report_runs) - .where(report_runs.c.id == report.run_id) + .where(report_runs.c.id == report.report_run_id) .values(status=ReportRunStatus.RUNNING, modal_call_id="fc-coordinator") ) act_as_the_service(connection) status = record_report_run_call( - connection, report_run_id=report.run_id, modal_call_id="fc-late" + connection, report_run_id=report.report_run_id, modal_call_id="fc-late" ) failed = fail_unstarted_report_run( connection, - report_run_id=report.run_id, + report_run_id=report.report_run_id, simulation_run_ids=(report.baseline.simulation_run_id,), error_message="modal_call_refused: Modal refused the call.", ) - stored = _row(connection, "report_runs", report.run_id) + stored = _row(connection, "report_runs", report.report_run_id) baseline = _row( connection, "simulation_runs", report.baseline.simulation_run_id ) @@ -501,7 +206,7 @@ def test_an_unstarted_report_run_and_its_new_simulation_runs_fail_at_once( failed = fail_unstarted_report_run( connection, - report_run_id=report.run_id, + report_run_id=report.report_run_id, simulation_run_ids=( report.baseline.simulation_run_id, report.reform.simulation_run_id, @@ -510,11 +215,11 @@ def test_an_unstarted_report_run_and_its_new_simulation_runs_fail_at_once( ) again = fail_unstarted_report_run( connection, - report_run_id=report.run_id, + report_run_id=report.report_run_id, simulation_run_ids=(), error_message="a second failure", ) - stored = _row(connection, "report_runs", report.run_id) + stored = _row(connection, "report_runs", report.report_run_id) stored_simulation_runs = connection.execute( select( simulation_runs.c.status, @@ -544,45 +249,38 @@ def test_a_simulation_runs_call_is_recorded_or_the_run_failed_while_unstarted( ) -> None: with rolled_back_transaction(public_api_database_url) as connection: economy = insert_economy_catalog(connection) - recorded = NewEconomySimulation( - id=uuid4(), - run_id=uuid4(), - choice=CURRENT_LAW, - population=economy.population(), - versions=VERSIONS, - ) - refused = NewEconomySimulation( - id=uuid4(), - run_id=uuid4(), - choice=CURRENT_LAW, - population=economy.population(), - versions=VERSIONS, + pending = RunShape(status=SimulationStatus.PENDING) + recorded, refused = ( + insert_simulation_run(connection, economy.population(), pending) + for _ in range(2) ) act_as_the_service(connection) - insert_economy_simulation(connection, recorded) - insert_economy_simulation(connection, refused) status = record_simulation_run_call( - connection, simulation_run_id=recorded.run_id, modal_call_id="fc-worker" + connection, + simulation_run_id=recorded.simulation_run_id, + modal_call_id="fc-worker", ) not_failed = fail_unstarted_simulation_run( connection, - simulation_run_id=recorded.run_id, + simulation_run_id=recorded.simulation_run_id, error_message="modal_call_refused: refused", ) failed = fail_unstarted_simulation_run( connection, - simulation_run_id=refused.run_id, + simulation_run_id=refused.simulation_run_id, error_message="modal_call_refused: refused", ) not_recorded = record_simulation_run_call( - connection, simulation_run_id=refused.run_id, modal_call_id="fc-late" + connection, + simulation_run_id=refused.simulation_run_id, + modal_call_id="fc-late", ) unknown = record_simulation_run_call( connection, simulation_run_id=uuid4(), modal_call_id="fc-other" ) - recorded_run = _row(connection, "simulation_runs", recorded.run_id) - refused_run = _row(connection, "simulation_runs", refused.run_id) + recorded_run = _row(connection, "simulation_runs", recorded.simulation_run_id) + refused_run = _row(connection, "simulation_runs", refused.simulation_run_id) assert (status, not_failed, failed, not_recorded, unknown) == ( SimulationStatus.PENDING, diff --git a/libs/policyengine-simulation-persistence/tests/test_economy_run_reuse.py b/libs/policyengine-simulation-persistence/tests/test_economy_run_reuse.py deleted file mode 100644 index ee750e10d..000000000 --- a/libs/policyengine-simulation-persistence/tests/test_economy_run_reuse.py +++ /dev/null @@ -1,307 +0,0 @@ -"""Which succeeded simulation run a new report reuses, if any. - -A report reuses the newest run of a simulation with the same policy, dynamic, -catalog version, dataset, region and year, that succeeded on the same country -package and .py versions, whose output file is in the output bucket, and that -a succeeded report run with the same options used. A run any report run -refused to reuse is never offered again. - -These run against a database the Public API's own v2 migration chain built -(``PUBLIC_API_SCHEMA_DATABASE_URL``), as the simulation service's role, each -in a transaction rolled back afterwards. -""" - -from __future__ import annotations - -from dataclasses import dataclass, field, replace -from datetime import timedelta -from typing import TYPE_CHECKING, Any -from uuid import UUID, uuid4 - -import pytest -from conftest import act_as_the_service, rolled_back_transaction -from economy_rows import ( - COMPLETED_AT, - CURRENT_LAW, - OPTIONS, - OUTPUT_BUCKET_PREFIX, - VERSIONS, - EconomyCatalog, - ReportRunOutcome, - RunShape, - StoredRun, - insert_economy_catalog, - insert_report_run_naming, - insert_reusable_run, - insert_simulation_run, -) -from policyengine_simulation_persistence import ( - ReportRunStatus, - ReusableRun, - RunVersions, - SimulationChoice, - SimulationStatus, - find_reusable_run, -) -from public_api_rows import insert_dataset, insert_dynamic, insert_policy, insert_region - -if TYPE_CHECKING: - from collections.abc import Callable - - from sqlalchemy import Connection - -pytestmark = pytest.mark.public_api_schema - - -@dataclass(frozen=True) -class Request: - """What a new report's simulation asks for, as the reuse search sees it.""" - - choice: SimulationChoice = CURRENT_LAW - year: int = 2026 - versions: RunVersions = VERSIONS - inputs: dict[str, Any] = field(default_factory=lambda: dict(OPTIONS)) - excluded_run_id: UUID | None = None - - -def _find( - connection: Connection, economy: EconomyCatalog, request: Request | None = None -) -> ReusableRun | None: - request = request or Request() - return find_reusable_run( - connection, - choice=request.choice, - population=economy.population(year=request.year), - versions=request.versions, - inputs=request.inputs, - output_uri_prefix=OUTPUT_BUCKET_PREFIX, - excluded_run_id=request.excluded_run_id, - ) - - -def _reusable(run: StoredRun) -> ReusableRun: - return ReusableRun( - simulation_id=run.simulation_id, simulation_run_id=run.simulation_run_id - ) - - -def test_a_succeeded_run_a_report_used_with_the_same_options_is_reused( - public_api_database_url, -) -> None: - with rolled_back_transaction(public_api_database_url) as connection: - economy = insert_economy_catalog(connection) - policy_id = insert_policy(connection, economy.catalog) - dynamic_id = insert_dynamic(connection, economy.catalog) - choice = SimulationChoice(policy_id=policy_id, dynamic_id=dynamic_id) - reused = insert_reusable_run(connection, economy, RunShape(choice=choice)) - act_as_the_service(connection) - - found = _find(connection, economy, Request(choice=choice)) - - assert found == _reusable(reused) - - -def _another_policy(connection: Connection, economy: EconomyCatalog) -> dict: - return { - "choice": SimulationChoice(insert_policy(connection, economy.catalog), None) - } - - -def _another_dynamic(connection: Connection, economy: EconomyCatalog) -> dict: - return { - "choice": SimulationChoice(None, insert_dynamic(connection, economy.catalog)) - } - - -# Each makes the request differ from the stored run in one way. -DIFFERENCES: dict[str, Callable[[Connection, EconomyCatalog], dict[str, Any]]] = { - "another policy": _another_policy, - "another dynamic": _another_dynamic, - "another year": lambda _connection, _economy: {"year": 2027}, - "another .py version": lambda _connection, _economy: { - "versions": replace(VERSIONS, policyengine_version="6.18.0") - }, - "another country package version": lambda _connection, _economy: { - "versions": replace(VERSIONS, country_package_version="1.765.0") - }, - "other options": lambda _connection, _economy: {"inputs": {"include_cliffs": True}}, -} - - -@pytest.mark.parametrize("difference", sorted(DIFFERENCES)) -def test_a_run_differing_from_the_request_is_not_reused( - public_api_database_url, difference: str -) -> None: - with rolled_back_transaction(public_api_database_url) as connection: - economy = insert_economy_catalog(connection) - insert_reusable_run(connection, economy) - request = DIFFERENCES[difference](connection, economy) - act_as_the_service(connection) - - assert _find(connection, economy, Request(**request)) is None - - -def test_a_run_of_another_region_or_dataset_is_not_reused( - public_api_database_url, -) -> None: - with rolled_back_transaction(public_api_database_url) as connection: - economy = insert_economy_catalog(connection) - insert_reusable_run(connection, economy) - other_dataset_id = insert_dataset(connection, economy.catalog, "acs_2024") - other_region_id = insert_region( - connection, - economy.catalog, - "state/ca", - default_dataset_id=economy.dataset_id, - region_type="state", - ) - act_as_the_service(connection) - - for other in ( - replace(economy, dataset_id=other_dataset_id), - replace(economy, region_id=other_region_id), - ): - assert _find(connection, other) is None - - -@pytest.mark.parametrize( - "status", - [SimulationStatus.PENDING, SimulationStatus.RUNNING, SimulationStatus.FAILED], -) -def test_an_unfinished_or_failed_run_is_not_reused( - public_api_database_url, status: SimulationStatus -) -> None: - with rolled_back_transaction(public_api_database_url) as connection: - economy = insert_economy_catalog(connection) - insert_reusable_run(connection, economy, RunShape(status=status)) - act_as_the_service(connection) - - assert _find(connection, economy) is None - - -def test_a_run_whose_file_is_outside_the_output_bucket_is_not_reused( - public_api_database_url, -) -> None: - with rolled_back_transaction(public_api_database_url) as connection: - economy = insert_economy_catalog(connection) - insert_reusable_run( - connection, - economy, - RunShape( - output_uri="gs://policyengine-stage12-staging-artifacts/runs/output.parquet" - ), - ) - # A bucket whose name starts with the output bucket's is another bucket. - insert_reusable_run( - connection, - economy, - RunShape( - output_uri=OUTPUT_BUCKET_PREFIX.rstrip("/") + "-old/output.parquet" - ), - ) - act_as_the_service(connection) - - assert _find(connection, economy) is None - - -@pytest.mark.parametrize( - "report_run_status", - [ReportRunStatus.PENDING, ReportRunStatus.RUNNING, ReportRunStatus.FAILED], -) -def test_a_run_no_succeeded_report_run_used_is_not_reused( - public_api_database_url, report_run_status: ReportRunStatus -) -> None: - with rolled_back_transaction(public_api_database_url) as connection: - economy = insert_economy_catalog(connection) - population = economy.population() - stored = insert_simulation_run(connection, population) - other_side = insert_simulation_run( - connection, population, RunShape(status=SimulationStatus.FAILED) - ) - insert_report_run_naming( - connection, - economy, - (stored, other_side), - ReportRunOutcome(status=report_run_status), - ) - # A run no report run names at all, such as a simulation's own. - insert_simulation_run(connection, population) - act_as_the_service(connection) - - assert _find(connection, economy) is None - - -@pytest.mark.parametrize("refused_as", ["baseline", "reform"]) -def test_a_run_a_report_run_refused_to_reuse_is_not_reused_again( - public_api_database_url, refused_as: str -) -> None: - with rolled_back_transaction(public_api_database_url) as connection: - economy = insert_economy_catalog(connection) - reused = insert_reusable_run(connection, economy) - other_side = insert_simulation_run( - connection, economy.population(), RunShape(status=SimulationStatus.FAILED) - ) - baseline, reform = ( - (reused, other_side) if refused_as == "baseline" else (other_side, reused) - ) - insert_report_run_naming( - connection, - economy, - (baseline, reform), - ReportRunOutcome( - status=ReportRunStatus.FAILED, - error_message=( - "reused_simulation_output_incompatible: a planned column is missing" - ), - ), - ) - act_as_the_service(connection) - - assert _find(connection, economy) is None - - -def test_a_run_whose_report_run_failed_for_another_reason_is_still_reused( - public_api_database_url, -) -> None: - with rolled_back_transaction(public_api_database_url) as connection: - economy = insert_economy_catalog(connection) - reused = insert_reusable_run(connection, economy) - other_side = insert_simulation_run( - connection, economy.population(), RunShape(status=SimulationStatus.FAILED) - ) - insert_report_run_naming( - connection, - economy, - (reused, other_side), - ReportRunOutcome( - status=ReportRunStatus.FAILED, - error_message=( - "simulation_failed: the reform's worker ran out of memory" - ), - ), - ) - act_as_the_service(connection) - - assert _find(connection, economy) == _reusable(reused) - - -def test_the_newest_matching_run_is_reused_unless_excluded( - public_api_database_url, -) -> None: - with rolled_back_transaction(public_api_database_url) as connection: - economy = insert_economy_catalog(connection) - older = insert_reusable_run(connection, economy) - newer = insert_reusable_run( - connection, economy, RunShape(completed_at=COMPLETED_AT + timedelta(days=1)) - ) - act_as_the_service(connection) - - newest = _find(connection, economy) - without_newest = _find( - connection, economy, Request(excluded_run_id=newer.simulation_run_id) - ) - without_any = _find(connection, economy, Request(excluded_run_id=uuid4())) - - assert newest == _reusable(newer) - assert without_newest == _reusable(older) - assert without_any == _reusable(newer) diff --git a/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py b/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py index 7ba3e04c8..8e61562f5 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py @@ -18,12 +18,12 @@ from conftest import act_as_the_service, rolled_back_transaction from economy_rows import ( CURRENT_LAW, - OPTIONS, - OUTPUT_BUCKET_PREFIX, POLICYENGINE_VERSION, VERSIONS, + RunShape, insert_economy_catalog, - insert_reusable_run, + insert_pending_report, + insert_simulation_run, ) from policyengine_simulation_persistence import ( CatalogDataset, @@ -34,14 +34,11 @@ EconomyRequest, EconomyRunStore, MissingPolicyParametersError, - NewEconomyReport, - NewEconomySimulation, + NewReportRerun, OverlappingReformError, ReportRunStatus, ReportSideError, - ReportSimulation, - ReusableRun, - RunReuse, + RerunSide, SideRefusal, SimulationChoice, SimulationStatus, @@ -50,6 +47,7 @@ UnknownDynamicError, UnknownPolicyError, UnknownRegionError, + economy_inputs, economy_run_store, ) from public_api_rows import StoredValue, insert_dataset, insert_dynamic, insert_policy @@ -73,9 +71,6 @@ dataset_name=None, year=2026, ) -REUSE = RunReuse( - versions=VERSIONS, inputs=OPTIONS, output_uri_prefix=OUTPUT_BUCKET_PREFIX -) def _store_on(connection: Connection) -> EconomyRunStore: @@ -100,16 +95,11 @@ def test_a_reports_inputs_are_read_together(public_api_database_url) -> None: dynamic_id = insert_dynamic( connection, economy.catalog, [StoredValue(ELASTICITY, -0.05, START)] ) - reused = insert_reusable_run(connection, economy) act_as_the_service(connection) - store = _store_on(connection) reform_choice = SimulationChoice(policy_id=policy_id, dynamic_id=dynamic_id) - inputs = store.read_report_inputs( - REQUEST, baseline=CURRENT_LAW, reform=reform_choice, reuse=REUSE - ) - without_reuse = store.read_report_inputs( - REQUEST, baseline=CURRENT_LAW, reform=reform_choice, reuse=None + inputs = _store_on(connection).read_report_inputs( + REQUEST, baseline=CURRENT_LAW, reform=reform_choice ) catalog = inputs.catalog @@ -133,27 +123,6 @@ def test_a_reports_inputs_are_read_together(public_api_database_url) -> None: CTC_AMOUNT: {"2026-01-01.2200-12-31": 3_000}, ELASTICITY: {"2026-01-01.2200-12-31": -0.05}, } - assert inputs.baseline.reusable_run == ReusableRun( - simulation_id=reused.simulation_id, simulation_run_id=reused.simulation_run_id - ) - assert inputs.reform.reusable_run is None - assert without_reuse.baseline.reusable_run is None - - -def test_the_two_sides_never_reuse_the_same_run(public_api_database_url) -> None: - with rolled_back_transaction(public_api_database_url) as connection: - economy = insert_economy_catalog(connection) - only = insert_reusable_run(connection, economy) - act_as_the_service(connection) - - inputs = _store_on(connection).read_report_inputs( - REQUEST, baseline=CURRENT_LAW, reform=CURRENT_LAW, reuse=REUSE - ) - - assert inputs.baseline.reusable_run == ReusableRun( - simulation_id=only.simulation_id, simulation_run_id=only.simulation_run_id - ) - assert inputs.reform.reusable_run is None def test_a_named_dataset_is_read_instead_of_the_regions_default( @@ -174,7 +143,6 @@ def test_a_named_dataset_is_read_instead_of_the_regions_default( "acs_local_2024", ) assert (inputs.simulation.choice, inputs.simulation.reform) == (CURRENT_LAW, {}) - assert inputs.simulation.reusable_run is None @pytest.mark.parametrize( @@ -208,9 +176,7 @@ def test_each_missing_row_a_request_names_is_refused( # A report names the side whose policy or dynamic is missing. side_refused = missing in {"policy", "dynamic"} with pytest.raises(ReportSideError if side_refused else error_type) as raised: - store.read_report_inputs( - request, baseline=CURRENT_LAW, reform=choice, reuse=REUSE - ) + store.read_report_inputs(request, baseline=CURRENT_LAW, reform=choice) with pytest.raises(error_type): store.read_simulation_inputs(request, choice) @@ -264,39 +230,25 @@ def _status(connection: Connection, table_name: str, run_id) -> tuple: ) -def test_a_report_is_created_then_its_call_recorded_or_its_run_failed( +def test_a_reports_call_is_recorded_or_its_run_failed( public_api_database_url, ) -> None: with rolled_back_transaction(public_api_database_url) as connection: economy = insert_economy_catalog(connection) + recorded, refused = ( + insert_pending_report(connection, economy) for _ in range(2) + ) act_as_the_service(connection) store = _store_on(connection) - reports = [ - NewEconomyReport( - id=uuid4(), - run_id=uuid4(), - country="us", - label=f"Report {number}", - description=None, - tax_benefit_model_id=economy.catalog.model_id, - population=economy.population(), - versions=VERSIONS, - inputs=OPTIONS, - baseline=ReportSimulation(uuid4(), uuid4(), CURRENT_LAW, reused=False), - reform=ReportSimulation(uuid4(), uuid4(), CURRENT_LAW, reused=False), - ) - for number in (1, 2) - ] - for report in reports: - store.create_report(report) - recorded, refused = reports - status = store.record_report_call(recorded.run_id, "fc-coordinator") + status = store.record_report_call(recorded.report_run_id, "fc-coordinator") failed = store.fail_unstarted_report( - refused.run_id, refused.new_simulation_run_ids, "modal_call_refused: no" + refused.report_run_id, + refused.simulation_run_ids, + "modal_call_refused: no", ) - recorded_state = _status(connection, "report_runs", recorded.run_id) - refused_state = _status(connection, "report_runs", refused.run_id) + recorded_state = _status(connection, "report_runs", recorded.report_run_id) + refused_state = _status(connection, "report_runs", refused.report_run_id) refused_baseline = _status( connection, "simulation_runs", refused.baseline.simulation_run_id ) @@ -307,33 +259,29 @@ def test_a_report_is_created_then_its_call_recorded_or_its_run_failed( assert refused_baseline == ("failed", None) -def test_a_simulation_is_created_then_its_call_recorded_or_its_run_failed( +def test_a_simulations_call_is_recorded_or_its_run_failed( public_api_database_url, ) -> None: with rolled_back_transaction(public_api_database_url) as connection: economy = insert_economy_catalog(connection) + pending = RunShape(status=SimulationStatus.PENDING) + recorded, refused = ( + insert_simulation_run(connection, economy.population(), pending) + for _ in range(2) + ) act_as_the_service(connection) store = _store_on(connection) - simulations = [ - NewEconomySimulation( - id=uuid4(), - run_id=uuid4(), - choice=CURRENT_LAW, - population=economy.population(), - versions=VERSIONS, - ) - for _ in range(2) - ] - for simulation in simulations: - store.create_simulation(simulation) - recorded, refused = simulations - status = store.record_simulation_call(recorded.run_id, "fc-worker") + status = store.record_simulation_call(recorded.simulation_run_id, "fc-worker") failed = store.fail_unstarted_simulation( - refused.run_id, "modal_call_refused: no" + refused.simulation_run_id, "modal_call_refused: no" + ) + recorded_state = _status( + connection, "simulation_runs", recorded.simulation_run_id + ) + refused_state = _status( + connection, "simulation_runs", refused.simulation_run_id ) - recorded_state = _status(connection, "simulation_runs", recorded.run_id) - refused_state = _status(connection, "simulation_runs", refused.run_id) assert (status, failed) == (SimulationStatus.PENDING, True) assert recorded_state == ("pending", "fc-worker") @@ -344,26 +292,12 @@ def test_a_report_and_a_simulation_are_read_as_they_stand( public_api_database_url, ) -> None: with rolled_back_transaction(public_api_database_url) as connection: - economy = insert_economy_catalog(connection) + report = insert_pending_report(connection, insert_economy_catalog(connection)) act_as_the_service(connection) store = _store_on(connection) - report = NewEconomyReport( - id=uuid4(), - run_id=uuid4(), - country="us", - label="Read back", - description=None, - tax_benefit_model_id=economy.catalog.model_id, - population=economy.population(), - versions=VERSIONS, - inputs=OPTIONS, - baseline=ReportSimulation(uuid4(), uuid4(), CURRENT_LAW, reused=False), - reform=ReportSimulation(uuid4(), uuid4(), CURRENT_LAW, reused=False), - ) - store.create_report(report) - store.record_report_call(report.run_id, "fc-coordinator") + store.record_report_call(report.report_run_id, "fc-coordinator") - stored_report = store.read_report(report.id) + stored_report = store.read_report(report.report_id) stored_simulation = store.read_simulation(report.baseline.simulation_id) missing = (store.read_report(uuid4()), store.read_simulation(uuid4())) @@ -371,7 +305,7 @@ def test_a_report_and_a_simulation_are_read_as_they_stand( assert stored_report is not None assert stored_report.run is not None assert (stored_report.run.id, stored_report.run.status) == ( - report.run_id, + report.report_run_id, ReportRunStatus.PENDING, ) assert stored_simulation is not None @@ -421,7 +355,6 @@ def test_a_reports_refused_values_name_the_side_they_belong_to( REQUEST, baseline=choices["baseline"], reform=choices["reform"], - reuse=None, ) assert raised.value.side == side @@ -451,14 +384,11 @@ def execute(self, statement, *arguments): self.statements.append(statement) -def _new_report() -> NewEconomyReport: - return NewEconomyReport( - id=uuid4(), +def _forced_rerun() -> NewReportRerun: + """Return a forced report re-run, whose create only inserts rows.""" + return NewReportRerun( + report_id=uuid4(), run_id=uuid4(), - country="us", - label="Lost commit", - description=None, - tax_benefit_model_id=uuid4(), population=EconomyPopulation( tax_benefit_model_version_id=uuid4(), region_id=uuid4(), @@ -466,29 +396,18 @@ def _new_report() -> NewEconomyReport: year=2026, ), versions=VERSIONS, - inputs=OPTIONS, - baseline=ReportSimulation(uuid4(), uuid4(), CURRENT_LAW, reused=False), - reform=ReportSimulation(uuid4(), uuid4(), CURRENT_LAW, reused=False), + baseline=RerunSide(simulation_id=uuid4(), simulation_run_id=uuid4()), + reform=RerunSide(simulation_id=uuid4(), simulation_run_id=uuid4()), + forced=True, ) def test_a_create_whose_commit_fails_may_have_been_written() -> None: connection = _RecordingConnection() store = EconomyRunStore(lambda: _CommitFails(connection)) - report = _new_report() with pytest.raises(EconomyRecordOutcomeUnknownError) as raised: - store.create_report(report) - with pytest.raises(EconomyRecordOutcomeUnknownError): - store.create_simulation( - NewEconomySimulation( - id=uuid4(), - run_id=uuid4(), - choice=CURRENT_LAW, - population=report.population, - versions=VERSIONS, - ) - ) + store.create_report_rerun(_forced_rerun()) assert isinstance(raised.value.__cause__, OperationalError) assert connection.statements @@ -510,7 +429,7 @@ def test_a_create_whose_statement_fails_is_not_written() -> None: store = EconomyRunStore(_StatementFails) with pytest.raises(OperationalError): - store.create_report(_new_report()) + store.create_report_rerun(_forced_rerun()) def test_every_side_refusal_is_raised_with_its_side(monkeypatch) -> None: @@ -521,7 +440,8 @@ def test_every_side_refusal_is_raised_with_its_side(monkeypatch) -> None: region=CatalogRegion(id=uuid4(), code="us", default_dataset_id=uuid4()), dataset=CatalogDataset(id=uuid4(), name="populace_us_2024"), ) - monkeypatch.setattr(economy_run_store, "_catalog_rows", lambda *_: catalog) + # Each patch replaces the name where its caller looks it up. + monkeypatch.setattr(economy_run_store, "read_catalog_rows", lambda *_: catalog) refusals = { UnknownPolicyError: UnknownPolicyError("no policy"), UnknownDynamicError: UnknownDynamicError("no dynamic"), @@ -540,9 +460,7 @@ def no_database(): def refuse(*_, refusal=refusal): raise refusal - monkeypatch.setattr(economy_run_store, "_simulation_inputs", refuse) + monkeypatch.setattr(economy_inputs, "read_simulation_values", refuse) with pytest.raises(ReportSideError) as raised: - store.read_report_inputs( - REQUEST, baseline=CURRENT_LAW, reform=CURRENT_LAW, reuse=None - ) + store.read_report_inputs(REQUEST, baseline=CURRENT_LAW, reform=CURRENT_LAW) assert (raised.value.side, raised.value.error) == ("baseline", refusal) diff --git a/libs/policyengine-simulation-persistence/tests/test_economy_window_reruns.py b/libs/policyengine-simulation-persistence/tests/test_economy_window_reruns.py index 6d7619f6b..6519323f2 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_window_reruns.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_window_reruns.py @@ -3,9 +3,8 @@ A budget window's re-run is a new budget-window run of the report, with a report run per year. Each year's sides are the simulations that year's report run of the report's newest window run names, which may belong to -another report when that year reused a run. A side may reuse a run of its -own simulation that succeeded on the current versions. These run against a -database the Public API's own v2 migration chain built +another report when that year joined another report's run. These run +against a database the Public API's own v2 migration chain built (``PUBLIC_API_SCHEMA_DATABASE_URL``), as the simulation service's role, in a transaction rolled back afterwards. """ @@ -23,42 +22,40 @@ CURRENT_LAW, LATER_POLICYENGINE_VERSION, LATER_VERSIONS, - OPTIONS, - OUTPUT_BUCKET_PREFIX, VERSIONS, EconomyCatalog, RunShape, + StoredRun, insert_economy_catalog, insert_later_catalog, - insert_report_run_of, - insert_run_of, + insert_report_of, + insert_simulation_run, ) from policyengine_simulation_persistence import ( - BudgetWindowYear, EconomyPopulation, EconomyRecordReferenceError, + EconomyReportDefinition, EconomyRequest, EconomyRunStore, - NewBudgetWindowReport, - NewReportRerun, + FoundBudgetWindow, + KeyedBudgetWindow, + KeyedWindowYear, NewWindowRerun, + ProposedSide, ReportRunStatus, ReportRunTrigger, - ReportSimulation, RerunRecordDeletedError, RerunSide, - ReusableRun, - RunInProgressError, - RunReuse, SimulationStatus, WindowRerunYear, WindowYearDefinition, - insert_budget_window_report, - insert_report_rerun, + budget_window_runs, + find_or_create_budget_window, insert_window_rerun, read_report_definition, + report_runs, ) -from sqlalchemy import text +from sqlalchemy import insert, text if TYPE_CHECKING: from collections.abc import Iterator @@ -75,9 +72,16 @@ dataset_name="populace_us_2024", year=2026, ) -LATER_REUSE = RunReuse( - versions=LATER_VERSIONS, inputs=OPTIONS, output_uri_prefix=OUTPUT_BUCKET_PREFIX -) + + +@dataclass(frozen=True) +class StoredWindowYear: + """A year of a stored window: its report run and each side's simulation run.""" + + year: int + report_run_id: UUID + baseline: StoredRun + reform: StoredRun @dataclass(frozen=True) @@ -86,16 +90,71 @@ class StoredWindow: report_id: UUID window_run_id: UUID - years: tuple[BudgetWindowYear, ...] + years: tuple[StoredWindowYear, ...] -def _new_side() -> ReportSimulation: - return ReportSimulation( - simulation_id=uuid4(), - simulation_run_id=uuid4(), - choice=CURRENT_LAW, - reused=False, +def _insert_window_rows( + connection: Connection, economy: EconomyCatalog +) -> StoredWindow: + """Insert a window with no key, as the service created one before keys. + + Each year has its own current-law simulations, with a pending run each; + the report names its first year's; its window run and each year's report + run are pending, with trigger ``initial``. + """ + pending = RunShape(status=SimulationStatus.PENDING) + years = tuple( + StoredWindowYear( + year=year, + report_run_id=uuid4(), + baseline=insert_simulation_run( + connection, economy.population(year=year), pending + ), + reform=insert_simulation_run( + connection, economy.population(year=year), pending + ), + ) + for year in WINDOW_YEARS + ) + first_year = years[0] + report_id = insert_report_of( + connection, + economy, + (first_year.baseline, first_year.reform), + budget_window_size=len(years), + ) + window_run_id = uuid4() + connection.execute( + insert(budget_window_runs).values( + id=window_run_id, + report_id=report_id, + tax_benefit_model_version_id=economy.catalog.version_id, + trigger=ReportRunTrigger.INITIAL, + recalculate=False, + status=ReportRunStatus.PENDING, + ) ) + connection.execute( + insert(report_runs), + [ + { + "id": window_year.report_run_id, + "report_id": report_id, + "baseline_simulation_run_id": window_year.baseline.simulation_run_id, + "reform_simulation_run_id": window_year.reform.simulation_run_id, + "budget_window_run_id": window_run_id, + "year": window_year.year, + "country_package_version": VERSIONS.country_package_version, + "policyengine_version": VERSIONS.policyengine_version, + "status": ReportRunStatus.PENDING, + "trigger": ReportRunTrigger.INITIAL, + "modal_call_id": None, + "forced": False, + } + for window_year in years + ], + ) + return StoredWindow(report_id=report_id, window_run_id=window_run_id, years=years) def _stored_window( @@ -104,29 +163,8 @@ def _stored_window( *, window_status: ReportRunStatus = ReportRunStatus.SUCCEEDED, ) -> StoredWindow: - """Insert a budget-window report as the service would, then end its runs.""" - years = tuple( - BudgetWindowYear( - year=year, - report_run_id=uuid4(), - baseline=_new_side(), - reform=_new_side(), - ) - for year in WINDOW_YEARS - ) - report = NewBudgetWindowReport( - id=uuid4(), - window_run_id=uuid4(), - country="us", - label="Ten-year cost", - description=None, - tax_benefit_model_id=economy.catalog.model_id, - population=economy.population(year=WINDOW_YEARS[0]), - versions=VERSIONS, - inputs=OPTIONS, - years=years, - ) - insert_budget_window_report(connection, report) + """Insert a window as the service created one before keys, then end its runs.""" + report = _insert_window_rows(connection, economy) # Earlier than anything else the test's transaction creates, whose rows # all get the transaction's time. for table, condition in ( @@ -165,9 +203,7 @@ def _stored_window( "window_run_id": report.window_run_id, }, ) - return StoredWindow( - report_id=report.id, window_run_id=report.window_run_id, years=years - ) + return report def _store_on(connection: Connection) -> EconomyRunStore: @@ -205,12 +241,10 @@ def _window_rerun_of( baseline=RerunSide( simulation_id=window_year.baseline.simulation_id, simulation_run_id=uuid4(), - reused=False, ), reform=RerunSide( simulation_id=window_year.reform.simulation_id, simulation_run_id=uuid4(), - reused=False, ), ) for window_year in stored.years @@ -247,7 +281,7 @@ def test_a_budget_windows_definition_names_each_years_simulations( def test_a_definitions_years_come_from_the_newest_window_run( public_api_database_url, ) -> None: - """A year that reused another report's run names that report's simulation.""" + """A year naming another report's simulation run names that simulation.""" with rolled_back_transaction(public_api_database_url) as connection: economy = insert_economy_catalog(connection) later = insert_later_catalog(connection, economy) @@ -259,8 +293,7 @@ def test_a_definitions_years_come_from_the_newest_window_run( years[1], baseline=RerunSide( simulation_id=other_2027.baseline.simulation_id, - simulation_run_id=other_2027.baseline.simulation_run_id, - reused=True, + simulation_run_id=uuid4(), ), ) act_as_the_service(connection) @@ -276,33 +309,18 @@ def test_a_definitions_years_come_from_the_newest_window_run( ] -def test_a_window_rerun_creates_a_window_run_and_each_years_runs( +def test_a_forced_window_rerun_creates_a_window_run_and_each_years_new_runs( public_api_database_url, ) -> None: + """Answers 3 and 6: no run is reused or joined, and no trigger is written.""" with rolled_back_transaction(public_api_database_url) as connection: economy = insert_economy_catalog(connection) later = insert_later_catalog(connection, economy) stored = _stored_window(connection, economy) - reused = insert_run_of( - connection, - stored.years[1].baseline.simulation_id, - later.population(year=2027), - RunShape(versions=LATER_VERSIONS), - ) rerun = _window_rerun_of(stored, later, recalculate=True) - years = list(rerun.years) - years[1] = replace( - years[1], - baseline=RerunSide( - simulation_id=reused.simulation_id, - simulation_run_id=reused.simulation_run_id, - reused=True, - ), - ) - rerun = replace(rerun, years=tuple(years)) act_as_the_service(connection) - insert_window_rerun(connection, rerun) + found = insert_window_rerun(connection, rerun) window_run = _row(connection, "budget_window_runs", rerun.window_run_id) year_runs = [ _row(connection, "report_runs", year.report_run_id) for year in rerun.years @@ -317,6 +335,7 @@ def test_a_window_rerun_creates_a_window_run_and_each_years_runs( for key in ( "report_id", "tax_benefit_model_version_id", + "policyengine_version", "trigger", "recalculate", "status", @@ -324,10 +343,16 @@ def test_a_window_rerun_creates_a_window_run_and_each_years_runs( } == { "report_id": stored.report_id, "tax_benefit_model_version_id": later.catalog.version_id, - "trigger": ReportRunTrigger.MANUAL, + "policyengine_version": LATER_POLICYENGINE_VERSION, + "trigger": None, "recalculate": True, "status": ReportRunStatus.PENDING, } + assert (found.window_run.id, found.window_run.inserted) == ( + rerun.window_run_id, + True, + ) + assert all(year.baseline.run_inserted for year in found.years) assert [ ( run["year"], @@ -341,13 +366,15 @@ def test_a_window_rerun_creates_a_window_run_and_each_years_runs( ( year, rerun.window_run_id, - ReportRunTrigger.MANUAL, + None, ReportRunStatus.PENDING, LATER_POLICYENGINE_VERSION, ) for year in WINDOW_YEARS ] - assert year_runs[1]["baseline_simulation_run_id"] == reused.simulation_run_id + assert year_runs[1]["baseline_simulation_run_id"] == ( + rerun.years[1].baseline.simulation_run_id + ) assert ( reform_run_2028["simulation_id"], reform_run_2028["year"], @@ -362,110 +389,144 @@ def test_a_window_rerun_creates_a_window_run_and_each_years_runs( assert earlier_window["status"] == ReportRunStatus.SUCCEEDED -@pytest.mark.parametrize("status", [ReportRunStatus.PENDING, ReportRunStatus.RUNNING]) -def test_a_window_rerun_is_refused_while_a_window_run_is_under_way( - public_api_database_url, status: ReportRunStatus +def _keyed_window(connection: Connection, economy: EconomyCatalog) -> FoundBudgetWindow: + """Create a keyed window of current law against current law, as the service.""" + definition = EconomyReportDefinition( + country="us", + baseline=CURRENT_LAW, + reform=CURRENT_LAW, + dataset_name="populace_us_2024", + region_code="us", + year=WINDOW_YEARS[0], + budget_window_size=len(WINDOW_YEARS), + spm=None, + ) + return find_or_create_budget_window( + connection, + KeyedBudgetWindow( + definition=definition, + report_id=uuid4(), + window_run_id=uuid4(), + tax_benefit_model_id=economy.catalog.model_id, + population=economy.population(year=WINDOW_YEARS[0]), + versions=VERSIONS, + inputs={}, + years=tuple( + KeyedWindowYear( + year=year, + report_run_id=uuid4(), + baseline=ProposedSide( + simulation_id=uuid4(), simulation_run_id=uuid4() + ), + reform=ProposedSide( + simulation_id=uuid4(), simulation_run_id=uuid4() + ), + ) + for year in WINDOW_YEARS + ), + ), + ) + + +def _rerun_of_keyed( + found: FoundBudgetWindow, economy: EconomyCatalog +) -> NewWindowRerun: + """Return an unforced re-run of a keyed window on its own versions.""" + return NewWindowRerun( + report_id=found.report_id, + window_run_id=uuid4(), + population=economy.population(year=WINDOW_YEARS[0]), + versions=VERSIONS, + recalculate=False, + years=tuple( + WindowRerunYear( + year=year.year, + report_run_id=uuid4(), + baseline=RerunSide( + simulation_id=year.baseline.simulation_id, + simulation_run_id=uuid4(), + ), + reform=RerunSide( + simulation_id=year.reform.simulation_id, + simulation_run_id=uuid4(), + ), + ) + for year in found.years + ), + ) + + +def test_an_unforced_window_rerun_joins_a_keyed_windows_run_on_its_versions( + public_api_database_url, ) -> None: + """Answers 3 and 8: the window run under way is joined, with its year runs.""" with rolled_back_transaction(public_api_database_url) as connection: economy = insert_economy_catalog(connection) - later = insert_later_catalog(connection, economy) - stored = _stored_window(connection, economy, window_status=status) act_as_the_service(connection) + found = _keyed_window(connection, economy) - with pytest.raises(RunInProgressError) as window_refused: - insert_window_rerun(connection, _window_rerun_of(stored, later)) - # A single-year re-run of the report checks the window runs too. - with pytest.raises(RunInProgressError) as report_refused: - insert_report_rerun( - connection, - NewReportRerun( - report_id=stored.report_id, - run_id=uuid4(), - population=later.population(), - versions=LATER_VERSIONS, - baseline=RerunSide( - simulation_id=stored.years[0].baseline.simulation_id, - simulation_run_id=uuid4(), - reused=False, - ), - reform=RerunSide( - simulation_id=stored.years[0].reform.simulation_id, - simulation_run_id=uuid4(), - reused=False, - ), - ), - ) + joined = insert_window_rerun(connection, _rerun_of_keyed(found, economy)) - assert window_refused.value.run_id == stored.window_run_id - assert report_refused.value.run_id == stored.window_run_id + assert (joined.window_run.id, joined.window_run.inserted) == ( + found.window_run.id, + False, + ) + assert [year.report_run_id for year in joined.years] == [ + year.report_run_id for year in found.years + ] -def test_a_window_reruns_inputs_name_each_years_own_reusable_runs( +def test_an_unforced_window_rerun_after_a_failed_run_names_its_years_runs( public_api_database_url, ) -> None: + """Each year's sides join their simulations' runs under a new window run.""" with rolled_back_transaction(public_api_database_url) as connection: economy = insert_economy_catalog(connection) - later = insert_later_catalog(connection, economy) - stored = _stored_window(connection, economy) - later_shape = RunShape(versions=LATER_VERSIONS) - reused_2027 = insert_run_of( - connection, - stored.years[1].baseline.simulation_id, - later.population(year=2027), - later_shape, - ) - failed_reform_2027 = insert_run_of( - connection, - stored.years[1].reform.simulation_id, - later.population(year=2027), - replace(later_shape, status=SimulationStatus.FAILED), - ) - insert_report_run_of( - connection, stored.report_id, (reused_2027, failed_reform_2027) + act_as_the_service(connection) + found = _keyed_window(connection, economy) + connection.execute(text("RESET ROLE")) + connection.execute( + text( + "UPDATE public.budget_window_runs SET status = 'failed', " + "completed_at = now() WHERE id = :id" + ), + {"id": found.window_run.id}, ) act_as_the_service(connection) - years = _definition_years(stored) + rerun = _rerun_of_keyed(found, economy) - inputs = _store_on(connection).read_window_rerun_inputs( - LATER_REQUEST, - baseline=CURRENT_LAW, - reform=CURRENT_LAW, - years=years, - reuse=LATER_REUSE, - ) - forced = _store_on(connection).read_window_rerun_inputs( - LATER_REQUEST, - baseline=CURRENT_LAW, - reform=CURRENT_LAW, - years=years, - reuse=None, - ) + created = insert_window_rerun(connection, rerun) + window_run = _row(connection, "budget_window_runs", rerun.window_run_id) - assert inputs.catalog.catalog_version_id == later.catalog.version_id - assert inputs.reusable_runs == { - 2026: (None, None), - 2027: ( - ReusableRun( - simulation_id=stored.years[1].baseline.simulation_id, - simulation_run_id=reused_2027.simulation_run_id, - ), - None, - ), - 2028: (None, None), - } - assert forced.reusable_runs == dict.fromkeys(WINDOW_YEARS, (None, None)) + assert (created.window_run.id, created.window_run.inserted) == ( + rerun.window_run_id, + True, + ) + assert (window_run["recalculate"], window_run["trigger"]) == (False, None) + for first, again in zip(found.years, created.years, strict=True): + assert again.baseline.simulation_run_id == first.baseline.simulation_run_id + assert again.baseline.run_inserted is False -def _definition_years(stored: StoredWindow) -> tuple[WindowYearDefinition, ...]: - """Return the stored window's years as its definition names them.""" - return tuple( - WindowYearDefinition( - year=window_year.year, - baseline_simulation_id=window_year.baseline.simulation_id, - reform_simulation_id=window_year.reform.simulation_id, +def test_a_window_reruns_inputs_are_read_on_the_current_catalog_version( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + later = insert_later_catalog(connection, economy) + _stored_window(connection, economy) + act_as_the_service(connection) + + inputs = _store_on(connection).read_window_rerun_inputs( + LATER_REQUEST, baseline=CURRENT_LAW, reform=CURRENT_LAW ) - for window_year in stored.years + + assert (inputs.catalog.catalog_version_id, inputs.catalog.region.id) == ( + later.catalog.version_id, + later.region_id, ) + assert inputs.catalog.dataset.id == later.dataset_id + assert (inputs.baseline.choice, inputs.reform.choice) == (CURRENT_LAW, CURRENT_LAW) def test_a_window_rerun_is_created_through_the_store(public_api_database_url) -> None: @@ -477,14 +538,14 @@ def test_a_window_rerun_is_created_through_the_store(public_api_database_url) -> act_as_the_service(connection) store = _store_on(connection) - store.create_window_rerun(rerun) - with pytest.raises(RunInProgressError) as refused: - store.create_window_rerun(_window_rerun_of(stored, later)) + created = store.create_window_rerun(rerun) + joined = store.create_window_rerun(_window_rerun_of(stored, later)) assert _row(connection, "budget_window_runs", rerun.window_run_id)[ - "trigger" - ] == (ReportRunTrigger.MANUAL) - assert refused.value.run_id == rerun.window_run_id + "policyengine_version" + ] == (LATER_POLICYENGINE_VERSION) + assert (created.window_run.inserted, joined.window_run.inserted) == (True, False) + assert joined.window_run.id == rerun.window_run_id def test_a_window_rerun_refuses_years_that_are_not_its_window() -> None: @@ -492,12 +553,8 @@ def test_a_window_rerun_refuses_years_that_are_not_its_window() -> None: year = WindowRerunYear( year=2026, report_run_id=uuid4(), - baseline=RerunSide( - simulation_id=uuid4(), simulation_run_id=uuid4(), reused=False - ), - reform=RerunSide( - simulation_id=uuid4(), simulation_run_id=uuid4(), reused=False - ), + baseline=RerunSide(simulation_id=uuid4(), simulation_run_id=uuid4()), + reform=RerunSide(simulation_id=uuid4(), simulation_run_id=uuid4()), ) rerun = NewWindowRerun( report_id=uuid4(), @@ -555,9 +612,7 @@ def test_a_window_rerun_of_a_deleted_report_or_year_simulation_is_refused( rerun = _window_rerun_of(stored, later) gone_year = replace( rerun.years[2], - reform=RerunSide( - simulation_id=uuid4(), simulation_run_id=uuid4(), reused=False - ), + reform=RerunSide(simulation_id=uuid4(), simulation_run_id=uuid4()), ) with pytest.raises(RerunRecordDeletedError), connection.begin_nested(): @@ -583,26 +638,37 @@ def test_a_window_rerun_of_a_deleted_report_or_year_simulation_is_refused( ) -def test_a_window_rerun_is_refused_while_a_year_still_runs_after_its_window_ended( - public_api_database_url, +@pytest.mark.parametrize( + "status", + [ReportRunStatus.PENDING, ReportRunStatus.RUNNING, ReportRunStatus.SUCCEEDED], +) +def test_a_forced_window_rerun_is_an_extra_run_beside_any_run_on_its_versions( + public_api_database_url, status: ReportRunStatus ) -> None: + """Answer 3: every year's report run and simulation runs are marked forced.""" with rolled_back_transaction(public_api_database_url) as connection: economy = insert_economy_catalog(connection) - later = insert_later_catalog(connection, economy) - stored = _stored_window( - connection, economy, window_status=ReportRunStatus.FAILED - ) - still_running = stored.years[2].report_run_id - connection.execute( - text( - "UPDATE public.report_runs SET status = 'running', " - "started_at = now(), completed_at = NULL WHERE id = :id" - ), - {"id": still_running}, + stored = _stored_window(connection, economy, window_status=status) + rerun = replace( + _window_rerun_of(stored, economy, recalculate=True), versions=VERSIONS ) act_as_the_service(connection) - with pytest.raises(RunInProgressError) as refused: - insert_window_rerun(connection, _window_rerun_of(stored, later)) + insert_window_rerun(connection, rerun) + window_run = _row(connection, "budget_window_runs", rerun.window_run_id) + year_runs = [ + _row(connection, "report_runs", year.report_run_id) for year in rerun.years + ] + simulation_runs = [ + _row(connection, "simulation_runs", side.simulation_run_id) + for year in rerun.years + for side in (year.baseline, year.reform) + ] - assert refused.value.run_id == still_running + assert (window_run["recalculate"], window_run["status"]) == ( + True, + ReportRunStatus.PENDING, + ) + assert all(run["forced"] for run in year_runs) + assert len(simulation_runs) == 2 * len(WINDOW_YEARS) + assert all(run["forced"] for run in simulation_runs) diff --git a/libs/policyengine-simulation-persistence/tests/test_household_report_reruns.py b/libs/policyengine-simulation-persistence/tests/test_household_report_reruns.py index 1a7c6c370..9a33414c0 100644 --- a/libs/policyengine-simulation-persistence/tests/test_household_report_reruns.py +++ b/libs/policyengine-simulation-persistence/tests/test_household_report_reruns.py @@ -17,24 +17,20 @@ import pytest from conftest import act_as_the_service, rolled_back_transaction +from household_report_rows import insert_household_report_rows from policyengine_simulation_persistence import ( EconomyRecordOutcomeUnknownError, EconomyRecordReferenceError, - HouseholdReportSimulation, HouseholdReportStore, HouseholdRerunSide, - NewHouseholdReport, NewHouseholdReportRerun, ReportRunStatus, - ReportRunTrigger, RerunRecordDeletedError, - RunInProgressError, RunVersions, SideDefinition, SimulationChoice, SimulationStatus, fail_unstarted_report_run, - insert_household_report, read_report_definition, ) from public_api_rows import ( @@ -50,6 +46,7 @@ from collections.abc import Iterator from uuid import UUID + from household_report_rows import StoredHouseholdReport from public_api_rows import CatalogVersion from sqlalchemy import Connection @@ -110,41 +107,23 @@ def _stored_report( *, with_reform: bool = True, first_run_ended: bool = True, -) -> NewHouseholdReport: +) -> StoredHouseholdReport: """Insert a household report and its first runs, as the superuser. With ``first_run_ended``, its first run failed before its call started, so the report has no run under way. """ - household_id = insert_household( - connection, country="us", default_year=2026, document=DOCUMENT - ) - report = NewHouseholdReport( - id=uuid4(), - run_id=uuid4(), - country="us", - label="A larger child tax credit", - description="For one family", - tax_benefit_model_id=catalog.model_id, - tax_benefit_model_version_id=catalog.version_id, - household_id=household_id, + report = insert_household_report_rows( + connection, + catalog, + household_id=insert_household( + connection, country="us", default_year=2026, document=DOCUMENT + ), year=REPORT_YEAR, versions=VERSIONS, - inputs={}, - baseline=HouseholdReportSimulation( - simulation_id=uuid4(), simulation_run_id=uuid4(), policy_id=None - ), - reform=( - HouseholdReportSimulation( - simulation_id=uuid4(), - simulation_run_id=uuid4(), - policy_id=insert_policy(connection, catalog), - ) - if with_reform - else None - ), + reform_policy_id=insert_policy(connection, catalog) if with_reform else None, + with_reform=with_reform, ) - insert_household_report(connection, report) if first_run_ended: fail_unstarted_report_run( connection, @@ -155,10 +134,29 @@ def _stored_report( return report +def _succeed_first_runs(connection: Connection, report: StoredHouseholdReport) -> None: + """Mark the report's first run and its side runs succeeded, as the superuser.""" + for table_name, run_ids in ( + ("report_runs", [report.run_id]), + ("simulation_runs", list(report.simulation_run_ids)), + ): + connection.execute( + text( + f"UPDATE public.{table_name} SET status = 'succeeded', " # noqa: S608 # fixed table names + "completed_at = now() WHERE id = ANY(:run_ids)" + ), + {"run_ids": run_ids}, + ) + + def _rerun_of( - report: NewHouseholdReport, catalog: CatalogVersion + report: StoredHouseholdReport, catalog: CatalogVersion ) -> NewHouseholdReportRerun: - """Return the report's re-run on ``catalog``: a new run of each side's own.""" + """Return the report's re-run on ``catalog``: a new run of each side's own. + + Forced, as the service re-runs a household report without keys + (interim answer B). + """ return NewHouseholdReportRerun( report_id=report.id, run_id=uuid4(), @@ -175,6 +173,7 @@ def _rerun_of( simulation_id=report.reform.simulation_id, simulation_run_id=uuid4() ) ), + forced=True, ) @@ -255,7 +254,8 @@ def test_a_household_reports_rerun_is_a_manual_run_of_its_own_simulations( side.simulation_run_id for side in rerun.sides ) assert report_run["report_id"] == report.id - assert report_run["trigger"] == ReportRunTrigger.MANUAL + # Answer 6: the trigger is each user's record's, not the shared run's. + assert report_run["trigger"] is None assert report_run["status"] == ReportRunStatus.PENDING assert report_run["modal_call_id"] is None assert ( @@ -292,6 +292,35 @@ def test_a_household_reports_rerun_is_a_manual_run_of_its_own_simulations( assert first_run["status"] == ReportRunStatus.FAILED +def test_a_rerun_on_the_versions_of_a_succeeded_run_is_a_forced_extra_run( + public_api_database_url, +) -> None: + """Interim answer B: a household report has no keys yet, so nothing joins. + + Its runs are marked forced, so the one-unfailed-run indexes leave them + out beside the succeeded runs on the same versions. + """ + with rolled_back_transaction(public_api_database_url) as connection: + catalog, _ = _catalogs(connection) + report = _stored_report(connection, catalog, first_run_ended=False) + _succeed_first_runs(connection, report) + act_as_the_service(connection) + rerun = replace(_rerun_of(report, catalog), versions=VERSIONS) + + _store_on(connection).create_report_rerun(rerun) + report_run = _row(connection, "report_runs", rerun.run_id) + side_runs = [ + _row(connection, "simulation_runs", run_id) + for run_id in rerun.simulation_run_ids + ] + first_run = _row(connection, "report_runs", report.run_id) + + assert report_run["forced"] is True + assert [side_run["forced"] for side_run in side_runs] == [True, True] + assert first_run["forced"] is False + assert first_run["status"] == ReportRunStatus.SUCCEEDED + + def test_a_rerun_of_a_report_of_the_baseline_alone_names_no_reform_run( public_api_database_url, ) -> None: @@ -316,16 +345,17 @@ def test_a_rerun_of_a_report_of_the_baseline_alone_names_no_reform_run( assert baseline_runs == 2 -def test_a_household_report_with_a_run_under_way_is_not_rerun( +def test_a_forced_household_rerun_beside_a_run_under_way_is_an_extra_run( public_api_database_url, ) -> None: + """Answer 3: a forced run is never refused, so the 409 goes.""" with rolled_back_transaction(public_api_database_url) as connection: catalog, later_catalog = _catalogs(connection) report = _stored_report(connection, catalog, first_run_ended=False) act_as_the_service(connection) + rerun = _rerun_of(report, later_catalog) - with pytest.raises(RunInProgressError) as under_way: - _store_on(connection).create_report_rerun(_rerun_of(report, later_catalog)) + created = _store_on(connection).create_report_rerun(rerun) report_runs = _count(connection, "report_runs", "report_id", report.id) baseline_runs = _count( connection, @@ -333,9 +363,19 @@ def test_a_household_report_with_a_run_under_way_is_not_rerun( "simulation_id", report.baseline.simulation_id, ) + first_run = _row(connection, "report_runs", report.run_id) - assert under_way.value.run_id == report.run_id - assert (report_runs, baseline_runs) == (1, 1) + assert (created.id, created.inserted, created.status) == ( + rerun.run_id, + True, + ReportRunStatus.PENDING, + ) + assert ( + created.baseline_simulation_run_id, + created.reform_simulation_run_id, + ) == rerun.simulation_run_ids + assert (report_runs, baseline_runs) == (2, 2) + assert first_run["status"] == ReportRunStatus.PENDING def test_a_rerun_naming_a_deleted_report_or_simulation_is_refused_by_its_key( @@ -414,6 +454,7 @@ def test_a_rerun_whose_commit_fails_may_have_been_written() -> None: simulation_id=uuid4(), simulation_run_id=uuid4() ), reform=None, + forced=True, ) ) diff --git a/libs/policyengine-simulation-persistence/tests/test_household_report_store.py b/libs/policyengine-simulation-persistence/tests/test_household_report_store.py index b7a138465..1b34bda4c 100644 --- a/libs/policyengine-simulation-persistence/tests/test_household_report_store.py +++ b/libs/policyengine-simulation-persistence/tests/test_household_report_store.py @@ -16,13 +16,10 @@ import pytest from conftest import act_as_the_service, rolled_back_transaction +from household_report_rows import insert_household_report_rows from policyengine_simulation_persistence import ( - EconomyRecordOutcomeUnknownError, - EconomyRecordReferenceError, - HouseholdReportSimulation, HouseholdReportStore, MissingPolicyParametersError, - NewHouseholdReport, ReportRunStatus, ReportSideError, RunVersions, @@ -38,7 +35,6 @@ insert_policy, ) from sqlalchemy import text -from sqlalchemy.exc import OperationalError if TYPE_CHECKING: from collections.abc import Iterator @@ -65,8 +61,6 @@ ], "household": [{"id": "your household", "values": {}}], } -# A household report has no options: it always adds missing variables. -OPTIONS: dict[str, object] = {} def _store_on(connection: Connection) -> HouseholdReportStore: @@ -96,40 +90,6 @@ def _household(connection: Connection, *, default_year: int | None = 2026) -> UU ) -def _new_report( - catalog: CatalogVersion, - household_id: UUID, - *, - reform_policy_id: UUID | None = None, - with_reform: bool = True, -) -> NewHouseholdReport: - return NewHouseholdReport( - id=uuid4(), - run_id=uuid4(), - country="us", - label="A larger child tax credit", - description="For one family", - tax_benefit_model_id=catalog.model_id, - tax_benefit_model_version_id=catalog.version_id, - household_id=household_id, - year=2026, - versions=VERSIONS, - inputs=OPTIONS, - baseline=HouseholdReportSimulation( - simulation_id=uuid4(), simulation_run_id=uuid4(), policy_id=None - ), - reform=( - HouseholdReportSimulation( - simulation_id=uuid4(), - simulation_run_id=uuid4(), - policy_id=reform_policy_id, - ) - if with_reform - else None - ), - ) - - def _row(connection: Connection, table_name: str, row_id: UUID) -> dict: return dict( connection.execute( @@ -236,127 +196,24 @@ def test_a_policy_setting_a_parameter_the_version_lacks_is_refused_on_its_side( assert refused.value.error.parameter_names == ("gov.removed.parameter",) -def test_a_household_report_is_created_with_its_simulations_and_pending_runs( - public_api_database_url, -) -> None: - with rolled_back_transaction(public_api_database_url) as connection: - catalog = _catalog(connection) - household_id = _household(connection) - policy_id = insert_policy(connection, catalog) - act_as_the_service(connection) - report = _new_report(catalog, household_id, reform_policy_id=policy_id) - assert report.reform is not None - - _store_on(connection).create_report(report) - stored_report = _row(connection, "reports", report.id) - stored_run = _row(connection, "report_runs", report.run_id) - simulations = [ - _row(connection, "simulations", side.simulation_id) - for side in (report.baseline, report.reform) - ] - simulation_runs = [ - _row(connection, "simulation_runs", side.simulation_run_id) - for side in (report.baseline, report.reform) - ] - - assert report.simulation_run_ids == ( - report.baseline.simulation_run_id, - report.reform.simulation_run_id, - ) - assert { - key: stored_report[key] - for key in ( - "label", - "description", - "country", - "type", - "tax_benefit_model_id", - "policy_id", - "baseline_simulation_id", - "reform_simulation_id", - "household_id", - "dataset_id", - "region_id", - "year", - "budget_window_size", - "inputs", - ) - } == { - "label": "A larger child tax credit", - "description": "For one family", - "country": "us", - "type": "household", - "tax_benefit_model_id": catalog.model_id, - "policy_id": policy_id, - "baseline_simulation_id": report.baseline.simulation_id, - "reform_simulation_id": report.reform.simulation_id, - "household_id": household_id, - "dataset_id": None, - "region_id": None, - "year": 2026, - "budget_window_size": None, - "inputs": OPTIONS, - } - assert (stored_run["status"], stored_run["trigger"]) == ("pending", "initial") - assert stored_run["modal_call_id"] is None - assert ( - stored_run["baseline_simulation_run_id"], - stored_run["reform_simulation_run_id"], - ) == report.simulation_run_ids - assert ( - stored_run["country_package_version"], - stored_run["policyengine_version"], - ) == ("1.764.6", POLICYENGINE_VERSION) - assert [simulation["simulation_type"] for simulation in simulations] == [ - "household", - "household", - ] - assert [simulation["policy_id"] for simulation in simulations] == [ - None, - policy_id, - ] - for simulation in simulations: - assert simulation["household_id"] == household_id - assert simulation["tax_benefit_model_version_id"] == catalog.version_id - assert (simulation["dataset_id"], simulation["region_id"]) == (None, None) - assert (simulation["dynamic_id"], simulation["year"]) == (None, 2026) - for run in simulation_runs: - assert (run["status"], run["modal_call_id"]) == ("pending", None) - assert (run["dataset_id"], run["region_id"], run["year"]) == (None, None, 2026) - assert run["household_result"] is None - assert run["policyengine_version"] == POLICYENGINE_VERSION - - -def test_a_report_of_the_baseline_alone_names_no_reform( - public_api_database_url, -) -> None: - with rolled_back_transaction(public_api_database_url) as connection: - catalog = _catalog(connection) - household_id = _household(connection) - act_as_the_service(connection) - report = _new_report(catalog, household_id, with_reform=False) - - _store_on(connection).create_report(report) - stored_report = _row(connection, "reports", report.id) - stored_run = _row(connection, "report_runs", report.run_id) - - assert report.simulation_run_ids == (report.baseline.simulation_run_id,) - assert stored_report["reform_simulation_id"] is None - assert stored_report["policy_id"] is None - assert stored_run["reform_simulation_run_id"] is None - - def test_a_report_run_records_its_call_or_is_failed_with_its_runs( public_api_database_url, ) -> None: with rolled_back_transaction(public_api_database_url) as connection: catalog = _catalog(connection) household_id = _household(connection) + recorded, refused = ( + insert_household_report_rows( + connection, + catalog, + household_id=household_id, + year=2026, + versions=VERSIONS, + ) + for _ in range(2) + ) act_as_the_service(connection) store = _store_on(connection) - recorded, refused = (_new_report(catalog, household_id) for _ in range(2)) - store.create_report(recorded) - store.create_report(refused) status = store.record_report_call(recorded.run_id, "fc-household") recorded_not_failed = store.fail_unstarted_report( @@ -386,67 +243,3 @@ def test_a_report_run_records_its_call_or_is_failed_with_its_runs( "modal_call_refused: no", ) assert [run["status"] for run in refused_simulation_runs] == ["failed", "failed"] - - -def test_a_report_naming_a_missing_household_is_refused_by_its_key( - public_api_database_url, -) -> None: - with rolled_back_transaction(public_api_database_url) as connection: - catalog = _catalog(connection) - act_as_the_service(connection) - - with pytest.raises(EconomyRecordReferenceError) as refused: - _store_on(connection).create_report(_new_report(catalog, uuid4())) - - assert refused.value.column_name == "household_id" - - -class _CommitFails: - """A transaction whose block runs, and whose commit then fails.""" - - def __init__(self, connection) -> None: - self.connection = connection - - def __enter__(self): - return self.connection - - def __exit__(self, error_type, error, traceback) -> None: - if error is None: - statement = "COMMIT" - raise OperationalError(statement, {}, Exception("connection lost")) - - -class _RecordingConnection: - def __init__(self) -> None: - self.statements: list[object] = [] - - def execute(self, statement, *arguments): - self.statements.append(statement) - - -def test_a_create_whose_commit_fails_may_have_been_written() -> None: - connection = _RecordingConnection() - store = HouseholdReportStore(lambda: _CommitFails(connection)) - catalog_rows = {"model_id": uuid4(), "version_id": uuid4()} - - with pytest.raises(EconomyRecordOutcomeUnknownError) as raised: - store.create_report( - NewHouseholdReport( - id=uuid4(), - run_id=uuid4(), - country="us", - label="Lost commit", - description=None, - tax_benefit_model_id=catalog_rows["model_id"], - tax_benefit_model_version_id=catalog_rows["version_id"], - household_id=uuid4(), - year=2026, - versions=VERSIONS, - inputs=OPTIONS, - baseline=HouseholdReportSimulation(uuid4(), uuid4(), None), - reform=None, - ) - ) - - assert isinstance(raised.value.__cause__, OperationalError) - assert connection.statements diff --git a/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py b/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py new file mode 100644 index 000000000..592b06423 --- /dev/null +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py @@ -0,0 +1,694 @@ +"""Find economy reports, simulations and their runs by key, or create them. + +Identical requests, together or apart, end on the same simulation, report +and run rows (C1 · 24), and only the request that inserted a run starts its +Modal call. These run against a database the Public API's own v2 migration +chain built (``PUBLIC_API_SCHEMA_DATABASE_URL``), as the simulation +service's role, most in a transaction rolled back afterwards; the tests of +two transactions commit their rows under a catalog of their own, which +``conftest`` deletes afterwards. +""" + +from __future__ import annotations + +import threading +from contextlib import contextmanager +from dataclasses import replace +from typing import TYPE_CHECKING, Any +from uuid import UUID, uuid4 + +import pytest +from committed_rows import ( + LOCK_WAIT_TIMEOUT_SECONDS, + run_together, + wait_until_another_backend_waits_for, +) +from conftest import act_as_the_service, rolled_back_transaction +from economy_rows import ( + CURRENT_LAW, + VERSIONS, + EconomyCatalog, + insert_economy_catalog, +) +from policyengine_simulation_persistence import ( + KEY_VERSION, + EconomyRecordReferenceError, + EconomyReportDefinition, + EconomyRunStore, + EconomySimulationDefinition, + KeyedEconomyReport, + KeyedEconomySimulation, + NewReportRerun, + ProposedSide, + ReportRunStatus, + RerunSide, + SimulationChoice, + SimulationStatus, + find_or_create_economy_report, + find_or_create_economy_simulation, + insert_report_rerun, + read_report_definition, + report_runs, + simulation_runs, +) +from public_api_rows import insert_policy +from sqlalchemy import event, func, insert, select, text, update + +if TYPE_CHECKING: + from collections.abc import Iterator + + from sqlalchemy import Connection + +pytestmark = pytest.mark.public_api_schema + +NATIONAL_SPM = {"geography_kind": "national"} + + +def _keyed_report( + economy: EconomyCatalog, + *, + reform: SimulationChoice = CURRENT_LAW, + spm: dict[str, Any] | None = None, +) -> KeyedEconomyReport: + """Return a request's report on ``economy``, with fresh IDs to propose.""" + definition = EconomyReportDefinition( + country=economy.catalog.country, + baseline=CURRENT_LAW, + reform=reform, + dataset_name="populace_us_2024", + region_code="us", + year=2026, + budget_window_size=None, + spm=spm, + ) + return KeyedEconomyReport( + definition=definition, + report_id=uuid4(), + run_id=uuid4(), + baseline=ProposedSide(simulation_id=uuid4(), simulation_run_id=uuid4()), + reform=ProposedSide(simulation_id=uuid4(), simulation_run_id=uuid4()), + tax_benefit_model_id=economy.catalog.model_id, + population=economy.population(), + versions=VERSIONS, + inputs={} if spm is None else {"spm": spm}, + ) + + +def _keyed_simulation( + economy: EconomyCatalog, choice: SimulationChoice = CURRENT_LAW +) -> KeyedEconomySimulation: + return KeyedEconomySimulation( + definition=EconomySimulationDefinition( + country=economy.catalog.country, + choice=choice, + dataset_name="populace_us_2024", + region_code="us", + year=2026, + spm=None, + ), + simulation_id=uuid4(), + run_id=uuid4(), + population=economy.population(), + versions=VERSIONS, + ) + + +def _row(connection: Connection, table_name: str, row_id: UUID) -> dict: + row = connection.execute( + text(f"SELECT * FROM public.{table_name} WHERE id = :id"), # noqa: S608 # fixed table names + {"id": row_id}, + ).mappings() + return dict(row.one()) + + +def _count(connection: Connection, table_name: str) -> int: + return connection.execute( + text(f"SELECT count(*) FROM public.{table_name}") # noqa: S608 # fixed table names + ).scalar_one() + + +def _set_status( + connection: Connection, table_name: str, row_id: UUID, status: str +) -> None: + """Set a run's status as the superuser, as a worker or the sweep would.""" + table = report_runs if table_name == "report_runs" else simulation_runs + ended = status in {"succeeded", "failed"} + connection.execute(text("RESET ROLE")) + connection.execute( + update(table) + .where(table.c.id == row_id) + .values(status=status, completed_at=func.now() if ended else None) + ) + act_as_the_service(connection) + + +def test_a_keyed_report_is_created_with_its_simulations_and_first_run( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + policy_id = insert_policy(connection, economy.catalog) + request = _keyed_report( + economy, + reform=SimulationChoice(policy_id=policy_id, dynamic_id=None), + spm=NATIONAL_SPM, + ) + act_as_the_service(connection) + + found = find_or_create_economy_report(connection, request) + report = _row(connection, "reports", found.report_id) + run = _row(connection, "report_runs", found.run.id) + baseline = _row(connection, "simulations", found.baseline.simulation_id) + reform = _row(connection, "simulations", found.reform.simulation_id) + reform_run = _row(connection, "simulation_runs", found.reform.simulation_run_id) + + definition = request.definition + assert (found.report_id, found.report_inserted) == (request.report_id, True) + assert (found.run.id, found.run.inserted) == (request.run_id, True) + assert found.run.status is ReportRunStatus.PENDING + assert found.baseline.simulation_id == request.baseline.simulation_id + assert found.reform.simulation_id == request.reform.simulation_id + assert found.baseline.run_inserted + assert found.reform.run_inserted + assert (found.baseline.simulation_run_id, found.reform.simulation_run_id) == ( + request.baseline.simulation_run_id, + request.reform.simulation_run_id, + ) + assert { + name: report[name] + for name in ( + "key_version", + "definition_key", + "dataset_independent_key", + "baseline_simulation_id", + "reform_simulation_id", + "policy_id", + "inputs", + "type", + "budget_window_size", + "label", + "description", + "user_id", + ) + } == { + "key_version": KEY_VERSION, + "definition_key": definition.definition_key, + "dataset_independent_key": definition.dataset_independent_key, + "baseline_simulation_id": request.baseline.simulation_id, + "reform_simulation_id": request.reform.simulation_id, + "policy_id": policy_id, + "inputs": {"spm": NATIONAL_SPM}, + "type": "economy", + "budget_window_size": None, + # Answer 6: a shared report holds no request's label or user. + "label": None, + "description": None, + "user_id": None, + } + assert (baseline["key_version"], baseline["definition_key"]) == ( + KEY_VERSION, + definition.simulation("baseline").definition_key, + ) + assert reform["definition_key"] == definition.simulation("reform").definition_key + # Answer 6: the trigger is each user's record's, not the shared run's. + assert (run["status"], run["forced"], run["trigger"]) == ( + ReportRunStatus.PENDING, + False, + None, + ) + assert ( + reform_run["status"], + reform_run["forced"], + reform_run["modal_call_id"], + ) == ( + SimulationStatus.PENDING, + False, + None, + ) + + +def test_an_identical_request_ends_on_the_same_rows_and_inserts_nothing( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + act_as_the_service(connection) + first = find_or_create_economy_report( + connection, _keyed_report(economy, spm=NATIONAL_SPM) + ) + counts = [ + _count(connection, name) + for name in ("simulations", "reports", "simulation_runs", "report_runs") + ] + + again = find_or_create_economy_report( + connection, _keyed_report(economy, spm=NATIONAL_SPM) + ) + counts_after = [ + _count(connection, name) + for name in ("simulations", "reports", "simulation_runs", "report_runs") + ] + + assert (again.report_id, again.run.id) == (first.report_id, first.run.id) + assert (again.baseline.simulation_run_id, again.reform.simulation_run_id) == ( + first.baseline.simulation_run_id, + first.reform.simulation_run_id, + ) + assert (again.report_inserted, again.run.inserted) == (False, False) + assert not again.baseline.run_inserted + assert not again.reform.run_inserted + assert counts_after == counts + + +def test_the_same_policy_on_both_sides_names_one_simulation_run_twice( + public_api_database_url, +) -> None: + """Current law against current law, as the staging check sends.""" + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + request = _keyed_report(economy) + act_as_the_service(connection) + + found = find_or_create_economy_report(connection, request) + run = _row(connection, "report_runs", found.run.id) + simulation_count = _count(connection, "simulations") + + assert found.baseline == found.reform + assert found.baseline.simulation_run_id == request.baseline.simulation_run_id + assert found.baseline.run_inserted + assert run["baseline_simulation_run_id"] == run["reform_simulation_run_id"] + assert simulation_count == 1 + + +def test_a_report_whose_run_failed_gets_a_new_run_joining_its_simulation_runs( + public_api_database_url, +) -> None: + """Answer 2: a failed run never counts; the unfailed simulation runs do.""" + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + policy_id = insert_policy(connection, economy.catalog) + reform = SimulationChoice(policy_id=policy_id, dynamic_id=None) + act_as_the_service(connection) + first = find_or_create_economy_report( + connection, _keyed_report(economy, reform=reform) + ) + _set_status( + connection, "simulation_runs", first.baseline.simulation_run_id, "succeeded" + ) + _set_status( + connection, "simulation_runs", first.reform.simulation_run_id, "failed" + ) + _set_status(connection, "report_runs", first.run.id, "failed") + + second = find_or_create_economy_report( + connection, _keyed_report(economy, reform=reform) + ) + + assert second.report_id == first.report_id + assert second.run.inserted is True + assert second.run.id != first.run.id + assert second.baseline.simulation_run_id == first.baseline.simulation_run_id + assert second.baseline.run_inserted is False + assert second.reform.run_inserted is True + assert second.reform.simulation_run_id != first.reform.simulation_run_id + + +def test_a_forced_run_is_never_joined_by_a_create(public_api_database_url) -> None: + """Answer 3: a forced re-run's runs are an extra run nobody joins.""" + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + act_as_the_service(connection) + first = find_or_create_economy_report(connection, _keyed_report(economy)) + _set_status( + connection, "simulation_runs", first.baseline.simulation_run_id, "failed" + ) + _set_status(connection, "report_runs", first.run.id, "failed") + forced_simulation_run_id = uuid4() + connection.execute( + insert(simulation_runs).values( + id=forced_simulation_run_id, + simulation_id=first.baseline.simulation_id, + year=2026, + tax_benefit_model_version_id=economy.catalog.version_id, + country_package_version=VERSIONS.country_package_version, + policyengine_version=VERSIONS.policyengine_version, + dataset_id=economy.dataset_id, + region_id=economy.region_id, + status=SimulationStatus.PENDING, + forced=True, + ) + ) + connection.execute( + insert(report_runs).values( + id=uuid4(), + report_id=first.report_id, + baseline_simulation_run_id=forced_simulation_run_id, + reform_simulation_run_id=forced_simulation_run_id, + country_package_version=VERSIONS.country_package_version, + policyengine_version=VERSIONS.policyengine_version, + status=ReportRunStatus.PENDING, + trigger="manual", + forced=True, + ) + ) + + second = find_or_create_economy_report(connection, _keyed_report(economy)) + + assert second.run.inserted is True + assert second.baseline.run_inserted is True + assert forced_simulation_run_id not in { + second.baseline.simulation_run_id, + second.reform.simulation_run_id, + } + + +def test_another_spm_selection_is_another_report_with_other_simulations( + public_api_database_url, +) -> None: + """Answer 4c: the SPM selection changes a simulation's own numbers.""" + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + act_as_the_service(connection) + + without = find_or_create_economy_report(connection, _keyed_report(economy)) + national = find_or_create_economy_report( + connection, _keyed_report(economy, spm=NATIONAL_SPM) + ) + + assert national.report_id != without.report_id + assert national.baseline.simulation_id != without.baseline.simulation_id + assert national.run.inserted is True + + +def test_a_report_sharing_a_side_with_another_names_that_sides_run_under_way( + public_api_database_url, +) -> None: + """Answer 5: a pending or running simulation run is joined.""" + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + first_policy = insert_policy(connection, economy.catalog) + second_policy = insert_policy(connection, economy.catalog) + act_as_the_service(connection) + first = find_or_create_economy_report( + connection, + _keyed_report(economy, reform=SimulationChoice(first_policy, None)), + ) + _set_status( + connection, "simulation_runs", first.baseline.simulation_run_id, "running" + ) + + second = find_or_create_economy_report( + connection, + _keyed_report(economy, reform=SimulationChoice(second_policy, None)), + ) + + assert second.report_id != first.report_id + assert second.run.inserted is True + assert second.baseline.simulation_id == first.baseline.simulation_id + assert second.baseline.simulation_run_id == first.baseline.simulation_run_id + assert second.baseline.run_inserted is False + assert second.reform.run_inserted is True + + +def test_a_keyed_simulation_joins_its_run_or_creates_it( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + act_as_the_service(connection) + report = find_or_create_economy_report(connection, _keyed_report(economy)) + + # The report's current-law simulation is this request's simulation. + joined = find_or_create_economy_simulation( + connection, _keyed_simulation(economy) + ) + _set_status( + connection, "simulation_runs", report.baseline.simulation_run_id, "failed" + ) + request = _keyed_simulation(economy) + created = find_or_create_economy_simulation(connection, request) + simulation = _row(connection, "simulations", created.simulation_id) + + assert (joined.simulation_id, joined.run.id) == ( + report.baseline.simulation_id, + report.baseline.simulation_run_id, + ) + assert (joined.simulation_inserted, joined.run.inserted) == (False, False) + assert joined.run.status is SimulationStatus.PENDING + assert created.simulation_id == report.baseline.simulation_id + assert (created.run.id, created.run.inserted) == (request.run_id, True) + assert simulation["definition_key"] == request.definition.definition_key + + +def test_two_identical_requests_at_once_end_on_the_same_rows_and_start_one_call( + committed_engine, committed_catalog +) -> None: + """The first holds its transaction open until the second waits on its rows. + + Each request starts a Modal call only for a report run it inserted, as + the service does; exactly one does. + """ + economy = committed_catalog + first_has_inserted = threading.Event() + found: dict[str, Any] = {} + started_calls: list[UUID] = [] + + def create_and_start(connection: Connection, name: str) -> None: + act_as_the_service(connection) + result = find_or_create_economy_report(connection, _keyed_report(economy)) + found[name] = result + if result.run.inserted: + started_calls.append(result.run.id) + + def first_request() -> None: + with committed_engine.begin() as connection: + create_and_start(connection, "first") + holder_pid = connection.execute(select(func.pg_backend_pid())).scalar_one() + first_has_inserted.set() + wait_until_another_backend_waits_for(committed_engine, holder_pid) + + def second_request() -> None: + assert first_has_inserted.wait(LOCK_WAIT_TIMEOUT_SECONDS) + with committed_engine.begin() as connection: + create_and_start(connection, "second") + + run_together((first_request, second_request), released=first_has_inserted) + + first, second = found["first"], found["second"] + assert (second.report_id, second.run.id) == (first.report_id, first.run.id) + assert second.baseline == replace(first.baseline, run_inserted=False) + assert started_calls == [first.run.id] + + +def test_a_request_losing_the_report_run_to_another_joins_it_and_keeps_nothing( + committed_engine, committed_catalog +) -> None: + """Another request inserts the report run between this one's lookup and insert.""" + economy = committed_catalog + with committed_engine.begin() as connection: + act_as_the_service(connection) + first = find_or_create_economy_report(connection, _keyed_report(economy)) + with committed_engine.begin() as connection: + connection.execute( + update(simulation_runs) + .where(simulation_runs.c.id == first.baseline.simulation_run_id) + .values(status=SimulationStatus.FAILED, completed_at=func.now()) + ) + connection.execute( + update(report_runs) + .where(report_runs.c.id == first.run.id) + .values(status=ReportRunStatus.FAILED, completed_at=func.now()) + ) + competing: list[UUID] = [] + request = _keyed_report(economy) + + def create_a_competing_run_first( + _connection, _cursor, statement, _parameters, _context, _executemany + ) -> None: + if competing or not statement.lstrip().startswith( + "INSERT INTO public.report_runs" + ): + return + # As the superuser, naming the first run's simulation runs, so it waits + # on nothing this transaction holds. + run_id = uuid4() + with committed_engine.begin() as other: + other.execute( + insert(report_runs).values( + id=run_id, + report_id=first.report_id, + baseline_simulation_run_id=first.baseline.simulation_run_id, + reform_simulation_run_id=first.reform.simulation_run_id, + country_package_version=VERSIONS.country_package_version, + policyengine_version=VERSIONS.policyengine_version, + status=ReportRunStatus.PENDING, + trigger="initial", + ) + ) + competing.append(run_id) + + with committed_engine.begin() as connection: + act_as_the_service(connection) + event.listen(connection, "before_cursor_execute", create_a_competing_run_first) + try: + joined = find_or_create_economy_report(connection, request) + finally: + event.remove( + connection, "before_cursor_execute", create_a_competing_run_first + ) + kept = connection.execute( + select(func.count()) + .select_from(simulation_runs) + .where(simulation_runs.c.id == request.baseline.simulation_run_id) + ).scalar_one() + + assert (joined.run.id, joined.run.inserted) == (competing[0], False) + assert joined.baseline.run_inserted is False + assert kept == 0 + + +def _store_on(connection: Connection) -> EconomyRunStore: + """Return a store whose transactions are savepoints of ``connection``.""" + + @contextmanager + def savepoint() -> Iterator[Connection]: + with connection.begin_nested(): + yield connection + + return EconomyRunStore(savepoint) + + +def test_the_store_finds_or_creates_reports_and_simulations_in_a_transaction( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + act_as_the_service(connection) + store = _store_on(connection) + + created = store.find_or_create_report(_keyed_report(economy)) + joined = store.find_or_create_report(_keyed_report(economy)) + simulation = store.find_or_create_simulation(_keyed_simulation(economy)) + + assert created.run.inserted is True + assert (joined.run.id, joined.run.inserted) == (created.run.id, False) + assert (simulation.simulation_id, simulation.run.id) == ( + created.baseline.simulation_id, + created.baseline.simulation_run_id, + ) + + +def test_a_keyed_reports_rerun_joins_each_sides_run_on_its_versions( + public_api_database_url, +) -> None: + """Answers 4 and 5: a side joins its simulation's unfailed run, in any state.""" + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + policy_id = insert_policy(connection, economy.catalog) + act_as_the_service(connection) + created = find_or_create_economy_report( + connection, + _keyed_report(economy, reform=SimulationChoice(policy_id, None)), + ) + _set_status( + connection, + "simulation_runs", + created.baseline.simulation_run_id, + "succeeded", + ) + _set_status(connection, "report_runs", created.run.id, "failed") + definition = read_report_definition(connection, created.report_id) + rerun = NewReportRerun( + report_id=created.report_id, + run_id=uuid4(), + population=economy.population(), + versions=VERSIONS, + baseline=RerunSide(created.baseline.simulation_id, uuid4()), + reform=RerunSide(created.reform.simulation_id, uuid4()), + ) + + found = insert_report_rerun(connection, rerun) + + assert definition is not None + assert definition.keyed is True + assert (found.id, found.inserted) == (rerun.run_id, True) + assert (found.baseline_simulation_run_id, found.reform_simulation_run_id) == ( + created.baseline.simulation_run_id, + created.reform.simulation_run_id, + ) + + +def test_a_keyed_rerun_with_one_simulation_on_both_sides_inserts_one_run( + public_api_database_url, +) -> None: + """Current law against current law: one new run, named on both sides.""" + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + act_as_the_service(connection) + created = find_or_create_economy_report(connection, _keyed_report(economy)) + _set_status( + connection, "simulation_runs", created.baseline.simulation_run_id, "failed" + ) + _set_status(connection, "report_runs", created.run.id, "failed") + simulation_id = created.baseline.simulation_id + rerun = NewReportRerun( + report_id=created.report_id, + run_id=uuid4(), + population=economy.population(), + versions=VERSIONS, + baseline=RerunSide(simulation_id, uuid4()), + reform=RerunSide(simulation_id, uuid4()), + ) + + found = insert_report_rerun(connection, rerun) + runs = connection.execute( + select(func.count()) + .select_from(simulation_runs) + .where(simulation_runs.c.simulation_id == simulation_id) + ).scalar_one() + + assert found.inserted is True + assert ( + found.baseline_simulation_run_id + == found.reform_simulation_run_id + == rerun.baseline.simulation_run_id + ) + assert runs == 2 + + +@pytest.mark.parametrize( + ("missing_row", "column_name"), + [ + ("region", "region_id"), + ("dataset", "dataset_id"), + ("dynamic", "dynamic_id"), + ("policy", "policy_id"), + ], +) +def test_a_report_naming_a_missing_row_names_the_column_that_refused_it( + public_api_database_url, missing_row: str, column_name: str +) -> None: + """The service answers each such column with its own refusal code.""" + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + report = _keyed_report( + economy, + reform={ + "dynamic": SimulationChoice(policy_id=None, dynamic_id=uuid4()), + "policy": SimulationChoice(policy_id=uuid4(), dynamic_id=None), + }.get(missing_row, CURRENT_LAW), + ) + if missing_row in {"region", "dataset"}: + report = replace( + report, + population=replace(report.population, **{column_name: uuid4()}), + ) + act_as_the_service(connection) + + with pytest.raises(EconomyRecordReferenceError) as refused: + find_or_create_economy_report(connection, report) + + assert (refused.value.table_name, refused.value.column_name) == ( + "simulations", + column_name, + ) diff --git a/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py b/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py new file mode 100644 index 000000000..120d20a70 --- /dev/null +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py @@ -0,0 +1,528 @@ +"""Find household reports and their runs by key, or create them (answer 8). + +Identical household report requests, together or apart, end on the same +simulation, report and run rows, as economy ones do. These run against a +database the Public API's own v2 migration chain built +(``PUBLIC_API_SCHEMA_DATABASE_URL``), as the simulation service's role, in +a transaction rolled back afterwards. +""" + +from __future__ import annotations + +from contextlib import contextmanager +from dataclasses import dataclass, replace +from typing import TYPE_CHECKING +from uuid import UUID, uuid4 + +import pytest +from conftest import act_as_the_service, rolled_back_transaction +from policyengine_simulation_persistence import ( + KEY_VERSION, + EconomyRecordReferenceError, + FoundHouseholdReport, + FoundSide, + HouseholdReportDefinition, + HouseholdReportStore, + HouseholdRerunSide, + KeyedHouseholdReport, + NewHouseholdReportRerun, + ProposedSide, + ReportRunStatus, + RunVersions, + SimulationChoice, + SimulationStatus, + find_or_create_household_report, + insert_household_report_rerun, +) +from public_api_rows import ( + CatalogVersion, + insert_catalog_version, + insert_household, + insert_model, + insert_policy, +) +from sqlalchemy import text + +if TYPE_CHECKING: + from collections.abc import Iterator + + from sqlalchemy import Connection + +pytestmark = pytest.mark.public_api_schema + +VERSIONS = RunVersions(country_package_version="1.764.6", policyengine_version="6.17.1") +CURRENT_LAW = SimulationChoice(policy_id=None, dynamic_id=None) +DOCUMENT = { + "people": [ + { + "id": "you", + "values": {"age": 40}, + "memberships": {"household": "your household"}, + } + ], + "household": [{"id": "your household", "values": {}}], +} + + +@dataclass(frozen=True) +class _StoredInputs: + """What a household report names: a catalog version, a household and a policy.""" + + catalog: CatalogVersion + household_id: UUID + reform_policy_id: UUID + + @property + def reform(self) -> SimulationChoice: + return SimulationChoice(policy_id=self.reform_policy_id, dynamic_id=None) + + +def _stored_inputs(connection: Connection) -> _StoredInputs: + """Insert the US model's catalog version, a household and a policy.""" + catalog = insert_catalog_version( + connection, + country="us", + model_id=insert_model(connection, "us"), + policyengine_version=VERSIONS.policyengine_version, + ) + return _StoredInputs( + catalog=catalog, + household_id=insert_household( + connection, country="us", default_year=2026, document=DOCUMENT + ), + reform_policy_id=insert_policy(connection, catalog), + ) + + +def _keyed_report( + stored: _StoredInputs, *, reform: SimulationChoice | None +) -> KeyedHouseholdReport: + """Return a request's household report, with fresh IDs to propose.""" + return KeyedHouseholdReport( + definition=HouseholdReportDefinition( + country="us", + baseline=CURRENT_LAW, + reform=reform, + household_id=stored.household_id, + year=2026, + ), + report_id=uuid4(), + run_id=uuid4(), + baseline=ProposedSide(simulation_id=uuid4(), simulation_run_id=uuid4()), + reform=( + None + if reform is None + else ProposedSide(simulation_id=uuid4(), simulation_run_id=uuid4()) + ), + tax_benefit_model_id=stored.catalog.model_id, + tax_benefit_model_version_id=stored.catalog.version_id, + versions=VERSIONS, + ) + + +def _row(connection: Connection, table_name: str, row_id: UUID) -> dict: + row = connection.execute( + text(f"SELECT * FROM public.{table_name} WHERE id = :id"), # noqa: S608 # fixed table names + {"id": row_id}, + ).mappings() + return dict(row.one()) + + +def _count(connection: Connection, table_name: str) -> int: + return connection.execute( + text(f"SELECT count(*) FROM public.{table_name}") # noqa: S608 # fixed table names + ).scalar_one() + + +def _fail_report_run(connection: Connection, run_id: UUID) -> None: + """Fail a report run as the superuser, as the household function would.""" + connection.execute(text("RESET ROLE")) + connection.execute( + text( + "UPDATE public.report_runs SET status = 'failed', completed_at = now() " + "WHERE id = :id" + ), + {"id": run_id}, + ) + act_as_the_service(connection) + + +def test_a_keyed_household_report_is_created_with_its_simulations_and_first_run( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + stored = _stored_inputs(connection) + request = _keyed_report(stored, reform=stored.reform) + act_as_the_service(connection) + + found = find_or_create_household_report(connection, request) + report = _row(connection, "reports", found.report_id) + report_run = _row(connection, "report_runs", found.run.id) + sides = { + "baseline": found.baseline, + "reform": found.reform, + } + stored_sides = { + side: ( + _row(connection, "simulations", found_side.simulation_id), + _row(connection, "simulation_runs", found_side.simulation_run_id), + ) + for side, found_side in sides.items() + if found_side is not None + } + + assert request.reform is not None + assert (found.report_id, found.report_inserted) == (request.report_id, True) + assert (found.run.id, found.run.inserted, found.run.status) == ( + request.run_id, + True, + ReportRunStatus.PENDING, + ) + assert found.baseline == FoundSide( + simulation_id=request.baseline.simulation_id, + simulation_run_id=request.baseline.simulation_run_id, + run_inserted=True, + ) + assert found.reform == FoundSide( + simulation_id=request.reform.simulation_id, + simulation_run_id=request.reform.simulation_run_id, + run_inserted=True, + ) + definition = request.definition + assert { + name: report[name] + for name in ( + "type", + "country", + "household_id", + "policy_id", + "dataset_id", + "region_id", + "year", + "budget_window_size", + "inputs", + "key_version", + "definition_key", + "dataset_independent_key", + "label", + "description", + "user_id", + ) + } == { + "type": "household", + "country": "us", + "household_id": stored.household_id, + "policy_id": stored.reform_policy_id, + "dataset_id": None, + "region_id": None, + "year": 2026, + "budget_window_size": None, + "inputs": {}, + "key_version": KEY_VERSION, + "definition_key": definition.definition_key, + "dataset_independent_key": definition.dataset_independent_key, + # Answer 6: a shared report holds no request's label or user. + "label": None, + "description": None, + "user_id": None, + } + assert (report["baseline_simulation_id"], report["reform_simulation_id"]) == ( + request.baseline.simulation_id, + request.reform.simulation_id, + ) + assert report_run["trigger"] is None + assert report_run["forced"] is False + assert ( + report_run["baseline_simulation_run_id"], + report_run["reform_simulation_run_id"], + ) == (request.baseline.simulation_run_id, request.reform.simulation_run_id) + for side, (simulation, simulation_run) in stored_sides.items(): + assert simulation["simulation_type"] == "household" + assert simulation["household_id"] == stored.household_id + assert (simulation["dataset_id"], simulation["region_id"]) == (None, None) + assert simulation["key_version"] == KEY_VERSION + side_key = definition.simulation(side).definition_key + assert simulation["definition_key"] == side_key + assert simulation_run["status"] == SimulationStatus.PENDING + assert (simulation_run["year"], simulation_run["forced"]) == (2026, False) + assert simulation_run["tax_benefit_model_version_id"] == ( + stored.catalog.version_id + ) + assert ( + simulation_run["country_package_version"], + simulation_run["policyengine_version"], + ) == (VERSIONS.country_package_version, VERSIONS.policyengine_version) + + +def test_an_identical_household_request_ends_on_the_same_rows_and_inserts_nothing( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + stored = _stored_inputs(connection) + act_as_the_service(connection) + first = find_or_create_household_report( + connection, _keyed_report(stored, reform=stored.reform) + ) + counts = [ + _count(connection, name) + for name in ("simulations", "reports", "simulation_runs", "report_runs") + ] + + again = find_or_create_household_report( + connection, _keyed_report(stored, reform=stored.reform) + ) + counts_again = [ + _count(connection, name) + for name in ("simulations", "reports", "simulation_runs", "report_runs") + ] + + assert (again.report_id, again.report_inserted) == (first.report_id, False) + assert (again.run.id, again.run.inserted) == (first.run.id, False) + assert again.baseline == replace(first.baseline, run_inserted=False) + assert again.reform == replace(first.reform, run_inserted=False) + assert counts_again == counts + + +def test_a_household_policy_compared_with_itself_names_one_simulation_run_twice( + public_api_database_url, +) -> None: + """Its two sides are one simulation, so one run, with the baseline's ID.""" + with rolled_back_transaction(public_api_database_url) as connection: + stored = _stored_inputs(connection) + request = _keyed_report(stored, reform=CURRENT_LAW) + act_as_the_service(connection) + + found = find_or_create_household_report(connection, request) + report_run = _row(connection, "report_runs", found.run.id) + + assert found.reform is not None + assert found.baseline.simulation_id == found.reform.simulation_id + assert found.baseline.simulation_run_id == found.reform.simulation_run_id + assert found.baseline.simulation_run_id == request.baseline.simulation_run_id + assert ( + report_run["baseline_simulation_run_id"] + == (report_run["reform_simulation_run_id"]) + ) + + +def test_a_household_report_of_the_baseline_alone_names_no_reform( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + stored = _stored_inputs(connection) + request = _keyed_report(stored, reform=None) + act_as_the_service(connection) + + found = find_or_create_household_report(connection, request) + again = find_or_create_household_report( + connection, _keyed_report(stored, reform=None) + ) + report = _row(connection, "reports", found.report_id) + report_run = _row(connection, "report_runs", found.run.id) + + assert found.reform is None + assert found.run.reform_simulation_run_id is None + assert (report["reform_simulation_id"], report["policy_id"]) == (None, None) + assert report_run["reform_simulation_run_id"] is None + assert (again.report_id, again.run.id, again.reform) == ( + found.report_id, + found.run.id, + None, + ) + + +def test_a_household_report_sharing_a_side_names_that_sides_run_under_way( + public_api_database_url, +) -> None: + """Answer 5: a report against current law joins current law's pending run.""" + with rolled_back_transaction(public_api_database_url) as connection: + stored = _stored_inputs(connection) + act_as_the_service(connection) + with_reform = find_or_create_household_report( + connection, _keyed_report(stored, reform=stored.reform) + ) + + alone = find_or_create_household_report( + connection, _keyed_report(stored, reform=None) + ) + + assert alone.report_id != with_reform.report_id + assert alone.run.inserted is True + assert alone.baseline == replace(with_reform.baseline, run_inserted=False) + + +def test_a_household_report_whose_run_failed_gets_a_new_run_on_its_simulations( + public_api_database_url, +) -> None: + """Answer 2: a failed report run never counts; its simulation runs still do.""" + with rolled_back_transaction(public_api_database_url) as connection: + stored = _stored_inputs(connection) + act_as_the_service(connection) + first = find_or_create_household_report( + connection, _keyed_report(stored, reform=stored.reform) + ) + _fail_report_run(connection, first.run.id) + + second = find_or_create_household_report( + connection, _keyed_report(stored, reform=stored.reform) + ) + + assert second.report_id == first.report_id + assert (second.run.inserted, second.run.id == first.run.id) == (True, False) + assert second.baseline == replace(first.baseline, run_inserted=False) + assert second.reform == replace(first.reform, run_inserted=False) + + +def test_the_household_store_finds_or_creates_a_report_in_a_transaction( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + stored = _stored_inputs(connection) + act_as_the_service(connection) + + @contextmanager + def savepoint() -> Iterator[Connection]: + with connection.begin_nested(): + yield connection + + store = HouseholdReportStore(savepoint) + found = store.find_or_create_report(_keyed_report(stored, reform=None)) + again = store.find_or_create_report(_keyed_report(stored, reform=None)) + + assert (found.run.inserted, again.run.inserted) == (True, False) + assert again.run.id == found.run.id + + +def test_a_request_proposing_a_reform_side_for_a_report_without_one_is_refused() -> ( + None +): + stored = _StoredInputs( + catalog=CatalogVersion( + country="us", + model_id=uuid4(), + version_id=uuid4(), + policyengine_version=VERSIONS.policyengine_version, + ), + household_id=uuid4(), + reform_policy_id=uuid4(), + ) + request = _keyed_report(stored, reform=None) + + with pytest.raises(ValueError, match="reform side"): + replace( + request, + reform=ProposedSide(simulation_id=uuid4(), simulation_run_id=uuid4()), + ) + + +def _rerun_of( + found: FoundHouseholdReport, stored: _StoredInputs, *, forced: bool = False +) -> NewHouseholdReportRerun: + """Return a re-run of a keyed report on its versions, proposing new run IDs.""" + return NewHouseholdReportRerun( + report_id=found.report_id, + run_id=uuid4(), + tax_benefit_model_version_id=stored.catalog.version_id, + year=2026, + versions=VERSIONS, + baseline=HouseholdRerunSide( + simulation_id=found.baseline.simulation_id, simulation_run_id=uuid4() + ), + reform=( + None + if found.reform is None + else HouseholdRerunSide( + simulation_id=found.reform.simulation_id, simulation_run_id=uuid4() + ) + ), + forced=forced, + ) + + +def test_a_keyed_household_reports_rerun_joins_its_run_on_the_versions( + public_api_database_url, +) -> None: + """Answers 3 and 8: a re-run joins the run under way, creating nothing.""" + with rolled_back_transaction(public_api_database_url) as connection: + stored = _stored_inputs(connection) + act_as_the_service(connection) + found = find_or_create_household_report( + connection, _keyed_report(stored, reform=stored.reform) + ) + counts = [ + _count(connection, name) for name in ("simulation_runs", "report_runs") + ] + + joined = insert_household_report_rerun(connection, _rerun_of(found, stored)) + counts_after = [ + _count(connection, name) for name in ("simulation_runs", "report_runs") + ] + + assert joined == replace(found.run, inserted=False) + assert counts_after == counts + + +def test_a_keyed_household_rerun_after_a_failed_run_names_its_simulations_runs( + public_api_database_url, +) -> None: + """Each side joins its simulation's run on the versions, as a create's does.""" + with rolled_back_transaction(public_api_database_url) as connection: + stored = _stored_inputs(connection) + act_as_the_service(connection) + found = find_or_create_household_report( + connection, _keyed_report(stored, reform=stored.reform) + ) + _fail_report_run(connection, found.run.id) + rerun = _rerun_of(found, stored) + + created = insert_household_report_rerun(connection, rerun) + report_run = _row(connection, "report_runs", created.id) + + assert found.reform is not None + assert (created.id, created.inserted) == (rerun.run_id, True) + assert ( + created.baseline_simulation_run_id, + created.reform_simulation_run_id, + ) == (found.baseline.simulation_run_id, found.reform.simulation_run_id) + assert (report_run["trigger"], report_run["forced"]) == (None, False) + + +def test_a_forced_keyed_household_rerun_is_an_extra_run_beside_the_one_under_way( + public_api_database_url, +) -> None: + """Answer 3: never joined, never refused, on new runs of both sides.""" + with rolled_back_transaction(public_api_database_url) as connection: + stored = _stored_inputs(connection) + act_as_the_service(connection) + found = find_or_create_household_report( + connection, _keyed_report(stored, reform=stored.reform) + ) + rerun = _rerun_of(found, stored, forced=True) + + created = insert_household_report_rerun(connection, rerun) + report_run = _row(connection, "report_runs", created.id) + side_runs = [ + _row(connection, "simulation_runs", run_id) + for run_id in rerun.simulation_run_ids + ] + + assert (created.id, created.inserted) == (rerun.run_id, True) + assert report_run["forced"] is True + assert [side_run["forced"] for side_run in side_runs] == [True, True] + + +def test_a_household_report_naming_a_missing_household_is_refused_by_its_key( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + stored = _stored_inputs(connection) + report = _keyed_report(stored, reform=None) + missing_household = replace( + report, definition=replace(report.definition, household_id=uuid4()) + ) + act_as_the_service(connection) + + with pytest.raises(EconomyRecordReferenceError) as refused: + find_or_create_household_report(connection, missing_household) + + assert refused.value.column_name == "household_id" diff --git a/libs/policyengine-simulation-persistence/tests/test_keyed_window_records.py b/libs/policyengine-simulation-persistence/tests/test_keyed_window_records.py new file mode 100644 index 000000000..746f4355b --- /dev/null +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_window_records.py @@ -0,0 +1,479 @@ +"""Find budget windows and their window runs by key, or create them (answer 8). + +A budget window's report is keyed with its window size; each year has its +own simulations, keyed by that year, and there is one window run per +report and version set that hasn't failed and isn't a recalculation. These +run against a database the Public API's own v2 migration chain built +(``PUBLIC_API_SCHEMA_DATABASE_URL``), as the simulation service's role, in +a transaction rolled back afterwards. +""" + +from __future__ import annotations + +import threading +from contextlib import contextmanager +from dataclasses import replace +from typing import TYPE_CHECKING +from uuid import UUID, uuid4 + +import pytest +from committed_rows import ( + LOCK_WAIT_TIMEOUT_SECONDS, + run_together, + wait_until_another_backend_waits_for, +) +from conftest import act_as_the_service, rolled_back_transaction +from economy_rows import ( + CURRENT_LAW, + VERSIONS, + EconomyCatalog, + insert_economy_catalog, +) +from policyengine_simulation_persistence import ( + KEY_VERSION, + EconomyPopulation, + EconomyRecordReferenceError, + EconomyReportDefinition, + EconomyRunStore, + FoundBudgetWindow, + KeyedBudgetWindow, + KeyedEconomyReport, + KeyedWindowYear, + ProposedSide, + ReportRunStatus, + SimulationChoice, + find_or_create_budget_window, + find_or_create_economy_report, +) +from public_api_rows import insert_policy +from sqlalchemy import func, select, text + +if TYPE_CHECKING: + from collections.abc import Iterator + + from sqlalchemy import Connection + +pytestmark = pytest.mark.public_api_schema + +FIRST_YEAR = 2026 +WINDOW_YEARS = (2026, 2027, 2028) + + +def _definition( + reform: SimulationChoice, + *, + country: str = "us", + year: int = FIRST_YEAR, + size: int | None = 3, +) -> EconomyReportDefinition: + return EconomyReportDefinition( + country=country, + baseline=CURRENT_LAW, + reform=reform, + dataset_name="populace_us_2024", + region_code="us", + year=year, + budget_window_size=size, + spm=None, + ) + + +def _keyed_window( + economy: EconomyCatalog, reform: SimulationChoice +) -> KeyedBudgetWindow: + """Return a request's three-year window on ``economy``, with fresh IDs.""" + return KeyedBudgetWindow( + definition=_definition(reform, country=economy.catalog.country), + report_id=uuid4(), + window_run_id=uuid4(), + tax_benefit_model_id=economy.catalog.model_id, + population=economy.population(), + versions=VERSIONS, + inputs={}, + years=tuple( + KeyedWindowYear( + year=year, + report_run_id=uuid4(), + baseline=ProposedSide(simulation_id=uuid4(), simulation_run_id=uuid4()), + reform=ProposedSide(simulation_id=uuid4(), simulation_run_id=uuid4()), + ) + for year in WINDOW_YEARS + ), + ) + + +def _reform(connection: Connection, economy: EconomyCatalog) -> SimulationChoice: + return SimulationChoice( + policy_id=insert_policy(connection, economy.catalog), dynamic_id=None + ) + + +def _row(connection: Connection, table_name: str, row_id: UUID) -> dict: + row = connection.execute( + text(f"SELECT * FROM public.{table_name} WHERE id = :id"), # noqa: S608 # fixed table names + {"id": row_id}, + ).mappings() + return dict(row.one()) + + +def _count(connection: Connection, table_name: str) -> int: + return connection.execute( + text(f"SELECT count(*) FROM public.{table_name}") # noqa: S608 # fixed table names + ).scalar_one() + + +def _counts(connection: Connection) -> list[int]: + return [ + _count(connection, name) + for name in ( + "simulations", + "reports", + "budget_window_runs", + "simulation_runs", + "report_runs", + ) + ] + + +def _fail_window_run(connection: Connection, window_run_id: UUID) -> None: + """Fail a window run as the superuser, as its coordinators would.""" + connection.execute(text("RESET ROLE")) + connection.execute( + text( + "UPDATE public.budget_window_runs SET status = 'failed', " + "completed_at = now() WHERE id = :id" + ), + {"id": window_run_id}, + ) + act_as_the_service(connection) + + +def test_a_keyed_window_is_created_with_each_years_simulations_and_runs( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + request = _keyed_window(economy, _reform(connection, economy)) + act_as_the_service(connection) + + found = find_or_create_budget_window(connection, request) + report = _row(connection, "reports", found.report_id) + window_run = _row(connection, "budget_window_runs", found.window_run.id) + year_runs = [ + _row(connection, "report_runs", year.report_run_id) for year in found.years + ] + year_simulations = [ + _row(connection, "simulations", year.reform.simulation_id) + for year in found.years + ] + + definition = request.definition + assert (found.report_id, found.report_inserted) == (request.report_id, True) + assert (found.window_run.id, found.window_run.inserted) == ( + request.window_run_id, + True, + ) + assert found.window_run.status is ReportRunStatus.PENDING + assert { + name: report[name] + for name in ( + "budget_window_size", + "year", + "key_version", + "definition_key", + "dataset_independent_key", + "label", + "description", + "user_id", + ) + } == { + "budget_window_size": 3, + "year": FIRST_YEAR, + "key_version": KEY_VERSION, + "definition_key": definition.definition_key, + "dataset_independent_key": definition.dataset_independent_key, + "label": None, + "description": None, + "user_id": None, + } + # The report names its first year's simulations. + assert report["reform_simulation_id"] == found.years[0].reform.simulation_id + assert { + name: window_run[name] + for name in ("policyengine_version", "recalculate", "trigger", "status") + } == { + "policyengine_version": VERSIONS.policyengine_version, + "recalculate": False, + "trigger": None, + "status": ReportRunStatus.PENDING, + } + assert [year.year for year in found.years] == list(WINDOW_YEARS) + for proposed, year, year_run, simulation in zip( + request.years, found.years, year_runs, year_simulations, strict=True + ): + assert year.report_run_id == proposed.report_run_id + assert year.baseline.run_inserted is True + assert year.reform.simulation_run_id == proposed.reform.simulation_run_id + assert (year_run["budget_window_run_id"], year_run["year"]) == ( + request.window_run_id, + year.year, + ) + assert (year_run["trigger"], year_run["forced"]) == (None, False) + assert year_run["reform_simulation_run_id"] == year.reform.simulation_run_id + # Each year's simulations are that year's, keyed by it. + assert simulation["year"] == year.year + assert simulation["definition_key"] == ( + definition.simulation("reform", year=year.year).definition_key + ) + + +def test_an_identical_window_request_joins_its_window_run_and_inserts_nothing( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + reform = _reform(connection, economy) + act_as_the_service(connection) + first = find_or_create_budget_window(connection, _keyed_window(economy, reform)) + counts = _counts(connection) + + again = find_or_create_budget_window(connection, _keyed_window(economy, reform)) + counts_again = _counts(connection) + + assert (again.report_id, again.report_inserted) == (first.report_id, False) + assert (again.window_run.id, again.window_run.inserted) == ( + first.window_run.id, + False, + ) + assert again.years == tuple( + replace( + year, + baseline=replace(year.baseline, run_inserted=False), + reform=replace(year.reform, run_inserted=False), + ) + for year in first.years + ) + assert counts_again == counts + + +def test_a_window_year_names_a_single_year_reports_simulation_run( + public_api_database_url, +) -> None: + """Review round 4's bug 3: a window year and a report of that year share runs.""" + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + reform = _reform(connection, economy) + act_as_the_service(connection) + single_year = find_or_create_economy_report( + connection, + KeyedEconomyReport( + definition=_definition( + reform, country=economy.catalog.country, year=2027, size=None + ), + report_id=uuid4(), + run_id=uuid4(), + baseline=ProposedSide(simulation_id=uuid4(), simulation_run_id=uuid4()), + reform=ProposedSide(simulation_id=uuid4(), simulation_run_id=uuid4()), + tax_benefit_model_id=economy.catalog.model_id, + population=economy.population(year=2027), + versions=VERSIONS, + inputs={}, + ), + ) + + window = find_or_create_budget_window( + connection, _keyed_window(economy, reform) + ) + + year_2027 = window.years[1] + assert year_2027.year == 2027 + assert (year_2027.reform.simulation_id, year_2027.reform.simulation_run_id) == ( + single_year.reform.simulation_id, + single_year.reform.simulation_run_id, + ) + assert year_2027.reform.run_inserted is False + assert window.years[0].reform.run_inserted is True + + +def test_a_window_whose_run_failed_gets_a_new_run_on_its_years_simulation_runs( + public_api_database_url, +) -> None: + """Answer 2: a failed window run never counts; its years' runs still may.""" + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + reform = _reform(connection, economy) + act_as_the_service(connection) + first = find_or_create_budget_window(connection, _keyed_window(economy, reform)) + _fail_window_run(connection, first.window_run.id) + + second = find_or_create_budget_window( + connection, _keyed_window(economy, reform) + ) + + assert second.report_id == first.report_id + assert second.window_run.inserted is True + assert second.window_run.id != first.window_run.id + for first_year, second_year in zip(first.years, second.years, strict=True): + assert second_year.report_run_id != first_year.report_run_id + assert second_year.reform.simulation_run_id == ( + first_year.reform.simulation_run_id + ) + assert second_year.reform.run_inserted is False + + +def test_a_window_comparing_a_policy_with_itself_names_one_run_a_year_twice( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + request = _keyed_window(economy, CURRENT_LAW) + act_as_the_service(connection) + + found = find_or_create_budget_window(connection, request) + + for proposed, year in zip(request.years, found.years, strict=True): + assert year.baseline.simulation_id == year.reform.simulation_id + assert year.baseline.simulation_run_id == year.reform.simulation_run_id + assert year.baseline.simulation_run_id == proposed.baseline.simulation_run_id + + +def test_the_store_finds_or_creates_a_window_in_a_transaction( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + reform = _reform(connection, economy) + act_as_the_service(connection) + + @contextmanager + def savepoint() -> Iterator[Connection]: + with connection.begin_nested(): + yield connection + + store = EconomyRunStore(savepoint) + found = store.find_or_create_budget_window(_keyed_window(economy, reform)) + again = store.find_or_create_budget_window(_keyed_window(economy, reform)) + + assert (found.window_run.inserted, again.window_run.inserted) == (True, False) + assert again.window_run.id == found.window_run.id + + +def test_a_window_request_naming_another_length_than_its_years_is_refused() -> None: + with pytest.raises(ValueError, match="first year and its length"): + KeyedBudgetWindow( + definition=_definition(CURRENT_LAW, size=2), + report_id=uuid4(), + window_run_id=uuid4(), + tax_benefit_model_id=uuid4(), + population=EconomyPopulation( + tax_benefit_model_version_id=uuid4(), + region_id=uuid4(), + dataset_id=uuid4(), + year=FIRST_YEAR, + ), + versions=VERSIONS, + inputs={}, + years=tuple( + KeyedWindowYear( + year=year, + report_run_id=uuid4(), + baseline=ProposedSide( + simulation_id=uuid4(), simulation_run_id=uuid4() + ), + reform=ProposedSide( + simulation_id=uuid4(), simulation_run_id=uuid4() + ), + ) + for year in WINDOW_YEARS + ), + ) + + +def test_two_identical_window_requests_at_once_end_on_one_window_run_started_once( + committed_engine, committed_catalog +) -> None: + """Both find the stored window; the second waits at the window run's index. + + An earlier window run of the report failed, so neither finds a run to + join; the first inserts one and holds its transaction open until the + second waits for it, then the second joins it with its year runs. Each + starts the first years only of a window run it inserted, as the service + does; exactly one does. + """ + economy = committed_catalog + with committed_engine.begin() as connection: + act_as_the_service(connection) + earlier = find_or_create_budget_window( + connection, _keyed_window(economy, CURRENT_LAW) + ) + with committed_engine.begin() as connection: + _fail_window_run(connection, earlier.window_run.id) + first_has_inserted = threading.Event() + found: dict[str, FoundBudgetWindow] = {} + started_windows: list[UUID] = [] + waited_on: list[str] = [] + + def create_and_start(connection: Connection, name: str) -> None: + act_as_the_service(connection) + result = find_or_create_budget_window( + connection, _keyed_window(economy, CURRENT_LAW) + ) + found[name] = result + if result.window_run.inserted: + started_windows.append(result.window_run.id) + + def first_request() -> None: + with committed_engine.begin() as connection: + create_and_start(connection, "first") + holder_pid = connection.execute(select(func.pg_backend_pid())).scalar_one() + first_has_inserted.set() + waited_on.append( + wait_until_another_backend_waits_for(committed_engine, holder_pid) + ) + + def second_request() -> None: + assert first_has_inserted.wait(LOCK_WAIT_TIMEOUT_SECONDS) + with committed_engine.begin() as connection: + create_and_start(connection, "second") + + run_together((first_request, second_request), released=first_has_inserted) + + # The second waited at the window run's index, not on another row. + (statement,) = waited_on + assert statement.lstrip().startswith("INSERT INTO public.budget_window_runs") + first, second = found["first"], found["second"] + assert first.report_id == second.report_id == earlier.report_id + assert first.window_run.id != earlier.window_run.id + assert (second.window_run.id, second.window_run.inserted) == ( + first.window_run.id, + False, + ) + assert [year.report_run_id for year in second.years] == [ + year.report_run_id for year in first.years + ] + assert started_windows == [first.window_run.id] + + +def test_a_window_naming_a_missing_policy_is_refused_and_writes_nothing( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + missing_policy = SimulationChoice(policy_id=uuid4(), dynamic_id=None) + act_as_the_service(connection) + before = _counts(connection) + + with ( + pytest.raises(EconomyRecordReferenceError) as refused, + connection.begin_nested(), + ): + find_or_create_budget_window( + connection, _keyed_window(economy, missing_policy) + ) + after = _counts(connection) + + assert (refused.value.table_name, refused.value.column_name) == ( + "simulations", + "policy_id", + ) + assert after == before diff --git a/libs/policyengine-simulation-persistence/tests/test_shared_rows.py b/libs/policyengine-simulation-persistence/tests/test_shared_rows.py new file mode 100644 index 000000000..47f225be5 --- /dev/null +++ b/libs/policyengine-simulation-persistence/tests/test_shared_rows.py @@ -0,0 +1,365 @@ +"""Find a shared simulation, report or run by its definition or versions, or insert it. + +These run against a database the Public API's own v2 migration chain built +(``PUBLIC_API_SCHEMA_DATABASE_URL``), as the simulation service's role. Most +run in a transaction rolled back afterwards. The tests of two transactions +commit their rows, under a catalog of a country no other test uses, and +delete them afterwards. +""" + +from __future__ import annotations + +import threading +from typing import TYPE_CHECKING, Any +from uuid import UUID, uuid4 + +import pytest +from committed_rows import ( + LOCK_WAIT_TIMEOUT_SECONDS, + run_together, + wait_until_another_backend_waits_for, +) +from conftest import act_as_the_service, rolled_back_transaction +from economy_rows import ( + CURRENT_LAW, + LATER_VERSIONS, + VERSIONS, + EconomyCatalog, + insert_economy_catalog, +) +from policyengine_simulation_persistence import ( + KEY_VERSION, + ReportRunStatus, + ReportRunTrigger, + RunVersions, + SimulationStatus, + SimulationType, + definition_key, + find_or_insert_report, + find_or_insert_report_run, + find_or_insert_simulation, + find_or_insert_simulation_run, + simulation_runs, +) +from sqlalchemy import event, insert, text, update + +if TYPE_CHECKING: + from sqlalchemy import Connection + +pytestmark = pytest.mark.public_api_schema + + +def _key(name: str) -> str: + return definition_key({"test": name}) + + +def _simulation_values(economy: EconomyCatalog, key: str) -> dict[str, Any]: + return { + "id": uuid4(), + "simulation_type": SimulationType.ECONOMY, + "dataset_id": economy.dataset_id, + "policy_id": CURRENT_LAW.policy_id, + "dynamic_id": CURRENT_LAW.dynamic_id, + "tax_benefit_model_version_id": economy.catalog.version_id, + "region_id": economy.region_id, + "year": 2026, + "key_version": KEY_VERSION, + "definition_key": key, + } + + +def _report_values( + economy: EconomyCatalog, key: str, simulation_id: UUID +) -> dict[str, Any]: + return { + "id": uuid4(), + "label": "Shared report", + "country": economy.catalog.country, + "type": "economy", + "tax_benefit_model_id": economy.catalog.model_id, + "baseline_simulation_id": simulation_id, + "reform_simulation_id": simulation_id, + "dataset_id": economy.dataset_id, + "region_id": economy.region_id, + "year": 2026, + "inputs": {"include_cliffs": False}, + "key_version": KEY_VERSION, + "definition_key": key, + "dataset_independent_key": _key(f"{key} without its dataset"), + } + + +def _simulation_run_values( + economy: EconomyCatalog, simulation_id: UUID, versions: RunVersions = VERSIONS +) -> dict[str, Any]: + return { + "id": uuid4(), + "simulation_id": simulation_id, + "year": 2026, + "tax_benefit_model_version_id": economy.catalog.version_id, + "country_package_version": versions.country_package_version, + "policyengine_version": versions.policyengine_version, + "dataset_id": economy.dataset_id, + "region_id": economy.region_id, + "status": SimulationStatus.PENDING, + } + + +def _report_run_values( + report_id: UUID, simulation_run_id: UUID, versions: RunVersions = VERSIONS +) -> dict[str, Any]: + return { + "id": uuid4(), + "report_id": report_id, + "baseline_simulation_run_id": simulation_run_id, + "reform_simulation_run_id": simulation_run_id, + "country_package_version": versions.country_package_version, + "policyengine_version": versions.policyengine_version, + "status": ReportRunStatus.PENDING, + "trigger": ReportRunTrigger.INITIAL, + } + + +def _fail(connection: Connection, table_name: str, row_id: UUID) -> None: + """Fail a run as the superuser, as a worker or the sweep would.""" + connection.execute( + text( + f"UPDATE public.{table_name} SET status = 'failed', " # noqa: S608 # fixed table names + "completed_at = now() WHERE id = :id" + ), + {"id": row_id}, + ) + + +def test_a_simulation_is_inserted_once_and_then_found_by_its_key( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + act_as_the_service(connection) + first_values = _simulation_values(economy, _key("simulation")) + + first = find_or_insert_simulation(connection, first_values) + again = find_or_insert_simulation( + connection, _simulation_values(economy, _key("simulation")) + ) + other = find_or_insert_simulation( + connection, _simulation_values(economy, _key("another simulation")) + ) + + assert (first.id, first.inserted) == (first_values["id"], True) + assert (again.id, again.inserted) == (first.id, False) + assert other.inserted is True + assert other.id != first.id + + +def test_a_report_is_inserted_once_and_then_found_by_its_key( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + act_as_the_service(connection) + simulation = find_or_insert_simulation( + connection, _simulation_values(economy, _key("simulation")) + ) + first_values = _report_values(economy, _key("report"), simulation.id) + + first = find_or_insert_report(connection, first_values) + again = find_or_insert_report( + connection, _report_values(economy, _key("report"), simulation.id) + ) + + assert (first.id, first.inserted) == (first_values["id"], True) + assert (again.id, again.inserted) == (first.id, False) + + +def test_a_simulation_run_is_joined_on_its_version_set_until_it_fails( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + act_as_the_service(connection) + simulation = find_or_insert_simulation( + connection, _simulation_values(economy, _key("simulation")) + ) + + first = find_or_insert_simulation_run( + connection, _simulation_run_values(economy, simulation.id) + ) + joined = find_or_insert_simulation_run( + connection, _simulation_run_values(economy, simulation.id) + ) + later_versions = find_or_insert_simulation_run( + connection, _simulation_run_values(economy, simulation.id, LATER_VERSIONS) + ) + connection.execute(text("RESET ROLE")) + _fail(connection, "simulation_runs", first.id) + act_as_the_service(connection) + after_failure = find_or_insert_simulation_run( + connection, _simulation_run_values(economy, simulation.id) + ) + + assert first.inserted is True + assert (joined.id, joined.inserted) == (first.id, False) + assert later_versions.inserted is True + assert after_failure.inserted is True + assert after_failure.id not in {first.id, later_versions.id} + + +def test_a_forced_run_is_never_joined_and_never_takes_a_runs_place( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + act_as_the_service(connection) + simulation = find_or_insert_simulation( + connection, _simulation_values(economy, _key("simulation")) + ) + forced_values = _simulation_run_values(economy, simulation.id) + connection.execute(insert(simulation_runs).values(**forced_values, forced=True)) + + first = find_or_insert_simulation_run( + connection, _simulation_run_values(economy, simulation.id) + ) + # Another forced run beside an unforced one conflicts with neither. + connection.execute( + insert(simulation_runs).values( + **_simulation_run_values(economy, simulation.id), forced=True + ) + ) + + assert first.inserted is True + assert first.id != forced_values["id"] + with pytest.raises(ValueError, match="forced"): + find_or_insert_simulation_run( + connection, + {**_simulation_run_values(economy, simulation.id), "forced": True}, + ) + + +def test_a_report_run_is_joined_on_its_versions_outside_budget_windows( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + act_as_the_service(connection) + simulation = find_or_insert_simulation( + connection, _simulation_values(economy, _key("simulation")) + ) + simulation_run = find_or_insert_simulation_run( + connection, _simulation_run_values(economy, simulation.id) + ) + report = find_or_insert_report( + connection, _report_values(economy, _key("report"), simulation.id) + ) + + first = find_or_insert_report_run( + connection, _report_run_values(report.id, simulation_run.id) + ) + joined = find_or_insert_report_run( + connection, _report_run_values(report.id, simulation_run.id) + ) + + assert first.inserted is True + assert (joined.id, joined.inserted) == (first.id, False) + assert joined.status is ReportRunStatus.PENDING + assert joined.baseline_simulation_run_id == simulation_run.id + assert joined.reform_simulation_run_id == simulation_run.id + with pytest.raises(ValueError, match="budget window"): + find_or_insert_report_run( + connection, + { + **_report_run_values(report.id, simulation_run.id), + "budget_window_run_id": uuid4(), + "year": 2026, + }, + ) + + +def test_a_transaction_inserting_a_run_another_has_inserted_waits_and_joins_it( + committed_engine, committed_catalog +) -> None: + economy = committed_catalog + with committed_engine.begin() as connection: + act_as_the_service(connection) + simulation = find_or_insert_simulation( + connection, _simulation_values(economy, _key("shared simulation")) + ) + first_has_inserted = threading.Event() + found: dict[str, Any] = {} + + def insert_then_commit_once_the_other_waits() -> None: + with committed_engine.begin() as connection: + act_as_the_service(connection) + found["first"] = find_or_insert_simulation_run( + connection, _simulation_run_values(economy, simulation.id) + ) + holder_pid = connection.execute( + text("SELECT pg_backend_pid()") + ).scalar_one() + first_has_inserted.set() + wait_until_another_backend_waits_for(committed_engine, holder_pid) + + def insert_once_the_first_has() -> None: + assert first_has_inserted.wait(LOCK_WAIT_TIMEOUT_SECONDS) + with committed_engine.begin() as connection: + act_as_the_service(connection) + found["second"] = find_or_insert_simulation_run( + connection, _simulation_run_values(economy, simulation.id) + ) + + run_together( + (insert_then_commit_once_the_other_waits, insert_once_the_first_has), + released=first_has_inserted, + ) + + assert found["first"].inserted is True + assert (found["second"].id, found["second"].inserted) == (found["first"].id, False) + + +def test_a_run_that_fails_between_the_insert_and_the_read_is_inserted_again( + committed_engine, committed_catalog +) -> None: + economy = committed_catalog + with committed_engine.begin() as connection: + act_as_the_service(connection) + simulation = find_or_insert_simulation( + connection, _simulation_values(economy, _key("shared simulation")) + ) + earlier = find_or_insert_simulation_run( + connection, _simulation_run_values(economy, simulation.id) + ) + + def fail_the_earlier_run_before_the_read( + _connection, _cursor, statement, _parameters, _context, _executemany + ) -> None: + if statement.lstrip().startswith("SELECT") and "simulation_runs" in statement: + with committed_engine.begin() as other: + other.execute( + update(simulation_runs) + .where( + simulation_runs.c.id == earlier.id, + simulation_runs.c.status != SimulationStatus.FAILED, + ) + .values(status=SimulationStatus.FAILED, completed_at=text("now()")) + ) + + with committed_engine.begin() as connection: + act_as_the_service(connection) + event.listen( + connection, "before_cursor_execute", fail_the_earlier_run_before_the_read + ) + try: + again = find_or_insert_simulation_run( + connection, _simulation_run_values(economy, simulation.id) + ) + finally: + event.remove( + connection, + "before_cursor_execute", + fail_the_earlier_run_before_the_read, + ) + + assert earlier.inserted is True + assert again.inserted is True + assert again.id != earlier.id diff --git a/libs/policyengine-simulation-persistence/tests/test_tables.py b/libs/policyengine-simulation-persistence/tests/test_tables.py index 2d7ade37f..40b7181ca 100644 --- a/libs/policyengine-simulation-persistence/tests/test_tables.py +++ b/libs/policyengine-simulation-persistence/tests/test_tables.py @@ -5,6 +5,7 @@ from policyengine_simulation_persistence import ( SERVICE_TABLE_PRIVILEGES, SimulationStatus, + budget_window_runs, household_jobs, input_metadata, referenced_metadata, @@ -12,10 +13,11 @@ reports, service_metadata, simulation_runs, + simulations, ) from policyengine_simulation_persistence import tables as tables_module from public_api_keys import KEYS_TO_PUBLIC_API_TABLES -from sqlalchemy import Enum, ForeignKeyConstraint, Table, UniqueConstraint +from sqlalchemy import Enum, ForeignKeyConstraint, Index, Table, UniqueConstraint def _key(constraint: ForeignKeyConstraint) -> tuple[tuple[str, ...], str, str]: @@ -211,3 +213,88 @@ def test_the_input_models_share_no_table_with_the_service_models() -> None: assert input_metadata.schema == "public" assert input_tables.isdisjoint(service_metadata.tables.values()) assert input_tables.isdisjoint(referenced_metadata.tables.values()) + + +def _index(table: Table, index_name: str) -> Index: + (index,) = (index for index in table.indexes if index.name == index_name) + return index + + +def test_simulations_and_reports_are_unique_on_their_definition_key() -> None: + """Find-or-create names this pair as its conflict target (C1 · 25).""" + for table in (simulations, reports): + assert table.c.key_version.nullable is True, table.name + assert table.c.definition_key.nullable is True, table.name + assert table.c.definition_key.type.length == 64, table.name + assert _unique_keys(table)[f"uq_{table.name}_key_version_definition_key"] == ( + "key_version", + "definition_key", + ) + assert reports.c.dataset_independent_key.nullable is True + # The app finds a report on another dataset by this key alone. + assert _indexed_columns(reports, "ix_reports_dataset_independent_key") == ( + "dataset_independent_key", + ) + + +def test_a_definition_and_version_set_has_one_unfailed_unforced_run() -> None: + """A failed or forced run is left out, so it never takes a joinable run's place.""" + simulation_run_index = _index( + simulation_runs, "uq_simulation_runs_unfailed_unforced_versions" + ) + report_run_index = _index(report_runs, "uq_report_runs_unfailed_unforced_versions") + + assert simulation_run_index.unique is True + assert tuple(column.name for column in simulation_run_index.columns) == ( + "simulation_id", + "year", + "tax_benefit_model_version_id", + "country_package_version", + "policyengine_version", + ) + assert str(simulation_run_index.dialect_options["postgresql"]["where"]) == ( + "status <> 'failed' AND NOT forced" + ) + assert report_run_index.unique is True + assert tuple(column.name for column in report_run_index.columns) == ( + "report_id", + "country_package_version", + "policyengine_version", + ) + assert str(report_run_index.dialect_options["postgresql"]["where"]) == ( + "budget_window_run_id IS NULL AND status <> 'failed' AND NOT forced" + ) + + +def test_a_run_is_unforced_unless_its_insert_marks_it() -> None: + for table in (simulation_runs, report_runs): + assert table.c.forced.nullable is False, table.name + assert str(table.c.forced.server_default.arg) == "false", table.name + + +def test_the_per_user_columns_are_nullable() -> None: + """Answer 6: the service writes no request's label, description or trigger.""" + assert reports.c.label.nullable is True + assert reports.c.description.nullable is True + assert reports.c.user_id.nullable is True + assert report_runs.c.trigger.nullable is True + assert budget_window_runs.c.trigger.nullable is True + + +def test_a_window_run_is_one_per_report_and_version_set_unless_recalculated() -> None: + """Answer 8: a window run on the versions is joined; a forced one is extra.""" + assert budget_window_runs.c.policyengine_version.nullable is True + assert budget_window_runs.c.policyengine_version.type.length == 128 + window_run_index = _index( + budget_window_runs, "uq_budget_window_runs_unfailed_unforced_versions" + ) + + assert window_run_index.unique is True + assert tuple(column.name for column in window_run_index.columns) == ( + "report_id", + "tax_benefit_model_version_id", + "policyengine_version", + ) + assert str(window_run_index.dialect_options["postgresql"]["where"]) == ( + "status <> 'failed' AND NOT recalculate" + ) diff --git a/libs/policyengine-stage12-persistence/tests/budget_window_database.py b/libs/policyengine-stage12-persistence/tests/budget_window_database.py index 0313febe7..83b5858a5 100644 --- a/libs/policyengine-stage12-persistence/tests/budget_window_database.py +++ b/libs/policyengine-stage12-persistence/tests/budget_window_database.py @@ -153,6 +153,9 @@ def seed_window_rerun(self, window: SeededWindow) -> SeededWindow: Each year gets a new report run and two new runs of the report's simulations; the earlier window run and its years are left as they are. + It recalculates, so it is a forced re-run: its year runs and + simulation runs are marked forced, as the simulation service inserts + them, and the Public API's one-unfailed-run indexes leave them out. """ table = self.seeder.table with self.engine.connect() as connection: @@ -202,6 +205,7 @@ def seed_window_rerun(self, window: SeededWindow) -> SeededWindow: tax_benefit_model_version_id=first_run.tax_benefit_model_version_id, dataset_id=first_run.dataset_id, status="pending", + forced=True, **later, **VERSIONS, ) @@ -216,6 +220,7 @@ def seed_window_rerun(self, window: SeededWindow) -> SeededWindow: year=seeded.year, status="pending", trigger="manual", + forced=True, **later, **VERSIONS, ) diff --git a/libs/policyengine-stage12-persistence/tests/test_report_run_sweep_store.py b/libs/policyengine-stage12-persistence/tests/test_report_run_sweep_store.py index 4f6850eef..e67ef4e61 100644 --- a/libs/policyengine-stage12-persistence/tests/test_report_run_sweep_store.py +++ b/libs/policyengine-stage12-persistence/tests/test_report_run_sweep_store.py @@ -318,26 +318,34 @@ def sweep(run_store): _SAME_RUN = object() -def _second_report_run( +def _second_report_run( # noqa: PLR0913 # the run, then what it names and whose it is seeder, seeded_run: SeededReportRun, status, *, baseline_simulation_run_id=_SAME_RUN, reform_simulation_run_id=_SAME_RUN, + of_another_report=False, ): - """Insert another report run of the same report. + """Insert another report run of the same report, or of a copy of it. It names the first report run's simulation runs unless given others; a - null reform run is a report with only a baseline. + null reform run is a report with only a baseline. With + ``of_another_report`` it is a run of a new report copying the first's + definition: one report has at most one unfailed run on a version set, + so two report runs naming the same runs at once are two reports' runs. + The seeder removes the copy with the seeded report, by their model. """ first = seeder.row("report_runs", seeded_run.run_ids.report_run_id) + report_id = first["report_id"] + if of_another_report: + report_id = _copy_of_report(seeder, report_id) second_id = uuid4() with seeder.engine.begin() as connection: connection.execute( insert(seeder.table("report_runs")).values( id=second_id, - report_id=first["report_id"], + report_id=report_id, baseline_simulation_run_id=( first["baseline_simulation_run_id"] if baseline_simulation_run_id is _SAME_RUN @@ -362,6 +370,30 @@ def _second_report_run( return second_id +# A report's definition keys, unique to it, which a copy leaves out. +_REPORT_KEY_COLUMNS = ("key_version", "definition_key", "dataset_independent_key") + + +def _copy_of_report(seeder, report_id): + """Insert a new report copying ``report_id``'s columns; return its ID. + + The copy has no definition keys, as a report created before keys existed, + so it never conflicts with the report it copies. + """ + report = seeder.row("reports", report_id) + copy_id = uuid4() + copied = { + name: None if name in _REPORT_KEY_COLUMNS else value + for name, value in report.items() + if name not in {"id", "created_at", "updated_at"} + } + with seeder.engine.begin() as connection: + connection.execute( + insert(seeder.table("reports")).values({**copied, "id": copy_id}) + ) + return copy_id + + # What another simulation run of the seeded baseline's simulation copies. SIMULATION_RUN_DEFINITION = ( "simulation_id", @@ -374,7 +406,12 @@ def _second_report_run( def _another_simulation_run(seeder, seeded_run: SeededReportRun, **state): - """Insert another simulation run of the seeded baseline's simulation.""" + """Insert another simulation run of the seeded baseline's simulation. + + It is on a .py version of its own: the Public API's index refuses two + runs of one simulation that haven't failed on one version set, and the + sweep doesn't read versions. + """ baseline = seeder.row( "simulation_runs", seeded_run.run_ids.baseline_simulation_run_id ) @@ -382,9 +419,14 @@ def _another_simulation_run(seeder, seeded_run: SeededReportRun, **state): with seeder.engine.begin() as connection: connection.execute( insert(seeder.table("simulation_runs")).values( - id=run_id, - **{name: baseline[name] for name in SIMULATION_RUN_DEFINITION}, - **state, + { + **{name: baseline[name] for name in SIMULATION_RUN_DEFINITION}, + "id": run_id, + "policyengine_version": ( + f"{baseline['policyengine_version']}+another.{run_id.hex[:8]}" + ), + **state, + } ) ) return run_id @@ -629,8 +671,9 @@ def test_the_sweep_never_lists_or_fails_a_succeeded_run_two_report_runs_reuse( output_uri="gs://detailed-save-outputs/simulations/shared-baseline.parquet", output_sha256="d" * 64, ) - # The seeded report run and a second one, each running under its own - # coordinator call, name the same succeeded baseline run at the same time. + # The seeded report run and another report's run, each running under its + # own coordinator call, name the same succeeded baseline run at the same + # time. _set_run( seeder, "report_runs", @@ -647,6 +690,7 @@ def test_the_sweep_never_lists_or_fails_a_succeeded_run_two_report_runs_reuse( reform_simulation_run_id=_another_simulation_run( seeder, seeded_run, status="pending" ), + of_another_report=True, ) _set_run( seeder, diff --git a/projects/policyengine-apis-integ/tests/test_economy_generated_client.py b/projects/policyengine-apis-integ/tests/test_economy_generated_client.py index 0f58c439f..5d19bda13 100644 --- a/projects/policyengine-apis-integ/tests/test_economy_generated_client.py +++ b/projects/policyengine-apis-integ/tests/test_economy_generated_client.py @@ -245,14 +245,8 @@ def test_a_simulation_rerun_is_read_with_its_new_run(): ("status_code", "body"), [ (404, {"code": "unknown_report", "detail": f"There is no report {REPORT_ID}."}), - ( - 409, - { - "code": "run_in_progress", - "detail": "The report has a run pending or running.", - "run_id": RUN_ID, - }, - ), + # No re-run is refused while a run is under way (C1 · 27): an + # unforced one joins it, so the only 409 is rerun_not_supported. (409, {"code": "rerun_not_supported", "detail": "Not yet."}), ( 503, diff --git a/projects/policyengine-simulation-entry/DEPLOYMENT.md b/projects/policyengine-simulation-entry/DEPLOYMENT.md index 5972daaff..fa001a6cc 100644 --- a/projects/policyengine-simulation-entry/DEPLOYMENT.md +++ b/projects/policyengine-simulation-entry/DEPLOYMENT.md @@ -119,28 +119,32 @@ fails the check. ## Economy reports and simulations `POST /reports` and `POST /simulations`, and their reads, use the same -database, Modal token and v2 manifest settings as the household routes, and -the deploy's `V2_SIMULATION_OUTPUT_BUCKET`, the `beta` or `prod` variable of -that name: the bucket that keeps v2 simulation output files for good. A -report reuses only a succeeded simulation run whose file is in it; the -service compares output URIs with it and never reads the bucket, so it needs -no storage permission. A missing or invalid bucket name stops the deploy. -The coordinator and workers get the same bucket from the Modal secret the -Stage 12 secret sync writes. +database, Modal token and v2 manifest settings as the household routes. A +report joins its sides' simulation runs by version set (C1 · 24's answers 4 +and 5), not by their output files, so the service needs no simulation +output bucket setting and no storage permission. The coordinator and workers +get the bucket they write those files to, `V2_SIMULATION_OUTPUT_BUCKET`, from +the Modal secret the Stage 12 secret sync writes. ### The staging economy check Every staging deployment runs `staging_economy_check` when the household -check runs: `.github/scripts/simulation-staging-economy-check.sh` creates a -small report, current law against current law for `country/wales` in 2026, -through the candidate's tagged URL with the authenticated tests' client -credentials, follows it through `GET /reports/{report_id}`, and requires its -run to succeed within 30 minutes. `deployment_ready` requires the check to -pass in staging, so a failure stops the production deployment. Each run adds -a report and its runs to the staging database. Once a .py version's first -check has succeeded, later checks on that version reuse its simulation runs, -so they check the coordinator's use of stored outputs rather than the -workers', which the v2 deployment's own validation calls. +check runs: `.github/scripts/simulation-staging-economy-check.sh` sends a +small report request, current law against current law for `country/wales` +in 2026, through the candidate's tagged URL with the authenticated tests' +client credentials (`POST /reports`), then forces a new run of the report +(`POST /reports/{report_id}/runs` with `{"force": true}`), follows that run +through `GET /reports/{report_id}`, and requires it to succeed within 30 +minutes. The report is found by key, so on versions an earlier check ran on, +the request ends on that check's report run and calculates nothing; the +forced run, which nothing joins, is what calculates on every deploy: both +simulations on the release's workers and the comparison on its +coordinator. Both requests need `simulation:submit`. `deployment_ready` +requires the check to pass in staging, so a failure stops the production +deployment. Each run adds a forced report run and its two simulation runs +to the staging database; a .py version's first check also adds the +report's ordinary run, on one simulation run for both sides (current law +compared with itself), which calculates as well. ## Candidate qualification diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index 1b8fce00b..340269648 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -122,20 +122,30 @@ the same fields for one policy and dynamic. Neither names a .py version or a record ID: the service runs the v2 version manifest's default worker and chooses every ID. -The service reads the rows itself and, in one transaction, creates the -records and their first runs, `pending` with no Modal call ID. A report -side reuses a simulation run that already succeeded instead of creating -one, when it is the newest run of the same policy, dynamic, catalog -version, dataset, region and year on the same country package and .py -versions, its output file is in the output bucket -(`V2_SIMULATION_OUTPUT_BUCKET`), a succeeded report run with the same -options used it, and no report run has refused to reuse it; the two sides -never name the same run. The service then starts the run's Modal call by -name: the report run's coordinator, given the report and its run IDs and no -Stage 12 evaluation record, or a standalone run's simulation function, -given its run's ID. It records the call's ID, and answers 201 with the -record's ID, its run's ID and status, and, for a report, each side's -simulation and run and whether it was reused. +Identical requests, together or a minute apart, end on the same +simulation, report and run rows. The service reads the rows itself and, in +one transaction, finds or creates each record by a key of its definition +(`definition_key`, with `key_version`): a simulation's is its country, +policy, dynamic, dataset name, region code, year and SPM selection; a +report's is its two sides' policies and dynamics, the dataset, region, year +and SPM selection they share, and its budget window size, with no other +option; a report also stores a `dataset_independent_key`, the same without +the dataset. It then joins the report's run on the default worker's +versions that hasn't failed and wasn't forced, pending, running or +succeeded, or else finds or creates each simulation's run on those +versions, catalog version and year (any that hasn't failed and wasn't +forced, whichever report first calculated it) and creates a report run +naming them, `pending` with no Modal call ID. Current law against current +law names one simulation and run on both sides. A report stores only the +request's SPM selection in `inputs`; `include_cliffs` is passed to the +calculation but never stored or keyed. Only for a run its own transaction +created does the service start a Modal call by name: the report run's +coordinator, given the report and its run IDs and no Stage 12 evaluation +record, or a standalone run's simulation function, given its run's ID. It +records the call's ID, and answers 201 with the record's ID, the run's ID +and status (as read, for a run it joined), and, for a report, each side's +simulation and run and whether it was reused, which is true for a side +whose run this request didn't create. A request is refused before anything is written: with 400 and a `code` when a row it names is missing (`unknown_region`, `unknown_dataset` and @@ -144,30 +154,40 @@ a row it names is missing (`unknown_region`, `unknown_dataset` and `missing_reference` are the service's state, such as a catalog version missing while a release deploys), and with 422 and a `code` when a policy or dynamic sets parameters the catalog version lacks (`missing_parameters`) or -both set one (`overlapping_parameters`). The routes answer 503 with +both set one (`overlapping_parameters`), and a report with +`include_cliffs: true` with 422 `cliffs_not_available`, located at the +field, until each simulation run's own cliff calculation exists (C1 · 39). +The routes answer 503 with `Retry-After` when the manifest or the database can't be read. When Modal -refuses the call, or doesn't confirm it within ten seconds, the run (and a -report run's new simulation runs) is failed at once and the 503 -(`modal_call_refused`) names the record, as `report_id` or `simulation_id`; +refuses the call, or doesn't confirm it within ten seconds, the run is +failed at once (a report run alone: its simulation runs may already be +another report run's, and the next coordinator naming them starts them) +and the 503 (`modal_call_refused`) names the record, as `report_id` or +`simulation_id`; a run claimed meanwhile is answered with 201. Every 500 is the JSON error with code `internal_error`, and may follow a write. No `detail` holds an exception's text. ### Budget windows -`POST /reports` with `report_type` `budget_window` creates a budget-window -report: the same baseline and reform in each year of a window that starts -at `year` and lasts `budget_window_size` years (1 to 75, ending by 2200). -It names the same fields as an economy report, except `include_cliffs`, -which it refuses; it stores the options of a report without cliffs, so its -years and single-year reports reuse each other's runs. In one transaction -the service creates the report (an economy report whose -`budget_window_size` is set), one `budget_window_runs` row, and for each -year a report run naming it and the year, with that year's own simulations -unless a side reuses a run of the same year. It then starts up to the -earliest five years, as its own role, under the window run's row lock +`POST /reports` with `report_type` `budget_window` finds or creates a +budget-window report: the same baseline and reform in each year of a window +that starts at `year` and lasts `budget_window_size` years (1 to 75, ending +by 2200). It names the same fields as an economy report, except +`include_cliffs`, which it refuses. Identical window requests end on the +same rows (C1 · 24's answer 8): in one transaction the service finds each +year's simulations by that year's key, which a single-year report of that +year shares, and the report by its key (an economy report whose +`budget_window_size` is set, in its key too); it joins the report's +`budget_window_runs` row on the default worker's catalog and .py versions +that hasn't failed and isn't a recalculation, or else creates one +(recording its .py version) and, for each year, a report run naming it and +the year, on each side's simulation run of that year, found or inserted. +Only for a window run it created does it then start up to the earliest +five years, as its own role, under the window run's row lock (`BudgetWindowStore.advance_window`): the first year's coordinator input is -built as an economy report's, and each later year's is derived from it. +built as an economy report's, and each later year's is derived from it. A +joined window run is answered as it is, with no new call. Each year's coordinator starts the next years when its year ends. The 201 names the report, the first year's report run, the window run, its status and every year's runs. A year Modal refuses fails the window, its waiting @@ -204,18 +224,27 @@ report holds every value, and `reports.inputs` is `{}`. A household's saved SPM selection is applied to both sides. The service reads the catalog version for the default worker's .py version, -the household and each side's policy, then creates, in one transaction, a -household simulation and a pending simulation run for each side (household -runs are never reused), the report (type `household`) and its pending -report run. It starts one call of the country's household function with the -report run's ID (`household_report_run_id`) and each side's household -contract request, whose calculation ID is the side's simulation run, and -records the call's ID. The household function claims the report run and each +the household and each side's policy, checks each side's household contract +request, then finds or creates, in one transaction, as an economy report's +create does (C1 · 24's answer 8): each side's household simulation by a key +of its country, policy, household and year; the report (type `household`) +by a key of its sides, household and year; and its run on the current +versions that hasn't failed and wasn't forced, or else a pending report +run naming each side's simulation run on those versions, found or +inserted. A policy compared with itself names one simulation and one run on +both sides. For a report run it created, it starts one call of the +country's household function with the report run's ID +(`household_report_run_id`) and each side's household contract request, +whose calculation ID is the side's simulation run, and records the call's +ID; a run it joined gets no call. A simulation run another report run is +calculating is waited for by the household function (C1 · 26). The household function claims the report run and each simulation run under its own call, writes each run's result or failure document to `household_result`, and marks the report run succeeded only if every side's run did; otherwise it fails with the first such side's reason. The answer is 201 with the report's and its run's IDs, the run's status, -the `year` and each side's simulation and simulation run. +the `year` and each side's simulation and simulation run, for the run the +request ended on. When Modal refuses the call, only the report run is +failed: its simulation runs may be another report run's. Refusals and outages answer as an economy report's do, with three more codes: 400 `unknown_household` and `no_household_function` (the default @@ -232,40 +261,66 @@ A policy setting parameters the catalog version lacks is 422 `POST /reports/{report_id}/runs` calculates a stored economy report again, as a new run on the default worker's versions, and keeps every earlier run. Its body is required: `{}` or `{"force": false}` re-runs the report, and -`{"force": true}` forces a recalculation. The report keeps its simulations: -each side gets a new run of its own simulation, or, without `force`, reuses -that simulation's newest run on the same versions, catalog version, dataset, -region and year that a new report's side could reuse; `force` calculates -both again. The new report run's trigger is `manual`. The service reads the +`{"force": true}` forces a recalculation. The report keeps its simulations. +Without `force`, a re-run of a report created by key while the report has +a run on the default worker's versions that hasn't failed and wasn't +forced, pending, running or succeeded, joins that run instead and answers +it as it is, with both sides reused and no Modal call; a run still under +way on older versions is no run to join. Otherwise each side joins its +simulation's run on those versions, catalog version and year that hasn't +failed and wasn't forced, in any state, or gets a new one, under a new +report run. `force` calculates both sides again, as an extra run: the new +report run and both simulation runs are marked `forced`, so nothing joins +them and the Public API's one-unfailed-run indexes leave them out, and a +forced re-run is never refused while a run is under way. A report created +before keys (C1 · 27), whose simulations have none, is always re-run that +way, forced or not: its runs may have been calculated with plans that +depended on that report (C1 · 24's interim answer B). The new report run +names no trigger (answer 6): the Public API's per-user report-run record +holds it. Such a +report stored asking for cliff impacts +(`include_cliffs: true` in its options) is refused with 422 +`cliffs_not_available`, located at `report.inputs.include_cliffs`, until +cliffs are calculated for each simulation run (C1 · 39; interim answer A). +The service reads the report's region code and dataset name, finds the rows with that code and name in the catalog version of the default worker's .py version, and reads each simulation's stored policy and dynamic on it. -A budget-window report's re-run is a new budget-window run, trigger -`manual`, with `recalculate` set by `force`, and a report run per year. Each -year's sides are the simulations that year's report run of the report's -newest window run names (a year that reused another report's run names that -report's simulation), and each reuses a run of them as a single-year side -does. Up to five years start at once, as a new window's do (a later year +A budget-window report's re-run joins or creates a budget-window run with +a report run per year, as a single-year report's does: a window created by +key, without `force`, joins its window run on the default worker's versions +that hasn't failed and isn't a recalculation, with no new call, or else +gets a new window run whose years' sides join their simulations' runs or +get new ones. `force`, and every re-run of a window created before keys, +recalculates it: `recalculate` is set, and its year runs and new +simulation runs are marked `forced`. Each year's sides are runs of the +simulations that year's report run of the report's newest window run names +(a year that named another report's run names that report's simulation). +Only a window run the re-run created has its first years started. Up to five years start at once, as a new window's do (a later year Modal doesn't confirm in time waits for an earlier year's coordinator); it answers 201 with the budget-window create's fields, naming the window run and every year. A household report's re-run calculates its stored household again in the report's own year (not the household's current `default_year`), under each -side's stored policy read on the current catalog version. Each side gets a -new run of its own household simulation, recording that catalog version: -household runs are never reused, so `force` changes nothing. The new report -run (trigger `manual`) is started by one household function call, as a new +side's stored policy read on the current catalog version, and joins or +creates its run as an economy report's re-run does: a keyed report's +unforced re-run joins its run on the current versions, or each side joins +its own household simulation's run on them or gets a new one; `force`, and +every re-run of a household report created before keys, makes an extra run +on a new run of each side, all marked `forced`. A report run it created +(naming no trigger: answer 6) is started by one household function call, as a new household report's is, and the re-run answers 201 with the household report create's fields. -`POST /simulations/{simulation_id}/runs`, with no body, creates and starts -a stored economy simulation's new run, which is always calculated. Each -answers 201 with the same fields as the create, naming the new run. +`POST /simulations/{simulation_id}/runs`, with no body, joins a stored +economy simulation's run on the default worker's versions, catalog version +and year that hasn't failed and wasn't forced, pending, running or +succeeded, and answers it as it is, with no Modal call; only when there is +none does it create and start a new run. Each answers 201 with the same +fields as the create, naming the run. A re-run is refused before anything is written: 404 (`unknown_report`, `unknown_simulation`) for a record that doesn't exist; 409 -`run_in_progress`, naming the run in `run_id`, while the record has a run -pending or running (for a report, its budget-window run, or else its report -run); 409 `rerun_not_supported` for a household simulation (re-run only +`rerun_not_supported` for a household simulation (re-run only through its report), a household report whose simulation names a dynamic (a household calculation applies none), a budget window whose newest window run lacks a year, or a record that names no region, dataset, year, simulation, @@ -277,18 +332,22 @@ household report's own codes: 400 `unknown_household` and `no_household_function`, and 422 `household_not_calculable`, located at the report's `household_id` or a side's `policy_id`. Without household reports configured, a household report the service could re-run answers 503 -`not_configured`. The check for a run under way and the inserts run under a -transaction-level advisory lock on the record's ID, so two re-runs of one -record never both create a run. A report's re-run checks only the report's -own runs: a side whose simulation has a run under way for another report, or -for the simulation's own re-run, still gets a new run, calculated -separately. A simulation's re-run checks every run of the simulation, -including those reports created. A report or simulation deleted after the +`not_configured`. No re-run is refused while a run is under way, and the +409 `run_in_progress` is gone. An unforced re-run of a report created by +key looks for the run to join and inserts under a transaction-level +advisory lock on the report's ID: a second one waits, then joins the +first's run. A simulation's re-run takes no lock: the Public API's index on +runs lets only one run that hasn't failed and wasn't forced exist on a +version set, so concurrent re-runs end on it. A forced re-run takes none +either, as nothing joins it. A re-run's answer names +the run it ended on; `GET /reports/{report_id}` and +`GET /simulations/{simulation_id}` read the newest run, which may be a later +one, such as a forced re-run's. A report or simulation deleted after the re-run read it answers 404. A report deleted with its simulations answers -400 `missing_reference`, naming a simulation, when a side gets a new run, as -a household report's sides always do, and 404 when both sides reuse a run; a -deleted budget-window report always answers 404, as its window run is -created first. When Modal refuses the new run's call, the run is failed, -with a household report's new simulation runs, and the 503 -`modal_call_refused` names the record and the run (`run_id`). +400 `missing_reference`, naming a simulation, when a side gets a new run, +and 404 when both sides join a run; a deleted budget-window report always +answers 404, as its window run is created first. When Modal refuses the new +run's call, the run is failed, with a forced run's new simulation runs, +which only it names, and the 503 `modal_call_refused` names the record and +the run (`run_id`). diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/app.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/app.py index 614c48111..ba75fa1d8 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/app.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/app.py @@ -575,7 +575,7 @@ def economy_submissions_for( It needs the simulation database and the v2 Modal environment; without them the economy routes answer 503. Nothing is read from Modal until the - first submission. Without the output bucket, no report reuses a run. It + first submission. It re-runs a household report through ``household_reports``; without it, a household report it could re-run answers 503. """ @@ -599,7 +599,6 @@ def economy_submissions_for( settings=ServiceSettings( environment=settings.environment, modal_environment=settings.v2_modal_environment, - output_bucket=settings.v2_simulation_output_bucket or None, ), ) diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/budget_window_api_models.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/budget_window_api_models.py index 467678e71..aecce669d 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/budget_window_api_models.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/budget_window_api_models.py @@ -24,6 +24,8 @@ from pydantic.json_schema import SkipJsonSchema from policyengine_simulation_entry.economy_api_models import ( + DESCRIPTION_NOT_STORED, + LABEL_NOT_STORED, CatalogKey, PolicyChoice, ReportDescription, @@ -56,8 +58,10 @@ class BudgetWindowReportRequest(BaseModel): country: CountryId report_type: Literal["budget_window"] - label: ReportLabel - description: ReportDescription | None = None + label: ReportLabel | None = Field(default=None, description=LABEL_NOT_STORED) + description: ReportDescription | None = Field( + default=None, description=DESCRIPTION_NOT_STORED + ) year: SimulationYear budget_window_size: BudgetWindowSize region_code: CatalogKey @@ -91,11 +95,11 @@ def years(self) -> tuple[int, ...]: return tuple(range(self.year, self.year + self.budget_window_size)) def options(self) -> dict[str, Any]: - """Return the report's options as it stores them (``reports.inputs``). + """Return the window's calculation options: no cliffs, and its SPM selection. - They are a single-year economy report's without cliffs, so the - window's years and such reports reuse each other's runs. ``spm`` - holds only the settings the request gave. + ``spm`` holds only the settings the request gave. The report stores + the selection alone (``economy_requests.stored_options``), and its + years share runs with single-year reports by key. """ options: dict[str, Any] = {"include_cliffs": False} if self.spm is not None: @@ -108,10 +112,11 @@ class _Answer(BaseModel): class BudgetWindowYearCreated(_Answer): - """One year of a created window: its report run and each side's run. + """One year of the window run a request ended on: its report run and sides. - ``…_reused`` is true for a side that names a run that already succeeded - in that year, rather than a new one. + ``…_reused`` is true for a side whose run this request didn't insert: + another request's run of that year's simulation, in any state, or, on + a joined window run, that run's own. """ year: int @@ -125,12 +130,14 @@ class BudgetWindowYearCreated(_Answer): class BudgetWindowReportCreated(_Answer): - """The budget-window report a request created, and its years' runs. - - ``report_run_id`` is the first year's report run, and ``status`` the - window's calculation's: ``pending`` once its first years' calls were - started, or when the start couldn't be recorded. ``years`` lists every - year, earliest first. + """The budget-window report and window run a request ended on, and its years. + + The window and window run are the ones a create found or created by + key, or a re-run joined or created. ``report_run_id`` is the first + year's report run, and ``status`` the window run's: for one the request + created, ``pending`` once its first years' calls were started, or when + the start couldn't be recorded; for a joined one, its status as read. + ``years`` lists every year, earliest first. """ report_id: UUID diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/budget_window_submissions.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/budget_window_submissions.py index ca120591f..ba8d84d64 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/budget_window_submissions.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/budget_window_submissions.py @@ -1,11 +1,18 @@ -"""Creating budget-window reports and starting their first years. - -A budget-window report is created as an economy report with one report run -per year of its window (``NewBudgetWindowReport``), all pending with no -Modal call, in one transaction. The service then advances the window as its -own role (``BudgetWindowStore.advance_window``): under the window run's row -lock, up to the earliest five years' coordinators are started and their -calls recorded. Each year's coordinator starts the next years when its year ends. +"""Finding or creating budget-window reports and starting their first years. + +A budget-window report is an economy report with one report run per year of +its window. Identical window requests, together or apart, end on the same +report, simulations, window run and year runs (C1 · 24's answer 8): in one +transaction the store finds each year's simulations and the report by +their keys, and the report's window run on the current versions that +hasn't failed and isn't a recalculation, or else creates the window run and +each year's report run on its sides' runs, found or inserted +(``find_or_create_budget_window``), all pending with no Modal call. Only +for a window run it created does the service then advance the window as +its own role (``BudgetWindowStore.advance_window``): under the window +run's row lock, up to the earliest five years' coordinators are started +and their calls recorded. Each year's coordinator starts the next ones when +its year ends. A joined window run is answered as it is. The first year's coordinator input is built as a single-year report's is; every later year's is derived from it (``year_calculation``), so all years @@ -21,7 +28,6 @@ import asyncio import logging import time -from dataclasses import replace from datetime import UTC, datetime from typing import TYPE_CHECKING, Any, Protocol from uuid import UUID, uuid4 @@ -33,10 +39,10 @@ year_calculation, ) from policyengine_simulation_persistence import ( - BudgetWindowYear, - NewBudgetWindowReport, + EconomyReportDefinition, + KeyedBudgetWindow, + KeyedWindowYear, ReportRunStatus, - RunReuse, SimulationChoice, ) from policyengine_stage12_persistence import RunStatus, YearStartDeferred @@ -49,6 +55,7 @@ from policyengine_simulation_entry.economy_calculation_inputs import ( report_run_calculation, ) +from policyengine_simulation_entry.economy_requests import stored_options from policyengine_simulation_entry.economy_submission_errors import call_refused from policyengine_simulation_entry.economy_submissions import ( CALL_START_TIMEOUT_SECONDS, @@ -61,13 +68,13 @@ ) if TYPE_CHECKING: - from collections.abc import Callable, Sequence + from collections.abc import Callable from policyengine_simulation_persistence import ( BudgetWindowInputs, EconomyRequest, - ReusableRun, - SimulationInputs, + FoundBudgetWindow, + FoundWindowYear, WindowYearRuns, ) from policyengine_stage12_persistence import ( @@ -100,14 +107,14 @@ def read_budget_window_inputs( *, baseline: SimulationChoice, reform: SimulationChoice, - reuse: RunReuse | None, - years: Sequence[int], ) -> BudgetWindowInputs: - """Read the window's catalog rows, both sides' values and each year's runs.""" + """Read the window's catalog rows and both sides' values.""" ... - def create_budget_window_report(self, report: NewBudgetWindowReport) -> None: - """Create the window's report, its budget-window run and each year's runs.""" + def find_or_create_budget_window( + self, window: KeyedBudgetWindow + ) -> FoundBudgetWindow: + """Find the window by key, with its window run, or create them.""" ... @@ -164,82 +171,93 @@ async def submit_budget_window( request_id: str, observability_context: dict[str, Any] | None, ) -> BudgetWindowReportCreated: - """Create the window's report and its years' runs, and start its first years. + """Find or create the window and its window run, and start a run it created. - Raise the errors ``submit_report`` raises; the 503 after a write - names the report, whose window was failed. + A window run the request joined is answered as it is, with no new + call. Raise the errors ``submit_report`` raises; the 503 after a + write names the report, whose window was failed. """ worker = await self._default_worker(request.country) options = request.options() - reuse_prefix = self._settings.reuse_prefix - reuse = ( - None - if reuse_prefix is None - else RunReuse( - versions=worker.versions, - inputs=options, - output_uri_prefix=reuse_prefix, - ) - ) + spm = options.get("spm") economy_request = economy_request_for(request, worker) inputs = await self._read_inputs( lambda: self._store.read_budget_window_inputs( economy_request, baseline=simulation_choice(request.baseline), reform=simulation_choice(request.reform), - reuse=reuse, - years=request.years, ), request=economy_request, ) - report = NewBudgetWindowReport( - id=self._new_id(), + catalog = inputs.catalog + window = KeyedBudgetWindow( + definition=EconomyReportDefinition( + country=request.country, + baseline=inputs.baseline.choice, + reform=inputs.reform.choice, + dataset_name=catalog.dataset.name, + region_code=catalog.region.code, + year=request.year, + budget_window_size=request.budget_window_size, + spm=spm, + ), + report_id=self._new_id(), window_run_id=self._new_id(), - country=request.country, - label=request.label, - description=request.description, - tax_benefit_model_id=inputs.catalog.model_id, - population=inputs.catalog.population(request.year), + tax_benefit_model_id=catalog.model_id, + population=catalog.population(request.year), versions=worker.versions, - inputs=options, - years=tuple(self._window_year(inputs, year) for year in request.years), - ) - first_year = report.first_year - first_calculation = report_run_calculation( - worker, - calculation_scope(request, worker, inputs.catalog, spm=options.get("spm")), - self._origin(request_id), - run_ids=year_run_ids(first_year), - baseline_policy=inputs.baseline.reform, - reform_policy=inputs.reform.reform, + inputs=stored_options(options), + years=tuple( + KeyedWindowYear( + year=year, + report_run_id=self._new_id(), + baseline=self._proposed_side(), + reform=self._proposed_side(), + ) + for year in request.years + ), ) - await self._create( - "report", lambda: self._store.create_budget_window_report(report) + scope = calculation_scope(request, worker, catalog, spm=spm) + proposed_first_year = window.years[0] + + def first_year_calculation(run_ids: ReportRunIds) -> RunCalculation: + return report_run_calculation( + worker, + scope, + self._origin(request_id), + run_ids=run_ids, + baseline_policy=inputs.baseline.reform, + reform_policy=inputs.reform.reform, + ) + + # Refused before anything is written, on the run IDs it proposes. + first_year_calculation( + ReportRunIds( + report_run_id=proposed_first_year.report_run_id, + baseline_simulation_run_id=proposed_first_year.baseline.simulation_run_id, + reform_simulation_run_id=proposed_first_year.reform.simulation_run_id, + ) ) - status = await self._start_first_years( - worker, - first_calculation, - report_id=report.id, - window_run_id=report.window_run_id, - first_year=first_year.year, - observability_context=observability_context, + found = await self._create( + "report", lambda: self._store.find_or_create_budget_window(window) ) + first_year = found.years[0] + status = found.window_run.status + if found.window_run.inserted: + status = await self._start_first_years( + worker, + first_year_calculation(year_run_ids(first_year)), + report_id=found.report_id, + window_run_id=found.window_run.id, + first_year=first_year.year, + observability_context=observability_context, + ) return BudgetWindowReportCreated( - report_id=report.id, + report_id=found.report_id, report_run_id=first_year.report_run_id, - budget_window_run_id=report.window_run_id, + budget_window_run_id=found.window_run.id, status=status, - years=[year_created(window_year) for window_year in report.years], - ) - - def _window_year(self, inputs: BudgetWindowInputs, year: int) -> BudgetWindowYear: - """Return a year naming its own year's reusable runs, or new ones.""" - baseline_run, reform_run = inputs.reusable_runs[year] - return BudgetWindowYear( - year=year, - report_run_id=self._new_id(), - baseline=self._side(_with_reusable(inputs.baseline, baseline_run)), - reform=self._side(_with_reusable(inputs.reform, reform_run)), + years=[year_created(window_year) for window_year in found.years], ) async def _start_first_years( # noqa: PLR0913 # the call, then the window it starts @@ -396,13 +414,6 @@ def _calculation( return year_report.model_dump(mode="json"), year_context.model_dump(mode="json") -def _with_reusable( - inputs: SimulationInputs, reusable_run: ReusableRun | None -) -> SimulationInputs: - """Return a side's values naming the year's reusable run, if any.""" - return replace(inputs, reusable_run=reusable_run) - - def _deferral(year_to_start: YearToStart) -> dict[str, Any]: """Return a deferred year's log fields: its year and its report run.""" return { @@ -420,8 +431,11 @@ def year_run_ids(window_year: WindowYearRuns) -> ReportRunIds: ) -def year_created(window_year: WindowYearRuns) -> BudgetWindowYearCreated: - """Return a new window's year, or a re-run's, as the answer lists it.""" +def year_created(window_year: FoundWindowYear) -> BudgetWindowYearCreated: + """Return a year of the window run a request ended on, as the answer lists it. + + A side is reused when its run isn't one this request inserted. + """ return BudgetWindowYearCreated( year=window_year.year, report_run_id=window_year.report_run_id, diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/config.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/config.py index 5b6ae75dd..58c935321 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/config.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/config.py @@ -102,10 +102,6 @@ class Settings: # manifest, and the manifest's name. Empty outside deployed environments. v2_modal_environment: str = "" v2_manifest_name: str = V2_VERSION_MANIFEST_NAME - # The bucket that keeps v2 simulation output files for good. An economy - # report reuses only a succeeded run whose file is in it; without it, no - # run is reused. Empty outside deployed environments. - v2_simulation_output_bucket: str = "" @classmethod def from_env(cls) -> Settings: @@ -161,7 +157,6 @@ def from_env(cls) -> Settings: v2_manifest_name=os.getenv( "SIMULATION_V2_MANIFEST_NAME", V2_VERSION_MANIFEST_NAME ), - v2_simulation_output_bucket=os.getenv("V2_SIMULATION_OUTPUT_BUCKET", ""), ) @property diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py index 8ab9bf797..0fb0546ea 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py @@ -18,10 +18,10 @@ is written; - 404 ``unknown_report`` or ``unknown_simulation`` when a re-run names no stored record; -- 409 with ``code`` and ``detail`` when a stored record is not re-run now: - ``run_in_progress``, naming the run pending or running (``run_id``), or - ``rerun_not_supported`` for a record this service does not re-run. - Nothing is written; +- 409 with ``code`` and ``detail``, ``rerun_not_supported``, for a stored + record this service does not re-run. Nothing is written. No re-run is + refused while a run is under way: an unforced one joins it, and a forced + one is an extra run; - 422 when the request's fields, or the stored values it names, cannot be calculated. Nothing is written; - 503 with ``code`` and ``detail`` when the service cannot answer now. Only @@ -52,6 +52,15 @@ CatalogKey = Annotated[str, Field(min_length=1, max_length=255, pattern=r"^\S+$")] ReportLabel = Annotated[str, Field(min_length=1, max_length=255)] ReportDescription = Annotated[str, Field(max_length=10_000)] +# A report's name and description are accepted and not stored: each user's +# saved report in the Public API holds them (C1 · 24's answer 6). +LABEL_NOT_STORED = ( + "The report's name, accepted for the Public API's callers and not stored: " + "each user's saved report holds it." +) +DESCRIPTION_NOT_STORED = ( + "The report's description, accepted and not stored, as the label is." +) # Why a request is refused (400), naming a row the caller chose that doesn't # exist: the Public API answers these as its caller's error. On a re-run they @@ -85,13 +94,12 @@ # be read, or the household functions' contract refuses what the report # would calculate: located at the household or a side's policy. "household_not_calculable", + # A report asks for cliffs (include_cliffs: true), which wait for each + # simulation run's own cliff calculation (C1 · 39); located at the field. + "cliffs_not_available", ] # Why a stored record is not re-run now (409). EconomyConflictCode = Literal[ - # The record has a run pending or running; ``run_id`` names it: for a - # report, its budget-window run, or else its report run; for a - # simulation, its simulation run. - "run_in_progress", # The service does not re-run this kind of record, or the record lacks a # row it calculates on. "rerun_not_supported", @@ -154,16 +162,19 @@ class EconomyReportRequest(_Request): """An economy report: a baseline and a reform simulation of one region's data. Both simulations use the report's year, region and dataset, as - ``EconomySimulationRequest`` describes them. ``include_cliffs`` also - calculates the baseline's and reform's cliff impact. ``spm`` selects the + ``EconomySimulationRequest`` describes them. ``include_cliffs: true`` is + refused (422 ``cliffs_not_available``) until cliffs are calculated per + simulation run (C1 · 39). ``spm`` selects the SPM forecast scenario and geography; omit it, rather than sending null, to use the bundle's certified defaults. """ country: CountryId report_type: Literal["economy"] - label: ReportLabel - description: ReportDescription | None = None + label: ReportLabel | None = Field(default=None, description=LABEL_NOT_STORED) + description: ReportDescription | None = Field( + default=None, description=DESCRIPTION_NOT_STORED + ) year: SimulationYear region_code: CatalogKey dataset_name: CatalogKey | None = None @@ -184,10 +195,11 @@ def refuse_null_spm(cls, value: object) -> object: return value def options(self) -> dict[str, Any]: - """Return the report's options as it stores them (``reports.inputs``). + """Return the request's options, as its calculation reads them. ``spm`` holds only the settings the request gave, and is left out - when it gave none. + when it gave none. The report stores the selection alone + (``economy_requests.stored_options``). """ options: dict[str, Any] = {"include_cliffs": self.include_cliffs} if self.spm is not None: @@ -198,9 +210,14 @@ def options(self) -> dict[str, Any]: class ReportRerunRequest(_Request): """A stored report's re-run on the default worker's versions. - Without ``force``, a side reuses a run of its own simulation that - succeeded on those versions, as a new report's side does; with it, both - simulations are calculated again. + Without ``force``, a re-run of a report created by key (economy, + budget window or household) joins the report's run on those versions + that hasn't failed and wasn't forced, pending, running or succeeded, + and otherwise each side joins its simulation's run on them or gets a + new one, as a new report's side does. With it, and always for a report + created before keys (C1 · 24's interim answer B), the report's + simulations are calculated again, as an extra run marked forced that + nothing joins. """ force: StrictBool = False @@ -211,12 +228,14 @@ class _Answer(BaseModel): class EconomySimulationCreated(_Answer): - """The simulation a request created or re-ran, its new run and its status. - - The status is the run's when its call's ID was recorded: ``pending``, or - whatever the simulation function had made it by then if it claimed the - run first. A run whose call Modal didn't confirm, or whose call's ID - couldn't be recorded, is answered ``pending``. + """The simulation a request created or re-ran, its run and that run's status. + + For a run the request created, the status is the run's when its call's + ID was recorded: ``pending``, or whatever the simulation function had + made it by then if it claimed the run first. A run whose call Modal + didn't confirm, or whose call's ID couldn't be recorded, is answered + ``pending``. A re-run that joined a run answers that run's status as + read. """ simulation_id: UUID @@ -225,14 +244,17 @@ class EconomySimulationCreated(_Answer): class EconomyReportCreated(_Answer): - """The report a request created or re-ran, its new run and its status. - - The status is the run's when its call's ID was recorded: ``pending``, or - whatever the coordinator had made it by then if it claimed the run - first. A run whose call Modal didn't confirm, or whose call's ID couldn't - be recorded, is answered ``pending``. Each side names its - simulation and simulation run; ``…_reused`` is true for a side that - names a run that already succeeded, rather than a new one. + """The report a request ended on, its run and that run's status. + + The report and run are the ones a create found or created by key, or a + re-run joined or created. For a run the request created, the status is + the run's when its call's ID was recorded: ``pending``, or whatever the + coordinator had made it by then if it claimed the run first. A run whose + call Modal didn't confirm, or whose call's ID couldn't be recorded, is + answered ``pending``. A joined run answers its status as read. Each side + names its simulation and simulation run; ``…_reused`` is true for a side + whose run this request didn't create: another request's run, in any + state, that the side joined, or, on a joined report run, that run's own. """ report_id: UUID @@ -303,10 +325,7 @@ class EconomyError(_Answer): ``/simulations``) is set only with ``modal_call_refused``: it names the record the service created or re-ran, whose new run it failed because Modal refused the call or didn't accept it in time. ``run_id`` names - that new run on a re-run (a budget window's: its budget-window run), - and with ``run_in_progress`` the record's run that is pending or - running: a report's budget-window run, or else its report run, or a - simulation's run. + that new run on a re-run (a budget window's: its budget-window run). """ code: EconomyErrorCode diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_requests.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_requests.py new file mode 100644 index 000000000..5139ac641 --- /dev/null +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_requests.py @@ -0,0 +1,174 @@ +"""What a report or simulation request becomes before and after its rows exist. + +The submission services (``economy_submissions``, ``budget_window_submissions``) +turn a request into the persistence library's ``EconomyRequest``, refuse what +can't be calculated yet (as the re-run service does for a stored report), +choose what a report stores of the request's +options, the calculation's scope on the default worker's bundle, and the +answer for the report and run a request ended on. +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, Any + +from policyengine_simulation_persistence import EconomyRequest + +from policyengine_simulation_entry.economy_api_models import EconomyReportCreated +from policyengine_simulation_entry.economy_calculation_inputs import ( + CalculationScope, + DatasetNotInBundleError, + bundle_dataset, + simulation_options, +) +from policyengine_simulation_entry.economy_submission_errors import ( + EconomySubmissionRefusedError, + EconomySubmissionUnprocessableError, + UnprocessableReason, +) + +if TYPE_CHECKING: + from collections.abc import Mapping + + from policyengine_simulation_persistence import ( + EconomyCatalogRows, + FoundEconomyReport, + ReportRunStatus, + ) + + from policyengine_simulation_entry.budget_window_api_models import ( + BudgetWindowReportRequest, + ) + from policyengine_simulation_entry.economy_api_models import ( + EconomyRefusalCode, + EconomyReportRequest, + EconomySimulationRequest, + ) + from policyengine_simulation_entry.economy_workers import EconomyWorker + + +def refuse_cliffs(request: EconomyReportRequest) -> None: + """Refuse ``include_cliffs: true`` until per-run cliff calculations exist. + + Identical requests share a report and its runs, so a cliff request can't + change what they calculate; C1 · 39 calculates each simulation run's + cliffs on its own instead (C1 · 24's interim answer A). + """ + if request.include_cliffs: + raise _cliffs_refused( + ("body", "include_cliffs"), + "Cliff impacts are not calculated yet: they will be calculated " + "for each simulation run on its own. Send include_cliffs: false.", + ) + + +def refuse_stored_cliffs(stored_inputs: Mapping[str, Any]) -> None: + """Refuse re-running a report stored asking for cliffs, until they exist. + + A report created before C1 · 27 stored its request's options; one whose + ``include_cliffs`` is true is refused as such a request now is (the + scope of C1 · 24's interim answer A). + """ + if stored_inputs.get("include_cliffs"): + raise _cliffs_refused( + ("report", "inputs", "include_cliffs"), + "This report was created asking for cliff impacts, which are not " + "calculated yet: they will be calculated for each simulation run " + "on its own.", + ) + + +def _cliffs_refused( + loc: tuple[str, ...], message: str +) -> EconomySubmissionUnprocessableError: + """Return the 422 refusing a cliff calculation, naming what asked for it.""" + return EconomySubmissionUnprocessableError( + code="cliffs_not_available", + reasons=( + UnprocessableReason(loc=loc, msg=message, type="cliffs_not_available"), + ), + ) + + +def stored_options(options: dict[str, Any]) -> dict[str, Any]: + """Return what a report stores of a request's options: the SPM selection. + + A report has no options of its own (C1 · 24's answer 4): ``include_cliffs`` + is a request option, never stored or keyed. + """ + return {name: value for name, value in options.items() if name == "spm"} + + +def report_created( + found: FoundEconomyReport, status: ReportRunStatus +) -> EconomyReportCreated: + """Answer the report and run a request ended on, with ``status``. + + A side is reused when this request didn't insert its run. + """ + return EconomyReportCreated( + report_id=found.report_id, + report_run_id=found.run.id, + status=status, + baseline_simulation_id=found.baseline.simulation_id, + baseline_simulation_run_id=found.baseline.simulation_run_id, + baseline_reused=not found.baseline.run_inserted, + reform_simulation_id=found.reform.simulation_id, + reform_simulation_run_id=found.reform.simulation_run_id, + reform_reused=not found.reform.run_inserted, + ) + + +def economy_request_for( + request: EconomyReportRequest + | EconomySimulationRequest + | BudgetWindowReportRequest, + worker: EconomyWorker, +) -> EconomyRequest: + """Return what the request names apart from policies, for the default worker.""" + return EconomyRequest( + country=request.country, + policyengine_version=worker.policyengine_version, + region_code=request.region_code, + dataset_name=request.dataset_name, + year=request.year, + ) + + +def calculation_scope( + request: EconomyReportRequest + | EconomySimulationRequest + | BudgetWindowReportRequest, + worker: EconomyWorker, + catalog: EconomyCatalogRows, + *, + spm: dict[str, Any] | None, +) -> CalculationScope: + """Return what the calculation runs on, with the bundle's dataset. + + Raise EconomySubmissionRefusedError when the bundle lacks the catalog + dataset: ``unknown_dataset`` when the request named it, and + ``dataset_not_in_bundle`` for the region's default. + """ + try: + dataset = bundle_dataset(worker, catalog.dataset.name) + except DatasetNotInBundleError: + code: EconomyRefusalCode = ( + "dataset_not_in_bundle" + if request.dataset_name is None + else "unknown_dataset" + ) + detail = ( + f"The default v2 worker, .py {worker.version}, has no dataset " + f"{catalog.dataset.name}." + ) + raise EconomySubmissionRefusedError(code=code, detail=detail) from None + return CalculationScope( + country=request.country, + region_code=catalog.region.code, + dataset=dataset, + year=request.year, + options=simulation_options( + include_cliffs=getattr(request, "include_cliffs", False), spm=spm + ), + ) diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_rerun_routes.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_rerun_routes.py index ae4675171..bda053bcb 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_rerun_routes.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_rerun_routes.py @@ -1,25 +1,37 @@ """The re-run routes: calculate a stored report or simulation again as a new run. - ``POST /reports/{report_id}/runs`` (permission ``simulation:submit``) - creates the stored report's new run on the v2 version manifest's default - worker and starts its coordinator, answering 201 with the report's ID, the - new run's ID and status, and each side's simulation and simulation run. - ``{"force": true}`` calculates both simulations again; otherwise a side - reuses a run of its own simulation that succeeded on the same versions. - A budget-window report's new run is a budget-window run with a report run - per year, up to five of them started at once as a new window's are; it - answers as the budget-window create does, naming the window run and every - year's runs. A household report's new run gives each side a new run of its - own household simulation, never reusing one, started by one household - function call; it answers as the household report create does. -- ``POST /simulations/{simulation_id}/runs`` (``simulation:submit``) creates - the stored simulation's new run and starts its simulation function, - answering 201 with the simulation's ID, the new run's ID and its status. + joins the stored report's run on the v2 version manifest's default + worker's versions, or creates its new run and starts its coordinator, + answering 201 with the report's ID, the run's ID and status, and each + side's simulation and simulation run. A report created by key has each + side join its simulation's run on those versions, or get a new one. + ``{"force": true}``, and every re-run of a report created before keys, + calculates both simulations again, as an extra run marked forced that + nothing joins. + A budget-window report's run is a budget-window run with a report run + per year, a new one's first five started at once as a new window's are; + it answers as the budget-window create does, naming the window run and + every year's runs. A household report's re-run joins or creates its run as an + economy report's does, each side's run of its own household simulation, + and a run it created is started by one household function call; it + answers as the household report create does. +- ``POST /simulations/{simulation_id}/runs`` (``simulation:submit``) joins + the stored simulation's run on the current versions that hasn't failed + and wasn't forced, pending, running or succeeded, or else creates one and + starts its + simulation function, answering 201 with the simulation's ID, the run's ID + and its status. Every earlier run is kept. A re-run answers 404 for a record that does not -exist, and 409 when the record has a run pending or running -(``run_in_progress``, naming it in ``run_id``) or is one this service does -not re-run (``rerun_not_supported``); then nothing is written. The other +exist, and 409 for a record this service does not re-run +(``rerun_not_supported``); then nothing is written. No re-run is refused +while a run is under way. Without ``force``, a keyed economy or household +report's re-run joins the report's run on the current versions that +hasn't failed and wasn't forced, pending, running or succeeded, and +answers it with no new call. A report stored asking for +cliff impacts answers 422 ``cliffs_not_available`` until they are +calculated per run. The other answers are the creates': 400 or 422 when the stored record cannot be calculated on the current catalog version, 503 with ``Retry-After`` before any write or when Modal refused the new run's call (then the run was failed, @@ -109,11 +121,8 @@ class EconomyService(EconomySubmissions, EconomyReruns, Protocol): """Create, read and re-run economy reports and simulations.""" -# The run a 409 run_in_progress names, by the record re-run. -_RUN_UNDER_WAY: dict[RecordName, str] = { - "report": "the report's budget-window run, or else its report run", - "simulation": "the simulation's run", -} +# Why a re-run answers 409; no run under way refuses one. +_CONFLICT = "the service does not re-run it (rerun_not_supported)" # The 400 codes that name a stored record's own rows on its re-run: a # report's re-run also names its stored simulations (missing_reference) and # a household report's its household. @@ -137,12 +146,27 @@ class EconomyService(EconomySubmissions, EconomyReruns, Protocol): }, "simulation": {503: "Economy runs are not configured"}, } +# A report stored before C1 · 27 asking for cliff impacts is refused until +# they are calculated per run (C1 · 24's interim answer A). +_STORED_CLIFFS: dict[RecordName, str] = { + "report": ( + "; or the stored report asks for cliff impacts, which are not " + "calculated yet (cliffs_not_available, located under report)" + ), + "simulation": "", +} def _responses(record: RecordName) -> dict[int | str, dict[str, Any]]: """Return every answer a re-run of ``record`` declares.""" return { - 201: {"description": f"The {record}'s new run was created and started"}, + 201: { + "description": ( + f"The {record}'s run the re-run ended on: one it joined, pending, " + "running or succeeded on the default worker's versions, which " + "gets no new call, or one it created and started" + ) + }, 400: { "description": ( f"The stored {record}'s region, dataset, policy or dynamic is " @@ -161,10 +185,7 @@ def _responses(record: RecordName) -> dict[int | str, dict[str, Any]]: }, 409: { "description": ( - f"The {record} is not re-run now, and nothing was written: it " - "has a run pending or running (run_in_progress; run_id names " - f"{_RUN_UNDER_WAY[record]}), or the service does not re-run it " - "(rerun_not_supported)" + f"The {record} is not re-run, and nothing was written: {_CONFLICT}" ), **ERROR_ANSWER, }, @@ -173,8 +194,8 @@ def _responses(record: RecordName) -> dict[int | str, dict[str, Any]]: "The ID or the body is malformed, or the stored policies and " "dynamics cannot be calculated on the current catalog version " "(missing_parameters or overlapping_parameters, located under " - f"{record}){_HOUSEHOLD_ANSWERS[record].get(422, '')}; nothing was " - "written" + f"{record}){_HOUSEHOLD_ANSWERS[record].get(422, '')}" + f"{_STORED_CLIFFS[record]}; nothing was written" ), "model": EconomyRequestUnprocessable, }, @@ -209,7 +230,7 @@ def _rerun_failure_response( if isinstance(error, EconomyRerunConflictError): return error_response( status.HTTP_409_CONFLICT, - EconomyError(code=error.code, detail=error.detail, run_id=error.run_id), + EconomyError(code=error.code, detail=error.detail), ) return submission_failure_response(error, record) @@ -268,14 +289,19 @@ async def answer( # the route, its record and how to re-run it description=( "Create the stored report's new run on the v2 version manifest's " "default worker, and start it; every earlier run is kept. Without " - "force, a side reuses a run of its own simulation that succeeded " - "on the same versions; with force, both simulations are " - "calculated again. A budget-window report's new run is a " - "budget-window run with a report run per year, up to five of them " - "started at once, each year on its own year's simulations. A " - "household report's new run calculates its stored household in " - "the report's year with a new run of each side's own household " - "simulation, never reused, all in one household function call." + "force, a report created by key joins the " + "report's run on those versions that hasn't failed and wasn't " + "forced, pending, running or succeeded, and answers it with no new " + "call; otherwise each side joins its simulation's run on those " + "versions or gets a new one. With force, and always for a report " + "created before keys, the report's simulations are calculated " + "again, as an extra run marked forced that nothing joins. A report " + "stored asking for cliff impacts is refused (422 " + "cliffs_not_available). A budget-window report's run is a " + "budget-window run with a report run per year, a new one's first " + "five started at once, each year on its own year's simulations. " + "A household report's run calculates its stored household in the " + "report's year, in one household function call." ), operation_id="rerun_report", status_code=status.HTTP_201_CREATED, @@ -305,9 +331,10 @@ async def rerun_report( SIMULATION_RUNS_PATH, summary="Re-run an economy simulation", description=( - "Create the stored simulation's new run on the v2 version " - "manifest's default worker, and start it; every earlier run is " - "kept, and the new run is always calculated." + "Join the stored simulation's run on the v2 version manifest's " + "default worker's versions that hasn't failed and wasn't forced, " + "pending, running or succeeded, or else create one and start it; " + "every earlier run is kept." ), operation_id="rerun_simulation", status_code=status.HTTP_201_CREATED, diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_reruns.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_reruns.py index 6573aea78..c95772da3 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_reruns.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_reruns.py @@ -4,43 +4,52 @@ default worker, as a new run, and keeps every earlier run. The service: 1. reads what the record calculates: its country, year, region code, - dataset name and each simulation's policy and dynamic. A record this - service does not re-run, or one missing a row it calculates on, is - refused (409 ``rerun_not_supported``), as is one that does not exist - (404); + dataset name, stored options and each simulation's policy and dynamic. + A record this service does not re-run, or one missing a row it + calculates on, is refused (409 ``rerun_not_supported``), as is one that + does not exist (404), and a report stored before C1 · 27 asking for + cliff impacts (422 ``cliffs_not_available``) until they are calculated + per run (C1 · 24's interim answer A); 2. finds the default worker's economy functions for the country, and reads, in one transaction, the country's catalog version for that worker's .py version, its region and dataset with the record's code and name, and each - simulation's policy and dynamic values on that catalog version. For a - report, unless the re-run is forced, each side's reusable run is a run of - that side's own simulation that succeeded on the current versions, as a - new report's would be (``find_reusable_run_of``); -3. creates, in one transaction, the new run (a report's with trigger - ``manual``) and each report side's new simulation run of its own - simulation, all pending with no Modal call ID, unless the record has a - run pending or running (409 ``run_in_progress``); -4. starts and records the new run's call as a new record's: the report run's - coordinator, or the simulation function, by run ID (C1 · 8's - coordination), failing the new runs when Modal refuses the call. - -A budget-window report's re-run is a new budget-window run with a report -run per year, each year on the simulations that year's report run of the -report's newest window run names; its first years start as a new window's -do. A household report's re-run is the household report service's -(``household_report_reruns``): a new run of each side's own household -simulation, started by one household function call. A household simulation -is re-run only through its report. Whatever is missing or cannot be -calculated is refused in steps 1 and 2, before anything is written. + simulation's policy and dynamic values on that catalog version; +3. for a simulation or a keyed economy report, joins, in one transaction, + the record's run on the current versions that hasn't failed and wasn't + forced, pending, running or succeeded (C1 · 24's answers 2 and 3), or + else creates the new run (naming no trigger, answer 6); a keyed + report's sides join their simulations' runs on those versions the same + way, or create them. A report whose simulations have no key, created + before C1 · 27, may have runs whose plans depended on the report that + calculated them, so its re-run, like a forced re-run, always creates its + runs, marked forced: extra runs that nothing joins (interim answer B). A + keyed budget window's re-run joins its window run on those versions, or + creates one whose years' sides join their simulations' runs (answer 8). + Every new run is pending with no Modal call ID, and a forced re-run is + never refused while a run is under way; +4. starts and records the call of a run it created as a new record's: the + report run's coordinator, or the simulation function, by run ID (C1 · 8's + coordination), failing the new runs when Modal refuses the call. A + joined run gets no call: whoever created it started it. + +A budget-window report's re-run joins or creates a budget-window run with +a report run per year, each year on the simulations that year's report +run of the report's newest window run names; a window run it created has +its first years started as a new window's do. A household report's re-run +is the household report service's (``household_report_reruns``), which +joins or creates its run as an economy report's re-run does, a run it +created started by one household function call. A household simulation is +re-run only through its report. Whatever is missing or cannot be calculated is refused +in steps 1 and 2, before anything is written. """ from __future__ import annotations from dataclasses import dataclass from datetime import UTC, datetime -from typing import TYPE_CHECKING, Any, Final, Protocol, get_args +from typing import TYPE_CHECKING, Any, Final, Protocol from uuid import uuid4 -from policyengine_simulation_contract.stage12_bundle import CountryId from policyengine_simulation_contract.stage12_execution import ReportRunIds from policyengine_simulation_persistence import ( EconomyRequest, @@ -48,7 +57,6 @@ NewSimulationRerun, NewWindowRerun, RerunSide, - RunReuse, WindowRerunYear, ) @@ -66,40 +74,40 @@ EconomySimulationCreated, ) from policyengine_simulation_entry.economy_calculation_inputs import ( - CalculationScope, - DatasetNotInBundleError, - bundle_dataset, report_run_calculation, - simulation_options, simulation_run_calculation, ) +from policyengine_simulation_entry.economy_requests import refuse_stored_cliffs from policyengine_simulation_entry.economy_submission_errors import ( STORED_REPORT, STORED_SIMULATION, EconomyRecordNotFoundError, - EconomyRerunConflictError, - EconomySubmissionRefusedError, EconomySubmissionUnavailableError, rerun_refusals, ) from policyengine_simulation_entry.economy_submissions import ( CALL_START_TIMEOUT_SECONDS, ) -from policyengine_simulation_entry.household_report_reruns import ( - StoredHouseholdReport, +from policyengine_simulation_entry.rerunnable_records import ( + StoredReportRows, + complete_window_years, + rerun_scope, + rerunnable_household_report, + rerunnable_report, + rerunnable_simulation, ) if TYPE_CHECKING: - from collections.abc import Callable, Sequence + from collections.abc import Callable from uuid import UUID from policyengine_simulation_persistence import ( BudgetWindowInputs, - EconomyCatalogRows, EconomyReportInputs, - RecordKind, + FoundBudgetWindow, + FoundReportRun, + FoundSimulationRun, ReportDefinition, - ReusableRun, SideDefinition, SimulationChoice, SimulationDefinition, @@ -129,12 +137,6 @@ HouseholdReportReruns, ) -# The kinds of stored economy report this service re-runs itself. -_RERUN_REPORT_KINDS: Final[frozenset[RecordKind]] = frozenset( - {"economy", "budget_window"} -) -# The countries this service calculates, as the contract names them. -_COUNTRIES: Final[tuple[CountryId, ...]] = get_args(CountryId) _REPORT: Final[RecordName] = "report" _SIMULATION: Final[RecordName] = "simulation" @@ -161,9 +163,8 @@ def read_report_rerun_inputs( *, baseline: SideDefinition, reform: SideDefinition, - reuse: RunReuse | None, ) -> EconomyReportInputs: - """Read a re-run's catalog rows, both sides' values and reusable runs.""" + """Read a re-run's catalog rows and both sides' values.""" ... def read_window_rerun_inputs( @@ -172,22 +173,20 @@ def read_window_rerun_inputs( *, baseline: SimulationChoice, reform: SimulationChoice, - years: Sequence[WindowYearDefinition], - reuse: RunReuse | None, ) -> BudgetWindowInputs: - """Read a window re-run's catalog rows, both sides' values and years' runs.""" + """Read a window re-run's catalog rows and both sides' values.""" ... - def create_window_rerun(self, rerun: NewWindowRerun) -> None: - """Create the window's new run, each year's report run and new runs.""" + def create_window_rerun(self, rerun: NewWindowRerun) -> FoundBudgetWindow: + """Join the window's run on the re-run's versions, or create it.""" ... - def create_report_rerun(self, rerun: NewReportRerun) -> None: - """Create the report's new run and its sides' new simulation runs.""" + def create_report_rerun(self, rerun: NewReportRerun) -> FoundReportRun: + """Join the report's run on the re-run's versions, or create it.""" ... - def create_simulation_rerun(self, rerun: NewSimulationRerun) -> None: - """Create the simulation's new run.""" + def create_simulation_rerun(self, rerun: NewSimulationRerun) -> FoundSimulationRun: + """Join the simulation's run on the re-run's versions, or create it.""" ... @@ -232,12 +231,13 @@ async def rerun_report( request_id: str, observability_context: dict[str, Any] | None, ) -> EconomyReportCreated | BudgetWindowReportCreated | HouseholdReportCreated: - """Create the stored report's new run on the current versions, and start it. + """Join or create the stored report's run on the current versions. - A budget window's new run is a budget-window run with a report run - per year, whose first years are started (``_rerun_window``); a - household report's is the household report service's, which - ``force`` changes nothing for. Raise EconomyRecordNotFoundError (404) + A budget window's run is a budget-window run with a report run per + year, a new one's first years started (``_rerun_window``); a + household report's is the household report service's, which joins + or forces as an economy report's does. Raise + EconomyRecordNotFoundError (404) or EconomyRerunConflictError (409) as the module describes, and otherwise the errors ``submit_report`` raises, a 503 for Modal's refusal naming the new run as well as the report. @@ -249,11 +249,14 @@ async def rerun_report( raise EconomyRecordNotFoundError(_REPORT) if definition.kind == "household": return await self._rerun_household_report( - definition, observability_context=observability_context + definition, + force=request.force, + observability_context=observability_context, ) - stored = _rerunnable_report(definition) + stored = rerunnable_report(definition) + refuse_stored_cliffs(definition.inputs) window_years = ( - _complete_window_years(definition) + complete_window_years(definition) if definition.kind == "budget_window" else () ) @@ -265,15 +268,10 @@ async def rerun_report( dataset_name=stored.dataset_name, year=stored.year, ) - reuse = ( - None - if request.force or self._settings.reuse_prefix is None - else RunReuse( - versions=worker.versions, - inputs=definition.inputs, - output_uri_prefix=self._settings.reuse_prefix, - ) - ) + # A report with no keys gets extra runs, marked forced, which + # nothing joins (interim answer B); a keyed report's sides join + # their simulations' runs on these versions instead. + forced = request.force or not definition.keyed if window_years: return await self._rerun_window( _WindowRerunRequest( @@ -281,8 +279,7 @@ async def rerun_report( options=definition.inputs, years=window_years, economy_request=economy_request, - reuse=reuse, - recalculate=request.force, + recalculate=forced, ), worker, request_id=request_id, @@ -293,7 +290,6 @@ async def rerun_report( economy_request, baseline=stored.baseline, reform=stored.reform, - reuse=reuse, ), request=economy_request, source=STORED_REPORT, @@ -303,56 +299,48 @@ async def rerun_report( run_id=self._new_id(), population=inputs.catalog.population(stored.year), versions=worker.versions, - baseline=self._rerun_side( - stored.baseline.simulation_id, inputs.baseline.reusable_run - ), - reform=self._rerun_side( - stored.reform.simulation_id, inputs.reform.reusable_run - ), + baseline=self._new_side(stored.baseline.simulation_id), + reform=self._new_side(stored.reform.simulation_id), + forced=forced, + ) + scope = rerun_scope( + stored.country, + economy_request, + worker, + inputs.catalog, + options=definition.inputs, + ) + found = await self._create_rerun( + _REPORT, + lambda: self._store.create_report_rerun(rerun), + source=STORED_REPORT, ) + if not found.inserted: + return _joined_report_run(stored, found) + answer = _created_report_run(stored, rerun, found) calculation = report_run_calculation( worker, - _rerun_scope( - stored.country, - economy_request, - worker, - inputs.catalog, - options=definition.inputs, - ), + scope, self._origin(request_id), run_ids=ReportRunIds( - report_run_id=rerun.run_id, - baseline_simulation_run_id=rerun.baseline.simulation_run_id, - reform_simulation_run_id=rerun.reform.simulation_run_id, + report_run_id=answer.report_run_id, + baseline_simulation_run_id=answer.baseline_simulation_run_id, + reform_simulation_run_id=answer.reform_simulation_run_id, ), baseline_policy=inputs.baseline.reform, reform_policy=inputs.reform.reform, ) - await self._create_rerun( - _REPORT, - lambda: self._store.create_report_rerun(rerun), - source=STORED_REPORT, - ) status = await self._start_report_run( worker, calculation, report_id=report_id, run_id=rerun.run_id, - new_simulation_run_ids=rerun.new_simulation_run_ids, + # An unforced re-run's simulation runs may be another report run's. + new_simulation_run_ids=rerun.new_simulation_run_ids if forced else (), observability_context=observability_context, rerun=True, ) - return EconomyReportCreated( - report_id=report_id, - report_run_id=rerun.run_id, - status=status, - baseline_simulation_id=rerun.baseline.simulation_id, - baseline_simulation_run_id=rerun.baseline.simulation_run_id, - baseline_reused=rerun.baseline.reused, - reform_simulation_id=rerun.reform.simulation_id, - reform_simulation_run_id=rerun.reform.simulation_run_id, - reform_reused=rerun.reform.reused, - ) + return answer.model_copy(update={"status": status}) async def rerun_simulation( self, @@ -361,18 +349,18 @@ async def rerun_simulation( request_id: str, observability_context: dict[str, Any] | None, ) -> EconomySimulationCreated: - """Create the stored simulation's new run on the current versions, and start it. + """Join or create the stored simulation's run on the current versions. - The run is always calculated: a simulation run is the calculation, - with nothing of it to reuse. Raise the errors ``rerun_report`` raises, - naming the simulation. + A run the store created is started; one it joined, pending, running + or succeeded, is answered as it is, with no call. Raise the errors + ``rerun_report`` raises, naming the simulation. """ definition = await self._read_state( lambda: self._store.read_simulation_definition(simulation_id) ) if definition is None: raise EconomyRecordNotFoundError(_SIMULATION) - stored = _rerunnable_simulation(definition) + stored = rerunnable_simulation(definition) worker = await self._default_worker(stored.country) economy_request = EconomyRequest( country=stored.country, @@ -396,18 +384,24 @@ async def rerun_simulation( ) calculation = simulation_run_calculation( worker, - _rerun_scope( + rerun_scope( stored.country, economy_request, worker, inputs.catalog, options={} ), self._origin(request_id), simulation_run_id=rerun.run_id, policy=inputs.simulation.reform, ) - await self._create_rerun( + found = await self._create_rerun( _SIMULATION, lambda: self._store.create_simulation_rerun(rerun), source=STORED_SIMULATION, ) + if not found.inserted: + return EconomySimulationCreated( + simulation_id=simulation_id, + simulation_run_id=found.id, + status=found.status, + ) status = await self._start_simulation_run( worker, calculation, @@ -426,16 +420,17 @@ async def _rerun_household_report( self, definition: ReportDefinition, *, + force: bool, observability_context: dict[str, Any] | None, ) -> HouseholdReportCreated: """Hand a stored household report the service can re-run to its service.""" - stored = _rerunnable_household_report(definition) + stored = rerunnable_household_report(definition) if self._household_reports is None: raise EconomySubmissionUnavailableError( code="not_configured", detail="Household reports are not configured." ) return await self._household_reports.rerun_report( - stored, observability_context=observability_context + stored, force=force, observability_context=observability_context ) async def _rerun_window( @@ -446,12 +441,15 @@ async def _rerun_window( request_id: str, observability_context: dict[str, Any] | None, ) -> BudgetWindowReportCreated: - """Create the window's new run and each year's runs; start its first years. - - Each year's sides are that year's own simulations, as its report run - in the report's newest window run names them, and each year reuses a - run of its own simulations unless the re-run is forced. The years - start as a new window's do (``_start_first_years``). + """Join or create the window's run on the current versions. + + Each year's sides are runs of that year's own simulations, as its + report run in the report's newest window run names them. A keyed + window's unforced re-run joins its window run, or each year's sides + join their simulations' runs; a forced one, or one of a window + created before keys (interim answer B), recalculates every year as + forced runs. Only a window run it created has its first years + started, as a new window's are (``_start_first_years``). """ stored = window.stored inputs = await self._read_inputs( @@ -459,8 +457,6 @@ async def _rerun_window( window.economy_request, baseline=stored.baseline.choice, reform=stored.reform.choice, - years=window.years, - reuse=window.reuse, ), request=window.economy_request, source=STORED_REPORT, @@ -472,213 +468,145 @@ async def _rerun_window( population=inputs.catalog.population(stored.year), versions=worker.versions, recalculate=window.recalculate, - years=tuple(self._window_rerun_year(year, inputs) for year in window.years), + years=tuple(self._window_rerun_year(year) for year in window.years), ) - first_year = rerun.years[0] - first_calculation = report_run_calculation( + scope = rerun_scope( + stored.country, + window.economy_request, worker, - _rerun_scope( - stored.country, - window.economy_request, - worker, - inputs.catalog, - options=window.options, - ), + inputs.catalog, + options=window.options, + ) + # Refused before anything is written, on the run IDs it proposes. + report_run_calculation( + worker, + scope, self._origin(request_id), - run_ids=year_run_ids(first_year), + run_ids=year_run_ids(rerun.years[0]), baseline_policy=inputs.baseline.reform, reform_policy=inputs.reform.reform, ) - await self._create_rerun( + found = await self._create_rerun( _REPORT, lambda: self._store.create_window_rerun(rerun), source=STORED_REPORT, ) - status = await self._start_first_years( - worker, - first_calculation, - report_id=stored.report_id, - window_run_id=window_run_id, - first_year=first_year.year, - observability_context=observability_context, - rerun=True, - ) + found_first_year = found.years[0] + status = found.window_run.status + if found.window_run.inserted: + status = await self._start_first_years( + worker, + report_run_calculation( + worker, + scope, + self._origin(request_id), + run_ids=year_run_ids(found_first_year), + baseline_policy=inputs.baseline.reform, + reform_policy=inputs.reform.reform, + ), + report_id=stored.report_id, + window_run_id=found.window_run.id, + first_year=found_first_year.year, + observability_context=observability_context, + rerun=True, + ) return BudgetWindowReportCreated( report_id=stored.report_id, - report_run_id=first_year.report_run_id, - budget_window_run_id=window_run_id, + report_run_id=found_first_year.report_run_id, + budget_window_run_id=found.window_run.id, status=status, - years=[year_created(window_year) for window_year in rerun.years], + years=[year_created(window_year) for window_year in found.years], ) - def _window_rerun_year( - self, year: WindowYearDefinition, inputs: BudgetWindowInputs - ) -> WindowRerunYear: - """Return a year naming its own simulations' reusable runs, or new runs.""" - baseline_run, reform_run = inputs.reusable_runs[year.year] + def _window_rerun_year(self, year: WindowYearDefinition) -> WindowRerunYear: + """Return a year naming new runs of its own simulations.""" return WindowRerunYear( year=year.year, report_run_id=self._new_id(), - baseline=self._rerun_side(year.baseline_simulation_id, baseline_run), - reform=self._rerun_side(year.reform_simulation_id, reform_run), + baseline=self._new_side(year.baseline_simulation_id), + reform=self._new_side(year.reform_simulation_id), ) - def _rerun_side( - self, simulation_id: UUID, reusable_run: ReusableRun | None - ) -> RerunSide: - """Return a side naming its own simulation's reusable run, or a new run.""" - if reusable_run is not None: - return RerunSide( - simulation_id=simulation_id, - simulation_run_id=reusable_run.simulation_run_id, - reused=True, - ) + def _new_side(self, simulation_id: UUID) -> RerunSide: + """Return a side proposing a new run of its own simulation. + + The run is created, unless a keyed report's side joins its + simulation's run on the re-run's versions. + """ return RerunSide( simulation_id=simulation_id, simulation_run_id=self._new_id(), - reused=False, ) - async def _create_rerun( + async def _create_rerun[Created]( self, record: RecordName, - create: Callable[[], None], + create: Callable[[], Created], *, source: RefusalSource, - ) -> None: - """Create the re-run's rows; refuse it while the record has a run under way. - - A record deleted after its reads is answered as not found. Any other - row the database refuses is named as ``source``'s; for a report, - that includes a side's simulation deleted with it. + ) -> Created: + """Create or join the re-run's rows, answering the store's refusals. + + Return what ``create`` returns: the run it joined or created. A + record deleted after its reads is + answered as not found. Any other row the database refuses is named + as ``source``'s; for a report, that includes a side's simulation + deleted with it. """ with rerun_refusals(record): - await self._create(record, create, rerun=True, source=source) - - -@dataclass(frozen=True) -class _StoredReportRows: - """The country and rows a stored report calculates on, each present.""" - - report_id: UUID - country: CountryId - year: int - region_code: str - dataset_name: str - baseline: SideDefinition - reform: SideDefinition - - -@dataclass(frozen=True) -class _StoredSimulationRows: - """The country and rows a stored simulation calculates on, each present.""" - - country: CountryId - year: int - region_code: str - dataset_name: str - + return await self._create(record, create, rerun=True, source=source) -def _calculated_country(country: str | None) -> CountryId | None: - """Return the country if this service calculates it, or None.""" - return next((known for known in _COUNTRIES if known == country), None) +def _joined_report_run( + stored: StoredReportRows, joined: FoundReportRun +) -> EconomyReportCreated: + """Answer the report's run a re-run joined, as it is; this call created nothing. -def _refusal( - record: RecordName, kind: RecordKind, missing: tuple[tuple[str, object], ...] -) -> EconomyRerunConflictError: - """Return why a stored record is not re-run: its kind, or the first row it lacks. - - ``missing`` pairs each row's description with the value the record holds. + Only a keyed report's unforced re-run joins a run; it names runs of the + report's own simulations, which this call didn't create, so both sides + are reused. """ - if kind == "unsupported": - detail = f"The service does not re-run this type of {record}." - elif record == _SIMULATION and kind == "household": - detail = ( - "The service re-runs a household simulation only through its report " - "(POST /reports/{report_id}/runs)." - ) - else: - lacking = next(name for name, value in missing if value is None) - detail = f"The {record} names no {lacking}, so it cannot be re-run." - return EconomyRerunConflictError(code="rerun_not_supported", detail=detail) - - -def _rerunnable_report(definition: ReportDefinition) -> _StoredReportRows: - """Return the stored report's rows, or refuse one this service can't re-run.""" - baseline, reform = definition.baseline, definition.reform - region_code, dataset_name = definition.region_code, definition.dataset_name - country, year = _calculated_country(definition.country), definition.year - if ( - definition.kind not in _RERUN_REPORT_KINDS - or country is None - or baseline is None - or reform is None - or region_code is None - or dataset_name is None - or year is None - ): - raise _refusal( - _REPORT, - definition.kind, - ( - ("country this service calculates", country), - ("baseline simulation", baseline), - ("reform simulation", reform), - ("region", region_code), - ("dataset", dataset_name), - ("year", year), - ), - ) - return _StoredReportRows( - report_id=definition.id, - country=country, - year=year, - region_code=region_code, - dataset_name=dataset_name, - baseline=baseline, - reform=reform, + if joined.reform_simulation_run_id is None: + msg = f"report run {joined.id} of an economy report names no reform run" + raise ValueError(msg) + return EconomyReportCreated( + report_id=stored.report_id, + report_run_id=joined.id, + status=joined.status, + baseline_simulation_id=stored.baseline.simulation_id, + baseline_simulation_run_id=joined.baseline_simulation_run_id, + baseline_reused=True, + reform_simulation_id=stored.reform.simulation_id, + reform_simulation_run_id=joined.reform_simulation_run_id, + reform_reused=True, ) -def _rerunnable_household_report( - definition: ReportDefinition, -) -> StoredHouseholdReport: - """Return the stored household report's rows, or refuse one it can't re-run. +def _created_report_run( + stored: StoredReportRows, rerun: NewReportRerun, created: FoundReportRun +) -> EconomyReportCreated: + """Answer the report run a re-run created, with the side runs it names. - A side naming a dynamic is refused: a household calculation applies none. + A side is reused when its run isn't one this re-run inserted: for a + keyed report, its simulation's run the store joined. The runs this + re-run may have inserted have the IDs its sides proposed; one + simulation on both sides gets one run, with the baseline's. The status + is the new run's, until its call is started. """ - country, year = _calculated_country(definition.country), definition.year - household_id, baseline = definition.household_id, definition.baseline - if country is None or household_id is None or baseline is None or year is None: - raise _refusal( - _REPORT, - definition.kind, - ( - ("country this service calculates", country), - ("household", household_id), - ("baseline simulation", baseline), - ("year", year), - ), - ) - if any( - side is not None and side.choice.dynamic_id is not None - for side in (baseline, definition.reform) - ): - raise EconomyRerunConflictError( - code="rerun_not_supported", - detail=( - "The report's household simulation names a dynamic, which a " - "household calculation does not apply, so it cannot be re-run." - ), - ) - return StoredHouseholdReport( - report_id=definition.id, - country=country, - household_id=household_id, - year=year, - baseline=baseline, - reform=definition.reform, + if created.reform_simulation_run_id is None: + msg = f"report run {created.id} of an economy report names no reform run" + raise ValueError(msg) + proposed = {rerun.baseline.simulation_run_id, rerun.reform.simulation_run_id} + return EconomyReportCreated( + report_id=stored.report_id, + report_run_id=created.id, + status=created.status, + baseline_simulation_id=stored.baseline.simulation_id, + baseline_simulation_run_id=created.baseline_simulation_run_id, + baseline_reused=created.baseline_simulation_run_id not in proposed, + reform_simulation_id=stored.reform.simulation_id, + reform_simulation_run_id=created.reform_simulation_run_id, + reform_reused=created.reform_simulation_run_id not in proposed, ) @@ -686,107 +614,8 @@ def _rerunnable_household_report( class _WindowRerunRequest: """What a budget window's re-run calculates, as the service has read it.""" - stored: _StoredReportRows + stored: StoredReportRows options: dict[str, Any] years: tuple[WindowYearDefinition, ...] economy_request: EconomyRequest - reuse: RunReuse | None recalculate: bool - - -def _complete_window_years( - definition: ReportDefinition, -) -> tuple[WindowYearDefinition, ...]: - """Return the stored window's years, or refuse a window that lacks one. - - Its newest calculation must have a report run naming both sides in each - year of its window, from the report's first year; the definition leaves - out a year naming no reform. - """ - expected = ( - () - if definition.year is None or definition.budget_window_size is None - else tuple( - range(definition.year, definition.year + definition.budget_window_size) - ) - ) - years = definition.window_years - if not expected or tuple(year.year for year in years) != expected: - raise EconomyRerunConflictError( - code="rerun_not_supported", - detail=( - "The report names no complete budget-window calculation, a " - "report run naming both sides in each year of its window, so " - "it cannot be re-run." - ), - ) - return years - - -def _rerunnable_simulation(definition: SimulationDefinition) -> _StoredSimulationRows: - """Return the stored simulation's country and rows, or refuse it. - - Its country is None when its catalog version's model is of no country - this service calculates. - """ - country, year = _calculated_country(definition.country), definition.year - region_code, dataset_name = definition.region_code, definition.dataset_name - if ( - definition.kind != "economy" - or country is None - or region_code is None - or dataset_name is None - or year is None - ): - raise _refusal( - _SIMULATION, - definition.kind, - ( - ("country this service calculates", country), - ("region", region_code), - ("dataset", dataset_name), - ("year", year), - ), - ) - return _StoredSimulationRows( - country=country, - year=year, - region_code=region_code, - dataset_name=dataset_name, - ) - - -def _rerun_scope( - country: CountryId, - request: EconomyRequest, - worker: EconomyWorker, - catalog: EconomyCatalogRows, - *, - options: dict[str, Any], -) -> CalculationScope: - """Return what a re-run calculates on, with the bundle's dataset. - - ``options`` are the stored report's (``reports.inputs``). Raise - EconomySubmissionRefusedError (``dataset_not_in_bundle``) when the - default worker's bundle lacks the stored dataset. - """ - try: - dataset = bundle_dataset(worker, catalog.dataset.name) - except DatasetNotInBundleError: - raise EconomySubmissionRefusedError( - code="dataset_not_in_bundle", - detail=( - f"The default v2 worker, .py {worker.version}, has no dataset " - f"{catalog.dataset.name}, which the stored record names." - ), - ) from None - return CalculationScope( - country=country, - region_code=catalog.region.code, - dataset=dataset, - year=request.year, - options=simulation_options( - include_cliffs=bool(options.get("include_cliffs", False)), - spm=options.get("spm"), - ), - ) diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_routes.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_routes.py index 80a46798f..2462d6023 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_routes.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_routes.py @@ -1,20 +1,26 @@ """The economy routes: create a report or a simulation, and start its calculation. -- ``POST /reports`` (permission ``simulation:submit``) creates an economy - report, its simulations and its first run, and starts the report run's - coordinator, answering 201 with the report's ID, its run's ID and status, +- ``POST /reports`` (permission ``simulation:submit``) finds or creates an + economy report and its simulations by key, and joins its run on the + current versions or creates one, starting the coordinator only for a run + it created, answering 201 with the report's ID, its run's ID and status, and each side's simulation and simulation run. With ``report_type`` - ``budget_window`` it creates a budget-window report with a report run per - year and starts up to its first five years, answering 201 with the report, the - first year's run, the window run, its status and every year's runs. With - ``household`` it creates a household report, a household simulation and - run for its baseline and any reform, and its first run, and starts one - household function call for the report run, answering 201 with the - report, its run, its status, its year and each side's simulation and - simulation run. -- ``POST /simulations`` (``simulation:submit``) creates a standalone - economy simulation and its first run, and starts the run's simulation - function, answering 201 with the simulation's ID, its run's ID and status. + ``budget_window`` it finds or creates a budget-window report by key, each + year's simulations by their year's keys, and joins its window run on the + current versions or creates one with a report run per year, starting up + to the first five years only of a window run it created, answering 201 + with the report, the first year's run, the window run, its status and + every year's runs. With + ``household`` it finds or creates a household report and a household + simulation for its baseline and any reform by key, and joins its run on + the current versions or creates one, starting one household function + call only for a run it created, answering 201 with the report, its run, + its status, its year and each side's simulation and simulation run. +- ``POST /simulations`` (``simulation:submit``) finds or creates a + standalone economy simulation by key and joins or creates its run on the + current versions, starting the run's simulation function only for a run + it created, answering 201 with the simulation's ID, its run's ID and + status. - ``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. The Public API reads results from the @@ -24,8 +30,9 @@ missing; ``code`` says which) or 422 (its fields, or the stored values it names, cannot be calculated), and writes nothing. Either route answers 503 with ``Retry-After`` when it is not configured or a dependency cannot be -read, before writing anything, or when Modal refused the run's call: then -the record was created and its run failed, and the answer names it. Every +read, before writing anything, or when Modal refused the call of the run +the request created: then the record it found or created is kept, that +run failed, and the answer names the record. Every 500 the routes answer is the JSON error with code ``internal_error``, and may follow a write; a failure outside a handler's ``try`` gets the request middleware's own plain-text 500, which the Public API reads alike. @@ -135,7 +142,9 @@ "cannot be calculated; nothing was written. Stored values that cannot " "be calculated carry a code: missing_parameters, " "overlapping_parameters, or household_not_calculable for a household " - "report's household" + "report's household; a report asking for cliffs (include_cliffs: " + "true) carries cliffs_not_available until each simulation run's own " + "cliff calculation exists" ), "model": EconomyRequestUnprocessable, } @@ -171,9 +180,10 @@ def _unavailable_description(record: RecordName) -> dict[str, Any]: "description": ( "Economy runs are not configured, or the v2 version manifest or the " "database cannot be read, and nothing was written; or Modal refused " - "the run's call, or didn't accept it in time " - f"(modal_call_refused): then the {record} named by {record}_id was " - "created and its run failed. Retry after Retry-After seconds" + "the call of the run this request created, or didn't accept it in " + f"time (modal_call_refused): then the {record} named by {record}_id, " + "found or created, is kept and that run failed. Retry after " + "Retry-After seconds" ), "headers": RETRY_AFTER_HEADER, **ERROR_ANSWER, @@ -531,18 +541,26 @@ def _submission_routes( REPORTS_PATH, summary="Create an economy, budget-window or household report", description=( - "Create an economy report comparing a baseline and a reform " - "simulation of one region's data for one year, on the v2 version " - "manifest's default worker, and start its first run. A side whose " - "simulation already succeeded on the same versions reuses that run. " + "Find or create an economy report comparing a baseline and a " + "reform simulation of one region's data for one year, by a key of " + "its definition, on the v2 version manifest's default worker: an " + "identical request ends on the same report and run. The report's " + "run on those versions that hasn't failed and wasn't forced is " + "joined, with no new call; otherwise each side joins its " + "simulation's run on those versions or gets a new one, and the new " + "report run is started. " "A budget-window report (report_type budget_window) compares them " "in each year of a window of 1 to 75 years, with a report run per " - "year, at most five running at once; each year reuses its own " - "year's runs. " + "year, at most five running at once, found or created by key as " + "an economy report is: its window run on the current versions is " + "joined, and each year's sides join their simulations' runs, which " + "a single-year report of that year shares. " "A household report (report_type household) calculates one stored " "household for its default year under a baseline and, optionally, " - "a reform, each a new household simulation run, all in one " - "household function call." + "a reform, found or created by a key of its definition as an " + "economy report is, its run on the current versions joined or " + "created; a run it created is started by one household function " + "call." ), operation_id="create_report", status_code=status.HTTP_201_CREATED, @@ -550,7 +568,15 @@ def _submission_routes( EconomyReportCreated | BudgetWindowReportCreated | HouseholdReportCreated ), responses={ - 201: {"description": "The report and its first runs were created"}, + 201: { + "description": ( + "The report the request ended on and its run: a report " + "(economy, budget window or household) found or created by " + "key, with its run (a window's: its window run) on the " + "default worker's versions, joined (no new call) or created " + "and started" + ) + }, 400: _REFUSED, 403: FORBIDDEN_ANSWER, 422: _UNPROCESSABLE, @@ -578,15 +604,23 @@ async def create_report(body: ReportRequest, request: Request) -> JSONResponse: SIMULATIONS_PATH, summary="Create an economy simulation", description=( - "Create a standalone economy simulation of one region's data for " - "one year under one stored policy and dynamic, on the v2 version " - "manifest's default worker, and start its first run." + "Find or create a standalone economy simulation of one region's " + "data for one year under one stored policy and dynamic, by a key of " + "its definition, on the v2 version manifest's default worker, and " + "join its run on those versions that hasn't failed and wasn't " + "forced, or else create and start one." ), operation_id="create_simulation", status_code=status.HTTP_201_CREATED, response_model=EconomySimulationCreated, responses={ - 201: {"description": "The simulation and its first run were created"}, + 201: { + "description": ( + "The simulation the request ended on, found or created by " + "key, and its run on the default worker's versions, joined " + "(no new call) or created and started" + ) + }, 400: _REFUSED, 403: FORBIDDEN_ANSWER, 422: _UNPROCESSABLE, diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submission_errors.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submission_errors.py index ac50b0132..10c882ee4 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submission_errors.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submission_errors.py @@ -22,7 +22,6 @@ OverlappingReformError, ReportSideError, RerunRecordDeletedError, - RunInProgressError, UnknownCatalogVersionError, UnknownDatasetError, UnknownDynamicError, @@ -151,20 +150,13 @@ def __init__(self, record: RecordName) -> None: class EconomyRerunConflictError(Exception): - """A stored record is not re-run now (409); nothing was written. + """A stored record is not re-run (409); nothing was written.""" - ``run_id`` names the record's run pending or running, with - ``run_in_progress``. - """ - - def __init__( - self, *, code: EconomyConflictCode, detail: str, run_id: UUID | None = None - ) -> None: - """Keep the reason's code, its description and any run under way.""" + def __init__(self, *, code: EconomyConflictCode, detail: str) -> None: + """Keep the reason's code and its description.""" super().__init__(detail) self.code: EconomyConflictCode = code self.detail = detail - self.run_id = run_id class EconomySubmissionUnavailableError(Exception): @@ -354,20 +346,11 @@ def call_refused( def rerun_refusals(record: RecordName) -> Iterator[None]: """Answer a re-run's create that the record's state refused. - A record deleted after the re-run read it is not found (404); a record - with a run pending or running is not re-run now (409 ``run_in_progress``, - naming that run). Nothing was created either way. + A record deleted after the re-run read it is not found (404); nothing + was created. No re-run the service sends is refused while a run is + under way: an unforced one joins it, and a forced one is an extra run. """ try: yield except RerunRecordDeletedError: raise EconomyRecordNotFoundError(record) from None - except RunInProgressError as error: - raise EconomyRerunConflictError( - code="run_in_progress", - detail=( - f"The {record} has a run pending or running; re-run it once " - "that run has ended." - ), - run_id=error.run_id, - ) from None diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submissions.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submissions.py index e9fef6726..644b99d41 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submissions.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submissions.py @@ -1,29 +1,36 @@ """Create economy reports and simulations, and start the calls that calculate them. A report submission names a region, a dataset, a year and each side's -stored policy and dynamic. The service: +stored policy and dynamic. Identical submissions, together or apart, end on +the same simulation, report and run rows (C1 · 24). The service: 1. finds the v2 version manifest's default worker's economy functions for the country, and its bundle; 2. reads, in one transaction, the country's catalog version for that - worker's .py version, the region and dataset, each side's policy and - dynamic values, and, when the output bucket is configured, each side's - reusable run: a run of the same simulation that succeeded on the same - versions, used by a succeeded report run with the same options, and - never refused for reuse; -3. creates, in one transaction, each side's new simulation and pending run - (none for a reused side), the report with its options, and its first - report run, pending with no Modal call ID; -4. starts the coordinator's call with ``spawn``, passing the report and its - run IDs, then records the call's ID while the report run is still - pending with none (the coordinator may have claimed it already). When - Modal refuses the call, or does not confirm it in time, it fails the - report run and its new simulation runs at once instead, under the same - condition; a run the coordinator claimed meanwhile, because Modal - accepted the call after all, is left as it is and answered ``pending``. - -A standalone simulation is created and started the same way, with one -simulation run calculated by the country's simulation function. + worker's .py version, the region and dataset, and each side's policy and + dynamic values; +3. finds or creates, in one transaction, each side's simulation and the + report by their keys (the catalog's dataset name and region code, the + year, the policies, dynamics and SPM selection), then the report's run + on the current versions that hasn't failed and wasn't forced, which it + joins, or else each simulation's run on those versions and a new report + run naming them (``keyed_economy_records``). The report stores only the + SPM selection of the request's options (answer 4); +4. starts the coordinator's call with ``spawn`` only for a report run its + own transaction inserted, passing the report and its run IDs, then + records the call's ID while the report run is still pending with none + (the coordinator may have claimed it already). When Modal refuses the + call, or does not confirm it in time, it fails the report run at once + instead, under the same condition, and leaves the simulation runs + pending: another report run may name them, and the next coordinator + that does starts them. A run the coordinator claimed meanwhile, because + Modal accepted the call after all, is left as it is and answered + ``pending``. A joined report run gets no call and is answered with its + status as read. + +A standalone simulation is found or created by key and started the same +way, with one simulation run calculated by the country's simulation +function. Whatever is missing or cannot be calculated is refused in steps 1 and 2, before anything is written. The coordinator and the simulation functions @@ -44,12 +51,14 @@ from policyengine_simulation_persistence import ( EconomyRecordOutcomeUnknownError, EconomyRecordReferenceError, + EconomyReportDefinition, EconomyRequest, - NewEconomyReport, - NewEconomySimulation, + EconomySimulationDefinition, + KeyedEconomyReport, + KeyedEconomySimulation, + ProposedSide, ReportRunStatus, - ReportSimulation, - RunReuse, + SharedRowNotSettledError, SimulationChoice, SimulationStatus, ) @@ -60,14 +69,17 @@ EconomySimulationCreated, ) from policyengine_simulation_entry.economy_calculation_inputs import ( - CalculationScope, CallOrigin, - DatasetNotInBundleError, - bundle_dataset, report_run_calculation, - simulation_options, simulation_run_calculation, ) +from policyengine_simulation_entry.economy_requests import ( + calculation_scope, + economy_request_for, + refuse_cliffs, + report_created, + stored_options, +) from policyengine_simulation_entry.economy_submission_errors import ( REQUEST_BODY, EconomySubmissionOutcomeUnknownError, @@ -90,19 +102,15 @@ from collections.abc import Callable, Sequence from policyengine_simulation_persistence import ( - EconomyCatalogRows, EconomyReportInputs, EconomyReportState, EconomySimulationInputs, EconomySimulationState, - SimulationInputs, + FoundEconomyReport, + FoundEconomySimulation, ) - from policyengine_simulation_entry.budget_window_api_models import ( - BudgetWindowReportRequest, - ) from policyengine_simulation_entry.economy_api_models import ( - EconomyRefusalCode, EconomyReportRequest, EconomySimulationRequest, PolicyChoice, @@ -132,9 +140,8 @@ def read_report_inputs( *, baseline: SimulationChoice, reform: SimulationChoice, - reuse: RunReuse | None, ) -> EconomyReportInputs: - """Read a report's catalog rows, both sides' values and reusable runs.""" + """Read a report's catalog rows and both sides' values.""" ... def read_simulation_inputs( @@ -143,12 +150,14 @@ def read_simulation_inputs( """Read a standalone simulation's catalog rows and values.""" ... - def create_report(self, report: NewEconomyReport) -> None: - """Create the report, its new simulations and its runs.""" + def find_or_create_report(self, report: KeyedEconomyReport) -> FoundEconomyReport: + """Find the report by key, with its run, or create them.""" ... - def create_simulation(self, simulation: NewEconomySimulation) -> None: - """Create the simulation and its first run.""" + def find_or_create_simulation( + self, simulation: KeyedEconomySimulation + ) -> FoundEconomySimulation: + """Find the simulation by key, with its run, or create them.""" ... def record_report_call( @@ -191,19 +200,12 @@ def read_simulation(self, simulation_id: UUID) -> EconomySimulationState | None: class ServiceSettings: """The deployment the service runs in. - ``environment`` labels the calls' artifacts, ``modal_environment`` holds - the v2 workers, and ``output_bucket`` is the bucket that keeps - simulation output files for good. Without it, no report reuses a run. + ``environment`` labels the calls' artifacts, and ``modal_environment`` + holds the v2 workers. """ environment: str modal_environment: str - output_bucket: str | None = None - - @property - def reuse_prefix(self) -> str | None: - """Return ``gs:///``, under which reusable output files lie.""" - return None if not self.output_bucket else f"gs://{self.output_bucket}/" def _database_unavailable() -> EconomySubmissionUnavailableError: @@ -262,76 +264,67 @@ async def submit_report( EconomySubmissionOutcomeUnknownError (500) when the create's commit failed after its rows were inserted. """ + refuse_cliffs(request) worker = await self._default_worker(request.country) options = request.options() - reuse_prefix = self._settings.reuse_prefix - reuse = ( - None - if reuse_prefix is None - else RunReuse( - versions=worker.versions, - inputs=options, - output_uri_prefix=reuse_prefix, - ) - ) + spm = options.get("spm") economy_request = economy_request_for(request, worker) inputs = await self._read_inputs( lambda: self._store.read_report_inputs( economy_request, baseline=simulation_choice(request.baseline), reform=simulation_choice(request.reform), - reuse=reuse, ), request=economy_request, ) - scope = calculation_scope( - request, worker, inputs.catalog, spm=options.get("spm") - ) - report = NewEconomyReport( - id=self._new_id(), + scope = calculation_scope(request, worker, inputs.catalog, spm=spm) + catalog = inputs.catalog + keyed = KeyedEconomyReport( + definition=EconomyReportDefinition( + country=request.country, + baseline=inputs.baseline.choice, + reform=inputs.reform.choice, + dataset_name=catalog.dataset.name, + region_code=catalog.region.code, + year=request.year, + budget_window_size=None, + spm=spm, + ), + report_id=self._new_id(), run_id=self._new_id(), - country=request.country, - label=request.label, - description=request.description, - tax_benefit_model_id=inputs.catalog.model_id, - population=inputs.catalog.population(request.year), + baseline=self._proposed_side(), + reform=self._proposed_side(), + tax_benefit_model_id=catalog.model_id, + population=catalog.population(request.year), versions=worker.versions, - inputs=options, - baseline=self._side(inputs.baseline), - reform=self._side(inputs.reform), - ) - calculation = report_run_calculation( - worker, - scope, - self._origin(request_id), - run_ids=ReportRunIds( - report_run_id=report.run_id, - baseline_simulation_run_id=report.baseline.simulation_run_id, - reform_simulation_run_id=report.reform.simulation_run_id, - ), - baseline_policy=inputs.baseline.reform, - reform_policy=inputs.reform.reform, - ) - await self._create("report", lambda: self._store.create_report(report)) - status = await self._start_report_run( - worker, - calculation, - report_id=report.id, - run_id=report.run_id, - new_simulation_run_ids=report.new_simulation_run_ids, - observability_context=observability_context, + inputs=stored_options(options), ) - return EconomyReportCreated( - report_id=report.id, - report_run_id=report.run_id, - status=status, - baseline_simulation_id=report.baseline.simulation_id, - baseline_simulation_run_id=report.baseline.simulation_run_id, - baseline_reused=report.baseline.reused, - reform_simulation_id=report.reform.simulation_id, - reform_simulation_run_id=report.reform.simulation_run_id, - reform_reused=report.reform.reused, + found = await self._create( + "report", lambda: self._store.find_or_create_report(keyed) ) + status = found.run.status + if found.run.inserted: + calculation = report_run_calculation( + worker, + scope, + self._origin(request_id), + run_ids=ReportRunIds( + report_run_id=found.run.id, + baseline_simulation_run_id=found.baseline.simulation_run_id, + reform_simulation_run_id=found.reform.simulation_run_id, + ), + baseline_policy=inputs.baseline.reform, + reform_policy=inputs.reform.reform, + ) + status = await self._start_report_run( + worker, + calculation, + report_id=found.report_id, + run_id=found.run.id, + new_simulation_run_ids=(), + observability_context=observability_context, + ) + return report_created(found, status) async def submit_simulation( self, @@ -355,33 +348,43 @@ async def submit_simulation( request=economy_request, ) scope = calculation_scope(request, worker, inputs.catalog, spm=None) - simulation = NewEconomySimulation( - id=self._new_id(), + catalog = inputs.catalog + keyed = KeyedEconomySimulation( + definition=EconomySimulationDefinition( + country=request.country, + choice=inputs.simulation.choice, + dataset_name=catalog.dataset.name, + region_code=catalog.region.code, + year=request.year, + spm=None, + ), + simulation_id=self._new_id(), run_id=self._new_id(), - choice=inputs.simulation.choice, - population=inputs.catalog.population(request.year), + population=catalog.population(request.year), versions=worker.versions, ) - calculation = simulation_run_calculation( - worker, - scope, - self._origin(request_id), - simulation_run_id=simulation.run_id, - policy=inputs.simulation.reform, - ) - await self._create( - "simulation", lambda: self._store.create_simulation(simulation) - ) - status = await self._start_simulation_run( - worker, - calculation, - simulation_id=simulation.id, - run_id=simulation.run_id, - observability_context=observability_context, + found = await self._create( + "simulation", lambda: self._store.find_or_create_simulation(keyed) ) + status = found.run.status + if found.run.inserted: + calculation = simulation_run_calculation( + worker, + scope, + self._origin(request_id), + simulation_run_id=found.run.id, + policy=inputs.simulation.reform, + ) + status = await self._start_simulation_run( + worker, + calculation, + simulation_id=found.simulation_id, + run_id=found.run.id, + observability_context=observability_context, + ) return EconomySimulationCreated( - simulation_id=simulation.id, - simulation_run_id=simulation.run_id, + simulation_id=found.simulation_id, + simulation_run_id=found.run.id, status=status, ) @@ -413,20 +416,10 @@ async def _read_state[State](self, read: Callable[[], State]) -> State: ) raise _database_unavailable() from None - def _side(self, inputs: SimulationInputs) -> ReportSimulation: - """Return a side naming its reusable run, or a new simulation and run.""" - if inputs.reusable_run is not None: - return ReportSimulation( - simulation_id=inputs.reusable_run.simulation_id, - simulation_run_id=inputs.reusable_run.simulation_run_id, - choice=inputs.choice, - reused=True, - ) - return ReportSimulation( - simulation_id=self._new_id(), - simulation_run_id=self._new_id(), - choice=inputs.choice, - reused=False, + def _proposed_side(self) -> ProposedSide: + """Return the IDs a side's rows get if this request inserts them.""" + return ProposedSide( + simulation_id=self._new_id(), simulation_run_id=self._new_id() ) def _origin(self, request_id: str) -> CallOrigin: @@ -480,23 +473,24 @@ async def _read_inputs[Inputs]( raise raise refusal from None - async def _create( + async def _create[Created]( self, record: RecordName, - create: Callable[[], None], + create: Callable[[], Created], *, rerun: bool = False, source: RefusalSource = REQUEST_BODY, - ) -> None: + ) -> Created: """Create the rows; answer a refusal, an unknown outcome or an outage. - A commit that failed after the rows were inserted may have written - them, so it is never answered as unavailable, which would tell the - caller nothing was created. ``rerun`` says the rows are a stored - record's new run, and ``source`` what names a refused row. + Return what ``create`` returns. A commit that failed after the rows + were inserted may have written them, so it is never answered as + unavailable, which would tell the caller nothing was created. + ``rerun`` says the rows are a stored record's new run, and ``source`` + what names a refused row. """ try: - await asyncio.to_thread(create) + return await asyncio.to_thread(create) except EconomyRecordReferenceError as error: raise reference_refusal(error, source) from None except EconomyRecordOutcomeUnknownError as error: @@ -504,7 +498,9 @@ async def _create( raise EconomySubmissionOutcomeUnknownError( record, error_type=type(error.__cause__).__name__, rerun=rerun ) from None - except SQLAlchemyError as error: + # A run kept failing between a lookup's insert and its read; its + # transaction wrote nothing, so the caller may ask again. + except (SharedRowNotSettledError, SQLAlchemyError) as error: logger.warning( "economy_records_not_created", extra={"error_type": type(error).__name__}, @@ -674,56 +670,16 @@ async def _record_call( return None if status is None else str(status) -def economy_request_for( - request: EconomyReportRequest - | EconomySimulationRequest - | BudgetWindowReportRequest, - worker: EconomyWorker, -) -> EconomyRequest: - """Return what the request names apart from policies, for the default worker.""" - return EconomyRequest( - country=request.country, - policyengine_version=worker.policyengine_version, - region_code=request.region_code, - dataset_name=request.dataset_name, - year=request.year, - ) - - -def calculation_scope( - request: EconomyReportRequest - | EconomySimulationRequest - | BudgetWindowReportRequest, - worker: EconomyWorker, - catalog: EconomyCatalogRows, - *, - spm: dict[str, Any] | None, -) -> CalculationScope: - """Return what the calculation runs on, with the bundle's dataset. - - Raise EconomySubmissionRefusedError when the bundle lacks the catalog - dataset: ``unknown_dataset`` when the request named it, and - ``dataset_not_in_bundle`` for the region's default. - """ - try: - dataset = bundle_dataset(worker, catalog.dataset.name) - except DatasetNotInBundleError: - code: EconomyRefusalCode = ( - "dataset_not_in_bundle" - if request.dataset_name is None - else "unknown_dataset" - ) - detail = ( - f"The default v2 worker, .py {worker.version}, has no dataset " - f"{catalog.dataset.name}." - ) - raise EconomySubmissionRefusedError(code=code, detail=detail) from None - return CalculationScope( - country=request.country, - region_code=catalog.region.code, - dataset=dataset, - year=request.year, - options=simulation_options( - include_cliffs=getattr(request, "include_cliffs", False), spm=spm - ), - ) +# The request helpers moved to economy_requests; their names stay importable here. +__all__ = [ + "CALL_START_TIMEOUT_SECONDS", + "EconomyRuns", + "EconomySubmissionService", + "ServiceSettings", + "calculation_scope", + "economy_request_for", + "refuse_cliffs", + "report_created", + "simulation_choice", + "stored_options", +] diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/household_report_api_models.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/household_report_api_models.py index d3764b54b..c18a2ddf9 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/household_report_api_models.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/household_report_api_models.py @@ -18,9 +18,11 @@ from policyengine_simulation_contract.stage12_bundle import CountryId from policyengine_simulation_persistence import ReportRunStatus -from pydantic import BaseModel, ConfigDict +from pydantic import BaseModel, ConfigDict, Field from policyengine_simulation_entry.economy_api_models import ( + DESCRIPTION_NOT_STORED, + LABEL_NOT_STORED, ReportDescription, ReportLabel, ) @@ -50,8 +52,10 @@ class HouseholdReportRequest(_Request): country: CountryId report_type: Literal["household"] - label: ReportLabel - description: ReportDescription | None = None + label: ReportLabel | None = Field(default=None, description=LABEL_NOT_STORED) + description: ReportDescription | None = Field( + default=None, description=DESCRIPTION_NOT_STORED + ) household_id: UUID baseline: HouseholdPolicyChoice reform: HouseholdPolicyChoice | None = None @@ -65,16 +69,19 @@ def options(self) -> dict[str, Any]: class HouseholdReportCreated(BaseModel): - """The household report a request created or re-ran, its new run and its status. - - The status is the run's when its call's ID was recorded: ``pending``, or - whatever the household function had made it by then if it claimed the - run first. A run whose call Modal didn't confirm, or whose call's ID - couldn't be recorded, is answered ``pending``. ``year`` is the year the - report calculates: a new report's is its household's default year, and a - re-run keeps the report's. Each side names its simulation, new for a new - report and the report's own on a re-run, and its new simulation run; the - reform's are null for a report of the baseline alone. + """The household report a request ended on, its run and that run's status. + + The report and run are the ones a create found or created by key, or a + re-run joined or created. For a run the request created, the status is + the run's when its call's ID was recorded: ``pending``, or whatever the + household function had made it by then if it claimed the run first. A + run whose call Modal didn't confirm, or whose call's ID couldn't be + recorded, is answered ``pending``; a joined run, its status as read. + ``year`` is the year the report calculates: a new report's is its + household's default year, and a re-run keeps the report's. Each side + names its simulation and the simulation run the report run names, which + may be another report run's; the reform's are null for a report of the + baseline alone. """ model_config = ConfigDict(extra="forbid", frozen=True) diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/household_report_calculations.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/household_report_calculations.py new file mode 100644 index 000000000..2b0fb8d51 --- /dev/null +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/household_report_calculations.py @@ -0,0 +1,245 @@ +"""Build a household report run's household function payload from its inputs. + +Each side's request calculates the stored household, in its country, for +the report's year with the household's saved SPM selection, on the default +worker's bundle; its calculation ID is the side's simulation run. The +household report services (``household_report_submissions``, +``household_report_reruns``) build it before writing anything, on the run +IDs a request proposes, and again for a run they created, on the runs it +names. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any + +from policyengine_simulation_contract.household_execution import ( + HouseholdExecutionRequest, +) +from policyengine_simulation_contract.household_report_execution import ( + HouseholdReportRunCalculation, +) +from pydantic import ValidationError + +from policyengine_simulation_entry.economy_submission_errors import ( + EconomySubmissionUnprocessableError, + UnprocessableReason, +) +from policyengine_simulation_entry.household_contract_fields import ( + job_policy_fields, + request_field_of, +) +from policyengine_simulation_entry.household_conversion import ( + UnreadableHouseholdError, + household_situation, + saved_spm_selection, +) + +if TYPE_CHECKING: + from collections.abc import Mapping + from uuid import UUID + + from policyengine_simulation_persistence import ( + HouseholdReportInputs, + PolicyReform, + ReportSide, + StoredHousehold, + ) + + from policyengine_simulation_entry.household_workers import HouseholdWorker + + +class HouseholdReportBuildError(Exception): + """The household function's contract refused a field the service built. + + The message names each refused field, never a value; the route answers + it as an internal error. + """ + + +def household_not_calculable( + *reasons: UnprocessableReason, +) -> EconomySubmissionUnprocessableError: + """Return the 422 refusing a household report that cannot be calculated.""" + return EconomySubmissionUnprocessableError( + code="household_not_calculable", reasons=reasons + ) + + +def _spm_fields(document: Mapping[str, Any]) -> dict[str, object]: + """Return the contract's SPM fields: the household's saved selection, if any.""" + saved = saved_spm_selection(document) + if saved is None: + return {} + return {"spm": saved, "spm_selection_source": "saved_household"} + + +def _contract_reasons( + error: ValidationError, side: ReportSide +) -> tuple[UnprocessableReason, ...]: + """Name each field the contract refuses by the request field it traces to. + + Raise HouseholdReportBuildError when the contract refuses a field the + service builds itself, which is no fault of the caller's. + """ + reasons = [] + built_wrong = [] + for item in error.errors(): + location = tuple(item["loc"]) + request_field = request_field_of(location, spm_from_request=False) + # A household report sets add_missing_variables itself. + if request_field is None or request_field == "add_missing_variables": + built_wrong.append(".".join(str(part) for part in location) or "request") + continue + field_location = ( + (side, request_field) if request_field == "policy_id" else (request_field,) + ) + reasons.append( + UnprocessableReason( + loc=("body", *field_location, *location), + msg=item["msg"], + type=item["type"], + ) + ) + if built_wrong: + msg = ( + "the household function's request has fields the service built " + f"wrong: {', '.join(built_wrong)}" + ) + raise HouseholdReportBuildError(msg) + return tuple(reasons) + + +@dataclass(frozen=True) +class HouseholdReportSideInputs: + """One side of a household report run: the simulation run it records. + + ``policy_values`` holds the side's policy values by parameter name and + period, empty for current law, as ``HouseholdReportStore.read_inputs`` + reads them into ``reforms``. + """ + + simulation_run_id: UUID + policy_values: PolicyReform + + +def side_runs_calculation( + inputs: HouseholdReportInputs, + *, + year: int, + run_ids: Mapping[ReportSide, UUID], + worker: HouseholdWorker, +) -> HouseholdReportRunCalculation: + """Build the household function payload for these side runs of ``inputs``. + + ``run_ids`` names each side's simulation run, the baseline's and any + reform's; raise as ``household_report_calculation`` does. + """ + sides = { + side: HouseholdReportSideInputs( + simulation_run_id=run_id, policy_values=inputs.reforms[side] + ) + for side, run_id in run_ids.items() + } + return household_report_calculation( + household=inputs.household, + year=year, + baseline=sides["baseline"], + reform=sides.get("reform"), + worker=worker, + ) + + +def household_report_calculation( + *, + household: StoredHousehold, + year: int, + baseline: HouseholdReportSideInputs, + reform: HouseholdReportSideInputs | None = None, + worker: HouseholdWorker, +) -> HouseholdReportRunCalculation: + """Build a household report run's household function payload from its inputs. + + Each side's request calculates the stored ``household``, in its + country, for ``year`` with the household's saved SPM selection, on + ``worker``'s bundle, and its calculation ID is the side's simulation + run; ``reform`` is None for a report of the baseline alone. Every side + adds the household's missing variables, so a household report holds + every value. Creating a report passes the household's default year. A + restart or re-run passes the stored report's year, and the household + and policy values as they are now read. + + Raise EconomySubmissionUnprocessableError (``household_not_calculable``) + when the stored household cannot be read, or the household contract + refuses what would be calculated, the baseline's checked first. Its + reasons are located at a report request's fields (``household_id``, a + side's ``policy_id``); a caller rebuilding a stored run reads them as + its own. Raise HouseholdReportBuildError when the contract refuses a + field the service builds, two sides recording one simulation run + included. + """ + country = household.country + try: + situation = household_situation(country, household.document) + except UnreadableHouseholdError: + raise household_not_calculable( + UnprocessableReason( + loc=("body", "household_id"), + msg="the stored household's people or groups cannot be read", + type="household_unreadable", + ) + ) from None + sides: dict[ReportSide, HouseholdReportSideInputs] = {"baseline": baseline} + if reform is not None: + sides["reform"] = reform + requests = { + side: _side_request( + side, + side_inputs, + year=year, + situation=situation, + household=household, + worker=worker, + ) + for side, side_inputs in sides.items() + } + try: + return HouseholdReportRunCalculation( + baseline=requests["baseline"], reform=requests.get("reform") + ) + except ValidationError as error: + msg = "the household report run's calculation was built wrong: " + "; ".join( + str(item["msg"]) for item in error.errors() + ) + raise HouseholdReportBuildError(msg) from None + + +def _side_request( # noqa: PLR0913 # the side and what it calculates + side: ReportSide, + side_inputs: HouseholdReportSideInputs, + *, + year: int, + situation: dict[str, Any], + household: StoredHousehold, + worker: HouseholdWorker, +) -> HouseholdExecutionRequest: + """Build one side's household contract request; raise its refusal.""" + try: + return HouseholdExecutionRequest.model_validate( + { + "calculation_id": side_inputs.simulation_run_id, + "country": household.country, + # The report's year, as a situation's period key. + "year": str(year), + "household": situation, + **job_policy_fields(reform=side_inputs.policy_values), + # A household report holds every value, as the Public API's + # stored-household route gives it. + "add_missing_variables": True, + "bundle": worker.bundle, + **_spm_fields(household.document), + } + ) + except ValidationError as error: + raise household_not_calculable(*_contract_reasons(error, side)) from None diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/household_report_reruns.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/household_report_reruns.py index 95e0f9980..127c8ab68 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/household_report_reruns.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/household_report_reruns.py @@ -1,25 +1,32 @@ """Re-run a stored household report on the current .py version. A household report's re-run calculates its stored household again, in the -report's own year, under each side's stored policy, as a new run, and keeps -every earlier run. The re-run service (``economy_reruns``) reads the stored -report and hands a household report to ``HouseholdReportRerunService``, -which: +report's own year, under each side's stored policy, on the current +versions, and keeps every earlier run. The re-run service +(``economy_reruns``) reads the stored report and hands a household report +to ``HouseholdReportRerunService``, which: 1. finds the v2 version manifest's default worker's household function for the country; 2. reads, in one transaction, the country's catalog version for that worker's .py version, its model, the stored household and each side's - policy values, and builds each side's household contract request with - the side's new simulation run ID as its calculation ID; -3. creates, in one transaction, the report's new run (trigger ``manual``) - and a new run of each side's own household simulation, all pending with - no Modal call ID, unless the report has a run pending or running; -4. starts one household function call for the new report run and records - its ID, as for a new report, failing the new runs when Modal refuses the - call. - -A household run is never reused, so a forced re-run creates the same runs. + policy values, and checks each side's household contract request; +3. for a keyed report's unforced re-run, joins, in one transaction, the + report's run on the current versions that hasn't failed and wasn't + forced, or else creates the report's new run (naming no trigger) + naming each side's household simulation run on those versions, found or + inserted, as an economy report's re-run does (C1 · 24's answer 8). A + forced re-run, and every re-run of a report created before keys, whose + runs may have been calculated for it alone (interim answer B), creates + an extra report run and a new run of each side, all marked forced, + which nothing joins and nothing refuses. Every new run is pending with + no Modal call ID; +4. for a report run it created, starts one household function call and + records its ID, as for a new report, with each side's simulation run as + its calculation ID, failing the new report run when Modal refuses the + call (and a forced re-run's simulation runs, which only it names). A + joined run gets no call. + The re-run service hands over only a report naming each row this needs and no dynamic, which a household calculation does not apply. Whatever is missing or cannot be calculated is refused in steps 1 and 2, before @@ -44,11 +51,12 @@ EconomySubmissionUnprocessableError, rerun_refusals, ) +from policyengine_simulation_entry.household_report_calculations import ( + side_runs_calculation, +) from policyengine_simulation_entry.household_report_submissions import ( HouseholdReports, - HouseholdReportSideInputs, HouseholdReportSubmissionService, - household_report_calculation, household_report_created, ) from policyengine_simulation_entry.household_workers import ( @@ -58,6 +66,7 @@ from policyengine_simulation_entry.simulation_database import SimulationDatabase if TYPE_CHECKING: + from collections.abc import Mapping from uuid import UUID from policyengine_simulation_contract.household_report_execution import ( @@ -65,10 +74,10 @@ ) from policyengine_simulation_contract.stage12_bundle import CountryId from policyengine_simulation_persistence import ( - PolicyReform, + FoundReportRun, + HouseholdReportInputs, ReportSide, SideDefinition, - StoredHousehold, ) from policyengine_simulation_entry.config import Settings @@ -95,6 +104,7 @@ class StoredHouseholdReport: with their stored policies; ``reform`` is None for a report of the baseline alone. Neither names a dynamic, which a household calculation does not apply: the re-run service refuses a report whose side does. + ``keyed`` says the report was found or created by key (C1 · 27). """ report_id: UUID @@ -103,6 +113,7 @@ class StoredHouseholdReport: year: int baseline: SideDefinition reform: SideDefinition | None + keyed: bool = False @property def sides(self) -> dict[ReportSide, SideDefinition]: @@ -119,8 +130,8 @@ class HouseholdReportRerunRows(HouseholdReports, Protocol): ``HouseholdReportStore`` is one. """ - def create_report_rerun(self, rerun: NewHouseholdReportRerun) -> None: - """Create the report's new run and each side's new simulation run.""" + def create_report_rerun(self, rerun: NewHouseholdReportRerun) -> FoundReportRun: + """Join the report's run on the re-run's versions, or create it.""" ... @@ -131,9 +142,10 @@ async def rerun_report( self, stored: StoredHouseholdReport, *, + force: bool, observability_context: dict[str, Any] | None, ) -> HouseholdReportCreated: - """Create the stored report's new run, and start its household function call.""" + """Join or create the stored report's run, and start a run it created.""" ... @@ -146,15 +158,17 @@ async def rerun_report( self, stored: StoredHouseholdReport, *, + force: bool, observability_context: dict[str, Any] | None, ) -> HouseholdReportCreated: - """Create the stored report's new run on the current versions, and start it. + """Join or create the stored report's run on the current versions. + ``force``, or a report without keys, makes it an extra forced run. + A run it created is started; one it joined is answered as it is. Raise EconomyRecordNotFoundError (404) for a report deleted after it - was read, EconomyRerunConflictError (409 ``run_in_progress``) while - it has a run pending or running, and otherwise the errors - ``submit_report`` raises, located at the stored report; a 503 for - Modal's refusal names the new run as well as the report. + was read, and otherwise the errors ``submit_report`` raises, located + at the stored report; a 503 for Modal's refusal names the new run as + well as the report. """ worker = await self._default_worker(stored.country) inputs = await self._read_inputs( @@ -175,6 +189,7 @@ async def rerun_report( ) for side, definition in stored.sides.items() } + forced = force or not stored.keyed rerun = NewHouseholdReportRerun( report_id=stored.report_id, run_id=run_id, @@ -186,40 +201,78 @@ async def rerun_report( ), baseline=new_sides["baseline"], reform=new_sides.get("reform"), + forced=forced, ) - calculation = _stored_report_calculation( - inputs.household, rerun, reforms=inputs.reforms, worker=worker + # Refused before anything is written, on the run IDs it proposes. + _stored_report_calculation( + inputs, + year=rerun.year, + run_ids={ + side: proposed.simulation_run_id + for side, proposed in rerun.named_sides.items() + }, + worker=worker, ) with rerun_refusals("report"): - await self._create( + found = await self._create( lambda: self._store.create_report_rerun(rerun), rerun=True, source=STORED_REPORT, ) - status = await self._start_report_run( - worker, - calculation, - report_id=rerun.report_id, - run_id=rerun.run_id, - simulation_run_ids=rerun.simulation_run_ids, - observability_context=observability_context, - rerun=True, - ) + run_ids = _side_run_ids(found, rerun.named_sides) + status = found.status + if found.inserted: + status = await self._start_report_run( + worker, + _stored_report_calculation( + inputs, year=rerun.year, run_ids=run_ids, worker=worker + ), + report_id=rerun.report_id, + run_id=found.id, + # Only a forced run's simulation runs are this re-run's alone. + simulation_run_ids=rerun.simulation_run_ids if forced else (), + observability_context=observability_context, + rerun=True, + ) + sides = { + side: HouseholdRerunSide( + simulation_id=definition.simulation_id, simulation_run_id=run_ids[side] + ) + for side, definition in stored.sides.items() + } return household_report_created( report_id=rerun.report_id, - run_id=rerun.run_id, + run_id=found.id, status=status, year=rerun.year, - baseline=rerun.baseline, - reform=rerun.reform, + baseline=sides["baseline"], + reform=sides.get("reform"), ) +def _side_run_ids( + run: FoundReportRun, sides: Mapping[ReportSide, object] +) -> dict[ReportSide, UUID]: + """Return the simulation run the report run names for each of ``sides``.""" + named: dict[ReportSide, UUID | None] = { + "baseline": run.baseline_simulation_run_id, + "reform": run.reform_simulation_run_id, + } + run_ids: dict[ReportSide, UUID] = {} + for side in sides: + run_id = named[side] + if run_id is None: + msg = f"report run {run.id} of a household report names no {side} run" + raise ValueError(msg) + run_ids[side] = run_id + return run_ids + + def _stored_report_calculation( - household: StoredHousehold, - rerun: NewHouseholdReportRerun, + inputs: HouseholdReportInputs, *, - reforms: dict[ReportSide, PolicyReform], + year: int, + run_ids: Mapping[ReportSide, UUID], worker: HouseholdWorker, ) -> HouseholdReportRunCalculation: """Build the re-run's household function payload, in the stored report's year. @@ -227,24 +280,8 @@ def _stored_report_calculation( A household or policy the contract refuses is located at the stored report's fields rather than a request's. """ - - def side_inputs( - side: HouseholdRerunSide, name: ReportSide - ) -> HouseholdReportSideInputs: - return HouseholdReportSideInputs( - simulation_run_id=side.simulation_run_id, policy_values=reforms[name] - ) - try: - return household_report_calculation( - household=household, - year=rerun.year, - baseline=side_inputs(rerun.baseline, "baseline"), - reform=None - if rerun.reform is None - else side_inputs(rerun.reform, "reform"), - worker=worker, - ) + return side_runs_calculation(inputs, year=year, run_ids=run_ids, worker=worker) except EconomySubmissionUnprocessableError as error: raise EconomySubmissionUnprocessableError( code=error.code, diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/household_report_submissions.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/household_report_submissions.py index 768e83cfd..6bc1aceca 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/household_report_submissions.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/household_report_submissions.py @@ -1,25 +1,33 @@ -"""Create household reports, and start the household function call that calculates them. +"""Find or create household reports, and start a new run's household function call. A household report submission names a stored household, the baseline's -stored policy and, optionally, the reform's. The service: +stored policy and, optionally, the reform's. Identical submissions, +together or apart, end on the same simulations, report and run (C1 · 24's +answer 8). The service: 1. finds the v2 version manifest's default worker's household function for the country, and its bundle; 2. reads, in one transaction, the country's catalog version for that worker's .py version, its model, the stored household and each side's - policy values, and builds each side's household contract request for - the household's ``default_year``, with the side's new simulation run ID - as its calculation ID; -3. creates, in one transaction, each side's household simulation and its - pending simulation run, the report, which has no options, and its first - report run, pending with no Modal call ID; -4. starts one household function call with ``spawn``, passing the report - run's ID and both sides' requests, then records the call's ID while the - report run is still pending with none (the function may have claimed it - already). When Modal refuses the call, or does not confirm it in time, it - fails the report run and its simulation runs at once instead, under the - same condition; a run the function claimed meanwhile, because Modal - accepted the call after all, is left as it is and answered ``pending``. + policy values, and checks each side's household contract request for + the household's ``default_year`` (on the run IDs it would propose); +3. finds or creates, in one transaction, each side's household simulation + by its key, the report by its key, which has no options, and its run on + the current versions that hasn't failed and wasn't forced, or else the + report run naming each side's simulation run on those versions, found + or inserted, all pending with no Modal call ID + (``find_or_create_household_report``); +4. for a report run it created, starts one household function call with + ``spawn``, passing the report run's ID and both sides' requests, each + with the side's simulation run as its calculation ID, then records the + call's ID while the report run is still pending with none (the function + may have claimed it already). When Modal refuses the call, or does not + confirm it in time, it fails the report run at once instead, under the + same condition, and leaves its simulation runs, which may be another + report run's, to the next call naming them or to the stuck-run sweep; a + run the function claimed meanwhile, because Modal accepted the call + after all, is left as it is and answered ``pending``. A run it joined + gets no call, and is answered with its status as read. Whatever is missing or cannot be calculated is refused in steps 1 and 2, before anything is written. The household function then claims the report @@ -35,30 +43,25 @@ import asyncio import logging -from dataclasses import dataclass from typing import TYPE_CHECKING, Any, Protocol from uuid import UUID, uuid4 -from policyengine_simulation_contract.household_execution import ( - HouseholdExecutionRequest, -) -from policyengine_simulation_contract.household_report_execution import ( - HouseholdReportRunCalculation, -) from policyengine_simulation_persistence import ( EconomyRecordOutcomeUnknownError, EconomyRecordReferenceError, - HouseholdReportSimulation, + HouseholdReportDefinition, + KeyedHouseholdReport, MissingPolicyParametersError, - NewHouseholdReport, + ProposedSide, ReportRunStatus, ReportSideError, RunVersions, + SharedRowNotSettledError, + SimulationChoice, UnknownCatalogVersionError, UnknownHouseholdError, UnknownPolicyError, ) -from pydantic import ValidationError from sqlalchemy.exc import SQLAlchemyError from policyengine_simulation_entry.economy_submission_errors import ( @@ -71,18 +74,16 @@ call_refused, reference_refusal, ) -from policyengine_simulation_entry.household_contract_fields import ( - job_policy_fields, - request_field_of, -) -from policyengine_simulation_entry.household_conversion import ( - UnreadableHouseholdError, - household_situation, - saved_spm_selection, -) from policyengine_simulation_entry.household_report_api_models import ( HouseholdReportCreated, ) +from policyengine_simulation_entry.household_report_calculations import ( + HouseholdReportBuildError, + HouseholdReportSideInputs, + household_not_calculable, + household_report_calculation, + side_runs_calculation, +) from policyengine_simulation_entry.household_workers import ( HouseholdFunctionUnavailableError, VersionManifestUnavailableError, @@ -91,9 +92,12 @@ if TYPE_CHECKING: from collections.abc import Callable, Mapping, Sequence + from policyengine_simulation_contract.household_report_execution import ( + HouseholdReportRunCalculation, + ) from policyengine_simulation_persistence import ( + FoundHouseholdReport, HouseholdReportInputs, - PolicyReform, ReportSide, StoredHousehold, ) @@ -132,8 +136,10 @@ def read_inputs( """Read the catalog version, household and each side's policy together.""" ... - def create_report(self, report: NewHouseholdReport) -> None: - """Create the report, its simulations and its runs.""" + def find_or_create_report( + self, report: KeyedHouseholdReport + ) -> FoundHouseholdReport: + """Find the report by key, with its run, or create them.""" ... def record_report_call( @@ -191,28 +197,12 @@ def household_report_created( # noqa: PLR0913 # the report, its run and each s ) -class HouseholdReportBuildError(Exception): - """The household function's contract refused a field the service built. - - The message names each refused field, never a value; the route answers - it as an internal error. - """ - - def _database_unavailable() -> EconomySubmissionUnavailableError: return EconomySubmissionUnavailableError( code="database_unavailable", detail="The simulation database could not be read." ) -def _not_calculable( - *reasons: UnprocessableReason, -) -> EconomySubmissionUnprocessableError: - return EconomySubmissionUnprocessableError( - code="household_not_calculable", reasons=reasons - ) - - def _policy_ids(request: HouseholdReportRequest) -> dict[ReportSide, UUID | None]: """Return each side the report calculates and its stored policy, if any.""" policy_ids: dict[ReportSide, UUID | None] = {"baseline": request.baseline.policy_id} @@ -275,161 +265,10 @@ def _read_refusal( return None -def _spm_fields(document: Mapping[str, Any]) -> dict[str, object]: - """Return the contract's SPM fields: the household's saved selection, if any.""" - saved = saved_spm_selection(document) - if saved is None: - return {} - return {"spm": saved, "spm_selection_source": "saved_household"} - - -def _contract_reasons( - error: ValidationError, side: ReportSide -) -> tuple[UnprocessableReason, ...]: - """Name each field the contract refuses by the request field it traces to. - - Raise HouseholdReportBuildError when the contract refuses a field the - service builds itself, which is no fault of the caller's. - """ - reasons = [] - built_wrong = [] - for item in error.errors(): - location = tuple(item["loc"]) - request_field = request_field_of(location, spm_from_request=False) - # A household report sets add_missing_variables itself. - if request_field is None or request_field == "add_missing_variables": - built_wrong.append(".".join(str(part) for part in location) or "request") - continue - field_location = ( - (side, request_field) if request_field == "policy_id" else (request_field,) - ) - reasons.append( - UnprocessableReason( - loc=("body", *field_location, *location), - msg=item["msg"], - type=item["type"], - ) - ) - if built_wrong: - msg = ( - "the household function's request has fields the service built " - f"wrong: {', '.join(built_wrong)}" - ) - raise HouseholdReportBuildError(msg) - return tuple(reasons) - - -@dataclass(frozen=True) -class HouseholdReportSideInputs: - """One side of a household report run: the simulation run it records. - - ``policy_values`` holds the side's policy values by parameter name and - period, empty for current law, as ``HouseholdReportStore.read_inputs`` - reads them into ``reforms``. - """ - - simulation_run_id: UUID - policy_values: PolicyReform - - -def household_report_calculation( - *, - household: StoredHousehold, - year: int, - baseline: HouseholdReportSideInputs, - reform: HouseholdReportSideInputs | None = None, - worker: HouseholdWorker, -) -> HouseholdReportRunCalculation: - """Build a household report run's household function payload from its inputs. - - Each side's request calculates the stored ``household``, in its - country, for ``year`` with the household's saved SPM selection, on - ``worker``'s bundle, and its calculation ID is the side's simulation - run; ``reform`` is None for a report of the baseline alone. Every side - adds the household's missing variables, so a household report holds - every value. Creating a report passes the household's default year. A - restart or re-run passes the stored report's year, and the household - and policy values as they are now read. - - Raise EconomySubmissionUnprocessableError (``household_not_calculable``) - when the stored household cannot be read, or the household contract - refuses what would be calculated, the baseline's checked first. Its - reasons are located at a report request's fields (``household_id``, a - side's ``policy_id``); a caller rebuilding a stored run reads them as - its own. Raise HouseholdReportBuildError when the contract refuses a - field the service builds, two sides recording one simulation run - included. - """ - country = household.country - try: - situation = household_situation(country, household.document) - except UnreadableHouseholdError: - raise _not_calculable( - UnprocessableReason( - loc=("body", "household_id"), - msg="the stored household's people or groups cannot be read", - type="household_unreadable", - ) - ) from None - sides: dict[ReportSide, HouseholdReportSideInputs] = {"baseline": baseline} - if reform is not None: - sides["reform"] = reform - requests = { - side: _side_request( - side, - side_inputs, - year=year, - situation=situation, - household=household, - worker=worker, - ) - for side, side_inputs in sides.items() - } - try: - return HouseholdReportRunCalculation( - baseline=requests["baseline"], reform=requests.get("reform") - ) - except ValidationError as error: - msg = "the household report run's calculation was built wrong: " + "; ".join( - str(item["msg"]) for item in error.errors() - ) - raise HouseholdReportBuildError(msg) from None - - -def _side_request( # noqa: PLR0913 # the side and what it calculates - side: ReportSide, - side_inputs: HouseholdReportSideInputs, - *, - year: int, - situation: dict[str, Any], - household: StoredHousehold, - worker: HouseholdWorker, -) -> HouseholdExecutionRequest: - """Build one side's household contract request; raise its refusal.""" - try: - return HouseholdExecutionRequest.model_validate( - { - "calculation_id": side_inputs.simulation_run_id, - "country": household.country, - # The report's year, as a situation's period key. - "year": str(year), - "household": situation, - **job_policy_fields(reform=side_inputs.policy_values), - # A household report holds every value, as the Public API's - # stored-household route gives it. - "add_missing_variables": True, - "bundle": worker.bundle, - **_spm_fields(household.document), - } - ) - except ValidationError as error: - raise _not_calculable(*_contract_reasons(error, side)) from None - - def _report_year(household: StoredHousehold) -> int: """Return the year a new report calculates: the household's default year.""" if household.default_year is None: - raise _not_calculable( + raise household_not_calculable( UnprocessableReason( loc=("body", "household_id"), msg="the household has no default year to calculate", @@ -469,13 +308,14 @@ async def submit_report( *, observability_context: dict[str, Any] | None, ) -> HouseholdReportCreated: - """Create the report and its runs, and start its household function call. - - Raise EconomySubmissionRefusedError (400) or - EconomySubmissionUnprocessableError (422) before writing anything; - EconomySubmissionUnavailableError (503) when the manifest or the - database cannot be read, or, naming the report, when Modal doesn't - confirm the call and the report run was failed; + """Find or create the report and its run, and start a run it created. + + A run the request joined, pending, running or succeeded, gets no + call and is answered as it is. Raise EconomySubmissionRefusedError + (400) or EconomySubmissionUnprocessableError (422) before writing + anything; EconomySubmissionUnavailableError (503) when the manifest + or the database cannot be read, or, naming the report, when Modal + doesn't confirm the call and the report run was failed; EconomySubmissionOutcomeUnknownError (500) when the create's commit failed after its rows were inserted; and HouseholdReportBuildError (500) when the service built a request the contract refuses. @@ -487,23 +327,44 @@ async def submit_report( policy_ids=_policy_ids(request), worker=worker, ) - report, calculation = self._prepare(request, worker, inputs) - await self._create(lambda: self._store.create_report(report)) - status = await self._start_report_run( - worker, - calculation, - report_id=report.id, - run_id=report.run_id, - simulation_run_ids=report.simulation_run_ids, - observability_context=observability_context, + report = self._keyed_report(request, worker, inputs) + year = report.definition.year + # Refused before anything is written, on the run IDs it proposes. + side_runs_calculation( + inputs, + year=year, + run_ids={ + side: proposed.simulation_run_id + for side, proposed in report.proposed_sides.items() + }, + worker=worker, ) + found = await self._create(lambda: self._store.find_or_create_report(report)) + status = found.run.status + if found.run.inserted: + run_ids: dict[ReportSide, UUID] = { + "baseline": found.baseline.simulation_run_id + } + if found.reform is not None: + run_ids["reform"] = found.reform.simulation_run_id + status = await self._start_report_run( + worker, + side_runs_calculation( + inputs, year=year, run_ids=run_ids, worker=worker + ), + report_id=found.report_id, + run_id=found.run.id, + # Its simulation runs may be another report run's. + simulation_run_ids=(), + observability_context=observability_context, + ) return household_report_created( - report_id=report.id, - run_id=report.run_id, + report_id=found.report_id, + run_id=found.run.id, status=status, - year=report.year, - baseline=report.baseline, - reform=report.reform, + year=year, + baseline=found.baseline, + reform=found.reform, ) async def _default_worker(self, country: str) -> HouseholdWorker: @@ -563,74 +424,67 @@ async def _read_inputs( raise raise refusal from None - def _prepare( + def _keyed_report( self, request: HouseholdReportRequest, worker: HouseholdWorker, inputs: HouseholdReportInputs, - ) -> tuple[NewHouseholdReport, HouseholdReportRunCalculation]: - """Return the report to create and the calculation its call is given.""" - household = inputs.household - year = _report_year(household) + ) -> KeyedHouseholdReport: + """Return the report the request names, with the IDs it proposes. + + The report calculates the household's default year, and has no + options (``reports.inputs`` is empty); a household calculation + applies no dynamic. + """ report_id, run_id = self._new_id(), self._new_id() - sides: dict[ReportSide, HouseholdReportSimulation] = { - side: HouseholdReportSimulation( - simulation_id=self._new_id(), - simulation_run_id=self._new_id(), - policy_id=policy_id, - ) - for side, policy_id in _policy_ids(request).items() - } - side_inputs = { - side: HouseholdReportSideInputs( - simulation_run_id=created.simulation_run_id, - policy_values=inputs.reforms[side], + proposed = { + side: ProposedSide( + simulation_id=self._new_id(), simulation_run_id=self._new_id() ) - for side, created in sides.items() + for side in _policy_ids(request) } - calculation = household_report_calculation( - household=household, - year=year, - baseline=side_inputs["baseline"], - reform=side_inputs.get("reform"), - worker=worker, - ) - report = NewHouseholdReport( - id=report_id, + reform = request.reform + return KeyedHouseholdReport( + definition=HouseholdReportDefinition( + country=request.country, + baseline=SimulationChoice( + policy_id=request.baseline.policy_id, dynamic_id=None + ), + reform=None + if reform is None + else SimulationChoice(policy_id=reform.policy_id, dynamic_id=None), + household_id=request.household_id, + year=_report_year(inputs.household), + ), + report_id=report_id, run_id=run_id, - country=request.country, - label=request.label, - description=request.description, + baseline=proposed["baseline"], + reform=proposed.get("reform"), tax_benefit_model_id=inputs.tax_benefit_model_id, tax_benefit_model_version_id=inputs.catalog_version_id, - household_id=request.household_id, - year=year, versions=RunVersions( country_package_version=worker.bundle.country_package_version, policyengine_version=worker.bundle.policyengine_version, ), - inputs=request.options(), - baseline=sides["baseline"], - reform=sides.get("reform"), ) - return report, calculation - async def _create( + async def _create[Created]( self, - create: Callable[[], None], + create: Callable[[], Created], *, rerun: bool = False, source: RefusalSource = REQUEST_BODY, - ) -> None: + ) -> Created: """Create the rows; answer a refusal, an unknown outcome or an outage. - A commit that failed after the rows were inserted may have written - them, so it is never answered as unavailable, which would tell the - caller nothing was created. ``rerun`` says the rows are a stored - report's new run, and ``source`` what names a refused row. + Return what ``create`` returns. A commit that failed after the rows + were inserted may have written them, so it is never answered as + unavailable, which would tell the caller nothing was created. + ``rerun`` says the rows are a stored report's new run, and + ``source`` what names a refused row. """ try: - await asyncio.to_thread(create) + return await asyncio.to_thread(create) except EconomyRecordReferenceError as error: raise reference_refusal(error, source) from None except EconomyRecordOutcomeUnknownError as error: @@ -639,7 +493,9 @@ async def _create( raise EconomySubmissionOutcomeUnknownError( record, error_type=type(error.__cause__).__name__, rerun=rerun ) from None - except SQLAlchemyError as error: + # A run kept failing between a lookup's insert and its read; its + # transaction wrote nothing, so the caller may ask again. + except (SharedRowNotSettledError, SQLAlchemyError) as error: logger.warning( "household_report_not_created", extra={"error_type": type(error).__name__}, @@ -659,9 +515,10 @@ async def _start_report_run( # noqa: PLR0913 # the call, then the runs it calc ) -> ReportRunStatus: """Start the report run's household function call and record it, or fail it. - ``simulation_run_ids`` are the simulation runs created with the - report run, which fail with it; ``rerun`` says the report existed - before its new run. + ``simulation_run_ids`` are the simulation runs that fail with the + report run: a forced re-run's, which only it names, and none for a + run whose simulation runs may be another report run's; ``rerun`` + says the report existed before its new run. """ try: call_id = await asyncio.wait_for( @@ -746,3 +603,18 @@ async def _fail_unconfirmed( }, ) return False + + +# The calculation building moved to household_report_calculations; its names +# stay importable here. +__all__ = [ + "CALL_START_TIMEOUT_SECONDS", + "HouseholdReportBuildError", + "HouseholdReportSideInputs", + "HouseholdReportSideRuns", + "HouseholdReportSubmissionService", + "HouseholdReports", + "household_report_calculation", + "household_report_created", + "side_runs_calculation", +] diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/rerunnable_records.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/rerunnable_records.py new file mode 100644 index 000000000..71fd675ac --- /dev/null +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/rerunnable_records.py @@ -0,0 +1,280 @@ +"""Which stored records the service re-runs, and what each calculates on. + +A re-run (``economy_reruns``) first reads what the stored report or +simulation calculates, then checks it here: a record of a kind the service +doesn't re-run, of a country it doesn't calculate, or missing a row it +calculates on is refused (409 ``rerun_not_supported``) before anything is +read from the catalog or written. ``rerun_scope`` then says what the re-run +calculates on, with the default worker's bundle dataset. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any, Final, get_args + +from policyengine_simulation_contract.stage12_bundle import CountryId + +from policyengine_simulation_entry.economy_calculation_inputs import ( + CalculationScope, + DatasetNotInBundleError, + bundle_dataset, + simulation_options, +) +from policyengine_simulation_entry.economy_submission_errors import ( + EconomyRerunConflictError, + EconomySubmissionRefusedError, +) +from policyengine_simulation_entry.household_report_reruns import ( + StoredHouseholdReport, +) + +if TYPE_CHECKING: + from uuid import UUID + + from policyengine_simulation_persistence import ( + EconomyCatalogRows, + EconomyRequest, + RecordKind, + ReportDefinition, + SideDefinition, + SimulationDefinition, + WindowYearDefinition, + ) + + from policyengine_simulation_entry.economy_submission_errors import RecordName + from policyengine_simulation_entry.economy_workers import EconomyWorker + +# The kinds of stored economy report this service re-runs itself. +_RERUN_REPORT_KINDS: Final[frozenset[RecordKind]] = frozenset( + {"economy", "budget_window"} +) +# The countries this service calculates, as the contract names them. +_COUNTRIES: Final[tuple[CountryId, ...]] = get_args(CountryId) +_REPORT: Final[RecordName] = "report" +_SIMULATION: Final[RecordName] = "simulation" + + +@dataclass(frozen=True) +class StoredReportRows: + """The country and rows a stored report calculates on, each present.""" + + report_id: UUID + country: CountryId + year: int + region_code: str + dataset_name: str + baseline: SideDefinition + reform: SideDefinition + + +@dataclass(frozen=True) +class StoredSimulationRows: + """The country and rows a stored simulation calculates on, each present.""" + + country: CountryId + year: int + region_code: str + dataset_name: str + + +def calculated_country(country: str | None) -> CountryId | None: + """Return the country if this service calculates it, or None.""" + return next((known for known in _COUNTRIES if known == country), None) + + +def rerun_refusal( + record: RecordName, kind: RecordKind, missing: tuple[tuple[str, object], ...] +) -> EconomyRerunConflictError: + """Return why a stored record is not re-run: its kind, or the first row it lacks. + + ``missing`` pairs each row's description with the value the record holds. + """ + if kind == "unsupported": + detail = f"The service does not re-run this type of {record}." + elif record == _SIMULATION and kind == "household": + detail = ( + "The service re-runs a household simulation only through its report " + "(POST /reports/{report_id}/runs)." + ) + else: + lacking = next(name for name, value in missing if value is None) + detail = f"The {record} names no {lacking}, so it cannot be re-run." + return EconomyRerunConflictError(code="rerun_not_supported", detail=detail) + + +def rerunnable_report(definition: ReportDefinition) -> StoredReportRows: + """Return the stored report's rows, or refuse one this service can't re-run.""" + baseline, reform = definition.baseline, definition.reform + region_code, dataset_name = definition.region_code, definition.dataset_name + country, year = calculated_country(definition.country), definition.year + if ( + definition.kind not in _RERUN_REPORT_KINDS + or country is None + or baseline is None + or reform is None + or region_code is None + or dataset_name is None + or year is None + ): + raise rerun_refusal( + _REPORT, + definition.kind, + ( + ("country this service calculates", country), + ("baseline simulation", baseline), + ("reform simulation", reform), + ("region", region_code), + ("dataset", dataset_name), + ("year", year), + ), + ) + return StoredReportRows( + report_id=definition.id, + country=country, + year=year, + region_code=region_code, + dataset_name=dataset_name, + baseline=baseline, + reform=reform, + ) + + +def rerunnable_household_report( + definition: ReportDefinition, +) -> StoredHouseholdReport: + """Return the stored household report's rows, or refuse one it can't re-run. + + A side naming a dynamic is refused: a household calculation applies none. + """ + country, year = calculated_country(definition.country), definition.year + household_id, baseline = definition.household_id, definition.baseline + if country is None or household_id is None or baseline is None or year is None: + raise rerun_refusal( + _REPORT, + definition.kind, + ( + ("country this service calculates", country), + ("household", household_id), + ("baseline simulation", baseline), + ("year", year), + ), + ) + if any( + side is not None and side.choice.dynamic_id is not None + for side in (baseline, definition.reform) + ): + raise EconomyRerunConflictError( + code="rerun_not_supported", + detail=( + "The report's household simulation names a dynamic, which a " + "household calculation does not apply, so it cannot be re-run." + ), + ) + return StoredHouseholdReport( + report_id=definition.id, + country=country, + household_id=household_id, + year=year, + baseline=baseline, + reform=definition.reform, + keyed=definition.keyed, + ) + + +def complete_window_years( + definition: ReportDefinition, +) -> tuple[WindowYearDefinition, ...]: + """Return the stored window's years, or refuse a window that lacks one. + + Its newest calculation must have a report run naming both sides in each + year of its window, from the report's first year; the definition leaves + out a year naming no reform. + """ + expected = ( + () + if definition.year is None or definition.budget_window_size is None + else tuple( + range(definition.year, definition.year + definition.budget_window_size) + ) + ) + years = definition.window_years + if not expected or tuple(year.year for year in years) != expected: + raise EconomyRerunConflictError( + code="rerun_not_supported", + detail=( + "The report names no complete budget-window calculation, a " + "report run naming both sides in each year of its window, so " + "it cannot be re-run." + ), + ) + return years + + +def rerunnable_simulation(definition: SimulationDefinition) -> StoredSimulationRows: + """Return the stored simulation's country and rows, or refuse it. + + Its country is None when its catalog version's model is of no country + this service calculates. + """ + country, year = calculated_country(definition.country), definition.year + region_code, dataset_name = definition.region_code, definition.dataset_name + if ( + definition.kind != "economy" + or country is None + or region_code is None + or dataset_name is None + or year is None + ): + raise rerun_refusal( + _SIMULATION, + definition.kind, + ( + ("country this service calculates", country), + ("region", region_code), + ("dataset", dataset_name), + ("year", year), + ), + ) + return StoredSimulationRows( + country=country, + year=year, + region_code=region_code, + dataset_name=dataset_name, + ) + + +def rerun_scope( + country: CountryId, + request: EconomyRequest, + worker: EconomyWorker, + catalog: EconomyCatalogRows, + *, + options: dict[str, Any], +) -> CalculationScope: + """Return what a re-run calculates on, with the bundle's dataset. + + ``options`` are the stored report's (``reports.inputs``). Raise + EconomySubmissionRefusedError (``dataset_not_in_bundle``) when the + default worker's bundle lacks the stored dataset. + """ + try: + dataset = bundle_dataset(worker, catalog.dataset.name) + except DatasetNotInBundleError: + raise EconomySubmissionRefusedError( + code="dataset_not_in_bundle", + detail=( + f"The default v2 worker, .py {worker.version}, has no dataset " + f"{catalog.dataset.name}, which the stored record names." + ), + ) from None + return CalculationScope( + country=country, + region_code=catalog.region.code, + dataset=dataset, + year=request.year, + options=simulation_options( + include_cliffs=bool(options.get("include_cliffs", False)), + spm=options.get("spm"), + ), + ) diff --git a/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py b/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py index 3bbb02623..3ffa4822a 100644 --- a/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py +++ b/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py @@ -13,7 +13,6 @@ from economy_service_fakes import ( CREATED_AT, DYNAMIC_ID, - OUTPUT_BUCKET, POLICY_ID, REFORM, FakeCaller, @@ -26,18 +25,24 @@ BudgetWindowInputs, EconomyReportInputs, EconomySimulationInputs, + FoundBudgetWindow, + FoundReportRun, + FoundSide, + FoundSimulationRun, + FoundWindowRun, + FoundWindowYear, ReportDefinition, + ReportRunStatus, SideDefinition, SimulationChoice, SimulationDefinition, SimulationInputs, + SimulationStatus, WindowYearDefinition, ) from test_budget_window_submissions import FakeAdvancer, FakeWindowStore if TYPE_CHECKING: - from collections.abc import Sequence - from policyengine_simulation_entry.household_report_reruns import ( HouseholdReportReruns, ) @@ -46,18 +51,18 @@ NewReportRerun, NewSimulationRerun, NewWindowRerun, - RunReuse, ) REPORT_ID = UUID("00000000-0000-4000-8000-0000000000a1") BASELINE_SIMULATION_ID = UUID("00000000-0000-4000-8000-0000000000a2") REFORM_SIMULATION_ID = UUID("00000000-0000-4000-8000-0000000000a3") SIMULATION_ID = UUID("00000000-0000-4000-8000-0000000000a4") -RUN_UNDER_WAY_ID = UUID("00000000-0000-4000-8000-0000000000a5") CURRENT_LAW = SimulationChoice(policy_id=None, dynamic_id=None) REFORM_CHOICE = SimulationChoice(policy_id=POLICY_ID, dynamic_id=DYNAMIC_ID) +# A report stored before C1 · 27 kept the request's options; one asking for +# cliffs is refused until cliffs are calculated per run (interim answer A). STORED_OPTIONS: dict[str, Any] = { - "include_cliffs": True, + "include_cliffs": False, "spm": {"geography_kind": "national"}, } STORED_REPORT = ReportDefinition( @@ -118,11 +123,14 @@ class FakeRerunStore(FakeWindowStore): """Records the re-run reads and writes, and answers as told. - A budget window's re-run is read with ``reusable_by_year``, as a new - window is, and recorded in ``windows``, where the fake advancer finds it. + A budget window's re-run is recorded in ``windows``, as a new window is, + where the fake advancer finds it. ``inputs_failure`` is raised by a re-run's read of its inputs, and - ``rerun_failure`` by its create instead of recording it. + ``rerun_failure`` by its create instead of recording it. A simulation + re-run joins ``joined_simulation_run`` when one is given, and otherwise + creates its own run; a report re-run joins ``joined_report_run`` the + same way. """ report_definition: ReportDefinition | None = STORED_REPORT @@ -132,6 +140,17 @@ class FakeRerunStore(FakeWindowStore): rerun_reads: list[tuple[EconomyRequest, Any]] = field(default_factory=list) report_reruns: list[NewReportRerun] = field(default_factory=list) simulation_reruns: list[NewSimulationRerun] = field(default_factory=list) + joined_simulation_run: FoundSimulationRun | None = None + joined_report_run: FoundReportRun | None = None + # A keyed window's run on the re-run's versions, which an unforced + # re-run joins. + joined_window: FoundBudgetWindow | None = None + # The side runs a keyed report's re-run joins, by side, in place of the + # runs it proposes. + joined_side_runs: dict[str, UUID] = field(default_factory=dict) + # A keyed report with one simulation on both sides: the store inserts one + # run, with the baseline's proposed ID, and names it on both sides. + one_run_on_both_sides: bool = False def read_report_definition(self, report_id: UUID) -> ReportDefinition | None: if self.read_failure is not None: @@ -153,23 +172,19 @@ def read_report_rerun_inputs( *, baseline: SideDefinition, reform: SideDefinition, - reuse: RunReuse | None, ) -> EconomyReportInputs: - self.rerun_reads.append((request, (baseline, reform, reuse))) + self.rerun_reads.append((request, (baseline, reform))) if self.inputs_failure is not None: raise self.inputs_failure - baseline_reusable, reform_reusable = self.reusable return EconomyReportInputs( catalog=self.catalog, - baseline=SimulationInputs( - choice=baseline.choice, - reform={}, - reusable_run=None if reuse is None else baseline_reusable, - ), + baseline=SimulationInputs(choice=baseline.choice, reform={}), + # Current law sets no values, on either side. reform=SimulationInputs( choice=reform.choice, - reform=REFORM, - reusable_run=None if reuse is None else reform_reusable, + reform=REFORM + if reform.choice.policy_id or reform.choice.dynamic_id + else {}, ), ) @@ -187,38 +202,79 @@ def read_window_rerun_inputs( *, baseline: SimulationChoice, reform: SimulationChoice, - years: Sequence[WindowYearDefinition], - reuse: RunReuse | None, ) -> BudgetWindowInputs: - self.rerun_reads.append((request, (baseline, reform, tuple(years), reuse))) + self.rerun_reads.append((request, (baseline, reform))) if self.inputs_failure is not None: raise self.inputs_failure return BudgetWindowInputs( catalog=self.catalog, baseline=SimulationInputs(choice=baseline, reform={}), reform=SimulationInputs(choice=reform, reform=REFORM), - reusable_runs={ - year.year: (None, None) - if reuse is None - else self.reusable_by_year.get(year.year, (None, None)) - for year in years - }, ) - def create_window_rerun(self, rerun: NewWindowRerun) -> None: + def create_window_rerun(self, rerun: NewWindowRerun) -> FoundBudgetWindow: if self.rerun_failure is not None: raise self.rerun_failure self.windows.append(rerun) + # As the store does, a recalculating re-run joins nothing. + if self.joined_window is not None and not rerun.recalculate: + return self.joined_window + return FoundBudgetWindow( + report_id=rerun.report_id, + report_inserted=False, + window_run=FoundWindowRun( + id=rerun.window_run_id, inserted=True, status=ReportRunStatus.PENDING + ), + years=tuple( + FoundWindowYear( + year=window_year.year, + report_run_id=window_year.report_run_id, + baseline=FoundSide( + simulation_id=window_year.baseline.simulation_id, + simulation_run_id=window_year.baseline.simulation_run_id, + run_inserted=True, + ), + reform=FoundSide( + simulation_id=window_year.reform.simulation_id, + simulation_run_id=window_year.reform.simulation_run_id, + run_inserted=True, + ), + ) + for window_year in rerun.years + ), + ) - def create_report_rerun(self, rerun: NewReportRerun) -> None: + def create_report_rerun(self, rerun: NewReportRerun) -> FoundReportRun: if self.rerun_failure is not None: raise self.rerun_failure self.report_reruns.append(rerun) + # As the store does, a forced re-run joins nothing. + if self.joined_report_run is not None and not rerun.forced: + return self.joined_report_run + return FoundReportRun( + id=rerun.run_id, + inserted=True, + status=ReportRunStatus.PENDING, + baseline_simulation_run_id=self.joined_side_runs.get( + "baseline", rerun.baseline.simulation_run_id + ), + reform_simulation_run_id=self.joined_side_runs.get( + "reform", + rerun.baseline.simulation_run_id + if self.one_run_on_both_sides + else rerun.reform.simulation_run_id, + ), + ) - def create_simulation_rerun(self, rerun: NewSimulationRerun) -> None: + def create_simulation_rerun(self, rerun: NewSimulationRerun) -> FoundSimulationRun: if self.rerun_failure is not None: raise self.rerun_failure self.simulation_reruns.append(rerun) + if self.joined_simulation_run is not None: + return self.joined_simulation_run + return FoundSimulationRun( + id=rerun.run_id, inserted=True, status=SimulationStatus.PENDING + ) class UnusedAdvancer: @@ -229,12 +285,11 @@ def advance_window(self, window_run_id: UUID, **_: Any) -> NoReturn: raise AssertionError(msg) -def rerun_service( # noqa: PLR0913 # the store, then each seam a test may replace +def rerun_service( # the store, then each seam a test may replace store: FakeRerunStore, *, workers: FakeWorkers | None = None, caller: FakeCaller | None = None, - output_bucket: str | None = OUTPUT_BUCKET, advancer: FakeAdvancer | None = None, household_reports: HouseholdReportReruns | None = None, ) -> EconomyRerunService: @@ -247,7 +302,6 @@ def rerun_service( # noqa: PLR0913 # the store, then each seam a test may repl settings=ServiceSettings( environment="staging", modal_environment="staging", - output_bucket=output_bucket, ), call_start_timeout_seconds=0.05, new_id=numbered_ids(), diff --git a/projects/policyengine-simulation-entry/tests/economy_service_fakes.py b/projects/policyengine-simulation-entry/tests/economy_service_fakes.py index 535873f0f..7978f2b7c 100644 --- a/projects/policyengine-simulation-entry/tests/economy_service_fakes.py +++ b/projects/policyengine-simulation-entry/tests/economy_service_fakes.py @@ -34,8 +34,12 @@ EconomyReportState, EconomySimulationInputs, EconomySimulationState, + FoundEconomyReport, + FoundEconomySimulation, + FoundReportRun, + FoundSide, + FoundSimulationRun, ReportRunStatus, - ReusableRun, SimulationInputs, SimulationStatus, ) @@ -45,9 +49,8 @@ from policyengine_simulation_persistence import ( EconomyRequest, - NewEconomyReport, - NewEconomySimulation, - RunReuse, + KeyedEconomyReport, + KeyedEconomySimulation, SimulationChoice, ) @@ -57,12 +60,13 @@ DATASET_ID = UUID("00000000-0000-4000-8000-0000000000c4") POLICY_ID = UUID("00000000-0000-4000-8000-0000000000c5") DYNAMIC_ID = UUID("00000000-0000-4000-8000-0000000000c6") -REUSED = ReusableRun( +# A side whose simulation run another request inserted, which a report joins. +REUSED = FoundSide( simulation_id=UUID("00000000-0000-4000-8000-0000000000d1"), simulation_run_id=UUID("00000000-0000-4000-8000-0000000000d2"), + run_inserted=False, ) CREATED_AT = datetime(2026, 11, 12, 15, tzinfo=UTC) -OUTPUT_BUCKET = "policyengine-v2-simulation-outputs-staging" CTC_AMOUNT = "gov.irs.credits.ctc.amount.base[0].amount" REFORM = {CTC_AMOUNT: {"2026-01-01.2200-12-31": 3_000}} CATALOG = EconomyCatalogRows( @@ -96,7 +100,14 @@ def report_request(**changes: Any) -> EconomyReportRequest: - return EconomyReportRequest.model_validate({**REPORT_BODY, **changes}) + """Return the report body's request, asking for no cliffs unless told to. + + The service refuses ``include_cliffs: true`` until per-run cliff + calculations exist (C1 · 24's interim answer A). + """ + return EconomyReportRequest.model_validate( + {**REPORT_BODY, "include_cliffs": False, **changes} + ) def simulation_request(**changes: Any) -> EconomySimulationRequest: @@ -115,16 +126,53 @@ def default_worker(self, country: str) -> EconomyWorker: return default_economy_worker(economy_manifest(), country) +def created_report(report: KeyedEconomyReport) -> FoundEconomyReport: + """Answer a report as created with every ID the request proposed. + + Both sides name one simulation and run when their keys are one. + """ + definition = report.definition + baseline = report.baseline + same_simulation = ( + definition.simulation("baseline").definition_key + == definition.simulation("reform").definition_key + ) + reform = baseline if same_simulation else report.reform + sides = [ + FoundSide( + simulation_id=side.simulation_id, + simulation_run_id=side.simulation_run_id, + run_inserted=True, + ) + for side in (baseline, reform) + ] + return FoundEconomyReport( + report_id=report.report_id, + report_inserted=True, + run=FoundReportRun( + id=report.run_id, + inserted=True, + status=ReportRunStatus.PENDING, + baseline_simulation_run_id=sides[0].simulation_run_id, + reform_simulation_run_id=sides[1].simulation_run_id, + ), + baseline=sides[0], + reform=sides[1], + ) + + @dataclass class FakeStore: """Records what the service asks of the database, and answers as told. ``claimed`` marks the run as claimed by its coordinator or function: a - failure write then changes nothing. + failure write then changes nothing. A report or simulation the service + finds or creates by key is answered ``found_report`` or + ``found_simulation`` when given, and otherwise as created with the IDs + the request proposed (one simulation when both sides have one key). """ catalog: EconomyCatalogRows = CATALOG - reusable: tuple[ReusableRun | None, ReusableRun | None] = (None, None) read_failure: Exception | None = None create_failure: Exception | None = None record_failure: Exception | None = None @@ -134,8 +182,10 @@ class FakeStore: stored_simulation: EconomySimulationState | None = None report_reads: list[tuple[EconomyRequest, Any]] = field(default_factory=list) simulation_reads: list[tuple[EconomyRequest, Any]] = field(default_factory=list) - reports: list[NewEconomyReport] = field(default_factory=list) - simulations: list[NewEconomySimulation] = field(default_factory=list) + reports: list[KeyedEconomyReport] = field(default_factory=list) + simulations: list[KeyedEconomySimulation] = field(default_factory=list) + found_report: FoundEconomyReport | None = None + found_simulation: FoundEconomySimulation | None = None recorded_calls: list[tuple[UUID, str]] = field(default_factory=list) failed_runs: list[tuple[UUID, tuple[UUID, ...], str]] = field(default_factory=list) @@ -145,19 +195,17 @@ def read_report_inputs( *, baseline: SimulationChoice, reform: SimulationChoice, - reuse: RunReuse | None, ) -> EconomyReportInputs: - self.report_reads.append((request, (baseline, reform, reuse))) + self.report_reads.append((request, (baseline, reform))) if self.read_failure is not None: raise self.read_failure - baseline_reusable, reform_reusable = self.reusable return EconomyReportInputs( catalog=self.catalog, - baseline=SimulationInputs( - choice=baseline, reform={}, reusable_run=baseline_reusable - ), + baseline=SimulationInputs(choice=baseline, reform={}), + # Current law sets no values, on either side. reform=SimulationInputs( - choice=reform, reform=REFORM, reusable_run=reform_reusable + choice=reform, + reform=REFORM if reform.policy_id or reform.dynamic_id else {}, ), ) @@ -184,15 +232,31 @@ def read_simulation(self, simulation_id: UUID) -> EconomySimulationState | None: stored = self.stored_simulation return stored if stored is not None and stored.id == simulation_id else None - def create_report(self, report: NewEconomyReport) -> None: + def find_or_create_report(self, report: KeyedEconomyReport) -> FoundEconomyReport: if self.create_failure is not None: raise self.create_failure self.reports.append(report) + if self.found_report is not None: + return self.found_report + return created_report(report) - def create_simulation(self, simulation: NewEconomySimulation) -> None: + def find_or_create_simulation( + self, simulation: KeyedEconomySimulation + ) -> FoundEconomySimulation: if self.create_failure is not None: raise self.create_failure self.simulations.append(simulation) + if self.found_simulation is not None: + return self.found_simulation + return FoundEconomySimulation( + simulation_id=simulation.simulation_id, + simulation_inserted=True, + run=FoundSimulationRun( + id=simulation.run_id, + inserted=True, + status=SimulationStatus.PENDING, + ), + ) def record_report_call( self, report_run_id: UUID, modal_call_id: str @@ -298,7 +362,6 @@ def service( *, workers: FakeWorkers | None = None, caller: FakeCaller | None = None, - output_bucket: str | None = OUTPUT_BUCKET, ) -> EconomySubmissionService: return EconomySubmissionService( store=store, @@ -307,7 +370,6 @@ def service( settings=ServiceSettings( environment="staging", modal_environment="staging", - output_bucket=output_bucket, ), call_start_timeout_seconds=0.05, new_id=numbered_ids(), diff --git a/projects/policyengine-simulation-entry/tests/household_report_fakes.py b/projects/policyengine-simulation-entry/tests/household_report_fakes.py index 84bc86cc5..0d4afd5b4 100644 --- a/projects/policyengine-simulation-entry/tests/household_report_fakes.py +++ b/projects/policyengine-simulation-entry/tests/household_report_fakes.py @@ -28,6 +28,9 @@ default_household_worker, ) from policyengine_simulation_persistence import ( + FoundHouseholdReport, + FoundReportRun, + FoundSide, HouseholdReportInputs, ReportRunStatus, StoredHousehold, @@ -37,7 +40,7 @@ from collections.abc import Mapping, Sequence from policyengine_simulation_persistence import ( - NewHouseholdReport, + KeyedHouseholdReport, NewHouseholdReportRerun, ) @@ -122,7 +125,11 @@ class FakeHouseholdReportStore: ``claimed`` marks the report run as claimed by its household function: a failure write then changes nothing. ``rerun_failure`` is raised by a - re-run's create instead of recording it. + re-run's create instead of recording it. ``joined_run`` is a report run + an identical request created, which a create or an unforced re-run + joins; ``joined_side_runs`` names, by side, a simulation run another + report run created, which a run this request creates names instead of + its own. """ default_year: int | None = 2026 @@ -133,8 +140,10 @@ class FakeHouseholdReportStore: fail_failure: Exception | None = None rerun_failure: Exception | None = None claimed: bool = False + joined_run: FoundReportRun | None = None + joined_side_runs: dict[str, UUID] = field(default_factory=dict) reads: list[dict[str, Any]] = field(default_factory=list) - reports: list[NewHouseholdReport] = field(default_factory=list) + keyed_reports: list[KeyedHouseholdReport] = field(default_factory=list) report_reruns: list[NewHouseholdReportRerun] = field(default_factory=list) recorded_calls: list[tuple[UUID, str]] = field(default_factory=list) failed_runs: list[tuple[UUID, tuple[UUID, ...], str]] = field(default_factory=list) @@ -172,15 +181,67 @@ def read_inputs( }, ) - def create_report(self, report: NewHouseholdReport) -> None: + def find_or_create_report( + self, report: KeyedHouseholdReport + ) -> FoundHouseholdReport: if self.create_failure is not None: raise self.create_failure - self.reports.append(report) + self.keyed_reports.append(report) + proposed = { + side: (side_ids.simulation_id, side_ids.simulation_run_id) + for side, side_ids in report.proposed_sides.items() + } + run = self._run(report.run_id, proposed, may_join=True) + run_ids = {"baseline": run.baseline_simulation_run_id} + run_ids["reform"] = run.reform_simulation_run_id + sides = { + side: FoundSide( + simulation_id=simulation_id, + simulation_run_id=run_ids[side], + run_inserted=run.inserted and run_ids[side] == proposed_run_id, + ) + for side, (simulation_id, proposed_run_id) in proposed.items() + } + return FoundHouseholdReport( + report_id=report.report_id, + report_inserted=run.inserted, + run=run, + baseline=sides["baseline"], + reform=sides.get("reform"), + ) - def create_report_rerun(self, rerun: NewHouseholdReportRerun) -> None: + def create_report_rerun(self, rerun: NewHouseholdReportRerun) -> FoundReportRun: if self.rerun_failure is not None: raise self.rerun_failure self.report_reruns.append(rerun) + proposed = { + side: (side_ids.simulation_id, side_ids.simulation_run_id) + for side, side_ids in rerun.named_sides.items() + } + # As the store does, a forced re-run joins nothing. + return self._run(rerun.run_id, proposed, may_join=not rerun.forced) + + def _run( + self, + run_id: UUID, + proposed: dict[str, tuple[UUID, UUID]], + *, + may_join: bool, + ) -> FoundReportRun: + """Return the joined run, or the one created, naming any joined side runs.""" + if may_join and self.joined_run is not None: + return self.joined_run + run_ids = { + side: (self.joined_side_runs.get(side, run) if may_join else run) + for side, (_, run) in proposed.items() + } + return FoundReportRun( + id=run_id, + inserted=True, + status=ReportRunStatus.PENDING, + baseline_simulation_run_id=run_ids["baseline"], + reform_simulation_run_id=run_ids.get("reform"), + ) def record_report_call( self, report_run_id: UUID, modal_call_id: str diff --git a/projects/policyengine-simulation-entry/tests/test_budget_window_requests.py b/projects/policyengine-simulation-entry/tests/test_budget_window_requests.py index acf3edfbf..5b4fdc406 100644 --- a/projects/policyengine-simulation-entry/tests/test_budget_window_requests.py +++ b/projects/policyengine-simulation-entry/tests/test_budget_window_requests.py @@ -28,9 +28,9 @@ def test_a_window_names_its_years_from_its_first() -> None: assert request.years == tuple(range(2026, 2036)) -def test_a_window_stores_the_options_a_report_without_cliffs_stores() -> None: - # Reuse compares a report's options, so a window's years and single-year - # reports without cliffs reuse each other's runs. +def test_a_windows_calculation_options_ask_for_no_cliffs() -> None: + # The report stores the SPM selection alone (stored_options); its years + # share runs with single-year reports by key. assert _request().options() == { "include_cliffs": False, "spm": {"geography_kind": "national"}, diff --git a/projects/policyengine-simulation-entry/tests/test_budget_window_submissions.py b/projects/policyengine-simulation-entry/tests/test_budget_window_submissions.py index f935d2c1c..1717f11d8 100644 --- a/projects/policyengine-simulation-entry/tests/test_budget_window_submissions.py +++ b/projects/policyengine-simulation-entry/tests/test_budget_window_submissions.py @@ -21,7 +21,6 @@ from economy_service_fakes import ( CATALOG, CREATED_AT, - OUTPUT_BUCKET, REFORM, FakeCaller, FakeStore, @@ -47,9 +46,12 @@ from policyengine_simulation_entry.economy_submissions import ServiceSettings from policyengine_simulation_persistence import ( BudgetWindowInputs, + EconomyReportDefinition, + FoundBudgetWindow, + FoundSide, + FoundWindowRun, + FoundWindowYear, ReportRunStatus, - ReusableRun, - RunReuse, SimulationInputs, ) from policyengine_stage12_persistence import ( @@ -63,39 +65,67 @@ from test_budget_window_requests import WINDOW_BODY OBSERVED = {"observability_id": "observed"} -REUSED_IN_2027 = ReusableRun( - simulation_id=UUID("00000000-0000-4000-8000-0000000000d1"), - simulation_run_id=UUID("00000000-0000-4000-8000-0000000000d2"), -) +# A 2027 simulation run another report inserted, which a window year joins. +JOINED_RUN_IN_2027 = UUID("00000000-0000-4000-8000-0000000000d2") @dataclass class FakeWindowStore(FakeStore): - """Also reads and creates budget-window reports.""" + """Also reads budget-window reports, and finds or creates them by key. - reusable_by_year: dict[int, tuple[ReusableRun | None, ReusableRun | None]] = field( - default_factory=dict - ) + ``joined_window`` is a window run an identical request created, which a + create joins; ``joined_year_runs`` names, by year and side, a simulation + run another report run created, which a window run this request creates + names instead of its own. + """ + + joined_window: FoundBudgetWindow | None = None + joined_year_runs: dict[tuple[int, str], UUID] = field(default_factory=dict) window_reads: list[tuple[Any, ...]] = field(default_factory=list) windows: list[Any] = field(default_factory=list) + found_windows: list[FoundBudgetWindow] = field(default_factory=list) - def read_budget_window_inputs(self, request, *, baseline, reform, reuse, years): - self.window_reads.append((request, baseline, reform, reuse, tuple(years))) + def read_budget_window_inputs(self, request, *, baseline, reform): + self.window_reads.append((request, baseline, reform)) if self.read_failure is not None: raise self.read_failure return BudgetWindowInputs( catalog=self.catalog, baseline=SimulationInputs(choice=baseline, reform={}), reform=SimulationInputs(choice=reform, reform=REFORM), - reusable_runs={ - year: self.reusable_by_year.get(year, (None, None)) for year in years - }, ) - def create_budget_window_report(self, report) -> None: + def find_or_create_budget_window(self, window) -> FoundBudgetWindow: if self.create_failure is not None: raise self.create_failure - self.windows.append(report) + self.windows.append(window) + found = self.joined_window or FoundBudgetWindow( + report_id=window.report_id, + report_inserted=True, + window_run=FoundWindowRun( + id=window.window_run_id, inserted=True, status=ReportRunStatus.PENDING + ), + years=tuple( + FoundWindowYear( + year=window_year.year, + report_run_id=window_year.report_run_id, + baseline=self._side(window_year, "baseline"), + reform=self._side(window_year, "reform"), + ) + for window_year in window.years + ), + ) + self.found_windows.append(found) + return found + + def _side(self, window_year, side: str) -> FoundSide: + proposed = getattr(window_year, side) + joined_run = self.joined_year_runs.get((window_year.year, side)) + return FoundSide( + simulation_id=proposed.simulation_id, + simulation_run_id=joined_run or proposed.simulation_run_id, + run_inserted=joined_run is None, + ) @dataclass @@ -120,9 +150,13 @@ def advance_window(self, window_run_id, *, now, start_year): time.sleep(self.delay_seconds) if self.failure is not None: raise self.failure - (report,) = self.store.windows + window = ( + self.store.found_windows[-1] + if getattr(self.store, "found_windows", None) + else self.store.windows[-1] + ) started_years = [] - for window_year in report.years[:BUDGET_WINDOW_MAX_RUNNING_YEARS]: + for window_year in window.years[:BUDGET_WINDOW_MAX_RUNNING_YEARS]: year_to_start = YearToStart( year=window_year.year, run_ids=ReportRunIds( @@ -161,7 +195,6 @@ def _service(store, *, caller=None, advancer=None): settings=ServiceSettings( environment="staging", modal_environment="staging", - output_bucket=OUTPUT_BUCKET, ), call_start_timeout_seconds=0.05, new_id=numbered_ids(), @@ -187,21 +220,26 @@ def test_a_window_is_created_with_a_run_per_year_and_its_first_five_started() -> _service(store, caller=caller, advancer=advancer), budget_window_size=7 ) - ((request, baseline, reform, reuse, years),) = store.window_reads + ((request, baseline, reform),) = store.window_reads assert (baseline.policy_id, str(reform.policy_id)) == ( None, WINDOW_BODY["reform"]["policy_id"], ) - assert (request.year, years) == (2026, tuple(range(2026, 2033))) - assert reuse == RunReuse( - versions=reuse.versions, - inputs={"include_cliffs": False, "spm": {"geography_kind": "national"}}, - output_uri_prefix=f"gs://{OUTPUT_BUCKET}/", - ) + assert request.year == 2026 (report,) = store.windows + assert report.definition == EconomyReportDefinition( + country="us", + baseline=baseline, + reform=reform, + dataset_name=CATALOG.dataset.name, + region_code=CATALOG.region.code, + year=2026, + budget_window_size=7, + spm={"geography_kind": "national"}, + ) assert [window_year.year for window_year in report.years] == list(range(2026, 2033)) assert report.population == CATALOG.population(2026) - assert report.inputs == reuse.inputs + assert report.inputs == {"spm": {"geography_kind": "national"}} assert advancer.advances == [report.window_run_id] # The first five years were started, each with its own year and runs. assert len(caller.report_runs) == 5 @@ -218,7 +256,7 @@ def test_a_window_is_created_with_a_run_per_year_and_its_first_five_started() -> assert (call_id, observed) == ("fc-coordinator", OBSERVED) first_year = report.years[0] assert created.model_dump() == { - "report_id": report.id, + "report_id": report.report_id, "report_run_id": first_year.report_run_id, "budget_window_run_id": report.window_run_id, "status": ReportRunStatus.PENDING, @@ -260,16 +298,63 @@ def test_each_later_year_is_derived_from_the_first() -> None: assert context == derived_context.model_dump(mode="json") -def test_a_year_reuses_its_own_year_s_run() -> None: - store = FakeWindowStore(reusable_by_year={2027: (REUSED_IN_2027, None)}) +def test_a_year_names_its_own_years_run_another_report_created() -> None: + """Answer 8: a window year and a single-year report share runs.""" + store = FakeWindowStore(joined_year_runs={(2027, "baseline"): JOINED_RUN_IN_2027}) + caller = FakeCaller() + advancer = FakeAdvancer(store) - created = _submit(_service(store), budget_window_size=3) + created = _submit( + _service(store, caller=caller, advancer=advancer), budget_window_size=3 + ) - years = {window_year.year: window_year for window_year in store.windows[0].years} - assert years[2027].baseline.simulation_run_id == REUSED_IN_2027.simulation_run_id - assert years[2027].baseline.reused - assert not years[2026].baseline.reused assert [year.baseline_reused for year in created.years] == [False, True, False] + assert created.years[1].baseline_simulation_run_id == (JOINED_RUN_IN_2027) + year_2027 = ReportExecutionInput.model_validate(caller.report_runs[1][1]) + assert year_2027.baseline.simulation_execution_id == (JOINED_RUN_IN_2027) + + +def test_an_identical_window_request_joins_its_window_run_and_starts_no_year() -> None: + joined = FoundBudgetWindow( + report_id=UUID(int=80), + report_inserted=False, + window_run=FoundWindowRun( + id=UUID(int=81), inserted=False, status=ReportRunStatus.RUNNING + ), + years=tuple( + FoundWindowYear( + year=year, + report_run_id=UUID(int=82 + offset), + baseline=FoundSide( + simulation_id=UUID(int=90 + offset), + simulation_run_id=UUID(int=95 + offset), + run_inserted=False, + ), + reform=FoundSide( + simulation_id=UUID(int=100 + offset), + simulation_run_id=UUID(int=105 + offset), + run_inserted=False, + ), + ) + for offset, year in enumerate((2026, 2027, 2028)) + ), + ) + store = FakeWindowStore(joined_window=joined) + caller = FakeCaller() + advancer = FakeAdvancer(store) + + created = _submit( + _service(store, caller=caller, advancer=advancer), budget_window_size=3 + ) + + assert (advancer.advances, caller.report_runs) == ([], []) + assert (created.report_id, created.budget_window_run_id, created.status) == ( + UUID(int=80), + UUID(int=81), + ReportRunStatus.RUNNING, + ) + assert created.report_run_id == UUID(int=82) + assert all(year.baseline_reused and year.reform_reused for year in created.years) def test_a_first_year_modal_refuses_answers_503_naming_the_report() -> None: @@ -280,7 +365,7 @@ def test_a_first_year_modal_refuses_answers_503_naming_the_report() -> None: _submit(_service(store, caller=caller), budget_window_size=3) assert refused.value.code == "modal_call_refused" - assert refused.value.record_id == store.windows[0].id + assert refused.value.record_id == store.windows[0].report_id def test_a_start_modal_does_not_confirm_in_time_is_refused() -> None: @@ -289,7 +374,7 @@ def test_a_start_modal_does_not_confirm_in_time_is_refused() -> None: with pytest.raises(EconomySubmissionUnavailableError) as refused: _submit(_service(store, caller=FakeCaller(hang=True)), budget_window_size=2) - assert refused.value.record_id == store.windows[0].id + assert refused.value.record_id == store.windows[0].report_id def test_a_window_whose_advance_cannot_be_written_is_answered_created() -> None: @@ -303,7 +388,7 @@ def test_a_window_whose_advance_cannot_be_written_is_answered_created() -> None: created = _submit(_service(store, advancer=advancer), budget_window_size=2) assert created.status is ReportRunStatus.PENDING - assert created.report_id == store.windows[0].id + assert created.report_id == store.windows[0].report_id @dataclass @@ -386,7 +471,7 @@ def test_a_later_year_modal_refuses_fails_the_window() -> None: _service(store, caller=RefusingAfterFirstCaller()), budget_window_size=3 ) - assert refused.value.record_id == store.windows[0].id + assert refused.value.record_id == store.windows[0].report_id def test_a_later_year_is_deferred_without_a_call_once_the_wait_has_run_out( diff --git a/projects/policyengine-simulation-entry/tests/test_config.py b/projects/policyengine-simulation-entry/tests/test_config.py index d3b72af5a..3d6612c99 100644 --- a/projects/policyengine-simulation-entry/tests/test_config.py +++ b/projects/policyengine-simulation-entry/tests/test_config.py @@ -412,18 +412,6 @@ def test_the_v2_manifest_settings_configure_no_stage12_resource(): assert not settings.stage12_resources_configured -def test_the_v2_output_bucket_is_read_from_the_environment(monkeypatch): - from policyengine_simulation_entry.config import Settings - - monkeypatch.setenv("V2_SIMULATION_OUTPUT_BUCKET", "policyengine-v2-outputs-staging") - - assert Settings.from_env().v2_simulation_output_bucket == ( - "policyengine-v2-outputs-staging" - ) - monkeypatch.delenv("V2_SIMULATION_OUTPUT_BUCKET") - assert Settings.from_env().v2_simulation_output_bucket == "" - - def test_economy_runs_need_the_database_and_the_v2_modal_environment(): assert not make_settings().economy_runs_configured assert not make_settings( diff --git a/projects/policyengine-simulation-entry/tests/test_deployment_assets_support.py b/projects/policyengine-simulation-entry/tests/test_deployment_assets_support.py index 5d8dc1eb0..a0c8ada56 100644 --- a/projects/policyengine-simulation-entry/tests/test_deployment_assets_support.py +++ b/projects/policyengine-simulation-entry/tests/test_deployment_assets_support.py @@ -644,5 +644,4 @@ def cloud_run_deploy_environment(tmp_path: Path) -> dict[str, str]: "SIMULATION_SERVICE_DATABASE_URL_SECRET_NAME": ( "simulation-staging-service-database-url" ), - "V2_SIMULATION_OUTPUT_BUCKET_VALUE": "policyengine-v2-outputs-staging", } diff --git a/projects/policyengine-simulation-entry/tests/test_economy_deployment.py b/projects/policyengine-simulation-entry/tests/test_economy_deployment.py deleted file mode 100644 index b500d1be7..000000000 --- a/projects/policyengine-simulation-entry/tests/test_economy_deployment.py +++ /dev/null @@ -1,84 +0,0 @@ -"""Deployment wiring for the economy report and simulation routes. - -Every deploy gives the service the bucket that keeps v2 simulation output -files for good (the environment variable ``V2_SIMULATION_OUTPUT_BUCKET``), -so a report reuses only a succeeded run whose file is in it. The service -compares output URIs with it and never reads the bucket. -""" - -from __future__ import annotations - -import json -import subprocess -from pathlib import Path - -import pytest -from test_deployment_assets_support import ( - CLOUD_RUN_DEPLOY_SCRIPT, - REUSABLE_DEPLOY_WORKFLOW, - cloud_run_deploy_environment, - workflow_jobs, -) - - -def _run_deploy(tmp_path, **overrides): - environment = cloud_run_deploy_environment(tmp_path) | overrides - result = subprocess.run( - [CLOUD_RUN_DEPLOY_SCRIPT], - check=False, - capture_output=True, - text=True, - env=environment, - ) - return result, environment - - -@pytest.mark.parametrize("deploy_stage12", ["true", "false"]) -def test_every_deploy_names_the_v2_output_bucket(tmp_path, deploy_stage12): - result, environment = _run_deploy( - tmp_path, - DEPLOY_STAGE12_V2=deploy_stage12, - V2_SIMULATION_OUTPUT_BUCKET_VALUE="policyengine-v2-outputs-staging", - ) - - assert result.returncode == 0, result.stderr - runtime_environment = json.loads( - Path(environment["GCLOUD_ENV_FILE_CAPTURE"]).read_text(encoding="utf-8") - ) - assert runtime_environment["V2_SIMULATION_OUTPUT_BUCKET"] == ( - "policyengine-v2-outputs-staging" - ) - - -@pytest.mark.parametrize( - ("bucket", "message"), - [ - ("", "V2_SIMULATION_OUTPUT_BUCKET_VALUE must be set"), - ( - "gs://policyengine-v2-outputs", - "V2_SIMULATION_OUTPUT_BUCKET_VALUE is invalid", - ), - ("Policyengine", "V2_SIMULATION_OUTPUT_BUCKET_VALUE is invalid"), - ], -) -def test_a_deploy_without_a_valid_output_bucket_stops(tmp_path, bucket, message): - result, environment = _run_deploy( - tmp_path, V2_SIMULATION_OUTPUT_BUCKET_VALUE=bucket - ) - - assert result.returncode != 0 - assert message in result.stderr - assert not Path(environment["GCLOUD_ARGUMENTS_CAPTURE"]).exists() - - -def test_the_deploy_step_passes_the_environments_output_bucket(): - deploy_entrypoint = workflow_jobs(REUSABLE_DEPLOY_WORKFLOW)["deploy_entrypoint"] - deploy_step = next( - step - for step in deploy_entrypoint["steps"] - if step.get("name") == "Deploy Cloud Run entrypoint candidate" - ) - - assert deploy_step["env"]["V2_SIMULATION_OUTPUT_BUCKET_VALUE"] == ( - "${{ vars.V2_SIMULATION_OUTPUT_BUCKET }}" - ) diff --git a/projects/policyengine-simulation-entry/tests/test_economy_rerun_routes.py b/projects/policyengine-simulation-entry/tests/test_economy_rerun_routes.py index 99cd90072..d767c5f24 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_rerun_routes.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_rerun_routes.py @@ -264,25 +264,6 @@ def test_an_unknown_record_answers_404(client_for, path, body, record) -> None: } -@pytest.mark.parametrize(("path", "body"), ROUTES) -def test_a_run_under_way_answers_409_naming_it(client_for, path, body) -> None: - reruns = FakeEconomyReruns( - failure=EconomyRerunConflictError( - code="run_in_progress", detail="a run is under way", run_id=RUN_ID - ) - ) - - with client_for(reruns) as client: - result = client.post(path, json=body) - - assert result.status_code == 409 - assert result.json() == { - "code": "run_in_progress", - "detail": "a run is under way", - "run_id": str(RUN_ID), - } - - @pytest.mark.parametrize(("path", "body"), ROUTES) def test_a_record_the_service_cannot_rerun_answers_409(client_for, path, body) -> None: reruns = FakeEconomyReruns( diff --git a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py index eb4efe3e7..0eb96f1da 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py @@ -11,7 +11,6 @@ BASELINE_SIMULATION_ID, REFORM_SIMULATION_ID, REPORT_ID, - RUN_UNDER_WAY_ID, SIMULATION_ID, STORED_OPTIONS, STORED_REPORT, @@ -23,7 +22,6 @@ ) from economy_service_fakes import ( CATALOG, - OUTPUT_BUCKET, REFORM, FakeCaller, ) @@ -46,6 +44,12 @@ CatalogDataset, EconomyRecordOutcomeUnknownError, EconomyRecordReferenceError, + FoundBudgetWindow, + FoundReportRun, + FoundSide, + FoundSimulationRun, + FoundWindowRun, + FoundWindowYear, MissingPolicyParametersError, NewReportRerun, NewSimulationRerun, @@ -53,10 +57,8 @@ ReportSideError, RerunRecordDeletedError, RerunSide, - ReusableRun, - RunInProgressError, - RunReuse, RunVersions, + SharedRowNotSettledError, SimulationStatus, UnknownRegionError, ) @@ -68,14 +70,6 @@ country_package_version="2.2.1", policyengine_version=POLICYENGINE_VERSION ) OBSERVED = {"observability_id": "observed"} -REUSED_2027 = ReusableRun( - simulation_id=UUID("00000000-0000-4000-8000-000000002027"), - simulation_run_id=UUID("00000000-0000-4000-8000-0000000000b2"), -) -REUSED_BASELINE = ReusableRun( - simulation_id=BASELINE_SIMULATION_ID, - simulation_run_id=UUID("00000000-0000-4000-8000-0000000000b1"), -) def _rerun_report(service, request: ReportRerunRequest | None = None): @@ -97,13 +91,16 @@ def _rerun_simulation(service, simulation_id: UUID = SIMULATION_ID): ) -def test_a_report_is_rerun_on_the_default_workers_versions_as_a_new_run() -> None: - store = FakeRerunStore(reusable=(REUSED_BASELINE, None)) +def test_a_report_with_no_keys_is_rerun_as_forced_runs_on_the_current_versions() -> ( + None +): + """Interim answer B: its simulations' runs may have report-dependent plans.""" + store = FakeRerunStore() caller = FakeCaller() rerun = _rerun_report(rerun_service(store, caller=caller)) - ((request, (baseline, reform, reuse)),) = store.rerun_reads + ((request, (baseline, reform)),) = store.rerun_reads assert (request.country, request.policyengine_version, request.year) == ( "us", POLICYENGINE_VERSION, @@ -111,11 +108,7 @@ def test_a_report_is_rerun_on_the_default_workers_versions_as_a_new_run() -> Non ) assert (request.region_code, request.dataset_name) == ("us", "populace_us_2024") assert (baseline, reform) == (STORED_REPORT.baseline, STORED_REPORT.reform) - assert reuse == RunReuse( - versions=VERSIONS, - inputs=STORED_OPTIONS, - output_uri_prefix=f"gs://{OUTPUT_BUCKET}/", - ) + # Extra runs, marked forced, which nothing joins and no index refuses. assert store.report_reruns == [ NewReportRerun( report_id=REPORT_ID, @@ -124,30 +117,29 @@ def test_a_report_is_rerun_on_the_default_workers_versions_as_a_new_run() -> Non versions=VERSIONS, baseline=RerunSide( simulation_id=BASELINE_SIMULATION_ID, - simulation_run_id=REUSED_BASELINE.simulation_run_id, - reused=True, + simulation_run_id=UUID(int=2), ), reform=RerunSide( simulation_id=REFORM_SIMULATION_ID, - simulation_run_id=UUID(int=2), - reused=False, + simulation_run_id=UUID(int=3), ), + forced=True, ) ] ((_, payload, context, observed),) = caller.report_runs assert observed == OBSERVED report = ReportExecutionInput.model_validate(payload) assert report.evaluation_id == UUID(int=1) - assert report.baseline.simulation_execution_id == REUSED_BASELINE.simulation_run_id + assert report.baseline.simulation_execution_id == UUID(int=2) assert (report.reform.simulation_execution_id, report.reform.policy) == ( - UUID(int=2), + UUID(int=3), REFORM, ) - assert report.reform.options == STORED_OPTIONS + assert report.reform.options == {"spm": STORED_OPTIONS["spm"]} assert Stage12InvocationContext.model_validate(context).report_run == ReportRunIds( report_run_id=UUID(int=1), - baseline_simulation_run_id=REUSED_BASELINE.simulation_run_id, - reform_simulation_run_id=UUID(int=2), + baseline_simulation_run_id=UUID(int=2), + reform_simulation_run_id=UUID(int=3), ) assert store.recorded_calls == [(UUID(int=1), "fc-coordinator")] assert rerun.model_dump() == { @@ -155,33 +147,153 @@ def test_a_report_is_rerun_on_the_default_workers_versions_as_a_new_run() -> Non "report_run_id": UUID(int=1), "status": ReportRunStatus.PENDING, "baseline_simulation_id": BASELINE_SIMULATION_ID, - "baseline_simulation_run_id": REUSED_BASELINE.simulation_run_id, - "baseline_reused": True, + "baseline_simulation_run_id": UUID(int=2), + "baseline_reused": False, "reform_simulation_id": REFORM_SIMULATION_ID, - "reform_simulation_run_id": UUID(int=2), + "reform_simulation_run_id": UUID(int=3), "reform_reused": False, } def test_a_forced_rerun_recalculates_both_simulations() -> None: - store = FakeRerunStore(reusable=(REUSED_BASELINE, None)) + store = FakeRerunStore() rerun = _rerun_report(rerun_service(store), ReportRerunRequest(force=True)) - assert store.rerun_reads[0][1][2] is None (created,) = store.report_reruns - assert (created.baseline.reused, created.reform.reused) == (False, False) + # An extra run, marked forced, which nothing joins (answer 3). + assert created.forced is True assert created.new_simulation_run_ids == (UUID(int=2), UUID(int=3)) assert created.baseline.simulation_id == BASELINE_SIMULATION_ID assert (rerun.baseline_reused, rerun.reform_reused) == (False, False) -def test_without_the_output_bucket_a_rerun_looks_for_no_run_to_reuse() -> None: - store = FakeRerunStore(reusable=(REUSED_BASELINE, None)) +@pytest.mark.parametrize( + "status", + [ReportRunStatus.PENDING, ReportRunStatus.RUNNING, ReportRunStatus.SUCCEEDED], +) +def test_a_report_rerun_joining_a_run_answers_it_and_starts_no_call( + status: ReportRunStatus, +) -> None: + """Answer 3: a run under way, or one that succeeded on these versions. + + Only a keyed report's re-run joins a run (interim answer B). + """ + joined = FoundReportRun( + id=UUID(int=90), + inserted=False, + status=status, + baseline_simulation_run_id=UUID(int=91), + reform_simulation_run_id=UUID(int=92), + ) + store = FakeRerunStore( + report_definition=replace(STORED_REPORT, keyed=True), + joined_report_run=joined, + ) + caller = FakeCaller() + + rerun = _rerun_report(rerun_service(store, caller=caller)) + + assert caller.report_runs == [] + assert store.recorded_calls == [] + assert store.failed_runs == [] + assert rerun.model_dump() == { + "report_id": REPORT_ID, + "report_run_id": UUID(int=90), + "status": status, + "baseline_simulation_id": BASELINE_SIMULATION_ID, + "baseline_simulation_run_id": UUID(int=91), + "baseline_reused": True, + "reform_simulation_id": REFORM_SIMULATION_ID, + "reform_simulation_run_id": UUID(int=92), + "reform_reused": True, + } + + +def test_a_keyed_reports_rerun_has_each_side_join_its_run_on_the_versions() -> None: + """Answers 4 and 5: a side joins its simulation's unfailed run, in any state.""" + joined_baseline_run = UUID(int=77) + store = FakeRerunStore( + report_definition=replace(STORED_REPORT, keyed=True), + joined_side_runs={"baseline": joined_baseline_run}, + ) + caller = FakeCaller() + + rerun = _rerun_report(rerun_service(store, caller=caller)) + + (created,) = store.report_reruns + assert created.forced is False + payload = ReportExecutionInput.model_validate(caller.report_runs[0][1]) + assert payload.baseline.simulation_execution_id == joined_baseline_run + assert payload.reform.simulation_execution_id == created.reform.simulation_run_id + assert (rerun.baseline_simulation_run_id, rerun.baseline_reused) == ( + joined_baseline_run, + True, + ) + assert (rerun.reform_simulation_run_id, rerun.reform_reused) == ( + created.reform.simulation_run_id, + False, + ) + + +def test_a_keyed_rerun_with_one_simulation_on_both_sides_reuses_neither() -> None: + """Review round 4: the one run this re-run inserted is named on both sides.""" + store = FakeRerunStore( + report_definition=replace( + STORED_REPORT, + keyed=True, + reform=STORED_REPORT.baseline, + ), + one_run_on_both_sides=True, + ) + caller = FakeCaller() + + rerun = _rerun_report(rerun_service(store, caller=caller)) + + (created,) = store.report_reruns + assert rerun.baseline_simulation_run_id == rerun.reform_simulation_run_id + assert rerun.baseline_simulation_run_id == created.baseline.simulation_run_id + assert (rerun.baseline_reused, rerun.reform_reused) == (False, False) + + +def test_a_keyed_reports_forced_rerun_joins_nothing() -> None: + """Answer 3: a forced run is an extra run, on new runs of both sides.""" + store = FakeRerunStore( + report_definition=replace(STORED_REPORT, keyed=True), + joined_report_run=FoundReportRun( + id=UUID(int=90), + inserted=False, + status=ReportRunStatus.SUCCEEDED, + baseline_simulation_run_id=UUID(int=91), + reform_simulation_run_id=UUID(int=92), + ), + ) + caller = FakeCaller() - _rerun_report(rerun_service(store, output_bucket=None)) + rerun = _rerun_report( + rerun_service(store, caller=caller), ReportRerunRequest(force=True) + ) + + (created,) = store.report_reruns + assert created.forced is True + assert created.new_simulation_run_ids == (UUID(int=2), UUID(int=3)) + assert rerun.report_run_id == UUID(int=1) + assert (rerun.baseline_reused, rerun.reform_reused) == (False, False) + assert len(caller.report_runs) == 1 - assert store.rerun_reads[0][1][2] is None + +def test_a_keyed_reports_refused_rerun_fails_only_the_report_run() -> None: + """Its simulation runs may already be another report run's.""" + store = FakeRerunStore(report_definition=replace(STORED_REPORT, keyed=True)) + + with pytest.raises(EconomySubmissionUnavailableError): + _rerun_report( + rerun_service(store, caller=FakeCaller(failure=ConnectionError("no"))) + ) + + ((run_id, simulation_run_ids, _message),) = store.failed_runs + assert run_id == store.report_reruns[0].run_id + assert simulation_run_ids == () def test_an_unknown_report_or_simulation_is_not_found() -> None: @@ -230,25 +342,8 @@ def test_a_report_missing_a_row_it_calculates_on_is_not_rerun(missing, named) -> assert store.rerun_reads == [] -def test_a_rerun_is_refused_while_a_run_is_under_way() -> None: - store = FakeRerunStore(rerun_failure=RunInProgressError(RUN_UNDER_WAY_ID)) - caller = FakeCaller() - service = rerun_service(store, caller=caller) - - with pytest.raises(EconomyRerunConflictError) as report: - _rerun_report(service) - with pytest.raises(EconomyRerunConflictError) as simulation: - _rerun_simulation(service) - - for refused, record in ((report, "report"), (simulation, "simulation")): - assert refused.value.code == "run_in_progress" - assert refused.value.run_id == RUN_UNDER_WAY_ID - assert f"The {record} has a run" in refused.value.detail - assert (caller.report_runs, caller.simulation_runs) == ([], []) - - def test_a_rerun_modal_refuses_fails_only_its_new_runs_and_names_them() -> None: - store = FakeRerunStore(reusable=(REUSED_BASELINE, None)) + store = FakeRerunStore() with pytest.raises(EconomySubmissionUnavailableError) as unavailable: _rerun_report( @@ -263,7 +358,7 @@ def test_a_rerun_modal_refuses_fails_only_its_new_runs_and_names_them() -> None: ) assert "the report's new run" in error.detail ((run_id, simulation_run_ids, message),) = store.failed_runs - assert (run_id, simulation_run_ids) == (UUID(int=1), (UUID(int=2),)) + assert (run_id, simulation_run_ids) == (UUID(int=1), (UUID(int=2), UUID(int=3))) assert message.startswith("modal_call_refused: Modal did not accept the report") @@ -297,6 +392,41 @@ def test_a_stored_policy_the_current_catalog_cannot_set_is_located_on_its_side() assert store.report_reruns == [] +@pytest.mark.parametrize("stored", [STORED_REPORT, STORED_WINDOW]) +def test_a_stored_report_asking_for_cliffs_is_not_rerun_until_cliffs_exist( + stored, +) -> None: + """Interim answer A: created before C1 · 27 with ``include_cliffs: true``.""" + store = FakeRerunStore( + report_definition=replace( + stored, inputs={**STORED_OPTIONS, "include_cliffs": True} + ) + ) + caller = FakeCaller() + + with pytest.raises(EconomySubmissionUnprocessableError) as refused: + _rerun_report(rerun_service(store, caller=caller)) + + assert refused.value.code == "cliffs_not_available" + ((reason,),) = (refused.value.reasons,) + assert reason.loc == ("report", "inputs", "include_cliffs") + assert "cliff impacts" in reason.msg + assert (store.rerun_reads, store.report_reruns, store.windows) == ([], [], []) + assert caller.report_runs == [] + + +def test_a_stored_report_whose_cliffs_were_not_asked_for_is_rerun() -> None: + store = FakeRerunStore( + report_definition=replace( + STORED_REPORT, inputs={**STORED_OPTIONS, "include_cliffs": False} + ) + ) + + _rerun_report(rerun_service(store)) + + assert len(store.report_reruns) == 1 + + def test_a_stored_region_the_current_catalog_lacks_is_refused_naming_the_report() -> ( None ): @@ -338,6 +468,22 @@ def test_a_database_that_cannot_be_read_is_unavailable_before_any_call() -> None assert caller.report_runs == [] +@pytest.mark.parametrize("record", ["report", "simulation"]) +def test_a_run_that_keeps_failing_before_it_is_read_is_answered_unavailable( + record: str, +) -> None: + """Nothing was written, so the caller is told to ask again (503).""" + store = FakeRerunStore(rerun_failure=SharedRowNotSettledError("kept failing")) + caller = FakeCaller() + rerun = _rerun_report if record == "report" else _rerun_simulation + + with pytest.raises(EconomySubmissionUnavailableError) as unavailable: + rerun(rerun_service(store, caller=caller)) + + assert unavailable.value.code == "database_unavailable" + assert (caller.report_runs, caller.simulation_runs) == ([], []) + + def test_a_rerun_whose_commit_is_unconfirmed_may_have_written_its_run() -> None: store = FakeRerunStore( rerun_failure=EconomyRecordOutcomeUnknownError("commit failed") @@ -386,6 +532,29 @@ def test_a_simulation_is_rerun_as_a_new_run_of_it() -> None: } +@pytest.mark.parametrize( + "status", [SimulationStatus.PENDING, SimulationStatus.SUCCEEDED] +) +def test_a_simulation_rerun_joining_a_run_answers_it_and_starts_no_call( + status: SimulationStatus, +) -> None: + """Answer 3: a run under way, or one that succeeded on these versions.""" + joined = FoundSimulationRun(id=UUID(int=99), inserted=False, status=status) + store = FakeRerunStore(joined_simulation_run=joined) + caller = FakeCaller() + + rerun = _rerun_simulation(rerun_service(store, caller=caller)) + + assert caller.simulation_runs == [] + assert store.recorded_calls == [] + assert store.failed_runs == [] + assert rerun.model_dump() == { + "simulation_id": SIMULATION_ID, + "simulation_run_id": UUID(int=99), + "status": status, + } + + @pytest.mark.parametrize( ("changes", "named"), [ @@ -478,32 +647,25 @@ def test_a_row_deleted_after_a_reruns_reads_is_refused_naming_the_report( def test_a_budget_window_is_rerun_as_a_new_window_run_and_its_first_years_started(): - store = FakeRerunStore( - report_definition=STORED_WINDOW, reusable_by_year={2027: (REUSED_2027, None)} - ) + """Interim answer B: a window has no keys yet, so every year is recalculated.""" + store = FakeRerunStore(report_definition=STORED_WINDOW) caller = FakeCaller() advancer = FakeAdvancer(store) rerun = _rerun_report(rerun_service(store, caller=caller, advancer=advancer)) - ((request, (baseline, reform, years, reuse)),) = store.rerun_reads + ((request, (baseline, reform)),) = store.rerun_reads assert (request.policyengine_version, request.year) == (POLICYENGINE_VERSION, 2026) assert (request.region_code, request.dataset_name) == ("us", "populace_us_2024") - assert (baseline, reform, years) == ( + assert (baseline, reform) == ( STORED_WINDOW.baseline.choice, STORED_WINDOW.reform.choice, - STORED_WINDOW.window_years, - ) - assert reuse == RunReuse( - versions=VERSIONS, - inputs=STORED_OPTIONS, - output_uri_prefix=f"gs://{OUTPUT_BUCKET}/", ) (window,) = store.windows assert (window.report_id, window.window_run_id, window.recalculate) == ( REPORT_ID, UUID(int=1), - False, + True, ) assert (window.population, window.versions) == (CATALOG.population(2026), VERSIONS) assert [window_year.year for window_year in window.years] == [2026, 2027, 2028] @@ -511,11 +673,6 @@ def test_a_budget_window_is_rerun_as_a_new_window_run_and_its_first_years_starte baseline_id, reform_id = WINDOW_SIMULATION_IDS[window_year.year] assert window_year.baseline.simulation_id == baseline_id assert window_year.reform.simulation_id == reform_id - year_2027 = window.years[1] - assert (year_2027.baseline.simulation_run_id, year_2027.baseline.reused) == ( - REUSED_2027.simulation_run_id, - True, - ) assert advancer.advances == [window.window_run_id] assert len(caller.report_runs) == 3 for (year_to_start, _), (_, payload, context, observed) in zip( @@ -524,7 +681,7 @@ def test_a_budget_window_is_rerun_as_a_new_window_run_and_its_first_years_starte report = ReportExecutionInput.model_validate(payload) assert report.baseline.year == report.reform.year == year_to_start.year assert report.reform.policy == REFORM - assert report.reform.options == STORED_OPTIONS + assert report.reform.options == {"spm": STORED_OPTIONS["spm"]} assert Stage12InvocationContext.model_validate(context).report_run == ( year_to_start.run_ids ) @@ -540,7 +697,7 @@ def test_a_budget_window_is_rerun_as_a_new_window_run_and_its_first_years_starte "report_run_id": window_year.report_run_id, "baseline_simulation_id": window_year.baseline.simulation_id, "baseline_simulation_run_id": window_year.baseline.simulation_run_id, - "baseline_reused": window_year.baseline.reused, + "baseline_reused": False, "reform_simulation_id": window_year.reform.simulation_id, "reform_simulation_run_id": window_year.reform.simulation_run_id, "reform_reused": False, @@ -551,22 +708,100 @@ def test_a_budget_window_is_rerun_as_a_new_window_run_and_its_first_years_starte def test_a_forced_window_rerun_recalculates_every_year() -> None: - store = FakeRerunStore( - report_definition=STORED_WINDOW, reusable_by_year={2027: (REUSED_2027, None)} - ) + store = FakeRerunStore(report_definition=STORED_WINDOW) rerun = _rerun_report( rerun_service(store, advancer=FakeAdvancer(store)), ReportRerunRequest(force=True), ) - assert store.rerun_reads[0][1][3] is None (window,) = store.windows assert window.recalculate is True - assert not any(window_year.baseline.reused for window_year in window.years) assert not any(year.baseline_reused for year in rerun.years) +KEYED_WINDOW = replace(STORED_WINDOW, keyed=True) + + +def test_a_keyed_windows_rerun_joins_its_window_run_and_starts_no_year() -> None: + """Answers 3 and 8: the window run on these versions is answered as it is.""" + joined = FoundBudgetWindow( + report_id=REPORT_ID, + report_inserted=False, + window_run=FoundWindowRun( + id=UUID(int=81), inserted=False, status=ReportRunStatus.SUCCEEDED + ), + years=tuple( + FoundWindowYear( + year=year, + report_run_id=UUID(int=82 + offset), + baseline=FoundSide( + simulation_id=WINDOW_SIMULATION_IDS[year][0], + simulation_run_id=UUID(int=90 + offset), + run_inserted=False, + ), + reform=FoundSide( + simulation_id=WINDOW_SIMULATION_IDS[year][1], + simulation_run_id=UUID(int=95 + offset), + run_inserted=False, + ), + ) + for offset, year in enumerate((2026, 2027, 2028)) + ), + ) + store = FakeRerunStore(report_definition=KEYED_WINDOW, joined_window=joined) + caller = FakeCaller() + advancer = FakeAdvancer(store) + + rerun = _rerun_report(rerun_service(store, caller=caller, advancer=advancer)) + + (window,) = store.windows + assert window.recalculate is False + assert (advancer.advances, caller.report_runs) == ([], []) + assert (rerun.budget_window_run_id, rerun.status, rerun.report_run_id) == ( + UUID(int=81), + ReportRunStatus.SUCCEEDED, + UUID(int=82), + ) + assert all(year.baseline_reused for year in rerun.years) + + +def test_a_keyed_windows_rerun_with_no_run_on_its_versions_starts_a_new_one() -> None: + store = FakeRerunStore(report_definition=KEYED_WINDOW) + advancer = FakeAdvancer(store) + + rerun = _rerun_report(rerun_service(store, advancer=advancer)) + + (window,) = store.windows + assert window.recalculate is False + assert advancer.advances == [window.window_run_id] + assert rerun.budget_window_run_id == window.window_run_id + + +def test_a_keyed_windows_forced_rerun_recalculates_every_year() -> None: + store = FakeRerunStore( + report_definition=KEYED_WINDOW, + joined_window=FoundBudgetWindow( + report_id=REPORT_ID, + report_inserted=False, + window_run=FoundWindowRun( + id=UUID(int=81), inserted=False, status=ReportRunStatus.SUCCEEDED + ), + years=(), + ), + ) + advancer = FakeAdvancer(store) + + rerun = _rerun_report( + rerun_service(store, advancer=advancer), ReportRerunRequest(force=True) + ) + + (window,) = store.windows + assert window.recalculate is True + assert advancer.advances == [window.window_run_id] + assert rerun.budget_window_run_id == window.window_run_id + + def test_a_window_rerun_whose_first_year_modal_refuses_names_the_window_run() -> None: store = FakeRerunStore(report_definition=STORED_WINDOW) caller = FakeCaller(failure=RuntimeError("Modal is unavailable")) diff --git a/projects/policyengine-simulation-entry/tests/test_economy_routes.py b/projects/policyengine-simulation-entry/tests/test_economy_routes.py index 30a1bcffc..6f88a5054 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_routes.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_routes.py @@ -370,7 +370,6 @@ def test_a_configured_service_builds_economy_submissions_without_connecting(): make_settings( simulation_database_url=DATABASE_URL, v2_modal_environment="staging", - v2_simulation_output_bucket="policyengine-v2-outputs-staging", ), database, ) diff --git a/projects/policyengine-simulation-entry/tests/test_economy_submissions.py b/projects/policyengine-simulation-entry/tests/test_economy_submissions.py index 062fa9b7c..47b9f3137 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_submissions.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_submissions.py @@ -12,7 +12,6 @@ CATALOG, CREATED_AT, DYNAMIC_ID, - OUTPUT_BUCKET, POLICY_ID, REFORM, REPORT_BODY, @@ -47,14 +46,21 @@ CatalogDataset, EconomyRecordOutcomeUnknownError, EconomyRecordReferenceError, + EconomyReportDefinition, EconomyReportState, + EconomySimulationDefinition, EconomySimulationState, + FoundEconomyReport, + FoundEconomySimulation, + FoundReportRun, + FoundSide, + FoundSimulationRun, MissingPolicyParametersError, OverlappingReformError, + ProposedSide, ReportRunState, ReportRunStatus, ReportSideError, - RunReuse, RunVersions, SimulationChoice, SimulationRunState, @@ -94,13 +100,13 @@ def _submit_simulation(submissions, request=None): ) -def test_a_report_is_created_with_new_runs_and_its_coordinator_started() -> None: +def test_a_report_is_created_by_key_and_its_coordinator_started() -> None: store = FakeStore() caller = FakeCaller() created = _submit_report(service(store, caller=caller)) - (request, (baseline, reform, reuse)) = store.report_reads[0] + (request, (baseline, reform)) = store.report_reads[0] assert (request.country, request.policyengine_version, request.region_code) == ( "us", POLICYENGINE_VERSION, @@ -109,70 +115,135 @@ def test_a_report_is_created_with_new_runs_and_its_coordinator_started() -> None assert (request.dataset_name, request.year) == (None, 2026) assert baseline == SimulationChoice(policy_id=None, dynamic_id=None) assert reform == SimulationChoice(policy_id=POLICY_ID, dynamic_id=DYNAMIC_ID) - options = {"include_cliffs": True, "spm": {"geography_kind": "national"}} - assert reuse == RunReuse( - versions=VERSIONS, inputs=options, output_uri_prefix=f"gs://{OUTPUT_BUCKET}/" - ) (report,) = store.reports - assert (report.id, report.run_id) == (UUID(int=1), UUID(int=2)) - assert (report.label, report.description, report.country) == ( - "A larger child tax credit", - "Raises the credit to $3,000", - "us", + spm = {"geography_kind": "national"} + assert report.definition == EconomyReportDefinition( + country="us", + baseline=baseline, + reform=reform, + dataset_name=CATALOG.dataset.name, + region_code=CATALOG.region.code, + year=2026, + budget_window_size=None, + spm=spm, + ) + assert (report.report_id, report.run_id) == (UUID(int=1), UUID(int=2)) + assert (report.baseline, report.reform) == ( + ProposedSide(simulation_id=UUID(int=3), simulation_run_id=UUID(int=4)), + ProposedSide(simulation_id=UUID(int=5), simulation_run_id=UUID(int=6)), ) assert report.tax_benefit_model_id == CATALOG.model_id assert report.population == CATALOG.population(2026) - assert (report.versions, report.inputs) == (VERSIONS, options) - assert (report.baseline.reused, report.reform.reused) == (False, False) - assert report.new_simulation_run_ids == (UUID(int=4), UUID(int=6)) - assert report.reform.choice == reform + # Answer 4: the report stores no option but the SPM selection. + assert (report.versions, report.inputs) == (VERSIONS, {"spm": spm}) ((_, payload, context, observed),) = caller.report_runs assert observed == OBSERVED assert ReportExecutionInput.model_validate(payload).reform.policy == REFORM assert Stage12InvocationContext.model_validate(context).report_run == ReportRunIds( - report_run_id=report.run_id, - baseline_simulation_run_id=report.baseline.simulation_run_id, - reform_simulation_run_id=report.reform.simulation_run_id, + report_run_id=UUID(int=2), + baseline_simulation_run_id=UUID(int=4), + reform_simulation_run_id=UUID(int=6), ) - assert store.recorded_calls == [(report.run_id, "fc-coordinator")] + assert store.recorded_calls == [(UUID(int=2), "fc-coordinator")] assert created.model_dump() == { - "report_id": report.id, - "report_run_id": report.run_id, + "report_id": UUID(int=1), + "report_run_id": UUID(int=2), "status": ReportRunStatus.PENDING, - "baseline_simulation_id": report.baseline.simulation_id, - "baseline_simulation_run_id": report.baseline.simulation_run_id, + "baseline_simulation_id": UUID(int=3), + "baseline_simulation_run_id": UUID(int=4), "baseline_reused": False, - "reform_simulation_id": report.reform.simulation_id, - "reform_simulation_run_id": report.reform.simulation_run_id, + "reform_simulation_id": UUID(int=5), + "reform_simulation_run_id": UUID(int=6), "reform_reused": False, } -def test_a_side_with_a_reusable_run_names_it_instead_of_a_new_one() -> None: - store = FakeStore(reusable=(REUSED, None)) +def _found_report(*, run_inserted: bool, status: ReportRunStatus) -> FoundEconomyReport: + """Return a report another request created, with its run as told.""" + return FoundEconomyReport( + report_id=UUID(int=90), + report_inserted=False, + run=FoundReportRun( + id=UUID(int=91), + inserted=run_inserted, + status=status, + baseline_simulation_run_id=REUSED.simulation_run_id, + reform_simulation_run_id=UUID(int=93), + ), + baseline=FoundSide( + simulation_id=REUSED.simulation_id, + simulation_run_id=REUSED.simulation_run_id, + run_inserted=False, + ), + reform=FoundSide( + simulation_id=UUID(int=92), + simulation_run_id=UUID(int=93), + run_inserted=run_inserted, + ), + ) + + +@pytest.mark.parametrize( + "status", + [ReportRunStatus.PENDING, ReportRunStatus.RUNNING, ReportRunStatus.SUCCEEDED], +) +def test_a_report_joining_a_run_answers_it_and_starts_no_call( + status: ReportRunStatus, +) -> None: + """An identical request ends on the same report and run, with no call.""" + store = FakeStore(found_report=_found_report(run_inserted=False, status=status)) caller = FakeCaller() created = _submit_report(service(store, caller=caller)) - (report,) = store.reports - assert report.baseline.reused is True - assert (report.baseline.simulation_id, report.baseline.simulation_run_id) == ( - REUSED.simulation_id, - REUSED.simulation_run_id, + assert caller.report_runs == [] + assert (store.recorded_calls, store.failed_runs) == ([], []) + assert created.model_dump() == { + "report_id": UUID(int=90), + "report_run_id": UUID(int=91), + "status": status, + "baseline_simulation_id": REUSED.simulation_id, + "baseline_simulation_run_id": REUSED.simulation_run_id, + "baseline_reused": True, + "reform_simulation_id": UUID(int=92), + "reform_simulation_run_id": UUID(int=93), + "reform_reused": True, + } + + +def test_a_side_whose_run_already_exists_is_named_and_answered_reused() -> None: + """A new report run naming a simulation run another request inserted.""" + store = FakeStore( + found_report=_found_report(run_inserted=True, status=ReportRunStatus.PENDING) ) - assert report.new_simulation_run_ids == (report.reform.simulation_run_id,) + caller = FakeCaller() + + created = _submit_report(service(store, caller=caller)) + payload = ReportExecutionInput.model_validate(caller.report_runs[0][1]) assert payload.baseline.simulation_execution_id == REUSED.simulation_run_id + assert payload.reform.simulation_execution_id == UUID(int=93) + assert store.recorded_calls == [(UUID(int=91), "fc-coordinator")] assert (created.baseline_reused, created.reform_reused) == (True, False) assert created.baseline_simulation_run_id == REUSED.simulation_run_id -def test_without_the_output_bucket_no_run_is_looked_for() -> None: +def test_the_same_policy_on_both_sides_names_one_simulation_run_twice() -> None: store = FakeStore() + caller = FakeCaller() - _submit_report(service(store, output_bucket=None)) + created = _submit_report( + service(store, caller=caller), + report_request(reform={"policy_id": None, "dynamic_id": None}), + ) - assert store.report_reads[0][1][2] is None + payload = ReportExecutionInput.model_validate(caller.report_runs[0][1]) + assert ( + payload.baseline.simulation_execution_id + == payload.reform.simulation_execution_id + == UUID(int=4) + ) + assert created.baseline_simulation_run_id == created.reform_simulation_run_id def test_the_report_stores_only_the_spm_settings_given() -> None: @@ -184,10 +255,9 @@ def test_the_report_stores_only_the_spm_settings_given() -> None: report_request(include_cliffs=False, spm={"scenario": "zero"}), ) - assert store.reports[0].inputs == { - "include_cliffs": False, - "spm": {"scenario": "zero"}, - } + (report,) = store.reports + assert report.inputs == {"spm": {"scenario": "zero"}} + assert report.definition.spm == {"scenario": "zero"} payload = ReportExecutionInput.model_validate(caller.report_runs[0][1]) assert payload.baseline.options == {"spm": {"scenario": "zero"}} @@ -195,16 +265,40 @@ def test_the_report_stores_only_the_spm_settings_given() -> None: def test_a_report_without_spm_settings_stores_none() -> None: store = FakeStore() caller = FakeCaller() - without_spm = {key: value for key, value in REPORT_BODY.items() if key != "spm"} + without_spm = { + **{key: value for key, value in REPORT_BODY.items() if key != "spm"}, + "include_cliffs": False, + } _submit_report( service(store, caller=caller), EconomyReportRequest.model_validate(without_spm), ) - assert store.reports[0].inputs == {"include_cliffs": True} + (report,) = store.reports + assert (report.inputs, report.definition.spm) == ({}, None) payload = ReportExecutionInput.model_validate(caller.report_runs[0][1]) - assert payload.reform.options == {"include_cliffs": True} + assert payload.reform.options == {} + + +def test_a_report_asking_for_cliffs_is_refused_before_anything_is_read() -> None: + """Interim answer A: a 422 until per-run cliff calculations exist (C1 · 39).""" + store = FakeStore() + caller = FakeCaller() + + with pytest.raises(EconomySubmissionUnprocessableError) as refusal: + _submit_report( + service(store, caller=caller), report_request(include_cliffs=True) + ) + + assert refusal.value.code == "cliffs_not_available" + ((reason),) = refusal.value.reasons + assert (reason.loc, reason.type) == ( + ("body", "include_cliffs"), + "cliffs_not_available", + ) + assert "cliff" in reason.msg + assert (store.report_reads, store.reports, caller.report_runs) == ([], [], []) @pytest.mark.parametrize( @@ -382,11 +476,13 @@ def test_a_call_modal_does_not_confirm_fails_the_report_run_and_names_it( (report,) = store.reports assert (unavailable.value.code, unavailable.value.record_id) == ( "modal_call_refused", - report.id, + report.report_id, ) + # Only the report run: once committed, another request's report run may + # have joined the simulation runs created with it. ((run_id, simulation_run_ids, message),) = store.failed_runs assert run_id == report.run_id - assert simulation_run_ids == report.new_simulation_run_ids + assert simulation_run_ids == () assert message.startswith("modal_call_refused: Modal did not accept the report") assert store.recorded_calls == [] @@ -399,7 +495,7 @@ def test_a_report_run_its_coordinator_claimed_meanwhile_is_answered_created() -> ) assert store.failed_runs == [] - assert created.report_id == store.reports[0].id + assert created.report_id == store.reports[0].report_id assert created.status is ReportRunStatus.PENDING @@ -414,7 +510,7 @@ def test_a_run_whose_state_cannot_be_written_is_answered_created_pending( created = _submit_report(service(store, caller=caller)) - assert created.report_id == store.reports[0].id + assert created.report_id == store.reports[0].report_id assert created.status is ReportRunStatus.PENDING @@ -428,7 +524,15 @@ def test_a_simulation_is_created_and_its_run_started_alone() -> None: assert (request.policyengine_version, request.year) == (POLICYENGINE_VERSION, 2026) assert choice == SimulationChoice(policy_id=POLICY_ID, dynamic_id=None) (simulation,) = store.simulations - assert (simulation.id, simulation.run_id) == (UUID(int=1), UUID(int=2)) + assert simulation.definition == EconomySimulationDefinition( + country="us", + choice=choice, + dataset_name=CATALOG.dataset.name, + region_code=CATALOG.region.code, + year=2026, + spm=None, + ) + assert (simulation.simulation_id, simulation.run_id) == (UUID(int=1), UUID(int=2)) assert simulation.population == CATALOG.population(2026) assert simulation.versions == VERSIONS ((_, payload, context, observed),) = caller.simulation_runs @@ -438,12 +542,37 @@ def test_a_simulation_is_created_and_its_run_started_alone() -> None: assert observed == OBSERVED assert store.recorded_calls == [(simulation.run_id, "fc-worker")] assert created.model_dump() == { - "simulation_id": simulation.id, + "simulation_id": simulation.simulation_id, "simulation_run_id": simulation.run_id, "status": SimulationStatus.PENDING, } +@pytest.mark.parametrize( + "status", [SimulationStatus.PENDING, SimulationStatus.SUCCEEDED] +) +def test_a_simulation_joining_its_run_answers_it_and_starts_no_call( + status: SimulationStatus, +) -> None: + joined = FoundEconomySimulation( + simulation_id=UUID(int=80), + simulation_inserted=False, + run=FoundSimulationRun(id=UUID(int=81), inserted=False, status=status), + ) + store = FakeStore(found_simulation=joined) + caller = FakeCaller() + + created = _submit_simulation(service(store, caller=caller)) + + assert caller.simulation_runs == [] + assert (store.recorded_calls, store.failed_runs) == ([], []) + assert created.model_dump() == { + "simulation_id": UUID(int=80), + "simulation_run_id": UUID(int=81), + "status": status, + } + + def test_a_simulation_run_modal_refuses_is_failed_and_the_simulation_named() -> None: store = FakeStore() @@ -455,7 +584,7 @@ def test_a_simulation_run_modal_refuses_is_failed_and_the_simulation_named() -> (simulation,) = store.simulations assert (unavailable.value.code, unavailable.value.record_id) == ( "modal_call_refused", - simulation.id, + simulation.simulation_id, ) assert store.failed_runs[0][0] == simulation.run_id assert store.failed_runs[0][2].startswith( diff --git a/projects/policyengine-simulation-entry/tests/test_household_report_reruns.py b/projects/policyengine-simulation-entry/tests/test_household_report_reruns.py index 5cab40adc..9bae4879d 100644 --- a/projects/policyengine-simulation-entry/tests/test_household_report_reruns.py +++ b/projects/policyengine-simulation-entry/tests/test_household_report_reruns.py @@ -16,7 +16,6 @@ from conftest import FakeBackend, make_settings from economy_rerun_fakes import ( REPORT_ID, - RUN_UNDER_WAY_ID, FakeRerunStore, rerun_service, ) @@ -61,6 +60,7 @@ from policyengine_simulation_persistence import ( EconomyRecordOutcomeUnknownError, EconomyRecordReferenceError, + FoundReportRun, HouseholdRerunSide, MissingPolicyParametersError, NewHouseholdReportRerun, @@ -68,7 +68,6 @@ ReportRunStatus, ReportSideError, RerunRecordDeletedError, - RunInProgressError, RunVersions, SideDefinition, SimulationChoice, @@ -157,7 +156,8 @@ def _side_request(calculation_id: UUID, parameters: dict) -> dict: } -# A household run is never reused, so a forced re-run creates the same runs. +# A household report without keys is always re-run as forced runs (interim +# answer B), so ``force`` changes nothing. @pytest.mark.parametrize("force", [False, True]) def test_a_household_report_is_rerun_as_new_runs_of_its_own_simulations( force, @@ -195,6 +195,7 @@ def test_a_household_report_is_rerun_as_new_runs_of_its_own_simulations( reform=HouseholdRerunSide( simulation_id=REFORM_SIMULATION_ID, simulation_run_id=REFORM_RUN_ID ), + forced=True, ) ] ((called_worker, payload, report_run_id, context),) = caller.calls @@ -397,21 +398,89 @@ def test_a_household_rerun_whose_inputs_cannot_be_read_answers_503() -> None: assert unavailable.value.code == "database_unavailable" -def test_a_household_report_with_a_run_under_way_is_not_rerun() -> None: - households = FakeHouseholdReportStore( - rerun_failure=RunInProgressError(RUN_UNDER_WAY_ID) +KEYED_HOUSEHOLD_REPORT = replace(STORED_HOUSEHOLD_REPORT, keyed=True) +JOINED_RUN = FoundReportRun( + id=UUID(int=90), + inserted=False, + status=ReportRunStatus.RUNNING, + baseline_simulation_run_id=UUID(int=91), + reform_simulation_run_id=UUID(int=92), +) + + +def test_a_keyed_household_reports_rerun_joins_its_run_and_starts_no_call() -> None: + """Answers 3 and 8: the run under way is answered as it is, so the 409 goes.""" + households = FakeHouseholdReportStore(joined_run=JOINED_RUN) + caller = FakeHouseholdReportCaller() + service, _, _ = _services( + KEYED_HOUSEHOLD_REPORT, households=households, caller=caller ) + + rerun = _rerun(service) + + (asked,) = households.report_reruns + assert asked.forced is False + assert rerun == HouseholdReportCreated( + report_id=REPORT_ID, + report_run_id=UUID(int=90), + status=ReportRunStatus.RUNNING, + year=2025, + baseline_simulation_id=BASELINE_SIMULATION_ID, + baseline_simulation_run_id=UUID(int=91), + reform_simulation_id=REFORM_SIMULATION_ID, + reform_simulation_run_id=UUID(int=92), + ) + assert (caller.calls, households.recorded_calls) == ([], []) + + +def test_a_keyed_household_reports_forced_rerun_is_an_extra_run() -> None: + """Answer 3: a forced run joins nothing and calculates both sides again.""" + households = FakeHouseholdReportStore(joined_run=JOINED_RUN) caller = FakeHouseholdReportCaller() - service, _, _ = _services(households=households, caller=caller) + service, _, _ = _services( + KEYED_HOUSEHOLD_REPORT, households=households, caller=caller + ) - with pytest.raises(EconomyRerunConflictError) as refused: + rerun = _rerun(service, force=True) + + (asked,) = households.report_reruns + assert asked.forced is True + assert (rerun.report_run_id, rerun.baseline_simulation_run_id) == ( + RUN_ID, + BASELINE_RUN_ID, + ) + ((_, _, report_run_id, _),) = caller.calls + assert report_run_id == RUN_ID + + +def test_a_keyed_household_rerun_is_calculated_on_the_side_runs_it_names() -> None: + """A side joins its simulation's run; Modal's refusal fails only the report run.""" + shared_baseline_run = UUID(int=77) + households = FakeHouseholdReportStore( + joined_side_runs={"baseline": shared_baseline_run} + ) + caller = FakeHouseholdReportCaller(failure=RuntimeError("Modal refused")) + service, _, _ = _services( + KEYED_HOUSEHOLD_REPORT, households=households, caller=caller + ) + + with pytest.raises(EconomySubmissionUnavailableError): _rerun(service) - assert (refused.value.code, refused.value.run_id) == ( - "run_in_progress", - RUN_UNDER_WAY_ID, + ((failed_run, failed_simulation_runs, _),) = households.failed_runs + assert (failed_run, failed_simulation_runs) == (RUN_ID, ()) + working = FakeHouseholdReportCaller() + service, _, _ = _services( + KEYED_HOUSEHOLD_REPORT, + households=FakeHouseholdReportStore( + joined_side_runs={"baseline": shared_baseline_run} + ), + caller=working, ) - assert caller.calls == [] + rerun = _rerun(service) + ((_, payload, _, _),) = working.calls + assert payload["baseline"]["calculation_id"] == str(shared_baseline_run) + assert rerun.baseline_simulation_run_id == shared_baseline_run def test_a_household_report_or_simulation_deleted_after_its_read_is_answered() -> None: diff --git a/projects/policyengine-simulation-entry/tests/test_household_report_submissions.py b/projects/policyengine-simulation-entry/tests/test_household_report_submissions.py index c2afb66f8..04d4ebc15 100644 --- a/projects/policyengine-simulation-entry/tests/test_household_report_submissions.py +++ b/projects/policyengine-simulation-entry/tests/test_household_report_submissions.py @@ -32,7 +32,7 @@ from policyengine_simulation_contract.household_report_execution import ( HouseholdReportRunCalculation, ) -from policyengine_simulation_entry import household_report_submissions +from policyengine_simulation_entry import household_report_calculations from policyengine_simulation_entry.economy_submission_errors import ( EconomySubmissionOutcomeUnknownError, EconomySubmissionRefusedError, @@ -54,10 +54,14 @@ from policyengine_simulation_persistence import ( EconomyRecordOutcomeUnknownError, EconomyRecordReferenceError, + FoundReportRun, + HouseholdReportDefinition, MissingPolicyParametersError, + ProposedSide, ReportRunStatus, ReportSideError, RunVersions, + SimulationChoice, StoredHousehold, UnknownCatalogVersionError, UnknownHouseholdError, @@ -124,28 +128,29 @@ def test_a_household_report_is_created_and_its_household_function_started(): "policyengine_version": worker.bundle.policyengine_version, } ] - (report,) = store.reports - assert (report.id, report.run_id, report.country) == (REPORT_ID, RUN_ID, "us") - assert report.label == "A larger child tax credit for one family" - assert report.description == "Raises the credit to $3,000" + # Answer 8: the report and its simulations are found or created by key. + (report,) = store.keyed_reports + assert report.definition == HouseholdReportDefinition( + country="us", + baseline=SimulationChoice(policy_id=None, dynamic_id=None), + reform=SimulationChoice(policy_id=POLICY_ID, dynamic_id=None), + household_id=HOUSEHOLD_ID, + year=2026, + ) + assert (report.report_id, report.run_id) == (REPORT_ID, RUN_ID) assert (report.tax_benefit_model_id, report.tax_benefit_model_version_id) == ( MODEL_ID, CATALOG_VERSION_ID, ) - assert (report.household_id, report.year) == (HOUSEHOLD_ID, 2026) - assert report.inputs == {} assert report.versions == RunVersions( country_package_version=worker.bundle.country_package_version, policyengine_version=worker.bundle.policyengine_version, ) - assert (report.baseline.simulation_id, report.baseline.policy_id) == ( - BASELINE_ID, - None, + assert report.baseline == ProposedSide( + simulation_id=BASELINE_ID, simulation_run_id=BASELINE_RUN_ID ) - assert report.reform is not None - assert (report.reform.simulation_run_id, report.reform.policy_id) == ( - REFORM_RUN_ID, - POLICY_ID, + assert report.reform == ProposedSide( + simulation_id=REFORM_ID, simulation_run_id=REFORM_RUN_ID ) ((called_worker, payload, report_run_id, context),) = caller.calls assert called_worker == worker @@ -174,9 +179,9 @@ def test_a_report_of_the_baseline_alone_creates_and_calculates_one_side(): None, ) assert store.reads[0]["policy_ids"] == {"baseline": POLICY_ID} - (report,) = store.reports - assert report.reform is None - assert report.simulation_run_ids == (BASELINE_RUN_ID,) + (report,) = store.keyed_reports + assert (report.reform, report.definition.reform) == (None, None) + assert report.definition.baseline.policy_id == POLICY_ID ((_, payload, _, _),) = caller.calls assert payload["reform"] is None assert payload["baseline"]["policy"] == {"parameters": REFORM} @@ -220,7 +225,64 @@ def test_the_default_workers_household_function_is_needed(failure, expected_type _submit(service) assert raised.value.code == code - assert (store.reads, store.reports) == ([], []) + assert (store.reads, store.keyed_reports) == ([], []) + + +def test_an_identical_request_joins_its_run_and_starts_no_call(): + """Answer 8: it ends on the report and run the first request created.""" + joined = FoundReportRun( + id=UUID(int=90), + inserted=False, + status=ReportRunStatus.SUCCEEDED, + baseline_simulation_run_id=UUID(int=91), + reform_simulation_run_id=UUID(int=92), + ) + store = FakeHouseholdReportStore(joined_run=joined) + caller = FakeHouseholdReportCaller() + + created = _submit(household_report_service(store, caller=caller)) + + assert created == HouseholdReportCreated( + report_id=REPORT_ID, + report_run_id=UUID(int=90), + status=ReportRunStatus.SUCCEEDED, + year=2026, + baseline_simulation_id=BASELINE_ID, + baseline_simulation_run_id=UUID(int=91), + reform_simulation_id=REFORM_ID, + reform_simulation_run_id=UUID(int=92), + ) + assert (caller.calls, store.recorded_calls, store.failed_runs) == ([], [], []) + + +def test_a_created_run_is_calculated_on_the_side_runs_it_names(): + """A side's run another report run created is the side's calculation ID.""" + shared_baseline_run = UUID(int=77) + store = FakeHouseholdReportStore(joined_side_runs={"baseline": shared_baseline_run}) + caller = FakeHouseholdReportCaller() + + created = _submit(household_report_service(store, caller=caller)) + + ((_, payload, report_run_id, _),) = caller.calls + assert report_run_id == RUN_ID + assert payload["baseline"]["calculation_id"] == str(shared_baseline_run) + assert payload["reform"]["calculation_id"] == str(REFORM_RUN_ID) + assert created.baseline_simulation_run_id == shared_baseline_run + + +def test_a_policy_compared_with_itself_is_calculated_on_one_run(): + """Its two sides are one simulation, so the store names one run twice.""" + store = FakeHouseholdReportStore(joined_side_runs={"reform": BASELINE_RUN_ID}) + caller = FakeHouseholdReportCaller() + + _submit( + household_report_service(store, caller=caller), + household_report_request(reform={"policy_id": None}), + ) + + ((_, payload, _, _),) = caller.calls + assert payload["baseline"] == payload["reform"] + HouseholdReportRunCalculation.model_validate(payload) @pytest.mark.parametrize( @@ -264,7 +326,7 @@ def test_each_missing_input_is_refused_before_anything_is_written( _submit(household_report_service(store, caller=caller)) assert (raised.value.code, raised.value.detail) == (code, detail) - assert (store.reports, caller.calls) == ([], []) + assert (store.keyed_reports, caller.calls) == ([], []) def test_a_policy_setting_missing_parameters_is_refused_on_its_side(): @@ -283,7 +345,7 @@ def test_a_policy_setting_missing_parameters_is_refused_on_its_side(): ("body", "baseline", "policy_id", "gov.b"), ] assert {reason.type for reason in raised.value.reasons} == {"missing_parameter"} - assert store.reports == [] + assert store.keyed_reports == [] @pytest.mark.parametrize( @@ -308,7 +370,7 @@ def test_a_household_that_cannot_be_calculated_is_refused(store, reason_type): assert (reason.loc, reason.type) == (("body", "household_id"), reason_type) # The detail is the service's own words, never the document's contents. assert "not a list of people" not in reason.msg - assert (store.reports, caller.calls) == ([], []) + assert (store.keyed_reports, caller.calls) == ([], []) def test_a_household_the_contract_refuses_is_located_on_the_household(): @@ -328,7 +390,7 @@ def test_a_household_the_contract_refuses_is_located_on_the_household(): reason.loc[:3] == ("body", "household_id", "household") for reason in raised.value.reasons ) - assert store.reports == [] + assert store.keyed_reports == [] @pytest.mark.parametrize( @@ -384,9 +446,8 @@ def test_a_create_the_database_cannot_take_is_unavailable(): ], ids=["refused", "not-confirmed-in-time"], ) -def test_a_call_modal_does_not_confirm_fails_the_report_run_and_its_runs( - caller, error_type -): +def test_a_call_modal_does_not_confirm_fails_only_the_report_run(caller, error_type): + """Its simulation runs may be another report run's (answer 8).""" store = FakeHouseholdReportStore() with pytest.raises(EconomySubmissionUnavailableError) as raised: @@ -397,7 +458,7 @@ def test_a_call_modal_does_not_confirm_fails_the_report_run_and_its_runs( assert store.failed_runs == [ ( RUN_ID, - (BASELINE_RUN_ID, REFORM_RUN_ID), + (), "modal_call_refused: Modal did not accept the report's call " f"({error_type}).", ) @@ -533,4 +594,4 @@ def test_a_refusal_of_the_missing_variables_option_is_the_services_fault(): HouseholdExecutionRequest.model_validate(refused_request) with pytest.raises(HouseholdReportBuildError, match="add_missing_variables"): - household_report_submissions._contract_reasons(refused.value, "baseline") + household_report_calculations._contract_reasons(refused.value, "baseline") diff --git a/projects/policyengine-simulation-entry/tests/test_openapi.py b/projects/policyengine-simulation-entry/tests/test_openapi.py index 248e2f478..14cc01a94 100644 --- a/projects/policyengine-simulation-entry/tests/test_openapi.py +++ b/projects/policyengine-simulation-entry/tests/test_openapi.py @@ -394,6 +394,9 @@ def test_economy_routes_declare_every_answer(): record = path.removeprefix("/").removesuffix("s") assert f"{record}_id" in responses["503"]["description"] assert "nothing was written" in responses["400"]["description"] + # A create answers the record and run it ended on, joined or created. + assert "joined" in responses["201"]["description"] + assert "found or created" in responses["503"]["description"] error_properties = spec["components"]["schemas"]["EconomyError"]["properties"] assert {"code", "detail", "report_id", "simulation_id", "run_id"} == set( error_properties @@ -458,16 +461,28 @@ def test_rerun_routes_declare_every_answer(): for status_code in ("400", "404", "409", "500", "503"): assert _response_schema(responses[status_code]) == error assert _response_schema(responses["422"]) == unprocessable - assert "run_id" in responses["409"]["description"] assert "run_id" in responses["503"]["description"] + # Both answer the run they ended on, created or joined. + assert "joined" in responses["201"]["description"] + # No re-run is refused while a run is under way: an unforced one joins + # it, and a forced one is an extra run (C1 · 24's answers 3 and 8). + for path in ("/reports/{report_id}/runs", "/simulations/{simulation_id}/runs"): + conflict = _responses(spec, "post", path)["409"] + assert "run_in_progress" not in conflict["description"] + assert "rerun_not_supported" in conflict["description"] codes = set( spec["components"]["schemas"]["EconomyError"]["properties"]["code"]["enum"] ) - assert {"run_in_progress", "rerun_not_supported"} <= codes + assert "rerun_not_supported" in codes + assert "run_in_progress" not in codes # A household report's re-run names its household's own codes. report_answers = _responses(spec, "post", "/reports/{report_id}/runs") assert "unknown_household" in report_answers["400"]["description"] assert "household_not_calculable" in report_answers["422"]["description"] + # A report stored asking for cliffs is refused until they exist. + assert "cliffs_not_available" in report_answers["422"]["description"] + simulation_answers = _responses(spec, "post", "/simulations/{simulation_id}/runs") + assert "cliffs_not_available" not in simulation_answers["422"]["description"] report_rerun = spec["components"]["schemas"]["ReportRerunRequest"] assert set(report_rerun["properties"]) == {"force"} assert ( @@ -518,6 +533,21 @@ def test_economy_requests_name_no_version_and_no_record_id(): assert "spm" not in schemas["EconomyReportRequest"].get("required", []) +def test_a_reports_label_and_description_are_optional_and_never_stored(): + """Answer 6: each user's saved report holds them, in the Public API.""" + schemas = create_app().openapi()["components"]["schemas"] + + for name in ( + "EconomyReportRequest", + "BudgetWindowReportRequest", + "HouseholdReportRequest", + ): + request = schemas[name] + assert {"label", "description"} <= set(request["properties"]), name + assert "label" not in request.get("required", []), name + assert "not stored" in request["properties"]["label"]["description"], name + + def test_a_report_request_is_an_economy_report_a_budget_window_or_a_household(): spec = create_app().openapi() body = spec["paths"]["/reports"]["post"]["requestBody"]["content"][ @@ -570,7 +600,6 @@ def test_a_household_report_names_its_household_and_each_sides_policy(): assert set(household_report["required"]) == { "country", "report_type", - "label", "household_id", "baseline", }