protocol-specs.yml

name: Protocol Specs

on:
  pull_request:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read

jobs:
  catalog:
    name: Validate protocol spec catalog
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803  # v6
        with:
          fetch-depth: 0

      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38  # v6
        with:
          node-version: 24

      - name: Install dependencies
        run: npm ci

      - name: Resolve Server OpenAPI authority ref
        id: server-openapi-authority
        run: |
          node -e "process.stdout.write('ref=' + require('./scripts/server-openapi-authority.json').ref + '\n')" >> "$GITHUB_OUTPUT"

      - name: Fetch Server OpenAPI authority
        env:
          GIT_TERMINAL_PROMPT: '0'
          SERVER_OPENAPI_AUTHORITY_REF: ${{ steps.server-openapi-authority.outputs.ref }}
        run: |
          set -euo pipefail

          authority_path="${GITHUB_WORKSPACE}/.server-openapi-authority"
          rm -rf "${authority_path}"
          git init "${authority_path}"
          git -C "${authority_path}" -c credential.helper= fetch \
            --depth=1 \
            --no-tags \
            https://github.com/durable-workflow/server.git \
            "${SERVER_OPENAPI_AUTHORITY_REF}"
          git -C "${authority_path}" checkout --detach FETCH_HEAD

          actual_ref="$(git -C "${authority_path}" rev-parse HEAD)"
          test "${actual_ref}" = "${SERVER_OPENAPI_AUTHORITY_REF}"

      - name: Resolve released Rust SDK version
        id: rust-sdk-release
        run: |
          node -e "process.stdout.write('version=' + require('./scripts/published-artifact-versions.json').artifacts['sdk-rust'] + '\n')" >> "$GITHUB_OUTPUT"

      - name: Download released Rust SDK metadata
        env:
          SDK_RUST_VERSION: ${{ steps.rust-sdk-release.outputs.version }}
        run: |
          set -euo pipefail

          crate_archive="${RUNNER_TEMP}/durable-workflow-${SDK_RUST_VERSION}.crate"
          version_metadata="${RUNNER_TEMP}/durable-workflow-${SDK_RUST_VERSION}.json"
          crate_root="${GITHUB_WORKSPACE}/released-sdk-rust"
          user_agent="durable-workflow-docs-compatibility-check"

          curl --fail --silent --show-error --location --retry 3 \
            --header "User-Agent: ${user_agent}" \
            --output "${version_metadata}" \
            "https://crates.io/api/v1/crates/durable-workflow/${SDK_RUST_VERSION}"

          published_version="$(node -e '
            const metadata = require(process.argv[1]);
            const expected = process.argv[2];
            if (metadata.version?.num !== expected) {
              throw new Error(`crates.io returned version ${metadata.version?.num} for ${expected}`);
            }
            process.stdout.write(metadata.version.num);
          ' "${version_metadata}" "${SDK_RUST_VERSION}")"
          published_checksum="$(node -e '
            const metadata = require(process.argv[1]);
            const checksum = metadata.version?.checksum;
            if (!/^[0-9a-f]{64}$/.test(checksum ?? "")) {
              throw new Error("crates.io returned an invalid SHA-256 checksum");
            }
            process.stdout.write(checksum);
          ' "${version_metadata}")"
          test "${published_version}" = "${SDK_RUST_VERSION}"

          curl --fail --silent --show-error --location --retry 3 \
            --header "User-Agent: ${user_agent}" \
            --output "${crate_archive}" \
            "https://crates.io/api/v1/crates/durable-workflow/${SDK_RUST_VERSION}/download"
          printf '%s  %s\n' "${published_checksum}" "${crate_archive}" \
            | sha256sum --check --strict

          mkdir -p "${crate_root}"
          tar -xzf "${crate_archive}" --strip-components=1 -C "${crate_root}"

      - name: Check compatibility authority
        run: node scripts/check-compatibility-authority.js
        env:
          SDK_RUST_REPO_PATH: ${{ github.workspace }}/released-sdk-rust

      - name: Test compatibility authority drift detection
        run: node scripts/check-compatibility-authority.test.js

      - name: Check platform protocol specs
        run: node scripts/check-platform-protocol-specs.js

      - name: Test malformed platform protocol specs
        run: node scripts/check-platform-protocol-specs.test.js

      - name: Test published server catalog drift detection
        run: node scripts/check-public-server-protocol-catalog.test.js

      - name: Check schedule-list OpenAPI server mirror
        env:
          SERVER_REPO_PATH: ${{ github.workspace }}/.server-openapi-authority
        run: node scripts/check-schedule-list-openapi.js --require-server-mirror

      - name: Test schedule-list OpenAPI server mirror enforcement
        run: node scripts/check-schedule-list-openapi.test.js

      - name: Test rendered protocol catalog associations
        run: node scripts/check-platform-protocol-page.test.js

      - name: Build rendered protocol retrieval surfaces
        run: |
          npm run docusaurus -- build
          node scripts/generate-llms-full.js

      - name: Check rendered protocol retrieval surfaces
        run: node scripts/check-platform-protocol-page.js

      - name: Check platform conformance authority
        run: node scripts/check-platform-conformance-authority.js