[anth-volk]

Fixes #995

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.

Changelog

• This PR adds a changelog fragment, changelog.d/<name>.<type>.md, whose type is breaking, added, changed, fixed or removed: changelog.d/b2-public-api-schema-check.added.md.

Summary

sim's CI now fails when its models of the Public API's tables (from the pull request below this one) differ from the tables the Public API's own v2 migration chain creates.

• Public API schema job (pr.yml): checks out PolicyEngine/policyengine-api, which is public, at the commit pinned in libs/policyengine-simulation-persistence/public-api-commit, without persisting any credential (neither checkout keeps the job's token, since the job runs the Public API's code). public-api-schema-reference.sh builds the Public API's tables with its chain into the job's PostgreSQL 17 and grants the privileges its manifest declares. The job then runs the persistence tests marked public_api_schema, which fail rather than skip there:
  • the comparison builds the models' tables from service_metadata in a disposable database and reads both through PostgreSQL's catalog (tests/schema_comparison.py): every column's type, nullability and default, every primary key, unique, foreign key, check and exclusion constraint and every other index by name and PostgreSQL's own definition, and every enum's values, in both directions;
  • the simulation service's role creates a row in every modelled table and lacks none of the privileges the service needs;
  • last, the pinned commit must be on the Public API's master, so the models only ever describe a chain the Public API has merged.
    CI complete needs the job.
• Choosing and keeping the pin. Pin the Public API commit whose chain the models describe: the merge commit of the Public API change that last altered a modelled table or the service role's grants, or, while that change is a pull request, its head (after a squash or rebase merge, move the pin to the commit that landed). A sim pull request that changes the models moves the pin with them. The new Public API schema drift workflow runs the same tests every Monday and on demand against the head of the Public API's master, so a merged change there shows up without waiting for a sim change.
• Rule sim.persistence.models-match-public-api, with a proof whose bad models copy simulation_runs.status as a varchar and leave out modal_call_id. A test keeps every test the rule names in the jobs that run it. Every script the jobs call is tested with fake commands.

Environment variables

None is a secret, and the jobs read no secret.

Variable	Read by	Provider	How it reaches the step
SIMULATION_TEST_DATABASE_URL, PUBLIC_API_SCHEMA_DATABASE_URL, SIMULATION_REQUIRE_DATABASE_TESTS, SIMULATION_REQUIRE_PUBLIC_API_SCHEMA	The persistence tests; the reference script	Literals pointing at the job's postgres:17 service	Job-level env: of public-api-schema and of public-api-schema-drift
commit (step output)	The Public API checkout's ref	public-api-schema-commit.sh, from the pin file	GITHUB_OUTPUT
PUBLIC_API_SCHEMA_COMMIT	The comparison's failure message	public-api-schema-reference.sh	GITHUB_ENV
V2_MIGRATION_DATABASE_URL, V2_ALEMBIC_DISPOSABLE_TEST, DEPLOYMENT_ENVIRONMENT, UV_PYTHON	The Public API's migration and privilege commands	Exported by public-api-schema-reference.sh from PUBLIC_API_SCHEMA_DATABASE_URL and literals (1, ci, 3.12)	The script's own child processes

What this waits for before merging

1. The pull request below this one (the simulation service's database connection and its table models), and everything it waits for.
2. The Public API's pull request that creates and reshapes these tables (Record each run of a v2 simulation and report, and key results by run policyengine-api#4162), merged: until then this job's last step fails, saying the pinned commit is not on the Public API's master. The pin is that pull request's head, d674032a2, which sits on the Public API's master at 528cef1f4. If the pull request is moved again, or lands by squash or rebase, the pin moves with it.
3. One approving review.

Testing

Built on the pull request below (its head 21760a9). The pin moved from c9c6eb6d3 to d674032a2 when the Public API's pull request was moved onto its master; the comparison and the role-write tests pass against a database built at d674032a2. Every commit was written test first: the new or changed tests were run by node ID and seen to fail for the expected reason, then to pass. Before each commit, Ruff (the CI-pinned version), the quality guards with the rules registry, the generated rules document, uv lock --check for the persistence library and Pyright passed. Against a PostgreSQL 17 database built by public-api-schema-reference.sh from the Public API at the pinned commit: the comparison found no difference, a deliberate model difference (simulation_runs.output_sha256 modelled as NOT NULL) made it fail, and the role-write tests passed. During review, the default-branch check was tried against scratch clones of the Public API: a merged commit passes, and the open pull request's head fails with the expected message. Only the tests this pull request adds or changes were run locally; this push's GitHub Actions runs report the rest, and this job fails at its last step until the Public API's pull request merges.

🤖 Generated with Claude Code