ci.yml

name: CI

on:
  push:
    branches: [main, python-adcp-sdk-setup]
  pull_request:
    branches:
      - main
      - conductor/reporting-webhook-activity-1168b
      - conductor/reporting-status-notifications-1168c
      - conductor/1167b1-materializer-contracts
      - conductor/1167b2-durable-managed-reporting
      - conductor/reporting-receipt-ingress-b22
      - conductor/reporting-frozen-account-feed-b23
      - conductor/reporting-schema-proof-receipt-diagnostics-hardening
      - conductor/reporting-production-tier-capabilities-b24
      - conductor/reporting-adcp-rc4-adoption
  workflow_dispatch:

# Exact AdCP 3.2.1 runner; the reference matrix also retains the AdCP 3.0 floor.
env:
  ADCP_SDK_VERSION: "14.0.0"

concurrency:
  # A tagged main commit needs its own full CI even when main advances.
  # PR updates may still cancel superseded runs for the same PR ref.
  group: ci-${{ github.event_name == 'pull_request' && github.ref || github.sha }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  changes:
    name: CI scope
    runs-on: ubuntu-latest
    timeout-minutes: 5
    permissions:
      contents: read
    outputs:
      run_tests: ${{ steps.scope.outputs.run_tests }}
      full_matrix: ${{ steps.scope.outputs.full_matrix }}
      run_postgres: ${{ steps.scope.outputs.run_postgres }}
      run_packaging: ${{ steps.scope.outputs.run_packaging }}
      run_storyboards: ${{ steps.scope.outputs.run_storyboards }}
      release_metadata: ${{ steps.scope.outputs.release_metadata }}
      expected_results: ${{ steps.scope.outputs.expected_results }}
    steps:
      # A PR merge commit's two parents contain the complete base/head diff.
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
        with:
          fetch-depth: 2
          persist-credentials: false
          sparse-checkout: scripts/ci/ci_scope.py
          sparse-checkout-cone-mode: false
      - name: Select SDK test scope
        id: scope
        run: python3 scripts/ci/ci_scope.py

  workflow-security:
    name: Workflow security
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
        with:
          persist-credentials: false
      - name: Lint workflows
        uses: raven-actions/actionlint@3d39aea434753780c3b3d4a1a31c854b4dbf49d7 # v2.2.0
        with:
          version: 1.7.7
          shellcheck: false
          # actionlint v1.7.x predates GitHub's `queue: max` concurrency
          # syntax. Keep linting every other workflow field until its parser
          # catches up.
          flags: >-
            -ignore ^unexpected\s+key\s+\x22queue\x22\s+for\s+\x22concurrency\x22\s+section
      - name: Test Ladon review-state helper
        run: node --test scripts/retire-superseded-ladon-reviews.test.cjs
      - name: Audit workflows
        uses: zizmorcore/zizmor-action@3dc1ecc9bcb9e94e9b2c709687979e1298497054 # v0.6.2
        with:
          inputs: >-
            .github/workflows/claude-issue-triage.yml
            .github/workflows/ipr-agreement.yml
            .github/workflows/sync-agent-roles.yml
            .github/workflows/slash-command-dispatch.yml
            .github/workflows/ai-review.yml
            .github/workflows/release-please.yml
            .github/workflows/release-publish.yml
          version: 1.29.0
          min-severity: high
          min-confidence: high
          advanced-security: false
          annotations: true

  test:
    needs: changes
    if: needs.changes.outputs.run_tests == 'true'
    name: Test Python ${{ matrix.python-version }}
    runs-on: ubuntu-latest
    # 3.12 always runs the canonical suite and coverage. Ordinary PRs use
    # compatibility checks on the other interpreters; main/manual runs and
    # shared build/schema/type changes retain exhaustive interpreter coverage.
    # Recent coverage runs take 53 minutes before setup/type checks. Keep
    # 15 minutes beyond each full-suite step for those other required checks.
    timeout-minutes: ${{ matrix.python-version == '3.12' && 85 || needs.changes.outputs.full_matrix == 'true' && 70 || 15 }}
    strategy:
      # Complete exhaustive lanes independently so late interpreter failures
      # preserve coverage results. Fast PR compatibility checks cancel early.
      fail-fast: ${{ needs.changes.outputs.full_matrix != 'true' }}
      matrix:
        python-version: ["3.10", "3.11", "3.12", "3.13"]

    steps:
      - uses: actions/checkout@v6

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v6
        with:
          python-version: ${{ matrix.python-version }}

      - name: Set up uv
        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
        with:
          version: "0.12.8"
          enable-cache: true
          cache-dependency-glob: pyproject.toml
          cache-suffix: ${{ matrix.python-version }}
          prune-cache: true

      - name: Install dependencies
        run: |
          uv pip install --system -e ".[dev]" -e "./packages/adcp-reporting-storage"

      - name: Run linter
        if: matrix.python-version == '3.12'
        run: ruff check src/ packages/adcp-reporting-storage/src/

      - name: Run type checker
        if: matrix.python-version == '3.12'
        run: mypy src/adcp/ packages/adcp-reporting-storage/src/adcp_reporting_storage/

      - name: Run adopter type-check suite
        if: matrix.python-version == '3.12'
        run: mypy --strict tests/type_checks/ examples/reporting_webhook_activity.py examples/reporting_status_notifications.py examples/reporting_destination_writer.py examples/reporting_durable_materializer.py examples/reporting_receipt_ingress.py examples/reporting_production.py

      - name: Run adopter type-check suite under pyright
        if: matrix.python-version == '3.12'
        # The fixtures that import psycopg need the pg extra, which this job's
        # dev-only install does not bring; pyright has no ignore_missing_imports.
        run: |
          uv pip install --system -e ".[pg]"
          python scripts/run_pyright_type_checks.py

      - name: Check versioned typing generation
        if: matrix.python-version == '3.12'
        run: |
          python scripts/generate_versioned_stubs.py --check
          python scripts/generate_versioned_bases.py --check

      - name: Enforce adopter type-check fixture contract
        if: matrix.python-version == '3.12'
        run: python scripts/check_type_ignore_contract.py

      - name: Run full native suite
        if: matrix.python-version != '3.12' && needs.changes.outputs.full_matrix == 'true'
        timeout-minutes: 55
        run: python scripts/ci/run_native_tests.py --mode full --unit-workers 2

      - name: Run interpreter compatibility checks
        if: (matrix.python-version != '3.12' && needs.changes.outputs.full_matrix != 'true') || needs.changes.outputs.release_metadata == 'true'
        timeout-minutes: 10
        run: python scripts/ci/run_native_tests.py --mode compatibility

      - name: Run canonical suite with coverage
        if: matrix.python-version == '3.12' && needs.changes.outputs.release_metadata != 'true'
        timeout-minutes: 70
        run: python scripts/ci/run_native_tests.py --mode full --coverage --unit-workers 2

      - name: Validate release metadata and built distributions
        if: matrix.python-version == '3.12' && needs.changes.outputs.release_metadata == 'true'
        timeout-minutes: 10
        run: |
          python -m pytest tests/test_release_configuration.py tests/test_normalize_pyproject_prerelease.py -n 0 -q
          python -m build --outdir "${RUNNER_TEMP}/release-metadata-dist"
          python -m scripts.ci.check_release_artifacts "${RUNNER_TEMP}/release-metadata-dist"

  pg-conformance:
    needs: changes
    if: needs.changes.outputs.run_postgres == 'true'
    name: Postgres conformance tests (Postgres 16, ${{ matrix.lane }})
    runs-on: ubuntu-latest
    timeout-minutes: ${{ matrix.timeout_minutes }}
    permissions:
      contents: read
    strategy:
      fail-fast: false
      matrix:
        include:
          # Core also builds and installs the reporting wheel/sdist fixtures.
          # It runs 25-29 minutes on main, so 30 cancelled it on slow runners.
          - lane: core
            timeout_minutes: 45
          - lane: process
            timeout_minutes: 15
    services:
      postgres:
        # CI-local ephemeral database. POSTGRES_HOST_AUTH_METHOD=trust
        # avoids shipping any password literal (real or placeholder) in
        # this workflow — GitHub's default CI network is already the
        # trust boundary for this throwaway service.
        image: postgres:16
        env:
          POSTGRES_HOST_AUTH_METHOD: trust
          POSTGRES_DB: adcp_test
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 5s
          --health-timeout 5s
          --health-retries 10

    steps:
      - uses: actions/checkout@v6

      - name: Fetch reviewed reporting baseline for rolling binary tests
        timeout-minutes: 1
        run: git fetch --no-tags --depth=1 origin 17ee407ae3978c8a2bb54437287afbf9dafb8130

      - name: Set up Python 3.12
        uses: actions/setup-python@v6
        with:
          python-version: "3.12"

      - name: Set up uv
        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
        with:
          version: "0.12.8"
          enable-cache: true
          cache-dependency-glob: pyproject.toml
          cache-suffix: "3.12"
          prune-cache: true

      - name: Install dependencies (with [pg] extra)
        run: |
          uv pip install --system -e ".[dev,pg]" -e "./packages/adcp-reporting-storage[pg,gcs,s3,azure]"

      - name: Run Postgres conformance tests
        env:
          ADCP_PG_TEST_URL: postgresql://postgres@localhost:5432/adcp_test
          PG_LANE: ${{ matrix.lane }}
        run: |
          # Keep every case and its per-case deadline. The core lane includes
          # installed artifact coverage and has a larger overall job budget.
          case "$PG_LANE" in
            core)
              python scripts/reporting_test_harness.py pytest tests/conformance/signing/test_pg_replay_store.py \
                     tests/conformance/signing/test_pg_replay_store_e2e.py \
                     tests/conformance/decisioning/test_pg_buyer_agent_registry.py \
                     tests/conformance/decisioning/test_pg_idempotency_backend.py \
                     tests/conformance/decisioning/test_pg_idempotency_reservation.py \
                     tests/test_decisioning_task_polling.py \
                     tests/test_decisioning_task_lifecycle.py \
                     tests/test_decisioning_lazy_pg_stores.py \
                     tests/conformance/decisioning/test_pg_task_webhook_outbox.py \
                     tests/conformance/decisioning/test_pg_notification_outbox.py \
                     tests/conformance/decisioning/test_pg_webhook_delivery_supervisor.py \
                     tests/test_notification_outbox.py \
                     tests/test_notification_outbox_artifacts.py \
                     tests/conformance/decisioning/test_pg_reference_workflow_queue.py \
                     tests/conformance/reporting/ \
                     tests/test_reporting_storyboard_orchestration.py::test_database_owner_returns_node_postgres_uri_after_psycopg_validation \
                     tests/test_reporting_storyboard_orchestration.py::test_node_database_url_materializes_libpq_default_user \
                     --ignore=tests/conformance/reporting/test_reporting_notification_process_matrix.py \
                     --ignore-glob='tests/conformance/reporting/test_reporting_status_*.py' \
                     --ignore=tests/conformance/reporting/test_reporting_materializer_rolling.py \
                     --ignore=tests/conformance/reporting/test_reporting_materializer_process.py \
                     --ignore=tests/conformance/reporting/test_reporting_materializer_migration.py \
                     --ignore=tests/conformance/reporting/test_reporting_materializer_installed_pg.py \
                     --ignore-glob='tests/conformance/reporting/test_reporting_receipt_*.py' \
                     --ignore-glob='tests/conformance/reporting/test_reporting_feed_*.py' \
                     --ignore-glob='tests/conformance/reporting/test_reporting_production*.py' \
                     --ignore-glob='tests/conformance/reporting/test_reporting_projection*.py' \
                     --ignore=tests/conformance/reporting/test_reporting_tier_projection.py \
                     --ignore=tests/conformance/reporting/test_reporting_schedule_schema.py \
                     --ignore=tests/conformance/reporting/test_reporting_rc6_rolling.py \
                     -v -ra
              ;;
            process)
              python scripts/reporting_test_harness.py pytest tests/conformance/reporting/test_reporting_notification_process_matrix.py -v -ra
              ;;
            *)
              echo "Unknown Postgres conformance lane"
              exit 1
              ;;
          esac

  reporting-js-interop:
    needs: changes
    if: needs.changes.outputs.run_postgres == 'true'
    name: Row storage interop with the JavaScript SDK (Postgres 16)
    runs-on: ubuntu-latest
    # npm ci and the full adcp-client build dominate; the interop test itself takes seconds.
    timeout-minutes: 30
    permissions:
      contents: read
    # PURPOSE: the shared row-storage layout is only shared if the shipped JavaScript SDK reads
    # what Python writes and the reverse, against one database and one bucket. This lane builds
    # adcp-client at its main branch (deliberately not pinned to a commit) and runs
    # test_one_database_and_one_bucket_in_both_directions with ADCP_REQUIRE_JS_INTEROP=1, so a
    # missing build or environment fails instead of skipping. If JavaScript main changes its
    # stored format before Python mirrors it, this job correctly fails: that is the gate.
    services:
      postgres:
        image: mirror.gcr.io/library/postgres:16
        env:
          POSTGRES_HOST_AUTH_METHOD: trust
          POSTGRES_DB: adcp_interop_test
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 5s
          --health-timeout 5s
          --health-retries 10
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with:
          python-version: "3.12"
      - name: Set up uv
        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
        with:
          version: "0.12.8"
          enable-cache: true
          cache-dependency-glob: pyproject.toml
          cache-suffix: "3.12"
          prune-cache: true
      - name: Check out the JavaScript SDK (main)
        uses: actions/checkout@v6
        with:
          repository: adcontextprotocol/adcp-client
          ref: main
          path: adcp-client-js
          persist-credentials: false
      - name: Set up Node 22.12.0
        uses: actions/setup-node@v6
        with:
          node-version: "22.12.0"
          cache: npm
          cache-dependency-path: adcp-client-js/package-lock.json
      - name: Build the JavaScript SDK
        working-directory: adcp-client-js
        run: |
          npm ci
          npm run build
          test -f dist/lib/reporting/ledger/index.js
          # SDK 16 moved the row storage into the @adcp/reporting-storage workspace
          # package, which the root build does not compile; the interop driver reads it.
          npm run build --workspace packages/reporting-storage
          test -f node_modules/@adcp/reporting-storage/dist/index.js
      - name: Install test dependencies
        run: uv pip install --system -e ".[dev,pg]" -e "./packages/adcp-reporting-storage[pg,gcs,s3,azure]"
      - name: Run the interop test in both directions
        env:
          ADCP_PG_TEST_URL: postgresql://postgres@localhost:5432/adcp_interop_test
          ADCP_JS_SDK_DIR: ${{ github.workspace }}/adcp-client-js
          ADCP_REQUIRE_JS_INTEROP: "1"
        run: |
          python -m pytest -n0 -p no:cacheprovider -v -ra \
            tests/conformance/reporting/test_reporting_row_storage_interop_pg.py

  pg-conformance-required-gate:
    name: Postgres conformance tests (Postgres 16)
    runs-on: ubuntu-latest
    timeout-minutes: 5
    permissions: {}
    needs: [changes, pg-conformance, pg-reporting-status, pg-reporting-materializer, pg-reporting-receipts, pg-reporting-receipt-compatibility, pg-reporting-feed, pg-reporting-feed-compatibility, pg-reporting-feed-installed, pg-reporting-production, pg-reporting-production-compatibility, pg-reporting-production-installed, reporting-js-interop, reporting-installed-artifact-matrix]
    # Failed lanes must still fail the gate; superseded runs should release
    # their concurrency slot instead of keeping an uncancelable job queued.
    if: ${{ !cancelled() }}
    steps:
      - name: Require every Postgres conformance lane
        env:
          CI_NEEDS: ${{ toJSON(needs) }}
        run: |
          python3 - <<'PY'
          import json, os
          needs = json.loads(os.environ["CI_NEEDS"])
          scope = needs.pop("changes")
          expected = json.loads(scope.get("outputs", {}).get("expected_results", "{}"))
          if scope["result"] != "success" or not isinstance(expected, dict) or not expected:
              raise SystemExit("CI scope could not be verified")
          bad = {
              name: job["result"] for name, job in needs.items()
              if expected.get(name) not in ("success", "skipped") or job["result"] != expected[name]
          }
          if not needs or bad:
              raise SystemExit("Required CI lanes did not complete as expected: " + json.dumps(bad))
          print("All required lanes completed according to the verified CI scope")
          PY

  pg-reporting-status:
    needs: changes
    if: needs.changes.outputs.run_postgres == 'true'
    name: Reporting status conformance (Postgres 16)
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_HOST_AUTH_METHOD: trust
          POSTGRES_DB: adcp_status_test
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 5s
          --health-timeout 5s
          --health-retries 10
    steps:
      - uses: actions/checkout@v6

      - name: Fetch exact reviewed A, B and C compatibility artifacts
        timeout-minutes: 1
        run: |
          git fetch --no-tags --depth=1 origin \
            17ee407ae3978c8a2bb54437287afbf9dafb8130 \
            0f34c666ac1961e9832fce43ef0ef6937b3c1dde \
            967b6e286301d7e5d089aea6fdbb90bea8ee5a16

      - name: Set up Python 3.12
        uses: actions/setup-python@v6
        with:
          python-version: "3.12"

      - name: Set up uv
        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
        with:
          version: "0.12.8"
          enable-cache: true
          cache-dependency-glob: pyproject.toml
          cache-suffix: "3.12"
          prune-cache: true

      - name: Install dependencies (with [pg] extra)
        run: |
          uv pip install --system -e ".[dev,pg]" -e "./packages/adcp-reporting-storage[pg,gcs,s3,azure]"

      - name: Run status semantics, transaction, clock/process and maintenance gates
        env:
          ADCP_PG_TEST_URL: postgresql://postgres@localhost:5432/adcp_status_test
        run: python scripts/reporting_test_harness.py pytest tests/conformance/reporting/test_reporting_status_*.py -v -ra

  pg-reporting-materializer:
    needs: changes
    if: needs.changes.outputs.run_postgres == 'true'
    name: Durable materializer and frozen artifacts (Postgres 16)
    runs-on: ubuntu-latest
    # Actual wheel builds/installations plus isolated worker processes are a
    # separate bounded job; do not consume the existing conformance headroom.
    # Seven real installations plus process/crash and Python 3.10 distribution
    # cells approach twenty minutes locally; allow runner variance and retain
    # five minutes outside the suite for setup and cleanup.
    timeout-minutes: 35
    permissions:
      contents: read
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_HOST_AUTH_METHOD: trust
          POSTGRES_DB: adcp_materializer_test
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 5s
          --health-timeout 5s
          --health-retries 10
    steps:
      - uses: actions/checkout@v6
      - name: Fetch exact frozen reporting artifacts
        timeout-minutes: 2
        run: |
          git fetch --no-tags --depth=1 origin \
            3e76aa54623529a3dda01cd690b8a5c287c75641 \
            3c405a21f978ed9d3208611bb4a7a8434a056933 \
            037de4ac822ecefb2f95d32c15c297fb4c45d683 \
            17ee407ae3978c8a2bb54437287afbf9dafb8130 \
            0f34c666ac1961e9832fce43ef0ef6937b3c1dde \
            967b6e286301d7e5d089aea6fdbb90bea8ee5a16 \
            5487f2bdef23c5102118b305be9e868228f6ce61
      - uses: actions/setup-python@v6
        id: materializer-python310
        with:
          python-version: "3.10"
      - uses: actions/setup-python@v6
        with:
          python-version: "3.12"
      - name: Set up uv
        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
        with:
          version: "0.12.8"
          enable-cache: true
          cache-dependency-glob: pyproject.toml
          cache-suffix: "3.12"
          prune-cache: true

      - name: Install test dependencies
        run: uv pip install --system -e ".[dev,pg]" -e "./packages/adcp-reporting-storage[pg,gcs,s3,azure]"
      - name: Run installed frozen binaries and materializer migrations
        # Propagate pytest failures through tee while retaining evidence for upload.
        shell: bash
        timeout-minutes: 30
        env:
          ADCP_PG_TEST_URL: postgresql://postgres@localhost:5432/adcp_materializer_test
          ADCP_PYTHON310: ${{ steps.materializer-python310.outputs.python-path }}
        run: |
          python scripts/reporting_test_harness.py pytest \
            tests/conformance/reporting/test_reporting_caller_ownership.py \
            tests/conformance/reporting/test_reporting_materializer_migration.py \
            tests/conformance/reporting/test_reporting_materializer_process.py \
            tests/conformance/reporting/test_reporting_materializer_installed_pg.py \
            -v -s -ra | tee materializer-evidence.log
      - name: Preserve installed module and worker evidence
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: materializer-evidence-${{ github.run_attempt }}
          retention-days: 7
          path: materializer-evidence.log
          if-no-files-found: error

  pg-reporting-receipts:
    needs: changes
    if: needs.changes.outputs.run_postgres == 'true'
    name: Authenticated receipts and installed replay (Postgres 16)
    runs-on: ubuntu-latest
    # Separate databases avoid shared account advisory locks. Keep five minutes
    # outside the bounded suite for checkout, installations and cleanup.
    timeout-minutes: 35
    permissions:
      contents: read
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_HOST_AUTH_METHOD: trust
          POSTGRES_DB: adcp_receipts_test
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 5s
          --health-timeout 5s
          --health-retries 10
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        id: receipt-python310
        with:
          python-version: "3.10"
      - uses: actions/setup-python@v6
        with:
          python-version: "3.12"
      - name: Set up uv
        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
        with:
          version: "0.12.8"
          enable-cache: true
          cache-dependency-glob: pyproject.toml
          cache-suffix: "3.12"
          prune-cache: true

      - name: Install test dependencies
        run: uv pip install --system -e ".[dev,pg]" -e "./packages/adcp-reporting-storage[pg,gcs,s3,azure]"
      - name: Run receipt transactions, real mounts, crash and installed gates
        shell: bash
        timeout-minutes: 30
        env:
          ADCP_PG_TEST_URL: postgresql://postgres@localhost:5432/adcp_receipts_test
          ADCP_PYTHON310: ${{ steps.receipt-python310.outputs.python-path }}
        run: |
          # Explicit pytest paths bypass --ignore; exclude rolling before invocation.
          shopt -s nullglob
          receipt_tests=()
          for test_file in tests/conformance/reporting/test_reporting_receipt_*.py; do
            if [[ "$test_file" != tests/conformance/reporting/test_reporting_receipt_rolling.py ]]; then
              receipt_tests+=("$test_file")
            fi
          done
          if (( ${#receipt_tests[@]} == 0 )); then
            echo "No receipt test files selected" >&2
            exit 1
          fi
          python scripts/reporting_test_harness.py pytest \
            "${receipt_tests[@]}" \
            -v -s -ra | tee pg-reporting-receipts-evidence.log
      - name: Preserve commands, counts, installed provenance and skip reasons
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: pg-reporting-receipts-evidence-${{ github.run_attempt }}
          retention-days: 7
          path: pg-reporting-receipts-evidence.log
          if-no-files-found: error

  pg-reporting-receipt-compatibility:
    needs: changes
    if: needs.changes.outputs.run_postgres == 'true'
    name: Receipt ownership maintenance upgrade (Postgres 16)
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_HOST_AUTH_METHOD: trust
          POSTGRES_DB: adcp_receipt_maintenance_test
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 5s
          --health-timeout 5s
          --health-retries 10
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with:
          python-version: "3.12"
      - name: Set up uv
        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
        with:
          version: "0.12.8"
          enable-cache: true
          cache-dependency-glob: pyproject.toml
          cache-suffix: "3.12"
          prune-cache: true

      - name: Install test dependencies
        run: uv pip install --system -e ".[dev,pg]" -e "./packages/adcp-reporting-storage[pg,gcs,s3,azure]"
      - name: Require stopped-worker retention, ownership backfill and receipt isolation
        env:
          ADCP_PG_TEST_URL: postgresql://postgres@localhost:5432/adcp_receipt_maintenance_test
        run: |
          python scripts/reporting_test_harness.py pytest \
            tests/conformance/reporting/test_reporting_caller_ownership.py \
            tests/conformance/reporting/test_reporting_reconciliation_migration.py \
            -v -ra

  pg-reporting-feed:
    needs: changes
    if: needs.changes.outputs.run_postgres == 'true'
    name: Frozen authorized feed and mounted isolation (Postgres 16)
    runs-on: ubuntu-latest
    # Crash processes and shared memory/SQL vectors have their own database
    # and bounded suite; setup and cleanup have five minutes of headroom.
    timeout-minutes: 25
    permissions:
      contents: read
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_HOST_AUTH_METHOD: trust
          POSTGRES_DB: adcp_feed_test
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 5s
          --health-timeout 5s
          --health-retries 10
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with:
          python-version: "3.12"
      - name: Set up uv
        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
        with:
          version: "0.12.8"
          enable-cache: true
          cache-dependency-glob: pyproject.toml
          cache-suffix: "3.12"
          prune-cache: true

      - name: Install test dependencies
        run: uv pip install --system -e ".[dev,pg]" -e "./packages/adcp-reporting-storage[pg,gcs,s3,azure]"
      - name: Run frozen feeds, checkpoints, mounts, transaction faults and migrations
        shell: bash
        timeout-minutes: 20
        env:
          ADCP_PG_TEST_URL: postgresql://postgres@localhost:5432/adcp_feed_test
        run: |
          # Filter before pytest receives explicit paths; --ignore cannot do this.
          shopt -s nullglob
          feed_tests=()
          for test_file in tests/conformance/reporting/test_reporting_feed_*.py; do
            case "$test_file" in
              tests/conformance/reporting/test_reporting_feed_rolling.py|tests/conformance/reporting/test_reporting_feed_packaging.py|tests/conformance/reporting/test_reporting_feed_installed_pg.py|tests/conformance/reporting/test_reporting_feed_hardening_installed.py) ;;
              *) feed_tests+=("$test_file") ;;
            esac
          done
          if (( ${#feed_tests[@]} == 0 )); then
            echo "No native feed test files selected" >&2
            exit 1
          fi
          python scripts/reporting_test_harness.py pytest \
            "${feed_tests[@]}" \
            -v -s -ra | tee pg-reporting-feed-evidence.log
      - name: Preserve exact public, private, restart and fault evidence
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: pg-reporting-feed-evidence-${{ github.run_attempt }}
          retention-days: 7
          path: pg-reporting-feed-evidence.log
          if-no-files-found: error

  pg-reporting-feed-compatibility:
    needs: changes
    if: needs.changes.outputs.run_postgres == 'true'
    name: Feed ownership maintenance upgrade (Postgres 16)
    runs-on: ubuntu-latest
    # Caller ownership is a breaking storage boundary. Old cursors and pending
    # work are retained in quarantine; mixed-version workers are unsupported.
    timeout-minutes: 50
    permissions:
      contents: read
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_HOST_AUTH_METHOD: trust
          POSTGRES_DB: adcp_feed_rolling_test
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 5s
          --health-timeout 5s
          --health-retries 10
    steps:
      - uses: actions/checkout@v6
      - name: Fetch all nine exact approved historical artifacts
        timeout-minutes: 2
        run: |
          git fetch --no-tags --depth=1 origin \
            3e76aa54623529a3dda01cd690b8a5c287c75641 \
            3c405a21f978ed9d3208611bb4a7a8434a056933 \
            037de4ac822ecefb2f95d32c15c297fb4c45d683 \
            17ee407ae3978c8a2bb54437287afbf9dafb8130 \
            0f34c666ac1961e9832fce43ef0ef6937b3c1dde \
            967b6e286301d7e5d089aea6fdbb90bea8ee5a16 \
            5487f2bdef23c5102118b305be9e868228f6ce61 \
            3fd62121c96a074e3ea458c30c5224d6a586f169 \
            09fd87f79a746665d828dea66b3a1dd9d1fc189e
      - uses: actions/setup-python@v6
        with:
          python-version: "3.12"
      - name: Set up uv
        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
        with:
          version: "0.12.8"
          enable-cache: true
          cache-dependency-glob: pyproject.toml
          cache-suffix: "3.12"
          prune-cache: true

      - name: Install test dependencies
        run: uv pip install --system -e ".[dev,pg]" -e "./packages/adcp-reporting-storage[pg,gcs,s3,azure]"
      - name: Require private feeds and legacy cursor invalidation after maintenance
        shell: bash
        timeout-minutes: 45
        env:
          ADCP_PG_TEST_URL: postgresql://postgres@localhost:5432/adcp_feed_rolling_test
        run: |
          python scripts/reporting_test_harness.py pytest \
            tests/conformance/reporting/test_reporting_caller_ownership.py \
            tests/conformance/reporting/test_reporting_generation_migration.py \
            -v -s -ra | tee pg-reporting-feed-compatibility-evidence.log
      - name: Preserve exact artifact origins, catalogs and original replay responses
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: pg-reporting-feed-compatibility-evidence-${{ github.run_attempt }}
          retention-days: 7
          path: pg-reporting-feed-compatibility-evidence.log
          if-no-files-found: error

  pg-reporting-feed-installed:
    needs: changes
    if: needs.changes.outputs.run_postgres == 'true'
    name: Installed frozen feed (Python 3.10 VCS and sdist)
    runs-on: ubuntu-latest
    timeout-minutes: 50
    permissions:
      contents: read
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_HOST_AUTH_METHOD: trust
          POSTGRES_DB: adcp_feed_installed_test
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 5s
          --health-timeout 5s
          --health-retries 10
    steps:
      - uses: actions/checkout@v6
      - name: Fetch the exact integrated B2.3 hardening comparison artifact
        timeout-minutes: 1
        run: git fetch --no-tags origin 2d777ace7b4bf8be519ce0abd4fd0a25ed4f1da7
      - uses: actions/setup-python@v6
        id: feed-python310
        with:
          python-version: "3.10"
      - uses: actions/setup-python@v6
        with:
          python-version: "3.12"
      - name: Set up uv
        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
        with:
          version: "0.12.8"
          enable-cache: true
          cache-dependency-glob: pyproject.toml
          cache-suffix: "3.12"
          prune-cache: true

      - name: Install test dependencies
        run: uv pip install --system -e ".[dev,pg]" -e "./packages/adcp-reporting-storage[pg,gcs,s3,azure]"
      - name: Run installed base and PostgreSQL restart cells
        shell: bash
        timeout-minutes: 40
        env:
          ADCP_PG_TEST_URL: postgresql://postgres@localhost:5432/adcp_feed_installed_test
          ADCP_PYTHON310: ${{ steps.feed-python310.outputs.python-path }}
          ADCP_HARDENING_EVIDENCE: ${{ runner.temp }}/hardening-installed-evidence
        run: |
          python scripts/reporting_test_harness.py pytest \
            tests/conformance/reporting/test_reporting_feed_packaging.py \
            tests/conformance/reporting/test_reporting_feed_installed_pg.py \
            tests/conformance/reporting/test_reporting_feed_hardening_installed.py \
            -v -s -ra | tee pg-reporting-feed-installed-evidence.log
      - name: Preserve installed origins, SQL, strict adopter and cold page evidence
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: pg-reporting-feed-installed-evidence-${{ github.run_attempt }}
          retention-days: 7
          path: |
            pg-reporting-feed-installed-evidence.log
            ${{ runner.temp }}/hardening-installed-evidence
          if-no-files-found: error

  pg-reporting-production:
    needs: changes
    if: needs.changes.outputs.run_postgres == 'true'
    name: Production reporting status, ownership and notification contracts
    runs-on: ubuntu-latest
    permissions:
      contents: read
    timeout-minutes: 45
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_HOST_AUTH_METHOD: trust
          POSTGRES_DB: adcp_production_test
        ports: ["5432:5432"]
        options: >-
          --health-cmd pg_isready --health-interval 5s
          --health-timeout 5s --health-retries 10
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with:
          python-version: "3.12"
      - name: Set up uv
        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
        with:
          version: "0.12.8"
          enable-cache: true
          cache-dependency-glob: pyproject.toml
          cache-suffix: "3.12"
          prune-cache: true

      - name: Install test dependencies
        run: uv pip install --system -e ".[dev,pg]" -e "./packages/adcp-reporting-storage[pg,gcs,s3,azure]"
      - name: Run complete production and projection conformance
        shell: bash
        # A passing suite plus harness cleanup can exceed 30 minutes.
        timeout-minutes: 40
        env:
          ADCP_PG_TEST_URL: postgresql://postgres@localhost:5432/adcp_production_test
        run: |
          # Explicit pytest paths bypass --ignore; preselect and reject empty globs.
          shopt -s nullglob
          source_tests=()
          for test in tests/conformance/reporting/test_reporting_production*.py; do
            case "$test" in
              *test_reporting_production_packaging.py|*test_reporting_production_rolling.py) continue ;;
            esac
            source_tests+=("$test")
          done
          projection_tests=(tests/conformance/reporting/test_reporting_projection*.py)
          if (( ${#source_tests[@]} == 0 || ${#projection_tests[@]} == 0 )); then
            echo "Production or projection test selection is empty"
            exit 1
          fi
          python scripts/reporting_test_harness.py pytest \
            "${source_tests[@]}" \
            "${projection_tests[@]}" \
            tests/conformance/reporting/test_reporting_tier_projection.py \
            tests/conformance/reporting/test_reporting_schedule_schema.py \
            tests/test_reporting_capability_models.py \
            tests/test_reporting_revision_ownership.py \
            tests/test_reporting_production_public.py \
            tests/test_schema_datetime_formats.py \
            tests/test_rc6_adoption.py \
            -v -s -ra | tee pg-reporting-production-evidence.log
      - name: Preserve production contract evidence
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: pg-reporting-production-evidence-${{ github.run_attempt }}
          retention-days: 7
          path: pg-reporting-production-evidence.log
          if-no-files-found: error

  pg-reporting-production-installed:
    needs: changes
    if: needs.changes.outputs.run_postgres == 'true'
    name: Installed production reporting (${{ matrix.cell }}, Python 3.10)
    runs-on: ubuntu-latest
    permissions:
      contents: read
    timeout-minutes: 50
    strategy:
      fail-fast: false
      matrix:
        cell: [base-vcs, base-sdist, pg-vcs, pg-sdist]
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_HOST_AUTH_METHOD: trust
          POSTGRES_DB: adcp_production_installed_test
        ports: ["5432:5432"]
        options: >-
          --health-cmd pg_isready --health-interval 5s
          --health-timeout 5s --health-retries 10
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        id: production-python310
        with:
          python-version: "3.10"
      - uses: actions/setup-python@v6
        with:
          python-version: "3.12"
      - name: Set up uv
        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
        with:
          version: "0.12.8"
          enable-cache: true
          cache-dependency-glob: pyproject.toml
          cache-suffix: "3.12"
          prune-cache: true

      - name: Install test dependencies
        run: uv pip install --system -e ".[dev,pg]" -e "./packages/adcp-reporting-storage[pg,gcs,s3,azure]"
      - name: Run installed source-equivalent production contract
        shell: bash
        timeout-minutes: 45
        env:
          ADCP_PG_TEST_URL: postgresql://postgres@localhost:5432/adcp_production_installed_test
          ADCP_PYTHON310: ${{ steps.production-python310.outputs.python-path }}
          ADCP_PRODUCTION_EVIDENCE: ${{ runner.temp }}/production-installed-evidence
          PRODUCTION_CELL: ${{ matrix.cell }}
        run: |
          python scripts/reporting_test_harness.py pytest \
            tests/conformance/reporting/test_reporting_production_packaging.py \
            -k "$PRODUCTION_CELL" -v -s -ra | tee pg-reporting-production-installed.log
      # Keep provenance and diagnostics; the wheel/sdist inputs are built and
      # verified above, but repeating them in every matrix upload dominates storage.
      - name: Preserve installed origins, original inner logs and exact asset hashes
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: pg-reporting-production-installed-${{ matrix.cell }}-${{ github.run_attempt }}
          retention-days: 7
          path: |
            pg-reporting-production-installed.log
            ${{ runner.temp }}/production-installed-evidence
            !${{ runner.temp }}/production-installed-evidence/**/*.whl
            !${{ runner.temp }}/production-installed-evidence/**/*.tar.gz
          if-no-files-found: error

  pg-reporting-production-compatibility:
    needs: changes
    if: needs.changes.outputs.run_postgres == 'true'
    name: Installed production ownership maintenance upgrade
    runs-on: ubuntu-latest
    permissions:
      contents: read
    timeout-minutes: 50
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_HOST_AUTH_METHOD: trust
          POSTGRES_DB: adcp_production_rolling_test
        ports: ["5432:5432"]
        options: >-
          --health-cmd pg_isready --health-interval 5s
          --health-timeout 5s --health-retries 10
    steps:
      - uses: actions/checkout@v6
      - name: Fetch integrated feed, hardening and production comparison artifacts
        timeout-minutes: 1
        run: git fetch --no-tags origin 2d777ace7b4bf8be519ce0abd4fd0a25ed4f1da7 e16eb8cf3074cabd45aab42840950f05ad6d2b43 34c8f6d929aeac3407e2f595104a8e903e572623
      - uses: actions/setup-python@v6
        id: production-python310
        with:
          python-version: "3.10"
      - uses: actions/setup-python@v6
        with:
          python-version: "3.12"
      - name: Set up uv
        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
        with:
          version: "0.12.8"
          enable-cache: true
          cache-dependency-glob: pyproject.toml
          cache-suffix: "3.12"
          prune-cache: true

      - name: Install test dependencies
        run: uv pip install --system -e ".[dev,pg]" -e "./packages/adcp-reporting-storage[pg,gcs,s3,azure]"
      - name: Require owned production admission and installed maintenance contracts
        shell: bash
        timeout-minutes: 42
        env:
          ADCP_PG_TEST_URL: postgresql://postgres@localhost:5432/adcp_production_rolling_test
          ADCP_PYTHON310: ${{ steps.production-python310.outputs.python-path }}
          ADCP_PRODUCTION_EVIDENCE: ${{ runner.temp }}/production-rolling-evidence
        run: |
          python scripts/reporting_test_harness.py pytest \
            tests/conformance/reporting/test_reporting_caller_ownership.py \
            tests/conformance/reporting/test_reporting_ownership_packaging.py \
            -v -s -ra | tee pg-reporting-production-rolling.log
      # Preserve continuity evidence without uploading another copy of each binary.
      - name: Preserve exact installed historical continuity and fence evidence
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: pg-reporting-production-rolling-${{ github.run_attempt }}
          retention-days: 7
          path: |
            pg-reporting-production-rolling.log
            ${{ runner.temp }}/production-rolling-evidence
            !${{ runner.temp }}/production-rolling-evidence/**/*.whl
            !${{ runner.temp }}/production-rolling-evidence/**/*.tar.gz
          if-no-files-found: error

  ipr-policy:
    name: IPR Policy / Signature
    runs-on: ubuntu-latest
    timeout-minutes: 10
    if: github.event_name == 'pull_request' || github.ref == 'refs/heads/main'
    permissions:
      contents: read
      pull-requests: read # Resolve the actual merged contributions and numeric PR author IDs.

    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
        with:
          ref: ${{ github.sha }}
          fetch-depth: 0
          persist-credentials: false
      # The existing PR/comment workflow records agreements. This job only
      # reads the canonical ledger and verifies the actual included PR authors.
      # Actions itself supplies the required App 15368 check-run provenance.
      - name: Verify contribution agreements for the exact source
        run: python3 -m scripts.check_main_policies ipr
        env:
          GH_TOKEN: ${{ github.token }}

  conventional-commits:
    name: Validate conventional commit format
    runs-on: ubuntu-latest
    timeout-minutes: 10
    if: github.event_name == 'pull_request' || github.ref == 'refs/heads/main'
    permissions:
      contents: read
      pull-requests: read # Read the current title/body when a check is rerun after an edit.

    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
        with:
          ref: ${{ github.sha }}
          fetch-depth: 0
          persist-credentials: false
      - name: Validate PR source or every integrated main commit and breaking footer
        run: python3 -m scripts.check_main_policies conventional
        env:
          GH_TOKEN: ${{ github.token }}

  downstream-imports:
    needs: changes
    if: needs.changes.outputs.run_packaging == 'true'
    name: Downstream import smoke (representative consumer symbols)
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - uses: actions/checkout@v6

      - name: Set up Python 3.11
        uses: actions/setup-python@v6
        with:
          python-version: "3.11"
          cache: pip
          cache-dependency-path: pyproject.toml

      - name: Build sdist and install its wheel
        run: |
          python -m pip install --upgrade pip build
          test ! -e src/adcp/_schemas
          # The default build path creates the sdist first, then builds the
          # wheel from that sdist. This covers both VCS and sdist consumers.
          python -m build --outdir dist/
          python scripts/ci/check_distribution_size.py dist/
          pip install dist/*.whl
          # The storage distribution is built from its own tree and must
          # install over the freshly built adcp wheel, never pull adcp from PyPI.
          python -m build --outdir dist-storage/ packages/adcp-reporting-storage
          pip install --no-deps dist-storage/*.whl

      - name: Verify prerelease dependency resolution imports server
        run: |
          python -m venv "$RUNNER_TEMP/adcp-prerelease-smoke"
          "$RUNNER_TEMP/adcp-prerelease-smoke/bin/python" -m pip install --pre dist/*.whl
          (
            cd "$RUNNER_TEMP"
            "$RUNNER_TEMP/adcp-prerelease-smoke/bin/python" -I -c 'import adcp.server; import httpx; assert hasattr(httpx, "AsyncClient")'
          )

      - name: Verify VCS-built wheel schemas
        working-directory: /tmp
        run: |
          python - <<'PY'
          import json
          from importlib.resources import files

          from adcp import get_adcp_spec_version
          from adcp.server.helpers import STANDARD_ERROR_CODES, adcp_error
          from adcp.types import ReportingCapabilities
          from adcp.types.versioned import make_versioned_base

          spec_version = get_adcp_spec_version()
          current_bundle = (
              spec_version
              if "-" in spec_version
              else ".".join(spec_version.split(".")[:2])
          )
          schema_root = files("adcp") / "_schemas"
          packaged_versions = {
              child.name
              for child in schema_root.iterdir()
              if child.is_dir()
          }
          # Ship released lines and the frozen 3.1.15 source snapshot offline.
          assert packaged_versions == {
              "3.0", "3.1", "3.1.15", current_bundle
          }
          error_schema = json.loads(
              (schema_root / current_bundle / "enums/error-code.json").read_text(encoding="utf-8")
          )
          # NOT_SUPPORTED is the SDK's explicit extension to the pinned vocabulary.
          assert set(STANDARD_ERROR_CODES) == {*error_schema["enum"], "NOT_SUPPORTED"}
          assert adcp_error("AUTH_MISSING", "x")["errors"][0]["recovery"] == "correctable"
          assert make_versioned_base("3.1", "ListCreativesRequest")
          assert ReportingCapabilities.__name__ == "ReportingCapabilities"
          PY

      # Proxy for real downstream import sites (salesagent, creative agents,
      # signals agents). Any ImportError here means we broke the public API
      # surface without a migration pointer — failing CI is the goal.
      - name: Import representative public-API symbols
        run: |
          python - <<'PY'
          from adcp import (
              ADCPClient,
              AgentConfig,
              BrandReference,
              CpmPricingOption,
              CreateMediaBuyRequest,
              Error,
              GetProductsRequest,
              ListCreativesRequest,
              MediaBuyStatus,
              Package,
              PackageRequest,
              PublisherPropertiesAll,
              SyncCatalogsRequest,
          )
          from adcp.types import (
              AudioFormatAsset,
              BriefFormatAsset,
              CatalogFormatAsset,
              ContextObject,
              CreativeAsset,
              CssFormatAsset,
              DaastFormatAsset,
              HtmlFormatAsset,
              ImageFormatAsset,
              JavascriptFormatAsset,
              MarkdownFormatAsset,
              RepeatableAssetGroup,
              TargetingOverlay,
              TextFormatAsset,
              UrlFormatAsset,
              VastFormatAsset,
              VideoFormatAsset,
              WebhookFormatAsset,
          )

          # Removed-type shims: old import paths must raise a guided
          # ImportError pointing at the migration guide.
          import adcp
          for name in ("BrandManifest", "FormatCategory", "DeliverTo"):
              try:
                  getattr(adcp, name)
              except ImportError as exc:
                  assert "MIGRATION_v3_to_v4" in str(exc), (
                      f"{name} deprecation shim dropped migration pointer: {exc}"
                  )
              else:
                  raise AssertionError(
                      f"{name} import should raise ImportError with migration pointer"
                  )

          # The deep submodule path (some older import sites reach this far)
          # must also surface the migration pointer, not a bare ModuleNotFoundError.
          try:
              from adcp.types.domains.enums.format_category import FormatCategory  # noqa: F401
          except ImportError as exc:
              assert "MIGRATION_v3_to_v4" in str(exc), exc
          else:
              raise AssertionError(
                  "format_category submodule should raise ImportError with migration pointer"
              )

          assert adcp.__version__ and adcp.__version__ != "3.12.0", (
              f"adcp.__version__={adcp.__version__!r} — expected real pkg metadata"
          )
          assert adcp.get_adcp_version(), "ADCP_VERSION file is empty"

          # The storage distribution's facade is lazy and its stores work without a driver installed.
          import sys
          import adcp_reporting_storage
          assert not [m for m in sys.modules if m.startswith("adcp_reporting_storage.")]
          from adcp_reporting_storage import PgReportingLedgerStore, ReportingRowStorageOptionsV1
          assert "adcp.reporting.ledger.pg" not in sys.modules, "the ledger store moved; adcp must not ship it"

          print(f"OK — adcp=={adcp.__version__}, spec={adcp.get_adcp_version()}, "
                f"adcp-reporting-storage=={adcp_reporting_storage.__version__}")
          PY

  schema-check:
    needs: changes
    if: needs.changes.outputs.run_tests == 'true'
    name: Validate schemas are up-to-date
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: "3.11"

      - name: Set up uv
        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
        with:
          version: "0.12.8"
          enable-cache: true
          cache-dependency-glob: pyproject.toml
          cache-suffix: "3.11"
          prune-cache: true

      - name: Install dependencies
        run: |
          uv pip install --system -e ".[dev]" -e "./packages/adcp-reporting-storage"

      # Blocking. Grades the COMMITTED generated tree against a regeneration
      # from the COMMITTED schemas, so it runs before the sync steps below
      # replace `schemas/cache/`. A hand edit to `src/adcp/types/domains/**`,
      # `_generated.py` or `_ergonomic.py` fails here; without this step the
      # "Generate models" step overwrites the edit before anything inspects it.
      # `generate_types.py --check` stages the regeneration in a temp tree and
      # leaves the checkout alone. It also grades every post-generation fix
      # against `scripts/post_generation_manifest.json`.
      #
      # `make validate-generated` is the same set of checks contributors run in
      # `make pre-push` and `make ci-local`; until now no CI job ran any of
      # them, including the versioned-stub check.
      - name: Validate committed generated code
        run: make validate-generated

      - name: Check ADCP version
        id: version-check
        run: |
          VERSION=$(cat src/adcp/ADCP_VERSION)
          echo "ADCP_VERSION=$VERSION"
          # Skip regeneration + drift check for pre-release tags (alpha/beta/rc)
          # and for `latest`, which is a moving dev snapshot — the committed
          # generated types are frozen against the bundle we last synced, and
          # CI's fresh sync against today's `latest.tgz` is expected to drift.
          if echo "$VERSION" | grep -qE '(alpha|beta|rc)' || [ "$VERSION" = "latest" ]; then
            echo "is_prerelease=true" >> $GITHUB_OUTPUT
            echo "Pre-release / latest version detected - will skip schema sync"
          else
            echo "is_prerelease=false" >> $GITHUB_OUTPUT
            echo "Stable version - will sync schemas from upstream"
          fi

      # Stable upstream tags ship Sigstore sidecars; sync_schemas.py
      # verifies the bundle via `cosign verify-blob` before extraction.
      # Installs cosign from the official sigstore/cosign-installer action.
      - name: Install cosign (for signature verification)
        if: steps.version-check.outputs.is_prerelease != 'true'
        uses: sigstore/cosign-installer@v3

      - name: Download latest schemas
        if: steps.version-check.outputs.is_prerelease != 'true'
        run: python scripts/sync_schemas.py

      - name: Fix schema references
        if: steps.version-check.outputs.is_prerelease != 'true'
        run: python scripts/fix_schema_refs.py

      - name: Bundle schemas into package
        if: steps.version-check.outputs.is_prerelease != 'true'
        run: python scripts/bundle_schemas.py

      - name: Generate models
        run: python scripts/generate_types.py

      - name: Validate generated code syntax
        run: |
          echo "Validating generated code can be parsed..."
          python -m py_compile src/adcp/types/_generated.py
          echo "✓ Syntax validation passed"

      - name: Validate generated code imports
        run: |
          echo "Validating generated code can be imported..."
          python -c "from adcp.types import _generated as generated; print(f'✓ Successfully imported {len(dir(generated))} symbols')"

      - name: Run code generation tests
        run: |
          echo "Running code generation test suite..."
          pytest tests/test_code_generation.py -v --tb=short

      - name: Check for schema drift
        if: steps.version-check.outputs.is_prerelease != 'true'
        run: |
          # This step compares the committed tree against a regeneration from
          # schemas freshly synced from upstream, so a diff here reports
          # UPSTREAM movement, not a stale commit. Staleness is graded by the
          # blocking "Validate committed generated code" step above, which runs
          # before the sync.
          #
          # Advisory, for two reasons:
          #   * upstream publishing a schema would otherwise turn every
          #     unrelated PR red;
          #   * datamodel-code-generator walks its input as
          #     ``sorted(path.rglob("*"), key=lambda p: p.name)``. Every pair
          #     of same-basename inputs ties (316 of 1169 inputs share a
          #     basename) and resolves in readdir order, which differs between
          #     APFS and ext4. Flipping every tie renumbers anonymous variant
          #     classes (Result9 -> Result13) in protocol/get_principal_response,
          #     protocol/sync_principal_response, both
          #     get_adcp_capabilities_response modules and _generated.py — 5
          #     files, measured. The semantic aliases in
          #     ``src/adcp/types/aliases.py`` re-point correctly, so the names
          #     adopters import are stable across the flip.
          #
          # The blocking step above shares that exposure: it is sound as long as
          # the generator's input order is total. Feeding the generator an
          # explicit file list, or sorting its walk by full path rather than
          # basename, closes it.
          if git diff --quiet src/adcp/types/_generated.py schemas/cache/; then
            echo "✓ Schemas are up-to-date (no diff)"
          else
            echo "ℹ Upstream schemas have moved since the last sync, or the"
            echo "  anonymous variant numbering shifted with the filesystem."
            echo "  Run: make regenerate-schemas — then commit the result."
            git diff --stat src/adcp/types/_generated.py schemas/cache/
          fi

  storyboard:
    needs: changes
    if: needs.changes.outputs.run_storyboards == 'true'
    name: AdCP storyboard runner — examples/seller_agent.py (@adcp/sdk ${{ matrix.adcp-sdk-tag }})
    runs-on: ubuntu-latest
    timeout-minutes: 20
    # Both the current 3.2.1 runner and the sticky 3.0 compatibility floor
    # must pass before the aggregate required check succeeds.
    strategy:
      fail-fast: false
      matrix:
        adcp-sdk-tag: ["adcp-3.0", "14.0.0"]

    steps:
      - uses: actions/checkout@v6

      - name: Set up Python 3.12
        uses: actions/setup-python@v6
        with:
          python-version: "3.12"
          cache: pip
          cache-dependency-path: pyproject.toml

      - name: Set up Node 22
        uses: actions/setup-node@v6
        with:
          node-version: "22"

      # Cache the npm tarball + extracted package directory so the
      # storyboard runner install isn't a cold network fetch every run.
      # The cache key is salted by the npm dist-tag; npm still resolves
      # the current concrete package for that tag on install.
      - name: Cache ~/.npm
        uses: actions/cache@v5
        with:
          path: ~/.npm
          key: ${{ runner.os }}-npm-adcp-sdk-${{ matrix.adcp-sdk-tag }}
          restore-keys: |
            ${{ runner.os }}-npm-

      - name: Run reference seller storyboard harness
        timeout-minutes: 15
        env:
          PYTHON: python
          ADCP_SDK_VERSION: ${{ matrix.adcp-sdk-tag }}
          STORYBOARD_RESULT_PATH: storyboard-result-${{ matrix.adcp-sdk-tag }}.json
        run: |
          scripts/ci/run_storyboard_reference_seller.sh

      - if: always()
        uses: actions/upload-artifact@v7
        with:
          name: storyboard-result-${{ matrix.adcp-sdk-tag }}-${{ github.run_attempt }}
          retention-days: 7
          path: storyboard-result-${{ matrix.adcp-sdk-tag }}.json
          if-no-files-found: warn

  storyboard-required-gate:
    name: AdCP storyboard runner — examples/seller_agent.py
    runs-on: ubuntu-latest
    timeout-minutes: 5
    needs: [changes, storyboard]
    # Run after a failed matrix so the aggregate required check fails, but
    # do not keep superseded workflow runs alive after concurrency cancels them.
    if: ${{ !cancelled() }}
    steps:
      - name: Require all reference seller storyboard matrix runs
        env:
          CI_NEEDS: ${{ toJSON(needs) }}
        run: |
          python3 - <<'PY'
          import json, os
          needs = json.loads(os.environ["CI_NEEDS"])
          scope = needs.pop("changes")
          expected = json.loads(scope.get("outputs", {}).get("expected_results", "{}"))
          if scope["result"] != "success" or not isinstance(expected, dict) or not expected:
              raise SystemExit("CI scope could not be verified")
          bad = {
              name: job["result"] for name, job in needs.items()
              if expected.get(name) not in ("success", "skipped") or job["result"] != expected[name]
          }
          if not needs or bad:
              raise SystemExit("Required CI lanes did not complete as expected: " + json.dumps(bad))
          print("All required lanes completed according to the verified CI scope")
          PY

  reporting-installed-artifact-matrix:
    needs: changes
    if: needs.changes.outputs.run_packaging == 'true'
    name: Reliable reporting installed artifacts — positive 2x2
    runs-on: ubuntu-latest
    timeout-minutes: 20
    permissions:
      contents: read
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_HOST_AUTH_METHOD: trust
          POSTGRES_DB: postgres
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 5s
          --health-timeout 5s
          --health-retries 10
    steps:
      - uses: actions/checkout@v6

      - name: Set up Python 3.10
        uses: actions/setup-python@v6
        with:
          python-version: "3.10"

      - name: Set up Node 22.12.0
        uses: actions/setup-node@v6
        with:
          node-version: "22.12.0"

      - name: Materialize exact installed artifact inputs
        shell: bash
        run: |
          set -euo pipefail
          INPUT_ROOT="${RUNNER_TEMP}/reporting-1199-inputs"
          mkdir -p "${INPUT_ROOT}/python" "${INPUT_ROOT}/ts-stable" "${INPUT_ROOT}/ts-candidate"

          curl --fail --silent --show-error --location --retry 4 --retry-delay 5 \
            --retry-connrefused --connect-timeout 15 --max-time 180 \
            https://files.pythonhosted.org/packages/97/07/74355b24ace6d7618cd330cc970a0ba24f82673e5e1e1e7767d153f73989/adcp-8.0.0b16-py3-none-any.whl \
            --output "${INPUT_ROOT}/python/adcp-8.0.0b16-py3-none-any.whl"
          curl --fail --silent --show-error --location --retry 4 --retry-delay 5 \
            --retry-connrefused --connect-timeout 15 --max-time 180 \
            https://files.pythonhosted.org/packages/6a/a9/85b61269bceefb5705a21ce87789f8d7869796a02ceb67f54268d444c36d/adcp-8.0.0rc3-py3-none-any.whl \
            --output "${INPUT_ROOT}/python/adcp-8.0.0rc3-py3-none-any.whl"
          echo "7589a546cacdddce3a7a827adaa11d4ccab34768c558689b1c6850b85cd098b1  ${INPUT_ROOT}/python/adcp-8.0.0b16-py3-none-any.whl" | sha256sum --check
          echo "c2378f3f3a9041512690c177d160174a936a86c7eea55474b618256abcc14370  ${INPUT_ROOT}/python/adcp-8.0.0rc3-py3-none-any.whl" | sha256sum --check
          python -m venv "${INPUT_ROOT}/python/stable"
          python -m venv "${INPUT_ROOT}/python/candidate"
          "${INPUT_ROOT}/python/stable/bin/pip" install --retries 5 --timeout 30 \
            "${INPUT_ROOT}/python/adcp-8.0.0b16-py3-none-any.whl[pg]" pytest==9.0.2
          "${INPUT_ROOT}/python/candidate/bin/pip" install --retries 5 --timeout 30 \
            "${INPUT_ROOT}/python/adcp-8.0.0rc3-py3-none-any.whl[pg]" pytest==9.0.2

          cp scripts/ci/reporting_interop/npm/rc47/package.json \
            scripts/ci/reporting_interop/npm/rc47/package-lock.json "${INPUT_ROOT}/ts-stable/"
          cp scripts/ci/reporting_interop/npm/rc48/package.json \
            scripts/ci/reporting_interop/npm/rc48/package-lock.json "${INPUT_ROOT}/ts-candidate/"
          curl --fail --silent --show-error --location --retry 4 --retry-delay 5 \
            --retry-connrefused --connect-timeout 15 --max-time 180 \
            https://registry.npmjs.org/@adcp/sdk/-/sdk-14.0.0-rc.47.tgz \
            --output "${INPUT_ROOT}/ts-stable/sdk-14.0.0-rc.47.tgz"
          curl --fail --silent --show-error --location --retry 4 --retry-delay 5 \
            --retry-connrefused --connect-timeout 15 --max-time 180 \
            https://registry.npmjs.org/@adcp/sdk/-/sdk-14.0.0-rc.48.tgz \
            --output "${INPUT_ROOT}/ts-candidate/sdk-14.0.0-rc.48.tgz"
          echo "1b14aeddab973809f1850e189f833ef645d061e25c82d74046c97fd92d346e49  ${INPUT_ROOT}/ts-stable/sdk-14.0.0-rc.47.tgz" | sha256sum --check
          echo "420c1fa36128f3c3285234f58096a74c5668b74ffbf12804d6603c370083149b  ${INPUT_ROOT}/ts-candidate/sdk-14.0.0-rc.48.tgz" | sha256sum --check
          npm ci --prefix "${INPUT_ROOT}/ts-stable" --ignore-scripts --no-audit --no-fund \
            --fetch-retries=5 --fetch-retry-mintimeout=5000 --fetch-retry-maxtimeout=30000
          npm ci --prefix "${INPUT_ROOT}/ts-candidate" --ignore-scripts --no-audit --no-fund \
            --fetch-retries=5 --fetch-retry-mintimeout=5000 --fetch-retry-maxtimeout=30000

      - name: Run installed Python seller x TypeScript client positive 2x2
        shell: bash
        run: |
          set -euo pipefail
          INPUT_ROOT="${RUNNER_TEMP}/reporting-1199-inputs"
          "${INPUT_ROOT}/python/candidate/bin/python" -I \
            scripts/ci/reporting_interop/run_installed_artifact_matrix.py \
            --python-stable-runtime "${INPUT_ROOT}/python/stable/bin/python" \
            --python-stable-artifact "${INPUT_ROOT}/python/adcp-8.0.0b16-py3-none-any.whl" \
            --python-candidate-runtime "${INPUT_ROOT}/python/candidate/bin/python" \
            --python-candidate-artifact "${INPUT_ROOT}/python/adcp-8.0.0rc3-py3-none-any.whl" \
            --typescript-stable-install "${INPUT_ROOT}/ts-stable" \
            --typescript-stable-archive "${INPUT_ROOT}/ts-stable/sdk-14.0.0-rc.47.tgz" \
            --typescript-candidate-install "${INPUT_ROOT}/ts-candidate" \
            --typescript-candidate-archive "${INPUT_ROOT}/ts-candidate/sdk-14.0.0-rc.48.tgz" \
            --node-runtime "$(command -v node)" \
            --pg-admin-url postgresql://postgres@127.0.0.1:5432/postgres \
            --output "${RUNNER_TEMP}/reporting-installed-artifact-matrix"

      - name: Run installed full reporting lifecycle 2x2
        shell: bash
        run: |
          set -euo pipefail
          INPUT_ROOT="${RUNNER_TEMP}/reporting-1199-inputs"
          "${INPUT_ROOT}/python/candidate/bin/python" -I \
            scripts/ci/reporting_interop/run_full_installed_artifact_matrix.py \
            --python-stable-runtime "${INPUT_ROOT}/python/stable/bin/python" \
            --python-stable-artifact "${INPUT_ROOT}/python/adcp-8.0.0b16-py3-none-any.whl" \
            --python-candidate-runtime "${INPUT_ROOT}/python/candidate/bin/python" \
            --python-candidate-artifact "${INPUT_ROOT}/python/adcp-8.0.0rc3-py3-none-any.whl" \
            --typescript-stable-install "${INPUT_ROOT}/ts-stable" \
            --typescript-stable-archive "${INPUT_ROOT}/ts-stable/sdk-14.0.0-rc.47.tgz" \
            --typescript-candidate-install "${INPUT_ROOT}/ts-candidate" \
            --typescript-candidate-archive "${INPUT_ROOT}/ts-candidate/sdk-14.0.0-rc.48.tgz" \
            --node-runtime "$(command -v node)" \
            --pg-admin-url postgresql://postgres@127.0.0.1:5432/postgres \
            --output "${RUNNER_TEMP}/reporting-full-installed-artifact-matrix"

      - if: always()
        uses: actions/upload-artifact@v7
        with:
          name: reporting-installed-artifact-matrix-${{ github.run_attempt }}
          retention-days: 7
          path: |
            ${{ runner.temp }}/reporting-installed-artifact-matrix
            ${{ runner.temp }}/reporting-full-installed-artifact-matrix
          if-no-files-found: warn

  reporting-installed-artifact-required-gate:
    name: Reliable reporting installed-artifact 2x2
    runs-on: ubuntu-latest
    timeout-minutes: 5
    permissions: {}
    needs: [changes, reporting-installed-artifact-matrix]
    if: ${{ !cancelled() }}
    steps:
      - name: Require the installed artifact positive 2x2
        env:
          CI_NEEDS: ${{ toJSON(needs) }}
        run: |
          python3 - <<'PY'
          import json, os
          needs = json.loads(os.environ["CI_NEEDS"])
          scope = needs.pop("changes")
          expected = json.loads(scope.get("outputs", {}).get("expected_results", "{}"))
          if scope["result"] != "success" or not isinstance(expected, dict) or not expected:
              raise SystemExit("CI scope could not be verified")
          bad = {
              name: job["result"] for name, job in needs.items()
              if expected.get(name) not in ("success", "skipped") or job["result"] != expected[name]
          }
          if not needs or bad:
              raise SystemExit("Required CI lanes did not complete as expected: " + json.dumps(bad))
          print("All required lanes completed according to the verified CI scope")
          PY

  v3-reference-seller-tests:
    needs: changes
    if: needs.changes.outputs.run_storyboards == 'true'
    name: v3 reference seller — pytest (respx-mocked upstream)
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - uses: actions/checkout@v6

      - name: Set up Python 3.12
        uses: actions/setup-python@v6
        with:
          python-version: "3.12"

      - name: Set up uv
        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
        with:
          version: "0.12.8"
          enable-cache: true
          cache-dependency-glob: pyproject.toml
          cache-suffix: "3.12"
          prune-cache: true

      - name: Install dependencies
        run: |
          uv pip install --system -e ".[dev,pg]" -e "./packages/adcp-reporting-storage[pg,gcs,s3,azure]"
          # Example-local deps: the v3 reference seller imports
          # sqlalchemy + asyncpg + httpx-respx but those aren't in the
          # SDK's [dev] extras. Install them inline rather than adding
          # a separate optional-dependencies group for a single example.
          pip install "sqlalchemy[asyncio]>=2.0" "asyncpg>=0.29" "respx>=0.20"

      - name: Run translator-pattern tests
        # The tests respx-mock the JS mock-server upstream so we don't
        # need to boot Node here. Storyboard CI (below) covers the
        # real boot-the-upstream path.
        run: |
          pytest examples/v3_reference_seller/tests/ -v

  storyboard-v3-reference-seller:
    needs: changes
    if: needs.changes.outputs.run_storyboards == 'true'
    name: "AdCP storyboard runner — v3 reference seller (translator)"
    runs-on: ubuntu-latest
    timeout-minutes: 20
    env:
      # Intentionally non-secret: gates loopback-only debug counters
      # inside this CI job.
      ADCP_DEBUG_TOKEN: storyboard-debug-token
    # Required as of @adcp/sdk@6.7.0 (sales-guaranteed mock-server
    # canonicalized; closes #449). Storyboard run + traffic-counter
    # assertions gate every PR's translator-pattern conformance.
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_HOST_AUTH_METHOD: trust
          POSTGRES_DB: adcp
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 5s
          --health-timeout 5s
          --health-retries 10

    steps:
      - uses: actions/checkout@v6

      - name: Set up Python 3.12
        uses: actions/setup-python@v6
        with:
          python-version: "3.12"

      - name: Set up Node 22
        uses: actions/setup-node@v6
        with:
          node-version: "22"

      # Same cache pattern as the storyboard job: keyed by
      # ADCP_SDK_VERSION so a bump invalidates deterministically.
      - name: Cache ~/.npm
        uses: actions/cache@v5
        with:
          path: ~/.npm
          key: ${{ runner.os }}-npm-adcp-sdk-${{ env.ADCP_SDK_VERSION }}
          restore-keys: |
            ${{ runner.os }}-npm-

      - name: Set up uv
        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
        with:
          version: "0.12.8"
          enable-cache: true
          cache-dependency-glob: pyproject.toml
          cache-suffix: "3.12"
          prune-cache: true

      - name: Install dependencies
        run: |
          uv pip install --system -e ".[dev,pg]" -e "./packages/adcp-reporting-storage[pg,gcs,s3,azure]"
          # Example-local deps: the v3 reference seller imports
          # sqlalchemy + asyncpg (async Postgres driver) which aren't
          # in the SDK's [dev,pg] extras. Install inline rather than
          # adding an example-only optional-dependencies group.
          pip install "sqlalchemy[asyncio]>=2.0" "asyncpg>=0.29" "respx>=0.20"

      - name: Pre-install @adcp/sdk (once, then call binary directly)
        # See the comment on the storyboard job's install step for the
        # AAO reference-formats fixture rationale (upstream adcp#3307).
        run: |
          npm install -g @adcp/sdk@${ADCP_SDK_VERSION}
          adcp --version
          SDK_ROOT="$(npm root -g)/@adcp/sdk"
          mkdir -p "${SDK_ROOT}/test/lib/v2-projection-fixtures"
          cp tests/fixtures/aao-reference-formats.json "${SDK_ROOT}/test/lib/v2-projection-fixtures/aao-reference-formats.json"
          mkdir -p "${SDK_ROOT}/schemas/cache/3.1.0-beta.2/registries"
          cp tests/fixtures/v1-canonical-mapping.json "${SDK_ROOT}/schemas/cache/3.1.0-beta.2/registries/v1-canonical-mapping.json"
          python scripts/ci/prepare_storyboard_sdk.py "${SDK_ROOT}"

      - name: Start JS mock-server upstream
        run: |
          # Cached install above means this is a hot-start (~2-3s on
          # GHA-hosted runners) — no npm install delay. Tee output to
          # /tmp/mock-server.log so failures surface their stack traces
          # (otherwise the readiness loop just times out silently).
          adcp mock-server sales-guaranteed --port 4503 --api-key test-key \
            > /tmp/mock-server.log 2>&1 &
          MOCK_PID=$!
          echo "MOCK_PID=$MOCK_PID" >> "$GITHUB_ENV"
          # Health-check via /_debug/traffic — non-network-scoped and
          # no-auth, so it doesn't break when the JS mock's seed-data
          # renames or removes a specific network. The endpoint is
          # always present on the harness-side mock.
          for i in $(seq 1 120); do
            # ``||`` runs on the assignment so curl's "000" stdout and the
            # fallback don't concatenate when the connection is refused.
            HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --max-time 1 \
              http://127.0.0.1:4503/_debug/traffic 2>/dev/null) || HTTP_CODE="000"
            if [ "$HTTP_CODE" = "200" ]; then
              echo "Upstream mock ready (HTTP 200, pid $MOCK_PID, $i polls)"
              break
            fi
            if [ "$i" -eq 120 ]; then
              echo "Upstream mock failed to start within 60s"
              echo "--- mock-server.log ---"
              cat /tmp/mock-server.log || echo "(log unavailable)"
              kill "$MOCK_PID" 2>/dev/null || true
              exit 1
            fi
            sleep 0.5
          done

      - name: Seed Postgres fixtures
        env:
          DATABASE_URL: postgresql+asyncpg://postgres@127.0.0.1:5432/adcp
        run: |
          cd examples/v3_reference_seller
          python -m seed

      - name: Boot v3 reference seller (translator)
        env:
          DATABASE_URL: postgresql+asyncpg://postgres@127.0.0.1:5432/adcp
          MOCK_AD_SERVER_URL: http://127.0.0.1:4503
          MOCK_AD_SERVER_API_KEY: test-key
          PORT: "3001"
          ADCP_REFERENCE_TEST_CONTROLLER: "1"
        run: |
          cd examples/v3_reference_seller
          python -m src.app > /tmp/v3-reference-seller.log 2>&1 &
          SELLER_PID=$!
          echo "SELLER_PID=$SELLER_PID" >> "$GITHUB_ENV"
          for i in $(seq 1 120); do
            # ``||`` runs on the assignment so curl's "000" stdout and the
            # fallback don't concatenate when the connection is refused.
            HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --max-time 1 \
              http://127.0.0.1:3001/mcp 2>/dev/null) || HTTP_CODE="000"
            if [ "$HTTP_CODE" != "000" ]; then
              echo "Seller ready (HTTP ${HTTP_CODE}, pid ${SELLER_PID})"
              break
            fi
            if [ "$i" -eq 120 ]; then
              echo "Seller failed to start within 60s"
              echo "--- v3-reference-seller.log ---"
              cat /tmp/v3-reference-seller.log || echo "(log unavailable)"
              kill "$SELLER_PID" 2>/dev/null || true
              exit 1
            fi
            sleep 0.5
          done
          # Upstream-still-alive probe — guard against the upstream
          # dying during seller startup (e.g. seller's connection
          # handshake crashes the mock). If the upstream is gone,
          # the storyboard run will fail in confusing ways; fail
          # here with a clear diagnostic instead.
          UPSTREAM_CODE=$(curl -s -o /dev/null -w "%{http_code}" --max-time 2 \
            -H "Authorization: Bearer test-key" \
            -H "X-Network-Code: net_premium_us" \
            http://127.0.0.1:4503/v1/products 2>/dev/null || echo "000")
          if [ "$UPSTREAM_CODE" != "200" ]; then
            echo "Upstream mock no longer responding after seller boot (HTTP ${UPSTREAM_CODE})"
            echo "The seller likely crashed the upstream during connection handshake."
            kill "$SELLER_PID" 2>/dev/null || true
            kill "$MOCK_PID" 2>/dev/null || true
            exit 1
          fi
          echo "Upstream still alive after seller boot (HTTP ${UPSTREAM_CODE})"

      - name: Run storyboard suite
        timeout-minutes: 5
        run: |
          # /etc/hosts override so the buyer can reach acme.localhost
          # (the seeded tenant subdomain).
          echo "127.0.0.1 acme.localhost" | sudo tee -a /etc/hosts
          cd examples/v3_reference_seller
          # ``adcp`` was installed once at job start — call the binary
          # directly to skip per-invocation ``npx`` extract+link.
          # --auth carries the seeded bearer credential (seed.py:74) so the
          # storyboard runner's requests resolve through the v3 ref seller's
          # PgBuyerAgentRegistry to ba_acme_bearer. Without this, every
          # request hits the Tier 2 commercial-allowlist gate and storyboard
          # steps fail with PERMISSION_DENIED across the board.
          adcp storyboard run \
            http://acme.localhost:3001/mcp media_buy_seller \
            --auth dev-bearer-token-acme-1 \
            --test-kit ../../tests/fixtures/storyboard-test-kit.yaml \
            --json --allow-http \
            > v3-storyboard-result.json

      - name: Assert storyboard runner produced output
        run: |
          # Hard gate: the runner must produce a non-empty result file.
          # The anti-façade invariant is enforced separately below: the
          # translator must call its real upstream as well as pass the suite.
          python -c "
          import json, sys, pathlib
          p = pathlib.Path('examples/v3_reference_seller/v3-storyboard-result.json')
          if not p.exists() or p.stat().st_size == 0:
              print('v3-storyboard-result.json missing or empty — runner produced no output')
              sys.exit(1)
          with p.open() as f:
              d = json.load(f)
          print('overall_status:', d.get('overall_status'))
          print('controller_detected:', d.get('controller_detected'))
          print('summary:', json.dumps(d.get('summary', {}), indent=2))
          "

      - name: Assert storyboard passed
        # The controller seeds only real SQL accounts and a scoped rejection
        # directive. Upstream-owned fixture types remain explicitly unsupported.
        # No failed step, missing tool, or failed prerequisite is accepted.
        run: |
          python -c "
          import json, sys, pathlib
          p = pathlib.Path('examples/v3_reference_seller/v3-storyboard-result.json')
          with p.open() as f:
              d = json.load(f)
          summary = d.get('summary') or {}
          skip_counts = summary.get('skipped_by_reason') or {}
          steps = [
              step for track in d.get('tracks', [])
              for scenario in track.get('scenarios', [])
              for step in scenario.get('steps', [])
          ]
          accepted = (
              d.get('overall_status') == 'passing'
              and d.get('controller_detected') is True
              and set(d.get('controller_scenarios') or []) == {'seed_account', 'force_get_products_arm'}
              and summary.get('steps_failed') == 0
              and summary.get('tracks_failed') == 0
              and (summary.get('steps_passed') or 0) > 0
              and set(skip_counts) <= {'not_applicable'}
              and not any(step.get('skip_reason') in {'missing_tool', 'prerequisite_failed'} for step in steps)
          )
          if not accepted:
              print(json.dumps(d, indent=2))
              sys.exit(1)
          print(f'Storyboard passing: summary={summary}')
          "

      - name: Assert upstream traffic (anti-façade gate)
        run: |
          # The v3 reference seller exposes /_debug/traffic with per-method
          # upstream-call counts. If the storyboard passed but the counts
          # are empty/zero, the seller served stub data without translating
          # to upstream — the façade-mode failure this job exists to catch
          # (see #410).
          curl -sf -H "X-Debug-Token: ${ADCP_DEBUG_TOKEN}" \
            http://127.0.0.1:3001/_debug/traffic > traffic.json
          python -c "
          import json, sys
          with open('traffic.json') as f:
              counts = json.load(f)
          if not counts:
              print('Empty traffic snapshot — seller invoked no upstream methods.')
              print('This is the façade-mode failure #410 gates against.')
              sys.exit(1)
          total = sum(counts.values())
          if total == 0:
              print(f'All upstream-method counts zero: {counts!r}')
              print('Seller served stub data without calling upstream — façade failure.')
              sys.exit(1)
          print(f'Upstream traffic: total={total} per-method={counts!r}')
          "

      - if: always()
        uses: actions/upload-artifact@v7
        with:
          name: v3-storyboard-result-${{ github.run_attempt }}
          retention-days: 7
          path: examples/v3_reference_seller/v3-storyboard-result.json
          if-no-files-found: warn

  storyboard-multi-platform-seller:
    needs: changes
    if: needs.changes.outputs.run_storyboards == 'true'
    name: "AdCP storyboard runner — examples/multi_platform_seller (PlatformRouter)"
    runs-on: ubuntu-latest
    timeout-minutes: 20
    # Multi-tenant proof: one process, two tenants, one router. Each
    # tenant's storyboard runs against its own subdomain
    # (tenant-a.localhost / tenant-b.localhost). Blocking gate — both
    # tenants must pass the AdCP storyboard suite for the example to
    # remain a credible reference. continue-on-error was dropped after
    # the mocks were aligned with the wire contract; future drift now
    # blocks CI.
    steps:
      - uses: actions/checkout@v6

      - name: Set up Python 3.12
        uses: actions/setup-python@v6
        with:
          python-version: "3.12"

      - name: Set up Node 22
        uses: actions/setup-node@v6
        with:
          node-version: "22"

      - name: Cache ~/.npm
        uses: actions/cache@v5
        with:
          path: ~/.npm
          key: ${{ runner.os }}-npm-adcp-sdk-${{ env.ADCP_SDK_VERSION }}
          restore-keys: |
            ${{ runner.os }}-npm-

      - name: Pre-install @adcp/sdk
        # See the comment on the storyboard job's install step for the
        # AAO reference-formats fixture rationale (upstream adcp#3307).
        run: |
          npm install -g @adcp/sdk@${ADCP_SDK_VERSION}
          adcp --version
          SDK_ROOT="$(npm root -g)/@adcp/sdk"
          mkdir -p "${SDK_ROOT}/test/lib/v2-projection-fixtures"
          cp tests/fixtures/aao-reference-formats.json "${SDK_ROOT}/test/lib/v2-projection-fixtures/aao-reference-formats.json"
          mkdir -p "${SDK_ROOT}/schemas/cache/3.1.0-beta.2/registries"
          cp tests/fixtures/v1-canonical-mapping.json "${SDK_ROOT}/schemas/cache/3.1.0-beta.2/registries/v1-canonical-mapping.json"
          python scripts/ci/prepare_storyboard_sdk.py "${SDK_ROOT}"

      - name: Set up uv
        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
        with:
          version: "0.12.8"
          enable-cache: true
          cache-dependency-glob: pyproject.toml
          cache-suffix: "3.12"
          prune-cache: true

      - name: Install dependencies
        run: |
          uv pip install --system -e ".[dev]" -e "./packages/adcp-reporting-storage"

      - name: Map tenant subdomains to localhost
        run: |
          # The storyboard runner connects to ``tenant-x.localhost`` —
          # /etc/hosts gives those names a 127.0.0.1 mapping so the
          # subdomain middleware on the seller process resolves the
          # right tenant from the Host header.
          echo "127.0.0.1 tenant-a.localhost tenant-b.localhost" \
            | sudo tee -a /etc/hosts

      - name: Boot multi-platform seller
        run: |
          ADCP_PORT=3001 python -m examples.multi_platform_seller.src.app &
          SELLER_PID=$!
          echo "SELLER_PID=$SELLER_PID" >> "$GITHUB_ENV"
          for i in $(seq 1 60); do
            HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --max-time 1 \
              http://127.0.0.1:3001/mcp 2>/dev/null) || HTTP_CODE="000"
            if [ "$HTTP_CODE" != "000" ]; then
              echo "Seller ready (HTTP ${HTTP_CODE}, pid ${SELLER_PID})"
              break
            fi
            if ! kill -0 "$SELLER_PID" 2>/dev/null; then
              echo "Seller process died during startup"
              exit 1
            fi
            if [ "$i" -eq 60 ]; then
              echo "Seller failed to start within 30s"
              kill "$SELLER_PID" 2>/dev/null || true
              exit 1
            fi
            sleep 0.5
          done

      - name: Run storyboard — tenant-a (sales-guaranteed)
        timeout-minutes: 5
        run: |
          adcp storyboard run \
            http://tenant-a.localhost:3001/mcp media_buy_seller \
            --json --allow-http \
            > tenant-a-storyboard.json
          head -50 tenant-a-storyboard.json

      - name: Run storyboard — tenant-b (sales-non-guaranteed)
        timeout-minutes: 5
        run: |
          adcp storyboard run \
            http://tenant-b.localhost:3001/mcp media_buy_seller \
            --json --allow-http \
            > tenant-b-storyboard.json
          head -50 tenant-b-storyboard.json

      - name: Require both tenant storyboards to pass
        run: |
          python - <<'PY'
          import json
          from pathlib import Path
          for tenant in ('a', 'b'):
              result = json.loads(Path(f'tenant-{tenant}-storyboard.json').read_text())
              summary = result.get('summary') or {}
              assert result.get('overall_status') == 'passing', result
              assert result.get('controller_detected') is True, result
              assert summary.get('steps_failed') == 0, summary
              assert summary.get('tracks_failed') == 0, summary
              assert (summary.get('steps_passed') or 0) > 0, summary
              assert set(summary.get('skipped_by_reason') or {}) <= {'not_applicable'}, summary
          PY

      - if: always()
        uses: actions/upload-artifact@v7
        with:
          name: multi-platform-storyboards-${{ github.run_attempt }}
          retention-days: 7
          path: |
            tenant-a-storyboard.json
            tenant-b-storyboard.json
          if-no-files-found: warn

  storyboard-sales-proposal-mode:
    needs: changes
    if: needs.changes.outputs.run_storyboards == 'true'
    name: "AdCP storyboard runner — sales-proposal-mode (proposal_finalize)"
    runs-on: ubuntu-latest
    timeout-minutes: 20
    # v1.5 ProposalManager finalize lifecycle proof. The mock seller
    # declares ``finalize=True`` + wires an ``InMemoryProposalStore``;
    # the framework's dispatch wiring intercepts ``refine[i].action='finalize'``
    # requests, runs ``finalize_proposal``, commits via the store, and
    # auto-hydrates ``ctx.recipes`` on subsequent ``create_media_buy``
    # calls. This job is the storyboard-level proof that the design
    # works end-to-end against the current runner.
    steps:
      - uses: actions/checkout@v6

      - name: Set up Python 3.12
        uses: actions/setup-python@v6
        with:
          python-version: "3.12"

      - name: Set up Node 22
        uses: actions/setup-node@v6
        with:
          node-version: "22"

      - name: Cache ~/.npm
        uses: actions/cache@v5
        with:
          path: ~/.npm
          key: ${{ runner.os }}-npm-adcp-sdk-${{ env.ADCP_SDK_VERSION }}
          restore-keys: |
            ${{ runner.os }}-npm-

      - name: Pre-install @adcp/sdk
        # See the comment on the storyboard job's install step for the
        # AAO reference-formats fixture rationale (upstream adcp#3307).
        run: |
          npm install -g @adcp/sdk@${ADCP_SDK_VERSION}
          adcp --version
          SDK_ROOT="$(npm root -g)/@adcp/sdk"
          mkdir -p "${SDK_ROOT}/test/lib/v2-projection-fixtures"
          cp tests/fixtures/aao-reference-formats.json "${SDK_ROOT}/test/lib/v2-projection-fixtures/aao-reference-formats.json"
          mkdir -p "${SDK_ROOT}/schemas/cache/3.1.0-beta.2/registries"
          cp tests/fixtures/v1-canonical-mapping.json "${SDK_ROOT}/schemas/cache/3.1.0-beta.2/registries/v1-canonical-mapping.json"
          python scripts/ci/prepare_storyboard_sdk.py "${SDK_ROOT}"

      - name: Set up uv
        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
        with:
          version: "0.12.8"
          enable-cache: true
          cache-dependency-glob: pyproject.toml
          cache-suffix: "3.12"
          prune-cache: true

      - name: Install dependencies
        run: |
          uv pip install --system -e ".[dev]" -e "./packages/adcp-reporting-storage"

      - name: Boot sales-proposal-mode seller
        run: |
          ADCP_PORT=3003 python -m examples.sales_proposal_mode_seller.src.app &
          SELLER_PID=$!
          echo "SELLER_PID=$SELLER_PID" >> "$GITHUB_ENV"
          for i in $(seq 1 60); do
            HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --max-time 1 \
              http://127.0.0.1:3003/mcp 2>/dev/null) || HTTP_CODE="000"
            if [ "$HTTP_CODE" != "000" ]; then
              echo "Seller ready (HTTP ${HTTP_CODE}, pid ${SELLER_PID})"
              break
            fi
            if ! kill -0 "$SELLER_PID" 2>/dev/null; then
              echo "Seller process died during startup"
              exit 1
            fi
            if [ "$i" -eq 60 ]; then
              echo "Seller failed to start within 30s"
              kill "$SELLER_PID" 2>/dev/null || true
              exit 1
            fi
            sleep 0.5
          done

      - name: Run storyboard — proposal_finalize
        timeout-minutes: 5
        # Full proposal_finalize storyboard. With @adcp/sdk@6.10.0 the
        # runner's stateful-chain controller exercises every phase
        # (setup, brief, refine, finalize, accept) end-to-end against
        # the framework's intercept seam. Earlier SDK versions skipped
        # refine/finalize/accept due to a sync_accounts cascade gap
        # that 6.10.0 closed (adcp#4053, adcp-client#1146/#1545).
        run: |
          adcp storyboard run \
            http://127.0.0.1:3003/mcp media_buy_seller/proposal_finalize \
            --json --allow-http \
            > proposal-finalize-storyboard.json
          head -200 proposal-finalize-storyboard.json

      - name: Assert v1.5 dispatch path scenarios pass
        run: |
          python -c "
          import json, sys, pathlib
          p = pathlib.Path('proposal-finalize-storyboard.json')
          if not p.exists() or p.stat().st_size == 0:
              print('storyboard result missing or empty')
              sys.exit(1)
          with p.open() as f:
              d = json.load(f)
          # Every phase of the proposal_finalize storyboard must pass:
          # setup → brief_with_proposals → refine_proposal →
          # finalize_proposal → accept_proposal. Each exercises a
          # different framework seam — see the per-scenario hints
          # below for what's wired where.
          required_passing = {
              'media_buy_seller/proposal_finalize/setup',
              'media_buy_seller/proposal_finalize/brief_with_proposals',
              'media_buy_seller/proposal_finalize/refine_proposal',
              'media_buy_seller/proposal_finalize/finalize_proposal',
              'media_buy_seller/proposal_finalize/accept_proposal',
          }
          passed = set()
          for track in d.get('tracks', []) or []:
              for s in track.get('scenarios', []) or []:
                  if s.get('overall_passed'):
                      passed.add(s.get('scenario'))
          missing = required_passing - passed
          if missing:
              # Per-scenario likely-cause hints. A contributor breaks the
              # framework finalize wiring; CI tells them what to look at
              # rather than just naming a scenario.
              hints = {
                  'media_buy_seller/proposal_finalize/setup': (
                      'sync_accounts dispatch failed (or the runner stopped '
                      'applying the sole-stateful-step exemption). See '
                      'docs/proposals/proposal-manager-v15-design.md § D5.'
                  ),
                  'media_buy_seller/proposal_finalize/brief_with_proposals': (
                      'Manager.get_products + framework draft persistence '
                      'broke. Check maybe_persist_draft_after_get_products '
                      'in src/adcp/decisioning/proposal_dispatch.py. See '
                      'docs/proposals/proposal-manager-v15-design.md § D1.'
                  ),
                  'media_buy_seller/proposal_finalize/refine_proposal': (
                      'Refine iteration broke. Check refine_products on '
                      'examples/sales_proposal_mode_seller/src/proposal_manager.py '
                      'and the maybe_persist_draft_after_get_products '
                      'overwrite path. See § D1 (refine iteration).'
                  ),
                  'media_buy_seller/proposal_finalize/finalize_proposal': (
                      'Finalize interception broke. Check '
                      'maybe_intercept_finalize in proposal_dispatch.py + '
                      'manager.finalize_proposal in the example. The seam '
                      'must commit via store.commit before projecting. See § D2.'
                  ),
                  'media_buy_seller/proposal_finalize/accept_proposal': (
                      'create_media_buy(proposal_id=...) or '
                      'create_media_buy(packages=[...]) broke. Check '
                      'maybe_hydrate_recipes_for_create_media_buy + '
                      'mark_proposal_consumed in proposal_dispatch.py and '
                      'the platform.create_media_buy adapter. See § D3 + D7.'
                  ),
              }
              print('FAIL: required scenarios did not pass:')
              for s in sorted(missing):
                  hint = hints.get(s, 'no hint registered for this scenario')
                  print(f'  - {s}')
                  print(f'    likely cause: {hint}')
              print()
              print('--- raw storyboard result ---')
              print(json.dumps(d, indent=2))
              sys.exit(1)
          print('PASS: full proposal_finalize storyboard chain (5/5 phases)')
          "

      - if: always()
        uses: actions/upload-artifact@v7
        with:
          name: sales-proposal-mode-storyboard-${{ github.run_attempt }}
          retention-days: 7
          path: proposal-finalize-storyboard.json
          if-no-files-found: warn