Implement Stage 11 API v2 household migration

[anth-volk]

Summary

• add immutable native /v2/households resources and mutable /v2/user-households associations backed by Supabase/Postgres
• copy selected US and UK API v1 household creates after Cloud SQL commits, retain exact-event operator replay, and add staging activation/rollback qualification
• correct Stage 10 policy mirroring so its snapshot uses the MySQL-stored JSON representation before v2 canonicalization

Migration scope

The household, user-household, and household migration workflow contracts are covered. API v1 household POST, GET, calculation, and all unrelated route groups remain on Flask and Cloud SQL. API v1 household PUT is intentionally removed because base households are immutable and no app-v2 caller uses it.

This prepares FastAPI household and association routes, SQLAlchemy/SQLModel models, separate Alembic revisions for Cloud SQL and Supabase, exact-event replay, Cloud Run configuration validation, generated migration contracts, and staging exercises. Production activation is intentionally not performed by this PR work.

Validation

• formatting and Ruff checks pass on all changed Python files
• MyPy passes for 83 configured files
• 277 Stage 10 focused unit/contract tests pass
• 294 Stage 11 focused unit/contract tests pass
• 169 migration-contract and deployment-script tests pass
• 36 disposable MySQL/Postgres lifecycle and cross-database tests pass
• 17 focused Stage 10 MySQL regression and service tests pass
• migration contract export and repository migration checks pass

[codecov]

Codecov Report

❌ Patch coverage is 85.40419% with 195 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.91%. Comparing base (37e168a) to head (a48178a).

Files with missing lines	Patch %	Lines
policyengine_api/data/v2/runtime_privileges.py	0.00%	42 Missing ⚠️
...icyengine_api/services/v2/households/validators.py	78.37%	12 Missing and 12 partials ⚠️
policyengine_api/services/household_service.py	77.22%	13 Missing and 10 partials ⚠️
...gine_api/services/v2/households/transformations.py	84.28%	10 Missing and 12 partials ⚠️
policyengine_api/fastapi_routes/dependencies.py	25.00%	10 Missing and 8 partials ⚠️
...olicyengine_api/services/v2/households/services.py	75.36%	15 Missing and 2 partials ⚠️
policyengine_api/routes/household_routes.py	70.21%	13 Missing and 1 partial ⚠️
...e_api/data/v2/household_migration_qualification.py	90.82%	8 Missing and 2 partials ⚠️
policyengine_api/services/household_mirroring.py	84.09%	5 Missing and 2 partials ⚠️
...yengine_api/fastapi_routes/v2/households/routes.py	93.50%	3 Missing and 2 partials ⚠️
... and 9 more

Additional details and impacted files

@@             Coverage Diff             @@
##           master    #3817       +/-   ##
===========================================
+ Coverage   46.26%   86.91%   +40.65%     
===========================================
  Files         135      177       +42     
  Lines        7963    10228     +2265     
  Branches     1326     1755      +429     
===========================================
+ Hits         3684     8890     +5206     
+ Misses       3990      839     -3151     
- Partials      289      499      +210     

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