[anth-volk]

Fixes #4091

Summary

The simulation API is adding two fields to a completed UK breakdown=local_areas result (kind: local_areas) in PolicyEngine/policyengine-sim-api#968: constituency_withheld_codes and local_authority_withheld_codes. Each is a sorted list of the ONS codes of that level's areas that the run estimated but disclosure control didn't publish. [] means none were withheld; null or an absent field means the result doesn't report them, as in older results.

• Pass-through, no code change. The Public API already stores and returns a breakdown result unchanged once its kind is local_areas (_breakdown_result_kind_error in services/economy_impact_execution.py); the service only adds policyengine_bundle and resolved_app_name, as it does to every economy result. The route-level storage test now runs for a result with the codes, one with null codes and one without them, and the simulation gateway contract test polls a result with the codes over HTTP.
• Breakdown results cached without the codes are recomputed. A simulation API deploy that keeps the same .py version doesn't change the cache identity, so breakdowns cached before the change would be served for up to 30 days without the fields. _build_options_hash now adds breakdown_schema=2 (LOCAL_AREA_BREAKDOWN_RESULT_SCHEMA_VERSION) to a request with a breakdown, after the version fields and before runtime_app_name, as it adds spm_provenance_schema for an SPM selection. The lookup matches the exact hash or hashes that start with it, and an earlier breakdown hash doesn't start with the new one, so the next breakdown request submits a new job. Requests without a breakdown get no new field: their hashes are byte-for-byte the same and their cache entries are still read. RUNTIME_CACHE_SCHEMA_VERSIONS["economy_impact"] is not raised, since that would recompute every cached economy result.
• Documentation. docs/canonical-spm.md describes both fields, with what [], null and absence mean, and says a breakdown cached before the fields existed is computed again because of the breakdown_schema=2 hash field. This PR also described them in the legacy OpenAPI document, but master removed that document with the routes only legacy.policyengine.org or the documentation used (Remove the routes only the legacy site used, check health at /health, and stop serving Canada, Nigeria and Israel #4017), so the merge of master drops that change.

For a client, an existing breakdown report shows computing once more after this deploys, then completes with the new fields.

Merge order

• Merge after the simulation API's executor change, Fill the withheld-area code lists in UK local-area breakdown results policyengine-sim-api#975, is deployed to the executor for the .py version the Public API pins. The simulation API's contract and gateway change, which only accepts the fields, is not enough: until the executor fills them, breakdowns recomputed after this change come back without the codes and stay cached under the new hash for 30 days. Executors for older .py versions never change, so the same applies if Update PolicyEngine UK to 0.62.1 #975 reaches only a different .py version's executor.

Testing

The work was done red-green: each behaviour change's tests were written first and seen failing before the code, and committed together with it.

• Test that breakdown results keep their withheld area codes: characterization tests of existing behaviour, so they passed when written. To check they detect a regression, _with_policyengine_bundle was temporarily changed to drop keys ending in _withheld_codes; the withheld-codes and null-withheld-codes cases then failed, and the case without the fields passed. The change was reverted.
• Stop serving breakdown results cached without withheld area codes: before the code change, the pinned breakdown-hash tests failed (no breakdown_schema=2), and test_a_breakdown_cached_before_the_withheld_codes_is_recomputed_but_not_national failed because the earlier breakdown result was returned with status ok instead of a new job being submitted. test_requests_without_a_breakdown_keep_their_stored_hashes pins, as written-out strings, the stored hashes of UK national, Scotland and Northern Ireland requests and US national and state requests, and passed before and after.
• Describe breakdown results' withheld area codes in the OpenAPI document: test_annual_economy_result_declares_the_breakdown_withheld_area_codes failed until the description was added. Both went when master, which had deleted the document and its test file, was merged in.

Run locally on Python 3.12 (focused, not the full suite):

• FLASK_DEBUG=1 uv run --frozen pytest on tests/unit/services/test_economy_service_request_plumbing.py, test_economy_service_simulation_options.py, test_economy_service_stored_impacts.py, test_economy_service_annual_cache_identity.py, test_economy_service_annual_simulation_requests.py, test_worker_spm.py, test_economy_impact_types.py, tests/unit/routes/test_economy_spm_query.py, tests/unit/test_openapi_spm.py, tests/unit/test_openapi_report_routes.py, tests/unit/test_constants.py and tests/contract/test_simulation_gateway_contract.py: all pass.
• make format, ruff check on the changed Python files, uv run --frozen --extra dev mypy and python scripts/run_quality_guards.py: pass.

After merging master on 3 Nov (103e98993), two tests followed master's other changes: they read stored impacts through the cache's recent(5), as master's tests do since #4017 removed ReformImpactsService.get_recent_reform_impacts, and the Northern Ireland case uses country/northern_ireland. Then:

• test_gateway_uk_comparison_sends_breakdown_only_when_requested, test_annual_route_stores_and_returns_a_completed_breakdown_unchanged, test_requests_without_a_breakdown_keep_their_stored_hashes, test_a_breakdown_cached_before_the_withheld_codes_is_recomputed_but_not_national and test_options_hash_marks_the_breakdown_result_schema: 13 passed.
• ruff check and ruff format --check on the changed Python files, and uv run --frozen --extra dev mypy: pass.

No inline ruff suppressions are added.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.21%. Comparing base (f29abfa) to head (103e989).
⚠️ Report is 8 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #4104      +/-   ##
==========================================
- Coverage   88.22%   88.21%   -0.02%     
==========================================
  Files         285      286       +1     
  Lines       16843    16879      +36     
  Branches     2741     2752      +11     
==========================================
+ Hits        14859    14889      +30     
- Misses       1302     1304       +2     
- Partials      682      686       +4     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.