Refactor the economy and calculation services within ruff's complexity limits

[anth-volk]

Fixes #3929

Summary

Phase 1 step 1.8, group 8b, part 1 of 3: the economy and calculation services, refactored within ruff's complexity limits. Stacked on #3924. Part 2 (#3933) covers the rest of the application, and part 3 (#3934) covers tests, scripts and the rules tool, then switches ruff to ALL.

• All 72 findings in scope are fixed by refactoring, with no suppressions. Before each refactor, a commit adds characterization tests that pin current behaviour; 166 in all.
• Economy comparison (economy_comparison.py):
  • The UK constituency and local-authority breakdowns each had complexity 22 and 57 statements. They keep their public signatures and now share one breakdown loop, with helper tables for income-change buckets and nation prefixes; each keeps its own nation-name casing.
  • Poverty age thresholds become ADULT_MIN_AGE and SENIOR_MIN_AGE.
  • Published results are pinned: tests/data/economy_comparison_snapshots.json stores the complete output of compare_economic_outputs and both breakdowns for UK, US and other-country inputs (17 regions each). It records every dict's key order, floats as repr, value types and the logs, and the refactor reproduces it exactly. Regenerate it only deliberately, with ECONOMY_COMPARISON_SNAPSHOTS=update. The file is about 200 KB.
• Economy service:
  • get_economic_impact and get_budget_window_economic_impact take an EconomicImpactRequest, in its own module, instead of 9–11 arguments.
  • The impact and budget-window flows are split into named steps: reuse, stored answer, create, claim, replay, poll and submit.
  • The private option builders take one setup-options object.
• Reform-impact cache and service: ReformImpactScope, ReformImpactIdentity and ReformImpactExecution replace the long argument lists. The cache's key strings and stored records are unchanged, and pinned by tests. set_error_reform_impact and set_complete_reform_impact drop the scope arguments they already ignored.
• Other modules:
  • budget_window_cache.build_key takes the scope.
  • HouseholdCalculationCache.get splits into a well-formedness check and a receipt check.
  • spm.normalize_spm_selection and worker_spm._check_worker_result are split into steps, with the same error codes, messages and causes.
  • household_calculation_service takes a HouseholdCalculationOptions.
• Call sites: routes/economy_routes.py, routes/household_routes.py and the affected tests.

Testing

• pytest tests/unit tests/contract, to_refactor and the dedupe integration test (the make test set) at this branch's tip: 2,599 passed, which is the base's 2,433 plus the 166 new tests.
• make typecheck-v2 is clean. mypy on the changed application files outside that gate shows no new errors.
• ruff check and ruff format --check (0.15.12) are clean.
• The runtime cache's Redis integration tests pass against a real redis-server.
• Every Pydantic model schema, the FastAPI OpenAPI with every native router enabled, the /v2/openapi.json preview and the legacy spec are byte-identical to the base. The only additions are adapter entries for the new internal dataclasses.
• Not fixed here; they're existing test-isolation problems: test_v1_route_contracts.py leaves a fake-backed economy_routes module bound for later tests, and test_alembic_baseline.py's logging setup disables existing loggers for the rest of the run. The new snapshot test records logs from the module logger for that reason.
• CI: this PR is above the bottom of its stack, so it runs only CI complete, which fails and says why. Its full run starts once the PRs below it merge.

🤖 Generated with Claude Code