[anth-volk]

Fixes #897

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

The Simulation Entrypoint gets its own Postgres schema, simulation, in the database that holds the Public API's v2 tables. After this deploys, the entrypoint has a database connection and an empty simulation schema at revision 0001; nothing reads or writes it yet. This is the first of four stacked PRs (simulations and reports, runs and their recording, and result tables follow).

• Persistence library (libs/policyengine-simulation-persistence): schema and role names, the naming convention, a pooled runtime engine (psycopg 3, pre-ping, no server-side prepared statements, so the same URL works through Supabase's poolers) and a reader for the applied revision. A malformed URL is refused without repeating it.
• One migration chain at migrations/, version table simulation.alembic_version. The schema is created only when it is missing (an operator may create it in advance), the schema creation and every pending revision run in one transaction, and a statement waits at most ten seconds for a lock. Revision 0001 grants the runtime role schema usage, revision reads and default SELECT/INSERT/UPDATE on later tables.
• Migration job before each deploy (migrate_simulation_database in the reusable deploy workflow): it is the only job that receives SIMULATION_MIGRATION_DATABASE_URL, in one step's env:. Deployments from main run alembic upgrade head and then alembic current --check-heads; a deployment dispatched from any other branch only runs the head check, so it can never apply an unmerged revision. deploy_entrypoint runs only after the job succeeds.
• Runtime URL and readiness: the deploy script mounts SIMULATION_DATABASE_URL as a pinned Secret Manager version on every deploy. GET /ready reports simulation_database {reachable, revision, expected_revision} without changing its status; the candidate check requires the two revisions to match, asking again while a cold candidate has not reached the database.
• Deploy script: each runtime secret is now resolved in its own assignment. Before, an array assignment took its exit status from its last substitution only, so a failed lookup of an earlier secret was ignored and the revision deployed with an empty reference. The Stage 12 block uses its own wrapper.
• Rules: sim.stage12.no-migration-chain is replaced by sim.persistence.one-migration-chain, executor-independent, no-modal-database-credentials (no database URL in any Modal secret, deployment, temporary app or source, except the comparison path's own STAGE12_DATABASE_URL), migrate-before-entrypoint and migration-cycle, each with proof fixtures. sim.deploy.workflow-shell-safety and sim.deploy.container-context-minimal are tightened and now have proofs too.
• CI: a new Simulation database job runs the chain's upgrade, alembic check, downgrade and upgrade cycle and every database test on postgres:17, as a migrator role that is not a superuser; it is part of CI complete.

Environment variables

Variable	Read by	Provider	How it reaches the job
SIMULATION_DATABASE_URL	Entrypoint runtime	Secret Manager, in the project named by SIMULATION_ENTRYPOINT_GCP_PROJECT_ID	The deploy script resolves the secret named by SIMULATION_DATABASE_URL_SECRET_NAME to its newest enabled version and mounts it with gcloud run deploy --set-secrets
SIMULATION_DATABASE_URL_SECRET_NAME	Deploy script	GitHub environment variable (beta, prod)	env: of the deploy step in deploy_entrypoint
SIMULATION_MIGRATION_DATABASE_URL	Migration environment and script	GitHub environment secret (beta, prod)	The migration job declares environment: ${{ inputs.release_environment }}; both callers use secrets: inherit; only the "Apply simulation schema migrations" step's env: holds it
SIMULATION_MIGRATION_MODE	Migration script	Computed from github.ref	Same step's env:
REQUIRE_CURRENT_SIMULATION_DATABASE_REVISION	Candidate smoke script	Literal true	env: of the candidate check step
SIMULATION_DATABASE_READY_MAX_ATTEMPTS	Candidate smoke script	Optional, defaults to 6	Not set
SIMULATION_TEST_DATABASE_URL, SIMULATION_REQUIRE_DATABASE_TESTS	Persistence tests in CI	Literals	Job env: of Simulation database, pointing at its postgres:17 service

Not verified from the repository: that the secret, the secret-name variable and the migrator secret exist in beta and prod; that the project is policyengine-simulation-entry; that only the runtime service accounts can read the runtime secret and that the deploy account can list its versions; that both roles exist; and that GitHub-hosted runners can reach the database. Each missing piece stops the deploy rather than being skipped.

Waits for

• The operator step that creates the simulation_migrator and simulation_runtime roles, stores their URLs (the migrator URL as the beta/prod environment secret, the runtime URL in Secret Manager readable only by the runtime service accounts), sets SIMULATION_DATABASE_URL_SECRET_NAME, and grants the migrator REFERENCES on the Public API tables, in staging and production. Merging before it makes every deploy stop at the migration job.
• Migrations in the simulation chain merge one at a time; the PRs stacked above this one each add the next revision.

Testing

Every commit was checked: persistence tests on PostgreSQL 17 with database tests required (39 passed at the tip), the entrypoint suite (709 passed), the executor's workflow tests, the rules tool's tests and python -m scripts.rules guard, all four quality guards, Ruff with the CI-pinned version, uv lock --check, and Pyright for the persistence library and the entrypoint.

🤖 Generated with Claude Code