build(api): guard that api.json changes require an info.version bump

.github/workflows/api-version-guard.yml

@@ -0,0 +1,52 @@
+name: API version guard
+
+# The OpenAPI contract version (modules/api.json -> info.version) is tracked
+# independently of the package version (pom.xml): the contract changes far less
+# often than the package. This guard enforces the one invariant that keeps the
+# contract version honest — if api.json changes in a PR, info.version must change
+# too. It does not police the size of the bump (patch/minor/major); that is left
+# to the author's semver judgment (and to a future automation, see the follow-up).
+#
+# Triggered only when modules/api.json is touched (PRs and branch pushes — the
+# latter gives contributors feedback before they open a PR). NOTE: keep this an
+# advisory check, not a required one — a paths-filtered job that is required would
+# block PRs that don't touch api.json (the check would never report).
+
+on:
+  pull_request:
+    branches: [develop]
+    paths: ['modules/api.json']
+  push:
+    paths: ['modules/api.json']
+
+permissions:
+  contents: read
+
+jobs:
+  api-version-bump:
+    name: Require an info.version bump when api.json changes
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Check modules/api.json info.version
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            base='${{ github.event.pull_request.base.sha }}'
+          else
+            git fetch --no-tags --quiet origin develop
+            base="$(git merge-base FETCH_HEAD HEAD)"
+          fi
+          if git diff --quiet "$base" HEAD -- modules/api.json; then
+            echo "modules/api.json unchanged relative to base — no API version bump required."
+            exit 0
+          fi
+          old=$(git show "$base:modules/api.json" | jq -r '.info.version')
+          new=$(jq -r '.info.version' modules/api.json)
+          echo "modules/api.json changed. info.version: '$old' -> '$new'"
+          if [ "$old" = "$new" ]; then
+            echo "::error file=modules/api.json::modules/api.json changed but info.version did not (still '$new'). The OpenAPI contract version is tracked independently of the package version — bump info.version whenever the API contract changes."
+            exit 1
+          fi
+          echo "info.version was bumped — OK"

modules/api.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.3",
   "info": {
     "title": "eXist-db Platform API",
-    "version": "0.9.0-SNAPSHOT",
+    "version": "0.9.0",
     "description": "Unified REST API for eXist-db: query execution, language services, database management, user management, package management, search, and cross-app linking.",
     "license": {
       "name": "LGPL-2.1",