From 731a2abfeb00d907aa5771e3f7f57d0025d2d599 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:12:40 +0400 Subject: [PATCH 001/107] Test sim's models of the Public API's definition keys and run indexes (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Public API's next revision (C1 · 25) gives simulations and reports a key_version and definition_key, unique together, reports a dataset_independent_key, and both run tables a forced marker and a partial unique index allowing one unfailed, unforced run per definition and version set. Find-or-create names these as its conflict targets, so the models must declare them under the same names and conditions. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_tables.py | 59 ++++++++++++++++++- 1 file changed, 58 insertions(+), 1 deletion(-) diff --git a/libs/policyengine-simulation-persistence/tests/test_tables.py b/libs/policyengine-simulation-persistence/tests/test_tables.py index 2d7ade37f..c2ac9254c 100644 --- a/libs/policyengine-simulation-persistence/tests/test_tables.py +++ b/libs/policyengine-simulation-persistence/tests/test_tables.py @@ -12,10 +12,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 +212,59 @@ 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 + assert _indexed_columns( + reports, "ix_reports_key_version_dataset_independent_key" + ) == ("key_version", "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 From d95cae5a3544947ce2d65260461dc7d9fbedae61 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:13:31 +0400 Subject: [PATCH 002/107] Model the Public API's definition keys, forced markers and run indexes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sim's copies of the columns C1 · 25's revision adds: key_version and definition_key on simulations and reports (with dataset_independent_key on reports), each nullable, with the Public API's checks, the unique constraint find-or-create targets and the dataset-independent index; forced on simulation_runs and report_runs, false unless a forced re-run inserts it; and the partial unique indexes allowing one unfailed, unforced run per definition and version set. The models now match the Public API's tables at revision 94dc43079186. Co-Authored-By: Claude Opus 5.5 --- .../tables.py | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) 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..bd19d23e4 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", @@ -284,6 +335,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 +389,24 @@ 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. + Index( + "ix_reports_key_version_dataset_independent_key", + "key_version", + "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 +439,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 +486,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", @@ -511,6 +595,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 +658,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", From f79fa9a7da9ea362c4c76f79cc4a20130892f88c Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:14:40 +0400 Subject: [PATCH 003/107] Test the definition keys of economy reports (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A key is the lowercase SHA-256 of a definition's canonical JSON: keys sorted, no spaces, UTF-8, UUIDs as lowercase strings, missing values null, and no value JSON can't write exactly. An economy report's object names its key version, record type, country, each side's policy and dynamic, dataset name, region code, year, window size and options, as C1 · 24's answer 1a sets out; the proposal's worked example gives three reports' keys. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_definition_keys.py | 123 ++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 libs/policyengine-simulation-persistence/tests/test_definition_keys.py 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..6d240a363 --- /dev/null +++ b/libs/policyengine-simulation-persistence/tests/test_definition_keys.py @@ -0,0 +1,123 @@ +"""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, + SimulationChoice, + canonical_json, + definition_key, +) + +REFORM_POLICY_ID = UUID("11111111-2222-3333-4444-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" + + +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, + options={"include_cliffs": False}, + ) + return replace(report, **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_the_proposals_worked_example_reports_have_its_keys() -> None: + """N, N2 and L of the proposal's worked example, by their first 16 digits.""" + report_n = _report_n() + report_n2 = _report_n(options={"include_cliffs": True}) + report_l = _report_n(dataset_name=LOCAL_AREA_DATASET, options={}) + + assert report_n.definition_key[:16] == "4bb1299756cb0a89" + assert report_n2.definition_key[:16] == "bb74ac904ed3a1c8" + assert report_l.definition_key[:16] == "907455a2702b0559" + + +def test_a_report_key_object_names_its_version_and_record() -> None: + assert KEY_VERSION == 1 + assert _report_n().key_object() == { + "baseline": {"dynamic_id": None, "policy_id": None}, + "budget_window_size": None, + "country": "uk", + "dataset": NATIONAL_DATASET, + "key_version": 1, + "options": {"include_cliffs": False}, + "record": "report", + "reform": {"dynamic_id": None, "policy_id": REFORM_POLICY_ID}, + "region": "uk", + "report_type": "economy", + "year": 2026, + } + + +def test_each_part_of_a_report_definition_changes_its_key() -> None: + dynamic_id = UUID("99999999-8888-7777-6666-555555555555") + 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(options={"include_cliffs": True}), + _report_n(options={"include_cliffs": False, "spm": {"scenario": "low"}}), + _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) From 7608e4f953820caececca082d3ea4b4987727768 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:15:22 +0400 Subject: [PATCH 004/107] Build the definition keys of economy reports MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit definition_keys hashes a definition's canonical JSON with SHA-256, the format key_version 1 names, and builds an economy report's key object: each side's policy and dynamic, the dataset name, region code and year both sides share, the window size and the stored options. Names and codes, not catalog IDs, so a report keeps its key across releases. The dataset-independent key waits for C1 · 24's revised answer 1a. Co-Authored-By: Claude Opus 5.5 --- .../__init__.py | 10 ++ .../definition_keys.py | 109 ++++++++++++++++++ 2 files changed, 119 insertions(+) create mode 100644 libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/definition_keys.py 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..b47e1dbfc 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py @@ -13,6 +13,12 @@ WindowYearRuns, insert_budget_window_report, ) +from policyengine_simulation_persistence.definition_keys import ( + KEY_VERSION, + EconomyReportDefinition, + canonical_json, + definition_key, +) from policyengine_simulation_persistence.economy_rerun_records import ( HouseholdRerunSide, NewHouseholdReportRerun, @@ -148,6 +154,7 @@ __all__ = [ "HOUSEHOLD_REPORT_TYPE", + "KEY_VERSION", "LATEST_YEAR", "MAX_BUDGET_WINDOW_YEARS", "SERVICE_TABLE_PRIVILEGES", @@ -160,6 +167,7 @@ "EconomyPopulation", "EconomyRecordOutcomeUnknownError", "EconomyRecordReferenceError", + "EconomyReportDefinition", "EconomyReportInputs", "EconomyReportState", "EconomyRequest", @@ -222,8 +230,10 @@ "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", 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..b0d7926dd --- /dev/null +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/definition_keys.py @@ -0,0 +1,109 @@ +"""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. +""" + +from __future__ import annotations + +import hashlib +import json +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any, Final +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 type, as the key and the Public API name it. +_ECONOMY: Final = "economy" + + +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} + + +@dataclass(frozen=True) +class EconomyReportDefinition: + """What identifies an economy report or a budget window (answer 1a). + + Each side's stored policy and dynamic (dynamics by ID, answer 1b), the + dataset name, region code and year both sides share, the window's size + (None for a single year) and the options as ``reports.inputs`` stores + them. 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 + options: Mapping[str, Any] + + 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, + "options": dict(self.options), + } + + @property + def definition_key(self) -> str: + """The report's ``definition_key``.""" + return definition_key(self.key_object()) From 0909244c6b4e7644f187615456f8bcf96700c9a7 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:18:57 +0400 Subject: [PATCH 005/107] Test finding a shared simulation, report or run, or inserting it (failing) Each lookup inserts against the Public API's unique index for the row's definition or version set and, when that does nothing, reads the row that won: a simulation or report by its key, a simulation run by simulation, year, catalog version and versions, a report run by report and versions. A failed run is no longer joined, a forced run is never joined and never takes a run's place, a transaction inserting a run another has inserted waits for it and joins it, and a run that fails between the insert and the read is inserted again. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_shared_rows.py | 430 ++++++++++++++++++ 1 file changed, 430 insertions(+) create mode 100644 libs/policyengine-simulation-persistence/tests/test_shared_rows.py 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..1028d4f19 --- /dev/null +++ b/libs/policyengine-simulation-persistence/tests/test_shared_rows.py @@ -0,0 +1,430 @@ +"""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 +import time +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 ( + CURRENT_LAW, + LATER_VERSIONS, + VERSIONS, + EconomyCatalog, + insert_economy_catalog, +) +from policyengine_simulation_persistence import ( + KEY_VERSION, + ReportRunStatus, + ReportRunTrigger, + RunVersions, + SimulationStatus, + SimulationType, + create_simulation_engine, + 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 collections.abc import Iterator + + from sqlalchemy import Connection, Engine + +pytestmark = pytest.mark.public_api_schema + +# How long a test waits for the other transaction to reach its insert. +LOCK_WAIT_TIMEOUT_SECONDS = 10.0 + + +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, + }, + ) + + +@pytest.fixture +def committed_engine(public_api_database_url) -> Iterator[Engine]: + 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) + + +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.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) + + +def _wait_for_a_statement_waiting_on_a_lock(engine: Engine) -> None: + """Return once another backend of this database waits for a lock.""" + deadline = time.monotonic() + LOCK_WAIT_TIMEOUT_SECONDS + with engine.connect() as connection: + while time.monotonic() < deadline: + waiting = connection.execute( + text( + "SELECT count(*) FROM pg_stat_activity " + "WHERE datname = current_database() AND wait_event_type = 'Lock'" + ) + ).scalar_one() + connection.rollback() + if waiting: + return + time.sleep(0.05) + msg = "the other transaction never waited for the first one's row" + raise AssertionError(msg) + + +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) + ) + first_has_inserted.set() + _wait_for_a_statement_waiting_on_a_lock(committed_engine) + + 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) + ) + + threads = [ + threading.Thread(target=insert_then_commit_once_the_other_waits), + threading.Thread(target=insert_once_the_first_has), + ] + for thread in threads: + thread.start() + for thread in threads: + thread.join(LOCK_WAIT_TIMEOUT_SECONDS * 2) + + 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 From d8a80b98e69b68fc58f119a974e1de0b75e56ebc Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:20:01 +0400 Subject: [PATCH 006/107] Find a shared simulation, report or run, or insert it shared_rows' four lookups each insert with ON CONFLICT DO NOTHING against the Public API's unique index for the row (a simulation's or report's definition key; a run's simulation or report, catalog version and versions, among runs neither failed nor forced) and, when that does nothing, read the row that won. A run that fails between the two is inserted again, up to three times. The partial indexes' predicates come from the models, so the conflict targets match the indexes. Forced runs and a budget window's year runs are never looked up. Co-Authored-By: Claude Opus 5.5 --- .../__init__.py | 16 ++ .../shared_rows.py | 248 ++++++++++++++++++ 2 files changed, 264 insertions(+) create mode 100644 libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/shared_rows.py 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 b47e1dbfc..816c8532f 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py @@ -134,6 +134,15 @@ read_dynamic_reform, read_policy_reform, ) +from policyengine_simulation_persistence.shared_rows import ( + FoundReportRun, + FoundRow, + SharedRowNotSettledError, + find_or_insert_report, + find_or_insert_report_run, + find_or_insert_simulation, + find_or_insert_simulation_run, +) from policyengine_simulation_persistence.tables import ( LATEST_YEAR, MAX_BUDGET_WINDOW_YEARS, @@ -174,6 +183,8 @@ "EconomyRunStore", "EconomySimulationInputs", "EconomySimulationState", + "FoundReportRun", + "FoundRow", "HouseholdCalculationInputs", "HouseholdJobRecord", "HouseholdJobReferenceError", @@ -209,6 +220,7 @@ "RunInProgressError", "RunReuse", "RunVersions", + "SharedRowNotSettledError", "SideDefinition", "SideRefusal", "SimulationChoice", @@ -237,6 +249,10 @@ "fail_unstarted_household_job", "fail_unstarted_report_run", "fail_unstarted_simulation_run", + "find_or_insert_report", + "find_or_insert_report_run", + "find_or_insert_simulation", + "find_or_insert_simulation_run", "find_reusable_run", "find_reusable_run_of", "household_jobs", 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..64fb12411 --- /dev/null +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/shared_rows.py @@ -0,0 +1,248 @@ +"""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. + +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, + 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 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 _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] +) -> FoundRow: + """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, ()) + return FoundRow(id=row.id, inserted=inserted) + + +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 _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) From e84e0964009ca2940e5cffaf640d899b66f6fa48 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:21:42 +0400 Subject: [PATCH 007/107] Test forced re-runs as extra runs, marked and never refused (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's answer 3: a forced re-run is an extra run. Its report run, or each year's report run of a budget window, and the simulation runs it calculates are marked forced, so the Public API's one-unfailed-run indexes leave them out: a forced re-run is inserted beside a pending, running or succeeded run on the same versions, and is never refused while one is under way. A forced report re-run calculates both sides. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_economy_reruns.py | 78 +++++++++++++++++++ .../tests/test_economy_window_reruns.py | 36 +++++++++ 2 files changed, 114 insertions(+) diff --git a/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py b/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py index 53babd5aa..69dc69ca5 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py @@ -39,6 +39,7 @@ insert_simulation_run, ) from policyengine_simulation_persistence import ( + EconomyPopulation, EconomyRecordReferenceError, EconomyRequest, EconomyRunStore, @@ -900,3 +901,80 @@ 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(), + reused=False, + ), + reform=RerunSide( + simulation_id=stored.reform.simulation_id, + simulation_run_id=uuid4(), + reused=False, + ), + 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, + ReportRunTrigger.MANUAL, + 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_forced_rerun_calculates_both_sides() -> None: + """A forced re-run never names a run it didn't create (answer 3).""" + reused = RerunSide(simulation_id=uuid4(), simulation_run_id=uuid4(), reused=True) + created = RerunSide(simulation_id=uuid4(), simulation_run_id=uuid4(), reused=False) + + with pytest.raises(ValueError, match="forced"): + NewReportRerun( + report_id=uuid4(), + run_id=uuid4(), + population=EconomyPopulation( + tax_benefit_model_version_id=uuid4(), + region_id=uuid4(), + dataset_id=uuid4(), + year=2026, + ), + versions=VERSIONS, + baseline=reused, + reform=created, + forced=True, + ) 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..6f5c27e06 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_window_reruns.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_window_reruns.py @@ -606,3 +606,39 @@ def test_a_window_rerun_is_refused_while_a_year_still_runs_after_its_window_ende insert_window_rerun(connection, _window_rerun_of(stored, later)) assert refused.value.run_id == still_running + + +@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) + stored = _stored_window(connection, economy, window_status=status) + rerun = replace( + _window_rerun_of(stored, economy, recalculate=True), versions=VERSIONS + ) + act_as_the_service(connection) + + 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 (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) From 5bbb7ddf554ca610f35141a391039ebdd9d0078e Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:23:27 +0400 Subject: [PATCH 008/107] Create forced re-runs as extra runs, marked forced MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A forced report re-run's report run and new simulation runs, and a recalculating budget-window re-run's year runs and simulation runs, are inserted with forced set, so the Public API's one-unfailed-run indexes leave them out. Such a re-run takes no re-run lock and is never refused while a run is under way; a forced report re-run reuses no run. Unforced re-runs are unchanged until C1 · 24's answers 4 and 8. Co-Authored-By: Claude Opus 5.5 --- .../budget_window_records.py | 6 ++- .../economy_rerun_records.py | 42 +++++++++++++++---- .../economy_run_records.py | 7 +++- 3 files changed, 43 insertions(+), 12 deletions(-) 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..18b4ac63d 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 @@ -227,18 +227,19 @@ def insert_budget_window_report( ) -def year_run_row( +def year_run_row( # noqa: PLR0913 # the year, then each column it doesn't name window_year: WindowYearRuns, *, report_id: UUID, window_run_id: UUID, versions: RunVersions, trigger: ReportRunTrigger, + forced: bool = False, ) -> 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. + which, and ``forced`` marks a forced re-run's. """ return { "id": window_year.report_run_id, @@ -252,4 +253,5 @@ def year_run_row( "status": ReportRunStatus.PENDING, "trigger": trigger, "modal_call_id": None, + "forced": forced, } 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..bc0704b57 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 @@ -25,6 +25,12 @@ 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. +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``). """ @@ -175,7 +181,11 @@ class RerunSide: @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. + + ``forced`` makes it a forced re-run's extra run, which calculates both + sides. + """ report_id: UUID run_id: UUID @@ -183,6 +193,13 @@ class NewReportRerun: versions: RunVersions baseline: RerunSide reform: RerunSide + forced: bool = False + + def __post_init__(self) -> None: + """Refuse a forced re-run naming a run it doesn't create.""" + if self.forced and (self.baseline.reused or self.reform.reused): + msg = "a forced re-run calculates both sides, reusing no run" + raise ValueError(msg) @property def new_simulation_run_ids(self) -> tuple[UUID, ...]: @@ -508,15 +525,17 @@ def _run_under_way( 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 + Unless the re-run is forced, take the report's re-run lock first, and + raise RunInProgressError, creating nothing, when the report has a run + pending or running; a forced re-run's runs are marked forced. 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) + if not rerun.forced: + lock_reruns_of(connection, rerun.report_id) + _refuse_while_report_runs(connection, rerun.report_id) with _record_checked(report_runs.c.report_id), references_checked(): for side in (rerun.baseline, rerun.reform): if not side.reused: @@ -526,6 +545,7 @@ def insert_report_rerun(connection: Connection, rerun: NewReportRerun) -> None: simulation_id=side.simulation_id, population=rerun.population, versions=rerun.versions, + forced=rerun.forced, ) connection.execute( insert(report_runs).values( @@ -540,6 +560,7 @@ def insert_report_rerun(connection: Connection, rerun: NewReportRerun) -> None: status=ReportRunStatus.PENDING, trigger=ReportRunTrigger.MANUAL, modal_call_id=None, + forced=rerun.forced, ) ) @@ -551,10 +572,13 @@ def insert_window_rerun(connection: Connection, rerun: NewWindowRerun) -> None: 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. + ``insert_report_rerun`` does. A re-run that recalculates is a forced + one: no lock or refusal, and its year runs and simulation runs are + marked forced. """ - lock_reruns_of(connection, rerun.report_id) - _refuse_while_report_runs(connection, rerun.report_id) + if not rerun.recalculate: + lock_reruns_of(connection, rerun.report_id) + _refuse_while_report_runs(connection, rerun.report_id) population = rerun.population with ( _record_checked(budget_window_runs.c.report_id, report_runs.c.report_id), @@ -581,6 +605,7 @@ def insert_window_rerun(connection: Connection, rerun: NewWindowRerun) -> None: simulation_id=side.simulation_id, population=rerun.population_in(window_year.year), versions=rerun.versions, + forced=rerun.recalculate, ) connection.execute( insert(report_runs), @@ -591,6 +616,7 @@ def insert_window_rerun(connection: Connection, rerun: NewWindowRerun) -> None: window_run_id=rerun.window_run_id, versions=rerun.versions, trigger=ReportRunTrigger.MANUAL, + forced=rerun.recalculate, ) for window_year in rerun.years ], 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..66e327fcc 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 @@ -550,18 +550,20 @@ def insert_simulation_with_run( # noqa: PLR0913 # the simulation's and its run ) -def insert_simulation_run( +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, + forced: bool = False, ) -> 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. + on, which a re-run's may differ from its simulation's. ``forced`` marks + a forced re-run's run, which nothing joins. """ connection.execute( insert(simulation_runs).values( @@ -575,6 +577,7 @@ def insert_simulation_run( region_id=population.region_id, status=SimulationStatus.PENDING, modal_call_id=None, + forced=forced, ) ) From ca1469284c97ceff0f97c17863616f0b12c02181 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:23:27 +0400 Subject: [PATCH 009/107] Test that the service marks a forced report re-run forced (failing) Co-Authored-By: Claude Opus 5.5 --- .../policyengine-simulation-entry/tests/test_economy_reruns.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py index eb4efe3e7..a13b4e314 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py @@ -170,6 +170,8 @@ def test_a_forced_rerun_recalculates_both_simulations() -> None: assert store.rerun_reads[0][1][2] is None (created,) = store.report_reruns + # An extra run, marked forced, which nothing joins (answer 3). + assert created.forced is True assert (created.baseline.reused, created.reform.reused) == (False, False) assert created.new_simulation_run_ids == (UUID(int=2), UUID(int=3)) assert created.baseline.simulation_id == BASELINE_SIMULATION_ID From 2c58d9a938428098785ceb722c5edc53400df9c2 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:24:08 +0400 Subject: [PATCH 010/107] Mark a forced report re-run forced The service passes a re-run's force to its new run, which the store then inserts as an extra run marked forced, never refused while a run is under way. A budget window's recalculate already did. The README and the module's steps say so. Co-Authored-By: Claude Opus 5.5 --- projects/policyengine-simulation-entry/README.md | 9 ++++++--- .../src/policyengine_simulation_entry/economy_reruns.py | 5 ++++- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index 1b8fce00b..af16cb4bb 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -236,12 +236,15 @@ Its body is required: `{}` or `{"force": false}` re-runs the report, and 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 +both again, as an extra run: the new report run and both simulation runs +are marked `forced`, so nothing joins them, and a forced re-run is never +refused while a run is under way. The new report run's trigger is `manual`. 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 +`manual`, with `recalculate` set by `force`, and a report run per year; +a forced one's year runs and new simulation runs are marked `forced`. 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 @@ -265,7 +268,7 @@ 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 +run), unless the re-run is forced; 409 `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, 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..9d1d8ac74 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 @@ -18,7 +18,9 @@ 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``); + run pending or running (409 ``run_in_progress``). A forced re-run is + never refused: its runs are marked forced, an extra run that nothing + joins (C1 · 24's answer 3); 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. @@ -309,6 +311,7 @@ async def rerun_report( reform=self._rerun_side( stored.reform.simulation_id, inputs.reform.reusable_run ), + forced=request.force, ) calculation = report_run_calculation( worker, From e27b64cdd53696662eef4e9ea57d556a5aeab001 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:25:28 +0400 Subject: [PATCH 011/107] Test the staging economy check forcing a new run (failing) Once identical requests join existing runs, the check's report request ends on a run a check on the same versions already calculated. The check then forces a new run with POST /reports/{report_id}/runs and {"force": true}, asked once, and waits for that run; a refused or unanswered re-run, or one naming no run, fails the check before any read. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_staging_economy_check.py | 109 +++++++++++++++--- 1 file changed, 93 insertions(+), 16 deletions(-) diff --git a/projects/policyengine-simulation-entry/tests/test_staging_economy_check.py b/projects/policyengine-simulation-entry/tests/test_staging_economy_check.py index 097ab1974..c3ab3d03f 100644 --- a/projects/policyengine-simulation-entry/tests/test_staging_economy_check.py +++ b/projects/policyengine-simulation-entry/tests/test_staging_economy_check.py @@ -1,13 +1,15 @@ """The staging economy check, run on every staging deploy. -``simulation-staging-economy-check.sh`` creates a small economy report, -current law against current law for Wales in 2026, through the deployed -candidate's ``POST /reports``, then follows its run through -``GET /reports/{report_id}`` and requires it to succeed. It runs after the -v2 manifest's default has moved to the release's worker, so the report runs -on the release's own coordinator. Once a .py version's first check has -succeeded, later checks on it reuse those simulation runs, and check the -coordinator's use of their stored output. +``simulation-staging-economy-check.sh`` finds or creates a small economy +report, current law against current law for Wales in 2026, through the +deployed candidate's ``POST /reports``, then forces a new run of it with +``POST /reports/{report_id}/runs``, follows that run through +``GET /reports/{report_id}`` and requires it to succeed. An identical +request ends on the report's existing run (C1 · 24), which a check on the +same versions has already calculated, so only a forced run, which nothing +joins, calculates on every deploy (answer 3). It runs after the v2 +manifest's default has moved to the release's worker, so the run calculates +on the release's own coordinator and workers. """ from __future__ import annotations @@ -28,12 +30,15 @@ CHECK_JOB = "staging_economy_check" BASE_URL = "https://policyengine-simulation-entry-staging-s-123.a.run.app" REPORT_ID = "00000000-0000-4000-8000-0000000000e1" +# The forced run the check waits for, and the run the create ended on. REPORT_RUN_ID = "00000000-0000-4000-8000-0000000000e2" OLDER_RUN_ID = "00000000-0000-4000-8000-0000000000e3" +FOUND_RUN_ID = "00000000-0000-4000-8000-0000000000e4" ACCESS_TOKEN = "test-access-token" -# The fake curl answers the token request, the submission and each poll in -# turn, and keeps each request body it was sent on standard input. +# The fake curl answers the token request, the submission, the forced re-run +# and each poll in turn, and keeps each request body it was sent on standard +# input. FAKE_CURL = r""" output="" url="" @@ -54,6 +59,14 @@ cat > "${FAKE_STATE}/body-${calls}.json" fi case "${method} ${url}" in + "POST ${FAKE_BASE_URL}/reports/"*"/runs") + echo "${url}" > "${FAKE_STATE}/rerun-url" + if [[ "${FAKE_RERUN_STATUS}" == "TRANSPORT" ]]; then + exit 28 + fi + printf '%s' "${FAKE_RERUN_BODY}" > "${output}" + printf '%s' "${FAKE_RERUN_STATUS}" + ;; "POST https://issuer.example/oauth/token") printf '{"access_token": "%s"}' "${FAKE_ACCESS_TOKEN}" > "${output}" printf '200' @@ -82,8 +95,8 @@ """ CREATED = { "report_id": REPORT_ID, - "report_run_id": REPORT_RUN_ID, - "status": "pending", + "report_run_id": FOUND_RUN_ID, + "status": "succeeded", "baseline_simulation_id": "00000000-0000-4000-8000-0000000000f1", "baseline_simulation_run_id": "00000000-0000-4000-8000-0000000000f2", "baseline_reused": True, @@ -91,6 +104,14 @@ "reform_simulation_run_id": "00000000-0000-4000-8000-0000000000f4", "reform_reused": False, } +FORCED = { + **CREATED, + "report_run_id": REPORT_RUN_ID, + "status": "pending", + "baseline_simulation_run_id": "00000000-0000-4000-8000-0000000000f5", + "baseline_reused": False, + "reform_simulation_run_id": "00000000-0000-4000-8000-0000000000f6", +} def _report(status: str, *, run_id: str = REPORT_RUN_ID, **run_fields) -> str: @@ -140,13 +161,15 @@ def _run(fakes, tmp_path, answers: list[str], **overrides): "FAKE_ACCESS_TOKEN": ACCESS_TOKEN, "FAKE_SUBMISSION_STATUS": "201", "FAKE_SUBMISSION_BODY": json.dumps(CREATED), + "FAKE_RERUN_STATUS": "201", + "FAKE_RERUN_BODY": json.dumps(FORCED), **overrides, } result = run_script(CHECK_SCRIPT, BASE_URL + "/", env=fakes.env(**environment)) return result, state -def test_the_check_creates_a_small_report_and_waits_for_its_run_to_succeed( +def test_the_check_forces_a_new_run_of_the_small_report_and_waits_for_it( fakes, tmp_path ): result, state = _run( @@ -161,7 +184,8 @@ def test_the_check_creates_a_small_report_and_waits_for_its_run_to_succeed( assert result.returncode == 0, result.stderr assert REPORT_ID in result.stdout - assert "reused" in result.stdout + assert FOUND_RUN_ID in result.stdout + assert f"forced run {REPORT_RUN_ID}" in result.stdout token_request = json.loads((state / "body-1.json").read_text(encoding="utf-8")) assert token_request["grant_type"] == "client_credentials" submission = json.loads((state / "body-2.json").read_text(encoding="utf-8")) @@ -175,6 +199,11 @@ def test_the_check_creates_a_small_report_and_waits_for_its_run_to_succeed( "reform": {"policy_id": None, "dynamic_id": None}, "include_cliffs": False, } + forced_rerun = json.loads((state / "body-3.json").read_text(encoding="utf-8")) + assert forced_rerun == {"force": True} + assert (state / "rerun-url").read_text(encoding="utf-8").strip() == ( + f"{BASE_URL}/reports/{REPORT_ID}/runs" + ) assert (state / "read-url").read_text(encoding="utf-8").strip() == ( f"{BASE_URL}/reports/{REPORT_ID}" ) @@ -203,7 +232,7 @@ def test_a_failed_run_fails_the_check_with_its_error_message(fakes, tmp_path): assert fakes.calls("sleep") == [] -def test_a_newest_run_other_than_the_created_one_fails_the_check(fakes, tmp_path): +def test_a_newest_run_other_than_the_forced_one_fails_the_check(fakes, tmp_path): result, _ = _run( fakes, tmp_path, [f"200 {_report('succeeded', run_id=OLDER_RUN_ID)}"] ) @@ -233,6 +262,53 @@ def test_a_refused_submission_fails_the_check_with_its_answer( assert result.returncode == 1 assert status in result.stderr assert body["code"] in result.stderr + assert not (state / "rerun-url").exists() + assert not (state / "polls").exists() + + +@pytest.mark.parametrize( + ("status", "body"), + [ + ("404", {"code": "unknown_report", "detail": "no report"}), + ("503", {"code": "modal_call_refused", "detail": "x", "report_id": REPORT_ID}), + ], +) +def test_a_refused_forced_rerun_fails_the_check_with_its_answer( + fakes, tmp_path, status, body +): + result, state = _run( + fakes, + tmp_path, + [], + FAKE_RERUN_STATUS=status, + FAKE_RERUN_BODY=json.dumps(body), + ) + + assert result.returncode == 1 + assert f"/reports/{REPORT_ID}/runs answered {status}" in result.stderr + assert body["code"] in result.stderr + assert not (state / "polls").exists() + + +def test_a_forced_rerun_that_gets_no_answer_fails_the_check(fakes, tmp_path): + """It may have created a run, so it isn't asked again.""" + result, state = _run(fakes, tmp_path, [], FAKE_RERUN_STATUS="TRANSPORT") + + assert result.returncode == 1 + assert "may have created a run" in result.stderr + assert not (state / "polls").exists() + + +def test_a_forced_rerun_naming_no_run_fails_the_check(fakes, tmp_path): + result, state = _run( + fakes, + tmp_path, + [], + FAKE_RERUN_BODY=json.dumps({**FORCED, "report_run_id": None}), + ) + + assert result.returncode == 1 + assert "the forced re-run named no report run" in result.stderr assert not (state / "polls").exists() @@ -266,7 +342,7 @@ def test_a_read_that_gets_no_answer_is_asked_again(fakes, tmp_path): def test_every_request_has_a_time_limit(fakes, tmp_path): - """The submission, which isn't asked again, may take Cloud Run's full minute.""" + """The submission and the re-run, never asked again, may take a full minute.""" result, _ = _run(fakes, tmp_path, [f"200 {_report('succeeded')}"]) assert result.returncode == 0, result.stderr @@ -276,6 +352,7 @@ def test_every_request_has_a_time_limit(fakes, tmp_path): assert limits == { "https://issuer.example/oauth/token": "30", f"{BASE_URL}/reports": "60", + f"{BASE_URL}/reports/{REPORT_ID}/runs": "60", f"{BASE_URL}/reports/{REPORT_ID}": "30", } From 734bd24dfb3ba644ab6302cbed552b61300dc7e7 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:26:34 +0400 Subject: [PATCH 012/107] Force a new run in the staging economy check MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The check finds or creates its Wales report as before, then sends POST /reports/{report_id}/runs with {"force": true}, asked once, and waits for that run. Once identical requests join existing runs, the report request alone would end on a run an earlier check on the same versions calculated; a forced run, which nothing joins, calculates on every deploy (C1 · 24's answer 3). The re-run needs the same simulation:submit permission and reads no new variable. Co-Authored-By: Claude Opus 5.5 --- .../simulation-staging-economy-check.sh | 38 +++++++++++++------ .../DEPLOYMENT.md | 22 ++++++----- 2 files changed, 39 insertions(+), 21 deletions(-) diff --git a/.github/scripts/simulation-staging-economy-check.sh b/.github/scripts/simulation-staging-economy-check.sh index ae24e8673..c947d3d3a 100755 --- a/.github/scripts/simulation-staging-economy-check.sh +++ b/.github/scripts/simulation-staging-economy-check.sh @@ -1,7 +1,10 @@ #!/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. +# Find or create a small economy report through a deployed Simulation +# Entrypoint, force a new run of it, and require that run to succeed: current +# law against current law for Wales in 2026, which needs no stored policy. +# An identical request ends on the report's existing run, which a check on +# the same versions has already calculated, so only a forced run, which +# nothing joins, calculates 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 +12,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 +89,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 'Found or created 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 +121,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/projects/policyengine-simulation-entry/DEPLOYMENT.md b/projects/policyengine-simulation-entry/DEPLOYMENT.md index 5972daaff..863b190a8 100644 --- a/projects/policyengine-simulation-entry/DEPLOYMENT.md +++ b/projects/policyengine-simulation-entry/DEPLOYMENT.md @@ -131,16 +131,20 @@ 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 +check runs: `.github/scripts/simulation-staging-economy-check.sh` finds or +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 (`POST /reports`), then forces a new run of it +(`POST /reports/{report_id}/runs` with `{"force": true}`), follows that run +through `GET /reports/{report_id}`, and requires it to succeed within 30 +minutes. An identical request ends on the report's existing run, which an +earlier check on the same versions already calculated, so 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 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. +a forced report run and its two simulation runs to the staging database, +and the first check on a .py version also its ordinary run. ## Candidate qualification From c5396b7a8a1cb66f11bbe016061006e57e7b8a33 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:27:37 +0400 Subject: [PATCH 013/107] Test a simulation re-run joining its run on the current versions (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's answer 3: a re-run joins a run under way, so #1059's 409 run_in_progress goes, and a re-run on unchanged versions joins the succeeded run there. Answer 2: a failed run is never joined, so the next re-run inserts a new one. The re-run answers the run it ended on, whether it inserted it, and its status. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_economy_reruns.py | 51 ++++++++++++++++--- 1 file changed, 44 insertions(+), 7 deletions(-) diff --git a/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py b/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py index 69dc69ca5..088107610 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py @@ -496,9 +496,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) @@ -511,25 +512,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( From 5667a00c0633c39e1cb168a18453e465f3e41270 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:28:52 +0400 Subject: [PATCH 014/107] Join a simulation's run on the re-run's versions, or create it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A simulation re-run now looks up the simulation's run that hasn't failed and wasn't forced on the same year, catalog version and versions, pending, running or succeeded, and creates one only when there is none (C1 · 24's answers 2 and 3). It takes no re-run lock and raises no RunInProgressError: the Public API's index makes concurrent re-runs end on one run. It returns the run, its status and whether it was created, so the service starts a Modal call only for a run it created. The store's creates return what their insert returns. Co-Authored-By: Claude Opus 5.5 --- .../__init__.py | 2 + .../economy_rerun_records.py | 48 +++++++++++-------- .../economy_run_records.py | 42 +++++++++++----- .../economy_run_store.py | 21 ++++---- .../shared_rows.py | 19 ++++++-- 5 files changed, 89 insertions(+), 43 deletions(-) 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 816c8532f..64a2d589b 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py @@ -137,6 +137,7 @@ from policyengine_simulation_persistence.shared_rows import ( FoundReportRun, FoundRow, + FoundSimulationRun, SharedRowNotSettledError, find_or_insert_report, find_or_insert_report_run, @@ -185,6 +186,7 @@ "EconomySimulationState", "FoundReportRun", "FoundRow", + "FoundSimulationRun", "HouseholdCalculationInputs", "HouseholdJobRecord", "HouseholdJobReferenceError", 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 bc0704b57..15e5e864d 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 @@ -19,9 +19,12 @@ 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 +calculates on. A simulation's re-run joins the simulation's run that +hasn't failed on the current versions, catalog version and year, when there +is one, pending, running or succeeded, rather than create one (C1 · 24's +answers 2 and 3; ``shared_rows``). For a report, nothing is created while +the record has a run that is ``pending`` or ``running`` (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. @@ -53,6 +56,7 @@ SimulationChoice, insert_simulation_run, references_checked, + simulation_run_row, ) from policyengine_simulation_persistence.household_report_records import ( HOUSEHOLD_REPORT_TYPE, @@ -65,6 +69,9 @@ tax_benefit_model_versions, tax_benefit_models, ) +from policyengine_simulation_persistence.shared_rows import ( + find_or_insert_simulation_run, +) from policyengine_simulation_persistence.tables import ( ReportRunStatus, ReportRunTrigger, @@ -87,6 +94,7 @@ EconomyPopulation, RunVersions, ) + from policyengine_simulation_persistence.shared_rows import FoundSimulationRun # 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 @@ -676,29 +684,27 @@ def _refuse_while_report_runs(connection: Connection, report_id: UUID) -> None: raise RunInProgressError(under_way) -def insert_simulation_rerun(connection: Connection, rerun: NewSimulationRerun) -> None: - """Create the simulation's new run, pending with no call. +def insert_simulation_rerun( + connection: Connection, rerun: NewSimulationRerun +) -> FoundSimulationRun: + """Join the simulation's run on the re-run's versions, or create it, pending. - 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, + ), ) 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 66e327fcc..49af66865 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 @@ -567,21 +567,41 @@ def insert_simulation_run( # noqa: PLR0913 # the run, what it calculates on, a """ 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=forced, + simulation_run_row( + run_id=run_id, + simulation_id=simulation_id, + population=population, + versions=versions, + forced=forced, + ) ) ) +def simulation_run_row( + *, + run_id: UUID, + simulation_id: UUID, + population: EconomyPopulation, + versions: RunVersions, + 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 def references_checked() -> Iterator[None]: """Turn a foreign-key refusal into EconomyRecordReferenceError. 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..77f0801bd 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 @@ -93,6 +93,7 @@ NewEconomySimulation, ) from policyengine_simulation_persistence.policy_reform import PolicyReform + from policyengine_simulation_persistence.shared_rows import FoundSimulationRun from policyengine_simulation_persistence.tables import ( ReportRunStatus, SimulationStatus, @@ -422,12 +423,14 @@ def create_report_rerun(self, rerun: NewReportRerun) -> None: """ 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. """ - 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, @@ -493,23 +496,25 @@ def create_simulation(self, simulation: NewEconomySimulation) -> None: lambda connection: insert_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 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 index 64fb12411..3f823fd57 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/shared_rows.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/shared_rows.py @@ -69,6 +69,15 @@ class FoundRow: 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.""" @@ -156,15 +165,19 @@ def find_or_insert_report( def find_or_insert_simulation_run( connection: Connection, values: Mapping[str, Any] -) -> FoundRow: +) -> 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, ()) - return FoundRow(id=row.id, inserted=inserted) + 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_report_run( From 106902ffd6e8900fccf8861a9e7f8ea3300d520f Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:29:28 +0400 Subject: [PATCH 015/107] Test that a simulation re-run joining a run starts no call (failing) Once the store joins the simulation's run on the re-run's versions, the service answers that run and its status, and starts and records no Modal call for it. Co-Authored-By: Claude Opus 5.5 --- .../tests/economy_rerun_fakes.py | 14 +++++++++-- .../tests/test_economy_reruns.py | 24 +++++++++++++++++++ 2 files changed, 36 insertions(+), 2 deletions(-) diff --git a/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py b/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py index 3bbb02623..80f87eccf 100644 --- a/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py +++ b/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py @@ -26,11 +26,13 @@ BudgetWindowInputs, EconomyReportInputs, EconomySimulationInputs, + FoundSimulationRun, ReportDefinition, SideDefinition, SimulationChoice, SimulationDefinition, SimulationInputs, + SimulationStatus, WindowYearDefinition, ) from test_budget_window_submissions import FakeAdvancer, FakeWindowStore @@ -122,7 +124,9 @@ class FakeRerunStore(FakeWindowStore): window is, and recorded in ``windows``, 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. """ report_definition: ReportDefinition | None = STORED_REPORT @@ -132,6 +136,7 @@ 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 def read_report_definition(self, report_id: UUID) -> ReportDefinition | None: if self.read_failure is not None: @@ -215,10 +220,15 @@ def create_report_rerun(self, rerun: NewReportRerun) -> None: raise self.rerun_failure self.report_reruns.append(rerun) - 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: diff --git a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py index a13b4e314..1d0e767fd 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py @@ -46,6 +46,7 @@ CatalogDataset, EconomyRecordOutcomeUnknownError, EconomyRecordReferenceError, + FoundSimulationRun, MissingPolicyParametersError, NewReportRerun, NewSimulationRerun, @@ -388,6 +389,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"), [ From 7297491c95d6f19643ae9f489becdee66cb69cf9 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:33:00 +0400 Subject: [PATCH 016/107] Start a simulation re-run's call only for a run it created POST /simulations/{simulation_id}/runs now answers the run the store joined, pending, running or succeeded, with its status and no Modal call, and starts and records a call only for a run the store created. The service's create helpers return what the store's create returns. The route's description, the module's steps and the README say so, and that 409 run_in_progress is a report's only. The checks of which stored records the service re-runs, and what each calculates on, move unchanged from economy_reruns into rerunnable_records, which keeps economy_reruns under the 800-line limit. Co-Authored-By: Claude Opus 5.5 --- .../policyengine-simulation-entry/README.md | 15 +- .../economy_rerun_routes.py | 22 +- .../economy_reruns.py | 315 +++--------------- .../economy_submissions.py | 17 +- .../rerunnable_records.py | 279 ++++++++++++++++ 5 files changed, 356 insertions(+), 292 deletions(-) create mode 100644 projects/policyengine-simulation-entry/src/policyengine_simulation_entry/rerunnable_records.py diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index af16cb4bb..a9acb4293 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -260,15 +260,18 @@ 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 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), unless the re-run is forced; 409 `rerun_not_supported` for a household simulation (re-run only +`run_in_progress`, naming the run in `run_id`, while a report has a run +pending or running (its budget-window run, or else its report run), unless +the re-run is forced; 409 `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, 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..2a8e68536 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 @@ -12,14 +12,17 @@ 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. +- ``POST /simulations/{simulation_id}/runs`` (``simulation:submit``) joins + the stored simulation's run on the current versions that hasn't failed, + 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 when a report has a run pending or running, unless the +re-run is forced (``run_in_progress``, naming it in ``run_id``), or the +record is one this service does not re-run (``rerun_not_supported``); then +nothing is written. 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, @@ -305,9 +308,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, 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 9d1d8ac74..fd74e31ee 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 @@ -17,13 +17,16 @@ 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 + simulation, all pending with no Modal call ID, unless the report has a run pending or running (409 ``run_in_progress``). A forced re-run is never refused: its runs are marked forced, an extra run that nothing - joins (C1 · 24's answer 3); -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. + joins (C1 · 24's answer 3). A simulation's re-run instead joins the + simulation's run on the current versions that hasn't failed, pending, + running or succeeded, and creates one only when there is none; +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 is a new budget-window run with a report run per year, each year on the simulations that year's report run of the @@ -39,10 +42,9 @@ 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, @@ -68,27 +70,26 @@ 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_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: @@ -97,9 +98,8 @@ from policyengine_simulation_persistence import ( BudgetWindowInputs, - EconomyCatalogRows, EconomyReportInputs, - RecordKind, + FoundSimulationRun, ReportDefinition, ReusableRun, SideDefinition, @@ -131,12 +131,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" @@ -188,8 +182,8 @@ def create_report_rerun(self, rerun: NewReportRerun) -> None: """Create the report's new run and its sides' new simulation runs.""" ... - 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.""" ... @@ -253,9 +247,9 @@ async def rerun_report( return await self._rerun_household_report( definition, observability_context=observability_context ) - stored = _rerunnable_report(definition) + stored = rerunnable_report(definition) window_years = ( - _complete_window_years(definition) + complete_window_years(definition) if definition.kind == "budget_window" else () ) @@ -315,7 +309,7 @@ async def rerun_report( ) calculation = report_run_calculation( worker, - _rerun_scope( + rerun_scope( stored.country, economy_request, worker, @@ -364,18 +358,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, @@ -399,18 +393,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, @@ -432,7 +432,7 @@ async def _rerun_household_report( 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." @@ -480,7 +480,7 @@ async def _rerun_window( first_year = rerun.years[0] first_calculation = report_run_calculation( worker, - _rerun_scope( + rerun_scope( stored.country, window.economy_request, worker, @@ -542,254 +542,31 @@ def _rerun_side( reused=False, ) - async def _create_rerun( + async def _create_rerun[Created]( self, record: RecordName, - create: Callable[[], None], + create: Callable[[], Created], *, source: RefusalSource, - ) -> None: + ) -> Created: """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. + Return what ``create`` returns. 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 - - -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 _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 _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 _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, - ) + return await self._create(record, create, rerun=True, source=source) @dataclass(frozen=True) 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_submissions.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submissions.py index e9fef6726..626127ef4 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 @@ -480,23 +480,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: 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..43b124afb --- /dev/null +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/rerunnable_records.py @@ -0,0 +1,279 @@ +"""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, + ) + + +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"), + ), + ) From 8307444ab991af3e439f2f20de8c64c5ccabbf03 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:34:44 +0400 Subject: [PATCH 017/107] Test a report re-run joining the report's run on its versions (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's answer 3: a re-run while the report has a run pending, running or succeeded on the current versions joins that run, with the simulation runs it names, and creates nothing, so #1059's 409 run_in_progress goes. A run still under way on older versions is no run to join: the re-run creates its own on the current versions. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_economy_reruns.py | 66 +++++++++++++++---- 1 file changed, 53 insertions(+), 13 deletions(-) diff --git a/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py b/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py index 088107610..03712eb69 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py @@ -43,6 +43,7 @@ EconomyRecordReferenceError, EconomyRequest, EconomyRunStore, + FoundReportRun, MissingPolicyParametersError, NewReportRerun, NewSimulationRerun, @@ -53,7 +54,6 @@ RerunRecordDeletedError, RerunSide, ReusableRun, - RunInProgressError, RunReuse, SideDefinition, SimulationChoice, @@ -79,7 +79,7 @@ insert_policy, insert_region, ) -from sqlalchemy import insert, text +from sqlalchemy import bindparam, insert, text from sqlalchemy.exc import OperationalError if TYPE_CHECKING: @@ -447,28 +447,67 @@ def test_a_report_rerun_creates_runs_of_the_reports_own_simulations( assert baseline_runs == 2 -@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) + joined = insert_report_rerun(connection, rerun) created = connection.execute( - text("SELECT count(*) FROM public.report_runs WHERE id = :id"), - {"id": rerun.run_id}, + text( + "SELECT count(*) FROM public.simulation_runs WHERE id IN :ids" + ).bindparams(bindparam("ids", expanding=True)), + {"ids": [rerun.run_id, *rerun.new_simulation_run_ids]}, ).scalar_one() - assert refused.value.run_id == stored.report_run_id + 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 == 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: with rolled_back_transaction(public_api_database_url) as connection: economy = insert_economy_catalog(connection) @@ -752,8 +791,9 @@ 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 From 1b920ab5c9578cf09496cde52a72c569034bba66 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:37:49 +0400 Subject: [PATCH 018/107] Test a report re-run that loses to a run created after its lookup (failing) Another request may create the report's run on the re-run's versions between the re-run's lookup and its insert. The re-run then joins that run and takes back the simulation runs it had inserted, so no simulation run is left that no report run names. The fixtures committing a catalog for tests of two transactions move to conftest, the deletion of its rows to committed_rows, so both test modules use them. Co-Authored-By: Claude Opus 5.5 --- .../tests/committed_rows.py | 41 +++++++++++++ .../tests/conftest.py | 27 ++++++++- .../tests/test_economy_reruns.py | 58 ++++++++++++++++++- .../tests/test_shared_rows.py | 46 --------------- 4 files changed, 124 insertions(+), 48 deletions(-) create mode 100644 libs/policyengine-simulation-persistence/tests/committed_rows.py 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..bd7b0fba7 --- /dev/null +++ b/libs/policyengine-simulation-persistence/tests/committed_rows.py @@ -0,0 +1,41 @@ +"""Remove the rows a test of two transactions committed. + +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. +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +from sqlalchemy import text + +if TYPE_CHECKING: + from economy_rows import EconomyCatalog + from sqlalchemy import Connection + + +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) 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/test_economy_reruns.py b/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py index 03712eb69..d3ff75f98 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py @@ -79,7 +79,7 @@ insert_policy, insert_region, ) -from sqlalchemy import bindparam, insert, text +from sqlalchemy import bindparam, event, insert, text from sqlalchemy.exc import OperationalError if TYPE_CHECKING: @@ -1055,3 +1055,59 @@ def test_a_forced_rerun_calculates_both_sides() -> None: reform=created, forced=True, ) + + +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_shared_rows.py b/libs/policyengine-simulation-persistence/tests/test_shared_rows.py index 1028d4f19..d9346917d 100644 --- a/libs/policyengine-simulation-persistence/tests/test_shared_rows.py +++ b/libs/policyengine-simulation-persistence/tests/test_shared_rows.py @@ -30,7 +30,6 @@ RunVersions, SimulationStatus, SimulationType, - create_simulation_engine, definition_key, find_or_insert_report, find_or_insert_report_run, @@ -41,8 +40,6 @@ from sqlalchemy import event, insert, text, update if TYPE_CHECKING: - from collections.abc import Iterator - from sqlalchemy import Connection, Engine pytestmark = pytest.mark.public_api_schema @@ -278,49 +275,6 @@ def test_a_report_run_is_joined_on_its_versions_outside_budget_windows( ) -@pytest.fixture -def committed_engine(public_api_database_url) -> Iterator[Engine]: - 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) - - -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.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) - - def _wait_for_a_statement_waiting_on_a_lock(engine: Engine) -> None: """Return once another backend of this database waits for a lock.""" deadline = time.monotonic() + LOCK_WAIT_TIMEOUT_SECONDS From 6becdff61ed91a60256125c0ff425b6d39be8b66 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:38:02 +0400 Subject: [PATCH 019/107] Join a report's run on the re-run's versions, or create it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An unforced report re-run, under the report's re-run lock, joins the report's run on the current versions that hasn't failed and wasn't forced, pending, running or succeeded, with the simulation runs it names, and creates nothing (C1 · 24's answers 2 and 3). Only a budget window's run under way still refuses it. Otherwise it creates its run inside a savepoint, inserting the report run against the Public API's index: one another request created after the lookup is joined, and the savepoint takes back this re-run's simulation runs. It returns the run, its status and pair, and whether it created it. shared_rows gains the lookup of a report's joinable run. Co-Authored-By: Claude Opus 5.5 --- .../__init__.py | 2 + .../economy_rerun_records.py | 144 ++++++++++++------ .../economy_run_store.py | 11 +- .../shared_rows.py | 36 +++++ 4 files changed, 145 insertions(+), 48 deletions(-) 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 64a2d589b..e1b8d65c0 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py @@ -139,6 +139,7 @@ FoundRow, FoundSimulationRun, SharedRowNotSettledError, + find_joinable_report_run, find_or_insert_report, find_or_insert_report_run, find_or_insert_simulation, @@ -251,6 +252,7 @@ "fail_unstarted_household_job", "fail_unstarted_report_run", "fail_unstarted_simulation_run", + "find_joinable_report_run", "find_or_insert_report", "find_or_insert_report_run", "find_or_insert_simulation", 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 15e5e864d..930b1e634 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 @@ -19,14 +19,15 @@ 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. A simulation's re-run joins the simulation's run that -hasn't failed on the current versions, catalog version and year, when there -is one, pending, running or succeeded, rather than create one (C1 · 24's -answers 2 and 3; ``shared_rows``). For a report, nothing is created while -the record has a run that is ``pending`` or ``running`` (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 re-run joins the record's run that hasn't failed on the +current versions, when there is one, pending, running or succeeded, rather +than create one (C1 · 24's answers 2 and 3; ``shared_rows``): a +simulation's run on those versions, catalog version and year, or a +report's run on those versions. A report's re-run takes a +transaction-level advisory lock on its 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; nothing is created while a budget window's +run of the report is ``pending`` or ``running``. 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 @@ -70,6 +71,9 @@ tax_benefit_models, ) from policyengine_simulation_persistence.shared_rows import ( + FoundReportRun, + find_joinable_report_run, + find_or_insert_report_run, find_or_insert_simulation_run, ) from policyengine_simulation_persistence.tables import ( @@ -530,47 +534,90 @@ def _run_under_way( ).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. +def insert_report_rerun( + connection: Connection, rerun: NewReportRerun +) -> FoundReportRun: + """Join the report's run on the re-run's versions, or create it, pending. - Unless the re-run is forced, take the report's re-run lock first, and - raise RunInProgressError, creating nothing, when the report has a run - pending or running; a forced re-run's runs are marked forced. 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. + Unless the re-run is forced, take the report's re-run lock, raise + RunInProgressError, creating nothing, while a budget window's run of + the report is pending or running, 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 create the new run and its sides' new simulation runs; a + forced re-run's are marked forced, and 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. """ + versions = rerun.versions if not rerun.forced: lock_reruns_of(connection, rerun.report_id) - _refuse_while_report_runs(connection, rerun.report_id) - with _record_checked(report_runs.c.report_id), references_checked(): - for side in (rerun.baseline, rerun.reform): - if not side.reused: - insert_simulation_run( - connection, - run_id=side.simulation_run_id, - simulation_id=side.simulation_id, - population=rerun.population, - versions=rerun.versions, - forced=rerun.forced, - ) - 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, - forced=rerun.forced, - ) + _refuse_while_window_runs(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 = { + "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": versions.country_package_version, + "policyengine_version": versions.policyengine_version, + "status": ReportRunStatus.PENDING, + "trigger": ReportRunTrigger.MANUAL, + "modal_call_id": None, + "forced": rerun.forced, + } + with _record_checked(report_runs.c.report_id), references_checked(): + # A run another request created after the lookup above is joined, + # and the savepoint takes back this call's simulation runs with it. + savepoint = connection.begin_nested() + try: + for side in (rerun.baseline, rerun.reform): + if not side.reused: + insert_simulation_run( + connection, + run_id=side.simulation_run_id, + simulation_id=side.simulation_id, + population=rerun.population, + versions=versions, + forced=rerun.forced, + ) + if rerun.forced: + connection.execute(insert(report_runs).values(row)) + found = _created(rerun) + else: + found = find_or_insert_report_run(connection, row) + except BaseException: + savepoint.rollback() + raise + if found.inserted: + savepoint.commit() + else: + savepoint.rollback() + return found + + +def _created(rerun: NewReportRerun) -> FoundReportRun: + """Return the report run a re-run created, as a lookup would.""" + return FoundReportRun( + id=rerun.run_id, + inserted=True, + status=ReportRunStatus.PENDING, + baseline_simulation_run_id=rerun.baseline.simulation_run_id, + reform_simulation_run_id=rerun.reform.simulation_run_id, + ) def insert_window_rerun(connection: Connection, rerun: NewWindowRerun) -> None: @@ -672,6 +719,15 @@ def insert_household_report_rerun( ) +def _refuse_while_window_runs(connection: Connection, report_id: UUID) -> None: + """Raise RunInProgressError while the report has a budget-window run under way.""" + under_way = _run_under_way( + connection, budget_window_runs, budget_window_runs.c.report_id == report_id + ) + if under_way is not None: + raise RunInProgressError(under_way) + + def _refuse_while_report_runs(connection: Connection, report_id: UUID) -> None: """Raise RunInProgressError while the report has a run pending or running. 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 77f0801bd..c7cb13598 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 @@ -93,7 +93,10 @@ NewEconomySimulation, ) from policyengine_simulation_persistence.policy_reform import PolicyReform - from policyengine_simulation_persistence.shared_rows import FoundSimulationRun + from policyengine_simulation_persistence.shared_rows import ( + FoundReportRun, + FoundSimulationRun, + ) from policyengine_simulation_persistence.tables import ( ReportRunStatus, SimulationStatus, @@ -415,13 +418,13 @@ def create_window_rerun(self, rerun: NewWindowRerun) -> None: """ 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. """ - 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) -> FoundSimulationRun: """Join or create the simulation's run; see ``insert_simulation_rerun``. 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 index 3f823fd57..424f8dde6 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/shared_rows.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/shared_rows.py @@ -212,6 +212,42 @@ def find_or_insert_report_run( ) +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" From 806d9c03eb3a1d69fb4b91e0d4f98ae929f20fa8 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:38:47 +0400 Subject: [PATCH 020/107] Test that a report re-run joining a run starts no call (failing) Once the store joins the report's run on the re-run's versions, the service answers that run, its status and the simulation runs it names, with both sides reused, and starts and records no coordinator call. Co-Authored-By: Claude Opus 5.5 --- .../tests/economy_rerun_fakes.py | 17 ++++++++- .../tests/test_economy_reruns.py | 37 +++++++++++++++++++ 2 files changed, 52 insertions(+), 2 deletions(-) diff --git a/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py b/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py index 80f87eccf..f1477d8e1 100644 --- a/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py +++ b/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py @@ -26,8 +26,10 @@ BudgetWindowInputs, EconomyReportInputs, EconomySimulationInputs, + FoundReportRun, FoundSimulationRun, ReportDefinition, + ReportRunStatus, SideDefinition, SimulationChoice, SimulationDefinition, @@ -126,7 +128,8 @@ class FakeRerunStore(FakeWindowStore): ``inputs_failure`` is raised by a re-run's read of its inputs, and ``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. + creates its own run; a report re-run joins ``joined_report_run`` the + same way. """ report_definition: ReportDefinition | None = STORED_REPORT @@ -137,6 +140,7 @@ class FakeRerunStore(FakeWindowStore): 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 def read_report_definition(self, report_id: UUID) -> ReportDefinition | None: if self.read_failure is not None: @@ -215,10 +219,19 @@ def create_window_rerun(self, rerun: NewWindowRerun) -> None: raise self.rerun_failure self.windows.append(rerun) - 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) + if self.joined_report_run is not None: + return self.joined_report_run + return FoundReportRun( + id=rerun.run_id, + inserted=True, + status=ReportRunStatus.PENDING, + baseline_simulation_run_id=rerun.baseline.simulation_run_id, + reform_simulation_run_id=rerun.reform.simulation_run_id, + ) def create_simulation_rerun(self, rerun: NewSimulationRerun) -> FoundSimulationRun: if self.rerun_failure is not None: diff --git a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py index 1d0e767fd..aa3b7c9e2 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py @@ -46,6 +46,7 @@ CatalogDataset, EconomyRecordOutcomeUnknownError, EconomyRecordReferenceError, + FoundReportRun, FoundSimulationRun, MissingPolicyParametersError, NewReportRerun, @@ -179,6 +180,42 @@ def test_a_forced_rerun_recalculates_both_simulations() -> None: assert (rerun.baseline_reused, rerun.reform_reused) == (False, False) +@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.""" + 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(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_without_the_output_bucket_a_rerun_looks_for_no_run_to_reuse() -> None: store = FakeRerunStore(reusable=(REUSED_BASELINE, None)) From 9875411a7234e91d7f25a012a6ce82e52a1deff5 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:39:10 +0400 Subject: [PATCH 021/107] Answer a report re-run that joined a run, with no call MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit POST /reports/{report_id}/runs now answers the run the store joined, pending, running or succeeded on the current versions, with its status, the simulation runs it names and both sides reused, and starts no coordinator. Only a run the store created gets its call. The 409 run_in_progress is left to budget windows, whose re-runs C1 · 24's answer 8 decides; the README, the route's notes and the module's steps say so. Co-Authored-By: Claude Opus 5.5 --- .../policyengine-simulation-entry/README.md | 12 +++-- .../economy_rerun_routes.py | 10 ++-- .../economy_reruns.py | 49 ++++++++++++++----- 3 files changed, 52 insertions(+), 19 deletions(-) diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index a9acb4293..4818c6ce2 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -238,7 +238,11 @@ 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, as an extra run: the new report run and both simulation runs are marked `forced`, so nothing joins them, and a forced re-run is never -refused while a run is under way. The new report run's trigger is `manual`. The service reads the +refused while a run is under way. The new report run's trigger is `manual`. +Without `force`, a re-run while the report has a run on the default +worker's versions that hasn't failed, 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. 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. @@ -269,9 +273,9 @@ 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 a report has a run -pending or running (its budget-window run, or else its report run), unless -the re-run is forced; 409 `rerun_not_supported` for a household simulation (re-run only +`run_in_progress`, naming the run in `run_id`, while a budget window's run +of the report, or one of its year runs, is pending or running, unless the +re-run is forced; 409 `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, 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 2a8e68536..0e68a6929 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 @@ -19,10 +19,12 @@ and its status. Every earlier run is kept. A re-run answers 404 for a record that does not -exist, and 409 when a report has a run pending or running, unless the -re-run is forced (``run_in_progress``, naming it in ``run_id``), or the -record is one this service does not re-run (``rerun_not_supported``); then -nothing is written. The other +exist, and 409 while a budget window's run of the report is pending or +running, unless the re-run is forced (``run_in_progress``, naming it in +``run_id``), or for a record this service does not re-run +(``rerun_not_supported``); then nothing is written. Without ``force``, a +report's re-run joins the report's run on the current versions that hasn't +failed, pending, running or succeeded, and answers it with no new call. 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, 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 fd74e31ee..a1144473d 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 @@ -15,14 +15,14 @@ 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 report has a - run pending or running (409 ``run_in_progress``). A forced re-run is - never refused: its runs are marked forced, an extra run that nothing - joins (C1 · 24's answer 3). A simulation's re-run instead joins the - simulation's run on the current versions that hasn't failed, pending, - running or succeeded, and creates one only when there is none; +3. 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 (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. A forced re-run + always creates its runs, marked forced, an extra run that nothing joins. + A budget window's re-run is refused while a window run of the report is + pending or running (409 ``run_in_progress``); 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 @@ -99,6 +99,7 @@ from policyengine_simulation_persistence import ( BudgetWindowInputs, EconomyReportInputs, + FoundReportRun, FoundSimulationRun, ReportDefinition, ReusableRun, @@ -178,8 +179,8 @@ def create_window_rerun(self, rerun: NewWindowRerun) -> None: """Create the window's new run, each year's report run and new runs.""" ... - 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) -> FoundSimulationRun: @@ -325,11 +326,13 @@ async def rerun_report( baseline_policy=inputs.baseline.reform, reform_policy=inputs.reform.reform, ) - await self._create_rerun( + 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) status = await self._start_report_run( worker, calculation, @@ -560,6 +563,30 @@ async def _create_rerun[Created]( return await self._create(record, create, rerun=True, source=source) +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. + + The run names runs of the report's own simulations; a side reusing no + run never joins, so both sides are reused. + """ + 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, + ) + + @dataclass(frozen=True) class _WindowRerunRequest: """What a budget window's re-run calculates, as the service has read it.""" From 7338dcd82a409a4dcbb6e29b9cc389dc8fce73de Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:59:52 +0400 Subject: [PATCH 022/107] Test that no report reuses a forced run (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review round 1's bug: the reuse search behind find_reusable_run and find_reusable_run_of has no condition on forced, so a forced re-run's succeeded simulation run is offered to the next identical report, and to an unforced re-run of the same report. C1 · 24's answer 3 says nothing joins a forced run. The test rows' run shape gains the forced marker. Co-Authored-By: Claude Opus 5.5 --- .../tests/economy_rows.py | 4 +++- .../tests/test_economy_run_reuse.py | 22 +++++++++++++++++++ 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/libs/policyengine-simulation-persistence/tests/economy_rows.py b/libs/policyengine-simulation-persistence/tests/economy_rows.py index b203b6aea..adcf4e4eb 100644 --- a/libs/policyengine-simulation-persistence/tests/economy_rows.py +++ b/libs/policyengine-simulation-persistence/tests/economy_rows.py @@ -147,7 +147,7 @@ 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. + ``output_uri`` names another. ``forced`` marks a forced re-run's run. """ choice: SimulationChoice = CURRENT_LAW @@ -155,6 +155,7 @@ class RunShape: versions: RunVersions = VERSIONS output_uri: str | None = None completed_at: datetime = COMPLETED_AT + forced: bool = False def insert_simulation_run( @@ -212,6 +213,7 @@ def insert_run_of( else None ), output_sha256="d" * 64 if succeeded else None, + forced=shape.forced, ) ) return StoredRun(simulation_id=simulation_id, simulation_run_id=run_id) diff --git a/libs/policyengine-simulation-persistence/tests/test_economy_run_reuse.py b/libs/policyengine-simulation-persistence/tests/test_economy_run_reuse.py index ee750e10d..6049c1f5a 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_run_reuse.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_run_reuse.py @@ -42,6 +42,7 @@ SimulationChoice, SimulationStatus, find_reusable_run, + find_reusable_run_of, ) from public_api_rows import insert_dataset, insert_dynamic, insert_policy, insert_region @@ -179,6 +180,27 @@ def test_an_unfinished_or_failed_run_is_not_reused( assert _find(connection, economy) is None +def test_a_forced_run_is_never_reused(public_api_database_url) -> None: + """Answer 3: a forced re-run's run is never named by another report run.""" + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + forced = insert_reusable_run(connection, economy, RunShape(forced=True)) + act_as_the_service(connection) + + by_definition = _find(connection, economy) + by_own_simulation = find_reusable_run_of( + connection, + simulation_id=forced.simulation_id, + population=economy.population(), + versions=VERSIONS, + inputs=OPTIONS, + output_uri_prefix=OUTPUT_BUCKET_PREFIX, + ) + + assert by_definition is None + assert by_own_simulation is None + + def test_a_run_whose_file_is_outside_the_output_bucket_is_not_reused( public_api_database_url, ) -> None: From 4e689fa881f7d6cd38414095f214abb23f0dda0f Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:59:55 +0400 Subject: [PATCH 023/107] Never reuse a forced run MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The reuse search behind find_reusable_run and find_reusable_run_of now leaves out runs marked forced, so a forced re-run's simulation runs are never named by another report run, as C1 · 24's answer 3 requires. Fixes review round 1's bug. Co-Authored-By: Claude Opus 5.5 --- .../economy_run_records.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) 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 49af66865..daac997e2 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 @@ -301,7 +301,9 @@ def find_reusable_run( # noqa: PLR0913 # each keyword is one part of the match 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 + calculates the simulation again; + - that wasn't forced: a forced re-run's run is never named by another + report run (C1 · 24's answer 3); and - that is not ``excluded_run_id``, the other side's run. The coordinator may still refuse it, when the new report plans outputs @@ -408,6 +410,7 @@ def _newest_reusable_run( conditions = [ *simulation_conditions, simulation_runs.c.status == SimulationStatus.SUCCEEDED, + simulation_runs.c.forced.is_(False), simulation_runs.c.year == population.year, simulation_runs.c.tax_benefit_model_version_id == population.tax_benefit_model_version_id, From 94e996dd67e57976997ea75ccb835febdfe265a6 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:01:30 +0400 Subject: [PATCH 024/107] Tighten two of the shared-run tests (review round 1) The report re-run join test counts report runs for the re-run's report run ID, and simulation runs for its simulation run IDs, rather than looking for the report run among simulation runs. The two-transaction test commits the first transaction only once a backend waits on a lock that transaction holds (pg_blocking_pids), not on any lock in the database, and re-raises a thread's error instead of failing on a missing result. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_economy_reruns.py | 10 ++++-- .../tests/test_shared_rows.py | 33 +++++++++++++++---- 2 files changed, 33 insertions(+), 10 deletions(-) diff --git a/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py b/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py index d3ff75f98..1c9066a79 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py @@ -469,11 +469,15 @@ def test_a_report_rerun_joins_the_reports_run_on_its_versions( act_as_the_service(connection) joined = insert_report_rerun(connection, rerun) - created = connection.execute( + 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": [rerun.run_id, *rerun.new_simulation_run_ids]}, + {"ids": list(rerun.new_simulation_run_ids)}, ).scalar_one() assert joined == FoundReportRun( @@ -483,7 +487,7 @@ def test_a_report_rerun_joins_the_reports_run_on_its_versions( baseline_simulation_run_id=stored.baseline.simulation_run_id, reform_simulation_run_id=stored.reform.simulation_run_id, ) - assert created == 0 + 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( diff --git a/libs/policyengine-simulation-persistence/tests/test_shared_rows.py b/libs/policyengine-simulation-persistence/tests/test_shared_rows.py index d9346917d..ee9e0311a 100644 --- a/libs/policyengine-simulation-persistence/tests/test_shared_rows.py +++ b/libs/policyengine-simulation-persistence/tests/test_shared_rows.py @@ -40,6 +40,8 @@ from sqlalchemy import event, insert, text, update if TYPE_CHECKING: + from collections.abc import Callable + from sqlalchemy import Connection, Engine pytestmark = pytest.mark.public_api_schema @@ -275,16 +277,17 @@ def test_a_report_run_is_joined_on_its_versions_outside_budget_windows( ) -def _wait_for_a_statement_waiting_on_a_lock(engine: Engine) -> None: - """Return once another backend of this database waits for a lock.""" +def _wait_until_another_backend_waits_for(engine: Engine, holder_pid: int) -> None: + """Return once a backend waits for a lock the backend ``holder_pid`` holds.""" deadline = time.monotonic() + LOCK_WAIT_TIMEOUT_SECONDS with engine.connect() as connection: while time.monotonic() < deadline: waiting = connection.execute( text( "SELECT count(*) FROM pg_stat_activity " - "WHERE datname = current_database() AND wait_event_type = 'Lock'" - ) + "WHERE :holder_pid = ANY(pg_blocking_pids(pid))" + ), + {"holder_pid": holder_pid}, ).scalar_one() connection.rollback() if waiting: @@ -305,6 +308,17 @@ def test_a_transaction_inserting_a_run_another_has_inserted_waits_and_joins_it( ) first_has_inserted = threading.Event() found: dict[str, Any] = {} + errors: list[BaseException] = [] + + def recording_errors(work: Callable[[], None]) -> Callable[[], None]: + def run() -> None: + try: + work() + except BaseException as error: # noqa: BLE001 # re-raised by the test's thread + errors.append(error) + first_has_inserted.set() + + return run def insert_then_commit_once_the_other_waits() -> None: with committed_engine.begin() as connection: @@ -312,8 +326,11 @@ def insert_then_commit_once_the_other_waits() -> None: 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_for_a_statement_waiting_on_a_lock(committed_engine) + _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) @@ -324,14 +341,16 @@ def insert_once_the_first_has() -> None: ) threads = [ - threading.Thread(target=insert_then_commit_once_the_other_waits), - threading.Thread(target=insert_once_the_first_has), + threading.Thread(target=recording_errors(work)) + for work in (insert_then_commit_once_the_other_waits, insert_once_the_first_has) ] for thread in threads: thread.start() for thread in threads: thread.join(LOCK_WAIT_TIMEOUT_SECONDS * 2) + if errors: + raise errors[0] assert found["first"].inserted is True assert (found["second"].id, found["second"].inserted) == (found["first"].id, False) From b7a496a0f1b483b3db496addd41782f194f053a7 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:01:55 +0400 Subject: [PATCH 025/107] Test a 503 for a run that keeps failing before it is read (failing) Review round 1: SharedRowNotSettledError, raised when the run a lookup lost to keeps failing before it can be read, was answered as a 500. Nothing was written, so the re-run should be answered unavailable and asked again. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_economy_reruns.py | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py index aa3b7c9e2..a3480681b 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py @@ -59,6 +59,7 @@ RunInProgressError, RunReuse, RunVersions, + SharedRowNotSettledError, SimulationStatus, UnknownRegionError, ) @@ -378,6 +379,23 @@ 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")) + service = rerun_service(store) + + with pytest.raises(EconomySubmissionUnavailableError) as unavailable: + if record == "report": + _rerun_report(service) + else: + _rerun_simulation(service) + + assert unavailable.value.code == "database_unavailable" + + def test_a_rerun_whose_commit_is_unconfirmed_may_have_written_its_run() -> None: store = FakeRerunStore( rerun_failure=EconomyRecordOutcomeUnknownError("commit failed") From 4bfbd3facf7e3973b99d968380e33bab2648c1bb Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:02:17 +0400 Subject: [PATCH 026/107] Answer a run that keeps failing before it is read as unavailable The service's create answers SharedRowNotSettledError, raised when the run a lookup lost to keeps failing before it can be read, as the 503 database_unavailable it gives a database error: its transaction wrote nothing, so the caller may ask again. Fixes a review round 1 finding. Co-Authored-By: Claude Opus 5.5 --- .../src/policyengine_simulation_entry/economy_submissions.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) 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 626127ef4..5fe2d8f88 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 @@ -50,6 +50,7 @@ ReportRunStatus, ReportSimulation, RunReuse, + SharedRowNotSettledError, SimulationChoice, SimulationStatus, ) @@ -505,7 +506,9 @@ async def _create[Created]( 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__}, From 2dc7d77b79ede9b9206b0bc1cfb01661b3a35e6e Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:02:40 +0400 Subject: [PATCH 027/107] Keep one statement in the unavailable re-run test's raises block Co-Authored-By: Claude Opus 5.5 --- .../tests/test_economy_reruns.py | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py index a3480681b..4b80b36e3 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py @@ -385,13 +385,10 @@ def test_a_run_that_keeps_failing_before_it_is_read_is_answered_unavailable( ) -> None: """Nothing was written, so the caller is told to ask again (503).""" store = FakeRerunStore(rerun_failure=SharedRowNotSettledError("kept failing")) - service = rerun_service(store) + rerun = _rerun_report if record == "report" else _rerun_simulation with pytest.raises(EconomySubmissionUnavailableError) as unavailable: - if record == "report": - _rerun_report(service) - else: - _rerun_simulation(service) + rerun(rerun_service(store)) assert unavailable.value.code == "database_unavailable" From 087522b16ad7759bb41d4e93fcb572eb0ac81305 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:04:13 +0400 Subject: [PATCH 028/107] Test the re-run routes' documented answers after joining (failing) Review round 1: the OpenAPI document still says a re-run's 201 is a new run, created and started, and that a simulation's re-run answers 409 run_in_progress, which it no longer can: it joins its run. The 201 must say the run may have been joined, and only the report route's 409 names run_in_progress. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_openapi.py | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/projects/policyengine-simulation-entry/tests/test_openapi.py b/projects/policyengine-simulation-entry/tests/test_openapi.py index 248e2f478..d0250c938 100644 --- a/projects/policyengine-simulation-entry/tests/test_openapi.py +++ b/projects/policyengine-simulation-entry/tests/test_openapi.py @@ -458,8 +458,17 @@ 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"] + # Only a report's re-run is refused while a run is under way; a + # simulation's joins its run (C1 · 24's answer 3). + report_conflict = _responses(spec, "post", "/reports/{report_id}/runs")["409"] + simulation_conflict = _responses(spec, "post", "/simulations/{simulation_id}/runs")[ + "409" + ] + assert "run_id" in report_conflict["description"] + assert "run_in_progress" not in simulation_conflict["description"] codes = set( spec["components"]["schemas"]["EconomyError"]["properties"]["code"]["enum"] ) From df7c61fe71393e3f87eec006945856b1c6dbf5ba Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:06:11 +0400 Subject: [PATCH 029/107] Describe re-runs that join, and the staging check as it is (review round 1) Review round 1's documentation findings: - The re-run routes' 201 says the run may have been joined, and only the report route's 409 names run_in_progress, for a budget-window or household report with a run under way; a simulation's re-run joins. - The report route's description, ReportRerunRequest, the conflict codes, and the created answers' status and reused fields describe joining. - The READMEs say which re-runs take the advisory lock, that a household report's re-run is still refused while a run is under way, that an unforced re-run whose side has an unreused run on the current versions answers 500 until sides are found by version set, and that the GET routes read the newest run, which may be later than the one answered. - The staging check's script, guide, tests and workflow comment say its report request reuses simulation runs (and, once reports are found by key, the report run), so the forced run is what calculates. - insert_report_rerun says when its sides' plain inserts are refused, and the budget-window refusal shares one query. Co-Authored-By: Claude Opus 5.5 --- .../simulation-staging-economy-check.sh | 13 ++--- .../workflows/simulation-deploy.reusable.yml | 5 +- .../README.md | 21 +++++--- .../economy_rerun_records.py | 32 +++++++---- .../DEPLOYMENT.md | 24 +++++---- .../policyengine-simulation-entry/README.md | 26 ++++++--- .../economy_api_models.py | 53 +++++++++++-------- .../economy_rerun_routes.py | 35 ++++++++---- .../economy_reruns.py | 8 +-- .../tests/test_staging_economy_check.py | 21 ++++---- 10 files changed, 146 insertions(+), 92 deletions(-) diff --git a/.github/scripts/simulation-staging-economy-check.sh b/.github/scripts/simulation-staging-economy-check.sh index c947d3d3a..b73198890 100755 --- a/.github/scripts/simulation-staging-economy-check.sh +++ b/.github/scripts/simulation-staging-economy-check.sh @@ -1,10 +1,11 @@ #!/bin/bash -# Find or create a small economy report through a deployed Simulation -# Entrypoint, force a new run of it, and require that run to succeed: current -# law against current law for Wales in 2026, which needs no stored policy. -# An identical request ends on the report's existing run, which a check on -# the same versions has already calculated, so only a forced run, which -# nothing joins, calculates on every deploy. +# 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 diff --git a/.github/workflows/simulation-deploy.reusable.yml b/.github/workflows/simulation-deploy.reusable.yml index b89de5283..1707731d6 100644 --- a/.github/workflows/simulation-deploy.reusable.yml +++ b/.github/workflows/simulation-deploy.reusable.yml @@ -1263,8 +1263,9 @@ jobs: # 12, with the default as it is). It calls the tagged candidate URL, # which serves this release's revision whether or not it was promoted. # The report's rows are written in the staging database, and its - # coordinator records the run. Once a .py version's first check has - # succeeded, later checks on it reuse those simulation runs. + # coordinator records the run. The check then forces a new run of the + # report, which nothing joins or reuses, so both simulations are + # calculated on every deploy. if: >- ${{ !cancelled() && diff --git a/libs/policyengine-simulation-persistence/README.md b/libs/policyengine-simulation-persistence/README.md index 7a7bab9ac..cc1e32b89 100644 --- a/libs/policyengine-simulation-persistence/README.md +++ b/libs/policyengine-simulation-persistence/README.md @@ -165,14 +165,19 @@ version, dataset and region it calculates on. 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, trigger `manual`, + and a new run of each side's simulation that reuses none. 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; it refuses with `RunInProgressError` only while a + budget-window run of the report is under way. A forced one + (`NewReportRerun.forced`) takes no lock, always creates its runs, marked + `forced`, and reuses 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`. 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 930b1e634..6ca1e4ae6 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 @@ -510,8 +510,10 @@ 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 unforced re-run of the same report waits + here until the first one's transaction ends, then sees its run. A + simulation's re-run and a forced one take none: the Public API's index + on runs lets one joinable run exist, and nothing joins a forced run. """ connection.execute( select( @@ -540,12 +542,21 @@ def insert_report_rerun( """Join the report's run on the re-run's versions, or create it, pending. Unless the re-run is forced, take the report's re-run lock, raise - RunInProgressError, creating nothing, while a budget window's run of - the report is pending or running, 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 create the new run and its sides' new simulation runs; a - forced re-run's are marked forced, and never joined. Return the run and - whether this call created it, which only then needs its Modal call. + RunInProgressError, creating nothing, while a budget-window run of the + report is pending or running (the service re-runs a budget window with + ``insert_window_rerun``; one passed here directly is refused that way), + 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 create the new run and + its sides' new simulation runs; a forced re-run's are marked forced, and + never joined. Return the run and whether this call created it, which + only then needs its Modal call. + + A side's new simulation run is a plain insert, so while that side's + simulation has another run on these versions that hasn't failed (one + another report run is calculating, or one ``find_reusable_run_of`` + didn't offer), the Public API's index refuses it and the database error + propagates; finding a side's run by version set waits for C1 · 24's + answers 4 and 5. Raise RerunRecordDeletedError when the database refuses the new run's key to the report, which no longer exists, and @@ -733,9 +744,10 @@ def _refuse_while_report_runs(connection: Connection, report_id: UUID) -> None: A budget-window run under way is named first, then a report run. """ + _refuse_while_window_runs(connection, report_id) 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) + connection, report_runs, report_runs.c.report_id == report_id + ) if under_way is not None: raise RunInProgressError(under_way) diff --git a/projects/policyengine-simulation-entry/DEPLOYMENT.md b/projects/policyengine-simulation-entry/DEPLOYMENT.md index 863b190a8..d653d0a88 100644 --- a/projects/policyengine-simulation-entry/DEPLOYMENT.md +++ b/projects/policyengine-simulation-entry/DEPLOYMENT.md @@ -131,20 +131,22 @@ 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` finds or -creates a small report, current law against current law for `country/wales` +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 it +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. An identical request ends on the report's existing run, which an -earlier check on the same versions already calculated, so 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, -and the first check on a .py version also its ordinary run. +minutes. The request reuses the simulation runs an earlier check on the same +versions calculated, and once reports are found by key it ends on that +check's report run, so the forced run, which nothing joins or reuses, 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, and, +until reports are found by key, a new report and its ordinary run too, which +on a .py version's first check calculates both simulations as well. ## Candidate qualification diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index 4818c6ce2..be5f4d76c 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -275,7 +275,8 @@ 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 a budget window's run of the report, or one of its year runs, is pending or running, unless the -re-run is forced; 409 `rerun_not_supported` for a household simulation (re-run only +re-run is forced, or while a household report has a run pending or running; +409 `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, @@ -287,13 +288,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`. An unforced report re-run (economy, budget-window or +household) looks for the run to join, or for a run under way, and inserts +under a transaction-level advisory lock on the report's ID, so two such +re-runs of one report end on one run. A simulation's re-run takes no lock: +the Public API's index on runs lets only one run that hasn't failed exist on +a version set, so concurrent re-runs end on it. A forced re-run takes none +either, as nothing joins it. A household report's re-run, forced or not, is +still refused with 409 `run_in_progress` while any run of the report is +pending or running. Until a report's sides find their simulation runs by +version set (C1 · 24's answers 4 and 5), an unforced economy report re-run +whose side has a run on the current versions that hasn't failed but isn't +reused (one another report run is calculating, or one used with other +options) is refused by that index and answered 500. 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 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..d384ff352 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 @@ -19,9 +19,9 @@ - 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; + ``run_in_progress``, naming the run pending or running (``run_id``) of a + budget-window or household report, or ``rerun_not_supported`` for a + record this service does not re-run. Nothing is written; - 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 @@ -88,9 +88,10 @@ ] # 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. + # A budget-window report has a window run or year run pending or + # running, or a household report a run, and the re-run isn't forced; + # ``run_id`` names the budget-window run, or else the report run. An + # economy report's or a simulation's re-run joins its run instead. "run_in_progress", # The service does not re-run this kind of record, or the record lacks a # row it calculates on. @@ -198,9 +199,11 @@ 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``, an economy report's re-run joins the report's run on + those versions that hasn't failed, pending, running or succeeded, and + otherwise a side reuses a run of its own simulation that succeeded on + them, as a new report's side does. With it, both simulations are + calculated again, as an extra run marked forced that nothing joins. """ force: StrictBool = False @@ -211,12 +214,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 +230,16 @@ 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 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 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 + re-run that joined a run answers that run's status as read. Each side + names its simulation and simulation run; ``…_reused`` is true for a side + whose run this request didn't create: a run that already succeeded, or, + on a joined run, that run's own. """ report_id: UUID 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 0e68a6929..48c5b2d64 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 @@ -115,9 +115,15 @@ class EconomyService(EconomySubmissions, EconomyReruns, Protocol): # 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", +_CONFLICTS: dict[RecordName, str] = { + "report": ( + "a budget-window report has a window run or year run pending or " + "running, or a household report a run, and the re-run isn't forced " + "(run_in_progress; run_id names the report's budget-window run, or " + "else its report run), or the service does not re-run it " + "(rerun_not_supported)" + ), + "simulation": "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 @@ -147,7 +153,13 @@ class EconomyService(EconomySubmissions, EconomyReruns, Protocol): 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 " @@ -166,10 +178,8 @@ 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 now, and nothing was written: " + f"{_CONFLICTS[record]}" ), **ERROR_ANSWER, }, @@ -273,9 +283,12 @@ 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 " + "force, an economy report's re-run joins the report's run on those " + "versions that hasn't failed, pending, running or succeeded, and " + "answers it with no new call; otherwise a side reuses a run of its " + "own simulation that succeeded on the same versions. With force, " + "both simulations are calculated again, as an extra run marked " + "forced that nothing joins. 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 " 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 a1144473d..bb2a3c6f6 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 @@ -229,7 +229,7 @@ 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 @@ -552,9 +552,11 @@ async def _create_rerun[Created]( *, source: RefusalSource, ) -> Created: - """Create the re-run's rows; refuse it while the record has a run under way. + """Create or join the re-run's rows, answering the store's refusals. - Return what ``create`` returns. A record deleted after its reads is + Return what ``create`` returns: the run it joined or created. A + budget-window or household report with a run under way is refused + (409 ``run_in_progress``). 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. diff --git a/projects/policyengine-simulation-entry/tests/test_staging_economy_check.py b/projects/policyengine-simulation-entry/tests/test_staging_economy_check.py index c3ab3d03f..f20b6e822 100644 --- a/projects/policyengine-simulation-entry/tests/test_staging_economy_check.py +++ b/projects/policyengine-simulation-entry/tests/test_staging_economy_check.py @@ -1,15 +1,16 @@ """The staging economy check, run on every staging deploy. -``simulation-staging-economy-check.sh`` finds or creates a small economy -report, current law against current law for Wales in 2026, through the -deployed candidate's ``POST /reports``, then forces a new run of it with -``POST /reports/{report_id}/runs``, follows that run through -``GET /reports/{report_id}`` and requires it to succeed. An identical -request ends on the report's existing run (C1 · 24), which a check on the -same versions has already calculated, so only a forced run, which nothing -joins, calculates on every deploy (answer 3). It runs after the v2 -manifest's default has moved to the release's worker, so the run calculates -on the release's own coordinator and workers. +``simulation-staging-economy-check.sh`` sends a small economy report +request, current law against current law for Wales in 2026, through the +deployed candidate's ``POST /reports``, then forces a new run of the report +with ``POST /reports/{report_id}/runs``, follows that run through +``GET /reports/{report_id}`` and requires it to succeed. 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; C1 · 24), so +only a forced run, which nothing joins or reuses, calculates on every deploy +(answer 3). It runs after the v2 manifest's default has moved to the +release's worker, so the run calculates on the release's own coordinator and +workers. """ from __future__ import annotations From 4446b9a01eaf37bd53f1a6779b8babc8d2ff41fe Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:08:45 +0400 Subject: [PATCH 030/107] Keep the re-run and read tests within one unfailed run per version set Seven tests stored two runs that haven't failed and weren't forced on one version set, which the Public API's next revision refuses; each failed with a unique violation against it and passes now, its intent kept: - the test rows' report run takes its versions, and the later run the re-run tests reuse is used by another report's run on the later versions, not by a run of the stored report, which a re-run would now join (five re-run tests); - the re-run after a failed re-run fails that re-run's simulation runs too, as its runs have ended; - the newest-run read's two later runs are forced re-runs' runs. Co-Authored-By: Claude Opus 5.5 --- .../tests/economy_rows.py | 7 ++-- .../tests/test_economy_reruns.py | 38 ++++++++++++++----- .../tests/test_economy_run_reads.py | 8 +++- 3 files changed, 39 insertions(+), 14 deletions(-) diff --git a/libs/policyengine-simulation-persistence/tests/economy_rows.py b/libs/policyengine-simulation-persistence/tests/economy_rows.py index adcf4e4eb..0bc78c70b 100644 --- a/libs/policyengine-simulation-persistence/tests/economy_rows.py +++ b/libs/policyengine-simulation-persistence/tests/economy_rows.py @@ -221,11 +221,12 @@ 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 its report's options.""" status: ReportRunStatus = ReportRunStatus.SUCCEEDED inputs: dict[str, Any] | None = None error_message: str | None = None + versions: RunVersions = VERSIONS def insert_report_run_naming( @@ -300,8 +301,8 @@ 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, completed_at=COMPLETED_AT if finished else None, diff --git a/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py b/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py index 1c9066a79..01d6daf19 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py @@ -275,7 +275,12 @@ def _find_later_run_of( 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 the later catalog, reused the baseline's + run; its succeeded run is on the later versions. The stored report itself + has no run on them, so a re-run of it has none to join. + """ later_shape = RunShape(versions=LATER_VERSIONS) later_baseline = insert_run_of( connection, stored.baseline.simulation_id, later.population(), later_shape @@ -286,7 +291,15 @@ def _used_on_later_catalog( later.population(), replace(later_shape, status=SimulationStatus.FAILED), ) - insert_report_run_of(connection, stored.report_id, (later_baseline, later_reform)) + other_report_id = insert_report_of( + connection, later, (later_baseline, later_reform) + ) + insert_report_run_of( + connection, + other_report_id, + (later_baseline, later_reform), + ReportRunOutcome(versions=LATER_VERSIONS), + ) return later_baseline @@ -520,15 +533,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) 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..679e040f5 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_run_reads.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_run_reads.py @@ -39,7 +39,12 @@ 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. + """ population = economy.population() baseline = insert_simulation_run(connection, population) reform = insert_simulation_run( @@ -70,6 +75,7 @@ def _report_with_runs(connection, economy: EconomyCatalog) -> tuple[UUID, list[U policyengine_version=POLICYENGINE_VERSION, status=ReportRunStatus.PENDING, trigger="manual", + forced=True, ) ) run_ids.append(run_id) From 87d75bc033e71524482b5491271ae8774b4cdb24 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:12:45 +0400 Subject: [PATCH 031/107] Keep the Stage 12 sweep and window tests within one unfailed run per version set Five Stage 12 persistence test cases stored two runs that haven't failed and weren't forced on one version set, which the Public API's next revision refuses; each failed with a unique violation against it and passes now: - another simulation run of the seeded baseline's simulation is on a .py version of its own (the sweep doesn't read versions), in the reform-run, unnamed-run and shared-run sweep tests; - the shared-run sweep test's second running report run is another report's, copying the seeded report: 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 window re-run seeder's runs are marked forced, as a recalculating re-run's are. The sweep tests using those helpers were run by node ID too. Co-Authored-By: Claude Opus 5.5 --- .../tests/budget_window_database.py | 5 ++ .../tests/test_report_run_sweep_store.py | 60 +++++++++++++++---- 2 files changed, 55 insertions(+), 10 deletions(-) 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..ba9358c57 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,26 @@ def _second_report_run( return second_id +def _copy_of_report(seeder, report_id): + """Insert a new report copying ``report_id``'s columns; return its ID.""" + report = seeder.row("reports", report_id) + copy_id = uuid4() + with seeder.engine.begin() as connection: + connection.execute( + insert(seeder.table("reports")).values( + { + **{ + name: value + for name, value in report.items() + if name not in {"id", "created_at", "updated_at"} + }, + "id": copy_id, + } + ) + ) + return copy_id + + # What another simulation run of the seeded baseline's simulation copies. SIMULATION_RUN_DEFINITION = ( "simulation_id", @@ -374,7 +402,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 +415,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 +667,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 +686,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, From 1e4352e385fcbe8aefbff8eca5a39012b536e6e0 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:22:41 +0400 Subject: [PATCH 032/107] Test the dataset-independent key's index on that key alone (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 25's revision now indexes reports' dataset_independent_key alone, as ix_reports_dataset_independent_key, in place of the index on (key_version, dataset_independent_key): the app finds a report on another dataset by that key alone (approved by the user on 2026-11-14). Co-Authored-By: Claude Opus 5.5 --- .../tests/test_tables.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/libs/policyengine-simulation-persistence/tests/test_tables.py b/libs/policyengine-simulation-persistence/tests/test_tables.py index c2ac9254c..a9ae9a415 100644 --- a/libs/policyengine-simulation-persistence/tests/test_tables.py +++ b/libs/policyengine-simulation-persistence/tests/test_tables.py @@ -230,9 +230,10 @@ def test_simulations_and_reports_are_unique_on_their_definition_key() -> None: "definition_key", ) assert reports.c.dataset_independent_key.nullable is True - assert _indexed_columns( - reports, "ix_reports_key_version_dataset_independent_key" - ) == ("key_version", "dataset_independent_key") + # 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: From 6181ae6b71f638d94ec25d8de6dcdbe11dd32f6e Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:23:15 +0400 Subject: [PATCH 033/107] Model the index on the dataset-independent key alone MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sim's reports model declares ix_reports_dataset_independent_key on dataset_independent_key, as C1 · 25's revision now does, in place of the index on (key_version, dataset_independent_key). The models match the Public API's tables at C1 · 25's commit f3705ca9f. Co-Authored-By: Claude Opus 5.5 --- .../src/policyengine_simulation_persistence/tables.py | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) 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 bd19d23e4..8a561cb50 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/tables.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/tables.py @@ -401,12 +401,9 @@ def _public_api_key( "definition_key", name="uq_reports_key_version_definition_key", ), - # Reports that differ only in their dataset share this key. - Index( - "ix_reports_key_version_dataset_independent_key", - "key_version", - "dataset_independent_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. From d1afb83efb03f6b637a676ef50175eebce27fff2 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:24:17 +0400 Subject: [PATCH 034/107] Seed rows the service could write, and check the 503 starts no call (review round 2) - The later run the re-run tests reuse is used by another report created on the earlier catalog beside the stored one, naming the same simulations, whose manual re-run on the later catalog succeeded; the test rows' report run takes its trigger. - The newest-run read's forced report runs name forced simulation runs of their own, as a forced re-run creates them. - The test of a run that keeps failing before it is read also checks that no Modal call was started. Co-Authored-By: Claude Opus 5.5 --- .../tests/economy_rows.py | 5 ++-- .../tests/test_economy_reruns.py | 26 +++++++++++-------- .../tests/test_economy_run_reads.py | 13 +++++++--- .../tests/test_economy_reruns.py | 4 ++- 4 files changed, 31 insertions(+), 17 deletions(-) diff --git a/libs/policyengine-simulation-persistence/tests/economy_rows.py b/libs/policyengine-simulation-persistence/tests/economy_rows.py index 0bc78c70b..0b90d3a24 100644 --- a/libs/policyengine-simulation-persistence/tests/economy_rows.py +++ b/libs/policyengine-simulation-persistence/tests/economy_rows.py @@ -221,12 +221,13 @@ def insert_run_of( @dataclass(frozen=True) class ReportRunOutcome: - """How a stored report run ended, its versions, and its report's options.""" + """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( @@ -304,7 +305,7 @@ def insert_report_run_of( 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, ) diff --git a/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py b/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py index 01d6daf19..85e25636c 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py @@ -273,13 +273,17 @@ def _find_later_run_of( def _used_on_later_catalog( - connection: Connection, stored: StoredReport, later: EconomyCatalog + connection: Connection, + stored: StoredReport, + economy: EconomyCatalog, + later: EconomyCatalog, ) -> StoredRun: """Insert a succeeded later run of the baseline that another report used. - The other report, created on the later catalog, reused the baseline's - run; its succeeded run is on the later versions. The stored report itself - has no run on them, so a re-run of it has none to join. + The other report, created on ``economy`` beside the stored one, reused + its simulations' runs; its re-run on the later catalog created the later + runs, and succeeded. The stored report itself has no run on the later + versions, so a re-run of it has none to join. """ later_shape = RunShape(versions=LATER_VERSIONS) later_baseline = insert_run_of( @@ -292,13 +296,13 @@ def _used_on_later_catalog( replace(later_shape, status=SimulationStatus.FAILED), ) other_report_id = insert_report_of( - connection, later, (later_baseline, later_reform) + connection, economy, (stored.baseline, stored.reform) ) insert_report_run_of( connection, other_report_id, (later_baseline, later_reform), - ReportRunOutcome(versions=LATER_VERSIONS), + ReportRunOutcome(versions=LATER_VERSIONS, trigger=ReportRunTrigger.MANUAL), ) return later_baseline @@ -310,7 +314,7 @@ def test_a_simulations_own_run_on_a_later_catalog_version_is_reused( 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) + later_baseline = _used_on_later_catalog(connection, stored, economy, later) act_as_the_service(connection) found = _find_later_run_of(connection, stored.baseline.simulation_id, later) @@ -345,7 +349,7 @@ def test_another_simulations_run_is_not_reused_for_a_simulations_rerun( economy = insert_economy_catalog(connection) later = insert_later_catalog(connection, economy) stored = _stored_report(connection, economy) - _used_on_later_catalog(connection, stored, later) + _used_on_later_catalog(connection, stored, economy, later) other = _stored_report(connection, economy) act_as_the_service(connection) @@ -394,7 +398,7 @@ def test_a_report_rerun_creates_runs_of_the_reports_own_simulations( economy = insert_economy_catalog(connection) later = insert_later_catalog(connection, economy) stored = _stored_report(connection, economy) - reused = _used_on_later_catalog(connection, stored, later) + reused = _used_on_later_catalog(connection, stored, economy, later) rerun = _rerun_of(stored, later, baseline_reused=reused) act_as_the_service(connection) @@ -660,7 +664,7 @@ 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) + reused = _used_on_later_catalog(connection, stored, economy, later) act_as_the_service(connection) store = _store_on(connection) sides = { @@ -694,7 +698,7 @@ def test_both_sides_of_one_simulation_never_reuse_the_same_run( economy = insert_economy_catalog(connection) later = insert_later_catalog(connection, economy) stored = _stored_report(connection, economy) - reused = _used_on_later_catalog(connection, stored, later) + reused = _used_on_later_catalog(connection, stored, economy, later) act_as_the_service(connection) side = SideDefinition(stored.baseline.simulation_id, CURRENT_LAW) 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 679e040f5..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 ( @@ -43,7 +44,8 @@ def _report_with_runs(connection, economy: EconomyCatalog) -> tuple[UUID, list[U 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. + 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) @@ -63,14 +65,19 @@ 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, diff --git a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py index 4b80b36e3..b9257c5ac 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py @@ -385,12 +385,14 @@ def test_a_run_that_keeps_failing_before_it_is_read_is_answered_unavailable( ) -> 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)) + 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: From b8c34880b6449c50c7fbdf42fa1e3ede5679183d Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:25:43 +0400 Subject: [PATCH 035/107] Say how each kind of re-run is answered (review round 2) Review round 2's bug and documentation findings: - A re-run whose side's insert the run index refuses is answered 503 database_unavailable, which the entry README and insert_report_rerun now say, with the likelier cases: a succeeded side run whose report run failed, or one a coordinator refused. Finding sides' runs by version set (answers 4 and 5) removes it. - A household report's re-run ignores force: the 409 description, the conflict code's comment, ReportRerunRequest, the route description and module docstring, the README's lock paragraph and lock_reruns_of say it takes the lock and is refused while any run is under way, forced or not, and that a second budget-window or household re-run is refused where an economy one joins. - The reuse conditions in both READMEs leave out forced runs, the join sentence names unforced runs, and the persistence README's window paragraph says a recalculating re-run is never refused. - The staging script prints what the report request answered, and the workflow's job comment and step name say the check forces a run. Co-Authored-By: Claude Opus 5.5 --- .../simulation-staging-economy-check.sh | 2 +- .../workflows/simulation-deploy.reusable.yml | 9 ++-- .../README.md | 10 ++-- .../economy_rerun_records.py | 16 ++++--- .../policyengine-simulation-entry/README.md | 39 +++++++++------- .../economy_api_models.py | 17 ++++--- .../economy_rerun_routes.py | 46 +++++++++++-------- .../economy_reruns.py | 4 +- 8 files changed, 83 insertions(+), 60 deletions(-) diff --git a/.github/scripts/simulation-staging-economy-check.sh b/.github/scripts/simulation-staging-economy-check.sh index b73198890..6f420c2fb 100755 --- a/.github/scripts/simulation-staging-economy-check.sh +++ b/.github/scripts/simulation-staging-economy-check.sh @@ -93,7 +93,7 @@ report_id="$(jq -r '.report_id // empty' "${submission}")" found_run_id="$(jq -r '.report_run_id // empty' "${submission}")" [[ "${report_id}" =~ ${uuid_pattern} ]] || fail "the submission named no report" [[ "${found_run_id}" =~ ${uuid_pattern} ]] || fail "the submission named no report run" -printf 'Found or created report %s, run %s (%s)\n' \ +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" diff --git a/.github/workflows/simulation-deploy.reusable.yml b/.github/workflows/simulation-deploy.reusable.yml index 1707731d6..49f939272 100644 --- a/.github/workflows/simulation-deploy.reusable.yml +++ b/.github/workflows/simulation-deploy.reusable.yml @@ -1255,9 +1255,10 @@ jobs: staging_economy_check: name: Create a staging economy report through the candidate - # Every staging deployment creates a small economy report, current law - # against current law for Wales in 2026, through the candidate's - # POST /reports, and requires its run to succeed. The routes use only + # Every staging deployment sends a small economy report request, current + # law against current law for Wales in 2026, through the candidate's + # POST /reports, forces a new run of the report, and requires that run + # to succeed. The routes use only # the v2 manifest's default worker, so the check runs after the default # has moved to the release's worker (or, in a deployment without Stage # 12, with the default as it is). It calls the tagged candidate URL, @@ -1283,7 +1284,7 @@ jobs: steps: - uses: actions/checkout@v6 - - name: Create the staging economy report and require its run to succeed + - name: Force a run of the staging economy report and require it to succeed env: SIMULATION_TEST_AUTH_ISSUER: ${{ secrets.SIMULATION_ENTRYPOINT_AUTH_ISSUER }} SIMULATION_TEST_AUTH_AUDIENCE: ${{ secrets.SIMULATION_ENTRYPOINT_AUTH_AUDIENCE }} diff --git a/libs/policyengine-simulation-persistence/README.md b/libs/policyengine-simulation-persistence/README.md index cc1e32b89..4ba7a9643 100644 --- a/libs/policyengine-simulation-persistence/README.md +++ b/libs/policyengine-simulation-persistence/README.md @@ -163,7 +163,7 @@ version, dataset and region it calculates on. - `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 + with the same options, no refused reuse, not forced); it doesn't compare the simulation row, which keeps the catalog rows it was created on. - `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), @@ -185,9 +185,11 @@ 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`. +report run per year and each year's new runs of its own simulations. An +unforced window re-run is refused while a budget-window run or a report run +of the report is `pending` or `running`; one that recalculates is a forced +re-run, never refused, whose year runs and simulation runs are marked +`forced`. A household report's definition also names its household (`household_id`). `insert_household_report_rerun` creates its new report run (trigger 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 6ca1e4ae6..2ca0af8f4 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 @@ -510,10 +510,13 @@ 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 unforced re-run of the same report waits - here until the first one's transaction ends, then sees its run. A - simulation's re-run and a forced one take none: the Public API's index - on runs lets one joinable run exist, and nothing joins a forced 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 + report's re-run joins and a budget-window or household report's is + refused for. 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 economy + or budget-window re-run, which nothing joins; a household report's + re-run takes it, forced or not. """ connection.execute( select( @@ -555,8 +558,9 @@ def insert_report_rerun( simulation has another run on these versions that hasn't failed (one another report run is calculating, or one ``find_reusable_run_of`` didn't offer), the Public API's index refuses it and the database error - propagates; finding a side's run by version set waits for C1 · 24's - answers 4 and 5. + propagates, which the service answers 503 ``database_unavailable``; + finding a side's run by version set waits for C1 · 24's answers 4 and + 5. Raise RerunRecordDeletedError when the database refuses the new run's key to the report, which no longer exists, and diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index be5f4d76c..89f791db5 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -129,7 +129,8 @@ 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 +options used it, no report run has refused to reuse it, and it wasn't +a forced re-run's (nothing reuses those); 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, @@ -240,8 +241,8 @@ both again, as an extra run: the new report run and both simulation runs are marked `forced`, so nothing joins them, and a forced re-run is never refused while a run is under way. The new report run's trigger is `manual`. Without `force`, a re-run while the report has a run on the default -worker's versions that hasn't failed, pending, running or succeeded, joins -that run instead and answers it as it is, with both sides reused and no +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. 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 @@ -288,19 +289,25 @@ 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`. An unforced report re-run (economy, budget-window or -household) looks for the run to join, or for a run under way, and inserts -under a transaction-level advisory lock on the report's ID, so two such -re-runs of one report end on one run. A simulation's re-run takes no lock: -the Public API's index on runs lets only one run that hasn't failed exist on -a version set, so concurrent re-runs end on it. A forced re-run takes none -either, as nothing joins it. A household report's re-run, forced or not, is -still refused with 409 `run_in_progress` while any run of the report is -pending or running. Until a report's sides find their simulation runs by -version set (C1 · 24's answers 4 and 5), an unforced economy report re-run -whose side has a run on the current versions that hasn't failed but isn't -reused (one another report run is calculating, or one used with other -options) is refused by that index and answered 500. A re-run's answer names +`not_configured`. An unforced economy or budget-window report re-run, and +every household report re-run, looks for the run to join, or for a run +under way, and inserts under a transaction-level advisory lock on the +report's ID: a second economy report re-run waits, then joins the first's +run; a second budget-window or household one waits, then is refused with +409 naming it. A simulation's re-run takes no lock: the Public API's index +on runs lets only one run that hasn't failed exist on a version set, so +concurrent re-runs end on it. A forced economy or budget-window re-run +takes none either, as nothing joins it. A household report's re-run ignores +`force`, so it takes the lock and is refused with 409 `run_in_progress` +while any run of the report is pending or running. Until a report's sides +find their simulation runs by version set (C1 · 24's answers 4 and 5), an +unforced economy report re-run whose side has a run on the current +versions that hasn't failed but isn't reused is refused by that index: +for example a succeeded run whose report run failed for the other side, +one a coordinator refused to reuse, one used with other options, or one +another report run is calculating. The service answers that database error +503 `database_unavailable`, though asking again fails the same way while +that run is there. 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 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 d384ff352..e83f0db0a 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 @@ -89,9 +89,10 @@ # Why a stored record is not re-run now (409). EconomyConflictCode = Literal[ # A budget-window report has a window run or year run pending or - # running, or a household report a run, and the re-run isn't forced; - # ``run_id`` names the budget-window run, or else the report run. An - # economy report's or a simulation's re-run joins its run instead. + # running and the re-run isn't forced, or a household report has a run + # pending or running, forced or not; ``run_id`` names the budget-window + # run, or else the report run. An economy report's or a simulation's + # re-run joins its run instead. "run_in_progress", # The service does not re-run this kind of record, or the record lacks a # row it calculates on. @@ -200,10 +201,12 @@ class ReportRerunRequest(_Request): """A stored report's re-run on the default worker's versions. Without ``force``, an economy report's re-run joins the report's run on - those versions that hasn't failed, pending, running or succeeded, and - otherwise a side reuses a run of its own simulation that succeeded on - them, as a new report's side does. With it, both simulations are - calculated again, as an extra run marked forced that nothing joins. + those versions that hasn't failed and wasn't forced, pending, running or + succeeded, and otherwise a side reuses a run of its own simulation that + succeeded on them, as a new report's side does. With it, an economy or + budget-window report's simulations are calculated again, as an extra run + marked forced that nothing joins; a household report's re-run ignores + it. """ force: StrictBool = False 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 48c5b2d64..a09affb6c 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,11 +1,13 @@ """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. + 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. For an economy or budget-window + report, ``{"force": true}`` calculates both simulations again, as an + extra run marked forced that nothing joins; 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 @@ -19,12 +21,14 @@ and its status. Every earlier run is kept. A re-run answers 404 for a record that does not -exist, and 409 while a budget window's run of the report is pending or -running, unless the re-run is forced (``run_in_progress``, naming it in -``run_id``), or for a record this service does not re-run -(``rerun_not_supported``); then nothing is written. Without ``force``, a -report's re-run joins the report's run on the current versions that hasn't -failed, pending, running or succeeded, and answers it with no new call. The other +exist, and 409 (``run_in_progress``, naming the run in ``run_id``) while a +budget-window report has a window run or year run pending or running and +the re-run isn't forced, or while a household report has a run pending or +running (a household re-run ignores ``force``), or for a record this +service does not re-run (``rerun_not_supported``); then nothing is +written. Without ``force``, an economy 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. 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, @@ -118,10 +122,10 @@ class EconomyService(EconomySubmissions, EconomyReruns, Protocol): _CONFLICTS: dict[RecordName, str] = { "report": ( "a budget-window report has a window run or year run pending or " - "running, or a household report a run, and the re-run isn't forced " - "(run_in_progress; run_id names the report's budget-window run, or " - "else its report run), or the service does not re-run it " - "(rerun_not_supported)" + "running and the re-run isn't forced, or a household report has a " + "run pending or running, forced or not (run_in_progress; run_id " + "names the report's budget-window run, or else its report run), or " + "the service does not re-run it (rerun_not_supported)" ), "simulation": "the service does not re-run it (rerun_not_supported)", } @@ -284,11 +288,13 @@ async def answer( # the route, its record and how to re-run it "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, an economy report's re-run joins the report's run on those " - "versions that hasn't failed, pending, running or succeeded, and " - "answers it with no new call; otherwise a side reuses a run of its " - "own simulation that succeeded on the same versions. With force, " - "both simulations are calculated again, as an extra run marked " - "forced that nothing joins. A budget-window report's new run is a " + "versions that hasn't failed and wasn't forced, pending, running " + "or succeeded, and answers it with no new call; otherwise a side " + "reuses a run of its own simulation that succeeded on the same " + "versions. With force, an economy or budget-window report's " + "simulations are calculated again, as an extra run marked forced " + "that nothing joins; a household report's re-run ignores force. " + "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 " 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 bb2a3c6f6..fc573441b 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 @@ -21,8 +21,8 @@ with trigger ``manual``) and each report side's new simulation run of its own simulation, all pending with no Modal call ID. A forced re-run always creates its runs, marked forced, an extra run that nothing joins. - A budget window's re-run is refused while a window run of the report is - pending or running (409 ``run_in_progress``); + An unforced budget window's re-run is refused while a window run or year + run of the report is pending or running (409 ``run_in_progress``); 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 From d904d337b8a6f52797ff8dd2bb1e1e2a0ad60720 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:27:38 +0400 Subject: [PATCH 036/107] Test the dataset-independent key: the report key without its dataset (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's revised answer 1a (2026-11-14): dataset_independent_key is the report's key object without the dataset, keeping the options, under its own record name, so a national report matches exactly the local-area report with the same options. Reports differing only in their dataset share it; other options or another region don't. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_definition_keys.py | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/libs/policyengine-simulation-persistence/tests/test_definition_keys.py b/libs/policyengine-simulation-persistence/tests/test_definition_keys.py index 6d240a363..a1505fd68 100644 --- a/libs/policyengine-simulation-persistence/tests/test_definition_keys.py +++ b/libs/policyengine-simulation-persistence/tests/test_definition_keys.py @@ -121,3 +121,34 @@ def test_each_part_of_a_report_definition_changes_its_key() -> None: ] assert len({variant.definition_key for variant in variants}) == len(variants) + + +def test_the_dataset_independent_key_is_the_report_key_without_its_dataset() -> None: + """Revised answer 1a: the options stay, so each national report has one match.""" + 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] == "b00bdfd986dd6ab7" + + +def test_reports_differing_only_in_their_dataset_share_that_key() -> None: + national = _report_n() + local_area = _report_n(dataset_name=LOCAL_AREA_DATASET) + with_cliffs = _report_n( + dataset_name=LOCAL_AREA_DATASET, options={"include_cliffs": True} + ) + 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 with_cliffs.dataset_independent_key != national.dataset_independent_key + assert other_region.dataset_independent_key != national.dataset_independent_key From 413e453162ca02653c688555612c7470391f9ddf Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:27:54 +0400 Subject: [PATCH 037/107] Build the dataset-independent key of an economy report MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit EconomyReportDefinition's dataset_independent_key hashes its key object without the dataset, record "report_dataset_independent", keeping the options (C1 · 24's revised answer 1a). It is derived from the same object as the definition key, so a later change to the options (question 4 may take include_cliffs out) changes both together. Co-Authored-By: Claude Opus 5.5 --- .../definition_keys.py | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) 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 index b0d7926dd..a8a8c2aa6 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/definition_keys.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/definition_keys.py @@ -11,7 +11,10 @@ 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. +releases, and each release's calculation is a new run of it. A report also +stores a ``dataset_independent_key``: its key object without the dataset, +keeping the options (C1 · 24's revised answer 1a), which a national report +and its local-area report with the same options share. """ from __future__ import annotations @@ -107,3 +110,15 @@ def key_object(self) -> dict[str, object]: 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()) From 124d632bb0da0687e214243c73ef4d364d926b06 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:41:26 +0400 Subject: [PATCH 038/107] Describe each re-run's joining exactly, and seed realistic rows (review round 3) Review round 3 found no bugs; its quality findings: - economy_rerun_records' module docstring and step 3 of economy_reruns say that only a simulation's and an unforced economy report's re-run join, that window and household re-runs are refused while a run is under way, and which take the lock; the simulation re-run route says it joins only an unforced run. - The entry README says a household report's re-run, and an unforced window re-run with an unreused side run on the current versions, are refused by the run index and answered 503 too, until answer 8. - The later run the re-run tests reuse comes from another report comparing the stored baseline with a reform of its own, whose initial run and manual re-run both succeeded; the Stage 12 sweep test's report copy has no definition keys, so it can never conflict with the report it copies. Co-Authored-By: Claude Opus 5.5 --- .../economy_rerun_records.py | 21 +++++++------ .../tests/test_economy_reruns.py | 31 +++++++++---------- .../tests/test_report_run_sweep_store.py | 26 +++++++++------- .../policyengine-simulation-entry/README.md | 9 ++++-- .../economy_rerun_routes.py | 11 ++++--- .../economy_reruns.py | 11 ++++--- 6 files changed, 60 insertions(+), 49 deletions(-) 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 2ca0af8f4..93fe2c6cd 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 @@ -19,15 +19,18 @@ 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. A re-run joins the record's run that hasn't failed on the -current versions, when there is one, pending, running or succeeded, rather -than create one (C1 · 24's answers 2 and 3; ``shared_rows``): a -simulation's run on those versions, catalog version and year, or a -report's run on those versions. A report's re-run takes a -transaction-level advisory lock on its 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; nothing is created while a budget window's -run of the report is ``pending`` or ``running``. +calculates on. A simulation's re-run, and an unforced economy 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 and 3; ``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, and every household report's, joins nothing: it is refused while a +run of the report is ``pending`` or ``running`` (a budget-window run or a +report run). 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 diff --git a/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py b/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py index 85e25636c..c0ddff96b 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py @@ -280,28 +280,27 @@ def _used_on_later_catalog( ) -> StoredRun: """Insert a succeeded later run of the baseline that another report used. - The other report, created on ``economy`` beside the stored one, reused - its simulations' runs; its re-run on the later catalog created the later - runs, and succeeded. The stored report itself has no run on the later - versions, so a re-run of it has none to join. + The other report, created on ``economy`` beside the stored one, compares + the stored report's baseline simulation (reusing 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. """ - later_shape = RunShape(versions=LATER_VERSIONS) - later_baseline = insert_run_of( - connection, stored.baseline.simulation_id, later.population(), later_shape - ) - later_reform = insert_run_of( - connection, - stored.reform.simulation_id, - later.population(), - replace(later_shape, status=SimulationStatus.FAILED), - ) + other_reform = insert_simulation_run(connection, economy.population()) other_report_id = insert_report_of( - connection, economy, (stored.baseline, stored.reform) + 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, 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) ) insert_report_run_of( connection, other_report_id, - (later_baseline, later_reform), + (later_baseline, later_other_reform), ReportRunOutcome(versions=LATER_VERSIONS, trigger=ReportRunTrigger.MANUAL), ) return later_baseline 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 ba9358c57..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 @@ -370,22 +370,26 @@ def _second_report_run( # noqa: PLR0913 # the run, then what it names and whos 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.""" + """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( - { - **{ - name: value - for name, value in report.items() - if name not in {"id", "created_at", "updated_at"} - }, - "id": copy_id, - } - ) + insert(seeder.table("reports")).values({**copied, "id": copy_id}) ) return copy_id diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index 89f791db5..ca26db0ec 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -305,9 +305,12 @@ unforced economy report re-run whose side has a run on the current versions that hasn't failed but isn't reused is refused by that index: for example a succeeded run whose report run failed for the other side, one a coordinator refused to reuse, one used with other options, or one -another report run is calculating. The service answers that database error -503 `database_unavailable`, though asking again fails the same way while -that run is there. A re-run's answer names +another report run is calculating. So, until C1 · 24's answer 8, is a +household report's re-run, forced or not, once its earlier run has ended +on the current versions without failing (each side's new run is unforced), +and an unforced budget window's whose year side has such a run. The +service answers that database error 503 `database_unavailable`, though +asking again fails the same way while that run is there. 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 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 a09affb6c..f8d4485a1 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 @@ -15,8 +15,9 @@ 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``) joins - the stored simulation's run on the current versions that hasn't failed, - pending, running or succeeded, or else creates one and starts its + 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. @@ -330,9 +331,9 @@ async def rerun_report( summary="Re-run an economy simulation", description=( "Join the stored simulation's run on the v2 version manifest's " - "default worker's versions that hasn't failed, pending, running or " - "succeeded, or else create one and start it; every earlier run is " - "kept." + "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 fc573441b..009fa43e0 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 @@ -15,11 +15,12 @@ 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. 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 (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. A forced re-run +3. for a simulation or an 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 (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; a budget window's re-run always creates its runs. A forced re-run always creates its runs, marked forced, an extra run that nothing joins. An unforced budget window's re-run is refused while a window run or year run of the report is pending or running (409 ``run_in_progress``); From 5ed8c9b37fe57d4fc3c1021bd6be2ef059773512 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:14:42 +0400 Subject: [PATCH 039/107] Test a report run naming one simulation run on both sides (failing) Under the shared-report keys, a report whose baseline and reform have the same policy and dynamic names one simulation, and one run of it, on both sides. The contract refuses that today: ReportRunIds requires three different runs, and ReportExecutionInput different execution IDs. Co-Authored-By: Claude Opus 5.5 --- .../test_stage12_one_simulation_report.py | 113 ++++++++++++++++++ .../tests/test_stage12_report_run_ids.py | 23 +++- 2 files changed, 133 insertions(+), 3 deletions(-) create mode 100644 libs/policyengine-simulation-contract/tests/test_stage12_one_simulation_report.py diff --git a/libs/policyengine-simulation-contract/tests/test_stage12_one_simulation_report.py b/libs/policyengine-simulation-contract/tests/test_stage12_one_simulation_report.py new file mode 100644 index 000000000..079b6b211 --- /dev/null +++ b/libs/policyengine-simulation-contract/tests/test_stage12_one_simulation_report.py @@ -0,0 +1,113 @@ +"""A report input may compare one simulation, calculated once, with itself. + +A report whose baseline and reform have the same policy and dynamic names one +simulation and one run of it on both sides. Its two inputs then carry that +run's ID as their execution ID, and must be the same simulation in every +other way too, policy included. +""" + +from __future__ import annotations + +from uuid import UUID + +import pytest +from policyengine_simulation_contract.stage12_execution import ( + BundleProvenance, + DatasetArtifactMediaType, + DatasetArtifactReference, + DatasetPopulationInput, + DatasetProvenance, + GeographySelection, + ReportAggregate, + ReportExecutionInput, + SimulationExecutionInput, + SimulationRole, +) +from pydantic import JsonValue, ValidationError + +REPORT_RUN_ID = UUID("00000000-0000-0000-0000-0000000000a1") +SIMULATION_RUN_ID = UUID("00000000-0000-0000-0000-0000000000b1") +OTHER_SIMULATION_RUN_ID = UUID("00000000-0000-0000-0000-0000000000c1") +DATASET_URI = "hf://policyengine/data/microcosm_uk_2024_25.h5@revision" +REFORM_POLICY: dict[str, JsonValue] = { + "gov.hmrc.income_tax.allowances.personal_allowance.amount": { + "2026-01-01": 13_000 + } +} + + +def _side( + role: SimulationRole, + simulation_run_id: UUID, + *, + policy: dict[str, JsonValue] | None = None, +) -> SimulationExecutionInput: + return SimulationExecutionInput( + evaluation_id=REPORT_RUN_ID, + simulation_execution_id=simulation_run_id, + role=role, + policy=policy or {}, + population=DatasetPopulationInput( + artifact=DatasetArtifactReference( + uri=DATASET_URI, + media_type=DatasetArtifactMediaType.HDF5, + content_sha256="d" * 64, + ) + ), + year=2026, + geography=GeographySelection(country="uk", region="country/wales"), + options={}, + bundle=BundleProvenance( + policyengine_version="6.17.1", + country_package_name="policyengine-uk", + country_package_version="2.174.1", + dataset=DatasetProvenance( + identity="microcosm_uk_2024_25", + uri=DATASET_URI, + artifact_revision="revision", + data_package_name="microcosm-uk", + data_package_version="1.0.0", + ), + bundle_manifest_sha256="b" * 64, + ), + ) + + +def _report( + baseline: SimulationExecutionInput, reform: SimulationExecutionInput +) -> ReportExecutionInput: + return ReportExecutionInput( + evaluation_id=REPORT_RUN_ID, + baseline=baseline, + reform=reform, + requested_aggregates=tuple(ReportAggregate), + ) + + +def test_a_report_may_name_one_simulation_run_on_both_sides() -> None: + report = _report( + _side(SimulationRole.BASELINE, SIMULATION_RUN_ID), + _side(SimulationRole.REFORM, SIMULATION_RUN_ID), + ) + + assert report.baseline.simulation_execution_id == SIMULATION_RUN_ID + assert report.reform.simulation_execution_id == SIMULATION_RUN_ID + + +def test_one_simulation_run_on_both_sides_must_have_one_policy() -> None: + with pytest.raises(ValidationError, match="one simulation run on both sides"): + _report( + _side(SimulationRole.BASELINE, SIMULATION_RUN_ID), + _side(SimulationRole.REFORM, SIMULATION_RUN_ID, policy=REFORM_POLICY), + ) + + +def test_two_simulation_runs_may_have_the_same_policy() -> None: + # A forced re-run of a report comparing a simulation with itself + # calculates two runs of it. + report = _report( + _side(SimulationRole.BASELINE, SIMULATION_RUN_ID), + _side(SimulationRole.REFORM, OTHER_SIMULATION_RUN_ID), + ) + + assert report.reform.simulation_execution_id == OTHER_SIMULATION_RUN_ID diff --git a/libs/policyengine-simulation-contract/tests/test_stage12_report_run_ids.py b/libs/policyengine-simulation-contract/tests/test_stage12_report_run_ids.py index a09cc387d..859ccc426 100644 --- a/libs/policyengine-simulation-contract/tests/test_stage12_report_run_ids.py +++ b/libs/policyengine-simulation-contract/tests/test_stage12_report_run_ids.py @@ -76,16 +76,33 @@ def test_each_role_names_its_own_simulation_run() -> None: [ {"baseline_simulation_run_id": REPORT_RUN_ID}, {"reform_simulation_run_id": REPORT_RUN_ID}, - {"reform_simulation_run_id": BASELINE_RUN_ID}, + { + "baseline_simulation_run_id": REPORT_RUN_ID, + "reform_simulation_run_id": REPORT_RUN_ID, + }, ], ) -def test_run_ids_must_name_three_different_runs(repeated_ids) -> None: +def test_the_report_run_must_differ_from_its_simulation_runs(repeated_ids) -> None: fields = {**_run_ids().model_dump(), **repeated_ids} - with pytest.raises(ValidationError, match="three different runs"): + with pytest.raises(ValidationError, match="differ from its simulation runs"): ReportRunIds(**fields) +def test_one_simulation_run_may_be_both_the_baseline_and_the_reform() -> None: + # A report comparing a simulation with itself names that simulation's run + # on both sides, since a simulation has one unfailed run per version set. + run_ids = ReportRunIds( + report_run_id=REPORT_RUN_ID, + baseline_simulation_run_id=BASELINE_RUN_ID, + reform_simulation_run_id=BASELINE_RUN_ID, + ) + + assert run_ids.names_one_simulation_run + assert run_ids.simulation_run_id(SimulationRole.REFORM) == BASELINE_RUN_ID + assert not _run_ids().names_one_simulation_run + + def test_a_shadow_comparison_run_cannot_record_report_runs() -> None: with pytest.raises(ValidationError, match="production function call"): Stage12InvocationContext( From ae48b44a04cb80796ff8cefdc0e44a23509c23ef Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:15:10 +0400 Subject: [PATCH 040/107] Accept a report run naming one simulation run on both sides ReportRunIds requires only that the report run differ from its simulation runs, and names_one_simulation_run says when both sides are one run. ReportExecutionInput lets the two inputs share an execution ID when they are the same simulation, policy included. Co-Authored-By: Claude Opus 5.5 --- .../stage12_execution/comparison_runs.py | 23 +++++++++++-------- .../stage12_execution/report_inputs.py | 20 ++++++++++++---- 2 files changed, 29 insertions(+), 14 deletions(-) diff --git a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/comparison_runs.py b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/comparison_runs.py index ba0207617..6f8b2e346 100644 --- a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/comparison_runs.py +++ b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/comparison_runs.py @@ -26,9 +26,11 @@ class ReportRunIds(StrictContractModel): """The Public API's report run and simulation runs one report call records on. - The simulation service creates the three rows before it starts the - coordinator. The coordinator records the report run's status and results, - and each worker it starts claims and records its own simulation run. + The simulation service creates the rows before it starts the coordinator. + The coordinator records the report run's status and results, and each + worker it starts claims and records its own simulation run. A report + comparing a simulation with itself names that simulation's one run on + both sides (``names_one_simulation_run``). """ report_run_id: UUID @@ -37,17 +39,20 @@ class ReportRunIds(StrictContractModel): @model_validator(mode="after") def validate_distinct_runs(self) -> ReportRunIds: - """Require the report run and both simulation runs to be different rows.""" - run_ids = { - self.report_run_id, + """Require the report run to be another row than its simulation runs.""" + if self.report_run_id in { self.baseline_simulation_run_id, self.reform_simulation_run_id, - } - if len(run_ids) != 3: # noqa: PLR2004 # one report run and two simulation runs - msg = "report run IDs must name three different runs" + }: + msg = "the report run must differ from its simulation runs" raise ValueError(msg) return self + @property + def names_one_simulation_run(self) -> bool: + """Whether the baseline and the reform are the same simulation run.""" + return self.baseline_simulation_run_id == self.reform_simulation_run_id + def simulation_run_id(self, role: SimulationRole) -> UUID: """Return the simulation run of ``role``; a standalone role has none.""" if role is SimulationRole.BASELINE: diff --git a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/report_inputs.py b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/report_inputs.py index 8d4a4ea42..029f212f1 100644 --- a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/report_inputs.py +++ b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/report_inputs.py @@ -161,7 +161,9 @@ class ReportExecutionInput(StrictContractModel): """A baseline and reform simulation pair to run and aggregate into one report. Both simulations must belong to this report, carry the baseline and reform - roles and distinct execution IDs, and differ only in their policy. + roles, and differ only in their policy. Their execution IDs differ, except + in a report that names one simulation run on both sides, whose two inputs + are then the same simulation, policy included. """ contract_version: Literal[1] = 1 @@ -174,8 +176,9 @@ class ReportExecutionInput(StrictContractModel): def require_aligned_simulations(self) -> ReportExecutionInput: """Check the two simulations form one comparable report. - Roles must be baseline and reform, both must belong to this report with - distinct execution ids, and everything but the policy must match. + Roles must be baseline and reform, both must belong to this report, + and everything but the policy must match. Inputs sharing one + execution ID name one simulation run, so their policies match too. """ if self.baseline.role is not SimulationRole.BASELINE: msg = "baseline input must use the baseline role" @@ -189,8 +192,15 @@ def require_aligned_simulations(self) -> ReportExecutionInput: if self.reform.evaluation_id != self.evaluation_id: msg = "reform evaluation_id must match the report" raise ValueError(msg) - if self.baseline.simulation_execution_id == self.reform.simulation_execution_id: - msg = "baseline and reform simulation identifiers must differ" + if ( + self.baseline.simulation_execution_id + == self.reform.simulation_execution_id + and self.baseline.policy != self.reform.policy + ): + msg = ( + "a report naming one simulation run on both sides must give " + "both the same policy" + ) raise ValueError(msg) for field_name in ( "population", From 74deda2d27ca42a93991e8cd0050a614d93c04db Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:47:25 +0400 Subject: [PATCH 041/107] Test the keys under answer 4: SPM in the simulation key, no report options (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's answer 4 (2026-11-14): a simulation is everything that changes its own numbers, so its key holds the SPM selection, as given or absent; a report is its two simulations and its window size, with no options of its own, so its key names the SPM selection once as a field both sides share and holds no include_cliffs, and its dataset-independent key is that key without the dataset. A report's sides are the simulations its definition names, each year's for a budget window, and current law against current law names one simulation on both sides. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_definition_keys.py | 107 ++++++++++++++---- 1 file changed, 84 insertions(+), 23 deletions(-) diff --git a/libs/policyengine-simulation-persistence/tests/test_definition_keys.py b/libs/policyengine-simulation-persistence/tests/test_definition_keys.py index a1505fd68..99de4fb75 100644 --- a/libs/policyengine-simulation-persistence/tests/test_definition_keys.py +++ b/libs/policyengine-simulation-persistence/tests/test_definition_keys.py @@ -11,16 +11,19 @@ from policyengine_simulation_persistence import ( KEY_VERSION, EconomyReportDefinition, + EconomySimulationDefinition, 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: @@ -33,11 +36,24 @@ def _report_n(**changes: Any) -> EconomyReportDefinition: region_code="uk", year=2026, budget_window_size=None, - options={"include_cliffs": False}, + 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", @@ -74,36 +90,62 @@ def test_a_value_json_has_no_form_for_is_refused() -> None: canonical_json({"value": {1, 2}}) -def test_the_proposals_worked_example_reports_have_its_keys() -> None: - """N, N2 and L of the proposal's worked example, by their first 16 digits.""" - report_n = _report_n() - report_n2 = _report_n(options={"include_cliffs": True}) - report_l = _report_n(dataset_name=LOCAL_AREA_DATASET, options={}) +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" - assert report_n.definition_key[:16] == "4bb1299756cb0a89" - assert report_n2.definition_key[:16] == "bb74ac904ed3a1c8" - assert report_l.definition_key[:16] == "907455a2702b0559" +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={}), + ] -def test_a_report_key_object_names_its_version_and_record() -> None: - assert KEY_VERSION == 1 + 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, - "options": {"include_cliffs": False}, "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: - dynamic_id = UUID("99999999-8888-7777-6666-555555555555") variants = [ _report_n(), _report_n(country="us"), @@ -111,20 +153,41 @@ def test_each_part_of_a_report_definition_changes_its_key() -> None: _report_n(region_code="country/wales"), _report_n(year=2027), _report_n(budget_window_size=10), - _report_n(options={"include_cliffs": True}), - _report_n(options={"include_cliffs": False, "spm": {"scenario": "low"}}), + _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) + reform=SimulationChoice(policy_id=REFORM_POLICY_ID, dynamic_id=DYNAMIC_ID) ), - _report_n(baseline=SimulationChoice(policy_id=None, 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: the options stay, so each national report has one match.""" + """Revised answer 1a and answer 4: the report key holds no options.""" report_n = _report_n() expected = { name: value @@ -135,20 +198,18 @@ def test_the_dataset_independent_key_is_the_report_key_without_its_dataset() -> assert report_n.dataset_independent_key_object() == expected assert report_n.dataset_independent_key == definition_key(expected) - assert report_n.dataset_independent_key[:16] == "b00bdfd986dd6ab7" + 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) - with_cliffs = _report_n( - dataset_name=LOCAL_AREA_DATASET, options={"include_cliffs": True} - ) + 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 with_cliffs.dataset_independent_key != national.dataset_independent_key + assert other_spm.dataset_independent_key != national.dataset_independent_key assert other_region.dataset_independent_key != national.dataset_independent_key From d61f2cdfd2851c0ec9d99cc12e796cce85ed63a1 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:48:00 +0400 Subject: [PATCH 042/107] Key simulations by everything that changes their numbers, reports by their sides MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Under C1 · 24's answer 4, EconomySimulationDefinition keys an economy simulation by its country, policy, dynamic, dataset name, region code, year, a null filter and the SPM selection as given or absent. An EconomyReportDefinition has no options: its key names each side's policy and dynamic, the dataset, region, year and SPM selection both sides share, and its window size; its dataset-independent key is that key without the dataset. A report's simulation() returns the simulation a side names, in the report's year or a window's later one. Co-Authored-By: Claude Opus 5.5 --- .../__init__.py | 2 + .../definition_keys.py | 85 ++++++++++++++++--- 2 files changed, 75 insertions(+), 12 deletions(-) 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 e1b8d65c0..782fe91fc 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py @@ -16,6 +16,7 @@ from policyengine_simulation_persistence.definition_keys import ( KEY_VERSION, EconomyReportDefinition, + EconomySimulationDefinition, canonical_json, definition_key, ) @@ -183,6 +184,7 @@ "EconomyReportState", "EconomyRequest", "EconomyRunStore", + "EconomySimulationDefinition", "EconomySimulationInputs", "EconomySimulationState", "FoundReportRun", 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 index a8a8c2aa6..e08539299 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/definition_keys.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/definition_keys.py @@ -11,10 +11,12 @@ 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 report also -stores a ``dataset_independent_key``: its key object without the dataset, -keeping the options (C1 · 24's revised answer 1a), which a national report -and its local-area report with the same options share. +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. """ from __future__ import annotations @@ -22,7 +24,7 @@ import hashlib import json from dataclasses import dataclass -from typing import TYPE_CHECKING, Any, Final +from typing import TYPE_CHECKING, Any, Final, Literal from uuid import UUID if TYPE_CHECKING: @@ -71,14 +73,57 @@ 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 (answer 1a). + """What identifies an economy report or a budget window (answers 1a and 4). - Each side's stored policy and dynamic (dynamics by ID, answer 1b), the - dataset name, region code and year both sides share, the window's size - (None for a single year) and the options as ``reports.inputs`` stores - them. Never a version: versions belong to runs. + 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 @@ -88,7 +133,7 @@ class EconomyReportDefinition: region_code: str year: int budget_window_size: int | None - options: Mapping[str, Any] + spm: Mapping[str, Any] | None def key_object(self) -> dict[str, object]: """Return the object whose canonical JSON the report's key hashes.""" @@ -103,7 +148,7 @@ def key_object(self) -> dict[str, object]: "region": self.region_code, "year": self.year, "budget_window_size": self.budget_window_size, - "options": dict(self.options), + "spm": _selection(self.spm), } @property @@ -122,3 +167,19 @@ def dataset_independent_key_object(self) -> dict[str, object]: 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, + ) From 18bd6e5a0850496d638bee0f1b8eb5bf7b838425 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:48:29 +0400 Subject: [PATCH 043/107] Format the one-run-on-both-sides check as the pinned Ruff does Co-Authored-By: Claude Opus 5.5 --- .../stage12_execution/report_inputs.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/report_inputs.py b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/report_inputs.py index 029f212f1..da65cad2f 100644 --- a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/report_inputs.py +++ b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/report_inputs.py @@ -193,8 +193,7 @@ def require_aligned_simulations(self) -> ReportExecutionInput: msg = "reform evaluation_id must match the report" raise ValueError(msg) if ( - self.baseline.simulation_execution_id - == self.reform.simulation_execution_id + self.baseline.simulation_execution_id == self.reform.simulation_execution_id and self.baseline.policy != self.reform.policy ): msg = ( From cda2e4e1e5445ee696999b4e6768c9d2dbe4284c Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:51:16 +0400 Subject: [PATCH 044/107] Test finding economy reports and simulations by key, or creating them (failing) In one transaction, each side's simulation by its key, the report by its key, then the report's run on the current versions that hasn't failed and wasn't forced, or else each simulation's run on those versions and a new report run naming them. Tests: a create stores the keys; an identical request ends on the same rows and inserts nothing; current law against current law names one simulation run on both sides; a report whose run failed gets a new run joining its unfailed simulation runs (answer 2); a forced run is never joined (answer 3); another SPM selection is another report (answer 4c); a side's run under way is joined (answer 5); a standalone simulation joins its run or creates it; two identical requests at once end on the same rows and start one call; a request losing the report run to another joins it and keeps nothing it inserted. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_keyed_economy_records.py | 580 ++++++++++++++++++ 1 file changed, 580 insertions(+) create mode 100644 libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py 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..07f993d9e --- /dev/null +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py @@ -0,0 +1,580 @@ +"""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 +import time +from dataclasses import replace +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 ( + CURRENT_LAW, + VERSIONS, + EconomyCatalog, + insert_economy_catalog, +) +from policyengine_simulation_persistence import ( + KEY_VERSION, + EconomyReportDefinition, + EconomySimulationDefinition, + KeyedEconomyReport, + KeyedEconomySimulation, + ProposedSide, + ReportRunStatus, + SimulationChoice, + SimulationStatus, + find_or_create_economy_report, + find_or_create_economy_simulation, + 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 Callable + + from sqlalchemy import Connection, Engine + +pytestmark = pytest.mark.public_api_schema + +LOCK_WAIT_TIMEOUT_SECONDS = 10.0 +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()), + label="Shared report", + description=None, + 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.inserted_simulation_run_ids == ( + 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", + ) + } == { + "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, + } + assert (baseline["key_version"], baseline["definition_key"]) == ( + KEY_VERSION, + definition.simulation("baseline").definition_key, + ) + assert reform["definition_key"] == definition.simulation("reform").definition_key + assert (run["status"], run["forced"], run["trigger"]) == ( + ReportRunStatus.PENDING, + False, + "initial", + ) + 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 again.inserted_simulation_run_ids == () + 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.inserted_simulation_run_ids == (request.baseline.simulation_run_id,) + 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 + assert second.inserted_simulation_run_ids == (second.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 _wait_until_another_backend_waits_for(engine: Engine, holder_pid: int) -> None: + """Return once a backend waits for a lock the backend ``holder_pid`` holds.""" + deadline = time.monotonic() + LOCK_WAIT_TIMEOUT_SECONDS + with engine.connect() as connection: + while time.monotonic() < deadline: + waiting = connection.execute( + text( + "SELECT count(*) FROM pg_stat_activity " + "WHERE :holder_pid = ANY(pg_blocking_pids(pid))" + ), + {"holder_pid": holder_pid}, + ).scalar_one() + connection.rollback() + if waiting: + return + 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] + + +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 From f3b16f7bfffb46ba16eca858ae6e501e1f337683 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:53:03 +0400 Subject: [PATCH 045/107] Find economy reports and simulations by key, with their runs, or create them MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit keyed_economy_records runs a report's find-or-create in one transaction: each side's simulation by key, in key order (one simulation when both sides share a key); the report by key, storing its definition and dataset-independent keys; the report's run on the current versions that hasn't failed and wasn't forced, which the request joins with the simulation runs it names; or else, in a savepoint, each distinct simulation's run on those versions found or inserted in simulation ID order, then the report run naming them, a competing report run joined with the savepoint rolled back. Any unfailed, unforced simulation run is joined, pending, running or succeeded (C1 · 24's answers 4 and 5). A standalone simulation and its run are found or created the same way. The answer says what the request inserted, so only it starts a Modal call. Co-Authored-By: Claude Opus 5.5 --- .../__init__.py | 18 + .../keyed_economy_records.py | 381 ++++++++++++++++++ 2 files changed, 399 insertions(+) create mode 100644 libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/keyed_economy_records.py 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 782fe91fc..e7854d3d5 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py @@ -125,6 +125,16 @@ 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.policy_reform import ( MissingPolicyParametersError, OverlappingReformError, @@ -187,8 +197,11 @@ "EconomySimulationDefinition", "EconomySimulationInputs", "EconomySimulationState", + "FoundEconomyReport", + "FoundEconomySimulation", "FoundReportRun", "FoundRow", + "FoundSide", "FoundSimulationRun", "HouseholdCalculationInputs", "HouseholdJobRecord", @@ -199,6 +212,8 @@ "HouseholdReportSimulation", "HouseholdReportStore", "HouseholdRerunSide", + "KeyedEconomyReport", + "KeyedEconomySimulation", "MissingPolicyParametersError", "NewBudgetWindowReport", "NewEconomyReport", @@ -211,6 +226,7 @@ "NewWindowRerun", "OverlappingReformError", "PolicyReform", + "ProposedSide", "RecordKind", "ReportDefinition", "ReportRunState", @@ -255,6 +271,8 @@ "fail_unstarted_report_run", "fail_unstarted_simulation_run", "find_joinable_report_run", + "find_or_create_economy_report", + "find_or_create_economy_simulation", "find_or_insert_report", "find_or_insert_report_run", "find_or_insert_simulation", 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..5f20903d7 --- /dev/null +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/keyed_economy_records.py @@ -0,0 +1,381 @@ +"""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, +) +from policyengine_simulation_persistence.tables import ( + ReportRunStatus, + ReportRunTrigger, + SimulationType, +) + +if TYPE_CHECKING: + 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). + ``label`` and ``description`` are stored only by the request that + creates the report. + """ + + definition: EconomyReportDefinition + report_id: UUID + run_id: UUID + baseline: ProposedSide + reform: ProposedSide + label: str + description: str | None + 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 + + +@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 + + @property + def inserted_simulation_run_ids(self) -> tuple[UUID, ...]: + """Return the simulation runs this request inserted, each once.""" + inserted = [ + side.simulation_run_id + for side in (self.baseline, self.reform) + if side.run_inserted + ] + return tuple(dict.fromkeys(inserted)) + + +@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, _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()) + # A report run another request inserts after the lookup is joined, + # and the savepoint takes back this request's simulation runs. + savepoint = connection.begin_nested() + try: + runs = _find_or_insert_simulation_runs(connection, request, simulation_ids) + side_runs: dict[Side, UUID] = { + side: runs[simulation_ids[side]].id for side in _SIDES + } + run = find_or_insert_report_run( + connection, _report_run_row(request, report.id, side_runs) + ) + except BaseException: + savepoint.rollback() + raise + if not run.inserted: + savepoint.rollback() + return _found(report.id, report.inserted, run, simulation_ids, set()) + savepoint.commit() + 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, + _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, + _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_simulation_runs( + connection: Connection, + request: KeyedEconomyReport, + simulation_ids: dict[Side, UUID], +) -> dict[UUID, FoundSimulationRun]: + """Return each distinct simulation's run, found or inserted, by simulation ID. + + Inserted in simulation ID order; one simulation on both sides gets one + run, with the baseline's proposed ID. + """ + proposed: dict[UUID, UUID] = {} + for side in reversed(_SIDES): + proposed[simulation_ids[side]] = getattr(request, side).simulation_run_id + return { + simulation_id: find_or_insert_simulation_run( + connection, + simulation_run_row( + run_id=proposed[simulation_id], + simulation_id=simulation_id, + population=request.population, + versions=request.versions, + ), + ) + for simulation_id in sorted(proposed) + } + + +def _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 _report_row( + request: KeyedEconomyReport, simulation_ids: dict[Side, UUID] +) -> dict[str, Any]: + """Return a keyed economy report as inserted, naming its sides' simulations.""" + definition = request.definition + population = request.population + return { + "id": request.report_id, + "label": request.label, + "description": request.description, + "country": definition.country, + "type": ECONOMY_REPORT_TYPE, + "user_id": None, + "tax_benefit_model_id": request.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": request.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, + side_runs: dict[Side, UUID], +) -> dict[str, Any]: + """Return the report's first run on these versions, naming its sides' runs.""" + return { + "id": request.run_id, + "report_id": report_id, + "baseline_simulation_run_id": side_runs["baseline"], + "reform_simulation_run_id": side_runs["reform"], + "budget_window_run_id": None, + "year": None, + "country_package_version": request.versions.country_package_version, + "policyengine_version": request.versions.policyengine_version, + "status": ReportRunStatus.PENDING, + "trigger": ReportRunTrigger.INITIAL, + "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"], + ) From b802f00fab2f4cbc60328bae6fa0d12357aec3c8 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:55:52 +0400 Subject: [PATCH 046/107] Test the service creating reports and simulations by key (failing) POST /reports and POST /simulations ask the store to find or create the record by key, with fresh IDs it uses only for rows it inserts, and look for no reusable run. The report's definition names the catalog's dataset and region, and the report stores only the SPM selection (answer 4). A request that joined a run answers it, with both sides reused, and starts no call; a side whose run another request inserted is named and answered reused; current law against current law names one simulation run on both sides; and a refused coordinator call fails only the report run, as the simulation runs may already be another report run's. The fake store answers creates by key. Co-Authored-By: Claude Opus 5.5 --- .../tests/economy_service_fakes.py | 75 ++++++- .../tests/test_economy_submissions.py | 206 ++++++++++++++---- 2 files changed, 227 insertions(+), 54 deletions(-) diff --git a/projects/policyengine-simulation-entry/tests/economy_service_fakes.py b/projects/policyengine-simulation-entry/tests/economy_service_fakes.py index 535873f0f..f947e6d55 100644 --- a/projects/policyengine-simulation-entry/tests/economy_service_fakes.py +++ b/projects/policyengine-simulation-entry/tests/economy_service_fakes.py @@ -34,6 +34,11 @@ EconomyReportState, EconomySimulationInputs, EconomySimulationState, + FoundEconomyReport, + FoundEconomySimulation, + FoundReportRun, + FoundSide, + FoundSimulationRun, ReportRunStatus, ReusableRun, SimulationInputs, @@ -45,8 +50,8 @@ from policyengine_simulation_persistence import ( EconomyRequest, - NewEconomyReport, - NewEconomySimulation, + KeyedEconomyReport, + KeyedEconomySimulation, RunReuse, SimulationChoice, ) @@ -115,12 +120,50 @@ 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 @@ -134,8 +177,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) @@ -184,15 +229,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 diff --git a/projects/policyengine-simulation-entry/tests/test_economy_submissions.py b/projects/policyengine-simulation-entry/tests/test_economy_submissions.py index 062fa9b7c..f9eaa8acd 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,7 +100,7 @@ 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() @@ -109,70 +115,141 @@ 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}/" - ) + # Runs are found by key, not searched for (C1 · 24). + assert reuse is None (report,) = store.reports - assert (report.id, report.run_id) == (UUID(int=1), UUID(int=2)) - assert (report.label, report.description, report.country) == ( + 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.label, report.description) == ( "A larger child tax credit", "Raises the credit to $3,000", - "us", ) 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 +261,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"}} @@ -202,7 +278,8 @@ def test_a_report_without_spm_settings_stores_none() -> None: 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} @@ -382,11 +459,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 +478,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 +493,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 +507,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 +525,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 +567,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( From 5b2133efc84ae342364459ebaa9be26558da65da Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:56:13 +0400 Subject: [PATCH 047/107] Test the store finding or creating by key in its own transaction (failing) Co-Authored-By: Claude Opus 5.5 --- .../tests/test_keyed_economy_records.py | 35 ++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py b/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py index 07f993d9e..9291e84d3 100644 --- a/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py @@ -13,6 +13,7 @@ import threading import time +from contextlib import contextmanager from dataclasses import replace from typing import TYPE_CHECKING, Any from uuid import UUID, uuid4 @@ -28,6 +29,7 @@ from policyengine_simulation_persistence import ( KEY_VERSION, EconomyReportDefinition, + EconomyRunStore, EconomySimulationDefinition, KeyedEconomyReport, KeyedEconomySimulation, @@ -44,7 +46,7 @@ from sqlalchemy import event, func, insert, select, text, update if TYPE_CHECKING: - from collections.abc import Callable + from collections.abc import Callable, Iterator from sqlalchemy import Connection, Engine @@ -578,3 +580,34 @@ def create_a_competing_run_first( 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, + ) From bb10db88944065305fafa26bd65d7c728c577d25 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:56:30 +0400 Subject: [PATCH 048/107] Find or create reports and simulations by key through the store EconomyRunStore's find_or_create_report and find_or_create_simulation run keyed_economy_records' find-or-create in a transaction of their own, answering a failed commit after the inserts as an unknown outcome, as the other creates do. Co-Authored-By: Claude Opus 5.5 --- .../economy_run_store.py | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) 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 c7cb13598..de1efc6f4 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 @@ -49,6 +49,10 @@ record_simulation_run_call, ) from policyengine_simulation_persistence.engine import bounded_transaction +from policyengine_simulation_persistence.keyed_economy_records import ( + find_or_create_economy_report, + find_or_create_economy_simulation, +) from policyengine_simulation_persistence.household_job_records import ( read_catalog_version_id, ) @@ -92,6 +96,12 @@ NewEconomyReport, NewEconomySimulation, ) + from policyengine_simulation_persistence.keyed_economy_records import ( + FoundEconomyReport, + FoundEconomySimulation, + KeyedEconomyReport, + KeyedEconomySimulation, + ) from policyengine_simulation_persistence.policy_reform import PolicyReform from policyengine_simulation_persistence.shared_rows import ( FoundReportRun, @@ -481,6 +491,28 @@ def create_budget_window_report(self, report: NewBudgetWindowReport) -> None: """ self._create(lambda connection: insert_budget_window_report(connection, report)) + def find_or_create_report(self, report: KeyedEconomyReport) -> FoundEconomyReport: + """Find the report by key, with its run, or create them. + + See ``find_or_create_economy_report``; raise its errors, and + EconomyRecordOutcomeUnknownError when the commit fails after the + rows were inserted. + """ + return self._create( + lambda connection: find_or_create_economy_report(connection, report) + ) + + def find_or_create_simulation( + self, simulation: KeyedEconomySimulation + ) -> FoundEconomySimulation: + """Find the simulation by key, with its run, or create them. + + Raise as ``find_or_create_report`` does. + """ + return self._create( + lambda connection: find_or_create_economy_simulation(connection, simulation) + ) + def create_report(self, report: NewEconomyReport) -> None: """Create the report, its new simulations and its runs. From a3aa206df6f26f87ea41af4ba61c042942b4bdc0 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:58:22 +0400 Subject: [PATCH 049/107] Move an economy request's types and input reads out of the store economy_run_store had grown past the 800-line limit. What a request is read from (EconomyRequest, the catalog rows and each side's inputs, the reuse search, and their errors) and the reads themselves move unchanged into economy_inputs, their helpers now public; the store keeps its transactions and re-exports the moved names, so every import path still works. The store's imports are also sorted (the previous commit's lint). Co-Authored-By: Claude Opus 5.5 --- .../economy_inputs.py | 400 ++++++++++++++++ .../economy_run_store.py | 446 +++--------------- 2 files changed, 456 insertions(+), 390 deletions(-) create mode 100644 libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_inputs.py 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..1f6c4402f --- /dev/null +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_inputs.py @@ -0,0 +1,400 @@ +"""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, with the runs a side may reuse +when a search is given. ``EconomyRunStore`` runs these in its transactions. +""" + +from __future__ import annotations + +from dataclasses import dataclass, replace +from typing import TYPE_CHECKING, Any, Literal, get_args + +from policyengine_simulation_persistence.economy_run_records import ( + CatalogDataset, + CatalogRegion, + EconomyPopulation, + ReusableRun, + RunVersions, + SimulationChoice, + find_reusable_run, + find_reusable_run_of, + 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 collections.abc import Callable, Iterable + 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"] +# 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 + + +@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]] + + +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( # 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 = read_side_values(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 read_window_sides( # 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 = read_side_values( + connection, request, catalog, "baseline", baseline + ) + reform_inputs = read_side_values(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 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 de1efc6f4..2f113c1bd 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 @@ -9,14 +9,33 @@ 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, + RunReuse, + SideRefusal, + SimulationInputs, + UnknownDatasetError, + UnknownRegionError, + read_catalog_rows, + read_report_sides, + read_simulation_values, + read_window_sides, + search_by_definition, + search_own_runs, +) from policyengine_simulation_persistence.economy_rerun_records import ( insert_report_rerun, insert_simulation_rerun, @@ -29,22 +48,11 @@ 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, ) @@ -53,24 +61,9 @@ find_or_create_economy_report, find_or_create_economy_simulation, ) -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 collections.abc import Callable, Iterable, Sequence + from collections.abc import Callable, Sequence from contextlib import AbstractContextManager from uuid import UUID @@ -102,7 +95,6 @@ KeyedEconomyReport, KeyedEconomySimulation, ) - from policyengine_simulation_persistence.policy_reform import PolicyReform from policyengine_simulation_persistence.shared_rows import ( FoundReportRun, FoundSimulationRun, @@ -113,45 +105,6 @@ ) 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): @@ -162,100 +115,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.""" @@ -276,7 +135,7 @@ def transaction() -> AbstractContextManager[Connection]: return cls(transaction) - def read_simulation_inputs( + def readread_simulation_values( self, request: EconomyRequest, choice: SimulationChoice ) -> EconomySimulationInputs: """Read a standalone simulation's catalog rows and values together. @@ -287,13 +146,13 @@ 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) - def read_report_inputs( + def readread_report_sides( self, request: EconomyRequest, *, @@ -309,15 +168,15 @@ def read_report_inputs( or ReportSideError naming the side whose policy or dynamic is refused. """ with self._transaction() as connection: - catalog = _catalog_rows(connection, request) + catalog = read_catalog_rows(connection, request) search = ( None if reuse is None - else _search_by_definition( + else search_by_definition( connection, catalog.population(request.year), reuse ) ) - return _report_inputs( + return read_report_sides( connection, request, catalog, @@ -355,11 +214,11 @@ def read_report_rerun_inputs( Raise the errors ``read_report_inputs`` raises. """ with self._transaction() as connection: - catalog = _catalog_rows(connection, request) + catalog = read_catalog_rows(connection, request) search = ( None if reuse is None - else _search_own_runs( + else search_own_runs( connection, catalog.population(request.year), reuse, @@ -369,7 +228,7 @@ def read_report_rerun_inputs( }, ) ) - return _report_inputs( + return read_report_sides( connection, request, catalog, @@ -395,8 +254,8 @@ def read_window_rerun_inputs( baseline's. Raise the errors ``read_report_inputs`` raises. """ with self._transaction() as connection: - catalog = _catalog_rows(connection, request) - return _window_inputs( + catalog = read_catalog_rows(connection, request) + return read_window_sides( connection, request, catalog, @@ -407,7 +266,7 @@ def read_window_rerun_inputs( window_year.year, None if reuse is None - else _search_own_runs( + else search_own_runs( connection, catalog.population(window_year.year), reuse, @@ -445,7 +304,7 @@ def create_simulation_rerun(self, rerun: NewSimulationRerun) -> FoundSimulationR lambda connection: insert_simulation_rerun(connection, rerun) ) - def read_budget_window_inputs( + def read_budgetread_window_sides( self, request: EconomyRequest, *, @@ -462,8 +321,8 @@ def read_budget_window_inputs( ``read_report_inputs`` raises. """ with self._transaction() as connection: - catalog = _catalog_rows(connection, request) - return _window_inputs( + catalog = read_catalog_rows(connection, request) + return read_window_sides( connection, request, catalog, @@ -474,7 +333,7 @@ def read_budget_window_inputs( year, None if reuse is None - else _search_by_definition( + else search_by_definition( connection, catalog.population(year), reuse ), ) @@ -608,213 +467,20 @@ 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", + "RunReuse", + "SideRefusal", + "SimulationInputs", + "TransactionFactory", + "UnknownDatasetError", + "UnknownRegionError", +] From e8c10097b856f11cd0b6e429526f66d4663ca39b Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:00:53 +0400 Subject: [PATCH 050/107] Restore the three store methods the move renamed by mistake Moving the input reads out of the store renamed their helpers by text, which also caught read_simulation_inputs, read_report_inputs and read_budget_window_inputs, the store's own methods. Their names are restored; nothing else in the move changed. Co-Authored-By: Claude Opus 5.5 --- .../economy_run_store.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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 2f113c1bd..f0c4e916c 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 @@ -135,7 +135,7 @@ def transaction() -> AbstractContextManager[Connection]: return cls(transaction) - def readread_simulation_values( + def read_simulation_inputs( self, request: EconomyRequest, choice: SimulationChoice ) -> EconomySimulationInputs: """Read a standalone simulation's catalog rows and values together. @@ -152,7 +152,7 @@ def readread_simulation_values( ) return EconomySimulationInputs(catalog=catalog, simulation=simulation) - def readread_report_sides( + def read_report_inputs( self, request: EconomyRequest, *, @@ -304,7 +304,7 @@ def create_simulation_rerun(self, rerun: NewSimulationRerun) -> FoundSimulationR lambda connection: insert_simulation_rerun(connection, rerun) ) - def read_budgetread_window_sides( + def read_budget_window_inputs( self, request: EconomyRequest, *, From 393050611d317f185adf0fe0d1ab13273afb86ae Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:00:55 +0400 Subject: [PATCH 051/107] Create economy reports and simulations by key, calling only for new runs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit POST /reports builds the report's definition from the catalog's dataset name and region code, the year, both sides' policies and dynamics and the SPM selection, and asks the store to find or create it with fresh IDs. Only a report run its own transaction inserted gets the coordinator's call, built from the runs it names (one simulation run on both sides for current law against current law); a joined run is answered with its status as read, both sides reused. The report stores only the SPM selection (C1 · 24's answer 4). A refused call fails only the report run, leaving its simulation runs for the next coordinator that names them. POST /simulations finds or creates the simulation and its run the same way. Creates no longer search for reusable runs. The fake store's current law sets no values. Co-Authored-By: Claude Opus 5.5 --- .../economy_submissions.py | 254 +++++++++++------- .../tests/economy_service_fakes.py | 5 +- 2 files changed, 157 insertions(+), 102 deletions(-) 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 5fe2d8f88..a6894bab4 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, @@ -96,6 +105,9 @@ EconomyReportState, EconomySimulationInputs, EconomySimulationState, + FoundEconomyReport, + FoundEconomySimulation, + RunReuse, SimulationInputs, ) @@ -144,12 +156,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( @@ -265,74 +279,67 @@ async def submit_report( """ 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, + reuse=None, ), 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, + baseline=self._proposed_side(), + reform=self._proposed_side(), 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, - 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, @@ -356,33 +363,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, ) @@ -414,6 +431,12 @@ async def _read_state[State](self, read: Callable[[], State]) -> State: ) raise _database_unavailable() from None + 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 _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: @@ -678,6 +701,35 @@ async def _record_call( return None if status is None else str(status) +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 diff --git a/projects/policyengine-simulation-entry/tests/economy_service_fakes.py b/projects/policyengine-simulation-entry/tests/economy_service_fakes.py index f947e6d55..89c41a20f 100644 --- a/projects/policyengine-simulation-entry/tests/economy_service_fakes.py +++ b/projects/policyengine-simulation-entry/tests/economy_service_fakes.py @@ -201,8 +201,11 @@ def read_report_inputs( baseline=SimulationInputs( choice=baseline, reform={}, reusable_run=baseline_reusable ), + # 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 {}, + reusable_run=reform_reusable, ), ) From 413b021eba0d5eb1d57ed1c913c6848494f50dc2 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:02:06 +0400 Subject: [PATCH 052/107] Describe creates by key in the README and the economy routes The README's economy section and the routes' notes and descriptions say how POST /reports and POST /simulations find or create by key, which runs they join, what a report stores and keys, that only a run the request created gets a call, and that a refused call fails the report run alone. Co-Authored-By: Claude Opus 5.5 --- .../policyengine-simulation-entry/README.md | 47 ++++++++++++------- .../economy_routes.py | 35 +++++++++----- 2 files changed, 51 insertions(+), 31 deletions(-) diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index ca26db0ec..48d4dbd36 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -122,21 +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, no report run has refused to reuse it, and it wasn't -a forced re-run's (nothing reuses those); 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 @@ -147,9 +156,11 @@ 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 `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. 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..903f8961c 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,8 +1,9 @@ """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 @@ -12,9 +13,11 @@ 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. +- ``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 @@ -531,10 +534,14 @@ 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 " @@ -578,9 +585,11 @@ 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, From 7224b9da9d1aa68b3b800485a3f085c79955a8e7 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:02:51 +0400 Subject: [PATCH 053/107] Test a keyed report's re-run joining each side's run on its versions (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A report created by key has only simulations whose runs C1 · 26's coordinator calculated with plans that don't depend on the report, so under C1 · 24's answers 4 and 5 a re-run's side joins its simulation's run on the current versions that hasn't failed and wasn't forced, in any state, rather than inserting one. The stored definition says whether a report is keyed. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_keyed_economy_records.py | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py b/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py index 9291e84d3..a32f0c882 100644 --- a/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py @@ -33,12 +33,16 @@ 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, ) @@ -611,3 +615,44 @@ def test_the_store_finds_or_creates_reports_and_simulations_in_a_transaction( 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(), reused=False), + reform=RerunSide(created.reform.simulation_id, uuid4(), reused=False), + sides_join_runs=True, + ) + + 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, + ) From e0a94ba105ebda3688774327ac0567810e8be3ec Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:03:46 +0400 Subject: [PATCH 054/107] Join each side's run on a keyed report's re-run MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A stored report's definition says whether it was created by key. A keyed report's unforced re-run (NewReportRerun.sides_join_runs) makes each side join its simulation's run on the re-run's versions that hasn't failed and wasn't forced, in any state, or insert one, in simulation ID order and once for one simulation on both sides, inside the re-run's savepoint (C1 · 24's answers 4 and 5). Other re-runs are unchanged until the user decides how a re-run of a report created before keys treats a run calculated with an older plan. Co-Authored-By: Claude Opus 5.5 --- .../economy_rerun_records.py | 82 +++++++++++++++---- 1 file changed, 65 insertions(+), 17 deletions(-) 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 93fe2c6cd..3de758fa9 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 @@ -161,6 +161,9 @@ class ReportDefinition: 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) @@ -199,7 +202,10 @@ class NewReportRerun: """A stored report's new run, on the current versions and catalog rows. ``forced`` makes it a forced re-run's extra run, which calculates both - sides. + sides. ``sides_join_runs`` (a keyed report's unforced re-run) makes each + side join its simulation's unfailed, unforced run on the re-run's + versions rather than insert one; a side's ``simulation_run_id`` is then + the ID it proposes, used only if it inserts the run. """ report_id: UUID @@ -209,11 +215,14 @@ class NewReportRerun: baseline: RerunSide reform: RerunSide forced: bool = False + sides_join_runs: bool = False def __post_init__(self) -> None: - """Refuse a forced re-run naming a run it doesn't create.""" - if self.forced and (self.baseline.reused or self.reform.reused): - msg = "a forced re-run calculates both sides, reusing no run" + """Refuse a forced re-run naming a run it doesn't create, or joining one.""" + if self.forced and ( + self.baseline.reused or self.reform.reused or self.sides_join_runs + ): + msg = "a forced re-run calculates both sides, reusing and joining no run" raise ValueError(msg) @property @@ -344,6 +353,7 @@ def read_report_definition( 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"), @@ -381,6 +391,7 @@ def read_report_definition( _window_years(connection, report_id) if kind == "budget_window" else () ), household_id=row["household_id"], + keyed=row["key_version"] is not None, ) @@ -583,11 +594,9 @@ def insert_report_rerun( ) if joined is not None: return joined - row = { + row: dict[str, Any] = { "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": versions.country_package_version, @@ -602,16 +611,9 @@ def insert_report_rerun( # and the savepoint takes back this call's simulation runs with it. savepoint = connection.begin_nested() try: - for side in (rerun.baseline, rerun.reform): - if not side.reused: - insert_simulation_run( - connection, - run_id=side.simulation_run_id, - simulation_id=side.simulation_id, - population=rerun.population, - versions=versions, - forced=rerun.forced, - ) + baseline_run_id, reform_run_id = _side_runs(connection, rerun) + row["baseline_simulation_run_id"] = baseline_run_id + row["reform_simulation_run_id"] = reform_run_id if rerun.forced: connection.execute(insert(report_runs).values(row)) found = _created(rerun) @@ -627,6 +629,52 @@ def insert_report_rerun( return found +def _side_runs(connection: Connection, rerun: NewReportRerun) -> tuple[UUID, UUID]: + """Return the baseline's and the reform's run, joined or inserted for the re-run. + + A reused side names its run. With ``sides_join_runs`` (a keyed report's + unforced re-run), every other side joins its simulation's run on the + re-run's versions that hasn't failed and wasn't forced, or inserts one, + in simulation ID order, one run for one simulation on both sides. + Otherwise each other side inserts a new run, forced on a forced re-run. + """ + sides = (rerun.baseline, rerun.reform) + if not rerun.sides_join_runs: + for side in sides: + if not side.reused: + insert_simulation_run( + connection, + run_id=side.simulation_run_id, + simulation_id=side.simulation_id, + population=rerun.population, + versions=rerun.versions, + forced=rerun.forced, + ) + return rerun.baseline.simulation_run_id, rerun.reform.simulation_run_id + proposed = { + side.simulation_id: side.simulation_run_id + for side in reversed(sides) + if not side.reused + } + found = { + simulation_id: find_or_insert_simulation_run( + connection, + simulation_run_row( + run_id=proposed[simulation_id], + simulation_id=simulation_id, + population=rerun.population, + versions=rerun.versions, + ), + ).id + for simulation_id in sorted(proposed) + } + baseline_run_id, reform_run_id = ( + side.simulation_run_id if side.reused else found[side.simulation_id] + for side in sides + ) + return baseline_run_id, reform_run_id + + def _created(rerun: NewReportRerun) -> FoundReportRun: """Return the report run a re-run created, as a lookup would.""" return FoundReportRun( From 0f7cf6e4ec45ef7f0837304706a228895d38433d Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:04:56 +0400 Subject: [PATCH 055/107] Move what a re-run reads of a stored record into rerun_definitions economy_rerun_records had grown past the 800-line limit (the previous commit's file-length check). The definition reads (RecordKind, the report, simulation, side and window-year definitions, and read_report_definition and read_simulation_definition with their private helpers) move unchanged into rerun_definitions; economy_rerun_records keeps the inserts and re-exports the moved names, so every import path still works. Co-Authored-By: Claude Opus 5.5 --- .../economy_rerun_records.py | 310 ++---------------- .../rerun_definitions.py | 303 +++++++++++++++++ 2 files changed, 339 insertions(+), 274 deletions(-) create mode 100644 libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/rerun_definitions.py 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 3de758fa9..6410c0a52 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 @@ -46,7 +46,7 @@ from contextlib import contextmanager from dataclasses import dataclass, replace -from typing import TYPE_CHECKING, Any, Final, Literal +from typing import TYPE_CHECKING, Any, Final from sqlalchemy import func, insert, literal, select @@ -55,23 +55,22 @@ 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, 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.rerun_definitions import ( + RecordKind, + ReportDefinition, + SideDefinition, + SimulationDefinition, + WindowYearDefinition, + read_report_definition, + read_simulation_definition, ) from policyengine_simulation_persistence.shared_rows import ( FoundReportRun, @@ -83,19 +82,16 @@ ReportRunStatus, ReportRunTrigger, SimulationStatus, - SimulationType, budget_window_runs, report_runs, - reports, simulation_runs, - simulations, ) if TYPE_CHECKING: from collections.abc import Iterator from uuid import UUID - from sqlalchemy import Column, ColumnElement, Connection, RowMapping, Table + from sqlalchemy import Column, ColumnElement, Connection, Table from policyengine_simulation_persistence.economy_run_records import ( EconomyPopulation, @@ -103,86 +99,11 @@ ) from policyengine_simulation_persistence.shared_rows import FoundSimulationRun -# 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 - # 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 - - @dataclass(frozen=True) class RerunSide: """The simulation run one side of a report's re-run names. @@ -335,191 +256,6 @@ def __init__(self, run_id: UUID) -> None: 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, - 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"] - ), - ) - - def lock_reruns_of(connection: Connection, record_id: UUID) -> None: """Wait for, then hold until the transaction ends, the record's re-run lock. @@ -845,3 +581,29 @@ 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", + "RunInProgressError", + "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/rerun_definitions.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/rerun_definitions.py new file mode 100644 index 000000000..e1561ba75 --- /dev/null +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/rerun_definitions.py @@ -0,0 +1,303 @@ +"""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 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 + # 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"] + ), + ) From ac3ed06e12882e659011e62194d126df98a13032 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:05:46 +0400 Subject: [PATCH 056/107] Test a keyed report's re-run joining each side's run in the service (failing) A report created by key is re-run with no search for reusable runs: the store joins each side's simulation run on the current versions, the call is built from the runs the store answers, a side whose run the store joined is answered reused, and a refused call fails only the report run. Co-Authored-By: Claude Opus 5.5 --- .../tests/economy_rerun_fakes.py | 11 ++++- .../tests/test_economy_reruns.py | 42 +++++++++++++++++++ 2 files changed, 51 insertions(+), 2 deletions(-) diff --git a/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py b/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py index f1477d8e1..a5242e75f 100644 --- a/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py +++ b/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py @@ -141,6 +141,9 @@ class FakeRerunStore(FakeWindowStore): simulation_reruns: list[NewSimulationRerun] = field(default_factory=list) joined_simulation_run: FoundSimulationRun | None = None joined_report_run: FoundReportRun | 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) def read_report_definition(self, report_id: UUID) -> ReportDefinition | None: if self.read_failure is not None: @@ -229,8 +232,12 @@ def create_report_rerun(self, rerun: NewReportRerun) -> FoundReportRun: id=rerun.run_id, inserted=True, status=ReportRunStatus.PENDING, - baseline_simulation_run_id=rerun.baseline.simulation_run_id, - reform_simulation_run_id=rerun.reform.simulation_run_id, + 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.reform.simulation_run_id + ), ) def create_simulation_rerun(self, rerun: NewSimulationRerun) -> FoundSimulationRun: diff --git a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py index b9257c5ac..83a684869 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py @@ -217,6 +217,48 @@ def test_a_report_rerun_joining_a_run_answers_it_and_starts_no_call( } +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)) + + assert store.rerun_reads[0][1][2] is None + (created,) = store.report_reruns + assert created.sides_join_runs is True + assert (created.baseline.reused, created.reform.reused) == (False, 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_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_without_the_output_bucket_a_rerun_looks_for_no_run_to_reuse() -> None: store = FakeRerunStore(reusable=(REUSED_BASELINE, None)) From b1739d5bd91e675cf5328d8631e3c8bc2cf425b6 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:06:46 +0400 Subject: [PATCH 057/107] Have a keyed report's re-run join each side's run in the service A report created by key is re-run with no search for reusable runs: its new run asks the store to join each side's simulation run on the current versions. The call is built after the create, from the runs the store answers; a side whose run the store joined is answered reused; and a refused call fails only the report run, as its simulation runs may be another report run's. Reports created before keys keep today's re-run. Co-Authored-By: Claude Opus 5.5 --- .../economy_reruns.py | 82 ++++++++++++------- 1 file changed, 53 insertions(+), 29 deletions(-) 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 009fa43e0..783400c73 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 @@ -263,9 +263,10 @@ async def rerun_report( dataset_name=stored.dataset_name, year=stored.year, ) + # A keyed report's sides join their runs by version set instead. reuse = ( None - if request.force or self._settings.reuse_prefix is None + if request.force or definition.keyed or self._settings.reuse_prefix is None else RunReuse( versions=worker.versions, inputs=definition.inputs, @@ -308,24 +309,14 @@ async def rerun_report( stored.reform.simulation_id, inputs.reform.reusable_run ), forced=request.force, + sides_join_runs=definition.keyed and not request.force, ) - calculation = report_run_calculation( + scope = rerun_scope( + stored.country, + economy_request, worker, - rerun_scope( - stored.country, - economy_request, - worker, - inputs.catalog, - options=definition.inputs, - ), - 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, - ), - baseline_policy=inputs.baseline.reform, - reform_policy=inputs.reform.reform, + inputs.catalog, + options=definition.inputs, ) found = await self._create_rerun( _REPORT, @@ -334,26 +325,32 @@ async def rerun_report( ) if not found.inserted: return _joined_report_run(stored, found) + answer = _created_report_run(stored, rerun, found) + calculation = report_run_calculation( + worker, + scope, + self._origin(request_id), + run_ids=ReportRunIds( + 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, + ) 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, + # A keyed report's simulation runs may be another report run's. + new_simulation_run_ids=() + if rerun.sides_join_runs + else rerun.new_simulation_run_ids, 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, @@ -590,6 +587,33 @@ def _joined_report_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 is reused when its run isn't one this re-run inserted: a reused + run, or, for a keyed report, its simulation's run the store joined. + The status is the new run's, until its call is started. + """ + 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) + 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=rerun.baseline.reused + or created.baseline_simulation_run_id != rerun.baseline.simulation_run_id, + reform_simulation_id=stored.reform.simulation_id, + reform_simulation_run_id=created.reform_simulation_run_id, + reform_reused=rerun.reform.reused + or created.reform_simulation_run_id != rerun.reform.simulation_run_id, + ) + + @dataclass(frozen=True) class _WindowRerunRequest: """What a budget window's re-run calculates, as the service has read it.""" From aecf14ba25309d13731d1314d6ef51b53b57d3d9 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:08:10 +0400 Subject: [PATCH 058/107] Describe the shared simulations, reports and runs in the READMEs The simulation persistence README gains a section on the definition keys, the find-or-create lookups and the keyed economy records, and notes that the unkeyed inserts remain for budget windows; the entry README says a keyed report's re-run has each side join its simulation's run. Co-Authored-By: Claude Opus 5.5 --- .../README.md | 40 ++++++++++++++++++- .../policyengine-simulation-entry/README.md | 5 ++- 2 files changed, 43 insertions(+), 2 deletions(-) diff --git a/libs/policyengine-simulation-persistence/README.md b/libs/policyengine-simulation-persistence/README.md index 4ba7a9643..c65fd6e1a 100644 --- a/libs/policyengine-simulation-persistence/README.md +++ b/libs/policyengine-simulation-persistence/README.md @@ -94,7 +94,9 @@ 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 +run. Both create unkeyed rows; the Simulation Entrypoint now creates by key +("Shared simulations, reports and runs" below), and budget windows still +create this way. 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 @@ -125,6 +127,42 @@ 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). Three 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. 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, joined or offered for reuse. +- `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) and the + report run naming them, a competing report run joined with the savepoint + rolled back. `find_or_create_economy_simulation` does the same 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. + ## Household reports `household_report_records.py` holds the simulation service's writes for a diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index 48d4dbd36..a0770451e 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -254,7 +254,10 @@ refused while a run is under way. The new report run's trigger is `manual`. Without `force`, a re-run 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. The service reads the +Modal call; a run still under way on older versions is no run to join. A +report created by key re-runs with no search for reusable runs: each side +joins its simulation's run on those versions that hasn't failed and wasn't +forced, in any state, or gets a new one. 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. From e4d83ac2a137f08890f79b66ac6d7996bac68c55 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:29:50 +0400 Subject: [PATCH 059/107] Patch the input reads where they now live, in the store's side-refusal test Review round 4's bug: moving the input reads into economy_inputs left test_every_side_refusal_is_raised_with_its_side patching names the store no longer has, so it failed with an AttributeError. It now replaces read_catalog_rows where the store looks it up, and read_simulation_values where economy_inputs does. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_economy_run_store.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) 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..3c0156ebb 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py @@ -50,6 +50,7 @@ UnknownDynamicError, UnknownPolicyError, UnknownRegionError, + economy_inputs, economy_run_store, ) from public_api_rows import StoredValue, insert_dataset, insert_dynamic, insert_policy @@ -521,7 +522,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,7 +542,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 From 9bbd25ce90173b7d18242b74c89c7cdcd040c4a5 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:30:51 +0400 Subject: [PATCH 060/107] Test a keyed re-run with one simulation on both sides (failing) Review round 4's bug: a keyed report comparing current law with current law, re-run where it has no unfailed run, inserts one simulation run with the baseline's proposed ID and names it on both sides; the service then answered the reform side reused, though this re-run created that run. The persistence test (passing) pins the one run; the service test fails on the reform's flag. The re-run fake's current law sets no values. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_keyed_economy_records.py | 39 +++++++++++++++++++ .../tests/economy_rerun_fakes.py | 13 ++++++- .../tests/test_economy_reruns.py | 20 ++++++++++ 3 files changed, 70 insertions(+), 2 deletions(-) diff --git a/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py b/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py index a32f0c882..ae47a2b18 100644 --- a/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py @@ -656,3 +656,42 @@ def test_a_keyed_reports_rerun_joins_each_sides_run_on_its_versions( 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(), reused=False), + reform=RerunSide(simulation_id, uuid4(), reused=False), + sides_join_runs=True, + ) + + 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 diff --git a/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py b/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py index a5242e75f..515a13b87 100644 --- a/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py +++ b/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py @@ -144,6 +144,9 @@ class FakeRerunStore(FakeWindowStore): # 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: @@ -178,9 +181,12 @@ def read_report_rerun_inputs( reform={}, reusable_run=None if reuse is None else baseline_reusable, ), + # Current law sets no values, on either side. reform=SimulationInputs( choice=reform.choice, - reform=REFORM, + reform=REFORM + if reform.choice.policy_id or reform.choice.dynamic_id + else {}, reusable_run=None if reuse is None else reform_reusable, ), ) @@ -236,7 +242,10 @@ def create_report_rerun(self, rerun: NewReportRerun) -> FoundReportRun: "baseline", rerun.baseline.simulation_run_id ), reform_simulation_run_id=self.joined_side_runs.get( - "reform", rerun.reform.simulation_run_id + "reform", + rerun.baseline.simulation_run_id + if self.one_run_on_both_sides + else rerun.reform.simulation_run_id, ), ) diff --git a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py index 83a684869..f8695a6e3 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py @@ -245,6 +245,26 @@ def test_a_keyed_reports_rerun_has_each_side_join_its_run_on_the_versions() -> N ) +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_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)) From 0b1ada5207fa66b0fa3b73d19b26a2889ec2b2a5 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:31:53 +0400 Subject: [PATCH 061/107] Answer a side reused only when its run isn't one the re-run inserted Review round 4's bug: a keyed re-run with one simulation on both sides inserts one run, with the baseline's proposed ID, and names it on both sides; the service now answers a side reused only when its run is none of the IDs the re-run's unreused sides proposed, so neither side is reused there. shared_rows' find_or_insert_simulation_runs finds or inserts each simulation's joinable run in simulation ID order for both the keyed creates and the keyed re-runs, which round 4 found written twice, and the creates read their proposed sides by name rather than by attribute. Co-Authored-By: Claude Opus 5.5 --- .../__init__.py | 2 ++ .../economy_rerun_records.py | 27 +++++++++---------- .../keyed_economy_records.py | 25 +++++++++-------- .../shared_rows.py | 15 +++++++++++ .../economy_reruns.py | 17 +++++++----- 5 files changed, 52 insertions(+), 34 deletions(-) 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 e7854d3d5..fb716b82f 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py @@ -155,6 +155,7 @@ 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, @@ -277,6 +278,7 @@ "find_or_insert_report_run", "find_or_insert_simulation", "find_or_insert_simulation_run", + "find_or_insert_simulation_runs", "find_reusable_run", "find_reusable_run_of", "household_jobs", 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 6410c0a52..e7bcecb60 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 @@ -77,6 +77,7 @@ find_joinable_report_run, find_or_insert_report_run, find_or_insert_simulation_run, + find_or_insert_simulation_runs, ) from policyengine_simulation_persistence.tables import ( ReportRunStatus, @@ -387,25 +388,21 @@ def _side_runs(connection: Connection, rerun: NewReportRerun) -> tuple[UUID, UUI forced=rerun.forced, ) return rerun.baseline.simulation_run_id, rerun.reform.simulation_run_id - proposed = { - side.simulation_id: side.simulation_run_id + # The reform first, so one simulation on both sides keeps the baseline's + # proposed ID. + rows = { + side.simulation_id: simulation_run_row( + run_id=side.simulation_run_id, + simulation_id=side.simulation_id, + population=rerun.population, + versions=rerun.versions, + ) for side in reversed(sides) if not side.reused } - found = { - simulation_id: find_or_insert_simulation_run( - connection, - simulation_run_row( - run_id=proposed[simulation_id], - simulation_id=simulation_id, - population=rerun.population, - versions=rerun.versions, - ), - ).id - for simulation_id in sorted(proposed) - } + found = find_or_insert_simulation_runs(connection, rows) baseline_run_id, reform_run_id = ( - side.simulation_run_id if side.reused else found[side.simulation_id] + side.simulation_run_id if side.reused else found[side.simulation_id].id for side in sides ) return baseline_run_id, reform_run_id 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 index 5f20903d7..65ea1daf3 100644 --- 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 @@ -45,6 +45,7 @@ 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, @@ -263,21 +264,19 @@ def _find_or_insert_simulation_runs( Inserted in simulation ID order; one simulation on both sides gets one run, with the baseline's proposed ID. """ - proposed: dict[UUID, UUID] = {} - for side in reversed(_SIDES): - proposed[simulation_ids[side]] = getattr(request, side).simulation_run_id - return { - simulation_id: find_or_insert_simulation_run( - connection, - simulation_run_row( - run_id=proposed[simulation_id], - simulation_id=simulation_id, - population=request.population, - versions=request.versions, - ), + proposed_sides = {"baseline": request.baseline, "reform": request.reform} + rows = { + simulation_ids[side]: simulation_run_row( + run_id=proposed_sides[side].simulation_run_id, + simulation_id=simulation_ids[side], + population=request.population, + versions=request.versions, ) - for simulation_id in sorted(proposed) + # The reform first, so one simulation on both sides keeps the + # baseline's proposed ID. + for side in reversed(_SIDES) } + return find_or_insert_simulation_runs(connection, rows) def _simulation_row( 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 index 424f8dde6..1d13559ff 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/shared_rows.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/shared_rows.py @@ -180,6 +180,21 @@ def find_or_insert_simulation_run( ) +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) + } + + def find_or_insert_report_run( connection: Connection, values: Mapping[str, Any] ) -> FoundReportRun: 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 783400c73..bbc7dfa49 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 @@ -593,24 +593,29 @@ def _created_report_run( """Answer the report run a re-run created, with the side runs it names. A side is reused when its run isn't one this re-run inserted: a reused - run, or, for a keyed report, its simulation's run the store joined. - The status is the new run's, until its call is started. + run, or, for a keyed report, its simulation's run the store joined. The + runs this re-run may have inserted have the IDs its unreused 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. """ 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 = { + side.simulation_run_id + for side in (rerun.baseline, rerun.reform) + if not side.reused + } 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=rerun.baseline.reused - or created.baseline_simulation_run_id != rerun.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=rerun.reform.reused - or created.reform_simulation_run_id != rerun.reform.simulation_run_id, + reform_reused=created.reform_simulation_run_id not in proposed, ) From 1b59eeb5a335a35fe014cf7f9b5daba059d51c59 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:33:03 +0400 Subject: [PATCH 062/107] Test refusing a report that asks for cliffs, until per-run cliffs exist (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's interim answer A (2026-11-14): POST /reports refuses include_cliffs: true with 422, code cliffs_not_available, located at the field, before anything is read or written, until C1 · 39 starts per-run cliff calculations. The service tests' report request asks for no cliffs by default. Co-Authored-By: Claude Opus 5.5 --- .../tests/economy_service_fakes.py | 9 ++++++- .../tests/test_economy_submissions.py | 27 +++++++++++++++++-- 2 files changed, 33 insertions(+), 3 deletions(-) diff --git a/projects/policyengine-simulation-entry/tests/economy_service_fakes.py b/projects/policyengine-simulation-entry/tests/economy_service_fakes.py index 89c41a20f..40bc933a0 100644 --- a/projects/policyengine-simulation-entry/tests/economy_service_fakes.py +++ b/projects/policyengine-simulation-entry/tests/economy_service_fakes.py @@ -101,7 +101,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: diff --git a/projects/policyengine-simulation-entry/tests/test_economy_submissions.py b/projects/policyengine-simulation-entry/tests/test_economy_submissions.py index f9eaa8acd..5a8306d09 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_submissions.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_submissions.py @@ -271,7 +271,10 @@ 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), @@ -281,7 +284,27 @@ def test_a_report_without_spm_settings_stores_none() -> None: (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( From 486f0bf48286e45524184fd4ede00f43571b0a13 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:34:46 +0400 Subject: [PATCH 063/107] Refuse a report asking for cliffs until per-run cliffs exist MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit POST /reports answers include_cliffs: true with 422 cliffs_not_available, located at the field, before anything is read or written (C1 · 24's interim answer A). Identical requests share a report and its runs, so a cliff request can't change what they calculate; C1 · 39 lifts this once each simulation run's cliffs are calculated on their own. The route's 422 description and the README say so. The request helpers (the refusal, stored_options, report_created, economy_request_for and calculation_scope) move from economy_submissions, which had passed the 800-line limit, into economy_requests; the submissions module re-exports them. Co-Authored-By: Claude Opus 5.5 --- .../policyengine-simulation-entry/README.md | 5 +- .../economy_api_models.py | 3 + .../economy_requests.py | 152 ++++++++++++++++++ .../economy_routes.py | 4 +- .../economy_submissions.py | 112 +++---------- 5 files changed, 183 insertions(+), 93 deletions(-) create mode 100644 projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_requests.py diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index a0770451e..bb3400ea1 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -154,7 +154,10 @@ 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 is failed at once (a report run alone: its simulation runs may already be 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 e83f0db0a..fbac3cfd2 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 @@ -85,6 +85,9 @@ # 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[ 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..f8792f0cc --- /dev/null +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_requests.py @@ -0,0 +1,152 @@ +"""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, 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 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 EconomySubmissionUnprocessableError( + code="cliffs_not_available", + reasons=( + UnprocessableReason( + loc=("body", "include_cliffs"), + msg=( + "Cliff impacts are not calculated yet: they will be " + "calculated for each simulation run on its own. Send " + "include_cliffs: false." + ), + 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_routes.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_routes.py index 903f8961c..af4d0db0c 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 @@ -138,7 +138,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, } 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 a6894bab4..978a60555 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 @@ -70,14 +70,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, @@ -100,7 +103,6 @@ from collections.abc import Callable, Sequence from policyengine_simulation_persistence import ( - EconomyCatalogRows, EconomyReportInputs, EconomyReportState, EconomySimulationInputs, @@ -111,11 +113,7 @@ SimulationInputs, ) - from policyengine_simulation_entry.budget_window_api_models import ( - BudgetWindowReportRequest, - ) from policyengine_simulation_entry.economy_api_models import ( - EconomyRefusalCode, EconomyReportRequest, EconomySimulationRequest, PolicyChoice, @@ -277,6 +275,7 @@ 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() spm = options.get("spm") @@ -701,85 +700,16 @@ async def _record_call( return None if status is None else str(status) -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 - ), - ) +# 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", +] From 876fc0ed4f47f365e8e4b9c92fbb02f97d188f88 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:41:53 +0400 Subject: [PATCH 064/107] Test re-runs of reports with no keys as forced runs, and refusing stored cliffs (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's interim answer B: a re-run of a report whose simulations have no key always calculates new runs, marked forced, with no reuse search and no join, so the one-unfailed-run indexes never refuse them. That covers a budget window's years and a household report's runs. Interim answer A's scope: a stored report whose options hold include_cliffs: true is refused with 422 until per-run cliffs exist. The fake re-run store joins nothing for a forced re-run, as the store does, and a keyed report's forced re-run is now tested (review round 4's gap). Co-Authored-By: Claude Opus 5.5 --- .../tests/test_household_report_reruns.py | 44 +++++++ .../tests/economy_rerun_fakes.py | 7 +- .../tests/test_economy_reruns.py | 121 ++++++++++++------ 3 files changed, 132 insertions(+), 40 deletions(-) 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..daa59adfc 100644 --- a/libs/policyengine-simulation-persistence/tests/test_household_report_reruns.py +++ b/libs/policyengine-simulation-persistence/tests/test_household_report_reruns.py @@ -155,6 +155,21 @@ def _stored_report( return report +def _succeed_first_runs(connection: Connection, report: NewHouseholdReport) -> 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 ) -> NewHouseholdReportRerun: @@ -292,6 +307,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: diff --git a/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py b/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py index 515a13b87..a3fab3037 100644 --- a/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py +++ b/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py @@ -60,8 +60,10 @@ 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( @@ -232,7 +234,8 @@ def create_report_rerun(self, rerun: NewReportRerun) -> FoundReportRun: if self.rerun_failure is not None: raise self.rerun_failure self.report_reruns.append(rerun) - if self.joined_report_run is not None: + # 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, diff --git a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py index f8695a6e3..5e5ed1a01 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py @@ -23,7 +23,6 @@ ) from economy_service_fakes import ( CATALOG, - OUTPUT_BUCKET, REFORM, FakeCaller, ) @@ -57,7 +56,6 @@ RerunSide, ReusableRun, RunInProgressError, - RunReuse, RunVersions, SharedRowNotSettledError, SimulationStatus, @@ -100,7 +98,10 @@ 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: +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(reusable=(REUSED_BASELINE, None)) caller = FakeCaller() @@ -114,11 +115,8 @@ 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}/", - ) + assert reuse is None + # Extra runs, marked forced, which nothing joins and no index refuses. assert store.report_reruns == [ NewReportRerun( report_id=REPORT_ID, @@ -127,30 +125,31 @@ 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), + reused=False, ), reform=RerunSide( simulation_id=REFORM_SIMULATION_ID, - simulation_run_id=UUID(int=2), + simulation_run_id=UUID(int=3), reused=False, ), + 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 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() == { @@ -158,10 +157,10 @@ 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, } @@ -265,6 +264,32 @@ def test_a_keyed_rerun_with_one_simulation_on_both_sides_reuses_neither() -> Non 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 = _rerun_report( + rerun_service(store, caller=caller), ReportRerunRequest(force=True) + ) + + (created,) = store.report_reruns + assert (created.forced, created.sides_join_runs) == (True, False) + 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 + + 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)) @@ -279,14 +304,6 @@ def test_a_keyed_reports_refused_rerun_fails_only_the_report_run() -> None: assert simulation_run_ids == () -def test_without_the_output_bucket_a_rerun_looks_for_no_run_to_reuse() -> None: - store = FakeRerunStore(reusable=(REUSED_BASELINE, None)) - - _rerun_report(rerun_service(store, output_bucket=None)) - - assert store.rerun_reads[0][1][2] is None - - def test_an_unknown_report_or_simulation_is_not_found() -> None: store = FakeRerunStore(report_definition=None, simulation_definition=None) service = rerun_service(store) @@ -366,7 +383,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") @@ -400,6 +417,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 ): @@ -620,6 +672,7 @@ 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(): + """Interim answer B: a window has no keys yet, so every year is recalculated.""" store = FakeRerunStore( report_definition=STORED_WINDOW, reusable_by_year={2027: (REUSED_2027, None)} ) @@ -636,16 +689,12 @@ def test_a_budget_window_is_rerun_as_a_new_window_run_and_its_first_years_starte STORED_WINDOW.reform.choice, STORED_WINDOW.window_years, ) - assert reuse == RunReuse( - versions=VERSIONS, - inputs=STORED_OPTIONS, - output_uri_prefix=f"gs://{OUTPUT_BUCKET}/", - ) + assert reuse is None (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] @@ -653,11 +702,7 @@ 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 not any(window_year.baseline.reused for window_year in window.years) assert advancer.advances == [window.window_run_id] assert len(caller.report_runs) == 3 for (year_to_start, _), (_, payload, context, observed) in zip( From 2431ca6007067dd907d9070a355c49b4e38eb5a6 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:47:36 +0400 Subject: [PATCH 065/107] Re-run reports with no keys as forced runs, and refuse stored cliffs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's interim answer B: a report created before keys may have runs whose plans depended on it, so its re-run always calculates new runs, marked forced, which nothing joins and the one-unfailed-run indexes leave out. A budget window has no keys yet, so every window re-run recalculates; a household report's re-run marks its report run and simulation runs forced. Re-runs no longer search for a run to reuse: a keyed report's sides join their simulations' runs, and everything else is forced. Interim answer A's scope: a stored report whose options hold include_cliffs: true answers 422 cliffs_not_available, located at report.inputs.include_cliffs, before anything is read or written. The routes, models and READMEs describe both, and 409 run_in_progress now comes only from a household report's re-run. Co-Authored-By: Claude Opus 5.5 --- .../README.md | 5 +- .../economy_rerun_records.py | 10 +- .../household_report_records.py | 5 +- .../policyengine-simulation-entry/README.md | 87 +++++------ .../economy_api_models.py | 22 +-- .../economy_requests.py | 50 ++++-- .../economy_rerun_routes.py | 61 +++++--- .../economy_reruns.py | 145 ++++++++---------- .../tests/test_economy_reruns.py | 14 +- .../tests/test_openapi.py | 4 + 10 files changed, 218 insertions(+), 185 deletions(-) diff --git a/libs/policyengine-simulation-persistence/README.md b/libs/policyengine-simulation-persistence/README.md index c65fd6e1a..e87faea0c 100644 --- a/libs/policyengine-simulation-persistence/README.md +++ b/libs/policyengine-simulation-persistence/README.md @@ -233,7 +233,10 @@ 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 +household runs are never reused. A household report has no keys yet, so the +report run and both simulation runs are marked `forced`, extra runs that +nothing joins and the one-unfailed-run indexes leave out (C1 · 24's interim +answer B). 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 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 e7bcecb60..e088d18cc 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 @@ -205,7 +205,8 @@ 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. + report's ``year``, marked forced like the report run; ``reform`` is None + for a report of the baseline alone. """ report_id: UUID @@ -485,7 +486,10 @@ def insert_household_report_rerun( The report run has trigger ``manual`` and names no budget-window run; 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. + report run. A household report has no keys yet, so its runs may have + been calculated for it alone: each is an extra run, marked forced, that + nothing joins and the one-unfailed-run indexes leave out (C1 · 24's + interim answer B). Raise as ``insert_report_rerun`` does. """ lock_reruns_of(connection, rerun.report_id) _refuse_while_report_runs(connection, rerun.report_id) @@ -498,6 +502,7 @@ def insert_household_report_rerun( year=rerun.year, tax_benefit_model_version_id=rerun.tax_benefit_model_version_id, versions=rerun.versions, + forced=True, ) connection.execute( insert(report_runs).values( @@ -514,6 +519,7 @@ def insert_household_report_rerun( status=ReportRunStatus.PENDING, trigger=ReportRunTrigger.MANUAL, modal_call_id=None, + forced=True, ) ) 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..9d8cc062d 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 @@ -184,11 +184,13 @@ 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( @@ -202,5 +204,6 @@ def insert_household_simulation_run( # noqa: PLR0913 # the run and what it cal region_id=None, status=SimulationStatus.PENDING, modal_call_id=None, + forced=forced, ) ) diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index bb3400ea1..e5ab517bd 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -247,30 +247,36 @@ 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, as an extra run: the new report run and both simulation runs -are marked `forced`, so nothing joins them, and a forced re-run is never -refused while a run is under way. The new report run's trigger is `manual`. -Without `force`, a re-run 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. A -report created by key re-runs with no search for reusable runs: each side -joins its simulation's run on those versions that hasn't failed and wasn't -forced, in any state, or gets a new one. 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's +trigger is `manual`. 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; -a forced one's year runs and new simulation runs are marked `forced`. 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 +`manual`, and a report run per year. A window has no keys yet, so every +re-run recalculates it, forced or not: `recalculate` is set, and its year +runs and new simulation runs are marked `forced`. Each year's sides are new +runs of 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). 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. @@ -278,7 +284,8 @@ 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 +household runs are never reused, so `force` changes nothing, and each is +marked `forced`, as a household report has no keys yet. The new report run (trigger `manual`) 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. @@ -291,9 +298,8 @@ 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 a budget window's run -of the report, or one of its year runs, is pending or running, unless the -re-run is forced, or while a household report has a run pending or running; +`run_in_progress`, naming the run in `run_id`, while a household report has +a run pending or running; 409 `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 @@ -306,28 +312,17 @@ 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`. An unforced economy or budget-window report re-run, and -every household report re-run, looks for the run to join, or for a run -under way, and inserts under a transaction-level advisory lock on the -report's ID: a second economy report re-run waits, then joins the first's -run; a second budget-window or household one waits, then is refused with -409 naming it. A simulation's re-run takes no lock: the Public API's index -on runs lets only one run that hasn't failed exist on a version set, so -concurrent re-runs end on it. A forced economy or budget-window re-run -takes none either, as nothing joins it. A household report's re-run ignores -`force`, so it takes the lock and is refused with 409 `run_in_progress` -while any run of the report is pending or running. Until a report's sides -find their simulation runs by version set (C1 · 24's answers 4 and 5), an -unforced economy report re-run whose side has a run on the current -versions that hasn't failed but isn't reused is refused by that index: -for example a succeeded run whose report run failed for the other side, -one a coordinator refused to reuse, one used with other options, or one -another report run is calculating. So, until C1 · 24's answer 8, is a -household report's re-run, forced or not, once its earlier run has ended -on the current versions without failing (each side's new run is unforced), -and an unforced budget window's whose year side has such a run. The -service answers that database error 503 `database_unavailable`, though -asking again fails the same way while that run is there. A re-run's answer names +`not_configured`. An unforced re-run of a report created by key, and every +household report re-run, looks for the run to join, or for a run under way, +and inserts under a transaction-level advisory lock on the report's ID: a +second keyed economy report re-run waits, then joins the first's run; a +second household one waits, then is refused with 409 naming it. 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 household report's re-run ignores `force`, so it takes the lock +and is refused with 409 `run_in_progress` while any run of the report is +pending or running. 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 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 fbac3cfd2..766eadbaa 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 @@ -20,7 +20,7 @@ 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``) of a - budget-window or household report, or ``rerun_not_supported`` for a + household report, or ``rerun_not_supported`` for a record this service does not re-run. Nothing is written; - 422 when the request's fields, or the stored values it names, cannot be calculated. Nothing is written; @@ -203,13 +203,14 @@ def options(self) -> dict[str, Any]: class ReportRerunRequest(_Request): """A stored report's re-run on the default worker's versions. - Without ``force``, an economy report's re-run joins the report's run on - those versions that hasn't failed and wasn't forced, pending, running or - succeeded, and otherwise a side reuses a run of its own simulation that - succeeded on them, as a new report's side does. With it, an economy or - budget-window report's simulations are calculated again, as an extra run - marked forced that nothing joins; a household report's re-run ignores - it. + Without ``force``, a re-run of an economy 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 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 budget-window report or one 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; a + household report's re-run ignores it. """ force: StrictBool = False @@ -317,9 +318,8 @@ class EconomyError(_Answer): 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. + and with ``run_in_progress`` the household report's run that is + pending or running. """ 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 index f8792f0cc..5139ac641 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_requests.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_requests.py @@ -2,7 +2,8 @@ The submission services (``economy_submissions``, ``budget_window_submissions``) turn a request into the persistence library's ``EconomyRequest``, refuse what -can't be calculated yet, choose what a report stores of the request's +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. """ @@ -27,6 +28,8 @@ ) if TYPE_CHECKING: + from collections.abc import Mapping + from policyengine_simulation_persistence import ( EconomyCatalogRows, FoundEconomyReport, @@ -52,22 +55,41 @@ def refuse_cliffs(request: EconomyReportRequest) -> None: cliffs on its own instead (C1 · 24's interim answer A). """ if request.include_cliffs: - raise EconomySubmissionUnprocessableError( - code="cliffs_not_available", - reasons=( - UnprocessableReason( - loc=("body", "include_cliffs"), - msg=( - "Cliff impacts are not calculated yet: they will be " - "calculated for each simulation run on its own. Send " - "include_cliffs: false." - ), - type="cliffs_not_available", - ), - ), + 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. 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 f8d4485a1..c9de826d0 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 @@ -4,10 +4,11 @@ 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. For an economy or budget-window - report, ``{"force": true}`` calculates both simulations again, as an - extra run marked forced that nothing joins; otherwise a side reuses a run - of its own simulation that succeeded on the same versions. + side's simulation and simulation run. An economy 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 budget-window report or + of one created before keys, calculates both simulations again, as an + extra run marked forced that nothing joins. 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 @@ -23,13 +24,14 @@ Every earlier run is kept. A re-run answers 404 for a record that does not exist, and 409 (``run_in_progress``, naming the run in ``run_id``) while a -budget-window report has a window run or year run pending or running and -the re-run isn't forced, or while a household report has a run pending or -running (a household re-run ignores ``force``), or for a record this -service does not re-run (``rerun_not_supported``); then nothing is -written. Without ``force``, an economy 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. The other +household report has a run pending or running (a household re-run ignores +``force``), or for a record this service does not re-run +(``rerun_not_supported``); then nothing is written. Without ``force``, a +keyed economy 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, @@ -122,11 +124,9 @@ class EconomyService(EconomySubmissions, EconomyReruns, Protocol): # The run a 409 run_in_progress names, by the record re-run. _CONFLICTS: dict[RecordName, str] = { "report": ( - "a budget-window report has a window run or year run pending or " - "running and the re-run isn't forced, or a household report has a " - "run pending or running, forced or not (run_in_progress; run_id " - "names the report's budget-window run, or else its report run), or " - "the service does not re-run it (rerun_not_supported)" + "a household report has a run pending or running, forced or not " + "(run_in_progress; run_id names that report run), or the service " + "does not re-run it (rerun_not_supported)" ), "simulation": "the service does not re-run it (rerun_not_supported)", } @@ -153,6 +153,15 @@ 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]]: @@ -193,8 +202,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, }, @@ -288,13 +297,15 @@ 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, an economy report's re-run 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 a side " - "reuses a run of its own simulation that succeeded on the same " - "versions. With force, an economy or budget-window report's " - "simulations are calculated again, as an extra run marked forced " - "that nothing joins; a household report's re-run ignores force. " + "force, an economy 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 budget-window report or one " + "created before keys, the report's simulations are calculated " + "again, as an extra run marked forced that nothing joins; a " + "household report's re-run ignores force. A report stored asking " + "for cliff impacts is refused (422 cliffs_not_available). " "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 " 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 bbc7dfa49..b5cac1f95 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,26 +4,28 @@ 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. for a simulation or an economy report, joins, in one transaction, the - record's run on the current versions that hasn't failed and wasn't + 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 (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; a budget window's re-run always creates its runs. A forced re-run - always creates its runs, marked forced, an extra run that nothing joins. - An unforced budget window's re-run is refused while a window run or year - run of the report is pending or running (409 ``run_in_progress``); + else creates the new run (a report's with trigger ``manual``); 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 + budget window has no keys yet, so its re-run always creates its runs, + marked forced. 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 @@ -34,9 +36,10 @@ 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, marked forced as a household report has no keys yet, 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 @@ -53,7 +56,6 @@ NewSimulationRerun, NewWindowRerun, RerunSide, - RunReuse, WindowRerunYear, ) @@ -74,6 +76,7 @@ report_run_calculation, 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, @@ -103,7 +106,7 @@ FoundReportRun, FoundSimulationRun, ReportDefinition, - ReusableRun, + RunReuse, SideDefinition, SimulationChoice, SimulationDefinition, @@ -250,6 +253,7 @@ async def rerun_report( definition, observability_context=observability_context ) stored = rerunnable_report(definition) + refuse_stored_cliffs(definition.inputs) window_years = ( complete_window_years(definition) if definition.kind == "budget_window" @@ -263,16 +267,10 @@ async def rerun_report( dataset_name=stored.dataset_name, year=stored.year, ) - # A keyed report's sides join their runs by version set instead. - reuse = ( - None - if request.force or definition.keyed 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( @@ -280,8 +278,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, @@ -292,7 +289,8 @@ async def rerun_report( economy_request, baseline=stored.baseline, reform=stored.reform, - reuse=reuse, + # A re-run reuses no run: its sides join or are forced. + reuse=None, ), request=economy_request, source=STORED_REPORT, @@ -302,14 +300,10 @@ 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 - ), - forced=request.force, - sides_join_runs=definition.keyed and not request.force, + baseline=self._new_side(stored.baseline.simulation_id), + reform=self._new_side(stored.reform.simulation_id), + forced=forced, + sides_join_runs=not forced, ) scope = rerun_scope( stored.country, @@ -452,10 +446,10 @@ async def _rerun_window( ) -> 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``). + Each year's sides are new runs of that year's own simulations, as + its report run in the report's newest window run names them, marked + forced: a window has no keys yet (interim answer B). The years start + as a new window's do (``_start_first_years``). """ stored = window.stored inputs = await self._read_inputs( @@ -464,7 +458,7 @@ async def _rerun_window( baseline=stored.baseline.choice, reform=stored.reform.choice, years=window.years, - reuse=window.reuse, + reuse=None, ), request=window.economy_request, source=STORED_REPORT, @@ -476,7 +470,7 @@ 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( @@ -515,28 +509,21 @@ async def _rerun_window( years=[year_created(window_year) for window_year in rerun.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(), @@ -552,9 +539,9 @@ async def _create_rerun[Created]( ) -> 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 - budget-window or household report with a run under way is refused - (409 ``run_in_progress``). A record deleted after its reads is + Return what ``create`` returns: the run it joined or created. A run + under way the store refuses the re-run for answers 409 + ``run_in_progress``. 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. @@ -568,8 +555,9 @@ def _joined_report_run( ) -> EconomyReportCreated: """Answer the report's run a re-run joined, as it is; this call created nothing. - The run names runs of the report's own simulations; a side reusing no - run never joins, so both sides are reused. + 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 joined.reform_simulation_run_id is None: msg = f"report run {joined.id} of an economy report names no reform run" @@ -592,20 +580,16 @@ def _created_report_run( ) -> EconomyReportCreated: """Answer the report run a re-run created, with the side runs it names. - A side is reused when its run isn't one this re-run inserted: a reused - run, or, for a keyed report, its simulation's run the store joined. The - runs this re-run may have inserted have the IDs its unreused 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. + 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. """ 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 = { - side.simulation_run_id - for side in (rerun.baseline, rerun.reform) - if not side.reused - } + proposed = {rerun.baseline.simulation_run_id, rerun.reform.simulation_run_id} return EconomyReportCreated( report_id=stored.report_id, report_run_id=created.id, @@ -627,5 +611,4 @@ class _WindowRerunRequest: options: dict[str, Any] years: tuple[WindowYearDefinition, ...] economy_request: EconomyRequest - reuse: RunReuse | None recalculate: bool diff --git a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py index 5e5ed1a01..2c10ce410 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py @@ -145,7 +145,7 @@ def test_a_report_with_no_keys_is_rerun_as_forced_runs_on_the_current_versions() 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=UUID(int=2), @@ -187,7 +187,10 @@ def test_a_forced_rerun_recalculates_both_simulations() -> None: 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.""" + """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, @@ -195,7 +198,10 @@ def test_a_report_rerun_joining_a_run_answers_it_and_starts_no_call( baseline_simulation_run_id=UUID(int=91), reform_simulation_run_id=UUID(int=92), ) - store = FakeRerunStore(joined_report_run=joined) + store = FakeRerunStore( + report_definition=replace(STORED_REPORT, keyed=True), + joined_report_run=joined, + ) caller = FakeCaller() rerun = _rerun_report(rerun_service(store, caller=caller)) @@ -711,7 +717,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 ) diff --git a/projects/policyengine-simulation-entry/tests/test_openapi.py b/projects/policyengine-simulation-entry/tests/test_openapi.py index d0250c938..a8903d83f 100644 --- a/projects/policyengine-simulation-entry/tests/test_openapi.py +++ b/projects/policyengine-simulation-entry/tests/test_openapi.py @@ -477,6 +477,10 @@ def test_rerun_routes_declare_every_answer(): 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 ( From 1a70fdf3f31f313821b7be50b8db2e04c7cd71c2 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:55:02 +0400 Subject: [PATCH 066/107] Find or insert a report's side runs in one place, for creates and re-runs Review round 4's findings. A keyed report's create and an unforced re-run of it now name their sides' runs through one helper, find_or_insert_side_runs, which returns each side's run with the flag saying whether this request inserted it. With interim answer B, every unforced report re-run is a keyed report's, so NewReportRerun loses sides_join_runs: unforced, each side joins its simulation's run on the re-run's versions or inserts one; forced, both are inserted, marked forced. No side of a report's re-run names a reused run. The create routes' 201 and 503 answers, EconomyReportCreated and the persistence README say what a request may join, not only create. Co-Authored-By: Claude Opus 5.5 --- .../README.md | 30 ++-- .../economy_rerun_records.py | 143 ++++++++---------- .../keyed_economy_records.py | 49 +++--- .../tests/test_economy_reruns.py | 52 +++---- .../tests/test_keyed_economy_records.py | 2 - .../economy_api_models.py | 19 +-- .../economy_reruns.py | 7 +- .../economy_routes.py | 30 +++- .../tests/test_economy_reruns.py | 4 +- .../tests/test_openapi.py | 3 + 10 files changed, 179 insertions(+), 160 deletions(-) diff --git a/libs/policyengine-simulation-persistence/README.md b/libs/policyengine-simulation-persistence/README.md index e87faea0c..fc9276520 100644 --- a/libs/policyengine-simulation-persistence/README.md +++ b/libs/policyengine-simulation-persistence/README.md @@ -156,9 +156,10 @@ report and run rows (C1 · 24). Three modules do it: 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) and the - report run naming them, a competing report run joined with the savepoint - rolled back. `find_or_create_economy_simulation` does the same for one + simulation's joinable run (whatever report first calculated it), found + or inserted by `find_or_insert_side_runs`, and the report run naming + them, a competing report run joined with the savepoint rolled back. + `find_or_create_economy_simulation` does the same 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. @@ -206,13 +207,17 @@ version, dataset and region it calculates on. - `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, trigger `manual`, - and a new run of each side's simulation that reuses none. 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; it refuses with `RunInProgressError` only while a - budget-window run of the report is under way. A forced one - (`NewReportRerun.forced`) takes no lock, always creates its runs, marked - `forced`, and reuses none. `insert_simulation_rerun` joins or creates the + 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; it refuses + with `RunInProgressError` only while a budget-window run of the report is + under way. A forced one (`NewReportRerun.forced`) takes no lock, always + creates a new run of each side, marked `forced`, and joins none. No side + of a report's re-run names a reused run. `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 @@ -243,8 +248,9 @@ 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. `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. +the stored region code and dataset name, and each side's values, with, given +`reuse`, its reusable run of its own simulation, never giving both sides the +same run; the service passes none, as its re-runs join or force their runs. `read_window_rerun_inputs` does the same for each year of a window. `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/src/policyengine_simulation_persistence/economy_rerun_records.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_rerun_records.py index e088d18cc..07ea81f75 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,14 +7,15 @@ ``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`` - 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. +- 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 report re-run's side joins its simulation's run on the current + versions instead, when there is one. A report's new run has trigger + ``manual``. 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, marked forced: household + runs are never reused or joined. The record itself is never changed: the service may not update ``reports`` or ``simulations``, so a report keeps naming the simulations it was created @@ -63,6 +64,9 @@ from policyengine_simulation_persistence.household_report_records import ( insert_household_simulation_run, ) +from policyengine_simulation_persistence.keyed_economy_records import ( + find_or_insert_side_runs, +) from policyengine_simulation_persistence.rerun_definitions import ( RecordKind, ReportDefinition, @@ -77,7 +81,6 @@ find_joinable_report_run, find_or_insert_report_run, find_or_insert_simulation_run, - find_or_insert_simulation_runs, ) from policyengine_simulation_persistence.tables import ( ReportRunStatus, @@ -107,11 +110,13 @@ @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. With ``reused`` (an unforced + budget window's year only), the run is one of its runs that succeeded + on the current versions, and nothing is created for the side; otherwise + ``simulation_run_id`` is the run created, pending, or the ID an economy + report's side proposes, used only if it inserts the run. """ simulation_id: UUID @@ -123,11 +128,11 @@ class RerunSide: class NewReportRerun: """A stored report's new run, on the current versions and catalog rows. - ``forced`` makes it a forced re-run's extra run, which calculates both - sides. ``sides_join_runs`` (a keyed report's unforced re-run) makes each - side join its simulation's unfailed, unforced run on the re-run's - versions rather than insert one; a side's ``simulation_run_id`` is then - the ID it proposes, used only if it inserts the run. + 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. No side names a reused run. """ report_id: UUID @@ -137,24 +142,21 @@ class NewReportRerun: baseline: RerunSide reform: RerunSide forced: bool = False - sides_join_runs: bool = False def __post_init__(self) -> None: - """Refuse a forced re-run naming a run it doesn't create, or joining one.""" - if self.forced and ( - self.baseline.reused or self.reform.reused or self.sides_join_runs - ): - msg = "a forced re-run calculates both sides, reusing and joining no run" + """Refuse a side naming a reused run: each side joins or creates its run.""" + if self.baseline.reused or self.reform.reused: + msg = "a report re-run's sides join or create their runs, reusing none" raise ValueError(msg) @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) @@ -301,18 +303,14 @@ def insert_report_rerun( report is pending or running (the service re-runs a budget window with ``insert_window_rerun``; one passed here directly is refused that way), 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 create the new run and - its sides' new simulation runs; a forced re-run's are marked forced, and - never joined. Return the run and whether this call created it, which - only then needs its Modal call. - - A side's new simulation run is a plain insert, so while that side's - simulation has another run on these versions that hasn't failed (one - another report run is calculating, or one ``find_reusable_run_of`` - didn't offer), the Public API's index refuses it and the database error - propagates, which the service answers 503 ``database_unavailable``; - finding a side's run by version set waits for C1 · 24's answers 4 and - 5. + 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 @@ -370,43 +368,36 @@ def insert_report_rerun( def _side_runs(connection: Connection, rerun: NewReportRerun) -> tuple[UUID, UUID]: """Return the baseline's and the reform's run, joined or inserted for the re-run. - A reused side names its run. With ``sides_join_runs`` (a keyed report's - unforced re-run), every other side joins its simulation's run on the - re-run's versions that hasn't failed and wasn't forced, or inserts one, - in simulation ID order, one run for one simulation on both sides. - Otherwise each other side inserts a new run, forced on a forced re-run. + A forced re-run inserts a new run of each side's simulation, marked + forced. Otherwise each side joins its simulation's run on the re-run's + versions that hasn't failed and wasn't forced, or inserts one, one run + for one simulation on both sides (``find_or_insert_side_runs``). """ - sides = (rerun.baseline, rerun.reform) - if not rerun.sides_join_runs: - for side in sides: - if not side.reused: - insert_simulation_run( - connection, - run_id=side.simulation_run_id, - simulation_id=side.simulation_id, - population=rerun.population, - versions=rerun.versions, - forced=rerun.forced, - ) + if rerun.forced: + for side in (rerun.baseline, rerun.reform): + insert_simulation_run( + connection, + run_id=side.simulation_run_id, + simulation_id=side.simulation_id, + population=rerun.population, + versions=rerun.versions, + forced=True, + ) return rerun.baseline.simulation_run_id, rerun.reform.simulation_run_id - # The reform first, so one simulation on both sides keeps the baseline's - # proposed ID. - rows = { - side.simulation_id: simulation_run_row( - run_id=side.simulation_run_id, - simulation_id=side.simulation_id, - population=rerun.population, - versions=rerun.versions, - ) - for side in reversed(sides) - if not side.reused - } - found = find_or_insert_simulation_runs(connection, rows) - baseline_run_id, reform_run_id = ( - side.simulation_run_id if side.reused else found[side.simulation_id].id - for side in sides + found = find_or_insert_side_runs( + connection, + simulation_ids={ + "baseline": rerun.baseline.simulation_id, + "reform": rerun.reform.simulation_id, + }, + proposed_run_ids={ + "baseline": rerun.baseline.simulation_run_id, + "reform": rerun.reform.simulation_run_id, + }, + population=rerun.population, + versions=rerun.versions, ) - return baseline_run_id, reform_run_id + return found["baseline"].id, found["reform"].id def _created(rerun: NewReportRerun) -> FoundReportRun: 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 index 65ea1daf3..dbe4837e0 100644 --- 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 @@ -54,6 +54,7 @@ ) if TYPE_CHECKING: + from collections.abc import Mapping from uuid import UUID from sqlalchemy import Connection @@ -181,10 +182,17 @@ def find_or_create_economy_report( # and the savepoint takes back this request's simulation runs. savepoint = connection.begin_nested() try: - runs = _find_or_insert_simulation_runs(connection, request, simulation_ids) - side_runs: dict[Side, UUID] = { - side: runs[simulation_ids[side]].id for side in _SIDES - } + runs = find_or_insert_side_runs( + connection, + simulation_ids=simulation_ids, + proposed_run_ids={ + "baseline": request.baseline.simulation_run_id, + "reform": request.reform.simulation_run_id, + }, + population=request.population, + versions=request.versions, + ) + side_runs: dict[Side, UUID] = {side: runs[side].id for side in _SIDES} run = find_or_insert_report_run( connection, _report_run_row(request, report.id, side_runs) ) @@ -254,29 +262,36 @@ def _find_or_insert_simulations( return simulation_ids -def _find_or_insert_simulation_runs( +def find_or_insert_side_runs( connection: Connection, - request: KeyedEconomyReport, - simulation_ids: dict[Side, UUID], -) -> dict[UUID, FoundSimulationRun]: - """Return each distinct simulation's run, found or inserted, by simulation ID. - - Inserted in simulation ID order; one simulation on both sides gets one - run, with the baseline's proposed ID. + *, + simulation_ids: Mapping[Side, UUID], + proposed_run_ids: Mapping[Side, UUID], + population: EconomyPopulation, + versions: RunVersions, +) -> dict[Side, FoundSimulationRun]: + """Return each side's run of its simulation on these versions, found or inserted. + + Each distinct simulation's run on ``versions`` and ``population``'s + catalog version and year that hasn't failed and wasn't forced is found, + or inserted with its side's proposed ID, in simulation ID order + (``find_or_insert_simulation_runs``). One simulation on both sides gets + one run, with the baseline's proposed ID. A keyed report's create and + an unforced re-run of it both name their sides' runs this way. """ - proposed_sides = {"baseline": request.baseline, "reform": request.reform} rows = { simulation_ids[side]: simulation_run_row( - run_id=proposed_sides[side].simulation_run_id, + run_id=proposed_run_ids[side], simulation_id=simulation_ids[side], - population=request.population, - versions=request.versions, + population=population, + versions=versions, ) # The reform first, so one simulation on both sides keeps the # baseline's proposed ID. for side in reversed(_SIDES) } - return find_or_insert_simulation_runs(connection, rows) + found = find_or_insert_simulation_runs(connection, rows) + return {side: found[simulation_ids[side]] for side in _SIDES} def _simulation_row( diff --git a/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py b/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py index c0ddff96b..882101dbf 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py @@ -357,31 +357,18 @@ def test_another_simulations_run_is_not_reused_for_a_simulations_rerun( 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(), + reused=False, + ), reform=RerunSide( simulation_id=stored.reform.simulation_id, simulation_run_id=uuid4(), @@ -390,15 +377,19 @@ def _rerun_of( ) -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, economy, 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) @@ -407,7 +398,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 ( @@ -424,7 +414,7 @@ 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, @@ -458,9 +448,10 @@ 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 def _unforced_rerun_on_unchanged_versions( @@ -1060,12 +1051,13 @@ def test_a_forced_report_rerun_is_an_extra_run_beside_any_run_on_its_versions( assert earlier_run["forced"] is False -def test_a_forced_rerun_calculates_both_sides() -> None: - """A forced re-run never names a run it didn't create (answer 3).""" +@pytest.mark.parametrize("forced", [True, False]) +def test_a_report_rerun_names_no_reused_run(forced: bool) -> None: # noqa: FBT001 # the parameter + """Each side joins or creates its run; a forced one creates it (answer 3).""" reused = RerunSide(simulation_id=uuid4(), simulation_run_id=uuid4(), reused=True) created = RerunSide(simulation_id=uuid4(), simulation_run_id=uuid4(), reused=False) - with pytest.raises(ValueError, match="forced"): + with pytest.raises(ValueError, match="reusing none"): NewReportRerun( report_id=uuid4(), run_id=uuid4(), @@ -1078,7 +1070,7 @@ def test_a_forced_rerun_calculates_both_sides() -> None: versions=VERSIONS, baseline=reused, reform=created, - forced=True, + forced=forced, ) diff --git a/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py b/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py index ae47a2b18..a203ac9c9 100644 --- a/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py @@ -644,7 +644,6 @@ def test_a_keyed_reports_rerun_joins_each_sides_run_on_its_versions( versions=VERSIONS, baseline=RerunSide(created.baseline.simulation_id, uuid4(), reused=False), reform=RerunSide(created.reform.simulation_id, uuid4(), reused=False), - sides_join_runs=True, ) found = insert_report_rerun(connection, rerun) @@ -678,7 +677,6 @@ def test_a_keyed_rerun_with_one_simulation_on_both_sides_inserts_one_run( versions=VERSIONS, baseline=RerunSide(simulation_id, uuid4(), reused=False), reform=RerunSide(simulation_id, uuid4(), reused=False), - sides_join_runs=True, ) found = insert_report_rerun(connection, rerun) 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 766eadbaa..14a619bcf 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 @@ -237,16 +237,17 @@ class EconomySimulationCreated(_Answer): class EconomyReportCreated(_Answer): - """The report 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 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 - re-run that joined a run answers that run's status as read. Each side + """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: a run that already succeeded, or, - on a joined run, that run's own. + 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 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 b5cac1f95..0a87f0fa9 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 @@ -303,7 +303,6 @@ async def rerun_report( baseline=self._new_side(stored.baseline.simulation_id), reform=self._new_side(stored.reform.simulation_id), forced=forced, - sides_join_runs=not forced, ) scope = rerun_scope( stored.country, @@ -337,10 +336,8 @@ async def rerun_report( calculation, report_id=report_id, run_id=rerun.run_id, - # A keyed report's simulation runs may be another report run's. - new_simulation_run_ids=() - if rerun.sides_join_runs - else 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, ) 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 af4d0db0c..c238bbf70 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 @@ -27,8 +27,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. @@ -176,9 +177,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, @@ -559,7 +561,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: an economy " + "report found or created by key, with its run on the default " + "worker's versions, joined (no new call) or created and " + "started; a budget-window or household report and its first " + "runs, created" + ) + }, 400: _REFUSED, 403: FORBIDDEN_ANSWER, 422: _UNPROCESSABLE, @@ -597,7 +607,13 @@ async def create_report(body: ReportRequest, request: Request) -> JSONResponse: 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/tests/test_economy_reruns.py b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py index 2c10ce410..4be1e21f5 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py @@ -235,7 +235,7 @@ def test_a_keyed_reports_rerun_has_each_side_join_its_run_on_the_versions() -> N assert store.rerun_reads[0][1][2] is None (created,) = store.report_reruns - assert created.sides_join_runs is True + assert created.forced is False assert (created.baseline.reused, created.reform.reused) == (False, False) payload = ReportExecutionInput.model_validate(caller.report_runs[0][1]) assert payload.baseline.simulation_execution_id == joined_baseline_run @@ -289,7 +289,7 @@ def test_a_keyed_reports_forced_rerun_joins_nothing() -> None: ) (created,) = store.report_reruns - assert (created.forced, created.sides_join_runs) == (True, False) + 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) diff --git a/projects/policyengine-simulation-entry/tests/test_openapi.py b/projects/policyengine-simulation-entry/tests/test_openapi.py index a8903d83f..d3e89aec1 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 From e8d4d43d22f3ade0c1f2c411e9ec0bc3ce030af2 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:59:38 +0400 Subject: [PATCH 067/107] Test one household simulation run named on both sides of a calculation (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From C1 · 26's c1158144 and dba70353 (its contract and builder tests only): a household report comparing a policy with itself names that simulation's one run on both sides, which the household contract must accept when both sides are one calculation, policy included. Keyed household reports (C1 · 24's answer 8) name such a run. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_household_report_execution.py | 19 +++++++++++++++--- .../test_household_report_submissions.py | 20 +++++++++++-------- 2 files changed, 28 insertions(+), 11 deletions(-) diff --git a/libs/policyengine-simulation-contract/tests/test_household_report_execution.py b/libs/policyengine-simulation-contract/tests/test_household_report_execution.py index c0236beea..a29e29da7 100644 --- a/libs/policyengine-simulation-contract/tests/test_household_report_execution.py +++ b/libs/policyengine-simulation-contract/tests/test_household_report_execution.py @@ -91,9 +91,22 @@ def test_a_calculation_round_trips_through_json() -> None: assert HouseholdReportRunCalculation.model_validate(payload) == calculation -def test_each_side_is_its_own_calculation() -> None: - with pytest.raises(ValidationError, match="different simulation runs"): - _calculation(reform=_request(BASELINE_RUN_ID)) +def test_one_simulation_run_may_be_both_sides_of_one_calculation() -> None: + # A household report comparing a policy with itself names that + # simulation's one run on both sides. + calculation = _calculation(reform=_request(BASELINE_RUN_ID)) + + assert [request.calculation_id for _, request in calculation.sides()] == [ + BASELINE_RUN_ID, + BASELINE_RUN_ID, + ] + + +def test_one_simulation_run_on_both_sides_must_have_one_policy() -> None: + with pytest.raises(ValidationError, match="one simulation run on both sides"): + _calculation( + reform=_request(BASELINE_RUN_ID, policy={"parameters": CTC_REFORM}) + ) @pytest.mark.parametrize( 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 48f9b1714..c2afb66f8 100644 --- a/projects/policyengine-simulation-entry/tests/test_household_report_submissions.py +++ b/projects/policyengine-simulation-entry/tests/test_household_report_submissions.py @@ -503,17 +503,21 @@ def test_a_stored_household_the_builder_cannot_read_is_not_calculable(): assert [reason.type for reason in raised.value.reasons] == ["household_unreadable"] -def test_two_sides_recording_one_simulation_run_are_built_wrong(): - side = HouseholdReportSideInputs( - simulation_run_id=BASELINE_RUN_ID, policy_values={} - ) - - with pytest.raises(HouseholdReportBuildError, match="different simulation runs"): +def test_one_simulation_run_on_both_sides_with_two_policies_is_built_wrong(): + # One run on both sides is one calculation, which a report comparing a + # policy with itself names; with two policies it can't be one. + with pytest.raises( + HouseholdReportBuildError, match="one simulation run on both sides" + ): household_report_calculation( household=_stored_household(), year=2026, - baseline=side, - reform=side, + baseline=HouseholdReportSideInputs( + simulation_run_id=BASELINE_RUN_ID, policy_values={} + ), + reform=HouseholdReportSideInputs( + simulation_run_id=BASELINE_RUN_ID, policy_values=REFORM + ), worker=manifest_household_worker("us"), ) From 5f373f7f5354de5d72f3e69aeba074bffdbe4826 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:59:52 +0400 Subject: [PATCH 068/107] Accept one household simulation run on both sides of one calculation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From C1 · 26's dba70353 (its contract part only): two sides may name one simulation run when they are one calculation, policy included, as a household report comparing a policy with itself does once its simulations are found by key. Co-Authored-By: Claude Opus 5.5 --- .../household_report_execution.py | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/household_report_execution.py b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/household_report_execution.py index 2f710697b..f979989e5 100644 --- a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/household_report_execution.py +++ b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/household_report_execution.py @@ -44,11 +44,22 @@ class HouseholdReportRunCalculation(StrictHouseholdModel): @model_validator(mode="after") def validate_one_household(self) -> HouseholdReportRunCalculation: - """Require two sides to record different runs of one household calculation.""" + """Require two sides to calculate one household the same way. + + They record different simulation runs, except a report comparing a + policy with itself, which names that simulation's one run on both + sides: its two sides are then one calculation, policy included. + """ if self.reform is None: return self - if self.reform.calculation_id == self.baseline.calculation_id: - msg = "the baseline and the reform must record different simulation runs" + if ( + self.reform.calculation_id == self.baseline.calculation_id + and self.reform.policy != self.baseline.policy + ): + msg = ( + "a household report naming one simulation run on both sides " + "must give both the same policy" + ) raise ValueError(msg) baseline = self.baseline.model_dump(include=_SHARED_FIELDS) reform = self.reform.model_dump(include=_SHARED_FIELDS) From f1ebcbce4aaad5327388db6c41000ea6cf431db8 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:01:45 +0400 Subject: [PATCH 069/107] Test the keys of household simulations and reports (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's answer 8: household reports are found by key, as economy ones are. A household simulation is keyed by its country, policy, dynamic, stored household's ID (in place of a dataset and region) and year; a household report by both sides (the reform null for a report of the baseline alone), its household and its year. Its dataset-independent key, which the Public API's check requires with the other two, differs only in its record name, as it has no dataset. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_definition_keys.py | 118 ++++++++++++++++++ 1 file changed, 118 insertions(+) diff --git a/libs/policyengine-simulation-persistence/tests/test_definition_keys.py b/libs/policyengine-simulation-persistence/tests/test_definition_keys.py index 99de4fb75..e6bff982b 100644 --- a/libs/policyengine-simulation-persistence/tests/test_definition_keys.py +++ b/libs/policyengine-simulation-persistence/tests/test_definition_keys.py @@ -12,6 +12,8 @@ KEY_VERSION, EconomyReportDefinition, EconomySimulationDefinition, + HouseholdReportDefinition, + HouseholdSimulationDefinition, SimulationChoice, canonical_json, definition_key, @@ -213,3 +215,119 @@ def test_reports_differing_only_in_their_dataset_share_that_key() -> None: 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 + ) From 07841132dcf3c830576508e95a4cecba10e252f8 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:02:49 +0400 Subject: [PATCH 070/107] Key household simulations and reports HouseholdSimulationDefinition keys a household simulation by its country, policy, dynamic, stored household and year; HouseholdReportDefinition keys a household report by its sides, household and year, gives each side's simulation definition, and a dataset-independent key under its own record name. 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. Co-Authored-By: Claude Opus 5.5 --- .../__init__.py | 4 + .../definition_keys.py | 110 +++++++++++++++++- 2 files changed, 112 insertions(+), 2 deletions(-) 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 fb716b82f..8d4470e1f 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py @@ -17,6 +17,8 @@ KEY_VERSION, EconomyReportDefinition, EconomySimulationDefinition, + HouseholdReportDefinition, + HouseholdSimulationDefinition, canonical_json, definition_key, ) @@ -209,10 +211,12 @@ "HouseholdJobReferenceError", "HouseholdJobStatus", "HouseholdJobStore", + "HouseholdReportDefinition", "HouseholdReportInputs", "HouseholdReportSimulation", "HouseholdReportStore", "HouseholdRerunSide", + "HouseholdSimulationDefinition", "KeyedEconomyReport", "KeyedEconomySimulation", "MissingPolicyParametersError", 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 index e08539299..5583fe336 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/definition_keys.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/definition_keys.py @@ -16,7 +16,9 @@ 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. +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 @@ -36,8 +38,9 @@ # The format of every key this module builds. KEY_VERSION: Final = 1 -# A report's type, as the key and the Public API name it. +# 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: @@ -183,3 +186,106 @@ def simulation( 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, + ) From d9491db7b6ea4408d2e3301ea3b956b5eb464806 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:04:55 +0400 Subject: [PATCH 071/107] Test finding or creating household reports by key (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's answer 8: a household report request finds its simulations by key, then the report by key, then the report's run on the current versions that hasn't failed and wasn't forced, or creates what is missing. Tested: the first request inserts everything with its keys; an identical one ends on the same rows and inserts nothing; a policy compared with itself names one simulation run on both sides; a report of the baseline alone names no reform; a report sharing a side joins that side's run under way; a failed report run gets a new run on the same simulation runs; the store runs it in a transaction; and a request proposing a reform side without a reform is refused. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_keyed_household_records.py | 405 ++++++++++++++++++ 1 file changed, 405 insertions(+) create mode 100644 libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py 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..35edee6f1 --- /dev/null +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py @@ -0,0 +1,405 @@ +"""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, + FoundSide, + HouseholdReportDefinition, + HouseholdReportStore, + KeyedHouseholdReport, + ProposedSide, + ReportRunStatus, + ReportRunTrigger, + RunVersions, + SimulationChoice, + SimulationStatus, + find_or_create_household_report, +) +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()) + ), + label="A larger child tax credit", + description=None, + 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", + ) + } == { + "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, + } + assert (report["baseline_simulation_id"], report["reform_simulation_id"]) == ( + request.baseline.simulation_id, + request.reform.simulation_id, + ) + assert report_run["trigger"] == ReportRunTrigger.INITIAL + 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()), + ) From 05bfcde1d08f65bcaf62a9c43777d24c634415a8 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:07:05 +0400 Subject: [PATCH 072/107] Find or create household reports by key MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's answer 8. find_or_create_household_report finds each side's household simulation by key, in key order, then the report by key, then the report's run on the current versions that hasn't failed and wasn't forced; otherwise, inside a savepoint, each distinct simulation's run on those versions and the report run naming them, as an economy report's create does. HouseholdReportStore.find_or_create_report runs it in a transaction of its own. find_or_insert_side_runs now takes each side's run row, economy or household (household_simulation_run_row, which the household run insert now shares), and a report of the baseline alone has no reform side. Co-Authored-By: Claude Opus 5.5 --- .../__init__.py | 8 + .../economy_rerun_records.py | 19 +- .../household_report_records.py | 47 ++- .../household_report_store.py | 30 +- .../keyed_economy_records.py | 49 ++- .../keyed_household_records.py | 300 ++++++++++++++++++ 6 files changed, 404 insertions(+), 49 deletions(-) create mode 100644 libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/keyed_household_records.py 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 8d4470e1f..37b96f65e 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py @@ -137,6 +137,11 @@ 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.policy_reform import ( MissingPolicyParametersError, OverlappingReformError, @@ -202,6 +207,7 @@ "EconomySimulationState", "FoundEconomyReport", "FoundEconomySimulation", + "FoundHouseholdReport", "FoundReportRun", "FoundRow", "FoundSide", @@ -219,6 +225,7 @@ "HouseholdSimulationDefinition", "KeyedEconomyReport", "KeyedEconomySimulation", + "KeyedHouseholdReport", "MissingPolicyParametersError", "NewBudgetWindowReport", "NewEconomyReport", @@ -278,6 +285,7 @@ "find_joinable_report_run", "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", 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 07ea81f75..6aeb6827f 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 @@ -101,6 +101,7 @@ EconomyPopulation, RunVersions, ) + from policyengine_simulation_persistence.keyed_economy_records import Side from policyengine_simulation_persistence.shared_rows import FoundSimulationRun # Every run table's statuses (simulation, report and budget-window runs) use @@ -384,18 +385,18 @@ def _side_runs(connection: Connection, rerun: NewReportRerun) -> tuple[UUID, UUI forced=True, ) return rerun.baseline.simulation_run_id, rerun.reform.simulation_run_id + sides: dict[Side, RerunSide] = {"baseline": rerun.baseline, "reform": rerun.reform} found = find_or_insert_side_runs( connection, - simulation_ids={ - "baseline": rerun.baseline.simulation_id, - "reform": rerun.reform.simulation_id, - }, - proposed_run_ids={ - "baseline": rerun.baseline.simulation_run_id, - "reform": rerun.reform.simulation_run_id, + { + name: simulation_run_row( + run_id=side.simulation_run_id, + simulation_id=side.simulation_id, + population=rerun.population, + versions=rerun.versions, + ) + for name, side in sides.items() }, - population=rerun.population, - versions=rerun.versions, ) return found["baseline"].id, found["reform"].id 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 9d8cc062d..083c1a77c 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 @@ -194,16 +194,41 @@ def insert_household_simulation_run( # noqa: PLR0913 # the run and what it cal """ 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, - forced=forced, + { + **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..4326c2619 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 @@ -42,6 +42,9 @@ 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, UnknownPolicyError, @@ -65,6 +68,10 @@ 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.tables import ReportRunStatus @@ -176,6 +183,19 @@ def read_inputs( reforms=reforms, ) + def find_or_create_report( + self, report: KeyedHouseholdReport + ) -> FoundHouseholdReport: + """Find the report by key, with its run, or create them. + + See ``find_or_create_household_report``; raise its errors, and + EconomyRecordOutcomeUnknownError when the commit fails after the + rows were inserted. + """ + return self._create( + lambda connection: find_or_create_household_report(connection, report) + ) + def create_report(self, report: NewHouseholdReport) -> None: """Create the report, its simulations and its runs. @@ -195,18 +215,22 @@ def create_report_rerun(self, rerun: NewHouseholdReportRerun) -> None: 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 index dbe4837e0..2d4bfa538 100644 --- 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 @@ -182,15 +182,18 @@ def find_or_create_economy_report( # and the savepoint takes back this request's simulation runs. savepoint = connection.begin_nested() try: + proposed = {"baseline": request.baseline, "reform": request.reform} runs = find_or_insert_side_runs( connection, - simulation_ids=simulation_ids, - proposed_run_ids={ - "baseline": request.baseline.simulation_run_id, - "reform": request.reform.simulation_run_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 }, - population=request.population, - versions=request.versions, ) side_runs: dict[Side, UUID] = {side: runs[side].id for side in _SIDES} run = find_or_insert_report_run( @@ -263,35 +266,29 @@ def _find_or_insert_simulations( def find_or_insert_side_runs( - connection: Connection, - *, - simulation_ids: Mapping[Side, UUID], - proposed_run_ids: Mapping[Side, UUID], - population: EconomyPopulation, - versions: RunVersions, + connection: Connection, side_rows: Mapping[Side, Mapping[str, Any]] ) -> dict[Side, FoundSimulationRun]: - """Return each side's run of its simulation on these versions, found or inserted. - - Each distinct simulation's run on ``versions`` and ``population``'s - catalog version and year that hasn't failed and wasn't forced is found, - or inserted with its side's proposed ID, in simulation ID order + """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. A keyed report's create and - an unforced re-run of it both name their sides' runs this way. + one run, with the baseline's proposed ID. Keyed reports' creates and + unforced re-runs name their sides' runs this way. """ rows = { - simulation_ids[side]: simulation_run_row( - run_id=proposed_run_ids[side], - simulation_id=simulation_ids[side], - population=population, - versions=versions, - ) + 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[simulation_ids[side]] for side in _SIDES} + return {side: found[row["simulation_id"]] for side, row in side_rows.items()} def _simulation_row( 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..0008fb0d3 --- /dev/null +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/keyed_household_records.py @@ -0,0 +1,300 @@ +"""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 (``find_or_insert_side_runs``), 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. + +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_side_runs, +) +from policyengine_simulation_persistence.shared_rows import ( + FoundReportRun, + find_joinable_report_run, + find_or_insert_report, + find_or_insert_report_run, + find_or_insert_simulation, +) +from policyengine_simulation_persistence.tables import ( + ReportRunStatus, + ReportRunTrigger, + 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``. ``label`` and ``description`` are + stored only by the request that creates the report. + """ + + definition: HouseholdReportDefinition + report_id: UUID + run_id: UUID + baseline: ProposedSide + reform: ProposedSide | None + label: str + description: str | 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()) + # A report run another request inserts after the lookup is joined, + # and the savepoint takes back this request's simulation runs. + savepoint = connection.begin_nested() + try: + runs = find_or_insert_side_runs( + connection, + { + 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() + }, + ) + run = find_or_insert_report_run( + connection, + _report_run_row( + request, report.id, {side: found.id for side, found in runs.items()} + ), + ) + except BaseException: + savepoint.rollback() + raise + if not run.inserted: + savepoint.rollback() + return _found(report.id, report.inserted, run, simulation_ids, set()) + savepoint.commit() + 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, + "label": request.label, + "description": request.description, + "country": definition.country, + "type": HOUSEHOLD_REPORT_TYPE, + "user_id": None, + "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, + side_runs: dict[Side, UUID], +) -> dict[str, Any]: + """Return the report's first run on these versions, naming its sides' runs.""" + return { + "id": request.run_id, + "report_id": report_id, + "baseline_simulation_run_id": side_runs["baseline"], + "reform_simulation_run_id": side_runs.get("reform"), + "budget_window_run_id": None, + "year": None, + "country_package_version": request.versions.country_package_version, + "policyengine_version": request.versions.policyengine_version, + "status": ReportRunStatus.PENDING, + "trigger": ReportRunTrigger.INITIAL, + "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"), + ) From 78af963a53814960dc3ace9f4bfd1659e23c453c Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:09:35 +0400 Subject: [PATCH 073/107] Test household re-runs that join a keyed report's run or are forced (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's answers 3 and 8, and interim answer B: a keyed household report's unforced re-run joins the report's run on its versions, or each side joins its simulation's run under a new report run, as an economy report's does; a forced re-run, which every re-run of a household report without keys is, is an extra run, marked forced, never joined and never refused while a run is under way, so the household re-run's 409 goes. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_household_report_reruns.py | 30 +++-- .../tests/test_keyed_household_records.py | 103 ++++++++++++++++++ 2 files changed, 126 insertions(+), 7 deletions(-) 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 daa59adfc..cc533adbc 100644 --- a/libs/policyengine-simulation-persistence/tests/test_household_report_reruns.py +++ b/libs/policyengine-simulation-persistence/tests/test_household_report_reruns.py @@ -28,7 +28,6 @@ ReportRunStatus, ReportRunTrigger, RerunRecordDeletedError, - RunInProgressError, RunVersions, SideDefinition, SimulationChoice, @@ -173,7 +172,11 @@ def _succeed_first_runs(connection: Connection, report: NewHouseholdReport) -> N def _rerun_of( report: NewHouseholdReport, 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(), @@ -190,6 +193,7 @@ def _rerun_of( simulation_id=report.reform.simulation_id, simulation_run_id=uuid4() ) ), + forced=True, ) @@ -360,16 +364,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, @@ -377,9 +382,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( @@ -458,6 +473,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_keyed_household_records.py b/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py index 35edee6f1..cb5e96aaa 100644 --- a/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py @@ -18,10 +18,13 @@ from conftest import act_as_the_service, rolled_back_transaction from policyengine_simulation_persistence import ( KEY_VERSION, + FoundHouseholdReport, FoundSide, HouseholdReportDefinition, HouseholdReportStore, + HouseholdRerunSide, KeyedHouseholdReport, + NewHouseholdReportRerun, ProposedSide, ReportRunStatus, ReportRunTrigger, @@ -29,6 +32,7 @@ SimulationChoice, SimulationStatus, find_or_create_household_report, + insert_household_report_rerun, ) from public_api_rows import ( CatalogVersion, @@ -403,3 +407,102 @@ def test_a_request_proposing_a_reform_side_for_a_report_without_one_is_refused() 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 == found.run + 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"]) == ( + ReportRunTrigger.MANUAL, + 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] From 67bd61d5b6781b19864a3064f259b6cd8f761c31 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:12:25 +0400 Subject: [PATCH 074/107] Join a keyed household report's run on re-run, or force an extra run MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's answers 3 and 8, and interim answer B. insert_household_report_rerun now joins or creates as insert_report_rerun does: unforced, as a keyed household report's re-run is, it takes the report's re-run lock and joins the report's run on its versions, or else each side joins its own household simulation's run on them or inserts one, under a new report run. A forced re-run, as every re-run of a household report without keys is, takes no lock, is never refused, and marks its runs forced. It returns the run, as HouseholdReportStore.create_report_rerun does. find_or_insert_report_run_on_sides is the savepoint step keyed creates and unforced re-runs, economy and household, now share: each side's run found or inserted, then the report run naming them, a competing one joined and this call's simulation runs taken back. The service still sends unforced household re-runs; the next commits force them for reports without keys. Co-Authored-By: Claude Opus 5.5 --- .../README.md | 31 +- .../economy_rerun_records.py | 292 ++++++++++-------- .../household_report_store.py | 9 +- .../keyed_economy_records.py | 93 +++--- .../keyed_household_records.py | 66 ++-- .../tests/test_keyed_household_records.py | 2 +- 6 files changed, 261 insertions(+), 232 deletions(-) diff --git a/libs/policyengine-simulation-persistence/README.md b/libs/policyengine-simulation-persistence/README.md index fc9276520..712857991 100644 --- a/libs/policyengine-simulation-persistence/README.md +++ b/libs/policyengine-simulation-persistence/README.md @@ -157,9 +157,12 @@ report and run rows (C1 · 24). Three modules do it: 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 by `find_or_insert_side_runs`, and the report run naming - them, a competing report run joined with the savepoint rolled back. - `find_or_create_economy_simulation` does the same for one + 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. @@ -235,17 +238,17 @@ re-run, never refused, whose year runs and simulation runs are marked `forced`. 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. A household report has no keys yet, so the -report run and both simulation runs are marked `forced`, extra runs that -nothing joins and the one-unfailed-run indexes leave out (C1 · 24's interim -answer B). 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 (trigger `manual`). 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, with, given 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 6aeb6827f..55dea197a 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 @@ -9,29 +9,29 @@ version's rows with the same code and name can be found; - 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 report re-run's side joins its simulation's run on the current - versions instead, when there is one. A report's new run has trigger - ``manual``. 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, marked forced: household - runs are never reused or joined. + economy or household report re-run's side joins its simulation's run on + the current versions instead, when there is one. A report's new run has + trigger ``manual``. 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 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. A simulation's re-run, and an unforced economy 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 and 3; ``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, and every household report's, joins nothing: it is refused while a -run of the report is ``pending`` or ``running`` (a budget-window run or a -report run). A simulation's re-run takes no lock. +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 nothing: it is refused while a run of the report is +``pending`` or ``running`` (a budget-window run or a report run); the +service forces every window re-run, as windows have no keys yet. 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 @@ -62,10 +62,11 @@ simulation_run_row, ) from policyengine_simulation_persistence.household_report_records import ( + household_simulation_run_row, insert_household_simulation_run, ) from policyengine_simulation_persistence.keyed_economy_records import ( - find_or_insert_side_runs, + find_or_insert_report_run_on_sides, ) from policyengine_simulation_persistence.rerun_definitions import ( RecordKind, @@ -79,7 +80,6 @@ from policyengine_simulation_persistence.shared_rows import ( FoundReportRun, find_joinable_report_run, - find_or_insert_report_run, find_or_insert_simulation_run, ) from policyengine_simulation_persistence.tables import ( @@ -92,7 +92,7 @@ ) if TYPE_CHECKING: - from collections.abc import Iterator + from collections.abc import Iterator, Mapping from uuid import UUID from sqlalchemy import Column, ColumnElement, Connection, Table @@ -207,9 +207,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``, marked forced like the report run; ``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 @@ -219,6 +221,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, ...]: @@ -227,7 +238,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) @@ -267,11 +282,10 @@ def lock_reruns_of(connection: Connection, record_id: UUID) -> None: 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 waits here until the first one's transaction ends, then sees its run, which an economy - report's re-run joins and a budget-window or household report's is - refused for. 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 economy - or budget-window re-run, which nothing joins; a household report's - re-run takes it, forced or not. + or household report's re-run joins and a budget window's is refused + for. 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( @@ -331,9 +345,45 @@ def insert_report_rerun( ) if joined is not None: return joined - row: dict[str, Any] = { - "id": rerun.run_id, - "report_id": rerun.report_id, + 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(): + 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=versions, + forced=True, + ) + 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 _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.""" + return { + "id": run_id, + "report_id": report_id, "budget_window_run_id": None, "year": None, "country_package_version": versions.country_package_version, @@ -341,74 +391,34 @@ def insert_report_rerun( "status": ReportRunStatus.PENDING, "trigger": ReportRunTrigger.MANUAL, "modal_call_id": None, - "forced": rerun.forced, } - with _record_checked(report_runs.c.report_id), references_checked(): - # A run another request created after the lookup above is joined, - # and the savepoint takes back this call's simulation runs with it. - savepoint = connection.begin_nested() - try: - baseline_run_id, reform_run_id = _side_runs(connection, rerun) - row["baseline_simulation_run_id"] = baseline_run_id - row["reform_simulation_run_id"] = reform_run_id - if rerun.forced: - connection.execute(insert(report_runs).values(row)) - found = _created(rerun) - else: - found = find_or_insert_report_run(connection, row) - except BaseException: - savepoint.rollback() - raise - if found.inserted: - savepoint.commit() - else: - savepoint.rollback() - return found - -def _side_runs(connection: Connection, rerun: NewReportRerun) -> tuple[UUID, UUID]: - """Return the baseline's and the reform's run, joined or inserted for the re-run. - A forced re-run inserts a new run of each side's simulation, marked - forced. Otherwise each side joins its simulation's run on the re-run's - versions that hasn't failed and wasn't forced, or inserts one, one run - for one simulation on both sides (``find_or_insert_side_runs``). - """ - if rerun.forced: - for side in (rerun.baseline, rerun.reform): - insert_simulation_run( - connection, - run_id=side.simulation_run_id, - simulation_id=side.simulation_id, - population=rerun.population, - versions=rerun.versions, - forced=True, - ) - return rerun.baseline.simulation_run_id, rerun.reform.simulation_run_id - sides: dict[Side, RerunSide] = {"baseline": rerun.baseline, "reform": rerun.reform} - found = find_or_insert_side_runs( - connection, - { - name: simulation_run_row( - run_id=side.simulation_run_id, - simulation_id=side.simulation_id, - population=rerun.population, - versions=rerun.versions, - ) - for name, side in sides.items() - }, +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 found["baseline"].id, found["reform"].id - - -def _created(rerun: NewReportRerun) -> FoundReportRun: - """Return the report run a re-run created, as a lookup would.""" return FoundReportRun( - id=rerun.run_id, + id=row["id"], inserted=True, status=ReportRunStatus.PENDING, - baseline_simulation_run_id=rerun.baseline.simulation_run_id, - reform_simulation_run_id=rerun.reform.simulation_run_id, + baseline_simulation_run_id=baseline_run_id, + reform_simulation_run_id=reform_run_id, ) @@ -472,48 +482,68 @@ def insert_window_rerun(connection: Connection, rerun: NewWindowRerun) -> None: 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; 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. A household report has no keys yet, so its runs may have - been calculated for it alone: each is an extra run, marked forced, that - nothing joins and the one-unfailed-run indexes leave out (C1 · 24's - interim answer B). 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, - 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=( - 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, - forced=True, - ) + 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_window_runs(connection: Connection, report_id: UUID) -> 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 4326c2619..0ddd4209e 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 @@ -73,6 +73,7 @@ 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]] @@ -205,13 +206,13 @@ def create_report(self, report: NewHouseholdReport) -> None: """ self._create(lambda connection: insert_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 + See ``insert_household_report_rerun``; raise its errors, and EconomyRecordOutcomeUnknownError as ``create_report`` does. """ - self._create( + return self._create( lambda connection: insert_household_report_rerun(connection, rerun) ) 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 index 2d4bfa538..a8123b0c5 100644 --- 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 @@ -28,7 +28,7 @@ from __future__ import annotations -from dataclasses import dataclass +from dataclasses import dataclass, replace from typing import TYPE_CHECKING, Any, Final, Literal from policyengine_simulation_persistence.definition_keys import KEY_VERSION @@ -178,34 +178,20 @@ def find_or_create_economy_report( ) if joined is not None: return _found(report.id, report.inserted, joined, simulation_ids, set()) - # A report run another request inserts after the lookup is joined, - # and the savepoint takes back this request's simulation runs. - savepoint = connection.begin_nested() - try: - proposed = {"baseline": request.baseline, "reform": request.reform} - runs = find_or_insert_side_runs( - connection, - { - 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 - }, - ) - side_runs: dict[Side, UUID] = {side: runs[side].id for side in _SIDES} - run = find_or_insert_report_run( - connection, _report_run_row(request, report.id, side_runs) - ) - except BaseException: - savepoint.rollback() - raise - if not run.inserted: - savepoint.rollback() - return _found(report.id, report.inserted, run, simulation_ids, set()) - savepoint.commit() + 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) @@ -265,6 +251,45 @@ def _find_or_insert_simulations( 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, which holds only when this call + inserted the report run (otherwise nothing it inserted is kept). + """ + 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, { + side: replace(found, inserted=False) for side, found in runs.items() + } + savepoint.commit() + return run, runs + + def find_or_insert_side_runs( connection: Connection, side_rows: Mapping[Side, Mapping[str, Any]] ) -> dict[Side, FoundSimulationRun]: @@ -341,17 +366,11 @@ def _report_row( } -def _report_run_row( - request: KeyedEconomyReport, - report_id: UUID, - side_runs: dict[Side, UUID], -) -> dict[str, Any]: - """Return the report's first run on these versions, naming its sides' runs.""" +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, - "baseline_simulation_run_id": side_runs["baseline"], - "reform_simulation_run_id": side_runs["reform"], "budget_window_run_id": None, "year": None, "country_package_version": request.versions.country_package_version, 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 index 0008fb0d3..dd95fa513 100644 --- 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 @@ -14,9 +14,10 @@ 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 (``find_or_insert_side_runs``), 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. + 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 @@ -42,13 +43,12 @@ FoundSide, ProposedSide, Side, - find_or_insert_side_runs, + 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_report_run, find_or_insert_simulation, ) from policyengine_simulation_persistence.tables import ( @@ -140,38 +140,20 @@ def find_or_create_household_report( ) if joined is not None: return _found(report.id, report.inserted, joined, simulation_ids, set()) - # A report run another request inserts after the lookup is joined, - # and the savepoint takes back this request's simulation runs. - savepoint = connection.begin_nested() - try: - runs = find_or_insert_side_runs( - connection, - { - 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() - }, - ) - run = find_or_insert_report_run( - connection, - _report_run_row( - request, report.id, {side: found.id for side, found in runs.items()} - ), - ) - except BaseException: - savepoint.rollback() - raise - if not run.inserted: - savepoint.rollback() - return _found(report.id, report.inserted, run, simulation_ids, set()) - savepoint.commit() + 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) @@ -247,17 +229,11 @@ def _report_row( } -def _report_run_row( - request: KeyedHouseholdReport, - report_id: UUID, - side_runs: dict[Side, UUID], -) -> dict[str, Any]: - """Return the report's first run on these versions, naming its sides' runs.""" +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, - "baseline_simulation_run_id": side_runs["baseline"], - "reform_simulation_run_id": side_runs.get("reform"), "budget_window_run_id": None, "year": None, "country_package_version": request.versions.country_package_version, diff --git a/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py b/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py index cb5e96aaa..1840c05ca 100644 --- a/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py @@ -452,7 +452,7 @@ def test_a_keyed_household_reports_rerun_joins_its_run_on_the_versions( _count(connection, name) for name in ("simulation_runs", "report_runs") ] - assert joined == found.run + assert joined == replace(found.run, inserted=False) assert counts_after == counts From 65643504969c9479a64b83ffce04a460ded214e9 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:16:24 +0400 Subject: [PATCH 075/107] Test household reports found by key and re-runs joining in the service (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's answers 3 and 8 and interim answer B, in the entry: a household report request finds or creates its report by key and starts a call only for a run it created, calculated on the side runs that run names (one run on both sides for a policy compared with itself); a request joining a run answers it as it is; Modal's refusal fails only the report run, whose simulation runs may be another report run's. A keyed household report's re-run joins its run, or is an extra forced run with force; a household report without keys is always re-run as forced runs. The fake household store finds or creates by key and can join, the re-run protocol's create returns the run, and the household create helper returns what its create returns. Co-Authored-By: Claude Opus 5.5 --- .../household_report_reruns.py | 5 +- .../household_report_submissions.py | 17 +-- .../tests/household_report_fakes.py | 73 +++++++++++- .../tests/test_household_report_reruns.py | 93 +++++++++++++-- .../test_household_report_submissions.py | 107 ++++++++++++++---- 5 files changed, 246 insertions(+), 49 deletions(-) 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..249193ddc 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 @@ -65,6 +65,7 @@ ) from policyengine_simulation_contract.stage12_bundle import CountryId from policyengine_simulation_persistence import ( + FoundReportRun, PolicyReform, ReportSide, SideDefinition, @@ -119,8 +120,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.""" ... 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..0588e39e5 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 @@ -615,22 +615,23 @@ def _prepare( ) 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: 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_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..d16ce0732 100644 --- a/projects/policyengine-simulation-entry/tests/test_household_report_submissions.py +++ b/projects/policyengine-simulation-entry/tests/test_household_report_submissions.py @@ -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,31 @@ 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") + # 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.label == "A larger child tax credit for one family" assert report.description == "Raises the credit to $3,000" 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 +181,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 +227,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 +328,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 +347,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 +372,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 +392,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 +448,10 @@ 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( +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 +462,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}).", ) From 07a1f4454fb2c0004494058b5156cb60e59192a6 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:20:17 +0400 Subject: [PATCH 076/107] Find or create household reports by key, and join or force their re-runs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's answers 3 and 8 and interim answer B, in the service. A household report request now finds or creates its simulations, report and run by key (KeyedHouseholdReport), checking each side's household contract request on the run IDs it proposes before writing anything; only a request that created the report run starts its household function call, on the side runs that run names, and Modal's refusal fails only that report run. A request that joined a run answers it as it is. A keyed household report's re-run joins its run, or each side's simulation run, as an economy one does; force makes it an extra forced run, and a household report without keys is always re-run that way. A forced re-run's simulation runs, which only it names, fail with it. The contract request building moved to household_report_calculations, which both services use; its names stay importable from household_report_submissions. Co-Authored-By: Claude Opus 5.5 --- .../economy_reruns.py | 7 +- .../household_report_calculations.py | 245 +++++++++++ .../household_report_reruns.py | 154 ++++--- .../household_report_submissions.py | 401 ++++++------------ .../rerunnable_records.py | 1 + 5 files changed, 483 insertions(+), 325 deletions(-) create mode 100644 projects/policyengine-simulation-entry/src/policyengine_simulation_entry/household_report_calculations.py 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 0a87f0fa9..73b254ca2 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 @@ -250,7 +250,9 @@ 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) refuse_stored_cliffs(definition.inputs) @@ -421,6 +423,7 @@ 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.""" @@ -430,7 +433,7 @@ async def _rerun_household_report( 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( 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 249193ddc..b85f33167 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 (trigger ``manual``) + 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 ( @@ -66,10 +75,9 @@ from policyengine_simulation_contract.stage12_bundle import CountryId from policyengine_simulation_persistence import ( FoundReportRun, - PolicyReform, + HouseholdReportInputs, ReportSide, SideDefinition, - StoredHousehold, ) from policyengine_simulation_entry.config import Settings @@ -96,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 @@ -104,6 +113,7 @@ class StoredHouseholdReport: year: int baseline: SideDefinition reform: SideDefinition | None + keyed: bool = False @property def sides(self) -> dict[ReportSide, SideDefinition]: @@ -132,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.""" ... @@ -147,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( @@ -176,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, @@ -187,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. @@ -228,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 0588e39e5..6061c5fd3 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,57 +424,51 @@ 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, + proposed = { + side: ProposedSide( + simulation_id=self._new_id(), simulation_run_id=self._new_id() ) - for side, policy_id in _policy_ids(request).items() + for side in _policy_ids(request) } - side_inputs = { - side: HouseholdReportSideInputs( - simulation_run_id=created.simulation_run_id, - policy_values=inputs.reforms[side], - ) - for side, created in sides.items() - } - 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, + baseline=proposed["baseline"], + reform=proposed.get("reform"), label=request.label, description=request.description, 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[Created]( self, @@ -640,7 +495,9 @@ async def _create[Created]( 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__}, @@ -660,9 +517,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( @@ -747,3 +605,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 index 43b124afb..71fd675ac 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/rerunnable_records.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/rerunnable_records.py @@ -178,6 +178,7 @@ def rerunnable_household_report( year=year, baseline=baseline, reform=definition.reform, + keyed=definition.keyed, ) From 2a57409e43145d63bfb5ded893126f97a07b2238 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:21:04 +0400 Subject: [PATCH 077/107] Call the contract-refusal helper where it now lives, in the builder's test 07a1f445 moved _contract_reasons to household_report_calculations; the test of a refused missing-variables option called it through household_report_submissions and failed. Run by node ID, passing. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_household_report_submissions.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 d16ce0732..030264a36 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, @@ -598,4 +598,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") From 4d525f7857f3c57bff1d0f48bbb367e7560a4cf1 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:22:28 +0400 Subject: [PATCH 078/107] Test that no re-run answers 409 run_in_progress any more (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's answers 3 and 8 and interim answer B leave no re-run refused while a run is under way: an unforced re-run of a keyed economy or household report joins that run, and a forced one, as every re-run of a budget window or of a report without keys is, is an extra run. So the OpenAPI document must name no run_in_progress code, and the two tests of that 409 go. Co-Authored-By: Claude Opus 5.5 --- .../tests/economy_rerun_fakes.py | 1 - .../tests/test_economy_rerun_routes.py | 19 ------------------- .../tests/test_economy_reruns.py | 19 ------------------- .../tests/test_openapi.py | 17 ++++++++--------- 4 files changed, 8 insertions(+), 48 deletions(-) diff --git a/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py b/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py index a3fab3037..875a8a90d 100644 --- a/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py +++ b/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py @@ -57,7 +57,6 @@ 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 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 4be1e21f5..d08ee60f8 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, @@ -55,7 +54,6 @@ RerunRecordDeletedError, RerunSide, ReusableRun, - RunInProgressError, RunVersions, SharedRowNotSettledError, SimulationStatus, @@ -356,23 +354,6 @@ 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)) diff --git a/projects/policyengine-simulation-entry/tests/test_openapi.py b/projects/policyengine-simulation-entry/tests/test_openapi.py index d3e89aec1..c9111e848 100644 --- a/projects/policyengine-simulation-entry/tests/test_openapi.py +++ b/projects/policyengine-simulation-entry/tests/test_openapi.py @@ -464,18 +464,17 @@ def test_rerun_routes_declare_every_answer(): assert "run_id" in responses["503"]["description"] # Both answer the run they ended on, created or joined. assert "joined" in responses["201"]["description"] - # Only a report's re-run is refused while a run is under way; a - # simulation's joins its run (C1 · 24's answer 3). - report_conflict = _responses(spec, "post", "/reports/{report_id}/runs")["409"] - simulation_conflict = _responses(spec, "post", "/simulations/{simulation_id}/runs")[ - "409" - ] - assert "run_id" in report_conflict["description"] - assert "run_in_progress" not in simulation_conflict["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"] From 0d94eba023b676126102b7af6ec59f5c2d7e0a68 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:24:16 +0400 Subject: [PATCH 079/107] Answer no re-run with 409 run_in_progress MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit No re-run the service sends is refused while a run is under way any more (C1 · 24's answers 3 and 8, interim answer B), so the code leaves EconomyConflictCode, EconomyRerunConflictError loses its run_id, and rerun_refusals no longer turns the store's RunInProgressError into a 409. The re-run routes' 409 answers rerun_not_supported alone. API v1's re-run client (C1 · 28) was told the 409 goes. Co-Authored-By: Claude Opus 5.5 --- .../economy_api_models.py | 18 ++++-------- .../economy_rerun_routes.py | 29 +++++++------------ .../economy_reruns.py | 5 ++-- .../economy_submission_errors.py | 29 ++++--------------- 4 files changed, 23 insertions(+), 58 deletions(-) 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 14a619bcf..da72c1d24 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``) of a - household report, 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 @@ -91,12 +91,6 @@ ] # Why a stored record is not re-run now (409). EconomyConflictCode = Literal[ - # A budget-window report has a window run or year run pending or - # running and the re-run isn't forced, or a household report has a run - # pending or running, forced or not; ``run_id`` names the budget-window - # run, or else the report run. An economy report's or a simulation's - # re-run joins its run instead. - "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", @@ -318,9 +312,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 household report's run that is - pending or running. + 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_rerun_routes.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_rerun_routes.py index c9de826d0..9e0c277e3 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 @@ -23,13 +23,12 @@ and its status. Every earlier run is kept. A re-run answers 404 for a record that does not -exist, and 409 (``run_in_progress``, naming the run in ``run_id``) while a -household report has a run pending or running (a household re-run ignores -``force``), or for a record this service does not re-run -(``rerun_not_supported``); then nothing is written. Without ``force``, a -keyed economy 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 +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 @@ -121,15 +120,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. -_CONFLICTS: dict[RecordName, str] = { - "report": ( - "a household report has a run pending or running, forced or not " - "(run_in_progress; run_id names that report run), or the service " - "does not re-run it (rerun_not_supported)" - ), - "simulation": "the service does not re-run it (rerun_not_supported)", -} +# 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. @@ -192,8 +184,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: " - f"{_CONFLICTS[record]}" + f"The {record} is not re-run, and nothing was written: {_CONFLICT}" ), **ERROR_ANSWER, }, @@ -238,7 +229,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) 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 73b254ca2..d8bfcfa76 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 @@ -539,9 +539,8 @@ async def _create_rerun[Created]( ) -> 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 run - under way the store refuses the re-run for answers 409 - ``run_in_progress``. A record deleted after its reads is + 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. 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 From e60f5268a67dacc0124094cc4c0e8e3a26d8b62a Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:25:24 +0400 Subject: [PATCH 080/107] Describe household reports found by key, and re-runs that join or force The create and re-run routes, HouseholdReportCreated and the entry README say a household report and its simulations are found or created by key, its run joined or created, a policy compared with itself named on one run, and a call started only for a run the request created; that Modal's refusal fails only that report run; and that no re-run is refused while a run is under way. Co-Authored-By: Claude Opus 5.5 --- .../policyengine-simulation-entry/README.md | 72 ++++++++++--------- .../economy_rerun_routes.py | 35 +++++---- .../economy_routes.py | 16 +++-- .../household_report_api_models.py | 23 +++--- 4 files changed, 78 insertions(+), 68 deletions(-) diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index e5ab517bd..8ba5b70a0 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -219,18 +219,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 @@ -282,11 +291,13 @@ 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, and each is -marked `forced`, as a household report has no keys yet. 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 +(trigger `manual`) 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, joins a stored @@ -298,9 +309,7 @@ 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 a household report has -a run pending or running; -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, @@ -312,25 +321,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`. An unforced re-run of a report created by key, and every -household report re-run, looks for the run to join, or for a run under way, -and inserts under a transaction-level advisory lock on the report's ID: a -second keyed economy report re-run waits, then joins the first's run; a -second household one waits, then is refused with 409 naming it. 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 household report's re-run ignores `force`, so it takes the lock -and is refused with 409 `run_in_progress` while any run of the report is -pending or running. A re-run's answer names +`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/economy_rerun_routes.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_rerun_routes.py index 9e0c277e3..f4cc13f6a 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 @@ -12,9 +12,10 @@ 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. + 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 @@ -288,21 +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, an economy 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 budget-window report or one " - "created before keys, the report's simulations are calculated " - "again, as an extra run marked forced that nothing joins; a " - "household report's re-run ignores force. A report stored asking " - "for cliff impacts is refused (422 cliffs_not_available). " - "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, an economy or household 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 " + "budget-window report or one 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 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 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, 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 c238bbf70..5b0c0cddc 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 @@ -8,11 +8,11 @@ ``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. + ``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 @@ -552,8 +552,10 @@ def _submission_routes( "year's runs. " "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, 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..eb1e2b86c 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 @@ -65,16 +65,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) From 651616dbe8049e4d93966b8548ffd7b47bfa05ea Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:28:41 +0400 Subject: [PATCH 081/107] Test the nullable per-user columns and the window run index (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 25's schema at its pushed 63cce8273 (PolicyEngine/policyengine-api#4303): answer 6 makes reports.label, report_runs.trigger and budget_window_runs.trigger nullable, so the service can stop writing them; answer 8 adds budget_window_runs.policyengine_version and uq_budget_window_runs_unfailed_unforced_versions, one window run per report and version set unless recalculated. B1 · 5's comparison with this test database, rebuilt from that commit, shows those five differences. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_tables.py | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/libs/policyengine-simulation-persistence/tests/test_tables.py b/libs/policyengine-simulation-persistence/tests/test_tables.py index a9ae9a415..144dfe086 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, @@ -269,3 +270,31 @@ 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_and_the_service_writes_none() -> None: + """Answer 6: a shared row holds 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" + ) From b7db8b56af29c99a374ecc8818b7b344322e66ee Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:29:17 +0400 Subject: [PATCH 082/107] Model the nullable per-user columns and the window run index MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Matching the Public API at C1 · 25's 63cce8273: reports.label, report_runs.trigger and budget_window_runs.trigger are nullable (answer 6), and budget_window_runs has policyengine_version and uq_budget_window_runs_unfailed_unforced_versions on (report_id, tax_benefit_model_version_id, policyengine_version) where status <> 'failed' AND NOT recalculate (answer 8). B1 · 5's comparison with the rebuilt test database passes. Co-Authored-By: Claude Opus 5.5 --- .../tables.py | 24 ++++++++++++++++--- .../tests/test_tables.py | 4 ++-- 2 files changed, 23 insertions(+), 5 deletions(-) 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 8a561cb50..7e5822411 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/tables.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/tables.py @@ -319,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), @@ -511,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", @@ -551,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( @@ -567,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"), diff --git a/libs/policyengine-simulation-persistence/tests/test_tables.py b/libs/policyengine-simulation-persistence/tests/test_tables.py index 144dfe086..40b7181ca 100644 --- a/libs/policyengine-simulation-persistence/tests/test_tables.py +++ b/libs/policyengine-simulation-persistence/tests/test_tables.py @@ -272,8 +272,8 @@ def test_a_run_is_unforced_unless_its_insert_marks_it() -> None: assert str(table.c.forced.server_default.arg) == "false", table.name -def test_the_per_user_columns_are_nullable_and_the_service_writes_none() -> None: - """Answer 6: a shared row holds no request's label, description or trigger.""" +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 From f67de3cc3e734c70a73b777b810f7f5f470d4db9 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:30:23 +0400 Subject: [PATCH 083/107] Test keyed creates and re-runs writing no per-user column (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's answer 6: a shared report holds no request's label, description or user, and a shared run no trigger (each user's report-run record holds it). Keyed economy and household creates, and economy and household re-runs, joined or forced, must leave all four null. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_economy_reruns.py | 9 ++++----- .../tests/test_household_report_reruns.py | 4 ++-- .../tests/test_keyed_economy_records.py | 10 +++++++++- .../tests/test_keyed_household_records.py | 15 +++++++++------ 4 files changed, 24 insertions(+), 14 deletions(-) diff --git a/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py b/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py index 882101dbf..73e3fbfc6 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py @@ -419,7 +419,8 @@ def test_a_report_rerun_joins_or_creates_runs_of_the_reports_own_simulations( "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, @@ -811,9 +812,7 @@ def test_a_rerun_and_its_runs_are_created_through_the_store( 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) @@ -1041,7 +1040,7 @@ def test_a_forced_report_rerun_is_an_extra_run_beside_any_run_on_its_versions( assert (report_run["forced"], report_run["trigger"], report_run["status"]) == ( True, - ReportRunTrigger.MANUAL, + None, ReportRunStatus.PENDING, ) assert len(simulation_runs) == 2 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 cc533adbc..03548be41 100644 --- a/libs/policyengine-simulation-persistence/tests/test_household_report_reruns.py +++ b/libs/policyengine-simulation-persistence/tests/test_household_report_reruns.py @@ -26,7 +26,6 @@ NewHouseholdReport, NewHouseholdReportRerun, ReportRunStatus, - ReportRunTrigger, RerunRecordDeletedError, RunVersions, SideDefinition, @@ -274,7 +273,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 ( diff --git a/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py b/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py index a203ac9c9..71c6475d6 100644 --- a/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py @@ -184,6 +184,9 @@ def test_a_keyed_report_is_created_with_its_simulations_and_first_run( "inputs", "type", "budget_window_size", + "label", + "description", + "user_id", ) } == { "key_version": KEY_VERSION, @@ -195,16 +198,21 @@ def test_a_keyed_report_is_created_with_its_simulations_and_first_run( "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, - "initial", + None, ) assert ( reform_run["status"], diff --git a/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py b/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py index 1840c05ca..f31db679e 100644 --- a/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py @@ -27,7 +27,6 @@ NewHouseholdReportRerun, ProposedSide, ReportRunStatus, - ReportRunTrigger, RunVersions, SimulationChoice, SimulationStatus, @@ -206,6 +205,9 @@ def test_a_keyed_household_report_is_created_with_its_simulations_and_first_run( "key_version", "definition_key", "dataset_independent_key", + "label", + "description", + "user_id", ) } == { "type": "household", @@ -220,12 +222,16 @@ def test_a_keyed_household_report_is_created_with_its_simulations_and_first_run( "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"] == ReportRunTrigger.INITIAL + assert report_run["trigger"] is None assert report_run["forced"] is False assert ( report_run["baseline_simulation_run_id"], @@ -478,10 +484,7 @@ def test_a_keyed_household_rerun_after_a_failed_run_names_its_simulations_runs( 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"]) == ( - ReportRunTrigger.MANUAL, - False, - ) + 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( From c2e439601cd57e8191ac5ad4fd79fcfcc2aea889 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:32:14 +0400 Subject: [PATCH 084/107] Write no per-user column on keyed creates and re-runs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's answer 6, on C1 · 25's nullable columns: the keyed economy and household creates write no reports.label, description or user_id and no report_runs.trigger, and re-runs, joined or forced, write no trigger. Each user's saved report and report-run record (API v1, C1 · 28) hold them. KeyedEconomyReport and KeyedHouseholdReport lose label and description, which the service no longer passes. Co-Authored-By: Claude Opus 5.5 --- .../economy_rerun_records.py | 6 ++++-- .../keyed_economy_records.py | 11 ++--------- .../keyed_household_records.py | 11 ++--------- .../tests/test_keyed_economy_records.py | 2 -- .../tests/test_keyed_household_records.py | 2 -- .../economy_submissions.py | 2 -- .../household_report_submissions.py | 2 -- .../tests/test_economy_submissions.py | 4 ---- .../tests/test_household_report_submissions.py | 2 -- 9 files changed, 8 insertions(+), 34 deletions(-) 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 55dea197a..387c7bca9 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 @@ -380,7 +380,10 @@ def insert_report_rerun( 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.""" + """Return a re-run's report run as inserted, without its sides' runs. + + It names no trigger: each user's report-run record holds it (answer 6). + """ return { "id": run_id, "report_id": report_id, @@ -389,7 +392,6 @@ def _rerun_report_run_row( "country_package_version": versions.country_package_version, "policyengine_version": versions.policyengine_version, "status": ReportRunStatus.PENDING, - "trigger": ReportRunTrigger.MANUAL, "modal_call_id": None, } 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 index a8123b0c5..704c6026f 100644 --- 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 @@ -49,7 +49,6 @@ ) from policyengine_simulation_persistence.tables import ( ReportRunStatus, - ReportRunTrigger, SimulationType, ) @@ -89,8 +88,8 @@ class KeyedEconomyReport: 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). - ``label`` and ``description`` are stored only by the request that - creates the report. + 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 @@ -98,8 +97,6 @@ class KeyedEconomyReport: run_id: UUID baseline: ProposedSide reform: ProposedSide - label: str - description: str | None tax_benefit_model_id: UUID population: EconomyPopulation versions: RunVersions @@ -345,11 +342,8 @@ def _report_row( population = request.population return { "id": request.report_id, - "label": request.label, - "description": request.description, "country": definition.country, "type": ECONOMY_REPORT_TYPE, - "user_id": None, "tax_benefit_model_id": request.tax_benefit_model_id, "policy_id": definition.reform.policy_id, "baseline_simulation_id": simulation_ids["baseline"], @@ -376,7 +370,6 @@ def _report_run_row(request: KeyedEconomyReport, report_id: UUID) -> dict[str, A "country_package_version": request.versions.country_package_version, "policyengine_version": request.versions.policyengine_version, "status": ReportRunStatus.PENDING, - "trigger": ReportRunTrigger.INITIAL, "modal_call_id": None, } 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 index dd95fa513..f8ec4bc4b 100644 --- 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 @@ -53,7 +53,6 @@ ) from policyengine_simulation_persistence.tables import ( ReportRunStatus, - ReportRunTrigger, SimulationType, ) @@ -74,8 +73,8 @@ class KeyedHouseholdReport: ``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``. ``label`` and ``description`` are - stored only by the request that creates the report. + ``tax_benefit_model_version_id``. No label, description, user or + trigger is stored on the shared rows (answer 6). """ definition: HouseholdReportDefinition @@ -83,8 +82,6 @@ class KeyedHouseholdReport: run_id: UUID baseline: ProposedSide reform: ProposedSide | None - label: str - description: str | None tax_benefit_model_id: UUID tax_benefit_model_version_id: UUID versions: RunVersions @@ -207,11 +204,8 @@ def _report_row( reform = definition.reform return { "id": request.report_id, - "label": request.label, - "description": request.description, "country": definition.country, "type": HOUSEHOLD_REPORT_TYPE, - "user_id": None, "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"], @@ -239,7 +233,6 @@ def _report_run_row(request: KeyedHouseholdReport, report_id: UUID) -> dict[str, "country_package_version": request.versions.country_package_version, "policyengine_version": request.versions.policyengine_version, "status": ReportRunStatus.PENDING, - "trigger": ReportRunTrigger.INITIAL, "modal_call_id": None, } diff --git a/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py b/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py index 71c6475d6..a4388a854 100644 --- a/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py @@ -83,8 +83,6 @@ def _keyed_report( run_id=uuid4(), baseline=ProposedSide(simulation_id=uuid4(), simulation_run_id=uuid4()), reform=ProposedSide(simulation_id=uuid4(), simulation_run_id=uuid4()), - label="Shared report", - description=None, tax_benefit_model_id=economy.catalog.model_id, population=economy.population(), versions=VERSIONS, diff --git a/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py b/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py index f31db679e..9dca6f3fc 100644 --- a/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py @@ -113,8 +113,6 @@ def _keyed_report( if reform is None else ProposedSide(simulation_id=uuid4(), simulation_run_id=uuid4()) ), - label="A larger child tax credit", - description=None, tax_benefit_model_id=stored.catalog.model_id, tax_benefit_model_version_id=stored.catalog.version_id, versions=VERSIONS, 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 978a60555..a04e91db4 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 @@ -306,8 +306,6 @@ async def submit_report( run_id=self._new_id(), baseline=self._proposed_side(), reform=self._proposed_side(), - label=request.label, - description=request.description, tax_benefit_model_id=catalog.model_id, population=catalog.population(request.year), versions=worker.versions, 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 6061c5fd3..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 @@ -460,8 +460,6 @@ def _keyed_report( run_id=run_id, baseline=proposed["baseline"], reform=proposed.get("reform"), - label=request.label, - description=request.description, tax_benefit_model_id=inputs.tax_benefit_model_id, tax_benefit_model_version_id=inputs.catalog_version_id, versions=RunVersions( diff --git a/projects/policyengine-simulation-entry/tests/test_economy_submissions.py b/projects/policyengine-simulation-entry/tests/test_economy_submissions.py index 5a8306d09..e7c5804ef 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_submissions.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_submissions.py @@ -134,10 +134,6 @@ def test_a_report_is_created_by_key_and_its_coordinator_started() -> None: 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.label, report.description) == ( - "A larger child tax credit", - "Raises the credit to $3,000", - ) assert report.tax_benefit_model_id == CATALOG.model_id assert report.population == CATALOG.population(2026) # Answer 4: the report stores no option but the SPM selection. 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 030264a36..5d372d9a9 100644 --- a/projects/policyengine-simulation-entry/tests/test_household_report_submissions.py +++ b/projects/policyengine-simulation-entry/tests/test_household_report_submissions.py @@ -138,8 +138,6 @@ def test_a_household_report_is_created_and_its_household_function_started(): year=2026, ) assert (report.report_id, report.run_id) == (REPORT_ID, RUN_ID) - assert report.label == "A larger child tax credit for one family" - assert report.description == "Raises the credit to $3,000" assert (report.tax_benefit_model_id, report.tax_benefit_model_version_id) == ( MODEL_ID, CATALOG_VERSION_ID, From fa1e4bdfbc1b300e0044c71bca90e413ab96e395 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:32:38 +0400 Subject: [PATCH 085/107] Test a report request's label and description as optional and unstored (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's answer 6: the Public API keeps a report's name and description on each user's saved report, and sim stores neither, so its report requests may leave out the label and say it is not stored. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_openapi.py | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/projects/policyengine-simulation-entry/tests/test_openapi.py b/projects/policyengine-simulation-entry/tests/test_openapi.py index c9111e848..14cc01a94 100644 --- a/projects/policyengine-simulation-entry/tests/test_openapi.py +++ b/projects/policyengine-simulation-entry/tests/test_openapi.py @@ -533,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"][ @@ -585,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", } From 8fef28cc0af98855d115626bf9118f77180bbc5b Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:33:53 +0400 Subject: [PATCH 086/107] Accept an economy or household report's label and description without storing them MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's answer 6: both are optional on EconomyReportRequest and HouseholdReportRequest and say they are not stored (each user's saved report in the Public API holds them); given ones are still checked, so the Public API's callers' requests stay valid. A budget window's follow with its keys. Co-Authored-By: Claude Opus 5.5 --- .../economy_api_models.py | 15 +++++++++++++-- .../household_report_api_models.py | 10 +++++++--- .../tests/test_openapi.py | 7 ++----- 3 files changed, 22 insertions(+), 10 deletions(-) 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 da72c1d24..ca73f7877 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 @@ -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 @@ -161,8 +170,10 @@ class EconomyReportRequest(_Request): 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 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 eb1e2b86c..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 diff --git a/projects/policyengine-simulation-entry/tests/test_openapi.py b/projects/policyengine-simulation-entry/tests/test_openapi.py index 14cc01a94..0d9fdfefd 100644 --- a/projects/policyengine-simulation-entry/tests/test_openapi.py +++ b/projects/policyengine-simulation-entry/tests/test_openapi.py @@ -537,11 +537,8 @@ 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", - ): + # A budget window's come with its keys (answer 8). + for name in ("EconomyReportRequest", "HouseholdReportRequest"): request = schemas[name] assert {"label", "description"} <= set(request["properties"]), name assert "label" not in request.get("required", []), name From 01b4b09b3e109a16e08d3ea70509401fe55dffd1 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:36:44 +0400 Subject: [PATCH 087/107] Test finding or creating budget windows by key (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's answer 8, on C1 · 25's window run index: a window request finds each year's simulations by that year's key and the report by its key (the window size in it), then joins the report's window run on the current versions that hasn't failed and isn't a recalculation, with its year runs; otherwise it creates the window run, recording its .py version, and each year's report run on its sides' runs, found or inserted. Tested: the first request's rows and keys, no per-user columns (answer 6); an identical request joining and inserting nothing; a window year naming a single-year report's simulation run (review round 4's bug 3); a failed window run getting a new one on the years' runs; one run a year for a policy compared with itself; the store; and a definition whose length isn't its years'. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_keyed_window_records.py | 375 ++++++++++++++++++ 1 file changed, 375 insertions(+) create mode 100644 libs/policyengine-simulation-persistence/tests/test_keyed_window_records.py 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..4f6d79ec1 --- /dev/null +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_window_records.py @@ -0,0 +1,375 @@ +"""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 + +from contextlib import contextmanager +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, + insert_economy_catalog, +) +from policyengine_simulation_persistence import ( + KEY_VERSION, + EconomyPopulation, + EconomyReportDefinition, + EconomyRunStore, + 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 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, *, year: int = FIRST_YEAR, size: int | None = 3 +) -> EconomyReportDefinition: + return EconomyReportDefinition( + country="us", + 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), + 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, 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 + ), + ) From 17ac16f5a60933cbf2da0ed2dcd612946ce8a16c Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:39:20 +0400 Subject: [PATCH 088/107] Find or create budget windows by key MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's answer 8, on C1 · 25's window run index. find_or_create_budget_window finds each year's simulations by that year's key, in key order across every year, and the report by its key (the window's first year and size in it); it joins the report's window run on the current catalog and .py versions that hasn't failed and isn't a recalculation, with its year runs, or else inserts the window run first (find_or_insert_window_run: a request inserting one another has inserted waits for it and joins it), then every year's side runs, found or inserted in simulation ID order, and each year's report run naming them. A window year so names a single-year report's simulation run, and the reverse (review round 4's bug 3). No per-user column is written, and the window run records its .py version. EconomyRunStore.find_or_create_budget_window runs it in a transaction of its own. The economy create's simulation and report rows are built by economy_simulation_row and economy_report_row, which the window shares, and FoundSide says whether a side's run is reused, as answers do. Co-Authored-By: Claude Opus 5.5 --- .../__init__.py | 14 + .../economy_run_store.py | 19 + .../keyed_economy_records.py | 47 +- .../keyed_window_records.py | 406 ++++++++++++++++++ .../shared_rows.py | 70 ++- 5 files changed, 543 insertions(+), 13 deletions(-) create mode 100644 libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/keyed_window_records.py 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 37b96f65e..2ae9f656c 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py @@ -142,6 +142,13 @@ 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, @@ -156,6 +163,7 @@ FoundReportRun, FoundRow, FoundSimulationRun, + FoundWindowRun, SharedRowNotSettledError, find_joinable_report_run, find_or_insert_report, @@ -205,6 +213,7 @@ "EconomySimulationDefinition", "EconomySimulationInputs", "EconomySimulationState", + "FoundBudgetWindow", "FoundEconomyReport", "FoundEconomySimulation", "FoundHouseholdReport", @@ -212,6 +221,8 @@ "FoundRow", "FoundSide", "FoundSimulationRun", + "FoundWindowRun", + "FoundWindowYear", "HouseholdCalculationInputs", "HouseholdJobRecord", "HouseholdJobReferenceError", @@ -223,9 +234,11 @@ "HouseholdReportStore", "HouseholdRerunSide", "HouseholdSimulationDefinition", + "KeyedBudgetWindow", "KeyedEconomyReport", "KeyedEconomySimulation", "KeyedHouseholdReport", + "KeyedWindowYear", "MissingPolicyParametersError", "NewBudgetWindowReport", "NewEconomyReport", @@ -283,6 +296,7 @@ "fail_unstarted_report_run", "fail_unstarted_simulation_run", "find_joinable_report_run", + "find_or_create_budget_window", "find_or_create_economy_report", "find_or_create_economy_simulation", "find_or_create_household_report", 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 f0c4e916c..9e5531ec3 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 @@ -61,6 +61,9 @@ find_or_create_economy_report, find_or_create_economy_simulation, ) +from policyengine_simulation_persistence.keyed_window_records import ( + find_or_create_budget_window, +) if TYPE_CHECKING: from collections.abc import Callable, Sequence @@ -95,6 +98,10 @@ KeyedEconomyReport, KeyedEconomySimulation, ) + from policyengine_simulation_persistence.keyed_window_records import ( + FoundBudgetWindow, + KeyedBudgetWindow, + ) from policyengine_simulation_persistence.shared_rows import ( FoundReportRun, FoundSimulationRun, @@ -361,6 +368,18 @@ def find_or_create_report(self, report: KeyedEconomyReport) -> FoundEconomyRepor lambda connection: find_or_create_economy_report(connection, report) ) + def find_or_create_budget_window( + self, window: KeyedBudgetWindow + ) -> FoundBudgetWindow: + """Find the window by key, with its window run, or create them. + + See ``find_or_create_budget_window``; raise as + ``find_or_create_report`` does. + """ + return self._create( + lambda connection: find_or_create_budget_window(connection, window) + ) + def find_or_create_simulation( self, simulation: KeyedEconomySimulation ) -> FoundEconomySimulation: 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 index 704c6026f..0eb7ef8cd 100644 --- 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 @@ -111,6 +111,11 @@ class FoundSide: 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: @@ -165,7 +170,17 @@ def find_or_create_economy_report( """ with references_checked(): simulation_ids = _find_or_insert_simulations(connection, request) - report = find_or_insert_report(connection, _report_row(request, simulation_ids)) + 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, @@ -203,7 +218,7 @@ def find_or_create_economy_simulation( with references_checked(): simulation = find_or_insert_simulation( connection, - _simulation_row( + economy_simulation_row( request.definition, request.simulation_id, request.population ), ) @@ -237,7 +252,7 @@ def _find_or_insert_simulations( sides = by_key[key] found = find_or_insert_simulation( connection, - _simulation_row( + economy_simulation_row( request.definition.simulation(sides[0]), proposed[sides[0]].simulation_id, request.population, @@ -313,7 +328,7 @@ def find_or_insert_side_runs( return {side: found[row["simulation_id"]] for side, row in side_rows.items()} -def _simulation_row( +def economy_simulation_row( definition: EconomySimulationDefinition, simulation_id: UUID, population: EconomyPopulation, @@ -334,17 +349,25 @@ def _simulation_row( } -def _report_row( - request: KeyedEconomyReport, simulation_ids: dict[Side, UUID] +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 as inserted, naming its sides' simulations.""" - definition = request.definition - population = request.population + """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": request.report_id, + "id": report_id, "country": definition.country, "type": ECONOMY_REPORT_TYPE, - "tax_benefit_model_id": request.tax_benefit_model_id, + "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"], @@ -353,7 +376,7 @@ def _report_row( "region_id": population.region_id, "year": definition.year, "budget_window_size": definition.budget_window_size, - "inputs": request.inputs, + "inputs": inputs, "key_version": KEY_VERSION, "definition_key": definition.definition_key, "dataset_independent_key": definition.dataset_independent_key, 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..cfcbc87ef --- /dev/null +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/keyed_window_records.py @@ -0,0 +1,406 @@ +"""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 ( + 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 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] + + +@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_years(connection, request, report.id, simulation_ids) + 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_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_years( + connection: Connection, + request: KeyedBudgetWindow, + report_id: UUID, + simulation_ids: dict[YearSide, UUID], +) -> tuple[FoundWindowYear, ...]: + """Find or insert every year's side runs, then insert each year's report run.""" + rows: dict[UUID, dict[str, Any]] = {} + for window_year in request.years: + # The reform first, so one simulation on both sides keeps the + # baseline's proposed ID. + for side, side_ids in _sides(window_year, reform_first=True): + simulation_id = simulation_ids[window_year.year, side] + rows[simulation_id] = simulation_run_row( + run_id=side_ids.simulation_run_id, + simulation_id=simulation_id, + population=request.population_in(window_year.year), + versions=request.versions, + ) + runs = find_or_insert_simulation_runs(connection, rows) + years = tuple( + FoundWindowYear( + year=window_year.year, + report_run_id=window_year.report_run_id, + baseline=_found_side(runs, simulation_ids[window_year.year, "baseline"]), + reform=_found_side(runs, simulation_ids[window_year.year, "reform"]), + ) + for window_year in request.years + ) + connection.execute( + insert(report_runs), + [ + window_year_run_row( + run_id=year.report_run_id, + report_id=report_id, + window_run_id=request.window_run_id, + year=year.year, + side_runs={ + "baseline": year.baseline.simulation_run_id, + "reform": year.reform.simulation_run_id, + }, + versions=request.versions, + forced=False, + ) + for year in years + ], + ) + return years + + +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 _found_side(runs: dict[UUID, Any], simulation_id: UUID) -> FoundSide: + run = runs[simulation_id] + return FoundSide( + simulation_id=simulation_id, simulation_run_id=run.id, run_inserted=run.inserted + ) + + +def _stored_years( + connection: Connection, + window_run_id: UUID, + simulation_ids: dict[YearSide, UUID], +) -> tuple[FoundWindowYear, ...]: + """Return a joined window run's years, as its year runs name them. + + 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/shared_rows.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/shared_rows.py index 1d13559ff..7cf2ff7da 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/shared_rows.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/shared_rows.py @@ -9,7 +9,9 @@ - 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. + 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 @@ -36,6 +38,7 @@ from policyengine_simulation_persistence.tables import ( ReportRunStatus, SimulationStatus, + budget_window_runs, report_runs, reports, simulation_runs, @@ -89,6 +92,15 @@ class FoundReportRun: 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.""" @@ -195,6 +207,62 @@ def find_or_insert_simulation_runs( } +_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: From e4b5f51e6e9edfe4dbfda2d0bb64e0f2212437c3 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:41:11 +0400 Subject: [PATCH 089/107] Test window re-runs that join a keyed window's run or force an extra one (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's answers 3, 6 and 8: an unforced window re-run joins the report's window run on its versions, with its year runs, or else creates one whose years' sides join their simulations' runs; a forced one (recalculate) is an extra window run on new runs of every year, all forced. Both record the window run's .py version and no trigger, return the window run and years they ended on, and name no reused side. No window re-run is refused while a run is under way any more; a single-year re-run of a window report still is, which the service never sends. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_economy_window_reruns.py | 238 +++++++++++++----- 1 file changed, 180 insertions(+), 58 deletions(-) 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 6f5c27e06..bd67d6134 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_window_reruns.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_window_reruns.py @@ -37,13 +37,17 @@ BudgetWindowYear, EconomyPopulation, EconomyRecordReferenceError, + EconomyReportDefinition, EconomyRequest, EconomyRunStore, + FoundBudgetWindow, + KeyedBudgetWindow, + KeyedWindowYear, NewBudgetWindowReport, NewReportRerun, NewWindowRerun, + ProposedSide, ReportRunStatus, - ReportRunTrigger, ReportSimulation, RerunRecordDeletedError, RerunSide, @@ -53,6 +57,7 @@ SimulationStatus, WindowRerunYear, WindowYearDefinition, + find_or_create_budget_window, insert_budget_window_report, insert_report_rerun, insert_window_rerun, @@ -276,33 +281,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 +307,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 +315,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 +338,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,8 +361,131 @@ def test_a_window_rerun_creates_a_window_run_and_each_years_runs( assert earlier_window["status"] == ReportRunStatus.SUCCEEDED +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(), + reused=False, + ), + reform=RerunSide( + simulation_id=year.reform.simulation_id, + simulation_run_id=uuid4(), + reused=False, + ), + ) + 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) + act_as_the_service(connection) + found = _keyed_window(connection, economy) + + joined = insert_window_rerun(connection, _rerun_of_keyed(found, economy)) + + 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_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) + 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) + rerun = _rerun_of_keyed(found, economy) + + created = insert_window_rerun(connection, rerun) + window_run = _row(connection, "budget_window_runs", rerun.window_run_id) + + 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 + + @pytest.mark.parametrize("status", [ReportRunStatus.PENDING, ReportRunStatus.RUNNING]) -def test_a_window_rerun_is_refused_while_a_window_run_is_under_way( +def test_a_single_year_rerun_of_a_window_is_refused_while_a_window_run_is_under_way( public_api_database_url, status: ReportRunStatus ) -> None: with rolled_back_transaction(public_api_database_url) as connection: @@ -372,9 +494,7 @@ def test_a_window_rerun_is_refused_while_a_window_run_is_under_way( stored = _stored_window(connection, economy, window_status=status) act_as_the_service(connection) - 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. + # The service re-runs a window with insert_window_rerun. with pytest.raises(RunInProgressError) as report_refused: insert_report_rerun( connection, @@ -396,7 +516,6 @@ def test_a_window_rerun_is_refused_while_a_window_run_is_under_way( ), ) - assert window_refused.value.run_id == stored.window_run_id assert report_refused.value.run_id == stored.window_run_id @@ -477,14 +596,42 @@ 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_names_no_reused_side() -> None: + """Each year's sides join or create their runs, as a report re-run's do.""" + reused = RerunSide(simulation_id=uuid4(), simulation_run_id=uuid4(), reused=True) + created = RerunSide(simulation_id=uuid4(), simulation_run_id=uuid4(), reused=False) + + with pytest.raises(ValueError, match="reusing none"): + NewWindowRerun( + report_id=uuid4(), + window_run_id=uuid4(), + population=EconomyPopulation( + tax_benefit_model_version_id=uuid4(), + region_id=uuid4(), + dataset_id=uuid4(), + year=WINDOW_YEARS[0], + ), + versions=VERSIONS, + recalculate=False, + years=( + WindowRerunYear( + year=WINDOW_YEARS[0], + report_run_id=uuid4(), + baseline=reused, + reform=created, + ), + ), + ) def test_a_window_rerun_refuses_years_that_are_not_its_window() -> None: @@ -583,31 +730,6 @@ 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, -) -> None: - 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}, - ) - act_as_the_service(connection) - - with pytest.raises(RunInProgressError) as refused: - insert_window_rerun(connection, _window_rerun_of(stored, later)) - - assert refused.value.run_id == still_running - - @pytest.mark.parametrize( "status", [ReportRunStatus.PENDING, ReportRunStatus.RUNNING, ReportRunStatus.SUCCEEDED], From ca67663078947058fe8a2f027ac2d5effdee2c13 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:43:52 +0400 Subject: [PATCH 090/107] Join a keyed window's run on re-run, or force an extra one MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's answers 3, 6 and 8. insert_window_rerun, unforced, takes the report's re-run lock and joins its 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 it inserts the window run (a concurrent one is joined) and each year's report run on its sides' runs, found or inserted, as a keyed window's create does. A forced re-run inserts an extra window run on new runs of every year, all forced. Both record the window run's .py version and no trigger, and return the window run and years they ended on, as EconomyRunStore.create_window_rerun does. No window re-run is refused while a run is under way, and none names a reused side. insert_window_years is the year insert the window's create and re-runs share; stored_window_years reads a joined window run's years. Co-Authored-By: Claude Opus 5.5 --- .../economy_rerun_records.py | 172 +++++++++++------- .../economy_run_store.py | 6 +- .../keyed_window_records.py | 169 +++++++++++++---- .../tests/test_economy_window_reruns.py | 6 +- .../economy_reruns.py | 5 +- 5 files changed, 250 insertions(+), 108 deletions(-) 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 387c7bca9..f3a1ee335 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 @@ -53,7 +53,6 @@ from policyengine_simulation_persistence.budget_window_records import ( check_window_years, - year_run_row, ) from policyengine_simulation_persistence.economy_run_records import ( EconomyRecordReferenceError, @@ -68,6 +67,13 @@ 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, @@ -79,12 +85,14 @@ ) 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, budget_window_runs, report_runs, @@ -176,7 +184,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. No side names a reused run. """ report_id: UUID @@ -187,8 +199,13 @@ 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 from the first, or a reused side.""" check_window_years(self.population.year, [year.year for year in self.years]) + if any( + side.reused for year in self.years for side in (year.baseline, year.reform) + ): + msg = "a window re-run's sides join or create their runs, reusing none" + raise ValueError(msg) def population_in(self, year: int) -> EconomyPopulation: """Return what the window's simulations of ``year`` calculate on.""" @@ -424,62 +441,104 @@ def _insert_forced_report_run( ) -def insert_window_rerun(connection: Connection, rerun: NewWindowRerun) -> None: - """Create the budget window's new run, each year's report run and new 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. A re-run that recalculates is a forced - one: no lock or refusal, and its year runs and simulation runs are - marked forced. +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. """ - if not rerun.recalculate: - lock_reruns_of(connection, rerun.report_id) - _refuse_while_report_runs(connection, rerun.report_id) - population = rerun.population + 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, - forced=rerun.recalculate, - ) - 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, - forced=rerun.recalculate, + 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( @@ -557,19 +616,6 @@ def _refuse_while_window_runs(connection: Connection, report_id: UUID) -> None: raise RunInProgressError(under_way) -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. - """ - _refuse_while_window_runs(connection, report_id) - under_way = _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: 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 9e5531ec3..23b7e43ba 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 @@ -287,12 +287,12 @@ def read_window_rerun_inputs( ), ) - 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. """ - 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) -> FoundReportRun: """Join or create the report's run; see ``insert_report_rerun``. 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 index cfcbc87ef..9fbf98711 100644 --- 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 @@ -39,6 +39,7 @@ check_window_years, ) from policyengine_simulation_persistence.economy_run_records import ( + insert_simulation_run, references_checked, simulation_run_row, ) @@ -63,6 +64,7 @@ ) if TYPE_CHECKING: + from collections.abc import Sequence from uuid import UUID from sqlalchemy import Connection @@ -77,6 +79,20 @@ # 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) @@ -197,7 +213,15 @@ def find_or_create_budget_window( ), ) if window_run.inserted: - years = _insert_years(connection, request, report.id, simulation_ids) + 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, @@ -209,7 +233,7 @@ def find_or_create_budget_window( report_id=report.id, report_inserted=report.inserted, window_run=joined, - years=_stored_years(connection, joined.id, simulation_ids), + years=stored_window_years(connection, joined.id, simulation_ids), ) @@ -295,54 +319,112 @@ def _find_or_insert_simulations( return simulation_ids -def _insert_years( +def insert_window_years( # noqa: PLR0913 # the years, then the window they belong to connection: Connection, - request: KeyedBudgetWindow, + years: Sequence[WindowYearToInsert], + *, report_id: UUID, - simulation_ids: dict[YearSide, UUID], + window_run_id: UUID, + population: EconomyPopulation, + versions: RunVersions, + forced: bool, ) -> tuple[FoundWindowYear, ...]: - """Find or insert every year's side runs, then insert each year's report run.""" - rows: dict[UUID, dict[str, Any]] = {} - for window_year in request.years: - # The reform first, so one simulation on both sides keeps the - # baseline's proposed ID. - for side, side_ids in _sides(window_year, reform_first=True): - simulation_id = simulation_ids[window_year.year, side] - rows[simulation_id] = simulation_run_row( - run_id=side_ids.simulation_run_id, - simulation_id=simulation_id, - population=request.population_in(window_year.year), - versions=request.versions, + """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 + }, ) - runs = find_or_insert_simulation_runs(connection, rows) - years = tuple( - FoundWindowYear( - year=window_year.year, - report_run_id=window_year.report_run_id, - baseline=_found_side(runs, simulation_ids[window_year.year, "baseline"]), - reform=_found_side(runs, simulation_ids[window_year.year, "reform"]), + 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 ) - for window_year in request.years - ) connection.execute( insert(report_runs), [ window_year_run_row( run_id=year.report_run_id, report_id=report_id, - window_run_id=request.window_run_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=request.versions, - forced=False, + versions=versions, + forced=forced, ) - for year in years + for year in found_years ], ) - return 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( @@ -356,19 +438,32 @@ def _sides( return sides[::-1] if reform_first else sides -def _found_side(runs: dict[UUID, Any], simulation_id: UUID) -> FoundSide: - run = runs[simulation_id] - return FoundSide( - simulation_id=simulation_id, simulation_run_id=run.id, run_inserted=run.inserted +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_years( +def stored_window_years( connection: Connection, window_run_id: UUID, simulation_ids: dict[YearSide, UUID], ) -> tuple[FoundWindowYear, ...]: - """Return a joined window run's years, as its year runs name them. + """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. 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 bd67d6134..e0a916609 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_window_reruns.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_window_reruns.py @@ -252,7 +252,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) @@ -264,8 +264,8 @@ 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(), + reused=False, ), ) act_as_the_service(connection) 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 d8bfcfa76..76dedbe7b 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 @@ -103,6 +103,7 @@ from policyengine_simulation_persistence import ( BudgetWindowInputs, EconomyReportInputs, + FoundBudgetWindow, FoundReportRun, FoundSimulationRun, ReportDefinition, @@ -179,8 +180,8 @@ def read_window_rerun_inputs( """Read a window re-run's catalog rows, both sides' values and years' runs.""" ... - 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) -> FoundReportRun: From 0f69b1797ecbc443bbffa7359c3a8d7851250e13 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:46:37 +0400 Subject: [PATCH 091/107] Test budget windows found by key and keyed window re-runs in the service (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's answer 8, in the entry: a window request reads no run to reuse, finds or creates its window by key (its definition holding its first year, size and SPM selection, its inputs the selection alone), starts its first years only for a window run it created, on the year runs the store names (a year may name another report's run), and answers a joined window run as it is, starting no year. A keyed window's unforced re-run joins its window run the same way; force recalculates. The fakes find or create windows and can join. Also the pinned formatter's one-line change to the household builder's test. Co-Authored-By: Claude Opus 5.5 --- .../tests/economy_rerun_fakes.py | 36 ++++- .../tests/test_budget_window_submissions.py | 152 +++++++++++++++--- .../tests/test_economy_reruns.py | 86 ++++++++++ .../test_household_report_submissions.py | 4 +- 4 files changed, 250 insertions(+), 28 deletions(-) diff --git a/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py b/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py index 875a8a90d..966393973 100644 --- a/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py +++ b/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py @@ -26,8 +26,12 @@ BudgetWindowInputs, EconomyReportInputs, EconomySimulationInputs, + FoundBudgetWindow, FoundReportRun, + FoundSide, FoundSimulationRun, + FoundWindowRun, + FoundWindowYear, ReportDefinition, ReportRunStatus, SideDefinition, @@ -142,6 +146,9 @@ class FakeRerunStore(FakeWindowStore): 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) @@ -224,10 +231,37 @@ def read_window_rerun_inputs( }, ) - 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) -> FoundReportRun: if self.rerun_failure is not None: 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..ef2cca099 100644 --- a/projects/policyengine-simulation-entry/tests/test_budget_window_submissions.py +++ b/projects/policyengine-simulation-entry/tests/test_budget_window_submissions.py @@ -47,9 +47,13 @@ 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 ( @@ -71,13 +75,22 @@ @dataclass class FakeWindowStore(FakeStore): - """Also reads and creates budget-window reports.""" + """Also reads budget-window reports, and finds or creates them by key. + + ``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. + """ reusable_by_year: dict[int, tuple[ReusableRun | None, ReusableRun | None]] = field( default_factory=dict ) + 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))) @@ -92,10 +105,37 @@ def read_budget_window_inputs(self, request, *, baseline, reform, reuse, 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 +160,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( @@ -193,15 +237,22 @@ def test_a_window_is_created_with_a_run_per_year_and_its_first_five_started() -> 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}/", - ) + # Answer 8: found or created by key; no run is searched for to reuse. + assert reuse is None (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 +269,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 +311,69 @@ 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"): REUSED_IN_2027.simulation_run_id} + ) + 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 == ( + REUSED_IN_2027.simulation_run_id + ) + year_2027 = ReportExecutionInput.model_validate(caller.report_runs[1][1]) + assert year_2027.baseline.simulation_execution_id == ( + REUSED_IN_2027.simulation_run_id + ) + + +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 +384,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 +393,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 +407,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 +490,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_economy_reruns.py b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py index d08ee60f8..8e10cb48f 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py @@ -44,8 +44,12 @@ CatalogDataset, EconomyRecordOutcomeUnknownError, EconomyRecordReferenceError, + FoundBudgetWindow, FoundReportRun, + FoundSide, FoundSimulationRun, + FoundWindowRun, + FoundWindowYear, MissingPolicyParametersError, NewReportRerun, NewSimulationRerun, @@ -741,6 +745,88 @@ def test_a_forced_window_rerun_recalculates_every_year() -> None: 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_household_report_submissions.py b/projects/policyengine-simulation-entry/tests/test_household_report_submissions.py index 5d372d9a9..04d4ebc15 100644 --- a/projects/policyengine-simulation-entry/tests/test_household_report_submissions.py +++ b/projects/policyengine-simulation-entry/tests/test_household_report_submissions.py @@ -446,9 +446,7 @@ 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_only_the_report_run( - 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() From 405ed0b9dcc1bfd77f813f876904b2fe44d4076e Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:49:04 +0400 Subject: [PATCH 092/107] Find or create budget windows by key in the service, and join keyed window re-runs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's answer 8, in the entry. A window request reads no run to reuse, checks its first year's calculation on the run IDs it proposes, and finds or creates its window by key (KeyedBudgetWindow: the definition holds its first year, size and SPM selection; the report stores the selection alone); only for a window run it created does it start the first years, on the year runs the store names, which may be another report's. A joined window run is answered as it is. A keyed window's unforced re-run joins its window run the same way, and starts its first years only for a window run it created; force, or a window without keys, recalculates. The economy service's reusable-side helper, which only the window create used, goes. Co-Authored-By: Claude Opus 5.5 --- .../budget_window_submissions.py | 174 ++++++++++-------- .../economy_reruns.py | 57 +++--- .../economy_submissions.py | 18 -- 3 files changed, 130 insertions(+), 119 deletions(-) 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..77b639ce6 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, @@ -66,8 +73,8 @@ from policyengine_simulation_persistence import ( BudgetWindowInputs, EconomyRequest, - ReusableRun, - SimulationInputs, + FoundBudgetWindow, + RunReuse, WindowYearRuns, ) from policyengine_stage12_persistence import ( @@ -106,8 +113,10 @@ def read_budget_window_inputs( """Read the window's catalog rows, both sides' values and each year's runs.""" ... - 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 +173,95 @@ 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, + reuse=None, 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 +418,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 { @@ -421,7 +436,10 @@ 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.""" + """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/economy_reruns.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_reruns.py index 76dedbe7b..97dd4d18c 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 @@ -473,41 +473,52 @@ async def _rerun_window( recalculate=window.recalculate, 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) -> WindowRerunYear: 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 a04e91db4..cfd1d563d 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 @@ -58,7 +58,6 @@ KeyedEconomySimulation, ProposedSide, ReportRunStatus, - ReportSimulation, SharedRowNotSettledError, SimulationChoice, SimulationStatus, @@ -110,7 +109,6 @@ FoundEconomyReport, FoundEconomySimulation, RunReuse, - SimulationInputs, ) from policyengine_simulation_entry.economy_api_models import ( @@ -434,22 +432,6 @@ def _proposed_side(self) -> ProposedSide: simulation_id=self._new_id(), simulation_run_id=self._new_id() ) - 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 _origin(self, request_id: str) -> CallOrigin: return CallOrigin( environment=self._settings.environment, From bddcb2dafc982944fa59a2b2f42f014f7e3f3847 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:49:14 +0400 Subject: [PATCH 093/107] Test a budget window's label and description as optional and unstored (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's answer 6: the window's report stores neither, as an economy or household report's doesn't. Co-Authored-By: Claude Opus 5.5 --- .../policyengine-simulation-entry/tests/test_openapi.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/projects/policyengine-simulation-entry/tests/test_openapi.py b/projects/policyengine-simulation-entry/tests/test_openapi.py index 0d9fdfefd..14cc01a94 100644 --- a/projects/policyengine-simulation-entry/tests/test_openapi.py +++ b/projects/policyengine-simulation-entry/tests/test_openapi.py @@ -537,8 +537,11 @@ 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"] - # A budget window's come with its keys (answer 8). - for name in ("EconomyReportRequest", "HouseholdReportRequest"): + for name in ( + "EconomyReportRequest", + "BudgetWindowReportRequest", + "HouseholdReportRequest", + ): request = schemas[name] assert {"label", "description"} <= set(request["properties"]), name assert "label" not in request.get("required", []), name From c7b6a667e934f9476dd3fe2d3166dfe0aefc5f3e Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:49:32 +0400 Subject: [PATCH 094/107] Accept a budget window's label and description without storing them MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · 24's answer 6, as for economy and household reports. Co-Authored-By: Claude Opus 5.5 --- .../budget_window_api_models.py | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) 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..1d92ecc2e 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 From 176ed55f2a43c09b59f05ab1e290cfc354baaf14 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:51:21 +0400 Subject: [PATCH 095/107] Describe budget windows found by key, and window re-runs that join or force The routes, ReportRerunRequest, the re-run modules and both READMEs say a budget window, its years' simulations and its window run are found or created by key, a window year sharing a single-year report's runs; that only a window run the request created has its first years started; that a keyed window's re-run joins its window run, force or a window created before keys recalculating; and that no keyed create writes a per-user column. Co-Authored-By: Claude Opus 5.5 --- .../README.md | 32 ++++++++++--- .../economy_rerun_records.py | 8 ++-- .../policyengine-simulation-entry/README.md | 47 +++++++++++-------- .../economy_api_models.py | 16 +++---- .../economy_rerun_routes.py | 34 +++++++------- .../economy_reruns.py | 38 ++++++++------- .../economy_routes.py | 15 ++++-- 7 files changed, 112 insertions(+), 78 deletions(-) diff --git a/libs/policyengine-simulation-persistence/README.md b/libs/policyengine-simulation-persistence/README.md index 712857991..5340ae679 100644 --- a/libs/policyengine-simulation-persistence/README.md +++ b/libs/policyengine-simulation-persistence/README.md @@ -166,6 +166,21 @@ report and run rows (C1 · 24). Three modules do it: 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 @@ -229,13 +244,16 @@ version, dataset and region it calculates on. 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. An -unforced window re-run is refused while a budget-window run or a report run -of the report is `pending` or `running`; one that recalculates is a forced -re-run, never refused, whose year runs and simulation runs are marked -`forced`. +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` joins or creates its run as 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 f3a1ee335..49a642977 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 @@ -27,11 +27,9 @@ 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 nothing: it is refused while a run of the report is -``pending`` or ``running`` (a budget-window run or a report run); the -service forces every window re-run, as windows have no keys yet. A -simulation's re-run takes no 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 diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index 8ba5b70a0..f1706629d 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -170,19 +170,24 @@ 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 @@ -279,13 +284,17 @@ 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`, and a report run per year. A window has no keys yet, so every -re-run recalculates it, forced or not: `recalculate` is set, and its year -runs and new simulation runs are marked `forced`. Each year's sides are new -runs of 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). 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. 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 ca73f7877..f61de90d1 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 @@ -208,14 +208,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 re-run of an economy 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 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 budget-window report or one 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; a - household report's re-run ignores it. + 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 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 f4cc13f6a..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 @@ -4,15 +4,15 @@ 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. An economy 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 budget-window report or - of one created before keys, calculates both simulations again, as an - extra run marked forced that nothing joins. - 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 re-run joins or creates its run as an + 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. @@ -289,17 +289,17 @@ 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, an economy or household report created by key joins the " + "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 " - "budget-window report or one 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 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. " + "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." ), 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 97dd4d18c..014cd4adf 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 @@ -23,22 +23,23 @@ 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 - budget window has no keys yet, so its re-run always creates its runs, - marked forced. Every new run is pending with no Modal call ID, and a - forced re-run is never refused while a run is under way; + 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 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, marked forced as a household report has no keys yet, 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 +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. """ @@ -445,12 +446,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 new runs of that year's own simulations, as - its report run in the report's newest window run names them, marked - forced: a window has no keys yet (interim answer B). 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( 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 5b0c0cddc..e73209b67 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 @@ -5,9 +5,12 @@ 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 + ``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 @@ -548,8 +551,10 @@ def _submission_routes( "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, found or created by a key of its definition as an " From b62fc04df412640c636a1d32b1b695575dd53496 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:51:49 +0400 Subject: [PATCH 096/107] Say the staging check's report is found by key, in the deployment notes Co-Authored-By: Claude Opus 5.5 --- .../DEPLOYMENT.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/projects/policyengine-simulation-entry/DEPLOYMENT.md b/projects/policyengine-simulation-entry/DEPLOYMENT.md index d653d0a88..d22e35c81 100644 --- a/projects/policyengine-simulation-entry/DEPLOYMENT.md +++ b/projects/policyengine-simulation-entry/DEPLOYMENT.md @@ -137,16 +137,16 @@ 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 request reuses the simulation runs an earlier check on the same -versions calculated, and once reports are found by key it ends on that -check's report run, so the forced run, which nothing joins or reuses, 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, and, -until reports are found by key, a new report and its ordinary run too, which -on a .py version's first check calculates both simulations as well. +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 From df7efa1f8f6c3cdd99656235a57c958bd52ec688 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 04:13:03 +0400 Subject: [PATCH 097/107] Remove what no re-run reaches any more, after review round 5 Round 5's finding 4 and 6. insert_report_rerun no longer refuses while a window run of the report is under way: the service re-runs a window with insert_window_rerun, and nothing maps the refusal any more, so RunInProgressError, its query and the test of it go. The unused ServiceSettings.reuse_prefix and the test-only FoundEconomyReport.inserted_simulation_run_ids go too (the tests check each side's run_inserted instead). find_or_insert_report_run_on_sides returns no side runs after a lost race, since the savepoint took back what it inserted. The output bucket setting stays, read by nothing, until the reuse search is removed with its deployment setting. Co-Authored-By: Claude Opus 5.5 --- .../__init__.py | 2 - .../economy_rerun_records.py | 56 +++---------------- .../keyed_economy_records.py | 21 ++----- .../tests/test_economy_window_reruns.py | 38 ------------- .../tests/test_keyed_economy_records.py | 7 +-- .../economy_submissions.py | 9 +-- 6 files changed, 18 insertions(+), 115 deletions(-) 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 2ae9f656c..68f8e2076 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py @@ -32,7 +32,6 @@ ReportDefinition, RerunRecordDeletedError, RerunSide, - RunInProgressError, SideDefinition, SimulationDefinition, WindowRerunYear, @@ -263,7 +262,6 @@ "RerunRecordDeletedError", "RerunSide", "ReusableRun", - "RunInProgressError", "RunReuse", "RunVersions", "SharedRowNotSettledError", 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 49a642977..04f2ac2c0 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 @@ -45,7 +45,7 @@ from contextlib import contextmanager from dataclasses import dataclass, replace -from typing import TYPE_CHECKING, Any, Final +from typing import TYPE_CHECKING, Any from sqlalchemy import func, insert, literal, select @@ -91,7 +91,6 @@ ) from policyengine_simulation_persistence.tables import ( ReportRunStatus, - SimulationStatus, budget_window_runs, report_runs, simulation_runs, @@ -101,7 +100,7 @@ from collections.abc import Iterator, Mapping from uuid import UUID - from sqlalchemy import Column, ColumnElement, Connection, Table + from sqlalchemy import Column, Connection from policyengine_simulation_persistence.economy_run_records import ( EconomyPopulation, @@ -110,10 +109,6 @@ from policyengine_simulation_persistence.keyed_economy_records import Side from policyengine_simulation_persistence.shared_rows import FoundSimulationRun -# 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 RerunSide: @@ -279,18 +274,6 @@ 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 lock_reruns_of(connection: Connection, record_id: UUID) -> None: """Wait for, then hold until the transaction ends, the record's re-run lock. @@ -311,30 +294,16 @@ 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 ) -> FoundReportRun: """Join the report's run on the re-run's versions, or create it, pending. - Unless the re-run is forced, take the report's re-run lock, raise - RunInProgressError, creating nothing, while a budget-window run of the - report is pending or running (the service re-runs a budget window with - ``insert_window_rerun``; one passed here directly is refused that way), - 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 + 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 @@ -351,7 +320,6 @@ def insert_report_rerun( versions = rerun.versions if not rerun.forced: lock_reruns_of(connection, rerun.report_id) - _refuse_while_window_runs(connection, rerun.report_id) joined = find_joinable_report_run( connection, report_id=rerun.report_id, @@ -605,15 +573,6 @@ def insert_household_report_rerun( return found -def _refuse_while_window_runs(connection: Connection, report_id: UUID) -> None: - """Raise RunInProgressError while the report has a budget-window run under way.""" - under_way = _run_under_way( - connection, budget_window_runs, budget_window_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: @@ -665,7 +624,6 @@ def _record_checked(*own_keys: Column[Any]) -> Iterator[None]: "ReportDefinition", "RerunRecordDeletedError", "RerunSide", - "RunInProgressError", "SideDefinition", "SimulationDefinition", "WindowRerunYear", 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 index 0eb7ef8cd..e5691ad30 100644 --- 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 @@ -28,7 +28,7 @@ from __future__ import annotations -from dataclasses import dataclass, replace +from dataclasses import dataclass from typing import TYPE_CHECKING, Any, Final, Literal from policyengine_simulation_persistence.definition_keys import KEY_VERSION @@ -127,16 +127,6 @@ class FoundEconomyReport: baseline: FoundSide reform: FoundSide - @property - def inserted_simulation_run_ids(self) -> tuple[UUID, ...]: - """Return the simulation runs this request inserted, each once.""" - inserted = [ - side.simulation_run_id - for side in (self.baseline, self.reform) - if side.run_inserted - ] - return tuple(dict.fromkeys(inserted)) - @dataclass(frozen=True) class KeyedEconomySimulation: @@ -275,8 +265,9 @@ def find_or_insert_report_run_on_sides( 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, which holds only when this call - inserted the report run (otherwise nothing it inserted is kept). + 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: @@ -295,9 +286,7 @@ def find_or_insert_report_run_on_sides( raise if not run.inserted: savepoint.rollback() - return run, { - side: replace(found, inserted=False) for side, found in runs.items() - } + return run, {} savepoint.commit() return run, runs 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 e0a916609..c35a6ec7d 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_window_reruns.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_window_reruns.py @@ -44,7 +44,6 @@ KeyedBudgetWindow, KeyedWindowYear, NewBudgetWindowReport, - NewReportRerun, NewWindowRerun, ProposedSide, ReportRunStatus, @@ -52,14 +51,12 @@ RerunRecordDeletedError, RerunSide, ReusableRun, - RunInProgressError, RunReuse, SimulationStatus, WindowRerunYear, WindowYearDefinition, find_or_create_budget_window, insert_budget_window_report, - insert_report_rerun, insert_window_rerun, read_report_definition, ) @@ -484,41 +481,6 @@ def test_an_unforced_window_rerun_after_a_failed_run_names_its_years_runs( assert again.baseline.run_inserted is False -@pytest.mark.parametrize("status", [ReportRunStatus.PENDING, ReportRunStatus.RUNNING]) -def test_a_single_year_rerun_of_a_window_is_refused_while_a_window_run_is_under_way( - public_api_database_url, status: ReportRunStatus -) -> None: - 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) - - # The service re-runs a window with insert_window_rerun. - 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, - ), - ), - ) - - assert report_refused.value.run_id == stored.window_run_id - - def test_a_window_reruns_inputs_name_each_years_own_reusable_runs( public_api_database_url, ) -> None: diff --git a/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py b/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py index a4388a854..aa4087ede 100644 --- a/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py @@ -166,7 +166,7 @@ def test_a_keyed_report_is_created_with_its_simulations_and_first_run( assert found.reform.simulation_id == request.reform.simulation_id assert found.baseline.run_inserted assert found.reform.run_inserted - assert found.inserted_simulation_run_ids == ( + assert (found.baseline.simulation_run_id, found.reform.simulation_run_id) == ( request.baseline.simulation_run_id, request.reform.simulation_run_id, ) @@ -253,7 +253,6 @@ def test_an_identical_request_ends_on_the_same_rows_and_inserts_nothing( assert (again.report_inserted, again.run.inserted) == (False, False) assert not again.baseline.run_inserted assert not again.reform.run_inserted - assert again.inserted_simulation_run_ids == () assert counts_after == counts @@ -271,7 +270,8 @@ def test_the_same_policy_on_both_sides_names_one_simulation_run_twice( simulation_count = _count(connection, "simulations") assert found.baseline == found.reform - assert found.inserted_simulation_run_ids == (request.baseline.simulation_run_id,) + 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 @@ -307,7 +307,6 @@ def test_a_report_whose_run_failed_gets_a_new_run_joining_its_simulation_runs( 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 - assert second.inserted_simulation_run_ids == (second.reform.simulation_run_id,) def test_a_forced_run_is_never_joined_by_a_create(public_api_database_url) -> 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 cfd1d563d..9eda9b7bc 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 @@ -204,18 +204,15 @@ class ServiceSettings: ``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. + simulation output files for good. The service reads it no longer: a + report joins its sides' runs by version set (C1 · 24's answers 4 and + 5), not by their files; the setting goes with the reuse search. """ 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: return EconomySubmissionUnavailableError( From 11c95ffd1a0a95d4cb3e435ed3deec3b6f24adaf Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 04:14:18 +0400 Subject: [PATCH 098/107] Say what re-runs, windows and requests do now, after review round 5 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Round 5's findings 1 to 3: no re-run writes a trigger (answer 6); a keyed window's re-run joins after the re-run lock, as a report's does; a household report's re-run joins or forces as an economy one's does; window answers name the window run a request ended on, joined or created, and a side reused when this request didn't insert its run; request options are what the calculation reads, the report storing the SPM selection alone; include_cliffs: true is refused until C1 · 39; the old create functions without keys are no longer the service's, kept for tests; the persistence README lists the household keys. The window options test is renamed for what it checks. Co-Authored-By: Claude Opus 5.5 --- .../README.md | 22 +++++++++----- .../budget_window_records.py | 15 +++++----- .../economy_rerun_records.py | 11 +++---- .../policyengine-simulation-entry/README.md | 2 +- .../src/policyengine_simulation_entry/app.py | 2 +- .../budget_window_api_models.py | 29 ++++++++++--------- .../economy_api_models.py | 10 ++++--- .../economy_reruns.py | 11 +++---- .../economy_routes.py | 10 +++---- .../household_report_reruns.py | 2 +- .../tests/test_budget_window_requests.py | 6 ++-- 11 files changed, 67 insertions(+), 53 deletions(-) diff --git a/libs/policyengine-simulation-persistence/README.md b/libs/policyengine-simulation-persistence/README.md index 5340ae679..8a672da9a 100644 --- a/libs/policyengine-simulation-persistence/README.md +++ b/libs/policyengine-simulation-persistence/README.md @@ -94,9 +94,11 @@ 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. Both create unkeyed rows; the Simulation Entrypoint now creates by key -("Shared simulations, reports and runs" below), and budget windows still -create this way. A row naming one that does not exist is refused by its foreign key with +run. Both create unkeyed rows, as `insert_budget_window_report` and +`insert_household_report` do; the Simulation Entrypoint calls none of them +now, creating every record by key ("Shared simulations, reports and runs" +below), and tests use them to store records created before keys. 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 @@ -130,7 +132,7 @@ 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). Three modules do it: +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 @@ -141,7 +143,11 @@ report and run rows (C1 · 24). Three modules do it: 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. Names and codes, not + 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 @@ -224,8 +230,8 @@ version, dataset and region it calculates on. simulation row, which keeps the catalog rows it was created on. - `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, trigger `manual`, - each side joining its simulation's run on those versions that hasn't + 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 @@ -261,7 +267,7 @@ A household report's definition also names its household (`household_id`). 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 (trigger `manual`). A forced +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 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 18b4ac63d..f03db9baf 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 @@ -5,13 +5,14 @@ whose ``budget_window_size`` is the window's length, with one ``budget_window_runs`` row for its 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. + +``insert_budget_window_report`` creates such a window without keys, as +windows were created before C1 · 27; the simulation service now finds or +creates windows by key (``keyed_window_records``), and tests use this to +store a window created before keys. Every row is pending with no Modal +call; the service then starts the first years, and each year's coordinator +starts the next ones (see ``policyengine_stage12_persistence.BudgetWindowStore``). """ from __future__ import annotations 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 04f2ac2c0..c88e13238 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 @@ -10,8 +10,9 @@ - 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. A report's new run has - trigger ``manual``. A budget window's new run is a ``budget_window_runs`` + 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 names runs of its own household simulations. @@ -280,8 +281,8 @@ def lock_reruns_of(connection: Connection, record_id: UUID) -> None: 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 waits here until the first one's transaction ends, then sees its run, which an economy - or household report's re-run joins and a budget window's is refused - for. A simulation's re-run takes none, as the Public API's index on runs + 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. """ @@ -512,7 +513,7 @@ def insert_household_report_rerun( ) -> 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 a report run it created. Unforced (a keyed report's re-run), take the diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index f1706629d..25b1b5b5d 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -306,7 +306,7 @@ 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 -(trigger `manual`) is started by one household function call, as a new +(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, joins a stored 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..7f1e43a68 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. """ 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 1d92ecc2e..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 @@ -95,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: @@ -112,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 @@ -129,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/economy_api_models.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py index f61de90d1..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 @@ -162,8 +162,9 @@ 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. """ @@ -194,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: 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 014cd4adf..fc2cec1ad 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 @@ -17,7 +17,7 @@ 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 (a report's with trigger ``manual``); a keyed + 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 @@ -237,10 +237,11 @@ async def rerun_report( ) -> EconomyReportCreated | BudgetWindowReportCreated | HouseholdReportCreated: """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. 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 e73209b67..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 @@ -570,11 +570,11 @@ def _submission_routes( responses={ 201: { "description": ( - "The report the request ended on and its run: an economy " - "report found or created by key, with its run on the default " - "worker's versions, joined (no new call) or created and " - "started; a budget-window or household report and its first " - "runs, created" + "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, 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 b85f33167..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 @@ -13,7 +13,7 @@ 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 (trigger ``manual``) + 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 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"}, From 3e3e4a1dedcd97c4252a766d7a4ffd2c31e53385 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 04:15:49 +0400 Subject: [PATCH 099/107] Test two identical window requests at once ending on one window run Round 5's finding 5. Both find the stored window, whose earlier window run failed, so neither finds a run to join; the first inserts a window run and holds its transaction open until the second waits for it at the window run's index, then the second joins it with its year runs, and only the first starts its years. It passes against the code already there. The two-transaction helpers moved from the economy test module to committed_rows, which both use. Co-Authored-By: Claude Opus 5.5 --- .../tests/committed_rows.py | 64 ++++++++++++++++- .../tests/test_keyed_economy_records.py | 63 +++-------------- .../tests/test_keyed_window_records.py | 68 ++++++++++++++++++- 3 files changed, 137 insertions(+), 58 deletions(-) diff --git a/libs/policyengine-simulation-persistence/tests/committed_rows.py b/libs/policyengine-simulation-persistence/tests/committed_rows.py index bd7b0fba7..54cca255e 100644 --- a/libs/policyengine-simulation-persistence/tests/committed_rows.py +++ b/libs/policyengine-simulation-persistence/tests/committed_rows.py @@ -1,20 +1,26 @@ -"""Remove the rows a test of two transactions committed. +"""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. +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 + from sqlalchemy import Connection, Engine def delete_catalog_rows(connection: Connection, economy: EconomyCatalog) -> None: @@ -39,3 +45,55 @@ def delete_catalog_rows(connection: Connection, economy: EconomyCatalog) -> None "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) -> None: + """Return once a backend waits for a lock the backend ``holder_pid`` holds.""" + deadline = time.monotonic() + LOCK_WAIT_TIMEOUT_SECONDS + with engine.connect() as connection: + while time.monotonic() < deadline: + waiting = connection.execute( + text( + "SELECT count(*) FROM pg_stat_activity " + "WHERE :holder_pid = ANY(pg_blocking_pids(pid))" + ), + {"holder_pid": holder_pid}, + ).scalar_one() + connection.rollback() + if waiting: + return + 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/test_keyed_economy_records.py b/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py index aa4087ede..ebe33047b 100644 --- a/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py @@ -12,13 +12,17 @@ from __future__ import annotations import threading -import time 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, @@ -50,13 +54,12 @@ from sqlalchemy import event, func, insert, select, text, update if TYPE_CHECKING: - from collections.abc import Callable, Iterator + from collections.abc import Iterator - from sqlalchemy import Connection, Engine + from sqlalchemy import Connection pytestmark = pytest.mark.public_api_schema -LOCK_WAIT_TIMEOUT_SECONDS = 10.0 NATIONAL_SPM = {"geography_kind": "national"} @@ -436,54 +439,6 @@ def test_a_keyed_simulation_joins_its_run_or_creates_it( assert simulation["definition_key"] == request.definition.definition_key -def _wait_until_another_backend_waits_for(engine: Engine, holder_pid: int) -> None: - """Return once a backend waits for a lock the backend ``holder_pid`` holds.""" - deadline = time.monotonic() + LOCK_WAIT_TIMEOUT_SECONDS - with engine.connect() as connection: - while time.monotonic() < deadline: - waiting = connection.execute( - text( - "SELECT count(*) FROM pg_stat_activity " - "WHERE :holder_pid = ANY(pg_blocking_pids(pid))" - ), - {"holder_pid": holder_pid}, - ).scalar_one() - connection.rollback() - if waiting: - return - 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] - - def test_two_identical_requests_at_once_end_on_the_same_rows_and_start_one_call( committed_engine, committed_catalog ) -> None: @@ -509,14 +464,14 @@ def first_request() -> None: 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) + 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) + 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) diff --git a/libs/policyengine-simulation-persistence/tests/test_keyed_window_records.py b/libs/policyengine-simulation-persistence/tests/test_keyed_window_records.py index 4f6d79ec1..7f4c3df3e 100644 --- a/libs/policyengine-simulation-persistence/tests/test_keyed_window_records.py +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_window_records.py @@ -10,12 +10,18 @@ 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, @@ -28,6 +34,7 @@ EconomyPopulation, EconomyReportDefinition, EconomyRunStore, + FoundBudgetWindow, KeyedBudgetWindow, KeyedEconomyReport, KeyedWindowYear, @@ -38,7 +45,7 @@ find_or_create_economy_report, ) from public_api_rows import insert_policy -from sqlalchemy import text +from sqlalchemy import func, select, text if TYPE_CHECKING: from collections.abc import Iterator @@ -373,3 +380,62 @@ def test_a_window_request_naming_another_length_than_its_years_is_refused() -> N 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] = [] + + 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() + 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 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] From cb503bdd97ff6003278ae4719530cbee5faf9527 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 04:28:51 +0400 Subject: [PATCH 100/107] Fix review round 6's findings: last stale passages, an unused parameter, test isolation - Docs: the persistence README no longer names the removed run-in-progress refusal; the entry README's economy re-run names no trigger; the deployment notes say the service no longer reads the output bucket; the Stage 12 document's re-run and household re-run passages describe joining and forced runs with no trigger. - budget_window_records' year run row, used only by the window insert without keys, is private and writes initial and unforced itself; the module docstring says such a window could name a succeeded run on a year's side. - The window two-transaction test keys its window under the committed catalog's own country, and asserts that the second request waited at the window run's insert (wait_until_another_backend_waits_for now returns the waiting statement); test_shared_rows uses committed_rows' helpers instead of its own copies. The pinned formatter's changes to three test files come with them. Co-Authored-By: Claude Opus 5.5 --- .../stage-12-modal-worker-foundation.md | 32 +++++----- .../README.md | 5 +- .../budget_window_records.py | 23 ++++--- .../tests/committed_rows.py | 14 ++--- .../tests/test_definition_keys.py | 4 +- .../tests/test_economy_window_reruns.py | 4 +- .../tests/test_keyed_household_records.py | 5 +- .../tests/test_keyed_window_records.py | 22 +++++-- .../tests/test_shared_rows.py | 60 ++++--------------- .../DEPLOYMENT.md | 10 ++-- .../policyengine-simulation-entry/README.md | 5 +- 11 files changed, 81 insertions(+), 103 deletions(-) diff --git a/docs/migration/stage-12-modal-worker-foundation.md b/docs/migration/stage-12-modal-worker-foundation.md index 5b5900672..b54ccad9f 100644 --- a/docs/migration/stage-12-modal-worker-foundation.md +++ b/docs/migration/stage-12-modal-worker-foundation.md @@ -335,15 +335,18 @@ columns, for example a reform that turns on labour supply responses, can't reuse it and fails with `reused_simulation_output_incompatible`. **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. For a record created by key, unless the re-run is +forced, it joins the record's run on the current versions that hasn't failed +and wasn't forced, which gets no call, or else creates the record'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 @@ -801,11 +804,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 8a672da9a..7718cdfe3 100644 --- a/libs/policyengine-simulation-persistence/README.md +++ b/libs/policyengine-simulation-persistence/README.md @@ -237,9 +237,8 @@ version, dataset and region it calculates on. 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; it refuses - with `RunInProgressError` only while a budget-window run of the report is - under way. A forced one (`NewReportRerun.forced`) takes no lock, always + 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. No side of a report's re-run names a reused run. `insert_simulation_rerun` joins or creates the simulation's run on the re-run's versions, catalog version and year 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 f03db9baf..80f0c6510 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 @@ -5,7 +5,9 @@ whose ``budget_window_size`` is the window's length, with one ``budget_window_runs`` row for its 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. The report names its first year's simulations. +simulations, of that year; a window created before keys could instead name, +on a year's side, a run that already succeeded (``ReportSimulation.reused``). +The report names its first year's simulations. ``insert_budget_window_report`` creates such a window without keys, as windows were created before C1 · 27; the simulation service now finds or @@ -216,31 +218,28 @@ def insert_budget_window_report( connection.execute( insert(report_runs), [ - year_run_row( + _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( # noqa: PLR0913 # the year, then each column it doesn't name - window_year: WindowYearRuns, +def _year_run_row( + window_year: BudgetWindowYear, *, report_id: UUID, window_run_id: UUID, versions: RunVersions, - trigger: ReportRunTrigger, - forced: bool = False, ) -> dict[str, Any]: - """Return a year's report run in a window run, pending with no call, as inserted. + """Return a window's first year run as created before keys, pending, unforced. - ``window_year`` is a new window's year or a re-run's; ``trigger`` says - which, and ``forced`` marks a forced re-run's. + Keyed windows' year runs, which name no trigger, are + ``keyed_window_records.window_year_run_row``'s. """ return { "id": window_year.report_run_id, @@ -252,7 +251,7 @@ def year_run_row( # noqa: PLR0913 # the year, then each column it doesn't name "country_package_version": versions.country_package_version, "policyengine_version": versions.policyengine_version, "status": ReportRunStatus.PENDING, - "trigger": trigger, + "trigger": ReportRunTrigger.INITIAL, "modal_call_id": None, - "forced": forced, + "forced": False, } diff --git a/libs/policyengine-simulation-persistence/tests/committed_rows.py b/libs/policyengine-simulation-persistence/tests/committed_rows.py index 54cca255e..7b93b793b 100644 --- a/libs/policyengine-simulation-persistence/tests/committed_rows.py +++ b/libs/policyengine-simulation-persistence/tests/committed_rows.py @@ -51,21 +51,21 @@ def delete_catalog_rows(connection: Connection, economy: EconomyCatalog) -> None LOCK_WAIT_TIMEOUT_SECONDS = 10.0 -def wait_until_another_backend_waits_for(engine: Engine, holder_pid: int) -> None: - """Return once a backend waits for a lock the backend ``holder_pid`` holds.""" +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.""" deadline = time.monotonic() + LOCK_WAIT_TIMEOUT_SECONDS with engine.connect() as connection: while time.monotonic() < deadline: waiting = connection.execute( text( - "SELECT count(*) FROM pg_stat_activity " - "WHERE :holder_pid = ANY(pg_blocking_pids(pid))" + "SELECT query FROM pg_stat_activity " + "WHERE :holder_pid = ANY(pg_blocking_pids(pid)) LIMIT 1" ), {"holder_pid": holder_pid}, - ).scalar_one() + ).scalar_one_or_none() connection.rollback() - if waiting: - return + if waiting is not None: + return waiting time.sleep(0.05) msg = "the second request never waited for the first one's rows" raise AssertionError(msg) diff --git a/libs/policyengine-simulation-persistence/tests/test_definition_keys.py b/libs/policyengine-simulation-persistence/tests/test_definition_keys.py index e6bff982b..3382a3851 100644 --- a/libs/policyengine-simulation-persistence/tests/test_definition_keys.py +++ b/libs/policyengine-simulation-persistence/tests/test_definition_keys.py @@ -304,9 +304,7 @@ def test_each_part_of_a_household_report_definition_changes_its_key() -> None: 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 -): +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"} 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 c35a6ec7d..2cb13f189 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_window_reruns.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_window_reruns.py @@ -358,9 +358,7 @@ def test_a_forced_window_rerun_creates_a_window_run_and_each_years_new_runs( assert earlier_window["status"] == ReportRunStatus.SUCCEEDED -def _keyed_window( - connection: Connection, economy: EconomyCatalog -) -> FoundBudgetWindow: +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", diff --git a/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py b/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py index 9dca6f3fc..f277830ed 100644 --- a/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py @@ -298,8 +298,9 @@ def test_a_household_policy_compared_with_itself_names_one_simulation_run_twice( 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"] + assert ( + report_run["baseline_simulation_run_id"] + == (report_run["reform_simulation_run_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 index 7f4c3df3e..9d3ce4fed 100644 --- a/libs/policyengine-simulation-persistence/tests/test_keyed_window_records.py +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_window_records.py @@ -59,10 +59,14 @@ def _definition( - reform: SimulationChoice, *, year: int = FIRST_YEAR, size: int | None = 3 + reform: SimulationChoice, + *, + country: str = "us", + year: int = FIRST_YEAR, + size: int | None = 3, ) -> EconomyReportDefinition: return EconomyReportDefinition( - country="us", + country=country, baseline=CURRENT_LAW, reform=reform, dataset_name="populace_us_2024", @@ -78,7 +82,7 @@ def _keyed_window( ) -> KeyedBudgetWindow: """Return a request's three-year window on ``economy``, with fresh IDs.""" return KeyedBudgetWindow( - definition=_definition(reform), + definition=_definition(reform, country=economy.catalog.country), report_id=uuid4(), window_run_id=uuid4(), tax_benefit_model_id=economy.catalog.model_id, @@ -262,7 +266,9 @@ def test_a_window_year_names_a_single_year_reports_simulation_run( single_year = find_or_create_economy_report( connection, KeyedEconomyReport( - definition=_definition(reform, year=2027, size=None), + 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()), @@ -404,6 +410,7 @@ def test_two_identical_window_requests_at_once_end_on_one_window_run_started_onc 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) @@ -419,7 +426,9 @@ def first_request() -> None: 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) + 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) @@ -428,6 +437,9 @@ def second_request() -> None: 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 diff --git a/libs/policyengine-simulation-persistence/tests/test_shared_rows.py b/libs/policyengine-simulation-persistence/tests/test_shared_rows.py index ee9e0311a..64a5ffaaf 100644 --- a/libs/policyengine-simulation-persistence/tests/test_shared_rows.py +++ b/libs/policyengine-simulation-persistence/tests/test_shared_rows.py @@ -10,11 +10,15 @@ from __future__ import annotations import threading -import time 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, @@ -40,14 +44,11 @@ from sqlalchemy import event, insert, text, update if TYPE_CHECKING: - from collections.abc import Callable - - from sqlalchemy import Connection, Engine + from sqlalchemy import Connection pytestmark = pytest.mark.public_api_schema # How long a test waits for the other transaction to reach its insert. -LOCK_WAIT_TIMEOUT_SECONDS = 10.0 def _key(name: str) -> str: @@ -277,26 +278,6 @@ def test_a_report_run_is_joined_on_its_versions_outside_budget_windows( ) -def _wait_until_another_backend_waits_for(engine: Engine, holder_pid: int) -> None: - """Return once a backend waits for a lock the backend ``holder_pid`` holds.""" - deadline = time.monotonic() + LOCK_WAIT_TIMEOUT_SECONDS - with engine.connect() as connection: - while time.monotonic() < deadline: - waiting = connection.execute( - text( - "SELECT count(*) FROM pg_stat_activity " - "WHERE :holder_pid = ANY(pg_blocking_pids(pid))" - ), - {"holder_pid": holder_pid}, - ).scalar_one() - connection.rollback() - if waiting: - return - time.sleep(0.05) - msg = "the other transaction never waited for the first one's row" - raise AssertionError(msg) - - def test_a_transaction_inserting_a_run_another_has_inserted_waits_and_joins_it( committed_engine, committed_catalog ) -> None: @@ -308,17 +289,6 @@ def test_a_transaction_inserting_a_run_another_has_inserted_waits_and_joins_it( ) first_has_inserted = threading.Event() found: dict[str, Any] = {} - errors: list[BaseException] = [] - - def recording_errors(work: Callable[[], None]) -> Callable[[], None]: - def run() -> None: - try: - work() - except BaseException as error: # noqa: BLE001 # re-raised by the test's thread - errors.append(error) - first_has_inserted.set() - - return run def insert_then_commit_once_the_other_waits() -> None: with committed_engine.begin() as connection: @@ -330,7 +300,7 @@ def insert_then_commit_once_the_other_waits() -> None: text("SELECT pg_backend_pid()") ).scalar_one() first_has_inserted.set() - _wait_until_another_backend_waits_for(committed_engine, holder_pid) + 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) @@ -340,17 +310,11 @@ def insert_once_the_first_has() -> None: connection, _simulation_run_values(economy, simulation.id) ) - threads = [ - threading.Thread(target=recording_errors(work)) - for work in (insert_then_commit_once_the_other_waits, insert_once_the_first_has) - ] - for thread in threads: - thread.start() - for thread in threads: - thread.join(LOCK_WAIT_TIMEOUT_SECONDS * 2) - - if errors: - raise errors[0] + 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) diff --git a/projects/policyengine-simulation-entry/DEPLOYMENT.md b/projects/policyengine-simulation-entry/DEPLOYMENT.md index d22e35c81..9602eec03 100644 --- a/projects/policyengine-simulation-entry/DEPLOYMENT.md +++ b/projects/policyengine-simulation-entry/DEPLOYMENT.md @@ -121,10 +121,12 @@ fails the check. `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. +that name: the bucket that keeps v2 simulation output files for good. The +service no longer reads it: a report joins its sides' simulation runs by +version set (C1 · 24's answers 4 and 5), not by their files, and the setting +goes with the reuse search's removal. It never reads the bucket itself, 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. diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index 25b1b5b5d..1eb697dc1 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -275,8 +275,9 @@ 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's -trigger is `manual`. Such a report stored asking for cliff impacts +depended on that report (C1 · 24's interim answer B). The new report run +names no trigger (answer 6): API v1's record of the request 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). From 9a245438d9838ed52e6c739da0d0c5e68b565b3e Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 04:37:24 +0400 Subject: [PATCH 101/107] Fix review round 7's findings: wording, a docstring, a stale comment, a race in a test helper - The entry README names the Public API's per-user report-run record, not API v1's. - The deployment notes say the deploy still sets and checks V2_SIMULATION_OUTPUT_BUCKET, the service reads it into its settings and uses it for nothing, and both go with the run-reuse search later. - The Stage 12 document's re-run passage says a simulation's re-run joins or creates its run whether or not the simulation has a key, and takes no force. - budget_window_records' year run row docstring says it builds each year's run of a window's first window run. - test_shared_rows loses a comment its moved constant left behind. - wait_until_another_backend_waits_for reads the waiting backend's statement again in a transaction of its own once it has found it, so the statement is the one the backend waits in, not the one before. Co-Authored-By: Claude Opus 5.5 --- .../stage-12-modal-worker-foundation.md | 16 ++++++++------- .../budget_window_records.py | 4 +++- .../tests/committed_rows.py | 20 ++++++++++++++----- .../tests/test_shared_rows.py | 1 - .../DEPLOYMENT.md | 17 ++++++++-------- .../policyengine-simulation-entry/README.md | 3 ++- 6 files changed, 38 insertions(+), 23 deletions(-) diff --git a/docs/migration/stage-12-modal-worker-foundation.md b/docs/migration/stage-12-modal-worker-foundation.md index b54ccad9f..9db9d9255 100644 --- a/docs/migration/stage-12-modal-worker-foundation.md +++ b/docs/migration/stage-12-modal-worker-foundation.md @@ -335,13 +335,15 @@ columns, for example a reform that turns on labour supply responses, can't reuse it and fails with `reused_simulation_output_incompatible`. **A re-run.** The service re-runs a stored report or simulation with the same -two calls, by run ID. For a record created by key, unless the re-run is -forced, it joins the record's run on the current versions that hasn't failed -and wasn't forced, which gets no call, or else creates the record'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 +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 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 80f0c6510..0b5be3fe0 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 @@ -236,7 +236,9 @@ def _year_run_row( window_run_id: UUID, versions: RunVersions, ) -> dict[str, Any]: - """Return a window's first year run as created before keys, pending, unforced. + """Return a year's report run in a window's first window run, pending, unforced. + + As windows were created before keys: trigger ``initial``. Keyed windows' year runs, which name no trigger, are ``keyed_window_records.window_year_run_row``'s. diff --git a/libs/policyengine-simulation-persistence/tests/committed_rows.py b/libs/policyengine-simulation-persistence/tests/committed_rows.py index 7b93b793b..2d648ea23 100644 --- a/libs/policyengine-simulation-persistence/tests/committed_rows.py +++ b/libs/policyengine-simulation-persistence/tests/committed_rows.py @@ -52,20 +52,30 @@ def delete_catalog_rows(connection: Connection, economy: EconomyCatalog) -> None 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.""" + """Return, once a backend waits for a lock ``holder_pid`` holds, its statement. + + The statement is read again, in a transaction of its own, once a waiting + backend 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 = connection.execute( + waiting_pid = connection.execute( text( - "SELECT query FROM pg_stat_activity " + "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 is not None: - return waiting + 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) diff --git a/libs/policyengine-simulation-persistence/tests/test_shared_rows.py b/libs/policyengine-simulation-persistence/tests/test_shared_rows.py index 64a5ffaaf..dfb915d14 100644 --- a/libs/policyengine-simulation-persistence/tests/test_shared_rows.py +++ b/libs/policyengine-simulation-persistence/tests/test_shared_rows.py @@ -48,7 +48,6 @@ pytestmark = pytest.mark.public_api_schema -# How long a test waits for the other transaction to reach its insert. def _key(name: str) -> str: diff --git a/projects/policyengine-simulation-entry/DEPLOYMENT.md b/projects/policyengine-simulation-entry/DEPLOYMENT.md index 9602eec03..2a759270f 100644 --- a/projects/policyengine-simulation-entry/DEPLOYMENT.md +++ b/projects/policyengine-simulation-entry/DEPLOYMENT.md @@ -119,14 +119,15 @@ 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. The -service no longer reads it: a report joins its sides' simulation runs by -version set (C1 · 24's answers 4 and 5), not by their files, and the setting -goes with the reuse search's removal. It never reads the bucket itself, so it -needs no storage permission. A missing or invalid bucket name stops the -deploy. +database, Modal token and v2 manifest settings as the household routes. The +deploy also sets `V2_SIMULATION_OUTPUT_BUCKET`, the `beta` or `prod` variable +of that name: the bucket that keeps v2 simulation output files for good. A +missing or invalid bucket name stops the deploy. The service reads it into +its settings but uses it for nothing: a report joins its sides' simulation +runs by version set (C1 · 24's answers 4 and 5), not by their files. The +setting and its deploy check are removed with the run-reuse search, in a +later change. The service never reads the bucket itself, so it needs no +storage permission. The coordinator and workers get the same bucket from the Modal secret the Stage 12 secret sync writes. diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index 1eb697dc1..340269648 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -276,7 +276,8 @@ 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): API v1's record of the request holds it. Such a +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 From 314a130971c222d0310b267697935973e3b22117 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 04:45:33 +0400 Subject: [PATCH 102/107] Fix review round 8's findings: the last passages on the output bucket The settings comment, the Cloud Run deploy script's comment above the bucket check, the economy deployment test's module docstring and ServiceSettings now say the same as the deployment notes: every deploy sets and checks V2_SIMULATION_OUTPUT_BUCKET, the service reads it into its settings and uses it for nothing, and both go with the run-reuse search. The two-transaction helper's docstring says the statement is read once the waiting backend's pid is found, and test_shared_rows is formatted again. Comments only in the deploy script: no variable or check changes. Co-Authored-By: Claude Opus 5.5 --- .github/scripts/deploy-cloud-run-simulation-entry.sh | 7 ++++--- .../tests/committed_rows.py | 7 ++++--- .../tests/test_shared_rows.py | 1 - .../src/policyengine_simulation_entry/config.py | 7 ++++--- .../policyengine_simulation_entry/economy_submissions.py | 7 ++++--- .../tests/test_economy_deployment.py | 7 ++++--- 6 files changed, 20 insertions(+), 16 deletions(-) diff --git a/.github/scripts/deploy-cloud-run-simulation-entry.sh b/.github/scripts/deploy-cloud-run-simulation-entry.sh index 6f0108438..320bfd236 100755 --- a/.github/scripts/deploy-cloud-run-simulation-entry.sh +++ b/.github/scripts/deploy-cloud-run-simulation-entry.sh @@ -129,9 +129,10 @@ 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. +# The bucket that keeps v2 simulation output files for good. The service +# reads it into its settings and uses it for nothing (a report joins its +# sides' simulation runs by version set); it never reads the bucket. The +# setting and this check go with the run-reuse search. [[ "${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]+$ ]] \ diff --git a/libs/policyengine-simulation-persistence/tests/committed_rows.py b/libs/policyengine-simulation-persistence/tests/committed_rows.py index 2d648ea23..7efca4731 100644 --- a/libs/policyengine-simulation-persistence/tests/committed_rows.py +++ b/libs/policyengine-simulation-persistence/tests/committed_rows.py @@ -54,9 +54,10 @@ def delete_catalog_rows(connection: Connection, economy: EconomyCatalog) -> None 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 again, in a transaction of its own, once a waiting - backend 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. + 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: diff --git a/libs/policyengine-simulation-persistence/tests/test_shared_rows.py b/libs/policyengine-simulation-persistence/tests/test_shared_rows.py index dfb915d14..47f225be5 100644 --- a/libs/policyengine-simulation-persistence/tests/test_shared_rows.py +++ b/libs/policyengine-simulation-persistence/tests/test_shared_rows.py @@ -49,7 +49,6 @@ pytestmark = pytest.mark.public_api_schema - def _key(name: str) -> str: return definition_key({"test": name}) 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..58814e7db 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/config.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/config.py @@ -102,9 +102,10 @@ 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. + # The bucket that keeps v2 simulation output files for good. The service + # uses it for nothing: a report joins its sides' simulation runs by + # version set, not by their files; it goes with the run-reuse search. + # Empty outside deployed environments. v2_simulation_output_bucket: str = "" @classmethod 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 9eda9b7bc..aabdc079b 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 @@ -204,9 +204,10 @@ class ServiceSettings: ``environment`` labels the calls' artifacts, ``modal_environment`` holds the v2 workers, and ``output_bucket`` is the bucket that keeps - simulation output files for good. The service reads it no longer: a - report joins its sides' runs by version set (C1 · 24's answers 4 and - 5), not by their files; the setting goes with the reuse search. + simulation output files for good. The service keeps it here and uses + it for nothing: a report joins its sides' runs by version set + (C1 · 24's answers 4 and 5), not by their files; the setting goes with + the reuse search. """ environment: str diff --git a/projects/policyengine-simulation-entry/tests/test_economy_deployment.py b/projects/policyengine-simulation-entry/tests/test_economy_deployment.py index b500d1be7..0686a8ef7 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_deployment.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_deployment.py @@ -1,9 +1,10 @@ """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. +files for good (the environment variable ``V2_SIMULATION_OUTPUT_BUCKET``) +and refuses a missing or invalid one. The service reads it into its +settings and uses it for nothing, since a report joins its sides' +simulation runs by version set; it never reads the bucket. """ from __future__ import annotations From 91a9c05c90b030ed069b8cda98b11d5b4e616ded Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 04:46:05 +0400 Subject: [PATCH 103/107] Add the changelog fragments for finding or creating records by key Co-Authored-By: Claude Opus 5.5 --- changelog.d/1073.changed.md | 1 + changelog.d/1073.removed.md | 1 + 2 files changed, 2 insertions(+) create mode 100644 changelog.d/1073.changed.md create mode 100644 changelog.d/1073.removed.md 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. From 0b1e7d092e1ac6c97262efeb31f7feefe6266686 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 04:59:42 +0400 Subject: [PATCH 104/107] Pin the Public API schema to PolicyEngine/policyengine-api#4303's head until it merges MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Public API schema job built the tables at 429d348ae, before #4303, so every test needing the key columns, forced markers and nullable per-user columns failed. 63cce8273 is #4303's pushed head, which this branch's models match (B1 · 5's comparison passes locally against it). The job's last step requires a commit on the Public API's master, so it fails until #4303 merges; then the pin moves to #4303's merge commit. Co-Authored-By: Claude Opus 5.5 --- libs/policyengine-simulation-persistence/public-api-commit | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libs/policyengine-simulation-persistence/public-api-commit b/libs/policyengine-simulation-persistence/public-api-commit index 90f10c4b5..06cd4409c 100644 --- a/libs/policyengine-simulation-persistence/public-api-commit +++ b/libs/policyengine-simulation-persistence/public-api-commit @@ -1 +1 @@ -429d348aeff84d1d345799fc93ee7c02f7e2014a +63cce8273e6a2c3659392d7b1f9dfeb917672645 From 56ba811f300cf3a100d745943032a34b96697774 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 05:18:28 +0400 Subject: [PATCH 105/107] Drop the removed 409 run_in_progress from the generated client's re-run test The Test integration job generates the client from the entry's OpenAPI document, which no longer lists run_in_progress, so the test's sample 409 with that code failed to parse. No re-run is refused while a run is under way; the 409 left is rerun_not_supported. Run by node ID against the regenerated client, passing. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_economy_generated_client.py | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) 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, From 9c5ab3acd4f9bfaa73d2337cf91f7ff49fccb2cd Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Tue, 17 Nov 2026 02:07:10 +0400 Subject: [PATCH 106/107] Remove the create functions without keys, the run-reuse search and the entrypoint's output-bucket setting After #1074 the Simulation Entrypoint finds or creates every simulation, report and run by its definition key, so nothing it runs calls the code that created those rows without keys or searched for an earlier succeeded simulation run to reuse. Remove that code, with no change in behaviour: - the persistence library's insert_economy_report, insert_economy_simulation, insert_household_report and insert_budget_window_report, their input types, and the store methods that wrapped them (EconomyRunStore.create_report, create_simulation and create_budget_window_report, HouseholdReportStore.create_report); - find_reusable_run, find_reusable_run_of, ReusableRun, RunReuse and the searches built on them, the store's `reuse` parameters (and the window reads' `years`, which only fed the searches), and the reusable_run and reusable_runs fields; - RerunSide.reused and the checks that refused it; - ServiceSettings.output_bucket, Settings.v2_simulation_output_bucket, and the entrypoint deploy's V2_SIMULATION_OUTPUT_BUCKET format check, runtime variable and workflow input. The Stage 12 steps, scripts and Modal workers keep the bucket. Tests that store a record created before keys now insert its rows directly (economy_rows.insert_pending_report, household_report_rows and a window helper in the window re-run tests). The economy store's commit-failure tests use a forced report re-run, whose create only inserts rows. Fixes #1081 Co-Authored-By: Claude Opus 5.5 --- .../deploy-cloud-run-simulation-entry.sh | 8 - .../workflows/simulation-deploy.reusable.yml | 1 - changelog.d/1081.removed.md | 1 + .../stage-12-modal-worker-foundation.md | 13 +- .../README.md | 81 ++-- .../__init__.py | 30 -- .../budget_window_records.py | 194 +-------- .../economy_inputs.py | 144 +------ .../economy_rerun_records.py | 26 +- .../economy_run_records.py | 386 +----------------- .../economy_run_store.py | 166 ++------ .../household_report_records.py | 157 +------ .../household_report_store.py | 31 +- .../rerun_definitions.py | 3 +- .../tests/economy_rows.py | 69 ++-- .../tests/household_report_rows.py | 189 +++++++++ .../tests/test_budget_window_records.py | 306 +------------- .../tests/test_economy_reruns.py | 204 +-------- .../tests/test_economy_run_records.py | 374 ++--------------- .../tests/test_economy_run_reuse.py | 329 --------------- .../tests/test_economy_run_store.py | 176 +++----- .../tests/test_economy_window_reruns.py | 242 +++++------ .../tests/test_household_report_reruns.py | 45 +- .../tests/test_household_report_store.py | 229 +---------- .../tests/test_keyed_economy_records.py | 8 +- .../DEPLOYMENT.md | 17 +- .../src/policyengine_simulation_entry/app.py | 1 - .../budget_window_submissions.py | 12 +- .../policyengine_simulation_entry/config.py | 6 - .../economy_reruns.py | 15 +- .../economy_submissions.py | 14 +- .../tests/economy_rerun_fakes.py | 33 +- .../tests/economy_service_fakes.py | 19 +- .../tests/test_budget_window_submissions.py | 37 +- .../tests/test_config.py | 12 - .../tests/test_deployment_assets_support.py | 1 - .../tests/test_economy_deployment.py | 85 ---- .../tests/test_economy_reruns.py | 43 +- .../tests/test_economy_routes.py | 1 - .../tests/test_economy_submissions.py | 4 +- 40 files changed, 634 insertions(+), 3078 deletions(-) create mode 100644 changelog.d/1081.removed.md create mode 100644 libs/policyengine-simulation-persistence/tests/household_report_rows.py delete mode 100644 libs/policyengine-simulation-persistence/tests/test_economy_run_reuse.py delete mode 100644 projects/policyengine-simulation-entry/tests/test_economy_deployment.py diff --git a/.github/scripts/deploy-cloud-run-simulation-entry.sh b/.github/scripts/deploy-cloud-run-simulation-entry.sh index 320bfd236..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,12 +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. The service -# reads it into its settings and uses it for nothing (a report joins its -# sides' simulation runs by version set); it never reads the bucket. The -# setting and this check go with the run-reuse search. -[[ "${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]+$ ]] \ @@ -202,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/workflows/simulation-deploy.reusable.yml b/.github/workflows/simulation-deploy.reusable.yml index 49f939272..eaa526412 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/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 1b90bd3f0..827667c23 100644 --- a/docs/migration/stage-12-modal-worker-foundation.md +++ b/docs/migration/stage-12-modal-worker-foundation.md @@ -288,11 +288,12 @@ 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` +**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`). It then starts the manifest's `report_coordinator_callable` (`coordinate_report`) with two arguments and no evaluation record: - the report input, a `ReportExecutionInput` whose `evaluation_id` is the report @@ -313,7 +314,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 a worker an earlier attempt started, which Modal never cancelled, the coordinator waits for that worker instead. 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 diff --git a/libs/policyengine-simulation-persistence/README.md b/libs/policyengine-simulation-persistence/README.md index 738ec2cde..46106b720 100644 --- a/libs/policyengine-simulation-persistence/README.md +++ b/libs/policyengine-simulation-persistence/README.md @@ -83,32 +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. Both create unkeyed rows, as `insert_budget_window_report` and -`insert_household_report` do; the Simulation Entrypoint calls none of them -now, creating every record by key ("Shared simulations, reports and runs" -below), and tests use them to store records created before keys. 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 @@ -119,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 @@ -157,7 +141,7 @@ report and run rows (C1 · 24). These modules do it: 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, joined or offered for reuse. + 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 @@ -190,23 +174,23 @@ report and run rows (C1 · 24). These modules do it: ## 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. @@ -223,11 +207,6 @@ 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, not forced); it doesn't compare the - simulation row, which keeps the catalog rows it was created on. - `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 @@ -239,8 +218,8 @@ version, dataset and region it calculates on. 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. No side - of a report's re-run names a reused run. `insert_simulation_rerun` joins or creates the + 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 @@ -274,10 +253,8 @@ 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, with, given -`reuse`, its reusable run of its own simulation, never giving both sides the -same run; the service passes none, as its re-runs join or force their runs. -`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/src/policyengine_simulation_persistence/__init__.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py index 68f8e2076..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,8 @@ 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, @@ -57,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, @@ -86,7 +75,6 @@ EconomySimulationInputs, ReportSide, ReportSideError, - RunReuse, SideRefusal, SimulationInputs, UnknownDatasetError, @@ -117,9 +105,6 @@ ) 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, @@ -197,7 +182,6 @@ "SERVICE_TABLE_PRIVILEGES", "SERVICE_UPDATABLE_COLUMNS", "BudgetWindowInputs", - "BudgetWindowYear", "CatalogDataset", "CatalogRegion", "EconomyCatalogRows", @@ -229,7 +213,6 @@ "HouseholdJobStore", "HouseholdReportDefinition", "HouseholdReportInputs", - "HouseholdReportSimulation", "HouseholdReportStore", "HouseholdRerunSide", "HouseholdSimulationDefinition", @@ -239,11 +222,7 @@ "KeyedHouseholdReport", "KeyedWindowYear", "MissingPolicyParametersError", - "NewBudgetWindowReport", - "NewEconomyReport", - "NewEconomySimulation", "NewHouseholdJob", - "NewHouseholdReport", "NewHouseholdReportRerun", "NewReportRerun", "NewSimulationRerun", @@ -258,11 +237,8 @@ "ReportRunTrigger", "ReportSide", "ReportSideError", - "ReportSimulation", "RerunRecordDeletedError", "RerunSide", - "ReusableRun", - "RunReuse", "RunVersions", "SharedRowNotSettledError", "SideDefinition", @@ -303,15 +279,9 @@ "find_or_insert_simulation", "find_or_insert_simulation_run", "find_or_insert_simulation_runs", - "find_reusable_run", - "find_reusable_run_of", "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 0b5be3fe0..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,53 +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; a window created before keys could instead name, -on a year's side, a run that already succeeded (``ReportSimulation.reused``). -The report names its first year's simulations. - -``insert_budget_window_report`` creates such a window without keys, as -windows were created before C1 · 27; the simulation service now finds or -creates windows by key (``keyed_window_records``), and tests use this to -store a window created before keys. Every row is pending with no Modal -call; the service then starts the first years, and 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.""" @@ -62,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 @@ -96,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``. @@ -159,101 +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, - ) - for window_year in report.years - ], - ) - - -def _year_run_row( - window_year: BudgetWindowYear, - *, - report_id: UUID, - window_run_id: UUID, - versions: RunVersions, -) -> dict[str, Any]: - """Return a year's report run in a window's first window run, pending, unforced. - - As windows were created before keys: trigger ``initial``. - - Keyed windows' year runs, which name no trigger, are - ``keyed_window_records.window_year_run_row``'s. - """ - 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": ReportRunTrigger.INITIAL, - "modal_call_id": None, - "forced": False, - } 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 index 1f6c4402f..4d0ad395e 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_inputs.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_inputs.py @@ -4,24 +4,20 @@ 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, with the runs a side may reuse -when a search is given. ``EconomyRunStore`` runs these in its transactions. +each side's values on that catalog version. ``EconomyRunStore`` runs these +in its transactions. """ from __future__ import annotations -from dataclasses import dataclass, replace -from typing import TYPE_CHECKING, Any, Literal, get_args +from dataclasses import dataclass +from typing import TYPE_CHECKING, Literal, get_args from policyengine_simulation_persistence.economy_run_records import ( CatalogDataset, CatalogRegion, EconomyPopulation, - ReusableRun, - RunVersions, SimulationChoice, - find_reusable_run, - find_reusable_run_of, read_dataset, read_dataset_by_id, read_model_id, @@ -44,7 +40,6 @@ ) if TYPE_CHECKING: - from collections.abc import Callable, Iterable from uuid import UUID from sqlalchemy import Connection @@ -53,11 +48,6 @@ # 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 @@ -108,20 +98,6 @@ class EconomyRequest: 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.""" @@ -143,15 +119,10 @@ def population(self, year: int) -> EconomyPopulation: @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. - """ + """One simulation's policy and dynamic, and the values they set together.""" choice: SimulationChoice reform: PolicyReform - reusable_run: ReusableRun | None = None @dataclass(frozen=True) @@ -173,17 +144,15 @@ class EconomyReportInputs: @dataclass(frozen=True) class BudgetWindowInputs: - """What a budget-window report is read from, and each year's reusable runs. + """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. ``reusable_runs`` gives, by year, the baseline's and the reform's - reusable run, each None when there is none. + year. """ catalog: EconomyCatalogRows baseline: SimulationInputs reform: SimulationInputs - reusable_runs: dict[int, tuple[ReusableRun | None, ReusableRun | None]] def read_catalog_rows( @@ -289,112 +258,33 @@ def read_side_values( raise ReportSideError(side, error) from error -def read_report_sides( # noqa: PLR0913 # the request's rows, both sides and the search +def read_report_sides( 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), + """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), ) - for side, choice in requested: - inputs = read_side_values(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 read_window_sides( # noqa: PLR0913 # the request's rows, both sides and each year's search +def read_window_sides( 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 = read_side_values( - connection, request, catalog, "baseline", baseline - ) - reform_inputs = read_side_values(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) + """Read both sides' values, the baseline's first, for every year of a window.""" return BudgetWindowInputs( catalog=catalog, - baseline=baseline_inputs, - reform=reform_inputs, - reusable_runs=reusable_runs, + baseline=read_side_values(connection, request, catalog, "baseline", baseline), + reform=read_side_values(connection, request, catalog, "reform", reform), ) - - -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 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 c88e13238..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 @@ -115,16 +115,13 @@ class RerunSide: """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`` (an unforced - budget window's year only), the run is one of its runs that succeeded - on the current versions, and nothing is created for the side; otherwise - ``simulation_run_id`` is the run created, pending, or the ID an economy - report's side proposes, used only if it inserts the run. + 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) @@ -135,7 +132,7 @@ class NewReportRerun: 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. No side names a reused run. + new run of each side, marked forced. """ report_id: UUID @@ -146,12 +143,6 @@ class NewReportRerun: reform: RerunSide forced: bool = False - def __post_init__(self) -> None: - """Refuse a side naming a reused run: each side joins or creates its run.""" - if self.baseline.reused or self.reform.reused: - msg = "a report re-run's sides join or create their runs, reusing none" - raise ValueError(msg) - @property def new_simulation_run_ids(self) -> tuple[UUID, ...]: """Return the IDs of the simulation runs a forced re-run creates. @@ -182,7 +173,7 @@ class NewWindowRerun: 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. No side names a reused run. + proposes. """ report_id: UUID @@ -193,13 +184,8 @@ class NewWindowRerun: years: tuple[WindowRerunYear, ...] def __post_init__(self) -> None: - """Refuse years that aren't 1 to 75 from the first, or a reused side.""" + """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]) - if any( - side.reused for year in self.years for side in (year.baseline, year.reform) - ): - msg = "a window re-run's sides join or create their runs, reusing none" - raise ValueError(msg) def population_in(self, year: int) -> EconomyPopulation: """Return what the window's simulations of ``year`` calculate on.""" 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 daac997e2..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,283 +193,6 @@ 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; - - that wasn't forced: a forced re-run's run is never named by another - report run (C1 · 24's answer 3); 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 - connection: Connection, - *, - 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.forced.is_(False), - 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 -) -> None: - """Create the standalone simulation and its first run, pending. - - Raise EconomyRecordReferenceError when the database refuses a row it - names. The refusal ends the caller's transaction, or its savepoint. - """ - 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_run( - connection, - run_id=run_id, - simulation_id=simulation_id, - population=population, - versions=versions, - ) - - def insert_simulation_run( # noqa: PLR0913 # the run, what it calculates on, and its marker connection: Connection, *, 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 23b7e43ba..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,9 +2,12 @@ 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 @@ -13,9 +16,6 @@ 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, @@ -24,7 +24,6 @@ EconomySimulationInputs, ReportSide, ReportSideError, - RunReuse, SideRefusal, SimulationInputs, UnknownDatasetError, @@ -33,8 +32,6 @@ read_report_sides, read_simulation_values, read_window_sides, - search_by_definition, - search_own_runs, ) from policyengine_simulation_persistence.economy_rerun_records import ( insert_report_rerun, @@ -51,8 +48,6 @@ SimulationChoice, fail_unstarted_report_run, fail_unstarted_simulation_run, - insert_economy_report, - insert_economy_simulation, record_report_run_call, record_simulation_run_call, ) @@ -72,9 +67,6 @@ 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,16 +74,11 @@ 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, @@ -165,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 = read_catalog_rows(connection, request) - search = ( - None - if reuse is None - else search_by_definition( - connection, catalog.population(request.year), reuse - ) - ) return read_report_sides( - connection, - request, - catalog, - baseline=baseline, - reform=reform, - search=search, + connection, request, catalog, baseline=baseline, reform=reform ) def read_report_definition(self, report_id: UUID) -> ReportDefinition | None: @@ -210,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 = read_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 read_report_sides( connection, request, catalog, baseline=baseline.choice, reform=reform.choice, - search=search, ) def read_window_rerun_inputs( @@ -250,47 +206,24 @@ 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 = read_catalog_rows(connection, request) return read_window_sides( - 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 - ), + connection, request, catalog, baseline=baseline, reform=reform ) 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. """ return self._create(lambda connection: insert_window_rerun(connection, rerun)) @@ -298,14 +231,14 @@ 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. """ return self._create(lambda connection: insert_report_rerun(connection, 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. """ return self._create( lambda connection: insert_simulation_rerun(connection, rerun) @@ -317,46 +250,18 @@ 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 = read_catalog_rows(connection, request) return read_window_sides( - 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 - ), + 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. - - Raise ``insert_budget_window_report``'s errors, and - EconomyRecordOutcomeUnknownError when the commit fails after the - rows were inserted. - """ - self._create(lambda connection: insert_budget_window_report(connection, report)) - def find_or_create_report(self, report: KeyedEconomyReport) -> FoundEconomyReport: """Find the report by key, with its run, or create them. @@ -391,24 +296,6 @@ def find_or_create_simulation( lambda connection: find_or_create_economy_simulation(connection, simulation) ) - def create_report(self, report: NewEconomyReport) -> None: - """Create the report, its new simulations and its runs. - - Raise ``insert_economy_report``'s errors, and - EconomyRecordOutcomeUnknownError when the commit fails after the - rows were inserted. - """ - self._create(lambda connection: insert_economy_report(connection, report)) - - def create_simulation(self, simulation: NewEconomySimulation) -> None: - """Create the simulation and its run; see ``insert_economy_simulation``. - - Raise EconomyRecordOutcomeUnknownError as ``create_report`` does. - """ - self._create( - lambda connection: insert_economy_simulation(connection, simulation) - ) - def _create[Created](self, insert: Callable[[Connection], Created]) -> Created: """Run ``insert`` in a transaction, telling a failed commit apart. @@ -496,7 +383,6 @@ def read_simulation(self, simulation_id: UUID) -> EconomySimulationState | None: "EconomySimulationInputs", "ReportSide", "ReportSideError", - "RunReuse", "SideRefusal", "SimulationInputs", "TransactionFactory", 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 083c1a77c..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, *, 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 0ddd4209e..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,9 +39,6 @@ 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, ) @@ -65,9 +62,6 @@ 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, @@ -197,20 +191,11 @@ def find_or_create_report( lambda connection: find_or_create_household_report(connection, report) ) - def create_report(self, report: NewHouseholdReport) -> None: - """Create the report, its simulations and its runs. - - Raise ``insert_household_report``'s errors, and - EconomyRecordOutcomeUnknownError when the commit fails after the - rows were inserted: they may exist. - """ - self._create(lambda connection: insert_household_report(connection, report)) - def create_report_rerun(self, rerun: NewHouseholdReportRerun) -> FoundReportRun: """Join a stored report's run on the re-run's versions, or create it. See ``insert_household_report_rerun``; raise its errors, and - EconomyRecordOutcomeUnknownError as ``create_report`` does. + EconomyRecordOutcomeUnknownError as ``find_or_create_report`` does. """ return self._create( lambda connection: insert_household_report_rerun(connection, rerun) 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 index e1561ba75..af0f332c4 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/rerun_definitions.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/rerun_definitions.py @@ -61,8 +61,7 @@ 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 that joined another report's run names that run's simulation. """ year: int diff --git a/libs/policyengine-simulation-persistence/tests/economy_rows.py b/libs/policyengine-simulation-persistence/tests/economy_rows.py index 0b90d3a24..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,13 @@ 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. ``forced`` marks a forced re-run's run. + 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 @@ -206,11 +205,9 @@ 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, @@ -313,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_economy_reruns.py b/libs/policyengine-simulation-persistence/tests/test_economy_reruns.py index 73e3fbfc6..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, @@ -39,7 +38,6 @@ insert_simulation_run, ) from policyengine_simulation_persistence import ( - EconomyPopulation, EconomyRecordReferenceError, EconomyRequest, EconomyRunStore, @@ -53,8 +51,6 @@ ReportSideError, RerunRecordDeletedError, RerunSide, - ReusableRun, - RunReuse, SideDefinition, SimulationChoice, SimulationDefinition, @@ -62,8 +58,6 @@ SimulationType, UnknownDatasetError, UnknownRegionError, - find_reusable_run, - find_reusable_run_of, insert_report_rerun, insert_simulation_rerun, lock_reruns_of, @@ -100,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) @@ -254,24 +245,6 @@ def test_a_stored_economy_simulations_definition_is_read( ) -def _find_later_run_of( - connection: Connection, - simulation_id: UUID, - 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, @@ -281,7 +254,7 @@ def _used_on_later_catalog( """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 (reusing its run) with a reform + 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 @@ -306,57 +279,6 @@ def _used_on_later_catalog( 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, economy, 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, economy, 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) -> NewReportRerun: """Return an unforced re-run of ``stored`` on the later catalog's versions.""" return NewReportRerun( @@ -367,12 +289,10 @@ def _rerun_of(stored: StoredReport, later: EconomyCatalog) -> NewReportRerun: baseline=RerunSide( simulation_id=stored.baseline.simulation_id, simulation_run_id=uuid4(), - reused=False, ), reform=RerunSide( simulation_id=stored.reform.simulation_id, simulation_run_id=uuid4(), - reused=False, ), ) @@ -655,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, economy, 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, economy, 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( @@ -722,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" @@ -761,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, ) @@ -822,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: @@ -979,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, @@ -1005,12 +848,10 @@ def _forced_rerun_of(stored: StoredReport, economy: EconomyCatalog) -> NewReport baseline=RerunSide( simulation_id=stored.baseline.simulation_id, simulation_run_id=uuid4(), - reused=False, ), reform=RerunSide( simulation_id=stored.reform.simulation_id, simulation_run_id=uuid4(), - reused=False, ), forced=True, ) @@ -1050,29 +891,6 @@ def test_a_forced_report_rerun_is_an_extra_run_beside_any_run_on_its_versions( assert earlier_run["forced"] is False -@pytest.mark.parametrize("forced", [True, False]) -def test_a_report_rerun_names_no_reused_run(forced: bool) -> None: # noqa: FBT001 # the parameter - """Each side joins or creates its run; a forced one creates it (answer 3).""" - reused = RerunSide(simulation_id=uuid4(), simulation_run_id=uuid4(), reused=True) - created = RerunSide(simulation_id=uuid4(), simulation_run_id=uuid4(), reused=False) - - with pytest.raises(ValueError, match="reusing none"): - NewReportRerun( - report_id=uuid4(), - run_id=uuid4(), - population=EconomyPopulation( - tax_benefit_model_version_id=uuid4(), - region_id=uuid4(), - dataset_id=uuid4(), - year=2026, - ), - versions=VERSIONS, - baseline=reused, - reform=created, - forced=forced, - ) - - def test_a_report_rerun_losing_to_a_run_created_after_its_lookup_joins_it( committed_engine, committed_catalog ) -> None: 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 6049c1f5a..000000000 --- a/libs/policyengine-simulation-persistence/tests/test_economy_run_reuse.py +++ /dev/null @@ -1,329 +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, - find_reusable_run_of, -) -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_forced_run_is_never_reused(public_api_database_url) -> None: - """Answer 3: a forced re-run's run is never named by another report run.""" - with rolled_back_transaction(public_api_database_url) as connection: - economy = insert_economy_catalog(connection) - forced = insert_reusable_run(connection, economy, RunShape(forced=True)) - act_as_the_service(connection) - - by_definition = _find(connection, economy) - by_own_simulation = find_reusable_run_of( - connection, - simulation_id=forced.simulation_id, - population=economy.population(), - versions=VERSIONS, - inputs=OPTIONS, - output_uri_prefix=OUTPUT_BUCKET_PREFIX, - ) - - assert by_definition is None - assert by_own_simulation 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 3c0156ebb..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, @@ -74,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: @@ -101,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 @@ -134,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( @@ -175,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( @@ -209,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) @@ -265,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 ) @@ -308,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") @@ -345,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())) @@ -372,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 @@ -422,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 @@ -452,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(), @@ -467,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 @@ -511,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: @@ -544,7 +462,5 @@ def refuse(*_, refusal=refusal): 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 2cb13f189..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,18 +22,16 @@ 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, @@ -43,24 +40,22 @@ FoundBudgetWindow, KeyedBudgetWindow, KeyedWindowYear, - NewBudgetWindowReport, NewWindowRerun, ProposedSide, ReportRunStatus, - ReportSimulation, + ReportRunTrigger, RerunRecordDeletedError, RerunSide, - ReusableRun, - RunReuse, SimulationStatus, WindowRerunYear, WindowYearDefinition, + budget_window_runs, find_or_create_budget_window, - insert_budget_window_report, 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 @@ -77,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) @@ -88,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( @@ -106,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 ( @@ -167,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: @@ -207,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 @@ -262,7 +294,6 @@ def test_a_definitions_years_come_from_the_newest_window_run( baseline=RerunSide( simulation_id=other_2027.baseline.simulation_id, simulation_run_id=uuid4(), - reused=False, ), ) act_as_the_service(connection) @@ -414,12 +445,10 @@ def _rerun_of_keyed( baseline=RerunSide( simulation_id=year.baseline.simulation_id, simulation_run_id=uuid4(), - reused=False, ), reform=RerunSide( simulation_id=year.reform.simulation_id, simulation_run_id=uuid4(), - reused=False, ), ) for year in found.years @@ -479,72 +508,25 @@ def test_an_unforced_window_rerun_after_a_failed_run_names_its_years_runs( assert again.baseline.run_inserted is False -def test_a_window_reruns_inputs_name_each_years_own_reusable_runs( +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 = _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) - ) + _stored_window(connection, economy) act_as_the_service(connection) - years = _definition_years(stored) 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, + LATER_REQUEST, baseline=CURRENT_LAW, reform=CURRENT_LAW ) - 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)) - - -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, - ) - 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: @@ -566,45 +548,13 @@ def test_a_window_rerun_is_created_through_the_store(public_api_database_url) -> assert joined.window_run.id == rerun.window_run_id -def test_a_window_rerun_names_no_reused_side() -> None: - """Each year's sides join or create their runs, as a report re-run's do.""" - reused = RerunSide(simulation_id=uuid4(), simulation_run_id=uuid4(), reused=True) - created = RerunSide(simulation_id=uuid4(), simulation_run_id=uuid4(), reused=False) - - with pytest.raises(ValueError, match="reusing none"): - NewWindowRerun( - report_id=uuid4(), - window_run_id=uuid4(), - population=EconomyPopulation( - tax_benefit_model_version_id=uuid4(), - region_id=uuid4(), - dataset_id=uuid4(), - year=WINDOW_YEARS[0], - ), - versions=VERSIONS, - recalculate=False, - years=( - WindowRerunYear( - year=WINDOW_YEARS[0], - report_run_id=uuid4(), - baseline=reused, - reform=created, - ), - ), - ) - - def test_a_window_rerun_refuses_years_that_are_not_its_window() -> None: """Its years run one at a time from its first year, at most 75 of them.""" 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(), @@ -662,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(): 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 03548be41..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,13 +17,12 @@ 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, RerunRecordDeletedError, @@ -32,7 +31,6 @@ SimulationChoice, SimulationStatus, fail_unstarted_report_run, - insert_household_report, read_report_definition, ) from public_api_rows import ( @@ -48,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 @@ -108,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, @@ -153,7 +134,7 @@ def _stored_report( return report -def _succeed_first_runs(connection: Connection, report: NewHouseholdReport) -> None: +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]), @@ -169,7 +150,7 @@ def _succeed_first_runs(connection: Connection, report: NewHouseholdReport) -> N 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. 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 index ebe33047b..5aedea5ca 100644 --- a/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py @@ -602,8 +602,8 @@ def test_a_keyed_reports_rerun_joins_each_sides_run_on_its_versions( run_id=uuid4(), population=economy.population(), versions=VERSIONS, - baseline=RerunSide(created.baseline.simulation_id, uuid4(), reused=False), - reform=RerunSide(created.reform.simulation_id, uuid4(), reused=False), + baseline=RerunSide(created.baseline.simulation_id, uuid4()), + reform=RerunSide(created.reform.simulation_id, uuid4()), ) found = insert_report_rerun(connection, rerun) @@ -635,8 +635,8 @@ def test_a_keyed_rerun_with_one_simulation_on_both_sides_inserts_one_run( run_id=uuid4(), population=economy.population(), versions=VERSIONS, - baseline=RerunSide(simulation_id, uuid4(), reused=False), - reform=RerunSide(simulation_id, uuid4(), reused=False), + baseline=RerunSide(simulation_id, uuid4()), + reform=RerunSide(simulation_id, uuid4()), ) found = insert_report_rerun(connection, rerun) diff --git a/projects/policyengine-simulation-entry/DEPLOYMENT.md b/projects/policyengine-simulation-entry/DEPLOYMENT.md index 2a759270f..fa001a6cc 100644 --- a/projects/policyengine-simulation-entry/DEPLOYMENT.md +++ b/projects/policyengine-simulation-entry/DEPLOYMENT.md @@ -119,17 +119,12 @@ 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. The -deploy also sets `V2_SIMULATION_OUTPUT_BUCKET`, the `beta` or `prod` variable -of that name: the bucket that keeps v2 simulation output files for good. A -missing or invalid bucket name stops the deploy. The service reads it into -its settings but uses it for nothing: a report joins its sides' simulation -runs by version set (C1 · 24's answers 4 and 5), not by their files. The -setting and its deploy check are removed with the run-reuse search, in a -later change. The service never reads the bucket itself, so it needs no -storage permission. -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 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 7f1e43a68..ba75fa1d8 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/app.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/app.py @@ -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_submissions.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/budget_window_submissions.py index 77b639ce6..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 @@ -68,13 +68,13 @@ ) if TYPE_CHECKING: - from collections.abc import Callable, Sequence + from collections.abc import Callable from policyengine_simulation_persistence import ( BudgetWindowInputs, EconomyRequest, FoundBudgetWindow, - RunReuse, + FoundWindowYear, WindowYearRuns, ) from policyengine_stage12_persistence import ( @@ -107,10 +107,8 @@ 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 find_or_create_budget_window( @@ -188,8 +186,6 @@ async def submit_budget_window( economy_request, baseline=simulation_choice(request.baseline), reform=simulation_choice(request.reform), - reuse=None, - years=request.years, ), request=economy_request, ) @@ -435,7 +431,7 @@ def year_run_ids(window_year: WindowYearRuns) -> ReportRunIds: ) -def year_created(window_year: WindowYearRuns) -> BudgetWindowYearCreated: +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. 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 58814e7db..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,11 +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. The service - # uses it for nothing: a report joins its sides' simulation runs by - # version set, not by their files; it goes with the run-reuse search. - # Empty outside deployed environments. - v2_simulation_output_bucket: str = "" @classmethod def from_env(cls) -> Settings: @@ -162,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_reruns.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_reruns.py index fc2cec1ad..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 @@ -98,7 +98,7 @@ ) if TYPE_CHECKING: - from collections.abc import Callable, Sequence + from collections.abc import Callable from uuid import UUID from policyengine_simulation_persistence import ( @@ -108,7 +108,6 @@ FoundReportRun, FoundSimulationRun, ReportDefinition, - RunReuse, SideDefinition, SimulationChoice, SimulationDefinition, @@ -164,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( @@ -175,10 +173,8 @@ 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) -> FoundBudgetWindow: @@ -294,8 +290,6 @@ async def rerun_report( economy_request, baseline=stored.baseline, reform=stored.reform, - # A re-run reuses no run: its sides join or are forced. - reuse=None, ), request=economy_request, source=STORED_REPORT, @@ -463,8 +457,6 @@ async def _rerun_window( window.economy_request, baseline=stored.baseline.choice, reform=stored.reform.choice, - years=window.years, - reuse=None, ), request=window.economy_request, source=STORED_REPORT, @@ -544,7 +536,6 @@ def _new_side(self, simulation_id: UUID) -> RerunSide: return RerunSide( simulation_id=simulation_id, simulation_run_id=self._new_id(), - reused=False, ) async def _create_rerun[Created]( 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 aabdc079b..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 @@ -108,7 +108,6 @@ EconomySimulationState, FoundEconomyReport, FoundEconomySimulation, - RunReuse, ) from policyengine_simulation_entry.economy_api_models import ( @@ -141,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( @@ -202,17 +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. The service keeps it here and uses - it for nothing: a report joins its sides' runs by version set - (C1 · 24's answers 4 and 5), not by their files; the setting goes with - the reuse search. + ``environment`` labels the calls' artifacts, and ``modal_environment`` + holds the v2 workers. """ environment: str modal_environment: str - output_bucket: str | None = None def _database_unavailable() -> EconomySubmissionUnavailableError: @@ -281,7 +274,6 @@ async def submit_report( economy_request, baseline=simulation_choice(request.baseline), reform=simulation_choice(request.reform), - reuse=None, ), request=economy_request, ) diff --git a/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py b/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py index 966393973..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, @@ -44,8 +43,6 @@ 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, ) @@ -54,7 +51,6 @@ NewReportRerun, NewSimulationRerun, NewWindowRerun, - RunReuse, ) REPORT_ID = UUID("00000000-0000-4000-8000-0000000000a1") @@ -127,8 +123,8 @@ 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. A simulation @@ -176,26 +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 if reform.choice.policy_id or reform.choice.dynamic_id else {}, - reusable_run=None if reuse is None else reform_reusable, ), ) @@ -213,22 +202,14 @@ 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) -> FoundBudgetWindow: @@ -304,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: @@ -322,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 40bc933a0..7978f2b7c 100644 --- a/projects/policyengine-simulation-entry/tests/economy_service_fakes.py +++ b/projects/policyengine-simulation-entry/tests/economy_service_fakes.py @@ -40,7 +40,6 @@ FoundSide, FoundSimulationRun, ReportRunStatus, - ReusableRun, SimulationInputs, SimulationStatus, ) @@ -52,7 +51,6 @@ EconomyRequest, KeyedEconomyReport, KeyedEconomySimulation, - RunReuse, SimulationChoice, ) @@ -62,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( @@ -174,7 +173,6 @@ class FakeStore: """ 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 @@ -197,22 +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 if reform.policy_id or reform.dynamic_id else {}, - reusable_run=reform_reusable, ), ) @@ -369,7 +362,6 @@ def service( *, workers: FakeWorkers | None = None, caller: FakeCaller | None = None, - output_bucket: str | None = OUTPUT_BUCKET, ) -> EconomySubmissionService: return EconomySubmissionService( store=store, @@ -378,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/test_budget_window_submissions.py b/projects/policyengine-simulation-entry/tests/test_budget_window_submissions.py index ef2cca099..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, @@ -53,7 +52,6 @@ FoundWindowRun, FoundWindowYear, ReportRunStatus, - ReusableRun, SimulationInputs, ) from policyengine_stage12_persistence import ( @@ -67,10 +65,8 @@ 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 @@ -83,26 +79,20 @@ class FakeWindowStore(FakeStore): names instead of its own. """ - reusable_by_year: dict[int, tuple[ReusableRun | None, ReusableRun | None]] = field( - default_factory=dict - ) 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 find_or_create_budget_window(self, window) -> FoundBudgetWindow: @@ -205,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(), @@ -231,14 +220,12 @@ 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))) - # Answer 8: found or created by key; no run is searched for to reuse. - assert reuse is None + assert request.year == 2026 (report,) = store.windows assert report.definition == EconomyReportDefinition( country="us", @@ -313,9 +300,7 @@ def test_each_later_year_is_derived_from_the_first() -> 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"): REUSED_IN_2027.simulation_run_id} - ) + store = FakeWindowStore(joined_year_runs={(2027, "baseline"): JOINED_RUN_IN_2027}) caller = FakeCaller() advancer = FakeAdvancer(store) @@ -324,13 +309,9 @@ def test_a_year_names_its_own_years_run_another_report_created() -> None: ) assert [year.baseline_reused for year in created.years] == [False, True, False] - assert created.years[1].baseline_simulation_run_id == ( - REUSED_IN_2027.simulation_run_id - ) + 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 == ( - REUSED_IN_2027.simulation_run_id - ) + 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: 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 0686a8ef7..000000000 --- a/projects/policyengine-simulation-entry/tests/test_economy_deployment.py +++ /dev/null @@ -1,85 +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``) -and refuses a missing or invalid one. The service reads it into its -settings and uses it for nothing, since a report joins its sides' -simulation runs by version set; it 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_reruns.py b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py index 8e10cb48f..0eb96f1da 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py @@ -57,7 +57,6 @@ ReportSideError, RerunRecordDeletedError, RerunSide, - ReusableRun, RunVersions, SharedRowNotSettledError, SimulationStatus, @@ -71,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): @@ -104,12 +95,12 @@ 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(reusable=(REUSED_BASELINE, None)) + 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, @@ -117,7 +108,6 @@ def test_a_report_with_no_keys_is_rerun_as_forced_runs_on_the_current_versions() ) assert (request.region_code, request.dataset_name) == ("us", "populace_us_2024") assert (baseline, reform) == (STORED_REPORT.baseline, STORED_REPORT.reform) - assert reuse is None # Extra runs, marked forced, which nothing joins and no index refuses. assert store.report_reruns == [ NewReportRerun( @@ -128,12 +118,10 @@ def test_a_report_with_no_keys_is_rerun_as_forced_runs_on_the_current_versions() baseline=RerunSide( simulation_id=BASELINE_SIMULATION_ID, simulation_run_id=UUID(int=2), - reused=False, ), reform=RerunSide( simulation_id=REFORM_SIMULATION_ID, simulation_run_id=UUID(int=3), - reused=False, ), forced=True, ) @@ -168,15 +156,13 @@ def test_a_report_with_no_keys_is_rerun_as_forced_runs_on_the_current_versions() 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 # An extra run, marked forced, which nothing joins (answer 3). assert created.forced is True - assert (created.baseline.reused, created.reform.reused) == (False, False) 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) @@ -235,10 +221,8 @@ def test_a_keyed_reports_rerun_has_each_side_join_its_run_on_the_versions() -> N rerun = _rerun_report(rerun_service(store, caller=caller)) - assert store.rerun_reads[0][1][2] is None (created,) = store.report_reruns assert created.forced is False - assert (created.baseline.reused, created.reform.reused) == (False, 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 @@ -359,7 +343,7 @@ def test_a_report_missing_a_row_it_calculates_on_is_not_rerun(missing, named) -> 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( @@ -664,23 +648,19 @@ 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(): """Interim answer B: a window has no keys yet, so every year is recalculated.""" - store = FakeRerunStore( - report_definition=STORED_WINDOW, reusable_by_year={2027: (REUSED_2027, None)} - ) + 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 is None (window,) = store.windows assert (window.report_id, window.window_run_id, window.recalculate) == ( REPORT_ID, @@ -693,7 +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 - assert not any(window_year.baseline.reused for window_year in window.years) assert advancer.advances == [window.window_run_id] assert len(caller.report_runs) == 3 for (year_to_start, _), (_, payload, context, observed) in zip( @@ -718,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, @@ -729,19 +708,15 @@ 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) 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 e7c5804ef..47b9f3137 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_submissions.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_submissions.py @@ -106,7 +106,7 @@ def test_a_report_is_created_by_key_and_its_coordinator_started() -> None: 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, @@ -115,8 +115,6 @@ def test_a_report_is_created_by_key_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) - # Runs are found by key, not searched for (C1 · 24). - assert reuse is None (report,) = store.reports spm = {"geography_kind": "national"} assert report.definition == EconomyReportDefinition( From 81ee633e0165f3fc2897d2f069133499a7c0174f Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Tue, 17 Nov 2026 02:20:43 +0400 Subject: [PATCH 107/107] Test that the keyed creators name a refused reference's column, and correct the Stage 12 creation passages Review round 1: the tests deleted with the create functions without keys were the only database tests that a refused region, dataset, dynamic, policy or household reference names its column, which the Simulation Entrypoint turns into its unknown_* refusals. The same checks now call find_or_create_economy_report, find_or_create_household_report and find_or_create_budget_window, and pass, as the behaviour is unchanged. The Stage 12 migration doc's standalone-simulation and budget-window passages now say the service finds or creates the rows by key and starts a call only for a run it created. Refs #1081 Co-Authored-By: Claude Opus 5.5 --- .../stage-12-modal-worker-foundation.md | 20 ++++++---- .../tests/test_keyed_economy_records.py | 39 +++++++++++++++++++ .../tests/test_keyed_household_records.py | 18 +++++++++ .../tests/test_keyed_window_records.py | 26 +++++++++++++ 4 files changed, 96 insertions(+), 7 deletions(-) diff --git a/docs/migration/stage-12-modal-worker-foundation.md b/docs/migration/stage-12-modal-worker-foundation.md index 827667c23..4c08b260f 100644 --- a/docs/migration/stage-12-modal-worker-foundation.md +++ b/docs/migration/stage-12-modal-worker-foundation.md @@ -293,8 +293,10 @@ 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`). It then starts the manifest's `report_coordinator_callable` -(`coordinate_report`) with two arguments and no evaluation record: +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 @@ -323,8 +325,10 @@ the report run with its result rows. 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 @@ -395,9 +399,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 diff --git a/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py b/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py index 5aedea5ca..592b06423 100644 --- a/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_economy_records.py @@ -32,6 +32,7 @@ ) from policyengine_simulation_persistence import ( KEY_VERSION, + EconomyRecordReferenceError, EconomyReportDefinition, EconomyRunStore, EconomySimulationDefinition, @@ -653,3 +654,41 @@ def test_a_keyed_rerun_with_one_simulation_on_both_sides_inserts_one_run( == 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 index f277830ed..120d20a70 100644 --- a/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_household_records.py @@ -18,6 +18,7 @@ from conftest import act_as_the_service, rolled_back_transaction from policyengine_simulation_persistence import ( KEY_VERSION, + EconomyRecordReferenceError, FoundHouseholdReport, FoundSide, HouseholdReportDefinition, @@ -508,3 +509,20 @@ def test_a_forced_keyed_household_rerun_is_an_extra_run_beside_the_one_under_way 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 index 9d3ce4fed..746f4355b 100644 --- a/libs/policyengine-simulation-persistence/tests/test_keyed_window_records.py +++ b/libs/policyengine-simulation-persistence/tests/test_keyed_window_records.py @@ -32,6 +32,7 @@ from policyengine_simulation_persistence import ( KEY_VERSION, EconomyPopulation, + EconomyRecordReferenceError, EconomyReportDefinition, EconomyRunStore, FoundBudgetWindow, @@ -451,3 +452,28 @@ def second_request() -> None: 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