From 064adf9a7b0344947fa81a1a4eca7fa308288ed7 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 18:53:36 +0400 Subject: [PATCH 01/18] Test that economy reports take an optional local-area breakdown (failing) POST /reports accepts breakdown "local_areas" for a UK-wide or nation report, with or without include_cliffs, and records it in the report's options. A null, another value, another country, or a constituency or local-authority region is refused with 422 at the breakdown field. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_economy_routes.py | 72 +++++++++++++++++++ .../tests/test_openapi.py | 7 ++ 2 files changed, 79 insertions(+) diff --git a/projects/policyengine-simulation-entry/tests/test_economy_routes.py b/projects/policyengine-simulation-entry/tests/test_economy_routes.py index 90ca6e108..8d1b8706c 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_routes.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_routes.py @@ -219,6 +219,78 @@ def test_a_malformed_request_is_refused_with_its_reasons(client_for, path, body) assert (submissions.reports, submissions.simulations) == ([], []) +# A UK-wide report asking for its local-area breakdown, with cliffs and no +# SPM settings. +LOCAL_AREA_REPORT_BODY: dict[str, Any] = { + **{name: value for name, value in REPORT_BODY.items() if name != "spm"}, + "country": "uk", + "region_code": "uk", + "breakdown": "local_areas", +} + + +@pytest.mark.parametrize( + ("changes", "expected_message"), + [ + ({"breakdown": None}, "omit it to ask for no breakdown"), + ({"breakdown": "constituencies"}, "Input should be 'local_areas'"), + ( + {"country": "us", "region_code": "us"}, + "breakdown is supported only for UK requests", + ), + ({"region_code": "constituency/Aldershot"}, "UK-wide or nation region"), + ({"region_code": "local_authority/Cardiff"}, "UK-wide or nation region"), + ], + ids=[ + "null", + "another value", + "another country", + "a constituency", + "a local authority", + ], +) +def test_a_breakdown_a_report_cannot_have_is_refused( + client_for, changes, expected_message +) -> None: + submissions = FakeEconomySubmissions() + + with client_for(submissions) as client: + result = client.post("/reports", json={**LOCAL_AREA_REPORT_BODY, **changes}) + + assert result.status_code == 422 + (reason,) = result.json()["detail"] + assert reason["loc"][-1] == "breakdown" + assert expected_message in reason["msg"] + assert submissions.reports == [] + + +@pytest.mark.parametrize( + "region_code", + [ + "uk", + "country/england", + "country/scotland", + "country/wales", + "country/northern_ireland", + ], +) +def test_a_uk_wide_or_nation_report_may_ask_for_its_local_areas( + client_for, region_code +) -> None: + submissions = FakeEconomySubmissions() + + with client_for(submissions) as client: + result = client.post( + "/reports", json={**LOCAL_AREA_REPORT_BODY, "region_code": region_code} + ) + + assert result.status_code == 201 + ((request, _, _),) = submissions.reports + assert request.breakdown == "local_areas" + # The report still calculates cliffs, and stores that it asked for areas. + assert request.options() == {"include_cliffs": True, "breakdown": "local_areas"} + + @pytest.mark.parametrize(("path", "body"), ROUTES) def test_a_refusal_answers_400_with_its_code(client_for, path, body) -> None: submissions = FakeEconomySubmissions( diff --git a/projects/policyengine-simulation-entry/tests/test_openapi.py b/projects/policyengine-simulation-entry/tests/test_openapi.py index de8226b4d..aee37875f 100644 --- a/projects/policyengine-simulation-entry/tests/test_openapi.py +++ b/projects/policyengine-simulation-entry/tests/test_openapi.py @@ -440,6 +440,7 @@ def test_economy_requests_name_no_version_and_no_record_id(): "reform", "include_cliffs", "spm", + "breakdown", } assert set(schemas["EconomySimulationRequest"]["properties"]) == { "country", @@ -455,6 +456,12 @@ def test_economy_requests_name_no_version_and_no_record_id(): assert spm["$ref"] == "#/components/schemas/SPMSelection" assert "default" not in spm assert "spm" not in schemas["EconomyReportRequest"].get("required", []) + # Omitted, not null, unless the caller asks for the local-area breakdown. + breakdown = schemas["EconomyReportRequest"]["properties"]["breakdown"] + assert breakdown["const"] == "local_areas" + assert breakdown["type"] == "string" + assert "default" not in breakdown + assert "breakdown" not in schemas["EconomyReportRequest"].get("required", []) def test_a_report_request_is_an_economy_report_a_budget_window_or_a_household(): From 68f116776183a25ba7c3116678f8a65af115baee Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 18:54:56 +0400 Subject: [PATCH 02/18] Accept breakdown "local_areas" on UK-wide and nation economy reports EconomyReportRequest gains an optional breakdown, left out unless given. Null and any other value are refused with one reason, and the contract's local_area_breakdown_error refuses another country or a region other than uk and the four nations, all with 422 at the breakdown field. Neither include_cliffs nor segmented is passed to it: the national run calculates the cliffs, so the pair is accepted. The report's stored options record the breakdown only when it was asked for. Co-Authored-By: Claude Opus 5.5 --- .../economy_api_models.py | 73 ++++++++++++++++++- .../tests/test_economy_routes.py | 4 +- 2 files changed, 73 insertions(+), 4 deletions(-) diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py index cd0e71b0a..4b2b1bf5a 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py @@ -32,10 +32,21 @@ from typing import Annotated, Any, Literal from uuid import UUID +from policyengine_simulation_contract.local_area_breakdown import ( + LOCAL_AREAS_BREAKDOWN, + local_area_breakdown_error, +) from policyengine_simulation_contract.spm import SPMSelection from policyengine_simulation_contract.stage12_bundle import CountryId from policyengine_simulation_persistence import ReportRunStatus, SimulationStatus -from pydantic import BaseModel, ConfigDict, Field, StrictBool, field_validator +from pydantic import ( + BaseModel, + ConfigDict, + Field, + StrictBool, + ValidationInfo, + field_validator, +) from pydantic.json_schema import SkipJsonSchema # The bounds the tables accept. @@ -43,6 +54,9 @@ CatalogKey = Annotated[str, Field(min_length=1, max_length=255, pattern=r"^\S+$")] ReportLabel = Annotated[str, Field(min_length=1, max_length=255)] ReportDescription = Annotated[str, Field(max_length=10_000)] +# The one breakdown a report may ask for: its constituency and local-authority +# impacts, calculated on the local-area dataset beside the national result. +LocalAreasBreakdown = Literal["local_areas"] # Why a request is refused (400), naming a row the caller chose that doesn't # exist: the Public API answers these as its caller's error. @@ -135,6 +149,12 @@ class EconomyReportRequest(_Request): calculates the baseline's and reform's cliff impact. ``spm`` selects the SPM forecast scenario and geography; omit it, rather than sending null, to use the bundle's certified defaults. + + ``breakdown: "local_areas"`` also asks for the report's constituency and + local-authority impacts, calculated on the catalog version's local-area + dataset whatever ``dataset_name`` names. Only a UK report whose region is + ``uk`` or one of the four ``country/*`` nations may ask, with or without + ``include_cliffs``; omit it, rather than sending null, to ask for none. """ country: CountryId @@ -150,6 +170,10 @@ class EconomyReportRequest(_Request): spm: SPMSelection | SkipJsonSchema[None] = Field( default=None, json_schema_extra=omit_null_default ) + # Last, so its check can read the country and region. + breakdown: LocalAreasBreakdown | SkipJsonSchema[None] = Field( + default=None, json_schema_extra=omit_null_default + ) @field_validator("spm", mode="before") @classmethod @@ -160,15 +184,60 @@ def refuse_null_spm(cls, value: object) -> object: raise ValueError(msg) return value + @field_validator("breakdown", mode="before") + @classmethod + def refuse_another_breakdown(cls, value: object) -> object: + """Refuse null and any other value with one reason. + + Omit ``breakdown`` to ask for none. Without this, another value would + be refused once by each member of the field's type. + """ + if value != LOCAL_AREAS_BREAKDOWN: + msg = ( + f'breakdown must be "{LOCAL_AREAS_BREAKDOWN}" when given; omit it ' + "to ask for no breakdown" + ) + raise ValueError(msg) + return value + + @field_validator("breakdown") + @classmethod + def refuse_a_breakdown_the_region_cannot_have( + cls, breakdown: LocalAreasBreakdown | None, info: ValidationInfo + ) -> LocalAreasBreakdown | None: + """Refuse local areas for another country, or a region not UK-wide or a nation. + + A country or region that failed its own validation is reported by + that field alone. + """ + country = info.data.get("country") + region_code = info.data.get("region_code") + if breakdown is None or country is None or region_code is None: + return breakdown + # The breakdown's own calculation has no cliffs and no segments, so + # neither option is passed: the national run calculates the cliffs. + reason = local_area_breakdown_error( + country=country, + region=region_code, + region_group=None, + include_cliffs=None, + segmented=None, + ) + if reason is not None: + raise ValueError(reason) + return breakdown + def options(self) -> dict[str, Any]: """Return the report's options as it stores them (``reports.inputs``). ``spm`` holds only the settings the request gave, and is left out - when it gave none. + when it gave none; ``breakdown`` is there only when asked for. """ options: dict[str, Any] = {"include_cliffs": self.include_cliffs} if self.spm is not None: options["spm"] = self.spm.model_dump(mode="json") + if self.breakdown is not None: + options["breakdown"] = self.breakdown return options diff --git a/projects/policyengine-simulation-entry/tests/test_economy_routes.py b/projects/policyengine-simulation-entry/tests/test_economy_routes.py index 8d1b8706c..183c81534 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_routes.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_routes.py @@ -232,8 +232,8 @@ def test_a_malformed_request_is_refused_with_its_reasons(client_for, path, body) @pytest.mark.parametrize( ("changes", "expected_message"), [ - ({"breakdown": None}, "omit it to ask for no breakdown"), - ({"breakdown": "constituencies"}, "Input should be 'local_areas'"), + ({"breakdown": None}, 'breakdown must be "local_areas" when given'), + ({"breakdown": "constituencies"}, 'breakdown must be "local_areas" when given'), ( {"country": "us", "region_code": "us"}, "breakdown is supported only for UK requests", From d4957ed4f34b678b075f8a70204394704f82b4af Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 18:58:19 +0400 Subject: [PATCH 03/18] Test that the local-area dataset is read from the catalog version (failing) A catalog version's local-area dataset is the one default dataset its constituency and local-authority regions all use, even the national file. A version with no area regions, only one area type, or a dataset for each type has none, and another version's regions are never read. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_economy_run_records.py | 132 +++++++++++++++++- 1 file changed, 131 insertions(+), 1 deletion(-) diff --git a/libs/policyengine-simulation-persistence/tests/test_economy_run_records.py b/libs/policyengine-simulation-persistence/tests/test_economy_run_records.py index 1ddf50262..e4274e344 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_run_records.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_run_records.py @@ -35,6 +35,7 @@ insert_economy_simulation, read_dataset, read_dataset_by_id, + read_local_area_dataset, read_model_id, read_region, record_report_run_call, @@ -42,10 +43,16 @@ report_runs, simulation_runs, ) -from public_api_rows import insert_dataset, insert_policy, insert_region +from public_api_rows import ( + insert_catalog_version, + insert_dataset, + insert_policy, + insert_region, +) from sqlalchemy import select, text, update if TYPE_CHECKING: + from public_api_rows import CatalogVersion from sqlalchemy import Connection pytestmark = pytest.mark.public_api_schema @@ -179,6 +186,129 @@ def test_a_dataset_is_found_by_name_or_id_in_its_catalog_version_only( assert (by_id.id, by_id.name) == (economy.dataset_id, "populace_us_2024") +def _insert_area_regions( + connection: Connection, + catalog: CatalogVersion, + *, + constituency_dataset_id: UUID, + local_authority_dataset_id: UUID, +) -> None: + """Insert two constituencies and a local authority, each using its dataset.""" + for code in ("constituency/Aldershot", "constituency/Cardiff West"): + insert_region( + connection, + catalog, + code, + default_dataset_id=constituency_dataset_id, + region_type="constituency", + ) + insert_region( + connection, + catalog, + "local_authority/Cardiff", + default_dataset_id=local_authority_dataset_id, + region_type="local_authority", + ) + + +def test_the_local_area_dataset_is_the_one_both_area_types_use( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection, country="uk") + local_area_id = insert_dataset( + connection, economy.catalog, "microcosm_uk_2024_25_dense" + ) + _insert_area_regions( + connection, + economy.catalog, + constituency_dataset_id=local_area_id, + local_authority_dataset_id=local_area_id, + ) + # Another catalog version of the model routes its areas elsewhere. + older = insert_catalog_version( + connection, + country="uk", + model_id=economy.catalog.model_id, + policyengine_version="6.16.0", + ) + older_dataset_id = insert_dataset(connection, older, "microcosm_uk_2024_25") + _insert_area_regions( + connection, + older, + constituency_dataset_id=older_dataset_id, + local_authority_dataset_id=older_dataset_id, + ) + act_as_the_service(connection) + + found = read_local_area_dataset( + connection, catalog_version_id=economy.catalog.version_id + ) + + assert found is not None + assert (found.id, found.name) == (local_area_id, "microcosm_uk_2024_25_dense") + + +@pytest.mark.parametrize( + "area_regions", ["none", "constituencies only", "a dataset for each type"] +) +def test_a_catalog_version_without_one_dataset_for_both_area_types_has_none( + public_api_database_url, area_regions +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection, country="uk") + constituency_dataset_id = insert_dataset( + connection, economy.catalog, "microcosm_uk_constituencies" + ) + local_authority_dataset_id = insert_dataset( + connection, economy.catalog, "microcosm_uk_local_authorities" + ) + if area_regions == "constituencies only": + insert_region( + connection, + economy.catalog, + "constituency/Aldershot", + default_dataset_id=constituency_dataset_id, + region_type="constituency", + ) + elif area_regions == "a dataset for each type": + _insert_area_regions( + connection, + economy.catalog, + constituency_dataset_id=constituency_dataset_id, + local_authority_dataset_id=local_authority_dataset_id, + ) + act_as_the_service(connection) + + found = read_local_area_dataset( + connection, catalog_version_id=economy.catalog.version_id + ) + + assert found is None + + +def test_the_local_area_dataset_may_be_the_national_default( + public_api_database_url, +) -> None: + """Stage 12 leaves the areas out of a national run whenever both use one file.""" + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection, country="uk") + _insert_area_regions( + connection, + economy.catalog, + constituency_dataset_id=economy.dataset_id, + local_authority_dataset_id=economy.dataset_id, + ) + act_as_the_service(connection) + + found = read_local_area_dataset( + connection, catalog_version_id=economy.catalog.version_id + ) + + assert found is not None + assert (found.id, found.name) == (economy.dataset_id, "populace_uk_2024") + + def test_a_report_its_simulations_and_runs_are_created_pending( public_api_database_url, ) -> None: From b4e95c10fa054a4d60fce37fa9db0f825e2f07d5 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 18:59:39 +0400 Subject: [PATCH 04/18] Read a catalog version's local-area dataset read_local_area_dataset returns the one default dataset every constituency and local-authority region of the version uses, or None when the version has no such regions, only one type, or a dataset for each. It is never chosen from the request's dataset_name. It may be the national file: Stage 12 leaves the areas out of a UK-wide or nation run whenever the release routes both types to one dataset, so the areas are calculated apart even then. The read-only regions model gains region_type, modelled as the Public API's v2_region_type enum, which the pinned schema comparison checks. Co-Authored-By: Claude Opus 5.5 --- .../__init__.py | 2 + .../economy_run_records.py | 41 +++++++++++++++++++ .../input_tables.py | 31 +++++++++++++- 3 files changed, 73 insertions(+), 1 deletion(-) diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py index 461bda49c..cc5dbe895 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py @@ -37,6 +37,7 @@ insert_economy_simulation, read_dataset, read_dataset_by_id, + read_local_area_dataset, read_model_id, read_region, record_report_run_call, @@ -202,6 +203,7 @@ "read_economy_report", "read_economy_simulation", "read_household_job", + "read_local_area_dataset", "read_missing_table_privileges", "read_model_id", "read_policy_reform", diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_records.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_records.py index 10c7ea28a..a56ee1fbc 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_records.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_records.py @@ -38,6 +38,7 @@ from typing import TYPE_CHECKING, Any, Final from sqlalchemy import ( + String, cast, func, insert, @@ -51,6 +52,7 @@ from policyengine_simulation_persistence.input_tables import ( MODEL_NAME_PREFIX, + UK_AREA_REGION_TYPES, datasets, regions, tax_benefit_models, @@ -265,6 +267,45 @@ def read_dataset_by_id( return _dataset(connection, catalog_version_id, datasets.c.id == dataset_id) +def read_local_area_dataset( + connection: Connection, *, catalog_version_id: UUID +) -> CatalogDataset | None: + """Return the catalog version's local-area dataset, or None when it has none. + + It is the one default dataset every constituency and local-authority + region of the version uses. The Public API's catalog lists those regions + only when the .py release routes them to a dataset of their own, and + gives them that dataset, so a version with no such regions, with only + one of the two types, or with a dataset for each type has none: its + national runs calculate both area levels themselves. The dataset may be + the national file: Stage 12 leaves the areas out of a UK-wide or nation + run whenever the release routes both types to one dataset + (``uk_area_breakdowns_omitted``), so they are calculated apart even then. + """ + region_type = cast(regions.c.region_type, String) + rows = connection.execute( + select(region_type.label("region_type"), datasets.c.id, datasets.c.name) + .distinct() + .join( + datasets, + (datasets.c.id == regions.c.default_dataset_id) + & ( + datasets.c.tax_benefit_model_version_id + == regions.c.tax_benefit_model_version_id + ), + ) + .where( + regions.c.tax_benefit_model_version_id == catalog_version_id, + region_type.in_(UK_AREA_REGION_TYPES), + ) + ).all() + region_types = {row.region_type for row in rows} + found = {CatalogDataset(id=row.id, name=row.name) for row in rows} + if region_types != set(UK_AREA_REGION_TYPES) or len(found) != 1: + return None + return found.pop() + + def _dataset( connection: Connection, catalog_version_id: UUID, condition: ColumnElement[bool] ) -> CatalogDataset | None: diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/input_tables.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/input_tables.py index ec9797fad..76200115f 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/input_tables.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/input_tables.py @@ -15,7 +15,16 @@ from typing import Final -from sqlalchemy import Column, DateTime, Integer, MetaData, String, Table, Uuid +from sqlalchemy import ( + Column, + DateTime, + Enum, + Integer, + MetaData, + String, + Table, + Uuid, +) from sqlalchemy.dialects.postgresql import JSONB from policyengine_simulation_persistence.tables import TABLE_SCHEMA @@ -24,6 +33,20 @@ # A country's tax-benefit model is named "policyengine-". MODEL_NAME_PREFIX: Final = "policyengine-" +# The kinds of geography a region covers, as the Public API's +# ``v2_region_type`` lists them. +REGION_TYPES: Final = ( + "national", + "country", + "state", + "congressional_district", + "constituency", + "local_authority", + "city", + "place", +) +# The UK region types a local-area breakdown covers. +UK_AREA_REGION_TYPES: Final = ("constituency", "local_authority") tax_benefit_models = Table( "tax_benefit_models", @@ -49,6 +72,12 @@ input_metadata, Column("id", Uuid, nullable=False), Column("code", String(255), nullable=False), + # The enum names its schema itself, as the service tables' enums do. + Column( + "region_type", + Enum(*REGION_TYPES, name="v2_region_type", schema=TABLE_SCHEMA), + nullable=False, + ), Column("tax_benefit_model_version_id", Uuid, nullable=False), Column("default_dataset_id", Uuid, nullable=False), ) From a2e23a8e6d51413e0241be2900f61ce4bd853e1a Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 19:58:01 +0400 Subject: [PATCH 05/18] Test that local areas follow the worker's declaration and the catalog (failing) A report asking for local areas is refused with 400 local_areas_unsupported, before any read, when the default worker's UK entry declares no local-area report runs or another input version. When the declaration names no dataset, the release routes the areas to none of their own and no area part is made. When it names one, the store reads that catalog dataset with the report's inputs, never the request's dataset_name, and refuses it (400 local_area_dataset_mismatch) unless the catalog gives both area types that dataset. Co-Authored-By: Claude Opus 5.5 --- .../tests/economy_rows.py | 25 +++ .../tests/test_economy_run_records.py | 35 +--- .../tests/test_economy_run_store.py | 77 ++++++++ .../tests/economy_fixtures.py | 34 ++++ .../tests/economy_service_fakes.py | 30 +++- .../tests/test_local_area_submissions.py | 164 ++++++++++++++++++ 6 files changed, 330 insertions(+), 35 deletions(-) create mode 100644 projects/policyengine-simulation-entry/tests/test_local_area_submissions.py diff --git a/libs/policyengine-simulation-persistence/tests/economy_rows.py b/libs/policyengine-simulation-persistence/tests/economy_rows.py index 4cb6a9014..830d2197d 100644 --- a/libs/policyengine-simulation-persistence/tests/economy_rows.py +++ b/libs/policyengine-simulation-persistence/tests/economy_rows.py @@ -89,6 +89,31 @@ def insert_economy_catalog( return EconomyCatalog(catalog=catalog, dataset_id=dataset_id, region_id=region_id) +def insert_uk_area_regions( + connection: Connection, + catalog: CatalogVersion, + *, + constituency_dataset_id: UUID, + local_authority_dataset_id: UUID, +) -> None: + """Insert two constituencies and a local authority, each using its dataset.""" + for code in ("constituency/Aldershot", "constituency/Cardiff West"): + insert_region( + connection, + catalog, + code, + default_dataset_id=constituency_dataset_id, + region_type="constituency", + ) + insert_region( + connection, + catalog, + "local_authority/Cardiff", + default_dataset_id=local_authority_dataset_id, + region_type="local_authority", + ) + + @dataclass(frozen=True) class StoredRun: """A simulation and one of its runs, as stored.""" diff --git a/libs/policyengine-simulation-persistence/tests/test_economy_run_records.py b/libs/policyengine-simulation-persistence/tests/test_economy_run_records.py index e4274e344..c3da4fb32 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_run_records.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_run_records.py @@ -20,6 +20,7 @@ EconomyCatalog, insert_economy_catalog, insert_reusable_run, + insert_uk_area_regions, ) from policyengine_simulation_persistence import ( EconomyRecordReferenceError, @@ -52,7 +53,6 @@ from sqlalchemy import select, text, update if TYPE_CHECKING: - from public_api_rows import CatalogVersion from sqlalchemy import Connection pytestmark = pytest.mark.public_api_schema @@ -186,31 +186,6 @@ def test_a_dataset_is_found_by_name_or_id_in_its_catalog_version_only( assert (by_id.id, by_id.name) == (economy.dataset_id, "populace_us_2024") -def _insert_area_regions( - connection: Connection, - catalog: CatalogVersion, - *, - constituency_dataset_id: UUID, - local_authority_dataset_id: UUID, -) -> None: - """Insert two constituencies and a local authority, each using its dataset.""" - for code in ("constituency/Aldershot", "constituency/Cardiff West"): - insert_region( - connection, - catalog, - code, - default_dataset_id=constituency_dataset_id, - region_type="constituency", - ) - insert_region( - connection, - catalog, - "local_authority/Cardiff", - default_dataset_id=local_authority_dataset_id, - region_type="local_authority", - ) - - def test_the_local_area_dataset_is_the_one_both_area_types_use( public_api_database_url, ) -> None: @@ -219,7 +194,7 @@ def test_the_local_area_dataset_is_the_one_both_area_types_use( local_area_id = insert_dataset( connection, economy.catalog, "microcosm_uk_2024_25_dense" ) - _insert_area_regions( + insert_uk_area_regions( connection, economy.catalog, constituency_dataset_id=local_area_id, @@ -233,7 +208,7 @@ def test_the_local_area_dataset_is_the_one_both_area_types_use( policyengine_version="6.16.0", ) older_dataset_id = insert_dataset(connection, older, "microcosm_uk_2024_25") - _insert_area_regions( + insert_uk_area_regions( connection, older, constituency_dataset_id=older_dataset_id, @@ -272,7 +247,7 @@ def test_a_catalog_version_without_one_dataset_for_both_area_types_has_none( region_type="constituency", ) elif area_regions == "a dataset for each type": - _insert_area_regions( + insert_uk_area_regions( connection, economy.catalog, constituency_dataset_id=constituency_dataset_id, @@ -293,7 +268,7 @@ def test_the_local_area_dataset_may_be_the_national_default( """Stage 12 leaves the areas out of a national run whenever both use one file.""" with rolled_back_transaction(public_api_database_url) as connection: economy = insert_economy_catalog(connection, country="uk") - _insert_area_regions( + insert_uk_area_regions( connection, economy.catalog, constituency_dataset_id=economy.dataset_id, diff --git a/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py b/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py index 7ba3e04c8..79b7c4497 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py @@ -24,6 +24,7 @@ VERSIONS, insert_economy_catalog, insert_reusable_run, + insert_uk_area_regions, ) from policyengine_simulation_persistence import ( CatalogDataset, @@ -33,6 +34,7 @@ EconomyRecordOutcomeUnknownError, EconomyRequest, EconomyRunStore, + LocalAreaDatasetMismatchError, MissingPolicyParametersError, NewEconomyReport, NewEconomySimulation, @@ -140,6 +142,81 @@ def test_a_reports_inputs_are_read_together(public_api_database_url) -> None: assert without_reuse.baseline.reusable_run is None +UK_REQUEST = replace(REQUEST, country="uk", region_code="uk") +# The dataset the UK worker declares it calculates local areas on. +LOCAL_AREA_DATASET_NAME = "microcosm_uk_2024_25_dense" + + +def test_a_reports_local_area_dataset_is_read_with_its_inputs( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection, country="uk") + local_area_id = insert_dataset( + connection, economy.catalog, LOCAL_AREA_DATASET_NAME + ) + insert_uk_area_regions( + connection, + economy.catalog, + constituency_dataset_id=local_area_id, + local_authority_dataset_id=local_area_id, + ) + act_as_the_service(connection) + store = _store_on(connection) + + with_areas = store.read_report_inputs( + UK_REQUEST, + baseline=CURRENT_LAW, + reform=CURRENT_LAW, + reuse=None, + local_area_dataset_name=LOCAL_AREA_DATASET_NAME, + ) + without_areas = store.read_report_inputs( + UK_REQUEST, baseline=CURRENT_LAW, reform=CURRENT_LAW, reuse=None + ) + + assert with_areas.local_area_dataset == CatalogDataset( + id=local_area_id, name=LOCAL_AREA_DATASET_NAME + ) + assert without_areas.local_area_dataset is None + # The national part is read as it is without the local areas. + assert with_areas.catalog == without_areas.catalog + + +@pytest.mark.parametrize( + "area_datasets", ["another dataset", "a dataset for each type"] +) +def test_a_declared_dataset_the_catalog_does_not_give_both_area_types_is_refused( + public_api_database_url, area_datasets +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection, country="uk") + local_area_id = insert_dataset( + connection, economy.catalog, LOCAL_AREA_DATASET_NAME + ) + other_id = insert_dataset(connection, economy.catalog, "microcosm_uk_2024_25") + insert_uk_area_regions( + connection, + economy.catalog, + constituency_dataset_id=( + other_id if area_datasets == "another dataset" else local_area_id + ), + local_authority_dataset_id=other_id, + ) + act_as_the_service(connection) + + with pytest.raises(LocalAreaDatasetMismatchError) as mismatch: + _store_on(connection).read_report_inputs( + UK_REQUEST, + baseline=CURRENT_LAW, + reform=CURRENT_LAW, + reuse=None, + local_area_dataset_name=LOCAL_AREA_DATASET_NAME, + ) + + assert mismatch.value.declared_dataset == LOCAL_AREA_DATASET_NAME + + def test_the_two_sides_never_reuse_the_same_run(public_api_database_url) -> None: with rolled_back_transaction(public_api_database_url) as connection: economy = insert_economy_catalog(connection) diff --git a/projects/policyengine-simulation-entry/tests/economy_fixtures.py b/projects/policyengine-simulation-entry/tests/economy_fixtures.py index d24a831bd..d6eebf30e 100644 --- a/projects/policyengine-simulation-entry/tests/economy_fixtures.py +++ b/projects/policyengine-simulation-entry/tests/economy_fixtures.py @@ -9,6 +9,8 @@ from household_fixtures import POLICYENGINE_VERSION, household_worker_version from policyengine_simulation_contract.stage12_bundle import Stage12Dataset from policyengine_simulation_contract.stage12_manifest import ( + LOCAL_AREA_REPORTS_VERSION, + LocalAreaReports, V2VersionManifest, V2WorkerVersion, ) @@ -20,6 +22,19 @@ sha256="c" * 64, repo_type="dataset", ) +# The dataset the UK release routes constituencies and local authorities to. +LOCAL_AREA_DATASET = Stage12Dataset( + identity="microcosm_uk_2024_25_dense", + uri="hf://policyengine/data/microcosm_uk_2024_25_dense.h5@dense-revision", + artifact_revision="dense-revision", + sha256="d" * 64, + repo_type="dataset", +) +# A UK worker's declaration that its coordinator runs local-area report runs +# on that dataset. +ROUTED_LOCAL_AREAS = LocalAreaReports( + input_version=LOCAL_AREA_REPORTS_VERSION, dataset=LOCAL_AREA_DATASET.identity +) def economy_worker_version( @@ -38,6 +53,25 @@ def economy_worker_version( ) +def local_area_worker_version( + local_area_reports: LocalAreaReports | None, +) -> V2WorkerVersion: + """Return the economy worker with the local-area dataset in its UK bundle. + + Its UK entry declares ``local_area_reports``, or nothing for None. The + worker is validated again, so the declaration must name a dataset of the + UK bundle. + """ + document = economy_worker_version().model_dump(mode="json") + for country in document["bundle"]["countries"]: + if country["country"] == "uk": + country["datasets"].append(LOCAL_AREA_DATASET.model_dump(mode="json")) + for country in document["countries"]: + if country["country"] == "uk" and local_area_reports is not None: + country["local_area_reports"] = local_area_reports.model_dump(mode="json") + return V2WorkerVersion.model_validate(document) + + def economy_manifest( default_worker: V2WorkerVersion | None = None, ) -> V2VersionManifest: diff --git a/projects/policyengine-simulation-entry/tests/economy_service_fakes.py b/projects/policyengine-simulation-entry/tests/economy_service_fakes.py index 535873f0f..b2af1c5c2 100644 --- a/projects/policyengine-simulation-entry/tests/economy_service_fakes.py +++ b/projects/policyengine-simulation-entry/tests/economy_service_fakes.py @@ -7,7 +7,7 @@ from __future__ import annotations import asyncio -from dataclasses import dataclass, field +from dataclasses import dataclass, field, replace from datetime import UTC, datetime from itertools import count from typing import TYPE_CHECKING, Any @@ -43,6 +43,7 @@ if TYPE_CHECKING: from collections.abc import Sequence + from policyengine_simulation_contract.stage12_manifest import V2WorkerVersion from policyengine_simulation_persistence import ( EconomyRequest, NewEconomyReport, @@ -104,15 +105,25 @@ def simulation_request(**changes: Any) -> EconomySimulationRequest: class FakeWorkers: - """The default worker's economy functions, or the lookup's failure.""" + """The default worker's economy functions, or the lookup's failure. - def __init__(self, failure: Exception | None = None) -> None: + ``worker_version`` is the manifest's default worker; without it, the + economy fixtures' worker. + """ + + def __init__( + self, + failure: Exception | None = None, + *, + worker_version: V2WorkerVersion | None = None, + ) -> None: self.failure = failure + self.worker_version = worker_version def default_worker(self, country: str) -> EconomyWorker: if self.failure is not None: raise self.failure - return default_economy_worker(economy_manifest(), country) + return default_economy_worker(economy_manifest(self.worker_version), country) @dataclass @@ -132,7 +143,11 @@ class FakeStore: claimed: bool = False stored_report: EconomyReportState | None = None stored_simulation: EconomySimulationState | None = None + # The catalog's local-area dataset a report read finds, when asked for one. + local_area_dataset: CatalogDataset | None = None report_reads: list[tuple[EconomyRequest, Any]] = field(default_factory=list) + # The local-area dataset each report read was asked for, or None. + local_area_reads: list[str | None] = field(default_factory=list) simulation_reads: list[tuple[EconomyRequest, Any]] = field(default_factory=list) reports: list[NewEconomyReport] = field(default_factory=list) simulations: list[NewEconomySimulation] = field(default_factory=list) @@ -146,12 +161,14 @@ def read_report_inputs( baseline: SimulationChoice, reform: SimulationChoice, reuse: RunReuse | None, + local_area_dataset_name: str | None = None, ) -> EconomyReportInputs: self.report_reads.append((request, (baseline, reform, reuse))) + self.local_area_reads.append(local_area_dataset_name) if self.read_failure is not None: raise self.read_failure baseline_reusable, reform_reusable = self.reusable - return EconomyReportInputs( + inputs = EconomyReportInputs( catalog=self.catalog, baseline=SimulationInputs( choice=baseline, reform={}, reusable_run=baseline_reusable @@ -160,6 +177,9 @@ def read_report_inputs( choice=reform, reform=REFORM, reusable_run=reform_reusable ), ) + if local_area_dataset_name is None: + return inputs + return replace(inputs, local_area_dataset=self.local_area_dataset) def read_simulation_inputs( self, request: EconomyRequest, choice: SimulationChoice diff --git a/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py b/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py new file mode 100644 index 000000000..1ba2e5394 --- /dev/null +++ b/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py @@ -0,0 +1,164 @@ +"""Economy reports that ask for their local areas, with the store and Modal faked. + +A UK-wide or nation report with ``breakdown: "local_areas"`` is calculated +by the default worker only when its UK entry declares the local-area report +runs its coordinator runs (``local_area_reports``). The declaration's +dataset is the one the release routes constituencies and local authorities +to, or None when a national run calculates them itself. +""" + +from __future__ import annotations + +import asyncio +from dataclasses import replace +from typing import TYPE_CHECKING, Any +from uuid import UUID + +import pytest +from economy_fixtures import ( + LOCAL_AREA_DATASET, + ROUTED_LOCAL_AREAS, + local_area_worker_version, +) +from economy_service_fakes import ( + CATALOG, + REPORT_BODY, + FakeStore, + FakeWorkers, + service, +) +from policyengine_simulation_contract.stage12_manifest import LocalAreaReports +from policyengine_simulation_entry.economy_api_models import EconomyReportRequest +from policyengine_simulation_entry.economy_submission_errors import ( + EconomySubmissionRefusedError, +) +from policyengine_simulation_persistence import ( + CatalogDataset, + LocalAreaDatasetMismatchError, +) + +if TYPE_CHECKING: + from policyengine_simulation_entry.economy_api_models import ( + EconomyReportCreated, + ) + from policyengine_simulation_entry.economy_submissions import ( + EconomySubmissionService, + ) + +# The UK worker's default dataset, which a UK-wide report calculates on. +NATIONAL_DATASET_NAME = "populace_uk_2024" +UK_CATALOG = replace( + CATALOG, + region=replace(CATALOG.region, code="uk"), + dataset=CatalogDataset(id=CATALOG.dataset.id, name=NATIONAL_DATASET_NAME), +) +CATALOG_LOCAL_AREA_DATASET = CatalogDataset( + id=UUID("00000000-0000-4000-8000-0000000000c7"), name=LOCAL_AREA_DATASET.identity +) + + +def _uk_report_request(**changes: Any) -> EconomyReportRequest: + """Return a UK-wide report request, with no SPM settings.""" + body = {name: value for name, value in REPORT_BODY.items() if name != "spm"} + return EconomyReportRequest.model_validate( + {**body, "country": "uk", "region_code": "uk", **changes} + ) + + +def _submit( + submissions: EconomySubmissionService, request: EconomyReportRequest +) -> EconomyReportCreated: + return asyncio.run( + submissions.submit_report( + request, request_id="observed", observability_context=None + ) + ) + + +def _workers_declaring(local_area_reports: LocalAreaReports | None) -> FakeWorkers: + return FakeWorkers(worker_version=local_area_worker_version(local_area_reports)) + + +def test_the_uk_worker_fixture_calculates_on_its_default_dataset() -> None: + """The national dataset the tests' UK catalog names is the UK bundle's default.""" + worker = _workers_declaring(None).default_worker("uk") + + assert worker.country.default_dataset == NATIONAL_DATASET_NAME + + +@pytest.mark.parametrize( + "declaration", + [ + None, + LocalAreaReports(input_version=2, dataset=LOCAL_AREA_DATASET.identity), + ], + ids=["no declaration", "another input version"], +) +def test_local_areas_the_worker_cannot_run_are_refused_before_any_read( + declaration, +) -> None: + store = FakeStore(catalog=UK_CATALOG) + + with pytest.raises(EconomySubmissionRefusedError) as refusal: + _submit( + service(store, workers=_workers_declaring(declaration)), + _uk_report_request(breakdown="local_areas"), + ) + + assert refusal.value.code == "local_areas_unsupported" + assert store.report_reads == [] + assert store.reports == [] + + +def test_a_report_without_local_areas_needs_no_declaration() -> None: + store = FakeStore(catalog=UK_CATALOG) + + _submit(service(store, workers=_workers_declaring(None)), _uk_report_request()) + + assert store.local_area_reads == [None] + assert len(store.reports) == 1 + + +def test_local_areas_on_a_release_that_routes_none_are_the_national_runs() -> None: + """The national run calculates both area levels, so no area part is made.""" + store = FakeStore(catalog=UK_CATALOG) + declaration = LocalAreaReports(input_version=1, dataset=None) + + _submit( + service(store, workers=_workers_declaring(declaration)), + _uk_report_request(breakdown="local_areas"), + ) + + assert store.local_area_reads == [None] + (report,) = store.reports + assert report.inputs == {"include_cliffs": True, "breakdown": "local_areas"} + + +def test_the_catalog_is_asked_for_the_local_area_dataset_the_worker_routes_to() -> None: + store = FakeStore(catalog=UK_CATALOG, local_area_dataset=CATALOG_LOCAL_AREA_DATASET) + + _submit( + service(store, workers=_workers_declaring(ROUTED_LOCAL_AREAS)), + _uk_report_request(breakdown="local_areas", dataset_name=NATIONAL_DATASET_NAME), + ) + + # Never the request's dataset_name (decision 4). + assert store.local_area_reads == [LOCAL_AREA_DATASET.identity] + + +def test_a_catalog_whose_area_regions_use_another_dataset_is_refused() -> None: + store = FakeStore( + catalog=UK_CATALOG, + read_failure=LocalAreaDatasetMismatchError(LOCAL_AREA_DATASET.identity), + ) + + with pytest.raises(EconomySubmissionRefusedError) as refusal: + _submit( + service(store, workers=_workers_declaring(ROUTED_LOCAL_AREAS)), + _uk_report_request(breakdown="local_areas"), + ) + + assert refusal.value.code == "local_area_dataset_mismatch" + # Written from the declaration, never from the error's text. + assert LOCAL_AREA_DATASET.identity in refusal.value.detail + assert store.reports == [] From 5fe191fa929e25291f566def1733d819f11ab8d8 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 19:59:44 +0400 Subject: [PATCH 06/18] Decide a report's local areas by the default worker's declaration The service reads the default worker's UK local_area_reports declaration from the v2 manifest (EconomyWorker.local_area_reports). A report asking for local areas is refused with 400 local_areas_unsupported, before any read, when the worker declares none or another input version. A declaration naming no dataset means the release gives the areas none of their own, so no area part is made. One naming a dataset makes the store read that catalog dataset with the report's inputs, never the request's dataset_name, and refuse it with 400 local_area_dataset_mismatch unless the catalog version gives both area types that dataset. The rule comes from one source, the publisher's own reading of the release (uk_area_regions_routed), so the service, Stage 12's national aggregation and the UK worker decide alike on every release. Co-Authored-By: Claude Opus 5.5 --- .../__init__.py | 2 + .../economy_run_store.py | 51 +++++++++++++++-- .../policyengine-simulation-entry/README.md | 23 ++++++++ .../economy_api_models.py | 6 ++ .../economy_submission_errors.py | 13 ++++- .../economy_submissions.py | 9 ++- .../economy_workers.py | 6 ++ .../local_area_reports.py | 56 +++++++++++++++++++ 8 files changed, 160 insertions(+), 6 deletions(-) create mode 100644 projects/policyengine-simulation-entry/src/policyengine_simulation_entry/local_area_reports.py diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py index cc5dbe895..74e62cffa 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py @@ -51,6 +51,7 @@ EconomyRequest, EconomyRunStore, EconomySimulationInputs, + LocalAreaDatasetMismatchError, ReportSide, ReportSideError, RunReuse, @@ -149,6 +150,7 @@ "HouseholdReportInputs", "HouseholdReportSimulation", "HouseholdReportStore", + "LocalAreaDatasetMismatchError", "MissingPolicyParametersError", "NewBudgetWindowReport", "NewEconomyReport", diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_store.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_store.py index 2ba26499c..c593cede6 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_store.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_store.py @@ -35,6 +35,7 @@ insert_economy_simulation, read_dataset, read_dataset_by_id, + read_local_area_dataset, read_model_id, read_region, record_report_run_call, @@ -103,6 +104,23 @@ class UnknownDatasetError(LookupError): """The catalog version has no dataset with the requested name.""" +class LocalAreaDatasetMismatchError(LookupError): + """The catalog doesn't give both area types the dataset the worker routes them to. + + ``declared_dataset`` is the dataset the default worker declares it + calculates a report's local areas on. The catalog version's + constituency and local-authority regions use another, or one each. + """ + + def __init__(self, declared_dataset: str) -> None: + """Keep the declared dataset.""" + super().__init__( + "the catalog version's constituency and local-authority regions do " + f"not all use {declared_dataset}" + ) + self.declared_dataset = declared_dataset + + class ReportSideError(Exception): """A report side's policy or dynamic is refused. @@ -198,11 +216,16 @@ class EconomySimulationInputs: @dataclass(frozen=True) class EconomyReportInputs: - """What an economy report is read from: the catalog rows and both sides.""" + """What an economy report is read from: the catalog rows and both sides. + + ``local_area_dataset`` is the catalog dataset the report's area part is + calculated on, read only when the request asked for one. + """ catalog: EconomyCatalogRows baseline: SimulationInputs reform: SimulationInputs + local_area_dataset: CatalogDataset | None = None @dataclass(frozen=True) @@ -264,16 +287,31 @@ def read_report_inputs( baseline: SimulationChoice, reform: SimulationChoice, reuse: RunReuse | None, + local_area_dataset_name: str | None = None, ) -> EconomyReportInputs: """Read a report's catalog rows, both sides' values and reusable runs. With ``reuse``, each side gets the run ``find_reusable_run`` finds, - and the reform never gets the baseline's. Raise + and the reform never gets the baseline's. With + ``local_area_dataset_name``, the dataset the default worker calculates + local areas on, the catalog dataset of that name is read too. Raise UnknownCatalogVersionError, UnknownRegionError or UnknownDatasetError, - or ReportSideError naming the side whose policy or dynamic is refused. + ReportSideError naming the side whose policy or dynamic is refused, + or LocalAreaDatasetMismatchError when the catalog version doesn't + give both area types that dataset (``read_local_area_dataset``). """ with self._transaction() as connection: catalog = _catalog_rows(connection, request) + local_area_dataset = None + if local_area_dataset_name is not None: + local_area_dataset = read_local_area_dataset( + connection, catalog_version_id=catalog.catalog_version_id + ) + if ( + local_area_dataset is None + or local_area_dataset.name != local_area_dataset_name + ): + raise LocalAreaDatasetMismatchError(local_area_dataset_name) population = catalog.population(request.year) sides = [] excluded_run_id = None @@ -306,7 +344,12 @@ def read_report_inputs( reusable_run=reusable_run, ) sides.append(inputs) - return EconomyReportInputs(catalog=catalog, baseline=sides[0], reform=sides[1]) + return EconomyReportInputs( + catalog=catalog, + baseline=sides[0], + reform=sides[1], + local_area_dataset=local_area_dataset, + ) def read_budget_window_inputs( self, diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index 0d1408c33..04fcb43b4 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -151,6 +151,29 @@ a run claimed meanwhile is answered with 201. Every 500 is the JSON error with code `internal_error`, and may follow a write. No `detail` holds an exception's text. +### Local areas + +An economy report may also ask for its constituency and local-authority +impacts with `breakdown: "local_areas"`, left out unless given (null and any +other value are refused with 422). Only a UK report whose region is `uk` or +one of the four `country/*` nations may ask, with or without +`include_cliffs`; any other country or region is refused with 422 at +`breakdown`. The report's stored options record `"breakdown": "local_areas"` +only when asked for. + +The default worker's UK entry in the v2 version manifest decides the rest +(`local_area_reports`): the input version its coordinator accepts for a +local-area report run, and the dataset the .py release routes constituency +and local-authority regions to, which the publisher computes by the rule +Stage 12's national aggregation uses to leave the areas out. Without that +declaration, or with another input version, the request is refused with 400 +`local_areas_unsupported` before anything is read. With no dataset, the +release gives the areas none of their own, and the national run calculates +both area levels itself. With one, the catalog version's constituency and +local-authority regions must all use it, whatever `dataset_name` names; +otherwise the request is refused with 400 `local_area_dataset_mismatch`. +Both codes are the service's state, not the caller's. + ### Budget windows `POST /reports` with `report_type` `budget_window` creates a budget-window diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py index 4b2b1bf5a..ac2c83775 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py @@ -77,6 +77,12 @@ "unknown_household", # The default worker has no household function for the country. "no_household_function", + # The default worker's coordinator runs no local-area report runs of the + # input this service sends. + "local_areas_unsupported", + # The catalog version's constituency and local-authority regions don't + # all use the dataset the default worker calculates local areas on. + "local_area_dataset_mismatch", ] EconomyRefusalCode = Literal[CallerRowRefusalCode, ServiceStateRefusalCode] # Why stored values cannot be calculated (422). diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submission_errors.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submission_errors.py index a284af30e..d08f457ec 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submission_errors.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submission_errors.py @@ -15,6 +15,7 @@ from typing import TYPE_CHECKING, Literal from policyengine_simulation_persistence import ( + LocalAreaDatasetMismatchError, MissingPolicyParametersError, OverlappingReformError, ReportSideError, @@ -136,7 +137,9 @@ def read_refusal( """Return the refusal a store read's error means, or None for any other error. A missing catalog version, region, dataset, policy or dynamic is refused - (400); a policy or dynamic setting parameters the catalog version lacks, + (400), and so is a catalog whose area regions don't use the dataset the + default worker calculates local areas on; a policy or dynamic setting + parameters the catalog version lacks, or both setting one, cannot be calculated (422). A report side's refusal (ReportSideError) is located on that side's fields. Every detail is written from ``request``, never from the error's text. @@ -183,6 +186,14 @@ def _missing_row_refusal( "unknown_dynamic", f"No stored dynamic matches the one {named_by} names.", ) + elif isinstance(error, LocalAreaDatasetMismatchError): + # The dataset is the default worker's declaration, not the request's. + refusal = ( + "local_area_dataset_mismatch", + f"{catalog}'s constituency and local-authority regions do not all " + f"use {error.declared_dataset}, the dataset the default v2 worker " + "calculates local areas on.", + ) if refusal is None: return None code, detail = refusal diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submissions.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submissions.py index a6011bae7..aa5334bf1 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submissions.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submissions.py @@ -82,6 +82,7 @@ from policyengine_simulation_entry.household_workers import ( VersionManifestUnavailableError, ) +from policyengine_simulation_entry.local_area_reports import local_area_dataset_name if TYPE_CHECKING: from collections.abc import Callable, Sequence @@ -130,8 +131,12 @@ def read_report_inputs( baseline: SimulationChoice, reform: SimulationChoice, reuse: RunReuse | None, + local_area_dataset_name: str | None = None, ) -> EconomyReportInputs: - """Read a report's catalog rows, both sides' values and reusable runs.""" + """Read a report's catalog rows, both sides' values and reusable runs. + + With ``local_area_dataset_name``, also the catalog's local-area dataset. + """ ... def read_simulation_inputs( @@ -259,6 +264,7 @@ async def submit_report( failed after its rows were inserted. """ worker = await self._default_worker(request.country) + area_dataset_name = local_area_dataset_name(request, worker) options = request.options() reuse_prefix = self._settings.reuse_prefix reuse = ( @@ -277,6 +283,7 @@ async def submit_report( baseline=simulation_choice(request.baseline), reform=simulation_choice(request.reform), reuse=reuse, + local_area_dataset_name=area_dataset_name, ), request=economy_request, ) diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_workers.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_workers.py index b07a6e693..438271f38 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_workers.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_workers.py @@ -33,6 +33,7 @@ if TYPE_CHECKING: from policyengine_simulation_contract.stage12_bundle import Stage12CountryBundle from policyengine_simulation_contract.stage12_manifest import ( + LocalAreaReports, V2ManifestStore, V2VersionManifest, ) @@ -48,6 +49,9 @@ class EconomyWorker: ``version`` is the worker's .py version, the manifest's default, and ``version_manifest_sha256`` the digest of the manifest it was read from. + ``local_area_reports`` is the country's declaration of the local-area + report runs the coordinator runs, and the dataset it runs them on; None + when it runs none. """ version: str @@ -58,6 +62,7 @@ class EconomyWorker: bundle_manifest_sha256: str policyengine_version: str country: Stage12CountryBundle + local_area_reports: LocalAreaReports | None = None @property def versions(self) -> RunVersions: @@ -99,6 +104,7 @@ def default_economy_worker(manifest: V2VersionManifest, country: str) -> Economy bundle_manifest_sha256=worker.bundle_manifest_sha256, policyengine_version=worker.bundle.policyengine_version, country=country_bundle, + local_area_reports=country_worker.local_area_reports, ) diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/local_area_reports.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/local_area_reports.py new file mode 100644 index 000000000..2b1d3379f --- /dev/null +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/local_area_reports.py @@ -0,0 +1,56 @@ +"""Whether an economy report gets a local-area part, and on which dataset. + +A UK-wide or nation report that asks for ``breakdown: "local_areas"`` gets +its constituency and local-authority impacts from a local-area report run of +its own, on the dataset the .py release routes those regions to. The +default worker's UK entry in the v2 version manifest declares both whether +its coordinator runs such runs (``local_area_reports``, with the input +version it accepts) and that dataset, which the publisher computes in the +worker's own environment by the rule Stage 12's national aggregation uses +to leave the areas out (``uk_area_regions_routed``). So the service, the +national run and the worker decide alike on every release. +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +from policyengine_simulation_contract.stage12_manifest import ( + LOCAL_AREA_REPORTS_VERSION, +) + +from policyengine_simulation_entry.economy_submission_errors import ( + EconomySubmissionRefusedError, +) + +if TYPE_CHECKING: + from policyengine_simulation_entry.economy_api_models import ( + EconomyReportRequest, + ) + from policyengine_simulation_entry.economy_workers import EconomyWorker + + +def local_area_dataset_name( + request: EconomyReportRequest, worker: EconomyWorker +) -> str | None: + """Return the dataset the report's area part is calculated on, or None. + + None means no area part: the request asks for none, or the release + routes the area regions to no dataset of their own, so the national run + calculates both area levels itself. Raise EconomySubmissionRefusedError + (``local_areas_unsupported``) when the request asks for local areas and + the default worker declares no local-area report runs of the input + version this service sends. + """ + if request.breakdown is None: + return None + declared = worker.local_area_reports + if declared is None or declared.input_version != LOCAL_AREA_REPORTS_VERSION: + raise EconomySubmissionRefusedError( + code="local_areas_unsupported", + detail=( + f"The default v2 worker, .py {worker.version}, cannot calculate " + f"a {request.country} report's local areas." + ), + ) + return declared.dataset From dd6ae8abe648dbc29f278095758128830e26c2fc Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 22:46:16 +0400 Subject: [PATCH 07/18] Test that a report's local-area breakdown is never stored (failing) The user's 2026-11-13 design makes breakdown a request option: it finds or creates the report on the local-area dataset beside the national one, and is never stored in the report's options, so it never changes which report a request names. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_economy_routes.py | 5 +++-- .../tests/test_local_area_submissions.py | 3 ++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/projects/policyengine-simulation-entry/tests/test_economy_routes.py b/projects/policyengine-simulation-entry/tests/test_economy_routes.py index 183c81534..29c90ff5a 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_routes.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_routes.py @@ -287,8 +287,9 @@ def test_a_uk_wide_or_nation_report_may_ask_for_its_local_areas( assert result.status_code == 201 ((request, _, _),) = submissions.reports assert request.breakdown == "local_areas" - # The report still calculates cliffs, and stores that it asked for areas. - assert request.options() == {"include_cliffs": True, "breakdown": "local_areas"} + # The report still calculates cliffs. The breakdown is a request option, + # never stored, so it never changes which report the request names. + assert request.options() == {"include_cliffs": True} @pytest.mark.parametrize(("path", "body"), ROUTES) diff --git a/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py b/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py index 1ba2e5394..09ab443ef 100644 --- a/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py +++ b/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py @@ -131,7 +131,8 @@ def test_local_areas_on_a_release_that_routes_none_are_the_national_runs() -> No assert store.local_area_reads == [None] (report,) = store.reports - assert report.inputs == {"include_cliffs": True, "breakdown": "local_areas"} + # The breakdown is never stored. + assert report.inputs == {"include_cliffs": True} def test_the_catalog_is_asked_for_the_local_area_dataset_the_worker_routes_to() -> None: From fa71c6c4f152ac0bd73614856472d34f38fa707a Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 22:46:38 +0400 Subject: [PATCH 08/18] Never store a report's local-area breakdown breakdown is a request option: EconomyReportRequest.options() no longer records it, so a report's stored options, and whatever names the report by them, are the same with or without it. Its validation and 422 refusals are unchanged. Co-Authored-By: Claude Opus 5.5 --- projects/policyengine-simulation-entry/README.md | 3 +-- .../src/policyengine_simulation_entry/economy_api_models.py | 6 +++--- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index 04fcb43b4..4d0f25d42 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -158,8 +158,7 @@ impacts with `breakdown: "local_areas"`, left out unless given (null and any other value are refused with 422). Only a UK report whose region is `uk` or one of the four `country/*` nations may ask, with or without `include_cliffs`; any other country or region is refused with 422 at -`breakdown`. The report's stored options record `"breakdown": "local_areas"` -only when asked for. +`breakdown`. It is a request option, never stored with the report. The default worker's UK entry in the v2 version manifest decides the rest (`local_area_reports`): the input version its coordinator accepts for a diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py index ac2c83775..7c3dfc1d7 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py @@ -161,6 +161,7 @@ class EconomyReportRequest(_Request): dataset whatever ``dataset_name`` names. Only a UK report whose region is ``uk`` or one of the four ``country/*`` nations may ask, with or without ``include_cliffs``; omit it, rather than sending null, to ask for none. + It is a request option, never stored with the report. """ country: CountryId @@ -237,13 +238,12 @@ def options(self) -> dict[str, Any]: """Return the report's options as it stores them (``reports.inputs``). ``spm`` holds only the settings the request gave, and is left out - when it gave none; ``breakdown`` is there only when asked for. + when it gave none. ``breakdown`` is never stored: it asks for the + report on the local-area dataset too, and never changes this one. """ options: dict[str, Any] = {"include_cliffs": self.include_cliffs} if self.spm is not None: options["spm"] = self.spm.model_dump(mode="json") - if self.breakdown is not None: - options["breakdown"] = self.breakdown return options From caa96682106b029c5dea0c6702cfea93a9da300c Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:26:00 +0400 Subject: [PATCH 09/18] Test that a UK-wide or nation report runs on the local-area dataset with data_source (failing) data_source: "local_area_dataset" replaces breakdown: the report itself runs on the dataset the default worker's UK entry declares for local-area report runs, read from the catalog in place of the region's default, with its own options. Another value, country or region is refused with 422 at data_source, and so is a release that routes the areas to no dataset of its own (no_local_area_dataset); a worker that declares no local-area runs, and a catalog whose area regions use another dataset, are still refused with 400. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_economy_run_store.py | 35 +++++---- .../tests/economy_service_fakes.py | 9 ++- .../tests/test_economy_routes.py | 30 +++++--- .../tests/test_local_area_submissions.py | 77 +++++++++++++------ .../tests/test_openapi.py | 14 ++-- 5 files changed, 102 insertions(+), 63 deletions(-) diff --git a/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py b/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py index 79b7c4497..be3cbc087 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py @@ -147,7 +147,7 @@ def test_a_reports_inputs_are_read_together(public_api_database_url) -> None: LOCAL_AREA_DATASET_NAME = "microcosm_uk_2024_25_dense" -def test_a_reports_local_area_dataset_is_read_with_its_inputs( +def test_a_report_on_the_local_area_dataset_is_read_on_it( public_api_database_url, ) -> None: with rolled_back_transaction(public_api_database_url) as connection: @@ -164,27 +164,29 @@ def test_a_reports_local_area_dataset_is_read_with_its_inputs( act_as_the_service(connection) store = _store_on(connection) - with_areas = store.read_report_inputs( + on_local_areas = store.read_report_inputs( UK_REQUEST, baseline=CURRENT_LAW, reform=CURRENT_LAW, reuse=None, local_area_dataset_name=LOCAL_AREA_DATASET_NAME, ) - without_areas = store.read_report_inputs( + national = store.read_report_inputs( UK_REQUEST, baseline=CURRENT_LAW, reform=CURRENT_LAW, reuse=None ) - assert with_areas.local_area_dataset == CatalogDataset( + # The local-area dataset takes the place of the region's default. + assert on_local_areas.catalog.dataset == CatalogDataset( id=local_area_id, name=LOCAL_AREA_DATASET_NAME ) - assert without_areas.local_area_dataset is None - # The national part is read as it is without the local areas. - assert with_areas.catalog == without_areas.catalog + assert national.catalog.dataset.id == economy.dataset_id + assert on_local_areas.catalog == replace( + national.catalog, dataset=on_local_areas.catalog.dataset + ) @pytest.mark.parametrize( - "area_datasets", ["another dataset", "a dataset for each type"] + "area_datasets", ["another dataset", "a dataset for each type", "no area regions"] ) def test_a_declared_dataset_the_catalog_does_not_give_both_area_types_is_refused( public_api_database_url, area_datasets @@ -195,14 +197,15 @@ def test_a_declared_dataset_the_catalog_does_not_give_both_area_types_is_refused connection, economy.catalog, LOCAL_AREA_DATASET_NAME ) other_id = insert_dataset(connection, economy.catalog, "microcosm_uk_2024_25") - insert_uk_area_regions( - connection, - economy.catalog, - constituency_dataset_id=( - other_id if area_datasets == "another dataset" else local_area_id - ), - local_authority_dataset_id=other_id, - ) + if area_datasets != "no area regions": + insert_uk_area_regions( + connection, + economy.catalog, + constituency_dataset_id=( + other_id if area_datasets == "another dataset" else local_area_id + ), + local_authority_dataset_id=other_id, + ) act_as_the_service(connection) with pytest.raises(LocalAreaDatasetMismatchError) as mismatch: diff --git a/projects/policyengine-simulation-entry/tests/economy_service_fakes.py b/projects/policyengine-simulation-entry/tests/economy_service_fakes.py index b2af1c5c2..2ca8f7166 100644 --- a/projects/policyengine-simulation-entry/tests/economy_service_fakes.py +++ b/projects/policyengine-simulation-entry/tests/economy_service_fakes.py @@ -143,7 +143,8 @@ class FakeStore: claimed: bool = False stored_report: EconomyReportState | None = None stored_simulation: EconomySimulationState | None = None - # The catalog's local-area dataset a report read finds, when asked for one. + # The catalog's local-area dataset a report read calculates on, when + # asked for one. local_area_dataset: CatalogDataset | None = None report_reads: list[tuple[EconomyRequest, Any]] = field(default_factory=list) # The local-area dataset each report read was asked for, or None. @@ -177,9 +178,11 @@ def read_report_inputs( choice=reform, reform=REFORM, reusable_run=reform_reusable ), ) - if local_area_dataset_name is None: + if local_area_dataset_name is None or self.local_area_dataset is None: return inputs - return replace(inputs, local_area_dataset=self.local_area_dataset) + return replace( + inputs, catalog=replace(self.catalog, dataset=self.local_area_dataset) + ) def read_simulation_inputs( self, request: EconomyRequest, choice: SimulationChoice diff --git a/projects/policyengine-simulation-entry/tests/test_economy_routes.py b/projects/policyengine-simulation-entry/tests/test_economy_routes.py index 29c90ff5a..ab6f52f15 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_routes.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_routes.py @@ -219,24 +219,29 @@ def test_a_malformed_request_is_refused_with_its_reasons(client_for, path, body) assert (submissions.reports, submissions.simulations) == ([], []) -# A UK-wide report asking for its local-area breakdown, with cliffs and no -# SPM settings. +# A UK-wide report on the local-area dataset, with cliffs and no SPM settings. LOCAL_AREA_REPORT_BODY: dict[str, Any] = { **{name: value for name, value in REPORT_BODY.items() if name != "spm"}, "country": "uk", "region_code": "uk", - "breakdown": "local_areas", + "data_source": "local_area_dataset", } @pytest.mark.parametrize( ("changes", "expected_message"), [ - ({"breakdown": None}, 'breakdown must be "local_areas" when given'), - ({"breakdown": "constituencies"}, 'breakdown must be "local_areas" when given'), + ( + {"data_source": None}, + 'data_source must be "local_area_dataset" when given', + ), + ( + {"data_source": "local_areas"}, + 'data_source must be "local_area_dataset" when given', + ), ( {"country": "us", "region_code": "us"}, - "breakdown is supported only for UK requests", + "the local-area dataset is available only to UK reports", ), ({"region_code": "constituency/Aldershot"}, "UK-wide or nation region"), ({"region_code": "local_authority/Cardiff"}, "UK-wide or nation region"), @@ -249,7 +254,7 @@ def test_a_malformed_request_is_refused_with_its_reasons(client_for, path, body) "a local authority", ], ) -def test_a_breakdown_a_report_cannot_have_is_refused( +def test_a_data_source_a_report_cannot_have_is_refused( client_for, changes, expected_message ) -> None: submissions = FakeEconomySubmissions() @@ -259,7 +264,7 @@ def test_a_breakdown_a_report_cannot_have_is_refused( assert result.status_code == 422 (reason,) = result.json()["detail"] - assert reason["loc"][-1] == "breakdown" + assert reason["loc"][-1] == "data_source" assert expected_message in reason["msg"] assert submissions.reports == [] @@ -274,7 +279,7 @@ def test_a_breakdown_a_report_cannot_have_is_refused( "country/northern_ireland", ], ) -def test_a_uk_wide_or_nation_report_may_ask_for_its_local_areas( +def test_a_uk_wide_or_nation_report_may_ask_for_the_local_area_dataset( client_for, region_code ) -> None: submissions = FakeEconomySubmissions() @@ -286,9 +291,10 @@ def test_a_uk_wide_or_nation_report_may_ask_for_its_local_areas( assert result.status_code == 201 ((request, _, _),) = submissions.reports - assert request.breakdown == "local_areas" - # The report still calculates cliffs. The breakdown is a request option, - # never stored, so it never changes which report the request names. + assert request.data_source == "local_area_dataset" + # The report still calculates cliffs. The data source is never stored as + # an option: the dataset it chooses is stored with the report's + # simulations. assert request.options() == {"include_cliffs": True} diff --git a/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py b/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py index 09ab443ef..f2f06ccab 100644 --- a/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py +++ b/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py @@ -1,10 +1,10 @@ -"""Economy reports that ask for their local areas, with the store and Modal faked. +"""Economy reports on the local-area dataset, with the store and Modal faked. -A UK-wide or nation report with ``breakdown: "local_areas"`` is calculated -by the default worker only when its UK entry declares the local-area report -runs its coordinator runs (``local_area_reports``). The declaration's -dataset is the one the release routes constituencies and local authorities -to, or None when a national run calculates them itself. +A UK-wide or nation report created with ``data_source: "local_area_dataset"`` +is calculated on the dataset the default worker's UK entry declares for +local-area report runs (``local_area_reports``): the one the release routes +constituencies and local authorities to. A release that routes them to no +dataset of its own has none, and the request is refused. """ from __future__ import annotations @@ -23,14 +23,17 @@ from economy_service_fakes import ( CATALOG, REPORT_BODY, + FakeCaller, FakeStore, FakeWorkers, service, ) +from policyengine_simulation_contract.stage12_execution import ReportExecutionInput from policyengine_simulation_contract.stage12_manifest import LocalAreaReports from policyengine_simulation_entry.economy_api_models import EconomyReportRequest from policyengine_simulation_entry.economy_submission_errors import ( EconomySubmissionRefusedError, + EconomySubmissionUnprocessableError, ) from policyengine_simulation_persistence import ( CatalogDataset, @@ -65,6 +68,10 @@ def _uk_report_request(**changes: Any) -> EconomyReportRequest: ) +def _local_area_report_request(**changes: Any) -> EconomyReportRequest: + return _uk_report_request(data_source="local_area_dataset", **changes) + + def _submit( submissions: EconomySubmissionService, request: EconomyReportRequest ) -> EconomyReportCreated: @@ -94,7 +101,7 @@ def test_the_uk_worker_fixture_calculates_on_its_default_dataset() -> None: ], ids=["no declaration", "another input version"], ) -def test_local_areas_the_worker_cannot_run_are_refused_before_any_read( +def test_the_local_area_dataset_the_worker_cannot_run_is_refused_before_any_read( declaration, ) -> None: store = FakeStore(catalog=UK_CATALOG) @@ -102,7 +109,7 @@ def test_local_areas_the_worker_cannot_run_are_refused_before_any_read( with pytest.raises(EconomySubmissionRefusedError) as refusal: _submit( service(store, workers=_workers_declaring(declaration)), - _uk_report_request(breakdown="local_areas"), + _local_area_report_request(), ) assert refusal.value.code == "local_areas_unsupported" @@ -110,41 +117,61 @@ def test_local_areas_the_worker_cannot_run_are_refused_before_any_read( assert store.reports == [] -def test_a_report_without_local_areas_needs_no_declaration() -> None: +def test_a_report_without_a_data_source_needs_no_declaration() -> None: store = FakeStore(catalog=UK_CATALOG) _submit(service(store, workers=_workers_declaring(None)), _uk_report_request()) assert store.local_area_reads == [None] - assert len(store.reports) == 1 + (report,) = store.reports + assert report.population.dataset_id == UK_CATALOG.dataset.id -def test_local_areas_on_a_release_that_routes_none_are_the_national_runs() -> None: - """The national run calculates both area levels, so no area part is made.""" +def test_a_release_that_routes_no_areas_has_no_local_area_dataset() -> None: + """Its national reports calculate both area levels themselves (decision 8).""" store = FakeStore(catalog=UK_CATALOG) declaration = LocalAreaReports(input_version=1, dataset=None) - _submit( - service(store, workers=_workers_declaring(declaration)), - _uk_report_request(breakdown="local_areas"), - ) + with pytest.raises(EconomySubmissionUnprocessableError) as refusal: + _submit( + service(store, workers=_workers_declaring(declaration)), + _local_area_report_request(), + ) - assert store.local_area_reads == [None] - (report,) = store.reports - # The breakdown is never stored. - assert report.inputs == {"include_cliffs": True} + assert refusal.value.code == "no_local_area_dataset" + (reason,) = refusal.value.reasons + assert reason.loc == ("body", "data_source") + assert "routes constituencies and local authorities to no dataset" in reason.msg + assert store.report_reads == [] + assert store.reports == [] -def test_the_catalog_is_asked_for_the_local_area_dataset_the_worker_routes_to() -> None: +def test_the_report_is_calculated_on_the_local_area_dataset_the_worker_routes_to() -> ( + None +): store = FakeStore(catalog=UK_CATALOG, local_area_dataset=CATALOG_LOCAL_AREA_DATASET) + caller = FakeCaller() _submit( - service(store, workers=_workers_declaring(ROUTED_LOCAL_AREAS)), - _uk_report_request(breakdown="local_areas", dataset_name=NATIONAL_DATASET_NAME), + service(store, workers=_workers_declaring(ROUTED_LOCAL_AREAS), caller=caller), + _local_area_report_request(), ) - # Never the request's dataset_name (decision 4). assert store.local_area_reads == [LOCAL_AREA_DATASET.identity] + ((request, _),) = store.report_reads + # The dataset comes from the declaration, never from the request. + assert request.dataset_name is None + (report,) = store.reports + assert report.population.dataset_id == CATALOG_LOCAL_AREA_DATASET.id + # An ordinary report: its options are the request's, cliffs included. + assert report.inputs == {"include_cliffs": True} + ((_, payload, _, _),) = caller.report_runs + execution = ReportExecutionInput.model_validate(payload) + for side in (execution.baseline, execution.reform): + assert side.bundle.dataset.identity == LOCAL_AREA_DATASET.identity + assert side.population.artifact.uri == LOCAL_AREA_DATASET.uri + assert side.geography.region == "uk" + assert side.options == {"include_cliffs": True} def test_a_catalog_whose_area_regions_use_another_dataset_is_refused() -> None: @@ -156,7 +183,7 @@ def test_a_catalog_whose_area_regions_use_another_dataset_is_refused() -> None: with pytest.raises(EconomySubmissionRefusedError) as refusal: _submit( service(store, workers=_workers_declaring(ROUTED_LOCAL_AREAS)), - _uk_report_request(breakdown="local_areas"), + _local_area_report_request(), ) assert refusal.value.code == "local_area_dataset_mismatch" diff --git a/projects/policyengine-simulation-entry/tests/test_openapi.py b/projects/policyengine-simulation-entry/tests/test_openapi.py index aee37875f..efc6cf81a 100644 --- a/projects/policyengine-simulation-entry/tests/test_openapi.py +++ b/projects/policyengine-simulation-entry/tests/test_openapi.py @@ -440,7 +440,7 @@ def test_economy_requests_name_no_version_and_no_record_id(): "reform", "include_cliffs", "spm", - "breakdown", + "data_source", } assert set(schemas["EconomySimulationRequest"]["properties"]) == { "country", @@ -456,12 +456,12 @@ def test_economy_requests_name_no_version_and_no_record_id(): assert spm["$ref"] == "#/components/schemas/SPMSelection" assert "default" not in spm assert "spm" not in schemas["EconomyReportRequest"].get("required", []) - # Omitted, not null, unless the caller asks for the local-area breakdown. - breakdown = schemas["EconomyReportRequest"]["properties"]["breakdown"] - assert breakdown["const"] == "local_areas" - assert breakdown["type"] == "string" - assert "default" not in breakdown - assert "breakdown" not in schemas["EconomyReportRequest"].get("required", []) + # Omitted, not null, unless the caller asks for the local-area dataset. + data_source = schemas["EconomyReportRequest"]["properties"]["data_source"] + assert data_source["const"] == "local_area_dataset" + assert data_source["type"] == "string" + assert "default" not in data_source + assert "data_source" not in schemas["EconomyReportRequest"].get("required", []) def test_a_report_request_is_an_economy_report_a_budget_window_or_a_household(): From 9a3c9ec7ce3aaf92ae4675a7d993326226894499 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:29:36 +0400 Subject: [PATCH 10/18] Run a UK-wide or nation report on the local-area dataset with data_source data_source: "local_area_dataset" replaces breakdown on economy reports. The report runs on the dataset the default worker's UK entry declares for local-area report runs: the store reads the catalog version's local-area dataset in place of the region's default, so the report's simulations, population and calculation are on it, and its options are its own, cliffs included. Null, another value, another country and a region other than uk and the four nations are refused with 422 at data_source. A release that routes the areas to no dataset of their own has no local-area dataset, and is refused with 422 no_local_area_dataset (its national reports calculate both area levels). A worker declaring no local-area runs (400 local_areas_unsupported) and a catalog whose area regions use another dataset (400 local_area_dataset_mismatch) stay the service's state. Co-Authored-By: Claude Opus 5.5 --- .../economy_run_records.py | 9 +- .../economy_run_store.py | 72 ++++++------- .../input_tables.py | 2 +- .../policyengine-simulation-entry/README.md | 37 ++++--- .../economy_api_models.py | 101 ++++++++++-------- .../economy_submissions.py | 16 +-- .../local_area_reports.py | 62 +++++++---- 7 files changed, 167 insertions(+), 132 deletions(-) diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_records.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_records.py index a56ee1fbc..ffcb23275 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_records.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_records.py @@ -277,10 +277,11 @@ def read_local_area_dataset( only when the .py release routes them to a dataset of their own, and gives them that dataset, so a version with no such regions, with only one of the two types, or with a dataset for each type has none: its - national runs calculate both area levels themselves. The dataset may be - the national file: Stage 12 leaves the areas out of a UK-wide or nation - run whenever the release routes both types to one dataset - (``uk_area_breakdowns_omitted``), so they are calculated apart even then. + national reports calculate both area levels themselves. A report created + with ``data_source`` runs on this dataset, which may be the national + file: Stage 12 leaves the areas out of a UK-wide or nation run whenever + the release routes both types to one dataset + (``uk_area_breakdowns_omitted``). """ region_type = cast(regions.c.region_type, String) rows = connection.execute( diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_store.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_store.py index c593cede6..0381dd947 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_store.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_store.py @@ -216,16 +216,11 @@ class EconomySimulationInputs: @dataclass(frozen=True) class EconomyReportInputs: - """What an economy report is read from: the catalog rows and both sides. - - ``local_area_dataset`` is the catalog dataset the report's area part is - calculated on, read only when the request asked for one. - """ + """What an economy report is read from: the catalog rows and both sides.""" catalog: EconomyCatalogRows baseline: SimulationInputs reform: SimulationInputs - local_area_dataset: CatalogDataset | None = None @dataclass(frozen=True) @@ -293,25 +288,19 @@ def read_report_inputs( With ``reuse``, each side gets the run ``find_reusable_run`` finds, and the reform never gets the baseline's. With - ``local_area_dataset_name``, the dataset the default worker calculates - local areas on, the catalog dataset of that name is read too. Raise - UnknownCatalogVersionError, UnknownRegionError or UnknownDatasetError, - ReportSideError naming the side whose policy or dynamic is refused, - or LocalAreaDatasetMismatchError when the catalog version doesn't - give both area types that dataset (``read_local_area_dataset``). + ``local_area_dataset_name``, the dataset the default worker + calculates local-area reports on, the report is read on the catalog + version's local-area dataset (``read_local_area_dataset``) in place + of the region's default. Raise UnknownCatalogVersionError, + UnknownRegionError or UnknownDatasetError, ReportSideError naming the + side whose policy or dynamic is refused, or + LocalAreaDatasetMismatchError when the catalog version doesn't give + both area types that dataset. """ with self._transaction() as connection: - catalog = _catalog_rows(connection, request) - local_area_dataset = None - if local_area_dataset_name is not None: - local_area_dataset = read_local_area_dataset( - connection, catalog_version_id=catalog.catalog_version_id - ) - if ( - local_area_dataset is None - or local_area_dataset.name != local_area_dataset_name - ): - raise LocalAreaDatasetMismatchError(local_area_dataset_name) + catalog = _catalog_rows( + connection, request, local_area_dataset_name=local_area_dataset_name + ) population = catalog.population(request.year) sides = [] excluded_run_id = None @@ -344,12 +333,7 @@ def read_report_inputs( reusable_run=reusable_run, ) sides.append(inputs) - return EconomyReportInputs( - catalog=catalog, - baseline=sides[0], - reform=sides[1], - local_area_dataset=local_area_dataset, - ) + return EconomyReportInputs(catalog=catalog, baseline=sides[0], reform=sides[1]) def read_budget_window_inputs( self, @@ -510,12 +494,17 @@ def read_simulation(self, simulation_id: UUID) -> EconomySimulationState | None: def _catalog_rows( - connection: Connection, request: EconomyRequest + connection: Connection, + request: EconomyRequest, + *, + local_area_dataset_name: str | None = None, ) -> EconomyCatalogRows: """Read the catalog version, model, region and dataset a request names. - Raise UnknownCatalogVersionError, UnknownRegionError or - UnknownDatasetError. + With ``local_area_dataset_name``, the dataset is the catalog version's + local-area dataset, which must have that name. Raise + UnknownCatalogVersionError, UnknownRegionError, UnknownDatasetError or + LocalAreaDatasetMismatchError. """ country = request.country catalog_version_id = read_catalog_version_id( @@ -538,19 +527,22 @@ def _catalog_rows( f"has no region {request.region_code}" ) raise UnknownRegionError(msg) - dataset = ( - read_dataset_by_id( + if local_area_dataset_name is not None: + dataset = read_local_area_dataset( + connection, catalog_version_id=catalog_version_id + ) + if dataset is None or dataset.name != local_area_dataset_name: + raise LocalAreaDatasetMismatchError(local_area_dataset_name) + elif request.dataset_name is None: + dataset = read_dataset_by_id( connection, catalog_version_id=catalog_version_id, dataset_id=region.default_dataset_id, ) - if request.dataset_name is None - else read_dataset( - connection, - catalog_version_id=catalog_version_id, - name=request.dataset_name, + else: + dataset = read_dataset( + connection, catalog_version_id=catalog_version_id, name=request.dataset_name ) - ) if dataset is None: msg = ( f"{country}'s catalog version for .py {request.policyengine_version} " diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/input_tables.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/input_tables.py index 76200115f..aef548d47 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/input_tables.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/input_tables.py @@ -45,7 +45,7 @@ "city", "place", ) -# The UK region types a local-area breakdown covers. +# The UK region types a report on the local-area dataset calculates. UK_AREA_REGION_TYPES: Final = ("constituency", "local_authority") tax_benefit_models = Table( diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index 4d0f25d42..4e439df2a 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -153,25 +153,34 @@ exception's text. ### Local areas -An economy report may also ask for its constituency and local-authority -impacts with `breakdown: "local_areas"`, left out unless given (null and any -other value are refused with 422). Only a UK report whose region is `uk` or -one of the four `country/*` nations may ask, with or without -`include_cliffs`; any other country or region is refused with 422 at -`breakdown`. It is a request option, never stored with the report. +An economy report created with `data_source: "local_area_dataset"` runs on +the bundle's local-area dataset, the one the .py release routes +constituencies and local authorities to, in place of its region's dataset. +It is an ordinary report: it returns its full results, cliffs included when +asked, and its constituency and local-authority impacts, and is re-run on +the same dataset. `data_source` is left out unless given (null and any other +value are refused with 422), and is never stored as an option: the dataset +is stored with the report's simulations. Only a UK report whose region is +`uk` or one of the four `country/*` nations may ask; any other country or +region is refused with 422 at `data_source`. The default worker's UK entry in the v2 version manifest decides the rest (`local_area_reports`): the input version its coordinator accepts for a local-area report run, and the dataset the .py release routes constituency and local-authority regions to, which the publisher computes by the rule -Stage 12's national aggregation uses to leave the areas out. Without that -declaration, or with another input version, the request is refused with 400 -`local_areas_unsupported` before anything is read. With no dataset, the -release gives the areas none of their own, and the national run calculates -both area levels itself. With one, the catalog version's constituency and -local-authority regions must all use it, whatever `dataset_name` names; -otherwise the request is refused with 400 `local_area_dataset_mismatch`. -Both codes are the service's state, not the caller's. +Stage 12's national aggregation uses to leave the areas out. Before anything +is read: + +- without that declaration, or with another input version, the request is + refused with 400 `local_areas_unsupported`, the service's state; +- with no dataset, the release routes the areas to none of their own, and + the request is refused with 422 `no_local_area_dataset` at `data_source`: + that release's national reports calculate both area levels themselves. + +With a dataset, the catalog version's constituency and local-authority +regions must all use it, or the request is refused with 400 +`local_area_dataset_mismatch`, the service's state; the report is then +calculated on the catalog's row for that dataset. ### Budget windows diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py index 7c3dfc1d7..fd53da375 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py @@ -32,10 +32,7 @@ from typing import Annotated, Any, Literal from uuid import UUID -from policyengine_simulation_contract.local_area_breakdown import ( - LOCAL_AREAS_BREAKDOWN, - local_area_breakdown_error, -) +from policyengine_simulation_contract.local_area_breakdown import UK_NATION_REGIONS from policyengine_simulation_contract.spm import SPMSelection from policyengine_simulation_contract.stage12_bundle import CountryId from policyengine_simulation_persistence import ReportRunStatus, SimulationStatus @@ -54,9 +51,13 @@ CatalogKey = Annotated[str, Field(min_length=1, max_length=255, pattern=r"^\S+$")] ReportLabel = Annotated[str, Field(min_length=1, max_length=255)] ReportDescription = Annotated[str, Field(max_length=10_000)] -# The one breakdown a report may ask for: its constituency and local-authority -# impacts, calculated on the local-area dataset beside the national result. -LocalAreasBreakdown = Literal["local_areas"] +# The one data source a report may ask for: the bundle's local-area dataset, +# on which a UK-wide or nation report also calculates its constituency and +# local-authority impacts. +LOCAL_AREA_DATA_SOURCE = "local_area_dataset" +LocalAreaDataSource = Literal["local_area_dataset"] +# The regions whose reports may run on the local-area dataset. +LOCAL_AREA_DATA_SOURCE_REGIONS = frozenset({"uk", *UK_NATION_REGIONS}) # Why a request is refused (400), naming a row the caller chose that doesn't # exist: the Public API answers these as its caller's error. @@ -93,6 +94,10 @@ # be read, or the household functions' contract refuses what the report # would calculate: located at the household or a side's policy. "household_not_calculable", + # The default worker's .py release routes constituencies and local + # authorities to no dataset of their own, so it has no local-area dataset + # for ``data_source``: located at ``data_source``. + "no_local_area_dataset", ] # Why a route cannot answer now (503); retry after ``Retry-After`` seconds. EconomyUnavailableCode = Literal[ @@ -156,12 +161,14 @@ class EconomyReportRequest(_Request): SPM forecast scenario and geography; omit it, rather than sending null, to use the bundle's certified defaults. - ``breakdown: "local_areas"`` also asks for the report's constituency and - local-authority impacts, calculated on the catalog version's local-area - dataset whatever ``dataset_name`` names. Only a UK report whose region is - ``uk`` or one of the four ``country/*`` nations may ask, with or without - ``include_cliffs``; omit it, rather than sending null, to ask for none. - It is a request option, never stored with the report. + ``data_source: "local_area_dataset"`` runs the report on the bundle's + local-area dataset, the one its .py release routes constituencies and + local authorities to, in place of the region's own: the report returns + its full results, cliffs included when asked, and its constituency and + local-authority impacts. Only a UK report whose region is ``uk`` or one + of the four ``country/*`` nations may ask; omit it, rather than sending + null, to use the region's dataset. It is never stored as an option: the + dataset it chooses is stored with the report's simulations. """ country: CountryId @@ -178,7 +185,7 @@ class EconomyReportRequest(_Request): default=None, json_schema_extra=omit_null_default ) # Last, so its check can read the country and region. - breakdown: LocalAreasBreakdown | SkipJsonSchema[None] = Field( + data_source: LocalAreaDataSource | SkipJsonSchema[None] = Field( default=None, json_schema_extra=omit_null_default ) @@ -191,55 +198,56 @@ def refuse_null_spm(cls, value: object) -> object: raise ValueError(msg) return value - @field_validator("breakdown", mode="before") + @field_validator("data_source", mode="before") @classmethod - def refuse_another_breakdown(cls, value: object) -> object: + def refuse_another_data_source(cls, value: object) -> object: """Refuse null and any other value with one reason. - Omit ``breakdown`` to ask for none. Without this, another value would - be refused once by each member of the field's type. + Omit ``data_source`` to use the region's dataset. Without this, + another value would be refused once by each member of the field's + type. """ - if value != LOCAL_AREAS_BREAKDOWN: + if value != LOCAL_AREA_DATA_SOURCE: msg = ( - f'breakdown must be "{LOCAL_AREAS_BREAKDOWN}" when given; omit it ' - "to ask for no breakdown" + f'data_source must be "{LOCAL_AREA_DATA_SOURCE}" when given; omit ' + "it to use the region's dataset" ) raise ValueError(msg) return value - @field_validator("breakdown") + @field_validator("data_source") @classmethod - def refuse_a_breakdown_the_region_cannot_have( - cls, breakdown: LocalAreasBreakdown | None, info: ValidationInfo - ) -> LocalAreasBreakdown | None: - """Refuse local areas for another country, or a region not UK-wide or a nation. - - A country or region that failed its own validation is reported by - that field alone. + def refuse_a_data_source_the_region_cannot_have( + cls, data_source: LocalAreaDataSource | None, info: ValidationInfo + ) -> LocalAreaDataSource | None: + """Refuse the local-area dataset for another country or region. + + Only a UK report whose region is UK-wide or a nation may run on it. A + country or region that failed its own validation is reported by that + field alone. """ country = info.data.get("country") region_code = info.data.get("region_code") - if breakdown is None or country is None or region_code is None: - return breakdown - # The breakdown's own calculation has no cliffs and no segments, so - # neither option is passed: the national run calculates the cliffs. - reason = local_area_breakdown_error( - country=country, - region=region_code, - region_group=None, - include_cliffs=None, - segmented=None, - ) - if reason is not None: - raise ValueError(reason) - return breakdown + if data_source is None or country is None or region_code is None: + return data_source + if country != "uk": + msg = "the local-area dataset is available only to UK reports" + raise ValueError(msg) + if region_code not in LOCAL_AREA_DATA_SOURCE_REGIONS: + accepted = ", ".join(sorted(LOCAL_AREA_DATA_SOURCE_REGIONS)) + msg = ( + "the local-area dataset needs a UK-wide or nation region " + f"({accepted}), not {region_code!r}" + ) + raise ValueError(msg) + return data_source def options(self) -> dict[str, Any]: """Return the report's options as it stores them (``reports.inputs``). ``spm`` holds only the settings the request gave, and is left out - when it gave none. ``breakdown`` is never stored: it asks for the - report on the local-area dataset too, and never changes this one. + when it gave none. ``data_source`` is never an option: the dataset + it chooses is stored with the report's simulations. """ options: dict[str, Any] = {"include_cliffs": self.include_cliffs} if self.spm is not None: @@ -373,6 +381,9 @@ class EconomyRequestUnprocessable(_Answer): cannot be calculated carry one: ``missing_parameters`` for a policy or dynamic setting parameters the catalog version lacks, and ``overlapping_parameters`` for a policy and dynamic setting the same one. + ``no_local_area_dataset`` refuses ``data_source`` on a .py release that + routes constituencies and local authorities to no dataset of their own: + its national reports calculate both area levels themselves. """ detail: list[EconomyRequestReason] diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submissions.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submissions.py index aa5334bf1..2c0d4ebab 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submissions.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submissions.py @@ -4,13 +4,14 @@ stored policy and dynamic. The service: 1. finds the v2 version manifest's default worker's economy functions for - the country, and its bundle; + the country, and its bundle, and, for a report with ``data_source``, the + local-area dataset its UK entry declares (``local_area_reports``); 2. reads, in one transaction, the country's catalog version for that - worker's .py version, the region and dataset, each side's policy and - dynamic values, and, when the output bucket is configured, each side's - reusable run: a run of the same simulation that succeeded on the same - versions, used by a succeeded report run with the same options, and - never refused for reuse; + worker's .py version, the region and its dataset (or the catalog's + local-area dataset), each side's policy and dynamic values, and, when + the output bucket is configured, each side's reusable run: a run of the + same simulation that succeeded on the same versions, used by a succeeded + report run with the same options, and never refused for reuse; 3. creates, in one transaction, each side's new simulation and pending run (none for a reused side), the report with its options, and its first report run, pending with no Modal call ID; @@ -135,7 +136,8 @@ def read_report_inputs( ) -> EconomyReportInputs: """Read a report's catalog rows, both sides' values and reusable runs. - With ``local_area_dataset_name``, also the catalog's local-area dataset. + With ``local_area_dataset_name``, the report is read on the catalog's + local-area dataset, which must have that name. """ ... diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/local_area_reports.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/local_area_reports.py index 2b1d3379f..28b6efdcb 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/local_area_reports.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/local_area_reports.py @@ -1,14 +1,14 @@ -"""Whether an economy report gets a local-area part, and on which dataset. - -A UK-wide or nation report that asks for ``breakdown: "local_areas"`` gets -its constituency and local-authority impacts from a local-area report run of -its own, on the dataset the .py release routes those regions to. The -default worker's UK entry in the v2 version manifest declares both whether -its coordinator runs such runs (``local_area_reports``, with the input -version it accepts) and that dataset, which the publisher computes in the -worker's own environment by the rule Stage 12's national aggregation uses -to leave the areas out (``uk_area_regions_routed``). So the service, the -national run and the worker decide alike on every release. +"""Which dataset a report created with ``data_source: "local_area_dataset"`` runs on. + +Such a UK-wide or nation report runs on the dataset the .py release routes +constituencies and local authorities to, and returns its full results and +both area levels. The default worker's UK entry in the v2 version manifest +declares both whether its coordinator runs such report runs +(``local_area_reports``, with the input version it accepts) and that +dataset, which the publisher computes in the worker's own environment by the +rule Stage 12's national aggregation uses to leave the areas out +(``uk_area_regions_routed``). So the service, the national runs and the +worker decide alike on every release. """ from __future__ import annotations @@ -21,6 +21,8 @@ from policyengine_simulation_entry.economy_submission_errors import ( EconomySubmissionRefusedError, + EconomySubmissionUnprocessableError, + UnprocessableReason, ) if TYPE_CHECKING: @@ -33,16 +35,18 @@ def local_area_dataset_name( request: EconomyReportRequest, worker: EconomyWorker ) -> str | None: - """Return the dataset the report's area part is calculated on, or None. - - None means no area part: the request asks for none, or the release - routes the area regions to no dataset of their own, so the national run - calculates both area levels itself. Raise EconomySubmissionRefusedError - (``local_areas_unsupported``) when the request asks for local areas and - the default worker declares no local-area report runs of the input - version this service sends. + """Return the dataset a report on the local-area dataset runs on, or None. + + None means the request names no ``data_source``: the report runs on its + region's dataset. Raise EconomySubmissionRefusedError + (``local_areas_unsupported``, the service's state) when the default + worker declares no local-area report runs of the input version this + service sends, and EconomySubmissionUnprocessableError + (``no_local_area_dataset``) when its release routes constituencies and + local authorities to no dataset of their own: there, national reports + calculate both area levels themselves. """ - if request.breakdown is None: + if request.data_source is None: return None declared = worker.local_area_reports if declared is None or declared.input_version != LOCAL_AREA_REPORTS_VERSION: @@ -50,7 +54,23 @@ def local_area_dataset_name( code="local_areas_unsupported", detail=( f"The default v2 worker, .py {worker.version}, cannot calculate " - f"a {request.country} report's local areas." + f"a {request.country} report on the local-area dataset." + ), + ) + if declared.dataset is None: + raise EconomySubmissionUnprocessableError( + code="no_local_area_dataset", + reasons=( + UnprocessableReason( + loc=("body", "data_source"), + msg=( + f".py {worker.policyengine_version} routes constituencies " + "and local authorities to no dataset of their own, so it " + "has no local-area dataset; its national reports " + "calculate both area levels" + ), + type="no_local_area_dataset", + ), ), ) return declared.dataset From 787b47c98e8d8f1ecec32551fa03a731b8caeaee Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:35:04 +0400 Subject: [PATCH 11/18] Test that no report, simulation or budget-window request names a dataset (failing) No request chooses a dataset: a report or simulation runs on its region's dataset, or a UK-wide or nation report on the local-area dataset with data_source. POST /reports (economy reports and budget windows) and POST /simulations refuse dataset_name, given or null, with 422, and the OpenAPI document lists it in none of the three requests. The Public API stops sending it first (PolicyEngine/policyengine-api#4307). A re-run still reads its stored report's dataset by name, so a missing stored dataset keeps its unknown_dataset refusal. Co-Authored-By: Claude Opus 5.5 --- .../test_budget_window_generated_client.py | 1 - .../tests/test_economy_generated_client.py | 2 - .../tests/economy_service_fakes.py | 2 - .../tests/test_economy_routes.py | 26 +++++++++++ .../tests/test_economy_submissions.py | 45 +++++++++++-------- .../tests/test_openapi.py | 3 -- 6 files changed, 52 insertions(+), 27 deletions(-) diff --git a/projects/policyengine-apis-integ/tests/test_budget_window_generated_client.py b/projects/policyengine-apis-integ/tests/test_budget_window_generated_client.py index 86b6d3eb4..ee015c792 100644 --- a/projects/policyengine-apis-integ/tests/test_budget_window_generated_client.py +++ b/projects/policyengine-apis-integ/tests/test_budget_window_generated_client.py @@ -26,7 +26,6 @@ "year": 2026, "budget_window_size": 2, "region_code": "us", - "dataset_name": None, "baseline": {"policy_id": None, "dynamic_id": None}, "reform": {"policy_id": POLICY_ID, "dynamic_id": None}, } diff --git a/projects/policyengine-apis-integ/tests/test_economy_generated_client.py b/projects/policyengine-apis-integ/tests/test_economy_generated_client.py index 5f32692db..077784d88 100644 --- a/projects/policyengine-apis-integ/tests/test_economy_generated_client.py +++ b/projects/policyengine-apis-integ/tests/test_economy_generated_client.py @@ -39,7 +39,6 @@ "description": None, "year": 2026, "region_code": "us", - "dataset_name": None, "baseline": {"policy_id": None, "dynamic_id": None}, "reform": {"policy_id": POLICY_ID, "dynamic_id": None}, "include_cliffs": False, @@ -49,7 +48,6 @@ "simulation_type": "economy", "year": 2026, "region_code": "country/wales", - "dataset_name": None, "policy_id": None, "dynamic_id": None, } diff --git a/projects/policyengine-simulation-entry/tests/economy_service_fakes.py b/projects/policyengine-simulation-entry/tests/economy_service_fakes.py index 2ca8f7166..1f7c385dc 100644 --- a/projects/policyengine-simulation-entry/tests/economy_service_fakes.py +++ b/projects/policyengine-simulation-entry/tests/economy_service_fakes.py @@ -79,7 +79,6 @@ "description": "Raises the credit to $3,000", "year": 2026, "region_code": "us", - "dataset_name": None, "baseline": {"policy_id": None, "dynamic_id": None}, "reform": {"policy_id": str(POLICY_ID), "dynamic_id": str(DYNAMIC_ID)}, "include_cliffs": True, @@ -90,7 +89,6 @@ "simulation_type": "economy", "year": 2026, "region_code": "us", - "dataset_name": None, "policy_id": str(POLICY_ID), "dynamic_id": None, } diff --git a/projects/policyengine-simulation-entry/tests/test_economy_routes.py b/projects/policyengine-simulation-entry/tests/test_economy_routes.py index ab6f52f15..8bf0e622f 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_routes.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_routes.py @@ -42,6 +42,7 @@ ReportRunStatus, SimulationStatus, ) +from test_budget_window_requests import WINDOW_BODY OBSERVABILITY_ID = "6e1f3d4c-0a5b-4c39-9d2e-7f8a9b0c1d2e" RECORD_ID = UUID("00000000-0000-4000-8000-0000000000e1") @@ -219,6 +220,31 @@ def test_a_malformed_request_is_refused_with_its_reasons(client_for, path, body) assert (submissions.reports, submissions.simulations) == ([], []) +@pytest.mark.parametrize("dataset_name", ["enhanced_cps_2024", None]) +@pytest.mark.parametrize( + ("path", "body"), + [ + ("/reports", REPORT_BODY), + ("/simulations", SIMULATION_BODY), + ("/reports", WINDOW_BODY), + ], + ids=["report", "simulation", "budget window"], +) +def test_a_request_naming_a_dataset_is_refused( + client_for, path, body, dataset_name +) -> None: + """No request chooses a dataset: each runs on its region's (or data_source's).""" + submissions = FakeEconomySubmissions() + + with client_for(submissions) as client: + result = client.post(path, json={**body, "dataset_name": dataset_name}) + + assert result.status_code == 422 + (reason,) = result.json()["detail"] + assert (reason["loc"][-1], reason["type"]) == ("dataset_name", "extra_forbidden") + assert (submissions.reports, submissions.simulations) == ([], []) + + # A UK-wide report on the local-area dataset, with cliffs and no SPM settings. LOCAL_AREA_REPORT_BODY: dict[str, Any] = { **{name: value for name, value in REPORT_BODY.items() if name != "spm"}, diff --git a/projects/policyengine-simulation-entry/tests/test_economy_submissions.py b/projects/policyengine-simulation-entry/tests/test_economy_submissions.py index 062fa9b7c..01108af01 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_submissions.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_submissions.py @@ -36,6 +36,7 @@ EconomySubmissionRefusedError, EconomySubmissionUnavailableError, EconomySubmissionUnprocessableError, + read_refusal, ) from policyengine_simulation_entry.economy_workers import ( EconomyWorkerUnavailableError, @@ -48,6 +49,7 @@ EconomyRecordOutcomeUnknownError, EconomyRecordReferenceError, EconomyReportState, + EconomyRequest, EconomySimulationState, MissingPolicyParametersError, OverlappingReformError, @@ -262,24 +264,20 @@ def test_a_parameter_the_policy_and_dynamic_both_set_cannot_be_calculated() -> N ] -@pytest.mark.parametrize( - ("dataset_name", "code"), - [(None, "dataset_not_in_bundle"), ("enhanced_cps_2024", "unknown_dataset")], -) -def test_a_catalog_dataset_the_bundle_lacks_is_refused(dataset_name, code) -> None: +def test_a_region_dataset_the_bundle_lacks_is_the_services_state() -> None: catalog = replace( CATALOG, dataset=CatalogDataset(id=CATALOG.dataset.id, name="enhanced_cps_2024") ) store = FakeStore(catalog=catalog) with pytest.raises(EconomySubmissionRefusedError) as refusal: - _submit_report(service(store), report_request(dataset_name=dataset_name)) + _submit_report(service(store), report_request()) - assert refusal.value.code == code + assert refusal.value.code == "dataset_not_in_bundle" assert store.reports == [] -def test_a_named_dataset_in_the_bundle_is_the_one_calculated() -> None: +def test_the_catalog_dataset_in_the_bundle_is_the_one_calculated() -> None: catalog = replace( CATALOG, dataset=CatalogDataset(id=CATALOG.dataset.id, name=STATE_DATASET.identity), @@ -287,10 +285,7 @@ def test_a_named_dataset_in_the_bundle_is_the_one_calculated() -> None: store = FakeStore(catalog=catalog) caller = FakeCaller() - _submit_report( - service(store, caller=caller), - report_request(dataset_name=STATE_DATASET.identity), - ) + _submit_report(service(store, caller=caller), report_request()) payload = ReportExecutionInput.model_validate(caller.report_runs[0][1]) assert payload.baseline.bundle.dataset.identity == STATE_DATASET.identity @@ -585,13 +580,6 @@ def test_a_reports_overlapping_parameters_are_located_on_their_side() -> None: f"us's catalog version for .py {POLICYENGINE_VERSION} has no region " "state/zz.", ), - ( - UnknownDatasetError(ERROR_TEXT), - {"dataset_name": "acs_2099"}, - "unknown_dataset", - f"us's catalog version for .py {POLICYENGINE_VERSION} has no dataset " - "acs_2099.", - ), ( UnknownDatasetError(ERROR_TEXT), {}, @@ -625,6 +613,25 @@ def test_a_refusals_detail_is_built_from_the_request_not_the_error( assert ERROR_TEXT not in refusal.value.detail +def test_a_stored_dataset_the_catalog_lacks_is_named_in_the_refusal() -> None: + """A request names no dataset, but a re-run reads its stored report's by name.""" + stored = EconomyRequest( + country="us", + policyengine_version=POLICYENGINE_VERSION, + region_code="us", + dataset_name="acs_2099", + year=2026, + ) + + refusal = read_refusal(UnknownDatasetError(ERROR_TEXT), stored) + + assert isinstance(refusal, EconomySubmissionRefusedError) + assert (refusal.code, refusal.detail) == ( + "unknown_dataset", + f"us's catalog version for .py {POLICYENGINE_VERSION} has no dataset acs_2099.", + ) + + def test_a_standalone_simulations_unknown_rows_name_its_own_fields() -> None: for error, detail in ( (UnknownPolicyError(ERROR_TEXT), "us has no stored policy the request names."), diff --git a/projects/policyengine-simulation-entry/tests/test_openapi.py b/projects/policyengine-simulation-entry/tests/test_openapi.py index efc6cf81a..a3b7cbc21 100644 --- a/projects/policyengine-simulation-entry/tests/test_openapi.py +++ b/projects/policyengine-simulation-entry/tests/test_openapi.py @@ -435,7 +435,6 @@ def test_economy_requests_name_no_version_and_no_record_id(): "description", "year", "region_code", - "dataset_name", "baseline", "reform", "include_cliffs", @@ -447,7 +446,6 @@ def test_economy_requests_name_no_version_and_no_record_id(): "simulation_type", "year", "region_code", - "dataset_name", "policy_id", "dynamic_id", } @@ -489,7 +487,6 @@ def test_a_report_request_is_an_economy_report_a_budget_window_or_a_household(): "year", "budget_window_size", "region_code", - "dataset_name", "baseline", "reform", "spm", From f176fec08b930b0e1287c5a415d8c0a7261bc4a4 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:36:34 +0400 Subject: [PATCH 12/18] Take no dataset_name on reports, simulations or budget windows EconomyReportRequest, EconomySimulationRequest and BudgetWindowReportRequest lose dataset_name, so their strict models refuse it, given or null, with 422: a report or simulation runs on the dataset the catalog gives its region, or a UK-wide or nation report on the local-area dataset with data_source. A bundle lacking the catalog dataset is always the service's state (dataset_not_in_bundle). The persistence library's EconomyRequest keeps dataset_name, which re-runs set from the stored report. The Public API stops sending the field first (PolicyEngine/policyengine-api#4307), and this deploys only after that. Co-Authored-By: Claude Opus 5.5 --- .../policyengine-simulation-entry/README.md | 12 ++++---- .../budget_window_api_models.py | 9 +++--- .../economy_api_models.py | 24 +++++++-------- .../economy_submission_errors.py | 7 +++-- .../economy_submissions.py | 29 ++++++++++--------- 5 files changed, 42 insertions(+), 39 deletions(-) diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index 4e439df2a..0d82b42b5 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -111,11 +111,13 @@ staging check. `POST /reports` creates an economy report: a baseline and a reform simulation of one region's data for one year. It names the `country`, `report_type` (`economy`), `label`, `description`, `year`, `region_code` -and `dataset_name` (a region and dataset of the country's catalog version -for the default worker's .py version; null for the region's default -dataset), each side's stored `policy_id` and `dynamic_id` (null for current -law), `include_cliffs`, and `spm` (SPM settings; omit it, since null is -refused). `POST /simulations` creates a standalone economy simulation from +(a region of the country's catalog version for the default worker's .py +version), each side's stored `policy_id` and `dynamic_id` (null for current +law), `include_cliffs`, `spm` (SPM settings; omit it, since null is +refused) and, for a UK-wide or nation report, `data_source` (see "Local +areas"). No request names a dataset: a report or simulation runs on the +dataset the catalog version gives its region, and `dataset_name` is refused +with 422. `POST /simulations` creates a standalone economy simulation from the same fields for one policy and dynamic. Neither names a .py version or a record ID: the service runs the v2 version manifest's default worker and chooses every ID. diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/budget_window_api_models.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/budget_window_api_models.py index 467678e71..c4a41cc51 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/budget_window_api_models.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/budget_window_api_models.py @@ -46,10 +46,10 @@ class BudgetWindowReportRequest(BaseModel): """A budget-window report: a baseline and a reform in each year of a window. ``year`` is the window's first year, and ``budget_window_size`` its - length. Every year uses the request's region and dataset, as an economy - report does. ``spm`` selects the SPM forecast scenario and geography; - omit it, rather than sending null, to use the bundle's certified - defaults. + length. Every year uses the request's region and its dataset, as an + economy report does; no request names a dataset. ``spm`` selects the SPM + forecast scenario and geography; omit it, rather than sending null, to + use the bundle's certified defaults. """ model_config = ConfigDict(extra="forbid", frozen=True, allow_inf_nan=False) @@ -61,7 +61,6 @@ class BudgetWindowReportRequest(BaseModel): year: SimulationYear budget_window_size: BudgetWindowSize region_code: CatalogKey - dataset_name: CatalogKey | None = None baseline: PolicyChoice reform: PolicyChoice spm: SPMSelection | SkipJsonSchema[None] = Field( diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py index fd53da375..714021fbc 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py @@ -1,9 +1,11 @@ """Request and response models of the economy simulation and report routes. -The Public API names a region and dataset of the country's catalog by code -and name, and each simulation's stored policy and dynamic by ID; the -Simulation Entrypoint reads them from the Public API's tables itself, and -calculates on the v2 version manifest's default worker. A request names no +The Public API names a region of the country's catalog by code, and each +simulation's stored policy and dynamic by ID; the Simulation Entrypoint +reads them, and the dataset the catalog gives the region, from the Public +API's tables itself, and calculates on the v2 version manifest's default +worker. No request names a dataset: only a UK-wide or nation report may +choose the bundle's local-area dataset instead (``data_source``). A request names no .py version and no record ID: the service runs its default worker's version and chooses every ID. @@ -60,7 +62,8 @@ LOCAL_AREA_DATA_SOURCE_REGIONS = frozenset({"uk", *UK_NATION_REGIONS}) # Why a request is refused (400), naming a row the caller chose that doesn't -# exist: the Public API answers these as its caller's error. +# exist, or its region's dataset (a stored report's, on a re-run): the Public +# API answers these as its caller's error. CallerRowRefusalCode = Literal["unknown_region", "unknown_dataset", "unknown_dynamic"] # Why a request is refused (400) for the service's own state, or a row the # Public API checks before asking. @@ -140,23 +143,21 @@ class EconomySimulationRequest(PolicyChoice): """An economy simulation: a policy and dynamic applied to one region's data. ``region_code`` is a region of the country's catalog version for the - default worker's .py version (``us``, ``state/ca``, ``country/wales``), - and ``dataset_name`` one of that version's datasets; without it, the - region's default dataset is used. + default worker's .py version (``us``, ``state/ca``, ``country/wales``); + the simulation runs on the dataset that version gives the region. """ country: CountryId simulation_type: Literal["economy"] year: SimulationYear region_code: CatalogKey - dataset_name: CatalogKey | None = None class EconomyReportRequest(_Request): """An economy report: a baseline and a reform simulation of one region's data. - Both simulations use the report's year, region and dataset, as - ``EconomySimulationRequest`` describes them. ``include_cliffs`` also + Both simulations use the report's year and region, and the region's + dataset, as ``EconomySimulationRequest`` describes them. ``include_cliffs`` also calculates the baseline's and reform's cliff impact. ``spm`` selects the SPM forecast scenario and geography; omit it, rather than sending null, to use the bundle's certified defaults. @@ -177,7 +178,6 @@ class EconomyReportRequest(_Request): description: ReportDescription | None = None year: SimulationYear region_code: CatalogKey - dataset_name: CatalogKey | None = None baseline: PolicyChoice reform: PolicyChoice include_cliffs: StrictBool = False diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submission_errors.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submission_errors.py index d08f457ec..36cc0e381 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submission_errors.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submission_errors.py @@ -42,9 +42,10 @@ ) # Each column whose foreign key can refuse a submission's rows: the code the -# refusal answers with and the row it names. A region, dataset or dynamic is -# the caller's own choice; any other row is one the Public API checked first, -# or one the service chose, so its refusal is the service's state. +# refusal answers with and the row it names. A region or dynamic is the +# caller's own choice, and a dataset its region's (or a stored report's, on a +# re-run); any other row is one the Public API checked first, or one the +# service chose, so its refusal is the service's state. REFERENCE_REFUSALS: dict[str, tuple[EconomyRefusalCode, str]] = { "region_id": ("unknown_region", "region"), "dataset_id": ("unknown_dataset", "dataset"), diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submissions.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submissions.py index 2c0d4ebab..0046214fe 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submissions.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submissions.py @@ -1,7 +1,8 @@ """Create economy reports and simulations, and start the calls that calculate them. -A report submission names a region, a dataset, a year and each side's -stored policy and dynamic. The service: +A report submission names a region, a year and each side's stored policy +and dynamic, and runs on the region's dataset, or, with ``data_source``, on +the bundle's local-area dataset. The service: 1. finds the v2 version manifest's default worker's economy functions for the country, and its bundle, and, for a report with ``data_source``, the @@ -101,7 +102,6 @@ BudgetWindowReportRequest, ) from policyengine_simulation_entry.economy_api_models import ( - EconomyRefusalCode, EconomyReportRequest, EconomySimulationRequest, PolicyChoice, @@ -664,12 +664,16 @@ def economy_request_for( | BudgetWindowReportRequest, worker: EconomyWorker, ) -> EconomyRequest: - """Return what the request names apart from policies, for the default worker.""" + """Return what the request names apart from policies, for the default worker. + + It names no dataset: the store reads the region's, or the local-area + dataset a report on it asks for. + """ return EconomyRequest( country=request.country, policyengine_version=worker.policyengine_version, region_code=request.region_code, - dataset_name=request.dataset_name, + dataset_name=None, year=request.year, ) @@ -685,23 +689,20 @@ def calculation_scope( ) -> CalculationScope: """Return what the calculation runs on, with the bundle's dataset. - Raise EconomySubmissionRefusedError when the bundle lacks the catalog - dataset: ``unknown_dataset`` when the request named it, and - ``dataset_not_in_bundle`` for the region's default. + Raise EconomySubmissionRefusedError (``dataset_not_in_bundle``, the + service's state) when the bundle lacks the catalog dataset: no request + names one. """ try: dataset = bundle_dataset(worker, catalog.dataset.name) except DatasetNotInBundleError: - code: EconomyRefusalCode = ( - "dataset_not_in_bundle" - if request.dataset_name is None - else "unknown_dataset" - ) detail = ( f"The default v2 worker, .py {worker.version}, has no dataset " f"{catalog.dataset.name}." ) - raise EconomySubmissionRefusedError(code=code, detail=detail) from None + raise EconomySubmissionRefusedError( + code="dataset_not_in_bundle", detail=detail + ) from None return CalculationScope( country=request.country, region_code=catalog.region.code, From 2ca53c7e34b4e6821a21ce4b0055b1fdd2fac525 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:37:46 +0400 Subject: [PATCH 13/18] Test that the staging economy check's Wales report runs on the local-area dataset (failing) The check's POST /reports sends data_source: "local_area_dataset", so its current-law Wales 2026 run also calculates Wales's constituencies and local authorities. The coordinator fails a run of such a report unless both area levels have rows or withheld codes, so the check's requirement that the run succeeds covers them. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_staging_economy_check.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/projects/policyengine-simulation-entry/tests/test_staging_economy_check.py b/projects/policyengine-simulation-entry/tests/test_staging_economy_check.py index 097ab1974..335cb1571 100644 --- a/projects/policyengine-simulation-entry/tests/test_staging_economy_check.py +++ b/projects/policyengine-simulation-entry/tests/test_staging_economy_check.py @@ -174,6 +174,10 @@ def test_the_check_creates_a_small_report_and_waits_for_its_run_to_succeed( "baseline": {"policy_id": None, "dynamic_id": None}, "reform": {"policy_id": None, "dynamic_id": None}, "include_cliffs": False, + # On the local-area dataset, so the run also calculates Wales's + # constituencies and local authorities: the coordinator fails a run of + # such a report unless both area levels have rows or withheld codes. + "data_source": "local_area_dataset", } assert (state / "read-url").read_text(encoding="utf-8").strip() == ( f"{BASE_URL}/reports/{REPORT_ID}" From 2a3bbc61602590c575bcf1aa0b72343f262c5eba Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:38:23 +0400 Subject: [PATCH 14/18] Run the staging economy check's Wales report on the local-area dataset Its POST /reports sends data_source: "local_area_dataset", so the run also calculates Wales's constituencies and local authorities, and the coordinator's condition that both area levels have rows or withheld codes makes the run's success cover them (decision 9). DEPLOYMENT.md and the deploy workflow's job comment say so. Changelog fragments for data_source and for removing dataset_name. Co-Authored-By: Claude Opus 5.5 --- .github/scripts/simulation-staging-economy-check.sh | 8 ++++++-- .github/workflows/simulation-deploy.reusable.yml | 5 +++-- changelog.d/c1-29a-data-source.added.md | 1 + changelog.d/c1-29a-no-dataset-name.removed.md | 1 + projects/policyengine-simulation-entry/DEPLOYMENT.md | 5 ++++- 5 files changed, 15 insertions(+), 5 deletions(-) create mode 100644 changelog.d/c1-29a-data-source.added.md create mode 100644 changelog.d/c1-29a-no-dataset-name.removed.md diff --git a/.github/scripts/simulation-staging-economy-check.sh b/.github/scripts/simulation-staging-economy-check.sh index ae24e8673..433b79b4e 100755 --- a/.github/scripts/simulation-staging-economy-check.sh +++ b/.github/scripts/simulation-staging-economy-check.sh @@ -1,7 +1,10 @@ #!/bin/bash # Create a small economy report through a deployed Simulation Entrypoint, and # require its run to succeed: current law against current law for Wales in -# 2026, which needs no stored policy. +# 2026, which needs no stored policy, on the bundle's local-area dataset +# (data_source), so the run also calculates Wales's constituencies and local +# authorities. The coordinator fails a run of such a report unless both area +# levels have rows or withheld codes, so its success covers them. # Usage: simulation-staging-economy-check.sh # Required env vars: the test client's SIMULATION_TEST_AUTH_ISSUER, # SIMULATION_TEST_AUTH_AUDIENCE, SIMULATION_TEST_AUTH_CLIENT_ID and @@ -76,7 +79,8 @@ submission_status="$( region_code: "country/wales", baseline: {policy_id: null, dynamic_id: null}, reform: {policy_id: null, dynamic_id: null}, - include_cliffs: false + include_cliffs: false, + data_source: "local_area_dataset" }' \ | send submission "${submission_timeout_seconds}" --request POST --header "@${authorization_header}" \ --header 'Content-Type: application/json' --data @- \ diff --git a/.github/workflows/simulation-deploy.reusable.yml b/.github/workflows/simulation-deploy.reusable.yml index b89de5283..ea5aec373 100644 --- a/.github/workflows/simulation-deploy.reusable.yml +++ b/.github/workflows/simulation-deploy.reusable.yml @@ -1256,8 +1256,9 @@ jobs: staging_economy_check: name: Create a staging economy report through the candidate # Every staging deployment creates a small economy report, current law - # against current law for Wales in 2026, through the candidate's - # POST /reports, and requires its run to succeed. The routes use only + # against current law for Wales in 2026 on the local-area dataset, + # through the candidate's POST /reports, and requires its run, which also + # calculates Wales's constituencies and local authorities, to succeed. The routes use only # the v2 manifest's default worker, so the check runs after the default # has moved to the release's worker (or, in a deployment without Stage # 12, with the default as it is). It calls the tagged candidate URL, diff --git a/changelog.d/c1-29a-data-source.added.md b/changelog.d/c1-29a-data-source.added.md new file mode 100644 index 000000000..c71fbd40c --- /dev/null +++ b/changelog.d/c1-29a-data-source.added.md @@ -0,0 +1 @@ +`POST /reports` takes `data_source: "local_area_dataset"` on UK-wide and nation economy reports: the report runs on the bundle's local-area dataset (the one constituency and local-authority regions use) and returns its full results with its constituency and local-authority results. Another value, another country or region, and a release that routes those areas to no dataset of their own (`no_local_area_dataset`) are refused with 422. The staging economy check's Wales report runs on that dataset. diff --git a/changelog.d/c1-29a-no-dataset-name.removed.md b/changelog.d/c1-29a-no-dataset-name.removed.md new file mode 100644 index 000000000..5a7911579 --- /dev/null +++ b/changelog.d/c1-29a-no-dataset-name.removed.md @@ -0,0 +1 @@ +`POST /reports` (economy reports and budget windows) and `POST /simulations` no longer take `dataset_name`, and refuse it with 422: a report or simulation runs on the dataset the catalog gives its region, or on the local-area dataset with `data_source`. The Public API stopped sending it in PolicyEngine/policyengine-api#4307, which must be deployed first. diff --git a/projects/policyengine-simulation-entry/DEPLOYMENT.md b/projects/policyengine-simulation-entry/DEPLOYMENT.md index 5972daaff..d22656a90 100644 --- a/projects/policyengine-simulation-entry/DEPLOYMENT.md +++ b/projects/policyengine-simulation-entry/DEPLOYMENT.md @@ -133,9 +133,12 @@ Stage 12 secret sync writes. Every staging deployment runs `staging_economy_check` when the household check runs: `.github/scripts/simulation-staging-economy-check.sh` creates a small report, current law against current law for `country/wales` in 2026, +on the bundle's local-area dataset (`data_source: "local_area_dataset"`), through the candidate's tagged URL with the authenticated tests' client credentials, follows it through `GET /reports/{report_id}`, and requires its -run to succeed within 30 minutes. `deployment_ready` requires the check to +run to succeed within 30 minutes. The run also calculates Wales's +constituencies and local authorities, and the coordinator fails it unless +both area levels have rows or withheld codes, so its success covers them. `deployment_ready` requires the check to pass in staging, so a failure stops the production deployment. Each run adds a report and its runs to the staging database. Once a .py version's first check has succeeded, later checks on that version reuse its simulation runs, From 0855c6132fd8d36c7aa06071c2a36fafd9159fb2 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:02:41 +0400 Subject: [PATCH 15/18] Test review round 1's findings for data_source (one failing) Review round 1 found no bugs; these cover its test gaps. Passing as guards: the routes answer 400 local_areas_unsupported and local_area_dataset_mismatch, and 422 no_local_area_dataset at data_source, with their codes; the OpenAPI document lists the three codes; budget windows, household reports and report re-runs refuse data_source as an unknown field; and a report stored on the local-area dataset is re-run on it. Failing: the catalog read refuses a request that names a dataset and the local-area dataset at once, which today reads the local-area one silently. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_economy_run_store.py | 13 ++++ .../tests/test_economy_rerun_routes.py | 13 ++++ .../tests/test_economy_routes.py | 75 +++++++++++++++++++ .../tests/test_local_area_submissions.py | 49 +++++++++++- .../tests/test_openapi.py | 13 ++++ 5 files changed, 162 insertions(+), 1 deletion(-) diff --git a/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py b/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py index ead2e413d..bc9725255 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py @@ -54,6 +54,7 @@ UnknownRegionError, economy_run_store, ) +from policyengine_simulation_persistence.economy_catalog_rows import read_catalog_rows from public_api_rows import StoredValue, insert_dataset, insert_dynamic, insert_policy from sqlalchemy import text from sqlalchemy.exc import OperationalError @@ -628,3 +629,15 @@ def refuse(*_, refusal=refusal): REQUEST, baseline=CURRENT_LAW, reform=CURRENT_LAW, reuse=None ) assert (raised.value.side, raised.value.error) == ("baseline", refusal) + + +def test_a_request_naming_a_dataset_and_the_local_area_dataset_is_refused() -> None: + """A re-run names its stored dataset and a create the local-area one, never both.""" + named = EconomyRequest(**{**vars(UK_REQUEST), "dataset_name": "acs_local_2024"}) + + with pytest.raises(ValueError, match="either a dataset name or"): + read_catalog_rows( + None, # refused before any read + named, + local_area_dataset_name=LOCAL_AREA_DATASET_NAME, + ) diff --git a/projects/policyengine-simulation-entry/tests/test_economy_rerun_routes.py b/projects/policyengine-simulation-entry/tests/test_economy_rerun_routes.py index 99cd90072..47006fd5b 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_rerun_routes.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_rerun_routes.py @@ -416,3 +416,16 @@ def test_an_unconfigured_service_answers_503(client_for, path, body) -> None: assert result.status_code == 503 assert result.json()["code"] == "not_configured" + + +def test_a_report_rerun_takes_no_data_source(client_for) -> None: + """A re-run keeps the stored report's dataset, whatever it was created with.""" + reruns = FakeEconomyReruns() + + with client_for(reruns) as client: + result = client.post(REPORT_RUNS, json={"data_source": "local_area_dataset"}) + + assert result.status_code == 422 + (reason,) = result.json()["detail"] + assert (reason["loc"][-1], reason["type"]) == ("data_source", "extra_forbidden") + assert reruns.report_reruns == [] diff --git a/projects/policyengine-simulation-entry/tests/test_economy_routes.py b/projects/policyengine-simulation-entry/tests/test_economy_routes.py index 927965bae..9cf572945 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_routes.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_routes.py @@ -13,6 +13,7 @@ from conftest import FakeBackend, make_settings from economy_service_fakes import REPORT_BODY, SIMULATION_BODY from fastapi.testclient import TestClient +from household_report_fakes import HOUSEHOLD_REPORT_BODY from policyengine_observability import REQUEST_ID_HEADER from policyengine_simulation_entry import app as app_module from policyengine_simulation_entry.app import create_app @@ -295,6 +296,80 @@ def test_a_data_source_a_report_cannot_have_is_refused( assert submissions.reports == [] +@pytest.mark.parametrize( + ("failure", "status_code", "answer"), + [ + ( + EconomySubmissionRefusedError( + code="local_areas_unsupported", detail="no local-area report runs" + ), + 400, + {"code": "local_areas_unsupported", "detail": "no local-area report runs"}, + ), + ( + EconomySubmissionRefusedError( + code="local_area_dataset_mismatch", detail="another dataset" + ), + 400, + {"code": "local_area_dataset_mismatch", "detail": "another dataset"}, + ), + ( + EconomySubmissionUnprocessableError( + code="no_local_area_dataset", + reasons=( + UnprocessableReason( + loc=("body", "data_source"), + msg="no local-area dataset", + type="no_local_area_dataset", + ), + ), + ), + 422, + { + "detail": [ + { + "loc": ["body", "data_source"], + "msg": "no local-area dataset", + "type": "no_local_area_dataset", + } + ], + "code": "no_local_area_dataset", + }, + ), + ], + ids=["unsupported", "mismatch", "no dataset"], +) +def test_a_local_area_refusal_answers_with_its_code( + client_for, failure, status_code, answer +) -> None: + submissions = FakeEconomySubmissions(failure=failure) + + with client_for(submissions) as client: + result = client.post("/reports", json=LOCAL_AREA_REPORT_BODY) + + assert result.status_code == status_code + assert result.json() == answer + + +@pytest.mark.parametrize( + "body", + [WINDOW_BODY, HOUSEHOLD_REPORT_BODY], + ids=["budget window", "household report"], +) +def test_only_an_economy_report_takes_a_data_source(client_for, body) -> None: + submissions = FakeEconomySubmissions() + + with client_for(submissions) as client: + result = client.post( + "/reports", json={**body, "data_source": "local_area_dataset"} + ) + + assert result.status_code == 422 + (reason,) = result.json()["detail"] + assert (reason["loc"][-1], reason["type"]) == ("data_source", "extra_forbidden") + assert submissions.reports == [] + + @pytest.mark.parametrize( "region_code", [ diff --git a/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py b/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py index f2f06ccab..242f966a4 100644 --- a/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py +++ b/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py @@ -20,6 +20,12 @@ ROUTED_LOCAL_AREAS, local_area_worker_version, ) +from economy_rerun_fakes import ( + REPORT_ID, + STORED_REPORT, + FakeRerunStore, + rerun_service, +) from economy_service_fakes import ( CATALOG, REPORT_BODY, @@ -30,7 +36,10 @@ ) from policyengine_simulation_contract.stage12_execution import ReportExecutionInput from policyengine_simulation_contract.stage12_manifest import LocalAreaReports -from policyengine_simulation_entry.economy_api_models import EconomyReportRequest +from policyengine_simulation_entry.economy_api_models import ( + EconomyReportRequest, + ReportRerunRequest, +) from policyengine_simulation_entry.economy_submission_errors import ( EconomySubmissionRefusedError, EconomySubmissionUnprocessableError, @@ -190,3 +199,41 @@ def test_a_catalog_whose_area_regions_use_another_dataset_is_refused() -> None: # Written from the declaration, never from the error's text. assert LOCAL_AREA_DATASET.identity in refusal.value.detail assert store.reports == [] + + +def test_a_report_on_the_local_area_dataset_is_rerun_on_it() -> None: + """A re-run reads the stored report's dataset by name, and takes no data_source.""" + stored = replace( + STORED_REPORT, + country="uk", + region_code="uk", + dataset_name=LOCAL_AREA_DATASET.identity, + inputs={"include_cliffs": True}, + ) + store = FakeRerunStore( + report_definition=stored, + catalog=replace(UK_CATALOG, dataset=CATALOG_LOCAL_AREA_DATASET), + ) + caller = FakeCaller() + + asyncio.run( + rerun_service( + store, workers=_workers_declaring(ROUTED_LOCAL_AREAS), caller=caller + ).rerun_report( + REPORT_ID, + ReportRerunRequest(), + request_id="observed", + observability_context=None, + ) + ) + + ((request, _),) = store.rerun_reads + assert (request.region_code, request.dataset_name) == ( + "uk", + LOCAL_AREA_DATASET.identity, + ) + ((_, payload, _, _),) = caller.report_runs + execution = ReportExecutionInput.model_validate(payload) + for side in (execution.baseline, execution.reform): + assert side.bundle.dataset.identity == LOCAL_AREA_DATASET.identity + assert side.geography.region == "uk" diff --git a/projects/policyengine-simulation-entry/tests/test_openapi.py b/projects/policyengine-simulation-entry/tests/test_openapi.py index d22ecec30..267754f56 100644 --- a/projects/policyengine-simulation-entry/tests/test_openapi.py +++ b/projects/policyengine-simulation-entry/tests/test_openapi.py @@ -610,3 +610,16 @@ def test_economy_reads_declare_every_answer(): names = operation_ids(cast("OpenAPIDocument", spec)) assert names[("GET", "/reports/{report_id}")] == "get_report" assert names[("GET", "/simulations/{simulation_id}")] == "get_simulation" + + +def test_the_local_area_refusals_are_in_the_error_codes(): + """A report on the local-area dataset has two 400 codes and one 422 code.""" + schemas = create_app().openapi()["components"]["schemas"] + + error_codes = set(schemas["EconomyError"]["properties"]["code"]["enum"]) + unprocessable_codes = set( + schemas["EconomyRequestUnprocessable"]["properties"]["code"]["enum"] + ) + + assert {"local_areas_unsupported", "local_area_dataset_mismatch"} <= error_codes + assert "no_local_area_dataset" in unprocessable_codes From ed55d3550798d574c1623981d9b2fa0a4091c1ef Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:03:50 +0400 Subject: [PATCH 16/18] Fix review round 1's findings for data_source The catalog read refuses, before any read, a request naming a dataset together with the local-area dataset (a re-run names its stored dataset, a create the local-area one), so neither silently wins. The /reports 400 and 422 descriptions, the entry README and the persistence library's README now say a create names no dataset, list the local-area codes, and describe read_local_area_dataset, economy_catalog_rows and LocalAreaDatasetMismatchError. Co-Authored-By: Claude Opus 5.5 --- .../README.md | 17 +++++++++++++---- .../economy_catalog_rows.py | 16 ++++++++++++---- .../policyengine-simulation-entry/README.md | 17 ++++++++++------- .../economy_routes.py | 17 ++++++++++------- 4 files changed, 45 insertions(+), 22 deletions(-) diff --git a/libs/policyengine-simulation-persistence/README.md b/libs/policyengine-simulation-persistence/README.md index b3ca22046..d567019e3 100644 --- a/libs/policyengine-simulation-persistence/README.md +++ b/libs/policyengine-simulation-persistence/README.md @@ -87,7 +87,9 @@ runs too long and the limit never stays on a pooled connection. an economy report, or a standalone economy simulation. It reads the country's model (`read_model_id`) and a catalog version's region by code (`read_region`) and dataset by name or ID (`read_dataset`, -`read_dataset_by_id`). `insert_economy_report` creates, in the caller's +`read_dataset_by_id`), and its local-area dataset +(`read_local_area_dataset`): the one default dataset every constituency and +local-authority region of the version uses, or none. `insert_economy_report` creates, in the caller's transaction, each side's new simulation and first run, the report naming both simulations and the reform's policy with its options in `inputs`, and its first report run, trigger `initial`; every run is `pending` with no @@ -118,9 +120,16 @@ a transaction of its own: `read_report_inputs` reads the catalog version, model, region and dataset, each side's policy and dynamic values, and each side's reusable run together, never giving both sides the same run; `read_simulation_inputs` does the same for one simulation; the writes and -reads each take their own. A missing region or dataset raises -`UnknownRegionError` or `UnknownDatasetError`, and a report side's refused -policy or dynamic raises `ReportSideError`, naming the side. A create whose +reads each take their own. The catalog rows come from +`economy_catalog_rows.py` (`read_catalog_rows`): the dataset is the +region's default, a re-run's stored dataset by name (`EconomyRequest`'s +`dataset_name`), or, for a report created with `data_source` +(`read_report_inputs`'s `local_area_dataset_name`), the catalog version's +local-area dataset, never two of these at once. A missing region or dataset +raises `UnknownRegionError` or `UnknownDatasetError`, a local-area dataset +the catalog doesn't give both area types raises +`LocalAreaDatasetMismatchError`, and a report side's refused policy or +dynamic raises `ReportSideError`, naming the side. A create whose commit fails after its rows were inserted raises `EconomyRecordOutcomeUnknownError`: PostgreSQL may have applied the commit, so the rows may exist. diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_catalog_rows.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_catalog_rows.py index ebf7b5e02..fded807dc 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_catalog_rows.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_catalog_rows.py @@ -103,11 +103,19 @@ def read_catalog_rows( ) -> EconomyCatalogRows: """Read the catalog version, model, region and dataset a request names. - With ``local_area_dataset_name``, the dataset is the catalog version's - local-area dataset, which must have that name. Raise - UnknownCatalogVersionError, UnknownRegionError, UnknownDatasetError or - LocalAreaDatasetMismatchError. + The dataset is the region's default, or the one ``request`` names (a + re-run's stored dataset), or, with ``local_area_dataset_name``, the + catalog version's local-area dataset, which must have that name (a + report created with ``data_source``). Raise ValueError, before any read, + when both name a dataset; otherwise UnknownCatalogVersionError, + UnknownRegionError, UnknownDatasetError or LocalAreaDatasetMismatchError. """ + if local_area_dataset_name is not None and request.dataset_name is not None: + msg = ( + "a catalog read takes either a dataset name or the local-area " + "dataset, not both" + ) + raise ValueError(msg) country = request.country catalog_version_id = read_catalog_version_id( connection, diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index f7738754a..06dfd0610 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -140,13 +140,16 @@ record's ID, its run's ID and status, and, for a report, each side's simulation and run and whether it was reused. A request is refused before anything is written: with 400 and a `code` when -a row it names is missing (`unknown_region`, `unknown_dataset` and -`unknown_dynamic` name the caller's own choice; `unknown_catalog_version`, -`unknown_policy`, `no_economy_worker`, `dataset_not_in_bundle` and -`missing_reference` are the service's state, such as a catalog version -missing while a release deploys), and with 422 and a `code` when a policy or -dynamic sets parameters the catalog version lacks (`missing_parameters`) or -both set one (`overlapping_parameters`). The routes answer 503 with +a row it names is missing (`unknown_region` and `unknown_dynamic` name the +caller's own choice, and `unknown_dataset` its region's dataset; +`unknown_catalog_version`, `unknown_policy`, `no_economy_worker`, +`dataset_not_in_bundle` and `missing_reference` are the service's state, +such as a catalog version missing while a release deploys, and so are the +two local-area codes under "Local areas"), and with 422 and a `code` when a +policy or dynamic sets parameters the catalog version lacks +(`missing_parameters`), both set one (`overlapping_parameters`), or the +release has no local-area dataset for `data_source` +(`no_local_area_dataset`). The routes answer 503 with `Retry-After` when the manifest or the database can't be read. When Modal refuses the call, or doesn't confirm it within ten seconds, the run (and a report run's new simulation runs) is failed at once and the 503 diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_routes.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_routes.py index 80a46798f..42582aec4 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_routes.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_routes.py @@ -120,12 +120,14 @@ _REFUSED = { "description": ( "A row the request names, or a function it needs, is missing; nothing " - "was written. unknown_region, unknown_dataset and unknown_dynamic name " - "the caller's own region, dataset or dynamic; a household report's " - "unknown_household and no_household_function name its household and " - "the default worker's household function; any other code is the " - "service's state, such as a catalog version missing while a release " - "deploys" + "was written. unknown_region and unknown_dynamic name the caller's own " + "region or dynamic, and unknown_dataset its region's dataset (a " + "request names none); a household report's unknown_household and " + "no_household_function name its household and the default worker's " + "household function; any other code is the service's state, such as " + "a catalog version missing while a release deploys, or " + "local_areas_unsupported and local_area_dataset_mismatch for a report " + "on the local-area dataset" ), **ERROR_ANSWER, } @@ -135,7 +137,8 @@ "cannot be calculated; nothing was written. Stored values that cannot " "be calculated carry a code: missing_parameters, " "overlapping_parameters, or household_not_calculable for a household " - "report's household" + "report's household; no_local_area_dataset refuses data_source on a " + "release with no local-area dataset" ), "model": EconomyRequestUnprocessable, } From b14ce85379956ea7b88738ee598d3af18811df88 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:11:20 +0400 Subject: [PATCH 17/18] Fix review round 2's findings for data_source Review round 2 found no bugs. The /reports 400 description and the entry README now tell the two local-area codes apart from missing rows; read_report_inputs and the persistence README say a request naming two datasets raises ValueError; the re-run test uses a worker declaring no local-area runs, since a re-run never reads the declaration; and the catalog read test builds its request with replace and a UK dataset name. Co-Authored-By: Claude Opus 5.5 --- .../README.md | 3 ++- .../economy_run_store.py | 10 +++++----- .../tests/test_economy_run_store.py | 2 +- projects/policyengine-simulation-entry/README.md | 6 ++++-- .../economy_routes.py | 16 +++++++++------- .../tests/test_local_area_submissions.py | 8 ++++++-- 6 files changed, 27 insertions(+), 18 deletions(-) diff --git a/libs/policyengine-simulation-persistence/README.md b/libs/policyengine-simulation-persistence/README.md index d567019e3..6e565dbe2 100644 --- a/libs/policyengine-simulation-persistence/README.md +++ b/libs/policyengine-simulation-persistence/README.md @@ -125,7 +125,8 @@ reads each take their own. The catalog rows come from region's default, a re-run's stored dataset by name (`EconomyRequest`'s `dataset_name`), or, for a report created with `data_source` (`read_report_inputs`'s `local_area_dataset_name`), the catalog version's -local-area dataset, never two of these at once. A missing region or dataset +local-area dataset; a request naming two of them is refused with +`ValueError` before any read. A missing region or dataset raises `UnknownRegionError` or `UnknownDatasetError`, a local-area dataset the catalog doesn't give both area types raises `LocalAreaDatasetMismatchError`, and a report side's refused policy or diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_store.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_store.py index b2d243738..c782bfe90 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_store.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_store.py @@ -270,11 +270,11 @@ def read_report_inputs( ``local_area_dataset_name``, the dataset the default worker calculates local-area reports on, the report is read on the catalog version's local-area dataset (``read_local_area_dataset``) in place - of the region's default. Raise UnknownCatalogVersionError, - UnknownRegionError or UnknownDatasetError, ReportSideError naming the - side whose policy or dynamic is refused, or - LocalAreaDatasetMismatchError when the catalog version doesn't give - both area types that dataset. + of the region's default. Raise ValueError when ``request`` also names + a dataset; otherwise UnknownCatalogVersionError, UnknownRegionError + or UnknownDatasetError, ReportSideError naming the side whose policy + or dynamic is refused, or LocalAreaDatasetMismatchError when the + catalog version doesn't give both area types that dataset. """ with self._transaction() as connection: catalog = read_catalog_rows( diff --git a/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py b/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py index bc9725255..dfec193ed 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py @@ -633,7 +633,7 @@ def refuse(*_, refusal=refusal): def test_a_request_naming_a_dataset_and_the_local_area_dataset_is_refused() -> None: """A re-run names its stored dataset and a create the local-area one, never both.""" - named = EconomyRequest(**{**vars(UK_REQUEST), "dataset_name": "acs_local_2024"}) + named = replace(UK_REQUEST, dataset_name="microcosm_uk_2024_25") with pytest.raises(ValueError, match="either a dataset name or"): read_catalog_rows( diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index 06dfd0610..e9fd583db 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -144,8 +144,10 @@ a row it names is missing (`unknown_region` and `unknown_dynamic` name the caller's own choice, and `unknown_dataset` its region's dataset; `unknown_catalog_version`, `unknown_policy`, `no_economy_worker`, `dataset_not_in_bundle` and `missing_reference` are the service's state, -such as a catalog version missing while a release deploys, and so are the -two local-area codes under "Local areas"), and with 422 and a `code` when a +such as a catalog version missing while a release deploys), or, for a report +on the local-area dataset, when the default worker or the catalog can't +serve it (`local_areas_unsupported` and `local_area_dataset_mismatch`, also +the service's state; see "Local areas"); and with 422 and a `code` when a policy or dynamic sets parameters the catalog version lacks (`missing_parameters`), both set one (`overlapping_parameters`), or the release has no local-area dataset for `data_source` diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_routes.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_routes.py index 42582aec4..688654fd1 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_routes.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_routes.py @@ -119,15 +119,17 @@ } _REFUSED = { "description": ( - "A row the request names, or a function it needs, is missing; nothing " - "was written. unknown_region and unknown_dynamic name the caller's own " - "region or dynamic, and unknown_dataset its region's dataset (a " - "request names none); a household report's unknown_household and " + "A row the request names, or a function it needs, is missing, or the " + "catalog disagrees with the default worker; nothing was written. " + "unknown_region and unknown_dynamic name the caller's own region or " + "dynamic, and unknown_dataset its region's dataset (a request names " + "none); a household report's unknown_household and " "no_household_function name its household and the default worker's " "household function; any other code is the service's state, such as " - "a catalog version missing while a release deploys, or " - "local_areas_unsupported and local_area_dataset_mismatch for a report " - "on the local-area dataset" + "a catalog version missing while a release deploys, or, for a report " + "on the local-area dataset, local_areas_unsupported (the default " + "worker runs no such reports) and local_area_dataset_mismatch (the " + "catalog's area regions use another dataset)" ), **ERROR_ANSWER, } diff --git a/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py b/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py index 242f966a4..d6ee63fab 100644 --- a/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py +++ b/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py @@ -202,7 +202,11 @@ def test_a_catalog_whose_area_regions_use_another_dataset_is_refused() -> None: def test_a_report_on_the_local_area_dataset_is_rerun_on_it() -> None: - """A re-run reads the stored report's dataset by name, and takes no data_source.""" + """A re-run reads the stored report's dataset by name, and takes no data_source. + + It never reads the worker's local-area declaration, so a worker declaring + none still re-runs the report on its dataset. + """ stored = replace( STORED_REPORT, country="uk", @@ -218,7 +222,7 @@ def test_a_report_on_the_local_area_dataset_is_rerun_on_it() -> None: asyncio.run( rerun_service( - store, workers=_workers_declaring(ROUTED_LOCAL_AREAS), caller=caller + store, workers=_workers_declaring(None), caller=caller ).rerun_report( REPORT_ID, ReportRerunRequest(), From a25e0647946a179116413b0716e5f7d443b3b14f Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:16:22 +0400 Subject: [PATCH 18/18] Describe the local-area 400 codes' conditions exactly Review round 3 found no bugs; its one finding: the /reports 400 description now says local_areas_unsupported covers a declaration of another input version too, and local_area_dataset_mismatch a catalog version whose area regions don't share the declared dataset (or lack a type). Co-Authored-By: Claude Opus 5.5 --- .../src/policyengine_simulation_entry/economy_routes.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_routes.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_routes.py index 688654fd1..d1b1ae214 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_routes.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_routes.py @@ -128,8 +128,9 @@ "household function; any other code is the service's state, such as " "a catalog version missing while a release deploys, or, for a report " "on the local-area dataset, local_areas_unsupported (the default " - "worker runs no such reports) and local_area_dataset_mismatch (the " - "catalog's area regions use another dataset)" + "worker declares no local-area report runs of this service's input " + "version) and local_area_dataset_mismatch (the catalog version doesn't " + "give its constituency and local-authority regions that one dataset)" ), **ERROR_ANSWER, }