Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
45 commits
Select commit Hold shift + click to select a range
60fa681
Test the local-area output profile and a UK bundle's local-area datas…
anth-volk Nov 13, 2026
bd6dc78
Accept the local-area output profile, and name a UK bundle's local-ar…
anth-volk Nov 13, 2026
9ff2fd8
Test the output plan of a UK local-area report run's simulations (fai…
anth-volk Nov 13, 2026
5424871
Plan a UK local-area report run's simulations with only the area columns
anth-volk Nov 13, 2026
853639a
Test a UK-wide or nation simulation on the local-area dataset (failing)
anth-volk Nov 13, 2026
ae77648
Calculate a UK-wide or nation simulation on the local-area dataset it…
anth-volk Nov 13, 2026
964b3b0
Test the v2 manifest's local-area report capability under its own key…
anth-volk Nov 13, 2026
873e1ed
Declare in the v2 manifest that the coordinator runs local-area repor…
anth-volk Nov 13, 2026
9c62e16
Test one routing rule for the UK local-area dataset in the manifest a…
anth-volk Nov 13, 2026
c924097
Declare the UK local-area dataset in the manifest by the executor's r…
anth-volk Nov 13, 2026
2a89656
Describe local-area report runs as runs of reports on the local-area …
anth-volk Nov 13, 2026
1e1d07c
Test recognising a run of a UK-wide or nation report on the local-are…
anth-volk Nov 13, 2026
6407131
Recognise a run of a UK-wide or nation report on the local-area dataset
anth-volk Nov 13, 2026
19111ed
Test a local-area report run's area and withheld-code rows (failing)
anth-volk Nov 13, 2026
1249fc3
Store a local-area report run's area and withheld-code rows
anth-volk Nov 13, 2026
ef9eb1f
Test the public rule for a simulation on the local-area dataset (fail…
anth-volk Nov 13, 2026
98a6144
Make the rule for a simulation on the local-area dataset public
anth-volk Nov 13, 2026
06fda41
Test the area columns of a UK simulation planned alone on the local-a…
anth-volk Nov 13, 2026
7486afc
Plan the area columns for a UK-wide or nation simulation on the local…
anth-volk Nov 13, 2026
035703a
Plan a UK-wide report on the local-area dataset for its full results
anth-volk Nov 13, 2026
1b99f1d
Test storing a UK result's withheld area codes (failing)
anth-volk Nov 13, 2026
46c38f0
Store the withheld area codes a UK result lists
anth-volk Nov 13, 2026
71d1a55
Describe local-area report runs as returning full results and areas
anth-volk Nov 13, 2026
f41fe26
Test the area results of a UK-wide report on the local-area dataset (…
anth-volk Nov 13, 2026
2673e52
Build a UK-wide local-area report's areas and withheld codes in its a…
anth-volk Nov 13, 2026
a4b8cad
Describe Stage 12's reports on the UK local-area dataset
anth-volk Nov 13, 2026
291d8f7
Test the region-dataset rollback step with the local-area key (failing)
anth-volk Nov 13, 2026
22137bd
Stop reading the local-area key once active-schema-2 is deleted
anth-volk Nov 13, 2026
d865e3e
Fix review round 1's documentation findings for local-area reports
anth-volk Nov 13, 2026
98e95d9
Fix review round 1's test findings for local-area reports
anth-volk Nov 13, 2026
7cdc25e
Add the changelog fragment for local-area reports
anth-volk Nov 13, 2026
fa9dc73
Test that verifying a default move requires active-schema-2
anth-volk Nov 13, 2026
037e962
Test the UK worker's local-area dataset over the installed release
anth-volk Nov 13, 2026
e7239ac
Fix review round 2's documentation findings for local-area reports
anth-volk Nov 13, 2026
dd6b466
Fix review round 3's findings for local-area reports
anth-volk Nov 13, 2026
30c9ebe
Test storing a local-area run's withheld codes on PostgreSQL
anth-volk Nov 13, 2026
2fad6c7
Fix review round 4's findings for the withheld-code tests
anth-volk Nov 13, 2026
0983765
Test that a local-area report estimating no area of a level fails (fa…
anth-volk Nov 13, 2026
32b7976
Fail a local-area report run whose aggregate estimated no area of a l…
anth-volk Nov 13, 2026
392a984
Fix review round 5's findings for the local-area area check
anth-volk Nov 13, 2026
248553e
Merge main into the local-area report branch
anth-volk Nov 13, 2026
93f2243
Expect the household-only manifest under both schema version 2 keys
anth-volk Nov 13, 2026
b383db2
Pin the Public API commit that adds withheld_area_codes
anth-volk Nov 13, 2026
38fa58b
Expect the two withheld-code fields in the economy output's schema
anth-volk Nov 13, 2026
45ffb33
Fix review round 6's findings for the pin and the schema tests
anth-volk Nov 13, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/c1-23-local-area-reports.added.md
Original file line number Diff line number Diff line change
@@ -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; 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.
123 changes: 90 additions & 33 deletions docs/migration/stage-12-modal-worker-foundation.md
Original file line number Diff line number Diff line change
Expand Up @@ -471,8 +471,24 @@ 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: 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.
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
Expand Down Expand Up @@ -673,36 +689,76 @@ 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
`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.
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 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
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, 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
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.

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
Expand All @@ -712,7 +768,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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
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.
"""

spm_provenance: SPMComparisonProvenance | None = None

Expand All @@ -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.

Expand Down
Loading
Loading