interop-python.yml

name: Reference Seller Interop

on:
  pull_request:
    branches: [main, 16.x]
  workflow_dispatch:
    inputs:
      python_ref:
        description: 'adcp-client-python commit SHA, tag, or branch to test against'
        required: false
        default: '' # Use the pinned matrix fallback unless explicitly overridden.
      runner_package_ref:
        description: 'Optional @adcp/sdk npm package ref for manual runner probes, e.g. adcp-3.0 or @adcp/sdk@adcp-3.1. Empty packs this checkout.'
        required: false
        default: ''
  workflow_call:
    inputs:
      python_ref:
        description: 'adcp-client-python commit SHA, tag, or branch to test against'
        required: false
        type: string
        default: '' # Use the pinned matrix fallback unless explicitly overridden.
      runner_package_ref:
        description: 'Optional @adcp/sdk npm package ref for manual runner probes. Empty packs this checkout.'
        required: false
        type: string
        default: ''

permissions:
  contents: read

jobs:
  pack-sdk-runner:
    name: Pack SDK runner
    runs-on: ubuntu-latest
    timeout-minutes: 15
    env:
      RUNNER_PACKAGE_REF: ${{ inputs.runner_package_ref || '' }}

    steps:
      - name: Checkout @adcp/sdk
        uses: actions/checkout@v5
        with:
          persist-credentials: false

      - name: Setup Node.js
        uses: actions/setup-node@v5
        with:
          node-version: 24
          cache: npm

      - name: Install dependencies
        if: env.RUNNER_PACKAGE_REF == ''
        run: npm ci

      - name: Build SDK runner
        if: env.RUNNER_PACKAGE_REF == ''
        run: npm run build:lib

      - name: Pack SDK runner
        shell: bash
        run: |
          set -euo pipefail
          pack_dir="$RUNNER_TEMP/adcp-sdk-pack"
          mkdir -p "$pack_dir"
          if [[ -n "${RUNNER_PACKAGE_REF:-}" ]]; then
            package_ref="$RUNNER_PACKAGE_REF"
            if [[ "$package_ref" != @adcp/sdk@* ]]; then
              package_ref="@adcp/sdk@$package_ref"
            fi
            echo "Packing SDK runner from npm package ref $package_ref"
            npm pack "$package_ref" --pack-destination "$pack_dir" --silent
          else
            echo "Packing SDK runner from this checkout"
            npm pack --pack-destination "$pack_dir" --silent
          fi
          mapfile -t tarballs < <(find "$pack_dir" -maxdepth 1 -type f -name '*.tgz' -print)
          if [[ "${#tarballs[@]}" -ne 1 ]]; then
            echo "::error::Expected one packed SDK tarball in $pack_dir, found ${#tarballs[@]}."
            printf '%s\n' "${tarballs[@]}"
            exit 1
          fi
          echo "Packed SDK runner at ${tarballs[0]}"

      - name: Upload SDK runner tarball
        uses: actions/upload-artifact@v7
        with:
          name: adcp-sdk-runner-tarball
          if-no-files-found: error
          path: ${{ runner.temp }}/adcp-sdk-pack/*.tgz

      # The reporting evidence gate installs the PostgreSQL ledger store from its own package. A manual
      # probe of a published SDK ref (RUNNER_PACKAGE_REF) has no storage package to pack, and that gate
      # does not run for it.
      - name: Pack reporting storage
        if: env.RUNNER_PACKAGE_REF == ''
        shell: bash
        run: |
          set -euo pipefail
          pack_dir="$RUNNER_TEMP/adcp-reporting-storage-pack"
          mkdir -p "$pack_dir"
          npm pack --workspace=@adcp/reporting-storage --pack-destination "$pack_dir" --silent
          mapfile -t tarballs < <(find "$pack_dir" -maxdepth 1 -type f -name '*.tgz' -print)
          if [[ "${#tarballs[@]}" -ne 1 ]]; then
            echo "::error::Expected one packed reporting storage tarball in $pack_dir, found ${#tarballs[@]}."
            printf '%s\n' "${tarballs[@]}"
            exit 1
          fi
          echo "Packed reporting storage at ${tarballs[0]}"

      - name: Upload reporting storage tarball
        if: env.RUNNER_PACKAGE_REF == ''
        uses: actions/upload-artifact@v7
        with:
          name: adcp-reporting-storage-tarball
          if-no-files-found: error
          path: ${{ runner.temp }}/adcp-reporting-storage-pack/*.tgz

  reporting-evidence-and-reverse-runtime:
    name: Reporting evidence and reverse runtime (Node ${{ matrix.node }})
    # Historical runner probes remain available; this gate qualifies the checkout.
    if: inputs.runner_package_ref == ''
    needs: pack-sdk-runner
    runs-on: ubuntu-latest
    timeout-minutes: 30
    strategy:
      fail-fast: false
      matrix:
        node: ['20.19.0', '24']
    services:
      postgres:
        image: mirror.gcr.io/library/postgres:16
        env:
          POSTGRES_USER: postgres
          POSTGRES_HOST_AUTH_METHOD: trust
          POSTGRES_DB: postgres
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - name: Checkout interoperability gate
        uses: actions/checkout@v5
        with:
          persist-credentials: false

      - name: Checkout pinned Python harness
        uses: actions/checkout@v5
        with:
          repository: adcontextprotocol/adcp-client-python
          ref: 68345b5043b1cd8bae973c3d2ba0c0e7e53b6294
          path: .context/reporting-python-harness
          # Git archive can inspect objects outside its selected paths. A full
          # pinned checkout keeps the bounded export local; export.py still
          # verifies and exports only scripts/tests, excluding SDK source.
          persist-credentials: false

      - name: Setup Node.js
        uses: actions/setup-node@v5
        with:
          node-version: ${{ matrix.node }}

      - name: Setup Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.10'

      - name: Download packed SDK
        uses: actions/download-artifact@v7
        with:
          name: adcp-sdk-runner-tarball
          path: ${{ runner.temp }}/reporting-sdk

      - name: Download packed reporting storage
        uses: actions/download-artifact@v7
        with:
          name: adcp-reporting-storage-tarball
          path: ${{ runner.temp }}/reporting-storage

      - name: Install pinned SDK artifacts and record resolved dependencies
        shell: bash
        run: |
          set -euo pipefail
          task_dir="$RUNNER_TEMP/reporting-sdk"
          mapfile -t archives < <(find "$task_dir" -maxdepth 1 -name '*.tgz' -type f)
          test "${#archives[@]}" -eq 1
          mapfile -t storage_archives < <(find "$RUNNER_TEMP/reporting-storage" -maxdepth 1 -name '*.tgz' -type f)
          test "${#storage_archives[@]}" -eq 1
          npm install --prefix "$task_dir/install" --ignore-scripts --no-audit --no-fund "${archives[0]}" "${storage_archives[0]}" pg
          python - "$task_dir" <<'PY'
          import hashlib, json, sys, urllib.request
          from pathlib import Path
          pins = json.loads(Path('scripts/reporting-interop/pins.json').read_bytes())
          with urllib.request.urlopen(pins['python_wheel_url'], timeout=60) as response:
              body = response.read()
          if hashlib.sha256(body).hexdigest() != pins['python_wheel_sha256']:
              raise SystemExit('Python wheel digest differs from immutable pin')
          wheel = Path(sys.argv[1]) / 'adcp-8.0.0-py3-none-any.whl'
          wheel.write_bytes(body)
          PY
          python -m venv "$task_dir/python"
          "$task_dir/python/bin/python" -m pip install "$task_dir/adcp-8.0.0-py3-none-any.whl" 'psycopg[binary,pool]' pytest pytest-asyncio
          echo "REPORTING_TS_ARCHIVE=${archives[0]}" >> "$GITHUB_ENV"
          echo "REPORTING_STORAGE_ARCHIVE=${storage_archives[0]}" >> "$GITHUB_ENV"

      - name: Verify both evidence directions and TypeScript seller with Python buyer
        env:
          REPORTING_INTEROP_PG_URL: postgresql://postgres@127.0.0.1:5432/postgres
        run: |
          node scripts/reporting-interop/run.mjs \
            "$RUNNER_TEMP/reporting-sdk/python/bin/python" \
            "$RUNNER_TEMP/reporting-sdk/install" \
            "$REPORTING_TS_ARCHIVE" \
            "$REPORTING_STORAGE_ARCHIVE" \
            "$RUNNER_TEMP/reporting-sdk/adcp-8.0.0-py3-none-any.whl" \
            "$GITHUB_WORKSPACE/.context/reporting-python-harness" \
            "$RUNNER_TEMP/reporting-evidence"

      - name: Upload reporting evidence
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: reporting-evidence-node-${{ matrix.node }}
          if-no-files-found: error
          path: ${{ runner.temp }}/reporting-evidence

  reference-seller-matrix:
    name: ${{ matrix.language }} reference seller
    needs: pack-sdk-runner
    runs-on: ubuntu-latest
    timeout-minutes: 25
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: python
            repository: adcontextprotocol/adcp-client-python
            # adcp-client-python#1507 makes discovery servable: output schemas are
            # advertised compactly instead of inlining every shared $ref, taking
            # tools/list from 22.2 MiB to 1.34 MiB. The previous pin's reply was
            # refused by this SDK's 4 MiB default response cap (adcp-client#3253),
            # which left the lane with zero executed tracks.
            #
            # Pinned to the fix itself rather than main's head: the next commit
            # (#1504, d5195a95) is a buyer-side response cap this seller lane never
            # exercises. Verified on this ref — negotiates AdCP 3.2.4, advertises 14
            # tools, and executes 2/2 passing tracks under the 4 MiB default.
            ref: ${{ inputs.python_ref || 'd908aaa98caa88e5b0cd992037eb5010dc009da1' }}
            harness: scripts/ci/run_storyboard_reference_seller.sh
            port: 3001
            advisory: true
          - language: typescript
            repository: adcontextprotocol/adcp-client
            ref: df7b5837896154002bb5a4941b4b07c828521001 # @adcp/sdk@8.1.0-beta.17
            harness: scripts/ci/run_storyboard_reference_seller.sh
            port: 3002
            advisory: true
          - language: go
            repository: adcontextprotocol/adcp-go
            ref: adcp-v2.0.1
            harness: scripts/ci/run_storyboard_reference_seller.sh
            port: 3004
            advisory: true
    env:
      STORYBOARD_RESULT_PATH: ${{ github.workspace }}/storyboard-result-${{ matrix.language }}.json
      SELLER_LOG_PATH: ${{ github.workspace }}/storyboard-seller-${{ matrix.language }}.log

    steps:
      - name: Checkout candidate SDK harness
        uses: actions/checkout@v5
        with:
          persist-credentials: false

      - name: Setup Node.js
        uses: actions/setup-node@v5
        with:
          node-version: 24

      - name: Setup Python
        if: matrix.language == 'python'
        uses: actions/setup-python@v6
        with:
          python-version: '3.12'

      - name: Setup Go
        if: matrix.language == 'go'
        uses: actions/setup-go@v6
        with:
          go-version: '1.26.2'

      - name: Download SDK runner tarball
        uses: actions/download-artifact@v7
        with:
          name: adcp-sdk-runner-tarball
          path: ${{ runner.temp }}/adcp-sdk-pack

      - name: Resolve SDK runner tarball
        id: pack
        shell: bash
        run: |
          set -euo pipefail
          mapfile -t tarballs < <(find "$RUNNER_TEMP/adcp-sdk-pack" -maxdepth 1 -type f -name '*.tgz' -print)
          if [[ "${#tarballs[@]}" -ne 1 ]]; then
            echo "::error::Expected one SDK runner tarball, found ${#tarballs[@]}."
            printf '%s\n' "${tarballs[@]}"
            exit 1
          fi
          echo "tarball=${tarballs[0]}" >> "$GITHUB_OUTPUT"
          echo "Using SDK runner tarball ${tarballs[0]}"

      - name: Checkout ${{ matrix.language }} reference seller
        uses: actions/checkout@v5
        with:
          repository: ${{ matrix.repository }}
          ref: ${{ matrix.ref }}
          path: reference-${{ matrix.language }}
          persist-credentials: false

      - name: Verify ${{ matrix.language }} storyboard harness
        shell: bash
        run: |
          set -euo pipefail
          harness="reference-${{ matrix.language }}/${{ matrix.harness }}"
          if [[ ! -f "$harness" ]]; then
            echo "::error::Pinned ${{ matrix.repository }} ref '${{ matrix.ref }}' does not contain ${{ matrix.harness }}."
            echo "::error::Pin a tag or commit that includes a blocking reference-seller storyboard harness."
            exit 1
          fi
          chmod +x "$harness"

      - name: Run ${{ matrix.language }} reference seller storyboard
        shell: bash
        run: |
          set -euo pipefail
          cd "reference-${{ matrix.language }}"
          set +e
          ADCP_SDK_TARBALL="${{ steps.pack.outputs.tarball }}" \
            ADCP_PORT="${{ matrix.port }}" \
            STORYBOARD_RESULT_PATH="$STORYBOARD_RESULT_PATH" \
            SELLER_LOG_PATH="$SELLER_LOG_PATH" \
            "$GITHUB_WORKSPACE/.github/scripts/run-reference-seller.sh" "${{ matrix.language }}" "${{ matrix.harness }}"
          status=$?
          set -e

          if [[ "$status" -ne 0 && "${{ matrix.advisory }}" == "true" ]]; then
            echo "::warning::${{ matrix.language }} reference seller storyboard failed; this lane is advisory."
            exit 0
          fi

          exit "$status"

      - name: Require Python interop to execute tracks
        if: matrix.language == 'python'
        shell: bash
        run: |
          python3 - <<'PY'
          import json
          import os
          from pathlib import Path

          path = Path(os.environ['STORYBOARD_RESULT_PATH'])
          if not path.is_file() or path.stat().st_size == 0:
              raise SystemExit('Python reference seller produced no storyboard result')
          result = json.loads(path.read_text())
          summary = result.get('summary') or {}
          executed = sum(summary.get(f'tracks_{status}', 0) for status in ('passed', 'failed', 'partial', 'silent'))
          if executed == 0:
              raise SystemExit('Python reference seller executed zero tracks; check version negotiation')
          print(f'Python reference seller executed {executed} tracks')
          PY

      - name: Add interop summary
        if: always()
        shell: bash
        run: |
          {
            echo "### Reference seller interop"
            echo ""
            echo "- Implementation: \`${{ matrix.language }}\`"
            echo "- Repository: \`${{ matrix.repository }}\`"
            echo "- Ref: \`${{ matrix.ref }}\`"
            echo "- Harness: \`${{ matrix.harness }}\`"
            echo "- Advisory: \`${{ matrix.advisory }}\`"
          } >> "$GITHUB_STEP_SUMMARY"

      - name: Upload storyboard artifacts
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: ${{ matrix.language }}-reference-seller-storyboard
          if-no-files-found: ignore
          path: |
            storyboard-result-${{ matrix.language }}.json
            storyboard-seller-${{ matrix.language }}.log

  typescript-reference-seller-current:
    name: TypeScript reference seller (current checkout)
    if: github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch'
    needs: pack-sdk-runner
    runs-on: ubuntu-latest
    timeout-minutes: 25
    env:
      STORYBOARD_RESULT_PATH: ${{ github.workspace }}/storyboard-result-typescript.json
      SELLER_LOG_PATH: ${{ github.workspace }}/storyboard-seller-typescript.log

    steps:
      - name: Checkout @adcp/sdk
        uses: actions/checkout@v5
        with:
          persist-credentials: false

      - name: Setup Node.js
        uses: actions/setup-node@v5
        with:
          node-version: 24
          cache: npm

      - name: Download SDK runner tarball
        uses: actions/download-artifact@v7
        with:
          name: adcp-sdk-runner-tarball
          path: ${{ runner.temp }}/adcp-sdk-pack

      - name: Resolve SDK runner tarball
        id: pack
        shell: bash
        run: |
          set -euo pipefail
          mapfile -t tarballs < <(find "$RUNNER_TEMP/adcp-sdk-pack" -maxdepth 1 -type f -name '*.tgz' -print)
          if [[ "${#tarballs[@]}" -ne 1 ]]; then
            echo "::error::Expected one SDK runner tarball, found ${#tarballs[@]}."
            printf '%s\n' "${tarballs[@]}"
            exit 1
          fi
          echo "tarball=${tarballs[0]}" >> "$GITHUB_OUTPUT"
          echo "Using SDK runner tarball ${tarballs[0]}"

      - name: Run TypeScript example seller storyboard
        shell: bash
        run: |
          set -euo pipefail
          chmod +x scripts/ci/run_storyboard_reference_seller.sh
          ADCP_SDK_TARBALL="${{ steps.pack.outputs.tarball }}" \
            ADCP_PORT=3002 \
            STORYBOARD_RESULT_PATH="$STORYBOARD_RESULT_PATH" \
            SELLER_LOG_PATH="$SELLER_LOG_PATH" \
            ./scripts/ci/run_storyboard_reference_seller.sh

      - name: Add interop summary
        if: always()
        shell: bash
        run: |
          {
            echo "### TypeScript reference seller harness"
            echo ""
            echo "- Repository: \`${{ github.repository }}\`"
            echo "- Ref: current checkout \`${{ github.sha }}\`"
            echo "- Seller: \`examples/hello_seller_adapter_guaranteed.ts\`"
            echo "- Harness: \`scripts/ci/run_storyboard_reference_seller.sh\`"
            echo "- Note: tagged TypeScript release compatibility is covered by the matrix row pinned to @adcp/sdk@8.1.0-beta.17."
          } >> "$GITHUB_STEP_SUMMARY"

      - name: Upload storyboard artifacts
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: typescript-reference-seller-storyboard
          if-no-files-found: ignore
          path: |
            storyboard-result-typescript.json
            storyboard-seller-typescript.log

  typescript-strict-adcp-3-0-reference-seller:
    name: TypeScript strict AdCP 3.0 reference seller
    if: github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_call'
    needs: pack-sdk-runner
    runs-on: ubuntu-latest
    timeout-minutes: 25
    env:
      STORYBOARD_RESULT_PATH: ${{ github.workspace }}/storyboard-result-typescript-strict-3-0.json
      SELLER_LOG_PATH: ${{ github.workspace }}/storyboard-seller-typescript-strict-3-0.log
      # v5.22.0 is the final tagged TypeScript SDK release line pinned to
      # AdCP 3.0.x before the 3.1 beta envelope shipped. The harness runs it
      # behind a strict proxy that rejects the 3.1-only adcp_version marker.
      STRICT_ADCP_3_0_REF: 88bacfdcc0fca4066462d5b621ffc2d7f7a5d348

    steps:
      - name: Checkout candidate @adcp/sdk
        uses: actions/checkout@v5
        with:
          path: candidate-sdk
          persist-credentials: false

      - name: Checkout pinned strict AdCP 3.0 TypeScript reference seller
        uses: actions/checkout@v5
        with:
          repository: adcontextprotocol/adcp-client
          ref: ${{ env.STRICT_ADCP_3_0_REF }}
          path: reference-typescript-strict-3-0
          persist-credentials: false

      - name: Setup Node.js
        uses: actions/setup-node@v5
        with:
          node-version: 24

      - name: Download SDK runner tarball
        uses: actions/download-artifact@v7
        with:
          name: adcp-sdk-runner-tarball
          path: ${{ runner.temp }}/adcp-sdk-pack

      - name: Resolve SDK runner tarball
        id: pack
        shell: bash
        run: |
          set -euo pipefail
          mapfile -t tarballs < <(find "$RUNNER_TEMP/adcp-sdk-pack" -maxdepth 1 -type f -name '*.tgz' -print)
          if [[ "${#tarballs[@]}" -ne 1 ]]; then
            echo "::error::Expected one SDK runner tarball, found ${#tarballs[@]}."
            printf '%s\n' "${tarballs[@]}"
            exit 1
          fi
          echo "tarball=${tarballs[0]}" >> "$GITHUB_OUTPUT"
          echo "Using SDK runner tarball ${tarballs[0]}"

      - name: Run strict AdCP 3.0 reference seller storyboard
        shell: bash
        run: |
          set -euo pipefail
          chmod +x candidate-sdk/scripts/ci/run_storyboard_strict_3_0_reference_seller.sh
          ADCP_SDK_TARBALL="${{ steps.pack.outputs.tarball }}" \
            ADCP_REFERENCE_REPO_ROOT="${{ github.workspace }}/reference-typescript-strict-3-0" \
            ADCP_PORT=3003 \
            ADCP_INTERNAL_PORT=3004 \
            STORYBOARD_RESULT_PATH="$STORYBOARD_RESULT_PATH" \
            SELLER_LOG_PATH="$SELLER_LOG_PATH" \
            candidate-sdk/scripts/ci/run_storyboard_strict_3_0_reference_seller.sh

      - name: Add interop summary
        if: always()
        shell: bash
        run: |
          {
            echo "### Strict AdCP 3.0 reference seller interop"
            echo ""
            echo "- Repository: \`adcontextprotocol/adcp-client\`"
            echo "- Ref: \`${STRICT_ADCP_3_0_REF}\`"
            echo "- Protocol pin: AdCP 3.0.x"
            echo "- Harness: \`scripts/ci/run_storyboard_strict_3_0_reference_seller.sh\`"
            echo "- Advisory: \`false\`"
          } >> "$GITHUB_STEP_SUMMARY"

      - name: Upload storyboard artifacts
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: typescript-strict-adcp-3-0-reference-seller-storyboard
          if-no-files-found: ignore
          path: |
            storyboard-result-typescript-strict-3-0.json
            storyboard-seller-typescript-strict-3-0.log