Stage 2: Add FastAPI shell with Flask fallback

[anth-volk]

Fixes #3642

Summary

• Add a FastAPI ASGI shell around the existing Flask app using WSGI middleware.
• Add a native ASGI /health endpoint while leaving existing v1 routes on Flask fallback.
• Add Flask-direct vs FastAPI-fallback contract clients and representative app-v2 route contract coverage.
• Add a local ASGI runbook and make debug-asgi command.
• Handle budget-window Modal 400/422 submission validation errors as structured budget-window errors while preserving auth, rate-limit, and server failures as exceptions.

Stage 2 Scope

Included:

• FastAPI process shell.
• Flask fallback for existing API v1 behavior.
• Representative route parity coverage for current app-v2 API v1 contracts.
• No production traffic shift.

Not included:

• Cloud Run deployment or traffic migration.
• Native FastAPI route implementation beyond /health.
• Supabase, Alembic, SQLAlchemy model migration, or schema changes.
• Modal compute migration.

Verification

• ruff check policyengine_api/asgi.py policyengine_api/asgi_factory.py policyengine_api/services/economy_service.py tests/contract/clients.py tests/contract/test_v1_route_contracts.py tests/unit/test_asgi_factory.py tests/unit/routes/test_migration_context_logging.py tests/unit/services/test_economy_service.py
• git diff --check
• FLASK_DEBUG=1 .venv/bin/python -m pytest tests/unit/test_asgi_factory.py tests/contract/test_v1_route_contracts.py tests/unit/routes/test_migration_context_logging.py tests/unit/services/test_economy_service.py::TestEconomyService::TestGetBudgetWindowEconomicImpact -q

[codecov]

Codecov Report

❌ Patch coverage is 96.36364% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.89%. Comparing base (71b6a2c) to head (d36050d).
⚠️ Report is 12 commits behind head on master.

Files with missing lines	Patch %	Lines
policyengine_api/asgi_factory.py	96.66%	0 Missing and 1 partial ⚠️
policyengine_api/services/economy_service.py	95.23%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #3643      +/-   ##
==========================================
+ Coverage   78.66%   78.89%   +0.22%     
==========================================
  Files          70       72       +2     
  Lines        4186     4241      +55     
  Branches      776      787      +11     
==========================================
+ Hits         3293     3346      +53     
  Misses        691      691              
- Partials      202      204       +2     

☔ View full report in Codecov by Sentry.
📢 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.