Add a script to check for breaking C ABI changes

.github/workflows/check-c-abi.yaml

@@ -0,0 +1,127 @@
+name: C ABI Compatibility Check
+
+on:
+  workflow_call:
+
+jobs:
+  # Check PRs for breaking ABI changes
+  check-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout PR branch
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install Python dependencies
+        run: |
+          pip install --upgrade pip
+          pip install ci/check_c_abi
+
+      - name: Get dlpack dependency
+        run: |
+          git clone https://github.com/dmlc/dlpack
+
+      - name: Find merge base commit
+        id: merge-base
+        run: |
+          git fetch origin main
+          MERGE_BASE=$(git merge-base HEAD origin/main)
+          echo "merge_base_sha=${MERGE_BASE}" >> $GITHUB_OUTPUT
+          echo "Merge base commit: ${MERGE_BASE}"
+
+      - name: Try to download baseline for merge-base commit (most accurate)
+        id: download-merge-base
+        continue-on-error: true
+        uses: dawidd6/action-download-artifact@v3
+        with:
+          name: c-abi-baseline-${{ steps.merge-base.outputs.merge_base_sha }}
+          workflow: check-c-abi.yaml
+          commit: ${{ steps.merge-base.outputs.merge_base_sha }}
+          path: baseline/
+
+      - name: Try to download latest main baseline (fallback 1)
+        id: download-main
+        if: steps.download-merge-base.outcome == 'failure'
+        continue-on-error: true
+        uses: dawidd6/action-download-artifact@v3
+        with:
+          name: c-abi-baseline-main
+          workflow: check-c-abi.yaml
+          branch: main
+          path: baseline/
+
+      - name: Extract baseline ABI from main branch (fallback 2)
+        if: steps.download-merge-base.outcome == 'failure' && steps.download-main.outcome == 'failure'
+        run: |
+          echo "⚠️ No baseline artifacts found, extracting from main branch..."
+          echo "This is slower but ensures we always have a baseline for comparison."
+          git worktree add ../cuvs-main main
+          mkdir -p baseline
+          check-c-abi extract \
+            --header-path ../cuvs-main/c/include \
+            --include-file cuvs/core/all.h \
+            --output-file baseline/c_abi.json.gz \
+            --dlpack-include-path dlpack/include
+
+          echo "✓ Baseline ABI extracted from main branch"
+
+      - name: Report baseline source
+        run: |
+          if [ "${{ steps.download-merge-base.outcome }}" == "success" ]; then
+            echo "✓ Using baseline from merge-base commit: ${{ steps.merge-base.outputs.merge_base_sha }}"
+          elif [ "${{ steps.download-main.outcome }}" == "success" ]; then
+            echo "✓ Using latest main baseline (merge-base baseline not yet available)"
+          else
+            echo "✓ Using freshly extracted baseline from main branch"
+          fi
+
+      - name: Analyze current branch for ABI breaking changes
+        run: |
+          check-c-abi analyze \
+            --abi-file baseline/c_abi.json.gz \
+            --header-path c/include \
+            --include-file cuvs/core/all.h \
+            --dlpack-include-path dlpack/include
+
+      - name: Comment on PR with results
+        if: failure() && github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: `## ⚠️ C ABI Breaking Changes Detected
+                This PR introduces breaking changes to the C ABI. Please review the changes carefully.
+
+                Breaking ABI changes are only allowed in major releases. If this is intentional for a major release,
+                the baseline ABI will need to be updated after merge.
+
+                See the job logs for details on what specific changes were detected.
+
+                ### What are breaking ABI changes?
+
+                Breaking ABI changes include:
+                - Removing functions from the public API
+                - Changing function signatures (parameters or return types)
+                - Removing struct members or changing their types
+                - Removing or changing enum values
+
+                ### Next steps
+
+                1. Review the changes flagged in the CI logs
+                2. If these changes are unintentional, update your PR to maintain ABI compatibility
+                3. If these changes are required, ensure:
+                   - This is part of a major version release
+                   - The changes are documented in the changelog
+                   - Migration guide is provided for users
+
+                For more information, see the [C ABI documentation](../docs/source/c_developer_guide.md).`
+            });

.github/workflows/pr.yaml

@@ -12,6 +12,7 @@ jobs:
       - check-nightly-ci
       - changed-files
       - checks
