[anth-volk]

Fixes #4102

Warning

Deploying this PR changes the staging and production v2 database schemas. The release's v2 migration job drops four columns, and their values can't be recovered. Anthony must approve the merge.

Summary

API v2's constituency_impacts and local_authority_impacts tables stored each area's hex-map position in required x and y integer columns. Nothing reads or writes either table, and the app draws its maps from its own layout files, so the positions are unused.

• ConstituencyImpact and LocalAuthorityImpact no longer define x and y.
• v2 revision e86f19a6c4da (parent f5c1d9b4685b, catalog format 2 metadata) was autogenerated from that metadata with uv run alembic -c alembic-v2.ini revision --autogenerate --rev-id e86f19a6c4da, against a disposable Postgres database at the previous head. After master gained fb1a3e40d3d6 on the same parent, it was generated again on top of it in the merge commit 75c797384, and again on top of f5c1d9b4685b in the merge commit be0e090fd, each time with the same operations. It has no post-generation corrections. Its upgrade drops the four columns; its downgrade adds them back as required integers without a server default, which works only while both tables are empty. V2_ALEMBIC_HEAD_REVISION is now e86f19a6c4da.
• Compatibility with the previous Public API revision. The Stage 12A revision kept every column the previous Public API revision maps, so that revision keeps working during the deploy window and after an application rollback. This revision drops four columns that the previous revision maps. That is safe because the previous revision can't read or write either table: no managed database role (policyengine_v2_runtime, policyengine_v2_catalog_writer, policyengine_stage12_<environment>) holds any privilege on them in policyengine_api/data/v2/privileges.py, and no Public API code refers to them outside the models.
• test_stage_12a_schema_serves_the_previous_revision and master's test_countries_schema_serves_the_previous_revision upgraded to head. Each now upgrades to the revision it was written for (fbb7488ebe8a and fb1a3e40d3d6), because head now drops columns that their parent revisions map. A new lifecycle test, test_area_impact_coordinate_removal_changes_nothing_else, checks that the four columns are the only difference between f5c1d9b4685b and head.
• The Alembic guide (docs/engineering/skills/alembic-migrations.md) documents the revision, and the Stage 12A guide names its own revision where it said head.

No route, request or response changes: nothing serves these tables. No CI workflow, Docker image or deployment code changes; the existing v2 seed workflow applies the revision before each Cloud Run deploy. No inline ruff suppressions are added.

Testing

The work was done red-green: the tests were written first and seen failing, then the code was written and both were committed together in b03f88e55.

Seen failing before the change (5 failed, 64 passed):

• tests/unit/v2/test_models.py::test_uk_area_impacts_store_no_map_coordinates: x and y were on both tables.
• tests/unit/v2/test_alembic_v2.py::test_v2_revision_chain_has_generated_policy_and_user_identity_changes: the chain had no revision after the previous head.
• tests/unit/v2/test_alembic_v2.py::test_area_impact_coordinate_removal_is_generated_and_reversible: the revision file didn't exist.
• tests/integration/test_alembic_v2_lifecycle.py::test_empty_upgrade_check_base_downgrade_and_reupgrade: head still had the columns.
• tests/integration/test_alembic_v2_lifecycle.py::test_area_impact_coordinate_removal_changes_nothing_else: no columns were dropped.

After the change, against a disposable postgres:17 database named policyengine_v2_alembic_test, set up as the alembic-v2-check.yml service container is:

• FLASK_DEBUG=1 uv run --frozen pytest tests/unit/v2/test_models.py tests/unit/v2/test_alembic_v2.py tests/integration/test_alembic_v2_lifecycle.py tests/unit/v2/test_catalog_publication.py tests/unit/v2/test_user_association_migration_qualification.py tests/unit/v2/test_privilege_manifest.py -q: 122 passed.
• tests/integration/test_v2_privilege_reconciliation.py (DEPLOYMENT_ENVIRONMENT=test): 3 passed.
• tests/unit/test_alembic_skill.py, tests/unit/test_alembic_workflows.py, tests/unit/data/test_database_access_boundaries.py: 26 passed.
• alembic -c alembic-v2.ini check before generating: exactly four remove_column operations, one for each column. After upgrading: No new upgrade operations detected.
• alembic -c alembic-v2.ini downgrade -1, then upgrade head, then current --check-heads: e86f19a6c4da (head).
• make format, ruff check ., uv run --frozen --extra dev mypy, python scripts/run_quality_guards.py and python scripts/export_migration_contracts.py (no generated changes): all pass.

After merging master on 3 Nov (be0e090fd), on a disposable postgres:17 database:

• alembic -c alembic-v2.ini heads: e86f19a6c4da (head); check: No new upgrade operations detected.
• The revision-chain, coordinate-removal and countries tests in tests/unit/v2/test_alembic_v2.py: passed.
• test_empty_upgrade_check_base_downgrade_and_reupgrade, test_stage_12a_schema_serves_the_previous_revision, test_countries_schema_serves_the_previous_revision and test_area_impact_coordinate_removal_changes_nothing_else: 4 passed.
• ruff check and ruff format --check on the changed Python files, and uv run --frozen --extra dev mypy: pass.

The full suite runs in CI.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.22%. Comparing base (eb96f3a) to head (be0e090).
⚠️ Report is 43 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #4103   +/-   ##
=======================================
  Coverage   88.22%   88.22%           
=======================================
  Files         285      285           
  Lines       16847    16856    +9     
  Branches     2741     2744    +3     
=======================================
+ Hits        14863    14871    +8     
  Misses       1302     1302           
- Partials      682      683    +1     

☔ 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.