[anth-volk]

Fixes #954

Same-Repository Draft PR Check

• This PR is a draft.
• This PR is from a branch in PolicyEngine/policyengine-sim-api, not a personal fork.

When to merge

Merging to main deploys staging and then production. Before PolicyEngine/policyengine-app-v2#1439, the app read congressional districts from nationwide results. #1439 reached production on 4 November at 15:17 UTC, and this may merge once it has been in production for a day: from 15:17 UTC on 5 November. Its prerequisites, the Public API's PolicyEngine/policyengine-api#4064 and this repository's #940, are deployed.

Summary

Why:

• A US national run computes congressional district impacts from the national dataset. A state run computes them from its own state dataset. So the same district shows different figures in a nationwide report and in its state's report.
• With Nationwide congressional districts from state runs, in v3 and v2 policyengine-app-v2#1439, nationwide reports take each district from a separate run of its state (and DC) on that state's dataset instead. National runs no longer need to compute districts.
• A search of PolicyEngine's repositories found no other reader of nationwide districts. The Public API passes the field through unchanged.

What changes:

• _should_build_us_congressional_district_impact (simulation_output_geographic.py) now returns true only for a state/* region, in any case.
• Computes no districts (congressional_district_impact is null in the output, and the gateway's job-status response, sent with response_model_exclude_none=True, leaves the field out):
  • national runs, with no region or us;
  • region-group runs, which include the children of a segmented national run;
  • the segmented national reduce and Stage 12 aggregation of a national report, which build their output with the national region;
  • district and place runs, as before.
• Still computes districts: a state run, and Stage 12 aggregation of a state report, which passes on that state's region as the request spelled it, so only a state/... spelling matches there (a bare ut computes none on that path, as before this change; the Public API always sends state/...).
• The contract field is already nullable, so the schema and the generated clients are unchanged.
• Docstrings updated in simulation_output_geographic.py and segmented_national_reduce.py, and a changelog entry.
• Integration checks:
  • a new helper, assert_no_congressional_district_results, checks that the field is absent or null;
  • test_calculate_default_model, a US national run, uses it in place of the at-large district check;
  • the Utah state check still expects UT- districts, and the pinned-version check now runs Vermont and expects exactly VT-01.
• _AT_LARGE_DISTRICT_IDS served only the national check, so it is removed. assert_congressional_district_results' expected_district_ids option, which also served only that check, now matches a state's district IDs exactly (item 5 below).

Older model versions: a deployment rebuilds only the Modal app for the current policyengine.py version. Apps already deployed for older versions are not rebuilt and keep their code, so a request pinned to an older model version can still return nationwide districts.

Testing

Each commit is red-green: the tests were written first and run before the code change.

1. Build congressional districts for state runs only

   • Seen failing first:
     • TestCongressionalDistrictRegions::test__rejects_national_and_group (None, us, region_group/…);
     • test_builder_skips_districts_for_national_and_region_group_runs for None, us and a region group, because the output builder still ran the district calculation.
   • Passed before and after:
     • test__allows_states (state/ca, STATE/CA);
     • test__rejects_district_and_place;
     • test_builder_builds_districts_for_state_runs (state/ut).

2. Expect no congressional districts on a US national integration result

   • Seen failing first, because the helper did not exist: its local tests, which accept a null field in a dict or a generated client object, and refuse an empty district list, a listed district and a generated client object with districts.

3. Say which Stage 12 reports still compute congressional districts

   • Documentation only: the check's docstring and the changelog item now say "Stage 12 aggregation of a national report", so there is no failing-test step.

4. Accept a national result without the district field (review round 1)

   • The helper first required the field to be present, which a deployed result never has, so the beta check would have failed after deploy and stopped the production deploy. test_national_us_assertions_accept_a_result_without_districts now also passes a dict and a generated client object without the field; it failed with "Missing 'congressional_district_impact'" before the helper was changed to .get(...) is None, as assert_no_uk_area_results already does. The test that refused a result without the field is removed.

5. Check an at-large state's one district in beta (review round 2)

   • Removing the national check left no deployed check of an at-large state, and the two Utah beta tests sent the same request. test_calculate_specific_model now runs state/vt and expects exactly VT-01, through assert_congressional_district_results' expected_district_ids option, which main has as a subset check for the national result: an earlier commit here removed it with that check, and this one restores it as an exact match of the sorted IDs, so a district listed twice fails too (review round 3). Its local tests (test_state_assertions_accept_an_at_large_state_with_its_one_district, test_state_assertions_reject_other_district_ids) failed first, because the option did not exist on this branch and then because a repeated district passed. The beta suite keeps the same number of tests.

6. File the change under Removed, and test a bare state code (review round 4, after merging main)

   • The changelog fragment is now 954.removed.md, since national and region-group runs stop returning a field they returned before, and its text is two user-facing sentences.
   • TestCongressionalDistrictRegions::test__rejects_a_bare_state_code_as_stage12_aggregation_passes_it checks that ut and UT compute no districts, as the predicate's docstring says. No code changed, so it passed when written.

Checks:

• After merging main (9583da9d1), CI's PR checks run 41872658422 passed every job, including Test integration and CI complete; at f90d8b357, PR checks, PR image smoke and PR description passed.
• Review round 4: the new test by node ID, CI's Ruff 0.15.22 check and format on the changed test file, and BASE_SHA=origin/main .github/scripts/check-changelog-fragment.sh.
• Before main was merged: the executor's unit tests, the local integration tests, make check and the quality guards passed.

Not run locally: the beta_only integration tests, which run against the beta deployment. The national check runs on the app that beta's latest route points to, and latest moves only to a newer policyengine.py version (or when forced): if a branch with a newer version and without this change were deployed to beta by hand, that check would fail, and stop the production deploy, until latest points to an app with this change. After this deploys to beta, a US national result from the current version's app should have no congressional_district_impact field, a state/ut result should still list UT- districts, and a state/vt result should list exactly VT-01. The null check applies only to the current version's app, for the reason under "Older model versions".

🤖 Generated with Claude Code