EgorMajj · Oct 1, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -37,3 +37,13 @@ jobs:
 
       - name: Compile the example against the installed SDK
         run: mvn -B -ntp -f examples/httpserver/pom.xml verify
+
+  contract:
+    name: Shared contract files match the lock
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+        with:
+          persist-credentials: false
+      - name: Contract files match .shieldlabs-contract.lock
+        run: python3 scripts/sync_contract.py --check
diff --git a/.github/workflows/contract-sync.yml b/.github/workflows/contract-sync.yml
@@ -0,0 +1,175 @@
+name: Contract sync
+
+# Takes the shared API contract (test fixtures, see contract-sync.json) from the newest
+# shieldlabs-openapi release, or from the release given by hand or by a contract-release
+# dispatch. When files change, it runs the full test suite and opens a pull request with the
+# result. Pull requests opened with GITHUB_TOKEN start no other workflow, so the tests run here.
+
+on:
+  schedule:
+    - cron: '17 6 * * *'
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Contract release: 'latest' or a tag such as v1.0.1"
+        required: false
+        default: latest
+        type: string
+  repository_dispatch:
+    types: [contract-release]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: contract-sync-${{ github.repository }}
+  cancel-in-progress: false
+
+jobs:
+  sync:
+    name: Sync the shared contract
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+        with:
+          persist-credentials: false
+
+      - name: Sync the contract files
+        id: sync
+        env:
+          INPUT_REF: ${{ inputs.ref }}
+          DISPATCH_REF: ${{ github.event.client_payload.ref }}
+          # Only raises the GitHub API rate limit when resolving 'latest'.
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          ref="${DISPATCH_REF:-${INPUT_REF:-latest}}"
+          if ! [[ "$ref" =~ ^(latest|v[0-9]+\.[0-9]+\.[0-9]+)$ ]]; then
+            echo "::error::Invalid contract ref: use latest or a tag such as v1.0.1."
+            exit 1
+          fi
+          python3 scripts/sync_contract.py --ref "$ref"
+          resolved="$(python3 -c 'import json; print(json.load(open(".shieldlabs-contract.lock"))["ref"])')"
+          if ! [[ "$resolved" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::Unexpected ref in .shieldlabs-contract.lock."
+            exit 1
+          fi
+          mapfile -t files < <(python3 -c 'import json; print("\n".join(json.load(open("contract-sync.json"))["files"].values()))')
+          if [ -n "$(git status --porcelain -- "${files[@]}")" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            # Same bytes under a newer tag: keep the lock as it is, no pull request.
+            git checkout -- .shieldlabs-contract.lock
+            echo "Contract files are already those of $resolved."
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+          echo "ref=$resolved" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/setup-java@b6effb05e454b25005698d916606bdc6ffcbf961 # v5.7.0
+        if: steps.sync.outputs.changed == 'true'
+        with:
+          distribution: temurin
+          java-version: '17'
+          cache: maven
+
+      - name: Run the full test suite
+        id: tests
+        if: steps.sync.outputs.changed == 'true'
+        continue-on-error: true
+        shell: bash
+        run: |
+          {
+            mvn -B -ntp install
+            mvn -B -ntp -f examples/httpserver/pom.xml verify
+          } 2>&1 | tee "$RUNNER_TEMP/contract-tests.log"
+
+      - name: Push the branch and open or update the pull request
+        if: steps.sync.outputs.changed == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          CONTRACT_REF: ${{ steps.sync.outputs.ref }}
+          TESTS: ${{ steps.tests.outcome }}
+        run: |
+          set -euo pipefail
+          if ! [[ "$CONTRACT_REF" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::Unexpected contract ref."
+            exit 1
+          fi
+          export GH_REPO="$GITHUB_REPOSITORY"
+          base="$GITHUB_REF_NAME"
+          branch="contract-sync/$CONTRACT_REF"
+          label="contract-change-needs-code"
+          version="$(python3 -c 'import json; print(json.load(open(".shieldlabs-contract.lock"))["contract_version"])')"
+          mapfile -t files < <(python3 -c 'import json; print("\n".join(json.load(open("contract-sync.json"))["files"].values()))')
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git switch -c "$branch"
+          git add -- "${files[@]}" .shieldlabs-contract.lock
+          changes="$(git diff --cached --name-status)"
+          git commit -q -m "chore: sync the shared contract $CONTRACT_REF"
+
+          remote_sha="$(gh api "repos/$GITHUB_REPOSITORY/git/ref/heads/$branch" --jq .object.sha 2>/dev/null || true)"
+          remote_tree=""
+          if [[ "$remote_sha" =~ ^[0-9a-f]{40}$ ]]; then
+            remote_tree="$(gh api "repos/$GITHUB_REPOSITORY/git/commits/$remote_sha" --jq .tree.sha)"
+          fi
+          if [ "$remote_tree" = "$(git rev-parse 'HEAD^{tree}')" ]; then
+            echo "$branch already holds these changes."
+          else
+            git push --force "https://x-access-token:$GH_TOKEN@${GITHUB_SERVER_URL#https://}/$GITHUB_REPOSITORY.git" "HEAD:refs/heads/$branch"
+          fi
+
+          body="$RUNNER_TEMP/contract-pr.md"
+          {
+            echo "Syncs the shared API contract to [$CONTRACT_REF](https://github.com/ShieldLabs-ai/shieldlabs-openapi/releases/tag/$CONTRACT_REF) of shieldlabs-openapi (contract_version $version)."
+            echo
+            echo "Changed files:"
+            echo
+            echo '```'
+            echo "$changes"
+            echo '```'
+            echo
+            if [ "$TESTS" = "success" ]; then
+              echo "Tests: the full test suite passes with these files."
+            else
+              echo "Tests: **the full test suite fails with these files** ($TESTS). The SDK must change before it can take this contract; push the fixes to this branch."
+              echo
+              echo "<details><summary>Last lines of the test log</summary>"
+              echo
+              echo '```'
+              tail -n 80 "$RUNNER_TEMP/contract-tests.log" 2>/dev/null | cut -c1-300 || true
+              echo '```'
+              echo
+              echo "</details>"
+            fi
+            echo
+            echo "Run: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
+            echo
+            echo "Pull requests opened by this workflow start no other workflow. Close and reopen this pull request (or push to its branch) to run the usual checks."
+          } > "$body"
+
+          number="$(gh pr list --head "$branch" --base "$base" --state open --json number --jq '.[0].number // empty')"
+          if [ -n "$number" ]; then
+            gh pr edit "$number" --body-file "$body"
+          elif ! gh pr create --base "$base" --head "$branch" --title "chore: sync the shared contract $CONTRACT_REF" --body-file "$body"; then
+            echo "::error::Could not open the pull request. Enable 'Allow GitHub Actions to create and approve pull requests' for this repository, or open it by hand: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/compare/$base...$branch"
+            exit 1
+          fi
+
+          if [ "$TESTS" = "success" ]; then
+            gh pr edit "$branch" --remove-label "$label" >/dev/null 2>&1 || true
+          else
+            gh label create "$label" --force --color D93F0B --description "A contract sync whose tests fail: the SDK must change first" \
+              || echo "::warning::Could not create the $label label."
+            gh pr edit "$branch" --add-label "$label"
+          fi
+
+      - name: Fail when the new contract breaks the tests
+        if: steps.tests.outcome == 'failure'
+        run: |
+          echo "::error::The test suite fails with the new contract files. See the pull request labeled contract-change-needs-code."
+          exit 1
diff --git a/.shieldlabs-contract.lock b/.shieldlabs-contract.lock
@@ -0,0 +1,21 @@
+{
+  "ref": "v1.0.1",
+  "contract_version": "1.0.1",
+  "files": {
+    "error-responses.json": "2be02da69063dcbbf40643559ac6eb6250ae22f5b41562f79810e97e9e3915e0",
+    "history-empty.json": "5616a1180d8234908daca7a08a05afa49a2d0ce06426cc97ebaf7971ba05b339",
+    "history-page.json": "50abc4a9622f800154043b2c67c0479f7e445d01ea46e882e973b217f32f7c9e",
+    "management-profile-expected.json": "5069ddc195bd0a11f5f53c8c964a6096bb54c116c0797fd3a6dd5d26149bc6f9",
+    "management-profile.json": "a02126112d37f0e5857f71d51cbfa201e876217001433af4f41ff27c31e488e6",
+    "normalization-cases.json": "66f1dae0293c26bf55370e713dc54a801b81d433e892022eede22ab592c5bcbe",
+    "risk-band-cases.json": "c9b168f5df1738faccffd69cea23bfdc8d299329ac2a129206ddf7cf9891c20c",
+    "signal-slug-cases.json": "8a79760a89503d48eb11c1e5e5d9b7dbe6756734092fc5a0a93f110f46228365",
+    "webhook-identification-scored.json": "be64dd698516acd46c773c62000bacf5e152ff54b7845c3b1819a563b948ffb2",
+    "webhook-identification-scored.raw.txt": "4cfa0fd3fe0fcfed1de1172d2b7d94c17246c0d6f27c2125909f03d05c71b029",
+    "webhook-ping.json": "90569a442e10c0af00393fcc455e5347d88b1e60624749056815b09ca267a471",
+    "webhook-ping.raw.txt": "5d0fde10a301d142970dc184d2a61cbb03ee58394481abb2e316065a390d4f77",
+    "webhook-rate-limited.json": "4985e08b2b306187d4ad3a78dc9e9d6ecf3bfcbd5fb781921bc02bb9f8a90ccd",
+    "webhook-signature-vectors.json": "33daee0c2823bb9b86b63a688b3065e9cfde3b8ecec14f9a988dfbdd5552fe89",
+    "webhook-test-delivery.json": "7678d32cf757ec604adb35b5b1dbe2a226530cec25266756ed96268f81c6d16d"
+  }
+}
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -31,7 +31,11 @@ mvn -f examples/httpserver/pom.xml verify
 - Tests must not need network access: use `TestServer` (a local `com.sun.net.httpserver` server)
   and `FakeTimer` for anything that waits.
 - The files in `src/test/resources/fixtures` are shared test fixtures that every ShieldLabs server
-  SDK passes. Do not edit them by hand; open an issue if one looks wrong.
+  SDK passes. Do not edit them by hand; open an issue if one looks wrong. They are synced from
+  `contract/` in shieldlabs-openapi: `contract-sync.json` maps each file,
+  `.shieldlabs-contract.lock` records the release, CI runs
+  `python3 scripts/sync_contract.py --check`, and the `contract-sync.yml` workflow opens a pull
+  request when a new release changes them.
 - Documentation and comments use plain, technical English: "risk signals", the three risk bands
   (trusted 0-29, suspicious 30-59, dangerous 60-100), colons or parentheses instead of dashes.
 - Use conventional commit messages (`feat: ...`, `fix: ...`, `test: ...`, `docs: ...`, `ci: ...`) and

diff --git a/contract-sync.json b/contract-sync.json
@@ -0,0 +1,20 @@
+{
+  "source": "shieldlabs-openapi",
+  "files": {
+    "error-responses.json": "src/test/resources/fixtures/error-responses.json",
+    "history-empty.json": "src/test/resources/fixtures/history-empty.json",
+    "history-page.json": "src/test/resources/fixtures/history-page.json",
+    "management-profile-expected.json": "src/test/resources/fixtures/management-profile-expected.json",
+    "management-profile.json": "src/test/resources/fixtures/management-profile.json",
+    "normalization-cases.json": "src/test/resources/fixtures/normalization-cases.json",
+    "risk-band-cases.json": "src/test/resources/fixtures/risk-band-cases.json",
+    "signal-slug-cases.json": "src/test/resources/fixtures/signal-slug-cases.json",
+    "webhook-identification-scored.json": "src/test/resources/fixtures/webhook-identification-scored.json",
+    "webhook-identification-scored.raw.txt": "src/test/resources/fixtures/webhook-identification-scored.raw.txt",
+    "webhook-ping.json": "src/test/resources/fixtures/webhook-ping.json",
+    "webhook-ping.raw.txt": "src/test/resources/fixtures/webhook-ping.raw.txt",
+    "webhook-rate-limited.json": "src/test/resources/fixtures/webhook-rate-limited.json",
+    "webhook-signature-vectors.json": "src/test/resources/fixtures/webhook-signature-vectors.json",
+    "webhook-test-delivery.json": "src/test/resources/fixtures/webhook-test-delivery.json"
+  }
+}