[anth-volk]

Fixes #4016

Do not merge yet. This PR may merge only after legacy.policyengine.org is no longer served, after Cloud Run request logs show no remaining traffic to the routes and countries it removes, and after the external uptime monitor that polls GET / is moved to /health. It is stacked on #4012.

Summary

• Routes only the legacy site or the documentation used are removed, from both the Flask application and the native routes: the v1 saved-policy routes (POST, GET, PUT /{country_id}/user-policy), the user-profile routes (POST, GET, PUT /{country_id}/user-profile), the policy search (GET /{country_id}/policies), the recent-simulations list (GET /simulations), the GET / landing page and GET /specification with its hand-written OpenAPI document. Code only they called goes too. POST /{country_id}/calculate stays: it served about 140,000 requests in 30 days, and its callers move first. The v1 saved-policy service and copying modules stay until dual-write is deleted.
• Health checks use /health. /health answers 503 {"status": "not_ready"} until the readiness probe passes (startup warmup finished, runtime configuration valid) and 200 {"status": "healthy"} after, taking over from /readiness-check. The Cloud Run startup probe and the seven health checks in push.yml (candidates, stable URLs and revision restores) poll it; a previous revision also answers 200 on /health once up, so a restore still passes its check. /liveness-check and /readiness-check are removed. This repository configures no load balancer health check: the public load balancer's backend is a serverless network endpoint group, which does not use one.
• Canada, Nigeria and Israel are no longer served. Their requests get the unknown-country 400 response before any read or write, and their model packages are no longer installed (uv.lock loses them and 13 packages only they needed). COUNTRIES, the package-name lists in constants.py and the loaded country models now derive from the one country list in policyengine_api/supported_countries.py.

