[anth-volk]

Fixes #4063

Summary

A failed US state economy job now keeps its error for two minutes instead of 30 days, so a client's Retry can run the state again. The app will run every state on its ACS-local dataset for a nationwide report's congressional districts, and will offer Retry per state; until now a failed state returned its stored error for 30 days.

• US state failures: for country_id us with region state/... (a bare state code such as ca is normalized to state/ca first), the failed job's own record becomes an error that expires after 120 seconds. Until then every request gets the same error, ending "A new run for this state can be requested 2 minutes after this failure."; after it, the next request finds no record and submits a new job.
• Shared code: this reuses the mechanism that failed UK local-area breakdowns already use. _record_breakdown_failure becomes _record_retryable_failure, which takes the retry note, and the new _failure_retry_note picks the breakdown note, the US state note, or none. LOCAL_AREA_BREAKDOWN_FAILURE_SECONDS is renamed RETRYABLE_FAILURE_SECONDS (still 120), since both kinds of job now use it. Since Split the economy service and its tests under the file-length limit #4056 split the economy service into modules, the two methods are in economy_impact_execution.py, and the constants, with the new US_STATE_RETRY_NOTE, are in economy_impact_types.py, which economy_service.py re-exports.
• Unchanged: US national, congressional district and place failures, UK national failures and typed SPM failures are still kept for 30 days. Budget-window jobs use a separate path and are not affected.
• Documentation: docs/canonical-spm.md and changelog.d/us-state-failure-retry.changed.md. (The legacy OpenAPI document this also changed was removed from master by Remove the routes only the legacy site used, check health at /health, and stop serving Canada, Nigeria and Israel #4017.)

A state error stored before this deploys keeps its 30-day lifetime, unless a package version change gives it a different cache version.

Testing

The work was done red-green: the tests were written first and seen failing for the expected reason, then the code was written, and both are in one commit. After master was merged in, with the change moved into the split modules, the same tests were run again against master's code (the US state tests failed, the rest passed) and then with the change (all passed).

• tests/unit/services/test_economy_service_request_plumbing.py, with a new _us_request(region) helper:
  • test_a_failed_us_state_job_is_returned_for_two_minutes_then_resubmitted (for state/ca and the bare ca): red before the change, at its first assertion, because the error had no retry note. (Before the change the stored error would also have been returned 121 seconds after the failure, without a new run; the test stops before it checks that.)
  • test_a_failed_us_national_job_is_still_replayed and test_a_failed_us_district_job_is_still_replayed: passed before and after.
• tests/unit/services/test_economy_service_impact_execution.py, TestHandleExecutionState:
  • a state/ca failure is stored with keep_seconds=120 and the retry note: red before the change;
  • national, district and place failures are stored without keep_seconds: passed before and after.
• After the merge: the five tests above by node ID (8 cases) passed; ruff format --check and ruff check on the changed files, uv run --frozen --extra dev mypy, python scripts/run_quality_guards.py and BASE_SHA=origin/master .github/scripts/check_changelog_fragment.sh: all passed. The full suite runs in CI.
• After review rounds 1 and 2: the state test also checks that the failure is logged at ERROR with its reason (through EconomicImpactResult.error), since its stored error expires after two minutes. The check runs before the test builds its expected result, which logs too; with _record_retryable_failure temporarily changed to build its result without logging, the test failed ("call not found"). The constants' comment now says the app will offer Retry per state.

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.14%. Comparing base (02d4fad) to head (4c20d07).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff             @@
##           master    #4064       +/-   ##
===========================================
+ Coverage   51.71%   88.14%   +36.42%     
===========================================
  Files         267      279       +12     
  Lines       15184    16389     +1205     
  Branches     2432     2671      +239     
===========================================
+ Hits         7853    14446     +6593     
+ Misses       6676     1282     -5394     
- Partials      655      661        +6     

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