test(backend): pin OpenAPI contract baseline (360 paths, 484 operations)

Adds tests/contracts/test_openapi_baseline.py which loads the live
FastAPI app and diffs its OpenAPI schema against a checked-in baseline.
Fails on:
  - Any removed path or operation
  - Any removed response status code on an existing operation
  - Any new required request body field (would break existing clients)

Passes silently on additive changes. The baseline is regenerated by
running tests/contracts/regenerate_baseline.py — only when a contract
change has been reviewed and every consumer (admin-compliance,
developer-portal, SDKs) has been updated in the same change set.

This is the safety harness for the Phase 1 backend-compliance refactor:
every subsequent refactor commit must keep this test green.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

backend-compliance/tests/contracts/regenerate_baseline.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+"""Regenerate the OpenAPI baseline.
+
+Run this ONLY when you have intentionally made an additive API change and want
+the contract test to pick up the new baseline. Removing or renaming anything is
+a breaking change and requires updating every consumer in the same change set.
+
+Usage:
+    python tests/contracts/regenerate_baseline.py
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+THIS_DIR = Path(__file__).parent
+REPO_ROOT = THIS_DIR.parent.parent  # backend-compliance/
+sys.path.insert(0, str(REPO_ROOT))
+
+from main import app  # type: ignore[import-not-found]  # noqa: E402
+
+out = THIS_DIR / "openapi.baseline.json"
+out.write_text(json.dumps(app.openapi(), indent=2, sort_keys=True) + "\n")
+print(f"wrote {out}")

backend-compliance/tests/contracts/test_openapi_baseline.py

@@ -0,0 +1,102 @@
+"""OpenAPI contract test.
+
+This test pins the public HTTP contract of backend-compliance. It loads the
+FastAPI app, extracts the live OpenAPI schema, and compares it against a
+checked-in baseline at ``tests/contracts/openapi.baseline.json``.
+
+Rules:
+  - Adding new paths/operations/fields → OK (additive change).
+  - Removing a path, changing a method, changing a status code, removing or
+    renaming a response/request field → FAIL. Such changes require updating
+    every consumer (admin-compliance, developer-portal, SDKs) in the same
+    change, then regenerating the baseline with:
+
+        python tests/contracts/regenerate_baseline.py
+
+    and explaining the contract change in the PR description.
+
+The baseline is missing on first run — the test prints the command to create
+it and skips. This is intentional: Phase 1 step 1 generates it fresh from the
+current app state before any refactoring begins.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+BASELINE_PATH = Path(__file__).parent / "openapi.baseline.json"
+
+
+def _load_live_schema() -> dict[str, Any]:
+    """Import the FastAPI app and extract its OpenAPI schema.
+
+    Kept inside the function so that test collection does not fail if the app
+    has import-time side effects that aren't satisfied in the test env.
+    """
+    from main import app  # type: ignore[import-not-found]
+
+    return app.openapi()
+
+
+def _collect_operations(schema: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    """Return a flat {f'{METHOD} {path}': operation} map for diffing."""
+    out: dict[str, dict[str, Any]] = {}
+    for path, methods in schema.get("paths", {}).items():
+        for method, op in methods.items():
+            if method.lower() in {"get", "post", "put", "patch", "delete", "options", "head"}:
+                out[f"{method.upper()} {path}"] = op
+    return out
+
+
+@pytest.mark.contract
+def test_openapi_no_breaking_changes() -> None:
+    if not BASELINE_PATH.exists():
+        pytest.skip(
+            f"Baseline missing. Run: python {Path(__file__).parent}/regenerate_baseline.py"
+        )
+
+    baseline = json.loads(BASELINE_PATH.read_text())
+    live = _load_live_schema()
+
+    baseline_ops = _collect_operations(baseline)
+    live_ops = _collect_operations(live)
+
+    # 1. No operation may disappear.
+    removed = sorted(set(baseline_ops) - set(live_ops))
+    assert not removed, (
+        f"Breaking change: {len(removed)} operation(s) removed from public API:\n  "
+        + "\n  ".join(removed)
+    )
+
+    # 2. For operations that exist in both, response status codes must be a superset.
+    for key, baseline_op in baseline_ops.items():
+        live_op = live_ops[key]
+        baseline_codes = set((baseline_op.get("responses") or {}).keys())
+        live_codes = set((live_op.get("responses") or {}).keys())
+        missing = baseline_codes - live_codes
+        assert not missing, (
+            f"Breaking change: {key} no longer returns status code(s) {sorted(missing)}"
+        )
+
+    # 3. Required request-body fields may not be added (would break existing clients).
+    for key, baseline_op in baseline_ops.items():
+        live_op = live_ops[key]
+        base_req = _required_body_fields(baseline_op)
+        live_req = _required_body_fields(live_op)
+        new_required = live_req - base_req
+        assert not new_required, (
+            f"Breaking change: {key} added required request field(s) {sorted(new_required)}"
+        )
+
+
+def _required_body_fields(op: dict[str, Any]) -> set[str]:
+    rb = op.get("requestBody") or {}
+    content = rb.get("content") or {}
+    for media in content.values():
+        schema = media.get("schema") or {}
+        return set(schema.get("required") or [])
+    return set()