[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, after the Public API's tables their keys name (referenced_metadata, each by its id alone), and reads the models' tables and the Public API's 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 modelled tables' foreign keys to the Public API's own tables (users, policies, dynamics, households, datasets, regions and the model catalog) are exactly the 20 named in tests/public_api_keys.py, so a change to them shows even when the models follow it (a test outside the rule);
  • 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. When that comparison fails, a second job (report-public-api-schema-drift, needs: the comparison with if: failure()) runs public-api-schema-drift-issue.sh: it comments on the open issue labelled public-api-schema-drift, or opens one with the run's address and what to do. Only that job may write issues, with the workflow's own token; it checks out sim alone and never the Public API, and the comparison job's token stays read-only. The pin still moves only in a pull request.
• 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
GH_TOKEN	gh in public-api-schema-drift-issue.sh	GitHub's automatic workflow token (github.token), limited by the reporting job's permissions: to contents: read and issues: write	Step env: of "Open or comment on the drift issue"
GH_REPO	gh in the same script	The github.repository context	Same step env:
GITHUB_SERVER_URL, GITHUB_REPOSITORY, GITHUB_RUN_ID	The same script, for the failed run's address	GitHub's default variables	Set by the runner in every step; the script stops before any gh call if one is missing

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, 772ca6b14, which merged the Public API's master at 90b212b51. The Public API merges pull requests with a merge commit, which keeps the head on master. If the pull request gets new commits, or lands by squash or rebase, the pin moves with it.
3. One approving review.

Testing

Built on the pull request below (its head c49d22c, with sim's main merged in), merged in rather than rebased, so neither branch is rewritten. The pin moved from c9c6eb6d3 to d674032a2 when the Public API's pull request was moved onto its master, then on 2026-11-06 to 772ca6b14, which carries the tables the user decided on 2026-11-05. Against a database built at d674032a2 the new models fail the comparison and the keys test finds none of the 20 keys; against one built at 772ca6b14 the comparison, the keys test and the role-write tests pass. 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. The drift report's script is tested with a fake gh that applies the script's own --jq filter: a first failure opens an issue with the label, a later one comments on the open issue, and a failed GitHub request fails the job. 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