From fa9f6c0916bb8132f82dc46fbea0e12c000c472a Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Tue, 17 Nov 2026 19:22:38 +0400 Subject: [PATCH 01/18] Test reading report cliffs from simulation runs' cliff calculations (failing) A report run's cliff impact comes from its two simulation runs' cliff_impacts rows, not from report_runs' four cliff columns, and an economy report read says how far each side's cliff calculation has got (cliffs). The fixtures store a result's cliffs as each simulation run's succeeded calculation. Co-Authored-By: Claude Opus 5.5 --- tests/fixtures/economy_results.py | 48 ++- tests/integration/stored_report_rows.py | 37 ++ .../integration/test_v2_report_cliff_reads.py | 269 +++++++++++++++ tests/integration/test_v2_report_creation.py | 27 ++ tests/unit/v2/stored_report_support.py | 7 + tests/unit/v2/test_economy_result_rebuild.py | 60 +++- tests/unit/v2/test_report_cliff_reads.py | 315 ++++++++++++++++++ tests/unit/v2/test_report_read_routes.py | 80 +++++ 8 files changed, 826 insertions(+), 17 deletions(-) create mode 100644 tests/integration/test_v2_report_cliff_reads.py create mode 100644 tests/unit/v2/test_report_cliff_reads.py diff --git a/tests/fixtures/economy_results.py b/tests/fixtures/economy_results.py index d5ee9f6a4..df75f45d8 100644 --- a/tests/fixtures/economy_results.py +++ b/tests/fixtures/economy_results.py @@ -7,14 +7,20 @@ its rows is tested against the same mapping. Its ``withheld_area_codes`` rows follow the writer as PolicyEngine/policyengine-sim-api#1068 changes it (``46c38f07``): one row per code a result's ``constituency_withheld_codes`` -and ``local_authority_withheld_codes`` list. Each row is a dict of the -table's columns; ``id`` and ``created_at`` are left for the caller. +and ``local_authority_withheld_codes`` list. A result's ``cliff_impact`` is +not the report run's: each side's simulation run stores its own succeeded +cliff calculation (``cliff_impacts``, which sim's cliff calculation writes, +not that writer), and the report run's four cliff columns stay null, as the +writer leaves them from PolicyEngine/policyengine-sim-api's C1 · 38 on. Each +row is a dict of the table's columns; ``id`` and ``created_at`` are left for +the caller. """ from __future__ import annotations import copy from dataclasses import dataclass +from datetime import UTC, datetime, timedelta from typing import TYPE_CHECKING, Any if TYPE_CHECKING: @@ -372,18 +378,7 @@ def economy_result_rows( "baseline_simulation_run_id": run_ids.baseline_simulation_run_id, "reform_simulation_run_id": run_ids.reform_simulation_run_id, } - cliffs = output.get("cliff_impact") report_run_columns = { - "baseline_cliff_gap": None - if cliffs is None - else cliffs["baseline"]["cliff_gap"], - "baseline_cliff_share": ( - None if cliffs is None else cliffs["baseline"]["cliff_share"] - ), - "reform_cliff_gap": None if cliffs is None else cliffs["reform"]["cliff_gap"], - "reform_cliff_share": None - if cliffs is None - else cliffs["reform"]["cliff_share"], "spm_provenance": output.get("spm_provenance"), "data_version": output["data_version"], } @@ -406,10 +401,37 @@ def economy_result_rows( output.get("local_authority_impact"), report_keys, "local_authority" ), "withheld_area_codes": _withheld_rows(output, report_keys), + "cliff_impacts": _cliff_rows(output, run_ids), }, ) +# When a stored cliff calculation started and finished. +CLIFF_CALCULATION_STARTED_AT = datetime(2026, 11, 17, 9, tzinfo=UTC) +CLIFF_CALCULATION_COMPLETED_AT = CLIFF_CALCULATION_STARTED_AT + timedelta(minutes=1) + + +def _cliff_rows(output: dict[str, Any], run_ids: RunIds) -> list[dict[str, Any]]: + """Return each simulation run's succeeded cliff calculation, if it has cliffs.""" + cliffs = output.get("cliff_impact") + if cliffs is None: + return [] + return [ + { + "simulation_run_id": simulation_run_id, + "status": "succeeded", + "started_at": CLIFF_CALCULATION_STARTED_AT, + "completed_at": CLIFF_CALCULATION_COMPLETED_AT, + "cliff_gap": cliffs[side]["cliff_gap"], + "cliff_share": cliffs[side]["cliff_share"], + } + for side, simulation_run_id in ( + ("baseline", run_ids.baseline_simulation_run_id), + ("reform", run_ids.reform_simulation_run_id), + ) + ] + + def _labor_supply_rows(output: dict[str, Any], run_ids: RunIds) -> list[dict[str, Any]]: response = output.get("labor_supply_response") if response is None: diff --git a/tests/integration/stored_report_rows.py b/tests/integration/stored_report_rows.py index 9c5c16f9a..53848196c 100644 --- a/tests/integration/stored_report_rows.py +++ b/tests/integration/stored_report_rows.py @@ -429,6 +429,43 @@ def store_report_run( return run_ids +def store_cliff_calculation( # noqa: PLR0913 # the connection, the run and its status, then each column a test sets + connection: Connection, + simulation_run_id: UUID, + status: str, + *, + created_at: datetime = STARTED_AT, + error_message: str | None = None, + cliff_gap: float | None = None, + cliff_share: float | None = None, +) -> UUID: + """Store one cliff calculation of the simulation run, as sim and its worker do. + + A finished calculation has a completion time; a succeeded one needs + ``cliff_gap`` and ``cliff_share``, a failed one an ``error_message``. + """ + calculation_id = uuid4() + insert_row( + connection, + "cliff_impacts", + id=calculation_id, + created_at=created_at, + updated_at=created_at, + simulation_run_id=simulation_run_id, + status=status, + error_message=error_message, + started_at=None if status == "pending" else created_at, + completed_at=( + created_at + timedelta(minutes=1) + if status in {"succeeded", "failed"} + else None + ), + cliff_gap=cliff_gap, + cliff_share=cliff_share, + ) + return calculation_id + + def store_budget_window_run( connection: Connection, catalog: CatalogRows, diff --git a/tests/integration/test_v2_report_cliff_reads.py b/tests/integration/test_v2_report_cliff_reads.py new file mode 100644 index 000000000..f8c423bc0 --- /dev/null +++ b/tests/integration/test_v2_report_cliff_reads.py @@ -0,0 +1,269 @@ +"""Read a v2 report's cliffs from its simulation runs' cliff calculations. + +The routes run as the Public API's runtime role, so the tests prove its +``SELECT`` on ``cliff_impacts`` covers the read (rule +``api.v2.runtime-privileges-tested-as-runtime-role``). The simulation +service inserts a run's cliff calculations and its Modal worker finishes +them; here the database owner stores them, commits them, and the catalog's +deletion removes them with their runs. +""" + +from __future__ import annotations + +import json +from datetime import timedelta +from typing import TYPE_CHECKING, Any + +import pytest +from alembic import command +from alembic.config import Config +from fastapi.testclient import TestClient +from flask import Flask +from sqlalchemy import create_engine, text +from sqlalchemy.orm import sessionmaker +from sqlalchemy.pool import NullPool +from sqlmodel import Session + +from policyengine_api.asgi_factory import create_asgi_app +from policyengine_api.constants import REPO +from policyengine_api.fastapi_routes.dependencies import NativeRouteDependencies +from policyengine_api.migration_flags import ( + RouteImplementation, + RouteImplementationSettings, +) +from policyengine_api.services.v2.simulation_service.types import PackageVersions +from policyengine_api.services.v2.stored_reports.database_session import ( + StoredReportDatabaseSession, +) +from policyengine_api.services.v2.stored_reports.services import V2StoredReportService +from tests.fixtures.economy_results import uk_economy_result, us_economy_result +from tests.integration.stored_report_rows import ( + STARTED_AT, + RunSettings, + delete_catalog, + store_catalog, + store_cliff_calculation, + store_report, + store_report_run, +) + +if TYPE_CHECKING: + from collections.abc import Iterator + + from sqlalchemy import Engine + + from tests.integration.stored_report_rows import CatalogRows + +CURRENT_VERSIONS = {"country_package_version": "1.5.0", "policyengine_version": "4.2.0"} +FAILURE = "cliff_calculation_failed: the calculation raised an error" + + +def current_versions(country_id: str) -> PackageVersions: + return PackageVersions(**CURRENT_VERSIONS) + + +@pytest.fixture +def owner_engine(disposable_v2_database_url: str) -> Iterator[Engine]: + command.upgrade(Config(str(REPO / "alembic-v2.ini")), "head") + engine = create_engine(disposable_v2_database_url, poolclass=NullPool) + yield engine + engine.dispose() + + +@pytest.fixture +def catalogs(owner_engine: Engine) -> Iterator[dict[str, CatalogRows]]: + """Store a US and a UK catalog, and delete them and their reports after.""" + with owner_engine.begin() as connection: + stored = { + country: store_catalog(connection, country) for country in ("us", "uk") + } + yield stored + with owner_engine.begin() as connection: + for catalog in stored.values(): + delete_catalog(connection, catalog) + + +@pytest.fixture +def client(managed_v2_roles, v2_engine_as_role) -> Iterator[TestClient]: + """Serve the report routes as the runtime role.""" + runtime_engine = v2_engine_as_role(managed_v2_roles.runtime, poolclass=NullPool) + sessions = sessionmaker(runtime_engine, class_=Session) + dependencies = NativeRouteDependencies( + readiness_probe=lambda: True, + gateway_client_factory=lambda: None, + metadata_reader_factory=lambda: None, + v2_stored_report_service_factory=lambda: V2StoredReportService( + StoredReportDatabaseSession(sessions), current_versions=current_versions + ), + ) + settings = RouteImplementationSettings( + health=RouteImplementation.FLASK_FALLBACK, + specification=RouteImplementation.FLASK_FALLBACK, + metadata=RouteImplementation.FLASK_FALLBACK, + ) + yield TestClient( + create_asgi_app( + Flask(__name__), dependencies=dependencies, route_settings=settings + ) + ) + runtime_engine.dispose() + + +def read_report(client: TestClient, report_id: object, country: str) -> Any: + response = client.get(f"/v2/reports/{report_id}?country_id={country}") + assert response.status_code == 200, response.text + return response.json()["result"]["item"] + + +def test_a_succeeded_run_reads_its_simulation_runs_cliff_results( + owner_engine: Engine, catalogs: dict[str, CatalogRows], client: TestClient +) -> None: + catalog = catalogs["us"] + output = us_economy_result() + with owner_engine.begin() as connection: + report = store_report(connection, catalog) + # The result's cliff impact is stored as each simulation run's + # succeeded cliff calculation. + store_report_run( + connection, + catalog, + report, + RunSettings(versions=CURRENT_VERSIONS), + result=output, + ) + + item = read_report(client, report.report_id, "us") + + assert item["result"]["cliff_impact"] == json.loads( + json.dumps(output["cliff_impact"]) + ) + assert item["cliffs"] == { + "status": "succeeded", + "baseline": {"status": "succeeded", "error_message": None}, + "reform": {"status": "succeeded", "error_message": None}, + } + + +def test_a_report_runs_own_cliff_columns_are_not_read( + owner_engine: Engine, catalogs: dict[str, CatalogRows], client: TestClient +) -> None: + catalog = catalogs["uk"] + with owner_engine.begin() as connection: + report = store_report(connection, catalog) + run_ids = store_report_run( + connection, + catalog, + report, + RunSettings(versions=CURRENT_VERSIONS), + result=uk_economy_result(), + ) + # As a report run stored its cliffs before C1 · 38. + connection.execute( + text( + "UPDATE report_runs SET baseline_cliff_gap = 1.0, " + "baseline_cliff_share = 0.1, reform_cliff_gap = 2.0, " + "reform_cliff_share = 0.2 WHERE id = :id" + ), + {"id": run_ids.report_run_id}, + ) + + item = read_report(client, report.report_id, "uk") + + assert item["status"] == "succeeded" + assert item["result"]["cliff_impact"] is None + assert item["cliffs"]["status"] == "not_calculated" + + +def test_a_run_still_calculating_reads_each_sides_cliff_progress( + owner_engine: Engine, catalogs: dict[str, CatalogRows], client: TestClient +) -> None: + catalog = catalogs["us"] + with owner_engine.begin() as connection: + report = store_report(connection, catalog) + run_ids = store_report_run( + connection, + catalog, + report, + RunSettings(versions=CURRENT_VERSIONS, status="running"), + ) + store_cliff_calculation( + connection, run_ids.baseline_simulation_run_id, "running" + ) + # A failed calculation never counts: the newer pending one is read. + store_cliff_calculation( + connection, + run_ids.reform_simulation_run_id, + "failed", + error_message=FAILURE, + ) + store_cliff_calculation( + connection, + run_ids.reform_simulation_run_id, + "pending", + created_at=STARTED_AT + timedelta(minutes=5), + ) + + item = read_report(client, report.report_id, "us") + + assert item["result"] is None + assert item["cliffs"] == { + "status": "running", + "baseline": {"status": "running", "error_message": None}, + "reform": {"status": "pending", "error_message": None}, + } + + +def test_a_side_whose_calculations_all_failed_says_why_the_newest_failed( + owner_engine: Engine, catalogs: dict[str, CatalogRows], client: TestClient +) -> None: + catalog = catalogs["uk"] + with owner_engine.begin() as connection: + report = store_report(connection, catalog) + run_ids = store_report_run( + connection, + catalog, + report, + RunSettings(versions=CURRENT_VERSIONS), + result=uk_economy_result(), + ) + store_cliff_calculation( + connection, + run_ids.baseline_simulation_run_id, + "succeeded", + cliff_gap=1_000_000.0, + cliff_share=0.02, + ) + store_cliff_calculation( + connection, + run_ids.reform_simulation_run_id, + "failed", + error_message="modal_call_ended: the call ended without a result", + ) + store_cliff_calculation( + connection, + run_ids.reform_simulation_run_id, + "failed", + created_at=STARTED_AT + timedelta(minutes=5), + error_message=FAILURE, + ) + + item = read_report(client, report.report_id, "uk") + + assert item["result"]["cliff_impact"] is None + assert item["cliffs"] == { + "status": "failed", + "baseline": {"status": "succeeded", "error_message": None}, + "reform": {"status": "failed", "error_message": FAILURE}, + } + + +def test_a_report_with_no_run_reads_no_cliffs( + owner_engine: Engine, catalogs: dict[str, CatalogRows], client: TestClient +) -> None: + with owner_engine.begin() as connection: + report = store_report(connection, catalogs["us"]) + + item = read_report(client, report.report_id, "us") + + assert item["status"] == "not_run" + assert item["cliffs"] is None diff --git a/tests/integration/test_v2_report_creation.py b/tests/integration/test_v2_report_creation.py index 7ce1d32b7..6cebf553d 100644 --- a/tests/integration/test_v2_report_creation.py +++ b/tests/integration/test_v2_report_creation.py @@ -63,6 +63,7 @@ RunSettings, delete_catalog, store_catalog, + store_cliff_calculation, store_report, store_report_run, store_simulation, @@ -93,6 +94,8 @@ class StoringSimulationService: With ``answer_unstored``, it answers with IDs it stored nothing for, and keeps them in ``unstored_ids`` (a report's run in ``unstored_run_ids``). + A report with ``include_cliffs`` also gets a pending cliff calculation for + each side's simulation run, as the simulation service starts them. """ engine: Engine @@ -120,6 +123,12 @@ def submit_report(self, report: EconomyReportCreationInput) -> SubmittedReport: stored, RunSettings(versions=CURRENT_VERSIONS, status="pending"), ) + if report.include_cliffs: + for simulation_run_id in ( + run_ids.baseline_simulation_run_id, + run_ids.reform_simulation_run_id, + ): + store_cliff_calculation(connection, simulation_run_id, "pending") return SubmittedReport( report_id=stored.report_id, report_run_id=run_ids.report_run_id ) @@ -246,6 +255,24 @@ def test_a_created_report_is_answered_as_the_tables_hold_it( assert sent.include_cliffs is True +def test_a_report_created_with_cliffs_answers_their_pending_calculations( + owner_engine: Engine, catalog: CatalogRows, runtime_sessions: Any +) -> None: + simulation_service = StoringSimulationService(owner_engine, catalog) + + response = client_for(runtime_sessions, simulation_service).post( + "/v2/reports?country_id=us", json=report_body(catalog.policy_id) + ) + + assert response.status_code == 201, response.text + item = response.json()["result"]["item"] + assert item["cliffs"] == { + "status": "pending", + "baseline": {"status": "pending", "error_message": None}, + "reform": {"status": "pending", "error_message": None}, + } + + def test_a_report_naming_a_policy_the_country_does_not_store_is_not_sent( owner_engine: Engine, catalog: CatalogRows, runtime_sessions: Any ) -> None: diff --git a/tests/unit/v2/stored_report_support.py b/tests/unit/v2/stored_report_support.py index b566275f2..bb3c89757 100644 --- a/tests/unit/v2/stored_report_support.py +++ b/tests/unit/v2/stored_report_support.py @@ -21,6 +21,8 @@ EconomyResult, ) from policyengine_api.services.v2.stored_reports.types import ( + CliffCalculationRead, + ReportCliffsRead, ReportRead, ReportRunRead, ReportSimulationRead, @@ -110,6 +112,11 @@ def report_summary_read(**changes: Any) -> ReportSummaryRead: def report_read(**changes: Any) -> ReportRead: fields = { "result": EconomyResult.model_validate(us_economy_result()), + "cliffs": ReportCliffsRead( + status="succeeded", + baseline=CliffCalculationRead(status="succeeded", error_message=None), + reform=CliffCalculationRead(status="succeeded", error_message=None), + ), **report_summary_fields(), **changes, } diff --git a/tests/unit/v2/test_economy_result_rebuild.py b/tests/unit/v2/test_economy_result_rebuild.py index bc42fb37f..0cbd9f3af 100644 --- a/tests/unit/v2/test_economy_result_rebuild.py +++ b/tests/unit/v2/test_economy_result_rebuild.py @@ -6,7 +6,10 @@ writer itself stored at a named commit (``scripts/generate_economy_result_golden.py``), so a rebuild that matches it reverses the real writer, and a change in the writer fails once the file is -generated again. +generated again. That writer no longer stores cliffs +(PolicyEngine/policyengine-sim-api's C1 · 38): a result's cliff impact comes +from its two simulation runs' cliff calculations, so the golden rows rebuild +their results without one, whatever the report run's four cliff columns hold. """ from __future__ import annotations @@ -21,6 +24,7 @@ from policyengine_api.data.v2.models import ( BudgetSummary, + CliffImpact, CongressionalDistrictImpact, ConstituencyImpact, DecileImpact, @@ -39,6 +43,7 @@ from policyengine_api.services.v2.stored_reports.economy_results.types import ( EconomyResultRows, EconomyResultUnreadableError, + ReportRunCliffRows, ReportRunResultColumns, ) from policyengine_api.spm import SPMComparisonProvenance @@ -69,7 +74,29 @@ "constituency_impacts": ConstituencyImpact, "local_authority_impacts": LocalAuthorityImpact, "withheld_area_codes": WithheldAreaCode, + "cliff_impacts": CliffImpact, } +# The report run's own cliff columns, which no read uses: C1 · 41 drops them. +REPORT_RUN_CLIFF_COLUMNS = ( + "baseline_cliff_gap", + "baseline_cliff_share", + "reform_cliff_gap", + "reform_cliff_share", +) +NO_CLIFF_CALCULATIONS = ReportRunCliffRows(baseline=None, reform=None) + + +def side_calculations( + calculations: tuple[CliffImpact, ...], run_ids: RunIds +) -> ReportRunCliffRows: + """Return each side's cliff calculation among ``calculations``, or none.""" + by_run = { + calculation.simulation_run_id: calculation for calculation in calculations + } + return ReportRunCliffRows( + baseline=by_run.get(run_ids.baseline_simulation_run_id), + reform=by_run.get(run_ids.reform_simulation_run_id), + ) def stored_rows( @@ -99,6 +126,7 @@ def stored_rows( loaded.reverse() tables[table] = tuple(loaded) withheld_area_codes = tables.pop("withheld_area_codes") + cliff_calculations = side_calculations(tables.pop("cliff_impacts"), run_ids) local_area_rows: dict[str, Any] = ( {"on_local_area_dataset": True, "withheld_area_codes": withheld_area_codes} if on_local_area_dataset @@ -112,6 +140,7 @@ def stored_rows( ), baseline_simulation_run_id=run_ids.baseline_simulation_run_id, reform_simulation_run_id=run_ids.reform_simulation_run_id, + cliff_calculations=cliff_calculations, **tables, **local_area_rows, ) @@ -126,7 +155,8 @@ def golden_rows(case: dict[str, Any]) -> EconomyResultRows: """Load one golden case's stored rows as the database connectors read them. Run IDs come back as UUIDs and each row gets a new ID, as the writer - draws them. + draws them. The report run's cliff columns are left out, and neither + side has a cliff calculation. """ run_ids = {key: UUID(value) for key, value in GOLDEN["run_ids"].items()} @@ -143,10 +173,15 @@ def loaded(table: str, row: dict[str, Any]) -> Any: country_id=case["country"], report_run=ReportRunResultColumns( country_package_version=case["output"]["model_version"], - **case["report_run_columns"], + **{ + column: value + for column, value in case["report_run_columns"].items() + if column not in REPORT_RUN_CLIFF_COLUMNS + }, ), baseline_simulation_run_id=run_ids["baseline_simulation_run_id"], reform_simulation_run_id=run_ids["reform_simulation_run_id"], + cliff_calculations=NO_CLIFF_CALCULATIONS, **{ table: tuple(loaded(table, row) for row in rows) for table, rows in case["rows"].items() @@ -162,7 +197,24 @@ def test_rows_the_simulation_services_own_writer_stored_rebuild_its_result( ) -> None: rebuilt = result_transformations.economy_result(golden_rows(case)) - assert rebuilt.model_dump(mode="json", by_alias=True) == case["output"] + assert rebuilt.model_dump(mode="json", by_alias=True) == { + **case["output"], + "cliff_impact": None, + } + + +def test_the_golden_report_runs_cliff_columns_are_not_read() -> None: + case = next( + case for case in GOLDEN["cases"] if case["output"]["cliff_impact"] is not None + ) + assert all( + case["report_run_columns"][column] is not None + for column in REPORT_RUN_CLIFF_COLUMNS + ) + + rebuilt = result_transformations.economy_result(golden_rows(case)) + + assert rebuilt.cliff_impact is None def test_the_golden_rows_cover_the_shapes_the_fixtures_alone_do_not() -> None: diff --git a/tests/unit/v2/test_report_cliff_reads.py b/tests/unit/v2/test_report_cliff_reads.py new file mode 100644 index 000000000..13cd52229 --- /dev/null +++ b/tests/unit/v2/test_report_cliff_reads.py @@ -0,0 +1,315 @@ +"""Read a report run's cliffs from its two simulation runs' cliff calculations. + +Each simulation run has at most one cliff calculation that hasn't failed, and +any number of failed ones (``cliff_impacts``). A side reads its run's +unfailed calculation, else its newest failed one, else none. The report run's +cliff impact is the two sides' results once both have succeeded; ``cliffs`` +says how far each side's calculation has got. +""" + +from __future__ import annotations + +from datetime import UTC, datetime, timedelta +from typing import TYPE_CHECKING, get_args +from uuid import UUID, uuid4 + +import pytest + +from policyengine_api.data.v2.models import CliffImpact as CliffImpactRow +from policyengine_api.data.v2.models import SimulationStatus +from policyengine_api.services.v2.stored_reports.database_connectors import ( + reads_results as result_reads, +) +from policyengine_api.services.v2.stored_reports.economy_results import ( + transformations as result_transformations, +) +from policyengine_api.services.v2.stored_reports.economy_results.types import ( + CliffImpact, + CliffImpactInSimulation, + ReportRunCliffRows, +) +from policyengine_api.services.v2.stored_reports.types import ( + CliffCalculationRead, + CliffCalculationStatusName, + ReportCliffsRead, +) +from tests.unit.v2.sqlite_report_rows import sqlite_sessions + +if TYPE_CHECKING: + from collections.abc import Iterator + + from sqlalchemy.orm import sessionmaker + from sqlmodel import Session + +CALCULATED_AT = datetime(2026, 11, 17, 9, tzinfo=UTC) +FAILURE = "cliff_calculation_failed: the calculation raised an error" + + +def cliff_calculation( + status: SimulationStatus, + *, + simulation_run_id: UUID | None = None, + created_at: datetime = CALCULATED_AT, + cliff_gap: float = 1_200_000_000.0, + cliff_share: float = 0.04, +) -> CliffImpactRow: + """Return a cliff calculation in ``status``, as the table's checks allow it. + + A succeeded one has its two numbers, a failed one its error, and each + finished one its completion time. + """ + finished = status in {SimulationStatus.SUCCEEDED, SimulationStatus.FAILED} + succeeded = status is SimulationStatus.SUCCEEDED + return CliffImpactRow( + id=uuid4(), + created_at=created_at, + updated_at=created_at, + simulation_run_id=uuid4() if simulation_run_id is None else simulation_run_id, + status=status, + error_message=FAILURE if status is SimulationStatus.FAILED else None, + started_at=None if status is SimulationStatus.PENDING else created_at, + completed_at=created_at + timedelta(minutes=1) if finished else None, + cliff_gap=cliff_gap if succeeded else None, + cliff_share=cliff_share if succeeded else None, + ) + + +def side_calculation(status: CliffCalculationStatusName) -> CliffImpactRow | None: + """Return the calculation a side reads for ``status``: none when not calculated.""" + if status == "not_calculated": + return None + return cliff_calculation(SimulationStatus(status)) + + +def side(status: CliffCalculationStatusName) -> CliffCalculationRead: + """Return a side's read in ``status``, with the error only when failed.""" + return CliffCalculationRead( + status=status, error_message=FAILURE if status == "failed" else None + ) + + +@pytest.fixture +def sessions() -> Iterator[sessionmaker[Session]]: + yield from sqlite_sessions() + + +def store_calculations( + sessions: sessionmaker[Session], *calculations: CliffImpactRow +) -> None: + with sessions() as session: + session.add_all(calculations) + session.commit() + + +def test_sides_without_cliff_calculations_are_not_calculated() -> None: + cliffs = result_transformations.report_cliffs( + ReportRunCliffRows(baseline=None, reform=None) + ) + + assert cliffs == ReportCliffsRead( + status="not_calculated", + baseline=side("not_calculated"), + reform=side("not_calculated"), + ) + + +@pytest.mark.parametrize( + "status", + [SimulationStatus.PENDING, SimulationStatus.RUNNING, SimulationStatus.SUCCEEDED], + ids=["pending", "running", "succeeded"], +) +def test_a_side_reads_its_unfailed_calculations_status_without_an_error( + status: SimulationStatus, +) -> None: + calculation = cliff_calculation(status) + + cliffs = result_transformations.report_cliffs( + ReportRunCliffRows(baseline=calculation, reform=calculation) + ) + + assert cliffs.baseline == CliffCalculationRead( + status=status.value, error_message=None + ) + assert cliffs.reform == cliffs.baseline + + +def test_a_failed_side_says_why_its_calculation_failed() -> None: + cliffs = result_transformations.report_cliffs( + ReportRunCliffRows( + baseline=cliff_calculation(SimulationStatus.SUCCEEDED), + reform=cliff_calculation(SimulationStatus.FAILED), + ) + ) + + assert cliffs.reform == CliffCalculationRead(status="failed", error_message=FAILURE) + assert cliffs.baseline == side("succeeded") + + +@pytest.mark.parametrize( + ("baseline", "reform", "overall"), + [ + ("succeeded", "succeeded", "succeeded"), + ("succeeded", "failed", "failed"), + ("running", "failed", "failed"), + ("failed", "not_calculated", "failed"), + ("succeeded", "not_calculated", "not_calculated"), + ("running", "not_calculated", "not_calculated"), + ("succeeded", "running", "running"), + ("pending", "running", "running"), + ("succeeded", "pending", "pending"), + ("pending", "pending", "pending"), + ], +) +def test_the_reports_cliff_status_follows_its_least_finished_side( + baseline: CliffCalculationStatusName, + reform: CliffCalculationStatusName, + overall: CliffCalculationStatusName, +) -> None: + cliffs = result_transformations.report_cliffs( + ReportRunCliffRows( + baseline=side_calculation(baseline), reform=side_calculation(reform) + ) + ) + swapped = result_transformations.report_cliffs( + ReportRunCliffRows( + baseline=side_calculation(reform), reform=side_calculation(baseline) + ) + ) + + assert cliffs == ReportCliffsRead( + status=overall, baseline=side(baseline), reform=side(reform) + ) + assert swapped.status == overall + + +def test_every_side_status_is_one_a_report_can_have() -> None: + assert set(get_args(CliffCalculationStatusName)) == { + "not_calculated", + *(status.value for status in SimulationStatus), + } + + +def test_two_succeeded_sides_give_the_report_runs_cliff_impact() -> None: + cliff_impact = result_transformations.cliff_impact( + ReportRunCliffRows( + baseline=cliff_calculation( + SimulationStatus.SUCCEEDED, cliff_gap=1_200_000_000.0, cliff_share=0.04 + ), + reform=cliff_calculation( + SimulationStatus.SUCCEEDED, cliff_gap=1_100_000_000.0, cliff_share=0.035 + ), + ) + ) + + assert cliff_impact == CliffImpact( + baseline=CliffImpactInSimulation(cliff_gap=1_200_000_000.0, cliff_share=0.04), + reform=CliffImpactInSimulation(cliff_gap=1_100_000_000.0, cliff_share=0.035), + ) + + +@pytest.mark.parametrize( + "unfinished", ["not_calculated", "pending", "running", "failed"] +) +def test_a_side_without_a_result_leaves_the_cliff_impact_null( + unfinished: CliffCalculationStatusName, +) -> None: + succeeded = cliff_calculation(SimulationStatus.SUCCEEDED) + + for rows in ( + ReportRunCliffRows(baseline=succeeded, reform=side_calculation(unfinished)), + ReportRunCliffRows(baseline=side_calculation(unfinished), reform=succeeded), + ): + assert result_transformations.cliff_impact(rows) is None + + +def test_each_side_reads_its_runs_unfailed_calculation_before_a_newer_failed_one( + sessions: sessionmaker[Session], +) -> None: + baseline_run_id, reform_run_id = uuid4(), uuid4() + running = cliff_calculation( + SimulationStatus.RUNNING, simulation_run_id=baseline_run_id + ) + succeeded = cliff_calculation( + SimulationStatus.SUCCEEDED, simulation_run_id=reform_run_id + ) + store_calculations( + sessions, + running, + succeeded, + *( + cliff_calculation( + SimulationStatus.FAILED, + simulation_run_id=run_id, + created_at=CALCULATED_AT + timedelta(hours=1), + ) + for run_id in (baseline_run_id, reform_run_id) + ), + ) + + with sessions() as session: + rows = result_reads.read_cliff_calculations( + session, + baseline_simulation_run_id=baseline_run_id, + reform_simulation_run_id=reform_run_id, + ) + + assert rows.baseline is not None + assert rows.baseline.id == running.id + assert rows.reform is not None + assert rows.reform.id == succeeded.id + + +def test_a_side_with_only_failed_calculations_reads_the_newest( + sessions: sessionmaker[Session], +) -> None: + run_id = uuid4() + failures = [ + cliff_calculation( + SimulationStatus.FAILED, + simulation_run_id=run_id, + created_at=CALCULATED_AT + timedelta(minutes=minutes), + ) + for minutes in (0, 20, 10) + ] + store_calculations(sessions, *failures) + + with sessions() as session: + rows = result_reads.read_cliff_calculations( + session, baseline_simulation_run_id=run_id, reform_simulation_run_id=uuid4() + ) + + assert rows.baseline is not None + assert rows.baseline.id == failures[1].id + assert rows.reform is None + + +def test_another_runs_calculations_are_not_read( + sessions: sessionmaker[Session], +) -> None: + store_calculations(sessions, cliff_calculation(SimulationStatus.SUCCEEDED)) + + with sessions() as session: + rows = result_reads.read_cliff_calculations( + session, + baseline_simulation_run_id=uuid4(), + reform_simulation_run_id=uuid4(), + ) + + assert rows == ReportRunCliffRows(baseline=None, reform=None) + + +def test_one_run_on_both_sides_reads_its_calculation_for_each( + sessions: sessionmaker[Session], +) -> None: + run_id = uuid4() + succeeded = cliff_calculation(SimulationStatus.SUCCEEDED, simulation_run_id=run_id) + store_calculations(sessions, succeeded) + + with sessions() as session: + rows = result_reads.read_cliff_calculations( + session, baseline_simulation_run_id=run_id, reform_simulation_run_id=run_id + ) + + assert rows.baseline is not None + assert rows.baseline.id == succeeded.id + assert rows.reform is rows.baseline diff --git a/tests/unit/v2/test_report_read_routes.py b/tests/unit/v2/test_report_read_routes.py index f9a935d96..455371697 100644 --- a/tests/unit/v2/test_report_read_routes.py +++ b/tests/unit/v2/test_report_read_routes.py @@ -11,6 +11,10 @@ from policyengine_api.services.v2.stored_reports.economy_results.types import ( EconomyResultUnreadableError, ) +from policyengine_api.services.v2.stored_reports.types import ( + CliffCalculationRead, + ReportCliffsRead, +) from policyengine_api.services.v2.stored_reports.validators import ( ReportStorageError, StoredReportNotFoundError, @@ -100,6 +104,82 @@ def test_a_report_without_a_run_answers_with_no_run_and_no_result() -> None: assert item["result"] is None +def test_a_report_answers_how_far_each_sides_cliff_calculation_has_got() -> None: + service = FakeReportService() + service.report = replace( + service.report, + cliffs=ReportCliffsRead( + status="failed", + baseline=CliffCalculationRead(status="succeeded", error_message=None), + reform=CliffCalculationRead( + status="failed", error_message="cliff_share_undefined: no adults" + ), + ), + ) + + item = ( + report_route_client(reports=service) + .get(f"/v2/reports/{REPORT_ID}?country_id=us") + .json()["result"]["item"] + ) + + assert item["cliffs"] == { + "status": "failed", + "baseline": {"status": "succeeded", "error_message": None}, + "reform": { + "status": "failed", + "error_message": "cliff_share_undefined: no adults", + }, + } + + +def test_a_report_without_a_run_answers_no_cliffs() -> None: + service = FakeReportService() + service.report = replace( + service.report, status="not_run", run=None, result=None, cliffs=None + ) + + item = ( + report_route_client(reports=service) + .get(f"/v2/reports/{REPORT_ID}?country_id=us") + .json()["result"]["item"] + ) + + assert item["cliffs"] is None + + +def test_a_listed_report_answers_no_cliffs() -> None: + service = FakeReportService(listed=(report_summary_read(),)) + + response = report_route_client(reports=service).get( + f"/v2/reports?country_id=us&report_id={REPORT_ID}" + ) + + assert response.status_code == 200, response.text + (item,) = response.json()["result"]["items"] + assert "cliffs" not in item + + +def test_the_openapi_document_describes_a_reports_cliffs() -> None: + schemas = report_route_client().get("/openapi.json").json()["components"]["schemas"] + + cliffs = schemas["ReportCliffsItem"] + assert set(cliffs["properties"]) == {"status", "baseline", "reform"} + assert set(cliffs["properties"]["status"]["enum"]) == { + "not_calculated", + "pending", + "running", + "succeeded", + "failed", + } + assert set(schemas["CliffCalculationItem"]["properties"]) == { + "status", + "error_message", + } + assert "cliffs" in schemas["ReportItem"]["required"] + assert "cliffs" not in schemas["ReportSummaryItem"]["properties"] + + @pytest.mark.parametrize( ("error", "status_code", "message"), [ From e689730c8ee2ad3d5b818e5ccc89fcac3352b797 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Tue, 17 Nov 2026 19:28:34 +0400 Subject: [PATCH 02/18] Read report cliffs from simulation runs' cliff calculations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An economy report run's cliff impact is its two simulation runs' succeeded cliff_impacts rows, and no read uses report_runs' four cliff columns any more, so C1 · 41 can drop them. Each side reads its run's calculation that hasn't failed, else its newest failed one. Economy report reads (get, and the create and re-run answers) gain cliffs: an overall status and each side's status and error message, for a run in any status. Co-Authored-By: Claude Opus 5.5 --- .../v2/reports/response_models.py | 46 ++++++++++++++- .../database_connectors/reads_results.py | 58 +++++++++++++++++-- .../economy_results/transformations.py | 52 ++++++++++------- .../stored_reports/economy_results/types.py | 32 ++++++---- .../services/v2/stored_reports/services.py | 37 ++++++++---- .../v2/stored_reports/transformations.py | 58 ++++++++++++++++++- .../services/v2/stored_reports/types.py | 45 +++++++++++++- tests/unit/v2/test_economy_result_rebuild.py | 13 ++++- tests/unit/v2/test_report_cliff_reads.py | 17 +++--- tests/unit/v2/test_report_read_routes.py | 3 +- 10 files changed, 299 insertions(+), 62 deletions(-) diff --git a/policyengine_api/fastapi_routes/v2/reports/response_models.py b/policyengine_api/fastapi_routes/v2/reports/response_models.py index 3b9e3c760..70584effd 100644 --- a/policyengine_api/fastapi_routes/v2/reports/response_models.py +++ b/policyengine_api/fastapi_routes/v2/reports/response_models.py @@ -140,14 +140,58 @@ def from_summary(cls, read: ReportSummaryRead) -> ReportSummaryItem: return cls.model_validate(read) +# How far a side's cliff calculation has got. +CliffCalculationStatus = Literal[ + "not_calculated", "pending", "running", "succeeded", "failed" +] + + +class CliffCalculationItem(StrictReportAPIModel): + """How far one side's cliff calculation of its simulation run has got. + + ``status`` is ``not_calculated`` while the simulation run has no cliff + calculation, ``pending`` or ``running`` while one is under way, + ``succeeded`` once it has its result, and ``failed`` once its newest + calculation failed and none is under way; ``error_message`` then says + why, and is null otherwise. + """ + + status: CliffCalculationStatus + error_message: str | None + + +class ReportCliffsItem(StrictReportAPIModel): + """How far the cliff calculations of the run read's two simulation runs have got. + + A simulation run's cliffs are calculated apart from it, once, when a + create or re-run asks with ``include_cliffs``, and every report naming + the run shares them. ``status`` is ``succeeded`` once both sides are; + otherwise ``failed`` when either side is, else ``not_calculated`` when + either side is, else ``running`` when either side is, else ``pending``. + Running the report again with ``include_cliffs`` starts a new + calculation for each side that is ``not_calculated`` or ``failed``, and + joins one under way. A report naming one simulation run on both sides + gives its calculation for each. + """ + + status: CliffCalculationStatus + baseline: CliffCalculationItem + reform: CliffCalculationItem + + class ReportItem(ReportSummaryItem): """An economy report with its run's result. ``result`` is the single-year economy result, in the format the app reads - today, once the run read has succeeded, and null otherwise. + today, once the run read has succeeded, and null otherwise. Its + ``cliff_impact`` is the two simulation runs' cliff results once ``cliffs`` + is ``succeeded``, and null otherwise. ``cliffs`` says how far their cliff + calculations have got, whatever the run's status, and is null for a + report with no run. """ result: EconomyResult | None + cliffs: ReportCliffsItem | None @classmethod def from_read(cls, read: ReportRead) -> ReportItem: diff --git a/policyengine_api/services/v2/stored_reports/database_connectors/reads_results.py b/policyengine_api/services/v2/stored_reports/database_connectors/reads_results.py index c5285fb41..bec67bdfa 100644 --- a/policyengine_api/services/v2/stored_reports/database_connectors/reads_results.py +++ b/policyengine_api/services/v2/stored_reports/database_connectors/reads_results.py @@ -4,10 +4,12 @@ from typing import TYPE_CHECKING +from sqlalchemy import case from sqlmodel import col, select from policyengine_api.data.v2.models import ( BudgetSummary, + CliffImpact, CongressionalDistrictImpact, ConstituencyImpact, DecileImpact, @@ -18,10 +20,12 @@ LocalAuthorityImpact, Poverty, ProgramStatistics, + SimulationStatus, WithheldAreaCode, ) from policyengine_api.services.v2.stored_reports.economy_results.types import ( EconomyResultRows, + ReportRunCliffRows, ReportRunResultColumns, ) @@ -33,13 +37,57 @@ from policyengine_api.data.v2.models import ReportRun -def read_economy_result_rows( +def _side_cliff_calculation( + session: Session, simulation_run_id: UUID +) -> CliffImpact | None: + """Return the run's unfailed cliff calculation, else its newest failed one. + + A run has at most one calculation that hasn't failed + (``uq_cliff_impacts_unfailed``), so ordering failed ones last reads it + first; among failed ones, the newest is read, the larger ID breaking a + tie in creation time. + """ + return session.exec( + select(CliffImpact) + .where(CliffImpact.simulation_run_id == simulation_run_id) + .order_by( + case((col(CliffImpact.status) == SimulationStatus.FAILED, 1), else_=0), + col(CliffImpact.created_at).desc(), + col(CliffImpact.id).desc(), + ) + .limit(1) + ).first() + + +def read_cliff_calculations( + session: Session, + *, + baseline_simulation_run_id: UUID, + reform_simulation_run_id: UUID, +) -> ReportRunCliffRows: + """Return each side's cliff calculation of its simulation run, or None. + + It is the run's calculation that hasn't failed, else its newest failed + one: one query per distinct run, so a report run naming one simulation + run on both sides reads it once, for both. + """ + baseline = _side_cliff_calculation(session, baseline_simulation_run_id) + reform = ( + baseline + if reform_simulation_run_id == baseline_simulation_run_id + else _side_cliff_calculation(session, reform_simulation_run_id) + ) + return ReportRunCliffRows(baseline=baseline, reform=reform) + + +def read_economy_result_rows( # noqa: PLR0913 # the session, then each part of the run the read needs session: Session, *, country_id: str, report_run: ReportRun, reform_simulation_run_id: UUID, on_local_area_dataset: bool, + cliff_calculations: ReportRunCliffRows, ) -> EconomyResultRows: """Return every result row of ``report_run``, one query per result table. @@ -47,6 +95,9 @@ def read_economy_result_rows( inequality rows are those of its baseline and reform simulation runs. The withheld area codes are read only for a local-area report's run (``on_local_area_dataset``), whose writer records them. + ``cliff_calculations`` are its simulation runs' cliff calculations, as + ``read_cliff_calculations`` read them. The report run's own four cliff + columns are not read. """ report_run_id = report_run.id simulation_run_ids = ( @@ -59,10 +110,6 @@ def read_economy_result_rows( country_package_version=report_run.country_package_version, data_version=report_run.data_version, spm_provenance=report_run.spm_provenance, - baseline_cliff_gap=report_run.baseline_cliff_gap, - baseline_cliff_share=report_run.baseline_cliff_share, - reform_cliff_gap=report_run.reform_cliff_gap, - reform_cliff_share=report_run.reform_cliff_share, ), baseline_simulation_run_id=report_run.baseline_simulation_run_id, reform_simulation_run_id=reform_simulation_run_id, @@ -141,6 +188,7 @@ def read_economy_result_rows( ) ) ), + cliff_calculations=cliff_calculations, on_local_area_dataset=on_local_area_dataset, withheld_area_codes=( tuple( diff --git a/policyengine_api/services/v2/stored_reports/economy_results/transformations.py b/policyengine_api/services/v2/stored_reports/economy_results/transformations.py index 4909fad68..d82ed8962 100644 --- a/policyengine_api/services/v2/stored_reports/economy_results/transformations.py +++ b/policyengine_api/services/v2/stored_reports/economy_results/transformations.py @@ -24,9 +24,12 @@ order. - ``constituency_withheld_codes`` and ``local_authority_withheld_codes``, for a local-area report only, from ``withheld_area_codes``, sorted. -- ``cliff_impact``, ``spm_provenance``, ``data_version`` and - ``model_version`` from the report run's own columns; the SPM receipts are - read as ``SPMComparisonProvenance``. +- ``cliff_impact`` from each simulation run's cliff calculation + (``cliff_impacts``), once both have succeeded, and never from the report + run's own four cliff columns. +- ``spm_provenance``, ``data_version`` and ``model_version`` from the report + run's own columns; the SPM receipts are read as + ``SPMComparisonProvenance``. An optional part with no rows is null. The writer stores no rows for an empty list either, so a UK result whose areas were all withheld reads back with @@ -41,6 +44,7 @@ from pydantic import ValidationError +from policyengine_api.data.v2.models import SimulationStatus from policyengine_api.services.v2.stored_reports.economy_results.types import ( AgePoverty, BaselineReformValue, @@ -77,6 +81,7 @@ from pydantic import JsonValue from policyengine_api.data.v2.models import BudgetSummary as BudgetSummaryRow + from policyengine_api.data.v2.models import CliffImpact as CliffImpactRow from policyengine_api.data.v2.models import ( CongressionalDistrictImpact as CongressionalDistrictImpactRow, ) @@ -87,7 +92,7 @@ from policyengine_api.data.v2.models import Poverty as PovertyRow from policyengine_api.services.v2.stored_reports.economy_results.types import ( EconomyResultRows, - ReportRunResultColumns, + ReportRunCliffRows, ) # .py's poverty types behind the result's "poverty" and "deep_poverty". @@ -253,7 +258,7 @@ def economy_result(rows: EconomyResultRows) -> EconomyResult: congressional_district_impact=_districts(rows.congressional_district_impacts), constituency_withheld_codes=_withheld_codes(rows, "constituency"), local_authority_withheld_codes=_withheld_codes(rows, "local_authority"), - cliff_impact=_cliff_impact(report_run), + cliff_impact=cliff_impact(rows.cliff_calculations), ) @@ -601,25 +606,30 @@ def _districts( ) -def _cliff_impact(report_run: ReportRunResultColumns) -> CliffImpact | None: - """Return the cliff impact, or None when the run stores none. +def _cliff_result(calculation: CliffImpactRow | None) -> CliffImpactInSimulation | None: + """Return a side's cliff result, or None until its calculation has succeeded. - The database keeps the four columns all set or all null. + The table's check keeps both numbers set exactly when it has succeeded. """ if ( - report_run.baseline_cliff_gap is None - or report_run.baseline_cliff_share is None - or report_run.reform_cliff_gap is None - or report_run.reform_cliff_share is None + calculation is None + or calculation.status is not SimulationStatus.SUCCEEDED + or calculation.cliff_gap is None + or calculation.cliff_share is None ): return None - return CliffImpact( - baseline=CliffImpactInSimulation( - cliff_gap=report_run.baseline_cliff_gap, - cliff_share=report_run.baseline_cliff_share, - ), - reform=CliffImpactInSimulation( - cliff_gap=report_run.reform_cliff_gap, - cliff_share=report_run.reform_cliff_share, - ), + return CliffImpactInSimulation( + cliff_gap=calculation.cliff_gap, cliff_share=calculation.cliff_share ) + + +def cliff_impact(cliff_calculations: ReportRunCliffRows) -> CliffImpact | None: + """Return the report run's cliff impact, or None until both sides have one. + + Each side's is its simulation run's succeeded cliff calculation. + """ + baseline = _cliff_result(cliff_calculations.baseline) + reform = _cliff_result(cliff_calculations.reform) + if baseline is None or reform is None: + return None + return CliffImpact(baseline=baseline, reform=reform) diff --git a/policyengine_api/services/v2/stored_reports/economy_results/types.py b/policyengine_api/services/v2/stored_reports/economy_results/types.py index fb25dd75c..fbfedefe8 100644 --- a/policyengine_api/services/v2/stored_reports/economy_results/types.py +++ b/policyengine_api/services/v2/stored_reports/economy_results/types.py @@ -30,6 +30,7 @@ # The tables' models, named apart from the result parts they hold. from policyengine_api.data.v2.models import BudgetSummary as BudgetSummaryRow + from policyengine_api.data.v2.models import CliffImpact as CliffImpactRow from policyengine_api.data.v2.models import ( CongressionalDistrictImpact as CongressionalDistrictImpactRow, ) @@ -359,17 +360,26 @@ class EconomyResult(EconomyResultModel): class ReportRunResultColumns: """The result columns of the report run itself. - ``country_package_version`` is the run's; the four cliff columns are all - set or all null. + ``country_package_version`` is the run's. Its four cliff columns are not + read: a report run's cliffs are its simulation runs' (``cliff_impacts``). """ country_package_version: str data_version: str | None spm_provenance: dict[str, JsonValue] | None - baseline_cliff_gap: float | None - baseline_cliff_share: float | None - reform_cliff_gap: float | None - reform_cliff_share: float | None + + +@dataclass(frozen=True) +class ReportRunCliffRows: + """Each side's cliff calculation of the simulation run the report run names. + + It is the run's calculation that hasn't failed, of which it has at most + one, else its newest failed one, else None. A report run naming one + simulation run on both sides has the same calculation on each. + """ + + baseline: CliffImpactRow | None + reform: CliffImpactRow | None @dataclass(frozen=True) @@ -377,10 +387,11 @@ class EconomyResultRows: """Every result row of one report run, as the database connectors read them. The comparison tables' rows are the report run's; the poverty and - inequality rows are those of its baseline and reform simulation runs. - ``on_local_area_dataset`` says whether the run is a local-area report's, - whose ``withheld_area_codes`` rows are read and list every area its - writer withheld; for any other run they are not read. + inequality rows, and the cliff calculations, are those of its baseline + and reform simulation runs. ``on_local_area_dataset`` says whether the + run is a local-area report's, whose ``withheld_area_codes`` rows are + read and list every area its writer withheld; for any other run they are + not read. """ country_id: str @@ -398,5 +409,6 @@ class EconomyResultRows: congressional_district_impacts: tuple[CongressionalDistrictImpactRow, ...] constituency_impacts: tuple[ConstituencyImpactRow, ...] local_authority_impacts: tuple[LocalAuthorityImpactRow, ...] + cliff_calculations: ReportRunCliffRows on_local_area_dataset: bool = False withheld_area_codes: tuple[WithheldAreaCodeRow, ...] = () diff --git a/policyengine_api/services/v2/stored_reports/services.py b/policyengine_api/services/v2/stored_reports/services.py index 9107b5192..2012a19c3 100644 --- a/policyengine_api/services/v2/stored_reports/services.py +++ b/policyengine_api/services/v2/stored_reports/services.py @@ -17,7 +17,11 @@ The result is rebuilt from the run's result rows once it has succeeded; a local-area report's (a UK-wide or nation report on the dataset its catalog -version gives local areas) also lists its withheld area codes. A +version gives local areas) also lists its withheld area codes. An economy +report's read also says how far the cliff calculations of the run's two +simulation runs have got, whatever the run's status, and the result's cliff +impact is theirs once both have succeeded: a run's cliffs are calculated +apart from it, and never read from the report run's own cliff columns. A budget-window report's run is a budget-window run, read with its years; once that run has succeeded, its result is the budget-window format, rebuilt from each year's budget rows. Reading a @@ -117,6 +121,7 @@ household_report_read, household_report_summary_read, listed_reports, + report_cliffs, report_kind, report_policy_ids, report_read, @@ -460,21 +465,31 @@ def _read_report( if kind == "household": return self._household_report(session, stored) run = stored.run - result = None - if run is not None and run.status is ReportRunStatus.SUCCEEDED: - result = result_transformations.economy_result( - result_reads.read_economy_result_rows( - session, - country_id=country_id, - report_run=run, - reform_simulation_run_id=require_reform_run(run), - on_local_area_dataset=stored.on_local_area_dataset, - ) + result = cliffs = None + if run is not None: + reform_simulation_run_id = require_reform_run(run) + cliff_calculations = result_reads.read_cliff_calculations( + session, + baseline_simulation_run_id=run.baseline_simulation_run_id, + reform_simulation_run_id=reform_simulation_run_id, ) + cliffs = report_cliffs(cliff_calculations) + if run.status is ReportRunStatus.SUCCEEDED: + result = result_transformations.economy_result( + result_reads.read_economy_result_rows( + session, + country_id=country_id, + report_run=run, + reform_simulation_run_id=reform_simulation_run_id, + on_local_area_dataset=stored.on_local_area_dataset, + cliff_calculations=cliff_calculations, + ) + ) return report_read( stored, current_versions=self._current_versions(country_id), result=result, + cliffs=cliffs, ) def _budget_window( diff --git a/policyengine_api/services/v2/stored_reports/transformations.py b/policyengine_api/services/v2/stored_reports/transformations.py index dae16644f..36c9f0033 100644 --- a/policyengine_api/services/v2/stored_reports/transformations.py +++ b/policyengine_api/services/v2/stored_reports/transformations.py @@ -4,6 +4,7 @@ from typing import TYPE_CHECKING +from policyengine_api.data.v2.models import SimulationStatus from policyengine_api.services.v2.simulation_service.types import LOCAL_AREA_DATASET from policyengine_api.services.v2.stored_reports.types import ( BudgetWindowReportRead, @@ -11,8 +12,10 @@ BudgetWindowRunRead, BudgetWindowRunsRead, BudgetWindowYearRead, + CliffCalculationRead, HouseholdReportRead, HouseholdReportSummaryRead, + ReportCliffsRead, ReportDefinitionRead, ReportRead, ReportRunRead, @@ -27,6 +30,7 @@ from policyengine_api.data.v2.models import ( BudgetWindowRun, + CliffImpact, Report, ReportRun, Simulation, @@ -39,12 +43,14 @@ ) from policyengine_api.services.v2.stored_reports.economy_results.types import ( EconomyResult, + ReportRunCliffRows, ) from policyengine_api.services.v2.stored_reports.household_results.types import ( HouseholdReportFailure, HouseholdReportResult, ) from policyengine_api.services.v2.stored_reports.types import ( + CliffCalculationStatusName, ReportKind, ReportRunsKind, ReportStatusName, @@ -139,10 +145,58 @@ def report_read( *, current_versions: PackageVersions, result: EconomyResult | None, + cliffs: ReportCliffsRead | None, ) -> ReportRead: - """Return an economy report with the run read's result, if it has one.""" + """Return an economy report with the run read's result and cliffs, if any.""" summary = report_summary_read(rows, current_versions=current_versions) - return ReportRead(**vars(summary), result=result) + return ReportRead(**vars(summary), result=result, cliffs=cliffs) + + +# A side's status for its cliff calculation's. +CLIFF_CALCULATION_STATUSES: dict[SimulationStatus, CliffCalculationStatusName] = { + SimulationStatus.PENDING: "pending", + SimulationStatus.RUNNING: "running", + SimulationStatus.SUCCEEDED: "succeeded", + SimulationStatus.FAILED: "failed", +} + + +def _cliff_calculation_read(calculation: CliffImpact | None) -> CliffCalculationRead: + """Return how far a side's cliff calculation has got; the error once failed.""" + if calculation is None: + return CliffCalculationRead(status="not_calculated", error_message=None) + status = CLIFF_CALCULATION_STATUSES[calculation.status] + return CliffCalculationRead( + status=status, + error_message=calculation.error_message if status == "failed" else None, + ) + + +# A report run's cliff status is the first of these that either side has, +# else succeeded: a failed or missing side needs a new request, and one +# still pending or running needs only time. +CLIFF_STATUSES_BEFORE_SUCCESS: tuple[CliffCalculationStatusName, ...] = ( + "failed", + "not_calculated", + "running", + "pending", +) + + +def report_cliffs(cliff_calculations: ReportRunCliffRows) -> ReportCliffsRead: + """Return how far a report run's two cliff calculations have got. + + Its status is ``succeeded`` once both sides are, else the first of + ``CLIFF_STATUSES_BEFORE_SUCCESS`` either side has. + """ + baseline = _cliff_calculation_read(cliff_calculations.baseline) + reform = _cliff_calculation_read(cliff_calculations.reform) + side_statuses = {baseline.status, reform.status} + status: CliffCalculationStatusName = next( + (status for status in CLIFF_STATUSES_BEFORE_SUCCESS if status in side_statuses), + "succeeded", + ) + return ReportCliffsRead(status=status, baseline=baseline, reform=reform) def household_report_summary_read( diff --git a/policyengine_api/services/v2/stored_reports/types.py b/policyengine_api/services/v2/stored_reports/types.py index b6d8e2e90..6787d967b 100644 --- a/policyengine_api/services/v2/stored_reports/types.py +++ b/policyengine_api/services/v2/stored_reports/types.py @@ -53,6 +53,12 @@ # budget-window runs. ReportRunsKind = Literal["economy", "household"] ReportRunTriggerName = Literal["initial", "manual", "system"] +# How far a side's cliff calculation has got: not_calculated while its +# simulation run has none, else its calculation's status (failed once its +# newest calculation failed and none is pending, running or succeeded). +CliffCalculationStatusName = Literal[ + "not_calculated", "pending", "running", "succeeded", "failed" +] @dataclass(frozen=True) @@ -133,11 +139,48 @@ class ReportSummaryRead(ReportDefinitionRead): run: ReportRunRead | None +@dataclass(frozen=True) +class CliffCalculationRead: + """How far one side's cliff calculation of its simulation run has got. + + ``error_message`` says why a ``failed`` side's newest calculation failed, + and is None otherwise. + """ + + status: CliffCalculationStatusName + error_message: str | None + + +@dataclass(frozen=True) +class ReportCliffsRead: + """How far the cliff calculations of a report run's two simulation runs have got. + + A simulation run's cliffs are calculated apart from it, once, when a + request asks for them; every report naming the run shares them. + ``status`` is ``succeeded`` once both sides are; otherwise ``failed`` + when either side is, else ``not_calculated`` when either side is, else + ``running`` when either side is, else ``pending``. A request with + ``include_cliffs`` starts a new calculation for each side that is + ``not_calculated`` or ``failed``. A report naming one simulation run on + both sides reads its calculation for each. + """ + + status: CliffCalculationStatusName + baseline: CliffCalculationRead + reform: CliffCalculationRead + + @dataclass(frozen=True) class ReportRead(ReportSummaryRead): - """A report with its run's result, once that run has succeeded.""" + """A report with its run's result, once that run has succeeded. + + ``cliffs`` says how far the cliff calculations of the run read have got, + whatever its status, and is None for a report with no run. The result's + ``cliff_impact`` is set once both of them have succeeded. + """ result: EconomyResult | None + cliffs: ReportCliffsRead | None @dataclass(frozen=True) diff --git a/tests/unit/v2/test_economy_result_rebuild.py b/tests/unit/v2/test_economy_result_rebuild.py index 0cbd9f3af..1a8957122 100644 --- a/tests/unit/v2/test_economy_result_rebuild.py +++ b/tests/unit/v2/test_economy_result_rebuild.py @@ -35,6 +35,7 @@ LocalAuthorityImpact, Poverty, ProgramStatistics, + SimulationStatus, WithheldAreaCode, ) from policyengine_api.services.v2.stored_reports.economy_results import ( @@ -99,6 +100,16 @@ def side_calculations( ) +def table_row(table: str, row: dict[str, Any]) -> Any: + """Load one stored row as its table's model, with a new ID. + + A cliff calculation's status is loaded as the enum a database read gives. + """ + if "status" in row: + row = {**row, "status": SimulationStatus(row["status"])} + return TABLE_MODELS[table](id=uuid4(), **row) + + def stored_rows( output: dict[str, Any], *, @@ -121,7 +132,7 @@ def stored_rows( stored = economy_result_rows(output, run_ids=run_ids, country=country) tables: dict[str, tuple[Any, ...]] = {} for table, rows in stored.rows.items(): - loaded = [TABLE_MODELS[table](id=uuid4(), **row) for row in rows] + loaded = [table_row(table, row) for row in rows] if reverse_rows: loaded.reverse() tables[table] = tuple(loaded) diff --git a/tests/unit/v2/test_report_cliff_reads.py b/tests/unit/v2/test_report_cliff_reads.py index 13cd52229..0be7fde64 100644 --- a/tests/unit/v2/test_report_cliff_reads.py +++ b/tests/unit/v2/test_report_cliff_reads.py @@ -28,6 +28,9 @@ CliffImpactInSimulation, ReportRunCliffRows, ) +from policyengine_api.services.v2.stored_reports.transformations import ( + report_cliffs, +) from policyengine_api.services.v2.stored_reports.types import ( CliffCalculationRead, CliffCalculationStatusName, @@ -102,9 +105,7 @@ def store_calculations( def test_sides_without_cliff_calculations_are_not_calculated() -> None: - cliffs = result_transformations.report_cliffs( - ReportRunCliffRows(baseline=None, reform=None) - ) + cliffs = report_cliffs(ReportRunCliffRows(baseline=None, reform=None)) assert cliffs == ReportCliffsRead( status="not_calculated", @@ -123,9 +124,7 @@ def test_a_side_reads_its_unfailed_calculations_status_without_an_error( ) -> None: calculation = cliff_calculation(status) - cliffs = result_transformations.report_cliffs( - ReportRunCliffRows(baseline=calculation, reform=calculation) - ) + cliffs = report_cliffs(ReportRunCliffRows(baseline=calculation, reform=calculation)) assert cliffs.baseline == CliffCalculationRead( status=status.value, error_message=None @@ -134,7 +133,7 @@ def test_a_side_reads_its_unfailed_calculations_status_without_an_error( def test_a_failed_side_says_why_its_calculation_failed() -> None: - cliffs = result_transformations.report_cliffs( + cliffs = report_cliffs( ReportRunCliffRows( baseline=cliff_calculation(SimulationStatus.SUCCEEDED), reform=cliff_calculation(SimulationStatus.FAILED), @@ -165,12 +164,12 @@ def test_the_reports_cliff_status_follows_its_least_finished_side( reform: CliffCalculationStatusName, overall: CliffCalculationStatusName, ) -> None: - cliffs = result_transformations.report_cliffs( + cliffs = report_cliffs( ReportRunCliffRows( baseline=side_calculation(baseline), reform=side_calculation(reform) ) ) - swapped = result_transformations.report_cliffs( + swapped = report_cliffs( ReportRunCliffRows( baseline=side_calculation(reform), reform=side_calculation(baseline) ) diff --git a/tests/unit/v2/test_report_read_routes.py b/tests/unit/v2/test_report_read_routes.py index 455371697..ad8810cf0 100644 --- a/tests/unit/v2/test_report_read_routes.py +++ b/tests/unit/v2/test_report_read_routes.py @@ -161,7 +161,8 @@ def test_a_listed_report_answers_no_cliffs() -> None: def test_the_openapi_document_describes_a_reports_cliffs() -> None: - schemas = report_route_client().get("/openapi.json").json()["components"]["schemas"] + document = report_route_client().get("/v2/openapi.json").json() + schemas = document["components"]["schemas"] cliffs = schemas["ReportCliffsItem"] assert set(cliffs["properties"]) == {"status", "baseline", "reform"} From 7bd2fca88d7e0e54266eb0c08473322a11b70154 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Tue, 17 Nov 2026 19:30:44 +0400 Subject: [PATCH 03/18] Test include_cliffs on report re-runs (failing) POST /v2/reports/{id}/runs takes include_cliffs and passes it to the simulation service, sending it only when asked; a household report's or budget window's re-run asking for cliffs is refused with 422 before the service is asked. Co-Authored-By: Claude Opus 5.5 --- tests/integration/test_v2_report_runs.py | 81 +++++++++++++++++++ .../libs/test_simulation_report_reruns.py | 19 +++++ tests/unit/v2/report_run_support.py | 7 +- tests/unit/v2/test_report_run_routes.py | 53 +++++++++++- 4 files changed, 157 insertions(+), 3 deletions(-) diff --git a/tests/integration/test_v2_report_runs.py b/tests/integration/test_v2_report_runs.py index ca4612001..57d8c959d 100644 --- a/tests/integration/test_v2_report_runs.py +++ b/tests/integration/test_v2_report_runs.py @@ -73,6 +73,7 @@ household_only_catalog, store_budget_window_run, store_catalog, + store_cliff_calculation, store_report, store_report_run, store_year_simulations, @@ -153,6 +154,9 @@ class RerunningSimulationService: it records how many of the report service's sessions are open when asked. With ``window_years``, the report is a budget window, and the new run is a budget-window run with a pending report run for each of those years. + A report run again with ``include_cliffs`` also gets a pending cliff + calculation for each side's new simulation run, as the simulation + service starts them. """ engine: Engine @@ -208,6 +212,14 @@ def rerun_report(self, rerun: ReportRerunInput) -> StartedReportRun: else: run_ids = store_report_run(connection, self.catalog, report, settings) mark_manual(connection, run_ids.report_run_id) + if rerun.include_cliffs: + for simulation_run_id in ( + run_ids.baseline_simulation_run_id, + run_ids.reform_simulation_run_id, + ): + store_cliff_calculation( + connection, simulation_run_id, "pending" + ) self.new_run_ids.append(run_ids.report_run_id) started = StartedReportRun(report_run_id=run_ids.report_run_id) if self.delete_report: @@ -591,6 +603,75 @@ def test_running_a_report_again_answers_it_with_its_new_run( ] +def test_running_a_report_again_with_cliffs_asks_for_them_and_answers_their_progress( + owner_engine: Engine, catalog: CatalogRows, runtime_sessions: Any +) -> None: + with owner_engine.begin() as connection: + report = store_report(connection, catalog) + simulation_service = RerunningSimulationService(owner_engine, catalog) + + response = client_for(runtime_sessions, simulation_service).post( + f"/v2/reports/{report.report_id}/runs?country_id=us", + json={"include_cliffs": True}, + ) + + assert response.status_code == 201, response.text + assert simulation_service.reruns == [ + ReportRerunInput( + country_id="us", + report_id=report.report_id, + kind="economy", + force=False, + policy_ids=(None, catalog.policy_id), + include_cliffs=True, + ) + ] + item = response.json()["result"]["item"] + assert item["cliffs"] == { + "status": "pending", + "baseline": {"status": "pending", "error_message": None}, + "reform": {"status": "pending", "error_message": None}, + } + + +def test_a_budget_window_run_again_with_cliffs_is_refused_before_asking( + owner_engine: Engine, catalog: CatalogRows, runtime_sessions: Any +) -> None: + with owner_engine.begin() as connection: + window = store_report(connection, catalog, budget_window_size=2) + simulation_service = RerunningSimulationService( + owner_engine, catalog, window_years=(2026, 2027) + ) + + response = client_for(runtime_sessions, simulation_service).post( + f"/v2/reports/{window.report_id}/runs?country_id=us", + json={"include_cliffs": True}, + ) + + assert response.status_code == 422, response.text + assert "include_cliffs" in response.json()["message"] + assert simulation_service.reruns == [] + + +def test_a_household_report_run_again_asks_for_no_cliffs( + owner_engine: Engine, household_only_uk: CatalogRows, runtime_sessions: Any +) -> None: + with owner_engine.begin() as connection: + report = store_household_report(connection, household_only_uk) + simulation_service = RerunningSimulationService(owner_engine, household_only_uk) + client = client_for(runtime_sessions, simulation_service) + runs_path = f"/v2/reports/{report.report_id}/runs?country_id=uk" + + refused = client.post(runs_path, json={"include_cliffs": True}) + not_asked = client.post(runs_path, json={"include_cliffs": False}) + + assert refused.status_code == 422, refused.text + assert "include_cliffs" in refused.json()["message"] + assert not_asked.status_code == 201, not_asked.text + (rerun,) = simulation_service.reruns + assert rerun.include_cliffs is False + + def test_a_report_whose_reform_simulation_is_gone_is_left_to_the_service_to_refuse( owner_engine: Engine, catalog: CatalogRows, runtime_sessions: Any ) -> None: diff --git a/tests/unit/libs/test_simulation_report_reruns.py b/tests/unit/libs/test_simulation_report_reruns.py index fdefc74fa..1ed0e2470 100644 --- a/tests/unit/libs/test_simulation_report_reruns.py +++ b/tests/unit/libs/test_simulation_report_reruns.py @@ -132,6 +132,25 @@ def test_a_rerun_posts_force_to_the_reports_runs_route( assert json.loads(request.content) == {"force": force} +def test_a_rerun_asking_for_cliffs_sends_include_cliffs() -> None: + service = ScriptedService() + + service.rerun(include_cliffs=True) + + (request,) = service.requests + assert json.loads(request.content) == {"force": False, "include_cliffs": True} + + +def test_a_rerun_not_asking_for_cliffs_sends_no_include_cliffs() -> None: + """Sim's re-run body before C1 · 39 refuses any field but ``force``.""" + service = ScriptedService() + + service.rerun(include_cliffs=False) + + (request,) = service.requests + assert json.loads(request.content) == {"force": False} + + @pytest.mark.parametrize("status_code", [201, 202]) def test_a_started_rerun_naming_the_report_is_accepted(status_code: int) -> None: service = ScriptedService( diff --git a/tests/unit/v2/report_run_support.py b/tests/unit/v2/report_run_support.py index 5cd6cb3fa..83c4317e0 100644 --- a/tests/unit/v2/report_run_support.py +++ b/tests/unit/v2/report_run_support.py @@ -119,11 +119,16 @@ def rerun_report( country_id: str, report_id: UUID, force: bool, + include_cliffs: bool = False, requester: AccountPrincipal | None = None, ) -> StoredReportRead: self.requesters.append(requester) self._answer( - "rerun_report", country_id=country_id, report_id=report_id, force=force + "rerun_report", + country_id=country_id, + report_id=report_id, + force=force, + include_cliffs=include_cliffs, ) return self.report if self.rerun is None else self.rerun diff --git a/tests/unit/v2/test_report_run_routes.py b/tests/unit/v2/test_report_run_routes.py index 1f906988c..9ce831810 100644 --- a/tests/unit/v2/test_report_run_routes.py +++ b/tests/unit/v2/test_report_run_routes.py @@ -26,6 +26,7 @@ SubmissionStorageError, ) from policyengine_api.services.v2.stored_reports.validators import ( + CliffsNotAvailableError, ReportStorageError, RerunReportUnreadableError, StoredReportNotFoundError, @@ -239,10 +240,37 @@ def test_running_a_report_again_answers_the_report_with_its_new_run( assert item["result"] is None assert item["current_versions"]["policyengine_version"] == "4.2.0" assert service.calls == [ - ("rerun_report", {"country_id": "us", "report_id": REPORT_ID, "force": force}) + ( + "rerun_report", + { + "country_id": "us", + "report_id": REPORT_ID, + "force": force, + "include_cliffs": False, + }, + ) ] +@pytest.mark.parametrize( + ("body", "include_cliffs"), + [({}, False), ({"include_cliffs": False}, False), ({"include_cliffs": True}, True)], + ids=["omitted", "not-asked", "asked"], +) +def test_running_a_report_again_passes_on_whether_it_asks_for_cliffs( + body: dict[str, bool], + include_cliffs: bool, # noqa: FBT001 # pytest passes parameters positionally +) -> None: + service = FakeReportRunService() + + response = report_route_client(reports=service).post(RUNS_PATH, json=body) + + assert response.status_code == 201, response.text + ((_, arguments),) = service.calls + assert arguments["include_cliffs"] is include_cliffs + assert arguments["force"] is False + + @pytest.mark.parametrize( "body", [ @@ -252,8 +280,21 @@ def test_running_a_report_again_answers_the_report_with_its_new_run( {"force": True, "country_id": "us"}, [], "force", + {"include_cliffs": "yes"}, + {"include_cliffs": 1}, + {"include_cliffs": None}, + ], + ids=[ + "text", + "number", + "null", + "extra-field", + "list", + "string", + "text-cliffs", + "number-cliffs", + "null-cliffs", ], - ids=["text", "number", "null", "extra-field", "list", "string"], ) def test_a_rerun_refuses_a_malformed_body(body: object) -> None: service = FakeReportRunService() @@ -405,6 +446,13 @@ def test_a_new_run_whose_report_cannot_be_read_back_answers_the_reports_id() -> 503, "V2 report storage is unavailable", ), + ( + CliffsNotAvailableError( + "include_cliffs: a household report has no cliff impacts" + ), + 422, + "include_cliffs: a household report has no cliff impacts", + ), (RuntimeError("unexpected"), 500, "V2 report operation failed"), ], ids=[ @@ -418,6 +466,7 @@ def test_a_new_run_whose_report_cannot_be_read_back_answers_the_reports_id() -> "service-unavailable", "check-storage", "report-storage", + "no-cliffs", "unexpected", ], ) From bacc8f1b456e63418818f1cd41d104e9e0013887 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Tue, 17 Nov 2026 19:35:44 +0400 Subject: [PATCH 04/18] Take include_cliffs on report re-runs POST /v2/reports/{id}/runs takes include_cliffs and sends it to the simulation service only when true, so a re-run that doesn't ask still runs on a simulation service that doesn't take the field yet. A household report's or budget window's re-run asking for cliffs answers 422 before the service is asked or anything recorded. The create body's include_cliffs now says what it starts. Co-Authored-By: Claude Opus 5.5 --- .../resource_service_protocols.py | 4 ++++ .../fastapi_routes/v2/reports/routes.py | 19 +++++++++++----- .../fastapi_routes/v2/reports/run_models.py | 12 ++++++++-- .../libs/simulation_report_reruns.py | 20 +++++++++++++---- .../services/v2/simulation_service/types.py | 22 +++++++++++++------ .../services/v2/stored_reports/services.py | 17 ++++++++------ .../services/v2/stored_reports/validators.py | 21 +++++++++++++++++- 7 files changed, 89 insertions(+), 26 deletions(-) diff --git a/policyengine_api/fastapi_routes/resource_service_protocols.py b/policyengine_api/fastapi_routes/resource_service_protocols.py index aa2818879..ea08e7113 100644 --- a/policyengine_api/fastapi_routes/resource_service_protocols.py +++ b/policyengine_api/fastapi_routes/resource_service_protocols.py @@ -285,11 +285,15 @@ def rerun_report( country_id: str, report_id: UUID, force: bool, + include_cliffs: bool = False, requester: AccountPrincipal | None = None, ) -> StoredReportRead: """Run the country's report again; return it with the run the request ended on. That is the run the simulation service named, created or joined. + With ``include_cliffs``, it also starts the cliff calculations an + economy report run's simulation runs lack; ``CliffsNotAvailableError`` + is raised, before anything is asked, for any other kind. With a ``requester``, the request is recorded for its user once the simulation service has answered, and ``StandardUserRequiresSignInError`` is raised, before anything is diff --git a/policyengine_api/fastapi_routes/v2/reports/routes.py b/policyengine_api/fastapi_routes/v2/reports/routes.py index 2628f3053..b72aee27f 100644 --- a/policyengine_api/fastapi_routes/v2/reports/routes.py +++ b/policyengine_api/fastapi_routes/v2/reports/routes.py @@ -99,6 +99,7 @@ HouseholdResultUnreadableError, ) from policyengine_api.services.v2.stored_reports.validators import ( + CliffsNotAvailableError, CreatedReportUnreadableError, ForcedRerunRequiresAdminError, ForcedRerunRequiresSignInError, @@ -131,11 +132,13 @@ StoredReportNotFoundError, ReportRunNotFoundError, ForcedRerunRequiresAdminError, + CliffsNotAvailableError, *SUBMISSION_REFUSALS, ) REPORT_ERROR_MAPPINGS = ( V2ErrorMapping((StoredReportNotFoundError, ReportRunNotFoundError), 404), V2ErrorMapping((ForcedRerunRequiresAdminError,), 403), + V2ErrorMapping((CliffsNotAvailableError,), 422), *SUBMISSION_ERROR_MAPPINGS, V2ErrorMapping( ( @@ -321,10 +324,10 @@ def _rerun_report( *, country_id: str, report_id: UUID, - force: bool, + body: ReportRerunRequest, requester: AccountPrincipal | None, ) -> ReportDetailResponse | JSONResponse: - """Run the report again and answer it with the run the request ended on. + """Run the report again, as ``body`` asks; answer it with the run it ended on. The simulation service's refusal to run it again now answers 409 with the run it names; a report that cannot be read back once its run started @@ -339,7 +342,8 @@ def _rerun_report( report = service.rerun_report( country_id=country_id, report_id=report_id, - force=force, + force=body.force, + include_cliffs=body.include_cliffs, requester=requester, ) except (StandardUserRequiresSignInError, ForcedRerunRequiresSignInError) as error: @@ -390,7 +394,12 @@ def _add_report_run_routes( "side reuses a run of its own simulation that succeeded on those " "versions; with force, both simulations are calculated again. A " "household report's sides are always calculated again, so force " - "changes nothing for it. A budget window's new run is a " + "changes nothing for it. With include_cliffs, the simulation " + "service also starts a cliff calculation for each of an economy " + "report run's simulation runs that has none, or whose newest one " + "failed, and the answer's cliffs says how far they have got; a " + "household report or budget window asking for cliffs answers 422 " + "before anything is asked. A budget window's new run is a " "budget-window run with a report run for each year, and " "with force each year calculates its simulations again. Answers the " "report as stored, with the run the simulation service named (a " @@ -416,7 +425,7 @@ def rerun() -> ReportDetailResponse | JSONResponse: service_factory(), country_id=query.country_id, report_id=report_id, - force=body.force, + body=body, requester=requester, ) diff --git a/policyengine_api/fastapi_routes/v2/reports/run_models.py b/policyengine_api/fastapi_routes/v2/reports/run_models.py index 4680fa289..9dc6aaf72 100644 --- a/policyengine_api/fastapi_routes/v2/reports/run_models.py +++ b/policyengine_api/fastapi_routes/v2/reports/run_models.py @@ -44,10 +44,16 @@ class ReportRerunRequest(StrictSubmissionModel): Without ``force`` (``{}``), each side reuses a run of its own simulation that succeeded on those versions; with it, both simulations are calculated again. A household report's sides are always calculated - again. The new run is kept beside every earlier one. + again. The new run is kept beside every earlier one. ``include_cliffs`` + also starts a cliff calculation for each of the run's two simulation + runs that has none, or whose newest one failed, and joins one under way; + the report's ``cliffs`` then says how far they have got. Only an + economy report has cliffs: a household report or budget window asking + for them is refused with 422. """ force: StrictBool = False + include_cliffs: StrictBool = False class ReportRunListResult(StrictReportAPIModel): @@ -178,7 +184,9 @@ class RerunReportUnreadableResponse(V2ErrorResponse): 422: { "model": V2MissingParametersErrorResponse | V2ErrorResponse, "description": ( - "The request does not match the schema; the country has no economy " + "The request does not match the schema; a household report or " + "budget window asks for cliffs (include_cliffs), which only an " + "economy report has; the country has no economy " "reports, or no household calculations for a household report; a " "policy of the report's simulations sets " "parameters the running catalog version does not have (code " diff --git a/policyengine_api/libs/simulation_report_reruns.py b/policyengine_api/libs/simulation_report_reruns.py index 8f8d2e636..157d4db1c 100644 --- a/policyengine_api/libs/simulation_report_reruns.py +++ b/policyengine_api/libs/simulation_report_reruns.py @@ -3,10 +3,14 @@ ``start_report_rerun`` is what ``SimulationServiceReportClient.rerun_report`` does: it posts ``{"force": …}`` to the Cloud Run simulation service's ``POST /reports/{report_id}/runs``, through the same HTTP client as the -service's other v2 routes (``policyengine_api.libs.simulation_reports``). -The service creates the stored report's new run on its default worker's +service's other v2 routes (``policyengine_api.libs.simulation_reports``), +with ``"include_cliffs": true`` when the re-run asks for cliffs. The +service creates the stored report's new run on its default worker's versions and starts it, keeping every earlier run. Without ``force``, each side reuses a run of its own simulation that succeeded on those versions. +With ``include_cliffs``, it also starts a cliff calculation for each side's +simulation run that has none; until it calculates cliffs per simulation +run, it refuses the field with 422, which is passed on as any 422 is. The Public API reads the report in its country before asking, so it never asks about a report it does not have. The simulation service answers: @@ -132,8 +136,16 @@ def report_runs_path(report_id: UUID) -> str: def report_rerun_request(rerun: ReportRerunInput) -> dict[str, Any]: - """Return the simulation service's request body for the re-run.""" - return {"force": rerun.force} + """Return the simulation service's request body for the re-run. + + ``include_cliffs`` is sent only when true: a simulation service from + before cliffs were calculated per simulation run refuses the field, so a + re-run that doesn't ask for cliffs still runs there. + """ + body: dict[str, Any] = {"force": rerun.force} + if rerun.include_cliffs: + body["include_cliffs"] = True + return body def post_report_rerun( diff --git a/policyengine_api/services/v2/simulation_service/types.py b/policyengine_api/services/v2/simulation_service/types.py index 4691ba88e..402c3d270 100644 --- a/policyengine_api/services/v2/simulation_service/types.py +++ b/policyengine_api/services/v2/simulation_service/types.py @@ -258,12 +258,17 @@ def require_spm_object(cls, value: object) -> object: class EconomyReportFields(ReportDefinitionFields): """An economy report: a baseline and a reform simulation of one region's data. - ``include_cliffs`` also calculates the baseline's and reform's cliff - impact. ``data_source`` ``local_area_dataset`` calculates both - simulations on the dataset the catalog version gives local areas - instead of the region's, so the result also has each constituency's and - local authority's impact and the codes of those disclosure control - withheld; omit it, rather than sending null, for the region's dataset. + ``include_cliffs`` also starts a cliff calculation for each of the two + simulation runs that has none, or whose newest one failed, and joins one + under way: a simulation run's cliffs are calculated once, apart from it, + and every report naming the run shares them. It is never stored. The + report's ``cliffs`` says how far they have got, and its result's + ``cliff_impact`` holds them once both have succeeded. + ``data_source`` ``local_area_dataset`` calculates both simulations on + the dataset the catalog version gives local areas instead of the + region's, so the result also has each constituency's and local + authority's impact and the codes of those disclosure control withheld; + omit it, rather than sending null, for the region's dataset. The simulation service takes it only for ``uk`` and the four ``country/*`` nations, on a release that gives local areas a dataset of their own, and refuses it with 422 otherwise: the Public API checks only @@ -427,7 +432,9 @@ class ReportRerunInput: economy calculations. ``policy_ids`` are the policies of the report's simulations, baseline first, None for current law, a report of the baseline alone or a simulation that is gone, for the checks before the - simulation service is asked. + simulation service is asked. ``include_cliffs``, only for an economy + report, also starts a cliff calculation for each side's simulation run + that has none, or whose newest one failed; it is sent only when true. """ country_id: str @@ -435,6 +442,7 @@ class ReportRerunInput: kind: ReportRerunKind force: bool policy_ids: tuple[UUID | None, ...] + include_cliffs: bool = False class SimulationServiceClient(Protocol): diff --git a/policyengine_api/services/v2/stored_reports/services.py b/policyengine_api/services/v2/stored_reports/services.py index 2012a19c3..1387f4cc2 100644 --- a/policyengine_api/services/v2/stored_reports/services.py +++ b/policyengine_api/services/v2/stored_reports/services.py @@ -18,10 +18,7 @@ The result is rebuilt from the run's result rows once it has succeeded; a local-area report's (a UK-wide or nation report on the dataset its catalog version gives local areas) also lists its withheld area codes. An economy -report's read also says how far the cliff calculations of the run's two -simulation runs have got, whatever the run's status, and the result's cliff -impact is theirs once both have succeeded: a run's cliffs are calculated -apart from it, and never read from the report run's own cliff columns. A +report's read also gives its run's cliffs (``ReportCliffsRead``). A budget-window report's run is a budget-window run, read with its years; once that run has succeeded, its result is the budget-window format, rebuilt from each year's budget rows. Reading a @@ -135,6 +132,7 @@ ReportStorageError, RerunReportUnreadableError, require_admin_to_force, + require_cliffs_available, require_reform_run, require_report, require_report_run, @@ -680,6 +678,7 @@ def rerun_report( country_id: str, report_id: UUID, force: bool, + include_cliffs: bool = False, requester: AccountPrincipal | None = None, ) -> StoredReportRead: """Run the country's report again; return it with the run the request ended on. @@ -691,14 +690,16 @@ def rerun_report( on the current versions; with it, both are calculated again (a budget window's new run then recalculates each year). A household report's sides are always calculated again. Only an admin user may force a - re-run. With a ``requester``, it is + re-run; ``include_cliffs`` asks for an economy report run's cliffs + too. With a ``requester``, it is checked before the simulation service is asked, and the request is recorded for its user (trigger ``manual``, forced or not) once the service has answered: that run, or each year's report run of a budget window's. Raise StoredReportNotFoundError when the country has no such report, ForcedRerunRequiresSignInError for a forced re-run naming no - user and ForcedRerunRequiresAdminError for one by a user below admin, - both before the simulation service is asked, ReportStorageError when + user, ForcedRerunRequiresAdminError for one by a user below admin and + CliffsNotAvailableError for a household report's or window's cliffs, + each before the simulation service is asked, ReportStorageError when it cannot be read, the recorder's check's errors, the submission's checks' and the simulation service's errors (see ``SimulationSubmissionService.rerun_report``), @@ -715,6 +716,7 @@ def rerun_report( recording = self._run_recording(requester) if force: require_admin_to_force(None if recording is None else recording.requester) + require_cliffs_available(kind, include_cliffs=include_cliffs) started = submissions.rerun_report( ReportRerunInput( country_id=country_id, @@ -722,6 +724,7 @@ def rerun_report( kind=kind, force=force, policy_ids=report_policy_ids(stored), + include_cliffs=include_cliffs, ) ) if kind != "budget_window": diff --git a/policyengine_api/services/v2/stored_reports/validators.py b/policyengine_api/services/v2/stored_reports/validators.py index 683874a30..6982dcffb 100644 --- a/policyengine_api/services/v2/stored_reports/validators.py +++ b/policyengine_api/services/v2/stored_reports/validators.py @@ -17,7 +17,10 @@ from policyengine_api.services.v2.report_run_records.types import ( CheckedRequester, ) - from policyengine_api.services.v2.stored_reports.types import StoredReportRows + from policyengine_api.services.v2.stored_reports.types import ( + ReportKind, + StoredReportRows, + ) # A report run, or a budget window's budget-window run. RunT = TypeVar("RunT") @@ -64,6 +67,22 @@ class ForcedRerunRequiresAdminError(PermissionError): """A forced re-run's user is below admin; only an admin user may force one.""" +class CliffsNotAvailableError(ValueError): + """A re-run asked for cliffs of a report that has none. + + Only an economy report's simulation runs have cliff calculations: a + household report's and a budget window's have none. + """ + + +def require_cliffs_available(kind: ReportKind, *, include_cliffs: bool) -> None: + """Raise CliffsNotAvailableError when a re-run of a ``kind`` asks for cliffs.""" + if include_cliffs and kind != "economy": + name = "a household report" if kind == "household" else "a budget window" + msg = f"include_cliffs: {name} has no cliff impacts, so it cannot be true" + raise CliffsNotAvailableError(msg) + + FORCED_RERUN_SIGN_IN_MESSAGE = ( "Only admin users may force a re-run: sign in with a bearer access token" ) From 0c164c63966277937963309c6bbec152d3709665 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Tue, 17 Nov 2026 19:36:31 +0400 Subject: [PATCH 05/18] Add the changelog fragment for report cliffs from simulation runs Co-Authored-By: Claude Opus 5.5 --- changelog.d/report-cliffs-from-simulation-runs.changed.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/report-cliffs-from-simulation-runs.changed.md diff --git a/changelog.d/report-cliffs-from-simulation-runs.changed.md b/changelog.d/report-cliffs-from-simulation-runs.changed.md new file mode 100644 index 000000000..8d3b1ebb0 --- /dev/null +++ b/changelog.d/report-cliffs-from-simulation-runs.changed.md @@ -0,0 +1 @@ +`/v2/reports` reads a report run's cliff impact from its two simulation runs' cliff results, never from the report run's own cliff columns, and each economy report read gives `cliffs`: how far each side's cliff calculation has got. `POST /v2/reports/{report_id}/runs` takes `include_cliffs`, which a household report or budget window refuses with 422. From e98733356f4b3dc08c75fe800e7b1759fa8844d4 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Tue, 17 Nov 2026 19:53:21 +0400 Subject: [PATCH 06/18] Move the requester's view of reports out of the report service stored_reports.services reached its 800-line limit. The code that reads reports as the requesting user sees them (their saved report's label and their newest requested run) moves unchanged to stored_reports.requester_views.services; _requesters_view is renamed requesters_view there, since the report service now imports it. Co-Authored-By: Claude Opus 5.5 --- .../requester_views/__init__.py | 1 + .../requester_views/services.py | 118 ++++++++++++++++++ .../services/v2/stored_reports/services.py | 99 +-------------- 3 files changed, 125 insertions(+), 93 deletions(-) create mode 100644 policyengine_api/services/v2/stored_reports/requester_views/__init__.py create mode 100644 policyengine_api/services/v2/stored_reports/requester_views/services.py diff --git a/policyengine_api/services/v2/stored_reports/requester_views/__init__.py b/policyengine_api/services/v2/stored_reports/requester_views/__init__.py new file mode 100644 index 000000000..7eab48c57 --- /dev/null +++ b/policyengine_api/services/v2/stored_reports/requester_views/__init__.py @@ -0,0 +1 @@ +"""Reports as the requesting user sees them: their labels and requested runs.""" diff --git a/policyengine_api/services/v2/stored_reports/requester_views/services.py b/policyengine_api/services/v2/stored_reports/requester_views/services.py new file mode 100644 index 000000000..bc5474c4a --- /dev/null +++ b/policyengine_api/services/v2/stored_reports/requester_views/services.py @@ -0,0 +1,118 @@ +"""Reports as the requesting user sees them. + +A report's label and description are the requesting user's saved report's, +and a report the user asked to run is read with the run of their newest +request in place of its default. ``requesters_view`` gives that view of the +rows the report service read; it moved here from +``policyengine_api.services.v2.stored_reports.services`` unchanged. +""" + +from __future__ import annotations + +from dataclasses import replace +from typing import TYPE_CHECKING + +from policyengine_api.services.v2.identity.services import ( + find_principal_user_in_session, +) +from policyengine_api.services.v2.stored_reports.database_connectors import ( + reads_requests as request_reads, +) +from policyengine_api.services.v2.stored_reports.database_connectors.reads import ( + read_budget_window_years, +) + +if TYPE_CHECKING: + from collections.abc import Sequence + from uuid import UUID + + from sqlmodel import Session + + from policyengine_api.services.v2.identity.types import AccountPrincipal + from policyengine_api.services.v2.stored_reports.types import ( + StoredReportRows, + ) + + +def _viewer_user_id( + session: Session, + *, + requester: AccountPrincipal | None, + recorded_user_id: UUID | None, +) -> UUID | None: + """Return the ID of the user a read is for. + + That is ``recorded_user_id`` when a request was just recorded for it, or + else the requester's stored user's, or None. + """ + if recorded_user_id is not None: + return recorded_user_id + if requester is None: + return None + user = find_principal_user_in_session(session, requester) + return None if user is None else user.user_id + + +def requesters_view( + session: Session, + rows: Sequence[StoredReportRows], + *, + requester: AccountPrincipal | None, + recorded_user_id: UUID | None = None, + with_requested_runs: bool, +) -> list[StoredReportRows]: + """Return the reports as the requester sees them. + + The requester's stored user is looked up, unless ``recorded_user_id`` + names the user a request was just recorded for. Each report takes its + label and description from that user's saved report of it. With + ``with_requested_runs``, a report the user asked to run + is read with the run of their newest request in place of its default (a + budget window's with that year's budget-window run and its years). A + request naming no user, or a user not stored yet, sees each report's + default run and no label. Raise StandardUserRequiresSignInError for an + unauthenticated credential that names a signed-in user. + """ + user_id = _viewer_user_id( + session, requester=requester, recorded_user_id=recorded_user_id + ) + if user_id is None or not rows: + return list(rows) + report_ids = [stored.report.id for stored in rows] + labels = request_reads.read_saved_report_labels( + session, user_id=user_id, report_ids=report_ids + ) + requested_runs = ( + request_reads.read_requested_report_runs( + session, user_id=user_id, report_ids=report_ids + ) + if with_requested_runs + else {} + ) + window_run_ids = [ + run.budget_window_run_id + for run in requested_runs.values() + if run.budget_window_run_id is not None + ] + window_runs = request_reads.read_budget_window_runs_by_id( + session, budget_window_run_ids=window_run_ids + ) + window_years = read_budget_window_years(session, window_run_ids) + viewed = [] + for stored in rows: + name, description = labels.get(stored.report.id, (None, None)) + seen = replace( + stored, saved_report_name=name, saved_report_description=description + ) + requested = requested_runs.get(stored.report.id) + if requested is not None and requested.budget_window_run_id is None: + seen = replace(seen, run=requested) + elif requested is not None and requested.budget_window_run_id in window_runs: + window_run_id = requested.budget_window_run_id + seen = replace( + seen, + budget_window_run=window_runs[window_run_id], + budget_window_years=window_years.get(window_run_id, ()), + ) + viewed.append(seen) + return viewed diff --git a/policyengine_api/services/v2/stored_reports/services.py b/policyengine_api/services/v2/stored_reports/services.py index 1387f4cc2..8866cd938 100644 --- a/policyengine_api/services/v2/stored_reports/services.py +++ b/policyengine_api/services/v2/stored_reports/services.py @@ -68,9 +68,6 @@ from policyengine_api.data.v2.models import ReportRunStatus, ReportRunTrigger from policyengine_api.data.v2.models.base import utc_now from policyengine_api.query_parameters import MAXIMUM_LISTED_REPORTS -from policyengine_api.services.v2.identity.services import ( - find_principal_user_in_session, -) from policyengine_api.services.v2.report_run_records.types import ReportRunRequest from policyengine_api.services.v2.simulation_service.types import ( ReportRerunInput, @@ -85,9 +82,6 @@ from policyengine_api.services.v2.stored_reports.database_connectors import ( reads_household_results as household_result_reads, ) -from policyengine_api.services.v2.stored_reports.database_connectors import ( - reads_requests as request_reads, -) from policyengine_api.services.v2.stored_reports.database_connectors import ( reads_results as result_reads, ) @@ -111,6 +105,9 @@ from policyengine_api.services.v2.stored_reports.household_results.validators import ( require_household_report_result, ) +from policyengine_api.services.v2.stored_reports.requester_views.services import ( + requesters_view, +) from policyengine_api.services.v2.stored_reports.transformations import ( budget_window_read, budget_window_runs_read, @@ -248,90 +245,6 @@ def _record_request(recording: _RunRecording, request: ReportRunRequest) -> UUID ) from error -def _viewer_user_id( - session: Session, - *, - requester: AccountPrincipal | None, - recorded_user_id: UUID | None, -) -> UUID | None: - """Return the ID of the user a read is for. - - That is ``recorded_user_id`` when a request was just recorded for it, or - else the requester's stored user's, or None. - """ - if recorded_user_id is not None: - return recorded_user_id - if requester is None: - return None - user = find_principal_user_in_session(session, requester) - return None if user is None else user.user_id - - -def _requesters_view( - session: Session, - rows: Sequence[StoredReportRows], - *, - requester: AccountPrincipal | None, - recorded_user_id: UUID | None = None, - with_requested_runs: bool, -) -> list[StoredReportRows]: - """Return the reports as the requester sees them. - - The requester's stored user is looked up, unless ``recorded_user_id`` - names the user a request was just recorded for. Each report takes its - label and description from that user's saved report of it. With - ``with_requested_runs``, a report the user asked to run - is read with the run of their newest request in place of its default (a - budget window's with that year's budget-window run and its years). A - request naming no user, or a user not stored yet, sees each report's - default run and no label. Raise StandardUserRequiresSignInError for an - unauthenticated credential that names a signed-in user. - """ - user_id = _viewer_user_id( - session, requester=requester, recorded_user_id=recorded_user_id - ) - if user_id is None or not rows: - return list(rows) - report_ids = [stored.report.id for stored in rows] - labels = request_reads.read_saved_report_labels( - session, user_id=user_id, report_ids=report_ids - ) - requested_runs = ( - request_reads.read_requested_report_runs( - session, user_id=user_id, report_ids=report_ids - ) - if with_requested_runs - else {} - ) - window_run_ids = [ - run.budget_window_run_id - for run in requested_runs.values() - if run.budget_window_run_id is not None - ] - window_runs = request_reads.read_budget_window_runs_by_id( - session, budget_window_run_ids=window_run_ids - ) - window_years = read_budget_window_years(session, window_run_ids) - viewed = [] - for stored in rows: - name, description = labels.get(stored.report.id, (None, None)) - seen = replace( - stored, saved_report_name=name, saved_report_description=description - ) - requested = requested_runs.get(stored.report.id) - if requested is not None and requested.budget_window_run_id is None: - seen = replace(seen, run=requested) - elif requested is not None and requested.budget_window_run_id in window_runs: - window_run_id = requested.budget_window_run_id - seen = replace( - seen, - budget_window_run=window_runs[window_run_id], - budget_window_years=window_years.get(window_run_id, ()), - ) - viewed.append(seen) - return viewed - - def _summary_read( stored: StoredReportRows, *, current_versions: PackageVersions ) -> StoredReportSummaryRead: @@ -448,7 +361,7 @@ def _read_report( """ with _storage_failures(), self._database_session.read() as session: stored = _stored_report(session, country_id=country_id, report_id=report_id) - (stored,) = _requesters_view( + (stored,) = requesters_view( session, [stored], requester=requester, @@ -558,7 +471,7 @@ def list_reports( cannot be read. """ with _storage_failures(), self._database_session.read() as session: - rows = _requesters_view( + rows = requesters_view( session, read_report_rows(session, country_id=country_id, report_ids=report_ids), requester=requester, @@ -593,7 +506,7 @@ def search_reports( dataset_independent_key=dataset_independent_key, limit=MAXIMUM_LISTED_REPORTS, ) - rows = _requesters_view( + rows = requesters_view( session, read_report_rows(session, country_id=country_id, report_ids=report_ids), requester=requester, From 6ef47cb61ee1831a36e6542ae32515d71f0dab82 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Tue, 17 Nov 2026 19:56:08 +0400 Subject: [PATCH 07/18] Read an economy report in its own method, and say how cliffs read Review round 1's quality findings: the economy read moves into _economy_report, as household reports and budget windows have theirs; the result's cliff_impact, the read and create routes, and a re-run of a run on older versions now say how cliffs read and start, and that a simulation service that doesn't calculate cliffs per simulation run yet refuses include_cliffs with 422; get_report names the reform check for a run in any status. The golden test that couldn't fail is replaced by one that fails if the report run's result columns hold a cliff column again. Co-Authored-By: Claude Opus 5.5 --- .../v2/reports/response_models.py | 10 +-- .../fastapi_routes/v2/reports/routes.py | 13 +++- .../fastapi_routes/v2/reports/run_models.py | 3 +- .../stored_reports/economy_results/types.py | 7 +- .../services/v2/stored_reports/services.py | 67 +++++++++++-------- .../services/v2/stored_reports/types.py | 7 +- tests/unit/v2/test_economy_result_rebuild.py | 17 ++--- 7 files changed, 71 insertions(+), 53 deletions(-) diff --git a/policyengine_api/fastapi_routes/v2/reports/response_models.py b/policyengine_api/fastapi_routes/v2/reports/response_models.py index 70584effd..6e8e190c3 100644 --- a/policyengine_api/fastapi_routes/v2/reports/response_models.py +++ b/policyengine_api/fastapi_routes/v2/reports/response_models.py @@ -168,10 +168,12 @@ class ReportCliffsItem(StrictReportAPIModel): the run shares them. ``status`` is ``succeeded`` once both sides are; otherwise ``failed`` when either side is, else ``not_calculated`` when either side is, else ``running`` when either side is, else ``pending``. - Running the report again with ``include_cliffs`` starts a new - calculation for each side that is ``not_calculated`` or ``failed``, and - joins one under way. A report naming one simulation run on both sides - gives its calculation for each. + Running the report again with ``include_cliffs`` on the current versions + starts a new calculation for each side that is ``not_calculated`` or + ``failed``, and joins one under way; a run on older versions is not run + again, so its re-run answers another run, with that run's ``cliffs``. A + report naming one simulation run on both sides gives its calculation for + each. """ status: CliffCalculationStatus diff --git a/policyengine_api/fastapi_routes/v2/reports/routes.py b/policyengine_api/fastapi_routes/v2/reports/routes.py index b72aee27f..e4586ae6a 100644 --- a/policyengine_api/fastapi_routes/v2/reports/routes.py +++ b/policyengine_api/fastapi_routes/v2/reports/routes.py @@ -484,8 +484,12 @@ def build_v2_report_router(dependencies: NativeRouteDependencies) -> APIRouter: "local authority's impact and the codes of those withheld; the " "simulation service takes it for uk and its four nations only, on a " "release that gives local areas a dataset of their own, and the " - "Public API answers its refusal with 422. A household report (kind " - "household) " + "Public API answers its refusal with 422. With include_cliffs, the " + "simulation service also starts a cliff calculation for each of an " + "economy report's two simulation runs that has none, or whose newest " + "one failed, and joins one under way; a simulation service that " + "doesn't calculate cliffs per simulation run yet refuses it with 422. " + "A household report (kind household) " "is checked the same way, except that the country must have " "household calculations instead (a household-only country does), " "and the household it names must be stored in the country, with a " @@ -573,7 +577,10 @@ def read() -> ReportListResponse | JSONResponse: "its result. Its label and description are the requesting user's " "saved report's name and description, null without a user " "credential or a saved report. An economy report's run is one report " - "run and its result today's economy result. A household report's " + "run and its result today's economy result; its cliffs say how far " + "the cliff calculations of the run's two simulation runs have got, " + "whatever the run's status, and the result's cliff_impact holds them " + "once both have succeeded. A household report's " "result is each simulation's calculated household, as " "/v2/household-calculations answers one, and a failed run gives each " "side's error. A budget window's run is a budget-window run with a " diff --git a/policyengine_api/fastapi_routes/v2/reports/run_models.py b/policyengine_api/fastapi_routes/v2/reports/run_models.py index 9dc6aaf72..b2a3a02d1 100644 --- a/policyengine_api/fastapi_routes/v2/reports/run_models.py +++ b/policyengine_api/fastapi_routes/v2/reports/run_models.py @@ -49,7 +49,8 @@ class ReportRerunRequest(StrictSubmissionModel): runs that has none, or whose newest one failed, and joins one under way; the report's ``cliffs`` then says how far they have got. Only an economy report has cliffs: a household report or budget window asking - for them is refused with 422. + for them is refused with 422, and so is any request with it while the + simulation service doesn't calculate cliffs per simulation run yet. """ force: StrictBool = False diff --git a/policyengine_api/services/v2/stored_reports/economy_results/types.py b/policyengine_api/services/v2/stored_reports/economy_results/types.py index fbfedefe8..6428c9020 100644 --- a/policyengine_api/services/v2/stored_reports/economy_results/types.py +++ b/policyengine_api/services/v2/stored_reports/economy_results/types.py @@ -326,8 +326,11 @@ class EconomyResult(EconomyResultModel): and ``local_authority_withheld_codes`` are a local-area report's sorted codes of the areas each level withheld, empty when it withheld none; for every other report they are null and left out of the JSON, as the - simulation service leaves them out. ``labor_supply_response`` and - ``cliff_impact`` are null when the run did not compute them. + simulation service leaves them out. ``labor_supply_response`` is null + when the run did not compute it, and ``cliff_impact`` until both + simulation runs' cliff calculations have succeeded: a run's cliffs are + calculated apart from it, and the report's ``cliffs`` says how far they + have got. """ spm_provenance: SPMComparisonProvenance | None diff --git a/policyengine_api/services/v2/stored_reports/services.py b/policyengine_api/services/v2/stored_reports/services.py index 8866cd938..5d095065e 100644 --- a/policyengine_api/services/v2/stored_reports/services.py +++ b/policyengine_api/services/v2/stored_reports/services.py @@ -157,6 +157,7 @@ from policyengine_api.services.v2.stored_reports.types import ( BudgetWindowReportRead, HouseholdReportRead, + ReportRead, StoredReportRead, StoredReportRows, StoredReportRunsRead, @@ -329,8 +330,9 @@ def get_report( ``run_id`` (a budget window's runs are its budget-window runs; any other report's, its own report runs), StandardUserRequiresSignInError for an unauthenticated credential - that names a signed-in user, EconomyResultUnreadableError when a - succeeded run's rows lack a part every result has, + that names a signed-in user, EconomyResultUnreadableError when an + economy run names no reform simulation run or a succeeded one's rows + lack a part every result has, HouseholdResultUnreadableError when a succeeded household report run's calculated households cannot be read, BudgetWindowResultUnreadableError when a succeeded window run's @@ -375,33 +377,42 @@ def _read_report( return self._budget_window(session, stored) if kind == "household": return self._household_report(session, stored) - run = stored.run - result = cliffs = None - if run is not None: - reform_simulation_run_id = require_reform_run(run) - cliff_calculations = result_reads.read_cliff_calculations( - session, - baseline_simulation_run_id=run.baseline_simulation_run_id, - reform_simulation_run_id=reform_simulation_run_id, - ) - cliffs = report_cliffs(cliff_calculations) - if run.status is ReportRunStatus.SUCCEEDED: - result = result_transformations.economy_result( - result_reads.read_economy_result_rows( - session, - country_id=country_id, - report_run=run, - reform_simulation_run_id=reform_simulation_run_id, - on_local_area_dataset=stored.on_local_area_dataset, - cliff_calculations=cliff_calculations, - ) - ) - return report_read( - stored, - current_versions=self._current_versions(country_id), - result=result, - cliffs=cliffs, + return self._economy_report(session, stored) + + def _economy_report(self, session: Session, stored: StoredReportRows) -> ReportRead: + """Return an economy report with its run's cliffs, and its result if succeeded. + + The cliffs of its two simulation runs are read whatever the run's + status, since they are calculated apart from it; the result's cliff + impact is theirs once both have succeeded. + """ + run = stored.run + result = cliffs = None + if run is not None: + reform_simulation_run_id = require_reform_run(run) + cliff_calculations = result_reads.read_cliff_calculations( + session, + baseline_simulation_run_id=run.baseline_simulation_run_id, + reform_simulation_run_id=reform_simulation_run_id, ) + cliffs = report_cliffs(cliff_calculations) + if run.status is ReportRunStatus.SUCCEEDED: + result = result_transformations.economy_result( + result_reads.read_economy_result_rows( + session, + country_id=stored.report.country, + report_run=run, + reform_simulation_run_id=reform_simulation_run_id, + on_local_area_dataset=stored.on_local_area_dataset, + cliff_calculations=cliff_calculations, + ) + ) + return report_read( + stored, + current_versions=self._current_versions(stored.report.country), + result=result, + cliffs=cliffs, + ) def _budget_window( self, session: Session, stored: StoredReportRows diff --git a/policyengine_api/services/v2/stored_reports/types.py b/policyengine_api/services/v2/stored_reports/types.py index 6787d967b..8d30de6d1 100644 --- a/policyengine_api/services/v2/stored_reports/types.py +++ b/policyengine_api/services/v2/stored_reports/types.py @@ -160,9 +160,10 @@ class ReportCliffsRead: ``status`` is ``succeeded`` once both sides are; otherwise ``failed`` when either side is, else ``not_calculated`` when either side is, else ``running`` when either side is, else ``pending``. A request with - ``include_cliffs`` starts a new calculation for each side that is - ``not_calculated`` or ``failed``. A report naming one simulation run on - both sides reads its calculation for each. + ``include_cliffs`` ending on this run (on the current versions) starts a + new calculation for each side that is ``not_calculated`` or ``failed``. + A report naming one simulation run on both sides reads its calculation + for each. """ status: CliffCalculationStatusName diff --git a/tests/unit/v2/test_economy_result_rebuild.py b/tests/unit/v2/test_economy_result_rebuild.py index 1a8957122..e19e55f35 100644 --- a/tests/unit/v2/test_economy_result_rebuild.py +++ b/tests/unit/v2/test_economy_result_rebuild.py @@ -15,7 +15,7 @@ from __future__ import annotations import json -from dataclasses import replace +from dataclasses import fields, replace from pathlib import Path from typing import Any from uuid import UUID, uuid4 @@ -214,18 +214,11 @@ def test_rows_the_simulation_services_own_writer_stored_rebuild_its_result( } -def test_the_golden_report_runs_cliff_columns_are_not_read() -> None: - case = next( - case for case in GOLDEN["cases"] if case["output"]["cliff_impact"] is not None - ) - assert all( - case["report_run_columns"][column] is not None - for column in REPORT_RUN_CLIFF_COLUMNS - ) - - rebuilt = result_transformations.economy_result(golden_rows(case)) +def test_the_report_runs_result_columns_hold_none_of_its_cliff_columns() -> None: + """A report run's cliffs are its simulation runs'; its own columns are not read.""" + column_names = {column.name for column in fields(ReportRunResultColumns)} - assert rebuilt.cliff_impact is None + assert column_names.isdisjoint(REPORT_RUN_CLIFF_COLUMNS) def test_the_golden_rows_cover_the_shapes_the_fixtures_alone_do_not() -> None: From 820ef6a3c6538348c9581a2c60237a4355d3379f Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Wed, 18 Nov 2026 18:26:44 +0400 Subject: [PATCH 08/18] Test that the API says a service may refuse cliffs (failing) The simulation service keeps refusing include_cliffs until it calculates cliffs per simulation run, so the OpenAPI document must say so wherever it tells callers to ask for them. Two client tests pin that service's own 422 bodies, which the Public API already reads and answers as 422. Test wording stops saying the report run writer has already stopped storing cliffs. Co-Authored-By: Claude Opus 5.5 --- tests/fixtures/economy_results.py | 7 ++--- .../integration/test_v2_report_cliff_reads.py | 2 +- .../libs/test_simulation_report_reruns.py | 25 +++++++++++++++- tests/unit/libs/test_simulation_reports.py | 29 +++++++++++++++++++ tests/unit/v2/test_economy_result_rebuild.py | 7 ++--- tests/unit/v2/test_report_read_routes.py | 24 +++++++++++++++ 6 files changed, 84 insertions(+), 10 deletions(-) diff --git a/tests/fixtures/economy_results.py b/tests/fixtures/economy_results.py index df75f45d8..a1c0b1b2b 100644 --- a/tests/fixtures/economy_results.py +++ b/tests/fixtures/economy_results.py @@ -10,10 +10,9 @@ and ``local_authority_withheld_codes`` list. A result's ``cliff_impact`` is not the report run's: each side's simulation run stores its own succeeded cliff calculation (``cliff_impacts``, which sim's cliff calculation writes, -not that writer), and the report run's four cliff columns stay null, as the -writer leaves them from PolicyEngine/policyengine-sim-api's C1 · 38 on. Each -row is a dict of the table's columns; ``id`` and ``created_at`` are left for -the caller. +not that writer), and the report run's four cliff columns stay null, since +no read uses them. Each row is a dict of the table's columns; ``id`` and +``created_at`` are left for the caller. """ from __future__ import annotations diff --git a/tests/integration/test_v2_report_cliff_reads.py b/tests/integration/test_v2_report_cliff_reads.py index f8c423bc0..27fc00960 100644 --- a/tests/integration/test_v2_report_cliff_reads.py +++ b/tests/integration/test_v2_report_cliff_reads.py @@ -157,7 +157,7 @@ def test_a_report_runs_own_cliff_columns_are_not_read( RunSettings(versions=CURRENT_VERSIONS), result=uk_economy_result(), ) - # As a report run stored its cliffs before C1 · 38. + # As the report run writer stores a result that has cliffs. connection.execute( text( "UPDATE report_runs SET baseline_cliff_gap = 1.0, " diff --git a/tests/unit/libs/test_simulation_report_reruns.py b/tests/unit/libs/test_simulation_report_reruns.py index 1ed0e2470..965eca484 100644 --- a/tests/unit/libs/test_simulation_report_reruns.py +++ b/tests/unit/libs/test_simulation_report_reruns.py @@ -142,7 +142,7 @@ def test_a_rerun_asking_for_cliffs_sends_include_cliffs() -> None: def test_a_rerun_not_asking_for_cliffs_sends_no_include_cliffs() -> None: - """Sim's re-run body before C1 · 39 refuses any field but ``force``.""" + """A service not calculating cliffs per simulation run takes only ``force``.""" service = ScriptedService() service.rerun(include_cliffs=False) @@ -151,6 +151,29 @@ def test_a_rerun_not_asking_for_cliffs_sends_no_include_cliffs() -> None: assert json.loads(request.content) == {"force": False} +def test_a_rerun_asking_for_cliffs_the_service_does_not_take_is_refused() -> None: + """FastAPI's 422 for the field, from a service taking only ``force``.""" + service = ScriptedService( + status_code=422, + body={ + "detail": [ + { + "type": "extra_forbidden", + "loc": ["body", "include_cliffs"], + "msg": "Extra inputs are not permitted", + "input": True, + } + ] + }, + ) + + with pytest.raises(SimulationServiceInvalidRequestError) as refused: + service.rerun(include_cliffs=True) + + assert route_status(refused.value) == 422 + assert "include_cliffs: Extra inputs are not permitted" in str(refused.value) + + @pytest.mark.parametrize("status_code", [201, 202]) def test_a_started_rerun_naming_the_report_is_accepted(status_code: int) -> None: service = ScriptedService( diff --git a/tests/unit/libs/test_simulation_reports.py b/tests/unit/libs/test_simulation_reports.py index bf3a0befc..b495df71d 100644 --- a/tests/unit/libs/test_simulation_reports.py +++ b/tests/unit/libs/test_simulation_reports.py @@ -282,6 +282,35 @@ def test_request_fields_the_service_refuses_are_reported_one_by_one() -> None: ) +def test_a_report_asking_for_cliffs_the_service_does_not_calculate_is_refused() -> None: + """The 422 of a service that doesn't calculate cliffs per simulation run.""" + reason = ( + "Cliff impacts are not calculated yet: they will be calculated for each " + "simulation run on its own. Send include_cliffs: false." + ) + service = RecordingService( + status_code=422, + body={ + "detail": [ + { + "loc": ["body", "include_cliffs"], + "msg": reason, + "type": "cliffs_not_available", + } + ], + "code": "cliffs_not_available", + }, + ) + + with pytest.raises(SimulationServiceInvalidRequestError) as refused: + service.client().submit_report(report_input(include_cliffs=True)) + + assert str(refused.value) == ( + "The simulation service cannot run this request (cliffs_not_available): " + f"include_cliffs: {reason}" + ) + + def test_a_refusal_names_the_services_code_when_it_gives_one() -> None: service = RecordingService( status_code=422, diff --git a/tests/unit/v2/test_economy_result_rebuild.py b/tests/unit/v2/test_economy_result_rebuild.py index e19e55f35..445a9c912 100644 --- a/tests/unit/v2/test_economy_result_rebuild.py +++ b/tests/unit/v2/test_economy_result_rebuild.py @@ -6,10 +6,9 @@ writer itself stored at a named commit (``scripts/generate_economy_result_golden.py``), so a rebuild that matches it reverses the real writer, and a change in the writer fails once the file is -generated again. That writer no longer stores cliffs -(PolicyEngine/policyengine-sim-api's C1 · 38): a result's cliff impact comes -from its two simulation runs' cliff calculations, so the golden rows rebuild -their results without one, whatever the report run's four cliff columns hold. +generated again. A report run's own cliff columns are not read: a result's +cliff impact comes from its two simulation runs' cliff calculations, so the +golden rows rebuild their results without one, whatever those columns hold. """ from __future__ import annotations diff --git a/tests/unit/v2/test_report_read_routes.py b/tests/unit/v2/test_report_read_routes.py index ad8810cf0..49f9ef37b 100644 --- a/tests/unit/v2/test_report_read_routes.py +++ b/tests/unit/v2/test_report_read_routes.py @@ -181,6 +181,30 @@ def test_the_openapi_document_describes_a_reports_cliffs() -> None: assert "cliffs" not in schemas["ReportSummaryItem"]["properties"] +def test_the_openapi_document_says_a_service_may_refuse_to_calculate_cliffs() -> None: + document = report_route_client().get("/v2/openapi.json").json() + create = document["paths"]["/v2/reports"]["post"] + rerun = document["paths"]["/v2/reports/{report_id}/runs"]["post"] + schemas = document["components"]["schemas"] + descriptions = { + "create route": create["description"], + "create 422": create["responses"]["422"]["description"], + "re-run route": rerun["description"], + "re-run 422": rerun["responses"]["422"]["description"], + "re-run body": schemas["ReportRerunRequest"]["description"], + "cliffs": schemas["ReportCliffsItem"]["description"], + } + + missing = [ + name + for name, description in descriptions.items() + if "doesn't calculate cliffs per simulation run" + not in " ".join(description.split()) + ] + + assert missing == [] + + @pytest.mark.parametrize( ("error", "status_code", "message"), [ From 63bbd8d763d04a16186ee06b875ed297cd59f4aa Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Wed, 18 Nov 2026 18:27:04 +0400 Subject: [PATCH 09/18] Say that a simulation service may refuse include_cliffs A simulation service that doesn't calculate cliffs per simulation run refuses include_cliffs with 422 and creates or starts nothing, and that can stay true for some time. The create and re-run routes, their 422 answers, the re-run body, cliffs and the changelog fragment now say so, and that each side stays not_calculated meanwhile. Co-Authored-By: Claude Opus 5.5 --- .../report-cliffs-from-simulation-runs.changed.md | 2 +- .../fastapi_routes/v2/reports/response_models.py | 8 ++++++-- .../fastapi_routes/v2/reports/routes.py | 14 ++++++++------ .../fastapi_routes/v2/reports/run_models.py | 9 ++++++--- policyengine_api/libs/simulation_report_reruns.py | 8 ++++---- .../services/v2/simulation_service/types.py | 10 +++++++--- .../services/v2/stored_reports/types.py | 3 ++- 7 files changed, 34 insertions(+), 20 deletions(-) diff --git a/changelog.d/report-cliffs-from-simulation-runs.changed.md b/changelog.d/report-cliffs-from-simulation-runs.changed.md index 8d3b1ebb0..adbe3ae2d 100644 --- a/changelog.d/report-cliffs-from-simulation-runs.changed.md +++ b/changelog.d/report-cliffs-from-simulation-runs.changed.md @@ -1 +1 @@ -`/v2/reports` reads a report run's cliff impact from its two simulation runs' cliff results, never from the report run's own cliff columns, and each economy report read gives `cliffs`: how far each side's cliff calculation has got. `POST /v2/reports/{report_id}/runs` takes `include_cliffs`, which a household report or budget window refuses with 422. +`/v2/reports` reads a report run's cliff impact from its two simulation runs' cliff results, never from the report run's own cliff columns, and each economy report read gives `cliffs`: how far each side's cliff calculation has got. `POST /v2/reports/{report_id}/runs` takes `include_cliffs`, which a household report or budget window refuses with 422. A simulation service that doesn't calculate cliffs per simulation run refuses `include_cliffs: true` with 422, on creates and re-runs alike. diff --git a/policyengine_api/fastapi_routes/v2/reports/response_models.py b/policyengine_api/fastapi_routes/v2/reports/response_models.py index 6e8e190c3..a7b9fc4fd 100644 --- a/policyengine_api/fastapi_routes/v2/reports/response_models.py +++ b/policyengine_api/fastapi_routes/v2/reports/response_models.py @@ -173,7 +173,9 @@ class ReportCliffsItem(StrictReportAPIModel): ``failed``, and joins one under way; a run on older versions is not run again, so its re-run answers another run, with that run's ``cliffs``. A report naming one simulation run on both sides gives its calculation for - each. + each. A simulation service that doesn't calculate cliffs per simulation + run starts none, so each side stays ``not_calculated``, and it refuses + ``include_cliffs`` with 422. """ status: CliffCalculationStatus @@ -547,7 +549,9 @@ class ReportRunNotRecordedResponse(V2ErrorResponse): "sets parameters the running catalog version does not have " "(code missing_parameters, which names them; the baseline's policy is " "checked first); or the simulation service cannot run the report: its " - "422, or its 400 for a region, dataset or dynamic it does not have. The " + "422, such as one that doesn't calculate cliffs per simulation run " + "refusing include_cliffs, or its 400 for a region, dataset or dynamic " + "it does not have. The " "message says which; for the simulation service's refusal, it gives " "the service's code, when it gave one, and its reason, but not its " "status." diff --git a/policyengine_api/fastapi_routes/v2/reports/routes.py b/policyengine_api/fastapi_routes/v2/reports/routes.py index e4586ae6a..32fbddec0 100644 --- a/policyengine_api/fastapi_routes/v2/reports/routes.py +++ b/policyengine_api/fastapi_routes/v2/reports/routes.py @@ -397,9 +397,11 @@ def _add_report_run_routes( "changes nothing for it. With include_cliffs, the simulation " "service also starts a cliff calculation for each of an economy " "report run's simulation runs that has none, or whose newest one " - "failed, and the answer's cliffs says how far they have got; a " - "household report or budget window asking for cliffs answers 422 " - "before anything is asked. A budget window's new run is a " + "failed, and the answer's cliffs says how far they have got. A " + "simulation service that doesn't calculate cliffs per simulation " + "run refuses include_cliffs with 422 and starts no run. A household " + "report or budget window asking for cliffs answers 422 before " + "anything is asked. A budget window's new run is a " "budget-window run with a report run for each year, and " "with force each year calculates its simulations again. Answers the " "report as stored, with the run the simulation service named (a " @@ -487,9 +489,9 @@ def build_v2_report_router(dependencies: NativeRouteDependencies) -> APIRouter: "Public API answers its refusal with 422. With include_cliffs, the " "simulation service also starts a cliff calculation for each of an " "economy report's two simulation runs that has none, or whose newest " - "one failed, and joins one under way; a simulation service that " - "doesn't calculate cliffs per simulation run yet refuses it with 422. " - "A household report (kind household) " + "one failed, and joins one under way. A simulation service that " + "doesn't calculate cliffs per simulation run refuses include_cliffs " + "with 422 and creates nothing. A household report (kind household) " "is checked the same way, except that the country must have " "household calculations instead (a household-only country does), " "and the household it names must be stored in the country, with a " diff --git a/policyengine_api/fastapi_routes/v2/reports/run_models.py b/policyengine_api/fastapi_routes/v2/reports/run_models.py index b2a3a02d1..681c71c72 100644 --- a/policyengine_api/fastapi_routes/v2/reports/run_models.py +++ b/policyengine_api/fastapi_routes/v2/reports/run_models.py @@ -49,8 +49,9 @@ class ReportRerunRequest(StrictSubmissionModel): runs that has none, or whose newest one failed, and joins one under way; the report's ``cliffs`` then says how far they have got. Only an economy report has cliffs: a household report or budget window asking - for them is refused with 422, and so is any request with it while the - simulation service doesn't calculate cliffs per simulation run yet. + for them is refused with 422. A simulation service that doesn't + calculate cliffs per simulation run refuses ``include_cliffs`` with 422 + and starts no run. """ force: StrictBool = False @@ -187,7 +188,9 @@ class RerunReportUnreadableResponse(V2ErrorResponse): "description": ( "The request does not match the schema; a household report or " "budget window asks for cliffs (include_cliffs), which only an " - "economy report has; the country has no economy " + "economy report has; a simulation service that doesn't calculate " + "cliffs per simulation run refuses include_cliffs; the country has " + "no economy " "reports, or no household calculations for a household report; a " "policy of the report's simulations sets " "parameters the running catalog version does not have (code " diff --git a/policyengine_api/libs/simulation_report_reruns.py b/policyengine_api/libs/simulation_report_reruns.py index 157d4db1c..f4588a59a 100644 --- a/policyengine_api/libs/simulation_report_reruns.py +++ b/policyengine_api/libs/simulation_report_reruns.py @@ -9,8 +9,8 @@ versions and starts it, keeping every earlier run. Without ``force``, each side reuses a run of its own simulation that succeeded on those versions. With ``include_cliffs``, it also starts a cliff calculation for each side's -simulation run that has none; until it calculates cliffs per simulation -run, it refuses the field with 422, which is passed on as any 422 is. +simulation run that has none; a service that doesn't calculate cliffs per +simulation run refuses the field with 422, passed on as any 422 is. The Public API reads the report in its country before asking, so it never asks about a report it does not have. The simulation service answers: @@ -138,8 +138,8 @@ def report_runs_path(report_id: UUID) -> str: def report_rerun_request(rerun: ReportRerunInput) -> dict[str, Any]: """Return the simulation service's request body for the re-run. - ``include_cliffs`` is sent only when true: a simulation service from - before cliffs were calculated per simulation run refuses the field, so a + ``include_cliffs`` is sent only when true: a simulation service that + doesn't calculate cliffs per simulation run refuses the field, so a re-run that doesn't ask for cliffs still runs there. """ body: dict[str, Any] = {"force": rerun.force} diff --git a/policyengine_api/services/v2/simulation_service/types.py b/policyengine_api/services/v2/simulation_service/types.py index 402c3d270..3cddcc831 100644 --- a/policyengine_api/services/v2/simulation_service/types.py +++ b/policyengine_api/services/v2/simulation_service/types.py @@ -263,7 +263,9 @@ class EconomyReportFields(ReportDefinitionFields): under way: a simulation run's cliffs are calculated once, apart from it, and every report naming the run shares them. It is never stored. The report's ``cliffs`` says how far they have got, and its result's - ``cliff_impact`` holds them once both have succeeded. + ``cliff_impact`` holds them once both have succeeded. A simulation + service that doesn't calculate cliffs per simulation run refuses it with + 422 and creates nothing. ``data_source`` ``local_area_dataset`` calculates both simulations on the dataset the catalog version gives local areas instead of the region's, so the result also has each constituency's and local @@ -433,8 +435,10 @@ class ReportRerunInput: simulations, baseline first, None for current law, a report of the baseline alone or a simulation that is gone, for the checks before the simulation service is asked. ``include_cliffs``, only for an economy - report, also starts a cliff calculation for each side's simulation run - that has none, or whose newest one failed; it is sent only when true. + report, asks the service to start a cliff calculation for each side's + simulation run that has none, or whose newest one failed; it is sent + only when true, and a service that doesn't calculate cliffs per + simulation run refuses it. """ country_id: str diff --git a/policyengine_api/services/v2/stored_reports/types.py b/policyengine_api/services/v2/stored_reports/types.py index 8d30de6d1..faba45779 100644 --- a/policyengine_api/services/v2/stored_reports/types.py +++ b/policyengine_api/services/v2/stored_reports/types.py @@ -163,7 +163,8 @@ class ReportCliffsRead: ``include_cliffs`` ending on this run (on the current versions) starts a new calculation for each side that is ``not_calculated`` or ``failed``. A report naming one simulation run on both sides reads its calculation - for each. + for each. A simulation service that doesn't calculate cliffs per + simulation run starts none and refuses ``include_cliffs``. """ status: CliffCalculationStatusName From 4a3e9fe117bd9b438c3958bc606d0188a34d866f Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Wed, 18 Nov 2026 18:36:21 +0400 Subject: [PATCH 10/18] Test the exact cliff refusal the API describes (failing) The OpenAPI text must name include_cliffs: true, since false is accepted, and say that a side with no calculation stays not_calculated, since a side with a stored calculation keeps its status. Test support stops describing sim's writers as if they had already changed: the fixture says it leaves out the report run's cliff columns, which sim's writer can still fill. Co-Authored-By: Claude Opus 5.5 --- tests/fixtures/economy_results.py | 10 +++++----- tests/integration/stored_report_rows.py | 2 +- .../integration/test_v2_report_cliff_reads.py | 7 +++---- tests/integration/test_v2_report_creation.py | 2 +- tests/integration/test_v2_report_runs.py | 4 ++-- tests/unit/v2/test_report_read_routes.py | 18 ++++++++++++------ 6 files changed, 24 insertions(+), 19 deletions(-) diff --git a/tests/fixtures/economy_results.py b/tests/fixtures/economy_results.py index a1c0b1b2b..68f739227 100644 --- a/tests/fixtures/economy_results.py +++ b/tests/fixtures/economy_results.py @@ -8,10 +8,10 @@ follow the writer as PolicyEngine/policyengine-sim-api#1068 changes it (``46c38f07``): one row per code a result's ``constituency_withheld_codes`` and ``local_authority_withheld_codes`` list. A result's ``cliff_impact`` is -not the report run's: each side's simulation run stores its own succeeded -cliff calculation (``cliff_impacts``, which sim's cliff calculation writes, -not that writer), and the report run's four cliff columns stay null, since -no read uses them. Each row is a dict of the table's columns; ``id`` and +the one exception: that writer can store it in the report run's four cliff +columns, which no read uses, so they are left out here, and it becomes a +succeeded ``cliff_impacts`` row for each side's simulation run, the rows the +Public API reads. Each row is a dict of the table's columns; ``id`` and ``created_at`` are left for the caller. """ @@ -371,7 +371,7 @@ class StoredEconomyResult: def economy_result_rows( output: dict[str, Any], *, run_ids: RunIds, country: str ) -> StoredEconomyResult: - """Return the rows the simulation service's writer stores ``output`` as.""" + """Return the rows ``output`` is read from, as the module docstring describes.""" report_keys = { "report_run_id": run_ids.report_run_id, "baseline_simulation_run_id": run_ids.baseline_simulation_run_id, diff --git a/tests/integration/stored_report_rows.py b/tests/integration/stored_report_rows.py index 53848196c..f2dc6fd3d 100644 --- a/tests/integration/stored_report_rows.py +++ b/tests/integration/stored_report_rows.py @@ -439,7 +439,7 @@ def store_cliff_calculation( # noqa: PLR0913 # the connection, the run and its cliff_gap: float | None = None, cliff_share: float | None = None, ) -> UUID: - """Store one cliff calculation of the simulation run, as sim and its worker do. + """Store one cliff calculation of the simulation run, in the state named. A finished calculation has a completion time; a succeeded one needs ``cliff_gap`` and ``cliff_share``, a failed one an ``error_message``. diff --git a/tests/integration/test_v2_report_cliff_reads.py b/tests/integration/test_v2_report_cliff_reads.py index 27fc00960..3bf8a1ec4 100644 --- a/tests/integration/test_v2_report_cliff_reads.py +++ b/tests/integration/test_v2_report_cliff_reads.py @@ -2,9 +2,8 @@ The routes run as the Public API's runtime role, so the tests prove its ``SELECT`` on ``cliff_impacts`` covers the read (rule -``api.v2.runtime-privileges-tested-as-runtime-role``). The simulation -service inserts a run's cliff calculations and its Modal worker finishes -them; here the database owner stores them, commits them, and the catalog's +``api.v2.runtime-privileges-tested-as-runtime-role``). The database owner +stores each run's cliff calculations here, commits them, and the catalog's deletion removes them with their runs. """ @@ -157,7 +156,7 @@ def test_a_report_runs_own_cliff_columns_are_not_read( RunSettings(versions=CURRENT_VERSIONS), result=uk_economy_result(), ) - # As the report run writer stores a result that has cliffs. + # The report run's own columns hold cliffs; its simulation runs have none. connection.execute( text( "UPDATE report_runs SET baseline_cliff_gap = 1.0, " diff --git a/tests/integration/test_v2_report_creation.py b/tests/integration/test_v2_report_creation.py index 6cebf553d..5dd5466d6 100644 --- a/tests/integration/test_v2_report_creation.py +++ b/tests/integration/test_v2_report_creation.py @@ -95,7 +95,7 @@ class StoringSimulationService: With ``answer_unstored``, it answers with IDs it stored nothing for, and keeps them in ``unstored_ids`` (a report's run in ``unstored_run_ids``). A report with ``include_cliffs`` also gets a pending cliff calculation for - each side's simulation run, as the simulation service starts them. + each side's simulation run, as a service calculating them per run starts them. """ engine: Engine diff --git a/tests/integration/test_v2_report_runs.py b/tests/integration/test_v2_report_runs.py index 57d8c959d..a05ef7b8b 100644 --- a/tests/integration/test_v2_report_runs.py +++ b/tests/integration/test_v2_report_runs.py @@ -155,8 +155,8 @@ class RerunningSimulationService: With ``window_years``, the report is a budget window, and the new run is a budget-window run with a pending report run for each of those years. A report run again with ``include_cliffs`` also gets a pending cliff - calculation for each side's new simulation run, as the simulation - service starts them. + calculation for each side's new simulation run, as a service calculating + them per run starts them. """ engine: Engine diff --git a/tests/unit/v2/test_report_read_routes.py b/tests/unit/v2/test_report_read_routes.py index 49f9ef37b..7513986be 100644 --- a/tests/unit/v2/test_report_read_routes.py +++ b/tests/unit/v2/test_report_read_routes.py @@ -195,14 +195,20 @@ def test_the_openapi_document_says_a_service_may_refuse_to_calculate_cliffs() -> "cliffs": schemas["ReportCliffsItem"]["description"], } - missing = [ + def states_the_refusal(description: str) -> bool: + words = " ".join(description.replace("`", "").split()) + return ( + "doesn't calculate cliffs per simulation run" in words + and "include_cliffs: true" in words + ) + + assert [ name for name, description in descriptions.items() - if "doesn't calculate cliffs per simulation run" - not in " ".join(description.split()) - ] - - assert missing == [] + if not states_the_refusal(description) + ] == [] + cliffs_description = " ".join(descriptions["cliffs"].replace("`", "").split()) + assert "a side with no calculation stays not_calculated" in cliffs_description @pytest.mark.parametrize( From 5b47027620178d8b07c2874be68ed7a2eecffca4 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Wed, 18 Nov 2026 18:36:41 +0400 Subject: [PATCH 11/18] State exactly when a simulation service refuses cliffs The API text names include_cliffs: true, which is what such a service refuses, and says only a side with no calculation stays not_calculated. A re-run's request docstring no longer implies that every re-run without the field runs: a stored report can still be refused for its own stored options. Co-Authored-By: Claude Opus 5.5 --- .../fastapi_routes/v2/reports/response_models.py | 10 +++++----- policyengine_api/fastapi_routes/v2/reports/routes.py | 10 +++++----- .../fastapi_routes/v2/reports/run_models.py | 8 ++++---- policyengine_api/libs/simulation_report_reruns.py | 2 +- .../services/v2/simulation_service/types.py | 4 ++-- policyengine_api/services/v2/stored_reports/types.py | 2 +- 6 files changed, 18 insertions(+), 18 deletions(-) diff --git a/policyengine_api/fastapi_routes/v2/reports/response_models.py b/policyengine_api/fastapi_routes/v2/reports/response_models.py index a7b9fc4fd..c3006acea 100644 --- a/policyengine_api/fastapi_routes/v2/reports/response_models.py +++ b/policyengine_api/fastapi_routes/v2/reports/response_models.py @@ -174,8 +174,8 @@ class ReportCliffsItem(StrictReportAPIModel): again, so its re-run answers another run, with that run's ``cliffs``. A report naming one simulation run on both sides gives its calculation for each. A simulation service that doesn't calculate cliffs per simulation - run starts none, so each side stays ``not_calculated``, and it refuses - ``include_cliffs`` with 422. + run starts none, so a side with no calculation stays ``not_calculated``, + and it refuses ``include_cliffs: true`` with 422. """ status: CliffCalculationStatus @@ -549,9 +549,9 @@ class ReportRunNotRecordedResponse(V2ErrorResponse): "sets parameters the running catalog version does not have " "(code missing_parameters, which names them; the baseline's policy is " "checked first); or the simulation service cannot run the report: its " - "422, such as one that doesn't calculate cliffs per simulation run " - "refusing include_cliffs, or its 400 for a region, dataset or dynamic " - "it does not have. The " + "422, or its 400 for a region, dataset or dynamic it does not have. A " + "simulation service that doesn't calculate cliffs per simulation run " + "answers that 422 for include_cliffs: true. The " "message says which; for the simulation service's refusal, it gives " "the service's code, when it gave one, and its reason, but not its " "status." diff --git a/policyengine_api/fastapi_routes/v2/reports/routes.py b/policyengine_api/fastapi_routes/v2/reports/routes.py index 32fbddec0..f5e76ebdf 100644 --- a/policyengine_api/fastapi_routes/v2/reports/routes.py +++ b/policyengine_api/fastapi_routes/v2/reports/routes.py @@ -399,9 +399,9 @@ def _add_report_run_routes( "report run's simulation runs that has none, or whose newest one " "failed, and the answer's cliffs says how far they have got. A " "simulation service that doesn't calculate cliffs per simulation " - "run refuses include_cliffs with 422 and starts no run. A household " - "report or budget window asking for cliffs answers 422 before " - "anything is asked. A budget window's new run is a " + "run refuses include_cliffs: true with 422 and starts no run. A " + "household report or budget window asking for cliffs answers 422 " + "before anything is asked. A budget window's new run is a " "budget-window run with a report run for each year, and " "with force each year calculates its simulations again. Answers the " "report as stored, with the run the simulation service named (a " @@ -490,8 +490,8 @@ def build_v2_report_router(dependencies: NativeRouteDependencies) -> APIRouter: "simulation service also starts a cliff calculation for each of an " "economy report's two simulation runs that has none, or whose newest " "one failed, and joins one under way. A simulation service that " - "doesn't calculate cliffs per simulation run refuses include_cliffs " - "with 422 and creates nothing. A household report (kind household) " + "doesn't calculate cliffs per simulation run refuses include_cliffs: " + "true with 422 and creates nothing. A household report (kind household) " "is checked the same way, except that the country must have " "household calculations instead (a household-only country does), " "and the household it names must be stored in the country, with a " diff --git a/policyengine_api/fastapi_routes/v2/reports/run_models.py b/policyengine_api/fastapi_routes/v2/reports/run_models.py index 681c71c72..626f3749d 100644 --- a/policyengine_api/fastapi_routes/v2/reports/run_models.py +++ b/policyengine_api/fastapi_routes/v2/reports/run_models.py @@ -50,8 +50,8 @@ class ReportRerunRequest(StrictSubmissionModel): the report's ``cliffs`` then says how far they have got. Only an economy report has cliffs: a household report or budget window asking for them is refused with 422. A simulation service that doesn't - calculate cliffs per simulation run refuses ``include_cliffs`` with 422 - and starts no run. + calculate cliffs per simulation run refuses ``include_cliffs: true`` with + 422 and starts no run. """ force: StrictBool = False @@ -189,8 +189,8 @@ class RerunReportUnreadableResponse(V2ErrorResponse): "The request does not match the schema; a household report or " "budget window asks for cliffs (include_cliffs), which only an " "economy report has; a simulation service that doesn't calculate " - "cliffs per simulation run refuses include_cliffs; the country has " - "no economy " + "cliffs per simulation run refuses include_cliffs: true; the country " + "has no economy " "reports, or no household calculations for a household report; a " "policy of the report's simulations sets " "parameters the running catalog version does not have (code " diff --git a/policyengine_api/libs/simulation_report_reruns.py b/policyengine_api/libs/simulation_report_reruns.py index f4588a59a..4ad1c7a1c 100644 --- a/policyengine_api/libs/simulation_report_reruns.py +++ b/policyengine_api/libs/simulation_report_reruns.py @@ -140,7 +140,7 @@ def report_rerun_request(rerun: ReportRerunInput) -> dict[str, Any]: ``include_cliffs`` is sent only when true: a simulation service that doesn't calculate cliffs per simulation run refuses the field, so a - re-run that doesn't ask for cliffs still runs there. + re-run that doesn't ask for cliffs isn't refused for it. """ body: dict[str, Any] = {"force": rerun.force} if rerun.include_cliffs: diff --git a/policyengine_api/services/v2/simulation_service/types.py b/policyengine_api/services/v2/simulation_service/types.py index 3cddcc831..4ab0657d4 100644 --- a/policyengine_api/services/v2/simulation_service/types.py +++ b/policyengine_api/services/v2/simulation_service/types.py @@ -264,8 +264,8 @@ class EconomyReportFields(ReportDefinitionFields): and every report naming the run shares them. It is never stored. The report's ``cliffs`` says how far they have got, and its result's ``cliff_impact`` holds them once both have succeeded. A simulation - service that doesn't calculate cliffs per simulation run refuses it with - 422 and creates nothing. + service that doesn't calculate cliffs per simulation run refuses + ``include_cliffs: true`` with 422 and creates nothing. ``data_source`` ``local_area_dataset`` calculates both simulations on the dataset the catalog version gives local areas instead of the region's, so the result also has each constituency's and local diff --git a/policyengine_api/services/v2/stored_reports/types.py b/policyengine_api/services/v2/stored_reports/types.py index faba45779..96f8f6cea 100644 --- a/policyengine_api/services/v2/stored_reports/types.py +++ b/policyengine_api/services/v2/stored_reports/types.py @@ -164,7 +164,7 @@ class ReportCliffsRead: new calculation for each side that is ``not_calculated`` or ``failed``. A report naming one simulation run on both sides reads its calculation for each. A simulation service that doesn't calculate cliffs per - simulation run starts none and refuses ``include_cliffs``. + simulation run starts none and refuses ``include_cliffs: true``. """ status: CliffCalculationStatusName From 6def63764e088bfbf88196eb0169edde755ac3fa Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Wed, 18 Nov 2026 18:44:09 +0400 Subject: [PATCH 12/18] Describe the cliff test rows by what they do The fixture and its callers say what they store rather than what sim's writer stores, so the text holds before and after that writer changes, and the create 422 keeps its sentence about the message beside the causes it refers to. No behaviour changes. Co-Authored-By: Claude Opus 5.5 --- .../fastapi_routes/v2/reports/response_models.py | 7 +++---- tests/fixtures/economy_results.py | 8 ++++---- tests/integration/stored_report_rows.py | 4 ++-- tests/unit/v2/test_economy_result_rebuild.py | 2 +- 4 files changed, 10 insertions(+), 11 deletions(-) diff --git a/policyengine_api/fastapi_routes/v2/reports/response_models.py b/policyengine_api/fastapi_routes/v2/reports/response_models.py index c3006acea..188cfb9de 100644 --- a/policyengine_api/fastapi_routes/v2/reports/response_models.py +++ b/policyengine_api/fastapi_routes/v2/reports/response_models.py @@ -549,12 +549,11 @@ class ReportRunNotRecordedResponse(V2ErrorResponse): "sets parameters the running catalog version does not have " "(code missing_parameters, which names them; the baseline's policy is " "checked first); or the simulation service cannot run the report: its " - "422, or its 400 for a region, dataset or dynamic it does not have. A " - "simulation service that doesn't calculate cliffs per simulation run " - "answers that 422 for include_cliffs: true. The " + "422, or its 400 for a region, dataset or dynamic it does not have. The " "message says which; for the simulation service's refusal, it gives " "the service's code, when it gave one, and its reason, but not its " - "status." + "status. A simulation service that doesn't calculate cliffs per " + "simulation run answers that 422 for include_cliffs: true." ), }, 502: { diff --git a/tests/fixtures/economy_results.py b/tests/fixtures/economy_results.py index 68f739227..0110fa8e3 100644 --- a/tests/fixtures/economy_results.py +++ b/tests/fixtures/economy_results.py @@ -8,10 +8,10 @@ follow the writer as PolicyEngine/policyengine-sim-api#1068 changes it (``46c38f07``): one row per code a result's ``constituency_withheld_codes`` and ``local_authority_withheld_codes`` list. A result's ``cliff_impact`` is -the one exception: that writer can store it in the report run's four cliff -columns, which no read uses, so they are left out here, and it becomes a -succeeded ``cliff_impacts`` row for each side's simulation run, the rows the -Public API reads. Each row is a dict of the table's columns; ``id`` and +the one exception: the report run's four cliff columns are left out, whatever +that writer stores there, since no read uses them, and it becomes a succeeded +``cliff_impacts`` row for each side's simulation run, the rows the Public API +reads. Each row is a dict of the table's columns; ``id`` and ``created_at`` are left for the caller. """ diff --git a/tests/integration/stored_report_rows.py b/tests/integration/stored_report_rows.py index f2dc6fd3d..59756f1c2 100644 --- a/tests/integration/stored_report_rows.py +++ b/tests/integration/stored_report_rows.py @@ -347,8 +347,8 @@ def store_report_run( ) -> RunIds: """Store a run of the report and its two simulation runs. - With ``result``, the run's result columns and rows are stored as the - simulation service's writer stores that economy result. + With ``result``, the run's result columns and rows are stored as + ``economy_result_rows`` gives them. """ budget_window_year = settings.budget_window_year simulation_run_settings = replace(settings, run_id=None) diff --git a/tests/unit/v2/test_economy_result_rebuild.py b/tests/unit/v2/test_economy_result_rebuild.py index 445a9c912..459377278 100644 --- a/tests/unit/v2/test_economy_result_rebuild.py +++ b/tests/unit/v2/test_economy_result_rebuild.py @@ -116,7 +116,7 @@ def stored_rows( reverse_rows: bool = False, on_local_area_dataset: bool = False, ) -> EconomyResultRows: - """Store ``output`` as the writer does and load its rows as table models. + """Store ``output`` as ``economy_result_rows`` does; load its table models. With ``reverse_rows``, each table's rows come back in reverse order, as a query without an order may return them. With ``on_local_area_dataset``, From ae8d464285689a64218709a38c6e42d059688e0e Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:12:23 +0400 Subject: [PATCH 13/18] Test that report runs stop loading their cliff columns (failing) API v1 no longer uses report_runs' four cliff columns, but every whole-row load of a report run still names them in its SQL. The release serving while a later revision drops them would then fail each report read. Co-Authored-By: Claude Opus 5.5 --- .../integration/test_v2_report_cliff_reads.py | 66 +++++++++++++++++-- tests/unit/v2/test_simulation_run_models.py | 10 +++ 2 files changed, 71 insertions(+), 5 deletions(-) diff --git a/tests/integration/test_v2_report_cliff_reads.py b/tests/integration/test_v2_report_cliff_reads.py index 3bf8a1ec4..16e3b7dd0 100644 --- a/tests/integration/test_v2_report_cliff_reads.py +++ b/tests/integration/test_v2_report_cliff_reads.py @@ -18,7 +18,7 @@ from alembic.config import Config from fastapi.testclient import TestClient from flask import Flask -from sqlalchemy import create_engine, text +from sqlalchemy import create_engine, event, text from sqlalchemy.orm import sessionmaker from sqlalchemy.pool import NullPool from sqlmodel import Session @@ -55,6 +55,12 @@ CURRENT_VERSIONS = {"country_package_version": "1.5.0", "policyengine_version": "4.2.0"} FAILURE = "cliff_calculation_failed: the calculation raised an error" +REPORT_RUN_CLIFF_COLUMNS = ( + "baseline_cliff_gap", + "baseline_cliff_share", + "reform_cliff_gap", + "reform_cliff_share", +) def current_versions(country_id: str) -> PackageVersions: @@ -83,9 +89,29 @@ def catalogs(owner_engine: Engine) -> Iterator[dict[str, CatalogRows]]: @pytest.fixture -def client(managed_v2_roles, v2_engine_as_role) -> Iterator[TestClient]: +def runtime_engine(managed_v2_roles, v2_engine_as_role) -> Iterator[Engine]: + engine = v2_engine_as_role(managed_v2_roles.runtime, poolclass=NullPool) + yield engine + engine.dispose() + + +@pytest.fixture +def runtime_statements(runtime_engine: Engine) -> list[str]: + """Collect each SQL statement the runtime role runs during the test.""" + statements: list[str] = [] + + def record_statement( + _connection, _cursor, statement, _parameters, _context, _executemany + ) -> None: + statements.append(statement) + + event.listen(runtime_engine, "before_cursor_execute", record_statement) + return statements + + +@pytest.fixture +def client(runtime_engine: Engine) -> Iterator[TestClient]: """Serve the report routes as the runtime role.""" - runtime_engine = v2_engine_as_role(managed_v2_roles.runtime, poolclass=NullPool) sessions = sessionmaker(runtime_engine, class_=Session) dependencies = NativeRouteDependencies( readiness_probe=lambda: True, @@ -100,12 +126,11 @@ def client(managed_v2_roles, v2_engine_as_role) -> Iterator[TestClient]: specification=RouteImplementation.FLASK_FALLBACK, metadata=RouteImplementation.FLASK_FALLBACK, ) - yield TestClient( + return TestClient( create_asgi_app( Flask(__name__), dependencies=dependencies, route_settings=settings ) ) - runtime_engine.dispose() def read_report(client: TestClient, report_id: object, country: str) -> Any: @@ -173,6 +198,37 @@ def test_a_report_runs_own_cliff_columns_are_not_read( assert item["cliffs"]["status"] == "not_calculated" +def test_reading_a_report_and_its_runs_names_no_report_run_cliff_column( + owner_engine: Engine, + catalogs: dict[str, CatalogRows], + client: TestClient, + runtime_statements: list[str], +) -> None: + with owner_engine.begin() as connection: + report = store_report(connection, catalogs["us"]) + store_report_run( + connection, + catalogs["us"], + report, + RunSettings(versions=CURRENT_VERSIONS), + result=us_economy_result(), + ) + + read_report(client, report.report_id, "us") + runs = client.get(f"/v2/reports/{report.report_id}/runs?country_id=us") + + assert runs.status_code == 200, runs.text + report_run_loads = [ + statement for statement in runtime_statements if "report_runs" in statement + ] + assert report_run_loads + assert [ + column + for column in REPORT_RUN_CLIFF_COLUMNS + if any(column in statement for statement in report_run_loads) + ] == [] + + def test_a_run_still_calculating_reads_each_sides_cliff_progress( owner_engine: Engine, catalogs: dict[str, CatalogRows], client: TestClient ) -> None: diff --git a/tests/unit/v2/test_simulation_run_models.py b/tests/unit/v2/test_simulation_run_models.py index d3282dcb6..63e6904aa 100644 --- a/tests/unit/v2/test_simulation_run_models.py +++ b/tests/unit/v2/test_simulation_run_models.py @@ -288,6 +288,16 @@ def test_report_runs_record_cliff_impact_spm_receipt_and_data_version() -> None: ) +def test_report_runs_load_and_write_none_of_their_cliff_columns() -> None: + """A run's cliffs are its simulation runs', so a revision can drop the columns.""" + loaded_columns = str(sa.select(ReportRun).compile(dialect=postgresql.dialect())) + + assert [name for name in CLIFF_IMPACT_COLUMNS if name in loaded_columns] == [] + assert set(CLIFF_IMPACT_COLUMNS).isdisjoint( + sa.inspect(ReportRun).column_attrs.keys() + ) + + def test_labor_supply_responses_have_one_typed_row_per_report_run() -> None: responses = V2_METADATA.tables["labor_supply_responses"] From 61ac1d0570985126c9a0515bbc0ce874779f0319 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:17:04 +0400 Subject: [PATCH 14/18] Stop mapping report runs' four cliff columns ReportRun leaves baseline_cliff_gap, baseline_cliff_share, reform_cliff_gap and reform_cliff_share out of its mapper, so API v1 neither selects nor writes them. The table keeps the columns, their check constraint and their grants, so there is no revision, and a release of this code keeps serving report reads while a later revision drops them. Co-Authored-By: Claude Opus 5.5 --- policyengine_api/data/v2/models/reports.py | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/policyengine_api/data/v2/models/reports.py b/policyengine_api/data/v2/models/reports.py index 3336b3130..1ccdd1c37 100644 --- a/policyengine_api/data/v2/models/reports.py +++ b/policyengine_api/data/v2/models/reports.py @@ -7,7 +7,7 @@ from datetime import datetime from enum import StrEnum -from typing import TYPE_CHECKING, Any +from typing import TYPE_CHECKING, Any, ClassVar from uuid import UUID import sqlalchemy as sa @@ -277,11 +277,12 @@ class ReportRun(TimestampedModel, table=True): It compares ``baseline_simulation_run_id`` with ``reform_simulation_run_id``; a household report with only a baseline has no reform run. A year of a budget window names its ``budget_window_run_id`` - and ``year``, at most one report run per year of a window run. An economy - comparison's cliff impact is the baseline's and reform's cliff gap and - share, stored together or not at all; ``spm_provenance`` is the SPM receipt - and ``data_version`` the data release it used. Its labour supply response - has its own two tables. + and ``year``, at most one report run per year of a window run. + ``spm_provenance`` is the SPM receipt and ``data_version`` the data release + it used. Its labour supply response has its own two tables. Its cliff impact + is its two simulation runs' (``CliffImpact``): the table's four older cliff + columns are left out of this model, so API v1 neither loads nor writes them + and a release keeps working while a later revision drops them. Outside budget windows, a report has at most one run that hasn't failed for each pair of package versions, which identical requests join; a @@ -290,6 +291,14 @@ class ReportRun(TimestampedModel, table=True): """ __tablename__ = "report_runs" + __mapper_args__: ClassVar[dict[str, Any]] = { + "exclude_properties": ( + "baseline_cliff_gap", + "baseline_cliff_share", + "reform_cliff_gap", + "reform_cliff_share", + ) + } __table_args__ = ( sa.UniqueConstraint( "report_id", From 6be2b3ef1f75fa5306af20014d552e4fa358edf3 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:33:29 +0400 Subject: [PATCH 15/18] Test that the unmapped cliff columns are not model fields (failing) Unmapped columns declared as typed fields still look usable: a loaded report run returns a Column object for them, and a value passed to the constructor is dropped without an error. The table keeps them through a documented direct SQLAlchemy category until a revision removes them. Co-Authored-By: Claude Opus 5.5 --- tests/integration/test_v2_report_cliff_reads.py | 2 +- tests/unit/v2/test_model_persistence.py | 1 + tests/unit/v2/test_simulation_run_models.py | 2 ++ 3 files changed, 4 insertions(+), 1 deletion(-) diff --git a/tests/integration/test_v2_report_cliff_reads.py b/tests/integration/test_v2_report_cliff_reads.py index 16e3b7dd0..0c4bf743b 100644 --- a/tests/integration/test_v2_report_cliff_reads.py +++ b/tests/integration/test_v2_report_cliff_reads.py @@ -110,7 +110,7 @@ def record_statement( @pytest.fixture -def client(runtime_engine: Engine) -> Iterator[TestClient]: +def client(runtime_engine: Engine) -> TestClient: """Serve the report routes as the runtime role.""" sessions = sessionmaker(runtime_engine, class_=Session) dependencies = NativeRouteDependencies( diff --git a/tests/unit/v2/test_model_persistence.py b/tests/unit/v2/test_model_persistence.py index 732fa7d98..f6759795b 100644 --- a/tests/unit/v2/test_model_persistence.py +++ b/tests/unit/v2/test_model_persistence.py @@ -101,6 +101,7 @@ def test_direct_sqlalchemy_categories_are_complete_and_documented() -> None: "named_constraints_and_indexes", "ambiguous_foreign_key_relationships", "transaction_conflict_recovery", + "unmapped_columns_awaiting_removal", } assert all(DIRECT_SQLALCHEMY_EXCEPTIONS.values()) diff --git a/tests/unit/v2/test_simulation_run_models.py b/tests/unit/v2/test_simulation_run_models.py index 63e6904aa..4b21ab1d8 100644 --- a/tests/unit/v2/test_simulation_run_models.py +++ b/tests/unit/v2/test_simulation_run_models.py @@ -296,6 +296,8 @@ def test_report_runs_load_and_write_none_of_their_cliff_columns() -> None: assert set(CLIFF_IMPACT_COLUMNS).isdisjoint( sa.inspect(ReportRun).column_attrs.keys() ) + assert set(CLIFF_IMPACT_COLUMNS).isdisjoint(ReportRun.model_fields) + assert [name for name in CLIFF_IMPACT_COLUMNS if hasattr(ReportRun, name)] == [] def test_labor_supply_responses_have_one_typed_row_per_report_run() -> None: From 3fed540fc51811dc4341b85c152fa6a410ad4ab2 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:40:18 +0400 Subject: [PATCH 16/18] Keep report runs' cliff columns in the table only The four columns move from typed SQLModel fields to __table_args__, so a report run has no attribute or constructor field for them, and API v1's list of direct SQLAlchemy uses names this one. The ReportRun description now says this covers only these four: trigger is still mapped, so it needs an earlier release of its own before a revision drops it. Co-Authored-By: Claude Opus 5.5 --- policyengine_api/data/v2/models/base.py | 5 +++++ policyengine_api/data/v2/models/reports.py | 17 ++++++++++------- 2 files changed, 15 insertions(+), 7 deletions(-) diff --git a/policyengine_api/data/v2/models/base.py b/policyengine_api/data/v2/models/base.py index 82e171a54..751968e38 100644 --- a/policyengine_api/data/v2/models/base.py +++ b/policyengine_api/data/v2/models/base.py @@ -39,6 +39,11 @@ "Concurrent report idempotency requires a savepoint and bounded " "IntegrityError recovery around the database uniqueness constraint." ), + "unmapped_columns_awaiting_removal": ( + "A column nothing uses stays in its table, outside the SQLModel " + "fields and the mapper, so a release that doesn't load it can serve " + "while a later revision drops it." + ), } ) diff --git a/policyengine_api/data/v2/models/reports.py b/policyengine_api/data/v2/models/reports.py index 1ccdd1c37..aae5ef99e 100644 --- a/policyengine_api/data/v2/models/reports.py +++ b/policyengine_api/data/v2/models/reports.py @@ -280,9 +280,11 @@ class ReportRun(TimestampedModel, table=True): and ``year``, at most one report run per year of a window run. ``spm_provenance`` is the SPM receipt and ``data_version`` the data release it used. Its labour supply response has its own two tables. Its cliff impact - is its two simulation runs' (``CliffImpact``): the table's four older cliff - columns are left out of this model, so API v1 neither loads nor writes them - and a release keeps working while a later revision drops them. + is its two simulation runs' (``CliffImpact``). The table's four older cliff + columns are declared in ``__table_args__`` and left out of the mapper, so API + v1 neither loads nor writes them. This covers only those four: ``trigger`` is + still mapped, so it must stop being mapped in an earlier release before a + revision drops it. Outside budget windows, a report has at most one run that hasn't failed for each pair of package versions, which identical requests join; a @@ -300,6 +302,11 @@ class ReportRun(TimestampedModel, table=True): ) } __table_args__ = ( + # Kept in the table, unmapped, until a revision drops them. + sa.Column("baseline_cliff_gap", sa.Float), + sa.Column("baseline_cliff_share", sa.Float), + sa.Column("reform_cliff_gap", sa.Float), + sa.Column("reform_cliff_share", sa.Float), sa.UniqueConstraint( "report_id", "idempotency_key", @@ -402,10 +409,6 @@ class ReportRun(TimestampedModel, table=True): ) error_message: str | None = None markdown: str | None = Field(default=None, sa_type=sa.Text) - baseline_cliff_gap: float | None = None - baseline_cliff_share: float | None = None - reform_cliff_gap: float | None = None - reform_cliff_share: float | None = None spm_provenance: dict[str, Any] | None = Field( default=None, sa_type=sa.JSON().with_variant(postgresql.JSONB(), "postgresql"), From 608cfb7e092cbf7c7e1b9bbc9acef5152f44f76a Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Thu, 19 Nov 2026 03:07:40 +0400 Subject: [PATCH 17/18] Test the table-only column category's new name (failing) The earlier name contained the text the v2 model layer's rule forbids. Co-Authored-By: Claude Opus 5.5 --- tests/unit/v2/test_model_persistence.py | 2 +- tests/unit/v2/test_simulation_run_models.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/unit/v2/test_model_persistence.py b/tests/unit/v2/test_model_persistence.py index f6759795b..492245ab8 100644 --- a/tests/unit/v2/test_model_persistence.py +++ b/tests/unit/v2/test_model_persistence.py @@ -101,7 +101,7 @@ def test_direct_sqlalchemy_categories_are_complete_and_documented() -> None: "named_constraints_and_indexes", "ambiguous_foreign_key_relationships", "transaction_conflict_recovery", - "unmapped_columns_awaiting_removal", + "table_only_columns_awaiting_removal", } assert all(DIRECT_SQLALCHEMY_EXCEPTIONS.values()) diff --git a/tests/unit/v2/test_simulation_run_models.py b/tests/unit/v2/test_simulation_run_models.py index 4b21ab1d8..bb95589f7 100644 --- a/tests/unit/v2/test_simulation_run_models.py +++ b/tests/unit/v2/test_simulation_run_models.py @@ -289,7 +289,7 @@ def test_report_runs_record_cliff_impact_spm_receipt_and_data_version() -> None: def test_report_runs_load_and_write_none_of_their_cliff_columns() -> None: - """A run's cliffs are its simulation runs', so a revision can drop the columns.""" + """A run's cliffs are its simulation runs', so API v1 leaves these columns alone.""" loaded_columns = str(sa.select(ReportRun).compile(dialect=postgresql.dialect())) assert [name for name in CLIFF_IMPACT_COLUMNS if name in loaded_columns] == [] From a3c941bd28f217d15de8c77da1dd9de9b33a05a0 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Thu, 19 Nov 2026 03:10:49 +0400 Subject: [PATCH 18/18] Name the table-only columns category accurately The category no longer contains text the v2 model layer's rule forbids, and it says API v1 stopped using these columns rather than that nothing does: the simulation service still writes them until its own change deploys. Co-Authored-By: Claude Opus 5.5 --- policyengine_api/data/v2/models/base.py | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/policyengine_api/data/v2/models/base.py b/policyengine_api/data/v2/models/base.py index 751968e38..4b435cd51 100644 --- a/policyengine_api/data/v2/models/base.py +++ b/policyengine_api/data/v2/models/base.py @@ -11,7 +11,8 @@ # These are the complete direct-SQLAlchemy categories permitted in the v2 # table layer. Each remains underneath canonical SQLModel table classes and -# Field/Relationship declarations; no parallel declarative model exists. +# Field/Relationship declarations, apart from table-only columns awaiting +# removal; no parallel declarative model exists. DIRECT_SQLALCHEMY_EXCEPTIONS = MappingProxyType( { "timezone_aware_timestamps": ( @@ -39,10 +40,10 @@ "Concurrent report idempotency requires a savepoint and bounded " "IntegrityError recovery around the database uniqueness constraint." ), - "unmapped_columns_awaiting_removal": ( - "A column nothing uses stays in its table, outside the SQLModel " - "fields and the mapper, so a release that doesn't load it can serve " - "while a later revision drops it." + "table_only_columns_awaiting_removal": ( + "A column API v1 no longer uses stays in its table, outside the " + "SQLModel fields and the mapper, until other writers have stopped " + "and a later revision drops it; API v1 doesn't load it meanwhile." ), } )