From 60fa681ab1eeee79a604b141814ee7f662ddf346 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 18:50:42 +0400 Subject: [PATCH 01/44] Test the local-area output profile and a UK bundle's local-area dataset (failing) The coordinator must plan a UK local-area report run's simulations with only the geographic aggregate and no cliff impacts, and the UK worker must recognise the dataset a bundle gives its constituency and local-authority regions. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_stage12_execution.py | 39 +++++++ .../tests/test_stage12_local_area_dataset.py | 103 ++++++++++++++++++ 2 files changed, 142 insertions(+) create mode 100644 libs/policyengine-simulation-contract/tests/test_stage12_local_area_dataset.py diff --git a/libs/policyengine-simulation-contract/tests/test_stage12_execution.py b/libs/policyengine-simulation-contract/tests/test_stage12_execution.py index 6ac885892..7a16bd1f7 100644 --- a/libs/policyengine-simulation-contract/tests/test_stage12_execution.py +++ b/libs/policyengine-simulation-contract/tests/test_stage12_execution.py @@ -13,6 +13,7 @@ build_spm_provenance, ) from policyengine_simulation_contract.stage12_execution import ( + LOCAL_AREA_AGGREGATES, SIMULATION_PARQUET_PAYLOAD_CONTRACT, AggregateReportArtifactPayload, BundleProvenance, @@ -267,3 +268,41 @@ def test_aggregate_artifact_accepts_only_canonical_spm_provenance() -> None: bundle=artifact.bundle, result={"spm_provenance": mismatched}, ) + + +def _requirements( + aggregates: tuple[ReportAggregate, ...], *, include_cliff_impacts: bool = False +) -> ReportOutputRequirements: + return ReportOutputRequirements( + aggregates=aggregates, + include_cliff_impacts=include_cliff_impacts, + labor_supply_response_active=False, + ) + + +def test_output_requirements_accept_the_local_area_profile() -> None: + requirements = _requirements(LOCAL_AREA_AGGREGATES) + + assert requirements.aggregates == (ReportAggregate.GEOGRAPHIC,) + + +def test_the_local_area_profile_calculates_no_cliff_impacts() -> None: + with pytest.raises(ValidationError, match="calculates no cliff impacts"): + _requirements(LOCAL_AREA_AGGREGATES, include_cliff_impacts=True) + + +@pytest.mark.parametrize( + "aggregates", + [ + (ReportAggregate.BUDGET,), + (ReportAggregate.GEOGRAPHIC, ReportAggregate.BUDGET), + tuple(reversed(ReportAggregate)), + ], +) +def test_output_requirements_refuse_any_other_partial_profile( + aggregates: tuple[ReportAggregate, ...], +) -> None: + with pytest.raises( + ValidationError, match="complete aggregate profile or the local-area profile" + ): + _requirements(aggregates) diff --git a/libs/policyengine-simulation-contract/tests/test_stage12_local_area_dataset.py b/libs/policyengine-simulation-contract/tests/test_stage12_local_area_dataset.py new file mode 100644 index 000000000..7b0f15ffc --- /dev/null +++ b/libs/policyengine-simulation-contract/tests/test_stage12_local_area_dataset.py @@ -0,0 +1,103 @@ +"""Tests for the dataset a UK bundle gives constituency and local-authority regions.""" + +from __future__ import annotations + +from policyengine_simulation_contract.stage12_bundle import ( + Stage12CountryBundle, + Stage12Dataset, + Stage12RegionDataset, +) + +NATIONAL_DATASET = "microcosm_uk_2024_25" +LOCAL_AREA_DATASET = "microcosm_uk_2024_25_dense" + + +def _dataset(identity: str) -> Stage12Dataset: + return Stage12Dataset( + identity=identity, + uri=f"hf://policyengine/data/{identity}.h5@{identity}-revision", + artifact_revision=f"{identity}-revision", + sha256="a" * 64, + repo_type="model", + ) + + +def _uk_bundle( + region_datasets: dict[str, str | None] | None, +) -> Stage12CountryBundle: + return Stage12CountryBundle( + country="uk", + country_package_name="policyengine-uk", + country_package_version="2.174.1", + country_package_requirement="policyengine-uk==2.174.1", + data_package_name="microcosm-uk-data", + data_package_version="0.1.0", + data_release_version="release", + data_artifact_revision=f"{NATIONAL_DATASET}-revision", + default_dataset=NATIONAL_DATASET, + default_dataset_uri=_dataset(NATIONAL_DATASET).uri, + datasets=(_dataset(NATIONAL_DATASET), _dataset(LOCAL_AREA_DATASET)), + region_datasets=( + None + if region_datasets is None + else tuple( + Stage12RegionDataset(region_type=region_type, dataset=dataset) + for region_type, dataset in region_datasets.items() + ) + ), + ) + + +def test_both_area_region_types_on_their_own_dataset_name_the_local_area_dataset() -> ( + None +): + bundle = _uk_bundle( + { + "national": NATIONAL_DATASET, + "country": NATIONAL_DATASET, + "constituency": LOCAL_AREA_DATASET, + "local_authority": LOCAL_AREA_DATASET, + } + ) + + assert bundle.local_area_dataset() == LOCAL_AREA_DATASET + + +def test_area_regions_on_the_national_dataset_have_no_local_area_dataset() -> None: + bundle = _uk_bundle( + { + "national": NATIONAL_DATASET, + "constituency": NATIONAL_DATASET, + "local_authority": NATIONAL_DATASET, + } + ) + + assert bundle.local_area_dataset() is None + + +def test_area_regions_on_two_datasets_have_no_local_area_dataset() -> None: + bundle = _uk_bundle( + { + "national": NATIONAL_DATASET, + "constituency": LOCAL_AREA_DATASET, + "local_authority": "microcosm_uk_2024_25_authorities", + } + ) + + assert bundle.local_area_dataset() is None + + +def test_an_area_region_type_without_one_dataset_has_no_local_area_dataset() -> None: + bundle = _uk_bundle( + { + "national": NATIONAL_DATASET, + "constituency": LOCAL_AREA_DATASET, + "local_authority": None, + } + ) + + assert bundle.local_area_dataset() is None + + +def test_a_bundle_published_before_region_datasets_has_no_local_area_dataset() -> None: + assert _uk_bundle(None).local_area_dataset() is None From bd6dc782a826b31bb7a605744077433b2c320bd1 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 18:52:01 +0400 Subject: [PATCH 02/44] Accept the local-area output profile, and name a UK bundle's local-area dataset ReportOutputRequirements accepts LOCAL_AREA_AGGREGATES, the geographic aggregate alone with no cliff impacts, beside the complete profile. Stage12CountryBundle.local_area_dataset names the one dataset both UK area region types load when it differs from the national one. Co-Authored-By: Claude Opus 5.5 --- .../stage12_bundle.py | 23 +++++++++++++ .../stage12_execution/__init__.py | 2 ++ .../stage12_execution/report_inputs.py | 33 ++++++++++++++++--- 3 files changed, 53 insertions(+), 5 deletions(-) diff --git a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_bundle.py b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_bundle.py index 2270497e4..9754a9c44 100644 --- a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_bundle.py +++ b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_bundle.py @@ -10,6 +10,8 @@ Sha256Digest = Annotated[str, Field(pattern=r"^[0-9a-f]{64}$")] CountryId = Literal["us", "uk"] SUPPORTED_COUNTRIES: tuple[CountryId, ...] = ("us", "uk") +# The UK region types whose results a local-area report run calculates. +UK_AREA_REGION_TYPES = ("constituency", "local_authority") # A bare two-letter US region is a state code, such as "ut". _US_STATE_CODE_LENGTH = 2 @@ -100,6 +102,27 @@ def dataset_for_region(self, region: str | None) -> str | None: """Return the dataset identity a requested region code loads, or None.""" return self.dataset_for_region_type(region_type_of(self.country, region)) + def local_area_dataset(self) -> str | None: + """Return the dataset a UK local-area report run calculates on, or None. + + It is the one dataset both UK area region types (constituencies and + local authorities) load, when that is not the dataset national + regions load. None means a national run on this bundle calculates + the area results itself: the area region types load the national + dataset, name two datasets or none, or the bundle names no region + datasets. + """ + datasets = { + self.dataset_for_region_type(region_type) + for region_type in UK_AREA_REGION_TYPES + } + if len(datasets) != 1: + return None + dataset = datasets.pop() + if dataset is None or dataset == self.dataset_for_region_type("national"): + return None + return dataset + class Stage12BundleManifest(StrictBundleModel): """Stage 12's normalized subset of a PolicyEngine.py bundle.""" diff --git a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/__init__.py b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/__init__.py index 982db91b3..03aa8cb5b 100644 --- a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/__init__.py +++ b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/__init__.py @@ -48,6 +48,7 @@ Stage12InvocationContext, ) from policyengine_simulation_contract.stage12_execution.report_inputs import ( + LOCAL_AREA_AGGREGATES, EntityOutputPlan, PlannedSimulationExecutionInput, ReportAggregate, @@ -70,6 +71,7 @@ ) __all__ = [ + "LOCAL_AREA_AGGREGATES", "MAX_COMPARISON_RUN_ARTIFACT_RETENTION", "SIMULATION_PARQUET_PAYLOAD_CONTRACT", "AggregateReportArtifactDescriptor", diff --git a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/report_inputs.py b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/report_inputs.py index 8d4a4ea42..145a0184a 100644 --- a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/report_inputs.py +++ b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/report_inputs.py @@ -35,8 +35,18 @@ class ReportAggregate(StrEnum): PROGRAM_STATISTICS = "program_statistics" +# A UK local-area report run's one aggregate: the constituency and +# local-authority impacts, with the codes disclosure control withholds. +LOCAL_AREA_AGGREGATES: tuple[ReportAggregate, ...] = (ReportAggregate.GEOGRAPHIC,) + + class ReportOutputRequirements(StrictContractModel): - """Report features that determine which simulation columns must exist.""" + """Report features that determine which simulation columns must exist. + + ``aggregates`` is either the complete profile, every ``ReportAggregate`` + in declaration order, or the local-area profile + (``LOCAL_AREA_AGGREGATES``), which calculates no cliff impacts. + """ schema_version: Literal[1] = 1 aggregates: Annotated[tuple[ReportAggregate, ...], Field(min_length=1)] @@ -45,19 +55,32 @@ class ReportOutputRequirements(StrictContractModel): @field_validator("aggregates") @classmethod - def require_complete_aggregate_profile( + def require_a_supported_aggregate_profile( cls, value: tuple[ReportAggregate, ...], ) -> tuple[ReportAggregate, ...]: - """Require every ``ReportAggregate``, once each and in declaration order.""" + """Require the complete profile or the local-area profile, once each.""" if len(value) != len(set(value)): msg = "report output aggregates must be unique" raise ValueError(msg) - if value != tuple(ReportAggregate): - msg = "Stage 12 currently requires the complete aggregate profile" + if value not in (tuple(ReportAggregate), LOCAL_AREA_AGGREGATES): + msg = ( + "Stage 12 requires the complete aggregate profile or the " + "local-area profile" + ) raise ValueError(msg) return value + @model_validator(mode="after") + def require_no_cliffs_in_the_local_area_profile( + self, + ) -> ReportOutputRequirements: + """Refuse cliff impacts with the local-area profile.""" + if self.aggregates == LOCAL_AREA_AGGREGATES and self.include_cliff_impacts: + msg = "the local-area profile calculates no cliff impacts" + raise ValueError(msg) + return self + class EntityOutputPlan(StrictContractModel): """Required materialized columns for one country-model entity.""" From 9ff2fd8cd7a7579cf417cb12c149cee169115d92 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 18:54:11 +0400 Subject: [PATCH 03/44] Test the output plan of a UK local-area report run's simulations (failing) The plan names only the household columns disclosure control reads, the same for every policy pair, so a local-area baseline run is reusable by any report with that baseline. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_stage12_output_planning.py | 89 +++++++++++++++++++ 1 file changed, 89 insertions(+) diff --git a/projects/policyengine-simulation-executor/tests/test_stage12_output_planning.py b/projects/policyengine-simulation-executor/tests/test_stage12_output_planning.py index 2717f67a1..ff79b5ea7 100644 --- a/projects/policyengine-simulation-executor/tests/test_stage12_output_planning.py +++ b/projects/policyengine-simulation-executor/tests/test_stage12_output_planning.py @@ -10,6 +10,7 @@ import pytest from policyengine.core import Simulation from policyengine_simulation_contract.stage12_execution import ( + LOCAL_AREA_AGGREGATES, BundleProvenance, DatasetArtifactMediaType, DatasetArtifactReference, @@ -24,6 +25,7 @@ ) from policyengine_simulation_executor.stage12_runtime.output_planning import ( apply_output_plan, + resolve_local_area_output_plan, resolve_report_output_plan, resolve_simulation_output_plan, validate_output_frames, @@ -397,3 +399,90 @@ def test_a_simulation_planned_alone_gets_its_self_comparisons_plan( assert plan == resolve_report_output_plan(_self_comparison(standalone)) assert plan.requirements.include_cliff_impacts is bool(options) + + +# Household columns a UK local-area report run's simulations must write: the +# identifier, the income whose change disclosure control measures, the +# weights, and the area columns copied from the local-area dataset. +LOCAL_AREA_HOUSEHOLD_COLUMNS = { + "household_id", + "household_net_income", + "household_weight", + "constituency_code_oa", + "la_code_oa", + "region_code_oa", + "source_household_id", +} +UK_INCOME_ELASTICITY = "gov.simulation.labour_supply_responses.income_elasticity" + + +def _local_area_report( + *, region: str = "uk", reform: dict[str, JsonValue] | None = None +) -> ReportExecutionInput: + return _report("uk", region=region, reform=reform, aggregates=LOCAL_AREA_AGGREGATES) + + +@pytest.mark.parametrize("region", ["uk", "country/wales"]) +def test_a_local_area_plan_writes_only_the_household_columns_disclosure_reads( + region: str, +) -> None: + from policyengine_simulation_executor import uk_local_authority_metadata + + plan = resolve_local_area_output_plan(_local_area_report(region=region)) + + assert plan.country == "uk" + assert plan.requirements.aggregates == LOCAL_AREA_AGGREGATES + assert plan.requirements.include_cliff_impacts is False + assert [entity.entity for entity in plan.entities] == ["household"] + household = plan.entities[0] + assert set(household.materialized_variables) == LOCAL_AREA_HOUSEHOLD_COLUMNS + assert household.additional_variables == () + assert household.dataset_variables == ( + uk_local_authority_metadata.UK_AREA_DATASET_COLUMNS + ) + + +def test_a_local_area_plan_has_the_same_columns_for_every_policy_pair() -> None: + current_law = resolve_local_area_output_plan(_local_area_report()) + with_responses = resolve_local_area_output_plan( + _local_area_report(reform={UK_INCOME_ELASTICITY: 0.1}) + ) + + assert with_responses.requirements.labor_supply_response_active is True + assert current_law.requirements.labor_supply_response_active is False + assert with_responses.entities == current_law.entities + + +def test_a_local_area_plan_is_refused_for_a_us_report() -> None: + with pytest.raises(ValueError, match="UK"): + resolve_local_area_output_plan(_report("us", aggregates=LOCAL_AREA_AGGREGATES)) + + +def test_a_local_area_plan_is_refused_with_cliff_impacts() -> None: + report = _report( + "uk", include_cliffs=True, aggregates=LOCAL_AREA_AGGREGATES, region="uk" + ) + + with pytest.raises(ValueError, match="calculates no cliff impacts"): + resolve_local_area_output_plan(report) + + +def test_a_uk_simulation_satisfies_the_local_area_plan_without_extra_variables() -> ( + None +): + from policyengine.tax_benefit_models import uk + + plan = resolve_local_area_output_plan(_local_area_report()) + simulation = Simulation.model_construct( + policy={}, + dynamic=None, + dataset=None, + scoping_strategy=None, + extra_variables={}, + tax_benefit_model_version=uk.model, + output_dataset=None, + ) + + apply_output_plan(simulation, plan) + + assert simulation.extra_variables == {"household": []} From 54248714ce3cf668b2aa2521a90f2a9faadf3e29 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 18:55:31 +0400 Subject: [PATCH 04/44] Plan a UK local-area report run's simulations with only the area columns resolve_local_area_output_plan gives both simulations one household plan: the identifier, net income and weights, which the UK model writes by default, and the area columns copied from the local-area dataset whatever the region. It adds no cliff, labour-supply or budget variables. Co-Authored-By: Claude Opus 5.5 --- .../stage12_runtime/output_planning.py | 60 +++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/output_planning.py b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/output_planning.py index f619053fe..2348d358d 100644 --- a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/output_planning.py +++ b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/output_planning.py @@ -13,6 +13,7 @@ labor_supply_response_is_active, ) from policyengine_simulation_contract.stage12_execution import ( + LOCAL_AREA_AGGREGATES, EntityOutputPlan, PlannedSimulationExecutionInput, ReportAggregate, @@ -37,6 +38,15 @@ UK_GEOGRAPHIC_DATASET_VARIABLES: dict[str, tuple[str, ...]] = { "household": UK_AREA_DATASET_COLUMNS, } +# Household columns a UK local-area report run's simulations calculate: the +# identifier both sides are matched on, the income whose change disclosure +# control measures, and the weights it estimates with. The UK model writes +# all three by default. +LOCAL_AREA_CALCULATED_HOUSEHOLD_VARIABLES = ( + "household_id", + "household_net_income", + "household_weight", +) class OutputVariableModel(Protocol): @@ -172,6 +182,56 @@ def resolve_report_output_plan( ) +def resolve_local_area_output_plan( + report: ReportExecutionInput, + *, + stage_scope: StageScope = _unmonitored_stage_scope, +) -> Stage12OutputPlan: + """Resolve the output schema of a UK local-area report run's two simulations. + + The run calculates only the constituency and local-authority impacts, so + each simulation writes the household columns disclosure control reads: + ``LOCAL_AREA_CALCULATED_HOUSEHOLD_VARIABLES``, and the area columns + (``UK_AREA_DATASET_COLUMNS``) copied from the local-area dataset whatever + the region. No cliff, labour-supply or budget variables are added, so the + columns are the same for every policy pair, and a local-area simulation + run's output serves any report with that simulation. + ``labor_supply_response_active`` still records whether the policies + activate labour-supply responses, which the reform's net income includes + either way. Raises ``ValueError`` for a report outside the UK, or one + with cliff impacts. + """ + country = report.baseline.geography.country + if country != "uk": + msg = f"a local-area report run is a UK report, not a {country!r} one" + raise ValueError(msg) + stage_attributes = {"country": country} + with stage_scope(Stage.STAGE12_COUNTRY_MODEL_LOAD, stage_attributes): + model = _country_model(country) + with stage_scope(Stage.STAGE12_OUTPUT_CONFIGURATION, stage_attributes): + requirements = ReportOutputRequirements( + aggregates=LOCAL_AREA_AGGREGATES, + include_cliff_impacts=_include_cliff_impacts(report.baseline), + labor_supply_response_active=labor_supply_response_is_active( + _planning_simulation(report.baseline, model=model), + _planning_simulation(report.reform, model=model), + country_code=country, + ), + ) + household = EntityOutputPlan( + entity="household", + materialized_variables=tuple( + sorted( + {*LOCAL_AREA_CALCULATED_HOUSEHOLD_VARIABLES, *UK_AREA_DATASET_COLUMNS} + ) + ), + dataset_variables=UK_AREA_DATASET_COLUMNS, + ) + return Stage12OutputPlan( + country=country, requirements=requirements, entities=(household,) + ) + + def resolve_simulation_output_plan( simulation: SimulationExecutionInput, *, From 853639aaddd46e24c3d0d411a56e0f02d2cb4d15 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 18:58:49 +0400 Subject: [PATCH 05/44] Test a UK-wide or nation simulation on the local-area dataset (failing) The UK worker refuses a UK-wide or nation simulation whose provenance names the dataset the bundle gives constituency and local-authority regions, which a local-area report run's simulations calculate on. Co-Authored-By: Claude Opus 5.5 --- .../test_stage12_local_area_dataset_load.py | 359 ++++++++++++++++++ 1 file changed, 359 insertions(+) create mode 100644 projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py diff --git a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py new file mode 100644 index 000000000..a636caf78 --- /dev/null +++ b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py @@ -0,0 +1,359 @@ +"""Tests for a UK-wide or nation simulation calculated on the local-area dataset.""" + +from __future__ import annotations + +from contextlib import nullcontext +from dataclasses import dataclass, field +from types import SimpleNamespace +from typing import Any + +import pandas as pd +import pytest +from policyengine_simulation_contract.stage12_bundle import ( + ResolvedStage12Bundle, + Stage12BundleManifest, + Stage12CountryBundle, + Stage12Dataset, + Stage12RegionDataset, +) +from policyengine_simulation_contract.stage12_execution import ( + LOCAL_AREA_AGGREGATES, + BundleProvenance, + DatasetArtifactMediaType, + DatasetArtifactReference, + DatasetPopulationInput, + DatasetProvenance, + EntityOutputPlan, + GeographySelection, + PlannedSimulationExecutionInput, + ReportOutputRequirements, + SimulationRole, + Stage12OutputPlan, +) +from policyengine_simulation_contract.uk_geography import ( + UKLocalAuthorityBoundaryVersion, +) +from policyengine_simulation_executor.simulation_runtime import ( + DatasetSelection, + RegionResolution, +) +from policyengine_simulation_executor.stage12_runtime import ( + local_area_datasets, +) +from policyengine_simulation_executor.stage12_runtime import simulation as worker +from stage12_runtime_support import BASELINE_ID, EVALUATION_ID + +NATIONAL_DATASET = "microcosm_uk_2024_25" +LOCAL_AREA_DATASET = "microcosm_uk_2024_25_dense" +POLICYENGINE_VERSION = "6.17.1" +COUNTRY_PACKAGE_VERSION = "2.174.1" +BUNDLE_MANIFEST_SHA256 = "b" * 64 +# Wales as .py's region registry resolves it on the national dataset: the +# region's own dataset, and the filter that scopes a simulation to it. +WALES = RegionResolution( + code="country/wales", + dataset_reference=NATIONAL_DATASET, + scoping_strategy="households in Wales", +) + + +def _dataset(identity: str) -> Stage12Dataset: + return Stage12Dataset( + identity=identity, + uri=f"hf://policyengine/microcosm-uk/{identity}.h5@{identity}-revision", + artifact_revision=f"{identity}-revision", + sha256="a" * 64, + repo_type="model", + ) + + +def _installed_uk_bundle( + area_dataset: str = LOCAL_AREA_DATASET, +) -> ResolvedStage12Bundle: + """Return an installed bundle whose UK area regions load ``area_dataset``.""" + national = _dataset(NATIONAL_DATASET) + region_datasets = { + "national": NATIONAL_DATASET, + "country": NATIONAL_DATASET, + "constituency": area_dataset, + "local_authority": area_dataset, + } + return ResolvedStage12Bundle( + bundle=Stage12BundleManifest( + policyengine_version=POLICYENGINE_VERSION, + policyengine_requirement=f"policyengine=={POLICYENGINE_VERSION}", + core_package_version="3.33.3", + core_package_requirement="policyengine-core==3.33.3", + countries=( + Stage12CountryBundle( + country="uk", + country_package_name="policyengine-uk", + country_package_version=COUNTRY_PACKAGE_VERSION, + country_package_requirement=( + f"policyengine-uk=={COUNTRY_PACKAGE_VERSION}" + ), + data_package_name="microcosm-uk", + data_package_version="0.1.0", + data_release_version="release", + data_artifact_revision=national.artifact_revision, + default_dataset=NATIONAL_DATASET, + default_dataset_uri=national.uri, + datasets=(national, _dataset(LOCAL_AREA_DATASET)), + region_datasets=tuple( + Stage12RegionDataset(region_type=region_type, dataset=dataset) + for region_type, dataset in region_datasets.items() + ), + ), + ), + ), + bundle_manifest_sha256=BUNDLE_MANIFEST_SHA256, + ) + + +def _provenance(identity: str) -> BundleProvenance: + dataset = _dataset(identity) + return BundleProvenance( + policyengine_version=POLICYENGINE_VERSION, + country_package_name="policyengine-uk", + country_package_version=COUNTRY_PACKAGE_VERSION, + dataset=DatasetProvenance( + identity=identity, + uri=dataset.uri, + artifact_revision=dataset.artifact_revision, + data_package_name="microcosm-uk", + data_package_version="0.1.0", + ), + bundle_manifest_sha256=BUNDLE_MANIFEST_SHA256, + ) + + +def _uk_simulation( + region: str, identity: str, *, provenance: BundleProvenance | None = None +) -> PlannedSimulationExecutionInput: + bundle = provenance or _provenance(identity) + return PlannedSimulationExecutionInput( + evaluation_id=EVALUATION_ID, + simulation_execution_id=BASELINE_ID, + role=SimulationRole.BASELINE, + policy={}, + population=DatasetPopulationInput( + artifact=DatasetArtifactReference( + uri=bundle.dataset.uri, + media_type=DatasetArtifactMediaType.HDF5, + content_sha256="a" * 64, + ) + ), + year=2026, + geography=GeographySelection(country="uk", region=region), + bundle=bundle, + output_plan=Stage12OutputPlan( + country="uk", + requirements=ReportOutputRequirements( + aggregates=LOCAL_AREA_AGGREGATES, + include_cliff_impacts=False, + labor_supply_response_active=False, + ), + entities=( + EntityOutputPlan( + entity="household", + materialized_variables=("household_id", "household_net_income"), + ), + ), + ), + ) + + +@pytest.mark.parametrize("region", ["uk", "country/wales"]) +def test_the_installed_bundle_accepts_the_local_area_dataset_for_uk_and_a_nation( + monkeypatch, region: str +) -> None: + monkeypatch.setattr(worker, "load_stage12_bundle", _installed_uk_bundle) + + worker._require_installed_bundle(_uk_simulation(region, LOCAL_AREA_DATASET)) + + +def test_the_installed_bundle_refuses_a_dataset_area_regions_do_not_load_on_their_own( + monkeypatch, +) -> None: + monkeypatch.setattr( + worker, + "load_stage12_bundle", + lambda: _installed_uk_bundle(area_dataset=NATIONAL_DATASET), + ) + + with pytest.raises(RuntimeError, match="differs from the installed bundle"): + worker._require_installed_bundle(_uk_simulation("uk", LOCAL_AREA_DATASET)) + + +def test_the_installed_bundle_refuses_the_local_area_dataset_at_another_revision( + monkeypatch, +) -> None: + monkeypatch.setattr(worker, "load_stage12_bundle", _installed_uk_bundle) + provenance = _provenance(LOCAL_AREA_DATASET) + provenance = provenance.model_copy( + update={ + "dataset": provenance.dataset.model_copy( + update={"artifact_revision": "an-older-revision"} + ) + } + ) + + with pytest.raises(RuntimeError, match="differs from the installed bundle"): + worker._require_installed_bundle( + _uk_simulation("uk", LOCAL_AREA_DATASET, provenance=provenance) + ) + + +class _StoppedBeforeSimulatingError(Exception): + """Raised by a stubbed simulation build once the dataset has loaded.""" + + +@dataclass +class _Calculation: + """What a calculation stopped before simulating did.""" + + selected_by: list[RegionResolution] = field(default_factory=list) + built_with: list[Any] = field(default_factory=list) + detected_on: list[str] = field(default_factory=list) + + +def _area_household() -> pd.DataFrame: + return pd.DataFrame( + { + "household_id": [1, 2], + "constituency_code_oa": ["W07000081", "W07000082"], + # Cumberland exists only in the LAD23 boundaries. + "la_code_oa": ["E06000063", "W06000015"], + "region_code_oa": ["W92000004", "W92000004"], + "source_household_id": [10, 11], + } + ) + + +def _run_until_built( + monkeypatch, + simulation: PlannedSimulationExecutionInput, + *, + household: pd.DataFrame, +) -> _Calculation: + """Run a UK calculation of Wales up to its simulation build.""" + from policyengine_simulation_executor import simulation_runtime + from policyengine_simulation_executor.stage12_cache import state_datasets + + calculation = _Calculation() + dataset = SimpleNamespace( + data=SimpleNamespace(entity_data={"household": household}) + ) + uris = { + item.identity: item.uri + for item in _installed_uk_bundle().bundle.countries[0].datasets + } + + def select(_params, *, region_resolution: RegionResolution) -> DatasetSelection: + calculation.selected_by.append(region_resolution) + name = region_resolution.dataset_reference or NATIONAL_DATASET + return DatasetSelection( + name=name, uri=uris[name], is_default=name == NATIONAL_DATASET + ) + + def detect_on_the_national_dataset(_country, _dataset, **kwargs): + calculation.detected_on.append(kwargs["dataset_name"]) + + def stop_before_simulating(_params, *, resolved, **_kwargs): + calculation.built_with.append(resolved) + raise _StoppedBeforeSimulatingError + + monkeypatch.setattr(worker, "_require_installed_bundle", lambda _: None) + monkeypatch.setattr( + local_area_datasets, "load_stage12_bundle", _installed_uk_bundle + ) + monkeypatch.setattr(simulation_runtime, "setup_gcp_credentials", nullcontext) + monkeypatch.setattr( + simulation_runtime, "_country_module", lambda _country: object() + ) + monkeypatch.setattr(simulation_runtime, "resolve_region", lambda **_: WALES) + monkeypatch.setattr(simulation_runtime, "_resolve_dataset_selection", select) + monkeypatch.setattr( + simulation_runtime, "_load_dataset", lambda *_args, **_kwargs: dataset + ) + monkeypatch.setattr( + state_datasets, "baked_state_data_folder", lambda **_kwargs: None + ) + monkeypatch.setattr( + worker, "detect_uk_run_dataset_metadata", detect_on_the_national_dataset + ) + monkeypatch.setattr(worker, "build_stage12_simulation", stop_before_simulating) + + with pytest.raises(_StoppedBeforeSimulatingError): + worker.calculate_simulation_frames(simulation) + return calculation + + +def test_a_local_area_run_loads_the_local_area_dataset_scoped_to_its_nation( + monkeypatch, +) -> None: + calculation = _run_until_built( + monkeypatch, + _uk_simulation("country/wales", LOCAL_AREA_DATASET), + household=_area_household(), + ) + + (selected_by,) = calculation.selected_by + assert selected_by.code == "country/wales" + assert selected_by.dataset_reference == LOCAL_AREA_DATASET + (built_with,) = calculation.built_with + assert built_with.dataset_selection.name == LOCAL_AREA_DATASET + # The simulation keeps Wales's own scoping on the local-area dataset. + assert built_with.region == WALES + # The area columns were checked on the local-area dataset as it loaded. + assert calculation.detected_on == [] + + +def test_a_national_run_of_a_nation_loads_the_dataset_its_region_names( + monkeypatch, +) -> None: + calculation = _run_until_built( + monkeypatch, + _uk_simulation("country/wales", NATIONAL_DATASET), + household=_area_household(), + ) + + assert calculation.selected_by == [WALES] + assert calculation.detected_on == [NATIONAL_DATASET] + + +def test_a_local_area_run_detects_the_authority_boundaries_of_its_dataset( + monkeypatch, +) -> None: + detected = [] + original = worker.detect_uk_area_dataset_metadata + + def record_detection(dataset, *, dataset_name): + metadata = original(dataset, dataset_name=dataset_name) + detected.append((dataset_name, metadata.boundary_version)) + return metadata + + monkeypatch.setattr(worker, "detect_uk_area_dataset_metadata", record_detection) + + _run_until_built( + monkeypatch, + _uk_simulation("uk", LOCAL_AREA_DATASET), + household=_area_household(), + ) + + assert detected == [(LOCAL_AREA_DATASET, UKLocalAuthorityBoundaryVersion.LAD23)] + + +@pytest.mark.parametrize( + "missing", + ["constituency_code_oa", "la_code_oa", "region_code_oa", "source_household_id"], +) +def test_a_local_area_dataset_without_an_area_column_fails_before_simulating( + monkeypatch, missing: str +) -> None: + with pytest.raises(ValueError, match=f"has no {missing} column"): + _run_until_built( + monkeypatch, + _uk_simulation("uk", LOCAL_AREA_DATASET), + household=_area_household().drop(columns=[missing]), + ) From ae77648ab41a471f19b4facc644cab04f1c21642 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 19:00:02 +0400 Subject: [PATCH 06/44] Calculate a UK-wide or nation simulation on the local-area dataset it names The UK worker accepts a UK or nation simulation whose provenance names the dataset the bundle gives constituency and local-authority regions, selects that dataset in place of the region's own, keeps the region's scoping, and checks every column the area outputs read as the dataset loads. It reuses only the runtime helpers Stage 12 already calls. Co-Authored-By: Claude Opus 5.5 --- .../stage12_runtime/local_area_datasets.py | 82 +++++++++++++++++++ .../stage12_runtime/simulation.py | 31 +++++-- 2 files changed, 105 insertions(+), 8 deletions(-) create mode 100644 projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/local_area_datasets.py diff --git a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/local_area_datasets.py b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/local_area_datasets.py new file mode 100644 index 000000000..18dc4bc82 --- /dev/null +++ b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/local_area_datasets.py @@ -0,0 +1,82 @@ +"""The local-area dataset a UK-wide or nation simulation may be calculated on. + +A UK local-area report run calculates its UK-wide or nation region on the +dataset the bundle gives constituency and local-authority regions +(``Stage12CountryBundle.local_area_dataset``), not on the dataset the region +loads otherwise, so its area results come only from that dataset's own +weights. The simulation service names that dataset in each simulation's +provenance, as it names any dataset. The UK worker accepts it, selects it in +place of the region's own dataset, keeps the region's scoping (a nation's +filter), and checks the columns the area outputs read as it loads. +""" + +from __future__ import annotations + +from dataclasses import replace +from typing import TYPE_CHECKING + +from policyengine_simulation_contract.stage12_bundle import region_type_of + +from policyengine_simulation_executor.stage12_bundle import load_stage12_bundle + +if TYPE_CHECKING: + from policyengine_simulation_contract.stage12_bundle import ( + Stage12CountryBundle, + Stage12Dataset, + ) + from policyengine_simulation_contract.stage12_execution import ( + SimulationExecutionInput, + ) + + from policyengine_simulation_executor.region_resolution import RegionResolution + +# The region types a local-area report run covers: the UK and its nations. +LOCAL_AREA_RUN_REGION_TYPES = frozenset({"national", "country"}) + + +def named_local_area_dataset( + country: Stage12CountryBundle, simulation: SimulationExecutionInput +) -> Stage12Dataset | None: + """Return the local-area dataset ``simulation`` names, or None. + + It is the country's local-area dataset when the simulation is of the + country or one of its nations and its provenance names that dataset. + The caller still checks the provenance's URI and revision against it. + """ + identity = country.local_area_dataset() + if identity is None or simulation.bundle.dataset.identity != identity: + return None + region_type = region_type_of(country.country, simulation.geography.region) + if region_type not in LOCAL_AREA_RUN_REGION_TYPES: + return None + return next((item for item in country.datasets if item.identity == identity), None) + + +def local_area_dataset_name(simulation: SimulationExecutionInput) -> str | None: + """Return the local-area dataset ``simulation`` names in the installed bundle.""" + country = next( + ( + item + for item in load_stage12_bundle().bundle.countries + if item.country == simulation.geography.country + ), + None, + ) + if country is None: + return None + dataset = named_local_area_dataset(country, simulation) + return None if dataset is None else dataset.identity + + +def dataset_region( + region: RegionResolution, local_area_dataset: str | None +) -> RegionResolution: + """Return the resolution the simulation's dataset is selected by. + + A local-area run selects the local-area dataset; every other run selects + the dataset its region names. Only the dataset differs: the simulation + is still scoped by ``region`` itself. + """ + if local_area_dataset is None: + return region + return replace(region, dataset_reference=local_area_dataset) diff --git a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/simulation.py b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/simulation.py index 2d542f1ab..c552bdc09 100644 --- a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/simulation.py +++ b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/simulation.py @@ -37,6 +37,7 @@ ) from policyengine_simulation_executor.stage12_bundle import load_stage12_bundle from policyengine_simulation_executor.uk_local_authority_metadata import ( + detect_uk_area_dataset_metadata, detect_uk_run_dataset_metadata, ) @@ -56,6 +57,11 @@ Stage12FailureDetail, validate_policy_periods, ) +from .local_area_datasets import ( + dataset_region, + local_area_dataset_name, + named_local_area_dataset, +) from .output_planning import ( apply_output_plan, resolve_simulation_output_plan, @@ -172,12 +178,13 @@ def _require_installed_bundle(simulation: SimulationExecutionInput) -> None: for item in resolved.bundle.countries if item.country == simulation.geography.country ) - # A region loads the dataset the bundle names for its region type. Entry + # A region loads the dataset the bundle names for its region type, and a + # local-area run of the UK or a nation the local-area dataset. Entry # services released before regional provenance name the default dataset # for every region, so the default stays accepted until they are updated. regional = country.dataset_for_region(simulation.geography.region) named = simulation.bundle.dataset.identity - regional_entry = next( + regional_entry = named_local_area_dataset(country, simulation) or next( (item for item in country.datasets if item.identity == regional), None ) if regional_entry is not None and named == regional_entry.identity: @@ -258,6 +265,7 @@ def calculate_simulation_frames( msg = "population artifact differs from bundle dataset provenance" raise ValueError(msg) _require_installed_bundle(simulation) + local_area_dataset = local_area_dataset_name(simulation) country = simulation.geography.country params = simulation_runtime_params(simulation) from policyengine_simulation_executor.simulation_runtime import ( # noqa: PLC0415 # resolved per call so tests can patch simulation_runtime helpers @@ -288,7 +296,7 @@ def calculate_simulation_frames( with stage_span(Stage.DATASET_RESOLUTION): dataset_selection = _resolve_dataset_selection( params, - region_resolution=region, + region_resolution=dataset_region(region, local_area_dataset), ) _require_loaded_dataset_matches_provenance(simulation, dataset_selection) with stage_span(Stage.DATASET_LOAD): @@ -308,11 +316,18 @@ def calculate_simulation_frames( ), dataset_name=dataset_selection.name, ) - uk_local_authority_metadata = detect_uk_run_dataset_metadata( - country, - dataset, - region_code=region.code, - dataset_name=dataset_selection.name, + uk_local_authority_metadata = ( + detect_uk_run_dataset_metadata( + country, + dataset, + region_code=region.code, + dataset_name=dataset_selection.name, + ) + if local_area_dataset is None + # It must carry every column the area outputs read. + else detect_uk_area_dataset_metadata( + dataset, dataset_name=dataset_selection.name + ) ) with stage_span(Stage.POLICY_NORMALIZATION): policy = normalise_policy(simulation.policy) From 964b3b062dbd51d2f05bd07d8f4d61ad13846d77 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 19:13:49 +0400 Subject: [PATCH 07/44] Test the v2 manifest's local-area report capability under its own key (failing) The simulation service refuses a local-area breakdown before writing anything unless the default v2 worker declares that its coordinator runs local-area report runs. Readers released before the declaration forbid unknown fields and can read the manifest before the entry is promoted, so it goes under a new key that readers with it read first, while active-schema-2 keeps the manifest without it. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_stage12_manifest.py | 121 +++++++++++++++++- .../tests/test_stage12_manifest_default.py | 5 +- .../tests/test_update_v2_version_manifest.py | 11 +- ...test_update_v2_version_manifest_default.py | 19 ++- 4 files changed, 149 insertions(+), 7 deletions(-) diff --git a/libs/policyengine-simulation-contract/tests/test_stage12_manifest.py b/libs/policyengine-simulation-contract/tests/test_stage12_manifest.py index eb3b464af..3c4c1ca1d 100644 --- a/libs/policyengine-simulation-contract/tests/test_stage12_manifest.py +++ b/libs/policyengine-simulation-contract/tests/test_stage12_manifest.py @@ -15,6 +15,8 @@ ) from policyengine_simulation_contract.stage12_manifest import ( ACTIVE_MANIFEST_KEY, + LOCAL_AREA_REPORTS_MANIFEST_KEY, + LOCAL_AREA_REPORTS_VERSION, PRE_CACHE_MANIFEST_KEY, REGION_DATASETS_MANIFEST_KEY, SCHEMA_2_MANIFEST_KEY, @@ -26,16 +28,22 @@ V2VersionManifest, V2WorkerValidation, V2WorkerVersion, + add_v2_worker, assert_separate_manifest_names, manifest_digest, + move_v2_default, parse_v2_manifest, pre_cache_manifest_payload, pre_region_datasets_manifest_payload, publish_v2_manifest, + read_v2_manifest, schema_1_manifest_payload, + schema_2_manifest_payload, v2_application_name, + v2_manifest_copies, validate_manifest_has_no_credentials, ) +from pydantic import ValidationError class FakeStore: @@ -227,7 +235,8 @@ def test_publish_writes_one_complete_v2_document_per_key() -> None: ) assert store.writes == [ - (SCHEMA_2_MANIFEST_KEY, manifest.model_dump(mode="json")), + (LOCAL_AREA_REPORTS_MANIFEST_KEY, manifest.model_dump(mode="json")), + (SCHEMA_2_MANIFEST_KEY, schema_2_manifest_payload(manifest)), (REGION_DATASETS_MANIFEST_KEY, schema_1_manifest_payload(manifest)), (ACTIVE_MANIFEST_KEY, pre_region_datasets_manifest_payload(manifest)), (PRE_CACHE_MANIFEST_KEY, pre_cache_manifest_payload(manifest)), @@ -835,3 +844,113 @@ def test_a_household_only_manifest_is_read_until_an_older_publish_follows() -> N store.values[ACTIVE_MANIFEST_KEY] = pre_region_datasets_manifest_payload(older) assert V2ManifestLoader(store).load().default_version == "5.3.0" + + +# The fields of a worker entry before local-area report runs. Readers released +# before them forbid any other field, so adding one would stop them loading. +_WORKER_FIELDS_BEFORE_LOCAL_AREA_REPORTS = { + "application_name", + "bundle", + "bundle_manifest_sha256", + "cache", + "countries", + "report_coordinator_callable", + "validation", +} + + +def _local_area_worker(version: str = "5.2.0") -> V2WorkerVersion: + """Return a worker whose coordinator runs local-area report runs.""" + worker = _regional_worker(version, with_household_functions=True) + return V2WorkerVersion.model_validate( + { + **worker.model_dump(mode="json"), + "local_area_reports": LOCAL_AREA_REPORTS_VERSION, + } + ) + + +def test_a_publish_writes_the_local_area_capability_under_its_own_key() -> None: + store = FakeStore() + + manifest = publish_v2_manifest(store=store, worker=_local_area_worker()) + + stored = store.values[LOCAL_AREA_REPORTS_MANIFEST_KEY] + assert stored == manifest.model_dump(mode="json") + assert stored["versions"]["5.2.0"]["local_area_reports"] == 1 + loaded = V2ManifestLoader(store).load() + assert loaded.versions["5.2.0"].local_area_reports == LOCAL_AREA_REPORTS_VERSION + + +@pytest.mark.parametrize( + "key", + [ + SCHEMA_2_MANIFEST_KEY, + REGION_DATASETS_MANIFEST_KEY, + ACTIVE_MANIFEST_KEY, + PRE_CACHE_MANIFEST_KEY, + ], +) +def test_readers_released_before_local_area_reports_never_see_the_field( + key: str, +) -> None: + store = FakeStore() + publish_v2_manifest(store=store, worker=_local_area_worker()) + + worker = store.values[key]["versions"]["5.2.0"] + assert set(worker) <= _WORKER_FIELDS_BEFORE_LOCAL_AREA_REPORTS + + +def test_the_schema_2_key_holds_the_manifest_as_its_readers_accept_it() -> None: + store = FakeStore() + manifest = publish_v2_manifest(store=store, worker=_local_area_worker()) + + schema_2 = store.values[SCHEMA_2_MANIFEST_KEY] + assert set(schema_2["versions"]["5.2.0"]) == ( + _WORKER_FIELDS_BEFORE_LOCAL_AREA_REPORTS + ) + assert parse_v2_manifest(schema_2) == manifest.model_copy( + update={ + "versions": { + "5.2.0": manifest.versions["5.2.0"].model_copy( + update={"local_area_reports": None} + ) + } + } + ) + + +def test_a_worker_without_the_capability_is_written_as_before() -> None: + worker = _regional_worker(with_household_functions=True) + manifest = add_v2_worker(current=None, worker=worker) + + assert worker.local_area_reports is None + assert "local_area_reports" not in worker.model_dump(mode="json") + copies = v2_manifest_copies(manifest) + assert copies[LOCAL_AREA_REPORTS_MANIFEST_KEY] == copies[SCHEMA_2_MANIFEST_KEY] + + +def test_a_local_area_copy_left_behind_by_an_older_publish_is_not_read() -> None: + """After a rollback, code released before the field writes only older keys.""" + store = FakeStore() + publish_v2_manifest(store=store, worker=_local_area_worker()) + older = add_v2_worker( + current=read_v2_manifest(store), + worker=_regional_worker("5.3.0", with_household_functions=True), + ) + older = move_v2_default(current=older, version="5.3.0") + for key, copy in v2_manifest_copies(older).items(): + if key != LOCAL_AREA_REPORTS_MANIFEST_KEY: + store.values[key] = copy + + loaded = V2ManifestLoader(store).load() + + assert loaded.default_version == "5.3.0" + assert loaded.versions["5.2.0"].local_area_reports is None + + +def test_the_capability_names_a_version_of_one_or_more() -> None: + worker = _regional_worker().model_dump(mode="json") + + with pytest.raises(ValidationError, match="local_area_reports"): + V2WorkerVersion.model_validate({**worker, "local_area_reports": 0}) diff --git a/libs/policyengine-simulation-contract/tests/test_stage12_manifest_default.py b/libs/policyengine-simulation-contract/tests/test_stage12_manifest_default.py index 8a85a9696..c9eb6e307 100644 --- a/libs/policyengine-simulation-contract/tests/test_stage12_manifest_default.py +++ b/libs/policyengine-simulation-contract/tests/test_stage12_manifest_default.py @@ -9,6 +9,7 @@ import pytest from policyengine_simulation_contract.stage12_manifest import ( ACTIVE_MANIFEST_KEY, + LOCAL_AREA_REPORTS_MANIFEST_KEY, PRE_CACHE_MANIFEST_KEY, REGION_DATASETS_MANIFEST_KEY, SCHEMA_2_MANIFEST_KEY, @@ -21,6 +22,7 @@ publish_v2_manifest, read_v2_manifest, schema_1_manifest_payload, + schema_2_manifest_payload, v2_manifest_copies, write_v2_manifest, ) @@ -93,7 +95,8 @@ def test_writing_a_manifest_writes_each_readers_key_and_reads_back(): write_v2_manifest(store=store, manifest=manifest) assert store.writes == [ - (SCHEMA_2_MANIFEST_KEY, manifest.model_dump(mode="json")), + (LOCAL_AREA_REPORTS_MANIFEST_KEY, manifest.model_dump(mode="json")), + (SCHEMA_2_MANIFEST_KEY, schema_2_manifest_payload(manifest)), (REGION_DATASETS_MANIFEST_KEY, schema_1_manifest_payload(manifest)), (ACTIVE_MANIFEST_KEY, pre_region_datasets_manifest_payload(manifest)), (PRE_CACHE_MANIFEST_KEY, pre_cache_manifest_payload(manifest)), diff --git a/projects/policyengine-simulation-executor/tests/test_update_v2_version_manifest.py b/projects/policyengine-simulation-executor/tests/test_update_v2_version_manifest.py index 739ded97a..f4fda2510 100644 --- a/projects/policyengine-simulation-executor/tests/test_update_v2_version_manifest.py +++ b/projects/policyengine-simulation-executor/tests/test_update_v2_version_manifest.py @@ -6,7 +6,10 @@ from datetime import UTC, datetime import pytest -from policyengine_simulation_contract.stage12_manifest import V2WorkerValidation +from policyengine_simulation_contract.stage12_manifest import ( + LOCAL_AREA_REPORTS_VERSION, + V2WorkerValidation, +) from src.modal.utils import update_v2_version_manifest as publisher @@ -56,6 +59,12 @@ def test_publisher_records_every_bundle_country_as_economy_capable() -> None: ] +def test_publisher_records_that_its_coordinator_runs_local_area_report_runs() -> None: + worker = publisher.build_worker(_validation().model_dump(mode="json")) + + assert worker.local_area_reports == LOCAL_AREA_REPORTS_VERSION + + def test_publisher_records_each_validated_household_function() -> None: payload = _validation().model_dump(mode="json") payload["household_validation_invocation_ids"] = {"uk": "household-uk-1"} diff --git a/projects/policyengine-simulation-executor/tests/test_update_v2_version_manifest_default.py b/projects/policyengine-simulation-executor/tests/test_update_v2_version_manifest_default.py index 3b81a8d80..66b306da4 100644 --- a/projects/policyengine-simulation-executor/tests/test_update_v2_version_manifest_default.py +++ b/projects/policyengine-simulation-executor/tests/test_update_v2_version_manifest_default.py @@ -15,6 +15,7 @@ import pytest from policyengine_simulation_contract.stage12_manifest import ( ACTIVE_MANIFEST_KEY, + LOCAL_AREA_REPORTS_MANIFEST_KEY, PRE_CACHE_MANIFEST_KEY, REGION_DATASETS_MANIFEST_KEY, SCHEMA_2_MANIFEST_KEY, @@ -389,8 +390,18 @@ def test_force_default_is_refused_outside_a_worker_publication( # one of them missing. A write never deletes a key. OLDER_KEYS = pytest.mark.parametrize( "expired_key", - [REGION_DATASETS_MANIFEST_KEY, ACTIVE_MANIFEST_KEY, PRE_CACHE_MANIFEST_KEY], - ids=["active-with-region-datasets", "active-with-cache", "active"], + [ + SCHEMA_2_MANIFEST_KEY, + REGION_DATASETS_MANIFEST_KEY, + ACTIVE_MANIFEST_KEY, + PRE_CACHE_MANIFEST_KEY, + ], + ids=[ + "active-schema-2", + "active-with-region-datasets", + "active-with-cache", + "active", + ], ) @@ -432,9 +443,9 @@ def test_verify_accepts_an_expired_older_key( def test_move_refuses_a_manifest_without_its_newest_key(monkeypatch, tmp_path, store): - # Current readers read the schema version 2 key first, so it is required. + # Current readers read the local-area report key first, so it is required. _with_both_workers(store) - del store.values[SCHEMA_2_MANIFEST_KEY] + del store.values[LOCAL_AREA_REPORTS_MANIFEST_KEY] writes = store.writes with pytest.raises(ValueError, match="copies of the v2 manifest differ"): From 873e1edd64aabe5b28478dfa96a68dfdcd072827 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 19:16:27 +0400 Subject: [PATCH 08/44] Declare in the v2 manifest that the coordinator runs local-area report runs V2WorkerVersion gains local_area_reports, the LOCAL_AREA_REPORTS_VERSION of the UK local-area report runs a worker's coordinator runs, left out of the JSON when None so other workers' documents and digests stay the same. The publisher sets it. It is written only under the new active-schema-2-with-local-area-reports key, which readers with it read first; active-schema-2 keeps the manifest without it, and a copy left behind by an older publisher after a rollback is no longer read. Co-Authored-By: Claude Opus 5.5 --- .../stage-12-modal-worker-foundation.md | 18 ++++++ .../stage12_manifest.py | 57 +++++++++++++++++-- .../modal/utils/update_v2_version_manifest.py | 16 +++--- 3 files changed, 80 insertions(+), 11 deletions(-) diff --git a/docs/migration/stage-12-modal-worker-foundation.md b/docs/migration/stage-12-modal-worker-foundation.md index ae572dd91..7790f3235 100644 --- a/docs/migration/stage-12-modal-worker-foundation.md +++ b/docs/migration/stage-12-modal-worker-foundation.md @@ -692,6 +692,24 @@ not read while `active-with-cache` exists; a rollback that far needs the newer keys deleted from the Modal Dict first. Removing the older copies needs a later change, once no deployed or rollback revision reads them. +Each worker's `local_area_reports`, the version of the UK local-area report +runs its coordinator runs (`LOCAL_AREA_REPORTS_VERSION`), is written only under +the `active-schema-2-with-local-area-reports` key, which current readers read +first; `active-schema-2` holds the same manifest without it, for readers +released before it. A worker that runs none leaves the field out, so its +document and digest are as before. The publisher sets it on every worker it +publishes. Readers use the new key's document only while, without the field, +it equals the `active-schema-2` document and that document is current; code +released before the field republishes only the older keys, so after a rollback +the out-of-date copy stops matching and is no longer read. The same window as +for region datasets applies: a rollback deploys the older coordinator before +its publish job runs, so until then updated entry services may start a +local-area report run, which the older coordinator refuses (its input names an +unknown `breakdown`), failing only that run with its error recorded. To avoid +it, delete the `active-schema-2-with-local-area-reports` key from the +`simulation-api-v2-version-manifest` Modal Dict before deploying the older +code. + A rollback to code released before region datasets has one window: the older worker is deployed before its publish job runs, and until that publish the region dataset copy still matches, so updated entry services keep sending diff --git a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_manifest.py b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_manifest.py index 4e13ce2de..d4f5eadd3 100644 --- a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_manifest.py +++ b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_manifest.py @@ -5,7 +5,9 @@ households. It is stored under its own key. Whenever schema version 1 can describe the same manifest, it is also written in that form, without those fields, under the keys that readers released before schema version 2 read: -with region datasets, without them, and without them or cache releases. +with region datasets, without them, and without them or cache releases. Each +worker's ``local_area_reports`` is written only under its own key, which +readers released with it read first. """ from __future__ import annotations @@ -32,8 +34,11 @@ V1_ROUTING_STATE_NAME = "simulation-api-routing-state" V2_VERSION_MANIFEST_NAME = "simulation-api-v2-version-manifest" -# The schema version 2 manifest. Readers released with schema version 2 read -# this key first. +# The schema version 2 manifest with each worker's ``local_area_reports``. +# Readers released with it read this key first. +LOCAL_AREA_REPORTS_MANIFEST_KEY = "active-schema-2-with-local-area-reports" +# The schema version 2 manifest without ``local_area_reports``, which readers +# released before it forbid. They read this key first. SCHEMA_2_MANIFEST_KEY = "active-schema-2" # Readers released before schema version 2 forbid unknown fields, so they read # the keys below, which hold the same manifest in schema version 1 form. This @@ -50,6 +55,7 @@ # A write leaves the schema version 1 keys alone when schema version 1 can't # describe the manifest. V2_MANIFEST_KEYS = ( + LOCAL_AREA_REPORTS_MANIFEST_KEY, SCHEMA_2_MANIFEST_KEY, REGION_DATASETS_MANIFEST_KEY, ACTIVE_MANIFEST_KEY, @@ -59,6 +65,10 @@ V1_APPLICATION_PREFIX = "policyengine-simulation-py" _MAX_MODAL_APPLICATION_NAME_LENGTH = 64 _CALLABLE_PATTERN = re.compile(r"^[a-z][a-z0-9_]{0,127}$") +# The UK local-area report run input a coordinator runs: ``breakdown: +# "local_areas"`` with the geographic aggregate alone. A later change to that +# input raises it. +LOCAL_AREA_REPORTS_VERSION = 1 ManifestText = Annotated[str, Field(min_length=1, max_length=255)] CallableName = Annotated[str, Field(pattern=_CALLABLE_PATTERN.pattern)] @@ -170,6 +180,12 @@ class V2WorkerVersion(StrictManifestModel): bundle_manifest_sha256: Sha256Digest validation: V2WorkerValidation cache: Stage12CacheRelease | None = None + # The LOCAL_AREA_REPORTS_VERSION of the local-area report runs the + # coordinator runs; None for one that runs none. Left out of the JSON + # when None, so a worker without it is written, and digested, as before. + local_area_reports: Annotated[int, Field(ge=1)] | None = Field( + default=None, exclude_if=lambda value: value is None + ) @model_validator(mode="after") def validate_worker(self) -> V2WorkerVersion: @@ -355,6 +371,7 @@ def schema_1_manifest_payload( worker_exclude: dict[str, IncEx | bool] = { "countries": {"__all__": {"economy_capable", "household_callable"}}, "validation": validation_exclude, + "local_area_reports": True, } if not include_region_datasets: worker_exclude["bundle"] = {"countries": {"__all__": {"region_datasets"}}} @@ -369,6 +386,13 @@ def schema_1_manifest_payload( return payload +def schema_2_manifest_payload(manifest: V2VersionManifest) -> dict[str, object]: + """Return the manifest as readers released before local-area reports accept it.""" + return manifest.model_dump( + mode="json", exclude={"versions": {"__all__": {"local_area_reports"}}} + ) + + def pre_region_datasets_manifest_payload( manifest: V2VersionManifest, ) -> dict[str, object] | None: @@ -501,7 +525,31 @@ def _is_current_schema_2_document(store: V2ManifestStore, document: object) -> b return _newest_validation(older_manifest) <= _newest_validation(manifest) +def _is_current_local_area_copy(store: V2ManifestStore, document: object) -> bool: + """Return whether ``document``, under the local-area report key, is the latest. + + Code released before ``local_area_reports`` publishes only the older keys, + for example after a rollback, which leaves an out-of-date copy behind. A + current copy, without the field, is exactly the manifest under + ``active-schema-2``, which is itself current. An unreadable document + counts as current, so readers and publishers report it. + """ + try: + manifest = parse_v2_manifest(document) + except (TypeError, ValueError): + return True + without_field = schema_2_manifest_payload(manifest) + if store.get(SCHEMA_2_MANIFEST_KEY) not in (None, without_field): + return False + return _is_current_schema_2_document(store, without_field) + + def _current_manifest(store: V2ManifestStore) -> object: + local_area_document = store.get(LOCAL_AREA_REPORTS_MANIFEST_KEY) + if local_area_document is not None and _is_current_local_area_copy( + store, local_area_document + ): + return local_area_document # Until the first schema version 2 publish, only the older keys exist. schema_2_document = store.get(SCHEMA_2_MANIFEST_KEY) if schema_2_document is not None and _is_current_schema_2_document( @@ -618,7 +666,8 @@ def v2_manifest_copies(manifest: V2VersionManifest) -> dict[str, object]: keep the last manifest written there. """ copies: dict[str, object] = { - SCHEMA_2_MANIFEST_KEY: manifest.model_dump(mode="json") + LOCAL_AREA_REPORTS_MANIFEST_KEY: manifest.model_dump(mode="json"), + SCHEMA_2_MANIFEST_KEY: schema_2_manifest_payload(manifest), } schema_1_copies = _schema_1_copies(manifest) if schema_1_copies is not None: diff --git a/projects/policyengine-simulation-executor/src/modal/utils/update_v2_version_manifest.py b/projects/policyengine-simulation-executor/src/modal/utils/update_v2_version_manifest.py index 1272e84e4..154e35776 100644 --- a/projects/policyengine-simulation-executor/src/modal/utils/update_v2_version_manifest.py +++ b/projects/policyengine-simulation-executor/src/modal/utils/update_v2_version_manifest.py @@ -20,7 +20,7 @@ household_callable_name, ) from policyengine_simulation_contract.stage12_manifest import ( - SCHEMA_2_MANIFEST_KEY, + LOCAL_AREA_REPORTS_VERSION, V1_ROUTING_STATE_NAME, V2_MANIFEST_KEYS, V2_VERSION_MANIFEST_NAME, @@ -75,6 +75,8 @@ def build_worker(validation_payload: object) -> V2WorkerVersion: bundle_manifest_sha256=resolved.bundle_manifest_sha256, validation=validation, cache=validation.cache, + # This code's coordinator runs local-area report runs. + local_area_reports=LOCAL_AREA_REPORTS_VERSION, ) validate_manifest_has_no_credentials(worker.model_dump(mode="json")) return worker @@ -188,14 +190,14 @@ def _key_holds(store: V2ManifestStore, key: str, copies: tuple[object, ...]) -> """Return whether ``key`` holds one of ``copies``, or is an older key that expired. Modal expires a Dict entry after 7 days without a read or write, and - current readers read the schema version 1 keys only when the schema - version 2 key is missing or out of date, so they can expire between - deployments. A write never deletes a key, so a missing older key is never - one a part-way write left behind, and the next write restores it. The - schema version 2 key, which current readers read first, is required. + current readers read the older keys only when the newest key is missing + or out of date, so they can expire between deployments. A write never + deletes a key, so a missing older key is never one a part-way write left + behind, and the next write restores it. The newest key, which current + readers read first, is required. """ value = store.get(key) - if value is None and key != SCHEMA_2_MANIFEST_KEY: + if value is None and key != V2_MANIFEST_KEYS[0]: return True return value in copies From 9c62e1636cdf632b0c8e21888453b1a0fc2cba2a Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 19:20:33 +0400 Subject: [PATCH 09/44] Test one routing rule for the UK local-area dataset in the manifest and worker (failing) The simulation service can't tell from the catalog whether a release's UK national runs leave the area results out, so the UK country entry of the v2 manifest declares the local-area dataset by the rule Stage 12's national aggregation uses, and the UK worker accepts that dataset by the same rule. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_stage12_manifest.py | 147 +++++++++++++----- .../test_stage12_local_area_dataset_load.py | 32 ++-- .../tests/test_update_v2_version_manifest.py | 33 +++- 3 files changed, 157 insertions(+), 55 deletions(-) diff --git a/libs/policyengine-simulation-contract/tests/test_stage12_manifest.py b/libs/policyengine-simulation-contract/tests/test_stage12_manifest.py index 3c4c1ca1d..5398c4353 100644 --- a/libs/policyengine-simulation-contract/tests/test_stage12_manifest.py +++ b/libs/policyengine-simulation-contract/tests/test_stage12_manifest.py @@ -22,6 +22,7 @@ SCHEMA_2_MANIFEST_KEY, V1_ROUTING_STATE_NAME, V2_VERSION_MANIFEST_NAME, + LocalAreaReports, Stage12CacheRelease, V2CountryWorker, V2ManifestLoader, @@ -846,40 +847,76 @@ def test_a_household_only_manifest_is_read_until_an_older_publish_follows() -> N assert V2ManifestLoader(store).load().default_version == "5.3.0" -# The fields of a worker entry before local-area report runs. Readers released -# before them forbid any other field, so adding one would stop them loading. -_WORKER_FIELDS_BEFORE_LOCAL_AREA_REPORTS = { - "application_name", - "bundle", - "bundle_manifest_sha256", - "cache", - "countries", - "report_coordinator_callable", - "validation", +# The fields of a country entry before local-area report runs. Readers +# released before them forbid any other field, so adding one would stop them +# loading. +_COUNTRY_FIELDS_BEFORE_LOCAL_AREA_REPORTS = { + "country", + "economy_capable", + "household_callable", + "single_simulation_callable", } +_UK_LOCAL_AREA_DATASET = "populace_uk_2023_local" -def _local_area_worker(version: str = "5.2.0") -> V2WorkerVersion: - """Return a worker whose coordinator runs local-area report runs.""" - worker = _regional_worker(version, with_household_functions=True) - return V2WorkerVersion.model_validate( - { - **worker.model_dump(mode="json"), - "local_area_reports": LOCAL_AREA_REPORTS_VERSION, - } +def _local_area_worker( + version: str = "5.2.0", *, dataset: str | None = _UK_LOCAL_AREA_DATASET +) -> V2WorkerVersion: + """Return a worker whose UK coordinator runs local-area report runs. + + Its UK bundle also holds the local-area dataset ``dataset`` names. + """ + worker = _regional_worker(version, with_household_functions=True).model_dump( + mode="json" ) + for country in worker["bundle"]["countries"]: + if country["country"] == "uk": + local_area = dict(country["datasets"][0]) + local_area["identity"] = _UK_LOCAL_AREA_DATASET + country["datasets"].append(local_area) + for country in worker["countries"]: + if country["country"] == "uk": + country["local_area_reports"] = { + "input_version": LOCAL_AREA_REPORTS_VERSION, + "dataset": dataset, + } + return V2WorkerVersion.model_validate(worker) + + +def _uk(worker: V2WorkerVersion) -> V2CountryWorker: + return next(country for country in worker.countries if country.country == "uk") -def test_a_publish_writes_the_local_area_capability_under_its_own_key() -> None: +def _stored_countries(document: dict, version: str = "5.2.0") -> list[dict]: + return document["versions"][version]["countries"] + + +def test_a_publish_writes_the_local_area_declaration_under_its_own_key() -> None: store = FakeStore() manifest = publish_v2_manifest(store=store, worker=_local_area_worker()) stored = store.values[LOCAL_AREA_REPORTS_MANIFEST_KEY] assert stored == manifest.model_dump(mode="json") - assert stored["versions"]["5.2.0"]["local_area_reports"] == 1 - loaded = V2ManifestLoader(store).load() - assert loaded.versions["5.2.0"].local_area_reports == LOCAL_AREA_REPORTS_VERSION + (uk,) = [ + country for country in _stored_countries(stored) if country["country"] == "uk" + ] + assert uk["local_area_reports"] == { + "input_version": 1, + "dataset": _UK_LOCAL_AREA_DATASET, + } + loaded = _uk(V2ManifestLoader(store).load().versions["5.2.0"]) + assert loaded.local_area_reports == LocalAreaReports( + input_version=LOCAL_AREA_REPORTS_VERSION, dataset=_UK_LOCAL_AREA_DATASET + ) + + +def test_a_uk_worker_whose_national_runs_keep_the_areas_declares_no_dataset() -> None: + worker = _local_area_worker(dataset=None) + + assert _uk(worker).local_area_reports == LocalAreaReports( + input_version=LOCAL_AREA_REPORTS_VERSION, dataset=None + ) @pytest.mark.parametrize( @@ -897,8 +934,8 @@ def test_readers_released_before_local_area_reports_never_see_the_field( store = FakeStore() publish_v2_manifest(store=store, worker=_local_area_worker()) - worker = store.values[key]["versions"]["5.2.0"] - assert set(worker) <= _WORKER_FIELDS_BEFORE_LOCAL_AREA_REPORTS + for country in _stored_countries(store.values[key]): + assert set(country) <= _COUNTRY_FIELDS_BEFORE_LOCAL_AREA_REPORTS def test_the_schema_2_key_holds_the_manifest_as_its_readers_accept_it() -> None: @@ -906,26 +943,28 @@ def test_the_schema_2_key_holds_the_manifest_as_its_readers_accept_it() -> None: manifest = publish_v2_manifest(store=store, worker=_local_area_worker()) schema_2 = store.values[SCHEMA_2_MANIFEST_KEY] - assert set(schema_2["versions"]["5.2.0"]) == ( - _WORKER_FIELDS_BEFORE_LOCAL_AREA_REPORTS - ) - assert parse_v2_manifest(schema_2) == manifest.model_copy( + for country in _stored_countries(schema_2): + assert set(country) == _COUNTRY_FIELDS_BEFORE_LOCAL_AREA_REPORTS + worker = manifest.versions["5.2.0"] + without_declaration = worker.model_copy( update={ - "versions": { - "5.2.0": manifest.versions["5.2.0"].model_copy( - update={"local_area_reports": None} - ) - } + "countries": tuple( + country.model_copy(update={"local_area_reports": None}) + for country in worker.countries + ) } ) + assert parse_v2_manifest(schema_2) == manifest.model_copy( + update={"versions": {"5.2.0": without_declaration}} + ) -def test_a_worker_without_the_capability_is_written_as_before() -> None: +def test_a_worker_without_the_declaration_is_written_as_before() -> None: worker = _regional_worker(with_household_functions=True) manifest = add_v2_worker(current=None, worker=worker) - assert worker.local_area_reports is None - assert "local_area_reports" not in worker.model_dump(mode="json") + for country in worker.model_dump(mode="json")["countries"]: + assert "local_area_reports" not in country copies = v2_manifest_copies(manifest) assert copies[LOCAL_AREA_REPORTS_MANIFEST_KEY] == copies[SCHEMA_2_MANIFEST_KEY] @@ -946,11 +985,37 @@ def test_a_local_area_copy_left_behind_by_an_older_publish_is_not_read() -> None loaded = V2ManifestLoader(store).load() assert loaded.default_version == "5.3.0" - assert loaded.versions["5.2.0"].local_area_reports is None + assert _uk(loaded.versions["5.2.0"]).local_area_reports is None + +def test_the_declaration_names_an_input_version_of_one_or_more() -> None: + with pytest.raises(ValidationError, match="input_version"): + LocalAreaReports(input_version=0, dataset=None) + + +def test_only_an_economy_capable_uk_entry_declares_local_area_reports() -> None: + declaration = LocalAreaReports( + input_version=LOCAL_AREA_REPORTS_VERSION, dataset=None + ) + + with pytest.raises(ValidationError, match="UK"): + V2CountryWorker.model_validate( + { + **_country_worker("us").model_dump(mode="json"), + "local_area_reports": declaration.model_dump(mode="json"), + } + ) + with pytest.raises(ValidationError, match="economy-capable"): + V2CountryWorker.model_validate( + { + **_country_worker("uk", economy=False, household=True).model_dump( + mode="json" + ), + "local_area_reports": declaration.model_dump(mode="json"), + } + ) -def test_the_capability_names_a_version_of_one_or_more() -> None: - worker = _regional_worker().model_dump(mode="json") - with pytest.raises(ValidationError, match="local_area_reports"): - V2WorkerVersion.model_validate({**worker, "local_area_reports": 0}) +def test_the_declared_dataset_is_a_dataset_of_the_uk_bundle() -> None: + with pytest.raises(ValidationError, match="populace_uk_2023_missing"): + _local_area_worker(dataset="populace_uk_2023_missing") diff --git a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py index a636caf78..aeac6f275 100644 --- a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py +++ b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py @@ -67,16 +67,22 @@ def _dataset(identity: str) -> Stage12Dataset: ) -def _installed_uk_bundle( - area_dataset: str = LOCAL_AREA_DATASET, -) -> ResolvedStage12Bundle: - """Return an installed bundle whose UK area regions load ``area_dataset``.""" +def _route_uk_area_regions(monkeypatch, *, routed: bool = True) -> None: + """Make the installed release route UK area regions to the local-area dataset.""" + monkeypatch.setattr(local_area_datasets, "uk_area_regions_routed", lambda: routed) + monkeypatch.setattr( + local_area_datasets, "routed_uk_area_dataset_name", lambda: LOCAL_AREA_DATASET + ) + + +def _installed_uk_bundle() -> ResolvedStage12Bundle: + """Return an installed bundle holding the national and local-area datasets.""" national = _dataset(NATIONAL_DATASET) region_datasets = { "national": NATIONAL_DATASET, "country": NATIONAL_DATASET, - "constituency": area_dataset, - "local_authority": area_dataset, + "constituency": LOCAL_AREA_DATASET, + "local_authority": LOCAL_AREA_DATASET, } return ResolvedStage12Bundle( bundle=Stage12BundleManifest( @@ -167,19 +173,19 @@ def _uk_simulation( def test_the_installed_bundle_accepts_the_local_area_dataset_for_uk_and_a_nation( monkeypatch, region: str ) -> None: + _route_uk_area_regions(monkeypatch) monkeypatch.setattr(worker, "load_stage12_bundle", _installed_uk_bundle) worker._require_installed_bundle(_uk_simulation(region, LOCAL_AREA_DATASET)) -def test_the_installed_bundle_refuses_a_dataset_area_regions_do_not_load_on_their_own( +def test_the_installed_bundle_refuses_the_dataset_when_the_release_does_not_route( monkeypatch, ) -> None: - monkeypatch.setattr( - worker, - "load_stage12_bundle", - lambda: _installed_uk_bundle(area_dataset=NATIONAL_DATASET), - ) + # On such a release a UK-wide run calculates the area results itself, as + # Stage 12's national aggregation decides (uk_area_breakdowns_omitted). + _route_uk_area_regions(monkeypatch, routed=False) + monkeypatch.setattr(worker, "load_stage12_bundle", _installed_uk_bundle) with pytest.raises(RuntimeError, match="differs from the installed bundle"): worker._require_installed_bundle(_uk_simulation("uk", LOCAL_AREA_DATASET)) @@ -188,6 +194,7 @@ def test_the_installed_bundle_refuses_a_dataset_area_regions_do_not_load_on_thei def test_the_installed_bundle_refuses_the_local_area_dataset_at_another_revision( monkeypatch, ) -> None: + _route_uk_area_regions(monkeypatch) monkeypatch.setattr(worker, "load_stage12_bundle", _installed_uk_bundle) provenance = _provenance(LOCAL_AREA_DATASET) provenance = provenance.model_copy( @@ -264,6 +271,7 @@ def stop_before_simulating(_params, *, resolved, **_kwargs): raise _StoppedBeforeSimulatingError monkeypatch.setattr(worker, "_require_installed_bundle", lambda _: None) + _route_uk_area_regions(monkeypatch) monkeypatch.setattr( local_area_datasets, "load_stage12_bundle", _installed_uk_bundle ) diff --git a/projects/policyengine-simulation-executor/tests/test_update_v2_version_manifest.py b/projects/policyengine-simulation-executor/tests/test_update_v2_version_manifest.py index f4fda2510..f30ba6dbf 100644 --- a/projects/policyengine-simulation-executor/tests/test_update_v2_version_manifest.py +++ b/projects/policyengine-simulation-executor/tests/test_update_v2_version_manifest.py @@ -8,6 +8,7 @@ import pytest from policyengine_simulation_contract.stage12_manifest import ( LOCAL_AREA_REPORTS_VERSION, + LocalAreaReports, V2WorkerValidation, ) from src.modal.utils import update_v2_version_manifest as publisher @@ -59,10 +60,38 @@ def test_publisher_records_every_bundle_country_as_economy_capable() -> None: ] -def test_publisher_records_that_its_coordinator_runs_local_area_report_runs() -> None: +def _local_area_reports(worker) -> dict[str, LocalAreaReports | None]: + return {country.country: country.local_area_reports for country in worker.countries} + + +def test_publisher_records_the_uk_local_area_dataset_its_coordinator_runs_on() -> None: + from policyengine_simulation_executor.uk_local_authority_metadata import ( + routed_uk_area_dataset_name, + uk_area_regions_routed, + ) + + assert uk_area_regions_routed() worker = publisher.build_worker(_validation().model_dump(mode="json")) - assert worker.local_area_reports == LOCAL_AREA_REPORTS_VERSION + assert _local_area_reports(worker) == { + "us": None, + "uk": LocalAreaReports( + input_version=LOCAL_AREA_REPORTS_VERSION, + dataset=routed_uk_area_dataset_name(), + ), + } + + +def test_publisher_records_no_dataset_when_uk_national_runs_keep_the_areas( + monkeypatch, +) -> None: + monkeypatch.setattr(publisher, "uk_area_regions_routed", lambda: False) + + worker = publisher.build_worker(_validation().model_dump(mode="json")) + + assert _local_area_reports(worker)["uk"] == LocalAreaReports( + input_version=LOCAL_AREA_REPORTS_VERSION, dataset=None + ) def test_publisher_records_each_validated_household_function() -> None: From c924097918fd706444b577e0c9747640453bd7a4 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 19:53:02 +0400 Subject: [PATCH 10/44] Declare the UK local-area dataset in the manifest by the executor's routing rule The UK country entry's LocalAreaReports (input_version, dataset) replaces the worker-wide field. The publisher sets dataset by uk_area_regions_routed and routed_uk_area_dataset_name, the rule Stage 12's national aggregation uses, and the UK worker accepts a UK-wide or nation simulation on the local-area dataset by the same rule, so the simulation service creates an area part exactly when the national run leaves the areas out. The bundle helper local_area_dataset, which compared region datasets instead, goes. The manifest's models move, unchanged apart from the new one, to stage12_manifest_models, which stage12_manifest re-exports, keeping it under its line limit. Co-Authored-By: Claude Opus 5.5 --- .../stage-12-modal-worker-foundation.md | 22 +- .../stage12_bundle.py | 23 -- .../stage12_manifest.py | 335 ++++-------------- .../stage12_manifest_models.py | 317 +++++++++++++++++ .../tests/test_stage12_local_area_dataset.py | 103 ------ .../modal/utils/update_v2_version_manifest.py | 27 +- .../stage12_runtime/local_area_datasets.py | 37 +- ruff.toml | 2 +- 8 files changed, 450 insertions(+), 416 deletions(-) create mode 100644 libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_manifest_models.py delete mode 100644 libs/policyengine-simulation-contract/tests/test_stage12_local_area_dataset.py diff --git a/docs/migration/stage-12-modal-worker-foundation.md b/docs/migration/stage-12-modal-worker-foundation.md index 7790f3235..e591e44ed 100644 --- a/docs/migration/stage-12-modal-worker-foundation.md +++ b/docs/migration/stage-12-modal-worker-foundation.md @@ -692,13 +692,21 @@ not read while `active-with-cache` exists; a rollback that far needs the newer keys deleted from the Modal Dict first. Removing the older copies needs a later change, once no deployed or rollback revision reads them. -Each worker's `local_area_reports`, the version of the UK local-area report -runs its coordinator runs (`LOCAL_AREA_REPORTS_VERSION`), is written only under -the `active-schema-2-with-local-area-reports` key, which current readers read -first; `active-schema-2` holds the same manifest without it, for readers -released before it. A worker that runs none leaves the field out, so its -document and digest are as before. The publisher sets it on every worker it -publishes. Readers use the new key's document only while, without the field, +The UK entry's `local_area_reports` says that the worker's coordinator runs +UK local-area report runs: the version of the input it accepts +(`input_version`, `LOCAL_AREA_REPORTS_VERSION`) and the dataset their area +part is calculated on (`dataset`). That dataset is the one the release routes +constituency and local-authority regions to, or null when it routes them to no +dataset of their own and a UK-wide or nation run calculates both area levels +itself. The publisher decides it by `uk_area_regions_routed` and +`routed_uk_area_dataset_name`, the rule the national aggregation's +`uk_area_breakdowns_omitted` and the UK worker use, so the simulation service, +which can't read the release kind from the catalog, creates an area part +exactly when the national run leaves the areas out. The field is written only +under the `active-schema-2-with-local-area-reports` key, which current readers +read first; `active-schema-2` holds the same manifest without it, for readers +released before it. An entry without it leaves the field out, so its document +and digest are as before. Readers use the new key's document only while, without the field, it equals the `active-schema-2` document and that document is current; code released before the field republishes only the older keys, so after a rollback the out-of-date copy stops matching and is no longer read. The same window as diff --git a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_bundle.py b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_bundle.py index 9754a9c44..2270497e4 100644 --- a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_bundle.py +++ b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_bundle.py @@ -10,8 +10,6 @@ Sha256Digest = Annotated[str, Field(pattern=r"^[0-9a-f]{64}$")] CountryId = Literal["us", "uk"] SUPPORTED_COUNTRIES: tuple[CountryId, ...] = ("us", "uk") -# The UK region types whose results a local-area report run calculates. -UK_AREA_REGION_TYPES = ("constituency", "local_authority") # A bare two-letter US region is a state code, such as "ut". _US_STATE_CODE_LENGTH = 2 @@ -102,27 +100,6 @@ def dataset_for_region(self, region: str | None) -> str | None: """Return the dataset identity a requested region code loads, or None.""" return self.dataset_for_region_type(region_type_of(self.country, region)) - def local_area_dataset(self) -> str | None: - """Return the dataset a UK local-area report run calculates on, or None. - - It is the one dataset both UK area region types (constituencies and - local authorities) load, when that is not the dataset national - regions load. None means a national run on this bundle calculates - the area results itself: the area region types load the national - dataset, name two datasets or none, or the bundle names no region - datasets. - """ - datasets = { - self.dataset_for_region_type(region_type) - for region_type in UK_AREA_REGION_TYPES - } - if len(datasets) != 1: - return None - dataset = datasets.pop() - if dataset is None or dataset == self.dataset_for_region_type("national"): - return None - return dataset - class Stage12BundleManifest(StrictBundleModel): """Stage 12's normalized subset of a PolicyEngine.py bundle.""" diff --git a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_manifest.py b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_manifest.py index d4f5eadd3..81a9848ad 100644 --- a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_manifest.py +++ b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_manifest.py @@ -5,36 +5,86 @@ households. It is stored under its own key. Whenever schema version 1 can describe the same manifest, it is also written in that form, without those fields, under the keys that readers released before schema version 2 read: -with region datasets, without them, and without them or cache releases. Each -worker's ``local_area_reports`` is written only under its own key, which +with region datasets, without them, and without them or cache releases. The +UK entry's ``local_area_reports`` is written only under its own key, which readers released with it read first. """ from __future__ import annotations import json -import re from collections.abc import Mapping from copy import deepcopy -from datetime import datetime from hashlib import sha256 -from typing import TYPE_CHECKING, Annotated, Literal, Protocol +from typing import TYPE_CHECKING, Protocol from packaging.version import InvalidVersion, Version -from pydantic import BaseModel, ConfigDict, Field, model_validator -from policyengine_simulation_contract.stage12_bundle import ( - CountryId, - Sha256Digest, - Stage12BundleManifest, +from policyengine_simulation_contract.stage12_manifest_models import ( + LOCAL_AREA_REPORTS_VERSION, + V1_APPLICATION_PREFIX, + V2_APPLICATION_PREFIX, + CallableName, + LocalAreaReports, + ManifestText, + Stage12CacheRelease, + StrictManifestModel, + V2CountryWorker, + V2VersionManifest, + V2WorkerValidation, + V2WorkerVersion, + v2_application_name, ) if TYPE_CHECKING: + from datetime import datetime + from pydantic.main import IncEx +__all__ = [ + "ACTIVE_MANIFEST_KEY", + "LOCAL_AREA_REPORTS_MANIFEST_KEY", + "LOCAL_AREA_REPORTS_VERSION", + "PRE_CACHE_MANIFEST_KEY", + "REGION_DATASETS_MANIFEST_KEY", + "SCHEMA_2_MANIFEST_KEY", + "V1_APPLICATION_PREFIX", + "V1_ROUTING_STATE_NAME", + "V2_APPLICATION_PREFIX", + "V2_MANIFEST_KEYS", + "V2_VERSION_MANIFEST_NAME", + "CallableName", + "LocalAreaReports", + "ManifestText", + "Stage12CacheRelease", + "StrictManifestModel", + "V2CountryWorker", + "V2ManifestLoader", + "V2ManifestStore", + "V2VersionManifest", + "V2WorkerValidation", + "V2WorkerVersion", + "add_v2_worker", + "assert_separate_manifest_names", + "build_next_v2_manifest", + "manifest_digest", + "move_v2_default", + "parse_v2_manifest", + "pre_cache_manifest_payload", + "pre_region_datasets_manifest_payload", + "publish_v2_manifest", + "read_v2_manifest", + "schema_1_manifest_payload", + "schema_2_manifest_payload", + "v2_application_name", + "v2_manifest_copies", + "validate_manifest_has_no_credentials", + "write_v2_manifest", +] + V1_ROUTING_STATE_NAME = "simulation-api-routing-state" V2_VERSION_MANIFEST_NAME = "simulation-api-v2-version-manifest" -# The schema version 2 manifest with each worker's ``local_area_reports``. +# The schema version 2 manifest with the UK entry's ``local_area_reports``. # Readers released with it read this key first. LOCAL_AREA_REPORTS_MANIFEST_KEY = "active-schema-2-with-local-area-reports" # The schema version 2 manifest without ``local_area_reports``, which readers @@ -61,234 +111,6 @@ ACTIVE_MANIFEST_KEY, PRE_CACHE_MANIFEST_KEY, ) -V2_APPLICATION_PREFIX = "policyengine-simulation-v2-py" -V1_APPLICATION_PREFIX = "policyengine-simulation-py" -_MAX_MODAL_APPLICATION_NAME_LENGTH = 64 -_CALLABLE_PATTERN = re.compile(r"^[a-z][a-z0-9_]{0,127}$") -# The UK local-area report run input a coordinator runs: ``breakdown: -# "local_areas"`` with the geographic aggregate alone. A later change to that -# input raises it. -LOCAL_AREA_REPORTS_VERSION = 1 - -ManifestText = Annotated[str, Field(min_length=1, max_length=255)] -CallableName = Annotated[str, Field(pattern=_CALLABLE_PATTERN.pattern)] - - -class StrictManifestModel(BaseModel): - """Base for v2 version manifest models; unknown fields are rejected.""" - - model_config = ConfigDict(extra="forbid", frozen=True) - - -class V2CountryWorker(StrictManifestModel): - """A country served by a v2 worker application, and what it can calculate. - - An economy-capable country names the callable that runs one of its report - simulations; only such a country's reports are given to the report - coordinator. ``household_callable`` names the function that calculates - its households, and is None when the application has none or it was not - validated. - """ - - country: CountryId - economy_capable: bool - single_simulation_callable: CallableName | None = None - household_callable: CallableName | None = None - - @model_validator(mode="after") - def validate_capabilities(self) -> V2CountryWorker: - """Require a simulation callable exactly when the country is economy-capable. - - A country must also have at least one capability. - """ - if self.economy_capable != (self.single_simulation_callable is not None): - msg = ( - "an economy-capable country, and only one, names a simulation callable" - ) - raise ValueError(msg) - if not self.economy_capable and self.household_callable is None: - msg = "a country needs at least one capability" - raise ValueError(msg) - return self - - -class Stage12CacheRelease(StrictManifestModel): - """The US cache a worker image holds: its manifest digest and coverage. - - The cache covers 3 datasets and 60 baselines, one per region-group segment - and year. - """ - - manifest_sha256: Sha256Digest - partition_sha256: Sha256Digest - years: tuple[int, ...] - segment_count: Literal[20] = 20 - dataset_count: Literal[3] = 3 - baseline_count: Literal[60] = 60 - - -class V2WorkerValidation(StrictManifestModel): - """Receipt for a successful validation of a deployed v2 worker application. - - Names the application and bundle digest that were validated, when, and the - validation invocation IDs: overall, for each economy-capable country's - simulation worker, and for each country's household function. - """ - - validated: Literal[True] - application_name: ManifestText - bundle_manifest_sha256: Sha256Digest - validated_at: datetime - validation_invocation_id: ManifestText - country_validation_invocation_ids: dict[CountryId, ManifestText] - household_validation_invocation_ids: dict[CountryId, ManifestText] = Field( - default_factory=dict - ) - cache: Stage12CacheRelease | None = None - - -def _require_function_receipts( - countries: tuple[V2CountryWorker, ...], validation: V2WorkerValidation -) -> None: - """Require a validation invocation for exactly the functions countries name.""" - economy_countries = { - worker.country for worker in countries if worker.economy_capable - } - if set(validation.country_validation_invocation_ids) != economy_countries: - msg = "worker validation does not cover exactly the economy-capable countries" - raise ValueError(msg) - household_countries = { - worker.country for worker in countries if worker.household_callable is not None - } - if set(validation.household_validation_invocation_ids) != household_countries: - msg = "worker validation does not cover exactly the household functions" - raise ValueError(msg) - - -class V2WorkerVersion(StrictManifestModel): - """One deployed v2 worker application and the bundle it runs. - - Lists its report coordinator callable, its per-country workers and its - validation receipt; the countries must match the bundle's, in order, and - every function a country names must have been validated. - """ - - application_name: ManifestText - report_coordinator_callable: CallableName - countries: tuple[V2CountryWorker, ...] - bundle: Stage12BundleManifest - bundle_manifest_sha256: Sha256Digest - validation: V2WorkerValidation - cache: Stage12CacheRelease | None = None - # The LOCAL_AREA_REPORTS_VERSION of the local-area report runs the - # coordinator runs; None for one that runs none. Left out of the JSON - # when None, so a worker without it is written, and digested, as before. - local_area_reports: Annotated[int, Field(ge=1)] | None = Field( - default=None, exclude_if=lambda value: value is None - ) - - @model_validator(mode="after") - def validate_worker(self) -> V2WorkerVersion: - """Check the worker's name, validation receipt and countries match its bundle. - - The application name must be the v2 name derived from the bundle's - PolicyEngine.py version, the validation must name this application and - bundle digest, and the countries must equal the bundle's, in order, - each named function with a validation invocation. - """ - if not self.application_name.startswith(V2_APPLICATION_PREFIX): - msg = "v2 application uses an invalid name prefix" - raise ValueError(msg) - if self.application_name.startswith(V1_APPLICATION_PREFIX): - msg = "v2 application name collides with the v1 prefix" - raise ValueError(msg) - expected_name = v2_application_name(self.bundle.policyengine_version) - if self.application_name != expected_name: - msg = "v2 application name does not match its bundle version" - raise ValueError(msg) - if self.validation.application_name != self.application_name: - msg = "worker validation names another application" - raise ValueError(msg) - if self.validation.bundle_manifest_sha256 != self.bundle_manifest_sha256: - msg = "worker validation names another bundle digest" - raise ValueError(msg) - if self.validation.cache != self.cache: - msg = "worker cache metadata differs from worker validation" - raise ValueError(msg) - countries = tuple(worker.country for worker in self.countries) - bundle_countries = tuple(country.country for country in self.bundle.countries) - if len(countries) != len(set(countries)): - msg = "v2 worker countries must be unique" - raise ValueError(msg) - if countries != bundle_countries: - msg = "v2 worker countries do not match the normalized bundle" - raise ValueError(msg) - _require_function_receipts(self.countries, self.validation) - return self - - def economy_worker(self, country: str) -> V2CountryWorker | None: - """Return ``country``'s worker when it can run economy reports.""" - return next( - ( - worker - for worker in self.countries - if worker.country == country and worker.economy_capable - ), - None, - ) - - def economy_simulation_callable(self, country: str) -> str: - """Return the callable that runs one of ``country``'s report simulations. - - Raises LookupError when the manifest does not mark ``country`` as - economy-capable. - """ - worker = self.economy_worker(country) - if worker is None or worker.single_simulation_callable is None: - msg = ( - f"country {country!r} is not economy-capable in {self.application_name}" - ) - raise LookupError(msg) - return worker.single_simulation_callable - - def household_worker(self, country: str) -> V2CountryWorker | None: - """Return ``country``'s worker when it has a household function.""" - return next( - ( - worker - for worker in self.countries - if worker.country == country and worker.household_callable is not None - ), - None, - ) - - -class V2VersionManifest(StrictManifestModel): - """Registry of deployed v2 worker versions, keyed by PolicyEngine.py version. - - ``default_version`` is the version used when a request does not pin one, and - ``generation`` identifies the publish that produced this manifest. - """ - - schema_version: Literal[2] = 2 - generation: ManifestText - default_version: ManifestText - versions: dict[str, V2WorkerVersion] - - @model_validator(mode="after") - def validate_versions(self) -> V2VersionManifest: - """Check the default has an entry and each key is its bundle's version.""" - if not self.versions: - msg = "v2 manifest must contain a worker version" - raise ValueError(msg) - if self.default_version not in self.versions: - msg = "v2 default version has no worker entry" - raise ValueError(msg) - for version, worker in self.versions.items(): - if version != worker.bundle.policyengine_version: - msg = "v2 manifest version key does not match its bundle" - raise ValueError(msg) - return self class V2ManifestStore(Protocol): @@ -303,29 +125,6 @@ def __setitem__(self, key: str, value: object) -> None: ... -def v2_application_name(policyengine_version: str) -> str: - """Derive the v2 Modal application name from a PolicyEngine.py version. - - Dots and plus signs become hyphens. Raises ValueError for a version with - characters a Modal name cannot hold, or a name over 64 characters. - """ - if not policyengine_version or not re.fullmatch( - r"[A-Za-z0-9][A-Za-z0-9._+-]*", policyengine_version - ): - msg = "PolicyEngine.py version cannot form a Modal application name" - raise ValueError(msg) - name = V2_APPLICATION_PREFIX + policyengine_version.replace(".", "-").replace( - "+", "-" - ) - if len(name) > _MAX_MODAL_APPLICATION_NAME_LENGTH: - msg = ( - "v2 Modal application name exceeds " - f"{_MAX_MODAL_APPLICATION_NAME_LENGTH} characters" - ) - raise ValueError(msg) - return name - - def manifest_digest(manifest: V2VersionManifest) -> str: """Return the SHA-256 of the manifest's canonical JSON (sorted, compact).""" payload = json.dumps( @@ -369,9 +168,10 @@ def schema_1_manifest_payload( return None validation_exclude = {"household_validation_invocation_ids"} worker_exclude: dict[str, IncEx | bool] = { - "countries": {"__all__": {"economy_capable", "household_callable"}}, + "countries": { + "__all__": {"economy_capable", "household_callable", "local_area_reports"} + }, "validation": validation_exclude, - "local_area_reports": True, } if not include_region_datasets: worker_exclude["bundle"] = {"countries": {"__all__": {"region_datasets"}}} @@ -389,7 +189,10 @@ def schema_1_manifest_payload( def schema_2_manifest_payload(manifest: V2VersionManifest) -> dict[str, object]: """Return the manifest as readers released before local-area reports accept it.""" return manifest.model_dump( - mode="json", exclude={"versions": {"__all__": {"local_area_reports"}}} + mode="json", + exclude={ + "versions": {"__all__": {"countries": {"__all__": {"local_area_reports"}}}} + }, ) @@ -528,7 +331,7 @@ def _is_current_schema_2_document(store: V2ManifestStore, document: object) -> b def _is_current_local_area_copy(store: V2ManifestStore, document: object) -> bool: """Return whether ``document``, under the local-area report key, is the latest. - Code released before ``local_area_reports`` publishes only the older keys, + Code released before ``LocalAreaReports`` publishes only the older keys, for example after a rollback, which leaves an out-of-date copy behind. A current copy, without the field, is exactly the manifest under ``active-schema-2``, which is itself current. An unreadable document diff --git a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_manifest_models.py b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_manifest_models.py new file mode 100644 index 000000000..b77f2a11f --- /dev/null +++ b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_manifest_models.py @@ -0,0 +1,317 @@ +"""The v2 worker version manifest's models, and the v2 application name. + +A manifest (``V2VersionManifest``) lists each deployed v2 worker application +(``V2WorkerVersion``): the countries it serves and what each can calculate +(``V2CountryWorker``, with ``LocalAreaReports`` for the UK), the bundle it +runs, and its validation receipt. ``stage12_manifest`` stores and reads it, +and re-exports every name here. +""" + +from __future__ import annotations + +import re +from datetime import datetime +from typing import Annotated, Literal + +from pydantic import BaseModel, ConfigDict, Field, model_validator + +from policyengine_simulation_contract.stage12_bundle import ( + CountryId, + Sha256Digest, + Stage12BundleManifest, +) + +V2_APPLICATION_PREFIX = "policyengine-simulation-v2-py" +V1_APPLICATION_PREFIX = "policyengine-simulation-py" +_MAX_MODAL_APPLICATION_NAME_LENGTH = 64 +_CALLABLE_PATTERN = re.compile(r"^[a-z][a-z0-9_]{0,127}$") +# The UK local-area report run input a coordinator runs: ``breakdown: +# "local_areas"`` with the geographic aggregate alone. A later change to that +# input raises it. +LOCAL_AREA_REPORTS_VERSION = 1 + +ManifestText = Annotated[str, Field(min_length=1, max_length=255)] +CallableName = Annotated[str, Field(pattern=_CALLABLE_PATTERN.pattern)] + + +class StrictManifestModel(BaseModel): + """Base for v2 version manifest models; unknown fields are rejected.""" + + model_config = ConfigDict(extra="forbid", frozen=True) + + +class LocalAreaReports(StrictManifestModel): + """The UK local-area report runs a worker application's coordinator runs. + + ``input_version`` is the ``LOCAL_AREA_REPORTS_VERSION`` of the input it + accepts. ``dataset`` is the dataset a UK-wide or nation report's area part + is calculated on, which the release routes constituency and + local-authority regions to; None when the release routes them to no + dataset of their own, so a national run calculates both area levels + itself. The worker decides both by the rule its national aggregation + uses (``uk_area_regions_routed``). + """ + + input_version: Annotated[int, Field(ge=1)] + dataset: ManifestText | None + + +class V2CountryWorker(StrictManifestModel): + """A country served by a v2 worker application, and what it can calculate. + + An economy-capable country names the callable that runs one of its report + simulations; only such a country's reports are given to the report + coordinator. ``household_callable`` names the function that calculates + its households, and is None when the application has none or it was not + validated. ``local_area_reports`` is set only on an economy-capable UK + entry whose coordinator runs local-area report runs, and left out of the + JSON otherwise, so other entries are written, and digested, as before. + """ + + country: CountryId + economy_capable: bool + single_simulation_callable: CallableName | None = None + household_callable: CallableName | None = None + local_area_reports: LocalAreaReports | None = Field( + default=None, exclude_if=lambda value: value is None + ) + + @model_validator(mode="after") + def validate_capabilities(self) -> V2CountryWorker: + """Require a simulation callable exactly when the country is economy-capable. + + A country must also have at least one capability. + """ + if self.economy_capable != (self.single_simulation_callable is not None): + msg = ( + "an economy-capable country, and only one, names a simulation callable" + ) + raise ValueError(msg) + if not self.economy_capable and self.household_callable is None: + msg = "a country needs at least one capability" + raise ValueError(msg) + if self.local_area_reports is not None and ( + self.country != "uk" or not self.economy_capable + ): + msg = "only an economy-capable UK entry runs local-area report runs" + raise ValueError(msg) + return self + + +class Stage12CacheRelease(StrictManifestModel): + """The US cache a worker image holds: its manifest digest and coverage. + + The cache covers 3 datasets and 60 baselines, one per region-group segment + and year. + """ + + manifest_sha256: Sha256Digest + partition_sha256: Sha256Digest + years: tuple[int, ...] + segment_count: Literal[20] = 20 + dataset_count: Literal[3] = 3 + baseline_count: Literal[60] = 60 + + +class V2WorkerValidation(StrictManifestModel): + """Receipt for a successful validation of a deployed v2 worker application. + + Names the application and bundle digest that were validated, when, and the + validation invocation IDs: overall, for each economy-capable country's + simulation worker, and for each country's household function. + """ + + validated: Literal[True] + application_name: ManifestText + bundle_manifest_sha256: Sha256Digest + validated_at: datetime + validation_invocation_id: ManifestText + country_validation_invocation_ids: dict[CountryId, ManifestText] + household_validation_invocation_ids: dict[CountryId, ManifestText] = Field( + default_factory=dict + ) + cache: Stage12CacheRelease | None = None + + +def _require_local_area_datasets( + countries: tuple[V2CountryWorker, ...], bundle: Stage12BundleManifest +) -> None: + """Require each declared local-area dataset to be a dataset of the country.""" + for worker in countries: + declared = worker.local_area_reports + if declared is None or declared.dataset is None: + continue + identities = { + dataset.identity + for country in bundle.countries + if country.country == worker.country + for dataset in country.datasets + } + if declared.dataset not in identities: + msg = ( + f"the {worker.country} local-area dataset {declared.dataset!r} is " + "not a dataset of its bundle" + ) + raise ValueError(msg) + + +def _require_function_receipts( + countries: tuple[V2CountryWorker, ...], validation: V2WorkerValidation +) -> None: + """Require a validation invocation for exactly the functions countries name.""" + economy_countries = { + worker.country for worker in countries if worker.economy_capable + } + if set(validation.country_validation_invocation_ids) != economy_countries: + msg = "worker validation does not cover exactly the economy-capable countries" + raise ValueError(msg) + household_countries = { + worker.country for worker in countries if worker.household_callable is not None + } + if set(validation.household_validation_invocation_ids) != household_countries: + msg = "worker validation does not cover exactly the household functions" + raise ValueError(msg) + + +class V2WorkerVersion(StrictManifestModel): + """One deployed v2 worker application and the bundle it runs. + + Lists its report coordinator callable, its per-country workers and its + validation receipt; the countries must match the bundle's, in order, and + every function a country names must have been validated. + """ + + application_name: ManifestText + report_coordinator_callable: CallableName + countries: tuple[V2CountryWorker, ...] + bundle: Stage12BundleManifest + bundle_manifest_sha256: Sha256Digest + validation: V2WorkerValidation + cache: Stage12CacheRelease | None = None + + @model_validator(mode="after") + def validate_worker(self) -> V2WorkerVersion: + """Check the worker's name, validation receipt and countries match its bundle. + + The application name must be the v2 name derived from the bundle's + PolicyEngine.py version, the validation must name this application and + bundle digest, and the countries must equal the bundle's, in order, + each named function with a validation invocation. + """ + if not self.application_name.startswith(V2_APPLICATION_PREFIX): + msg = "v2 application uses an invalid name prefix" + raise ValueError(msg) + if self.application_name.startswith(V1_APPLICATION_PREFIX): + msg = "v2 application name collides with the v1 prefix" + raise ValueError(msg) + expected_name = v2_application_name(self.bundle.policyengine_version) + if self.application_name != expected_name: + msg = "v2 application name does not match its bundle version" + raise ValueError(msg) + if self.validation.application_name != self.application_name: + msg = "worker validation names another application" + raise ValueError(msg) + if self.validation.bundle_manifest_sha256 != self.bundle_manifest_sha256: + msg = "worker validation names another bundle digest" + raise ValueError(msg) + if self.validation.cache != self.cache: + msg = "worker cache metadata differs from worker validation" + raise ValueError(msg) + countries = tuple(worker.country for worker in self.countries) + bundle_countries = tuple(country.country for country in self.bundle.countries) + if len(countries) != len(set(countries)): + msg = "v2 worker countries must be unique" + raise ValueError(msg) + if countries != bundle_countries: + msg = "v2 worker countries do not match the normalized bundle" + raise ValueError(msg) + _require_function_receipts(self.countries, self.validation) + _require_local_area_datasets(self.countries, self.bundle) + return self + + def economy_worker(self, country: str) -> V2CountryWorker | None: + """Return ``country``'s worker when it can run economy reports.""" + return next( + ( + worker + for worker in self.countries + if worker.country == country and worker.economy_capable + ), + None, + ) + + def economy_simulation_callable(self, country: str) -> str: + """Return the callable that runs one of ``country``'s report simulations. + + Raises LookupError when the manifest does not mark ``country`` as + economy-capable. + """ + worker = self.economy_worker(country) + if worker is None or worker.single_simulation_callable is None: + msg = ( + f"country {country!r} is not economy-capable in {self.application_name}" + ) + raise LookupError(msg) + return worker.single_simulation_callable + + def household_worker(self, country: str) -> V2CountryWorker | None: + """Return ``country``'s worker when it has a household function.""" + return next( + ( + worker + for worker in self.countries + if worker.country == country and worker.household_callable is not None + ), + None, + ) + + +class V2VersionManifest(StrictManifestModel): + """Registry of deployed v2 worker versions, keyed by PolicyEngine.py version. + + ``default_version`` is the version used when a request does not pin one, and + ``generation`` identifies the publish that produced this manifest. + """ + + schema_version: Literal[2] = 2 + generation: ManifestText + default_version: ManifestText + versions: dict[str, V2WorkerVersion] + + @model_validator(mode="after") + def validate_versions(self) -> V2VersionManifest: + """Check the default has an entry and each key is its bundle's version.""" + if not self.versions: + msg = "v2 manifest must contain a worker version" + raise ValueError(msg) + if self.default_version not in self.versions: + msg = "v2 default version has no worker entry" + raise ValueError(msg) + for version, worker in self.versions.items(): + if version != worker.bundle.policyengine_version: + msg = "v2 manifest version key does not match its bundle" + raise ValueError(msg) + return self + + +def v2_application_name(policyengine_version: str) -> str: + """Derive the v2 Modal application name from a PolicyEngine.py version. + + Dots and plus signs become hyphens. Raises ValueError for a version with + characters a Modal name cannot hold, or a name over 64 characters. + """ + if not policyengine_version or not re.fullmatch( + r"[A-Za-z0-9][A-Za-z0-9._+-]*", policyengine_version + ): + msg = "PolicyEngine.py version cannot form a Modal application name" + raise ValueError(msg) + name = V2_APPLICATION_PREFIX + policyengine_version.replace(".", "-").replace( + "+", "-" + ) + if len(name) > _MAX_MODAL_APPLICATION_NAME_LENGTH: + msg = ( + "v2 Modal application name exceeds " + f"{_MAX_MODAL_APPLICATION_NAME_LENGTH} characters" + ) + raise ValueError(msg) + return name diff --git a/libs/policyengine-simulation-contract/tests/test_stage12_local_area_dataset.py b/libs/policyengine-simulation-contract/tests/test_stage12_local_area_dataset.py deleted file mode 100644 index 7b0f15ffc..000000000 --- a/libs/policyengine-simulation-contract/tests/test_stage12_local_area_dataset.py +++ /dev/null @@ -1,103 +0,0 @@ -"""Tests for the dataset a UK bundle gives constituency and local-authority regions.""" - -from __future__ import annotations - -from policyengine_simulation_contract.stage12_bundle import ( - Stage12CountryBundle, - Stage12Dataset, - Stage12RegionDataset, -) - -NATIONAL_DATASET = "microcosm_uk_2024_25" -LOCAL_AREA_DATASET = "microcosm_uk_2024_25_dense" - - -def _dataset(identity: str) -> Stage12Dataset: - return Stage12Dataset( - identity=identity, - uri=f"hf://policyengine/data/{identity}.h5@{identity}-revision", - artifact_revision=f"{identity}-revision", - sha256="a" * 64, - repo_type="model", - ) - - -def _uk_bundle( - region_datasets: dict[str, str | None] | None, -) -> Stage12CountryBundle: - return Stage12CountryBundle( - country="uk", - country_package_name="policyengine-uk", - country_package_version="2.174.1", - country_package_requirement="policyengine-uk==2.174.1", - data_package_name="microcosm-uk-data", - data_package_version="0.1.0", - data_release_version="release", - data_artifact_revision=f"{NATIONAL_DATASET}-revision", - default_dataset=NATIONAL_DATASET, - default_dataset_uri=_dataset(NATIONAL_DATASET).uri, - datasets=(_dataset(NATIONAL_DATASET), _dataset(LOCAL_AREA_DATASET)), - region_datasets=( - None - if region_datasets is None - else tuple( - Stage12RegionDataset(region_type=region_type, dataset=dataset) - for region_type, dataset in region_datasets.items() - ) - ), - ) - - -def test_both_area_region_types_on_their_own_dataset_name_the_local_area_dataset() -> ( - None -): - bundle = _uk_bundle( - { - "national": NATIONAL_DATASET, - "country": NATIONAL_DATASET, - "constituency": LOCAL_AREA_DATASET, - "local_authority": LOCAL_AREA_DATASET, - } - ) - - assert bundle.local_area_dataset() == LOCAL_AREA_DATASET - - -def test_area_regions_on_the_national_dataset_have_no_local_area_dataset() -> None: - bundle = _uk_bundle( - { - "national": NATIONAL_DATASET, - "constituency": NATIONAL_DATASET, - "local_authority": NATIONAL_DATASET, - } - ) - - assert bundle.local_area_dataset() is None - - -def test_area_regions_on_two_datasets_have_no_local_area_dataset() -> None: - bundle = _uk_bundle( - { - "national": NATIONAL_DATASET, - "constituency": LOCAL_AREA_DATASET, - "local_authority": "microcosm_uk_2024_25_authorities", - } - ) - - assert bundle.local_area_dataset() is None - - -def test_an_area_region_type_without_one_dataset_has_no_local_area_dataset() -> None: - bundle = _uk_bundle( - { - "national": NATIONAL_DATASET, - "constituency": LOCAL_AREA_DATASET, - "local_authority": None, - } - ) - - assert bundle.local_area_dataset() is None - - -def test_a_bundle_published_before_region_datasets_has_no_local_area_dataset() -> None: - assert _uk_bundle(None).local_area_dataset() is None diff --git a/projects/policyengine-simulation-executor/src/modal/utils/update_v2_version_manifest.py b/projects/policyengine-simulation-executor/src/modal/utils/update_v2_version_manifest.py index 154e35776..5c3fea16b 100644 --- a/projects/policyengine-simulation-executor/src/modal/utils/update_v2_version_manifest.py +++ b/projects/policyengine-simulation-executor/src/modal/utils/update_v2_version_manifest.py @@ -24,6 +24,7 @@ V1_ROUTING_STATE_NAME, V2_MANIFEST_KEYS, V2_VERSION_MANIFEST_NAME, + LocalAreaReports, V2CountryWorker, V2ManifestLoader, V2ManifestStore, @@ -42,6 +43,23 @@ write_v2_manifest, ) from policyengine_simulation_executor.stage12_bundle import load_stage12_bundle +from policyengine_simulation_executor.uk_local_authority_metadata import ( + routed_uk_area_dataset_name, + uk_area_regions_routed, +) + + +def uk_local_area_reports() -> LocalAreaReports: + """Return the UK local-area report runs this code's coordinator runs. + + The dataset is the one the installed release routes UK area regions to, + or None when it routes them to none, by the rule the worker and Stage + 12's national aggregation use; it reads only the packaged release. + """ + return LocalAreaReports( + input_version=LOCAL_AREA_REPORTS_VERSION, + dataset=routed_uk_area_dataset_name() if uk_area_regions_routed() else None, + ) def build_worker(validation_payload: object) -> V2WorkerVersion: @@ -49,7 +67,9 @@ def build_worker(validation_payload: object) -> V2WorkerVersion: Every bundle country has a single-simulation worker, so each is recorded as economy-capable. A country's household function is recorded when the - record shows that it calculated the validation household. Raises + record shows that it calculated the validation household. The UK entry + records that this code's coordinator runs local-area report runs, and on + which dataset (``uk_local_area_reports``). Raises ValueError if the record is invalid or the entry carries a credential-like key. """ @@ -68,6 +88,9 @@ def build_worker(validation_payload: object) -> V2WorkerVersion: if country.country in validation.household_validation_invocation_ids else None ), + local_area_reports=( + uk_local_area_reports() if country.country == "uk" else None + ), ) for country in resolved.bundle.countries ), @@ -75,8 +98,6 @@ def build_worker(validation_payload: object) -> V2WorkerVersion: bundle_manifest_sha256=resolved.bundle_manifest_sha256, validation=validation, cache=validation.cache, - # This code's coordinator runs local-area report runs. - local_area_reports=LOCAL_AREA_REPORTS_VERSION, ) validate_manifest_has_no_credentials(worker.model_dump(mode="json")) return worker diff --git a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/local_area_datasets.py b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/local_area_datasets.py index 18dc4bc82..8fdaaf7b4 100644 --- a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/local_area_datasets.py +++ b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/local_area_datasets.py @@ -1,13 +1,17 @@ """The local-area dataset a UK-wide or nation simulation may be calculated on. A UK local-area report run calculates its UK-wide or nation region on the -dataset the bundle gives constituency and local-authority regions -(``Stage12CountryBundle.local_area_dataset``), not on the dataset the region -loads otherwise, so its area results come only from that dataset's own -weights. The simulation service names that dataset in each simulation's -provenance, as it names any dataset. The UK worker accepts it, selects it in -place of the region's own dataset, keeps the region's scoping (a nation's -filter), and checks the columns the area outputs read as it loads. +dataset the release routes constituency and local-authority regions to +(``routed_uk_area_dataset_name``), not on the dataset the region loads +otherwise, so its area results come only from that dataset's own weights. It +does so only on a release that routes them (``uk_area_regions_routed``), +whose UK-wide and nation runs leave the area results out: the rule Stage 12's +national aggregation uses (``uk_area_breakdowns_omitted``), and the one the v2 +manifest's ``LocalAreaReports`` declares to the simulation service. The +service names that dataset in each simulation's provenance, as it names any +dataset. The UK worker accepts it, selects it in place of the region's own +dataset, keeps the region's scoping (a nation's filter), and checks the +columns the area outputs read as it loads. """ from __future__ import annotations @@ -18,6 +22,10 @@ from policyengine_simulation_contract.stage12_bundle import region_type_of from policyengine_simulation_executor.stage12_bundle import load_stage12_bundle +from policyengine_simulation_executor.uk_local_authority_metadata import ( + routed_uk_area_dataset_name, + uk_area_regions_routed, +) if TYPE_CHECKING: from policyengine_simulation_contract.stage12_bundle import ( @@ -39,15 +47,18 @@ def named_local_area_dataset( ) -> Stage12Dataset | None: """Return the local-area dataset ``simulation`` names, or None. - It is the country's local-area dataset when the simulation is of the - country or one of its nations and its provenance names that dataset. - The caller still checks the provenance's URI and revision against it. + It is the UK's local-area dataset when the release routes UK area regions + to it, the simulation is of the UK or one of its nations, and its + provenance names that dataset. The caller still checks the provenance's + URI and revision against it. """ - identity = country.local_area_dataset() - if identity is None or simulation.bundle.dataset.identity != identity: + if country.country != "uk": return None region_type = region_type_of(country.country, simulation.geography.region) - if region_type not in LOCAL_AREA_RUN_REGION_TYPES: + if region_type not in LOCAL_AREA_RUN_REGION_TYPES or not uk_area_regions_routed(): + return None + identity = routed_uk_area_dataset_name() + if simulation.bundle.dataset.identity != identity: return None return next((item for item in country.datasets if item.identity == identity), None) diff --git a/ruff.toml b/ruff.toml index 325e559de..16acea826 100644 --- a/ruff.toml +++ b/ruff.toml @@ -117,7 +117,7 @@ runtime-evaluated-base-classes = [ "policyengine_simulation_contract.stage12_bundle.StrictBundleModel", "policyengine_simulation_contract.stage12_execution.SimulationExecutionInput", "policyengine_simulation_contract.stage12_execution.StrictContractModel", - "policyengine_simulation_contract.stage12_manifest.StrictManifestModel", + "policyengine_simulation_contract.stage12_manifest_models.StrictManifestModel", "policyengine_simulation_executor.precompute_models._StrictModel", "policyengine_simulation_executor.stage_reporting_simulation.StageReportingSimulation", "pydantic.BaseModel", From 2a896561555bcb08401c4bbcfa597a6270a3d767 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 22:47:13 +0400 Subject: [PATCH 11/44] Describe local-area report runs as runs of reports on the local-area dataset A local-area report is now an ordinary report on the local-area dataset, linked to its national report by key, with no marker in its input, so the manifest declaration and the Stage 12 doc describe the runs the coordinator accepts that way. Co-Authored-By: Claude Opus 5.5 --- .../stage-12-modal-worker-foundation.md | 25 +++++++++++-------- .../stage12_manifest_models.py | 23 +++++++++-------- 2 files changed, 27 insertions(+), 21 deletions(-) diff --git a/docs/migration/stage-12-modal-worker-foundation.md b/docs/migration/stage-12-modal-worker-foundation.md index e591e44ed..d11c16269 100644 --- a/docs/migration/stage-12-modal-worker-foundation.md +++ b/docs/migration/stage-12-modal-worker-foundation.md @@ -693,27 +693,30 @@ keys deleted from the Modal Dict first. Removing the older copies needs a later change, once no deployed or rollback revision reads them. The UK entry's `local_area_reports` says that the worker's coordinator runs -UK local-area report runs: the version of the input it accepts -(`input_version`, `LOCAL_AREA_REPORTS_VERSION`) and the dataset their area -part is calculated on (`dataset`). That dataset is the one the release routes -constituency and local-authority regions to, or null when it routes them to no -dataset of their own and a UK-wide or nation run calculates both area levels +UK local-area report runs, the runs of UK-wide and nation reports on the +local-area dataset, which calculate the constituency and local-authority +results alone: the version of the runs it accepts (`input_version`, +`LOCAL_AREA_REPORTS_VERSION`) and the local-area dataset (`dataset`). That +dataset is the one the release routes constituency and local-authority +regions to, or null when it routes them to no dataset of their own and a +UK-wide or nation run on the national dataset calculates both area levels itself. The publisher decides it by `uk_area_regions_routed` and `routed_uk_area_dataset_name`, the rule the national aggregation's `uk_area_breakdowns_omitted` and the UK worker use, so the simulation service, -which can't read the release kind from the catalog, creates an area part -exactly when the national run leaves the areas out. The field is written only +which can't read the release kind from the catalog, creates a local-area +report exactly when the national run leaves the areas out. The field is written only under the `active-schema-2-with-local-area-reports` key, which current readers read first; `active-schema-2` holds the same manifest without it, for readers released before it. An entry without it leaves the field out, so its document -and digest are as before. Readers use the new key's document only while, without the field, -it equals the `active-schema-2` document and that document is current; code +and digest are as before. Readers use the new key's document only while, +without the field, it equals the `active-schema-2` document and that document +is current; code released before the field republishes only the older keys, so after a rollback the out-of-date copy stops matching and is no longer read. The same window as for region datasets applies: a rollback deploys the older coordinator before its publish job runs, so until then updated entry services may start a -local-area report run, which the older coordinator refuses (its input names an -unknown `breakdown`), failing only that run with its error recorded. To avoid +local-area report run, whose simulations on the local-area dataset the older +UK worker refuses, failing only that run with its error recorded. To avoid it, delete the `active-schema-2-with-local-area-reports` key from the `simulation-api-v2-version-manifest` Modal Dict before deploying the older code. diff --git a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_manifest_models.py b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_manifest_models.py index b77f2a11f..3a214d01a 100644 --- a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_manifest_models.py +++ b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_manifest_models.py @@ -25,9 +25,11 @@ V1_APPLICATION_PREFIX = "policyengine-simulation-py" _MAX_MODAL_APPLICATION_NAME_LENGTH = 64 _CALLABLE_PATTERN = re.compile(r"^[a-z][a-z0-9_]{0,127}$") -# The UK local-area report run input a coordinator runs: ``breakdown: -# "local_areas"`` with the geographic aggregate alone. A later change to that -# input raises it. +# The local-area report runs a coordinator runs: a run of a UK-wide or nation +# report on the local-area dataset, given as any report run is, calculates the +# constituency and local-authority results alone, with the codes disclosure +# control withholds. A later change to what such a run accepts or writes +# raises it. LOCAL_AREA_REPORTS_VERSION = 1 ManifestText = Annotated[str, Field(min_length=1, max_length=255)] @@ -43,13 +45,14 @@ class StrictManifestModel(BaseModel): class LocalAreaReports(StrictManifestModel): """The UK local-area report runs a worker application's coordinator runs. - ``input_version`` is the ``LOCAL_AREA_REPORTS_VERSION`` of the input it - accepts. ``dataset`` is the dataset a UK-wide or nation report's area part - is calculated on, which the release routes constituency and - local-authority regions to; None when the release routes them to no - dataset of their own, so a national run calculates both area levels - itself. The worker decides both by the rule its national aggregation - uses (``uk_area_regions_routed``). + ``input_version`` is the ``LOCAL_AREA_REPORTS_VERSION`` of the runs it + accepts. ``dataset`` is the local-area dataset, which the release routes + constituency and local-authority regions to: a run of a UK-wide or nation + report on it calculates the area results alone. It is None when the + release routes them to no dataset of their own, so a UK-wide or nation + run on the national dataset calculates both area levels itself. The + worker decides both by the rule its national aggregation uses + (``uk_area_regions_routed``). """ input_version: Annotated[int, Field(ge=1)] From 1e1d07c087cb50238ac534fa66b74d4de1d434e4 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 22:47:50 +0400 Subject: [PATCH 12/44] Test recognising a run of a UK-wide or nation report on the local-area dataset (failing) The local-area report is an ordinary report on the local-area dataset, so the coordinator recognises its runs by their simulations' dataset and region, not by a marker in the input. Co-Authored-By: Claude Opus 5.5 --- .../test_stage12_local_area_dataset_load.py | 77 ++++++++++++++++++- 1 file changed, 76 insertions(+), 1 deletion(-) diff --git a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py index aeac6f275..3c33d5f86 100644 --- a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py +++ b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py @@ -26,7 +26,10 @@ EntityOutputPlan, GeographySelection, PlannedSimulationExecutionInput, + ReportAggregate, + ReportExecutionInput, ReportOutputRequirements, + SimulationExecutionInput, SimulationRole, Stage12OutputPlan, ) @@ -41,7 +44,12 @@ local_area_datasets, ) from policyengine_simulation_executor.stage12_runtime import simulation as worker -from stage12_runtime_support import BASELINE_ID, EVALUATION_ID +from stage12_runtime_support import ( + BASELINE_ID, + EVALUATION_ID, + REFORM_ID, + report_execution_input, +) NATIONAL_DATASET = "microcosm_uk_2024_25" LOCAL_AREA_DATASET = "microcosm_uk_2024_25_dense" @@ -365,3 +373,70 @@ def test_a_local_area_dataset_without_an_area_column_fails_before_simulating( _uk_simulation("uk", LOCAL_AREA_DATASET), household=_area_household().drop(columns=[missing]), ) + + +def _uk_report(region: str, identity: str) -> ReportExecutionInput: + """Return a UK report whose two simulations are on the dataset ``identity``.""" + baseline = _uk_simulation(region, identity).model_dump( + mode="json", exclude={"output_plan"} + ) + reform = { + **baseline, + "simulation_execution_id": str(REFORM_ID), + "role": SimulationRole.REFORM.value, + "policy": {"gov.hmrc.income_tax.rates.uk[0].rate": {"2026-01-01": 0.21}}, + } + return ReportExecutionInput( + evaluation_id=EVALUATION_ID, + baseline=SimulationExecutionInput.model_validate(baseline), + reform=SimulationExecutionInput.model_validate(reform), + requested_aggregates=tuple(ReportAggregate), + ) + + +@pytest.mark.parametrize("region", ["uk", "country/wales"]) +def test_a_uk_wide_or_nation_report_on_the_local_area_dataset_calculates_areas( + monkeypatch, region: str +) -> None: + _route_uk_area_regions(monkeypatch) + + assert local_area_datasets.is_local_area_report( + _uk_report(region, LOCAL_AREA_DATASET) + ) + + +def test_a_report_on_the_national_dataset_is_no_local_area_report( + monkeypatch, +) -> None: + _route_uk_area_regions(monkeypatch) + + assert not local_area_datasets.is_local_area_report( + _uk_report("uk", NATIONAL_DATASET) + ) + + +def test_a_constituency_report_on_the_local_area_dataset_is_an_ordinary_report( + monkeypatch, +) -> None: + # Its national aggregation already calculates its one area. + _route_uk_area_regions(monkeypatch) + + assert not local_area_datasets.is_local_area_report( + _uk_report("constituency/W07000081", LOCAL_AREA_DATASET) + ) + + +def test_no_report_is_a_local_area_report_where_the_release_does_not_route( + monkeypatch, +) -> None: + _route_uk_area_regions(monkeypatch, routed=False) + + assert not local_area_datasets.is_local_area_report( + _uk_report("uk", LOCAL_AREA_DATASET) + ) + + +def test_a_us_report_is_no_local_area_report(monkeypatch) -> None: + _route_uk_area_regions(monkeypatch) + + assert not local_area_datasets.is_local_area_report(report_execution_input()) From 64071317b7bfb1027740e6ae3c98a8d7d9c46584 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 22:48:20 +0400 Subject: [PATCH 13/44] Recognise a run of a UK-wide or nation report on the local-area dataset is_local_area_report decides by the report's region and its simulations' dataset, by the routing rule the UK worker and the national aggregation use, so the coordinator can calculate the area results alone for any such report, however the simulation service found or created it. Co-Authored-By: Claude Opus 5.5 --- .../stage12_runtime/local_area_datasets.py | 35 +++++++++++++++---- 1 file changed, 28 insertions(+), 7 deletions(-) diff --git a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/local_area_datasets.py b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/local_area_datasets.py index 8fdaaf7b4..c845626ab 100644 --- a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/local_area_datasets.py +++ b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/local_area_datasets.py @@ -33,6 +33,7 @@ Stage12Dataset, ) from policyengine_simulation_contract.stage12_execution import ( + ReportExecutionInput, SimulationExecutionInput, ) @@ -42,6 +43,31 @@ LOCAL_AREA_RUN_REGION_TYPES = frozenset({"national", "country"}) +def _calculates_on_local_area_dataset(simulation: SimulationExecutionInput) -> bool: + """Whether ``simulation`` is of the UK or a nation, on the local-area dataset. + + That is the dataset the release routes UK area regions to, on a release + that routes them to one. + """ + if simulation.geography.country != "uk": + return False + region_type = region_type_of("uk", simulation.geography.region) + if region_type not in LOCAL_AREA_RUN_REGION_TYPES or not uk_area_regions_routed(): + return False + return simulation.bundle.dataset.identity == routed_uk_area_dataset_name() + + +def is_local_area_report(report: ReportExecutionInput) -> bool: + """Whether a run of ``report`` calculates the UK area results alone. + + It does for a report of the UK or a nation whose simulations are on the + local-area dataset: an ordinary report, which the simulation service + links to the national report with the same policies, region and year. + Both of a report's simulations share its dataset and region. + """ + return _calculates_on_local_area_dataset(report.baseline) + + def named_local_area_dataset( country: Stage12CountryBundle, simulation: SimulationExecutionInput ) -> Stage12Dataset | None: @@ -52,14 +78,9 @@ def named_local_area_dataset( provenance names that dataset. The caller still checks the provenance's URI and revision against it. """ - if country.country != "uk": - return None - region_type = region_type_of(country.country, simulation.geography.region) - if region_type not in LOCAL_AREA_RUN_REGION_TYPES or not uk_area_regions_routed(): - return None - identity = routed_uk_area_dataset_name() - if simulation.bundle.dataset.identity != identity: + if country.country != "uk" or not _calculates_on_local_area_dataset(simulation): return None + identity = simulation.bundle.dataset.identity return next((item for item in country.datasets if item.identity == identity), None) From 19111ed52776d05cfcee5adac2d77961166cc2c5 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 23:19:54 +0400 Subject: [PATCH 14/44] Test a local-area report run's area and withheld-code rows (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 ยท 21's decision 7 puts the codes disclosure control withholds in a new withheld_area_codes table, keyed like the other comparison tables. A local-area run stores its constituency and local-authority rows, one withheld-code row per withheld area, and its data version, and nothing else. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_local_area_results.py | 188 ++++++++++++++++++ .../test_stage12_local_area_completion.py | 67 +++++++ 2 files changed, 255 insertions(+) create mode 100644 libs/policyengine-stage12-persistence/tests/test_local_area_results.py create mode 100644 projects/policyengine-simulation-executor/tests/test_stage12_local_area_completion.py diff --git a/libs/policyengine-stage12-persistence/tests/test_local_area_results.py b/libs/policyengine-stage12-persistence/tests/test_local_area_results.py new file mode 100644 index 000000000..adeaf2c98 --- /dev/null +++ b/libs/policyengine-stage12-persistence/tests/test_local_area_results.py @@ -0,0 +1,188 @@ +"""Tests for a local-area report run's area results as result-table rows.""" + +from __future__ import annotations + +from typing import Any +from uuid import UUID + +import pytest +from policyengine_simulation_contract.stage12_execution import ReportRunIds +from policyengine_stage12_persistence.local_area_results import local_area_result +from policyengine_stage12_persistence.report_run_results import ( + constituency_impacts, + local_authority_impacts, + withheld_area_codes, +) +from pydantic import ValidationError + +RUN_IDS = ReportRunIds( + report_run_id=UUID("00000000-0000-0000-0000-00000000000a"), + baseline_simulation_run_id=UUID("00000000-0000-0000-0000-00000000000b"), + reform_simulation_run_id=UUID("00000000-0000-0000-0000-00000000000c"), +) +RUN_KEYS = { + "report_run_id": RUN_IDS.report_run_id, + "baseline_simulation_run_id": RUN_IDS.baseline_simulation_run_id, + "reform_simulation_run_id": RUN_IDS.reform_simulation_run_id, +} +DISCLOSURE = { + "disclosure_tier": "reported", + "average_household_income_change_lower": -12.0, + "average_household_income_change_upper": -8.0, + "relative_household_income_change_lower": -0.0004, + "relative_household_income_change_upper": -0.0002, +} + + +def _area_output(**changes: Any) -> dict[str, Any]: + """Return a local-area result with two constituencies and one authority.""" + return { + "kind": "local_areas", + "model_version": "2.174.1", + "policyengine_version": "6.17.1", + "dataset": "microcosm_uk_2024_25_dense", + "data_version": "microcosm-uk-2024-25-dense-20261107T173210Z-38605444", + "constituency_impact": [ + { + "constituency_code": "E14001063", + "constituency_name": "Aldershot", + "average_household_income_change": -10.0, + "relative_household_income_change": -0.0003, + "population": 41_000.0, + **DISCLOSURE, + }, + { + "constituency_code": "W07000081", + "constituency_name": "Aberafan Maesteg", + "average_household_income_change": -9.0, + "relative_household_income_change": -0.0003, + "population": 38_000.0, + **DISCLOSURE, + "disclosure_tier": "approximate", + }, + ], + "local_authority_impact": [ + { + "local_authority_code": "E06000063", + "local_authority_name": "Cumberland", + "average_household_income_change": -11.0, + "relative_household_income_change": -0.0004, + "population": 120_000.0, + **DISCLOSURE, + } + ], + "constituency_withheld_codes": ["S14000045"], + "local_authority_withheld_codes": ["E06000064", "W06000015"], + **changes, + } + + +def _rows_by_table(output: dict[str, Any]) -> dict[str, list[dict[str, Any]]]: + result = local_area_result(output, run_ids=RUN_IDS) + return { + rows.table.name: [ + {name: value for name, value in row.items() if name != "id"} + for row in rows.rows + ] + for rows in result.rows + } + + +def test_a_local_area_result_stores_its_areas_and_withheld_codes() -> None: + rows = _rows_by_table(_area_output()) + + assert set(rows) == { + constituency_impacts.name, + local_authority_impacts.name, + withheld_area_codes.name, + } + assert rows["constituency_impacts"] == [ + { + **RUN_KEYS, + "constituency_code": "E14001063", + "constituency_name": "Aldershot", + "average_household_income_change": -10.0, + "relative_household_income_change": -0.0003, + "population": 41_000.0, + **DISCLOSURE, + }, + { + **RUN_KEYS, + "constituency_code": "W07000081", + "constituency_name": "Aberafan Maesteg", + "average_household_income_change": -9.0, + "relative_household_income_change": -0.0003, + "population": 38_000.0, + **DISCLOSURE, + "disclosure_tier": "approximate", + }, + ] + assert rows["local_authority_impacts"] == [ + { + **RUN_KEYS, + "local_authority_code": "E06000063", + "local_authority_name": "Cumberland", + "average_household_income_change": -11.0, + "relative_household_income_change": -0.0004, + "population": 120_000.0, + **DISCLOSURE, + } + ] + assert rows["withheld_area_codes"] == [ + {**RUN_KEYS, "area_type": "constituency", "code": "S14000045"}, + {**RUN_KEYS, "area_type": "local_authority", "code": "E06000064"}, + {**RUN_KEYS, "area_type": "local_authority", "code": "W06000015"}, + ] + + +def test_each_row_has_its_own_id() -> None: + result = local_area_result(_area_output(), run_ids=RUN_IDS) + + ids = [row["id"] for rows in result.rows for row in rows.rows] + assert len(ids) == len(set(ids)) == 6 + + +def test_a_local_area_result_sets_only_the_runs_data_version() -> None: + result = local_area_result(_area_output(), run_ids=RUN_IDS) + + assert result.report_run_columns == { + "data_version": "microcosm-uk-2024-25-dense-20261107T173210Z-38605444" + } + assert not any(rows.shared_by_reports for rows in result.rows) + + +def test_a_level_with_every_area_withheld_stores_no_area_rows() -> None: + rows = _rows_by_table( + _area_output( + constituency_impact=[], + constituency_withheld_codes=["E14001063", "W07000081"], + ) + ) + + assert rows["constituency_impacts"] == [] + assert [row["code"] for row in rows["withheld_area_codes"]] == [ + "E14001063", + "W07000081", + "E06000064", + "W06000015", + ] + + +@pytest.mark.parametrize( + "missing", ["constituency_withheld_codes", "local_authority_withheld_codes"] +) +def test_a_local_area_result_without_its_withheld_codes_is_refused( + missing: str, +) -> None: + # A Stage 12 run always lists them; null means an older result format, + # where "none withheld" and "not reported" can't be told apart. + output = _area_output() + del output[missing] + + with pytest.raises(ValueError, match="withheld"): + local_area_result(output, run_ids=RUN_IDS) + + +def test_a_national_economy_result_is_refused() -> None: + with pytest.raises(ValidationError, match="kind"): + local_area_result({"budget": {}}, run_ids=RUN_IDS) diff --git a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_completion.py b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_completion.py new file mode 100644 index 000000000..35b4af826 --- /dev/null +++ b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_completion.py @@ -0,0 +1,67 @@ +"""Tests for completing a local-area report run with its area results.""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from typing import Any + +from policyengine_simulation_executor.stage12_runtime.report_run_recording import ( + ReportRunRecorder, +) +from policyengine_stage12_persistence import RunStatus, RunWrite +from policyengine_stage12_persistence.local_area_results import local_area_result +from stage12_fake_report_runs import REPORT_RUN_IDS + +MODAL_CALL_ID = "fc-local-area-coordinator" +AREA_OUTPUT = { + "kind": "local_areas", + "model_version": "2.174.1", + "policyengine_version": "6.17.1", + "dataset": "microcosm_uk_2024_25_dense", + "data_version": "microcosm-uk-2024-25-dense-20261107T173210Z-38605444", + "constituency_impact": [], + "local_authority_impact": [], + "constituency_withheld_codes": ["S14000045"], + "local_authority_withheld_codes": [], +} + + +@dataclass +class _CompletionWriter: + """Records each completion a recorder asks for.""" + + completions: list[dict[str, Any]] = field(default_factory=list) + + def complete_report_run( + self, run_ids, *, modal_call_id, completed_at, result=None + ) -> RunWrite: + self.completions.append( + {"run_ids": run_ids, "modal_call_id": modal_call_id, "result": result} + ) + return RunWrite(changed=True, status=RunStatus.SUCCEEDED) + + +def test_a_local_area_completion_stores_the_area_rows_under_the_calls_claim() -> None: + writer = _CompletionWriter() + recorder = ReportRunRecorder( + writer=writer, # pyright: ignore[reportArgumentType] + run_ids=REPORT_RUN_IDS, + modal_call_id=MODAL_CALL_ID, + ) + + written = recorder.complete_local_areas(AREA_OUTPUT) + + assert written == RunWrite(changed=True, status=RunStatus.SUCCEEDED) + (completion,) = writer.completions + assert completion["run_ids"] == REPORT_RUN_IDS + assert completion["modal_call_id"] == MODAL_CALL_ID + expected = local_area_result(AREA_OUTPUT, run_ids=REPORT_RUN_IDS) + stored = completion["result"] + assert stored.report_run_columns == expected.report_run_columns + assert [ + (rows.table.name, [{**row, "id": None} for row in rows.rows]) + for rows in stored.rows + ] == [ + (rows.table.name, [{**row, "id": None} for row in rows.rows]) + for rows in expected.rows + ] From 1249fc347459bc6bffeb0fdecd9500277163e334 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 23:21:21 +0400 Subject: [PATCH 15/44] Store a local-area report run's area and withheld-code rows MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit local_area_result validates a LocalAreaBreakdownOutput, refusing one that doesn't list each level's withheld codes, and returns its constituency and local-authority rows (through the national result's area rows, now area_record_rows), one withheld_area_codes row per withheld area, and the run's data version. ReportRunRecorder.complete_local_areas writes them in the completion's transaction under the call's claim. The table model follows C1 ยท 21's decision 7; its column types are checked against C1 ยท 22's revision once it exists. Co-Authored-By: Claude Opus 5.5 --- .../__init__.py | 2 + .../local_area_results.py | 81 +++++++++++++++++++ .../report_run_results.py | 24 +++++- .../stage12_runtime/report_run_recording.py | 16 ++++ 4 files changed, 121 insertions(+), 2 deletions(-) create mode 100644 libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/local_area_results.py diff --git a/libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/__init__.py b/libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/__init__.py index 7e86cb336..e2b48bbbf 100644 --- a/libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/__init__.py +++ b/libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/__init__.py @@ -11,6 +11,7 @@ from policyengine_stage12_persistence.household_report_run_store import ( HouseholdReportRunStore, ) +from policyengine_stage12_persistence.local_area_results import local_area_result from policyengine_stage12_persistence.report_run_results import ( DistrictCodes, ReportRunResult, @@ -55,6 +56,7 @@ "YearStarter", "YearToStart", "create_stage12_engine", + "local_area_result", "normalized_database_url", "report_run_result", "validate_runtime_database", diff --git a/libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/local_area_results.py b/libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/local_area_results.py new file mode 100644 index 000000000..b77294c0c --- /dev/null +++ b/libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/local_area_results.py @@ -0,0 +1,81 @@ +"""A local-area report run's area results as rows of the Public API's tables. + +A run of a UK-wide or nation report on the local-area dataset calculates the +constituency and local-authority results alone, as a +``LocalAreaBreakdownOutput``. They become ``constituency_impacts`` and +``local_authority_impacts`` rows, as a national result's areas do, and one +``withheld_area_codes`` row per area disclosure control withheld, each keyed +by the report run and its two simulation runs. The run's own data version is +its only result column; it stores no budget, decile, poverty, inequality, +programme, district or labour-supply rows. +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, Any +from uuid import uuid4 + +from policyengine_simulation_contract.macro_output import LocalAreaBreakdownOutput + +from policyengine_stage12_persistence.report_run_results import ( + ReportRunResult, + ResultRows, + area_record_rows, + constituency_impacts, + local_authority_impacts, + withheld_area_codes, +) + +if TYPE_CHECKING: + from collections.abc import Mapping + + from policyengine_simulation_contract.stage12_execution import ReportRunIds + + +def local_area_result( + output: Mapping[str, Any], *, run_ids: ReportRunIds +) -> ReportRunResult: + """Validate a local-area result and return what it is stored as. + + Raises ValueError (a pydantic ValidationError for another kind of result) + when it is not a local-area result, or does not list each level's + withheld codes: without them, an area with no row could be withheld or + never estimated. + """ + areas = LocalAreaBreakdownOutput.model_validate(output) + withheld = { + "constituency": areas.constituency_withheld_codes, + "local_authority": areas.local_authority_withheld_codes, + } + if any(codes is None for codes in withheld.values()): + msg = "a local-area result must list each level's withheld codes" + raise ValueError(msg) + keys = { + "report_run_id": run_ids.report_run_id, + "baseline_simulation_run_id": run_ids.baseline_simulation_run_id, + "reform_simulation_run_id": run_ids.reform_simulation_run_id, + } + return ReportRunResult( + report_run_columns={"data_version": areas.data_version}, + rows=( + ResultRows( + constituency_impacts, + area_record_rows(areas.constituency_impact, keys, "constituency"), + shared_by_reports=False, + ), + ResultRows( + local_authority_impacts, + area_record_rows(areas.local_authority_impact, keys, "local_authority"), + shared_by_reports=False, + ), + ResultRows( + withheld_area_codes, + tuple( + {"id": uuid4(), **keys, "area_type": area_type, "code": code} + for area_type, codes in withheld.items() + for code in codes or () + ), + shared_by_reports=False, + ), + ), + ) diff --git a/libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/report_run_results.py b/libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/report_run_results.py index fa077ac80..7362c3d2e 100644 --- a/libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/report_run_results.py +++ b/libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/report_run_results.py @@ -21,7 +21,7 @@ from policyengine_stage12_persistence.report_run_tables import metadata if TYPE_CHECKING: - from collections.abc import Mapping + from collections.abc import Mapping, Sequence from policyengine_simulation_contract.macro_output import ( AgePovertyOutput, @@ -38,6 +38,9 @@ from policyengine_simulation_contract.stage12_execution import ReportRunIds decile_type_type = ENUM("income", "wealth", name="v2_decile_type", create_type=False) +uk_area_type_type = ENUM( + "constituency", "local_authority", name="v2_uk_area_type", create_type=False +) def _report_run_keys() -> tuple[Column[Any], ...]: @@ -150,6 +153,15 @@ def _disclosure_values() -> tuple[Column[Any], ...]: Column("local_authority_code", String(64), nullable=False), Column("local_authority_name", String(255), nullable=False), ) +# The codes of the areas a local-area run estimated but disclosure control did +# not publish, one row per area: none means none were withheld. +withheld_area_codes = Table( + "withheld_area_codes", + metadata, + *_report_run_keys(), + Column("area_type", uk_area_type_type, nullable=False), + Column("code", String(64), nullable=False), +) budget_summary = Table( "budget_summary", metadata, @@ -536,7 +548,15 @@ def _area_rows( ) -> tuple[dict[str, Any], ...]: if areas is None: return () - records: list[ConstituencyImpactRecord | LocalAuthorityImpactRecord] = areas.root + return area_record_rows(areas.root, keys, kind) + + +def area_record_rows( + records: Sequence[ConstituencyImpactRecord | LocalAuthorityImpactRecord], + keys: Mapping[str, Any], + kind: Literal["constituency", "local_authority"], +) -> tuple[dict[str, Any], ...]: + """Return one area level's rows: each record's code, name, change and fields.""" return tuple( { "id": uuid4(), diff --git a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/report_run_recording.py b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/report_run_recording.py index d33056236..43d29ff46 100644 --- a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/report_run_recording.py +++ b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/report_run_recording.py @@ -18,6 +18,7 @@ from policyengine_stage12_persistence import ( DistrictCodes, RunStatus, + local_area_result, report_run_result, ) @@ -112,6 +113,21 @@ def complete(self, economy_output: Mapping[str, Any], *, country: str) -> RunWri ), ) + def complete_local_areas(self, area_output: Mapping[str, Any]) -> RunWrite: + """Mark a local-area report run succeeded, storing its area results. + + Its constituency, local-authority and withheld-code rows are written, + and its data version set, in the completion's transaction, only while + this call holds the run. An output that cannot be stored raises + ValueError. + """ + return self.writer.complete_report_run( + self.run_ids, + modal_call_id=self.modal_call_id, + completed_at=datetime.now(UTC), + result=local_area_result(area_output, run_ids=self.run_ids), + ) + def fail_quietly( self, detail: Stage12FailureDetail, *, runtime: ObservabilityRuntime | None ) -> None: From ef9eb1f366725278b04964cecccbd2f6b2043c67 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 23:38:55 +0400 Subject: [PATCH 16/44] Test the public rule for a simulation on the local-area dataset (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 ยท 26's stored output plans copy the area columns for a UK-wide or nation simulation on the local-area dataset, by the same rule the worker and the coordinator use. Co-Authored-By: Claude Opus 5.5 --- .../test_stage12_local_area_dataset_load.py | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py index 3c33d5f86..1951d761c 100644 --- a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py +++ b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py @@ -440,3 +440,26 @@ def test_a_us_report_is_no_local_area_report(monkeypatch) -> None: _route_uk_area_regions(monkeypatch) assert not local_area_datasets.is_local_area_report(report_execution_input()) + + +@pytest.mark.parametrize( + ("region", "identity", "on_local_area_dataset"), + [ + ("uk", LOCAL_AREA_DATASET, True), + ("country/wales", LOCAL_AREA_DATASET, True), + ("uk", NATIONAL_DATASET, False), + ("constituency/W07000081", LOCAL_AREA_DATASET, False), + ], +) +def test_a_simulation_is_on_the_local_area_dataset_by_its_region_and_dataset( + monkeypatch, region: str, identity: str, *, on_local_area_dataset: bool +) -> None: + # The rule a simulation's stored output plan uses for its area columns. + _route_uk_area_regions(monkeypatch) + + assert ( + local_area_datasets.calculates_on_local_area_dataset( + _uk_simulation(region, identity) + ) + is on_local_area_dataset + ) From 98a6144ff668972e10f0fc0f1168c7b01eb34861 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 23:39:11 +0400 Subject: [PATCH 17/44] Make the rule for a simulation on the local-area dataset public MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit calculates_on_local_area_dataset is the rule is_local_area_report and the worker's dataset check share; C1 ยท 26's stored output plans use it too. Co-Authored-By: Claude Opus 5.5 --- .../stage12_runtime/local_area_datasets.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/local_area_datasets.py b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/local_area_datasets.py index c845626ab..a0a1d3983 100644 --- a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/local_area_datasets.py +++ b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/local_area_datasets.py @@ -43,7 +43,7 @@ LOCAL_AREA_RUN_REGION_TYPES = frozenset({"national", "country"}) -def _calculates_on_local_area_dataset(simulation: SimulationExecutionInput) -> bool: +def calculates_on_local_area_dataset(simulation: SimulationExecutionInput) -> bool: """Whether ``simulation`` is of the UK or a nation, on the local-area dataset. That is the dataset the release routes UK area regions to, on a release @@ -65,7 +65,7 @@ def is_local_area_report(report: ReportExecutionInput) -> bool: links to the national report with the same policies, region and year. Both of a report's simulations share its dataset and region. """ - return _calculates_on_local_area_dataset(report.baseline) + return calculates_on_local_area_dataset(report.baseline) def named_local_area_dataset( @@ -78,7 +78,7 @@ def named_local_area_dataset( provenance names that dataset. The caller still checks the provenance's URI and revision against it. """ - if country.country != "uk" or not _calculates_on_local_area_dataset(simulation): + if country.country != "uk" or not calculates_on_local_area_dataset(simulation): return None identity = simulation.bundle.dataset.identity return next((item for item in country.datasets if item.identity == identity), None) From 06fda41995738da1adf6c7d622d352d872f067bc Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 23:41:35 +0400 Subject: [PATCH 18/44] Test the area columns of a UK simulation planned alone on the local-area dataset (failing) A simulation run the simulation service starts on its own may later be named by a local-area report, which reads the area columns. Today the plan copies them only for constituency and local-authority regions. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_stage12_output_planning.py | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/projects/policyengine-simulation-executor/tests/test_stage12_output_planning.py b/projects/policyengine-simulation-executor/tests/test_stage12_output_planning.py index ff79b5ea7..fa1cf53c3 100644 --- a/projects/policyengine-simulation-executor/tests/test_stage12_output_planning.py +++ b/projects/policyengine-simulation-executor/tests/test_stage12_output_planning.py @@ -401,6 +401,70 @@ def test_a_simulation_planned_alone_gets_its_self_comparisons_plan( assert plan.requirements.include_cliff_impacts is bool(options) +# The dataset a routing release assigns to UK constituency and local-authority +# regions, which a UK-wide or nation simulation may also be calculated on. +UK_LOCAL_AREA_DATASET = "microcosm_uk_2024_25_dense" + + +def _route_uk_area_regions_to_the_local_area_dataset(monkeypatch) -> None: + """Make the installed release route UK area regions to ``UK_LOCAL_AREA_DATASET``.""" + from policyengine_simulation_executor.stage12_runtime import local_area_datasets + + _route_uk_area_regions(monkeypatch, routed=True) + monkeypatch.setattr(local_area_datasets, "uk_area_regions_routed", lambda: True) + monkeypatch.setattr( + local_area_datasets, + "routed_uk_area_dataset_name", + lambda: UK_LOCAL_AREA_DATASET, + ) + + +def _on_dataset( + simulation: SimulationExecutionInput, dataset_name: str +) -> SimulationExecutionInput: + """Return ``simulation`` with its provenance naming the dataset ``dataset_name``.""" + dataset = simulation.bundle.dataset.model_copy( + update={ + "identity": dataset_name, + "uri": f"hf://policyengine/data/{dataset_name}.h5@revision", + } + ) + return simulation.model_copy( + update={"bundle": simulation.bundle.model_copy(update={"dataset": dataset})} + ) + + +@pytest.mark.parametrize( + ("region", "dataset_name", "copies_area_columns"), + [ + ("uk", UK_LOCAL_AREA_DATASET, True), + ("country/wales", UK_LOCAL_AREA_DATASET, True), + ("uk", "populace_uk_2023", False), + ("country/wales", "populace_uk_2023", False), + ], + ids=["uk-local-area", "wales-local-area", "uk-national", "wales-national"], +) +def test_a_uk_simulation_planned_alone_copies_area_columns_on_the_local_area_dataset( + monkeypatch, region: str, dataset_name: str, *, copies_area_columns: bool +) -> None: + from policyengine_simulation_executor import uk_local_authority_metadata + + _route_uk_area_regions_to_the_local_area_dataset(monkeypatch) + standalone = _on_dataset( + _simulation("uk", SimulationRole.STANDALONE, region=region), dataset_name + ) + + plan = resolve_simulation_output_plan(standalone) + + # A local-area report reading this run's file needs the area columns. + household = next(item for item in plan.entities if item.entity == "household") + assert household.dataset_variables == ( + uk_local_authority_metadata.UK_AREA_DATASET_COLUMNS + if copies_area_columns + else () + ) + + # Household columns a UK local-area report run's simulations must write: the # identifier, the income whose change disclosure control measures, the # weights, and the area columns copied from the local-area dataset. From 7486afc708100ac41ace8e31495e59eae6b5b0c4 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 23:43:03 +0400 Subject: [PATCH 19/44] Plan the area columns for a UK-wide or nation simulation on the local-area dataset MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The output plan copies UK_AREA_DATASET_COLUMNS for such a simulation too, by C1 ยท 23's rule (calculates_on_local_area_dataset), whether it is planned for a report or alone, so its run's file holds what a local-area report reads. Co-Authored-By: Claude Opus 5.5 --- .../stage12_runtime/output_planning.py | 25 +++++++++++++------ 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/output_planning.py b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/output_planning.py index 2348d358d..5b000b4fb 100644 --- a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/output_planning.py +++ b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/output_planning.py @@ -29,6 +29,8 @@ uk_area_codes_required, ) +from .local_area_datasets import calculates_on_local_area_dataset + if TYPE_CHECKING: import pandas as pd from policyengine_simulation_contract.stage12_bundle import CountryId @@ -120,9 +122,8 @@ def _include_cliff_impacts(simulation: SimulationExecutionInput) -> bool: def _required_dataset_variables( + simulation: SimulationExecutionInput, *, - country: CountryId, - region: str, aggregates: tuple[ReportAggregate, ...], ) -> dict[str, tuple[str, ...]]: """Return input-dataset columns copied into the materialized output. @@ -131,11 +132,21 @@ def _required_dataset_variables( simulations, except in a national or nation-level report whose bundle routes UK area regions to another dataset. Its national dataset may then carry no area codes, so none are planned, and the aggregate leaves the - area breakdowns out (``build_aggregate_report``). + area breakdowns out (``build_aggregate_report``). A UK-wide or nation + simulation on the dataset the release routes area regions to + (``calculates_on_local_area_dataset``) has them, and a local-area report + reads them, so they are planned there too, also when the simulation is + planned alone: its run's file then holds what a local-area report reads. """ - if country != "uk" or ReportAggregate.GEOGRAPHIC not in aggregates: + if ( + simulation.geography.country != "uk" + or ReportAggregate.GEOGRAPHIC not in aggregates + ): return {} - if not uk_area_codes_required(region): + if not ( + uk_area_codes_required(simulation.geography.region) + or calculates_on_local_area_dataset(simulation) + ): return {} return UK_GEOGRAPHIC_DATASET_VARIABLES @@ -283,9 +294,7 @@ def _resolve_output_plan( baseline_variables = model.resolve_entity_variables(baseline) reform_variables = model.resolve_entity_variables(reform) dataset_variables = _required_dataset_variables( - country=country, - region=baseline_input.geography.region, - aggregates=requirements.aggregates, + baseline_input, aggregates=requirements.aggregates ) entities = [] for entity in sorted( From 035703af0cb1ebd4362f9da60e1f46e6adbf6aa9 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 23:56:27 +0400 Subject: [PATCH 20/44] Plan a UK-wide report on the local-area dataset for its full results MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Under the data_source design a report on the local-area dataset returns its full results, cliffs included when asked, and its areas, so the area-only output plan (resolve_local_area_output_plan) and the contract's local-area aggregate profile go. The output plan's area columns come from C1 ยท 26's change, taken here; a test checks such a report plans every aggregate, its cliffs and the area columns. Co-Authored-By: Claude Opus 5.5 --- .../stage12_execution/__init__.py | 2 - .../stage12_execution/report_inputs.py | 33 +------ .../tests/test_stage12_execution.py | 39 -------- .../stage12_runtime/output_planning.py | 60 ------------ .../test_stage12_local_area_dataset_load.py | 3 +- .../tests/test_stage12_output_planning.py | 96 ++++--------------- 6 files changed, 22 insertions(+), 211 deletions(-) diff --git a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/__init__.py b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/__init__.py index 03aa8cb5b..982db91b3 100644 --- a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/__init__.py +++ b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/__init__.py @@ -48,7 +48,6 @@ Stage12InvocationContext, ) from policyengine_simulation_contract.stage12_execution.report_inputs import ( - LOCAL_AREA_AGGREGATES, EntityOutputPlan, PlannedSimulationExecutionInput, ReportAggregate, @@ -71,7 +70,6 @@ ) __all__ = [ - "LOCAL_AREA_AGGREGATES", "MAX_COMPARISON_RUN_ARTIFACT_RETENTION", "SIMULATION_PARQUET_PAYLOAD_CONTRACT", "AggregateReportArtifactDescriptor", diff --git a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/report_inputs.py b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/report_inputs.py index 145a0184a..8d4a4ea42 100644 --- a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/report_inputs.py +++ b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_execution/report_inputs.py @@ -35,18 +35,8 @@ class ReportAggregate(StrEnum): PROGRAM_STATISTICS = "program_statistics" -# A UK local-area report run's one aggregate: the constituency and -# local-authority impacts, with the codes disclosure control withholds. -LOCAL_AREA_AGGREGATES: tuple[ReportAggregate, ...] = (ReportAggregate.GEOGRAPHIC,) - - class ReportOutputRequirements(StrictContractModel): - """Report features that determine which simulation columns must exist. - - ``aggregates`` is either the complete profile, every ``ReportAggregate`` - in declaration order, or the local-area profile - (``LOCAL_AREA_AGGREGATES``), which calculates no cliff impacts. - """ + """Report features that determine which simulation columns must exist.""" schema_version: Literal[1] = 1 aggregates: Annotated[tuple[ReportAggregate, ...], Field(min_length=1)] @@ -55,32 +45,19 @@ class ReportOutputRequirements(StrictContractModel): @field_validator("aggregates") @classmethod - def require_a_supported_aggregate_profile( + def require_complete_aggregate_profile( cls, value: tuple[ReportAggregate, ...], ) -> tuple[ReportAggregate, ...]: - """Require the complete profile or the local-area profile, once each.""" + """Require every ``ReportAggregate``, once each and in declaration order.""" if len(value) != len(set(value)): msg = "report output aggregates must be unique" raise ValueError(msg) - if value not in (tuple(ReportAggregate), LOCAL_AREA_AGGREGATES): - msg = ( - "Stage 12 requires the complete aggregate profile or the " - "local-area profile" - ) + if value != tuple(ReportAggregate): + msg = "Stage 12 currently requires the complete aggregate profile" raise ValueError(msg) return value - @model_validator(mode="after") - def require_no_cliffs_in_the_local_area_profile( - self, - ) -> ReportOutputRequirements: - """Refuse cliff impacts with the local-area profile.""" - if self.aggregates == LOCAL_AREA_AGGREGATES and self.include_cliff_impacts: - msg = "the local-area profile calculates no cliff impacts" - raise ValueError(msg) - return self - class EntityOutputPlan(StrictContractModel): """Required materialized columns for one country-model entity.""" diff --git a/libs/policyengine-simulation-contract/tests/test_stage12_execution.py b/libs/policyengine-simulation-contract/tests/test_stage12_execution.py index 7a16bd1f7..6ac885892 100644 --- a/libs/policyengine-simulation-contract/tests/test_stage12_execution.py +++ b/libs/policyengine-simulation-contract/tests/test_stage12_execution.py @@ -13,7 +13,6 @@ build_spm_provenance, ) from policyengine_simulation_contract.stage12_execution import ( - LOCAL_AREA_AGGREGATES, SIMULATION_PARQUET_PAYLOAD_CONTRACT, AggregateReportArtifactPayload, BundleProvenance, @@ -268,41 +267,3 @@ def test_aggregate_artifact_accepts_only_canonical_spm_provenance() -> None: bundle=artifact.bundle, result={"spm_provenance": mismatched}, ) - - -def _requirements( - aggregates: tuple[ReportAggregate, ...], *, include_cliff_impacts: bool = False -) -> ReportOutputRequirements: - return ReportOutputRequirements( - aggregates=aggregates, - include_cliff_impacts=include_cliff_impacts, - labor_supply_response_active=False, - ) - - -def test_output_requirements_accept_the_local_area_profile() -> None: - requirements = _requirements(LOCAL_AREA_AGGREGATES) - - assert requirements.aggregates == (ReportAggregate.GEOGRAPHIC,) - - -def test_the_local_area_profile_calculates_no_cliff_impacts() -> None: - with pytest.raises(ValidationError, match="calculates no cliff impacts"): - _requirements(LOCAL_AREA_AGGREGATES, include_cliff_impacts=True) - - -@pytest.mark.parametrize( - "aggregates", - [ - (ReportAggregate.BUDGET,), - (ReportAggregate.GEOGRAPHIC, ReportAggregate.BUDGET), - tuple(reversed(ReportAggregate)), - ], -) -def test_output_requirements_refuse_any_other_partial_profile( - aggregates: tuple[ReportAggregate, ...], -) -> None: - with pytest.raises( - ValidationError, match="complete aggregate profile or the local-area profile" - ): - _requirements(aggregates) diff --git a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/output_planning.py b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/output_planning.py index 5b000b4fb..0281e8d24 100644 --- a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/output_planning.py +++ b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/output_planning.py @@ -13,7 +13,6 @@ labor_supply_response_is_active, ) from policyengine_simulation_contract.stage12_execution import ( - LOCAL_AREA_AGGREGATES, EntityOutputPlan, PlannedSimulationExecutionInput, ReportAggregate, @@ -40,15 +39,6 @@ UK_GEOGRAPHIC_DATASET_VARIABLES: dict[str, tuple[str, ...]] = { "household": UK_AREA_DATASET_COLUMNS, } -# Household columns a UK local-area report run's simulations calculate: the -# identifier both sides are matched on, the income whose change disclosure -# control measures, and the weights it estimates with. The UK model writes -# all three by default. -LOCAL_AREA_CALCULATED_HOUSEHOLD_VARIABLES = ( - "household_id", - "household_net_income", - "household_weight", -) class OutputVariableModel(Protocol): @@ -193,56 +183,6 @@ def resolve_report_output_plan( ) -def resolve_local_area_output_plan( - report: ReportExecutionInput, - *, - stage_scope: StageScope = _unmonitored_stage_scope, -) -> Stage12OutputPlan: - """Resolve the output schema of a UK local-area report run's two simulations. - - The run calculates only the constituency and local-authority impacts, so - each simulation writes the household columns disclosure control reads: - ``LOCAL_AREA_CALCULATED_HOUSEHOLD_VARIABLES``, and the area columns - (``UK_AREA_DATASET_COLUMNS``) copied from the local-area dataset whatever - the region. No cliff, labour-supply or budget variables are added, so the - columns are the same for every policy pair, and a local-area simulation - run's output serves any report with that simulation. - ``labor_supply_response_active`` still records whether the policies - activate labour-supply responses, which the reform's net income includes - either way. Raises ``ValueError`` for a report outside the UK, or one - with cliff impacts. - """ - country = report.baseline.geography.country - if country != "uk": - msg = f"a local-area report run is a UK report, not a {country!r} one" - raise ValueError(msg) - stage_attributes = {"country": country} - with stage_scope(Stage.STAGE12_COUNTRY_MODEL_LOAD, stage_attributes): - model = _country_model(country) - with stage_scope(Stage.STAGE12_OUTPUT_CONFIGURATION, stage_attributes): - requirements = ReportOutputRequirements( - aggregates=LOCAL_AREA_AGGREGATES, - include_cliff_impacts=_include_cliff_impacts(report.baseline), - labor_supply_response_active=labor_supply_response_is_active( - _planning_simulation(report.baseline, model=model), - _planning_simulation(report.reform, model=model), - country_code=country, - ), - ) - household = EntityOutputPlan( - entity="household", - materialized_variables=tuple( - sorted( - {*LOCAL_AREA_CALCULATED_HOUSEHOLD_VARIABLES, *UK_AREA_DATASET_COLUMNS} - ) - ), - dataset_variables=UK_AREA_DATASET_COLUMNS, - ) - return Stage12OutputPlan( - country=country, requirements=requirements, entities=(household,) - ) - - def resolve_simulation_output_plan( simulation: SimulationExecutionInput, *, diff --git a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py index 1951d761c..81930e534 100644 --- a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py +++ b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py @@ -17,7 +17,6 @@ Stage12RegionDataset, ) from policyengine_simulation_contract.stage12_execution import ( - LOCAL_AREA_AGGREGATES, BundleProvenance, DatasetArtifactMediaType, DatasetArtifactReference, @@ -163,7 +162,7 @@ def _uk_simulation( output_plan=Stage12OutputPlan( country="uk", requirements=ReportOutputRequirements( - aggregates=LOCAL_AREA_AGGREGATES, + aggregates=tuple(ReportAggregate), include_cliff_impacts=False, labor_supply_response_active=False, ), diff --git a/projects/policyengine-simulation-executor/tests/test_stage12_output_planning.py b/projects/policyengine-simulation-executor/tests/test_stage12_output_planning.py index fa1cf53c3..a7baa3259 100644 --- a/projects/policyengine-simulation-executor/tests/test_stage12_output_planning.py +++ b/projects/policyengine-simulation-executor/tests/test_stage12_output_planning.py @@ -10,7 +10,6 @@ import pytest from policyengine.core import Simulation from policyengine_simulation_contract.stage12_execution import ( - LOCAL_AREA_AGGREGATES, BundleProvenance, DatasetArtifactMediaType, DatasetArtifactReference, @@ -25,7 +24,6 @@ ) from policyengine_simulation_executor.stage12_runtime.output_planning import ( apply_output_plan, - resolve_local_area_output_plan, resolve_report_output_plan, resolve_simulation_output_plan, validate_output_frames, @@ -465,88 +463,26 @@ def test_a_uk_simulation_planned_alone_copies_area_columns_on_the_local_area_dat ) -# Household columns a UK local-area report run's simulations must write: the -# identifier, the income whose change disclosure control measures, the -# weights, and the area columns copied from the local-area dataset. -LOCAL_AREA_HOUSEHOLD_COLUMNS = { - "household_id", - "household_net_income", - "household_weight", - "constituency_code_oa", - "la_code_oa", - "region_code_oa", - "source_household_id", -} -UK_INCOME_ELASTICITY = "gov.simulation.labour_supply_responses.income_elasticity" - - -def _local_area_report( - *, region: str = "uk", reform: dict[str, JsonValue] | None = None -) -> ReportExecutionInput: - return _report("uk", region=region, reform=reform, aggregates=LOCAL_AREA_AGGREGATES) - - -@pytest.mark.parametrize("region", ["uk", "country/wales"]) -def test_a_local_area_plan_writes_only_the_household_columns_disclosure_reads( - region: str, +def test_a_uk_wide_report_on_the_local_area_dataset_plans_its_full_results( + monkeypatch, ) -> None: + # It returns its full results, cliffs included when asked, and its areas. from policyengine_simulation_executor import uk_local_authority_metadata - plan = resolve_local_area_output_plan(_local_area_report(region=region)) - - assert plan.country == "uk" - assert plan.requirements.aggregates == LOCAL_AREA_AGGREGATES - assert plan.requirements.include_cliff_impacts is False - assert [entity.entity for entity in plan.entities] == ["household"] - household = plan.entities[0] - assert set(household.materialized_variables) == LOCAL_AREA_HOUSEHOLD_COLUMNS - assert household.additional_variables == () - assert household.dataset_variables == ( - uk_local_authority_metadata.UK_AREA_DATASET_COLUMNS - ) - - -def test_a_local_area_plan_has_the_same_columns_for_every_policy_pair() -> None: - current_law = resolve_local_area_output_plan(_local_area_report()) - with_responses = resolve_local_area_output_plan( - _local_area_report(reform={UK_INCOME_ELASTICITY: 0.1}) - ) - - assert with_responses.requirements.labor_supply_response_active is True - assert current_law.requirements.labor_supply_response_active is False - assert with_responses.entities == current_law.entities - - -def test_a_local_area_plan_is_refused_for_a_us_report() -> None: - with pytest.raises(ValueError, match="UK"): - resolve_local_area_output_plan(_report("us", aggregates=LOCAL_AREA_AGGREGATES)) - - -def test_a_local_area_plan_is_refused_with_cliff_impacts() -> None: - report = _report( - "uk", include_cliffs=True, aggregates=LOCAL_AREA_AGGREGATES, region="uk" + _route_uk_area_regions_to_the_local_area_dataset(monkeypatch) + national = _report("uk", region="uk", include_cliffs=True) + report = national.model_copy( + update={ + "baseline": _on_dataset(national.baseline, UK_LOCAL_AREA_DATASET), + "reform": _on_dataset(national.reform, UK_LOCAL_AREA_DATASET), + } ) - with pytest.raises(ValueError, match="calculates no cliff impacts"): - resolve_local_area_output_plan(report) + plan = resolve_report_output_plan(report) - -def test_a_uk_simulation_satisfies_the_local_area_plan_without_extra_variables() -> ( - None -): - from policyengine.tax_benefit_models import uk - - plan = resolve_local_area_output_plan(_local_area_report()) - simulation = Simulation.model_construct( - policy={}, - dynamic=None, - dataset=None, - scoping_strategy=None, - extra_variables={}, - tax_benefit_model_version=uk.model, - output_dataset=None, + assert plan.requirements.aggregates == tuple(ReportAggregate) + assert plan.requirements.include_cliff_impacts is True + assert {"cliff_gap", "is_on_cliff"}.issubset(_additional_variables(plan, "person")) + assert _dataset_variables(plan, "household") == set( + uk_local_authority_metadata.UK_AREA_DATASET_COLUMNS ) - - apply_output_plan(simulation, plan) - - assert simulation.extra_variables == {"household": []} From 1b99f1d513db761603c2a0f2fd5fd0aa08add968 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 23:57:26 +0400 Subject: [PATCH 21/44] Test storing a UK result's withheld area codes (failing) A UK-wide report on the local-area dataset returns a national result, so its withheld area codes travel in that result and become withheld_area_codes rows when it is stored. The area-only result's tests go with the area-only output. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_local_area_results.py | 188 ------------------ .../tests/test_withheld_area_codes.py | 89 +++++++++ .../test_stage12_local_area_completion.py | 67 ------- 3 files changed, 89 insertions(+), 255 deletions(-) delete mode 100644 libs/policyengine-stage12-persistence/tests/test_local_area_results.py create mode 100644 libs/policyengine-stage12-persistence/tests/test_withheld_area_codes.py delete mode 100644 projects/policyengine-simulation-executor/tests/test_stage12_local_area_completion.py diff --git a/libs/policyengine-stage12-persistence/tests/test_local_area_results.py b/libs/policyengine-stage12-persistence/tests/test_local_area_results.py deleted file mode 100644 index adeaf2c98..000000000 --- a/libs/policyengine-stage12-persistence/tests/test_local_area_results.py +++ /dev/null @@ -1,188 +0,0 @@ -"""Tests for a local-area report run's area results as result-table rows.""" - -from __future__ import annotations - -from typing import Any -from uuid import UUID - -import pytest -from policyengine_simulation_contract.stage12_execution import ReportRunIds -from policyengine_stage12_persistence.local_area_results import local_area_result -from policyengine_stage12_persistence.report_run_results import ( - constituency_impacts, - local_authority_impacts, - withheld_area_codes, -) -from pydantic import ValidationError - -RUN_IDS = ReportRunIds( - report_run_id=UUID("00000000-0000-0000-0000-00000000000a"), - baseline_simulation_run_id=UUID("00000000-0000-0000-0000-00000000000b"), - reform_simulation_run_id=UUID("00000000-0000-0000-0000-00000000000c"), -) -RUN_KEYS = { - "report_run_id": RUN_IDS.report_run_id, - "baseline_simulation_run_id": RUN_IDS.baseline_simulation_run_id, - "reform_simulation_run_id": RUN_IDS.reform_simulation_run_id, -} -DISCLOSURE = { - "disclosure_tier": "reported", - "average_household_income_change_lower": -12.0, - "average_household_income_change_upper": -8.0, - "relative_household_income_change_lower": -0.0004, - "relative_household_income_change_upper": -0.0002, -} - - -def _area_output(**changes: Any) -> dict[str, Any]: - """Return a local-area result with two constituencies and one authority.""" - return { - "kind": "local_areas", - "model_version": "2.174.1", - "policyengine_version": "6.17.1", - "dataset": "microcosm_uk_2024_25_dense", - "data_version": "microcosm-uk-2024-25-dense-20261107T173210Z-38605444", - "constituency_impact": [ - { - "constituency_code": "E14001063", - "constituency_name": "Aldershot", - "average_household_income_change": -10.0, - "relative_household_income_change": -0.0003, - "population": 41_000.0, - **DISCLOSURE, - }, - { - "constituency_code": "W07000081", - "constituency_name": "Aberafan Maesteg", - "average_household_income_change": -9.0, - "relative_household_income_change": -0.0003, - "population": 38_000.0, - **DISCLOSURE, - "disclosure_tier": "approximate", - }, - ], - "local_authority_impact": [ - { - "local_authority_code": "E06000063", - "local_authority_name": "Cumberland", - "average_household_income_change": -11.0, - "relative_household_income_change": -0.0004, - "population": 120_000.0, - **DISCLOSURE, - } - ], - "constituency_withheld_codes": ["S14000045"], - "local_authority_withheld_codes": ["E06000064", "W06000015"], - **changes, - } - - -def _rows_by_table(output: dict[str, Any]) -> dict[str, list[dict[str, Any]]]: - result = local_area_result(output, run_ids=RUN_IDS) - return { - rows.table.name: [ - {name: value for name, value in row.items() if name != "id"} - for row in rows.rows - ] - for rows in result.rows - } - - -def test_a_local_area_result_stores_its_areas_and_withheld_codes() -> None: - rows = _rows_by_table(_area_output()) - - assert set(rows) == { - constituency_impacts.name, - local_authority_impacts.name, - withheld_area_codes.name, - } - assert rows["constituency_impacts"] == [ - { - **RUN_KEYS, - "constituency_code": "E14001063", - "constituency_name": "Aldershot", - "average_household_income_change": -10.0, - "relative_household_income_change": -0.0003, - "population": 41_000.0, - **DISCLOSURE, - }, - { - **RUN_KEYS, - "constituency_code": "W07000081", - "constituency_name": "Aberafan Maesteg", - "average_household_income_change": -9.0, - "relative_household_income_change": -0.0003, - "population": 38_000.0, - **DISCLOSURE, - "disclosure_tier": "approximate", - }, - ] - assert rows["local_authority_impacts"] == [ - { - **RUN_KEYS, - "local_authority_code": "E06000063", - "local_authority_name": "Cumberland", - "average_household_income_change": -11.0, - "relative_household_income_change": -0.0004, - "population": 120_000.0, - **DISCLOSURE, - } - ] - assert rows["withheld_area_codes"] == [ - {**RUN_KEYS, "area_type": "constituency", "code": "S14000045"}, - {**RUN_KEYS, "area_type": "local_authority", "code": "E06000064"}, - {**RUN_KEYS, "area_type": "local_authority", "code": "W06000015"}, - ] - - -def test_each_row_has_its_own_id() -> None: - result = local_area_result(_area_output(), run_ids=RUN_IDS) - - ids = [row["id"] for rows in result.rows for row in rows.rows] - assert len(ids) == len(set(ids)) == 6 - - -def test_a_local_area_result_sets_only_the_runs_data_version() -> None: - result = local_area_result(_area_output(), run_ids=RUN_IDS) - - assert result.report_run_columns == { - "data_version": "microcosm-uk-2024-25-dense-20261107T173210Z-38605444" - } - assert not any(rows.shared_by_reports for rows in result.rows) - - -def test_a_level_with_every_area_withheld_stores_no_area_rows() -> None: - rows = _rows_by_table( - _area_output( - constituency_impact=[], - constituency_withheld_codes=["E14001063", "W07000081"], - ) - ) - - assert rows["constituency_impacts"] == [] - assert [row["code"] for row in rows["withheld_area_codes"]] == [ - "E14001063", - "W07000081", - "E06000064", - "W06000015", - ] - - -@pytest.mark.parametrize( - "missing", ["constituency_withheld_codes", "local_authority_withheld_codes"] -) -def test_a_local_area_result_without_its_withheld_codes_is_refused( - missing: str, -) -> None: - # A Stage 12 run always lists them; null means an older result format, - # where "none withheld" and "not reported" can't be told apart. - output = _area_output() - del output[missing] - - with pytest.raises(ValueError, match="withheld"): - local_area_result(output, run_ids=RUN_IDS) - - -def test_a_national_economy_result_is_refused() -> None: - with pytest.raises(ValidationError, match="kind"): - local_area_result({"budget": {}}, run_ids=RUN_IDS) diff --git a/libs/policyengine-stage12-persistence/tests/test_withheld_area_codes.py b/libs/policyengine-stage12-persistence/tests/test_withheld_area_codes.py new file mode 100644 index 000000000..c7805ac22 --- /dev/null +++ b/libs/policyengine-stage12-persistence/tests/test_withheld_area_codes.py @@ -0,0 +1,89 @@ +"""Tests for the withheld area codes of a UK result, as result-table rows.""" + +from __future__ import annotations + +from typing import Any +from uuid import UUID + +from economy_output import uk_economy_output, uk_output_with_areas +from policyengine_simulation_contract.macro_output import SingleYearMacroOutput +from policyengine_simulation_contract.stage12_execution import ReportRunIds +from policyengine_stage12_persistence.report_run_results import ( + report_run_result, + withheld_area_codes, +) + +RUN_IDS = ReportRunIds( + report_run_id=UUID("00000000-0000-0000-0000-00000000000a"), + baseline_simulation_run_id=UUID("00000000-0000-0000-0000-00000000000b"), + reform_simulation_run_id=UUID("00000000-0000-0000-0000-00000000000c"), +) +RUN_KEYS = { + "report_run_id": RUN_IDS.report_run_id, + "baseline_simulation_run_id": RUN_IDS.baseline_simulation_run_id, + "reform_simulation_run_id": RUN_IDS.reform_simulation_run_id, +} + + +def _withheld_rows(output: dict[str, Any]) -> list[dict[str, Any]]: + result = report_run_result(output, run_ids=RUN_IDS, country="uk") + (rows,) = [rows for rows in result.rows if rows.table is withheld_area_codes] + assert rows.shared_by_reports is False + return [ + {name: value for name, value in row.items() if name != "id"} + for row in rows.rows + ] + + +def test_a_uk_result_stores_one_row_per_withheld_area() -> None: + output = { + **uk_output_with_areas(), + "constituency_withheld_codes": ["S14000045"], + "local_authority_withheld_codes": ["E06000064", "W06000015"], + } + + assert _withheld_rows(output) == [ + {**RUN_KEYS, "area_type": "constituency", "code": "S14000045"}, + {**RUN_KEYS, "area_type": "local_authority", "code": "E06000064"}, + {**RUN_KEYS, "area_type": "local_authority", "code": "W06000015"}, + ] + + +def test_withheld_rows_have_their_own_ids() -> None: + output = { + **uk_output_with_areas(), + "constituency_withheld_codes": ["S14000045", "S14000046"], + "local_authority_withheld_codes": [], + } + result = report_run_result(output, run_ids=RUN_IDS, country="uk") + + (rows,) = [rows for rows in result.rows if rows.table is withheld_area_codes] + assert len({row["id"] for row in rows.rows}) == 2 + + +def test_a_result_that_lists_no_withheld_codes_stores_none() -> None: + assert _withheld_rows(uk_output_with_areas()) == [] + + +def test_a_result_without_withheld_codes_dumps_as_before() -> None: + # National results, and every result calculated before the field, are + # written and compared exactly as they were. + dumped = SingleYearMacroOutput.model_validate(uk_economy_output()).model_dump( + mode="json" + ) + + assert "constituency_withheld_codes" not in dumped + assert "local_authority_withheld_codes" not in dumped + + +def test_a_result_with_withheld_codes_keeps_them() -> None: + output = { + **uk_output_with_areas(), + "constituency_withheld_codes": [], + "local_authority_withheld_codes": ["E06000064"], + } + + dumped = SingleYearMacroOutput.model_validate(output).model_dump(mode="json") + + assert dumped["constituency_withheld_codes"] == [] + assert dumped["local_authority_withheld_codes"] == ["E06000064"] diff --git a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_completion.py b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_completion.py deleted file mode 100644 index 35b4af826..000000000 --- a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_completion.py +++ /dev/null @@ -1,67 +0,0 @@ -"""Tests for completing a local-area report run with its area results.""" - -from __future__ import annotations - -from dataclasses import dataclass, field -from typing import Any - -from policyengine_simulation_executor.stage12_runtime.report_run_recording import ( - ReportRunRecorder, -) -from policyengine_stage12_persistence import RunStatus, RunWrite -from policyengine_stage12_persistence.local_area_results import local_area_result -from stage12_fake_report_runs import REPORT_RUN_IDS - -MODAL_CALL_ID = "fc-local-area-coordinator" -AREA_OUTPUT = { - "kind": "local_areas", - "model_version": "2.174.1", - "policyengine_version": "6.17.1", - "dataset": "microcosm_uk_2024_25_dense", - "data_version": "microcosm-uk-2024-25-dense-20261107T173210Z-38605444", - "constituency_impact": [], - "local_authority_impact": [], - "constituency_withheld_codes": ["S14000045"], - "local_authority_withheld_codes": [], -} - - -@dataclass -class _CompletionWriter: - """Records each completion a recorder asks for.""" - - completions: list[dict[str, Any]] = field(default_factory=list) - - def complete_report_run( - self, run_ids, *, modal_call_id, completed_at, result=None - ) -> RunWrite: - self.completions.append( - {"run_ids": run_ids, "modal_call_id": modal_call_id, "result": result} - ) - return RunWrite(changed=True, status=RunStatus.SUCCEEDED) - - -def test_a_local_area_completion_stores_the_area_rows_under_the_calls_claim() -> None: - writer = _CompletionWriter() - recorder = ReportRunRecorder( - writer=writer, # pyright: ignore[reportArgumentType] - run_ids=REPORT_RUN_IDS, - modal_call_id=MODAL_CALL_ID, - ) - - written = recorder.complete_local_areas(AREA_OUTPUT) - - assert written == RunWrite(changed=True, status=RunStatus.SUCCEEDED) - (completion,) = writer.completions - assert completion["run_ids"] == REPORT_RUN_IDS - assert completion["modal_call_id"] == MODAL_CALL_ID - expected = local_area_result(AREA_OUTPUT, run_ids=REPORT_RUN_IDS) - stored = completion["result"] - assert stored.report_run_columns == expected.report_run_columns - assert [ - (rows.table.name, [{**row, "id": None} for row in rows.rows]) - for rows in stored.rows - ] == [ - (rows.table.name, [{**row, "id": None} for row in rows.rows]) - for rows in expected.rows - ] From 46c38f07e325823bbbb6a0831c8121c0577c731a Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 23:59:41 +0400 Subject: [PATCH 22/44] Store the withheld area codes a UK result lists SingleYearMacroOutput gains constituency_withheld_codes and local_authority_withheld_codes, left out of the JSON when null so every other result is written and compared as before, and report_run_result writes one withheld_area_codes row per code. A UK-wide report on the local-area dataset returns a national result, so the area-only result (local_area_result, complete_local_areas) goes. The gateway's golden OpenAPI spec gains the two fields. Co-Authored-By: Claude Opus 5.5 --- .../macro_output.py | 24 ++++-- .../__init__.py | 2 - .../local_area_results.py | 81 ------------------- .../report_run_results.py | 32 +++++--- .../stage12_runtime/report_run_recording.py | 16 ---- .../tests/golden/openapi.json | 30 ++++++- 6 files changed, 70 insertions(+), 115 deletions(-) delete mode 100644 libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/local_area_results.py diff --git a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/macro_output.py b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/macro_output.py index 4fbd2aa01..696b83b86 100644 --- a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/macro_output.py +++ b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/macro_output.py @@ -325,8 +325,20 @@ class CongressionalDistrictImpactOutput(MacroOutputModel): districts: list[CongressionalDistrictImpactRecord] +def _is_none(value: object) -> bool: + return value is None + + class SingleYearMacroOutput(MacroOutputModel): - """Completed response returned by a single-year macro simulation.""" + """Completed response returned by a single-year macro simulation. + + ``constituency_withheld_codes`` and ``local_authority_withheld_codes`` + hold, sorted, the codes of each level's areas the run estimated but + disclosure control did not publish, as ``LocalAreaBreakdownOutput``'s do. + Stage 12 lists them for a UK-wide report on the local-area dataset; null + means the result does not report them, and the JSON then leaves both + keys out, so every other result is written as before. + """ spm_provenance: SPMComparisonProvenance | None = None @@ -346,13 +358,15 @@ class SingleYearMacroOutput(MacroOutputModel): constituency_impact: GeographicImpactOutput | None local_authority_impact: GeographicImpactOutput | None congressional_district_impact: CongressionalDistrictImpactOutput | None + constituency_withheld_codes: list[str] | None = Field( + default=None, exclude_if=_is_none + ) + local_authority_withheld_codes: list[str] | None = Field( + default=None, exclude_if=_is_none + ) cliff_impact: CliffImpactOutput | None = None -def _is_none(value: object) -> bool: - return value is None - - class LocalAreaBreakdownOutput(MacroOutputModel): """Completed result of a UK local-area breakdown run. diff --git a/libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/__init__.py b/libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/__init__.py index e2b48bbbf..7e86cb336 100644 --- a/libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/__init__.py +++ b/libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/__init__.py @@ -11,7 +11,6 @@ from policyengine_stage12_persistence.household_report_run_store import ( HouseholdReportRunStore, ) -from policyengine_stage12_persistence.local_area_results import local_area_result from policyengine_stage12_persistence.report_run_results import ( DistrictCodes, ReportRunResult, @@ -56,7 +55,6 @@ "YearStarter", "YearToStart", "create_stage12_engine", - "local_area_result", "normalized_database_url", "report_run_result", "validate_runtime_database", diff --git a/libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/local_area_results.py b/libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/local_area_results.py deleted file mode 100644 index b77294c0c..000000000 --- a/libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/local_area_results.py +++ /dev/null @@ -1,81 +0,0 @@ -"""A local-area report run's area results as rows of the Public API's tables. - -A run of a UK-wide or nation report on the local-area dataset calculates the -constituency and local-authority results alone, as a -``LocalAreaBreakdownOutput``. They become ``constituency_impacts`` and -``local_authority_impacts`` rows, as a national result's areas do, and one -``withheld_area_codes`` row per area disclosure control withheld, each keyed -by the report run and its two simulation runs. The run's own data version is -its only result column; it stores no budget, decile, poverty, inequality, -programme, district or labour-supply rows. -""" - -from __future__ import annotations - -from typing import TYPE_CHECKING, Any -from uuid import uuid4 - -from policyengine_simulation_contract.macro_output import LocalAreaBreakdownOutput - -from policyengine_stage12_persistence.report_run_results import ( - ReportRunResult, - ResultRows, - area_record_rows, - constituency_impacts, - local_authority_impacts, - withheld_area_codes, -) - -if TYPE_CHECKING: - from collections.abc import Mapping - - from policyengine_simulation_contract.stage12_execution import ReportRunIds - - -def local_area_result( - output: Mapping[str, Any], *, run_ids: ReportRunIds -) -> ReportRunResult: - """Validate a local-area result and return what it is stored as. - - Raises ValueError (a pydantic ValidationError for another kind of result) - when it is not a local-area result, or does not list each level's - withheld codes: without them, an area with no row could be withheld or - never estimated. - """ - areas = LocalAreaBreakdownOutput.model_validate(output) - withheld = { - "constituency": areas.constituency_withheld_codes, - "local_authority": areas.local_authority_withheld_codes, - } - if any(codes is None for codes in withheld.values()): - msg = "a local-area result must list each level's withheld codes" - raise ValueError(msg) - keys = { - "report_run_id": run_ids.report_run_id, - "baseline_simulation_run_id": run_ids.baseline_simulation_run_id, - "reform_simulation_run_id": run_ids.reform_simulation_run_id, - } - return ReportRunResult( - report_run_columns={"data_version": areas.data_version}, - rows=( - ResultRows( - constituency_impacts, - area_record_rows(areas.constituency_impact, keys, "constituency"), - shared_by_reports=False, - ), - ResultRows( - local_authority_impacts, - area_record_rows(areas.local_authority_impact, keys, "local_authority"), - shared_by_reports=False, - ), - ResultRows( - withheld_area_codes, - tuple( - {"id": uuid4(), **keys, "area_type": area_type, "code": code} - for area_type, codes in withheld.items() - for code in codes or () - ), - shared_by_reports=False, - ), - ), - ) diff --git a/libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/report_run_results.py b/libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/report_run_results.py index 7362c3d2e..78ff3b86e 100644 --- a/libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/report_run_results.py +++ b/libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/report_run_results.py @@ -21,7 +21,7 @@ from policyengine_stage12_persistence.report_run_tables import metadata if TYPE_CHECKING: - from collections.abc import Mapping, Sequence + from collections.abc import Mapping from policyengine_simulation_contract.macro_output import ( AgePovertyOutput, @@ -391,6 +391,11 @@ def report_run_result( ), shared_by_reports=False, ), + ResultRows( + withheld_area_codes, + _withheld_rows(economy, report_keys), + shared_by_reports=False, + ), ), ) @@ -548,15 +553,7 @@ def _area_rows( ) -> tuple[dict[str, Any], ...]: if areas is None: return () - return area_record_rows(areas.root, keys, kind) - - -def area_record_rows( - records: Sequence[ConstituencyImpactRecord | LocalAuthorityImpactRecord], - keys: Mapping[str, Any], - kind: Literal["constituency", "local_authority"], -) -> tuple[dict[str, Any], ...]: - """Return one area level's rows: each record's code, name, change and fields.""" + records: list[ConstituencyImpactRecord | LocalAuthorityImpactRecord] = areas.root return tuple( { "id": uuid4(), @@ -574,6 +571,21 @@ def area_record_rows( ) +def _withheld_rows( + economy: SingleYearMacroOutput, keys: Mapping[str, Any] +) -> tuple[dict[str, Any], ...]: + """Return a row per area disclosure control withheld, for the levels it lists.""" + levels = ( + ("constituency", economy.constituency_withheld_codes), + ("local_authority", economy.local_authority_withheld_codes), + ) + return tuple( + {"id": uuid4(), **keys, "area_type": area_type, "code": code} + for area_type, codes in levels + for code in codes or () + ) + + def _budget_rows( economy: SingleYearMacroOutput, keys: Mapping[str, Any], country: str ) -> tuple[dict[str, Any], ...]: diff --git a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/report_run_recording.py b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/report_run_recording.py index 43d29ff46..d33056236 100644 --- a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/report_run_recording.py +++ b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/report_run_recording.py @@ -18,7 +18,6 @@ from policyengine_stage12_persistence import ( DistrictCodes, RunStatus, - local_area_result, report_run_result, ) @@ -113,21 +112,6 @@ def complete(self, economy_output: Mapping[str, Any], *, country: str) -> RunWri ), ) - def complete_local_areas(self, area_output: Mapping[str, Any]) -> RunWrite: - """Mark a local-area report run succeeded, storing its area results. - - Its constituency, local-authority and withheld-code rows are written, - and its data version set, in the completion's transaction, only while - this call holds the run. An output that cannot be stored raises - ValueError. - """ - return self.writer.complete_report_run( - self.run_ids, - modal_call_id=self.modal_call_id, - completed_at=datetime.now(UTC), - result=local_area_result(area_output, run_ids=self.run_ids), - ) - def fail_quietly( self, detail: Stage12FailureDetail, *, runtime: ObservabilityRuntime | None ) -> None: diff --git a/projects/policyengine-simulation-gateway/tests/golden/openapi.json b/projects/policyengine-simulation-gateway/tests/golden/openapi.json index e1397025e..81eb77ab2 100644 --- a/projects/policyengine-simulation-gateway/tests/golden/openapi.json +++ b/projects/policyengine-simulation-gateway/tests/golden/openapi.json @@ -2657,6 +2657,34 @@ } ] }, + "constituency_withheld_codes": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Constituency Withheld Codes" + }, + "local_authority_withheld_codes": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Local Authority Withheld Codes" + }, "cliff_impact": { "anyOf": [ { @@ -2689,7 +2717,7 @@ "congressional_district_impact" ], "title": "SingleYearMacroOutput", - "description": "Completed response returned by a single-year macro simulation." + "description": "Completed response returned by a single-year macro simulation.\n\n``constituency_withheld_codes`` and ``local_authority_withheld_codes``\nhold, sorted, the codes of each level's areas the run estimated but\ndisclosure control did not publish, as ``LocalAreaBreakdownOutput``'s do.\nStage 12 lists them for a UK-wide report on the local-area dataset; null\nmeans the result does not report them, and the JSON then leaves both\nkeys out, so every other result is written as before." }, "TelemetryEnvelope": { "properties": { From 71d1a5535c77c01b4ede25ce92fa76b8eeddd26a Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:00:11 +0400 Subject: [PATCH 23/44] Describe local-area report runs as returning full results and areas Under the data_source design a report on the local-area dataset returns its full results as well as its area results, so the manifest declaration, the recognition rule's docstring and the Stage 12 doc say so. Co-Authored-By: Claude Opus 5.5 --- docs/migration/stage-12-modal-worker-foundation.md | 4 ++-- .../stage12_manifest_models.py | 10 +++++----- .../stage12_runtime/local_area_datasets.py | 9 +++++---- 3 files changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/migration/stage-12-modal-worker-foundation.md b/docs/migration/stage-12-modal-worker-foundation.md index d11c16269..986f97068 100644 --- a/docs/migration/stage-12-modal-worker-foundation.md +++ b/docs/migration/stage-12-modal-worker-foundation.md @@ -694,8 +694,8 @@ change, once no deployed or rollback revision reads them. The UK entry's `local_area_reports` says that the worker's coordinator runs UK local-area report runs, the runs of UK-wide and nation reports on the -local-area dataset, which calculate the constituency and local-authority -results alone: the version of the runs it accepts (`input_version`, +local-area dataset, which calculate their full results and their +constituency and local-authority results, with withheld codes: the version of the runs it accepts (`input_version`, `LOCAL_AREA_REPORTS_VERSION`) and the local-area dataset (`dataset`). That dataset is the one the release routes constituency and local-authority regions to, or null when it routes them to no dataset of their own and a diff --git a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_manifest_models.py b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_manifest_models.py index 3a214d01a..3657bf97f 100644 --- a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_manifest_models.py +++ b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_manifest_models.py @@ -26,10 +26,10 @@ _MAX_MODAL_APPLICATION_NAME_LENGTH = 64 _CALLABLE_PATTERN = re.compile(r"^[a-z][a-z0-9_]{0,127}$") # The local-area report runs a coordinator runs: a run of a UK-wide or nation -# report on the local-area dataset, given as any report run is, calculates the -# constituency and local-authority results alone, with the codes disclosure -# control withholds. A later change to what such a run accepts or writes -# raises it. +# report on the local-area dataset, given as any report run is, calculates its +# full results and its constituency and local-authority results, with the +# codes disclosure control withholds. A later change to what such a run +# accepts or writes raises it. LOCAL_AREA_REPORTS_VERSION = 1 ManifestText = Annotated[str, Field(min_length=1, max_length=255)] @@ -48,7 +48,7 @@ class LocalAreaReports(StrictManifestModel): ``input_version`` is the ``LOCAL_AREA_REPORTS_VERSION`` of the runs it accepts. ``dataset`` is the local-area dataset, which the release routes constituency and local-authority regions to: a run of a UK-wide or nation - report on it calculates the area results alone. It is None when the + report on it also calculates the area results. It is None when the release routes them to no dataset of their own, so a UK-wide or nation run on the national dataset calculates both area levels itself. The worker decides both by the rule its national aggregation uses diff --git a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/local_area_datasets.py b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/local_area_datasets.py index a0a1d3983..fb089be9f 100644 --- a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/local_area_datasets.py +++ b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/local_area_datasets.py @@ -58,12 +58,13 @@ def calculates_on_local_area_dataset(simulation: SimulationExecutionInput) -> bo def is_local_area_report(report: ReportExecutionInput) -> bool: - """Whether a run of ``report`` calculates the UK area results alone. + """Whether a run of ``report`` also calculates the UK area results. It does for a report of the UK or a nation whose simulations are on the - local-area dataset: an ordinary report, which the simulation service - links to the national report with the same policies, region and year. - Both of a report's simulations share its dataset and region. + local-area dataset, an ordinary report a request asks for with + ``data_source``: it returns its full results and its constituency and + local-authority results, with their withheld codes. Both of a report's + simulations share its dataset and region. """ return calculates_on_local_area_dataset(report.baseline) From f41fe2689aa229dad3c3342ab83c201e8750e205 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:04:52 +0400 Subject: [PATCH 24/44] Test the area results of a UK-wide report on the local-area dataset (failing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 ยท 21's decision 14: Stage 12's national aggregation stops leaving the areas out of a report on the local-area dataset and reads the withheld codes from the same disclosure pass. A UK-wide report on the national dataset still leaves them out, and an area report lists no withheld codes. Co-Authored-By: Claude Opus 5.5 --- .../test_stage12_local_area_aggregation.py | 228 ++++++++++++++++++ 1 file changed, 228 insertions(+) create mode 100644 projects/policyengine-simulation-executor/tests/test_stage12_local_area_aggregation.py diff --git a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_aggregation.py b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_aggregation.py new file mode 100644 index 000000000..f7853dae1 --- /dev/null +++ b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_aggregation.py @@ -0,0 +1,228 @@ +"""Tests for the area results of a UK-wide report on the local-area dataset.""" + +from __future__ import annotations + +from typing import Any + +import pandas as pd +import pytest +from policyengine_simulation_contract.stage12_execution import ReportExecutionInput +from policyengine_simulation_executor import ( + simulation_output_builder, + simulation_output_geographic, +) +from policyengine_simulation_executor.simulation_output_builder import ( + SimulationOutputBuilder, +) +from policyengine_simulation_executor.simulation_output_geographic import ( + UKAreaIncomeChange, + UKGeographyDisclosureOutput, +) +from policyengine_simulation_executor.stage12_runtime import ( + RetainedSimulationOutput, + build_aggregate_report, + local_area_datasets, +) +from stage12_fake_stores import FakeArtifacts +from stage12_runtime_support import bundle_provenance, report_execution_input + +NATIONAL_DATASET = "microcosm_uk_2024_25" +LOCAL_AREA_DATASET = "microcosm_uk_2024_25_dense" +UK_REFORM = { + "gov.hmrc.income_tax.charges.CB_HITC.phase_out_start": { + "2026-01-01.2100-12-31": 70_000 + } +} +PUBLISHED = UKAreaIncomeChange( + tier="reported", + average=-10.0, + average_lower=-12.0, + average_upper=-8.0, + relative=-0.0003, + relative_lower=-0.0004, + relative_upper=-0.0002, + population=41_000.0, +) +# Two constituencies and two authorities estimated; one of each published. +DISCLOSURE = UKGeographyDisclosureOutput( + areas={ + "constituency": {"E14001063": PUBLISHED}, + "local_authority": {"E06000063": PUBLISHED}, + }, + estimated={ + "constituency": frozenset({"E14001063", "W07000081"}), + "local_authority": frozenset({"E06000063", "W06000015", "E06000064"}), + }, +) + + +def _route_uk_area_regions(monkeypatch) -> None: + """Make the installed release route UK area regions to the local-area dataset.""" + monkeypatch.setattr( + "policyengine_simulation_executor.uk_local_authority_metadata." + "uk_area_regions_routed", + lambda: True, + ) + monkeypatch.setattr(local_area_datasets, "uk_area_regions_routed", lambda: True) + monkeypatch.setattr( + local_area_datasets, "routed_uk_area_dataset_name", lambda: LOCAL_AREA_DATASET + ) + + +def _uk_report(*, region: str, dataset: str) -> ReportExecutionInput: + """Return a UK report whose two simulations are on ``dataset``.""" + provenance = bundle_provenance() + bundle = provenance.model_copy( + update={ + "country_package_name": "policyengine-uk", + "country_package_version": "2.174.1", + "dataset": provenance.dataset.model_copy( + update={ + "identity": dataset, + "uri": f"hf://policyengine/microcosm-uk/{dataset}.h5@revision", + } + ), + } + ) + payload = report_execution_input().model_dump(mode="json") + for role, policy in (("baseline", {}), ("reform", UK_REFORM)): + payload[role].update( + { + "policy": policy, + "geography": {"country": "uk", "region": region}, + "bundle": bundle.model_dump(mode="json"), + "population": { + "kind": "dataset", + "artifact": { + "uri": bundle.dataset.uri, + "media_type": "application/x-hdf5", + "content_sha256": "a" * 64, + }, + }, + } + ) + return ReportExecutionInput.model_validate(payload) + + +class _CapturingBuilder: + """Stands in for the output builder: records its fields, lists codes.""" + + built: dict[str, Any] + + def __init__(self, **values: Any) -> None: + type(self).built = values + + def serialize(self) -> dict[str, Any]: + return {"constituency_impact": [], "local_authority_impact": []} + + def uk_withheld_area_codes(self) -> dict[str, list[str]]: + return { + "constituency": ["W07000081"], + "local_authority": ["E06000064", "W06000015"], + } + + +def _aggregate(monkeypatch, report: ReportExecutionInput) -> dict[str, Any]: + monkeypatch.setattr( + simulation_output_builder, "SimulationOutputBuilder", _CapturingBuilder + ) + frames = { + entity: pd.DataFrame({f"{entity}_id": [1]}) + for entity in ("person", "benunit", "household") + } + artifacts = FakeArtifacts() + return build_aggregate_report( + report=report, + baseline=RetainedSimulationOutput( + frames, artifacts.add_simulation(report.baseline) + ), + reform=RetainedSimulationOutput( + frames, artifacts.add_simulation(report.reform) + ), + )["result"] + + +def test_a_uk_wide_report_on_the_local_area_dataset_gets_its_areas( + monkeypatch, +) -> None: + _route_uk_area_regions(monkeypatch) + + result = _aggregate( + monkeypatch, _uk_report(region="uk", dataset=LOCAL_AREA_DATASET) + ) + + assert _CapturingBuilder.built["omit_uk_area_breakdowns"] is False + assert result["constituency_withheld_codes"] == ["W07000081"] + assert result["local_authority_withheld_codes"] == ["E06000064", "W06000015"] + + +def test_a_uk_wide_report_on_the_national_dataset_still_leaves_its_areas_out( + monkeypatch, +) -> None: + _route_uk_area_regions(monkeypatch) + + result = _aggregate(monkeypatch, _uk_report(region="uk", dataset=NATIONAL_DATASET)) + + assert _CapturingBuilder.built["omit_uk_area_breakdowns"] is True + assert "constituency_withheld_codes" not in result + assert "local_authority_withheld_codes" not in result + + +@pytest.mark.parametrize( + "region", ["constituency/E14001063", "local_authority/E06000063"] +) +def test_an_area_report_keeps_its_area_and_lists_no_withheld_codes( + monkeypatch, region: str +) -> None: + # Its result, and its comparison with production, stay as they are. + _route_uk_area_regions(monkeypatch) + + result = _aggregate( + monkeypatch, _uk_report(region=region, dataset=LOCAL_AREA_DATASET) + ) + + assert _CapturingBuilder.built["omit_uk_area_breakdowns"] is False + assert "constituency_withheld_codes" not in result + + +def test_the_builder_lists_each_levels_withheld_codes_from_its_disclosure_pass( + monkeypatch, +) -> None: + passes = [] + + def disclose(*_args, **_kwargs) -> UKGeographyDisclosureOutput: + passes.append(1) + return DISCLOSURE + + monkeypatch.setattr( + simulation_output_geographic, "compute_uk_geography_disclosure_output", disclose + ) + builder = SimulationOutputBuilder( + country="uk", + simulation_params={"time_period": "2026"}, + country_module=None, + dataset=None, + baseline=None, + reform=None, + ) + + assert builder.uk_withheld_area_codes() == { + "constituency": ["W07000081"], + "local_authority": ["E06000064", "W06000015"], + } + # The codes come from the disclosure pass the area results use. + builder.uk_withheld_area_codes() + assert len(passes) == 1 + + +def test_a_builder_outside_the_uk_lists_no_withheld_codes() -> None: + builder = SimulationOutputBuilder( + country="us", + simulation_params={}, + country_module=None, + dataset=None, + baseline=None, + reform=None, + ) + + assert builder.uk_withheld_area_codes() is None From 2673e524b86ecc0a3983660f85a1a17d1dbb4656 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:05:41 +0400 Subject: [PATCH 25/44] Build a UK-wide local-area report's areas and withheld codes in its aggregation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 ยท 21's decision 14: build_aggregate_report stops leaving the constituency and local-authority results out of a report on the local-area dataset (is_local_area_report), and adds each level's withheld codes from the same disclosure pass, through the new SimulationOutputBuilder.uk_withheld_area_codes. Other reports, and their comparison with production, are unchanged. Co-Authored-By: Claude Opus 5.5 --- .../simulation_output_builder.py | 14 +++++++++++ .../stage12_runtime/aggregation.py | 23 ++++++++++++++----- 2 files changed, 31 insertions(+), 6 deletions(-) diff --git a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/simulation_output_builder.py b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/simulation_output_builder.py index 7afbd7252..ce85849ed 100644 --- a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/simulation_output_builder.py +++ b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/simulation_output_builder.py @@ -291,6 +291,20 @@ def _uk_geography_disclosure_output( ) return self._uk_geography_disclosure + def uk_withheld_area_codes(self) -> dict[str, list[str]] | None: + """Return each UK level's withheld area codes, sorted; None outside the UK. + + They are the areas the disclosure pass behind the area results + estimated but did not publish, from that same pass. + """ + disclosure = self._uk_geography_disclosure_output() + if disclosure is None: + return None + return { + level: disclosure.withheld_codes(level) + for level in ("constituency", "local_authority") + } + def _simulation_year(self) -> int: """Return the simulated year, which labels the disclosure release.""" for value in ( diff --git a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/aggregation.py b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/aggregation.py index 24bde0c91..7c9e65bdd 100644 --- a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/aggregation.py +++ b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/aggregation.py @@ -175,7 +175,9 @@ def build_aggregate_report( the stored frames, so no model is recomputed. A UK national or nation-level report whose bundle routes area regions to another dataset has no area codes in its frames (see ``output_planning``), so its constituency and - local-authority breakdowns are left out. + local-authority breakdowns are left out, unless the report is on that + dataset (``is_local_area_report``): it then gets both levels and their + withheld codes, from the same disclosure pass. """ from policyengine_simulation_executor.simulation_output_builder import ( # noqa: PLC0415 # resolved per call so tests can patch simulation_output_builder.SimulationOutputBuilder SimulationOutputBuilder, @@ -188,6 +190,10 @@ def build_aggregate_report( uk_area_breakdowns_omitted, ) + from .local_area_datasets import ( # noqa: PLC0415 # loads the UK metadata module, which is not loaded at import + is_local_area_report, + ) + country = report.baseline.geography.country country_module = _country_module(country) datasets = { @@ -228,7 +234,8 @@ def stand_in( "region": report.baseline.geography.region, **report.baseline.options, } - output = SimulationOutputBuilder( + local_area_report = is_local_area_report(report) + builder = SimulationOutputBuilder( country=country, simulation_params=params, country_module=country_module, @@ -238,10 +245,14 @@ def stand_in( resolved_data_version=report.baseline.bundle.dataset.artifact_revision, resolved_region_code=report.baseline.geography.region, uk_local_authority_metadata=uk_local_authority_metadata, - omit_uk_area_breakdowns=uk_area_breakdowns_omitted( - country, report.baseline.geography.region - ), - ).serialize() + omit_uk_area_breakdowns=not local_area_report + and uk_area_breakdowns_omitted(country, report.baseline.geography.region), + ) + output = builder.serialize() + withheld = builder.uk_withheld_area_codes() if local_area_report else None + if withheld is not None: + output["constituency_withheld_codes"] = withheld["constituency"] + output["local_authority_withheld_codes"] = withheld["local_authority"] output.update( build_spm_result( report=report, From a4b8cadfa82acec01f1bd34568d2ebd2f83499d3 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:06:05 +0400 Subject: [PATCH 26/44] Describe Stage 12's reports on the UK local-area dataset The report output planning section says how a UK-wide or nation report on the local-area dataset loads it, plans its area columns, and keeps its areas and withheld codes. Co-Authored-By: Claude Opus 5.5 --- .../stage-12-modal-worker-foundation.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/migration/stage-12-modal-worker-foundation.md b/docs/migration/stage-12-modal-worker-foundation.md index 986f97068..75a355054 100644 --- a/docs/migration/stage-12-modal-worker-foundation.md +++ b/docs/migration/stage-12-modal-worker-foundation.md @@ -459,8 +459,20 @@ national run leaves them out too: both decide with `uk_area_breakdowns_omitted`, so their results still compare. Production computes those breakdowns in a separate `breakdown: "local_areas"` request on the routed dataset. The entry adapts no such request into a Stage 12 report -(skip reason `unsupported_options`), and Stage 12 has no local-area report -yet, so the shadow comparison does not cover the breakdown numbers. +(skip reason `unsupported_options`), so the shadow comparison does not cover +the breakdown numbers. + +A UK-wide or nation report on that routed dataset, the local-area dataset, +is an ordinary detailed-save report (a request asks for it with +`data_source: "local_area_dataset"`). Its simulations load the local-area +dataset in place of the region's own, keeping the region's scoping, and check +the area columns as it loads; the plan copies `UK_AREA_DATASET_COLUMNS` for +them; and the aggregate keeps both area levels, with each level's withheld +codes (`constituency_withheld_codes`, `local_authority_withheld_codes`) from +the same disclosure pass, which the report run stores as +`withheld_area_codes` rows beside its full results. All three decide by +`calculates_on_local_area_dataset` (`stage12_runtime/local_area_datasets.py`), +on the same routing rule as `uk_area_breakdowns_omitted`. Aggregation uses the retained output tables without rerunning either model. The precomputed baseline and reform simulations retain their original policy From 291d8f7d407fb3c99382876e47e4218874f5bd2e Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:32:00 +0400 Subject: [PATCH 27/44] Test the region-dataset rollback step with the local-area key (failing) Review round 1: deleting active-schema-2 and active-with-region-datasets before deploying code released before region datasets must stop readers released with the local-area key from reading it, and the publisher must require active-schema-2 again, since those readers use the new key only while it holds its copy. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_stage12_manifest.py | 22 +++++++++++++++ ...test_update_v2_version_manifest_default.py | 28 +++++++++---------- 2 files changed, 35 insertions(+), 15 deletions(-) diff --git a/libs/policyengine-simulation-contract/tests/test_stage12_manifest.py b/libs/policyengine-simulation-contract/tests/test_stage12_manifest.py index 5398c4353..74bde84a5 100644 --- a/libs/policyengine-simulation-contract/tests/test_stage12_manifest.py +++ b/libs/policyengine-simulation-contract/tests/test_stage12_manifest.py @@ -1019,3 +1019,25 @@ def test_only_an_economy_capable_uk_entry_declares_local_area_reports() -> None: def test_the_declared_dataset_is_a_dataset_of_the_uk_bundle() -> None: with pytest.raises(ValidationError, match="populace_uk_2023_missing"): _local_area_worker(dataset="populace_uk_2023_missing") + + +def test_the_region_dataset_rollback_step_sends_every_reader_to_the_cache_copy() -> ( + None +): + """The Stage 12 doc's step before deploying code released before region datasets. + + Deleting ``active-schema-2`` and ``active-with-region-datasets`` stops + readers released with the local-area key from reading it, as it stops + older readers reading those two keys. + """ + store = FakeStore() + publish_v2_manifest(store=store, worker=_local_area_worker()) + del store.values[SCHEMA_2_MANIFEST_KEY] + del store.values[REGION_DATASETS_MANIFEST_KEY] + + loaded = V2ManifestLoader(store).load() + + worker = loaded.versions["5.2.0"] + us = next(country for country in worker.bundle.countries if country.country == "us") + assert us.region_datasets is None + assert _uk(worker).local_area_reports is None diff --git a/projects/policyengine-simulation-executor/tests/test_update_v2_version_manifest_default.py b/projects/policyengine-simulation-executor/tests/test_update_v2_version_manifest_default.py index 66b306da4..44c27e391 100644 --- a/projects/policyengine-simulation-executor/tests/test_update_v2_version_manifest_default.py +++ b/projects/policyengine-simulation-executor/tests/test_update_v2_version_manifest_default.py @@ -390,18 +390,8 @@ def test_force_default_is_refused_outside_a_worker_publication( # one of them missing. A write never deletes a key. OLDER_KEYS = pytest.mark.parametrize( "expired_key", - [ - SCHEMA_2_MANIFEST_KEY, - REGION_DATASETS_MANIFEST_KEY, - ACTIVE_MANIFEST_KEY, - PRE_CACHE_MANIFEST_KEY, - ], - ids=[ - "active-schema-2", - "active-with-region-datasets", - "active-with-cache", - "active", - ], + [REGION_DATASETS_MANIFEST_KEY, ACTIVE_MANIFEST_KEY, PRE_CACHE_MANIFEST_KEY], + ids=["active-with-region-datasets", "active-with-cache", "active"], ) @@ -442,10 +432,18 @@ def test_verify_accepts_an_expired_older_key( assert f"v2 default version: {_installed_version()}" in capsys.readouterr().out -def test_move_refuses_a_manifest_without_its_newest_key(monkeypatch, tmp_path, store): - # Current readers read the local-area report key first, so it is required. +@pytest.mark.parametrize( + "required_key", + [LOCAL_AREA_REPORTS_MANIFEST_KEY, SCHEMA_2_MANIFEST_KEY], + ids=["active-schema-2-with-local-area-reports", "active-schema-2"], +) +def test_move_refuses_a_manifest_without_its_newest_key( + monkeypatch, tmp_path, store, required_key +): + # Current readers read the local-area report key first, and use it only + # while the schema version 2 key holds its copy, so both are required. _with_both_workers(store) - del store.values[LOCAL_AREA_REPORTS_MANIFEST_KEY] + del store.values[required_key] writes = store.writes with pytest.raises(ValueError, match="copies of the v2 manifest differ"): From 22137bdfa33cc39d3c984380061fc9477622f039 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:33:24 +0400 Subject: [PATCH 28/44] Stop reading the local-area key once active-schema-2 is deleted Review round 1: the documented step before rolling back to code released before region datasets deletes active-schema-2 and active-with-region-datasets, but readers released with the local-area key counted a missing active-schema-2 as matching and kept reading the new key, with its region datasets. The new key's document is now current only while active-schema-2 holds its copy, and the publisher requires both keys. The Stage 12 doc says so, and that a rollback drops local_area_reports from versions until each is published again. Co-Authored-By: Claude Opus 5.5 --- .../stage-12-modal-worker-foundation.md | 57 +++++++++++-------- .../stage12_manifest.py | 9 ++- .../modal/utils/update_v2_version_manifest.py | 13 ++++- 3 files changed, 48 insertions(+), 31 deletions(-) diff --git a/docs/migration/stage-12-modal-worker-foundation.md b/docs/migration/stage-12-modal-worker-foundation.md index 75a355054..89d2fb82d 100644 --- a/docs/migration/stage-12-modal-worker-foundation.md +++ b/docs/migration/stage-12-modal-worker-foundation.md @@ -704,32 +704,38 @@ not read while `active-with-cache` exists; a rollback that far needs the newer keys deleted from the Modal Dict first. Removing the older copies needs a later change, once no deployed or rollback revision reads them. -The UK entry's `local_area_reports` says that the worker's coordinator runs -UK local-area report runs, the runs of UK-wide and nation reports on the -local-area dataset, which calculate their full results and their -constituency and local-authority results, with withheld codes: the version of the runs it accepts (`input_version`, -`LOCAL_AREA_REPORTS_VERSION`) and the local-area dataset (`dataset`). That -dataset is the one the release routes constituency and local-authority -regions to, or null when it routes them to no dataset of their own and a -UK-wide or nation run on the national dataset calculates both area levels -itself. The publisher decides it by `uk_area_regions_routed` and +The UK entry's `local_area_reports` says that the worker's coordinator runs UK +local-area report runs, the runs of UK-wide and nation reports on the +local-area dataset, which calculate their full results and their constituency +and local-authority results, with withheld codes: the version of the runs it +accepts (`input_version`, `LOCAL_AREA_REPORTS_VERSION`) and the local-area +dataset (`dataset`). That dataset is the one the release routes constituency +and local-authority regions to, or null when it routes them to no dataset of +their own and a UK-wide or nation run on the national dataset calculates both +area levels itself. The publisher decides it by `uk_area_regions_routed` and `routed_uk_area_dataset_name`, the rule the national aggregation's `uk_area_breakdowns_omitted` and the UK worker use, so the simulation service, -which can't read the release kind from the catalog, creates a local-area -report exactly when the national run leaves the areas out. The field is written only -under the `active-schema-2-with-local-area-reports` key, which current readers -read first; `active-schema-2` holds the same manifest without it, for readers -released before it. An entry without it leaves the field out, so its document -and digest are as before. Readers use the new key's document only while, -without the field, it equals the `active-schema-2` document and that document -is current; code -released before the field republishes only the older keys, so after a rollback -the out-of-date copy stops matching and is no longer read. The same window as -for region datasets applies: a rollback deploys the older coordinator before -its publish job runs, so until then updated entry services may start a -local-area report run, whose simulations on the local-area dataset the older -UK worker refuses, failing only that run with its error recorded. To avoid -it, delete the `active-schema-2-with-local-area-reports` key from the +which can't read the release kind from the catalog, offers a local-area report +exactly where the national run leaves the areas out. + +The field is written only under the `active-schema-2-with-local-area-reports` +key, which current readers read first; `active-schema-2` holds the same +manifest without it, for readers released before it. An entry without it leaves +the field out, so its document and digest are as before. Readers use the new +key's document only while, without the field, it equals the `active-schema-2` +document and that document is current, and the publisher requires both keys. +Code released before the field republishes only the older keys, so after a +rollback the out-of-date copy stops matching and is no longer read; the next +publish starts from what the older code wrote, so versions published before the +rollback lose their `local_area_reports` until each is published again. +Deleting `active-schema-2` also stops readers using the new key, so the +region-dataset rollback step below sends every reader to `active-with-cache`. + +The same window as for region datasets applies: a rollback deploys the older +coordinator before its publish job runs, so until then updated entry services +may start a local-area report run, whose simulations on the local-area dataset +the older UK worker refuses, failing only that run with its error recorded. To +avoid it, delete the `active-schema-2-with-local-area-reports` key from the `simulation-api-v2-version-manifest` Modal Dict before deploying the older code. @@ -741,7 +747,8 @@ Only Stage 12 comparison runs fail in that window, never production responses; if the older deploy's validation fails, the window lasts until a later publish. To avoid it, delete the `active-schema-2` and `active-with-region-datasets` keys from the `simulation-api-v2-version-manifest` Modal Dict before deploying the -older code. +older code; readers released with `active-schema-2-with-local-area-reports` +then stop reading that key too. `region_datasets` names the dataset each region type loads. The entry service records that dataset as a state or district run's dataset provenance, and the diff --git a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_manifest.py b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_manifest.py index 81a9848ad..ae45eb1fe 100644 --- a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_manifest.py +++ b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/stage12_manifest.py @@ -334,15 +334,18 @@ def _is_current_local_area_copy(store: V2ManifestStore, document: object) -> boo Code released before ``LocalAreaReports`` publishes only the older keys, for example after a rollback, which leaves an out-of-date copy behind. A current copy, without the field, is exactly the manifest under - ``active-schema-2``, which is itself current. An unreadable document - counts as current, so readers and publishers report it. + ``active-schema-2``, which is itself current. Without an + ``active-schema-2`` copy it is not current: deleting that key is how an + operator sends every reader back to the older keys before a rollback. + An unreadable document counts as current, so readers and publishers + report it. """ try: manifest = parse_v2_manifest(document) except (TypeError, ValueError): return True without_field = schema_2_manifest_payload(manifest) - if store.get(SCHEMA_2_MANIFEST_KEY) not in (None, without_field): + if store.get(SCHEMA_2_MANIFEST_KEY) != without_field: return False return _is_current_schema_2_document(store, without_field) diff --git a/projects/policyengine-simulation-executor/src/modal/utils/update_v2_version_manifest.py b/projects/policyengine-simulation-executor/src/modal/utils/update_v2_version_manifest.py index 5c3fea16b..b5b3b94c9 100644 --- a/projects/policyengine-simulation-executor/src/modal/utils/update_v2_version_manifest.py +++ b/projects/policyengine-simulation-executor/src/modal/utils/update_v2_version_manifest.py @@ -20,7 +20,9 @@ household_callable_name, ) from policyengine_simulation_contract.stage12_manifest import ( + LOCAL_AREA_REPORTS_MANIFEST_KEY, LOCAL_AREA_REPORTS_VERSION, + SCHEMA_2_MANIFEST_KEY, V1_ROUTING_STATE_NAME, V2_MANIFEST_KEYS, V2_VERSION_MANIFEST_NAME, @@ -207,6 +209,11 @@ def _refresh(store: V2ManifestStore) -> V2VersionManifest: return manifest +# Current readers read the local-area report key first, and use it only +# while the schema version 2 key holds its copy. +REQUIRED_KEYS = frozenset({LOCAL_AREA_REPORTS_MANIFEST_KEY, SCHEMA_2_MANIFEST_KEY}) + + def _key_holds(store: V2ManifestStore, key: str, copies: tuple[object, ...]) -> bool: """Return whether ``key`` holds one of ``copies``, or is an older key that expired. @@ -214,11 +221,11 @@ def _key_holds(store: V2ManifestStore, key: str, copies: tuple[object, ...]) -> current readers read the older keys only when the newest key is missing or out of date, so they can expire between deployments. A write never deletes a key, so a missing older key is never one a part-way write left - behind, and the next write restores it. The newest key, which current - readers read first, is required. + behind, and the next write restores it. The two keys current readers + need are required (``REQUIRED_KEYS``). """ value = store.get(key) - if value is None and key != V2_MANIFEST_KEYS[0]: + if value is None and key not in REQUIRED_KEYS: return True return value in copies From d865e3ed2a3a7ae784fbd06abd91c57ae7c595c5 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:34:20 +0400 Subject: [PATCH 29/44] Fix review round 1's documentation findings for local-area reports SingleYearMacroOutput's description, which the gateway's OpenAPI spec publishes, no longer names Stage 12 and covers nation reports; the uk_area_breakdowns_omitted and SimulationOutputBuilder docstrings say that Stage 12 keeps the areas for a report on the local-area dataset; and the aggregation imports is_local_area_report at module level, since the UK metadata module is already loaded with the package. Co-Authored-By: Claude Opus 5.5 --- .../src/policyengine_simulation_contract/macro_output.py | 4 ++-- .../simulation_output_builder.py | 6 ++++-- .../stage12_runtime/aggregation.py | 6 ++---- .../uk_local_authority_metadata.py | 3 ++- .../tests/golden/openapi.json | 2 +- 5 files changed, 11 insertions(+), 10 deletions(-) diff --git a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/macro_output.py b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/macro_output.py index 696b83b86..2681faaa5 100644 --- a/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/macro_output.py +++ b/libs/policyengine-simulation-contract/src/policyengine_simulation_contract/macro_output.py @@ -335,8 +335,8 @@ class SingleYearMacroOutput(MacroOutputModel): ``constituency_withheld_codes`` and ``local_authority_withheld_codes`` hold, sorted, the codes of each level's areas the run estimated but disclosure control did not publish, as ``LocalAreaBreakdownOutput``'s do. - Stage 12 lists them for a UK-wide report on the local-area dataset; null - means the result does not report them, and the JSON then leaves both + They are listed for a UK-wide or nation report on the local-area dataset; + null means the result does not report them, and the JSON then leaves both keys out, so every other result is written as before. """ diff --git a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/simulation_output_builder.py b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/simulation_output_builder.py index ce85849ed..e467ca83e 100644 --- a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/simulation_output_builder.py +++ b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/simulation_output_builder.py @@ -61,8 +61,10 @@ class SimulationOutputBuilder: ``runtime`` is given. ``omit_uk_area_breakdowns`` leaves the UK constituency and local-authority breakdowns out, for a UK-wide or nation-level run on a bundle that routes area regions to a local-area - dataset (``uk_area_breakdowns_omitted``); those results come from a - separate local-area breakdown run (``LocalAreaBreakdownBuilder``). + dataset (``uk_area_breakdowns_omitted``); in the runtime those results + come from a separate local-area breakdown run + (``LocalAreaBreakdownBuilder``), and Stage 12 keeps them for a report on + the local-area dataset itself, with ``uk_withheld_area_codes``. """ country: str diff --git a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/aggregation.py b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/aggregation.py index 7c9e65bdd..9eb0a121b 100644 --- a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/aggregation.py +++ b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/aggregation.py @@ -15,6 +15,8 @@ stage12_output_plan_sha256, ) +from .local_area_datasets import is_local_area_report + if TYPE_CHECKING: from collections.abc import Mapping @@ -190,10 +192,6 @@ def build_aggregate_report( uk_area_breakdowns_omitted, ) - from .local_area_datasets import ( # noqa: PLC0415 # loads the UK metadata module, which is not loaded at import - is_local_area_report, - ) - country = report.baseline.geography.country country_module = _country_module(country) datasets = { diff --git a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/uk_local_authority_metadata.py b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/uk_local_authority_metadata.py index 70766120a..9fb60190e 100644 --- a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/uk_local_authority_metadata.py +++ b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/uk_local_authority_metadata.py @@ -349,7 +349,8 @@ def uk_area_breakdowns_omitted(country: str, region_code: str | None) -> bool: the routed dataset (``breakdown: "local_areas"``). Constituency and local-authority runs, UK runs on a bundle that does not route area regions, and other countries' runs are unaffected. The runtime and Stage - 12 both decide by this. + 12 both decide by this, except that Stage 12 keeps both levels for a + report on the routed dataset itself (``is_local_area_report``). """ return country == "uk" and not uk_area_codes_required(region_code) diff --git a/projects/policyengine-simulation-gateway/tests/golden/openapi.json b/projects/policyengine-simulation-gateway/tests/golden/openapi.json index 81eb77ab2..653d81f5a 100644 --- a/projects/policyengine-simulation-gateway/tests/golden/openapi.json +++ b/projects/policyengine-simulation-gateway/tests/golden/openapi.json @@ -2717,7 +2717,7 @@ "congressional_district_impact" ], "title": "SingleYearMacroOutput", - "description": "Completed response returned by a single-year macro simulation.\n\n``constituency_withheld_codes`` and ``local_authority_withheld_codes``\nhold, sorted, the codes of each level's areas the run estimated but\ndisclosure control did not publish, as ``LocalAreaBreakdownOutput``'s do.\nStage 12 lists them for a UK-wide report on the local-area dataset; null\nmeans the result does not report them, and the JSON then leaves both\nkeys out, so every other result is written as before." + "description": "Completed response returned by a single-year macro simulation.\n\n``constituency_withheld_codes`` and ``local_authority_withheld_codes``\nhold, sorted, the codes of each level's areas the run estimated but\ndisclosure control did not publish, as ``LocalAreaBreakdownOutput``'s do.\nThey are listed for a UK-wide or nation report on the local-area dataset;\nnull means the result does not report them, and the JSON then leaves both\nkeys out, so every other result is written as before." }, "TelemetryEnvelope": { "properties": { From 98e95d9f919987d72c97b507bef74764be6cffd0 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:35:23 +0400 Subject: [PATCH 30/44] Fix review round 1's test findings for local-area reports The aggregation tests cover a nation report on the local-area dataset, and a new test stores a complete local-area aggregate through AggregateReportArtifactPayload and report_run_result, with its withheld rows. Test names now say what they check, and the worker tests' bundle has no nation region dataset, as .py 6.17.1's has none. Co-Authored-By: Claude Opus 5.5 --- .../test_stage12_local_area_aggregation.py | 67 +++++++++++++++++-- .../test_stage12_local_area_dataset_load.py | 4 +- 2 files changed, 64 insertions(+), 7 deletions(-) diff --git a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_aggregation.py b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_aggregation.py index f7853dae1..259df368e 100644 --- a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_aggregation.py +++ b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_aggregation.py @@ -2,11 +2,16 @@ from __future__ import annotations +import copy from typing import Any import pandas as pd import pytest -from policyengine_simulation_contract.stage12_execution import ReportExecutionInput +from fixtures.macro_output import CURRENT_SINGLE_YEAR_MACRO_RESULT +from policyengine_simulation_contract.stage12_execution import ( + AggregateReportArtifactPayload, + ReportExecutionInput, +) from policyengine_simulation_executor import ( simulation_output_builder, simulation_output_geographic, @@ -23,6 +28,11 @@ build_aggregate_report, local_area_datasets, ) +from policyengine_stage12_persistence.report_run_results import ( + report_run_result, + withheld_area_codes, +) +from stage12_fake_report_runs import REPORT_RUN_IDS from stage12_fake_stores import FakeArtifacts from stage12_runtime_support import bundle_provenance, report_execution_input @@ -142,13 +152,14 @@ def _aggregate(monkeypatch, report: ReportExecutionInput) -> dict[str, Any]: )["result"] -def test_a_uk_wide_report_on_the_local_area_dataset_gets_its_areas( - monkeypatch, +@pytest.mark.parametrize("region", ["uk", "country/wales"]) +def test_a_uk_wide_or_nation_report_on_the_local_area_dataset_gets_its_areas( + monkeypatch, region: str ) -> None: _route_uk_area_regions(monkeypatch) result = _aggregate( - monkeypatch, _uk_report(region="uk", dataset=LOCAL_AREA_DATASET) + monkeypatch, _uk_report(region=region, dataset=LOCAL_AREA_DATASET) ) assert _CapturingBuilder.built["omit_uk_area_breakdowns"] is False @@ -185,7 +196,7 @@ def test_an_area_report_keeps_its_area_and_lists_no_withheld_codes( assert "constituency_withheld_codes" not in result -def test_the_builder_lists_each_levels_withheld_codes_from_its_disclosure_pass( +def test_the_builder_lists_each_levels_withheld_codes_from_one_disclosure_pass( monkeypatch, ) -> None: passes = [] @@ -226,3 +237,49 @@ def test_a_builder_outside_the_uk_lists_no_withheld_codes() -> None: ) assert builder.uk_withheld_area_codes() is None + + +class _FullOutputBuilder(_CapturingBuilder): + """Stands in for the output builder with a complete economy output.""" + + def serialize(self) -> dict[str, Any]: + output = copy.deepcopy(CURRENT_SINGLE_YEAR_MACRO_RESULT) + # A UK result: its areas, and no congressional districts. + output.update( + congressional_district_impact=None, + constituency_impact=[], + local_authority_impact=[], + ) + return output + + +def test_a_local_area_aggregate_is_stored_with_its_withheld_codes(monkeypatch) -> None: + _route_uk_area_regions(monkeypatch) + monkeypatch.setattr( + simulation_output_builder, "SimulationOutputBuilder", _FullOutputBuilder + ) + report = _uk_report(region="uk", dataset=LOCAL_AREA_DATASET) + frames = { + entity: pd.DataFrame({f"{entity}_id": [1]}) + for entity in ("person", "benunit", "household") + } + artifacts = FakeArtifacts() + aggregate = build_aggregate_report( + report=report, + baseline=RetainedSimulationOutput( + frames, artifacts.add_simulation(report.baseline) + ), + reform=RetainedSimulationOutput( + frames, artifacts.add_simulation(report.reform) + ), + ) + + # The coordinator validates the aggregate, then stores its result. + result = AggregateReportArtifactPayload.model_validate(aggregate).result + stored = report_run_result(result, run_ids=REPORT_RUN_IDS, country="uk") + (withheld,) = [rows for rows in stored.rows if rows.table is withheld_area_codes] + assert [(row["area_type"], row["code"]) for row in withheld.rows] == [ + ("constituency", "W07000081"), + ("local_authority", "E06000064"), + ("local_authority", "W06000015"), + ] diff --git a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py index 81930e534..0d5da2a53 100644 --- a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py +++ b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py @@ -86,8 +86,8 @@ def _installed_uk_bundle() -> ResolvedStage12Bundle: """Return an installed bundle holding the national and local-area datasets.""" national = _dataset(NATIONAL_DATASET) region_datasets = { + # As .py 6.17.1's bundle: nations have no region dataset of their own. "national": NATIONAL_DATASET, - "country": NATIONAL_DATASET, "constituency": LOCAL_AREA_DATASET, "local_authority": LOCAL_AREA_DATASET, } @@ -394,7 +394,7 @@ def _uk_report(region: str, identity: str) -> ReportExecutionInput: @pytest.mark.parametrize("region", ["uk", "country/wales"]) -def test_a_uk_wide_or_nation_report_on_the_local_area_dataset_calculates_areas( +def test_a_uk_wide_or_nation_report_on_the_local_area_dataset_is_recognised( monkeypatch, region: str ) -> None: _route_uk_area_regions(monkeypatch) From 7cdc25e1c1acbd883204947dba0afd44ef96abb7 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:35:48 +0400 Subject: [PATCH 31/44] Add the changelog fragment for local-area reports Co-Authored-By: Claude Opus 5.5 --- changelog.d/c1-23-local-area-reports.added.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/c1-23-local-area-reports.added.md diff --git a/changelog.d/c1-23-local-area-reports.added.md b/changelog.d/c1-23-local-area-reports.added.md new file mode 100644 index 000000000..4c697febf --- /dev/null +++ b/changelog.d/c1-23-local-area-reports.added.md @@ -0,0 +1 @@ +Stage 12 now calculates UK-wide and nation reports on the release's local-area dataset (the dataset UK constituency and local-authority regions use): the UK worker loads that dataset, and such a report's run returns its full results together with its constituency and local-authority results and the codes of the areas disclosure control withheld, which it stores as `withheld_area_codes` rows. The economy output gains optional `constituency_withheld_codes` and `local_authority_withheld_codes`, left out of every other result. The v2 version manifest's UK entry declares the local-area dataset (`local_area_reports`), under a new key that readers released before it never read. From fa9dc73a025a32b103701eec603de2900a37baa0 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:54:57 +0400 Subject: [PATCH 32/44] Test that verifying a default move requires active-schema-2 Review round 2: no test depended on the publisher requiring active-schema-2. With it deleted, current readers stop using the local-area report key and read an older copy, so --verify-plan must refuse the store; without the requirement it accepted it. Co-Authored-By: Claude Opus 5.5 --- .../test_update_v2_version_manifest_default.py | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/projects/policyengine-simulation-executor/tests/test_update_v2_version_manifest_default.py b/projects/policyengine-simulation-executor/tests/test_update_v2_version_manifest_default.py index 44c27e391..f550f8164 100644 --- a/projects/policyengine-simulation-executor/tests/test_update_v2_version_manifest_default.py +++ b/projects/policyengine-simulation-executor/tests/test_update_v2_version_manifest_default.py @@ -244,6 +244,19 @@ def test_verify_refuses_a_manifest_changed_since_the_move(monkeypatch, tmp_path, _run(monkeypatch, "--verify-plan", str(tmp_path / "plan.json")) +def test_verify_refuses_a_manifest_whose_schema_2_key_was_deleted( + monkeypatch, tmp_path, store +): + # Current readers then stop using the local-area report key and read an + # older copy, without household functions, so the move isn't live. + _with_both_workers(store) + _move(monkeypatch, tmp_path, _installed_version()) + del store.values[SCHEMA_2_MANIFEST_KEY] + + with pytest.raises(ValueError, match="is not what this default move wrote"): + _run(monkeypatch, "--verify-plan", str(tmp_path / "plan.json")) + + def test_restore_puts_the_default_back_only_while_the_move_is_live( monkeypatch, tmp_path, store, capsys ): From 037e9622ebc0d1c66af5d6ae856b0f4167414a9c Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:56:11 +0400 Subject: [PATCH 33/44] Test the UK worker's local-area dataset over the installed release Review round 2: every worker test replaced the bundle, the routing and the dataset selection. This one uses the installed .py bundle and routing, so a release that renames or moves the local-area dataset, or gives it another URI in dataset selection, fails here. Co-Authored-By: Claude Opus 5.5 --- .../test_stage12_local_area_dataset_load.py | 51 +++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py index 0d5da2a53..19ca68191 100644 --- a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py +++ b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py @@ -462,3 +462,54 @@ def test_a_simulation_is_on_the_local_area_dataset_by_its_region_and_dataset( ) is on_local_area_dataset ) + + +def test_the_installed_release_accepts_and_selects_its_own_local_area_dataset() -> None: + # Over the installed .py bundle and its routing, unpatched: a release + # upgrade that renames or moves the dataset fails here, not in staging. + from policyengine_simulation_executor.simulation_runtime import ( + _resolve_dataset_selection, + ) + from policyengine_simulation_executor.stage12_bundle import load_stage12_bundle + from policyengine_simulation_executor.stage12_runtime.worker_inputs import ( + simulation_runtime_params, + ) + from policyengine_simulation_executor.uk_local_authority_metadata import ( + routed_uk_area_dataset_name, + uk_area_regions_routed, + ) + + assert uk_area_regions_routed() + resolved = load_stage12_bundle() + uk = next(item for item in resolved.bundle.countries if item.country == "uk") + dataset = next( + item for item in uk.datasets if item.identity == routed_uk_area_dataset_name() + ) + simulation = _uk_simulation( + "uk", + dataset.identity, + provenance=BundleProvenance( + policyengine_version=resolved.bundle.policyengine_version, + country_package_name=uk.country_package_name, + country_package_version=uk.country_package_version, + dataset=DatasetProvenance( + identity=dataset.identity, + uri=dataset.uri, + artifact_revision=dataset.artifact_revision, + data_package_name=uk.data_package_name, + data_package_version=uk.data_package_version, + ), + bundle_manifest_sha256=resolved.bundle_manifest_sha256, + ), + ) + + worker._require_installed_bundle(simulation) + assert local_area_datasets.local_area_dataset_name(simulation) == dataset.identity + selection = _resolve_dataset_selection( + simulation_runtime_params(simulation), + region_resolution=local_area_datasets.dataset_region( + RegionResolution(code="uk"), dataset.identity + ), + ) + # The worker refuses a selection that differs from the provenance. + assert (selection.name, selection.uri) == (dataset.identity, dataset.uri) From e7239ac291ef735618e3cfa9db920ed4e3ab1618 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 00:56:54 +0400 Subject: [PATCH 34/44] Fix review round 2's documentation findings for local-area reports The Stage 12 doc's older manifest paragraphs say which key current readers use, now that the local-area report key comes first, and neither the doc nor is_local_area_report's docstring says a request can already ask for such a report: the simulation service names the dataset, and no field marks the run. Co-Authored-By: Claude Opus 5.5 --- .../stage-12-modal-worker-foundation.md | 70 ++++++++++--------- .../stage12_runtime/local_area_datasets.py | 8 +-- 2 files changed, 41 insertions(+), 37 deletions(-) diff --git a/docs/migration/stage-12-modal-worker-foundation.md b/docs/migration/stage-12-modal-worker-foundation.md index 89d2fb82d..e917de643 100644 --- a/docs/migration/stage-12-modal-worker-foundation.md +++ b/docs/migration/stage-12-modal-worker-foundation.md @@ -462,17 +462,18 @@ the routed dataset. The entry adapts no such request into a Stage 12 report (skip reason `unsupported_options`), so the shadow comparison does not cover the breakdown numbers. -A UK-wide or nation report on that routed dataset, the local-area dataset, -is an ordinary detailed-save report (a request asks for it with -`data_source: "local_area_dataset"`). Its simulations load the local-area -dataset in place of the region's own, keeping the region's scoping, and check -the area columns as it loads; the plan copies `UK_AREA_DATASET_COLUMNS` for -them; and the aggregate keeps both area levels, with each level's withheld -codes (`constituency_withheld_codes`, `local_authority_withheld_codes`) from -the same disclosure pass, which the report run stores as -`withheld_area_codes` rows beside its full results. All three decide by -`calculates_on_local_area_dataset` (`stage12_runtime/local_area_datasets.py`), -on the same routing rule as `uk_area_breakdowns_omitted`. +A UK-wide or nation report on that routed dataset, the local-area dataset, is +an ordinary detailed-save report: the simulation service names that dataset in +both simulations' provenance, and no field marks the run. Its simulations load +the local-area dataset in place of the region's own, keeping the region's +scoping, and check the area columns as it loads; the plan copies +`UK_AREA_DATASET_COLUMNS` for them; and the aggregate keeps both area levels, +with each level's withheld codes (`constituency_withheld_codes`, +`local_authority_withheld_codes`) from the same disclosure pass, which the +report run stores as `withheld_area_codes` rows beside its full results. All +three decide by `calculates_on_local_area_dataset` +(`stage12_runtime/local_area_datasets.py`), on the same routing rule as +`uk_area_breakdowns_omitted`. Aggregation uses the retained output tables without rerunning either model. The precomputed baseline and reform simulations retain their original policy @@ -673,30 +674,33 @@ skips any country the manifest does not mark as economy-capable, with the reason `unsupported_country`, so the coordinator receives only those countries' reports. -Readers released before a schema change reject fields they do not know, and -the manifest is published before the Cloud Run revision that reads it is -promoted. The publisher therefore writes the whole schema version 2 manifest -under the `active-schema-2` key and, in schema version 1 form (without the -capability and household fields), the same manifest under the -`active-with-region-datasets` key, without each country bundle's -`region_datasets` under the `active-with-cache` key, and without cache releases -either under the `active` key; readers released before each field keep reading -the key that lacks it. A schema version 1 document marks every listed country -economy-capable, with no household function. - -Current readers use the `active-schema-2` document while each older key holds -its schema version 1 form. Schema version 1 cannot describe a country that is -not economy-capable, so a manifest holding one is written only under -`active-schema-2` and the older keys keep the last manifest written there; such -a document is used unless the document under the older keys was validated -later. Otherwise readers use the `active-with-region-datasets` copy only while -it, with its region datasets removed, equals the manifest under +Readers released before a schema change reject fields they do not know, and the +manifest is published before the Cloud Run revision that reads it is promoted. +The publisher therefore writes the whole schema version 2 manifest under the +`active-schema-2-with-local-area-reports` key, the same manifest without the UK +entry's `local_area_reports` under the `active-schema-2` key (both described +below), and, in schema version 1 form (without the capability and household +fields), the same manifest under the `active-with-region-datasets` key, without +each country bundle's `region_datasets` under the `active-with-cache` key, and +without cache releases either under the `active` key; readers released before +each field keep reading the key that lacks it. A schema version 1 document +marks every listed country economy-capable, with no household function. + +Readers released before `local_area_reports` use the `active-schema-2` document +while each older key holds its schema version 1 form; current readers use the +local-area report key's document in its place while `active-schema-2` holds its +copy, and otherwise follow the same rules. Schema version 1 cannot describe a +country that is not economy-capable, so a manifest holding one is written only +under `active-schema-2` and the older keys keep the last manifest written +there; such a document is used unless the document under the older keys was +validated later. Otherwise readers use the `active-with-region-datasets` copy +only while it, with its region datasets removed, equals the manifest under `active-with-cache`; otherwise they read `active-with-cache`, falling back to `active` before the first publish that writes it. Code released before schema -version 2 or before region datasets republishes only the older keys it knows, so -after a rollback the out-of-date copies stop matching and are no longer read, -and the next publish starts from what the older code wrote. That document has -no household functions, so the manifest names none for versions published +version 2 or before region datasets republishes only the older keys it knows, +so after a rollback the out-of-date copies stop matching and are no longer +read, and the next publish starts from what the older code wrote. That document +has no household functions, so the manifest names none for versions published before the rollback until each is published again, and it lacks whatever only `active-schema-2` held, such as a version with a household-only country. Code released before cache releases writes only `active`, which current readers do diff --git a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/local_area_datasets.py b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/local_area_datasets.py index fb089be9f..18d853890 100644 --- a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/local_area_datasets.py +++ b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/local_area_datasets.py @@ -61,10 +61,10 @@ def is_local_area_report(report: ReportExecutionInput) -> bool: """Whether a run of ``report`` also calculates the UK area results. It does for a report of the UK or a nation whose simulations are on the - local-area dataset, an ordinary report a request asks for with - ``data_source``: it returns its full results and its constituency and - local-authority results, with their withheld codes. Both of a report's - simulations share its dataset and region. + local-area dataset, an ordinary report whose simulations the simulation + service names on that dataset: it returns its full results and its + constituency and local-authority results, with their withheld codes. + Both of a report's simulations share its dataset and region. """ return calculates_on_local_area_dataset(report.baseline) From dd6b466d221f4257e484b029e6a8766315af7c1d Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:09:20 +0400 Subject: [PATCH 35/44] Fix review round 3's findings for local-area reports The Stage 12 doc says a manifest with a country that isn't economy-capable goes under both schema version 2 keys, and no longer says the simulation service already uses the local-area declaration. The installed-release worker test calls the worker's own provenance check on the selection. Co-Authored-By: Claude Opus 5.5 --- .../stage-12-modal-worker-foundation.md | 38 ++++++++++--------- .../test_stage12_local_area_dataset_load.py | 3 +- 2 files changed, 22 insertions(+), 19 deletions(-) diff --git a/docs/migration/stage-12-modal-worker-foundation.md b/docs/migration/stage-12-modal-worker-foundation.md index e917de643..5b60955af 100644 --- a/docs/migration/stage-12-modal-worker-foundation.md +++ b/docs/migration/stage-12-modal-worker-foundation.md @@ -691,22 +691,24 @@ while each older key holds its schema version 1 form; current readers use the local-area report key's document in its place while `active-schema-2` holds its copy, and otherwise follow the same rules. Schema version 1 cannot describe a country that is not economy-capable, so a manifest holding one is written only -under `active-schema-2` and the older keys keep the last manifest written -there; such a document is used unless the document under the older keys was -validated later. Otherwise readers use the `active-with-region-datasets` copy -only while it, with its region datasets removed, equals the manifest under -`active-with-cache`; otherwise they read `active-with-cache`, falling back to -`active` before the first publish that writes it. Code released before schema -version 2 or before region datasets republishes only the older keys it knows, -so after a rollback the out-of-date copies stop matching and are no longer -read, and the next publish starts from what the older code wrote. That document -has no household functions, so the manifest names none for versions published -before the rollback until each is published again, and it lacks whatever only -`active-schema-2` held, such as a version with a household-only country. Code -released before cache releases writes only `active`, which current readers do -not read while `active-with-cache` exists; a rollback that far needs the newer -keys deleted from the Modal Dict first. Removing the older copies needs a later -change, once no deployed or rollback revision reads them. +under the two schema version 2 keys (`active-schema-2` and +`active-schema-2-with-local-area-reports`) and the older keys keep the last +manifest written there; such a document is used unless the document under the +older keys was validated later. Otherwise readers use the +`active-with-region-datasets` copy only while it, with its region datasets +removed, equals the manifest under `active-with-cache`; otherwise they read +`active-with-cache`, falling back to `active` before the first publish that +writes it. Code released before schema version 2 or before region datasets +republishes only the older keys it knows, so after a rollback the out-of-date +copies stop matching and are no longer read, and the next publish starts from +what the older code wrote. That document has no household functions, so the +manifest names none for versions published before the rollback until each is +published again, and it lacks whatever only the schema version 2 keys held, +such as a version with a household-only country. Code released before cache +releases writes only `active`, which current readers do not read while +`active-with-cache` exists; a rollback that far needs the newer keys deleted +from the Modal Dict first. Removing the older copies needs a later change, once +no deployed or rollback revision reads them. The UK entry's `local_area_reports` says that the worker's coordinator runs UK local-area report runs, the runs of UK-wide and nation reports on the @@ -719,8 +721,8 @@ their own and a UK-wide or nation run on the national dataset calculates both area levels itself. The publisher decides it by `uk_area_regions_routed` and `routed_uk_area_dataset_name`, the rule the national aggregation's `uk_area_breakdowns_omitted` and the UK worker use, so the simulation service, -which can't read the release kind from the catalog, offers a local-area report -exactly where the national run leaves the areas out. +which can't read the release kind from the catalog, can tell from it whether a +report on the local-area dataset is possible and which dataset it is. The field is written only under the `active-schema-2-with-local-area-reports` key, which current readers read first; `active-schema-2` holds the same diff --git a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py index 19ca68191..a60c6349f 100644 --- a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py +++ b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_dataset_load.py @@ -512,4 +512,5 @@ def test_the_installed_release_accepts_and_selects_its_own_local_area_dataset() ), ) # The worker refuses a selection that differs from the provenance. - assert (selection.name, selection.uri) == (dataset.identity, dataset.uri) + worker._require_loaded_dataset_matches_provenance(simulation, selection) + assert selection.name == dataset.identity From 30c9ebeab6c0f97420aecacc55821f3852ee27f4 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:44:07 +0400 Subject: [PATCH 36/44] Test storing a local-area run's withheld codes on PostgreSQL MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Against a database built from C1 ยท 22's revision of the Public API (withheld_area_codes, 1e1e3f079f2c): completing a run whose result lists withheld codes, as the Modal worker role, writes one row per code, naming the run's two simulation runs, beside its area rows, and a repeated completion writes no second set. Seen failing with the rows left out. The table is reflected in these tests alone, so the others still run on a database built before it. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_report_run_results.py | 89 ++++++++++++++++++- 1 file changed, 88 insertions(+), 1 deletion(-) diff --git a/libs/policyengine-stage12-persistence/tests/test_report_run_results.py b/libs/policyengine-stage12-persistence/tests/test_report_run_results.py index 47bcdf68b..a3543ceaa 100644 --- a/libs/policyengine-stage12-persistence/tests/test_report_run_results.py +++ b/libs/policyengine-stage12-persistence/tests/test_report_run_results.py @@ -25,7 +25,7 @@ ) from policyengine_stage12_persistence.report_run_results import ResultRows from report_run_database import NOW, SeededReportRun, worker_database_url -from sqlalchemy import insert, select +from sqlalchemy import MetaData, Table, insert, select from sqlalchemy.exc import IntegrityError LATER = NOW + timedelta(minutes=5) @@ -595,3 +595,90 @@ def test_a_district_in_an_unknown_state_is_refused(seeded_run: SeededReportRun) country="us", district_codes=DISTRICT_CODES, ) + + +def _withheld_area_codes(seeder, report_run_id) -> list[dict[str, object]]: + """Return a report run's withheld area code rows, as the seed role reads them. + + The table is reflected here, not with the seeded tables, so the other tests + run on a database built before the Public API added it. + """ + table = Table( + "withheld_area_codes", MetaData(schema="public"), autoload_with=seeder.engine + ) + with seeder.engine.connect() as connection: + return [ + dict(row._mapping) + for row in connection.execute( + select(table).where(table.c.report_run_id == report_run_id) + ) + ] + + +def _local_area_output() -> dict[str, object]: + return { + **uk_output_with_areas(), + "constituency_withheld_codes": ["S14000045"], + "local_authority_withheld_codes": ["E06000064", "W06000015"], + } + + +def test_a_local_area_result_stores_its_withheld_codes_with_the_completion( + store, seeder, seeded_run: SeededReportRun +) -> None: + run_ids = seeded_run.run_ids + + written = _complete(store, seeded_run, output=_local_area_output(), country="uk") + + assert written == RunWrite(changed=True, status=RunStatus.SUCCEEDED) + stored = _withheld_area_codes(seeder, run_ids.report_run_id) + assert sorted( + ( + row["area_type"], + row["code"], + row["baseline_simulation_run_id"], + row["reform_simulation_run_id"], + ) + for row in stored + ) == [ + ( + "constituency", + "S14000045", + run_ids.baseline_simulation_run_id, + run_ids.reform_simulation_run_id, + ), + ( + "local_authority", + "E06000064", + run_ids.baseline_simulation_run_id, + run_ids.reform_simulation_run_id, + ), + ( + "local_authority", + "W06000015", + run_ids.baseline_simulation_run_id, + run_ids.reform_simulation_run_id, + ), + ] + # The published areas are stored beside them, as for any UK result. + assert ( + len(seeder.rows("constituency_impacts", report_run_id=run_ids.report_run_id)) + == 2 + ) + + +def test_a_repeated_local_area_completion_stores_no_second_set_of_codes( + store, seeder, seeded_run: SeededReportRun +) -> None: + run_ids = seeded_run.run_ids + _complete(store, seeded_run, output=_local_area_output(), country="uk") + + repeated = store.complete_report_run( + run_ids, + modal_call_id="fc-coordinator", + completed_at=LATER, + result=report_run_result(_local_area_output(), run_ids=run_ids, country="uk"), + ) + + assert repeated == RunWrite(changed=False, status=RunStatus.SUCCEEDED) + assert len(_withheld_area_codes(seeder, run_ids.report_run_id)) == 3 From 2fad6c79de541b2bc51e02b5ea7324a01e7786e4 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:53:29 +0400 Subject: [PATCH 37/44] Fix review round 4's findings for the withheld-code tests A new test makes the withheld insert itself fail (a code listed twice) and checks the whole completion rolls back: the run stays running, with no area or withheld rows. The local-area tests also check the local-authority rows, share one fixture (uk_output_with_withheld_codes), and the package README says which Public API revision they need. Co-Authored-By: Claude Opus 5.5 --- .../README.md | 5 ++ .../tests/economy_output.py | 12 +++++ .../tests/test_report_run_results.py | 54 +++++++++++++------ .../tests/test_withheld_area_codes.py | 14 +++-- 4 files changed, 62 insertions(+), 23 deletions(-) diff --git a/libs/policyengine-stage12-persistence/README.md b/libs/policyengine-stage12-persistence/README.md index 9dd737d62..3e99f1305 100644 --- a/libs/policyengine-stage12-persistence/README.md +++ b/libs/policyengine-stage12-persistence/README.md @@ -60,3 +60,8 @@ unless both URLs are set: - `REPORT_RUN_TEST_DATABASE_URL`: logs in as `policyengine_v2_modal_worker`; - `REPORT_RUN_TEST_SEED_DATABASE_URL`: logs in as a role that may insert the rows the simulation service would create. + +The tests of a run's withheld area codes need the chain at the revision that +adds `withheld_area_codes` (`1e1e3f079f2c`) or later. On an older database +they fail at the completion's insert, which names the missing table; the +other tests don't read that table. diff --git a/libs/policyengine-stage12-persistence/tests/economy_output.py b/libs/policyengine-stage12-persistence/tests/economy_output.py index f2e4aee80..5a55cc4d6 100644 --- a/libs/policyengine-stage12-persistence/tests/economy_output.py +++ b/libs/policyengine-stage12-persistence/tests/economy_output.py @@ -237,3 +237,15 @@ def uk_output_with_areas() -> dict[str, Any]: } ] return output + + +def uk_output_with_withheld_codes() -> dict[str, Any]: + """Return the UK output with areas, and the codes of three withheld areas. + + A UK-wide or nation report on the local-area dataset lists them. + """ + return { + **uk_output_with_areas(), + "constituency_withheld_codes": ["S14000045"], + "local_authority_withheld_codes": ["E06000064", "W06000015"], + } diff --git a/libs/policyengine-stage12-persistence/tests/test_report_run_results.py b/libs/policyengine-stage12-persistence/tests/test_report_run_results.py index a3543ceaa..1cd058005 100644 --- a/libs/policyengine-stage12-persistence/tests/test_report_run_results.py +++ b/libs/policyengine-stage12-persistence/tests/test_report_run_results.py @@ -14,6 +14,7 @@ US_STATE_FIPS, uk_economy_output, uk_output_with_areas, + uk_output_with_withheld_codes, us_output_with_every_part, ) from policyengine_stage12_persistence import ( @@ -615,20 +616,14 @@ def _withheld_area_codes(seeder, report_run_id) -> list[dict[str, object]]: ] -def _local_area_output() -> dict[str, object]: - return { - **uk_output_with_areas(), - "constituency_withheld_codes": ["S14000045"], - "local_authority_withheld_codes": ["E06000064", "W06000015"], - } - - def test_a_local_area_result_stores_its_withheld_codes_with_the_completion( store, seeder, seeded_run: SeededReportRun ) -> None: run_ids = seeded_run.run_ids - written = _complete(store, seeded_run, output=_local_area_output(), country="uk") + written = _complete( + store, seeded_run, output=uk_output_with_withheld_codes(), country="uk" + ) assert written == RunWrite(changed=True, status=RunStatus.SUCCEEDED) stored = _withheld_area_codes(seeder, run_ids.report_run_id) @@ -661,24 +656,53 @@ def test_a_local_area_result_stores_its_withheld_codes_with_the_completion( ), ] # The published areas are stored beside them, as for any UK result. - assert ( - len(seeder.rows("constituency_impacts", report_run_id=run_ids.report_run_id)) - == 2 - ) + for table_name in ("constituency_impacts", "local_authority_impacts"): + assert seeder.rows(table_name, report_run_id=run_ids.report_run_id) def test_a_repeated_local_area_completion_stores_no_second_set_of_codes( store, seeder, seeded_run: SeededReportRun ) -> None: run_ids = seeded_run.run_ids - _complete(store, seeded_run, output=_local_area_output(), country="uk") + _complete(store, seeded_run, output=uk_output_with_withheld_codes(), country="uk") repeated = store.complete_report_run( run_ids, modal_call_id="fc-coordinator", completed_at=LATER, - result=report_run_result(_local_area_output(), run_ids=run_ids, country="uk"), + result=report_run_result( + uk_output_with_withheld_codes(), run_ids=run_ids, country="uk" + ), ) assert repeated == RunWrite(changed=False, status=RunStatus.SUCCEEDED) assert len(_withheld_area_codes(seeder, run_ids.report_run_id)) == 3 + + +def test_a_withheld_code_that_cannot_be_stored_rolls_back_the_completion( + store, seeder, seeded_run: SeededReportRun +) -> None: + # One code listed twice breaks the table's unique key in its insert. + run_ids = seeded_run.run_ids + store.claim_report_run( + run_ids.report_run_id, modal_call_id="fc-coordinator", claimed_at=NOW + ) + output = { + **uk_output_with_withheld_codes(), + "constituency_withheld_codes": ["S14000045", "S14000045"], + } + + with pytest.raises(IntegrityError, match="uq_withheld_area_codes_run_type_code"): + store.complete_report_run( + run_ids, + modal_call_id="fc-coordinator", + completed_at=LATER, + result=report_run_result(output, run_ids=run_ids, country="uk"), + ) + + report_run = seeder.row("report_runs", run_ids.report_run_id) + assert report_run["status"] == "running" + assert report_run["data_version"] is None + for table_name in ("constituency_impacts", "local_authority_impacts"): + assert seeder.rows(table_name, report_run_id=run_ids.report_run_id) == [] + assert _withheld_area_codes(seeder, run_ids.report_run_id) == [] diff --git a/libs/policyengine-stage12-persistence/tests/test_withheld_area_codes.py b/libs/policyengine-stage12-persistence/tests/test_withheld_area_codes.py index c7805ac22..01eae40ba 100644 --- a/libs/policyengine-stage12-persistence/tests/test_withheld_area_codes.py +++ b/libs/policyengine-stage12-persistence/tests/test_withheld_area_codes.py @@ -5,7 +5,11 @@ from typing import Any from uuid import UUID -from economy_output import uk_economy_output, uk_output_with_areas +from economy_output import ( + uk_economy_output, + uk_output_with_areas, + uk_output_with_withheld_codes, +) from policyengine_simulation_contract.macro_output import SingleYearMacroOutput from policyengine_simulation_contract.stage12_execution import ReportRunIds from policyengine_stage12_persistence.report_run_results import ( @@ -36,13 +40,7 @@ def _withheld_rows(output: dict[str, Any]) -> list[dict[str, Any]]: def test_a_uk_result_stores_one_row_per_withheld_area() -> None: - output = { - **uk_output_with_areas(), - "constituency_withheld_codes": ["S14000045"], - "local_authority_withheld_codes": ["E06000064", "W06000015"], - } - - assert _withheld_rows(output) == [ + assert _withheld_rows(uk_output_with_withheld_codes()) == [ {**RUN_KEYS, "area_type": "constituency", "code": "S14000045"}, {**RUN_KEYS, "area_type": "local_authority", "code": "E06000064"}, {**RUN_KEYS, "area_type": "local_authority", "code": "W06000015"}, From 0983765af2db855210ee76bd2dca5656c0b67ddd Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:54:13 +0400 Subject: [PATCH 38/44] Test that a local-area report estimating no area of a level fails (failing) A run of a report on the local-area dataset succeeds today even when a level has neither published nor withheld areas. Failing it instead means a succeeded run proves each level's rows exist, which the staging check needs, since it reads only the run's status. Co-Authored-By: Claude Opus 5.5 --- .../test_stage12_local_area_aggregation.py | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_aggregation.py b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_aggregation.py index 259df368e..b7aea6047 100644 --- a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_aggregation.py +++ b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_aggregation.py @@ -283,3 +283,46 @@ def test_a_local_area_aggregate_is_stored_with_its_withheld_codes(monkeypatch) - ("local_authority", "E06000064"), ("local_authority", "W06000015"), ] + + +class _NoAreaBuilder(_CapturingBuilder): + """Stands in for an output builder whose disclosure pass estimated no areas.""" + + withheld: dict[str, list[str]] + + def uk_withheld_area_codes(self) -> dict[str, list[str]]: + return type(self).withheld + + +@pytest.mark.parametrize("level", ["constituency", "local_authority"]) +def test_a_local_area_report_that_estimated_no_area_of_a_level_fails( + monkeypatch, level: str +) -> None: + # A succeeded run then proves each level's area or withheld-code rows + # exist, which a staging check reading only the run's status relies on. + _route_uk_area_regions(monkeypatch) + _NoAreaBuilder.withheld = { + "constituency": ["W07000081"], + "local_authority": ["W06000015"], + level: [], + } + monkeypatch.setattr( + simulation_output_builder, "SimulationOutputBuilder", _NoAreaBuilder + ) + report = _uk_report(region="country/wales", dataset=LOCAL_AREA_DATASET) + frames = { + entity: pd.DataFrame({f"{entity}_id": [1]}) + for entity in ("person", "benunit", "household") + } + artifacts = FakeArtifacts() + + with pytest.raises(ValueError, match=f"estimated no {level} area"): + build_aggregate_report( + report=report, + baseline=RetainedSimulationOutput( + frames, artifacts.add_simulation(report.baseline) + ), + reform=RetainedSimulationOutput( + frames, artifacts.add_simulation(report.reform) + ), + ) From 32b79768c7c76048afa6961ae3b1f2a60fee868f Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:54:32 +0400 Subject: [PATCH 39/44] Fail a local-area report run whose aggregate estimated no area of a level build_aggregate_report refuses, for a report on the local-area dataset, a level with neither published nor withheld areas, which a UK-wide or nation report always has. A succeeded run then proves each level's area or withheld-code rows exist. Co-Authored-By: Claude Opus 5.5 --- .../stage12_runtime/aggregation.py | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/aggregation.py b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/aggregation.py index 9eb0a121b..68e0c7892 100644 --- a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/aggregation.py +++ b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/aggregation.py @@ -249,6 +249,7 @@ def stand_in( output = builder.serialize() withheld = builder.uk_withheld_area_codes() if local_area_report else None if withheld is not None: + _require_estimated_areas(output, withheld) output["constituency_withheld_codes"] = withheld["constituency"] output["local_authority_withheld_codes"] = withheld["local_authority"] output.update( @@ -268,6 +269,22 @@ def stand_in( } +def _require_estimated_areas( + output: Mapping[str, Any], withheld: Mapping[str, list[str]] +) -> None: + """Raise unless each UK area level has an area, published or withheld. + + Disclosure control may withhold every area of a level, but a UK-wide or + nation report on the local-area dataset always estimates some, so a level + with neither means its area results weren't calculated. A succeeded run + of such a report then always has rows for each level. + """ + for level in ("constituency", "local_authority"): + if not (output.get(f"{level}_impact") or withheld[level]): + msg = f"the local-area report estimated no {level} area" + raise ValueError(msg) + + def build_spm_result( *, report: ReportExecutionInput, From 392a9843726783e44d20c7d45058683a984d730d Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:08:35 +0400 Subject: [PATCH 40/44] Fix review round 5's findings for the local-area area check A test covers a level whose areas are all published, which a check ignoring the published areas would fail; the stand-in builder takes its published and withheld areas through monkeypatch; and the aggregation's docstring, the Stage 12 doc and the changelog fragment say a local-area run fails when a level has no estimated area. Co-Authored-By: Claude Opus 5.5 --- changelog.d/c1-23-local-area-reports.added.md | 2 +- .../stage-12-modal-worker-foundation.md | 11 ++- .../stage12_runtime/aggregation.py | 4 +- .../test_stage12_local_area_aggregation.py | 89 ++++++++++++++----- 4 files changed, 76 insertions(+), 30 deletions(-) diff --git a/changelog.d/c1-23-local-area-reports.added.md b/changelog.d/c1-23-local-area-reports.added.md index 4c697febf..902e9a121 100644 --- a/changelog.d/c1-23-local-area-reports.added.md +++ b/changelog.d/c1-23-local-area-reports.added.md @@ -1 +1 @@ -Stage 12 now calculates UK-wide and nation reports on the release's local-area dataset (the dataset UK constituency and local-authority regions use): the UK worker loads that dataset, and such a report's run returns its full results together with its constituency and local-authority results and the codes of the areas disclosure control withheld, which it stores as `withheld_area_codes` rows. The economy output gains optional `constituency_withheld_codes` and `local_authority_withheld_codes`, left out of every other result. The v2 version manifest's UK entry declares the local-area dataset (`local_area_reports`), under a new key that readers released before it never read. +Stage 12 now calculates UK-wide and nation reports on the release's local-area dataset (the dataset UK constituency and local-authority regions use): the UK worker loads that dataset, and such a report's run returns its full results together with its constituency and local-authority results and the codes of the areas disclosure control withheld, which it stores as `withheld_area_codes` rows; such a run fails if a level has no estimated area, published or withheld. The economy output gains optional `constituency_withheld_codes` and `local_authority_withheld_codes`, left out of every other result. The v2 version manifest's UK entry declares the local-area dataset (`local_area_reports`), under a new key that readers released before it never read. diff --git a/docs/migration/stage-12-modal-worker-foundation.md b/docs/migration/stage-12-modal-worker-foundation.md index 5b60955af..603b2312d 100644 --- a/docs/migration/stage-12-modal-worker-foundation.md +++ b/docs/migration/stage-12-modal-worker-foundation.md @@ -470,10 +470,13 @@ scoping, and check the area columns as it loads; the plan copies `UK_AREA_DATASET_COLUMNS` for them; and the aggregate keeps both area levels, with each level's withheld codes (`constituency_withheld_codes`, `local_authority_withheld_codes`) from the same disclosure pass, which the -report run stores as `withheld_area_codes` rows beside its full results. All -three decide by `calculates_on_local_area_dataset` -(`stage12_runtime/local_area_datasets.py`), on the same routing rule as -`uk_area_breakdowns_omitted`. +report run stores as `withheld_area_codes` rows beside its full results. +Disclosure control may withhold every area of a level, but a run whose +disclosure pass estimated no area of a level fails +(`report_coordination_failed`), so a succeeded run always has area or +withheld-code rows for each level. All three decide by +`calculates_on_local_area_dataset` (`stage12_runtime/local_area_datasets.py`), +on the same routing rule as `uk_area_breakdowns_omitted`. Aggregation uses the retained output tables without rerunning either model. The precomputed baseline and reform simulations retain their original policy diff --git a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/aggregation.py b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/aggregation.py index 68e0c7892..4b732f85a 100644 --- a/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/aggregation.py +++ b/projects/policyengine-simulation-executor/src/policyengine_simulation_executor/stage12_runtime/aggregation.py @@ -179,7 +179,9 @@ def build_aggregate_report( codes in its frames (see ``output_planning``), so its constituency and local-authority breakdowns are left out, unless the report is on that dataset (``is_local_area_report``): it then gets both levels and their - withheld codes, from the same disclosure pass. + withheld codes, from the same disclosure pass, and raises ``ValueError`` + when a level has neither published nor withheld areas, so a succeeded run + always has rows for each level. """ from policyengine_simulation_executor.simulation_output_builder import ( # noqa: PLC0415 # resolved per call so tests can patch simulation_output_builder.SimulationOutputBuilder SimulationOutputBuilder, diff --git a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_aggregation.py b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_aggregation.py index b7aea6047..a0331f394 100644 --- a/projects/policyengine-simulation-executor/tests/test_stage12_local_area_aggregation.py +++ b/projects/policyengine-simulation-executor/tests/test_stage12_local_area_aggregation.py @@ -285,13 +285,38 @@ def test_a_local_area_aggregate_is_stored_with_its_withheld_codes(monkeypatch) - ] -class _NoAreaBuilder(_CapturingBuilder): - """Stands in for an output builder whose disclosure pass estimated no areas.""" +class _AreaBuilder(_CapturingBuilder): + """Stands in for an output builder with given published and withheld areas.""" + published: dict[str, list[dict[str, Any]]] withheld: dict[str, list[str]] + def serialize(self) -> dict[str, Any]: + return {f"{level}_impact": records for level, records in self.published.items()} + def uk_withheld_area_codes(self) -> dict[str, list[str]]: - return type(self).withheld + return self.withheld + + +def _aggregate_wales(monkeypatch) -> dict[str, Any]: + monkeypatch.setattr( + simulation_output_builder, "SimulationOutputBuilder", _AreaBuilder + ) + report = _uk_report(region="country/wales", dataset=LOCAL_AREA_DATASET) + frames = { + entity: pd.DataFrame({f"{entity}_id": [1]}) + for entity in ("person", "benunit", "household") + } + artifacts = FakeArtifacts() + return build_aggregate_report( + report=report, + baseline=RetainedSimulationOutput( + frames, artifacts.add_simulation(report.baseline) + ), + reform=RetainedSimulationOutput( + frames, artifacts.add_simulation(report.reform) + ), + )["result"] @pytest.mark.parametrize("level", ["constituency", "local_authority"]) @@ -301,28 +326,44 @@ def test_a_local_area_report_that_estimated_no_area_of_a_level_fails( # A succeeded run then proves each level's area or withheld-code rows # exist, which a staging check reading only the run's status relies on. _route_uk_area_regions(monkeypatch) - _NoAreaBuilder.withheld = { - "constituency": ["W07000081"], - "local_authority": ["W06000015"], - level: [], - } monkeypatch.setattr( - simulation_output_builder, "SimulationOutputBuilder", _NoAreaBuilder + _AreaBuilder, + "published", + {"constituency": [], "local_authority": []}, + raising=False, + ) + monkeypatch.setattr( + _AreaBuilder, + "withheld", + {"constituency": ["W07000081"], "local_authority": ["W06000015"], level: []}, + raising=False, ) - report = _uk_report(region="country/wales", dataset=LOCAL_AREA_DATASET) - frames = { - entity: pd.DataFrame({f"{entity}_id": [1]}) - for entity in ("person", "benunit", "household") - } - artifacts = FakeArtifacts() with pytest.raises(ValueError, match=f"estimated no {level} area"): - build_aggregate_report( - report=report, - baseline=RetainedSimulationOutput( - frames, artifacts.add_simulation(report.baseline) - ), - reform=RetainedSimulationOutput( - frames, artifacts.add_simulation(report.reform) - ), - ) + _aggregate_wales(monkeypatch) + + +def test_a_local_area_report_with_every_area_of_a_level_published_succeeds( + monkeypatch, +) -> None: + # Disclosure control may withhold nothing at a level, likely for a + # nation's few local authorities. + _route_uk_area_regions(monkeypatch) + published = {"local_authority_code": "W06000015", "local_authority_name": "Cardiff"} + monkeypatch.setattr( + _AreaBuilder, + "published", + {"constituency": [], "local_authority": [published]}, + raising=False, + ) + monkeypatch.setattr( + _AreaBuilder, + "withheld", + {"constituency": ["W07000081"], "local_authority": []}, + raising=False, + ) + + result = _aggregate_wales(monkeypatch) + + assert result["local_authority_impact"] == [published] + assert result["local_authority_withheld_codes"] == [] From 93f224396e310e4f29b426e376f2b833effb8904 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:13:36 +0400 Subject: [PATCH 41/44] Expect the household-only manifest under both schema version 2 keys CI: a manifest schema version 1 can't describe is now written under active-schema-2-with-local-area-reports as well as active-schema-2. Co-Authored-By: Claude Opus 5.5 --- .../tests/test_stage12_manifest.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/libs/policyengine-simulation-contract/tests/test_stage12_manifest.py b/libs/policyengine-simulation-contract/tests/test_stage12_manifest.py index 74bde84a5..7d7640c80 100644 --- a/libs/policyengine-simulation-contract/tests/test_stage12_manifest.py +++ b/libs/policyengine-simulation-contract/tests/test_stage12_manifest.py @@ -479,8 +479,11 @@ def test_a_household_only_country_leaves_schema_1_readers_on_their_manifest() -> manifest = publish_v2_manifest(store=store, worker=_worker(household_only=("uk",))) # Schema version 1 cannot describe a country without a single-simulation - # function, so only the schema version 2 document changes. - assert [key for key, _ in store.writes] == [SCHEMA_2_MANIFEST_KEY] + # function, so only the schema version 2 documents change. + assert [key for key, _ in store.writes] == [ + LOCAL_AREA_REPORTS_MANIFEST_KEY, + SCHEMA_2_MANIFEST_KEY, + ] assert store.values[ACTIVE_MANIFEST_KEY] == earlier assert schema_1_manifest_payload(manifest, include_cache=True) is None worker = manifest.versions["5.2.0"] From b383db266a811e22d00bd90ddf7baf28e9ed4519 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:25:03 +0400 Subject: [PATCH 42/44] Pin the Public API commit that adds withheld_area_codes ca4d396e merges PolicyEngine/policyengine-api#4305, whose revision 1e1e3f079f2c adds the withheld_area_codes table that Stage 12 writes a local-area report run's withheld codes to. Since the previous pin it adds no other migration and changes no table sim's persistence models describe. Co-Authored-By: Claude Opus 5.5 --- libs/policyengine-simulation-persistence/public-api-commit | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libs/policyengine-simulation-persistence/public-api-commit b/libs/policyengine-simulation-persistence/public-api-commit index 90f10c4b5..0954d35d2 100644 --- a/libs/policyengine-simulation-persistence/public-api-commit +++ b/libs/policyengine-simulation-persistence/public-api-commit @@ -1 +1 @@ -429d348aeff84d1d345799fc93ee7c02f7e2014a +ca4d396ebb13d655e139eb1c6b07e8c4fe20e224 From 38fa58be3e552d6bf62b22ac55d5f2a5b94520b6 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:27:33 +0400 Subject: [PATCH 43/44] Expect the two withheld-code fields in the economy output's schema SingleYearMacroOutput's fields and its published OpenAPI schema now hold constituency_withheld_codes and local_authority_withheld_codes, which only a UK-wide or nation report on the local-area dataset lists. The schema tests expect the current result keys plus those two (LOCAL_AREA_REPORT_KEYS); the tests of dumped and built results still expect the current keys alone, since every other result leaves the two out. Co-Authored-By: Claude Opus 5.5 --- .../fixtures/macro_output.py | 7 +++++++ .../tests/test_simulation_api_contracts.py | 7 +++++-- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/projects/policyengine-simulation-executor/fixtures/macro_output.py b/projects/policyengine-simulation-executor/fixtures/macro_output.py index 404296b5b..c3f313d08 100644 --- a/projects/policyengine-simulation-executor/fixtures/macro_output.py +++ b/projects/policyengine-simulation-executor/fixtures/macro_output.py @@ -26,6 +26,13 @@ "cliff_impact", } +# Listed only by a UK-wide or nation report on the local-area dataset, and +# left out of every other result, so the result keys above are unchanged. +LOCAL_AREA_REPORT_KEYS = { + "constituency_withheld_codes", + "local_authority_withheld_codes", +} + CURRENT_REQUIRED_BUDGET_KEYS = { "budgetary_impact", "tax_revenue_impact", diff --git a/projects/policyengine-simulation-executor/tests/test_simulation_api_contracts.py b/projects/policyengine-simulation-executor/tests/test_simulation_api_contracts.py index 03d639d93..ad108ac81 100644 --- a/projects/policyengine-simulation-executor/tests/test_simulation_api_contracts.py +++ b/projects/policyengine-simulation-executor/tests/test_simulation_api_contracts.py @@ -4,6 +4,7 @@ CURRENT_REQUIRED_BUDGET_KEYS, CURRENT_SINGLE_YEAR_MACRO_KEYS, CURRENT_SINGLE_YEAR_MACRO_RESULT, + LOCAL_AREA_REPORT_KEYS, ) from policyengine_simulation_contract.gateway_models import ( BudgetWindowAnnualImpact, @@ -33,7 +34,9 @@ def test_job_status_result_preserves_current_single_year_macro_dict_contract(): def test_internal_single_year_macro_schema_matches_current_public_keys(): - assert set(SingleYearMacroOutput.model_fields) == CURRENT_SINGLE_YEAR_MACRO_KEYS + assert set(SingleYearMacroOutput.model_fields) == ( + CURRENT_SINGLE_YEAR_MACRO_KEYS | LOCAL_AREA_REPORT_KEYS + ) def test_internal_single_year_macro_schema_serializes_current_public_contract(): @@ -48,7 +51,7 @@ def test_openapi_publishes_the_single_year_macro_result_schema(): assert "SingleYearMacroOutput" in schemas assert set(schemas["SingleYearMacroOutput"]["properties"]) == ( - CURRENT_SINGLE_YEAR_MACRO_KEYS + CURRENT_SINGLE_YEAR_MACRO_KEYS | LOCAL_AREA_REPORT_KEYS ) result_schema = schemas["JobStatusResponse"]["properties"]["result"] assert result_schema == { From 45ffb33e71649a9117572358d9863de88f44d972 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:38:59 +0400 Subject: [PATCH 44/44] Fix review round 6's findings for the pin and the schema tests The persistence README says the pin may move to a later merged commit that alters no modelled table, and that the job then still checks only this package's tables. The fixture's set of the two withheld-code fields is LOCAL_AREA_WITHHELD_CODE_KEYS, since it holds only those two keys. Co-Authored-By: Claude Opus 5.5 --- libs/policyengine-simulation-persistence/README.md | 5 ++++- .../fixtures/macro_output.py | 2 +- .../tests/test_simulation_api_contracts.py | 6 +++--- 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/libs/policyengine-simulation-persistence/README.md b/libs/policyengine-simulation-persistence/README.md index 7a7bab9ac..b3ca22046 100644 --- a/libs/policyengine-simulation-persistence/README.md +++ b/libs/policyengine-simulation-persistence/README.md @@ -270,7 +270,10 @@ altered a modelled table, or, while that change is still a pull request, its head commit. Until that pull request merges, the job's last step fails and says so. A merge commit keeps the pull request's head on `master`; if the Public API squashes or rebases the pull request instead, its head never -reaches `master`, so move the pin to the commit that landed. +reaches `master`, so move the pin to the commit that landed. The pin may +also move to a later merged commit that alters no modelled table, such as +one adding a table another package writes; the job still checks only this +package's tables, so moving the pin is no check of that other table. **Keeping it current.** A sim pull request that changes the models moves the pin in the same change. The `Public API schema drift` workflow runs the same diff --git a/projects/policyengine-simulation-executor/fixtures/macro_output.py b/projects/policyengine-simulation-executor/fixtures/macro_output.py index c3f313d08..84dee9808 100644 --- a/projects/policyengine-simulation-executor/fixtures/macro_output.py +++ b/projects/policyengine-simulation-executor/fixtures/macro_output.py @@ -28,7 +28,7 @@ # Listed only by a UK-wide or nation report on the local-area dataset, and # left out of every other result, so the result keys above are unchanged. -LOCAL_AREA_REPORT_KEYS = { +LOCAL_AREA_WITHHELD_CODE_KEYS = { "constituency_withheld_codes", "local_authority_withheld_codes", } diff --git a/projects/policyengine-simulation-executor/tests/test_simulation_api_contracts.py b/projects/policyengine-simulation-executor/tests/test_simulation_api_contracts.py index ad108ac81..507143329 100644 --- a/projects/policyengine-simulation-executor/tests/test_simulation_api_contracts.py +++ b/projects/policyengine-simulation-executor/tests/test_simulation_api_contracts.py @@ -4,7 +4,7 @@ CURRENT_REQUIRED_BUDGET_KEYS, CURRENT_SINGLE_YEAR_MACRO_KEYS, CURRENT_SINGLE_YEAR_MACRO_RESULT, - LOCAL_AREA_REPORT_KEYS, + LOCAL_AREA_WITHHELD_CODE_KEYS, ) from policyengine_simulation_contract.gateway_models import ( BudgetWindowAnnualImpact, @@ -35,7 +35,7 @@ def test_job_status_result_preserves_current_single_year_macro_dict_contract(): def test_internal_single_year_macro_schema_matches_current_public_keys(): assert set(SingleYearMacroOutput.model_fields) == ( - CURRENT_SINGLE_YEAR_MACRO_KEYS | LOCAL_AREA_REPORT_KEYS + CURRENT_SINGLE_YEAR_MACRO_KEYS | LOCAL_AREA_WITHHELD_CODE_KEYS ) @@ -51,7 +51,7 @@ def test_openapi_publishes_the_single_year_macro_result_schema(): assert "SingleYearMacroOutput" in schemas assert set(schemas["SingleYearMacroOutput"]["properties"]) == ( - CURRENT_SINGLE_YEAR_MACRO_KEYS | LOCAL_AREA_REPORT_KEYS + CURRENT_SINGLE_YEAR_MACRO_KEYS | LOCAL_AREA_WITHHELD_CODE_KEYS ) result_schema = schemas["JobStatusResponse"]["properties"]["result"] assert result_schema == {