ci.yml

name: CI

# Phase 02.2 — early 3-OS build + render-smoke regression net.
# Triggers (D-10): push + pull_request on the milestone branches ONLY — not all
# branches (keeps CI noise down). `master` is the eventual merge target;
# `v1.6-modernization` is the active milestone branch.
on:
  push:
    branches: [master, v1.6-modernization, v1.7-modernization, v1.7.1-modernization]
    # Docs-only commits don't change build inputs — skip the full 4-OS rebuild
    # (saves ~45-60 min of runner time per ROADMAP/CLAUDE.md push). Source-of-
    # truth for "what affects the build" is anything outside .planning/ and
    # top-level .md files. The list is paths-IGNORE (deny-list) rather than
    # paths (allow-list) so any new code dir is in-scope by default — fail-safe
    # toward retriggering, not toward skipping.
    paths-ignore:
      - '.planning/**'
      - '**.md'
      - 'LICENSE*'
      - 'doc/**'
  pull_request:
    branches: [master, v1.6-modernization, v1.7-modernization, v1.7.1-modernization]
    paths-ignore:
      - '.planning/**'
      - '**.md'
      - 'LICENSE*'
      - 'doc/**'

  # CI-HARDEN-W1 (Stage 2.5 — v1.7-PLAN.md): weekly cross-platform run
  # catches Windows/Linux surprises BEFORE Stage 3 closure-gate promotion.
  # Cheaper than full-matrix-always; eliminates the v1.6.2-style closure
  # crunch by warming Windows + ARM Linux every Monday morning UTC.
  schedule:
    - cron: '0 6 * * 1'

  # Manual trigger — any maintainer can force a full-matrix run before
  # high-risk phase work, e.g. before tagging an RC. Choose extra-matrix
  # axes via input if needed in the future.
  workflow_dispatch:

# Read-only token: this workflow only builds + checks, it never writes back.
permissions:
  contents: read

