ci: snapshot OpenAPI spec for cross-stack contract testing

[mastermanas805]

Summary

• Adds openapi.snapshot.json as the canonical, committed OpenAPI 3.1 contract — generated from handlers.OpenAPISpecProduction() (same spec served at GET /openapi.json in production, with the dev-only /internal/set-tier path stripped).
• Adds cmd/openapi-snapshot/ + make openapi-snapshot / make openapi-snapshot-check for local regen + drift detection.
• Adds a fast (<30s) PR-time CI gate (.github/workflows/openapi-snapshot.yml) that fails the PR with a clear "run make openapi-snapshot" message when internal/handlers/openapi.go changes but the snapshot is not regenerated.

Why

Today's prod login broke for ~24h because /auth/exchange (AUTH-004) shipped server-side without the dashboard's client being updated. Per-repo unit tests on both sides stayed green because each repo only saw its own half of the contract.

This PR makes the contract a committed artifact so the dashboard + instanode-web repos can deterministically generate typed clients via openapi-typescript. Future PRs (separately scoped) in those repos will:

1. Pull this snapshot from origin/master of api.
2. Regenerate src/lib/api.generated.ts.
3. CI-diff the regenerated file vs the committed one → fail if the api contract changed without a corresponding client regen.

This is rule 22 (contract surface checklist) made enforceable at PR time.

Note on /auth/exchange: it is currently not in the OpenAPI spec — that gap is the proximate cause of today's outage. This PR builds the infrastructure to catch the next gap; adding /auth/exchange to the spec is a separate fix that should follow this PR (it will trigger this gate and force the regeneration discipline from day one).

Coverage block (rule 17)

Symptom:        Contract drift between api spec and TS clients goes
                undetected at PR time → runtime login break.
Enumeration:    rg -F 'openAPISpec' --include='*.go'
Sites found:    Single const + ServeOpenAPI handler in
                internal/handlers/openapi.go.
Sites touched:  Added OpenAPISpecProduction() accessor next to
                ServeOpenAPI; both route through stripInternalSetTierPath
                so what the snapshot emits == what production serves.
Coverage test:  make openapi-snapshot-check (CI job snapshot-drift)
                regenerates and diffs on every PR touching openapi.go /
                cmd/openapi-snapshot/ / openapi.snapshot.json.
Live verified:  make openapi-snapshot wrote 383616 bytes; make
                openapi-snapshot-check returns "snapshot matches
                handlers.OpenAPISpecProduction()". /internal/set-tier
                correctly stripped (grep -c returns 0). go build ./...
                + go vet ./... clean. handlers OpenAPI test suite green.

Test plan

• CI: snapshot-drift job passes (snapshot is consistent with the const).
• CI: build-and-test still green.
• Local: make openapi-snapshot && git diff --exit-code openapi.snapshot.json → no drift.
• Local: edit openapi.go, run make openapi-snapshot-check → fails with the "out of date" message; run make openapi-snapshot → passes.
• Verify cmd/openapi-snapshot/ is excluded from existing test gates (no test files; go vet clean).

Follow-ups (separately scoped PRs)

• dashboard: add openapi-typescript dev dep + npm run generate:api-types (fetches this snapshot via gh api from origin/master) + CI diff job. Plus a Playwright AUTH-004 smoke test against E2E_API_URL.
• instanode-web: same pattern.
• infra (optional): NR dashboard tile + alert on cross_stack_contract_drift log events emitted by this workflow (rule 25 observability).

🤖 Generated with Claude Code