ci: add openapi spec drift check against fixture schema

[mandarini]

What this is

• CI gate that boots PostgREST against the existing spec test fixture schema, fetches the emitted OpenAPI (Swagger 2.0) document, and fails PRs that change the emitted spec without updating the committed snapshot.

What maintainers need to do

• Review the integration approach (uses the existing withTools.pg-17 + withPgrst from nix/tools/).
• Bootstrap the initial snapshot, either path:
  • Path A (no local Nix required): merge with no snapshot; CI fails once; download the openapi-snapshot artifact from the failing run; save as test/spec/fixtures/openapi-snapshot.json; commit.
  • Path B: locally run postgrest-with-pg-17 --fixtures test/spec/fixtures/load.sql postgrest-with-pgrst test/openapi-drift-check.sh, commit the resulting snapshot.
• On future PRs that touch the spec generator or schema-shaping fixture files: re-generate and commit (same flow — fail, download artifact, commit, push).
• Filename note: the committed snapshot is test/spec/fixtures/openapi-snapshot.json. The existing test/spec/fixtures/openapi.json is the draft-04 JSON Schema used by spec tests, not the spec itself, so a different name is used. Happy to relocate if preferred.

What it's used for

• Today the OpenAPI document is generated at request time and never persisted, so changes to the generator can ship silently. The snapshot turns it into a versioned artifact and makes accidental shape changes visible in PR diffs.
• Limitations called out explicitly: the snapshot reflects the fixture schema only. It does not document the query protocol (filter operators, embedding, prefer headers) — that would need a separate conformance suite. The spec itself remains Swagger 2.0; upgrading is out of scope here.

What was added and why

• test/openapi-drift-check.sh — bash script that curls the emitted spec via PGRST_SERVER_UNIX_SOCKET and either writes (default) the committed snapshot or --checks against it. Always writes the live spec to a gitignored .generated.json path so CI can upload it as an artifact regardless of pass/fail.
• .github/workflows/openapi.yml — runs the script in --check mode inside the existing Nix devShell. Triggers are narrow (only spec-affecting fixture files; data.sql excluded) so the 10–20 min build cost only hits relevant PRs.
• .gitignore — adds the *.generated.json side-by-side path.

Security posture

• The workflow does not pass CACHIX_AUTH_TOKEN to setup-nix. cachix-action falls back to skipPush=true when no token is set, so cache pulls still work (this workflow's only need) while no push token is exposed to scripts running under the job. Please don't add the token back without considering this.
• Workflow has explicit permissions: contents: read at both workflow and job scope; no other permissions are granted.
• All third-party actions are pinned to commit SHAs.
• Suggestion (out of scope for this PR, but worth considering): add a CODEOWNERS entry requiring maintainer review for .github/workflows/openapi.yml, test/openapi-drift-check.sh, and test/spec/fixtures/openapi-snapshot.json, so that any future modifications to the gate itself get the same scrutiny as production code.