# One in-flight run per ref — a newer push cancels the older run so pushes
# don't pile up on the hosted runners.
concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  # --------------------------------------------------------------------------
  # detect-platforms — CI-HARDEN-W1 (v1.7-PLAN Stage 2.5).
  #
  # Computes which OS matrix entries to dispatch based on the trigger:
  #   - Stage 1 default (push/PR on v1.7-modernization): macOS only
  #   - Schedule (weekly Monday 06:00 UTC): full matrix (macOS + Linux + Windows)
  #   - workflow_dispatch (manual): full matrix
  #   - push/PR touching high-risk paths (cmake/, ci.yml, vcpkg.json, CIFParser,
  #     atom.h, VIEW/, CMakeLists.txt): full matrix
  #   - master, v1.6-modernization branches: full matrix (legacy + maintenance)
  #
  # The high-risk paths list is the empirical surface where cross-platform
  # regressions historically hide:
  #   - cmake/**, CMakeLists.txt, CMakePresets.json   build system
  #   - .github/workflows/**                          CI workflow itself
  #   - vcpkg.json                                    Windows dep graph
  #   - source/FORMAT/CIFParser*                      Bison parser (gcc -Wformat-truncation)
  #   - include/BALL/KERNEL/atom.h                    MSVC C4910 pointer-vector
  #   - include/BALL/VIEW/**, source/VIEW/**          Qt 6 / GL surface
  #
  # The dynamic matrix outputs JSON consumed by the `build` job below via
  # `fromJSON()`. This is the cleanest GHA pattern for trigger-aware matrix
  # composition; matrix-entry-level `if:` is not supported by the runner.
  # --------------------------------------------------------------------------
  detect-platforms:
    name: detect-platforms (CI-HARDEN-W1)
    runs-on: ubuntu-24.04
    outputs:
      matrix: ${{ steps.set.outputs.matrix }}
      cross_platform: ${{ steps.set.outputs.cross_platform }}
    steps:
      # fetch-depth: 0 needed so the path-change diff (next step) can
      # reach the base SHA. dorny/paths-filter@v3 hit "fatal: shallow
      # file has changed since we read it" on the first CI-HARDEN-W1 run
      # (commit 9750fdd) because the default shallow clone (depth 1)
      # can't reach the push event's `before` SHA. Full clone avoids the
      # paths-filter action's internal git-deepen race entirely.
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0
      - id: set
        shell: bash
        run: |
          # Decide whether to dispatch the full matrix. Replaces the
          # earlier dorny/paths-filter@v3 step with explicit git-diff
          # logic for robustness + zero third-party action surface.
          #
          # Phase 999.48 §8.7 step (b) — ui_v2 axis REMOVED. The
          # BALL_UI_V2 flag no longer exists; doubling the matrix on the
          # flag value is dead weight. The remaining axes (macOS-only
          # vs. cross-platform) preserve the Stage 1 / full-matrix
          # dispatch logic unchanged.
          cross_platform="false"
          changed_paths_match="false"

          # Path-aware detection is meaningful only for push + pull_request.
          # schedule, workflow_dispatch, and maintenance branches force full
          # matrix unconditionally below.
          if [[ "${{ github.event_name }}" == "push" ]] || \
             [[ "${{ github.event_name }}" == "pull_request" ]]; then
            if [[ "${{ github.event_name }}" == "pull_request" ]]; then
              BASE_SHA="${{ github.event.pull_request.base.sha }}"
            else
              BASE_SHA="${{ github.event.before }}"
            fi
            # On first-push-to-new-branch the before SHA is all-zeros;
            # in that case there's no diff to compute → force full matrix.
            if [[ "$BASE_SHA" == "0000000000000000000000000000000000000000" ]]; then
              echo "::notice::First push to new branch — forcing cross_platform=true"
              changed_paths_match="true"
            elif ! git rev-parse --verify --quiet "$BASE_SHA" >/dev/null 2>&1; then
              echo "::warning::Base SHA $BASE_SHA not reachable; defaulting to cross_platform=true (safe fallback)"
              changed_paths_match="true"
            else
              CHANGED=$(git diff --name-only "$BASE_SHA" HEAD)
              echo "Changed files in this push:"
              echo "$CHANGED" | sed 's/^/  /'
              # Match against the high-risk path patterns (regex, anchored
              # at start). Any match → cross_platform=true.
              if echo "$CHANGED" | grep -qE '^(cmake/|CMakeLists\.txt|CMakePresets\.json|\.github/workflows/|vcpkg\.json|source/FORMAT/CIFParser|include/BALL/KERNEL/atom\.h|include/BALL/VIEW/|source/VIEW/)'; then
                changed_paths_match="true"
              fi
            fi
          fi

          if [[ "${{ github.event_name }}" == "schedule" ]] || \
             [[ "${{ github.event_name }}" == "workflow_dispatch" ]] || \
             [[ "${{ github.ref_name }}" == "master" ]] || \
             [[ "${{ github.ref_name }}" == "v1.6-modernization" ]] || \
             [[ "$changed_paths_match" == "true" ]]; then
            cross_platform="true"
          fi
          echo "cross_platform=${cross_platform}" >> "$GITHUB_OUTPUT"

          # The macOS entry is ALWAYS included (Stage 1 default).
          # The Linux + Windows entries are added when cross_platform=true.
          MAC_ENTRY='{
            "os": "macos-arm64",
            "runner": "macos-14",
            "blocking": true,
            "smoke": true,
            "ccache_dir": "~/Library/Caches/ccache"
          }'
          LINUX_X64_ENTRY='{
            "os": "linux-x64",
            "runner": "ubuntu-24.04",
            "blocking": true,
            "smoke": true,
            "ccache_dir": "~/.cache/ccache",
            "qt_host": "linux",
            "qt_version": "6.8.*"
          }'
          LINUX_ARM64_ENTRY='{
            "os": "linux-arm64",
            "runner": "ubuntu-24.04-arm",
            "blocking": true,
            "smoke": true,
            "ccache_dir": "~/.cache/ccache",
            "qt_host": "linux_arm64",
            "qt_version": "6.8.*"
          }'
          WINDOWS_ENTRY='{
            "os": "windows-x64",
            "runner": "windows-2025",
            "blocking": true,
            "smoke": false,
            "ccache_dir": "C:\\Users\\runneradmin\\AppData\\Local\\ccache",
            "qt_host": "windows",
            "qt_version": "6.8.*"
          }'
          if [[ "${cross_platform}" == "true" ]]; then
            INCLUDE="[${MAC_ENTRY},${LINUX_X64_ENTRY},${LINUX_ARM64_ENTRY},${WINDOWS_ENTRY}]"
          else
            INCLUDE="[${MAC_ENTRY}]"
          fi

          # Compact + strip newlines so the JSON fits on one line for $GITHUB_OUTPUT
          INCLUDE_ONELINE=$(echo "$INCLUDE" | jq -c '.' | tr -d '\n')
          echo "matrix={\"include\":${INCLUDE_ONELINE}}" >> "$GITHUB_OUTPUT"
          echo "::notice::cross_platform=${cross_platform}; matrix dispatch:"
          echo "$INCLUDE_ONELINE" | jq -r '.[] | "  - " + .os' || echo "$INCLUDE_ONELINE"

  # --------------------------------------------------------------------------
  # build — the dynamic-matrix Release build (D-07, D-11).
  #
  # Matrix shape now driven by detect-platforms above. macOS always runs
  # (Stage 1 default); Linux + Windows run on schedule, workflow_dispatch,
  # high-risk-path push/PR, or maintenance branches.
  # --------------------------------------------------------------------------
  build:
    needs: detect-platforms
    name: build (${{ matrix.os }})
    runs-on: ${{ matrix.runner }}
    # D-03: continue-on-error driven off matrix.blocking. macOS/Linux/Windows
    # are all "blocking: true" in the JSON above; the field is preserved so
    # future axes (e.g. spike backends) can flip without rewriting downstream.
    continue-on-error: ${{ !matrix.blocking }}
    # Phase 999.16 (BUILD-ACCEL-01): ccache + PCH compatibility requires these
    # sloppiness keys. Without them, PCH-enabled builds silently bust ccache hits.
    # See cmake/PCH.md §"ccache sloppiness contract" for per-flag rationale.
    #
    # v1.7.0-rc2 fix (2026-05-18): include the generated config.h in
    # CCACHE_EXTRAFILES so PROJECT VERSION bumps (and any other CMake-
    # configured macros) properly invalidate cached compilations. Without
    # this the VersionInfo_test fails after a version bump because libBALL
    # is rebuilt from cache against the OLD BALL_RELEASE_STRING while the
    # test TU compiles fresh against the NEW one. Diagnosed from CI run
    # 26016813212 linux-x64 build (test #6/295 VersionInfo_test FAILED).
    env:
      CCACHE_SLOPPINESS: "pch_defines,time_macros,include_file_mtime"
      CCACHE_EXTRAFILES: "${{ github.workspace }}/include/BALL/CONFIG/config.h.in"
    strategy:
      # Don't let one OS failing cancel the others — we want the full picture.
      fail-fast: false
      matrix: ${{ fromJSON(needs.detect-platforms.outputs.matrix) }}

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

      # ----------------------------------------------------------------------
      # ccache (D-06, D-11) — warm the compiler cache across runs. The configure
      # steps below wire CMAKE_<LANG>_COMPILER_LAUNCHER=ccache.
      # ----------------------------------------------------------------------
      - name: Cache ccache
        uses: actions/cache@v5
        with:
          path: ${{ matrix.ccache_dir }}
          # Phase 999.48 §8.7 step (b) — ui_v2 suffix removed from the
          # cache key with the BALL_UI_V2 flag's removal. Single-cell
          # per OS now reuses the same line every build.
          # v1.7.0-rc2 (2026-05-18) — bump cache key prefix v1 → v2 to
          # invalidate 1.6.0-era cached object files that survived the
          # PROJECT VERSION 1.6.0 → 1.7.0 bump and caused
          # VersionInfo_test to fail on Linux. Paired with the
          # CCACHE_EXTRAFILES addition above for the long-term fix.
          key: ccache-${{ matrix.os }}-pch-v2-${{ github.sha }}
          restore-keys: |
            ccache-${{ matrix.os }}-pch-v2-
            ccache-${{ matrix.os }}-

      # Phase 999.17 (BUILD-ACCEL-02): cache the Windows CMake build tree so warm-cache
      # Configure step skips the 2m32s vcpkg+CMake-configure rebuild when nothing
      # structural changed (CMakeLists.txt / cmake/** / vcpkg.json / CMakePresets.json).
      # Cache scope is the configure-output set ONLY — object files come from ccache,
      # not from this cache. Windows-only; macOS+Linux configure in <30s already.
      # ci.yml itself is NOT in hashFiles() — editing this comment triggers a warm run
      # that exercises the cache-HIT path without invalidating the cmake-tree key.
      - name: Cache Windows vcpkg deps
        if: matrix.os == 'windows-x64'
        uses: actions/cache@v5
        with:
          # Cache ONLY vcpkg_installed/ — the expensive Boost/FFTW/etc. build.
          # Do NOT cache CMakeCache.txt / CMakeFiles/ / build.ninja: those embed
          # the absolute MSVC compiler path (e.g. .../MSVC/14.44.35207/.../cl.exe),
          # while the key below hashes only source files, not the runner image.
          # When GitHub bumps the windows runner image (the 2026-06-15 windows-2025
          # → vs2026 migration bumped MSVC past 14.44.35207), the pinned compiler
          # path disappears and a restored CMakeCache makes PROJECT() fail with
          # "not a full path to an existing compiler tool" (see scheduled run
          # 27544121035). Letting CMake re-detect the compiler each run — cheap
          # once vcpkg_installed is warm; objects still come from the separate
          # ccache — eliminates that whole failure class. (Supersedes the deferred
          # Phase 999.36 per-source-hash invalidation idea, which this makes moot.)
          # v3: drops the compiler-pinned paths from v2 and invalidates poisoned
          # entries left by the runner-image bump.
          path: |
            build/ci-windows/vcpkg_installed/
          key: ci-windows-vcpkg-v3-${{ hashFiles('vcpkg.json', 'CMakePresets.json') }}
          restore-keys: |
            ci-windows-vcpkg-v3-

      # ======================================================================
      # macOS — Homebrew deps + the verbatim BUILD-macos.md flow.
      # ======================================================================
      - name: Cache Homebrew downloads (macOS)
        if: matrix.os == 'macos-arm64'
        uses: actions/cache@v5
        with:
          path: ~/Library/Caches/Homebrew
          key: brew-${{ matrix.os }}-${{ hashFiles('.github/workflows/ci.yml') }}
          restore-keys: |
            brew-${{ matrix.os }}-

      - name: Install dependencies (macOS / Homebrew)
        if: matrix.os == 'macos-arm64'
        run: |
          # D-06: the verbatim BUILD-macos.md dependency line + ccache.
          # Phase 5 (Plan 05-01 D-03): Homebrew unversioned `qt` is the Qt 6
          # source (currently 6.11.x, well above the D-01 6.5 floor). The
          # `macos-homebrew` CMake preset's CMAKE_PREFIX_PATH already points
          # at /opt/homebrew/opt/qt (not qt@5) — see Plan 05-01 SUMMARY.
          # Phase 999.2: `ninja` provisioned alongside ccache — the ci-macos
          # preset now declares "generator": "Ninja" so `ninja` must be on PATH
          # at configure time. Homebrew installs ninja as `/opt/homebrew/bin/ninja`
          # which is already on the runner PATH.
          brew install qt boost eigen fftw tbb glew open-babel lp_solve libsvm flex bison
          brew install ccache ninja

      - name: Configure (macOS)
        if: matrix.os == 'macos-arm64'
        run: |
          # D-07: preset is the single source of truth — mirrors BUILD-macos.md.
          # bison/flex executable paths are embedded in the ci-macos preset.
          # -DBALL_LICENSE=GPL: OpenBabel is GPL-gated (maintainer decision, Plan 04-01).
          # BALL_HAS_OPENBABEL=ON is already in the ci-macos preset's cacheVariables
          # (Plan 04-02) — the -DBALL_LICENSE=GPL flag is what actually enables the
          # GPL-block FIND_PACKAGE(OpenBabel3) call in CMakeLists.txt (Plan 04-03).
          # Phase 999.48 §8.7 step (b) — -DBALL_UI_V2 axis flag dropped here
          # with the BALL_UI_V2 CMake option removal.
          cmake --preset ci-macos -DBALL_LICENSE=GPL

      - name: Build (macOS)
        if: matrix.os == 'macos-arm64'
        run: |
          # D-07: the BUILD-macos.md target set, Release.
          # Phase 999.2: zero ccache stats before the Build, dump them after,
          # so the per-run cache-hit ratio is visible in the workflow log
          # (the warm-vs-cold delta is the key metric for the Ninja switch).
          ccache --zero-stats
          cmake --build --preset ci-macos --target BALL VIEW BALLView -j$(sysctl -n hw.ncpu)
          ccache --show-stats --verbose

      # ----------------------------------------------------------------------
      # Phase 999.19 (BUILD-ACCEL-04): per-TU build profiling instrumentation.
      # Runs after the Build step (even on Build failure) so the artifact is
      # available for diagnosing slow-then-failed runs. Uses bash shell on
      # macOS/Linux, pwsh on Windows. Artifact retention: 90 days.
      # ----------------------------------------------------------------------
      - name: Top-20 slowest TUs (${{ matrix.os }})
        if: (success() || failure()) && matrix.os == 'macos-arm64'
        shell: bash
        run: |
          # Disable pipefail for this block — `sort -rn | head -20` causes
          # `sort` to receive SIGPIPE when `head` exits after 20 lines, and
          # under GH Actions bash's default pipefail this becomes exit code
          # 2 which fails the step (and the whole job, now that ARM is
          # blocking). The telemetry itself is purely informational.
          set +o pipefail
          if [ -f build/ci-macos/.ninja_log ]; then
            echo "=== Top-20 slowest TUs (${{ matrix.os }}) ==="
            # ninja log v7: start_ms TAB end_ms TAB mtime TAB output_path TAB cmd_hash
            # Filter to CMakeFiles/ entries (source files only) to exclude
            # generated files (autogen/mocs_compilation.cpp etc).
            awk -F'\t' 'NF>=5 && $4 ~ /CMakeFiles\// {printf "%8d ms  %s\n", $2-$1, $4}' build/ci-macos/.ninja_log \
              | sort -rn | head -20
          else
            echo "WARN: .ninja_log not found at build/ci-macos/.ninja_log"
          fi

      - name: Upload .ninja_log artifact (${{ matrix.os }})
        if: (success() || failure()) && matrix.os == 'macos-arm64'
        uses: actions/upload-artifact@v6
        with:
          # ui_v2 in artifact name: doubled matrix would collide on the
          # shared `ninja-log-<os>-<sha>` key otherwise (actions/upload-
          # artifact@v4+ rejects duplicates).
          name: ninja-log-${{ matrix.os }}-${{ github.sha }}
          path: build/ci-macos/.ninja_log
          retention-days: 90
          include-hidden-files: true

      # ----------------------------------------------------------------------
      # Phase 9 gatekeeper (BLOCKING — TEST-CLOSE-02) — the BALL unit-test
      # tree (`test/`, 295 files) is now a load-bearing CI gate on macOS +
      # Linux. Three baseline failures triaged in 09-TRIAGE.md (Phase 9,
      # 2026-05-16): Directory_test KNOWN-PASSING; AmberFF_test FIX (ARM FP
      # tolerance); AssignBondOrderProcessor_test2 QUARANTINE (WILL_FAIL TRUE).
      # Windows test gatekeeper landed in Phase 999.34 (see Windows block below).
      # ----------------------------------------------------------------------
      # TEST-CLOSE-02 (Phase 9, 2026-05-16): gatekeeper flipped to blocking
      # after 3 baseline failures triaged in 09-TRIAGE.md.
      - name: Build BALL test suite (macOS — Phase 9 gatekeeper, blocking)
        if: matrix.os == 'macos-arm64'
        continue-on-error: false
        timeout-minutes: 45
        run: |
          cmake --build build/ci-macos --target build_tests -j$(sysctl -n hw.ncpu)

      # TEST-CLOSE-02 (Phase 9, 2026-05-16): gatekeeper flipped to blocking
      # after 3 baseline failures triaged in 09-TRIAGE.md.
      - name: Run BALL test suite (macOS — Phase 9 gatekeeper, blocking)
        if: matrix.os == 'macos-arm64'
        continue-on-error: false
        timeout-minutes: 60
        run: |
          cd build/ci-macos
          # BALL_DATA_PATH MUST be set so tests find FragmentDB, force-field
          # parameter files, rotamer libraries, etc. v1.6.0 local baseline:
          # 50/294 fail without it (= "data path unset" noise), 3/294 fail
          # with it (= actual triage candidates: Directory_test, AmberFF_test,
          # AssignBondOrderProcessor_test2 — Phase 9 main work).
          # --timeout 120 caps individual hangs (most BALL tests run in <10s;
          # ScoringFunction_test + AssignBondOrderProcessor_test{1,2} have
          # 2h timeouts set in test/CMakeLists.txt and will hit this cap —
          # acceptable for the gatekeeper, Phase 9 decides which to skip).
          export BALL_DATA_PATH="${{ github.workspace }}/data"
          # TEST-CLOSE-02: || true removed — this step is now blocking.
          # ctest exits non-zero if any non-WILL_FAIL test fails.
          # ui_v2 in the JUnit filename so ON + OFF cells don't clobber each
          # other's output (each cell runs on its own runner so the file
          # collision would only manifest at the test-report job which
          # `merge-multiple`s these — same-name files would race).
          ctest --output-on-failure --timeout 120 \
                --output-junit ${{ github.workspace }}/ball-tests-macos.xml

      - name: Upload test results (macOS)
        if: always() && matrix.os == 'macos-arm64'
        uses: actions/upload-artifact@v6
        with:
          name: ball-tests-macos-${{ github.run_id }}
          path: ball-tests-macos.xml
          if-no-files-found: warn
          retention-days: 30

      # ======================================================================
      # Linux — apt deps + the BUILD-macos.md flow adapted to Linux paths.
      # ======================================================================
      - name: Cache apt archives (Linux)
        if: startsWith(matrix.os, 'linux-')
        uses: actions/cache@v5
        with:
          # Phase 5.1 Plan 12 (Task D3): scope the cached path to `*.deb` only.
          # Caching the full `/var/cache/apt/archives` directory was triggering a
          # post-job warning on every Linux run:
          #   /usr/bin/tar: ../../../../../var/cache/apt/archives/lock: Cannot open: Permission denied
          #   /usr/bin/tar: ../../../../../var/cache/apt/archives/partial: Cannot open: Permission denied
          #   ##[warning]Failed to save: "/usr/bin/tar" failed ... exit code 2
          # The runner is unprivileged; APT's exclusive lock file and partial/
          # subdirectory are root-only (0640 / 0700), so tar fails on them. The
          # cache action's fallback re-tars without the unreadable entries and
          # the cache *is* still saved ("Cache saved with key: ..." follows the
          # warning), so this was definitionally cosmetic — but the warning
          # surfaced on 7/7 recent successful runs (chronic recurrence, not
          # transient). Narrowing the cached path to the .deb archives — which
          # is the only content `apt-get install` actually downloads and the
          # only content the cache restore needs — silences the warning by
          # construction and avoids the slower fallback tar pass.
          path: /var/cache/apt/archives/*.deb
          key: apt-${{ matrix.os }}-${{ hashFiles('.github/workflows/ci.yml') }}
          restore-keys: |
            apt-${{ matrix.os }}-

      - name: Install dependencies (Linux / apt)
        if: startsWith(matrix.os, 'linux-')
        run: |
          # D-06: apt equivalents of the Homebrew set, + build tooling + ccache,
          # + xvfb/software-Mesa for the headless render smoke check (D-08).
          #
          # Phase 5 (Plan 05-04): the Qt5 -dev packages (qtbase5-dev /
          # qtbase5-dev-tools / libqt5opengl5-dev / qttools5-dev) are REMOVED.
          # Ubuntu 24.04 apt ships Qt 6.4.2 which is below the D-01 6.5 floor;
          # Qt is installed through jurplel/install-qt-action in the dedicated
          # step below (aqtinstall, pinned to Qt 6.8.*). xvfb + Mesa stay for
          # the headless smoke check; non-Qt deps unchanged.
          # Phase 999.2: `ninja-build` provisioned for the Ninja generator
          # switch — the ci-linux preset now declares "generator": "Ninja".
          # `ninja-build` is in the Ubuntu main archive; apt no-ops cleanly
          # if already present in the runner image. `make` retained for any
          # ad-hoc sub-invocation; harmless under Ninja.
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends \
            cmake make ninja-build g++ ccache \
            libboost-all-dev libeigen3-dev libfftw3-dev libtbb-dev libglew-dev \
            libopenbabel-dev libsvm-dev flex bison \
            xvfb mesa-utils libgl1-mesa-dri
          # NOTE: liblpsolve55-dev is intentionally NOT installed. Ubuntu ships
          # liblpsolve55.a built WITHOUT -fPIC, which cannot be linked into
          # BALL's shared libBALL (ld: "relocation R_X86_64_PC32 ... can not be
          # used when making a shared object"). lp_solve is an OPTIONAL feature
          # (see the Feature Matrix in REQUIREMENTS.md) — Linux CI builds without
          # it; macOS keeps it (Homebrew's lp_solve is fine). Phase 4 (FEAT-01)
          # confirms the per-platform optional-dependency policy.

      - name: Install Qt 6 (Linux — jurplel/install-qt-action / aqtinstall)
        if: startsWith(matrix.os, 'linux-')
        # D-01 + D-02 (Plan 05-04): Ubuntu 24.04 apt ships Qt 6.4.2, below the
        # D-01 6.8 LTS floor (revised 2026-05-16, was 6.5). jurplel/install-qt-action wraps aqtinstall and
        # downloads the official Qt build from download.qt.io into the runner
        # workspace; the install location is exposed as Qt6_DIR so CMake's
        # FIND_PACKAGE(Qt6 6.5 ...) resolves cleanly.
        #
        # `modules:` is intentionally omitted. aqt v3.3.0 on Qt 6.8 LTS rejects
        # qtbase, qtopengl, AND qttools as module names — they are all part of
        # the default Qt 6 install on Linux, not separately-installable add-on
        # modules. BALL's actual Qt 6 requirements (Core, Network, Xml, OpenGL,
        # PrintSupport, Test, Widgets, OpenGLWidgets, LinguistTools) are all
        # in the default install, so no `modules:` entry is needed.
        # Phase 5.1 carry-forward: this finding came from CI runs 25925481471
        # and 25934288544 where aqt rejected each module list in turn.
        # D-05: NO qt5compat — clean break.
        uses: jurplel/install-qt-action@v4
        with:
          # matrix.qt_version = '6.8.*' on both x86_64 and ARM (post-2026-05-16
          # D-01 floor revision). matrix.qt_host = 'linux' / 'linux_arm64'.
          # Both pull official Qt 6.8+ desktop binaries from download.qt.io
          # — Qt 6.8 is the first version with Linux ARM64 desktop binaries.
          version: ${{ matrix.qt_version }}
          host: ${{ matrix.qt_host }}
          target: 'desktop'
          cache: true

      - name: Configure (Linux)
        if: startsWith(matrix.os, 'linux-')
        run: |
          # D-07: preset is the single source of truth for Linux paths.
          # bison/flex at /usr/bin, USE_LPSOLVE=OFF (non-PIC liblpsolve55.a),
          # ccache, and BALL_HAS_OPENBABEL=ON are all set by ci-linux preset.
          # -DBALL_LICENSE=GPL: OpenBabel is GPL-gated (maintainer decision, Plan 04-01).
          #: see macOS Configure step + the
          # detect-platforms job comment for axis rationale + drop conditions.
          cmake --preset ci-linux -DBALL_LICENSE=GPL

      - name: Build (Linux)
        if: startsWith(matrix.os, 'linux-')
        run: |
          # D-07: the BUILD-macos.md target set, Release.
          # Phase 999.2: zero ccache stats before / dump after — see the
          # matching block in "Build (macOS)" for rationale.
          ccache --zero-stats
          cmake --build --preset ci-linux --target BALL VIEW BALLView -j$(nproc)
          ccache --show-stats --verbose

      # Phase 999.19 (BUILD-ACCEL-04): per-TU build profiling (Linux).
      - name: Top-20 slowest TUs (${{ matrix.os }})
        if: (success() || failure()) && startsWith(matrix.os, 'linux-')
        shell: bash
        run: |
          # Disable pipefail — see macOS sibling step for rationale.
          # `sort | head` SIGPIPE under default pipefail = step fails =
          # blocking job fails on purely informational telemetry.
          set +o pipefail
          if [ -f build/ci-linux/.ninja_log ]; then
            echo "=== Top-20 slowest TUs (${{ matrix.os }}) ==="
            # ninja log v7: field 4 = output_path, field 5 = cmd_hash.
            awk -F'\t' 'NF>=5 && $4 ~ /CMakeFiles\// {printf "%8d ms  %s\n", $2-$1, $4}' build/ci-linux/.ninja_log \
              | sort -rn | head -20
          else
            echo "WARN: .ninja_log not found at build/ci-linux/.ninja_log"
          fi

      - name: Upload .ninja_log artifact (${{ matrix.os }})
        if: (success() || failure()) && startsWith(matrix.os, 'linux-')
        uses: actions/upload-artifact@v6
        with:
          # ui_v2 in artifact name — see macOS sibling rationale.
          name: ninja-log-${{ matrix.os }}-${{ github.sha }}
          path: build/ci-linux/.ninja_log
          retention-days: 90
          include-hidden-files: true

      # ----------------------------------------------------------------------
      # Phase 9 gatekeeper (BLOCKING — TEST-CLOSE-02) — see macOS counterpart.
      # Windows test gatekeeper landed in Phase 999.34 (see Windows block below).
      # ----------------------------------------------------------------------
      # TEST-CLOSE-02 (Phase 9, 2026-05-16): gatekeeper flipped to blocking
      # after 3 baseline failures triaged in 09-TRIAGE.md.
      - name: Build BALL test suite (Linux — Phase 9 gatekeeper, blocking)
        if: startsWith(matrix.os, 'linux-')
        continue-on-error: false
        timeout-minutes: 45
        run: |
          cmake --build build/ci-linux --target build_tests -j$(nproc)

      # TEST-CLOSE-02 (Phase 9, 2026-05-16): gatekeeper flipped to blocking
      # after 3 baseline failures triaged in 09-TRIAGE.md.
      - name: Run BALL test suite (Linux — Phase 9 gatekeeper, blocking)
        if: startsWith(matrix.os, 'linux-')
        continue-on-error: false
        timeout-minutes: 60
        run: |
          cd build/ci-linux
          # See macOS counterpart — BALL_DATA_PATH is the make-or-break env var.
          export BALL_DATA_PATH="${{ github.workspace }}/data"
          # TEST-CLOSE-02: || true removed — this step is now blocking.
          # ui_v2 in JUnit filename — see macOS sibling.
          ctest --output-on-failure --timeout 120 \
                --output-junit ${{ github.workspace }}/ball-tests-linux.xml

      - name: Upload test results (Linux)
        if: always() && startsWith(matrix.os, 'linux-')
        uses: actions/upload-artifact@v6
        with:
          name: ball-tests-linux-${{ github.run_id }}
          path: ball-tests-linux.xml
          if-no-files-found: warn
          retention-days: 30

      # ----------------------------------------------------------------------
      # Phase 999.60 (v1.7.x-25) — contract-tests gate (BLOCKING, Linux-only).
      #
      # The cross-surface contract-test harness + compile-fail infra
      # (.planning/v1.7.4-ARCHITECTURE-CONTRACT.md §11; test/contract/).
      # Runs as an ISOLATED, named, blocking gate via `ctest -L contract` so
      # a future dual-path bypass fails CI on its own line — distinct from the
      # general test-suite gate above. Reuses this job's ccache / Qt / preset
      # lineage (the plan's "same ccache lineage as the existing test job").
      #
      # Linux-only at v1.7.4 (matches tabOrder_test discipline — headless
      # BALLView is brittle on macOS; macOS/Windows coverage is v1.7.5).
      #
      # HARNESS-FIRST: the per-controller parity / bool-apply / re-entrancy
      # fixtures ship DISABLED and report STATUS-skips today; they flip green
      # as 999.59 cuts each controller over. The harness MUST compile + run.
      # ----------------------------------------------------------------------
      - name: Build contract tests (Linux — 999.60 gate, blocking)
        if: startsWith(matrix.os, 'linux-')
        continue-on-error: false
        timeout-minutes: 30
        run: |
          cmake --build build/ci-linux --target contract_tests -j$(nproc)

      - name: Run contract tests (Linux — 999.60 gate, blocking)
        if: startsWith(matrix.os, 'linux-')
        continue-on-error: false
        timeout-minutes: 15
        run: |
          cd build/ci-linux
          # BALL_DATA_PATH lets the selection-consumer fixture load 1BNA.pdb;
          # fixtures that need the sample skip cleanly if it is absent.
          export BALL_DATA_PATH="${{ github.workspace }}/data"
          ctest -L contract --output-on-failure --timeout 120 \
                --output-junit ${{ github.workspace }}/contract-tests-linux.xml

      - name: Upload contract-test results (Linux)
        if: always() && startsWith(matrix.os, 'linux-')
        uses: actions/upload-artifact@v6
        with:
          name: contract-tests-linux-${{ github.run_id }}
          path: contract-tests-linux.xml
          if-no-files-found: warn
          retention-days: 30

      # ======================================================================
      # Windows — real vcpkg + choco provisioning (Phase 4 / Plan 04-04).
      #
      # Provisioning strategy:
      #  1. vcpkg: GitHub windows-2022 runners ship vcpkg at C:\vcpkg (exposed
      #     as VCPKG_INSTALLATION_ROOT). The windows-vcpkg preset toolchainFile
      #     picks it up via $env{VCPKG_ROOT}, bridged in the Configure step.
      #     Build speed (T-04-17 mitigation):
      #       - vcpkg's default file binary cache (%LOCALAPPDATA%\vcpkg\archives)
      #         is cached via actions/cache. In MANIFEST mode vcpkg installs into
      #         <binaryDir>/vcpkg_installed — NOT C:\vcpkg\installed — so caching
      #         that path is useless; the binary archives dir is the reusable
      #         artifact. Split restore/save with `save` at `if: always()` so a
      #         failing Build step still persists the (expensive) port builds.
      #         (vcpkg's x-gha cache was tried and dropped: the current GitHub
      #         Actions cache service no longer exposes ACTIONS_CACHE_URL.)
      #       - the `x64-windows-release` overlay triplet (cmake/vcpkg-triplets)
      #         builds Release-only, skipping the debug half of every port —
      #         roughly halves a cold build.
      #  2. flex/bison: not vcpkg ports; provisioned via winflexbison3 (choco).
      #     winflexbison3 installs win_flex.exe + win_bison.exe in
      #     C:\ProgramData\chocolatey\bin\.  BALL's bison logic (CMakeLists.txt
      #     lines 113-124) looks for BALL-bison.bat first (not present in this
      #     repo) then falls through to FindBISON which searches the PATH/cache;
      #     we set -DBISON_EXECUTABLE and -DFLEX_EXECUTABLE explicitly so the
      #     IF(WIN32) FIND_PROGRAM doesn't shadow the cache values.
      # ======================================================================

      - name: Restore vcpkg binary cache (Windows)
        id: vcpkg-cache
        if: matrix.os == 'windows-x64'
        uses: actions/cache/restore@v5
        with:
          path: C:\Users\runneradmin\AppData\Local\vcpkg\archives
          key: vcpkg-${{ matrix.os }}-${{ hashFiles('vcpkg.json', 'cmake/vcpkg-triplets/x64-windows-release.cmake') }}
          restore-keys: |
            vcpkg-${{ matrix.os }}-

      # Windows tooling install: flex/bison + ccache + ninja via a single
      # composite action so each workflow has one call site for "the Windows
      # deps." See .github/actions/setup-windows-deps/action.yml — ninja
      # was folded in 2026-05-16 (Phase 999.2) so the ci-windows CMake
      # preset can declare "generator": "Ninja" with no per-workflow drift.
      - name: Set up Windows build deps (flex/bison + ccache + ninja)
        if: matrix.os == 'windows-x64'
        uses: ./.github/actions/setup-windows-deps

      # Phase 999.2: with Ninja replacing MSBuild, `cl.exe` is invoked
      # directly and needs the `vcvars64.bat` environment (PATH, INCLUDE,
      # LIB, LIBPATH, etc.). MSBuild had this implicit via the VS project
      # files; Ninja does not. `ilammy/msvc-dev-cmd@v1` is the canonical
      # GitHub Actions wrapper around `vcvarsall.bat x64` — sets every env
      # var for the remaining steps of THIS job (it modifies the runner's
      # exported env, not just the current shell).
      - name: Set up MSVC environment (Windows — vcvars64 for Ninja)
        if: matrix.os == 'windows-x64'
        uses: ilammy/msvc-dev-cmd@v1
        with:
          arch: x64

      # Port of v1.6.2 release.yml commit 046271e: cold vcpkg of Qt 6 + Boost
      # easily consumes 30+ GB of buildtrees and OOM-kills the runner's
      # diag-log writer on the windows-2025 standard runner. Required for the
      # FIRST cross-platform Windows CI run on v1.7-modernization (cache miss)
      # which hit `error: building qtbase:x64-windows-release failed with:
      # BUILD_FAILED` + `There is not enough space on the disk` in run
      # 25984453099. Subsequent warm-cache runs skip vcpkg compile entirely
      # and this cleanup is a no-op (~2s); kept always-on for resilience
      # against actions/cache eviction.
      - name: Free disk space before vcpkg (Windows)
        if: matrix.os == 'windows-x64'
        shell: pwsh
        run: |
          $before = (Get-PSDrive C).Free / 1GB
          Write-Host ("Free space before cleanup: {0:N1} GB" -f $before)

          $targets = @(
            # Hosted toolcache languages (each typically 1-3 GB)
            "C:\hostedtoolcache\windows\PyPy",
            "C:\hostedtoolcache\windows\Ruby",
            "C:\hostedtoolcache\windows\Java_Temurin-Hotspot_jdk",
            "C:\hostedtoolcache\windows\Java_Adopt_jdk",
            "C:\hostedtoolcache\windows\go",
            "C:\hostedtoolcache\windows\node",
            # Old Python versions (keep 3.12+ in case vcpkg or cmake helper needs)
            "C:\hostedtoolcache\windows\Python\3.7.*",
            "C:\hostedtoolcache\windows\Python\3.8.*",
            "C:\hostedtoolcache\windows\Python\3.9.*",
            "C:\hostedtoolcache\windows\Python\3.10.*",
            "C:\hostedtoolcache\windows\Python\3.11.*",
            # Browser installs (cmake build doesn't use them)
            "C:\Program Files\Google\Chrome",
            "C:\Program Files\Mozilla Firefox",
            "C:\Program Files (x86)\Google",
            "C:\Program Files (x86)\Mozilla Firefox",
            # Pre-installed DB servers (BALL build doesn't use them)
            "C:\Program Files\PostgreSQL",
            "C:\Program Files\MongoDB",
            "C:\Program Files\MySQL",
            "C:\Program Files\Microsoft SQL Server",
            # Strawberry Perl (cmake's Perl finder picks chocolatey or Git Bash perl first)
            "C:\Strawberry",
            # JDK variants outside hostedtoolcache
            "C:\Program Files\Java",
            "C:\Program Files\Eclipse Adoptium",
            "C:\Program Files\Microsoft\jdk*",
            # Old VS variants if present (keep 2022, primary)
            "C:\Program Files (x86)\Microsoft Visual Studio\2019"
          )

          foreach ($t in $targets) {
            if (Test-Path $t) {
              try {
                Remove-Item -Recurse -Force $t -ErrorAction Stop
                Write-Host ("  removed: {0}" -f $t)
              } catch {
                Write-Host ("  skip (in use): {0}" -f $t)
              }
            }
          }

          $after = (Get-PSDrive C).Free / 1GB
          Write-Host ("Free space after cleanup:  {0:N1} GB (gained {1:N1} GB)" -f $after, ($after - $before))

      - name: Install Qt 6 (Windows — jurplel/install-qt-action / aqtinstall)
        if: matrix.os == 'windows-x64'
        # 999.66 — Windows Qt via aqtinstall. Mirrors the Linux step above:
        # install the official prebuilt Qt 6.8 desktop kit (MSVC 2022 x64)
        # instead of building qtbase/qtsvg/qttools from source via vcpkg.
        # This eliminates the ~1.5-2h cold Qt-from-source build and the
        # windeployqt-missing failure class. The action exposes Qt6_DIR +
        # QT_ROOT_DIR so FIND_PACKAGE(Qt6) resolves (same as Linux).
        # `modules:` intentionally omitted — BALL's Qt modules (Core/Network/
        # Xml/OpenGL/PrintSupport/Test/Widgets/OpenGLWidgets/Svg/LinguistTools)
        # are all in the default install; aqt 6.8 rejects qtbase/qtopengl/qttools
        # as module names.
        uses: jurplel/install-qt-action@v4
        with:
          version: ${{ matrix.qt_version }}
          host: 'windows'
          target: 'desktop'
          arch: 'win64_msvc2022_64'
          cache: true

      - name: Configure (Windows)
        if: matrix.os == 'windows-x64'
        shell: pwsh
        run: |
          # GitHub windows-2022 runners ship vcpkg at C:\vcpkg but expose it as
          # VCPKG_INSTALLATION_ROOT, not VCPKG_ROOT. The windows-vcpkg preset's
          # toolchainFile uses $env{VCPKG_ROOT}, so bridge the two here. (The
          # runner OS env var is not visible via the ${{ env.* }} context, so
          # it must be read inside the shell.)
          $env:VCPKG_ROOT = $env:VCPKG_INSTALLATION_ROOT
          Write-Host "VCPKG_ROOT=$env:VCPKG_ROOT"
          # 999.66 — Windows Qt via aqtinstall. Qt is no longer in vcpkg.json,
          # so the vcpkg toolchain no longer provides Qt6 config files. The aqt
          # action exports QT_ROOT_DIR (+ Qt6_DIR); pass it as CMAKE_PREFIX_PATH
          # so FIND_PACKAGE(Qt6) resolves the prebuilt kit (same effect as Linux,
          # where Qt6_DIR alone suffices). vcpkg toolchain is still used for
          # Boost/Eigen/FFTW/TBB/GLEW/etc.
          Write-Host "QT_ROOT_DIR=$env:QT_ROOT_DIR"
          # D-07: ci-windows preset inherits windows-vcpkg (vcpkg toolchainFile,
          # VCPKG_TARGET_TRIPLET=x64-windows-release + overlay triplet,
          # USE_LPSOLVE=OFF, BALL_HAS_OPENBABEL=OFF, ccache) and installs
          # vcpkg.json deps at configure time.
          # win_bison.exe / win_flex.exe from winflexbison3 are passed explicitly
          # because FindBISON/FindFLEX search for 'bison'/'flex' by default.
          #
          # Phase 5 (Plan 05-04): USE_QTWEBENGINE=OFF on Windows — Plan 05-01
          # carried the CMakeLists USE_QTWEBENGINE OPTION default `ON` for
          # Phase 1+2+3+4 backward compatibility. The vcpkg manifest does NOT
          # declare `qtwebengine` (it bloats cold-build by ~30min and Windows
          # CI has no consumer for it), so the FIND_PACKAGE(Qt6 WebEngineCore)
          # call would fail. Flipping the option OFF at configure time is the
          # least-invasive fix; macOS Homebrew has qtwebengine so it stays ON
          # there. See Plan 05-01 SUMMARY §"Open Items for Downstream Plans"
          # for the carry-forward note.
          # Pass --clean-after-build via CMake cache variable (not env var):
          # vcpkg's manifest-mode cmake integration honors VCPKG_INSTALL_OPTIONS
          # as a CMake cache variable; the env-var spelling is for the
          # standalone `vcpkg install` CLI and gets silently ignored here.
          # Deletes buildtrees + packages + downloads after each port finishes,
          # bounding peak disk during cold installs to ~3 GB/port instead of
          # the cumulative ~30+ GB. Required to fit on the windows-2025
          # standard runner; ported from v1.6.2 release.yml commit 046271e.
          # Phase 999.48 §8.7 step (b) — -DBALL_UI_V2=<matrix.ui_v2>
          # dropped here along with the axis removal.
          cmake --preset ci-windows `
            -DCMAKE_PREFIX_PATH="$env:QT_ROOT_DIR" `
            -DUSE_QTWEBENGINE=OFF `
            -DBISON_EXECUTABLE="C:/ProgramData/chocolatey/bin/win_bison.exe" `
            -DFLEX_EXECUTABLE="C:/ProgramData/chocolatey/bin/win_flex.exe" `
            "-DVCPKG_INSTALL_OPTIONS=--clean-after-build"

      # Persist the vcpkg binary cache as soon as Configure finishes — runs
      # even if a later Build step fails, so iterating on build errors does
      # not re-pay the ~80min Qt5/Boost source build each time.
      - name: Save vcpkg binary cache (Windows)
        if: always() && matrix.os == 'windows-x64' && steps.vcpkg-cache.outputs.cache-hit != 'true'
        uses: actions/cache/save@v5
        with:
          path: C:\Users\runneradmin\AppData\Local\vcpkg\archives
          key: vcpkg-${{ matrix.os }}-${{ hashFiles('vcpkg.json', 'cmake/vcpkg-triplets/x64-windows-release.cmake') }}

      - name: Build (Windows)
        if: matrix.os == 'windows-x64'
        shell: pwsh
        run: |
          # Phase 999.2: zero ccache stats before / dump after — under Ninja,
          # CMAKE_<LANG>_COMPILER_LAUNCHER=ccache (from the ci-windows preset)
          # is finally honored, so the post-build stats are the load-bearing
          # measurement for whether the switch is paying off.
          #
          # 2026-05-16: dropped `--parallel $env:NUMBER_OF_PROCESSORS` so Ninja
          # uses its tuned default (`nproc + 2`) instead of capping at `nproc`.
          # On the new windows-2022-xlarge runner that means more concurrent
          # cl.exe processes per cycle. Vestigial flag from the MSBuild era
          # (where `--parallel N` mapped to `/maxcpucount:N`); under Ninja the
          # flag's cap was actively reducing concurrency vs the default.
          & ccache --zero-stats
          cmake --build --preset ci-windows --target BALL VIEW BALLView --config Release
          & ccache --show-stats --verbose

      # Phase 999.28 follow-up — release-pipeline cross-ref vcpkg cache seed.
      # Why: release.yml runs on tag-push refs, whose GitHub Actions cache
      # scope is disjoint from this v1.6-modernization branch's scope. CI's
      # warm vcpkg binary cache is invisible to the tag-triggered release
      # workflow → release always cold-builds Qt6 + Boost from source on
      # Windows (~2h, OOM-prone). Workaround: publish CI's vcpkg/archives
      # as a workflow ARTIFACT (cross-ref accessible via `gh run download`).
      # release.yml's seed step downloads the most recent successful
      # artifact and stages it under %LOCALAPPDATA%\vcpkg\archives before
      # cmake configure; vcpkg then hits the local archives and skips the
      # from-source compile.
      #
      # Upload on every successful Windows build (cache hit or miss):
      # the archives directory contains the same content regardless of
      # source — what matters is that the artifact exists for release.yml
      # to pull. `overwrite: true` ensures each successful CI run refreshes
      # the artifact in place; no stale 14-day-old artifacts.
      # `if-no-files-found: warn` because on a partial-failure run the
      # archives dir may be empty (and we don't want to fail the whole
      # job just for the artifact upload).
      - name: Upload vcpkg archives for release-pipeline reuse (Windows)
        # Windows-only artifact (vcpkg toolchain cache). Phase 999.48 §8.7
        # step (b) — the prior ui_v2=OFF cell guard is gone with the
        # BALL_UI_V2 axis removal; there's only one cell per OS now.
        if: success() && matrix.os == 'windows-x64'
        uses: actions/upload-artifact@v6
        with:
          name: vcpkg-archives-windows
          path: C:\Users\runneradmin\AppData\Local\vcpkg\archives
          retention-days: 14
          if-no-files-found: warn
          compression-level: 0   # archives are already deflated .zips
          overwrite: true

      # Phase 999.19 (BUILD-ACCEL-04): per-TU build profiling (Windows).
      - name: Top-20 slowest TUs (windows-x64)
        if: (success() || failure()) && matrix.os == 'windows-x64'
        shell: pwsh
        run: |
          $logPath = "build\ci-windows\.ninja_log"
          if (Test-Path $logPath) {
            Write-Host "=== Top-20 slowest TUs (windows-x64) ==="
            # ninja log v7: field[3] = output_path, field[4] = cmd_hash (0-indexed).
            # Filter to CMakeFiles\ entries (source compilations only).
            Get-Content $logPath | ForEach-Object {
              $f = $_ -split "`t"
              if ($f.Length -ge 5 -and $f[3] -match 'CMakeFiles\\') {
                [PSCustomObject]@{ ms = [int]$f[1] - [int]$f[0]; tu = $f[3] }
              }
            } | Sort-Object -Property ms -Descending | Select-Object -First 20 | Format-Table -AutoSize
          } else {
            Write-Host "WARN: .ninja_log not found at $logPath"
          }

      - name: Upload .ninja_log artifact (windows-x64)
        if: (success() || failure()) && matrix.os == 'windows-x64'
        uses: actions/upload-artifact@v6
        with:
          # ui_v2 in artifact name — see macOS sibling rationale.
          name: ninja-log-windows-x64-${{ github.sha }}
          path: build\ci-windows\.ninja_log
          retention-days: 90
          include-hidden-files: true

      # ----------------------------------------------------------------------
      # Phase 9 gatekeeper (BLOCKING — Phase 999.34, 2026-05-17) — Windows
      # parity with the macOS + Linux gatekeepers above. Promoted from BACKLOG
      # in Phase 999.34 (Windows test gatekeeper bring-up); see ROADMAP.md and
      # .planning/phases/999.34-windows-test-gatekeeper/999.34-01-SUMMARY.md.
      #
      # Quarantine inheritance (test/CMakeLists.txt):
      #  - AssignBondOrderProcessor_test2 — Apple-arm64-only WILL_FAIL (FP
      #    fine-penalty bug specific to Apple Silicon FMA); MSVC x64 uses the
      #    Intel-compatible FP path so this test PASSES on Windows like Linux.
      #  - PeptideCapProcessor_test / Peptides_test / RotamerLibrary_test —
      #    platform-independent OOS PR-merge data regressions (Phase 999.35),
      #    unconditional WILL_FAIL TRUE; expected-fail on Windows the same way.
      #
      # Windows DLL discovery: the test EXEs land in build\ci-windows\bin\TEST\
      # (test/CMakeLists.txt) but BALL.dll + VIEW.dll live in
      # build\ci-windows\bin\, and Qt6 + Boost DLLs live in
      # build\ci-windows\vcpkg_installed\x64-windows-release\bin\. Windows
      # searches the EXE's own dir first and then PATH, so we must extend PATH
      # with BOTH of those directories before invoking ctest.
      # ----------------------------------------------------------------------
      - name: Build BALL test suite (Windows — Phase 9 gatekeeper, blocking)
        if: matrix.os == 'windows-x64'
        continue-on-error: false
        timeout-minutes: 45
        shell: pwsh
        run: |
          cmake --build build\ci-windows --target build_tests --config Release

      - name: Run BALL test suite (Windows — Phase 9 gatekeeper, blocking)
        if: matrix.os == 'windows-x64'
        continue-on-error: false
        timeout-minutes: 60
        shell: pwsh
        run: |
          cd build\ci-windows
          # BALL_DATA_PATH MUST be set — see macOS gatekeeper for the post-mortem.
          $env:BALL_DATA_PATH = "${{ github.workspace }}\data"
          # Windows DLL search path: extend PATH so test EXEs (in bin\TEST\)
          # find BALL.dll + VIEW.dll (in bin\), Qt6 DLLs (in the aqt kit's
          # $env:QT_ROOT_DIR\bin\) and Boost DLLs (in
          # vcpkg_installed\x64-windows-release\bin\). Without this, every
          # test exits with STATUS_DLL_NOT_FOUND (0xc0000135) and ctest reports
          # mass failures unrelated to the BALL code under test.
          # 999.66 — Windows Qt via aqtinstall: Qt DLLs now live in the aqt kit,
          # not in vcpkg_installed, so $env:QT_ROOT_DIR\bin is prepended here.
          $env:PATH = "$PWD\bin;$env:QT_ROOT_DIR\bin;$PWD\vcpkg_installed\x64-windows-release\bin;$env:PATH"
          # Phase 999.34 (2026-05-17): gatekeeper is BLOCKING; ctest exits
          # non-zero if any non-WILL_FAIL test fails. ui_v2 in JUnit filename
          # so ON + OFF cells don't clobber each other's output at the
          # test-report merge step (same rationale as macOS sibling).
          # Contract tests are Linux-only by design — they have a dedicated
          # `ctest -L contract` gate (Linux job above). The offscreen-Qt harness
          # hangs on the Windows runner (12 fixtures timed out) and the §11
          # compile-checks are Linux-targeted; macOS/Windows contract coverage is
          # a v1.7.5 concern. Exclude the `contract` label so the general Windows
          # gatekeeper doesn't sweep them in. They still BUILD here (compile cover).
          ctest --output-on-failure --timeout 120 -LE contract `
                --output-junit "${{ github.workspace }}\ball-tests-windows.xml"

      - name: Upload test results (Windows)
        if: always() && matrix.os == 'windows-x64'
        uses: actions/upload-artifact@v6
        with:
          name: ball-tests-windows-${{ github.run_id }}
          path: ball-tests-windows.xml
          if-no-files-found: warn
          retention-days: 30

      # ======================================================================
      # Render smoke check (D-08) — macOS native, Linux under xvfb + software
      # Mesa. Gated on the `matrix.smoke` field so a future matrix axis cannot
      # accidentally enable/disable it. Blocking on macOS + Linux: a blank or
      # missing PNG fails the job.
      # ======================================================================
      - name: Render smoke check (macOS — native)
        if: matrix.smoke && matrix.os == 'macos-arm64'
        env:
          # v1.7.0-rc3 R8 follow-up: bump default 60s timeout to 180s.
          # Cumulative Wave-4 fixes (Inspector + Workspace + WelcomeScreen +
          # CommandPalette + RC3 UFG-08/17 mainframe central-widget shuffle)
          # added enough widget-construction work on startup that the 60s
          # window is insufficient on github-hosted macOS runners. Local
          # smoke completes in <10s; CI runners are slower + cold.
          BALLVIEW_SMOKE_TIMEOUT: "180"
        run: |
          # Preset puts the binary at build/ci-macos/; pass explicitly so the
          # script's autodetect (which looks in build/bin/) is not needed.
          # Phase 5 (Plan 05-04): tee stdout to /tmp/ballview-smoke.log so the
          # follow-up "Assert GL compat profile" step can grep BALLVIEW_GL_DIAG
          # for `gl_profile=compatibility` (D-06 / D-08 runtime oracle).
          bash .planning/phases/02.2-ci-and-build-smoke-matrix/scripts/render-smoke-check.sh \
            build/ci-macos/bin/BALLView.app/Contents/MacOS/BALLView 2>&1 \
            | tee /tmp/ballview-smoke.log

      - name: Assert GL compat profile (macOS — D-06 / D-08)
        if: matrix.smoke && matrix.os == 'macos-arm64'
        run: |
          # D-06 + D-08 runtime oracle (Plan 05-04): a non-blank PNG alone is
          # NOT enough — Qt 6 on macOS defaults to a GL 4.1 *core* context if
          # QSurfaceFormat is not forced, and a silently-degraded core context
          # would still render a blank-ish-but-not-fully-blank PNG that the
          # render-smoke threshold accepts. The BALLVIEW_GL_DIAG line emitted
          # from GLRenderWindow::initializeGL() reports the live granted
          # profile; this step asserts the live profile is `compatibility`
          # OR `none`. Apple Silicon's GL 2.1 implementation does not expose
          # the Core/Compat profile distinction at version 2.1 — both M4 Max
          # hardware and macos-latest software runner emit `gl_profile=none`
          # (verified live, 05-DRIVER-BEHAVIOUR.md §BALLVIEW_GL_DIAG Captures).
          # The original D-08 oracle was empirically invalidated post-Phase-5
          # and relaxed here; Linux retains the strict `compatibility` check
          # (llvmpipe DOES expose the distinction so a fallback to core is a
          # real regression on that platform).
          grep -E 'BALLVIEW_GL_DIAG.*gl_profile=(compatibility|none)' /tmp/ballview-smoke.log

      # ======================================================================
      # Spike smoke check (macOS — GLCore backend) — THROWAWAY (Plan 05-05).
      # Non-blocking (continue-on-error: true): the GL-core spike is the
      # SPIKE-01 throwaway prototype; a regression in it must NOT gate PR
      # merge per CONTEXT.md framing. The step rebuilds BALLView with
      # -DBALL_SPIKE_BACKEND=GLCore, runs the same render smoke script with
      # BALLVIEW_USE_SPIKE_BACKEND=1 set, and uploads the captured stdout
      # so the SPIKE-02 decision record (Plan 08) has a referenced artifact.
      # ======================================================================
      - name: Spike smoke check (macOS — GLCore backend)
        if: matrix.smoke && matrix.os == 'macos-arm64'
        continue-on-error: true
        run: |
          cmake --preset ci-macos -DBALL_LICENSE=GPL -DBALL_SPIKE_BACKEND=GLCore
          cmake --build --preset ci-macos --target BALLView -j$(sysctl -n hw.ncpu)
          BALLVIEW_USE_SPIKE_BACKEND=1 bash .planning/phases/02.2-ci-and-build-smoke-matrix/scripts/render-smoke-check.sh \
            build/ci-macos/bin/BALLView.app/Contents/MacOS/BALLView 2>&1 \
            | tee /tmp/ballview-spike-smoke.log

      - name: Upload spike smoke log (macOS — GLCore backend)
        if: matrix.smoke && matrix.os == 'macos-arm64'
        continue-on-error: true
        uses: actions/upload-artifact@v6
        with:
          # ui_v2 in artifact name — doubled cells would collide otherwise.
          name: spike-smoke-log-glcore-macos
          path: /tmp/ballview-spike-smoke.log
          if-no-files-found: ignore
          retention-days: 30

      - name: Render smoke check (Linux — xvfb + software Mesa)
        if: matrix.smoke && matrix.os == 'linux-x64'
        env:
          # D-08: software Mesa/llvmpipe — fully supports the compat profile
          # BALLView's fixed-function GL 2.1 path needs.
          LIBGL_ALWAYS_SOFTWARE: 1
          # Plan 01 script honors this prefix; it does not hardcode xvfb.
          BALLVIEW_SMOKE_RUNNER: xvfb-run -a
          # v1.7.0-rc3 R8 follow-up — same rationale as the macOS step above.
          # llvmpipe + xvfb is slower than the macOS native path so the bump
          # matters more here.
          BALLVIEW_SMOKE_TIMEOUT: "180"
        run: |
          # Preset puts the binary at build/ci-linux/; pass explicitly so the
          # script's autodetect (which looks in build/bin/) is not needed.
          # Phase 5 (Plan 05-04): tee stdout to /tmp/ballview-smoke.log for the
          # follow-up GL compat-profile assertion step (D-06 / D-08).
          bash .planning/phases/02.2-ci-and-build-smoke-matrix/scripts/render-smoke-check.sh \
            build/ci-linux/bin/BALLView 2>&1 \
            | tee /tmp/ballview-smoke.log

      - name: Assert GL compat profile (Linux — D-06 / D-08)
        if: matrix.smoke && matrix.os == 'linux-x64'
        run: |
          # D-06 + D-08 runtime oracle (Plan 05-04). See macOS counterpart
          # above for the rationale — same grep, same exit semantics. On
          # Linux under llvmpipe the compat profile is fully supported, so
          # the granted format MUST report `gl_profile=compatibility`. A
          # silent fall-through to core would be a Phase 5 regression.
          grep 'BALLVIEW_GL_DIAG.*gl_profile=compatibility' /tmp/ballview-smoke.log

      # On a smoke-check failure, upload the (blank) PNG + captured BALLView log
      # so the failure can be debugged without re-running CI. The Plan 01 script
      # leaves both in a temp dir on failure (D-05 debugging intent).
      - name: Upload render-smoke artifacts on failure
        if: failure() && matrix.smoke
        uses: actions/upload-artifact@v6
        with:
          # ui_v2 in artifact name — doubled cells would collide otherwise.
          name: render-smoke-${{ matrix.os }}
          path: |
            ${{ runner.temp }}/ballview-smoke.*
            /tmp/ballview-smoke.*
          if-no-files-found: ignore
          retention-days: 7

      # ======================================================================
      # OpenBabel smoke check (D-05) — macOS + Linux only (matrix.smoke).
      # Windows has OpenBabel OFF (not a vcpkg port) so this step is skipped
      # for windows-x64. The script compiles the standalone driver against
      # libBALL and asserts: (1) non-empty SMILES, (2) determinism, (3)
      # aromaticity-correct canonical SMILES via OBConversion round-trip.
      # Plan 04-03 (openbabel-smoke.C + openbabel-smoke.sh).
      # ======================================================================
      - name: OpenBabel smoke check (macOS)
        if: matrix.smoke && matrix.os == 'macos-arm64'
        run: |
          bash .planning/phases/04-dependency-system-overhaul/scripts/openbabel-smoke.sh \
            build/ci-macos 2>&1 | tee /tmp/04-03-smoke.log
          grep -q OPENBABEL_SMOKE_OK /tmp/04-03-smoke.log

      - name: OpenBabel smoke check (Linux)
        if: matrix.smoke && matrix.os == 'linux-x64'
        run: |
          bash .planning/phases/04-dependency-system-overhaul/scripts/openbabel-smoke.sh \
            build/ci-linux 2>&1 | tee /tmp/04-03-smoke.log
          grep -q OPENBABEL_SMOKE_OK /tmp/04-03-smoke.log

      - name: Upload openbabel-smoke artifacts on failure
        if: failure() && matrix.smoke
        uses: actions/upload-artifact@v6
        with:
          # ui_v2 in artifact name — doubled cells would collide otherwise.
          name: openbabel-smoke-${{ matrix.os }}
          path: /tmp/04-03-smoke.log
          if-no-files-found: ignore
          retention-days: 7

  # --------------------------------------------------------------------------
  # lint — the legacy-Qt-symbol grep gates.
  #
  # Its own lightweight job: it needs no build, so a fast standalone job is
  # cleaner than a per-OS step. Blocking/required — a legacy symbol regression
  # fails CI. Each script takes the repo root as $1 and exits 0/1.
  #
  # Phase 5 (Plan 05-04): the Linux runner bumped from ubuntu-22.04 to
  # ubuntu-24.04 in step with the build matrix (D-02). The new Qt 5 holdout
  # gate (check-no-legacy-qt6-symbols.sh, scripts/) was added alongside the
  # Phase 2 legacy-GL gate — same pattern, different LEGACY_PATTERN set.
  # --------------------------------------------------------------------------
  lint:
    name: lint (legacy-Qt grep gates)
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout
        uses: actions/checkout@v5

      - name: Legacy Qt GL symbol grep gate
        run: |
          bash .planning/phases/02-rendering-port-4a/scripts/check-no-legacy-gl-symbols.sh "$GITHUB_WORKSPACE"

      - name: Legacy Qt 5 symbol grep gate (Phase 5)
        run: |
          # Plan 05-04 Task 1 — catches QRegExp / QDesktopWidget /
          # QApplication::desktop / QString::SkipEmptyParts /
          # QtWidgets/QOpenGLWidget / QtWidgets/QDesktopWidget / Qt5:: under
          # source/ + include/BALL/. The Qt 6 migration (Plans 05-01..03)
          # eliminated every site; this step prevents regressions.
          bash scripts/check-no-legacy-qt6-symbols.sh "$GITHUB_WORKSPACE"

      - name: Tooltip lint (Phase 999.48 §8.5)
        run: |
          # Phase 999.48 — addAction-without-setToolTip gate. Catches
          # gross tooltip omissions in new UI work (a TU that calls
          # addAction inline with a string literal / tr(...) / new
          # QAction but never sets a tooltip). Pre-existing baseline
          # gaps are listed in the script's ALLOW_LIST with rationale.
          python3 revitalization/scripts/tooltip-lint.py

  # --------------------------------------------------------------------------
  # coverage — Phase 9 partial promotion (NON-BLOCKING) — code coverage on
  # Linux GCC using BALL's existing ENABLE_COVERAGE_TESTING CMake option
  # (CMakeLists.txt line 681 — wires -fprofile-arcs -ftest-coverage for
  # BALL + VIEW under GXX). Separate job from the main build matrix because:
  #   - Coverage instrumentation is 2-3x slower than Release; running it
  #     in the matrix would slow every PR
  #   - Coverage runs in parallel with the matrix on a separate runner —
  #     net wall-clock cost is ~0
  #   - Failures here are non-blocking (continue-on-error: true) — coverage
  #     gen errors should never block a PR that has otherwise-green CI
  # Produces gcovr HTML report + Cobertura XML, both uploaded as artifacts
  # for browsing + future Codecov / GitHub Code Insights integration.
  # --------------------------------------------------------------------------
  coverage:
    name: coverage (Linux, gcov, non-blocking)
    runs-on: ubuntu-24.04
    continue-on-error: true
    timeout-minutes: 90
    steps:
      - name: Checkout
        uses: actions/checkout@v5

      - name: Cache apt archives
        uses: actions/cache@v5
        with:
          path: /var/cache/apt/archives/*.deb
          key: apt-coverage-ubuntu-24.04-${{ hashFiles('.github/workflows/ci.yml') }}
          restore-keys: |
            apt-coverage-ubuntu-24.04-

      - name: Install dependencies + gcovr
        run: |
          # Phase 5.1 carry-forward (2026-05-16): apt's qt6-base-dev on
          # Ubuntu 24.04 is 6.4.2 — BELOW the D-01 6.8 LTS floor (revised 2026-05-16, was 6.5) in
          # CMakeLists.txt. The Qt 6 install moves to jurplel/install-qt-action
          # in the next step (mirrors the regular Linux build job, which
          # had the same issue resolved by Phase 5 / Plan 05-04 D-02).
          # Don't install apt's qt6-* here — would just waste disk +
          # confuse find_package's search path.
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends \
            cmake make g++ ccache ninja-build \
            libboost-all-dev libeigen3-dev libfftw3-dev libtbb-dev libglew-dev \
            libopenbabel-dev libsvm-dev flex bison \
            xvfb mesa-utils libgl1-mesa-dri \
            gcovr lcov

      - name: Install Qt 6 (Linux — jurplel/install-qt-action / aqtinstall)
        # Mirrors the main build job's Qt 6 install — same version pin
        # (6.8.* / D-01 LTS floor, revised 2026-05-16) so the coverage
        # build matches the blocking build's Qt surface bit-for-bit.
        # `modules:` omitted per the same finding (aqt v3.3.0 rejects
        # qtbase/qtopengl/qttools as separately-installable; they're in
        # the default Qt 6 install).
        uses: jurplel/install-qt-action@v4
        with:
          version: '6.8.*'
          host: 'linux'
          target: 'desktop'
          cache: true

      - name: Configure (Linux + ENABLE_COVERAGE_TESTING)
        run: |
          # Reuse ci-linux preset but inject the coverage flag + force
          # Debug build (no -O optimization so coverage line mapping is
          # accurate). BALL_LICENSE=GPL keeps OpenBabel paths exercised.
          cmake --preset ci-linux \
            -DENABLE_COVERAGE_TESTING=ON \
            -DCMAKE_BUILD_TYPE=Debug \
            -DBALL_LICENSE=GPL

      - name: Build BALL + tests (coverage build)
        run: |
          cmake --build build/ci-linux --target BALL VIEW BALLView -j$(nproc)
          cmake --build build/ci-linux --target build_tests -j$(nproc)

      - name: Run test suite under coverage
        run: |
          cd build/ci-linux
          export BALL_DATA_PATH="${{ github.workspace }}/data"
          # Don't fail the job on test failures — coverage % is the
          # signal of interest here, and the gatekeeper jobs (above)
          # are already capturing the pass/fail breakdown.
          ctest --output-on-failure --timeout 240 \
                --output-junit ${{ github.workspace }}/ball-tests-coverage.xml || true

      - name: Generate coverage report (gcovr HTML + Cobertura XML)
        run: |
          mkdir -p coverage-report
          gcovr \
            --root . \
            --exclude '.*build/.*' \
            --exclude '.*test/.*' \
            --exclude '/usr/.*' \
            --exclude '.*moc_.*\.cpp' \
            --exclude '.*ui_.*\.h' \
            --html-details coverage-report/index.html \
            --xml-pretty --xml coverage-report/coverage.xml \
            --print-summary 2>&1 | tee coverage-summary.txt
          echo ""
          echo "Coverage summary:"
          grep -E "^lines:|^functions:|^branches:" coverage-summary.txt || \
            tail -5 coverage-summary.txt

      - name: Upload coverage HTML report
        if: always()
        uses: actions/upload-artifact@v6
        with:
          name: coverage-html-${{ github.run_id }}
          path: coverage-report/
          retention-days: 30

      - name: Upload coverage Cobertura XML (for Codecov / GitHub Insights)
        if: always()
        uses: actions/upload-artifact@v6
        with:
          name: coverage-xml-${{ github.run_id }}
          path: coverage-report/coverage.xml
          retention-days: 90

  # --------------------------------------------------------------------------
  # test-report — Phase 9 partial promotion — runs after the build matrix +
  # coverage job, downloads each platform's JUnit XML artifact, and publishes
  # a unified test-results summary as a Check Run on the PR / push (visible
  # inline in the GitHub UI without needing to download the XML manually).
  #
  # Uses EnricoMi/publish-unit-test-result-action — the canonical OSS action
  # for this pattern. Configured to NEVER fail the build itself
  # (fail_on: "nothing") since the gatekeeper steps are non-blocking; this
  # job is purely visualization.
  #
  # Skipped on forked-PR runs because cross-repo PRs don't have permissions
  # to write check runs on the upstream. The Linux build's --output-junit
  # output remains available as a downloadable artifact in that case.
  # --------------------------------------------------------------------------
  test-report:
    name: test-report (PR check summary)
    needs: [build, coverage]
    if: always() && github.event.pull_request.head.repo.full_name == github.repository || github.event_name == 'push'
    runs-on: ubuntu-24.04
    permissions:
      checks: write
      pull-requests: write
    continue-on-error: true
    steps:
      - name: Download all test result artifacts
        uses: actions/download-artifact@v7
        with:
          pattern: ball-tests-*
          path: junit-artifacts
          merge-multiple: true

      - name: Publish unit test results
        uses: EnricoMi/publish-unit-test-result-action@v2
        if: always()
        with:
          files: |
            junit-artifacts/*.xml
          comment_mode: changes in failures
          check_name: "BALL test suite (Phase 9 gatekeeper)"
          fail_on: "nothing"
          report_individual_runs: true

  # --------------------------------------------------------------------------
  # lifetime-discipline — phase 999.61 (v1.7.x-26) Qt-lifetime lint.
  #
  # Enforces rule 5 of .planning/codebase/QT-LIFETIME.md: no deleteLater()
  # inside a destructor body (the dtor-order foot-gun behind UFG-30/32). This
  # is a blocking, pure-bash grep-class check — no compiler, no matrix, fast
  # (~seconds). It runs independent of the build matrix so a lifetime
  # regression fails fast even if the slow 3-OS build is still in flight.
  #
  # Lightweight by design; the full clang-tidy custom check
  # (ball-no-raw-deletelater) is deferred to v1.7.5.
  # --------------------------------------------------------------------------
  lifetime-discipline:
    name: lifetime-discipline (Qt dtor deleteLater lint)
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Reject deleteLater() inside destructors (QT-LIFETIME.md rule 5)
        run: bash cmake/scripts/check-deletelater-discipline.sh

  # sip-refresh — phase 999.59-06 (v1.7.4) PyBALL binding-surface lint.
  # SIP is disabled in the modernization build and is slated for full
  # replacement in v2.1 (Phase 6 generator bake-off), so we do NOT resurrect
  # SIP 4.9 to regenerate the bindings here. Instead this lightweight,
  # blocking lint enforces the durable §3d guarantee: every method declared in
  # controllers.sip maps to a real C++ symbol — catching the setter-rename rot
  # that 999.59-04's privatization would otherwise have hidden. Full regen +
  # runtime coverage land with the v2.1 PyBALL milestone.
  sip-refresh:
    name: sip-refresh (PyBALL binding-symbol lint)
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Verify controllers.sip methods map to real C++ symbols
        run: bash cmake/scripts/check-sip-symbols.sh

  # opaque-paint — phase 999.62 close-out (v1.7.4) opaque-paint contract lint.
  # Flags any VIEW/WIDGETS container that animates a child's height (the
  # UFG-05/09/10 flicker class) without declaring an opaque-paint marker
  # (WA_OpaquePaintEvent / autoFillBackground / opaqueContainer). Centralizes
  # the lesson as a themeable token (theme-neutral.qss) + a doc (THEME.md).
  opaque-paint:
    name: opaque-paint (container opaque-paint lint)
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Self-test the lint (compliant passes / violation fails / whitelist exempts)
        run: bash test/contract/opaque-paint-lint-selftest.sh

      - name: Enforce the opaque-paint contract on VIEW/WIDGETS
        run: bash cmake/scripts/check-opaque-paint.sh