Request logs (production, 30 days to 2026-10-19): user-policy and user-profile 0; GET /{country_id}/policies 13; GET /simulations 11; GET / about 24,300 (an uptime monitor and link previews); the three countries about 1,160 (784 from legacy.policyengine.org, 49 from app.policyengine.org, which PolicyEngine/policyengine-app-v2#1390 stops).

Migration notes

• Route groups covered: health, specification, policy (saved policies and search), user_profile (v1 profile routes), metadata (country list).
• What stays on the Flask/v1 path: every other v1 route, including POST /{country_id}/calculate.
• User-visible API changes: the removed routes and countries answer 404 or the unknown-country 400; /health answers 503 while an instance is not ready. ROUTE_IMPL_HEALTH and ROUTE_IMPL_SPECIFICATION no longer select a route but stay required by the deployment pipeline until the Flask fallback is removed.
• The app-v2 contract registry drops the removed requests and the generated contract documents are refreshed.

Rules

The session-ownership rule's enforcer now names test_flask_routes_do_not_manage_sessions (the check covers every Flask route module, instead of only the removed recent-simulations module). This changes rules/registry.toml, so it needs a review from a core developer other than the author.

Inline suppressions

None added.

Environment variables

• The startup probe (CLOUD_RUN_STARTUP_PROBE) keeps its existing provider: the default in .github/scripts/cloud_run_env.sh, which no workflow overrides; only the probed path changes. deploy_cloud_run_candidate.sh passes it to gcloud run deploy as before.
• The health checks in push.yml change only the URL path they poll; their inputs (steps.candidate.outputs.url, the stable URLs and the revisions to restore) come from the same earlier steps as before.
• /health now reads the same readiness inputs /readiness-check read (policyengine_api.readiness.validate_policy_runtime_configuration: the v1 source selectors, the v2 runtime database settings, user authentication and Auth0 management settings, and the SPM selection), all from the existing Cloud Run environment set by deploy_cloud_run_candidate.sh. Staging and production already pass this check on every deploy through /readiness-check. Not verified beyond that: staging has no Auth0 management settings while production does; the check accepted that configuration on /readiness-check, and /health uses the same function.
• The cross-database integration workflow now runs uv sync --frozen --extra dev; it reads no new variables (its database URLs are literals for its own service containers).
• No new variables, secrets or Terraform. Removing the three packages changes the image contents only; the Cloud Run image installs with uv sync --frozen --no-dev, which never included the dev tools.

What this PR waits for

1. legacy.policyengine.org no longer served (an operator step).
2. Cloud Run request logs showing no traffic to the removed routes and the three countries.
3. The external uptime monitor moved from GET / to /health (an operator step), and any other external monitor or probe that polls /liveness-check or /readiness-check moved too.
4. Add a v2 countries table that matches one country list in code, GET /v2/countries and a startup check #4012 merged first (this PR is stacked on it) and Offer only the US and the UK in the calculator policyengine-app-v2#1390 merged, so the calculator no longer requests the three countries.
5. Review, including a core developer for the rule change.

Testing

Each commit was written test-first:

• 6426607b0 (route removal): 4 tests failed first (the removed routes were still registered in the Flask blueprints and assembled by the app module, and the ASGI app still served /specification); then 217 passed in the route boundary, ASGI factory, request lifecycle, contract and runtime-cache tests.
• b6f75f19c (health checks): 26 tests failed first across the ASGI factory, deploy scripts, push workflow, boot smoke test, runtime measurement, request lifecycle, route boundaries and baseline capture; then 770 passed in those suites and the routes, contract and to-refactor API tests.
• df07a5c3d (countries): 17 tests failed first (lists, dependencies and current-law IDs still named the three countries, their writes reached the services, and a country added to the one list did not reach the v1 lists); then the unit, contract and to-refactor suites passed (3,304).
• 8e4b2d6e9 (review follow-up): 2 tests failed first (HEAD /health answered 404); then 633 passed in the affected suites.
• 379885d41 (CI follow-up): dropping policyengine-canada also dropped coverage from the environment uv sync --frozen installs (it was the only default dependency that pulled it in), so the cross-database integration workflow failed to start its tests. The workflow now installs the dev extra; its workflow test failed first, then passed.
• Against disposable MySQL 8.4 and PostgreSQL 17: tests/integration/test_v2_country_routes.py, test_v2_metadata_routes.py, test_v1_household_dual_write.py and test_v1_policy_dual_write.py pass (23).
• On every commit: ruff format --check ., ruff check ., uv run --frozen --extra dev mypy, python scripts/run_quality_guards.py, python -m scripts.rules guard --base-ref origin/master; uv lock --check passes after the lock change.

One review round found no bugs; its follow-ups are the last commit.

🤖 Generated with Claude Code

[vahid-ahmadi]

Review at 379885d41f.

Verdict: the change itself looks correct; it is ready once the four operator steps in the description are done and #4012 has merged. Stacked on #4012, so I reviewed only v2plan/1g-126-countries-table...v2plan/1g-128-remove-unused-routes. No must items.

1. should policyengine_api/fastapi_routes/health.py:62: /health now returns 503 whenever readiness_probe() fails, at any point in the instance's life, not only during warmup. That is right for the startup probe and the deploy checks, but once the uptime monitor moves to /health, an invalid runtime setting (for example a v2 secret that stops resolving, which Add a v2 countries table that matches one country list in code, GET /v2/countries and a startup check #4012's docstring says readiness reports) will page as "API down" while v1 is still serving. Worth deciding whether the external monitor should alert on that, or whether it needs a separate always-200 liveness path. Either way, a sentence in docs/migration/cloud-run-operations.md would help whoever moves the monitor.
2. nit Outside this repo: PolicyEngine/policyengine-skills skills/policyengine-api/SKILL.md:44 (and the same file in policyengine-claude) still lists /specification, /liveness-check and /readiness-check. Worth a follow-up so agents stop pointing people at removed routes.

Checked and fine:

• I searched the PolicyEngine org for callers of the removed routes. policyengine-app-v2 uses user-policy-associations (a different path), not /{country_id}/user-policy. I found no callers of user-profile, the policy search or /simulations against this API (policyengine-chat calls /simulations/ on v2.api.policyengine.org, a different service).
• The restore steps poll /health on the previous revision, which already answers 200 there, so a restore still passes.
• COUNTRIES, the package lists and the current_law_id now come from the one list, so v1 and v2 cannot disagree.

What I ran: fresh clone, uv sync --frozen --extra dev on this head, then pytest on every added or changed file under tests/unit and tests/contract: 681 passed. CI does not run here because the PR is stacked (the CI complete gate fails on purpose), so the full suite, the Docker build and the integration tests have not run on this head. I did not read the 1,344-line openapi_spec.yaml deletion or the deleted tests line by line.

🤖 Generated with Claude Code