ci.yml

name: CI

on:
  workflow_dispatch:
  merge_group:
    types: [checks_requested]
  pull_request:
    branches: [master]
    types: [opened, synchronize, reopened, ready_for_review]
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name != 'push' }}
jobs:
  filter:
    if: github.event_name != 'pull_request' || github.event.pull_request.draft != true
    runs-on: ubuntu-latest
    outputs:
      should-run: ${{ steps.filter.outputs.should-run }}
    steps:
      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
        with:
          fetch-depth: "2"
      - name: Diff changed files
        id: diff
        env:
          BASE_REF: ${{ github.base_ref }}
        run: |
          # This step prevents subsequent steps from running if only documentation was changed
          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
            git fetch origin "$BASE_REF"
            BASE="origin/${BASE_REF}"
          else
            BASE=HEAD^1
          fi

          filesPath="${RUNNER_TEMP}/changed-files.txt"
          if git diff --name-only "${BASE}...HEAD" > "$filesPath"; then
            echo "files-path=$filesPath" >> "$GITHUB_OUTPUT"
            echo "diff-ok=true" >> "$GITHUB_OUTPUT"
          else
            echo "Git diff failed, conservatively running tests"
            echo "diff-ok=false" >> "$GITHUB_OUTPUT"
          fi
      - id: filter_docs
        if: steps.diff.outputs.diff-ok == 'true'
        uses: ./.github/actions/docs-only-filter
        with:
          files-path: ${{ steps.diff.outputs.files-path }}
      - id: filter
        run: |
          echo "should-run=${{ steps.diff.outputs.diff-ok == 'false' || steps.filter_docs.outputs.should-run }}" >> "$GITHUB_OUTPUT"

  # Low-priority gate. This job runs for every PR/dispatch that needs CI, but
  # only nv-slang-bot[bot] workflow_dispatch runs can ever yield. Those are the
  # bot's draft-testing runs: a draft PR has no pull_request CI, so the bot
  # dispatches CI manually while iterating. Every other run — human PRs, the
  # bot's own ready-for-review PRs, and merge_group — is full priority, so the
  # gate succeeds immediately and the build jobs (which require this job to
  # succeed) proceed normally. When a throttled bot dispatch must yield to
  # human, merge-queue, or older bot CI, a marker step fails this job so it
  # consumes no expensive build/test runners; ci-retry-yielded-bot then reruns
  # it once CI is quiet.
  #
  # The job deliberately resolves to success or failure, never 'skipped':
  # a skipped dependency would collide with the implicit success() that gates
  # the build jobs and silently skip all of CI. See the build-job `if` below.
  wait-for-human-priority:
    needs: [filter]
    if: needs.filter.outputs.should-run == 'true'
    # This gate fires for every PR revision and does light work (checkout +
    # Python + `gh api`, no GPU) — the same shape as ci-health/ci-analytics.
    #
    # RUNNER SELECTION — switchable via the `ANALYTICS_RUNS_ON` repository
    # variable, WITHOUT a code change (Settings → Secrets and variables →
    # Actions → Variables):
    #   - variable UNSET (default): run on GitHub-hosted `ubuntu-latest`.
    #   - variable SET to a runs-on JSON string, e.g.
    #     `["Linux", "self-hosted", "analytics", "GCP"]`: run on the GCP
    #     analytics pool.
    # It was offloaded to the GCP analytics pool in June 2026 to keep it off the
    # 20-runner org cap. NOTE: ci-health.yml runs on the same variable; keeping
    # it on GCP avoids the self-starvation blind spot where the cap monitor is
    # itself starved by the cap it measures — prefer the GCP pool for this group
    # unless the Teams-tier cap has ample headroom.
    runs-on: ${{ vars.ANALYTICS_RUNS_ON && fromJSON(vars.ANALYTICS_RUNS_ON) || fromJSON('["ubuntu-latest"]') }}
    timeout-minutes: 10
    # Only reads Actions API state and runs a script; no write access needed.
    permissions:
      actions: read
      contents: read
    steps:
      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
        with:
          persist-credentials: false
      - id: priority
        name: Check priority gate
        env:
          GH_TOKEN: ${{ github.token }}
          # Only the bot's own workflow_dispatch runs (its draft-testing runs)
          # are throttled. The bot's ready-for-review PRs are treated as human.
          IS_THROTTLED_BOT: ${{ github.event_name == 'workflow_dispatch' && github.triggering_actor == 'nv-slang-bot[bot]' }}
        run: |
          if [[ "$IS_THROTTLED_BOT" != "true" ]]; then
            echo "Not a throttled bot run; proceeding without yielding."
            echo "yielded=false" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          python3 extras/ci/wait-for-priority.py \
            --repo "$GITHUB_REPOSITORY" \
            --workflow ci.yml \
            --max-yield-hours 12

      - name: Stop yielded bot CI
        if: steps.priority.outputs.yielded == 'true'
        run: |
          echo "::error::priority-gate-yielded: higher-priority CI is active; ci-retry-yielded-bot will rerun this bot CI when quiet"
          exit 1

  # Linux x86_64 builds run in the CI container.
  #
  # RUNNER SELECTION — switchable between GitHub-hosted and the GCP self-hosted
  # build pool via the `LINUX_BUILD_RUNS_ON` repository variable, WITHOUT a code
  # change (Settings → Secrets and variables → Actions → Variables):
  #   - variable UNSET (default): run on GitHub-hosted `ubuntu-22.04`.
  #   - variable SET to a runs-on JSON string, e.g.
  #     `["Linux", "self-hosted", "build", "GCP"]`: run on the GCP build pool.
  # These builds were offloaded to GCP in June 2026 (PR #11738) to relieve the
  # GitHub-hosted 20-runner org cap; with the Teams-tier 60-runner cap they can
  # ride the GitHub-hosted pool again by default, while the variable keeps a
  # zero-code-change escape hatch back to GCP if the cap tightens.
  #
  # container-user must track the runner: the GCP build image's runner owns
  # _work as UID:GID 1003, while GitHub-hosted runners use 1001 (the reusable
  # workflow's default). It is keyed off the SAME variable so the two never
  # diverge — set the variable → get the GCP UID; unset → get the hosted UID.
  build-linux-debug-gcc-x86_64:
    needs: [filter, wait-for-human-priority]
    if: >-
      needs.filter.outputs.should-run == 'true' &&
      (needs.wait-for-human-priority.result == 'success' ||
       needs.wait-for-human-priority.result == 'skipped')
    uses: ./.github/workflows/ci-slang-build-container.yml
    # id-token is never part of the default GITHUB_TOKEN even when the repo
    # default is "write"; it must be requested explicitly for the reusable
    # workflow's GCP Workload Identity auth step. Set it on the caller so the
    # token actually carries id-token:write rather than relying on the default.
    permissions:
      id-token: write
      contents: read
      packages: read
    with:
      config: debug
      runs-on: ${{ vars.LINUX_BUILD_RUNS_ON || '["ubuntu-22.04"]' }}
      container-user: ${{ vars.LINUX_BUILD_RUNS_ON && '1003:1003' || '1001:1001' }}

  # Runner selection and container-user tracking: see build-linux-debug-gcc-x86_64
  # above (both keyed off the `LINUX_BUILD_RUNS_ON` repository variable).
  build-linux-release-gcc-x86_64:
    needs: [filter, wait-for-human-priority]
    if: >-
      needs.filter.outputs.should-run == 'true' &&
      (needs.wait-for-human-priority.result == 'success' ||
       needs.wait-for-human-priority.result == 'skipped')
    uses: ./.github/workflows/ci-slang-build-container.yml
    # id-token is never part of the default GITHUB_TOKEN even when the repo
    # default is "write"; it must be requested explicitly for the reusable
    # workflow's GCP Workload Identity auth step. Set it on the caller so the
    # token actually carries id-token:write rather than relying on the default.
    permissions:
      id-token: write
      contents: read
      packages: read
    with:
      config: release
      runs-on: ${{ vars.LINUX_BUILD_RUNS_ON || '["ubuntu-22.04"]' }}
      container-user: ${{ vars.LINUX_BUILD_RUNS_ON && '1003:1003' || '1001:1001' }}

  # WASM build runs directly on the host (no container). It needs the gcc host
  # toolchain (g++) for the native generators build; emsdk is downloaded by the
  # build itself. Both GitHub-hosted `ubuntu-22.04` and the GCP linux-cpu-runner
  # image provide g++, so this job runs on either.
  #
  # RUNNER SELECTION — switchable via the `LINUX_BUILD_RUNS_ON` repository
  # variable, same as the x86_64 builds above: unset → GitHub-hosted
  # `ubuntu-22.04`; set to a runs-on JSON string → the GCP build pool. id-token
  # is requested for the reusable workflow's GCP Workload Identity auth step
  # (never part of the default GITHUB_TOKEN); it is harmless on GitHub-hosted.
  build-linux-release-gcc-wasm:
    needs: [filter, wait-for-human-priority]
    if: >-
      needs.filter.outputs.should-run == 'true' &&
      (needs.wait-for-human-priority.result == 'success' ||
       needs.wait-for-human-priority.result == 'skipped')
    uses: ./.github/workflows/ci-slang-build.yml
    permissions:
      id-token: write
      contents: read
      packages: read
    with:
      os: linux
      compiler: gcc
      platform: wasm
      config: release
      runs-on: ${{ vars.LINUX_BUILD_RUNS_ON || '["ubuntu-22.04"]' }}

  # Sanitizer build+test (blocking via check-ci, runs on every PR). Runs in the
  # clang CI container as `--user root`, so there is no container-user concern
  # and no runner-UID coupling — only the runner label switches.
  #
  # RUNNER SELECTION — switchable via the `LINUX_BUILD_RUNS_ON` repository
  # variable, same as the x86_64 builds above: unset → GitHub-hosted
  # `ubuntu-22.04`; set to a runs-on JSON string → the GCP build pool. id-token
  # is requested explicitly for GCP Workload Identity auth (never part of the
  # default GITHUB_TOKEN); it is harmless on GitHub-hosted.
  sanitizer-linux-clang-x86_64:
    needs: [filter, wait-for-human-priority]
    if: >-
      needs.filter.outputs.should-run == 'true' &&
      (needs.wait-for-human-priority.result == 'success' ||
       needs.wait-for-human-priority.result == 'skipped')
    uses: ./.github/workflows/ci-slang-sanitizer.yml
    permissions:
      # Required by ci-slang-sanitizer.yml's GCP Workload Identity auth step;
      # id-token is never part of the default GITHUB_TOKEN.
      id-token: write
      contents: read
      packages: read
    with:
      runs-on: ${{ vars.LINUX_BUILD_RUNS_ON || '["ubuntu-22.04"]' }}

  # macOS builds
  build-macos-debug-clang-aarch64:
    needs: [filter, wait-for-human-priority]
    if: >-
      needs.filter.outputs.should-run == 'true' &&
      (needs.wait-for-human-priority.result == 'success' ||
       needs.wait-for-human-priority.result == 'skipped')
    uses: ./.github/workflows/ci-slang-build.yml
    with:
      os: macos
      compiler: clang
      platform: aarch64
      config: debug
      runs-on: '["macos-latest"]'

  build-macos-release-clang-aarch64:
    needs: [filter, wait-for-human-priority]
    if: >-
      needs.filter.outputs.should-run == 'true' &&
      (needs.wait-for-human-priority.result == 'success' ||
       needs.wait-for-human-priority.result == 'skipped')
    uses: ./.github/workflows/ci-slang-build.yml
    with:
      os: macos
      compiler: clang
      platform: aarch64
      config: release
      runs-on: '["macos-latest"]'

  # Linux ARM64 builds (GitHub-hosted)
  build-linux-debug-gcc-aarch64:
    needs: [filter, wait-for-human-priority]
    if: >-
      needs.filter.outputs.should-run == 'true' &&
      (needs.wait-for-human-priority.result == 'success' ||
       needs.wait-for-human-priority.result == 'skipped')
    uses: ./.github/workflows/ci-slang-build.yml
    with:
      os: linux
      compiler: gcc
      platform: aarch64
      config: debug
      runs-on: '["ubuntu-24.04-arm"]'
      warnings-as-errors: false

  build-linux-release-gcc-aarch64:
    needs: [filter, wait-for-human-priority]
    if: >-
      needs.filter.outputs.should-run == 'true' &&
      (needs.wait-for-human-priority.result == 'success' ||
       needs.wait-for-human-priority.result == 'skipped')
    uses: ./.github/workflows/ci-slang-build.yml
    with:
      os: linux
      compiler: gcc
      platform: aarch64
      config: release
      runs-on: '["ubuntu-24.04-arm"]'
      warnings-as-errors: false

  # Unit tests for non-exported source/slang entry points. These need SLANG_LIB_TYPE=STATIC, a
  # configuration no other CI job builds, so they get their own workflow. They
  # build only the slang-static-unit-test target and run on GitHub-hosted runners
  # (no GPU needed), so they add no load to the self-hosted Windows pool.
  static-unit-test-linux-debug-gcc-aarch64:
    needs: [filter, wait-for-human-priority]
    if: >-
      needs.filter.outputs.should-run == 'true' &&
      (needs.wait-for-human-priority.result == 'success' ||
       needs.wait-for-human-priority.result == 'skipped')
    uses: ./.github/workflows/ci-slang-static-unit-test.yml
    with:
      os: linux
      compiler: gcc
      platform: aarch64
      config: debug
      runs-on: '["ubuntu-24.04-arm"]'

  static-unit-test-macos-debug-clang-aarch64:
    needs: [filter, wait-for-human-priority]
    if: >-
      needs.filter.outputs.should-run == 'true' &&
      (needs.wait-for-human-priority.result == 'success' ||
       needs.wait-for-human-priority.result == 'skipped')
    uses: ./.github/workflows/ci-slang-static-unit-test.yml
    with:
      os: macos
      compiler: clang
      platform: aarch64
      config: debug
      runs-on: '["macos-latest"]'

  static-unit-test-windows-debug-cl-x86_64:
    needs: [filter, wait-for-human-priority]
    if: >-
      needs.filter.outputs.should-run == 'true' &&
      (needs.wait-for-human-priority.result == 'success' ||
       needs.wait-for-human-priority.result == 'skipped')
    uses: ./.github/workflows/ci-slang-static-unit-test.yml
    with:
      os: windows
      compiler: cl
      platform: x86_64
      config: debug
      runs-on: '["windows-2022"]'

  # Windows builds (self-hosted)
  build-windows-debug-cl-x86_64-gpu:
    needs: [filter, wait-for-human-priority]
    if: >-
      needs.filter.outputs.should-run == 'true' &&
      (needs.wait-for-human-priority.result == 'success' ||
       needs.wait-for-human-priority.result == 'skipped')
    uses: ./.github/workflows/ci-slang-build.yml
    with:
      os: windows
      compiler: cl
      platform: x86_64
      config: debug
      runs-on: '["Windows", "self-hosted", "build"]'

  build-windows-release-cl-x86_64-gpu:
    needs: [filter, wait-for-human-priority]
    if: >-
      needs.filter.outputs.should-run == 'true' &&
      (needs.wait-for-human-priority.result == 'success' ||
       needs.wait-for-human-priority.result == 'skipped')
    uses: ./.github/workflows/ci-slang-build.yml
    with:
      os: windows
      compiler: cl
      platform: x86_64
      config: release
      runs-on: '["Windows", "self-hosted", "build"]'

  # Windows ARM64 build. GitHub-hosted, native — not cross-compiled.
  # Deliberately NOT added to check-ci's required needs list below: this
  # repo has zero real-world CI runs on this image yet (only
  # workflow_dispatch spikes during validation, before it merged). A
  # day-old GA image can still have rough edges a required check
  # shouldn't gate every PR merge on. Promote to required once it has run
  # cleanly across several PRs.
  build-windows-debug-cl-aarch64:
    needs: [filter, wait-for-human-priority]
    if: >-
      needs.filter.outputs.should-run == 'true' &&
      (needs.wait-for-human-priority.result == 'success' ||
       needs.wait-for-human-priority.result == 'skipped')
    uses: ./.github/workflows/ci-slang-build.yml
    permissions:
      # Required by ci-slang-build.yml's GCP Workload Identity auth step
      # (LLVM GCS cache); id-token is never part of the default GITHUB_TOKEN.
      id-token: write
      contents: read
    with:
      os: windows
      compiler: cl
      platform: aarch64
      config: debug
      runs-on: '["windows-11-vs2026-arm"]'
      build-llvm: true

  build-windows-release-cl-aarch64:
    needs: [filter, wait-for-human-priority]
    if: >-
      needs.filter.outputs.should-run == 'true' &&
      (needs.wait-for-human-priority.result == 'success' ||
       needs.wait-for-human-priority.result == 'skipped')
    uses: ./.github/workflows/ci-slang-build.yml
    permissions:
      id-token: write
      contents: read
    with:
      os: windows
      compiler: cl
      platform: aarch64
      config: release
      runs-on: '["windows-11-vs2026-arm"]'
      build-llvm: true

  # Vet-and-approve gate for the Falcor-only rebuild below. A job that
  # calls a reusable workflow via `uses:` cannot itself carry
  # `environment:` (GitHub only allows name/uses/with/secrets/needs/if/
  # permissions on such jobs), so the approval gate has to live on this
  # plain job instead, with the build depending on it.
  #
  # Skipped on `merge_group`: every commit reaching the merge queue already
  # passed this same gate as a `pull_request` run (`check-ci`, which
  # includes `test-falcor`, is a required status check, so a PR cannot
  # become mergeable -- and therefore cannot enter the queue -- without an
  # allowlisted actor or reviewer having already released this gate once).
  # The merge-queue run only recompiles the PR's already-vetted commits
  # merged onto a newer `master`; it introduces no code that has not
  # already cleared Falcor approval. Skipping here avoids asking an
  # approver to re-click a gate whose outcome is already determined,
  # without weakening the gate for its actual purpose: keeping unvetted,
  # first-look PR code off internal Falcor compute.
  #
  # A skipped job here does NOT by itself let the build below proceed --
  # see the `if` on build-windows-release-cl-x86_64-gpu-falcor, which
  # explicitly opts back in to running after a skip.
  falcor-build-approval-gate:
    needs: [filter]
    if: needs.filter.outputs.should-run == 'true' && github.event_name != 'merge_group'
    environment: falcor-ci
    runs-on: ubuntu-latest
    timeout-minutes: 5
    # Only runs `echo`; no GITHUB_TOKEN scopes are needed.
    permissions: {}
    steps:
      - name: Approved
        run: echo "Falcor rebuild approved."

  # A separate build for test-falcor, gated behind the same falcor-ci
  # approval as the test job itself. The regular Windows-release build
  # above runs eagerly and its slang-tests-* artifact expires (1-day
  # retention, and GitHub's download URLs are short-lived signed URLs)
  # long before a PR sitting in the Falcor approval queue gets looked at.
  # Building again here, only once approved, means the artifact this job
  # produces is always fresh when test-falcor actually needs it. The
  # other six consumers of build-windows-release-cl-x86_64-gpu's artifact
  # (dx/vk/cuda/rhi tests, MaterialX, compile-regression, benchmark) are
  # unaffected -- they keep using the eagerly-built, ungated artifact.
  #
  # If test-falcor fails on a stale/inaccessible artifact from this job
  # (observed: the bridge relay's own GitHub API artifact lookup can fail
  # for an unrelated attempt/token reason even when the artifact itself is
  # neither expired nor deleted -- see PR #12614 discussion), GitHub's
  # "Re-run failed jobs" will NOT rebuild here: re-run only ever
  # propagates to jobs downstream of a failure, never to an upstream job
  # that already succeeded (confirmed by a GitHub Actions maintainer,
  # https://github.com/actions/runner/issues/1961). Use "Re-run all jobs"
  # instead in that case, which forces this job to run fresh. This is a
  # known, accepted cost: a real Falcor regression needing a code fix
  # already forces a full re-run via a new commit, so this only affects
  # the narrower case of a transient retry with no code change.
  #
  # On `merge_group`, falcor-build-approval-gate above is skipped rather
  # than run. GitHub Actions does NOT treat a skipped `needs` job as
  # satisfying a dependent job by default -- "If a job fails or is
  # skipped, all jobs that need it are skipped unless the jobs use a
  # conditional expression that causes the job to continue" (GitHub Actions
  # docs). So this job's `if` must explicitly opt back in with `always()`
  # and then re-check the gate's own result: proceed when the gate
  # succeeded (the ordinary pull_request path) or was itself skipped
  # (the merge_group path added above), but still stop if the gate ran
  # and failed or was cancelled.
  build-windows-release-cl-x86_64-gpu-falcor:
    needs: [filter, falcor-build-approval-gate]
    if: >-
      always() && needs.filter.outputs.should-run == 'true' &&
      (needs.falcor-build-approval-gate.result == 'success' ||
      needs.falcor-build-approval-gate.result == 'skipped')
    uses: ./.github/workflows/ci-slang-build.yml
    with:
      os: windows
      compiler: cl
      platform: x86_64
      config: release
      runs-on: '["Windows", "self-hosted", "build"]'
      artifact-name-suffix: "-falcor"

  # Linux tests (self-hosted GPU runner, containerized)
  test-linux-debug-gcc-x86_64:
    needs: [filter, build-linux-debug-gcc-x86_64]
    if: needs.filter.outputs.should-run == 'true'
    uses: ./.github/workflows/ci-slang-test-container.yml
    with:
      config: debug
      server-count: 8

  test-linux-debug-gcc-x86_64-rhi:
    needs: [filter, build-linux-debug-gcc-x86_64]
    if: needs.filter.outputs.should-run == 'true'
    uses: ./.github/workflows/ci-rhi-test-container.yml
    with:
      config: debug

  test-linux-release-gcc-x86_64:
    needs: [filter, build-linux-release-gcc-x86_64]
    if: needs.filter.outputs.should-run == 'true'
    uses: ./.github/workflows/ci-slang-test-container.yml
    with:
      config: release
      server-count: 8

  test-linux-release-gcc-x86_64-rhi:
    needs: [filter, build-linux-release-gcc-x86_64]
    if: needs.filter.outputs.should-run == 'true'
    uses: ./.github/workflows/ci-rhi-test-container.yml
    with:
      config: release

  # Linux x86_64 SM80+ capability tests (self-hosted L4/Blackwell runner).
  # Runs only cooperative-matrix / neural coverage that T4 cannot safely
  # execute after CUDA coopmat moves to Ampere-only mma.sync PTX.
  test-linux-release-gcc-x86_64-sm80:
    needs: [filter, build-linux-release-gcc-x86_64]
    if: needs.filter.outputs.should-run == 'true'
    uses: ./.github/workflows/ci-slang-test-container.yml
    with:
      config: release
      runs-on: '["Linux", "self-hosted", "SM80Plus"]'
      gpu-tier: sm80plus
      server-count: 8

  # Linux x86_64 CPU-only tests (GitHub-hosted; no GPU).
  # Runs the test suite filtered to CPU and LLVM backends via
  # -api cpu+llvm, so GPU-targeted test variants are ignored rather than run.
  # Catches frontend / IR / diagnostic regressions on cheap hardware and
  # complements the GPU-runner jobs.
  test-linux-release-gcc-x86_64-cpu:
    needs: [filter, build-linux-release-gcc-x86_64]
    if: needs.filter.outputs.should-run == 'true'
    uses: ./.github/workflows/ci-slang-test.yml
    with:
      os: linux
      compiler: gcc
      platform: x86_64
      config: release
      runs-on: '["ubuntu-24.04"]'
      full-gpu-tests: false
      cpu-only: true
      server-count: 4

  # macOS tests
  test-macos-debug-clang-aarch64:
    needs: [filter, build-macos-debug-clang-aarch64]
    if: needs.filter.outputs.should-run == 'true'
    uses: ./.github/workflows/ci-slang-test.yml
    with:
      os: macos
      compiler: clang
      platform: aarch64
      config: debug
      runs-on: '["macos-latest"]'
      full-gpu-tests: true
      server-count: 3

  test-macos-debug-clang-aarch64-rhi:
    needs: [filter, build-macos-debug-clang-aarch64]
    if: needs.filter.outputs.should-run == 'true'
    uses: ./.github/workflows/ci-rhi-test.yml
    with:
      os: macos
      compiler: clang
      platform: aarch64
      config: debug
      runs-on: '["macos-latest"]'

  test-macos-release-clang-aarch64:
    needs: [filter, build-macos-release-clang-aarch64]
    if: needs.filter.outputs.should-run == 'true'
    uses: ./.github/workflows/ci-slang-test.yml
    with:
      os: macos
      compiler: clang
      platform: aarch64
      config: release
      runs-on: '["macos-latest"]'
      full-gpu-tests: true
      server-count: 3

  test-macos-release-clang-aarch64-rhi:
    needs: [filter, build-macos-release-clang-aarch64]
    if: needs.filter.outputs.should-run == 'true'
    uses: ./.github/workflows/ci-rhi-test.yml
    with:
      os: macos
      compiler: clang
      platform: aarch64
      config: release
      runs-on: '["macos-latest"]'

  # Linux ARM64 tests (GitHub-hosted, CPU only)
  test-linux-debug-gcc-aarch64:
    needs: [filter, build-linux-debug-gcc-aarch64]
    if: needs.filter.outputs.should-run == 'true'
    uses: ./.github/workflows/ci-slang-test.yml
    with:
      os: linux
      compiler: gcc
      platform: aarch64
      config: debug
      runs-on: '["ubuntu-24.04-arm"]'
      full-gpu-tests: false

  test-linux-release-gcc-aarch64:
    needs: [filter, build-linux-release-gcc-aarch64]
    if: needs.filter.outputs.should-run == 'true'
    uses: ./.github/workflows/ci-slang-test.yml
    with:
      os: linux
      compiler: gcc
      platform: aarch64
      config: release
      runs-on: '["ubuntu-24.04-arm"]'
      full-gpu-tests: false

  # Windows ARM64 test (GitHub-hosted, native, CPU only — no GPU on this
  # hosted image).
  test-windows-debug-cl-aarch64:
    needs: [filter, build-windows-debug-cl-aarch64]
    if: needs.filter.outputs.should-run == 'true'
    uses: ./.github/workflows/ci-slang-test.yml
    with:
      os: windows
      compiler: cl
      platform: aarch64
      config: debug
      runs-on: '["windows-11-vs2026-arm"]'
      full-gpu-tests: false
      # full-gpu-tests: false alone only disables full-GPU-test setup; the
      # -api expression it selects still defaults to "all", which the
      # Linux ARM64 jobs above handle via tests/expected-failure-no-gpu.txt.
      # That denylist hasn't been validated against this new, GPU-less
      # platform, so restrict directly to cpu+llvm via cpu-only instead of
      # relying on it.
      cpu-only: true

  test-windows-release-cl-aarch64:
    needs: [filter, build-windows-release-cl-aarch64]
    if: needs.filter.outputs.should-run == 'true'
    uses: ./.github/workflows/ci-slang-test.yml
    with:
      os: windows
      compiler: cl
      platform: aarch64
      config: release
      runs-on: '["windows-11-vs2026-arm"]'
      full-gpu-tests: false
      cpu-only: true

  # Windows GPU tests (self-hosted).
  # Each config is split into three parallel jobs to reduce wall-clock time:
  #   -gpu-dx:   dx11+dx12+wgpu
  #   -gpu-vk:   vk+cpu+llvm + no-API tests
  #   -gpu-cuda: cuda
  # The three jobs run concurrently on separate runners.
  test-windows-debug-cl-x86_64-gpu-dx:
    needs: [filter, build-windows-debug-cl-x86_64-gpu]
    if: needs.filter.outputs.should-run == 'true'
    uses: ./.github/workflows/ci-slang-test.yml
    with:
      os: windows
      compiler: cl
      platform: x86_64
      config: debug
      runs-on: '["Windows", "self-hosted", "GCP-T4"]'
      full-gpu-tests: true
      api: dx11+dx12+wgpu
      gpu-tier: t4

  test-windows-debug-cl-x86_64-gpu-vk:
    needs: [filter, build-windows-debug-cl-x86_64-gpu]
    if: needs.filter.outputs.should-run == 'true'
    uses: ./.github/workflows/ci-slang-test.yml
    with:
      os: windows
      compiler: cl
      platform: x86_64
      config: debug
      runs-on: '["Windows", "self-hosted", "GCP-T4"]'
      full-gpu-tests: true
      api: vk+cpu+llvm
      gpu-tier: t4

  test-windows-debug-cl-x86_64-gpu-cuda:
    needs: [filter, build-windows-debug-cl-x86_64-gpu]
    if: needs.filter.outputs.should-run == 'true'
    uses: ./.github/workflows/ci-slang-test.yml
    with:
      os: windows
      compiler: cl
      platform: x86_64
      config: debug
      runs-on: '["Windows", "self-hosted", "GCP-T4"]'
      full-gpu-tests: true
      api: cuda
      gpu-tier: t4

  test-windows-debug-cl-x86_64-gpu-rhi:
    needs: [filter, build-windows-debug-cl-x86_64-gpu]
    if: needs.filter.outputs.should-run == 'true'
    uses: ./.github/workflows/ci-rhi-test.yml
    with:
      os: windows
      compiler: cl
      platform: x86_64
      config: debug
      runs-on: '["Windows", "self-hosted", "GCP-T4"]'

  test-windows-release-cl-x86_64-gpu-dx:
    needs: [filter, build-windows-release-cl-x86_64-gpu]
    if: needs.filter.outputs.should-run == 'true'
    uses: ./.github/workflows/ci-slang-test.yml
    with:
      os: windows
      compiler: cl
      platform: x86_64
      config: release
      runs-on: '["Windows", "self-hosted", "GCP-T4"]'
      full-gpu-tests: true
      api: dx11+dx12+wgpu
      gpu-tier: t4

  test-windows-release-cl-x86_64-gpu-vk:
    needs: [filter, build-windows-release-cl-x86_64-gpu]
    if: needs.filter.outputs.should-run == 'true'
    uses: ./.github/workflows/ci-slang-test.yml
    with:
      os: windows
      compiler: cl
      platform: x86_64
      config: release
      runs-on: '["Windows", "self-hosted", "GCP-T4"]'
      full-gpu-tests: true
      api: vk+cpu+llvm
      gpu-tier: t4

  test-windows-release-cl-x86_64-gpu-cuda:
    needs: [filter, build-windows-release-cl-x86_64-gpu]
    if: needs.filter.outputs.should-run == 'true'
    uses: ./.github/workflows/ci-slang-test.yml
    with:
      os: windows
      compiler: cl
      platform: x86_64
      config: release
      runs-on: '["Windows", "self-hosted", "GCP-T4"]'
      full-gpu-tests: true
      api: cuda
      gpu-tier: t4

  test-windows-release-cl-x86_64-gpu-rhi:
    needs: [filter, build-windows-release-cl-x86_64-gpu]
    if: needs.filter.outputs.should-run == 'true'
    uses: ./.github/workflows/ci-rhi-test.yml
    with:
      os: windows
      compiler: cl
      platform: x86_64
      config: release
      runs-on: '["Windows", "self-hosted", "GCP-T4"]'

  # MaterialX integration test (Windows only for initial validation).
  test-materialx-windows-release:
    needs: [filter, build-windows-release-cl-x86_64-gpu]
    if: needs.filter.outputs.should-run == 'true'
    uses: ./.github/workflows/ci-materialx-regression-test.yml
    with:
      os: windows
      compiler: cl
      platform: x86_64
      config: release
      runs-on: '["windows-latest"]'

  # Verify docs/command-line-slangc-reference.md matches `slangc -help`.
  # Reuses the release artifact built by build-linux-release-gcc-x86_64 instead
  # of building slangc again from scratch (the old standalone
  # check-cmdline-ref.yml did a full redundant build for this one check).
  # Comment /regenerate-cmdline-ref on the PR to auto-fix a failure.
  check-cmdline-ref:
    needs: [filter, build-linux-release-gcc-x86_64]
    if: needs.filter.outputs.should-run == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      actions: read
    steps:
      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
        with:
          persist-credentials: false

      - name: Download Slang release artifact
        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
        with:
          name: slang-tests-linux-x86_64-gcc-release
          path: artifacts

      - name: Generate command line reference
        run: |
          # slangc is dynamically linked against libslang; the artifact lays
          # libraries under Release/lib, separate from the Release/bin binaries.
          chmod +x artifacts/Release/bin/* 2>/dev/null || true
          export LD_LIBRARY_PATH="$PWD/artifacts/Release/lib:$LD_LIBRARY_PATH"
          mkdir -p temp
          # Capture stdout+stderr to match how the golden file is produced by
          # regenerate-cmdline-ref.yml; otherwise stray stderr output would be
          # baked into the reference but missing here, causing a spurious diff.
          artifacts/Release/bin/slangc -help-style markdown -h > temp/command-line-slangc-reference.md 2>&1

      - name: Compare with existing reference
        run: |
          if ! diff -q temp/command-line-slangc-reference.md docs/command-line-slangc-reference.md > /dev/null; then
            echo "Command line reference is out of date. Diff:"
            diff -u docs/command-line-slangc-reference.md temp/command-line-slangc-reference.md
            echo "Please run 'slangc -help-style markdown -h > docs/command-line-slangc-reference.md' or comment '/regenerate-cmdline-ref' on your PR."
            exit 1
          fi

  # Verify docs/user-guide/a4-02-reference-capability-atoms.md matches
  # source/slang/slang-capabilities.capdef.
  # Reuses the release artifact built by build-linux-release-gcc-x86_64 instead
  # of building slang-capability-generator again from scratch.
  check-capability-atoms-ref:
    needs: [filter, build-linux-release-gcc-x86_64]
    if: needs.filter.outputs.should-run == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      actions: read
    steps:
      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
        with:
          persist-credentials: false

      - name: Download Slang release artifact
        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
        with:
          name: slang-tests-linux-x86_64-gcc-release
          path: artifacts

      - name: Generate capability atoms reference
        run: |
          # slang-capability-generator may depend on libraries under Release/lib,
          # separate from the Release/bin binaries.
          chmod +x artifacts/Release/bin/* 2>/dev/null || true
          export LD_LIBRARY_PATH="$PWD/artifacts/Release/lib:$LD_LIBRARY_PATH"
          if [[ ! -x artifacts/Release/bin/slang-capability-generator ]]; then
            echo "slang-capability-generator is missing from the Slang release artifact."
            exit 1
          fi
          mkdir -p temp/capability temp/docs/user-guide
          cp docs/user-guide/a4-02-reference-capability-atoms.md temp/docs/user-guide/a4-02-reference-capability-atoms.md
          capdefs=(source/slang/*.capdef)
          artifacts/Release/bin/slang-capability-generator \
            "${capdefs[@]}" \
            --target-directory temp/capability \
            --doc temp/docs/user-guide/a4-02-reference-capability-atoms.md

      - name: Compare with existing reference
        run: |
          if ! diff -q temp/docs/user-guide/a4-02-reference-capability-atoms.md docs/user-guide/a4-02-reference-capability-atoms.md > /dev/null; then
            echo "Capability atoms reference is out of date. Diff:"
            diff -u docs/user-guide/a4-02-reference-capability-atoms.md temp/docs/user-guide/a4-02-reference-capability-atoms.md
            echo "Please regenerate docs/user-guide/a4-02-reference-capability-atoms.md with slang-capability-generator."
            exit 1
          fi

  # Deliberately NOT added to check-ci's required needs list below: the
  # Falcor 1 bridge (vet/approve flow, KVM environment, approval gate) is
  # still being tuned, so it still runs and reports status on every PR that
  # runs CI at all (see the `filter` job above for what skips CI entirely),
  # but its result does not yet block merge. Promote it back to required
  # once the vet/approve balance has settled.
  test-falcor:
    needs: [filter, build-windows-release-cl-x86_64-gpu-falcor]
    if: needs.filter.outputs.should-run == 'true'
    permissions:
      contents: read
      actions: read
    uses: ./.github/workflows/ci-falcor-test.yml
    with:
      slang-artifact-name: slang-tests-windows-x86_64-cl-release-falcor

  # Not gated behind falcor-ci approval (runs on an ungated Windows perf
  # runner, not the KVM bridge), so it depends directly on the eagerly-built,
  # ungated artifact from build-windows-release-cl-x86_64-gpu rather than
  # waiting on the approval-gated build-windows-release-cl-x86_64-gpu-falcor.
  # A single `uses:` job can only carry one `needs:` list, so this needed its
  # own caller job separate from test-falcor above, fixing an artifact-not-
  # found failure: test-falcor-perf previously had no needs: at all and
  # could start before build-windows-release-cl-x86_64-gpu had finished
  # uploading its artifact.
  test-falcor-perf:
    needs: [filter, build-windows-release-cl-x86_64-gpu]
    if: needs.filter.outputs.should-run == 'true'
    permissions:
      contents: read
      actions: read
    uses: ./.github/workflows/ci-falcor-perf-test.yml
    with:
      slang-artifact-name: slang-tests-windows-x86_64-cl-release

  test-compile-regression:
    needs: [filter, build-windows-release-cl-x86_64-gpu]
    if: needs.filter.outputs.should-run == 'true'
    permissions:
      contents: read
      actions: read
    uses: ./.github/workflows/ci-slang-regression-test.yml

  test-benchmark:
    needs: [filter, build-windows-release-cl-x86_64-gpu]
    if: needs.filter.outputs.should-run == 'true'
    permissions:
      contents: read
      actions: read
    uses: ./.github/workflows/ci-mdl-benchmark-test.yml

  # Aggregate gate required by branch protection / the merge queue.
  #
  # The build jobs must be listed in `needs` even though every test job
  # already depends on a build job: when a needed job fails, GitHub
  # Actions marks the dependent jobs "skipped" (not "failed"). Once the
  # filter says CI should run, requiring every needed job to succeed
  # ensures skipped jobs cannot hide a failed dependency (see #11553).
  check-ci:
    needs:
      [
        filter,
        build-linux-debug-gcc-x86_64,
        build-linux-release-gcc-x86_64,
        build-linux-release-gcc-wasm,
        build-linux-debug-gcc-aarch64,
        build-linux-release-gcc-aarch64,
        build-macos-debug-clang-aarch64,
        build-macos-release-clang-aarch64,
        build-windows-debug-cl-x86_64-gpu,
        build-windows-release-cl-x86_64-gpu,
        static-unit-test-linux-debug-gcc-aarch64,
        static-unit-test-macos-debug-clang-aarch64,
        static-unit-test-windows-debug-cl-x86_64,
        test-windows-release-cl-x86_64-gpu-dx,
        test-windows-release-cl-x86_64-gpu-vk,
        test-windows-release-cl-x86_64-gpu-cuda,
        test-windows-release-cl-x86_64-gpu-rhi,
        test-windows-debug-cl-x86_64-gpu-dx,
        test-windows-debug-cl-x86_64-gpu-vk,
        test-windows-debug-cl-x86_64-gpu-cuda,
        test-windows-debug-cl-x86_64-gpu-rhi,
        test-macos-release-clang-aarch64,
        test-macos-release-clang-aarch64-rhi,
        test-macos-debug-clang-aarch64,
        test-macos-debug-clang-aarch64-rhi,
        test-linux-release-gcc-x86_64,
        test-linux-release-gcc-x86_64-rhi,
        test-linux-release-gcc-x86_64-sm80,
        test-linux-release-gcc-x86_64-cpu,
        test-linux-debug-gcc-x86_64,
        test-linux-debug-gcc-x86_64-rhi,
        test-linux-release-gcc-aarch64,
        test-linux-debug-gcc-aarch64,
        test-materialx-windows-release,
        sanitizer-linux-clang-x86_64,
        check-cmdline-ref,
        check-capability-atoms-ref,
        test-falcor-perf,
        test-compile-regression,
        test-benchmark,
        wait-for-human-priority,
      ]
    runs-on: ubuntu-latest
    if: always() && (github.event_name != 'pull_request' || github.event.pull_request.draft != true)
    steps:
      - name: Check CI Results
        env:
          NEEDS_JSON: ${{ toJSON(needs) }}
          FILTER_RESULT: ${{ needs.filter.result }}
          SHOULD_RUN: ${{ needs.filter.outputs.should-run }}
        run: |
          echo "=== CI Results Summary ==="
          echo "$NEEDS_JSON" | jq -r 'to_entries[] | "\(.key): \(.value.result)"'

          # If the filter succeeded and determined CI is unnecessary,
          # skipped build/test jobs are expected for a docs-only change.
          if [[ "$FILTER_RESULT" == "success" && "$SHOULD_RUN" != "true" ]]; then
            echo "Filter determined CI is unnecessary; skipped jobs are expected."
            exit 0
          fi

          # Require every needed job to succeed. Checking the generic
          # `needs` JSON (rather than enumerating each job) means any job
          # added to `needs` above is gated automatically.
          unsuccessful=$(echo "$NEEDS_JSON" | jq -r 'to_entries[]
            | select(.value.result != "success")
            | "\(.key): \(.value.result)"')
          if [[ -n "$unsuccessful" ]]; then
            echo "These CI jobs did not succeed:"
            echo "$unsuccessful"
            exit 1
          fi

          echo "All CI jobs completed successfully!"

  # Automatically retry GPU health check failures by dispatching ci-retry.yml,
  # which watches this run until it completes, then reruns only failed jobs.
  # Capped at 2 automatic retries via run_attempt check.
  retry-on-gpu-failure:
    needs: [check-ci]
    if: failure() && github.event_name == 'merge_group' && fromJSON(github.run_attempt) < 3
    runs-on: ubuntu-latest
    permissions:
      actions: write
    steps:
      - name: Check for GPU health check failures and dispatch retry
        env:
          GH_REPO: ${{ github.repository }}
          GH_TOKEN: ${{ github.token }}
        run: |
          gpu_failures=$(gh api "repos/${{ github.repository }}/actions/runs/${{ github.run_id }}/jobs?per_page=100" \
            --jq '[.jobs[]
              | select(.conclusion == "failure")
              | select(any(.steps[]?;
                  (.name == "GPU health check" and .conclusion == "failure") or
                  (.name == "GPU post-test diagnostics" and .conclusion == "failure")
                ))
            ] | length' \
            || echo "0")
          gpu_failures=${gpu_failures:-0}
          if ! [[ "$gpu_failures" =~ ^[0-9]+$ ]]; then
            gpu_failures=0
          fi

          if [ "$gpu_failures" -gt 0 ]; then
            echo "Found $gpu_failures GPU failure(s) — dispatching retry workflow..."
            gh workflow run ci-retry.yml -F run_id=${{ github.run_id }}
          else
            echo "No GPU failures — not retrying."
          fi