Route API v1 simulations through the Stage 5 entrypoint

[anth-volk]

Summary

• introduce a generic SimulationAPIClient and retain compatibility aliases for the former Modal-specific client;
• keep the old Modal gateway URL and the new Cloud Run Simulation Entrypoint URL independently configured;
• select the simulation entrypoint through validated, Git-controlled deployment configuration;
• keep the initial release pinned to SIM_ENTRYPOINT=old_gateway_direct;
• remove the manual percentage-ramp mechanism;
• deploy tagged, no-traffic Cloud Run API candidates, test them, and automatically assign 100% of stable service traffic to the exact tested revision;
• revalidate the candidate revision and immutable image before promotion, guard against concurrent traffic changes, and automatically restore the prior exact revision after an immediate promotion or stable-health failure; and
• require the complete staging sequence to pass before any production deployment begins.

Why

API v1 needs to adopt the separate Stage 5 simulation service boundary without coupling that code change to the eventual routing switch. Keeping both targets selectable allows the new client and deployment machinery to be qualified while API v1 continues to call the existing Modal gateway directly.

Every qualified API v1 release should still become the stable Cloud Run API release without an operator-run traffic ramp. The deployment workflow therefore promotes the exact tested API revision automatically, while the later simulation-path cutover remains a small Git change from old_gateway_direct to cloud_run_simulation_entrypoint.

Impact

This PR does not change API v1's active simulation network path: staging and production are both Git-pinned to the direct old-gateway mode. It does change API v1's Cloud Run release process so that successful staging and production candidates automatically receive 100% of their service's stable traffic, with exact-revision verification and immediate rollback protection.

Existing imports remain available through explicit compatibility aliases. Both simulation URLs remain configured so a later, independently reviewed PR can flip the selector without another client refactor.

Root cause

The previous client and deployment configuration assumed that API v1 called the Modal-hosted gateway directly. The first rollout design then coupled the simulation routing choice to an operator-run percentage ramp and left API Cloud Run service promotion manual. That did not match the desired release model: fully qualify staging, deploy production automatically, promote the exact tested release, and make the eventual simulation entrypoint switch through Git.

Validation

• 192 simulation client, gateway-contract, economy, and budget-window tests passed.
• 60 deployment and ASGI tests passed.
• The final focused deployment-script suite passed all 47 tests after exact candidate revision/image revalidation was added.
• The Cloud Run image built successfully and returned {"status":"healthy"} from /health and 200 OK from /readiness-check in a local runtime smoke test.
• Actionlint, ShellCheck, Bash syntax, Ruff, formatting, migration contract guards, generated-contract diff validation, YAML parsing, Python compilation, and git diff --check passed.
• Tests cover direct/new URL selection, startup validation, App Engine packaging, no-traffic deployment, exact-revision promotion, stale-state rejection, automatic rollback state transitions, full staging gating, and the absence of manual ramp or LATEST/tag-based traffic promotion.

Fixes #3775

[codecov]

Codecov Report

❌ Patch coverage is 97.20670% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.71%. Comparing base (e004986) to head (357f7e6).
⚠️ Report is 17 commits behind head on master.

Files with missing lines	Patch %	Lines
policyengine_api/libs/simulation_entrypoint.py	96.81%	3 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #3776      +/-   ##
==========================================
+ Coverage   80.03%   80.71%   +0.67%     
==========================================
  Files          70       74       +4     
  Lines        4342     4422      +80     
  Branches      809      822      +13     
==========================================
+ Hits         3475     3569      +94     
+ Misses        648      623      -25     
- Partials      219      230      +11     

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