Correct documentation drift and share one revision helper in the tests

- The persistence README's test commands and the Alembic configuration's
  example now use --frozen, as every install and test run must.
- DEPLOYMENT.md said the candidate smoke asks again "up to six times"; the
  default of six is six requests in all.
- The deploy script's comment on the Stage 12 wrapper now says what is
  separate (the wrapper) and what both blocks still use (the secret
  lookups that predate the split).
- The migration-cycle and migration-script tests read the applied revision
  through one helper in migration_support instead of two copies.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: anth-volk

.github/scripts/deploy-cloud-run-simulation-entry.sh

@@ -70,8 +70,9 @@ add_runtime_secret() {
   runtime_secrets+=("${variable_name}=${resolved_reference}")
 }
 
-# The Stage 12 comparison path's own copy, so it shares no deploy helper with
-# the main path and is removed with it.
+# The Stage 12 comparison path's own wrapper, removed with it, so the main
+# path's wrapper can change without touching the Stage 12 block. Both use the
+# secret lookups above, which predate the split.
 add_stage12_runtime_secret() {
   local variable_name="$1"
   local resolved_reference

libs/policyengine-simulation-persistence/README.md

@@ -102,8 +102,8 @@ the same time rebases onto the new head after the first merges.
 ## Tests
 
 ```bash
-uv sync --extra test
-uv run pytest tests/
+uv sync --frozen --extra test
+uv run --frozen pytest tests/
 ```
 
 Tests marked `postgres` need a disposable PostgreSQL server. Point

libs/policyengine-simulation-persistence/tests/migration_support.py

@@ -7,6 +7,10 @@
 
 from alembic import command
 from alembic.config import Config
+from policyengine_simulation_persistence import (
+    create_simulation_engine,
+    read_schema_revision,
+)
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -59,3 +63,13 @@ def migration_cycle_failures(config: Config, *, check: bool) -> list[str]:
         if failure is not None:
             return [failure]
     return []
+
+
+def applied_revision(database_url: str) -> str | None:
+    """Return the revision the database at ``database_url`` has applied."""
+    engine = create_simulation_engine(database_url)
+    try:
+        with engine.connect() as connection:
+            return read_schema_revision(connection)
+    finally:
+        engine.dispose()

libs/policyengine-simulation-persistence/tests/test_migration_cycle.py

@@ -10,30 +10,21 @@
     MIGRATOR_ROLE,
     REPOSITORY_ROOT,
     alembic_config,
+    applied_revision,
     chain_config,
     migration_cycle_failures,
 )
 from policyengine_simulation_persistence import (
     HEAD_REVISION,
     SIMULATION_SCHEMA,
     create_simulation_engine,
-    read_schema_revision,
 )
 from sqlalchemy import create_engine, inspect, text
 from sqlalchemy.exc import OperationalError, ProgrammingError
 
 pytestmark = pytest.mark.postgres
 
 
