feat(api): Rust consumer contracts and fail-closed artifact compatibility

.github/workflows/marreq-ci.yml

@@ -14,6 +14,38 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  api-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # v1
+        with:
+          toolchain: stable
+      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+          cache: npm
+      - name: Install pinned standards tooling
+        run: scripts/install-oasdiff.sh
+      - name: Install TypeScript tooling and consumers
+        run: |
+          npm ci
+          npm ci --prefix frontend
+          npm ci --prefix mcp-server
+      - name: Test native compatibility semantics and CLI failures
+        run: cargo test --locked -p marreq-contracts
+      - name: Check generated consumer schemas
+        run: node scripts/generate-api-types.mjs --check
+      - name: Verify compiled routes and handler wire contracts
+        run: |
+          cargo test --locked -p marreq-cloud --test api_contract_inventory
+          cargo test --locked -p marreq-core --features test-helpers --test it
+      - name: Exercise isolated real Server/Cloud and HTTP consumers
+        run: scripts/test-api-contracts.sh
+      - name: Require verified contracts for every current consumer operation
+        run: cargo run --locked -p marreq-contracts -- validate
+
   lint:
     runs-on: ubuntu-latest
     steps:
@@ -134,6 +166,9 @@ jobs:
         working-directory: frontend
         run: npm run build
 
+      - name: Build independent frontend image
+        run: docker build -f docker/frontend/Dockerfile -t marreq-frontend:ci .
+
   backend-build:
     runs-on: ubuntu-latest
     steps:
@@ -153,6 +188,35 @@ jobs:
       - name: Build workspace (release)
         run: cargo build --workspace --release
 
+  backend-images:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        binary: [marreq-server, marreq-cloud]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: docker/setup-buildx-action@v4
+      - name: Build production backend image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: docker/Dockerfile
+          load: true
+          tags: ${{ matrix.binary }}:ci
+          build-args: MARREQ_BIN=${{ matrix.binary }}
+          cache-from: type=gha,scope=${{ matrix.binary }}
+          cache-to: type=gha,mode=max,scope=${{ matrix.binary }}
+      - name: Verify runtime excludes contract tooling
+        run: |
+          docker run --rm --entrypoint sh ${{ matrix.binary }}:ci -ec '
+            test ! -e /app/tools
+            test ! -e /app/docs
+            ! command -v marreq-contracts
+            ! command -v oasdiff
+            ! command -v node
+          '
+
   mcp-tests:
     runs-on: ubuntu-latest
     steps:
@@ -258,6 +322,12 @@ jobs:
       MARREQ_TEST_DATABASE_URL: postgres://rust:rust@127.0.0.1:5433/marreq
     steps:
       - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+          cache: npm
+      - name: Install pinned OpenAPI bundler
+        run: npm ci
 
       - name: Free runner disk space
         run: |
@@ -293,6 +363,9 @@ jobs:
         with:
           tool: cargo-llvm-cov
 
+      - name: Install pinned OpenAPI standards engine for workspace tests
+        run: scripts/install-oasdiff.sh
+
       - name: Install diesel CLI
         run: cargo install diesel_cli --no-default-features --features postgres
 

.github/workflows/release-artifacts.yml

@@ -12,7 +12,71 @@ permissions:
   packages: write
 
 jobs:
+  compatibility:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # v1
+        with:
+          toolchain: stable
+      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+          cache: npm
+      - name: Install pinned OpenAPI bundler
+        run: npm ci
+      - name: Install pinned OpenAPI standards engine
+        run: scripts/install-oasdiff.sh
+      - name: Test contract semantics and validate producer document
+        run: |
+          cargo test --locked -p marreq-contracts
+          cargo run --locked -p marreq-contracts -- validate --document-only
+      - name: Verify candidate backend routes and serializers
+        if: startsWith(github.ref_name, 'marreq-server-v')
+        run: cargo test --locked -p marreq-cloud --test api_contract_inventory
+      - name: Require immutable deployment-plan revision
+        id: plan
+        env:
+          PLAN_SHA: ${{ vars.MARREQ_RELEASE_CONTRACTS_SHA }}
+        run: |
+          if [[ ! "$PLAN_SHA" =~ ^[a-f0-9]{40}$ ]]; then
+            echo "Set MARREQ_RELEASE_CONTRACTS_SHA to an immutable source revision containing deployment.json and exact retained contract bundles." >&2
+            exit 1
+          fi
+          echo "sha=$PLAN_SHA" >> "$GITHUB_OUTPUT"
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ steps.plan.outputs.sha }}
+          path: .release-contracts
+      - name: Verify exact candidate and unchanged deployment artifacts
+        env:
+          CANDIDATE_TAG: ${{ github.ref_name }}
+          CANDIDATE_SHA: ${{ github.sha }}
+        run: |
+          case "$CANDIDATE_TAG" in
+            marreq-server-v*) component=backend; version=${CANDIDATE_TAG#marreq-server-v} ;;
+            marreq-frontend-v*) component=frontend; version=${CANDIDATE_TAG#marreq-frontend-v} ;;
+            marreq-mcp-v*) component=mcp; version=${CANDIDATE_TAG#marreq-mcp-v} ;;
+            *) echo "unsupported component tag" >&2; exit 1 ;;
+          esac
+          if [[ "$component" == backend ]]; then
+            cargo run --locked -p marreq-contracts -- bundle --component backend --variant server --version "$version" --output /tmp/candidate-contract.json
+          else
+            cargo run --locked -p marreq-contracts -- bundle --component "$component" --version "$version" --output /tmp/candidate-contract.json
+          fi
+          scripts/check-api-compatibility.sh \
+            --manifest .release-contracts/deployment.json \
+            --candidate-component "$component" --candidate-version "$version" \
+            --candidate-source-sha "$CANDIDATE_SHA" \
+            --candidate-bundle /tmp/candidate-contract.json
+      - uses: actions/upload-artifact@v7
+        with:
+          name: candidate-api-contract
+          path: /tmp/candidate-contract.json
+
   backend:
+    needs: compatibility
     if: startsWith(github.ref_name, 'marreq-server-v')
     runs-on: ubuntu-latest
     steps:
@@ -51,6 +115,7 @@ jobs:
             MARREQ_GIT_SHA=${{ github.sha }}
 
   frontend:
+    needs: compatibility
     if: startsWith(github.ref_name, 'marreq-frontend-v')
     runs-on: ubuntu-latest
     steps:
@@ -88,6 +153,7 @@ jobs:
             MARREQ_GIT_SHA=${{ github.sha }}
 
   mcp:
+    needs: compatibility
     if: startsWith(github.ref_name, 'marreq-mcp-v')
     runs-on: ubuntu-latest
     steps:

.gitignore

@@ -63,9 +63,11 @@ backups/
 # nodejs
 node_modules
 frontend/dist
+mcp-server/dist/
 
-# MCP server: do not ship compiled Vitest sources
-mcp-server/dist/*.test.js
+# Python bytecode
+__pycache__/
+*.py[cod]
 
 # Export files
 exports/
@@ -79,3 +81,9 @@ _bmad-output/
 .cursorignore
 
 AGENTS.md
+
+# Optional self-contained OpenAPI output; edit openapi/root.yaml and domains.
+/docs/developer/openapi.yaml
+# Rust source module, not a generated coverage report.
+!/tools/marreq-contracts/src/coverage/
+!/tools/marreq-contracts/src/coverage/*.rs