From 1232cb68d99ff23e603e0caec35dcf4ea008ff97 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Thu, 19 Nov 2026 01:58:38 +0400 Subject: [PATCH 01/11] Test each run's cliff calculation through ORM sessions (failing) A request asking for cliffs finds or inserts one CliffImpact per simulation run its report run names, in the report run's own transaction: pending once, then joined; a failed row never joined; a succeeded row is the run's result; two transactions at once insert one. A calculation the database refuses leaves no report. The store records a calculation's Modal call, or fails it, while it is pending with none. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_cliff_calculations.py | 567 ++++++++++++++++++ 1 file changed, 567 insertions(+) create mode 100644 libs/policyengine-simulation-persistence/tests/test_cliff_calculations.py diff --git a/libs/policyengine-simulation-persistence/tests/test_cliff_calculations.py b/libs/policyengine-simulation-persistence/tests/test_cliff_calculations.py new file mode 100644 index 000000000..eee61289f --- /dev/null +++ b/libs/policyengine-simulation-persistence/tests/test_cliff_calculations.py @@ -0,0 +1,567 @@ +"""Find a simulation run's cliff calculation, or insert it, and start or fail it. + +A request asking for cliffs (``include_cliffs``) gets one cliff calculation +per simulation run it names that has none that hasn't failed (C1 · 24's +answer 4b, the ``cliff_impacts`` design). These run against a database the +Public API's own v2 migration chain built, as the simulation service's role. +Most run in a transaction rolled back afterwards; the test of two +transactions commits its rows under a catalog of a country no other test +uses, and deletes them afterwards. +""" + +from __future__ import annotations + +import threading +from typing import TYPE_CHECKING, Any +from uuid import UUID, uuid4 + +import pytest +from committed_rows import ( + LOCK_WAIT_TIMEOUT_SECONDS, + run_together, + wait_until_another_backend_waits_for, +) +from conftest import ( + act_as_the_service, + economy_store_on, + in_session, + rolled_back_transaction, +) +from economy_rows import ( + CURRENT_LAW, + VERSIONS, + EconomyCatalog, + insert_economy_catalog, + insert_simulation_run, +) +from policyengine_simulation_persistence import ( + CliffImpact, + EconomyReportDefinition, + EconomyRunStore, + KeyedEconomyReport, + NewReportRerun, + ProposedCliffs, + ProposedSide, + Report, + RerunSide, + SimulationChoice, + SimulationStatus, + find_or_create_economy_report, + find_or_insert_cliff_calculations, +) +from public_api_rows import insert_policy +from sqlalchemy import func, select, text, update +from sqlalchemy.exc import IntegrityError + +if TYPE_CHECKING: + from policyengine_simulation_persistence import FoundEconomyReport + from sqlalchemy import Connection + +pytestmark = pytest.mark.public_api_schema + + +def _keyed_report( + economy: EconomyCatalog, + *, + reform: SimulationChoice = CURRENT_LAW, + cliffs: ProposedCliffs | None = None, +) -> KeyedEconomyReport: + """Return a request's report on ``economy``, with fresh IDs to propose.""" + return KeyedEconomyReport( + 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=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(), + versions=VERSIONS, + inputs={}, + cliffs=cliffs, + ) + + +def _new_cliffs() -> ProposedCliffs: + return ProposedCliffs(baseline_id=uuid4(), reform_id=uuid4()) + + +def _calculations_of(connection: Connection, *simulation_run_ids: UUID) -> int: + return connection.execute( + select(func.count()).where( + CliffImpact.simulation_run_id.in_(simulation_run_ids) + ) + ).scalar_one() + + +def _seed_simulation_run(connection: Connection) -> UUID: + """Insert a catalog, a simulation and its pending run; return the run's ID.""" + economy = insert_economy_catalog(connection) + return insert_simulation_run(connection, economy.population()).simulation_run_id + + +def _finish_as_the_worker( + connection: Connection, cliff_result_id: UUID, values: dict[str, Any] +) -> None: + """End a cliff calculation as the worker or the sweep would, as the superuser.""" + connection.execute(text("RESET ROLE")) + connection.execute( + update(CliffImpact) + .where(CliffImpact.id == cliff_result_id) + .values(completed_at=text("now()"), **values) + ) + act_as_the_service(connection) + + +def _cliff_row(connection: Connection, cliff_result_id: UUID) -> Any: + return connection.execute( + select( + CliffImpact.status, + CliffImpact.modal_call_id, + CliffImpact.error_message, + CliffImpact.completed_at, + ).where(CliffImpact.id == cliff_result_id) + ).one() + + +def test_a_runs_cliff_calculation_is_inserted_pending_once_and_then_joined( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + run_id = _seed_simulation_run(connection) + act_as_the_service(connection) + proposed_id = uuid4() + + (first,) = in_session( + connection, find_or_insert_cliff_calculations, {run_id: proposed_id} + ).values() + (again,) = in_session( + connection, find_or_insert_cliff_calculations, {run_id: uuid4()} + ).values() + + assert (first.id, first.inserted, first.status) == ( + proposed_id, + True, + SimulationStatus.PENDING, + ) + assert first.simulation_run_id == again.simulation_run_id == run_id + assert (again.id, again.inserted, again.status) == ( + proposed_id, + False, + SimulationStatus.PENDING, + ) + assert _cliff_row(connection, proposed_id).modal_call_id is None + + +def test_each_run_named_gets_its_own_cliff_calculation( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + baseline_run_id = insert_simulation_run( + connection, economy.population() + ).simulation_run_id + reform_run_id = insert_simulation_run( + connection, economy.population() + ).simulation_run_id + act_as_the_service(connection) + proposed = {baseline_run_id: uuid4(), reform_run_id: uuid4()} + + found = in_session(connection, find_or_insert_cliff_calculations, proposed) + + assert {run_id: (each.id, each.inserted) for run_id, each in found.items()} == { + run_id: (proposed_id, True) for run_id, proposed_id in proposed.items() + } + + +def test_a_failed_cliff_calculation_is_never_joined(public_api_database_url) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + run_id = _seed_simulation_run(connection) + act_as_the_service(connection) + failed_id = uuid4() + in_session(connection, find_or_insert_cliff_calculations, {run_id: failed_id}) + _finish_as_the_worker( + connection, + failed_id, + {"status": "failed", "error_message": "cliff_calculation_failed: x"}, + ) + + (after_failure,) = in_session( + connection, find_or_insert_cliff_calculations, {run_id: uuid4()} + ).values() + + assert after_failure.inserted is True + assert after_failure.id != failed_id + assert after_failure.status is SimulationStatus.PENDING + + +def test_a_succeeded_cliff_calculation_is_the_runs_result_and_is_joined( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + run_id = _seed_simulation_run(connection) + act_as_the_service(connection) + result_id = uuid4() + in_session(connection, find_or_insert_cliff_calculations, {run_id: result_id}) + _finish_as_the_worker( + connection, + result_id, + {"status": "succeeded", "cliff_gap": 1.5e9, "cliff_share": 0.04}, + ) + + (found,) = in_session( + connection, find_or_insert_cliff_calculations, {run_id: uuid4()} + ).values() + + assert (found.id, found.inserted, found.status) == ( + result_id, + False, + SimulationStatus.SUCCEEDED, + ) + + +def test_two_requests_at_once_insert_one_cliff_calculation( + committed_engine, committed_catalog +) -> None: + with committed_engine.begin() as connection: + run_id = insert_simulation_run( + connection, committed_catalog.population() + ).simulation_run_id + 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"] = in_session( + connection, find_or_insert_cliff_calculations, {run_id: uuid4()} + )[run_id] + holder_pid = connection.execute( + text("SELECT pg_backend_pid()") + ).scalar_one() + first_has_inserted.set() + wait_until_another_backend_waits_for(committed_engine, holder_pid) + + def insert_once_the_first_has() -> None: + assert first_has_inserted.wait(LOCK_WAIT_TIMEOUT_SECONDS) + with committed_engine.begin() as connection: + act_as_the_service(connection) + found["second"] = in_session( + connection, find_or_insert_cliff_calculations, {run_id: uuid4()} + )[run_id] + + run_together( + (insert_then_commit_once_the_other_waits, insert_once_the_first_has), + released=first_has_inserted, + ) + + assert found["first"].inserted is True + assert (found["second"].id, found["second"].inserted) == (found["first"].id, False) + with committed_engine.begin() as connection: + rows = connection.execute( + select(CliffImpact.id).where(CliffImpact.simulation_run_id == run_id) + ).all() + assert [row.id for row in rows] == [found["first"].id] + + +def test_a_report_created_asking_for_cliffs_inserts_its_runs_calculations_with_it( + public_api_database_url, +) -> None: + """In the report's own transaction, so a failure writes neither (round 1).""" + 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) + store = economy_store_on(connection) + reform = SimulationChoice(policy_id, None) + proposed = _new_cliffs() + + created = store.find_or_create_report( + _keyed_report(economy, reform=reform, cliffs=proposed) + ) + joined = store.find_or_create_report( + _keyed_report(economy, reform=reform, cliffs=_new_cliffs()) + ) + + assert created.cliffs is not None + assert (created.cliffs.baseline.id, created.cliffs.baseline.inserted) == ( + proposed.baseline_id, + True, + ) + assert (created.cliffs.reform.id, created.cliffs.reform.inserted) == ( + proposed.reform_id, + True, + ) + assert created.cliffs.reform.status is SimulationStatus.PENDING + # An identical request joins the report run and its runs' calculations. + assert joined.run.inserted is False + assert joined.cliffs is not None + assert (joined.cliffs.baseline.id, joined.cliffs.baseline.inserted) == ( + proposed.baseline_id, + False, + ) + assert joined.cliffs.reform.id == proposed.reform_id + + +def test_two_identical_creates_asking_for_cliffs_at_once_insert_one_each( + committed_engine, committed_catalog +) -> None: + """Review round 2: the second loses the report run and joins its calculations. + + The first holds its transaction open until the second waits on its rows. + """ + economy = committed_catalog + first_has_inserted = threading.Event() + found: dict[str, FoundEconomyReport] = {} + + def create(connection: Connection, name: str) -> None: + act_as_the_service(connection) + found[name] = in_session( + connection, + find_or_create_economy_report, + _keyed_report(economy, cliffs=_new_cliffs()), + ) + + def first_request() -> None: + with committed_engine.begin() as connection: + create(connection, "first") + holder_pid = connection.execute( + text("SELECT pg_backend_pid()") + ).scalar_one() + first_has_inserted.set() + wait_until_another_backend_waits_for(committed_engine, holder_pid) + + def second_request() -> None: + assert first_has_inserted.wait(LOCK_WAIT_TIMEOUT_SECONDS) + with committed_engine.begin() as connection: + create(connection, "second") + + run_together((first_request, second_request), released=first_has_inserted) + + first, second = found["first"].cliffs, found["second"].cliffs + assert first is not None + assert second is not None + assert (first.baseline.inserted, second.baseline.inserted) == (True, False) + assert second.baseline.id == first.baseline.id + assert second.reform.id == first.reform.id + with committed_engine.begin() as connection: + calculations = _calculations_of(connection, first.baseline.simulation_run_id) + assert calculations == 1 + + +def test_a_report_not_asking_for_cliffs_inserts_no_calculation( + 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) + + created = economy_store_on(connection).find_or_create_report( + _keyed_report(economy) + ) + + assert created.cliffs is None + assert _calculations_of(connection, created.baseline.simulation_run_id) == 0 + + +def test_one_run_on_both_sides_gets_one_calculation(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) + proposed = _new_cliffs() + + created = economy_store_on(connection).find_or_create_report( + _keyed_report(economy, cliffs=proposed) + ) + + assert created.cliffs is not None + assert created.cliffs.baseline == created.cliffs.reform + assert created.cliffs.baseline.id == proposed.baseline_id + assert _calculations_of(connection, created.baseline.simulation_run_id) == 1 + + +def test_a_report_whose_calculations_cannot_be_inserted_writes_nothing( + public_api_database_url, +) -> None: + """Review round 1: the database refusing a calculation refuses the report.""" + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + other_run_id = insert_simulation_run( + connection, economy.population() + ).simulation_run_id + act_as_the_service(connection) + taken_id = uuid4() + in_session( + connection, find_or_insert_cliff_calculations, {other_run_id: taken_id} + ) + report = _keyed_report( + economy, cliffs=ProposedCliffs(baseline_id=taken_id, reform_id=uuid4()) + ) + + with pytest.raises(IntegrityError): + economy_store_on(connection).find_or_create_report(report) + + written = connection.execute( + select(func.count()).where( + Report.definition_key == report.definition.definition_key + ) + ).scalar_one() + assert written == 0 + + +def _stored_report_with_a_failed_run( + connection: Connection, economy: EconomyCatalog, store: EconomyRunStore +) -> FoundEconomyReport: + """Create a keyed report and fail its run, so a re-run creates a new one.""" + created = store.find_or_create_report(_keyed_report(economy)) + connection.execute(text("RESET ROLE")) + connection.execute( + text( + "UPDATE public.report_runs SET status = 'failed', completed_at = now() " + "WHERE id = :id" + ), + {"id": created.run.id}, + ) + act_as_the_service(connection) + return created + + +def _rerun_of( + economy: EconomyCatalog, + created: FoundEconomyReport, + *, + forced: bool = False, + cliffs: ProposedCliffs | None = None, +) -> NewReportRerun: + return NewReportRerun( + report_id=created.report_id, + run_id=uuid4(), + population=economy.population(), + versions=VERSIONS, + baseline=RerunSide(created.baseline.simulation_id, uuid4()), + reform=RerunSide(created.reform.simulation_id, uuid4()), + forced=forced, + cliffs=cliffs, + ) + + +def test_a_rerun_asking_for_cliffs_adds_its_runs_calculations_joined_or_created( + public_api_database_url, +) -> None: + """Answer 4b: a re-run on the current versions joins and adds its cliffs.""" + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + act_as_the_service(connection) + store = economy_store_on(connection) + created = _stored_report_with_a_failed_run(connection, economy, store) + proposed = _new_cliffs() + + rerun = store.create_report_rerun(_rerun_of(economy, created, cliffs=proposed)) + joined = store.create_report_rerun( + _rerun_of(economy, created, cliffs=_new_cliffs()) + ) + + assert rerun.inserted is True + assert rerun.cliffs is not None + assert (rerun.cliffs.baseline.id, rerun.cliffs.baseline.inserted) == ( + proposed.baseline_id, + True, + ) + assert (joined.id, joined.inserted) == (rerun.id, False) + assert joined.cliffs is not None + assert (joined.cliffs.baseline.id, joined.cliffs.baseline.inserted) == ( + proposed.baseline_id, + False, + ) + + +def test_a_forced_rerun_asking_for_cliffs_adds_its_new_runs_calculations( + 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 = economy_store_on(connection) + created = _stored_report_with_a_failed_run(connection, economy, store) + forced = _rerun_of(economy, created, forced=True, cliffs=_new_cliffs()) + + rerun = store.create_report_rerun(forced) + unasked = store.create_report_rerun(_rerun_of(economy, created, forced=True)) + + assert rerun.cliffs is not None + assert rerun.cliffs.baseline.inserted is True + assert _calculations_of(connection, forced.baseline.simulation_run_id) == 1 + assert unasked.cliffs is None + assert ( + _calculations_of( + connection, + unasked.baseline_simulation_run_id, + unasked.reform_simulation_run_id, + ) + == 0 + ) + + +def test_a_cliff_calculations_call_is_recorded_while_it_is_pending_with_none( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + run_id = _seed_simulation_run(connection) + act_as_the_service(connection) + store = economy_store_on(connection) + cliff_result_id = uuid4() + in_session( + connection, find_or_insert_cliff_calculations, {run_id: cliff_result_id} + ) + + recorded = store.record_cliff_call(cliff_result_id, "fc-first") + again = store.record_cliff_call(cliff_result_id, "fc-second") + + assert recorded is SimulationStatus.PENDING + assert again is SimulationStatus.PENDING + assert _cliff_row(connection, cliff_result_id).modal_call_id == "fc-first" + assert store.record_cliff_call(uuid4(), "fc-none") is None + + +def test_a_cliff_calculation_whose_call_was_refused_is_failed_only_while_unstarted( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + refused_run_id = insert_simulation_run( + connection, economy.population() + ).simulation_run_id + started_run_id = insert_simulation_run( + connection, economy.population() + ).simulation_run_id + act_as_the_service(connection) + store = economy_store_on(connection) + refused_id, started_id = uuid4(), uuid4() + in_session( + connection, + find_or_insert_cliff_calculations, + {refused_run_id: refused_id, started_run_id: started_id}, + ) + store.record_cliff_call(started_id, "fc-started") + + failed = store.fail_unstarted_cliff_calculation( + refused_id, "modal_call_refused: Modal did not accept the call." + ) + left = store.fail_unstarted_cliff_calculation( + started_id, "modal_call_refused: Modal did not accept the call." + ) + + assert (failed, left) == (True, False) + refused_row = _cliff_row(connection, refused_id) + assert refused_row.status == SimulationStatus.FAILED + assert refused_row.error_message.startswith("modal_call_refused: ") + assert refused_row.completed_at is not None + assert _cliff_row(connection, started_id).status == SimulationStatus.PENDING From ad1442b968ea1339e12b7eee859c2a756e3f2b0d Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:00:37 +0400 Subject: [PATCH 02/11] Write each run's cliff calculation with its report run, on ORM sessions A create or re-run asking for cliffs proposes its sides' calculation IDs (ProposedCliffs). In the transaction that settled its report run, find_or_insert_report_run_cliffs finds or inserts the CliffImpact of each simulation run that report run names, against uq_cliff_impacts_unfailed, in simulation run ID order, so a calculation the database refuses leaves nothing written. The economy store records a calculation's Modal call, or fails it, while it is pending with none. Co-Authored-By: Claude Opus 5.5 --- .../__init__.py | 8 ++ .../economy_rerun_records.py | 28 ++++- .../economy_run_records.py | 26 ++++- .../economy_run_store.py | 24 ++++ .../keyed_economy_records.py | 64 ++++++++++- .../shared_rows.py | 106 +++++++++++++++++- 6 files changed, 246 insertions(+), 10 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 0c0ca9823..73af8b9fe 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py @@ -187,12 +187,16 @@ result_metadata, ) from policyengine_simulation_persistence.shared_rows import ( + FoundCliffCalculation, + FoundCliffs, FoundReportRun, FoundRow, FoundSimulationRun, FoundWindowRun, + ProposedCliffs, SharedRowNotSettledError, find_joinable_report_run, + find_or_insert_cliff_calculations, find_or_insert_report, find_or_insert_report_run, find_or_insert_simulation, @@ -251,6 +255,8 @@ "EconomySimulationInputs", "EconomySimulationState", "FoundBudgetWindow", + "FoundCliffCalculation", + "FoundCliffs", "FoundEconomyReport", "FoundEconomySimulation", "FoundHouseholdReport", @@ -297,6 +303,7 @@ "PolicyReform", "Poverty", "ProgramStatistics", + "ProposedCliffs", "ProposedSide", "RecordKind", "ReferencedBase", @@ -357,6 +364,7 @@ "find_or_create_economy_report", "find_or_create_economy_simulation", "find_or_create_household_report", + "find_or_insert_cliff_calculations", "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 7bb49df2e..3fa5f2f5b 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 @@ -38,6 +38,10 @@ indexes leave out, so it is created beside any run on the same versions, even one under way, and nothing ever joins it. +An economy report's re-run asking for cliffs also finds or inserts the cliff +calculation of each simulation run the report run it ended on names, in the +same transaction (``find_or_insert_report_run_cliffs``, answer 4b). + The service then starts and records the new run's call as it does a new record's (``economy_run_records``). """ @@ -64,6 +68,7 @@ insert_household_simulation_run, ) from policyengine_simulation_persistence.keyed_economy_records import ( + find_or_insert_report_run_cliffs, find_or_insert_report_run_on_sides, ) from policyengine_simulation_persistence.keyed_window_records import ( @@ -108,7 +113,10 @@ RunVersions, ) from policyengine_simulation_persistence.keyed_economy_records import Side - from policyengine_simulation_persistence.shared_rows import FoundSimulationRun + from policyengine_simulation_persistence.shared_rows import ( + FoundSimulationRun, + ProposedCliffs, + ) @dataclass(frozen=True) @@ -132,7 +140,8 @@ 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. + new run of each side, marked forced. ``cliffs``, set when the re-run + asks for cliffs, proposes its sides' cliff calculations' IDs. """ report_id: UUID @@ -142,6 +151,7 @@ class NewReportRerun: baseline: RerunSide reform: RerunSide forced: bool = False + cliffs: ProposedCliffs | None = None @property def new_simulation_run_ids(self) -> tuple[UUID, ...]: @@ -294,7 +304,9 @@ def insert_report_rerun(session: Session, rerun: NewReportRerun) -> FoundReportR 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. + call. A re-run asking for cliffs also finds or inserts the cliff + calculation of each simulation run that report run names, joined or + created, and returns them with it. Raise RerunRecordDeletedError when the database refuses the new run's key to the report, which no longer exists, and @@ -302,6 +314,16 @@ def insert_report_rerun(session: Session, rerun: NewReportRerun) -> FoundReportR name, such as a side's simulation; either refusal ends the caller's transaction, or its savepoint. """ + found = _insert_report_rerun_run(session, rerun) + if rerun.cliffs is None: + return found + return replace( + found, cliffs=find_or_insert_report_run_cliffs(session, found, rerun.cliffs) + ) + + +def _insert_report_rerun_run(session: Session, rerun: NewReportRerun) -> FoundReportRun: + """Join or create the re-run's report run, as ``insert_report_rerun`` says.""" versions = rerun.versions if not rerun.forced: lock_reruns_of(session, rerun.report_id) 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 719b9450a..c8bf1f6ec 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 @@ -53,6 +53,7 @@ ) from policyengine_simulation_persistence.tables import ( BudgetWindowRun, + CliffImpact, Report, ReportRun, ReportRunStatus, @@ -69,7 +70,7 @@ from sqlalchemy.orm import Session # The two classes whose runs a Modal call calculates. -type RunModel = type[SimulationRun | ReportRun] +type RunModel = type[SimulationRun | ReportRun | CliffImpact] # PostgreSQL's SQLSTATE for a row naming one that does not exist. FOREIGN_KEY_VIOLATION: Final = "23503" @@ -351,6 +352,18 @@ def record_simulation_run_call( return None if status is None else SimulationStatus(status) +def record_cliff_calculation_call( + session: Session, *, cliff_result_id: UUID, modal_call_id: str +) -> SimulationStatus | None: + """Record a cliff calculation's Modal call ID while it is pending with none. + + Return its status afterwards, or None when there is no such row. One + the worker has claimed already keeps its claim. + """ + status = _record_call(session, CliffImpact, cliff_result_id, modal_call_id) + return None if status is None else SimulationStatus(status) + + def _record_call( session: Session, model: RunModel, run_id: UUID, modal_call_id: str ) -> str | None: @@ -402,6 +415,17 @@ def fail_unstarted_simulation_run( return _fail_unstarted(session, SimulationRun, simulation_run_id, error_message) +def fail_unstarted_cliff_calculation( + session: Session, *, cliff_result_id: UUID, error_message: str +) -> bool: + """Fail a cliff calculation at once while it is pending with no Modal call ID. + + Return whether it was failed: one a call has been recorded for, or one + the worker has claimed, is left as it is. + """ + return _fail_unstarted(session, CliffImpact, cliff_result_id, error_message) + + def _fail_unstarted( session: Session, model: RunModel, run_id: UUID, error_message: str ) -> bool: 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 dec3009ab..6d680b2be 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 @@ -46,8 +46,10 @@ ) from policyengine_simulation_persistence.economy_run_records import ( SimulationChoice, + fail_unstarted_cliff_calculation, fail_unstarted_report_run, fail_unstarted_simulation_run, + record_cliff_calculation_call, record_report_run_call, record_simulation_run_call, ) @@ -352,6 +354,28 @@ def fail_unstarted_simulation( error_message=error_message, ) + def record_cliff_call( + self, cliff_result_id: UUID, modal_call_id: str + ) -> SimulationStatus | None: + """Record a cliff calculation's call ID while it is pending with none.""" + with self._transaction() as session: + return record_cliff_calculation_call( + session, + cliff_result_id=cliff_result_id, + modal_call_id=modal_call_id, + ) + + def fail_unstarted_cliff_calculation( + self, cliff_result_id: UUID, error_message: str + ) -> bool: + """Fail a cliff calculation while it is pending with no call ID.""" + with self._transaction() as session: + return fail_unstarted_cliff_calculation( + session, + cliff_result_id=cliff_result_id, + error_message=error_message, + ) + def read_report(self, report_id: UUID) -> EconomyReportState | None: """Return the report with its newest run, or None when there is none.""" with self._transaction() as session: 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 9e7b73741..9b04f5506 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 @@ -15,7 +15,11 @@ 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. + the savepoint takes back this request's simulation runs; +5. for a request asking for cliffs, the cliff calculation of each + simulation run the report run it ended on names, found or inserted + (``find_or_insert_report_run_cliffs``, which a re-run uses too), so they + are written with the report run or not at all. Every simulation run counts whatever report first calculated it, pending, running or succeeded: its stored plan no longer depends on the report @@ -28,7 +32,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 @@ -43,6 +47,7 @@ find_joinable_report_run, find_or_insert_report, find_or_insert_report_run, + find_or_insert_side_cliffs, find_or_insert_simulation, find_or_insert_simulation_run, find_or_insert_simulation_runs, @@ -66,6 +71,10 @@ EconomyPopulation, RunVersions, ) + from policyengine_simulation_persistence.shared_rows import ( + FoundCliffs, + ProposedCliffs, + ) # A report's two sides, the baseline first. type Side = Literal["baseline", "reform"] @@ -90,6 +99,8 @@ class KeyedEconomyReport: selection when the request gave one, and no other option (answer 4). No label, description, user or trigger is stored on the shared rows (answer 6): each user's saved report and report-run record hold them. + ``cliffs``, set when the request asks for cliffs, proposes its sides' + cliff calculations' IDs; it is never stored (answer 4b). """ definition: EconomyReportDefinition @@ -101,6 +112,7 @@ class KeyedEconomyReport: population: EconomyPopulation versions: RunVersions inputs: dict[str, Any] + cliffs: ProposedCliffs | None = None @dataclass(frozen=True) @@ -126,6 +138,8 @@ class FoundEconomyReport: run: FoundReportRun baseline: FoundSide reform: FoundSide + # Each side's run's cliff calculation, when the request asked for cliffs. + cliffs: FoundCliffs | None = None @dataclass(frozen=True) @@ -179,7 +193,11 @@ def find_or_create_economy_report( policyengine_version=versions.policyengine_version, ) if joined is not None: - return _found(report.id, report.inserted, joined, simulation_ids, set()) + return _with_cliffs( + session, + _found(report.id, report.inserted, joined, simulation_ids, set()), + request.cliffs, + ) proposed = {"baseline": request.baseline, "reform": request.reform} run, runs = find_or_insert_report_run_on_sides( session, @@ -195,7 +213,45 @@ def find_or_create_economy_report( }, ) inserted = {found.id for found in runs.values() if found.inserted} - return _found(report.id, report.inserted, run, simulation_ids, inserted) + return _with_cliffs( + session, + _found(report.id, report.inserted, run, simulation_ids, inserted), + request.cliffs, + ) + + +def _with_cliffs( + session: Session, found: FoundEconomyReport, cliffs: ProposedCliffs | None +) -> FoundEconomyReport: + """Return ``found`` with its sides' runs' cliff calculations, when asked.""" + if cliffs is None: + return found + return replace( + found, cliffs=find_or_insert_report_run_cliffs(session, found.run, cliffs) + ) + + +def find_or_insert_report_run_cliffs( + session: Session, run: FoundReportRun, proposed: ProposedCliffs +) -> FoundCliffs: + """Return the cliff calculation of each simulation run ``run`` names. + + A request asking for cliffs calls it, for a create or a re-run, in the + transaction that settled ``run``, joined or created, so the calculations + are written with it or not at all. Raise EconomyRecordReferenceError + when the database refuses a run a calculation names, and ValueError for + a report run with no reform run, which no economy report has. + """ + if run.reform_simulation_run_id is None: + msg = f"report run {run.id} of an economy report names no reform run" + raise ValueError(msg) + with references_checked(): + return find_or_insert_side_cliffs( + session, + proposed, + baseline_simulation_run_id=run.baseline_simulation_run_id, + reform_simulation_run_id=run.reform_simulation_run_id, + ) def find_or_create_economy_simulation( 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 83133a357..cbe19dab1 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 @@ -11,7 +11,9 @@ - a report run by report, country package version and .py version, the same way, outside budget windows, whose year runs no index covers; - a budget-window run by report, catalog version and .py version, among - window runs that haven't failed and aren't recalculations (answer 8). + window runs that haven't failed and aren't recalculations (answer 8); +- a simulation run's cliff calculation (``CliffImpact``) by its run, among + calculations that haven't failed (answer 4b). Under READ COMMITTED an insert that conflicts with another transaction's uncommitted row waits until that transaction ends. Once it commits, the @@ -39,6 +41,7 @@ from policyengine_simulation_persistence.tables import ( BudgetWindowRun, + CliffImpact, Report, ReportRun, ReportRunStatus, @@ -56,7 +59,7 @@ # The classes a lookup inserts into. type SharedRowModel = type[ - Simulation | Report | SimulationRun | ReportRun | BudgetWindowRun + Simulation | Report | SimulationRun | ReportRun | BudgetWindowRun | CliffImpact ] # How many times a lookup inserts before giving up on a row that keeps @@ -98,6 +101,8 @@ class FoundReportRun: status: ReportRunStatus baseline_simulation_run_id: UUID reform_simulation_run_id: UUID | None + # Each side's run's cliff calculation, when the request asked for cliffs. + cliffs: FoundCliffs | None = None @dataclass(frozen=True) @@ -109,6 +114,40 @@ class FoundWindowRun: status: ReportRunStatus +@dataclass(frozen=True) +class FoundCliffCalculation: + """A simulation run's cliff calculation a lookup found or inserted. + + ``status`` is the calculation's: pending or running while it is being + calculated, succeeded once it holds the run's cliff gap and share. + """ + + id: UUID + simulation_run_id: UUID + inserted: bool + status: SimulationStatus + + +@dataclass(frozen=True) +class ProposedCliffs: + """The IDs a request asking for cliffs proposes for its sides' calculations. + + Each is used only for a calculation the request inserts; one run on + both sides gets one calculation, with the baseline's ID. + """ + + baseline_id: UUID + reform_id: UUID + + +@dataclass(frozen=True) +class FoundCliffs: + """Each side's simulation run's cliff calculation, found or inserted.""" + + baseline: FoundCliffCalculation + reform: FoundCliffCalculation + + @dataclass(frozen=True) class _UniqueIndex: """A unique index a lookup inserts against: its columns and condition.""" @@ -339,6 +378,69 @@ def find_joinable_report_run( ) +_UNFAILED_CLIFF_CALCULATION: Final = _partial_index( + CliffImpact, + "uq_cliff_impacts_unfailed", + (CliffImpact.status != SimulationStatus.FAILED,), +) + + +def find_or_insert_cliff_calculations( + session: Session, proposed: Mapping[UUID, UUID] +) -> dict[UUID, FoundCliffCalculation]: + """Return each simulation run's cliff calculation, inserting it when it has none. + + ``proposed`` maps each simulation run's ID to the ID its calculation + gets if this call inserts it, pending with no Modal call. A run's + calculation that hasn't failed, pending, running or succeeded, is + found instead: a run has one cliff result, and a failed calculation + never counts (answer 2's rule, applied to cliffs). The lookups go in + simulation run ID order, so two transactions never wait for each other + in opposite orders. Return the calculations by simulation run ID. + """ + found: dict[UUID, FoundCliffCalculation] = {} + for simulation_run_id in sorted(proposed): + row, inserted = _find_or_insert( + session, + _UNFAILED_CLIFF_CALCULATION, + { + "id": proposed[simulation_run_id], + "simulation_run_id": simulation_run_id, + "status": SimulationStatus.PENDING, + }, + (CliffImpact.status,), + ) + found[simulation_run_id] = FoundCliffCalculation( + id=row.id, + simulation_run_id=simulation_run_id, + inserted=inserted, + status=SimulationStatus(row.status), + ) + return found + + +def find_or_insert_side_cliffs( + session: Session, + proposed: ProposedCliffs, + *, + baseline_simulation_run_id: UUID, + reform_simulation_run_id: UUID, +) -> FoundCliffs: + """Return each side's run's cliff calculation, inserting those it lacks. + + Called in the transaction that settled the report run naming the two + runs (``keyed_economy_records.find_or_insert_report_run_cliffs``), so + the calculations are written with it, or not at all. + """ + proposed_by_run = {baseline_simulation_run_id: proposed.baseline_id} + proposed_by_run.setdefault(reform_simulation_run_id, proposed.reform_id) + found = find_or_insert_cliff_calculations(session, proposed_by_run) + return FoundCliffs( + baseline=found[baseline_simulation_run_id], + reform=found[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 4c72783963ef03f383e874886fb230a9b9564714 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:01:49 +0400 Subject: [PATCH 03/11] Test that include_cliffs starts each side's cliff calculation (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A report created or re-run with include_cliffs writes its runs' cliff calculations with its report run and starts, before the coordinator, only those it created, through the country's simulation function with a context naming the calculation. Two identical requests start one per run; include_cliffs is in no key, stored input or calculation option; a refused cliff call fails that calculation and the report is answered 201. The 422s of C1 · 24's interim answers A and B go, a stored report asking for cliffs asks for its new runs' cliffs, and a budget window's or household report's re-run asking for them is refused. Co-Authored-By: Claude Opus 5.5 --- .../tests/economy_rerun_fakes.py | 20 +- .../tests/economy_service_fakes.py | 104 +++++- .../tests/test_budget_window_requests.py | 14 +- .../tests/test_economy_calculation_inputs.py | 89 ++++- .../tests/test_economy_rerun_routes.py | 14 + .../tests/test_economy_reruns.py | 191 ++++++++++- .../tests/test_economy_routes.py | 48 ++- .../tests/test_economy_submissions.py | 320 +++++++++++++++++- .../tests/test_economy_workers.py | 26 ++ .../tests/test_local_area_submissions.py | 6 +- .../tests/test_openapi.py | 23 +- 11 files changed, 787 insertions(+), 68 deletions(-) diff --git a/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py b/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py index 3ffa4822a..aa4215507 100644 --- a/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py +++ b/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py @@ -6,7 +6,7 @@ from __future__ import annotations -from dataclasses import dataclass, field +from dataclasses import dataclass, field, replace from typing import TYPE_CHECKING, Any, NoReturn from uuid import UUID @@ -60,7 +60,8 @@ 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). +# cliffs asks for its runs' cliffs when re-run, and its stored option never +# reaches the coordinator. STORED_OPTIONS: dict[str, Any] = { "include_cliffs": False, "spm": {"geography_kind": "national"}, @@ -247,7 +248,22 @@ def create_window_rerun(self, rerun: NewWindowRerun) -> FoundBudgetWindow: def create_report_rerun(self, rerun: NewReportRerun) -> FoundReportRun: if self.rerun_failure is not None: raise self.rerun_failure + if rerun.cliffs is not None and self.cliff_failure is not None: + raise self.cliff_failure self.report_reruns.append(rerun) + found = self._report_rerun_run(rerun) + if rerun.cliffs is None or found.reform_simulation_run_id is None: + return found + return replace( + found, + cliffs=self.found_cliffs( + rerun.cliffs, + baseline_simulation_run_id=found.baseline_simulation_run_id, + reform_simulation_run_id=found.reform_simulation_run_id, + ), + ) + + def _report_rerun_run(self, rerun: NewReportRerun) -> FoundReportRun: # 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 diff --git a/projects/policyengine-simulation-entry/tests/economy_service_fakes.py b/projects/policyengine-simulation-entry/tests/economy_service_fakes.py index 402622a72..161f72db1 100644 --- a/projects/policyengine-simulation-entry/tests/economy_service_fakes.py +++ b/projects/policyengine-simulation-entry/tests/economy_service_fakes.py @@ -34,6 +34,8 @@ EconomyReportState, EconomySimulationInputs, EconomySimulationState, + FoundCliffCalculation, + FoundCliffs, FoundEconomyReport, FoundEconomySimulation, FoundReportRun, @@ -52,6 +54,7 @@ EconomyRequest, KeyedEconomyReport, KeyedEconomySimulation, + ProposedCliffs, SimulationChoice, ) @@ -99,11 +102,7 @@ def report_request(**changes: Any) -> EconomyReportRequest: - """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 the report body's request, asking for no cliffs unless told to.""" return EconomyReportRequest.model_validate( {**REPORT_BODY, "include_cliffs": False, **changes} ) @@ -202,6 +201,16 @@ class FakeStore: 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) + # Each simulation run's cliff calculation that hasn't failed, by run, as + # the store finds it; a request's new ones are added as it creates them, + # so an identical request joins them. + cliff_calculations: dict[UUID, FoundCliffCalculation] = field(default_factory=dict) + # Raised by a create asking for cliffs, which then writes nothing. + cliff_failure: Exception | None = None + # Each request's proposed cliff calculation IDs, by simulation run. + cliff_requests: list[dict[UUID, UUID]] = field(default_factory=list) + recorded_cliff_calls: list[tuple[UUID, str]] = field(default_factory=list) + failed_cliff_calculations: list[tuple[UUID, str]] = field(default_factory=list) def read_report_inputs( self, @@ -256,10 +265,20 @@ def read_simulation(self, simulation_id: UUID) -> EconomySimulationState | None: def find_or_create_report(self, report: KeyedEconomyReport) -> FoundEconomyReport: if self.create_failure is not None: raise self.create_failure + if report.cliffs is not None and self.cliff_failure is not None: + raise self.cliff_failure self.reports.append(report) - if self.found_report is not None: - return self.found_report - return created_report(report) + found = self.found_report or created_report(report) + if report.cliffs is None: + return found + return replace( + found, + cliffs=self.found_cliffs( + report.cliffs, + baseline_simulation_run_id=found.baseline.simulation_run_id, + reform_simulation_run_id=found.reform.simulation_run_id, + ), + ) def find_or_create_simulation( self, simulation: KeyedEconomySimulation @@ -320,16 +339,70 @@ def fail_unstarted_simulation( self.failed_runs.append((simulation_run_id, (), error_message)) return True + def found_cliffs( + self, + proposed: ProposedCliffs, + *, + baseline_simulation_run_id: UUID, + reform_simulation_run_id: UUID, + ) -> FoundCliffs: + """Find or create each side's run's cliff calculation, as the store does.""" + proposed_by_run = {baseline_simulation_run_id: proposed.baseline_id} + proposed_by_run.setdefault(reform_simulation_run_id, proposed.reform_id) + self.cliff_requests.append(proposed_by_run) + found: dict[UUID, FoundCliffCalculation] = {} + for simulation_run_id, proposed_id in proposed_by_run.items(): + existing = self.cliff_calculations.get(simulation_run_id) + if existing is not None: + found[simulation_run_id] = existing + continue + found[simulation_run_id] = FoundCliffCalculation( + id=proposed_id, + simulation_run_id=simulation_run_id, + inserted=True, + status=SimulationStatus.PENDING, + ) + self.cliff_calculations[simulation_run_id] = replace( + found[simulation_run_id], inserted=False + ) + return FoundCliffs( + baseline=found[baseline_simulation_run_id], + reform=found[reform_simulation_run_id], + ) + + def record_cliff_call( + self, cliff_result_id: UUID, modal_call_id: str + ) -> SimulationStatus | None: + if self.record_failure is not None: + raise self.record_failure + self.recorded_cliff_calls.append((cliff_result_id, modal_call_id)) + return SimulationStatus.RUNNING if self.claimed else SimulationStatus.PENDING + + def fail_unstarted_cliff_calculation( + self, cliff_result_id: UUID, error_message: str + ) -> bool: + if self.fail_failure is not None: + raise self.fail_failure + if self.claimed: + return False + self.failed_cliff_calculations.append((cliff_result_id, error_message)) + return True + @dataclass class FakeCaller: """Starts calls by recording them; ``failure`` is raised instead when set. ``hang`` makes a start wait until the service stops waiting for it. + ``cliff_failure`` is raised by a cliff calculation's start alone. """ failure: Exception | None = None hang: bool = False + cliff_failure: Exception | None = None + cliff_calculations: list[tuple[EconomyWorker, dict, dict, Any]] = field( + default_factory=list + ) report_runs: list[tuple[EconomyWorker, dict, dict, Any]] = field( default_factory=list ) @@ -365,6 +438,21 @@ async def start_simulation_run( ) return "fc-worker" + async def start_cliff_calculation( + self, + worker: EconomyWorker, + simulation_payload: dict[str, Any], + context_payload: dict[str, Any], + *, + observability_context: dict[str, Any] | None, + ) -> str: + if self.cliff_failure is not None: + raise self.cliff_failure + self.cliff_calculations.append( + (worker, simulation_payload, context_payload, observability_context) + ) + return f"fc-cliffs-{len(self.cliff_calculations)}" + async def _maybe_fail(self) -> None: if self.hang: await asyncio.sleep(60) 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 5b4fdc406..a2a1ce193 100644 --- a/projects/policyengine-simulation-entry/tests/test_budget_window_requests.py +++ b/projects/policyengine-simulation-entry/tests/test_budget_window_requests.py @@ -28,17 +28,13 @@ def test_a_window_names_its_years_from_its_first() -> None: assert request.years == tuple(range(2026, 2036)) -def test_a_windows_calculation_options_ask_for_no_cliffs() -> None: +def test_a_windows_calculation_options_hold_only_its_spm_selection() -> 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"}, - } + # share runs with single-year reports by key. No options object holds + # include_cliffs, which a window never takes. + assert _request().options() == {"spm": {"geography_kind": "national"}} without_spm = {name: value for name, value in WINDOW_BODY.items() if name != "spm"} - assert BudgetWindowReportRequest.model_validate(without_spm).options() == { - "include_cliffs": False - } + assert BudgetWindowReportRequest.model_validate(without_spm).options() == {} @pytest.mark.parametrize( diff --git a/projects/policyengine-simulation-entry/tests/test_economy_calculation_inputs.py b/projects/policyengine-simulation-entry/tests/test_economy_calculation_inputs.py index 188c8a8f6..c205612db 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_calculation_inputs.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_calculation_inputs.py @@ -7,6 +7,7 @@ import pytest from economy_fixtures import STATE_DATASET, economy_manifest +from economy_service_fakes import CATALOG, report_request from household_fixtures import POLICYENGINE_VERSION from policyengine_simulation_contract.stage12_execution import ( ReportAggregate, @@ -21,15 +22,20 @@ CallOrigin, DatasetNotInBundleError, bundle_dataset, + cliff_calculation, report_run_calculation, simulation_options, simulation_run_calculation, ) +from policyengine_simulation_entry.economy_requests import calculation_scope from policyengine_simulation_entry.economy_workers import default_economy_worker +from policyengine_simulation_entry.rerunnable_records import rerun_scope +from policyengine_simulation_persistence import EconomyRequest REPORT_RUN_ID = UUID("00000000-0000-4000-8000-000000000001") BASELINE_RUN_ID = UUID("00000000-0000-4000-8000-000000000002") REFORM_RUN_ID = UUID("00000000-0000-4000-8000-000000000003") +CLIFF_RESULT_ID = UUID("00000000-0000-4000-8000-000000000004") CREATED_AT = datetime(2026, 11, 12, 15, tzinfo=UTC) CTC_AMOUNT = "gov.irs.credits.ctc.amount.base[0].amount" REFORM = {CTC_AMOUNT: {"2026-01-01.2200-12-31": 3_000}} @@ -56,7 +62,7 @@ def _scope(**changes) -> CalculationScope: "region_code": "state/ca", "dataset": STATE_DATASET, "year": 2026, - "options": {"include_cliffs": True}, + "options": {"spm": {"geography_kind": "national"}}, } return CalculationScope(**{**values, **changes}) @@ -69,11 +75,45 @@ def test_the_bundle_dataset_is_the_one_the_catalog_dataset_names() -> None: bundle_dataset(worker, "enhanced_cps_2024") -def test_the_options_hold_cliffs_only_when_asked_and_the_spm_selection_given() -> None: - assert simulation_options(include_cliffs=False, spm=None) == {} - assert simulation_options( - include_cliffs=True, spm={"geography_kind": "national"} - ) == {"include_cliffs": True, "spm": {"geography_kind": "national"}} +def test_the_options_hold_only_the_spm_selection_given() -> None: + # Cliffs are each simulation run's own calculation (C1 · 24's answer + # 4b), so the coordinator and simulation functions never plan them. + assert simulation_options(spm=None) == {} + assert simulation_options(spm={"geography_kind": "national"}) == { + "spm": {"geography_kind": "national"} + } + + +def test_a_report_asking_for_cliffs_calculates_with_its_spm_selection_alone() -> None: + request = report_request(include_cliffs=True) + + scope = calculation_scope( + request, _worker(), CATALOG, spm=request.options().get("spm") + ) + + assert scope.options == {"spm": {"geography_kind": "national"}} + + +def test_a_stored_reports_cliff_option_never_reaches_the_calculation() -> None: + """A report stored before C1 · 27 kept its request's ``include_cliffs``.""" + worker = _worker() + stored_request = EconomyRequest( + country="us", + policyengine_version=worker.policyengine_version, + region_code=CATALOG.region.code, + dataset_name=CATALOG.dataset.name, + year=2026, + ) + + scope = rerun_scope( + "us", + stored_request, + worker, + CATALOG, + options={"include_cliffs": True, "spm": {"geography_kind": "national"}}, + ) + + assert scope.options == {"spm": {"geography_kind": "national"}} def test_a_report_run_is_named_by_its_run_ids_with_no_evaluation_record() -> None: @@ -103,7 +143,7 @@ def test_a_report_run_is_named_by_its_run_ids_with_no_evaluation_record() -> Non assert side.evaluation_id == REPORT_RUN_ID assert side.year == 2026 assert (side.geography.country, side.geography.region) == ("us", "state/ca") - assert side.options == {"include_cliffs": True} + assert side.options == {"spm": {"geography_kind": "national"}} assert side.population.artifact.uri == STATE_DATASET.uri assert side.population.artifact.content_sha256 == STATE_DATASET.sha256 assert side.bundle.policyengine_version == POLICYENGINE_VERSION @@ -175,3 +215,38 @@ def test_a_standalone_run_is_named_in_its_functions_context() -> None: assert calculation.context["artifact_prefix"] == ( f"stage-12-runs/staging/2026/11/{BASELINE_RUN_ID}" ) + + +def test_a_cliff_calculation_names_its_cliff_result_and_its_runs_own_input() -> None: + """C1 · 38's entry point: the simulation function, in its cliff mode. + + The payload is the simulation run's own, as a standalone run's, whichever + report named it; the context names the cliff result alone, under the + run's artifact prefix. + """ + worker = _worker() + + calculation = cliff_calculation( + worker, + _scope(options={"spm": {"geography_kind": "national"}}), + ORIGIN, + simulation_run_id=REFORM_RUN_ID, + cliff_result_id=CLIFF_RESULT_ID, + policy=REFORM, + ) + + simulation = SimulationExecutionInput.model_validate(calculation.payload) + assert simulation.role is SimulationRole.STANDALONE + assert simulation.simulation_execution_id == REFORM_RUN_ID + assert simulation.evaluation_id == REFORM_RUN_ID + assert simulation.policy == REFORM + assert simulation.options == {"spm": {"geography_kind": "national"}} + assert (simulation.geography.country, simulation.geography.region) == ( + "us", + "state/ca", + ) + context = Stage12InvocationContext.model_validate(calculation.context) + assert context.cliff_result_id == CLIFF_RESULT_ID + assert (context.simulation_run_id, context.report_run) == (None, None) + assert context.simulation_callable == "run_single_simulation_us" + assert context.artifact_prefix == f"stage-12-runs/staging/2026/11/{REFORM_RUN_ID}" 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 b424c83bb..c1e0fb896 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_rerun_routes.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_rerun_routes.py @@ -209,6 +209,18 @@ def test_a_report_rerun_without_force_reuses_runs(client_for) -> None: assert reruns.report_reruns[0][1] == ReportRerunRequest(force=False) +def test_a_report_rerun_may_ask_for_cliffs(client_for) -> None: + reruns = FakeEconomyReruns() + + with client_for(reruns) as client: + result = client.post(REPORT_RUNS, json={"include_cliffs": True}) + + assert result.status_code == 201 + assert reruns.report_reruns[0][1] == ReportRerunRequest( + force=False, include_cliffs=True + ) + + def test_a_simulation_rerun_answers_201_with_its_new_run(client_for) -> None: reruns = FakeEconomyReruns() @@ -231,6 +243,8 @@ def test_a_simulation_rerun_answers_201_with_its_new_run(client_for) -> None: [ (REPORT_RUNS, {"force": "yes"}), (REPORT_RUNS, {"force": None}), + (REPORT_RUNS, {"include_cliffs": "yes"}), + (REPORT_RUNS, {"include_cliffs": None}), (REPORT_RUNS, {"policyengine_version": "6.17.1"}), ("/reports/not-a-uuid/runs", {}), ("/simulations/not-a-uuid/runs", None), diff --git a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py index 0eb96f1da..8c99b2da9 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_reruns.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_reruns.py @@ -29,6 +29,7 @@ from policyengine_simulation_contract.stage12_execution import ( ReportExecutionInput, ReportRunIds, + SimulationExecutionInput, Stage12InvocationContext, ) from policyengine_simulation_entry.economy_api_models import ReportRerunRequest @@ -392,27 +393,138 @@ 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``.""" +def _started_cliff_runs(caller: FakeCaller) -> set[UUID]: + """Return the simulation runs whose cliff calculations the service started.""" + return { + SimulationExecutionInput.model_validate(payload).simulation_execution_id + for _, payload, _, _ in caller.cliff_calculations + } + + +def test_a_rerun_asking_for_cliffs_joins_the_run_and_starts_its_cliffs() -> None: + """Answer 4b: a re-run on the current versions joins and adds its cliffs.""" + 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 = FakeRerunStore( + report_definition=replace(STORED_REPORT, keyed=True), + joined_report_run=joined, + ) + caller = FakeCaller() + + rerun = _rerun_report( + rerun_service(store, caller=caller), ReportRerunRequest(include_cliffs=True) + ) + + assert caller.report_runs == [] + assert _started_cliff_runs(caller) == {UUID(int=91), UUID(int=92)} + (proposed,) = store.cliff_requests + assert (rerun.report_run_id, rerun.status) == ( + UUID(int=90), + ReportRunStatus.SUCCEEDED, + ) + assert rerun.cliffs is not None + assert rerun.cliffs.baseline.cliff_result_id == proposed[UUID(int=91)] + assert rerun.cliffs.reform.cliff_result_id == proposed[UUID(int=92)] + assert rerun.cliffs.reform.status is SimulationStatus.PENDING + + +def test_a_created_rerun_asking_for_cliffs_starts_its_runs_cliffs() -> None: + store = FakeRerunStore(report_definition=replace(STORED_REPORT, keyed=True)) + caller = FakeCaller() + + rerun = _rerun_report( + rerun_service(store, caller=caller), ReportRerunRequest(include_cliffs=True) + ) + + assert len(caller.report_runs) == 1 + assert _started_cliff_runs(caller) == { + rerun.baseline_simulation_run_id, + rerun.reform_simulation_run_id, + } + report = ReportExecutionInput.model_validate(caller.report_runs[0][1]) + assert report.reform.options == {"spm": STORED_OPTIONS["spm"]} + + +def test_a_forced_rerun_whose_cliff_calculations_cannot_be_written_starts_nothing() -> ( + None +): + """Review round 1: a 503 after a forced run's start would leave extra runs.""" + store = FakeRerunStore( + report_definition=replace(STORED_REPORT, keyed=True), + cliff_failure=DATABASE_ERROR, + ) + caller = FakeCaller() + + with pytest.raises(EconomySubmissionUnavailableError) as unavailable: + _rerun_report( + rerun_service(store, caller=caller), + ReportRerunRequest(force=True, include_cliffs=True), + ) + + assert unavailable.value.code == "database_unavailable" + assert store.report_reruns == [] + assert (caller.report_runs, caller.cliff_calculations) == ([], []) + + +def test_a_rerun_whose_coordinator_modal_refuses_still_starts_its_cliffs() -> None: + """Review round 2: written with the report run, so started before its call.""" + store = FakeRerunStore(report_definition=replace(STORED_REPORT, keyed=True)) + caller = FakeCaller(failure=RuntimeError("refused")) + + with pytest.raises(EconomySubmissionUnavailableError) as unavailable: + _rerun_report( + rerun_service(store, caller=caller), + ReportRerunRequest(include_cliffs=True), + ) + + assert unavailable.value.code == "modal_call_refused" + (created,) = store.report_reruns + assert _started_cliff_runs(caller) == { + created.baseline.simulation_run_id, + created.reform.simulation_run_id, + } + + +def test_a_rerun_not_asking_for_cliffs_touches_no_cliff_calculation() -> None: + store = FakeRerunStore(report_definition=replace(STORED_REPORT, keyed=True)) + caller = FakeCaller() + + rerun = _rerun_report(rerun_service(store, caller=caller)) + + assert (store.cliff_requests, caller.cliff_calculations) == ([], []) + assert rerun.cliffs is None + + +def test_a_stored_report_asking_for_cliffs_is_rerun_with_its_cliffs() -> None: + """Interim answer B is lifted: created before C1 · 27 with ``include_cliffs``. + + Its runs are forced (interim answer B), its stored option never reaches + the coordinator, and it asks for each new run's cliffs (the user, + 2026-11-17). + """ store = FakeRerunStore( report_definition=replace( - stored, inputs={**STORED_OPTIONS, "include_cliffs": True} + STORED_REPORT, inputs={**STORED_OPTIONS, "include_cliffs": True} ) ) caller = FakeCaller() - with pytest.raises(EconomySubmissionUnprocessableError) as refused: - _rerun_report(rerun_service(store, caller=caller)) + rerun = _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 == [] + (created,) = store.report_reruns + assert created.forced is True + report = ReportExecutionInput.model_validate(caller.report_runs[0][1]) + assert report.baseline.options == {"spm": STORED_OPTIONS["spm"]} + assert _started_cliff_runs(caller) == { + created.baseline.simulation_run_id, + created.reform.simulation_run_id, + } + assert rerun.cliffs is not None def test_a_stored_report_whose_cliffs_were_not_asked_for_is_rerun() -> None: @@ -421,10 +533,59 @@ def test_a_stored_report_whose_cliffs_were_not_asked_for_is_rerun() -> None: STORED_REPORT, inputs={**STORED_OPTIONS, "include_cliffs": False} ) ) + caller = FakeCaller() - _rerun_report(rerun_service(store)) + rerun = _rerun_report(rerun_service(store, caller=caller)) assert len(store.report_reruns) == 1 + assert caller.cliff_calculations == [] + assert rerun.cliffs is None + + +def test_a_stored_windows_cliff_option_never_reaches_its_years() -> None: + store = FakeRerunStore( + report_definition=replace( + STORED_WINDOW, inputs={**STORED_OPTIONS, "include_cliffs": True} + ) + ) + caller = FakeCaller() + advancer = FakeAdvancer(store) + + _rerun_report(rerun_service(store, caller=caller, advancer=advancer)) + + assert len(caller.report_runs) == 3 + for _, payload, _, _ in caller.report_runs: + report = ReportExecutionInput.model_validate(payload) + assert report.reform.options == {"spm": STORED_OPTIONS["spm"]} + assert (store.cliff_requests, caller.cliff_calculations) == ([], []) + + +@pytest.mark.parametrize( + "stored", + [STORED_WINDOW, replace(STORED_REPORT, kind="household")], + ids=["budget-window", "household"], +) +def test_a_rerun_of_a_report_without_cliffs_asking_for_them_is_refused( + stored, +) -> None: + """Budget windows and household reports calculate no cliffs.""" + store = FakeRerunStore(report_definition=stored) + caller = FakeCaller() + + with pytest.raises(EconomySubmissionUnprocessableError) as refused: + _rerun_report( + rerun_service(store, caller=caller), + ReportRerunRequest(include_cliffs=True), + ) + + assert refused.value.code == "cliffs_not_available" + ((reason,),) = (refused.value.reasons,) + assert (reason.loc, reason.type) == ( + ("body", "include_cliffs"), + "cliffs_not_available", + ) + assert (store.rerun_reads, store.report_reruns, store.windows) == ([], [], []) + assert (caller.report_runs, caller.cliff_calculations) == ([], []) def test_a_stored_region_the_current_catalog_lacks_is_refused_naming_the_report() -> ( diff --git a/projects/policyengine-simulation-entry/tests/test_economy_routes.py b/projects/policyengine-simulation-entry/tests/test_economy_routes.py index e584830a1..c19c11a09 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_routes.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_routes.py @@ -18,10 +18,12 @@ from policyengine_simulation_entry import app as app_module from policyengine_simulation_entry.app import create_app from policyengine_simulation_entry.economy_api_models import ( + CliffCalculationState, EconomyReportCreated, EconomyReportRequest, EconomySimulationCreated, EconomySimulationRequest, + ReportCliffs, ) from policyengine_simulation_entry.economy_routes import call_request_id_for from policyengine_simulation_entry.economy_submission_errors import ( @@ -80,6 +82,7 @@ class FakeEconomySubmissions: failure: Exception | None = None stored_report: EconomyReportState | None = None stored_simulation: EconomySimulationState | None = None + report_answer: EconomyReportCreated = CREATED_REPORT reports: list[tuple[EconomyReportRequest, str, Any]] = field(default_factory=list) simulations: list[tuple[EconomySimulationRequest, str, Any]] = field( default_factory=list @@ -95,7 +98,7 @@ async def submit_report( self.reports.append((request, request_id, observability_context)) if self.failure is not None: _raise(self.failure) - return CREATED_REPORT + return self.report_answer async def submit_simulation( self, @@ -164,18 +167,44 @@ def test_a_report_answers_201_with_its_records_and_runs(client_for) -> None: assert result.status_code == 201 assert result.json() == CREATED_REPORT.model_dump(mode="json") + # A request that didn't ask for cliffs is answered without them. + assert "cliffs" not in result.json() assert result.headers[OBSERVABILITY_ID_HEADER] == OBSERVABILITY_ID ((request, request_id, context),) = submissions.reports assert request.label == REPORT_BODY["label"] - assert request.options() == { - "include_cliffs": True, - "spm": {"geography_kind": "national"}, - } + # include_cliffs is the request's alone, in no options object (answer 4b). + assert request.include_cliffs is True + assert request.options() == {"spm": {"geography_kind": "national"}} # The call's request ID is the request's own (see the request ID test). assert request_id != OBSERVABILITY_ID assert context["observability_id"] == OBSERVABILITY_ID +def test_a_report_asking_for_cliffs_answers_each_sides_cliff_calculation( + client_for, +) -> None: + cliffs = ReportCliffs( + baseline=CliffCalculationState( + cliff_result_id=UUID(int=70), status=SimulationStatus.SUCCEEDED + ), + reform=CliffCalculationState( + cliff_result_id=UUID(int=71), status=SimulationStatus.PENDING + ), + ) + submissions = FakeEconomySubmissions( + report_answer=CREATED_REPORT.model_copy(update={"cliffs": cliffs}) + ) + + with client_for(submissions) as client: + result = client.post("/reports", json={**REPORT_BODY, "include_cliffs": True}) + + assert result.status_code == 201 + assert result.json()["cliffs"] == { + "baseline": {"cliff_result_id": str(UUID(int=70)), "status": "succeeded"}, + "reform": {"cliff_result_id": str(UUID(int=71)), "status": "pending"}, + } + + def test_a_simulation_answers_201_with_its_record_and_run(client_for) -> None: submissions = FakeEconomySubmissions() @@ -393,10 +422,11 @@ def test_a_uk_wide_or_nation_report_may_ask_for_the_local_area_dataset( assert result.status_code == 201 ((request, _, _),) = submissions.reports assert request.data_source == "local_area_dataset" - # The report still calculates cliffs. The data source is never stored as - # an option: the dataset it chooses is stored with the report's - # simulations. - assert request.options() == {"include_cliffs": True} + # The report still asks for cliffs, which are each simulation run's own + # calculation. The data source is never stored as an option: the dataset + # it chooses is stored with the report's simulations. + assert request.include_cliffs is True + assert request.options() == {} @pytest.mark.parametrize(("path", "body"), ROUTES) diff --git a/projects/policyengine-simulation-entry/tests/test_economy_submissions.py b/projects/policyengine-simulation-entry/tests/test_economy_submissions.py index 7aa234740..fccaf78da 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_submissions.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_submissions.py @@ -28,9 +28,14 @@ from policyengine_simulation_contract.stage12_execution import ( ReportExecutionInput, ReportRunIds, + SimulationExecutionInput, Stage12InvocationContext, ) -from policyengine_simulation_entry.economy_api_models import EconomyReportRequest +from policyengine_simulation_entry.economy_api_models import ( + CliffCalculationState, + EconomyReportRequest, + ReportCliffs, +) from policyengine_simulation_entry.economy_submission_errors import ( EconomySubmissionOutcomeUnknownError, EconomySubmissionRefusedError, @@ -53,6 +58,7 @@ EconomyRequest, EconomySimulationDefinition, EconomySimulationState, + FoundCliffCalculation, FoundEconomyReport, FoundEconomySimulation, FoundReportRun, @@ -284,24 +290,316 @@ def test_a_report_without_spm_settings_stores_none() -> None: 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).""" +def _started_cliff_calculations(caller: FakeCaller) -> dict[UUID, UUID]: + """Return each cliff calculation the service started, by its simulation run.""" + started: dict[UUID, UUID] = {} + for _, payload, context, _ in caller.cliff_calculations: + simulation = SimulationExecutionInput.model_validate(payload) + cliff_result_id = Stage12InvocationContext.model_validate( + context + ).cliff_result_id + assert cliff_result_id is not None + started[simulation.simulation_execution_id] = cliff_result_id + return started + + +def _cliff_payloads(caller: FakeCaller) -> dict[UUID, SimulationExecutionInput]: + return { + payload.simulation_execution_id: payload + for payload in ( + SimulationExecutionInput.model_validate(started[1]) + for started in caller.cliff_calculations + ) + } + + +def test_a_report_asking_for_cliffs_starts_each_side_runs_cliff_calculation() -> None: + """Interim answer A is lifted: one cliff calculation per simulation run (4b).""" store = FakeStore() caller = FakeCaller() - with pytest.raises(EconomySubmissionUnprocessableError) as refusal: + created = _submit_report( + service(store, caller=caller), report_request(include_cliffs=True) + ) + + (proposed,) = store.cliff_requests + assert set(proposed) == {UUID(int=4), UUID(int=6)} + assert _started_cliff_calculations(caller) == proposed + payloads = _cliff_payloads(caller) + assert (payloads[UUID(int=4)].policy, payloads[UUID(int=6)].policy) == ({}, REFORM) + assert payloads[UUID(int=6)].options == {"spm": {"geography_kind": "national"}} + assert all(observed == OBSERVED for *_, observed in caller.cliff_calculations) + assert sorted(cliff_id for cliff_id, _ in store.recorded_cliff_calls) == sorted( + proposed.values() + ) + assert created.cliffs == ReportCliffs( + baseline=CliffCalculationState( + cliff_result_id=proposed[UUID(int=4)], status=SimulationStatus.PENDING + ), + reform=CliffCalculationState( + cliff_result_id=proposed[UUID(int=6)], status=SimulationStatus.PENDING + ), + ) + # The report run is calculated as ever, and its coordinator plans no cliffs. + assert store.recorded_calls == [(UUID(int=2), "fc-coordinator")] + report = ReportExecutionInput.model_validate(caller.report_runs[0][1]) + assert ( + report.baseline.options + == report.reform.options + == {"spm": {"geography_kind": "national"}} + ) + + +@pytest.mark.parametrize( + "status", + [SimulationStatus.PENDING, SimulationStatus.RUNNING, SimulationStatus.SUCCEEDED], +) +def test_a_side_run_with_a_cliff_calculation_gets_no_new_one( + status: SimulationStatus, +) -> None: + """Being calculated, or calculated: the request joins it and starts nothing.""" + existing = FoundCliffCalculation( + id=UUID(int=70), simulation_run_id=UUID(int=6), inserted=False, status=status + ) + store = FakeStore(cliff_calculations={UUID(int=6): existing}) + caller = FakeCaller() + + created = _submit_report( + service(store, caller=caller), report_request(include_cliffs=True) + ) + + started = _started_cliff_calculations(caller) + assert list(started) == [UUID(int=4)] + assert UUID(int=70) not in {cliff_id for cliff_id, _ in store.recorded_cliff_calls} + assert created.cliffs is not None + assert created.cliffs.reform == CliffCalculationState( + cliff_result_id=UUID(int=70), status=status + ) + assert created.cliffs.baseline.cliff_result_id == started[UUID(int=4)] + + +def test_one_run_on_both_sides_gets_one_cliff_calculation() -> None: + store = FakeStore() + caller = FakeCaller() + + created = _submit_report( + service(store, caller=caller), + report_request( + include_cliffs=True, reform={"policy_id": None, "dynamic_id": None} + ), + ) + + (proposed,) = store.cliff_requests + assert list(proposed) == [UUID(int=4)] + assert _started_cliff_calculations(caller) == proposed + assert created.cliffs is not None + assert created.cliffs.baseline == created.cliffs.reform + assert created.cliffs.baseline.cliff_result_id == proposed[UUID(int=4)] + + +def test_a_joined_report_run_asking_for_cliffs_starts_its_runs_missing_ones() -> None: + """A re-asked report: its run is joined, and its runs get their cliffs.""" + store = FakeStore( + found_report=_found_report(run_inserted=False, status=ReportRunStatus.SUCCEEDED) + ) + caller = FakeCaller() + + created = _submit_report( + service(store, caller=caller), report_request(include_cliffs=True) + ) + + assert caller.report_runs == [] + started = _started_cliff_calculations(caller) + assert set(started) == {REUSED.simulation_run_id, UUID(int=93)} + payloads = _cliff_payloads(caller) + assert payloads[REUSED.simulation_run_id].policy == {} + assert payloads[UUID(int=93)].policy == REFORM + assert (created.report_run_id, created.status) == ( + UUID(int=91), + ReportRunStatus.SUCCEEDED, + ) + assert created.cliffs is not None + assert created.cliffs.reform.cliff_result_id == started[UUID(int=93)] + + +def test_two_identical_requests_start_one_cliff_calculation_per_run() -> None: + store = FakeStore() + caller = FakeCaller() + submissions = service(store, caller=caller) + + first = _submit_report(submissions, report_request(include_cliffs=True)) + # The second ends on the first's report and runs, as the store finds them. + store.found_report = FoundEconomyReport( + report_id=first.report_id, + report_inserted=False, + run=FoundReportRun( + id=first.report_run_id, + inserted=False, + status=ReportRunStatus.PENDING, + baseline_simulation_run_id=first.baseline_simulation_run_id, + reform_simulation_run_id=first.reform_simulation_run_id, + ), + baseline=FoundSide( + simulation_id=first.baseline_simulation_id, + simulation_run_id=first.baseline_simulation_run_id, + run_inserted=False, + ), + reform=FoundSide( + simulation_id=first.reform_simulation_id, + simulation_run_id=first.reform_simulation_run_id, + run_inserted=False, + ), + ) + second = _submit_report(submissions, report_request(include_cliffs=True)) + + assert len(caller.cliff_calculations) == 2 + assert len(caller.report_runs) == 1 + assert second.cliffs == first.cliffs + + +def test_include_cliffs_changes_no_key_and_is_never_stored() -> None: + """Answer 4b: a request option, in no key and no stored row.""" + stores = {asked: FakeStore() for asked in (True, False)} + callers = {asked: FakeCaller() for asked in (True, False)} + + for asked, store in stores.items(): + _submit_report( + service(store, caller=callers[asked]), + report_request(include_cliffs=asked), + ) + + (with_cliffs,) = stores[True].reports + (without_cliffs,) = stores[False].reports + assert with_cliffs.definition == without_cliffs.definition + assert with_cliffs.definition.definition_key == ( + without_cliffs.definition.definition_key + ) + assert with_cliffs.definition.dataset_independent_key == ( + without_cliffs.definition.dataset_independent_key + ) + assert ( + with_cliffs.inputs + == without_cliffs.inputs + == {"spm": {"geography_kind": "national"}} + ) + payloads = [ + ReportExecutionInput.model_validate(callers[asked].report_runs[0][1]) + for asked in (True, False) + ] + assert payloads[0].baseline.options == payloads[1].baseline.options + + +def test_a_report_not_asking_for_cliffs_touches_no_cliff_calculation() -> None: + store = FakeStore() + caller = FakeCaller() + + created = _submit_report(service(store, caller=caller)) + + assert (store.cliff_requests, caller.cliff_calculations) == ([], []) + assert created.cliffs is None + assert "cliffs" not in created.model_dump(mode="json") + + +def test_a_cliff_call_modal_refuses_fails_that_calculation_and_answers_the_report() -> ( + None +): + """The report run is calculated; the next request asking starts cliffs again.""" + store = FakeStore() + caller = FakeCaller(cliff_failure=RuntimeError("refused")) + + created = _submit_report( + service(store, caller=caller), report_request(include_cliffs=True) + ) + + (proposed,) = store.cliff_requests + failed = dict(store.failed_cliff_calculations) + assert set(failed) == set(proposed.values()) + assert all( + message.startswith("modal_call_refused: ") for message in failed.values() + ) + assert store.recorded_cliff_calls == [] + assert (created.report_run_id, created.status) == ( + UUID(int=2), + ReportRunStatus.PENDING, + ) + assert created.cliffs is not None + assert created.cliffs.baseline.status is SimulationStatus.FAILED + assert created.cliffs.reform.status is SimulationStatus.FAILED + + +def test_a_cliff_calculation_its_function_claimed_meanwhile_is_answered_pending() -> ( + None +): + """Modal accepted the call after the wait ended; the row is left as it is.""" + store = FakeStore(claimed=True) + caller = FakeCaller(cliff_failure=TimeoutError()) + + created = _submit_report( + service(store, caller=caller), report_request(include_cliffs=True) + ) + + assert store.failed_cliff_calculations == [] + assert created.cliffs is not None + assert created.cliffs.baseline.status is SimulationStatus.PENDING + + +def test_a_create_whose_cliff_calculations_cannot_be_written_starts_nothing() -> None: + """Review round 1: they're written with the report, so a 503 wrote nothing.""" + store = FakeStore(cliff_failure=DATABASE_ERROR) + caller = FakeCaller() + + with pytest.raises(EconomySubmissionUnavailableError) as unavailable: + _submit_report( + service(store, caller=caller), report_request(include_cliffs=True) + ) + + assert unavailable.value.code == "database_unavailable" + assert store.reports == [] + assert (caller.report_runs, caller.cliff_calculations) == ([], []) + + +def test_a_report_whose_coordinator_modal_refuses_still_starts_its_cliffs() -> None: + """The calculations were written with the report: each run's, kept for others.""" + store = FakeStore() + caller = FakeCaller(failure=RuntimeError("refused")) + + with pytest.raises(EconomySubmissionUnavailableError) as unavailable: _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 unavailable.value.code == "modal_call_refused" + (proposed,) = store.cliff_requests + assert _started_cliff_calculations(caller) == proposed + + +def test_a_cliff_call_whose_id_cannot_be_recorded_is_answered_pending() -> None: + """The function claims a pending calculation with no call ID itself.""" + store = FakeStore(record_failure=DATABASE_ERROR) + caller = FakeCaller() + + created = _submit_report( + service(store, caller=caller), report_request(include_cliffs=True) + ) + + assert len(caller.cliff_calculations) == 2 + assert created.cliffs is not None + assert created.cliffs.baseline.status is SimulationStatus.PENDING + assert created.cliffs.reform.status is SimulationStatus.PENDING + + +def test_a_refused_cliff_call_whose_failure_cannot_be_written_is_pending() -> None: + """The stuck-run sweep fails the calculation if no call ever claims it.""" + store = FakeStore(fail_failure=DATABASE_ERROR) + caller = FakeCaller(cliff_failure=RuntimeError("refused")) + + created = _submit_report( + service(store, caller=caller), report_request(include_cliffs=True) ) - assert "cliff" in reason.msg - assert (store.report_reads, store.reports, caller.report_runs) == ([], [], []) + + assert store.failed_cliff_calculations == [] + assert created.cliffs is not None + assert created.cliffs.baseline.status is SimulationStatus.PENDING @pytest.mark.parametrize( diff --git a/projects/policyengine-simulation-entry/tests/test_economy_workers.py b/projects/policyengine-simulation-entry/tests/test_economy_workers.py index 9192e4f27..b6795ca6e 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_workers.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_workers.py @@ -182,6 +182,32 @@ def test_a_standalone_run_starts_the_countrys_simulation_function( ] +def test_a_cliff_calculation_starts_the_countrys_simulation_function( + modal_functions, +) -> None: + """C1 · 38's cliff mode: the context names the cliff result, not a run.""" + looked_up, function = modal_functions + worker = default_economy_worker(economy_manifest(), "uk") + + call_id = asyncio.run( + ModalEconomyRunCaller("main").start_cliff_calculation( + worker, + {"simulation": 1}, + {"cliff_result_id": "cliffs"}, + observability_context={"observability_id": "observed"}, + ) + ) + + assert call_id == "fc-started" + assert looked_up == [(worker.application_name, "run_single_simulation_uk", "main")] + assert function.spawns == [ + ( + ({"simulation": 1}, {"cliff_result_id": "cliffs"}), + {"observability_context": {"observability_id": "observed"}}, + ) + ] + + @pytest.mark.parametrize("object_id", [None, ""]) def test_a_call_modal_gives_no_id_is_an_error(modal_functions, object_id) -> None: _, function = modal_functions diff --git a/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py b/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py index 4f0c9e521..0f30657f9 100644 --- a/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py +++ b/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py @@ -70,11 +70,7 @@ def _uk_report_request(**changes: Any) -> EconomyReportRequest: - """Return a UK-wide report request, with no SPM settings and no cliffs. - - The service refuses ``include_cliffs: true`` until per-run cliff - calculations exist (C1 · 24's interim answer A). - """ + """Return a UK-wide report request, with no SPM settings and no cliffs.""" body = {name: value for name, value in REPORT_BODY.items() if name != "spm"} return EconomyReportRequest.model_validate( { diff --git a/projects/policyengine-simulation-entry/tests/test_openapi.py b/projects/policyengine-simulation-entry/tests/test_openapi.py index d80944bd2..4aaa959a8 100644 --- a/projects/policyengine-simulation-entry/tests/test_openapi.py +++ b/projects/policyengine-simulation-entry/tests/test_openapi.py @@ -479,12 +479,13 @@ 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. + # A budget window's or household report's re-run asking for cliffs is + # refused: neither calculates them. 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 set(report_rerun["properties"]) == {"force", "include_cliffs"} assert ( "requestBody" not in spec["paths"]["/simulations/{simulation_id}/runs"]["post"] ) @@ -652,3 +653,21 @@ def test_the_local_area_refusals_are_in_the_error_codes(): assert {"local_areas_unsupported", "local_area_dataset_mismatch"} <= error_codes assert "no_local_area_dataset" in unprocessable_codes + + +def test_a_report_create_takes_include_cliffs_and_answers_each_sides_cliffs(): + """C1 · 39: ``include_cliffs`` starts each side's cliff calculation.""" + spec = create_app().openapi() + schemas = spec["components"]["schemas"] + + created = schemas["EconomyReportCreated"] + assert "cliffs" in created["properties"] + assert "cliffs" not in created.get("required", []) + assert set(schemas["ReportCliffs"]["properties"]) == {"baseline", "reform"} + assert set(schemas["CliffCalculationState"]["properties"]) == { + "cliff_result_id", + "status", + } + # A create no longer refuses cliffs. + create_answers = _responses(spec, "post", "/reports") + assert "cliffs_not_available" not in create_answers["422"]["description"] From 1d0b7825ed19f0d426552e415780019104f0d99b Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:04:08 +0400 Subject: [PATCH 04/11] Start each side's cliff calculation for a report asking for cliffs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit POST /reports with include_cliffs, and a re-run with the re-run body's new include_cliffs, propose their sides' calculation IDs with their report run. Before the report run's coordinator, the service starts only the calculations its request inserted: the country's simulation function, given the run's own input and a context naming the cliff calculation. A refused call fails that calculation and the report is still answered 201, naming each side's calculation and status in cliffs, a field left out when the request didn't ask. include_cliffs is never stored, keyed or in any calculation's options. The 422s of C1 · 24's interim answers A and B go: a report stored before keys asking for cliffs is re-run with its runs' cliffs, and a budget window's or household report's re-run asking for them is refused. Co-Authored-By: Claude Opus 5.5 --- .../budget_window_api_models.py | 16 +- .../cliff_calculation_starts.py | 242 ++++++++++++++++++ .../economy_api_models.py | 88 +++++-- .../economy_calculation_inputs.py | 76 ++++-- .../economy_requests.py | 81 +++--- .../economy_rerun_routes.py | 32 ++- .../economy_reruns.py | 96 ++++--- .../economy_routes.py | 16 +- .../economy_submissions.py | 74 +++++- .../economy_workers.py | 35 ++- .../rerunnable_records.py | 14 +- 11 files changed, 615 insertions(+), 155 deletions(-) create mode 100644 projects/policyengine-simulation-entry/src/policyengine_simulation_entry/cliff_calculation_starts.py 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 6396a501e..2ce1eb427 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 @@ -94,16 +94,16 @@ def years(self) -> tuple[int, ...]: return tuple(range(self.year, self.year + self.budget_window_size)) def options(self) -> dict[str, Any]: - """Return the window's calculation options: no cliffs, and its SPM selection. + """Return the window's calculation options: its SPM selection alone. - ``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. + ``spm`` holds only the settings the request gave, and is left out + when it gave none. The report stores the selection alone + (``economy_requests.stored_options``), and its years share runs with + single-year reports by key. A window takes no cliffs. """ - options: dict[str, Any] = {"include_cliffs": False} - if self.spm is not None: - options["spm"] = self.spm.model_dump(mode="json") - return options + if self.spm is None: + return {} + return {"spm": self.spm.model_dump(mode="json")} class _Answer(BaseModel): diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/cliff_calculation_starts.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/cliff_calculation_starts.py new file mode 100644 index 000000000..31fa0f977 --- /dev/null +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/cliff_calculation_starts.py @@ -0,0 +1,242 @@ +"""Start the cliff calculations a report's request created, one per simulation run. + +A simulation run has one cliff result, its cliff gap and cliff share, which +every report naming the run reads: cliffs are a calculation of the run, not +of any report (C1 · 24's answer 4b, the Public API's ``cliff_impacts``). +``include_cliffs`` is a request option, never stored or keyed. A create or +re-run asking for cliffs ends on a report run as any other does, and in the +same transaction finds or creates the cliff calculation of each simulation +run that report run names (``find_or_insert_report_run_cliffs``): a run's +calculation that hasn't failed, pending, running or succeeded, is joined, +and a failed one never counts. So two identical requests end on one +calculation per run, and a request the database refuses wrote neither the +report run nor its calculations. + +This module starts the calculations the request created, and only those, +before the report run's coordinator: they were written with the report +run, so they are started even when Modal then refuses the coordinator. It +starts the simulation run's simulation function, given the run's own input +and a context naming the calculation (C1 · 38's cliff mode), called with +``spawn``. It records the call's ID while the calculation is pending with +none. When Modal refuses the call, or doesn't confirm it in time, it fails +the calculation while it is still pending with no call, so the next request +asking for cliffs starts another; one the function claimed meanwhile is +left as it is and answered ``pending``. The report run is not affected +either way. A calculation runs beside its simulation run, whatever that +run's state: it recalculates the simulation from the same dataset and +policy, and doesn't read the run's output. +""" + +from __future__ import annotations + +import asyncio +import logging +from typing import TYPE_CHECKING, Any, Protocol + +from policyengine_simulation_persistence import SimulationStatus +from sqlalchemy.exc import SQLAlchemyError + +from policyengine_simulation_entry.economy_api_models import ( + CliffCalculationState, + ReportCliffs, +) +from policyengine_simulation_entry.economy_calculation_inputs import ( + cliff_calculation, +) + +if TYPE_CHECKING: + from uuid import UUID + + from policyengine_simulation_persistence import ( + FoundCliffCalculation, + FoundCliffs, + ) + + from policyengine_simulation_entry.economy_calculation_inputs import ( + CalculationScope, + CallOrigin, + ) + from policyengine_simulation_entry.economy_workers import ( + EconomyRunCaller, + EconomyWorker, + ) + +logger = logging.getLogger(__name__) + + +class CliffCalculationRuns(Protocol): + """The store's writes of cliff calculations (``EconomyRunStore``).""" + + def record_cliff_call( + self, cliff_result_id: UUID, modal_call_id: str + ) -> SimulationStatus | None: + """Record the calculation's call ID while it is pending with none.""" + ... + + def fail_unstarted_cliff_calculation( + self, cliff_result_id: UUID, error_message: str + ) -> bool: + """Fail the calculation while it is pending with no call ID.""" + ... + + +class CliffCalculationStarts: + """Start the cliff calculations a request created, and answer each side's.""" + + def __init__( + self, + *, + store: CliffCalculationRuns, + caller: EconomyRunCaller, + call_start_timeout_seconds: float, + ) -> None: + """Record calls in ``store``; wait this long for Modal to accept each.""" + self._store = store + self._caller = caller + self._call_start_timeout_seconds = call_start_timeout_seconds + + async def start( # noqa: PLR0913 # what each call calculates, then each side + self, + worker: EconomyWorker, + scope: CalculationScope, + origin: CallOrigin, + *, + found: FoundCliffs, + baseline_policy: dict[str, Any], + reform_policy: dict[str, Any], + observability_context: dict[str, Any] | None, + ) -> ReportCliffs: + """Start each calculation in ``found`` this request created; answer each side. + + ``found`` holds each side's run's calculation as the store found or + created it with the report run, and each policy is the one that + side's run calculates. One the store found is answered with its + status as read, and gets no call; one run on both sides has one + calculation, started once. + """ + sides = { + found.reform.simulation_run_id: (found.reform, reform_policy), + # The baseline's last, so one run on both sides keeps its policy. + found.baseline.simulation_run_id: (found.baseline, baseline_policy), + } + created = [ + (calculation, policy) + for calculation, policy in sides.values() + if calculation.inserted + ] + started = await asyncio.gather( + *( + self._start_one( + worker, + scope, + origin, + calculation=calculation, + policy=policy, + observability_context=observability_context, + ) + for calculation, policy in created + ) + ) + statuses = { + calculation.simulation_run_id: status + for (calculation, _), status in zip(created, started, strict=True) + } + + def state(calculation: FoundCliffCalculation) -> CliffCalculationState: + return CliffCalculationState( + cliff_result_id=calculation.id, + status=statuses.get(calculation.simulation_run_id, calculation.status), + ) + + return ReportCliffs(baseline=state(found.baseline), reform=state(found.reform)) + + async def _start_one( # noqa: PLR0913 # what the call calculates, then its row + self, + worker: EconomyWorker, + scope: CalculationScope, + origin: CallOrigin, + *, + calculation: FoundCliffCalculation, + policy: dict[str, Any], + observability_context: dict[str, Any] | None, + ) -> SimulationStatus: + """Start one calculation and record its call; or fail it, unless started. + + Return its status: as recorded, ``pending`` when the record couldn't + be written or the function claimed it first, ``failed`` when the + call wasn't confirmed and the calculation was failed. + """ + cliff_result_id = calculation.id + call = cliff_calculation( + worker, + scope, + origin, + simulation_run_id=calculation.simulation_run_id, + cliff_result_id=cliff_result_id, + policy=policy, + ) + try: + call_id = await asyncio.wait_for( + self._caller.start_cliff_calculation( + worker, + call.payload, + call.context, + observability_context=observability_context, + ), + timeout=self._call_start_timeout_seconds, + ) + # Modal raises its own errors; any of them, or the timeout, means the + # call was not confirmed, and the calculation is failed unless started. + except Exception as error: # noqa: BLE001 # every unconfirmed call is answered alike + failed = await self._fail_unconfirmed(cliff_result_id, error) + return SimulationStatus.FAILED if failed else SimulationStatus.PENDING + try: + status = await asyncio.to_thread( + self._store.record_cliff_call, cliff_result_id, call_id + ) + except SQLAlchemyError as error: + # The function claims a pending calculation with no call ID itself. + logger.warning( + "cliff_calculation_call_not_recorded", + extra={ + "cliff_result_id": str(cliff_result_id), + "error_type": type(error).__name__, + }, + ) + return SimulationStatus.PENDING + return SimulationStatus.PENDING if status is None else status + + async def _fail_unconfirmed( + self, cliff_result_id: UUID, error: BaseException + ) -> bool: + """Fail the calculation of a call Modal didn't confirm, unless it started. + + Return whether it was failed. When the write itself fails, the + calculation stays pending, and the stuck-run sweep fails it if no + call ever claims it. + """ + # The log names the error type only; its text could repeat request data. + logger.error( + "cliff_calculation_call_unconfirmed", + extra={ + "cliff_result_id": str(cliff_result_id), + "error_type": type(error).__name__, + }, + ) + message = ( + "modal_call_refused: Modal did not accept the cliff calculation's " + f"call ({type(error).__name__})." + ) + try: + return await asyncio.to_thread( + self._store.fail_unstarted_cliff_calculation, cliff_result_id, message + ) + except SQLAlchemyError as write_error: + logger.warning( + "cliff_calculation_not_failed", + extra={ + "cliff_result_id": str(cliff_result_id), + "error_type": type(write_error).__name__, + }, + ) + return False 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 3547c9dbe..c914d3a0c 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 @@ -12,7 +12,8 @@ Answers the Public API reads: - 201 with the created record's ID and its first run's ID, or, for a - re-run, the record's ID and its new run's ID; + re-run, the record's ID and its new run's ID; for a report asking for + cliffs, also each side's cliff calculation and its status; - 400 with ``code`` and ``detail``: one of ``CallerRowRefusalCode`` when the region, dataset or a dynamic the request names (or, for a re-run, the stored record names) does not exist, or another code for the service's own @@ -121,8 +122,8 @@ # authorities to no dataset of their own, so it has no local-area dataset # for ``data_source``: located at ``data_source``. "no_local_area_dataset", - # A report asks for cliffs (include_cliffs: true), which wait for each - # simulation run's own cliff calculation (C1 · 39); located at the field. + # A budget window's or household report's re-run asks for cliffs + # (include_cliffs: true), which neither calculates; located at the field. "cliffs_not_available", ] # Why a stored record is not re-run now (409). @@ -187,20 +188,24 @@ class EconomyReportRequest(_Request): """An economy report: a baseline and a reform simulation of one region's data. Both simulations use the report's year and region, and the region's - dataset, as ``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. + dataset, as ``EconomySimulationRequest`` describes them. + ``include_cliffs: true`` starts a cliff calculation for each side's + simulation run that has none, and joins one being calculated: a run's + cliffs are a calculation of their own, shared by every report naming + the run. It is never stored and in no key, so a request with it ends on + the same report and runs as one without. ``spm`` selects the SPM + forecast scenario and geography; omit it, rather than sending null, to + use the bundle's certified defaults. ``data_source: "local_area_dataset"`` runs the report on the bundle's local-area dataset, the one its .py release routes constituencies and local authorities to, in place of the region's own: the report returns - its full results, cliffs included when asked, and its constituency and - local-authority impacts. Only a UK report whose region is ``uk`` or one - of the four ``country/*`` nations may ask; omit it, rather than sending - null, to use the region's dataset. It is never stored as an option: the - dataset it chooses is stored with the report's simulations. + its full results and its constituency and local-authority impacts, and + its simulation runs' cliffs when asked. Only a UK report whose region is + ``uk`` or one of the four ``country/*`` nations may ask; omit it, rather + than sending null, to use the region's dataset. It is never stored as + an option: the dataset it chooses is stored with the report's + simulations. """ country: CountryId @@ -280,14 +285,14 @@ def options(self) -> dict[str, Any]: ``spm`` holds only the settings the request gave, and is left out when it gave none. The report stores the selection alone - (``economy_requests.stored_options``). ``data_source`` is never an - option: the dataset it chooses is stored with the report's - simulations. + (``economy_requests.stored_options``). Neither ``include_cliffs`` + nor ``data_source`` is an option: cliffs are each simulation run's + own calculation, and the dataset ``data_source`` chooses is stored + with the report's simulations. """ - options: dict[str, Any] = {"include_cliffs": self.include_cliffs} - if self.spm is not None: - options["spm"] = self.spm.model_dump(mode="json") - return options + if self.spm is None: + return {} + return {"spm": self.spm.model_dump(mode="json")} class ReportRerunRequest(_Request): @@ -301,9 +306,17 @@ class ReportRerunRequest(_Request): 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. + + ``include_cliffs: true`` starts a cliff calculation for each simulation + run the economy report's run names that has none, as a create's does, + whether the re-run joined its run or created it. A report stored before + C1 · 27 asking for cliffs asks for them on its re-run too. A budget + window or household report calculates no cliffs, and its re-run asking + for them is refused (422 ``cliffs_not_available``). """ force: StrictBool = False + include_cliffs: StrictBool = False class _Answer(BaseModel): @@ -326,6 +339,35 @@ class EconomySimulationCreated(_Answer): status: SimulationStatus +class CliffCalculationState(_Answer): + """A simulation run's cliff calculation a request started or joined. + + ``cliff_result_id`` is the calculation's row; ``status`` is ``pending`` + or ``running`` while it is calculated, ``succeeded`` once it holds the + run's cliff gap and share, and ``failed`` once it failed (the next + request asking for cliffs starts another). A calculation the request + joined is answered with its status as read, never ``failed``. One it + started is answered with its status when its call's ID was recorded: + ``pending``, or what the worker had made it by then, ``failed`` + included; ``failed`` when Modal refused or didn't confirm the call and + it was failed; and ``pending`` when that call's ID couldn't be recorded, + or the worker claimed it after an unconfirmed call. + """ + + cliff_result_id: UUID + status: SimulationStatus + + +class ReportCliffs(_Answer): + """Each side's cliff calculation: of the simulation run that side names. + + One simulation run on both sides names one calculation on both. + """ + + baseline: CliffCalculationState + reform: CliffCalculationState + + class EconomyReportCreated(_Answer): """The report a request ended on, its run and that run's status. @@ -338,6 +380,8 @@ class EconomyReportCreated(_Answer): names its simulation and simulation run; ``…_reused`` is true for a side whose run this request didn't create: another request's run, in any state, that the side joined, or, on a joined report run, that run's own. + ``cliffs``, given only when the request asked for them, names each + side's cliff calculation. """ report_id: UUID @@ -349,6 +393,10 @@ class EconomyReportCreated(_Answer): reform_simulation_id: UUID reform_simulation_run_id: UUID reform_reused: bool + # Left out of the answer when the request didn't ask for cliffs. + cliffs: ReportCliffs | None = Field( + default=None, exclude_if=lambda value: value is None + ) class SimulationRunRead(_Answer): diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_calculation_inputs.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_calculation_inputs.py index 879cda5e8..2d84713f0 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_calculation_inputs.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_calculation_inputs.py @@ -7,7 +7,9 @@ each simulation function the run it claims; no evaluation record is passed. A standalone simulation run's function takes that run's ``SimulationExecutionInput`` and a context naming the run -(``simulation_run_id``). +(``simulation_run_id``). A simulation run's cliff calculation is the same +function given the run's own input, as a standalone run's, and a context +naming the cliff calculation (``cliff_result_id``) instead (C1 · 38). Both sides of a report calculate on the same dataset, region, year, options and bundle; only their policies differ. The dataset is the bundle's @@ -62,8 +64,10 @@ class DatasetNotInBundleError(LookupError): class CalculationScope: """What every simulation of a request calculates on, as the worker reads it. - ``options`` are the simulation options both sides share: ``include_cliffs`` - when true, and the SPM selection when one was given. + ``options`` are the simulation options both sides share: the SPM + selection, when one was given. Cliffs are never among them: each + simulation run's cliffs are a calculation of their own (C1 · 24's + answer 4b). """ country: CountryId @@ -109,16 +113,9 @@ def bundle_dataset(worker: EconomyWorker, dataset_name: str) -> Stage12Dataset: return dataset -def simulation_options( - *, include_cliffs: bool, spm: dict[str, Any] | None -) -> dict[str, Any]: - """Return the options both sides of a calculation share.""" - options: dict[str, Any] = {} - if include_cliffs: - options["include_cliffs"] = True - if spm is not None: - options["spm"] = spm - return options +def simulation_options(*, spm: dict[str, Any] | None) -> dict[str, Any]: + """Return the options both sides of a calculation share: the SPM selection.""" + return {} if spm is None else {"spm": spm} def _simulation_input( # noqa: PLR0913 # the run, its role, its policy and what it calculates @@ -164,18 +161,25 @@ def _simulation_input( # noqa: PLR0913 # the run, its role, its policy and wha def _context( - worker: EconomyWorker, origin: CallOrigin, *, runs: ReportRunIds | UUID + worker: EconomyWorker, + origin: CallOrigin, + *, + runs: ReportRunIds | UUID, + cliff_result_id: UUID | None = None, ) -> Stage12InvocationContext: - """Return the call's context, naming ``runs``. + """Return the call's context, naming ``runs``, or the cliff calculation. - ``runs`` is a report run's IDs, for its coordinator, or a standalone - simulation run's ID, for its simulation function. The artifact prefix - names that report run or simulation run, so the two can't differ. + ``runs`` is a report run's IDs, for its coordinator, or a simulation + run's ID, for its simulation function. The artifact prefix names that + report run or simulation run, so the two can't differ. With + ``cliff_result_id``, the context names that cliff calculation of the + simulation run ``runs`` instead of the run, under the run's prefix. """ if isinstance(runs, ReportRunIds): report_run, simulation_run_id, run_id = runs, None, runs.report_run_id else: - report_run, simulation_run_id, run_id = None, runs, runs + report_run, run_id = None, runs + simulation_run_id = runs if cliff_result_id is None else None created_at = origin.created_at return Stage12InvocationContext( request_id=origin.request_id, @@ -193,6 +197,7 @@ def _context( retention_expires_at=created_at + ARTIFACT_RETENTION, report_run=report_run, simulation_run_id=simulation_run_id, + cliff_result_id=cliff_result_id, ) @@ -259,3 +264,36 @@ def simulation_run_calculation( payload=simulation.model_dump(mode="json"), context=context.model_dump(mode="json"), ) + + +def cliff_calculation( # noqa: PLR0913 # the run, its cliff calculation and policy + worker: EconomyWorker, + scope: CalculationScope, + origin: CallOrigin, + *, + simulation_run_id: UUID, + cliff_result_id: UUID, + policy: dict[str, Any], +) -> RunCalculation: + """Return the simulation function's input and context for a cliff calculation. + + The input is the simulation run's own, as a standalone run's, whichever + report named the run: the function recalculates the run's simulation + with the cliff variables and writes its cliff gap and share to the cliff + calculation the context names. + """ + simulation = _simulation_input( + worker, + scope, + evaluation_id=simulation_run_id, + simulation_run_id=simulation_run_id, + role=SimulationRole.STANDALONE, + policy=policy, + ) + context = _context( + worker, origin, runs=simulation_run_id, cliff_result_id=cliff_result_id + ) + return RunCalculation( + payload=simulation.model_dump(mode="json"), + context=context.model_dump(mode="json"), + ) 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 14f1f3948..74e24dd67 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 @@ -1,16 +1,16 @@ """What a report or simulation request becomes before and after its rows exist. The submission services (``economy_submissions``, ``budget_window_submissions``) -turn a request into the persistence library's ``EconomyRequest``, refuse what -can't be calculated yet (as the re-run service does for a stored report), -choose what a report stores of the request's -options, the calculation's scope on the default worker's bundle, and the -answer for the report and run a request ended on. +turn a request into the persistence library's ``EconomyRequest``, 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. The re-run service refuses cliffs for a report that +calculates none. """ from __future__ import annotations -from typing import TYPE_CHECKING, Any +from typing import TYPE_CHECKING, Any, Final from policyengine_simulation_persistence import EconomyRequest @@ -33,6 +33,7 @@ from policyengine_simulation_persistence import ( EconomyCatalogRows, FoundEconomyReport, + RecordKind, ReportRunStatus, ) @@ -46,49 +47,47 @@ from policyengine_simulation_entry.economy_workers import EconomyWorker -def refuse_cliffs(request: EconomyReportRequest) -> None: - """Refuse ``include_cliffs: true`` until per-run cliff calculations exist. - - Identical requests share a report and its runs, so a cliff request can't - change what they calculate; C1 · 39 calculates each simulation run's - cliffs on its own instead (C1 · 24's interim answer A). - """ - if request.include_cliffs: - raise _cliffs_refused( - ("body", "include_cliffs"), - "Cliff impacts are not calculated yet: they will be calculated " - "for each simulation run on its own. Send include_cliffs: false.", - ) +# The reports whose re-run calculates no cliffs, as their answers name them. +_REPORTS_WITHOUT_CLIFFS: Final[dict[RecordKind, str]] = { + "budget_window": "A budget-window report", + "household": "A household report", +} -def refuse_stored_cliffs(stored_inputs: Mapping[str, Any]) -> None: - """Refuse re-running a report stored asking for cliffs, until they exist. +def refuse_cliffs_for(kind: RecordKind) -> None: + """Refuse a re-run asking for cliffs of a report kind that calculates none. - 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). + A budget window or a household report has no cliff calculation: only an + economy report's simulation runs do (C1 · 24's answer 4b). """ - 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( + report = _REPORTS_WITHOUT_CLIFFS.get(kind) + if report is None: + return + raise EconomySubmissionUnprocessableError( code="cliffs_not_available", reasons=( - UnprocessableReason(loc=loc, msg=message, type="cliffs_not_available"), + UnprocessableReason( + loc=("body", "include_cliffs"), + msg=( + f"{report} calculates no cliff impacts. Send include_cliffs: false." + ), + type="cliffs_not_available", + ), ), ) +def asks_for_cliffs(*, include_cliffs: bool, stored_inputs: Mapping[str, Any]) -> bool: + """Return whether a report's re-run asks for its runs' cliffs. + + It does when the request sends ``include_cliffs: true``, or when the + report was stored before C1 · 27 asking for cliffs, which its stored + options still hold (the user, 2026-11-17). The stored value is only + read; nothing writes or keys it. + """ + return include_cliffs or stored_inputs.get("include_cliffs") is True + + def stored_options(options: dict[str, Any]) -> dict[str, Any]: """Return what a report stores of a request's options: the SPM selection. @@ -168,7 +167,5 @@ def calculation_scope( region_code=catalog.region.code, dataset=dataset, year=request.year, - options=simulation_options( - include_cliffs=getattr(request, "include_cliffs", False), spm=spm - ), + options=simulation_options(spm=spm), ) diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_rerun_routes.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_rerun_routes.py index bda053bcb..391d651f3 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 @@ -29,10 +29,12 @@ 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 +answers it with no new call. With ``include_cliffs``, an economy report's +re-run starts the cliff calculation of each simulation run its run names +that has none, as a create does; a report stored before C1 · 27 asking for +cliffs asks for them on its re-run too. A budget window's or household +report's re-run asking for cliffs answers 422 ``cliffs_not_available``. +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, and the answer names the record and the run), and the JSON 500. @@ -146,12 +148,13 @@ 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] = { +# A budget window or household report calculates no cliffs, so its re-run +# asking for them is refused. +_CLIFFS_REFUSED: dict[RecordName, str] = { "report": ( - "; or the stored report asks for cliff impacts, which are not " - "calculated yet (cliffs_not_available, located under report)" + "; or a budget window's or household report's re-run asks for " + "cliffs, which neither calculates (cliffs_not_available, located at " + "include_cliffs)" ), "simulation": "", } @@ -195,7 +198,7 @@ def _responses(record: RecordName) -> dict[int | str, dict[str, Any]]: "dynamics cannot be calculated on the current catalog version " "(missing_parameters or overlapping_parameters, located under " f"{record}){_HOUSEHOLD_ANSWERS[record].get(422, '')}" - f"{_STORED_CLIFFS[record]}; nothing was written" + f"{_CLIFFS_REFUSED[record]}; nothing was written" ), "model": EconomyRequestUnprocessable, }, @@ -295,9 +298,12 @@ async def answer( # the route, its record and how to re-run it "call; otherwise each side joins its simulation's run on those " "versions or gets a new one. With force, and always for a report " "created before keys, the report's simulations are calculated " - "again, as an extra run marked forced that nothing joins. A report " - "stored asking for cliff impacts is refused (422 " - "cliffs_not_available). A budget-window report's run is a " + "again, as an extra run marked forced that nothing joins. With " + "include_cliffs, an economy report's re-run starts each of its " + "run's simulation runs' cliff calculation that has none, as a " + "create does; a budget window's or household report's re-run " + "asking for cliffs 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 " 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 c95772da3..c4847f0fe 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 @@ -7,9 +7,9 @@ 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); + does not exist (404), and a budget window's or household report's + re-run asking for cliffs, which neither calculates (422 + ``cliffs_not_available``); 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 @@ -30,7 +30,13 @@ 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. + joined run gets no call: whoever created it started it; +5. for an economy report's re-run asking for cliffs, or of a report stored + before C1 · 27 asking for them (its stored ``include_cliffs``, only + read), finds or creates, in step 3's transaction, the cliff calculation + of each simulation run the report run names, joined or created, and + starts those it created before step 4's call, as a create does + (``cliff_calculation_starts``). 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 @@ -77,7 +83,10 @@ report_run_calculation, simulation_run_calculation, ) -from policyengine_simulation_entry.economy_requests import refuse_stored_cliffs +from policyengine_simulation_entry.economy_requests import ( + asks_for_cliffs, + refuse_cliffs_for, +) from policyengine_simulation_entry.economy_submission_errors import ( STORED_REPORT, STORED_SIMULATION, @@ -247,6 +256,8 @@ async def rerun_report( ) if definition is None: raise EconomyRecordNotFoundError(_REPORT) + if request.include_cliffs: + refuse_cliffs_for(definition.kind) if definition.kind == "household": return await self._rerun_household_report( definition, @@ -254,7 +265,6 @@ async def rerun_report( observability_context=observability_context, ) stored = rerunnable_report(definition) - refuse_stored_cliffs(definition.inputs) window_years = ( complete_window_years(definition) if definition.kind == "budget_window" @@ -302,6 +312,14 @@ async def rerun_report( baseline=self._new_side(stored.baseline.simulation_id), reform=self._new_side(stored.reform.simulation_id), forced=forced, + cliffs=( + self._proposed_cliffs() + if asks_for_cliffs( + include_cliffs=request.include_cliffs, + stored_inputs=definition.inputs, + ) + else None + ), ) scope = rerun_scope( stored.country, @@ -315,32 +333,48 @@ async def rerun_report( lambda: self._store.create_report_rerun(rerun), source=STORED_REPORT, ) - if not found.inserted: - return _joined_report_run(stored, found) - answer = _created_report_run(stored, rerun, found) - calculation = report_run_calculation( - worker, - 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, - # 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, + answer = ( + _created_report_run(stored, rerun, found) + if found.inserted + else _joined_report_run(stored, found) ) - return answer.model_copy(update={"status": status}) + cliffs = None + if found.cliffs is not None: + # Written with the report run, so started before its coordinator. + cliffs = await self._start_cliffs( + worker, + scope, + request_id, + found=found.cliffs, + baseline_policy=inputs.baseline.reform, + reform_policy=inputs.reform.reform, + observability_context=observability_context, + ) + if found.inserted: + status = await self._start_report_run( + worker, + 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, + ), + report_id=report_id, + run_id=rerun.run_id, + # 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, + ) + answer = answer.model_copy(update={"status": status}) + return answer.model_copy(update={"cliffs": cliffs}) async def rerun_simulation( self, 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 5e3e847d8..75a5f3eae 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 @@ -4,7 +4,9 @@ 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`` + and each side's simulation and simulation run. With ``include_cliffs`` + it also finds or creates each side's simulation run's cliff calculation, + starting only those it created, and answers each side's. With ``report_type`` ``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 @@ -149,9 +151,7 @@ "be calculated carry a code: missing_parameters, " "overlapping_parameters, or household_not_calculable for a household " "report's household; no_local_area_dataset refuses data_source on a " - "release with no local-area dataset; a report asking for cliffs " - "(include_cliffs: true) carries cliffs_not_available until each " - "simulation run's own cliff calculation exists" + "release with no local-area dataset" ), "model": EconomyRequestUnprocessable, } @@ -555,7 +555,10 @@ def _submission_routes( "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. " + "report run is started. With include_cliffs, each simulation run " + "the report run names that has no cliff calculation gets one, " + "started; one being calculated or calculated is joined, and " + "include_cliffs is never stored or keyed. " "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, found or created by key as " @@ -581,7 +584,8 @@ def _submission_routes( "(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" + "and started; with include_cliffs, each side's cliff " + "calculation and its status" ) }, 400: _REFUSED, 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 a8b2e2ea8..2a8eba0bc 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 @@ -28,7 +28,12 @@ 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. + status as read; +5. for a report asking for cliffs (``include_cliffs``, never stored or + keyed), finds or creates, in step 3's transaction, the cliff calculation + of each simulation run the report run names, created or joined, and + starts only those it created, before step 4's call + (``cliff_calculation_starts``). A standalone simulation is found or created by key and started the same way, with one simulation run calculated by the country's simulation @@ -62,6 +67,7 @@ EconomySimulationDefinition, KeyedEconomyReport, KeyedEconomySimulation, + ProposedCliffs, ProposedSide, ReportRunStatus, SharedRowNotSettledError, @@ -70,6 +76,10 @@ ) from sqlalchemy.exc import SQLAlchemyError +from policyengine_simulation_entry.cliff_calculation_starts import ( + CliffCalculationRuns, + CliffCalculationStarts, +) from policyengine_simulation_entry.economy_api_models import ( EconomyReportCreated, EconomySimulationCreated, @@ -82,7 +92,6 @@ from policyengine_simulation_entry.economy_requests import ( calculation_scope, economy_request_for, - refuse_cliffs, report_created, stored_options, ) @@ -114,6 +123,7 @@ EconomyReportState, EconomySimulationInputs, EconomySimulationState, + FoundCliffs, FoundEconomyReport, FoundEconomySimulation, ) @@ -122,8 +132,10 @@ EconomyReportRequest, EconomySimulationRequest, PolicyChoice, + ReportCliffs, ) from policyengine_simulation_entry.economy_calculation_inputs import ( + CalculationScope, RunCalculation, ) from policyengine_simulation_entry.economy_workers import ( @@ -139,8 +151,8 @@ CALL_START_TIMEOUT_SECONDS = 10.0 -class EconomyRuns(Protocol): - """The economy reads and writes (``EconomyRunStore``).""" +class EconomyRuns(CliffCalculationRuns, Protocol): + """The economy reads and writes (``EconomyRunStore``), cliff calculations' too.""" def read_report_inputs( self, @@ -259,6 +271,11 @@ def __init__( # noqa: PLR0913 # each seam tests replace self._call_start_timeout_seconds = call_start_timeout_seconds self._new_id = new_id self._clock = clock + self._cliff_starts = CliffCalculationStarts( + store=store, + caller=caller, + call_start_timeout_seconds=call_start_timeout_seconds, + ) async def submit_report( self, @@ -275,9 +292,10 @@ async def submit_report( database cannot be read, or, naming the report, when Modal doesn't confirm the call and the report run was failed; and EconomySubmissionOutcomeUnknownError (500) when the create's commit - failed after its rows were inserted. + failed after its rows were inserted. A report asking for cliffs + writes its runs' cliff calculations with them, and starts the new + ones before the coordinator. """ - refuse_cliffs(request) worker = await self._default_worker(request.country) area_dataset_name = local_area_dataset_name(request, worker) options = request.options() @@ -313,10 +331,22 @@ async def submit_report( population=catalog.population(request.year), versions=worker.versions, inputs=stored_options(options), + cliffs=self._proposed_cliffs() if request.include_cliffs else None, ) found = await self._create( "report", lambda: self._store.find_or_create_report(keyed) ) + cliffs = None + if found.cliffs is not None: + cliffs = await self._start_cliffs( + worker, + scope, + request_id, + found=found.cliffs, + baseline_policy=inputs.baseline.reform, + reform_policy=inputs.reform.reform, + observability_context=observability_context, + ) status = found.run.status if found.run.inserted: calculation = report_run_calculation( @@ -339,7 +369,7 @@ async def submit_report( new_simulation_run_ids=(), observability_context=observability_context, ) - return report_created(found, status) + return report_created(found, status).model_copy(update={"cliffs": cliffs}) async def submit_simulation( self, @@ -431,6 +461,35 @@ async def _read_state[State](self, read: Callable[[], State]) -> State: ) raise _database_unavailable() from None + async def _start_cliffs( # noqa: PLR0913 # what the calls calculate, then each side + self, + worker: EconomyWorker, + scope: CalculationScope, + request_id: str, + *, + found: FoundCliffs, + baseline_policy: dict[str, Any], + reform_policy: dict[str, Any], + observability_context: dict[str, Any] | None, + ) -> ReportCliffs: + """Start the sides' cliff calculations the request inserted; answer each.""" + return await self._cliff_starts.start( + worker, + scope, + self._origin(request_id), + found=found, + baseline_policy=baseline_policy, + reform_policy=reform_policy, + observability_context=observability_context, + ) + + def _proposed_cliffs(self) -> ProposedCliffs: + """Return the IDs the sides' cliff calculations get if a create inserts them. + + One run on both sides gets one calculation, with the baseline's ID. + """ + return ProposedCliffs(baseline_id=self._new_id(), reform_id=self._new_id()) + def _proposed_side(self) -> ProposedSide: """Return the IDs a side's rows get if this request inserts them.""" return ProposedSide( @@ -690,7 +749,6 @@ async def _record_call( "ServiceSettings", "calculation_scope", "economy_request_for", - "refuse_cliffs", "report_created", "simulation_choice", "stored_options", diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_workers.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_workers.py index 438271f38..1f3d83f86 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_workers.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_workers.py @@ -5,7 +5,8 @@ coordinator, each country's simulation function, and the bundle they run. A report run is calculated by the coordinator, which starts a simulation function for each simulation run it doesn't reuse; a standalone simulation -run is calculated by the simulation function alone. Each is called by name +run is calculated by the simulation function alone, and so is a simulation +run's cliff calculation, by the same function in its cliff mode. Each is called by name with ``spawn``, so a route waits only for Modal to accept the call, and is given the run IDs it claims and records, never a Stage 12 evaluation record. @@ -179,6 +180,17 @@ async def start_simulation_run( """Start the standalone simulation run's function; return its call ID.""" ... + async def start_cliff_calculation( + self, + worker: EconomyWorker, + simulation_payload: dict[str, Any], + context_payload: dict[str, Any], + *, + observability_context: dict[str, Any] | None, + ) -> str: + """Start a simulation run's cliff calculation; return its call ID.""" + ... + class ModalEconomyRunCaller: """Start economy calls on Modal, by application and function name.""" @@ -227,6 +239,27 @@ async def start_simulation_run( observability_context=observability_context, ) + async def start_cliff_calculation( + self, + worker: EconomyWorker, + simulation_payload: dict[str, Any], + context_payload: dict[str, Any], + *, + observability_context: dict[str, Any] | None, + ) -> str: + """Start the simulation function on a run's cliff calculation; return its ID. + + The context names the cliff calculation, which the function claims + and records. Raise RuntimeError when Modal returns no call ID. + """ + return await self._spawn( + worker, + worker.simulation_callable, + simulation_payload, + context_payload, + observability_context=observability_context, + ) + async def _spawn( self, worker: EconomyWorker, 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 71fd675ac..3df859006 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 @@ -254,9 +254,12 @@ def rerun_scope( ) -> 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. + ``options`` are the stored report's (``reports.inputs``), of which only + the SPM selection is calculated on: a report stored before C1 · 27 may + hold its request's ``include_cliffs``, which never reaches the + calculation. Raise EconomySubmissionRefusedError + (``dataset_not_in_bundle``) when the default worker's bundle lacks the + stored dataset. """ try: dataset = bundle_dataset(worker, catalog.dataset.name) @@ -273,8 +276,5 @@ def rerun_scope( 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"), - ), + options=simulation_options(spm=options.get("spm")), ) From 7c591174232e8a2b9f63c336c4befc37fc1cbc30 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:04:20 +0400 Subject: [PATCH 05/11] Document include_cliffs starting each side's cliff calculation The Simulation Entrypoint's README describes what a create or re-run asking for cliffs does and answers, and drops the interim 422s; the persistence README names the cliff calculation lookup and its writes; the Stage 12 foundation document says the service now starts each run's cliff calculation. Adds the changelog fragment. Co-Authored-By: Claude Opus 5.5 --- changelog.d/c1-39-include-cliffs.added.md | 1 + .../stage-12-modal-worker-foundation.md | 18 ++++--- .../README.md | 13 ++++- .../policyengine-simulation-entry/README.md | 54 ++++++++++++++----- 4 files changed, 63 insertions(+), 23 deletions(-) create mode 100644 changelog.d/c1-39-include-cliffs.added.md diff --git a/changelog.d/c1-39-include-cliffs.added.md b/changelog.d/c1-39-include-cliffs.added.md new file mode 100644 index 000000000..d54730b25 --- /dev/null +++ b/changelog.d/c1-39-include-cliffs.added.md @@ -0,0 +1 @@ +`POST /reports` and `POST /reports/{report_id}/runs` accept `include_cliffs: true` again: once the request has ended on its report run, created or joined, the Simulation Entrypoint finds or creates the cliff calculation (a row of the Public API's `cliff_impacts`) of each simulation run that report run names, and starts the run's simulation function in its cliff mode only for a calculation it created, so identical requests share one calculation per run. The answer names each side's cliff calculation and its status in `cliffs`. `include_cliffs` is never stored, keyed or passed to the coordinator, and a report stored before keys asking for cliffs is re-run with its runs' cliffs instead of a 422. A budget window's or household report's re-run asking for cliffs is refused with 422 `cliffs_not_available`. diff --git a/docs/migration/stage-12-modal-worker-foundation.md b/docs/migration/stage-12-modal-worker-foundation.md index e267e15d1..3e997ba6b 100644 --- a/docs/migration/stage-12-modal-worker-foundation.md +++ b/docs/migration/stage-12-modal-worker-foundation.md @@ -370,12 +370,13 @@ holds, or one that failed, it returns `{"deduplicated": true, **A simulation run's cliff result** (C1 · 24, answer 4b). Each simulation run can have one cliff result, its cliff gap and cliff share, which every report naming the run reads: a row of API v1's `cliff_impacts`, one per -calculation. Nothing starts one yet. The simulation service is to insert it -pending, start the country's simulation worker (`run_single_simulation_us` or -`run_single_simulation_uk`) with the run's own simulation input, built as a -standalone run's, and a context naming the row +calculation. The simulation service inserts it pending when a report's +create or re-run asks for cliffs (`include_cliffs`, C1 · 39) and the run has +none that hasn't failed, starts the country's simulation worker +(`run_single_simulation_us` or `run_single_simulation_uk`) with the run's own +simulation input, built as a standalone run's, and a context naming the row (`Stage12InvocationContext.cliff_result_id`, left out of a context that names -none, which older workers refuse), and record the call (C1 · 39). The worker +none, which older workers refuse), and records the call. The worker claims the row as a run is claimed, and refuses, failing it with `cliff_result_input_mismatch`, an input that is not the simulation of the row's run on that run's year and versions; the calculation then checks those @@ -412,9 +413,10 @@ policy turns a response on; in the US, the two inputs .py's labour-supply output reads from either side (`self_employment_income`, `weekly_hours_worked`); and never the cliff columns, so a US national run keeps its region-group split. Cliffs are a calculation of each simulation run of -their own (above). A report run asking for them (`include_cliffs: true`) still -fails before any worker starts, with `cliff_impacts_unavailable`, and touches -none of its simulation runs, and its completion never writes `report_runs`' +their own (above), so the simulation service never asks a coordinator for +them: a report run asking for them (`include_cliffs: true`) would fail before +any worker starts, with `cliff_impacts_unavailable`, and touch none of its +simulation runs, and a report run's completion never writes `report_runs`' four cliff columns. The coordinator gives each worker its simulation's stored plan, and keeps the report's own plan, from its pair, for what the diff --git a/libs/policyengine-simulation-persistence/README.md b/libs/policyengine-simulation-persistence/README.md index 528fe58b0..29429451f 100644 --- a/libs/policyengine-simulation-persistence/README.md +++ b/libs/policyengine-simulation-persistence/README.md @@ -215,7 +215,18 @@ 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 or joined. + up or joined. `find_or_insert_cliff_calculations` does the same for each + simulation run's cliff calculation, against `uq_cliff_impacts_unfailed`, + in simulation run ID order: a run's calculation that hasn't failed is + found, and otherwise one is inserted pending with no Modal call. A + keyed report's create, or an economy report's re-run, whose request asks + for cliffs (`KeyedEconomyReport.cliffs`, `NewReportRerun.cliffs`, the + IDs it proposes) runs it on the two simulation runs of the report run it + ended on, in the same transaction (`find_or_insert_report_run_cliffs`), so a + refused calculation writes nothing, and returns each side's calculation + (`FoundCliffs`). `EconomyRunStore.record_cliff_call` and + `fail_unstarted_cliff_calculation` record a calculation's call, or fail + it when Modal refused it, each only while it is pending with no call. - `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 diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index db161ed07..fffa840eb 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -144,8 +144,8 @@ 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 +request's SPM selection in `inputs`; `include_cliffs` is never stored, +keyed or passed to the coordinator. 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 @@ -154,6 +154,30 @@ 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 report asking for cliffs (`include_cliffs: true`) gets them as each +simulation run's own calculation (C1 · 24's answer 4b): a run has one +cliff result, its cliff gap and cliff share, in the Public API's +`cliff_impacts`, which every report naming the run reads. In the +transaction that ends on the report run, created or joined, the service +also finds or creates the cliff calculation of each simulation run that +report run names: a calculation that hasn't failed, pending, running or +succeeded, is joined, and a failed one never counts, so two identical +requests end on one calculation per run, and a request the database +refuses wrote neither. Only for a calculation it created does the service +start the run's simulation function, given the run's own input, as a +standalone run's, and a context naming the calculation (`cliff_result_id`), +and record the call's ID, before the report run's coordinator is started, +so they start even when Modal then refuses the coordinator. The +calculation runs beside its simulation run, whatever that run's state: it +recalculates the simulation from its dataset and policy. The 201 answer +then also has `cliffs`, each side's `cliff_result_id` and `status` +(`pending` or `running` while it is calculated, `succeeded` once it holds +the result; one run on both sides names one calculation twice); without +`include_cliffs` the field is left out. When Modal refuses a calculation's +call, or doesn't confirm it within ten seconds, the service fails that +calculation, answers its side `failed` and the report as usual, and the +next request asking for cliffs starts another. + A request is refused before anything is written: with 400 and a `code` when a row it names is missing (`unknown_region` and `unknown_dynamic` name the caller's own choice, and `unknown_dataset` its region's dataset; @@ -166,9 +190,7 @@ the service's state; see "Local areas"); and with 422 and a `code` when a policy or dynamic sets parameters the catalog version lacks (`missing_parameters`), both set one (`overlapping_parameters`), or the release has no local-area dataset for `data_source` -(`no_local_area_dataset`), 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 +(`no_local_area_dataset`). 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 @@ -184,9 +206,9 @@ exception's text. An economy report created with `data_source: "local_area_dataset"` runs on the bundle's local-area dataset, the one the .py release routes constituencies and local authorities to, in place of its region's dataset. -It is an ordinary report: it returns its full results, cliffs included when -asked, and its constituency and local-authority impacts, and is re-run on -the same dataset. `data_source` is left out unless given (null and any other +It is an ordinary report: it returns its full results and its constituency +and local-authority impacts, its simulation runs' cliffs are calculated when +asked, and it is re-run on the same dataset. `data_source` is left out unless given (null and any other value are refused with 422), and is never stored as an option: the dataset is stored with the report's simulations. Only a UK report whose region is `uk` or one of the four `country/*` nations may ask; any other country or @@ -319,12 +341,16 @@ before keys (C1 · 27), whose simulations have none, is always re-run that way, forced or not: its runs may have been calculated with plans that depended on that report (C1 · 24's interim answer B). The new report run names no trigger (answer 6): the Public API's per-user report-run record -holds it. Such a -report stored asking for cliff impacts -(`include_cliffs: true` in its options) is refused with 422 -`cliffs_not_available`, located at `report.inputs.include_cliffs`, until -cliffs are calculated for each simulation run (C1 · 39; interim answer A). -The service reads the +holds it. The body may also send `include_cliffs`: an economy report's +re-run, joined or created, forced or not, then starts the cliff +calculation of each simulation run its run names that has none, as a +create does (see "Economy reports and simulations"), and answers them in +`cliffs`. A report stored before C1 · 27 asking for cliffs +(`include_cliffs: true` in its options) asks for them on every re-run too; +its stored option is only read, and never reaches the coordinator. A +budget-window or household report's re-run asking for cliffs is refused +with 422 `cliffs_not_available`, located at `include_cliffs`: neither +calculates them. 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 721f775e483ac82d983e75d2072994077b11d316 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:17:32 +0400 Subject: [PATCH 06/11] Test a re-run's cliffs apart from its run, and the lookup's order (failing) From the ORM redo's review: a re-run asking for cliffs returns its report run and their calculations together, leaving FoundReportRun as every other lookup returns it. Also covers the simulation run ID order of the inserts, a request losing the report run taking the winner's runs' calculations, a re-run over two distinct simulation runs, and a refused calculation naming the column that refused it. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_cliff_calculations.py | 184 ++++++++++++++++-- 1 file changed, 166 insertions(+), 18 deletions(-) diff --git a/libs/policyengine-simulation-persistence/tests/test_cliff_calculations.py b/libs/policyengine-simulation-persistence/tests/test_cliff_calculations.py index eee61289f..da77ca878 100644 --- a/libs/policyengine-simulation-persistence/tests/test_cliff_calculations.py +++ b/libs/policyengine-simulation-persistence/tests/test_cliff_calculations.py @@ -36,21 +36,27 @@ ) from policyengine_simulation_persistence import ( CliffImpact, + EconomyRecordReferenceError, EconomyReportDefinition, EconomyRunStore, + FoundReportRun, KeyedEconomyReport, NewReportRerun, ProposedCliffs, ProposedSide, Report, + ReportRun, + ReportRunStatus, RerunSide, SimulationChoice, + SimulationRun, SimulationStatus, find_or_create_economy_report, find_or_insert_cliff_calculations, + find_or_insert_report_run_cliffs, ) from public_api_rows import insert_policy -from sqlalchemy import func, select, text, update +from sqlalchemy import event, func, insert, select, text, update from sqlalchemy.exc import IntegrityError if TYPE_CHECKING: @@ -182,6 +188,65 @@ def test_each_run_named_gets_its_own_cliff_calculation( } +def test_calculations_are_inserted_in_simulation_run_id_order( + public_api_database_url, +) -> None: + """So two transactions never wait for each other in opposite orders.""" + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection) + run_ids = sorted( + insert_simulation_run(connection, economy.population()).simulation_run_id + for _ in range(3) + ) + act_as_the_service(connection) + inserted: list[UUID] = [] + + def record_the_insert( + _connection, _cursor, statement, parameters, _context, _executemany + ) -> None: + if statement.lstrip().startswith("INSERT INTO public.cliff_impacts"): + inserted.append(parameters["simulation_run_id"]) + + event.listen(connection, "before_cursor_execute", record_the_insert) + try: + in_session( + connection, + find_or_insert_cliff_calculations, + {run_id: uuid4() for run_id in reversed(run_ids)}, + ) + finally: + event.remove(connection, "before_cursor_execute", record_the_insert) + + assert inserted == run_ids + + +def test_a_calculation_naming_a_missing_run_names_the_refusing_column( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + act_as_the_service(connection) + missing_runs = FoundReportRun( + id=uuid4(), + inserted=False, + status=ReportRunStatus.PENDING, + baseline_simulation_run_id=uuid4(), + reform_simulation_run_id=uuid4(), + ) + + with pytest.raises(EconomyRecordReferenceError) as refused: + in_session( + connection, + find_or_insert_report_run_cliffs, + missing_runs, + _new_cliffs(), + ) + + assert (refused.value.table_name, refused.value.column_name) == ( + "cliff_impacts", + "simulation_run_id", + ) + + def test_a_failed_cliff_calculation_is_never_joined(public_api_database_url) -> None: with rolled_back_transaction(public_api_database_url) as connection: run_id = _seed_simulation_run(connection) @@ -314,7 +379,7 @@ def test_a_report_created_asking_for_cliffs_inserts_its_runs_calculations_with_i def test_two_identical_creates_asking_for_cliffs_at_once_insert_one_each( committed_engine, committed_catalog ) -> None: - """Review round 2: the second loses the report run and joins its calculations. + """The second waits on the first's rows, then joins its run and calculations. The first holds its transaction open until the second waits on its rows. """ @@ -357,6 +422,74 @@ def second_request() -> None: assert calculations == 1 +def test_a_request_losing_the_report_run_adds_the_winners_runs_calculations( + committed_engine, committed_catalog +) -> None: + """Its savepoint takes back its simulation run; the cliffs follow the winner.""" + economy = committed_catalog + with committed_engine.begin() as connection: + act_as_the_service(connection) + first = in_session( + connection, find_or_create_economy_report, _keyed_report(economy) + ) + with committed_engine.begin() as connection: + connection.execute( + update(SimulationRun) + .where(SimulationRun.id == first.baseline.simulation_run_id) + .values(status=SimulationStatus.FAILED, completed_at=func.now()) + ) + connection.execute( + update(ReportRun) + .where(ReportRun.id == first.run.id) + .values(status=ReportRunStatus.FAILED, completed_at=func.now()) + ) + competing: list[UUID] = [] + proposed = _new_cliffs() + request = _keyed_report(economy, cliffs=proposed) + + 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 + run_id = uuid4() + with committed_engine.begin() as other: + other.execute( + insert(ReportRun).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 = in_session(connection, find_or_create_economy_report, request) + finally: + event.remove( + connection, "before_cursor_execute", create_a_competing_run_first + ) + on_the_proposed_run = _calculations_of( + connection, request.baseline.simulation_run_id + ) + + assert (joined.run.id, joined.run.inserted) == (competing[0], False) + assert joined.cliffs is not None + assert joined.cliffs.baseline.id == proposed.baseline_id + assert joined.cliffs.baseline.simulation_run_id == first.baseline.simulation_run_id + assert on_the_proposed_run == 0 + + def test_a_report_not_asking_for_cliffs_inserts_no_calculation( public_api_database_url, ) -> None: @@ -418,10 +551,13 @@ def test_a_report_whose_calculations_cannot_be_inserted_writes_nothing( def _stored_report_with_a_failed_run( - connection: Connection, economy: EconomyCatalog, store: EconomyRunStore + connection: Connection, + economy: EconomyCatalog, + store: EconomyRunStore, + reform: SimulationChoice = CURRENT_LAW, ) -> FoundEconomyReport: """Create a keyed report and fail its run, so a re-run creates a new one.""" - created = store.find_or_create_report(_keyed_report(economy)) + created = store.find_or_create_report(_keyed_report(economy, reform=reform)) connection.execute(text("RESET ROLE")) connection.execute( text( @@ -439,7 +575,6 @@ def _rerun_of( created: FoundEconomyReport, *, forced: bool = False, - cliffs: ProposedCliffs | None = None, ) -> NewReportRerun: return NewReportRerun( report_id=created.report_id, @@ -449,7 +584,6 @@ def _rerun_of( baseline=RerunSide(created.baseline.simulation_id, uuid4()), reform=RerunSide(created.reform.simulation_id, uuid4()), forced=forced, - cliffs=cliffs, ) @@ -459,28 +593,44 @@ def test_a_rerun_asking_for_cliffs_adds_its_runs_calculations_joined_or_created( """Answer 4b: a re-run on the current versions joins and adds its cliffs.""" 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) store = economy_store_on(connection) - created = _stored_report_with_a_failed_run(connection, economy, store) + created = _stored_report_with_a_failed_run( + connection, economy, store, SimulationChoice(policy_id, None) + ) proposed = _new_cliffs() - rerun = store.create_report_rerun(_rerun_of(economy, created, cliffs=proposed)) - joined = store.create_report_rerun( - _rerun_of(economy, created, cliffs=_new_cliffs()) + rerun = store.create_report_rerun_with_cliffs( + _rerun_of(economy, created), proposed + ) + joined = store.create_report_rerun_with_cliffs( + _rerun_of(economy, created), _new_cliffs() ) - assert rerun.inserted is True - assert rerun.cliffs is not None + assert rerun.run.inserted is True assert (rerun.cliffs.baseline.id, rerun.cliffs.baseline.inserted) == ( proposed.baseline_id, True, ) - assert (joined.id, joined.inserted) == (rerun.id, False) - assert joined.cliffs is not None + assert (rerun.cliffs.reform.id, rerun.cliffs.reform.inserted) == ( + proposed.reform_id, + True, + ) + assert rerun.cliffs.baseline.simulation_run_id == ( + rerun.run.baseline_simulation_run_id + ) + assert rerun.cliffs.reform.simulation_run_id == rerun.run.reform_simulation_run_id + assert rerun.run.baseline_simulation_run_id != rerun.run.reform_simulation_run_id + assert (joined.run.id, joined.run.inserted) == (rerun.run.id, False) assert (joined.cliffs.baseline.id, joined.cliffs.baseline.inserted) == ( proposed.baseline_id, False, ) + assert (joined.cliffs.reform.id, joined.cliffs.reform.inserted) == ( + proposed.reform_id, + False, + ) def test_a_forced_rerun_asking_for_cliffs_adds_its_new_runs_calculations( @@ -491,15 +641,13 @@ def test_a_forced_rerun_asking_for_cliffs_adds_its_new_runs_calculations( act_as_the_service(connection) store = economy_store_on(connection) created = _stored_report_with_a_failed_run(connection, economy, store) - forced = _rerun_of(economy, created, forced=True, cliffs=_new_cliffs()) + forced = _rerun_of(economy, created, forced=True) - rerun = store.create_report_rerun(forced) + rerun = store.create_report_rerun_with_cliffs(forced, _new_cliffs()) unasked = store.create_report_rerun(_rerun_of(economy, created, forced=True)) - assert rerun.cliffs is not None assert rerun.cliffs.baseline.inserted is True assert _calculations_of(connection, forced.baseline.simulation_run_id) == 1 - assert unasked.cliffs is None assert ( _calculations_of( connection, From 02e9f4838f1c1a5cb5b075e42b66dade5ca5254d Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:20:06 +0400 Subject: [PATCH 07/11] Return a re-run's cliffs beside its run, and name their refused column From the ORM redo's review: insert_report_rerun and FoundReportRun stay as every other caller uses them, and a re-run asking for cliffs goes through insert_report_rerun_with_cliffs, which returns its report run and their calculations together (FoundReportRerun). A cliff calculation naming a missing run now names cliff_impacts.simulation_run_id in EconomyRecordReferenceError, and the run classes' comments include it. Co-Authored-By: Claude Opus 5.5 --- .../README.md | 12 ++--- .../__init__.py | 6 +++ .../economy_rerun_records.py | 44 +++++++++------ .../economy_run_records.py | 13 +++-- .../economy_run_store.py | 15 ++++++ .../shared_rows.py | 2 - .../economy_reruns.py | 53 +++++++++++++------ .../tests/economy_rerun_fakes.py | 28 ++++++---- 8 files changed, 120 insertions(+), 53 deletions(-) diff --git a/libs/policyengine-simulation-persistence/README.md b/libs/policyengine-simulation-persistence/README.md index 29429451f..ac10788d4 100644 --- a/libs/policyengine-simulation-persistence/README.md +++ b/libs/policyengine-simulation-persistence/README.md @@ -219,12 +219,12 @@ report and run rows (C1 · 24). These modules do it: simulation run's cliff calculation, against `uq_cliff_impacts_unfailed`, in simulation run ID order: a run's calculation that hasn't failed is found, and otherwise one is inserted pending with no Modal call. A - keyed report's create, or an economy report's re-run, whose request asks - for cliffs (`KeyedEconomyReport.cliffs`, `NewReportRerun.cliffs`, the - IDs it proposes) runs it on the two simulation runs of the report run it - ended on, in the same transaction (`find_or_insert_report_run_cliffs`), so a - refused calculation writes nothing, and returns each side's calculation - (`FoundCliffs`). `EconomyRunStore.record_cliff_call` and + keyed report's create (`KeyedEconomyReport.cliffs`, the IDs it proposes) + or an economy report's re-run (`insert_report_rerun_with_cliffs`) whose + request asks for cliffs runs it on the two simulation runs of the report + run it ended on, in the same transaction + (`find_or_insert_report_run_cliffs`), so a refused calculation writes + nothing, and returns each side's calculation (`FoundCliffs`). `EconomyRunStore.record_cliff_call` and `fail_unstarted_cliff_calculation` record a calculation's call, or fail it when Modal refused it, each only while it is pending with no call. - `keyed_economy_records.py` runs a report's find-or-create in one 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 73af8b9fe..98298aa8d 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py @@ -22,6 +22,7 @@ definition_key, ) from policyengine_simulation_persistence.economy_rerun_records import ( + FoundReportRerun, HouseholdRerunSide, NewHouseholdReportRerun, NewReportRerun, @@ -37,6 +38,7 @@ WindowYearDefinition, insert_household_report_rerun, insert_report_rerun, + insert_report_rerun_with_cliffs, insert_simulation_rerun, insert_window_rerun, lock_reruns_of, @@ -139,6 +141,7 @@ ProposedSide, find_or_create_economy_report, find_or_create_economy_simulation, + find_or_insert_report_run_cliffs, ) from policyengine_simulation_persistence.keyed_household_records import ( FoundHouseholdReport, @@ -260,6 +263,7 @@ "FoundEconomyReport", "FoundEconomySimulation", "FoundHouseholdReport", + "FoundReportRerun", "FoundReportRun", "FoundRow", "FoundSide", @@ -367,6 +371,7 @@ "find_or_insert_cliff_calculations", "find_or_insert_report", "find_or_insert_report_run", + "find_or_insert_report_run_cliffs", "find_or_insert_simulation", "find_or_insert_simulation_run", "find_or_insert_simulation_runs", @@ -374,6 +379,7 @@ "insert_household_job", "insert_household_report_rerun", "insert_report_rerun", + "insert_report_rerun_with_cliffs", "insert_simulation_rerun", "insert_window_rerun", "lock_reruns_of", 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 3fa5f2f5b..612d229a5 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 @@ -114,6 +114,7 @@ ) from policyengine_simulation_persistence.keyed_economy_records import Side from policyengine_simulation_persistence.shared_rows import ( + FoundCliffs, FoundSimulationRun, ProposedCliffs, ) @@ -140,8 +141,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. ``cliffs``, set when the re-run - asks for cliffs, proposes its sides' cliff calculations' IDs. + new run of each side, marked forced. """ report_id: UUID @@ -151,7 +151,6 @@ class NewReportRerun: baseline: RerunSide reform: RerunSide forced: bool = False - cliffs: ProposedCliffs | None = None @property def new_simulation_run_ids(self) -> tuple[UUID, ...]: @@ -163,6 +162,14 @@ def new_simulation_run_ids(self) -> tuple[UUID, ...]: return (self.baseline.simulation_run_id, self.reform.simulation_run_id) +@dataclass(frozen=True) +class FoundReportRerun: + """The report run a re-run asking for cliffs ended on, and its runs' cliffs.""" + + run: FoundReportRun + cliffs: FoundCliffs + + @dataclass(frozen=True) class WindowRerunYear: """One year of a budget window's re-run: its report run and each side's run.""" @@ -304,9 +311,7 @@ def insert_report_rerun(session: Session, rerun: NewReportRerun) -> FoundReportR 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. A re-run asking for cliffs also finds or inserts the cliff - calculation of each simulation run that report run names, joined or - created, and returns them with it. + call. Raise RerunRecordDeletedError when the database refuses the new run's key to the report, which no longer exists, and @@ -314,16 +319,6 @@ def insert_report_rerun(session: Session, rerun: NewReportRerun) -> FoundReportR name, such as a side's simulation; either refusal ends the caller's transaction, or its savepoint. """ - found = _insert_report_rerun_run(session, rerun) - if rerun.cliffs is None: - return found - return replace( - found, cliffs=find_or_insert_report_run_cliffs(session, found, rerun.cliffs) - ) - - -def _insert_report_rerun_run(session: Session, rerun: NewReportRerun) -> FoundReportRun: - """Join or create the re-run's report run, as ``insert_report_rerun`` says.""" versions = rerun.versions if not rerun.forced: lock_reruns_of(session, rerun.report_id) @@ -367,6 +362,21 @@ def _insert_report_rerun_run(session: Session, rerun: NewReportRerun) -> FoundRe return found +def insert_report_rerun_with_cliffs( + session: Session, rerun: NewReportRerun, proposed: ProposedCliffs +) -> FoundReportRerun: + """Join or create the report's run, with its runs' cliff calculations. + + As ``insert_report_rerun``, then, in the same transaction, finds or + inserts the cliff calculation of each simulation run that report run + names, joined or created (``find_or_insert_report_run_cliffs``). + """ + run = insert_report_rerun(session, rerun) + return FoundReportRerun( + run=run, cliffs=find_or_insert_report_run_cliffs(session, run, proposed) + ) + + def _rerun_report_run_row( *, run_id: UUID, report_id: UUID, versions: RunVersions ) -> dict[str, Any]: @@ -620,6 +630,7 @@ def _record_checked(*own_keys: InstrumentedAttribute[Any]) -> Iterator[None]: # The definition reads moved to rerun_definitions; their names stay importable here. __all__ = [ + "FoundReportRerun", "HouseholdRerunSide", "NewHouseholdReportRerun", "NewReportRerun", @@ -635,6 +646,7 @@ def _record_checked(*own_keys: InstrumentedAttribute[Any]) -> Iterator[None]: "WindowYearDefinition", "insert_household_report_rerun", "insert_report_rerun", + "insert_report_rerun_with_cliffs", "insert_simulation_rerun", "insert_window_rerun", "lock_reruns_of", 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 c8bf1f6ec..8bc359d48 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 @@ -69,21 +69,28 @@ from sqlalchemy import ColumnElement from sqlalchemy.orm import Session -# The two classes whose runs a Modal call calculates. +# The classes whose rows a Modal call calculates: runs and cliff calculations. type RunModel = type[SimulationRun | ReportRun | CliffImpact] # PostgreSQL's SQLSTATE for a row naming one that does not exist. FOREIGN_KEY_VIOLATION: Final = "23503" # A report's type, as API v1 reads it. ECONOMY_REPORT_TYPE: Final = "economy" -# Both run tables' statuses use these values. +# These classes' statuses use these values. _PENDING: Final = SimulationStatus.PENDING.value _FAILED: Final = SimulationStatus.FAILED.value # Each foreign key of the tables the service writes, by name: its table and # the first column it constrains. _KEY_COLUMNS: Final = { str(constraint.name): (model.__tablename__, constraint.column_keys[0]) - for model in (Simulation, SimulationRun, Report, ReportRun, BudgetWindowRun) + for model in ( + Simulation, + SimulationRun, + Report, + ReportRun, + BudgetWindowRun, + CliffImpact, + ) for constraint in model.__table_args__ if isinstance(constraint, ForeignKeyConstraint) } 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 6d680b2be..cb7fa440b 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 @@ -35,6 +35,7 @@ ) from policyengine_simulation_persistence.economy_rerun_records import ( insert_report_rerun, + insert_report_rerun_with_cliffs, insert_simulation_rerun, insert_window_rerun, read_report_definition, @@ -74,6 +75,7 @@ from sqlalchemy.orm import Session, sessionmaker from policyengine_simulation_persistence.economy_rerun_records import ( + FoundReportRerun, NewReportRerun, NewSimulationRerun, NewWindowRerun, @@ -98,6 +100,7 @@ from policyengine_simulation_persistence.shared_rows import ( FoundReportRun, FoundSimulationRun, + ProposedCliffs, ) from policyengine_simulation_persistence.tables import ( ReportRunStatus, @@ -241,6 +244,18 @@ def create_report_rerun(self, rerun: NewReportRerun) -> FoundReportRun: """ return self._create(lambda session: insert_report_rerun(session, rerun)) + def create_report_rerun_with_cliffs( + self, rerun: NewReportRerun, cliffs: ProposedCliffs + ) -> FoundReportRerun: + """Join or create the report's run, with its runs' cliff calculations. + + See ``insert_report_rerun_with_cliffs``; raise as + ``create_report_rerun`` does. + """ + return self._create( + lambda session: insert_report_rerun_with_cliffs(session, rerun, cliffs) + ) + 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 cbe19dab1..581158561 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 @@ -101,8 +101,6 @@ class FoundReportRun: status: ReportRunStatus baseline_simulation_run_id: UUID reform_simulation_run_id: UUID | None - # Each side's run's cliff calculation, when the request asked for cliffs. - cliffs: FoundCliffs | None = None @dataclass(frozen=True) 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 c4847f0fe..e0bf41712 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 @@ -114,8 +114,11 @@ BudgetWindowInputs, EconomyReportInputs, FoundBudgetWindow, + FoundCliffs, + FoundReportRerun, FoundReportRun, FoundSimulationRun, + ProposedCliffs, ReportDefinition, SideDefinition, SimulationChoice, @@ -194,6 +197,12 @@ def create_report_rerun(self, rerun: NewReportRerun) -> FoundReportRun: """Join the report's run on the re-run's versions, or create it.""" ... + def create_report_rerun_with_cliffs( + self, rerun: NewReportRerun, cliffs: ProposedCliffs + ) -> FoundReportRerun: + """Join or create the report's run, with its runs' cliff calculations.""" + ... + def create_simulation_rerun(self, rerun: NewSimulationRerun) -> FoundSimulationRun: """Join the simulation's run on the re-run's versions, or create it.""" ... @@ -312,14 +321,14 @@ async def rerun_report( baseline=self._new_side(stored.baseline.simulation_id), reform=self._new_side(stored.reform.simulation_id), forced=forced, - cliffs=( - self._proposed_cliffs() - if asks_for_cliffs( - include_cliffs=request.include_cliffs, - stored_inputs=definition.inputs, - ) - else None - ), + ) + proposed_cliffs = ( + self._proposed_cliffs() + if asks_for_cliffs( + include_cliffs=request.include_cliffs, + stored_inputs=definition.inputs, + ) + else None ) scope = rerun_scope( stored.country, @@ -328,24 +337,20 @@ async def rerun_report( inputs.catalog, options=definition.inputs, ) - found = await self._create_rerun( - _REPORT, - lambda: self._store.create_report_rerun(rerun), - source=STORED_REPORT, - ) + found, found_cliffs = await self._create_report_rerun(rerun, proposed_cliffs) answer = ( _created_report_run(stored, rerun, found) if found.inserted else _joined_report_run(stored, found) ) cliffs = None - if found.cliffs is not None: + if found_cliffs is not None: # Written with the report run, so started before its coordinator. cliffs = await self._start_cliffs( worker, scope, request_id, - found=found.cliffs, + found=found_cliffs, baseline_policy=inputs.baseline.reform, reform_policy=inputs.reform.reform, observability_context=observability_context, @@ -376,6 +381,24 @@ async def rerun_report( answer = answer.model_copy(update={"status": status}) return answer.model_copy(update={"cliffs": cliffs}) + async def _create_report_rerun( + self, rerun: NewReportRerun, proposed_cliffs: ProposedCliffs | None + ) -> tuple[FoundReportRun, FoundCliffs | None]: + """Join or create the report's run, with its cliffs when they're asked for.""" + if proposed_cliffs is None: + run = await self._create_rerun( + _REPORT, + lambda: self._store.create_report_rerun(rerun), + source=STORED_REPORT, + ) + return run, None + found = await self._create_rerun( + _REPORT, + lambda: self._store.create_report_rerun_with_cliffs(rerun, proposed_cliffs), + source=STORED_REPORT, + ) + return found.run, found.cliffs + async def rerun_simulation( self, simulation_id: UUID, diff --git a/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py b/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py index aa4215507..4edac0eb3 100644 --- a/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py +++ b/projects/policyengine-simulation-entry/tests/economy_rerun_fakes.py @@ -6,7 +6,7 @@ from __future__ import annotations -from dataclasses import dataclass, field, replace +from dataclasses import dataclass, field from typing import TYPE_CHECKING, Any, NoReturn from uuid import UUID @@ -26,6 +26,7 @@ EconomyReportInputs, EconomySimulationInputs, FoundBudgetWindow, + FoundReportRerun, FoundReportRun, FoundSide, FoundSimulationRun, @@ -51,6 +52,7 @@ NewReportRerun, NewSimulationRerun, NewWindowRerun, + ProposedCliffs, ) REPORT_ID = UUID("00000000-0000-4000-8000-0000000000a1") @@ -248,18 +250,22 @@ def create_window_rerun(self, rerun: NewWindowRerun) -> FoundBudgetWindow: def create_report_rerun(self, rerun: NewReportRerun) -> FoundReportRun: if self.rerun_failure is not None: raise self.rerun_failure - if rerun.cliffs is not None and self.cliff_failure is not None: - raise self.cliff_failure self.report_reruns.append(rerun) - found = self._report_rerun_run(rerun) - if rerun.cliffs is None or found.reform_simulation_run_id is None: - return found - return replace( - found, + return self._report_rerun_run(rerun) + + def create_report_rerun_with_cliffs( + self, rerun: NewReportRerun, cliffs: ProposedCliffs + ) -> FoundReportRerun: + if self.cliff_failure is not None: + raise self.cliff_failure + run = self.create_report_rerun(rerun) + assert run.reform_simulation_run_id is not None + return FoundReportRerun( + run=run, cliffs=self.found_cliffs( - rerun.cliffs, - baseline_simulation_run_id=found.baseline_simulation_run_id, - reform_simulation_run_id=found.reform_simulation_run_id, + cliffs, + baseline_simulation_run_id=run.baseline_simulation_run_id, + reform_simulation_run_id=run.reform_simulation_run_id, ), ) From f2382482c94242a826f024a5f68585016b1a5933 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:58:36 +0400 Subject: [PATCH 08/11] Test that a cliff call's problems are logged naming its row (failing) Each log of a cliff calculation's unconfirmed call, unrecorded call ID or unwritten failure carries the error type and the cliff_impacts row through log_extra, the only fields that reach Cloud Logging. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_economy_submissions.py | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/projects/policyengine-simulation-entry/tests/test_economy_submissions.py b/projects/policyengine-simulation-entry/tests/test_economy_submissions.py index fccaf78da..23050df03 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_submissions.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_submissions.py @@ -1144,3 +1144,50 @@ def test_an_unconfirmed_call_is_logged_naming_its_report_or_simulation( "database_table": expected_table, "database_row_id": str(unavailable.value.record_id), } + + +@pytest.mark.parametrize( + ("store_changes", "cliff_failure", "event"), + [ + ({}, ConnectionError("refused"), "cliff_calculation_call_unconfirmed"), + ( + {"fail_failure": DATABASE_ERROR}, + ConnectionError("refused"), + "cliff_calculation_not_failed", + ), + ( + {"record_failure": DATABASE_ERROR}, + None, + "cliff_calculation_call_not_recorded", + ), + ], + ids=["unconfirmed", "not-failed", "not-recorded"], +) +def test_a_cliff_calculations_call_problem_is_logged_naming_its_row( + caplog, store_changes, cliff_failure, event +) -> None: + store = FakeStore(**store_changes) + caller = FakeCaller(cliff_failure=cliff_failure) + + with caplog.at_level(logging.INFO): + created = _submit_report( + service(store, caller=caller), report_request(include_cliffs=True) + ) + + assert created.cliffs is not None + logged = { + item.policyengine_attributes["database_row_id"]: item.policyengine_attributes + for item in caplog.records + if item.getMessage() == event + } + expected_error = "ConnectionError" if cliff_failure else "OperationalError" + if event == "cliff_calculation_not_failed": + expected_error = "OperationalError" + assert logged == { + str(side.cliff_result_id): { + "error_type": expected_error, + "database_table": "cliff_impacts", + "database_row_id": str(side.cliff_result_id), + } + for side in (created.cliffs.baseline, created.cliffs.reform) + } From 0a8115fcb06dca2e325db92a5ae47b763ffae701 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Thu, 19 Nov 2026 03:01:41 +0400 Subject: [PATCH 09/11] Log a cliff call's problems through log_extra, naming its row The three logs of a cliff calculation's call now reach Cloud Logging, with the error's type and the cliff_impacts row, as #1092's rule requires of every Simulation Entrypoint log. Co-Authored-By: Claude Opus 5.5 --- .../cliff_calculation_starts.py | 28 +++++++++++-------- 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/cliff_calculation_starts.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/cliff_calculation_starts.py index 31fa0f977..ec823f75b 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/cliff_calculation_starts.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/cliff_calculation_starts.py @@ -33,6 +33,10 @@ import logging from typing import TYPE_CHECKING, Any, Protocol +from policyengine_simulation_observability.log_records import ( + database_row_attributes, + log_extra, +) from policyengine_simulation_persistence import SimulationStatus from sqlalchemy.exc import SQLAlchemyError @@ -198,10 +202,10 @@ async def _start_one( # noqa: PLR0913 # what the call calculates, then its row # The function claims a pending calculation with no call ID itself. logger.warning( "cliff_calculation_call_not_recorded", - extra={ - "cliff_result_id": str(cliff_result_id), - "error_type": type(error).__name__, - }, + extra=log_extra( + error_type=type(error).__name__, + **database_row_attributes("cliff_impacts", cliff_result_id), + ), ) return SimulationStatus.PENDING return SimulationStatus.PENDING if status is None else status @@ -218,10 +222,10 @@ async def _fail_unconfirmed( # The log names the error type only; its text could repeat request data. logger.error( "cliff_calculation_call_unconfirmed", - extra={ - "cliff_result_id": str(cliff_result_id), - "error_type": type(error).__name__, - }, + extra=log_extra( + error_type=type(error).__name__, + **database_row_attributes("cliff_impacts", cliff_result_id), + ), ) message = ( "modal_call_refused: Modal did not accept the cliff calculation's " @@ -234,9 +238,9 @@ async def _fail_unconfirmed( except SQLAlchemyError as write_error: logger.warning( "cliff_calculation_not_failed", - extra={ - "cliff_result_id": str(cliff_result_id), - "error_type": type(write_error).__name__, - }, + extra=log_extra( + error_type=type(write_error).__name__, + **database_row_attributes("cliff_impacts", cliff_result_id), + ), ) return False From 0c5206d7262b5df38ee7376f7c3939a90eb20e52 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Thu, 19 Nov 2026 20:45:31 +0400 Subject: [PATCH 10/11] Call API v1 by its name in the cliff calculations' text Co-Authored-By: Claude Opus 5.5 --- changelog.d/c1-39-include-cliffs.added.md | 2 +- .../tests/test_cliff_calculations.py | 4 ++-- projects/policyengine-simulation-entry/README.md | 2 +- .../policyengine_simulation_entry/cliff_calculation_starts.py | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/changelog.d/c1-39-include-cliffs.added.md b/changelog.d/c1-39-include-cliffs.added.md index d54730b25..3cdf7b86f 100644 --- a/changelog.d/c1-39-include-cliffs.added.md +++ b/changelog.d/c1-39-include-cliffs.added.md @@ -1 +1 @@ -`POST /reports` and `POST /reports/{report_id}/runs` accept `include_cliffs: true` again: once the request has ended on its report run, created or joined, the Simulation Entrypoint finds or creates the cliff calculation (a row of the Public API's `cliff_impacts`) of each simulation run that report run names, and starts the run's simulation function in its cliff mode only for a calculation it created, so identical requests share one calculation per run. The answer names each side's cliff calculation and its status in `cliffs`. `include_cliffs` is never stored, keyed or passed to the coordinator, and a report stored before keys asking for cliffs is re-run with its runs' cliffs instead of a 422. A budget window's or household report's re-run asking for cliffs is refused with 422 `cliffs_not_available`. +`POST /reports` and `POST /reports/{report_id}/runs` accept `include_cliffs: true` again: once the request has ended on its report run, created or joined, the Simulation Entrypoint finds or creates the cliff calculation (a row of API v1's `cliff_impacts`) of each simulation run that report run names, and starts the run's simulation function in its cliff mode only for a calculation it created, so identical requests share one calculation per run. The answer names each side's cliff calculation and its status in `cliffs`. `include_cliffs` is never stored, keyed or passed to the coordinator, and a report stored before keys asking for cliffs is re-run with its runs' cliffs instead of a 422. A budget window's or household report's re-run asking for cliffs is refused with 422 `cliffs_not_available`. diff --git a/libs/policyengine-simulation-persistence/tests/test_cliff_calculations.py b/libs/policyengine-simulation-persistence/tests/test_cliff_calculations.py index da77ca878..d4edc24e1 100644 --- a/libs/policyengine-simulation-persistence/tests/test_cliff_calculations.py +++ b/libs/policyengine-simulation-persistence/tests/test_cliff_calculations.py @@ -2,8 +2,8 @@ A request asking for cliffs (``include_cliffs``) gets one cliff calculation per simulation run it names that has none that hasn't failed (C1 · 24's -answer 4b, the ``cliff_impacts`` design). These run against a database the -Public API's own v2 migration chain built, as the simulation service's role. +answer 4b, the ``cliff_impacts`` design). These run against a database +API v1's own v2 migration chain built, as the simulation service's role. Most run in a transaction rolled back afterwards; the test of two transactions commits its rows under a catalog of a country no other test uses, and deletes them afterwards. diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index fffa840eb..71b74ac7f 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -156,7 +156,7 @@ whose run this request didn't create. A report asking for cliffs (`include_cliffs: true`) gets them as each simulation run's own calculation (C1 · 24's answer 4b): a run has one -cliff result, its cliff gap and cliff share, in the Public API's +cliff result, its cliff gap and cliff share, in API v1's `cliff_impacts`, which every report naming the run reads. In the transaction that ends on the report run, created or joined, the service also finds or creates the cliff calculation of each simulation run that diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/cliff_calculation_starts.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/cliff_calculation_starts.py index ec823f75b..0fada3c52 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/cliff_calculation_starts.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/cliff_calculation_starts.py @@ -2,7 +2,7 @@ A simulation run has one cliff result, its cliff gap and cliff share, which every report naming the run reads: cliffs are a calculation of the run, not -of any report (C1 · 24's answer 4b, the Public API's ``cliff_impacts``). +of any report (C1 · 24's answer 4b, API v1's ``cliff_impacts``). ``include_cliffs`` is a request option, never stored or keyed. A create or re-run asking for cliffs ends on a report run as any other does, and in the same transaction finds or creates the cliff calculation of each simulation From 49858c366aa48308f3b43d1fd45aa7b1cd179a58 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Thu, 19 Nov 2026 20:50:51 +0400 Subject: [PATCH 11/11] State each cliff log case's error, and catch a row logged twice Co-Authored-By: Claude Opus 5.5 --- .../tests/test_economy_submissions.py | 48 +++++++++++-------- 1 file changed, 29 insertions(+), 19 deletions(-) diff --git a/projects/policyengine-simulation-entry/tests/test_economy_submissions.py b/projects/policyengine-simulation-entry/tests/test_economy_submissions.py index 23050df03..9b7f7a33f 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_submissions.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_submissions.py @@ -1147,24 +1147,31 @@ def test_an_unconfirmed_call_is_logged_naming_its_report_or_simulation( @pytest.mark.parametrize( - ("store_changes", "cliff_failure", "event"), + ("store_changes", "cliff_failure", "event", "expected_error"), [ - ({}, ConnectionError("refused"), "cliff_calculation_call_unconfirmed"), + ( + {}, + ConnectionError("refused"), + "cliff_calculation_call_unconfirmed", + "ConnectionError", + ), ( {"fail_failure": DATABASE_ERROR}, ConnectionError("refused"), "cliff_calculation_not_failed", + "OperationalError", ), ( {"record_failure": DATABASE_ERROR}, None, "cliff_calculation_call_not_recorded", + "OperationalError", ), ], ids=["unconfirmed", "not-failed", "not-recorded"], ) def test_a_cliff_calculations_call_problem_is_logged_naming_its_row( - caplog, store_changes, cliff_failure, event + caplog, store_changes, cliff_failure, event, expected_error ) -> None: store = FakeStore(**store_changes) caller = FakeCaller(cliff_failure=cliff_failure) @@ -1175,19 +1182,22 @@ def test_a_cliff_calculations_call_problem_is_logged_naming_its_row( ) assert created.cliffs is not None - logged = { - item.policyengine_attributes["database_row_id"]: item.policyengine_attributes - for item in caplog.records - if item.getMessage() == event - } - expected_error = "ConnectionError" if cliff_failure else "OperationalError" - if event == "cliff_calculation_not_failed": - expected_error = "OperationalError" - assert logged == { - str(side.cliff_result_id): { - "error_type": expected_error, - "database_table": "cliff_impacts", - "database_row_id": str(side.cliff_result_id), - } - for side in (created.cliffs.baseline, created.cliffs.reform) - } + logged_rows = sorted( + ( + item.policyengine_attributes + for item in caplog.records + if item.getMessage() == event + ), + key=lambda attributes: attributes["database_row_id"], + ) + assert logged_rows == sorted( + ( + { + "error_type": expected_error, + "database_table": "cliff_impacts", + "database_row_id": str(side.cliff_result_id), + } + for side in (created.cliffs.baseline, created.cliffs.reform) + ), + key=lambda attributes: attributes["database_row_id"], + )