Refactor the application package within ruff's complexity limits

[anth-volk]

Fixes #3930

Summary

Phase 1 step 1.8, group 8b, part 2 of 3: the rest of policyengine_api/, refactored within ruff's complexity limits. Stacked on #3932.

• All 89 findings in scope are fixed by refactoring, with no complexity or argument suppressions. Before each refactor, a commit adds characterization tests that pin current behaviour; 249 in all. A new tests/fixtures/recording_session.py records every statement, compiled for PostgreSQL, and every ORM write, in order.
• ASGI shell (asgi_factory, complexity 34 and 113 statements):
  • Lifespan, exception handlers and router wiring move to module level.
  • Per-request work moves into named steps: request context, telemetry, the route call and the response.
  • A new test pins the exact order of runtime and logger calls.
• Flask routes:
  • Household route errors are mapped by helpers that keep the old except precedence.
  • Saved-policy writes share configuration, mirror and failure steps.
  • Simulation identity checks move into their own step.
  • View signatures are unchanged.
• v2 services and routes:
  • Household and policy failures map through ordered error tables (run_v2_operation).
  • Household document validation and v1 household translation are split into collection, record and membership steps.
  • ComparisonReportRecord.validate_state keeps its Pydantic signature, with its checks split into helpers.
  • The parameter-value listing route takes one frozen ParameterValueListingQuery dependency; its OpenAPI is byte-identical.
• Data layer:
  • Catalog extraction splits into verification, selection and normalization steps, called in the same order.
  • Staging row generators move to module level.
  • Legacy user-policy persistence takes one revision value; a new test pins every statement and write in order.
  • Report and simulation runs take NewReportOutputRun, NewSimulationRun and ReportRunPackageVersions.
• Migration logging and flags:
  • Route groups come from a path table.
  • A served request is logged from one ServedRequest value.
  • Explicit database sources are one value.
• Mirroring and other services:
  • Mirror outcome loggers take one outcome value, and saved-policy mirror collaborators are grouped.
  • GatewayAuthTokenProvider takes GatewayAuthCredentials.
  • Two dead pieces are removed: policy_service._create_new_policy, which had no callers, and an always-true lock flag.
• Magic numbers (25): each becomes a named constant or an HTTPStatus member, with messages unchanged.
• Reconciled with Update PolicyEngine bundle to 6.3.4 #3918 (merged while this was in progress):
  • The split catalog extraction's region helper uses Update PolicyEngine bundle to 6.3.4 #3918's _serialize_region_filter_value, so flat membership lists such as the England filter are stored as JSON arrays.
  • The pinned "unsupported filter value" case now uses a mapping, which is still refused, instead of a list, which Update PolicyEngine bundle to 6.3.4 #3918 now accepts.
  • Update PolicyEngine bundle to 6.3.4 #3918's literal 255 limit is now MAX_REGION_FILTER_VALUE_LENGTH, with the message text unchanged.

Testing

• The make test set at this branch's tip: 2,848 passed, which is the base plus part 1's 166 and this PR's 249.
• Behaviour comparisons against the base:
  • Parameter-value queries are identical.
  • 4,800 household translation and normalization outcomes are identical.
  • 63 catalog extraction mutations are identical.
• make typecheck-v2 is clean. mypy on the 28 changed application files outside that gate gives identical output to the base.
• ruff check, ruff format --check and the quality guards (migration-contracts, rules-registry, ci-scripts) pass.
• The FastAPI OpenAPI, the /v2/openapi.json preview, the legacy spec and every existing model and adapter schema are byte-identical, with and without OLD_SIMULATION_GATEWAY_URL set.
• Not run locally: tests/integration/test_v1_user_policy_dual_write.py needs MySQL and PostgreSQL; its 6 call sites were updated.
• CI: above the bottom of its stack, so only CI complete runs until the PRs below merge.

🤖 Generated with Claude Code