[anth-volk]

Fixes #931

Same-Repository Draft PR Check

• This PR is a draft.
• This PR is from a branch in PolicyEngine/policyengine-sim-api, not a personal fork.

Summary

This is the comparison step only. The public GET /versions and GET /versions/{kind} routes still forward to the old gateway, and their answers do not change. Switching those routes to the v2 version manifest is a separate, later change, made after the Public API's v1 economy and budget-window routes are removed (see "Why /versions does not switch here").

• POST /ping is answered by the Simulation Entrypoint itself: the request's value plus one as incremented, with the same request validation and status codes as before. The old gateway is no longer called for it, so /ping answers even when the old gateway is unreachable.
• New module policyengine_simulation_entry.v2_versions builds the /versions and /versions/{kind} answers from the v2 version manifest, in the old gateway's response models (VersionsResponse, VersionMap, PolicyEngineBundle). It shares no code with the forwarding routes.
  • Routes name the v2 worker applications.
  • A model version contained in several bundles routes to the newest bundle by version number. The old gateway routes it to the bundle published last, which is the same bundle in staging and production today.
  • latest is the manifest's default version; each country's latest is that bundle's model version.
  • spm_capabilities is empty, because the manifest records no SPM capability.
• New internal routes GET /internal/v2/versions and GET /internal/v2/versions/{kind} serve those answers. They are public like /versions, left out of the OpenAPI document, and deployed to both environments.
  • An unknown kind gives 404 with the old gateway's message (Unknown version kind: …).
  • A manifest that is not configured, cannot be read, or takes over 5 seconds gives 503 with Retry-After: 10.
  • The manifest is read from the same Modal Dict the Stage 12 path reads, on a thread of its own.
• Each staging deploy runs .github/scripts/compare_versions_sources.py against its candidate revision, right after the smoke check. It reads /versions, each /versions/{kind} and an unknown kind from both sources, and writes every difference to the job summary.
  • Routes are compared by the PolicyEngine version each application serves, because the old gateway names v1 applications and the manifest names v2 ones.
  • The step only reports. It exits 0 whatever it finds, so it never fails a deploy, because the sources are known to differ today.

Why /versions does not switch here

The Public API reads /versions while it serves requests, not only in its release checks.

• Application names. The Public API's v1 economy and budget-window routes resolve the worker application through /versions/{country} or /versions/policyengine. They put that name into the key they store results under, and they recalculate a stored result whenever the name differs from the resolved_app_name the old gateway reports. The manifest names v2 applications (policyengine-simulation-v2-py…) while the old gateway reports v1 ones (policyengine-simulation-py…), so switching while those routes exist would recalculate on every read. The switch therefore comes in a later change, after those routes are removed.
• SPM capabilities. The Public API reads spm_capabilities to validate US SPM selections, and its release check (--check-installed-spm) requires a capability for the bundle it ships. The v2 manifest records none today. It will record them as part of the later switch, not in this PR.
• Versions older than the manifest. Production's routing state also lists versions published before the v2 manifest existed: 4.18.3, 4.18.5, 4.18.7, 4.18.8, 4.18.9, 4.20.3 and 4.22.0, their model-version routes, and some older per-country applications. What /versions answers for them is decided with the later switch, once request logs show whether anything still asks for them.

The same comparison, run locally on answers recorded from both environments, found:

• Staging: the same versions and routes in both sources. The only differences were the missing SPM capabilities, and dataset digests that only the manifest records for four older versions.
• Production: 77 differences, mostly the older versions above.

Choices still open for review

These choices were made in this PR and are open for a reviewer to change:

1. The staging comparison only reports. It exits 0 whatever it finds, so it never fails a deploy while the sources are known to differ.
2. /ping is answered by the entrypoint without a staging comparison. Its answer does not come from the manifest. Unit tests and the existing deploy smoke check (incremented == 2) show it gives the old gateway's answer.
3. A model version contained in several bundles routes to the newest bundle by version number. The old gateway routes it to the bundle published last, which is the same bundle in staging and production today.

Before this PR may merge

• A person's review.
• CI: the runs on this branch were cancelled at the user's request, so the checks have to run before merging.
• Merge coordination with Calculate a household under several policies in one call with v2 Modal household functions #903, which changes the v2 manifest model. If Calculate a household under several policies in one call with v2 Modal household functions #903 merges first, this branch is rebased and its tests are run again. The tests build manifests by copying the Stage 12 test worker, so they follow that model.

Environment variables

No new variables. The internal routes use values the entrypoint revision already receives whenever deploy_stage12_v2 is true, which it is for both beta and prod:

Variable	Provider	How it reaches the code
STAGE12_V2_MANIFEST_NAME	Literal simulation-api-v2-version-manifest in deploy-cloud-run-simulation-entry.sh	The script's --env-vars-file for gcloud run deploy, so it is a runtime environment variable on the revision
STAGE12_V2_MANIFEST_ENVIRONMENT	The reusable workflow input modal_environment (staging or main)	Job env: MODAL_ENVIRONMENT in deploy_entrypoint, then the deploy script's --env-vars-file
MODAL_TOKEN_ID, MODAL_TOKEN_SECRET	Secret Manager secrets named by the beta/prod GitHub environment variables MODAL_TOKEN_ID_SECRET_NAME and MODAL_TOKEN_SECRET_SECRET_NAME	Job env: in deploy_entrypoint, then the deploy script pins each secret's newest enabled version and mounts it with --set-secrets; the Modal client reads both from the environment
CANDIDATE_URL (comparison step)	Job output deploy_entrypoint.outputs.candidate_url	Step env: in the integration job, passed to the script as its argument
GITHUB_STEP_SUMMARY (comparison step)	The GitHub Actions runner	Set by the runner for every step

Not verified: that the runtime's Modal token can read the manifest Dict in each environment. The Stage 12 code in the same revision already reads that Dict with the same token, but the read was not tested for this PR.

Testing

Run locally on every commit; all passed:

• uv tool run ruff@0.15.22 format --check and uv tool run ruff@0.15.22 check .
• python scripts/run_quality_guards.py
• python -m scripts.rules pyright --sync projects/policyengine-simulation-entry
• uv run --frozen pytest tests/ in projects/policyengine-simulation-entry: 809 passed on the branch head
• The executor tests that read the deploy workflow (test_modal_scripts.py, test_update_v2_version_manifest.py, test_update_version_registry.py): 347 passed

New tests:

• test_v2_versions.py: the manifest's answers, including a check against the shape of the gateway's recorded answer.
• test_v2_versions_routes.py: the internal routes and the manifest source.
• test_compare_versions_sources.py: the comparison logic, whole runs against a local HTTP server, and the workflow step.
• test_app.py: /ping.

The comparison was also run end to end against the app on 127.0.0.1, serving answers recorded from staging and production.

🤖 Generated with Claude Code