[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. #4012, which it was stacked on, has merged, and it now targets master.

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

Since legacy.policyengine.org stopped serving (2026-10-30, 15:55 UTC), production request logs to 17:15 UTC show no requests to user-policy, user-profile, GET /{country_id}/policies, GET /simulations, /specification, /liveness-check or /readiness-check. GET / had 46 (the uptime monitor and link previews), and the three countries had 9 (8 from a local test run). These counts need more days before this PR merges.

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 already runs uv sync --frozen --extra dev on master; this PR only makes its workflow test require the dev extra, which the workflow needs once policyengine-canada no longer brings coverage in. 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). Done on 2026-10-30.
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. Offer only the US and the UK in the calculator policyengine-app-v2#1390 merged, so the calculator no longer requests the three countries. (Add a v2 countries table that matches one country list in code, GET /v2/countries and a startup check #4012 merged on 2026-10-30.)
5. Review, including a core developer for the rule change.

Testing

Each commit was written test-first:

• 054ad2f0b (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.
• a9003ffad (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.
• 630ca6461 (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).
• 72f8090be (review follow-up): 2 tests failed first (HEAD /health answered 404); then 633 passed in the affected suites.
• b54882286 (CI follow-up): dropping policyengine-canada also drops coverage from the environment uv sync --frozen installs (it was the only default dependency that pulled it in), and the cross-database integration workflow runs its tests under coverage. master already installs the dev extra there; the workflow test now requires it.
• Rebase onto master (2026-10-30). The counts above were measured before the rebase. Tests master added since then used code this PR removes, and failed on the rebased branch (12 cases); each was fixed in the commit that removes that code. The local-area breakdown tests read the impact cache directly instead of the removed get_recent_reform_impacts, the parameter-path tests query the policy table instead of the removed policy search, and the release-test shard weights drop the deleted saved-policy route tests. The /health changes to the deployment-script tests moved into the files master split them into, and uv.lock was relocked from master's (it still loses only the three packages and the 13 only they needed). All 12 cases pass, and ruff format --check ., ruff check ., mypy, python scripts/run_quality_guards.py, the rules guard and uv lock --check pass on the rebased head.
• 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 fourth commit. After the rebase, two review rounds on the conflict resolution: the first found the test changes described above, and the second found no bugs.

🤖 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

[codecov]

Codecov Report

❌ Patch coverage is 69.23077% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 51.45%. Comparing base (424cf47) to head (b548822).
⚠️ Report is 12 commits behind head on master.

Files with missing lines	Patch %	Lines
policyengine_api/country.py	0.00%	2 Missing ⚠️
policyengine_api/fastapi_routes/health.py	71.42%	2 Missing ⚠️

❗ There is a different number of reports uploaded between BASE (424cf47) and HEAD (b548822). Click for more details.

HEAD has 1 upload less than BASE

Flag	BASE (424cf47)	HEAD (b548822)
	2	1

Additional details and impacted files

@@             Coverage Diff             @@
##           master    #4017       +/-   ##
===========================================
- Coverage   88.11%   51.45%   -36.67%     
===========================================
  Files         285      267       -18     
  Lines       16577    15026     -1551     
  Branches     2712     2399      -313     
===========================================
- Hits        14607     7731     -6876     
- Misses       1292     6656     +5364     
+ Partials      678      639       -39     

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