-def _revision(database_url: str) -> str | None:
-    engine = create_simulation_engine(database_url)
-    try:
-        with engine.connect() as connection:
-            return read_schema_revision(connection)
-    finally:
-        engine.dispose()
-
-
 def _superuser_engine(database, **options):
     return create_engine(
         database.superuser_url.replace("postgresql://", "postgresql+psycopg://", 1),
@@ -45,10 +36,10 @@ def test_upgrade_check_downgrade_upgrade_cycle(disposable_database) -> None:
     config = alembic_config()
 
     assert migration_cycle_failures(config, check=True) == []
-    assert _revision(disposable_database.migrator_url) == HEAD_REVISION
+    assert applied_revision(disposable_database.migrator_url) == HEAD_REVISION
 
     command.downgrade(config, "base")
-    assert _revision(disposable_database.migrator_url) is None
+    assert applied_revision(disposable_database.migrator_url) is None
 
 
 def test_rule_proof_migration_cycle(disposable_database) -> None:
@@ -93,7 +84,7 @@ def test_the_version_table_lives_only_in_the_simulation_schema(
 
 
 def test_an_unmigrated_database_reports_no_revision(disposable_database) -> None:
-    assert _revision(disposable_database.migrator_url) is None
+    assert applied_revision(disposable_database.migrator_url) is None
 
 
 def _precreate_schema_without_database_create(database) -> None:
@@ -130,16 +121,16 @@ def test_a_precreated_schema_needs_no_database_create_privilege(
 
     command.upgrade(alembic_config(), "head")
 
-    assert _revision(disposable_database.migrator_url) == HEAD_REVISION
-    assert _revision(disposable_database.runtime_url) == HEAD_REVISION
+    assert applied_revision(disposable_database.migrator_url) == HEAD_REVISION
+    assert applied_revision(disposable_database.runtime_url) == HEAD_REVISION
 
 
 def test_the_runtime_role_reads_the_revision_but_cannot_change_the_schema(
     disposable_database,
 ) -> None:
     command.upgrade(alembic_config(), "head")
 
-    assert _revision(disposable_database.runtime_url) == HEAD_REVISION
+    assert applied_revision(disposable_database.runtime_url) == HEAD_REVISION
     engine = create_simulation_engine(disposable_database.runtime_url)
     try:
         with (

libs/policyengine-simulation-persistence/tests/test_migration_script.py

@@ -7,11 +7,13 @@
 from pathlib import Path
 
 import pytest
-from migration_support import MIGRATION_DATABASE_URL_VARIABLE, REPOSITORY_ROOT
+from migration_support import (
+    MIGRATION_DATABASE_URL_VARIABLE,
+    REPOSITORY_ROOT,
+    applied_revision,
+)
 from policyengine_simulation_persistence import (
     HEAD_REVISION,
-    create_simulation_engine,
-    read_schema_revision,
 )
 
 pytestmark = pytest.mark.postgres
@@ -35,26 +37,17 @@ def _run_script(database, mode: str) -> subprocess.CompletedProcess[str]:
     )
 
 
-def _revision(database) -> str | None:
-    engine = create_simulation_engine(database.migrator_url)
-    try:
-        with engine.connect() as connection:
-            return read_schema_revision(connection)
-    finally:
-        engine.dispose()
-
-
 def test_verify_mode_refuses_a_database_behind_the_chain(disposable_database) -> None:
     result = _run_script(disposable_database, "verify")
 
     assert result.returncode != 0
-    assert _revision(disposable_database) is None
+    assert applied_revision(disposable_database.migrator_url) is None
 
 
 def test_upgrade_mode_migrates_and_then_verify_mode_passes(disposable_database) -> None:
     upgraded = _run_script(disposable_database, "upgrade")
     assert upgraded.returncode == 0, upgraded.stderr
-    assert _revision(disposable_database) == HEAD_REVISION
+    assert applied_revision(disposable_database.migrator_url) == HEAD_REVISION
 
     verified = _run_script(disposable_database, "verify")
     assert verified.returncode == 0, verified.stderr

migrations/alembic.ini

@@ -1,6 +1,6 @@
 # The Simulation Entrypoint's only Alembic chain: the `simulation` schema.
 # Run it from the persistence library's environment, for example:
-#   uv run --project libs/policyengine-simulation-persistence --extra migrations \
+#   uv run --frozen --project libs/policyengine-simulation-persistence --extra migrations \
 #     alembic -c migrations/alembic.ini upgrade head
 # The database URL comes only from SIMULATION_MIGRATION_DATABASE_URL.
 # Ownership rules: libs/policyengine-simulation-persistence/README.md

projects/policyengine-simulation-entry/DEPLOYMENT.md

@@ -49,8 +49,9 @@ read it. Modal never receives either URL.
 image expects, under `simulation_database`. The database does not change the
 readiness status, because no old-gateway or Stage 12 route uses it. The
 candidate smoke check requires the two revisions to match, which shows that the
-runtime secret reached the revision and the migration ran. It asks again, up to
-six times, while a cold candidate has not reached its database yet; the stable and
+runtime secret reached the revision and the migration ran. While a cold
+candidate has not reached its database yet, it asks again, up to six requests
+in all; the stable and
 rollback checks do not, because an older image may run against a newer schema.
 The ownership rules and roles are described in
 `libs/policyengine-simulation-persistence/README.md`.