+      - check-c-abi
       - conda-cpp-build
       - conda-cpp-tests
       - conda-cpp-checks
@@ -315,6 +316,9 @@ jobs:
     with:
       enable_check_generated_files: false
       ignored_pr_jobs: "telemetry-summarize"
+  check-c-abi:
+    needs: telemetry-setup
+    uses: ./.github/workflows/check-c-abi.yaml
   conda-cpp-build:
     needs: checks
     secrets: inherit

.github/workflows/store-c-abi-baseline.yaml

@@ -0,0 +1,72 @@
+name: Archive C ABI Baseline for Release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version tag to archive baseline for (e.g., v26.02.00)'
+        required: true
+        type: string
+
+jobs:
+  archive-baseline:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Download main baseline artifact
+        uses: dawidd6/action-download-artifact@v3
+        with:
+          name: c-abi-baseline-main
+          workflow: check-c-abi.yaml
+          branch: main
+          path: baseline/
+
+      - name: Archive baseline with release version
+        uses: actions/upload-artifact@v4
+        with:
+          name: c-abi-baseline-${{ github.event.release.tag_name || inputs.version }}
+          path: baseline/c_abi.json.gz
+          retention-days: 400  # ~13 months
+
+      - name: Commit baseline to repository (for long-term storage)
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          # Create a baselines branch if it doesn't exist
+          git fetch origin baselines:baselines 2>/dev/null || git checkout --orphan baselines
+          git checkout baselines 2>/dev/null || true
+
+          # Copy the baseline file with version name
+          mkdir -p c-abi-baselines
+          cp baseline/c_abi.json.gz c-abi-baselines/c_abi_${{ github.event.release.tag_name || inputs.version }}.json.gz
+
+          # Commit and push
+          git add c-abi-baselines/
+          git commit -m "Archive C ABI baseline for ${{ github.event.release.tag_name || inputs.version }}"
+          git push origin baselines
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create release comment
+        if: github.event_name == 'release'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const tagName = context.payload.release.tag_name;
+
+            github.rest.repos.createCommitComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              commit_sha: context.payload.release.target_commitish,
+              body: |
+                `✅ C ABI baseline archived for release ${tagName}
+                 This baseline has been archived from the main branch and will be available for historical reference.
+                The baseline is stored in:
+                - Artifact: \`c-abi-baseline-${tagName}\` (available for ~13 months)
+                - Branch: \`baselines\` (permanent storage)`
+            });

.github/workflows/update-c-abi-baseline.yaml

@@ -0,0 +1,56 @@
+name: C ABI Update Baseleine
+
+on:
+  workflow_dispatch:  # Allow manual trigger for bootstrap
+  push:
+    branches:
+      - main
+    paths:
+      - 'c/include/**'
+      - 'ci/check_c_abi/**'
+
+jobs:
+  # Extract and store baseline ABI from main branch
+  update-baseline:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main branch
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install Python dependencies
+        run: |
+          pip install --upgrade pip
+          pip install -e ci/check_c_abi
+
+      - name: Get dlpack dependency
+        run: |
+          git clone https://github.com/dmlc/dlpack
+
+      - name: Extract ABI from main branch
+        run: |
+          mkdir -p baseline
+          check-c-abi extract \
+            --header-path c/include \
+            --include-file cuvs/core/all.h \
+            --output-file baseline/c_abi.json.gz \
+            --dlpack-include-path dlpack/include
+          echo "ABI extracted from main branch (commit: ${{ github.sha }})"
+
+      - name: Store commit-specific baseline
+        uses: actions/upload-artifact@v4
+        with:
+          name: c-abi-baseline-${{ github.sha }}
+          path: baseline/c_abi.json.gz
+          retention-days: 90  # Keep for 3 months
+
+      - name: Store main baseline (latest, never expires)
+        uses: actions/upload-artifact@v4
+        with:
+          name: c-abi-baseline-main
+          path: baseline/c_abi.json.gz
+          retention-days: 0  # Never expire

ci/check_c_abi/LICENSE

@@ -0,0 +1 @@
+../../LICENSE

ci/check_c_abi/VERSION

@@ -0,0 +1 @@
+../../VERSION

ci/check_c_abi/check_c_abi/__init__.py

@@ -0,0 +1,4 @@
+#
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION.
+# SPDX-License-Identifier: Apache-2.0
+#