feat(identity): publish the identity-resolution OpenAPI contract and gate it

.github/workflows/openapi-specs.yml

@@ -10,6 +10,9 @@ name: OpenAPI Specs
 #     no HTTP listener; see api::openapi_document).
 #   • authenticator — the offline `authenticator openapi` subcommand (no Redis,
 #     no IdP; see api::openapi_document), same shape as analytics.
+#   • identity-resolution — the offline `identity-resolution openapi`
+#     subcommand (no MariaDB, no ClickHouse; see api::openapi_document),
+#     same shape as analytics.
 
 on:
   # Deliberately NO `paths:` filter — this is meant to be a required status
@@ -99,9 +102,46 @@ jobs:
           if [ "$rc" -ne 0 ]; then echo "::error::Authenticator OpenAPI spec drift — $AUTHENTICATOR_SPEC is stale. Regenerate: (cd src/backend && cargo run -p authenticator --bin authenticator -- openapi) > dump.json && python3 scripts/ci/openapi_spec.py update --file $AUTHENTICATOR_SPEC --live-file dump.json"; fi
           exit "$rc"
 
+  # ─── identity-resolution — offline emit via the `openapi` subcommand ──────
+  identity-resolution:
+    name: Identity Resolution OpenAPI spec drift gate
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Install protoc
+        run: sudo apt-get update && sudo apt-get install -y protobuf-compiler
+      - uses: dtolnay/rust-toolchain@4cda84d5c5c54efe2404f9d843567869ab1699d4 # stable
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+        with:
+          workspaces: src/backend -> target
+          key: identity-resolution-openapi
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - name: Generate the OpenAPI doc offline and drift-check it
+        env:
+          IDENTITY_SPEC: docs/components/backend/identity-resolution/openapi.json
+        run: |
+          # `identity-resolution openapi` builds offline and prints the doc; a
+          # build failure here should abort loudly under the runner's default
+          # `set -e`.
+          (cd src/backend && cargo run --quiet -p identity-resolution --bin identity-resolution -- openapi) > identity.openapi.live.json
+          # Relax errexit from here: we capture the drift-check rc ourselves,
+          # write the committed-vs-generated diff to the step summary, and emit a
+          # friendly ::error:: before exiting non-zero.
+          set +e
+          python3 scripts/ci/openapi_spec.py check --file "$IDENTITY_SPEC" --live-file identity.openapi.live.json | tee identity_openapi_drift.txt
+          rc=${PIPESTATUS[0]}
+          if [ -n "${GITHUB_STEP_SUMMARY:-}" ]; then { echo '```'; cat identity_openapi_drift.txt; echo '```'; } >> "$GITHUB_STEP_SUMMARY"; fi
+          if [ "$rc" -ne 0 ]; then echo "::error::Identity Resolution OpenAPI spec drift — $IDENTITY_SPEC is stale. Regenerate: (cd src/backend && cargo run -p identity-resolution --bin identity-resolution -- openapi) > dump.json && python3 scripts/ci/openapi_spec.py update --file $IDENTITY_SPEC --live-file dump.json"; fi
+          exit "$rc"
+
   # ─── the models generated FROM those documents ────────────────────────────
   # `tests/stand/api/schemas/` is generated from the same committed documents
-  # the two jobs above gate, so it belongs in this workflow rather than beside
+  # the jobs above gate, so it belongs in this workflow rather than beside
   # the stand suite: a spec change and its models go stale in the same commit,
   # and this is where that commit is already being checked. No Rust — it reads
   # the committed documents, not the services.