ci.yml

# SPDX-FileCopyrightText: 2026 Uberware Inc. <https://uberware.net>
# SPDX-License-Identifier: AGPL-3.0-or-later

name: CI

# Runs on every push to main and on every pull request targeting main.
on:
  push:
    branches: [main]
  pull_request:
  workflow_dispatch: # allows manual triggering from the GitHub Actions UI

# If a new push arrives on the same branch while a run is in progress,
# cancel the older run. Prevents wasted minutes on stale commits.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# Minimal permissions — principle of least privilege.
# Individual jobs can elevate if needed (none currently do).
permissions:
  contents: read

jobs:
  # ── Change detection ─────────────────────────────────────────────────────────
  # Detects which areas changed so downstream jobs run only when relevant: the
  # Python jobs target `clients/python/`, the submitter jobs target
  # `clients/submitter/` and `presets/sqi/`, and the actionlint job targets the
  # workflow files themselves.
  changes:
    name: Detect changed paths
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read # paths-filter reads the PR diff via the API
    outputs:
      python: ${{ steps.filter.outputs.python }}
      submitter: ${{ steps.filter.outputs.submitter }}
      presets: ${{ steps.filter.outputs.presets }}
      workflows: ${{ steps.filter.outputs.workflows }}
    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Filter paths
        uses: dorny/paths-filter@v4
        id: filter
        with:
          filters: |
            python:
              - 'clients/python/**'
              - '.github/workflows/ci.yml'
            submitter:
              - 'clients/submitter/**'
              - 'presets/sqi/**'
              - '.github/workflows/ci.yml'
            # Gates the native Windows ffmpeg job below. Scoped to the presets
            # themselves and the code that executes them, deliberately NOT to
            # internal/worker or internal/openjd: a filter wide enough to catch
            # every possible influence would fire on nearly every PR, which is
            # the runner cost this job was carved out to control. The tradeoff
            # is that a change to the worker's format-string resolution can
            # break the PowerShell join without this firing — that lands on the
            # push-to-main run instead.
            presets:
              - 'presets/**'
              - 'test/integration/ffmpeg_presets_test.go'
              - 'test/integration/worker_binary_test.go'
              - '.github/workflows/ci.yml'
            workflows:
              - '.github/workflows/**'

  # ── Workflow linting ─────────────────────────────────────────────────────────
  # Lints the GitHub Actions workflow files with actionlint (run via `go run`,
  # pinned in the Makefile) whenever a workflow changes.
  actionlint:
    name: Lint workflows (actionlint)
    runs-on: ubuntu-latest
    needs: changes
    if: ${{ needs.changes.outputs.workflows == 'true' || github.event_name == 'workflow_dispatch' }}
    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up Go
        uses: actions/setup-go@v7
        with:
          go-version-file: go.mod

      - name: Run actionlint
        run: make lint-actions

  # ── Primary CI job ───────────────────────────────────────────────────────────
  # Runs build → vet → lint → test (race + coverage gate) → upload coverage.
  # All steps are sequential; failure in any step stops the job.
  test:
    name: Build, lint, and test
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up Go
        uses: actions/setup-go@v7
        with:
          # Reads the Go and toolchain versions from go.mod automatically.
          # Module download cache and build cache are enabled by default in v6.
          go-version-file: go.mod

      # Ensure go.mod (and go.sum once dependencies exist) are tidy, then check
      # that nothing changed. Fails the build if a developer forgot to commit
      # the result of go mod tidy.
      - name: Tidy module
        run: go mod tidy

      - name: Check go.mod is committed tidy
        run: git diff --exit-code go.mod go.sum

      # Verifies that the on-disk module cache matches go.sum exactly.
      # Catches tampered or corrupted dependencies before they can affect the build.
      - name: Verify module integrity
        run: go mod verify

      - name: Build
        run: make build

      # Publish the freshly-built binaries so the Python integration job can run
      # against them without rebuilding the web UI + Go toolchain itself.
      - name: Upload binaries
        uses: actions/upload-artifact@v7
        with:
          name: binaries
          path: |
            bin/sqi-server
            bin/sqi-worker
          retention-days: 1

      - name: go vet
        run: make vet

      # Uses the official golangci-lint GitHub Action, which handles binary
      # download and caching. Configuration is read from .golangci.yml at the
      # repo root.
      #
      # version is PINNED on purpose. Left unset the action resolves "latest",
      # so every new golangci-lint release lands on unrelated PRs as a red CI
      # run: v2.13.1 enabled the modernize/errorsastype analyzer and broke a
      # branch that had touched none of the reported code. Bump this
      # deliberately, in its own commit, with the fallout fixed alongside it.
      #
      # There is also a FLOOR below this pin: .golangci.yml excludes
      # errors.AsType from errcheck by function name, and errcheck before
      # 2.13.0 cannot resolve a generic function's name, so on an older
      # golangci-lint that exclusion silently fails to match and every
      # errors.AsType call site is reported. The floor is 2.13.0 (what Homebrew
      # ships, verified clean on this repo); this pin is one patch above it.
      # Keep docs/development.md's required-version note in step with both.
      #
      # Explicit path patterns mirror the Makefile LINT_PKGS variable: they
      # exclude web/node_modules/ (third-party JS packages that happen to
      # contain Go code and are not part of the sqi codebase).
      - name: golangci-lint
        uses: golangci/golangci-lint-action@v9
        with:
          version: v2.13.1
          args: --timeout=5m ./cmd/... ./internal/... ./pkg/... ./test/... ./web

      # The internal/openjd/expr path-engine differentials shell out to python3
      # and compare against pathlib. sqi implements CPython 3.13 path semantics
      # (PureWindowsPath.is_absolute() delegating to ntpath.isabs, and stem/suffix
      # no longer treating a name's leading/trailing dot run as an extension), so
      # those tests requirePython313 and SKIP on anything older — including the
      # ubuntu-latest system python, which is 3.12. Pin >= 3.13 here so the
      # differential actually ASSERTS rather than silently skipping. This is the
      # normal test suite only; the oracle job keeps its own 3.12 pin, which is
      # about the openjd-model venv, not pathlib.
      - name: Set up Python (>= 3.13 for the expr path differentials)
        uses: actions/setup-python@v7
        with:
          python-version: "3.13"

      # Run the full test suite with the race detector enabled and enforce
      # the minimum line-coverage threshold.
      # `make test-cover` enables -race via RACE=on (the Makefile default),
      # writes coverage.out, and exits non-zero if coverage < COVERAGE_MIN.
      # COVERAGE_MIN defaults to 70 in the Makefile — that is the single
      # source of truth; raise it there as coverage grows.
      - name: Test (race detector + coverage gate)
        run: make test-cover

      # Uploads coverage.out to Codecov. Requires the CODECOV_TOKEN secret
      # to be configured in the repository — see docs/development.md for setup
      # instructions. fail_ci_if_error is false so a Codecov outage does not
      # break the build.
      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v7
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          files: ./coverage.out
          fail_ci_if_error: false

  # ── Web UI quality gates ─────────────────────────────────────────────────────
  # Runs ESLint (--max-warnings 0), TypeScript type-check (tsc -b), and the
  # Vitest test suite with coverage enforcement — all in parallel with the Go
  # test job so neither blocks the other.
  web-check:
    name: Web UI lint, typecheck, and test
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      # Read the required Node version from .nvmrc at the repo root.
      # The engines field in web/package.json documents the same constraint.
      - name: Set up Node.js
        uses: actions/setup-node@v7
        with:
          node-version-file: .nvmrc
          cache: npm
          cache-dependency-path: web/package-lock.json

      - name: Install web dependencies
        working-directory: web
        run: npm ci

      # Prettier — fail if any file would be reformatted.
      - name: Check formatting (Prettier)
        working-directory: web
        run: npm run format:check

      # ESLint — --max-warnings 0 makes every warning a build failure.
      - name: Lint (ESLint)
        working-directory: web
        run: npm run lint

      # tsc -b type-checks all project references (tsconfig.app.json +
      # tsconfig.node.json) without emitting output.
      - name: Type-check (tsc -b)
        working-directory: web
        run: npm run typecheck

      # Vitest run with V8 coverage; exits non-zero if thresholds are not met.
      # The thresholds are defined in vite.config.ts (85 % lines / 82 % functions).
      - name: Test with coverage gate (Vitest)
        working-directory: web
        run: npm run test:coverage

      # Upload the JSON coverage report to Codecov so web coverage trends are
      # tracked separately from Go (flags: web).  Mirrors the Go upload step.
      # fail_ci_if_error: false so a Codecov outage does not break the build.
      - name: Upload web coverage to Codecov
        uses: codecov/codecov-action@v7
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          files: web/coverage/coverage-final.json
          flags: web
          fail_ci_if_error: false

  # ── Web end-to-end (Playwright) ──────────────────────────────────────────────
  # Builds the real binaries (sqi-server embeds web/dist) and drives the embedded
  # UI in Chromium, Firefox, and WebKit. The Playwright global setup boots a
  # server + worker on an ephemeral loopback port, seeds a farm/queue, submits a
  # job through the /submit form, and asserts it runs to completion with logs.
  # See docs/cross-platform-validation.md for the manual per-OS equivalent.
  web-e2e:
    name: Web UI end-to-end (Playwright)
    runs-on: ubuntu-latest
    # The worker refuses to run as root unless explicitly allowed; CI runs as
    # root, so the global setup boots it with this set.
    env:
      SQI_WORKER_ALLOW_ROOT: "true"

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up Go
        uses: actions/setup-go@v7
        with:
          go-version-file: go.mod

      - name: Set up Node.js
        uses: actions/setup-node@v7
        with:
          node-version-file: .nvmrc
          cache: npm
          cache-dependency-path: web/package-lock.json

      - name: Install web dependencies
        working-directory: web
        run: npm ci

      # Builds web/dist + both binaries into ./bin so the Playwright global
      # setup finds bin/sqi-server and bin/sqi-worker (it would build them
      # otherwise, but doing it here keeps the failure mode obvious).
      - name: Build binaries (server embeds the UI)
        run: make build

      # Installs the three browser engines plus their Linux system libraries.
      - name: Install Playwright browsers
        working-directory: web
        run: npx playwright install --with-deps

      - name: Run Playwright E2E (chromium, firefox, webkit)
        working-directory: web
        run: npm run test:e2e

      # Publish the HTML report and traces when the E2E run fails so flakes are
      # diagnosable from the CI artifacts.
      - name: Upload Playwright report on failure
        if: ${{ failure() }}
        uses: actions/upload-artifact@v7
        with:
          name: playwright-report
          path: web/playwright-report/
          retention-days: 7

  # ── Docker latest ────────────────────────────────────────────────────────────
  # Builds and pushes ghcr.io/uberware/sqi/sqi-server:latest on every push to
  # main. Uses the standalone multi-stage Dockerfile so the image is built from
  # source without needing goreleaser. Runs only after the test job passes.
  docker-latest:
    name: Publish :latest to GHCR
    runs-on: ubuntu-latest
    needs: [test, web-check]
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'

    permissions:
      contents: read  # required by actions/checkout
      packages: write

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up Go
        uses: actions/setup-go@v7
        with:
          go-version-file: go.mod

      - name: Export GOVERSION
        run: echo "GOVERSION=$(go version | awk '{print $3}')" >> "$GITHUB_ENV"

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Log in to GHCR
        uses: docker/login-action@v4
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push sqi-server :latest
        uses: docker/build-push-action@v7
        with:
          context: .
          file: deploy/docker/Dockerfile
          push: true
          platforms: linux/amd64,linux/arm64
          tags: ghcr.io/uberware/sqi/sqi-server:latest
          build-args: |
            VERSION=main
            COMMIT=${{ github.sha }}
            BUILD_DATE=${{ github.event.head_commit.timestamp || github.event.repository.updated_at }}
            GOVERSION=${{ env.GOVERSION }}
          # Per-image cache scope so the server and worker exports (both
          # mode=max, run back-to-back) don't clobber each other's blob refs.
          # ignore-error keeps a flaky GitHub Actions Cache export (the known
          # "error writing layer blob: not_found") from failing a job whose real
          # job — publishing :latest — has already succeeded.
          cache-from: type=gha,scope=docker-latest-server
          cache-to: type=gha,scope=docker-latest-server,mode=max,ignore-error=true

      - name: Build and push sqi-worker :latest
        uses: docker/build-push-action@v7
        with:
          context: .
          file: deploy/docker/worker/Dockerfile
          push: true
          platforms: linux/amd64,linux/arm64
          tags: ghcr.io/uberware/sqi/sqi-worker:latest
          build-args: |
            VERSION=main
            COMMIT=${{ github.sha }}
            BUILD_DATE=${{ github.event.head_commit.timestamp || github.event.repository.updated_at }}
            GOVERSION=${{ env.GOVERSION }}
          cache-from: type=gha,scope=docker-latest-worker
          cache-to: type=gha,scope=docker-latest-worker,mode=max,ignore-error=true

  # ── Cross-compilation matrix ─────────────────────────────────────────────────
  # Verifies that the binary compiles cleanly for all target platforms.
  # Runs only after the test job passes (needs: test).
  # fail-fast: false means a failure on one platform does not cancel the others,
  # giving a complete picture of which targets are broken.
  #
  # `go build ./cmd/sqi-server/... ./cmd/sqi-worker/...` below proves the two
  # binaries link, but `go build` never compiles _test.go files at all, so it
  # cannot catch a Windows-only break in test code — which is exactly what
  # happened on the task-isolation branch: internal/worker/isolation's
  # POSIX-only isolation_test.go referenced SysProcAttr.Credential, silently
  # breaking `GOOS=windows go vet` with nothing in CI to notice. The extra
  # windows/amd64-only step compiles every internal package (not just cmd/,
  # unlike the matrix build above) and vets internal/worker/... — vet, like
  # test compilation, type-checks _test.go files too — so the same class of
  # break fails a PR instead of surviving until someone runs it by hand.
  cross-compile:
    name: Cross-compile (${{ matrix.goos }}/${{ matrix.goarch }})
    runs-on: ubuntu-latest
    needs: test
    strategy:
      fail-fast: false
      matrix:
        goos: [linux, darwin, windows]
        goarch: [amd64, arm64]

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up Go
        uses: actions/setup-go@v7
        with:
          go-version-file: go.mod

      - name: Compile
        run: |
          GOOS=${{ matrix.goos }} GOARCH=${{ matrix.goarch }} go build ./cmd/sqi-server/...
          GOOS=${{ matrix.goos }} GOARCH=${{ matrix.goarch }} go build ./cmd/sqi-worker/...

      # See the job's own comment above for why this exists and why plain
      # `go build` (above) cannot substitute for it. amd64-only: GOARCH does
      # not affect what go vet's type-checking can see, so running this a
      # second time on arm64 would only cost CI minutes for no new coverage.
      - name: Windows internal packages build + vet
        if: matrix.goos == 'windows' && matrix.goarch == 'amd64'
        run: |
          GOOS=windows GOARCH=amd64 go build ./internal/... ./cmd/...
          GOOS=windows GOARCH=amd64 go vet ./internal/worker/...

  # ── Cross-platform runtime smoke ─────────────────────────────────────────────
  # cross-compile (above) proves the binaries *build* for every target; this job
  # proves they *run* — start, register a worker, execute a job, and stream logs
  # over REST + WebSocket — natively on macOS and Windows. Linux runtime is
  # already covered by the docker smoke-test and web-e2e jobs, so it is omitted
  # here. The manual VM-based equivalent is docs/cross-platform-validation.md.
  #
  # Native macOS/Windows runner minutes cost ~10x Linux, so this is skipped on
  # pull requests and runs only on pushes to main and manual dispatch.
  # fail-fast: false so a Windows-only failure still reports the macOS result.
  cross-platform-runtime:
    name: Runtime smoke (${{ matrix.os }})
    runs-on: ${{ matrix.os }}
    needs: test
    if: ${{ github.event_name != 'pull_request' }}
    strategy:
      fail-fast: false
      matrix:
        os: [macos-latest, windows-latest]
    # The worker refuses to run as root/elevated unless this is set; harmless on
    # the unprivileged runner users but keeps parity with the docker smoke job.
    env:
      SQI_WORKER_ALLOW_ROOT: "true"
    # Use bash on every OS (Git Bash on Windows) so the one smoke script runs
    # unchanged across platforms.
    defaults:
      run:
        shell: bash

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up Go
        uses: actions/setup-go@v7
        with:
          go-version-file: go.mod

      - name: Set up Node.js
        uses: actions/setup-node@v7
        with:
          node-version-file: .nvmrc
          cache: npm
          cache-dependency-path: web/package-lock.json

      # Provides a python with `websockets` so the smoke script's WebSocket
      # assertion runs for real (it otherwise degrades to a logged SKIP).
      - name: Set up Python
        uses: actions/setup-python@v7
        with:
          python-version: "3.x"

      - name: Install websockets for the WS smoke check
        run: python -m pip install --upgrade pip websockets

      # Build the web bundle first (the server embeds web/dist), then both
      # binaries with the platform-appropriate extension.
      - name: Build web bundle and binaries
        run: |
          (cd web && npm ci && npm run build)
          ext=""; [ "$RUNNER_OS" = "Windows" ] && ext=".exe"
          go build -o "bin/sqi-server${ext}" ./cmd/sqi-server
          go build -o "bin/sqi-worker${ext}" ./cmd/sqi-worker

      # Reuses scripts/smoke.sh (the same script developers run via `make smoke`).
      # Passing the prebuilt binaries skips its internal `make build`, so no GNU
      # make is required on the Windows runner.
      - name: End-to-end smoke (REST + WebSocket, plain / broker-auth / TLS)
        run: |
          ext=""; [ "$RUNNER_OS" = "Windows" ] && ext=".exe"
          export SQI_SERVER_BIN="bin/sqi-server${ext}"
          export SQI_WORKER_BIN="bin/sqi-worker${ext}"
          # Declare and assign separately so the command substitution's exit
          # status is not masked by `export` (shellcheck SC2155).
          SQI_SMOKE_PYTHON="$(command -v python)"
          export SQI_SMOKE_PYTHON
          bash scripts/smoke.sh 2>&1 | tee smoke-output.log
          status=${PIPESTATUS[0]}

          # The script runs three modes. Assert each one actually reported a
          # pass by name: a filter or branch regression that silently skipped a
          # mode would otherwise leave this job green while covering less.
          missing=0
          for mode in noauth brokerauth tls; do
            if ! grep -q "SMOKE TEST PASSED (mode=$mode)" smoke-output.log; then
              echo "::error::smoke mode $mode did not report a pass"
              missing=1
            fi
          done
          if [ "$status" -ne 0 ] || [ "$missing" -ne 0 ]; then
            echo "::error::the smoke test did not pass in all three modes (exit=$status)."
            exit 1
          fi
          echo "Confirmed all three smoke modes passed."

  # ── Docker smoke test ────────────────────────────────────────────────────────
  # Builds both Docker images from source (no registry push) and runs them
  # together via docker-compose.smoke.yml to verify that the worker registers
  # successfully with the server.  Runs on every push to main after the primary
  # test job passes; also runs on pull requests as a pre-merge gate.
  #
  # Plain `docker build` (not docker/build-push-action) is used here so that
  # setup-buildx is not needed.  setup-buildx pulls moby/buildkit from Docker
  # Hub at job start, which times out on congested runners.  The smoke test
  # only needs single-platform local builds, which the daemon's built-in
  # BuildKit supports without any external image.
  smoke-test:
    name: Docker smoke test (server + worker)
    runs-on: ubuntu-latest
    needs: test

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up Go
        uses: actions/setup-go@v7
        with:
          go-version-file: go.mod

      - name: Export GOVERSION
        run: echo "GOVERSION=$(go version | awk '{print $3}')" >> "$GITHUB_ENV"

      # Build images locally using the Docker daemon's built-in BuildKit.
      # docker build is used directly (no setup-buildx needed) because the
      # smoke test only requires a single-platform local image.
      - name: Build sqi-server image
        run: |
          DOCKER_BUILDKIT=1 docker build \
            -f deploy/docker/Dockerfile \
            --build-arg VERSION=smoke \
            --build-arg COMMIT=${{ github.sha }} \
            --build-arg BUILD_DATE=${{ github.event.head_commit.timestamp || github.event.pull_request.head.repo.updated_at || github.event.repository.updated_at }} \
            --build-arg GOVERSION=${{ env.GOVERSION }} \
            -t ghcr.io/uberware/sqi/sqi-server:latest \
            .

      - name: Build sqi-worker image
        run: |
          DOCKER_BUILDKIT=1 docker build \
            -f deploy/docker/worker/Dockerfile \
            --build-arg VERSION=smoke \
            --build-arg COMMIT=${{ github.sha }} \
            --build-arg BUILD_DATE=${{ github.event.head_commit.timestamp || github.event.pull_request.head.repo.updated_at || github.event.repository.updated_at }} \
            --build-arg GOVERSION=${{ env.GOVERSION }} \
            -t ghcr.io/uberware/sqi/sqi-worker:latest \
            .

      - name: Start smoke stack
        run: docker compose -f deploy/docker-compose.smoke.yml up -d

      - name: Wait for sqi-server to be ready
        run: |
          for i in $(seq 1 30); do
            if curl -sf http://localhost:8080/readyz > /dev/null; then
              echo "sqi-server is ready"
              exit 0
            fi
            echo "Waiting for sqi-server... ($i/30)"
            sleep 2
          done
          echo "ERROR: sqi-server did not become ready within 60 s"
          docker compose -f deploy/docker-compose.smoke.yml logs sqi-server
          exit 1

      - name: Wait for sqi-worker to register
        run: |
          for i in $(seq 1 30); do
            total=$(curl -sf http://localhost:8080/api/v1/workers \
              | python3 -c "import sys, json; print(json.load(sys.stdin).get('total', 0))" \
              2>/dev/null || echo "0")
            if [ "$total" -ge 1 ]; then
              echo "sqi-worker registered (total=$total)"
              exit 0
            fi
            echo "Waiting for worker... ($i/30)"
            sleep 2
          done
          echo "ERROR: no sqi-worker registered within 60 s"
          docker compose -f deploy/docker-compose.smoke.yml logs
          exit 1

      - name: Tear down
        if: always()
        run: docker compose -f deploy/docker-compose.smoke.yml down -v

  # ── Auth surface demo ────────────────────────────────────────────────────────
  # Runs scripts/auth-demo.sh (the same script developers run via `make
  # auth-demo`) against real binaries on a live local farm: auth enabled, a
  # bootstrap admin, a second non-admin account, and a worker executing a job.
  #
  # This is the end-to-end regression test for the auth surface — session
  # cookies, API keys, the CSRF guard, the RBAC permission matrix, and job owner
  # scoping — all of which are cross-cutting enough that the Go unit tests can
  # confirm each piece in isolation without catching a router that mounts the
  # wrong middleware on a real route.
  #
  # Linux-only and unconditional: it takes well under a minute, so unlike
  # cross-platform-runtime there is no reason to restrict it to pushes.
  #
  # The script needs curl + jq (preinstalled on GitHub-hosted runners) and
  # python3 (likewise; used only to allocate free loopback ports). Passing the
  # prebuilt binaries via SQI_*_BIN skips the script's internal `make build`.
  #
  # No Node build: the tracked placeholder web/dist/index.html is enough to keep
  # the server's //go:embed valid on a clean checkout, and this job exercises
  # only the REST API, never the UI bundle.
  auth-demo:
    name: Auth surface demo (live farm)
    runs-on: ubuntu-latest
    needs: test

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up Go
        uses: actions/setup-go@v7
        with:
          go-version-file: go.mod

      - name: Build binaries
        run: |
          go build -o bin/sqi-server ./cmd/sqi-server
          go build -o bin/sqi-worker ./cmd/sqi-worker

      - name: Auth surface demo (sessions, API keys, CSRF, RBAC, owner scoping)
        env:
          SQI_SERVER_BIN: bin/sqi-server
          SQI_WORKER_BIN: bin/sqi-worker
        run: bash scripts/auth-demo.sh

  # ── LDAP: real-directory integration ─────────────────────────────────────────
  # Runs the LDAP tests against an actual OpenLDAP server in a container, which
  # is the only thing that exercises sqi's go-ldap *wire* usage: search scopes,
  # attribute names, filter syntax, and how a real server answers a request it
  # does not support. Every other LDAP test drives a fake connection and cannot
  # see any of that — a wire bug passes the rest of CI and fails only against a
  # live directory. This job exists so that class of bug cannot merge.
  #
  # Docker is preinstalled on the ubuntu runners, so the test provisions its own
  # container and needs no service definition here. It skips (does not fail)
  # when Docker is unavailable, which keeps it harmless on any runner that lacks
  # it. Tagged `integration`, so it does not run in the default `make test`.
  ldap-integration:
    name: LDAP integration (${{ matrix.arch }})
    runs-on: ${{ matrix.runner }}
    needs: test

    # Both architectures, because the container image is multi-arch and its
    # variants have already proven not to be equivalent: the memberof module
    # registers its schema several seconds later on amd64 than on arm64, which
    # is a race a fixture can sit inside on one architecture and not the other.
    # Testing one arch would leave the other free to rot — and the LDAP wire
    # behavior this job exists to pin is exactly where that divergence showed
    # up. Native runners rather than QEMU: emulation is several times slower
    # and would test the emulator's timing rather than the runner's.
    #
    # fail-fast is off on purpose. When these two disagree, the disagreement IS
    # the finding, and cancelling the sibling job throws away half of it.
    strategy:
      fail-fast: false
      matrix:
        include:
          - arch: amd64
            runner: ubuntu-latest
          - arch: arm64
            runner: ubuntu-24.04-arm

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up Go
        uses: actions/setup-go@v7
        with:
          go-version-file: go.mod

      # Pulled explicitly so an image-registry problem fails here, with a clear
      # message, rather than inside the test where it would surface as a skip
      # and quietly turn this job green without having verified anything.
      - name: Pull OpenLDAP image
        run: docker pull osixia/openldap:1.5.0

      - name: Run LDAP integration tests
        run: make test-ldap

  # ── SSO against a real identity provider ─────────────────────────────────────
  # The SSO unit tests drive a fake provider. It signs real tokens, so a
  # validation mistake surfaces — but a fake returns whatever the test asks for,
  # so it cannot show what a real provider OMITS. Keycloak emits no group
  # membership at all without a protocol mapper configured for it, and a token
  # with no groups still validates: every user then lands on default_role, a
  # silent privilege downgrade with no error anywhere. This job is what makes
  # that class of bug fail before it merges. It also pins the two vendor
  # behaviors the logout design rests on (see test/integration/oidc_test.go).
  #
  # ONE architecture, unlike ldap-integration above, and deliberately so rather
  # than by oversight: that job runs both because the OpenLDAP image's arm64 and
  # amd64 variants have already proven to differ in real, test-visible ways
  # (cn=config credentials, overlay instantiation, module-registration timing).
  # No such divergence is known for the Keycloak image — it is a JVM application
  # whose HTTP and token behavior is what this job asserts on, none of which is
  # architecture-dependent — so a second runner would cost time without pinning
  # anything the first does not. Revisit if an arch-specific difference ever
  # does show up.
  #
  # Docker is preinstalled on the ubuntu runners, so the test provisions its own
  # container and needs no service definition here. It skips (does not fail)
  # when Docker is unavailable. Tagged `integration`, so it does not run in the
  # default `make test`.
  oidc-integration:
    name: OIDC integration
    runs-on: ubuntu-latest
    needs: test

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up Go
        uses: actions/setup-go@v7
        with:
          go-version-file: go.mod

      # Pulled explicitly so an image-registry problem fails here, with a clear
      # message, rather than inside the test where it would surface as a skip
      # and quietly turn this job green without having verified anything.
      #
      # Keep this tag in step with keycloakImage in test/integration/oidc_test.go:
      # the test scrapes Keycloak's login form, so the pin is load-bearing.
      - name: Pull Keycloak image
        run: docker pull quay.io/keycloak/keycloak:26.0.7

      - name: Run OIDC integration tests
        run: make test-oidc

  # ── Task isolation: run-as-user integration ──────────────────────────────────
  # Runs the run-as-user isolation suite as REAL root against REAL unprivileged
  # OS accounts inside a container — the only thing that exercises uid/gid
  # switching, session-directory ownership, environment filtering, and
  # process-group kill. internal/worker/isolation's fake Provider is
  # structurally blind to all of it; three Critical defects on this branch were
  # caught only because this suite runs against a real container. This job is
  # what makes that class of bug fail before it merges.
  #
  # Both architectures, matching ldap-integration above and for the same
  # reason: this exercises syscall-level behavior (setuid/setgid/setgroups,
  # SysProcAttr.Credential), which is exactly where arch divergence could hide.
  # oidc-integration's single-arch choice does not transfer here — its
  # justification is "no arch divergence is known for a JVM app", and this is
  # the opposite of that: raw kernel syscalls, not a JVM's HTTP/token behavior.
  # Native runners rather than QEMU, same reasoning as ldap-integration:
  # emulation is several times slower and would test the emulator's timing
  # rather than the runner's.
  #
  # `make test-isolation` builds its own image from a staged copy of the repo
  # (see the Makefile comment above the target), so unlike ldap-integration/
  # oidc-integration it needs no image pre-pulled here.
  #
  # IMPORTANT: `make test-isolation` exits 0 with a message when Docker is
  # unavailable — correct on a developer machine that may not have Docker, but
  # on a CI runner (where Docker is always preinstalled) a skip here would be a
  # silent false-green with nothing verified. So this job does not trust the
  # target's own exit code: it captures the output and fails unless (1) no
  # Docker-unavailable skip message appears and (2) all 11 TestIsolation_ tests
  # are confirmed PASS by name. A silent skip, a build failure, or a partial
  # run all fail the job instead of passing quietly.
  isolation-integration:
    name: Isolation integration (${{ matrix.arch }})
    runs-on: ${{ matrix.runner }}
    needs: test

    strategy:
      fail-fast: false
      matrix:
        include:
          - arch: amd64
            runner: ubuntu-latest
          - arch: arm64
            runner: ubuntu-24.04-arm

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up Go
        uses: actions/setup-go@v7
        with:
          go-version-file: go.mod

      # Does not trust a bare exit-0 from `make test-isolation`: asserts the
      # suite actually executed (no Docker-unavailable skip) and that every one
      # of the 11 TestIsolation_ tests is confirmed PASS by name, so a silent
      # skip or a partial run fails the job instead of passing quietly.
      - name: Run isolation integration tests
        run: |
          set +e
          make test-isolation 2>&1 | tee isolation-output.log
          status=${PIPESTATUS[0]}
          set -e

          if grep -q "docker unavailable" isolation-output.log; then
            echo "::error::Docker was unavailable — the isolation suite did not run. A skip here proves nothing, so this is a hard failure."
            exit 1
          fi

          pass_count=$(grep -c '^--- PASS: TestIsolation_' isolation-output.log || true)
          expected=11
          if [ "$status" -ne 0 ] || [ "$pass_count" -ne "$expected" ]; then
            echo "::error::Expected $expected TestIsolation_ tests to pass (exit=$status, found=$pass_count). Failing so a partial or failed run cannot look green."
            exit 1
          fi

          echo "Confirmed $pass_count/$expected TestIsolation_ tests passed."

  # ── Task isolation: run-as-user integration (Windows) ────────────────────────
  # Runs the Windows run-as-user isolation suite against REAL local accounts,
  # with its privileged tier running as SYSTEM — the Windows counterpart to
  # isolation-integration above, which covers POSIX.
  #
  # Two tiers because they need different privileges. CreateProcessAsUser —
  # which os/exec invokes whenever SysProcAttr.Token is set — requires
  # SeAssignPrimaryTokenPrivilege, held by default only by LocalSystem and the
  # LOCAL/NETWORK SERVICE accounts. The windows-latest runner user is an
  # administrator and does NOT hold it, so scripts/test-isolation-windows.ps1
  # registers a scheduled task with /ru SYSTEM for the tests that launch a
  # process as the target account (TestIsolationWindowsSystem_*). Everything
  # else — ACL shape, credential storage, impersonated access checks
  # (TestIsolationWindows_*) — runs directly under the elevated admin shell.
  #
  # One arch, matching oidc-integration's rationale rather than
  # ldap-integration's or isolation-integration's: the Win32 APIs this suite
  # exercises (ACLs, LogonUserW, CreateProcessAsUser) are not architecture-
  # dependent, and hosted windows-arm64 runners are not generally available.
  #
  # This job also runs the Windows-only UNIT tests, because nothing else in CI
  # does. cross-platform-runtime is a runtime smoke job and is skipped on pull
  # requests (if: github.event_name != 'pull_request'); the only other Windows
  # coverage is the cross-compile job's `GOOS=windows go vet`, which
  # type-checks test files but never executes them. Package list below is
  # every package with genuine `GOOS`-conditional behavior (a `_windows.go`
  # file, or a `runtime.GOOS == "windows"` branch in its tests) rather than
  # every package that merely imports something isolation-related:
  # internal/worker/isolation, internal/worker/executor, internal/worker/staging,
  # and cmd/sqi-worker each carry dedicated _windows.go/_windows_test.go files;
  # internal/worker/envutil and internal/worker/session have no such files but
  # branch on runtime.GOOS in their test bodies (path separators, credential
  # handling, profile-env resolution), so running them only on Linux would
  # silently skip the Windows branch of every one of those tests.
  #
  # IMPORTANT: scripts/test-isolation-windows.ps1 exits 0 with a message when
  # the shell is not elevated, mirroring how `make test-isolation` exits 0
  # without Docker. A bare exit 0 therefore proves NOTHING, which is why the
  # assertion step below checks for the not-elevated message and then counts
  # named PASS lines instead of trusting the exit code — the same shape as
  # isolation-integration's own assertion step above.
  isolation-integration-windows:
    name: Isolation integration (windows)
    runs-on: windows-latest
    needs: test

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up Go
        uses: actions/setup-go@v7
        with:
          go-version-file: go.mod

      # Windows-only unit tests. See the job comment above for why these six
      # packages and not others. -count=1 disables the test cache so a stale
      # pass from an earlier step can't stand in for a real run.
      - name: Windows unit tests
        shell: bash
        run: |
          go test -count=1 \
            ./internal/worker/isolation/... \
            ./internal/worker/executor/... \
            ./internal/worker/envutil/... \
            ./internal/worker/session/... \
            ./internal/worker/staging/... \
            ./cmd/sqi-worker/...

      - name: Run windows isolation integration tests
        shell: pwsh
        run: |
          powershell -NoProfile -ExecutionPolicy Bypass `
            -File scripts/test-isolation-windows.ps1 2>&1 | Tee-Object -FilePath isolation-windows.log

      # Does not trust a bare exit-0 from the script: asserts the suite
      # actually executed (the runner was elevated) and that every one of the
      # 16 named tests — 8 TestIsolationWindows_* (elevated admin) plus
      # 8 TestIsolationWindowsSystem_* (SYSTEM) — is confirmed PASS by name, so
      # a silent skip, a build failure, or a partial run all fail the job
      # instead of passing quietly.
      - name: Assert the suite actually ran
        shell: bash
        run: |
          if grep -q "not elevated" isolation-windows.log; then
            echo "::error::The runner was not elevated — the isolation suite did not run. A skip here proves nothing, so this is a hard failure."
            exit 1
          fi
          expected=(
            TestIsolationWindows_CapableRejectsPlainAdmin
            TestIsolationWindows_ChownRecursiveDoesNotFollowJunction
            TestIsolationWindows_CredentialDirectoryExcludesUnprivilegedTrustees
            TestIsolationWindows_CredentialFileNotReadableByRunAsAccount
            TestIsolationWindows_CredentialMissingIsActionable
            TestIsolationWindows_CredentialRoundTrip
            TestIsolationWindows_SecondAccountCannotOpenSessionDir
            TestIsolationWindows_SessionDirACLIsProtected
            TestIsolationWindowsSystem_Capable
            TestIsolationWindowsSystem_ChildCanWriteSessionDir
            TestIsolationWindowsSystem_ChildRunsAsTargetUser
            TestIsolationWindowsSystem_CrossUserSessionDirDenied
            TestIsolationWindowsSystem_DaemonEnvNotInherited
            TestIsolationWindowsSystem_NoIsolationUnchanged
            TestIsolationWindowsSystem_ProfileEnvPointsAtTargetUser
            TestIsolationWindowsSystem_RunsAsSystem
          )
          missing=0
          for name in "${expected[@]}"; do
            if ! grep -q -- "--- PASS: $name" isolation-windows.log; then
              echo "::error::$name did not pass"
              missing=1
            fi
          done
          if [ "$missing" -eq 0 ]; then
            echo "Confirmed all ${#expected[@]}/16 named isolation tests passed."
          fi
          exit $missing

  # ── Integration suite (whole package) ────────────────────────────────────────
  # Runs every file under test/integration/ via `make test-integration`, rather
  # than naming individual tests in a -run regex the way the LDAP, OIDC, and
  # isolation jobs below do. Those three name their tests because each needs
  # its own runner matrix or container prerequisites; everything else in the
  # package — broker auth, EXPR parameter binding and end-to-end execution,
  # failure-reason propagation (both in-process and against a real worker
  # binary), retry/auto-park behavior, and product retry-override submission —
  # shares no such prerequisite, so a single whole-package run covers a new
  # test the moment it is added instead of only if someone also remembers to
  # list it in a job. `go build`s a real sqi-worker binary along the way (see
  # worker_binary_test.go); no other tooling is required beyond Go itself.
  #
  # LDAP, OIDC, and isolation tests live in this same package and this job
  # exercises them too, but ubuntu-latest ships Docker so they are expected to
  # run rather than skip; the LDAP and Keycloak images are pulled explicitly
  # first so a registry hiccup fails here with a clear message instead of
  # inside the test as a cold-pull timeout that would read as a skip. The
  # isolation tests, in contrast, require running as root (see
  # isolation-integration below) and are expected to skip on this ordinary
  # runner — that is fine, and this job asserts nothing about them by name.
  #
  # IMPORTANT: a green `go test` here proves nothing on its own if the whole
  # suite silently collected zero tests (a build-tag regression, a stray
  # -run filter). This job does not trust the exit code alone: it requires a
  # test named from every file in the package that has no dedicated CI job of
  # its own — one exception is authfixture_test.go, which holds only helpers
  # shared by ldap_test.go and oidc_test.go and declares no test function of
  # its own to name. A confirmed-skip line for LDAP/OIDC/isolation does not
  # fail the job; only a missing PASS among the required names, or a nonzero
  # exit, does.
  integration-tests:
    name: Integration suite
    runs-on: ubuntu-latest
    needs: test

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up Go
        uses: actions/setup-go@v7
        with:
          go-version-file: go.mod

      # Pulled explicitly for the same reason ldap-integration and
      # oidc-integration below pull them: a registry problem fails here with a
      # clear message rather than surfacing inside the test as a cold-pull
      # timeout, which the test's own Docker-unavailable handling would read
      # as an ordinary skip.
      - name: Pull OpenLDAP image
        run: docker pull osixia/openldap:1.5.0

      - name: Pull Keycloak image
        run: docker pull quay.io/keycloak/keycloak:26.0.7

      - name: Run the integration suite
        run: |
          set +e
          # go test's own default (10m per package) leaves little headroom
          # once the LDAP and Keycloak containers are in the run: up to ~90s
          # for LDAP readiness plus up to ~180s for Keycloak, on top of the
          # suite's own runtime, which is dominated by that container
          # readiness rather than by the tests themselves. 15m is set
          # explicitly here, through INTEGRATION_TEST_FLAGS, so a slow runner
          # gets a clear failure instead of a default timeout landing close
          # enough to the estimate to be a coin flip; local runs are
          # unaffected since the Makefile leaves this empty by default.
          make test-integration INTEGRATION_TEST_FLAGS="-timeout 15m" 2>&1 | tee integration-output.log
          status=${PIPESTATUS[0]}
          set -e

          # One name from each file in test/integration/ that has no dedicated
          # CI job of its own, so a build-tag or filter regression that let the
          # suite silently collect zero tests cannot pass this job.
          expected=(
            TestDefaultConfig_NoBrokerAuth
            TestRevocation_DisconnectsAndReclaims
            TestEnrollment_ConnectsToRunningBrokerWithoutRestart
            TestEXPRParamTypes_BindAndCarry
            TestEXPRJobEndToEnd
            TestTaskFailureReason_VisibleEndToEnd
            TestWorkerBinaryStagingFailureReason
            TestProductSubmit_RetryOverrides
            TestAutoRetry_RetryThenSucceed
            TestTLSEndToEnd
            TestTLSWorkerWithoutCAIsRefused
          )
          missing=0
          for name in "${expected[@]}"; do
            if ! grep -q -- "--- PASS: $name" integration-output.log; then
              echo "::error::$name did not pass"
              missing=1
            fi
          done
          if [ "$status" -ne 0 ] || [ "$missing" -ne 0 ]; then
            echo "::error::the integration suite did not all pass (exit=$status)."
            exit 1
          fi
          echo "Confirmed all ${#expected[@]} named integration tests passed, and the whole suite exited 0."

  # ── mDNS discovery over real multicast ───────────────────────────────────────
  # A SEPARATE job, not folded into integration-tests, for two reasons. Whether
  # a hosted runner can do multicast on loopback is the one thing about this
  # suite that could not be verified before it was written, so isolating it
  # means such a runner fails this job precisely instead of taking the whole
  # integration suite down with an unrelated-looking error. And the real-binary
  # test binds the test broker to all interfaces, which should happen only when
  # discovery testing was asked for — `make test-integration` skips it.
  #
  # SQI_TEST_REQUIRE_MULTICAST=1 (set by `make test-discovery`) turns the
  # capability skip into a failure, so this job cannot go green while covering
  # nothing — the same guard ldap-integration and isolation-integration use.
  discovery-integration:
    name: mDNS discovery (real multicast)
    runs-on: ubuntu-latest
    needs: test
    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up Go
        uses: actions/setup-go@v7
        with:
          go-version-file: go.mod
          cache: true

      # The advertisement carries "<hostname>.local", which the worker dials.
      # macOS answers that through mDNSResponder; a stock ubuntu runner has no
      # mDNS NSS module, so the worker would discover the server and then fail
      # to dial it.
      #
      # A hosts entry rather than libnss-mdns + avahi: avahi-daemon would want
      # port 5353, which is the port the test's own responder binds, so
      # installing it to fix resolution risks breaking advertisement. Mapping
      # the name to loopback needs no daemon and cannot conflict.
      - name: Resolve this host's mDNS name locally
        run: |
          echo "127.0.0.1 $(hostname).local" | sudo tee -a /etc/hosts
          getent hosts "$(hostname).local" || {
            echo "::error::$(hostname).local still does not resolve"; exit 1; }

      # Two things a Linux loopback lacks that macOS lo0 has by default, and the
      # loopback-only advertisement needs both. The tests advertise on loopback
      # only — deliberately, so a run never announces a service on the network it
      # happens to be on — and refuse to fall back to a real interface, so
      # neither of these can be skipped: without them the suite cannot run at all.
      #
      #  1. The MULTICAST flag. Linux `lo` ships without it, and the tests select
      #     their interfaces by that flag, so an untouched `lo` looks to them like
      #     a host that cannot do multicast.
      #  2. A non-loopback address. zeroconf fills the advertisement's address
      #     records from the interface's own addresses and discards loopback ones
      #     (addrsForInterface: `!ipnet.IP.IsLoopback()`); a Linux `lo` carries
      #     only 127.0.0.1 and ::1, so registering on loopback alone fails
      #     outright with "Could not determine host IP addresses". macOS lo0 also
      #     carries fe80::1, which is the whole reason this never shows up there.
      #     Adding that same link-local address makes the two behave alike — it
      #     is scoped to the link and is not routed anywhere.
      - name: Prepare loopback for mDNS
        run: |
          ip -o addr show lo
          sudo ip link set lo multicast on
          ip link show lo | grep -q MULTICAST || {
            echo "::error::could not enable MULTICAST on lo"; exit 1; }
          sudo ip -6 addr add fe80::1/64 dev lo || true
          ip -o -6 addr show lo scope link | grep -q fe80 || {
            echo "::error::lo has no link-local address, so a loopback-only mDNS"
            echo "::error::advertisement cannot register — see the comment above"
            exit 1; }

      - name: Run the discovery suite over real multicast
        run: |
          set +e
          make test-discovery 2>&1 | tee discovery-output.log
          status=${PIPESTATUS[0]}
          set -e

          expected=(
            TestDiscovery_TLSRecordsCrossTheWire
            TestDiscovery_AdvertisedBrokerTLSReachesWorkerConfig
            TestDiscovery_RealBinaryFindsItsServerOverMDNS
          )
          missing=0
          for name in "${expected[@]}"; do
            if ! grep -q -- "--- PASS: $name" discovery-output.log; then
              echo "::error::$name did not pass"
              missing=1
            fi
          done
          if [ "$status" -ne 0 ] || [ "$missing" -ne 0 ]; then
            echo "::error::the mDNS discovery suite did not pass (exit=$status)."
            echo "::error::if the runner cannot do multicast, the suite says so explicitly."
            exit 1
          fi
          echo "Confirmed all ${#expected[@]} discovery tests passed over real multicast."

  # Runs the official OpenJD conformance suite (a pinned submodule under
  # third_party/) against internal/openjd. Tagged `conformance`, so it does not
  # run in the default `make test`.
  #
  # IMPORTANT: the assertion step below is not redundant. `make test-conformance`
  # would report success if the walker collected zero fixtures, so this job does
  # not trust the exit code alone — it requires the test names in the output,
  # the same guard ldap-integration and isolation-integration use.
  #
  # It listed four names until sub-project H2 made EXPR a supported extension:
  # TestConformance_Expressions (the second, EXPR-only scoring path) and
  # TestConformance_EXPRNotSupported (its drift guard) were both deleted with
  # that path, and TestConformance_Templates now scores EXPR/job_templates
  # itself. TestConformance_E3ProtectedFixtures takes the fourth slot — it is
  # the one that asserts named EXPR fixtures by their exact rejection message,
  # so requiring it keeps a zero-fixture run from looking green.
  conformance:
    name: OpenJD conformance
    runs-on: ubuntu-latest
    needs: test

    steps:
      - name: Check out the repository and the conformance suite
        uses: actions/checkout@v7
        with:
          submodules: true

      - name: Set up Go
        uses: actions/setup-go@v7
        with:
          go-version-file: go.mod

      - name: Run the official OpenJD conformance suite
        shell: bash
        run: make test-conformance 2>&1 | tee /tmp/conformance.log

      - name: Assert the suite actually ran
        run: |
          grep -q -- '--- PASS: TestConformance_SuitePresent' /tmp/conformance.log
          grep -q -- '--- PASS: TestConformance_Templates' /tmp/conformance.log
          grep -q -- '--- PASS: TestConformance_E3ProtectedFixtures' /tmp/conformance.log

  # Differential-tests internal/openjd/expr against the implementation the EXPR
  # specification names as its reference — the openjd.expr namespace of
  # openjd-model, which is a thin re-export layer over a compiled Rust crate
  # rather than a Python implementation. Tagged `oracle`, so it does not run in
  # the default `make test`.
  #
  # ── ffmpeg reference presets: execute them ───────────────────────────────────
  # The shipped ffmpeg presets (presets/sqi/ffmpeg-*.yaml) are covered three
  # ways: internal/product validates them against the schema, exprpresetcost
  # pins the portable variant's submission cost, and test/integration runs them
  # through a real server and worker and probes the video they produce. Only the
  # third can see a command line that parses perfectly and transcodes nothing —
  # the class of bug that produced two fixes on the branch that introduced these
  # presets (a BOM'd concat list, and an embedded join script with no .ps1
  # filename), both found by reading rather than by testing.
  #
  # This job exists because that third layer SKIPS without ffmpeg and ffprobe on
  # PATH, and nothing installs them: inside `make test-cover` those tests would
  # skip silently and the `test` job would stay green having executed no ffmpeg
  # at all. Installing the binaries and then requiring each PASS line by name is
  # the same guard conformance, expr-oracle, ldap-integration and
  # isolation-integration use.
  #
  # Linux is where the bash-joined variant's coverage is REQUIRED by name below.
  # That variant no longer gates on an OS -- bash is not POSIX-only, git-bash
  # puts it on Windows too -- so it also runs on the Windows job, but only
  # opportunistically there (see that job's own note). The PowerShell-gated
  # variant has its own job below (ffmpeg-presets-windows), because it can run
  # nowhere but a Windows runner.
  ffmpeg-presets:
    name: ffmpeg reference presets (execution)
    runs-on: ubuntu-latest
    needs: test

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up Go
        uses: actions/setup-go@v7
        with:
          go-version-file: go.mod

      # Explicit rather than relying on the runner image: ffmpeg being present
      # by accident is an undeclared dependency that disappears on an image
      # bump, and its absence is silent here by construction.
      - name: Install ffmpeg
        run: |
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends ffmpeg
          ffmpeg -version | head -1
          ffprobe -version | head -1

      - name: Execute the ffmpeg presets end to end
        shell: bash
        run: |
          go test -run TestFFmpegPreset -v -timeout 900s ./test/integration/ 2>&1 \
            | tee /tmp/ffmpeg-presets.log

      # Each case is named individually so that a preset losing its coverage --
      # by being skipped, renamed, or deleted -- fails here rather than
      # shrinking the suite quietly. The two PowerShell-gated and
      # Windows-skipped cases are deliberately absent.
      - name: Assert every linux-runnable case actually ran
        run: |
          for name in \
            TestFFmpegPreset_TranscodeProducesPlayableOutput \
            TestFFmpegPreset_PortableSegmentTranscodeJoins \
            TestFFmpegPreset_BashSegmentTranscodeJoins \
            TestFFmpegPreset_SegmentCountUsesCeilingNotTruncation \
            TestFFmpegPreset_SliceNamesAreZeroPadded \
            TestFFmpegPreset_PortableRejectsBeyondItsCostCeiling \
            TestFFmpegPreset_SequenceEncodeNamesOutputAfterPattern \
          ; do
            grep -q -- "--- PASS: ${name}" /tmp/ffmpeg-presets.log \
              || { echo "::error::${name} did not run to a PASS"; exit 1; }
          done

  # ── ffmpeg reference presets: the Windows-gated variant ──────────────────────
  # ffmpeg-segment-transcode-powershell gates on attr.worker.os.family = windows,
  # so a Windows runner is the ONLY place its join script can execute at all —
  # every other job in this workflow skips it by construction. That script has
  # already shipped two bugs a real run would have caught immediately and review
  # by reading did not: a BOM'd concat list the demuxer rejects, and an embedded
  # file with no .ps1 extension, which `powershell -File` refuses outright.
  #
  # Its own job rather than a step on cross-platform-runtime, for two reasons:
  # that job is a REST/WebSocket smoke test with a different purpose, and it is a
  # macOS+Windows matrix — a preset-only PR would pay for a macOS leg that skips
  # every case here.
  #
  # Runs on every push, and on pull requests only when the presets filter fires.
  # isolation-integration-windows already runs a windows-latest job on every PR
  # unconditionally, so a filtered one costs strictly less than the precedent.
  ffmpeg-presets-windows:
    name: ffmpeg reference presets (execution, windows)
    runs-on: windows-latest
    needs: [test, changes]
    if: ${{ github.event_name != 'pull_request' || needs.changes.outputs.presets == 'true' }}

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up Go
        uses: actions/setup-go@v7
        with:
          go-version-file: go.mod

      - name: Install ffmpeg
        run: choco install ffmpeg --yes --no-progress

      # bash (Git Bash, present on every windows runner) so the pipeline and the
      # grep assertion below are the same shell as the Linux job's.
      - name: Execute the ffmpeg presets end to end
        shell: bash
        run: |
          ffmpeg -version | head -1
          go test -run TestFFmpegPreset -v -timeout 900s ./test/integration/ 2>&1 \
            | tee /tmp/ffmpeg-presets-windows.log

      # Only the PowerShell case is required by name. The rest are already
      # required by name on the Linux job, and duplicating them would make this
      # job fail for reasons that have nothing to do with Windows.
      #
      # TestFFmpegPreset_BashSegmentTranscodeJoins is the interesting omission.
      # Its preset dropped its linux/macos gate (git-bash means bash is not
      # POSIX-only), so it no longer skips here by construction -- it runs, and
      # if its join fails on Windows the `go test` step above goes red, which is
      # exactly the coverage that change needs. It is NOT required by name yet
      # because it skips when `bash.exe` is not resolvable by Windows PATH
      # lookup from the worker process, and that has not been observed on this
      # runner image: requiring it now would turn the job red for an
      # environmental reason rather than a real one. Promote it to the list once
      # a run here is seen to PASS rather than SKIP.
      - name: Assert the PowerShell join actually ran
        shell: bash
        run: |
          grep -q -- '--- PASS: TestFFmpegPreset_PowerShellSegmentTranscodeJoins' \
            /tmp/ffmpeg-presets-windows.log \
            || { echo "::error::the PowerShell-joined preset did not run to a PASS"; exit 1; }

  # IMPORTANT: the assertion step below is not redundant. `make test-expr-oracle`
  # exits 0 when no interpreter has the package importable, and the test itself
  # SKIPS in that case — so a green job would otherwise prove nothing at all.
  # Requiring the PASS line is the same guard conformance, ldap-integration and
  # isolation-integration use.
  #
  # One arch: the corpus exercises expression semantics, and no arch divergence
  # is plausible for either side (Go's evaluator is pure Go; the reference ships
  # as an abi3 wheel built per-arch by upstream).
  expr-oracle:
    name: EXPR reference-implementation oracle
    runs-on: ubuntu-latest
    needs: test

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up Go
        uses: actions/setup-go@v7
        with:
          go-version-file: go.mod

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

      - name: Run the differential test against the OpenJD reference
        shell: bash
        run: make test-expr-oracle 2>&1 | tee /tmp/expr-oracle.log

      - name: Assert the oracle actually ran
        run: |
          grep -q -- '--- PASS: TestExprOracle_MatchesReferenceImplementation' /tmp/expr-oracle.log

  # ── Python client: lint + type-check ─────────────────────────────────────────
  # ruff and mypy are driven by config/target versions (mypy targets the 3.9
  # floor for src and 3.13 for tests via flags), not by the interpreter they run
  # on, so they run once on a single Python rather than across the matrix. (A
  # matrix here would only vary the resolved mypy *version*, which is noise.)
  python-lint:
    name: Python client lint + type-check
    runs-on: ubuntu-latest
    needs: changes
    if: ${{ needs.changes.outputs.python == 'true' || github.event_name == 'workflow_dispatch' }}
    defaults:
      run:
        working-directory: clients/python
    steps:
      - name: Checkout
        uses: actions/checkout@v7

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

      - name: Install client with all extras
        run: pip install -e '.[yaml,ws,dev]'

      - name: Ruff format check
        run: ruff format --check .

      - name: Ruff lint
        run: ruff check .

      # src is type-checked at the 3.9 floor (pyproject python_version); the
      # tests are checked at a newer target where they are allowed to run.
      - name: mypy
        run: mypy src && mypy --python-version=3.13 tests

  # ── Python client: unit tests ────────────────────────────────────────────────
  # Runtime behavior is what genuinely varies by interpreter, so the unit suite
  # (with its coverage gate) runs across the supported range: 3.9 floor through
  # the latest stable.
  python-test:
    name: Python client tests (${{ matrix.python-version }})
    runs-on: ubuntu-latest
    needs: changes
    if: ${{ needs.changes.outputs.python == 'true' || github.event_name == 'workflow_dispatch' }}
    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
    defaults:
      run:
        working-directory: clients/python
    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v7
        with:
          python-version: ${{ matrix.python-version }}
          cache: pip
          cache-dependency-path: clients/python/pyproject.toml

      - name: Install client with all extras
        run: pip install -e '.[yaml,ws,dev]'

      - name: Unit tests with coverage gate
        run: pytest

  # ── Python client: integration tests ─────────────────────────────────────────
  # Boots the real sqi-server/sqi-worker binaries (downloaded from the test job)
  # and runs the @pytest.mark.integration suite. One interpreter is sufficient.
  python-integration:
    name: Python client integration tests
    runs-on: ubuntu-latest
    needs: [changes, test]
    if: ${{ needs.changes.outputs.python == 'true' || github.event_name == 'workflow_dispatch' }}
    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Download server/worker binaries
        uses: actions/download-artifact@v8
        with:
          name: binaries
          path: bin

      - name: Make binaries executable
        run: chmod +x bin/sqi-server bin/sqi-worker

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

      - name: Install client with all extras
        working-directory: clients/python
        run: pip install -e '.[yaml,ws,dev]'

      # The harness finds the binaries at <repo-root>/bin by default; --no-cov
      # because the integration subset alone does not meet the unit coverage gate.
      - name: Integration tests
        working-directory: clients/python
        run: pytest -m integration --no-cov

  # ── Python client: package build check ───────────────────────────────────────
  # Builds the sdist + wheel and validates the metadata, so a broken package
  # fails the PR rather than the release.
  python-package:
    name: Python client package check
    runs-on: ubuntu-latest
    needs: changes
    if: ${{ needs.changes.outputs.python == 'true' || github.event_name == 'workflow_dispatch' }}
    defaults:
      run:
        working-directory: clients/python
    steps:
      - name: Checkout
        uses: actions/checkout@v7

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

      - name: Install build tooling
        run: python -m pip install --upgrade build twine

      - name: Build sdist + wheel
        run: python -m build

      - name: Check package metadata
        run: twine check dist/*

  # ── Submitter client: lint + type-check ──────────────────────────────────────
  # Mirrors python-lint above: ruff and mypy run once on a single Python rather
  # than across the matrix. The local sqi-sdk checkout is installed first (`pip
  # install -e ../python`) so the submitter's `sqi-sdk>=0.1` dependency resolves
  # to the in-repo package, never a published PyPI release.
  submitter-lint:
    name: Submitter client lint + type-check
    runs-on: ubuntu-latest
    needs: changes
    if: ${{ needs.changes.outputs.submitter == 'true' || github.event_name == 'workflow_dispatch' }}
    defaults:
      run:
        working-directory: clients/submitter
    steps:
      - name: Checkout
        uses: actions/checkout@v7

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

      - name: Install local sqi-sdk + submitter with dev extras
        run: pip install -e ../python -e '.[dev]'

      - name: Ruff format check
        run: ruff format --check .

      - name: Ruff lint
        run: ruff check .

      # src is type-checked at the 3.9 floor (pyproject python_version); the
      # tests are checked at a newer target where they are allowed to run.
      - name: mypy
        run: mypy src && mypy --python-version=3.13 tests

  # ── Submitter client: unit tests ─────────────────────────────────────────────
  # Runtime behavior is what genuinely varies by interpreter, so the unit suite
  # (with its coverage gate) runs across the supported range: 3.9 floor through
  # the latest stable.
  submitter-test:
    name: Submitter client tests (${{ matrix.python-version }})
    runs-on: ubuntu-latest
    needs: changes
    if: ${{ needs.changes.outputs.submitter == 'true' || github.event_name == 'workflow_dispatch' }}
    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
    defaults:
      run:
        working-directory: clients/submitter
    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v7
        with:
          python-version: ${{ matrix.python-version }}
          cache: pip
          cache-dependency-path: clients/submitter/pyproject.toml

      - name: Install local sqi-sdk + submitter with dev extras
        run: pip install -e ../python -e '.[dev]'

      - name: Unit tests with coverage gate
        run: pytest

  # ── Submitter client: Qt widget tests ────────────────────────────────────────
  # PySide6 widget/dialog tests are excluded from the main coverage-gated suite
  # (see pyproject.toml tool.coverage.run.omit) and run separately here, headless
  # via Qt's offscreen platform plugin. One interpreter is sufficient — this is
  # exercising Qt binding behavior, not sqi-submitter's own version matrix.
  submitter-qt-test:
    name: Submitter client Qt widget tests
    runs-on: ubuntu-latest
    needs: changes
    if: ${{ needs.changes.outputs.submitter == 'true' || github.event_name == 'workflow_dispatch' }}
    defaults:
      run:
        working-directory: clients/submitter
    steps:
      - name: Checkout
        uses: actions/checkout@v7

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

      # PySide6's offscreen QPA platform plugin needs a few system libraries
      # that ubuntu-latest runners do not ship by default. libegl1 + libgl1
      # satisfy Qt's GL loader, libxkbcommon0 satisfies the keyboard/input
      # abstraction the offscreen plugin still initializes.
      - name: Install PySide6 offscreen platform dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends libegl1 libgl1 libxkbcommon0

      - name: Install local sqi-sdk + submitter with dev,qt extras
        run: pip install -e ../python -e '.[dev,qt]'

      - name: Qt widget + dialog tests (offscreen)
        env:
          QT_QPA_PLATFORM: offscreen
        run: pytest tests/test_qt_widgets.py tests/test_qt_dialog.py --no-cov