ci.yml

name: CI

on:
  push:
    branches: [main, master]
  pull_request:

# Supersede a run that a newer commit on the same ref has already made
# obsolete. Without this every push queued a *fresh* full run of the ~16 legs
# below and left the previous one in the queue -- so a burst of six merges to
# master queued six complete generations of CI, none of which could be
# cancelled by the next.
#
# That is not only this repository's problem. GitHub's concurrency allowance is
# per ACCOUNT, not per repository, so those generations sit in one queue shared
# with every other repo in the org and starve them: `fastcached` had fifteen
# jobs waiting behind this workflow with none running, and the oldest run here
# had been queued for over five hours.
#
# `docs.yml`, `wasm-demo.yml` and `wasm-ladder.yml` already do this; `ci.yml` is
# by far the largest workflow and was the one without it.
concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: read

env:
  # Turn morph's own log stream back on for CI. Test binaries default to
  # LogLevel::off so a local run is quiet; a CI log is read after the fact, by
  # someone diagnosing a failure that has already happened, and the full stream
  # is what makes that possible. Set here rather than passed as --log-level
  # because every leg runs its suites through `ctest --preset ...` and
  # catch_discover_tests registers each test case as its own invocation, so
  # there is nowhere to thread an extra argument through. Costs ~2,949 stderr
  # lines per suite per leg, which the Valgrind leg pays three times over.
  MORPH_TEST_LOG_LEVEL: debug

  # vcpkg's x-gha binary caching backend has been removed upstream (confirmed
  # live: every Windows CI run logged "warning: The 'x-gha' binary caching
  # backend has been removed" and silently cached nothing, rebuilding every
  # vcpkg dependency from source on every run). Replaced with the officially
  # documented successor: a NuGet-based provider backed by GitHub Packages'
  # own NuGet feed, which every repo already has -- no new secret, just the
  # windows job's own GITHUB_TOKEN and packages: write (see that job's
  # permissions: block and its "Add NuGet source" step, which is what
  # actually defines the `github` source this string names).
  VCPKG_BINARY_SOURCES: "clear;nuget,github,readwrite"
  SCCACHE_DIR: /home/runner/.cache/sccache
  # Caps each cache family's on-disk sccache blob. Cache keys are scoped by
  # preset name alone (gcc-debug, gcc-release, clang-debug, clang-release,
  # clang-asan, clang-tsan, clang-ubsan, clang-coverage), not by job name --
  # sccache disambiguates by the actual compiler invocation, so every job that
  # builds a given preset (e.g. linux-compilers', linux-qt's, ladder-tests'
  # and valgrind's gcc-debug legs) shares one cache family instead of keeping
  # its own. That is 8 families total rather than one per job, so this cap
  # times 8 stays comfortably inside GitHub's 10 GB per-repo actions-cache
  # budget where 16 job-scoped 1 GB blobs did not, and every job's build now
  # also warms the cache the next job's build reads from.
  #
  # The write side still only fires on a push to master (see each job's "Save
  # sccache" step) so generations do not keep multiplying underneath this.
  # Whether 1 GB is the right cap per family is a question for the
  # `sccache --show-stats` output those steps emit -- deliberately left
  # unchanged here so the effect of the cache-sharing change can be read on
  # its own.
  SCCACHE_CACHE_SIZE: "1G"
  # Attributes every fastcache-cc invocation to this one job, so the
  # "fastcache-cc stats" steps below can report *this* build's hit rate.
  # Without it they call `--show-stats` bare, which reads the whole
  # invocations log -- a self-hosted runner's lifetime totals across every job
  # it has ever run. A run of `Linux / all optional features (clang)` that
  # compiled 609 translation units reported "80.0% of 9157 cacheable": roughly
  # fifteen jobs' worth, of which this job was 6.6%. The step exists to say
  # whether the build was cached and structurally could not, which is the
  # failure AGENTS.md puts first -- a hit rate says nothing until you know how
  # many compilations it was offered.
  #
  # A group id rather than `--zero-stats`: zeroing is a process-wide truncation
  # of a log this runner's other concurrent jobs are also writing to, so it
  # would race them and destroy their numbers as well as the history. The id is
  # explicitly not part of the cache key (see `fastcache-cc --help`,
  # FASTCACHE_PREFETCH_GROUP), so this partitions the *statistics* and never
  # the cache itself -- jobs still read each other's entries.
  FASTCACHE_PREFETCH_GROUP: "${{ github.run_id }}-${{ github.job }}"
  CLANG_VERSION: "22"
  # The Catch2 the `clang-tidy` job analyses against, through the
  # clang-tidy-diff.py run inside it. Not a version this
  # workflow installs -- `apt-get install -y catch2` takes whatever
  # ubuntu-24.04 ships -- but a record of what that has been measured to be,
  # which the "Assert the Catch2 this job analyses against" step below reads
  # back off the runner and fails on if it has moved.
  #
  # It is worth recording because it is load-bearing and invisible. The check
  # the version decides is `bugprone-chained-comparison`, not
  # `readability-function-cognitive-complexity`. Measured with
  # clang-tidy 22.1.8, one TEST_CASE of twelve `REQUIRE`s, both releases
  # reached the same way (-isystem, i.e. as a system header, which is how this
  # runner and a workstation both reach theirs):
  #
  #     bugprone-chained-comparison               3.4.0: 12    3.16.0: 0
  #     readability-function-cognitive-complexity 3.4.0: 48    3.16.0: 48
  #
  # Catch2 added `/* NOLINT(bugprone-chained-comparison) */` to
  # INTERNAL_CATCH_TEST in 3.15.3; 3.4.0 predates it. That is a pure property
  # of the release, it is exactly what the nine examples/*/tests/.clang-tidy
  # files subtract the check for, and if the runner's package moves past
  # 3.15.3 those nine subtractions become dead suppressions with nothing
  # saying so. Half B of scripts/check_catch2_pin.sh under `--strict` is what
  # turns that silent move into a failed job.
  #
  # The cognitive-complexity score is the same 48 under both releases and
  # under `-I` and `-isystem` alike, so the version does not decide it. What
  # decides whether such a finding is *reported* is whether the diagnostic or
  # any of its increment notes lands outside a system header: clang-tidy drops
  # a finding all of whose locations are in system headers or system macros. A
  # TEST_CASE whose increments come only from Catch2 macro *bodies* is dropped
  # here and on a workstation alike; one with an increment spelled in the test
  # source -- a hand-written `if`, or a lambda inside a `REQUIRE` argument,
  # since macro arguments are spelled in the caller's file -- is reported on
  # both. Verified against this job's own red report, run 35581623269:
  #
  #     .../test_bank_gui_qml_behaviour.cpp:115:1: error: function
  #     'dummyFunction72' has cognitive complexity of 87 (threshold 25)
  #     /usr/include/catch2/catch_test_macros.hpp:142:28: note: expanded from
  #         macro 'TEST_CASE'
  #     .../test_bank_gui_qml_behaviour.cpp:121:23: note: nesting level
  #         increased to 2
  #
  # -- the last line is the lambda in `REQUIRE(pumpUntil([&app] { ... }))`,
  # spelled in the test file, and it is why that finding survives the system
  # filter. So there is no local/CI asymmetry to pin on this check: a local run
  # that exits 0 where this job exits 1 is almost always a `git diff -U0 HEAD`
  # that analysed zero files, not a Catch2 difference.
  #
  # Which artefact this names, checked rather than assumed:
  # ubuntu-24.04's package is 3.4.0-1build1 and it ships /usr/lib/cmake/Catch2,
  # so `find_package(Catch2 CONFIG QUIET)` at CMakeLists.txt:557 SUCCEEDS on
  # this runner and the FetchContent v3.8.1 fallback never runs -- reproduced
  # in a clean ubuntu:24.04 container, and corroborated by this job's own log
  # (no `_deps/catch2-*`, no dep-cache line for Catch2) and by the report above
  # naming /usr/include. The pin therefore guards the installation this job
  # really analyses against. Catch2 reaches the translation units through the
  # compiler's implicit /usr/include with no include flag at all: over the 751
  # entries this job's configure produces, none names catch2.
  CATCH2_VERSION: "3.4.0"
  # MORPH_BUILD_FORMS_QML needs Qt 6.5+; ubuntu-24.04 apt still ships 6.4.2.
  QT_VERSION: "6.8.1"

jobs:
  # ── Windows: MSVC + clang-cl ──────────────────────────────────────────
  windows:
    name: Windows / ${{ matrix.preset }}
    runs-on: windows-latest
    # packages: write is what lets vcpkg push built binaries to this repo's
    # GitHub Packages NuGet feed (see "Add NuGet source" below); nothing else
    # in this job needs more than the default contents: read the workflow
    # grants at the top level.
    permissions:
      contents: read
      packages: write
    strategy:
      fail-fast: false
      matrix:
        preset: [cl-debug, cl-release, clangcl-debug, clangcl-release]
    steps:
      - uses: actions/checkout@v4

      - name: Setup MSVC environment
        uses: ilammy/msvc-dev-cmd@v1

      - name: Setup vcpkg
        uses: lukka/run-vcpkg@v11
        with:
          vcpkgGitCommitId: c3867e714dd3a51c272826eea77267876517ed99

      # Defines the `github` source VCPKG_BINARY_SOURCES (top-level env:)
      # names. GITHUB_TOKEN is scoped to this repo and already carries
      # packages: write from this job's permissions: block above -- no new
      # secret needed. `dotnet nuget` rather than `nuget.exe`: it ships with
      # the .NET SDK already on every GitHub-hosted Windows runner, so
      # nothing extra needs installing.
      - name: Add NuGet source (GitHub Packages, for vcpkg binary caching)
        shell: pwsh
        run: |
          dotnet nuget add source "https://nuget.pkg.github.com/${{ github.repository_owner }}/index.json" `
            --name github `
            --username "${{ github.repository_owner }}" `
            --password "${{ secrets.GITHUB_TOKEN }}" `
            --store-password-in-clear-text

      - name: Configure
        run: cmake --preset ${{ matrix.preset }}

      - name: Build
        run: cmake --build --preset ${{ matrix.preset }}

      - name: Test
        if: matrix.preset == 'cl-debug' || matrix.preset == 'clangcl-debug'
        run: ctest --preset ${{ matrix.preset }}

  # Picks a self-hosted lastrada-docker runner for the Linux legs when one is
  # registered, online, and idle; falls back to the GitHub-hosted label
  # otherwise. The runners are ORGANISATION-level (one fleet serves morph,
  # fastcached and Lightweight), so this queries the org endpoint -- the
  # repo endpoint returns zero for them and every run would silently go
  # GitHub-hosted with no error anywhere.
  #
  # GITHUB_TOKEN can't call the runners API, so this needs
  # RUNNER_STATUS_TOKEN: a PAT with organisation self-hosted-runner read
  # access (admin:org, or fine-grained "Self-hosted runners: Read-only" on
  # LASTRADA-Software), stored as a repo secret. Forked-repo PRs don't get
  # repo secrets at all (the token comes through empty), which this treats
  # the same as "no runner online": fall back to GitHub-hosted. A failed
  # curl, or a 200 response whose body is missing or the wrong shape for
  # `.runners`, are treated the same way. See
  # .github/self-hosted-runner/README.md for the fleet itself.
  probe-self-hosted:
    name: Probe self-hosted runner
    runs-on: ubuntu-24.04
    outputs:
      runs_on: ${{ steps.probe.outputs.runs_on }}
    steps:
      - name: Check for an idle lastrada-docker runner
        id: probe
        env:
          RUNNER_STATUS_TOKEN: ${{ secrets.RUNNER_STATUS_TOKEN }}
        run: |
          set -euo pipefail
          fallback='["ubuntu-24.04"]'

          if [ -z "${RUNNER_STATUS_TOKEN}" ]; then
            echo "No RUNNER_STATUS_TOKEN (e.g. a forked-repo PR) -- using GitHub-hosted."
            echo "runs_on=${fallback}" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          runners=$(curl -fsSL \
            -H "Authorization: Bearer ${RUNNER_STATUS_TOKEN}" \
            -H "Accept: application/vnd.github+json" \
            "https://api.github.com/orgs/LASTRADA-Software/actions/runners") || {
              echo "Runners API call failed -- using GitHub-hosted."
              echo "runs_on=${fallback}" >> "$GITHUB_OUTPUT"
              exit 0
            }

          online=$(echo "${runners}" | jq '[(.runners // [])[] |
            select(.status == "online" and .busy == false and
                   (.labels | map(.name) | contains(["lastrada-docker"])))] | length') || {
              echo "Malformed runners response -- using GitHub-hosted."
              echo "runs_on=${fallback}" >> "$GITHUB_OUTPUT"
              exit 0
            }

          if ! [[ "${online}" =~ ^[0-9]+$ ]]; then
            online=0
          fi

          if [ "${online}" -gt 0 ]; then
            echo "Found an idle lastrada-docker runner -- using self-hosted."
            echo 'runs_on=["self-hosted", "Linux", "X64", "lastrada-docker"]' >> "$GITHUB_OUTPUT"
          else
            echo "No idle lastrada-docker runner -- using GitHub-hosted."
            echo "runs_on=${fallback}" >> "$GITHUB_OUTPUT"
          fi

  # ── Linux: GCC and Clang plain builds ────────────────────────────────
  linux-compilers:
    name: Linux / ${{ matrix.preset }}
    needs: probe-self-hosted
    runs-on: ${{ fromJSON(needs.probe-self-hosted.outputs.runs_on) }}
    env:
      # Only set on the self-hosted path: host.docker.internal does not
      # resolve on a GitHub-hosted VM (it is not a Docker container), and an
      # address that is merely unreachable rather than refusing the
      # connection stalls fastcache-cc's TCP connect for up to ~2m30s per
      # matrix leg (CompileCache.cmake's own measured worst case) instead of
      # failing fast -- so this must stay empty on that path, not just
      # "wrong but harmless".
      FASTCACHE_ADDR: ${{ contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted') && 'host.docker.internal:6674' || '' }}
      # FASTCACHE_AUTO_INSTALL is a plain CMake option(), not something
      # CompileCache.cmake reads from the environment the way it does
      # FASTCACHE_ADDR -- an env var of this name is silently ignored, only
      # -DFASTCACHE_AUTO_INSTALL=ON on the cmake command line reaches it
      # (confirmed live: FASTCACHE_ADDR landed in CMakeCache.txt from the
      # environment, FASTCACHE_AUTO_INSTALL stayed OFF). This is that flag,
      # precomputed once so every Configure step below can just splice it in.
      MORPH_FASTCACHE_AUTO_INSTALL_FLAG: ${{ contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted') && '-DFASTCACHE_AUTO_INSTALL=ON' || '' }}
    strategy:
      fail-fast: false
      matrix:
        preset: [gcc-debug, gcc-release, clang-debug, clang-release]
    steps:
      - uses: actions/checkout@v4

      - name: Cache apt packages
        uses: actions/cache@v4
        with:
          path: /var/cache/apt/archives
          key: apt-compilers-${{ matrix.preset }}-${{ hashFiles('.github/workflows/ci.yml') }}
          restore-keys: apt-compilers-${{ matrix.preset }}-

      - name: Install GCC 15 and ninja
        if: startsWith(matrix.preset, 'gcc-')
        run: |
          sudo apt-get update -q
          sudo apt-get install -y software-properties-common
          sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
          sudo apt-get update -q
          sudo apt-get install -y gcc-15 g++-15 ninja-build catch2
          sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-15 15
          sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-15 15

      - name: Install Clang ${{ env.CLANG_VERSION }} from apt.llvm.org
        if: startsWith(matrix.preset, 'clang-')
        run: |
          sudo apt-get update -q
          sudo apt-get install -y ninja-build catch2
          # Download, check, then execute -- not
          # `wget -qO- https://apt.llvm.org/llvm.sh | sudo bash`.
          # `wget -q` writes no error document, so on an HTTP 4xx/5xx it exits
          # 8 having written zero bytes. `bash` then reads an empty script,
          # does nothing, and exits 0 -- and GitHub runs `run:` under `bash -e`
          # without pipefail, so the pipeline's status is bash's, not wget's.
          # That step reports success having installed no compiler, and the leg
          # goes red several steps later at Configure, naming a missing
          # compiler rather than the download that never happened.
          #
          # Measured against apt.llvm.org itself, on a path that 404s:
          #
          #     $ curl -sSL -o llvm.sh https://apt.llvm.org/does-not-exist.sh
          #     exit=0   564 bytes of error page
          #     $ curl -sSL --fail -o llvm.sh https://apt.llvm.org/does-not-exist.sh
          #     curl: (22) The requested URL returned error: 404
          #     exit=22
          #
          # Same three lines as the `Install sccache` steps, so the
          # repository has one download idiom rather than two: `--fail` so the
          # download reports its own failure, a file so nothing downstream runs
          # when it does, and `test -s` for the 200-with-empty-body case that
          # `--fail` cannot see. This is not a retry policy and it does not make
          # an apt.llvm.org outage less likely -- it makes the step that failed
          # be the step the log names.
          curl -sSL --fail -o /tmp/llvm.sh https://apt.llvm.org/llvm.sh
          test -s /tmp/llvm.sh
          sudo bash /tmp/llvm.sh ${{ env.CLANG_VERSION }}

      # Keyed by preset alone, not this job's name: gcc-debug/clang-debug's
      # object files are the same ones linux-qt, ladder-tests, valgrind (for
      # gcc-debug) and clang-tidy (for clang-debug) compile with extra
      # -DMORPH_BUILD_* flags layered on top. sccache disambiguates by the
      # actual compiler invocation, not by this key, so sharing one cache
      # entry per preset across jobs only raises the hit rate -- it cannot
      # serve a wrong object for a different flag set.

      # Skipped on the self-hosted path: CompileCache.cmake's
      # FASTCACHE_AUTO_INSTALL only fetches fastcache-cc when NONE of
      # fastcache-cc/sccache/ccache are already on PATH ("only when there is
      # nothing else to use" -- see that file's own comment on the guard).
      # Installing sccache unconditionally, as this job used to, permanently
      # defeated auto-install regardless of FASTCACHE_AUTO_INSTALL=ON:
      # sccache was always present, so the auto-install guard's `AND NOT
      # SCCACHE` was always false. GitHub-hosted's fallback still gets
      # sccache exactly as before.
      - name: Restore sccache
        if: "!contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted')"
        uses: actions/cache/restore@v4
        with:
          path: /home/runner/.cache/sccache
          key: sccache-${{ matrix.preset }}-${{ github.sha }}
          restore-keys: sccache-${{ matrix.preset }}-

      - name: Install sccache
        if: "!contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted')"
        run: |
          # `--fail`, and a file rather than a pipe into tar. Piped, a host
          # that serves an error page instead of a tarball kills the step with
          #
          #     gzip: stdin: not in gzip format
          #     tar: Child returned status 1
          #     tar: Error is not recoverable: exiting now
          #
          # because plain `curl` reports an HTTP 4xx/5xx as a *successful*
          # transfer of that page, exit 0, straight down the pipe. The only
          # diagnostic anyone sees names the decompressor, and the event that
          # actually happened -- the download failed, with a status -- appears
          # nowhere in the log. `set -o pipefail` cannot salvage it either:
          # GitHub runs `run:` under `bash -e`, without pipefail, so the
          # pipeline's status is tar's regardless of what curl did.
          #
          # `--fail` makes curl exit non-zero and print `curl: (22) The
          # requested URL returned error: 503`; writing to a file means tar
          # never runs at all when it does. This is not a retry policy and it
          # does not make the outage less likely -- it makes the log name the
          # thing that happened, which is the half of the problem that needs no
          # CI-wide decision. The rest of that class -- a retry policy, or a
          # marker that distinguishes "the environment failed" from "the
          # change failed" in the check list, and the apt/PPA outages that
          # are the other three quarters of the ticket -- is still open.
          curl -sSL --fail -o /tmp/sccache.tar.gz \
            https://github.com/mozilla/sccache/releases/download/v0.9.1/sccache-v0.9.1-x86_64-unknown-linux-musl.tar.gz
          tar -xzf /tmp/sccache.tar.gz --strip-components=1 -C /usr/local/bin \
            sccache-v0.9.1-x86_64-unknown-linux-musl/sccache

      # No -DCMAKE_..._COMPILER_LAUNCHER=sccache here on purpose: leaving the
      # launcher unset lets cmake/CompileCache.cmake's own auto-detection run,
      # which prefers fastcache-cc (this job's FASTCACHE_ADDR, set above, only
      # when running self-hosted) and falls back to the sccache install steps
      # above when no daemon answers -- e.g. this exact job on the
      # GitHub-hosted fallback runner, which never gets a FASTCACHE_ADDR to
      # begin with. Setting the launcher explicitly, as every other Linux job
      # still does, would make CompileCache.cmake bail out before it ever
      # probes for fastcache-cc (see that file's own comment).
      - name: Configure (gcc)
        if: startsWith(matrix.preset, 'gcc-')
        run: cmake --preset ${{ matrix.preset }} $MORPH_FASTCACHE_AUTO_INSTALL_FLAG

      - name: Configure (clang)
        if: startsWith(matrix.preset, 'clang-')
        run: |
          cmake --preset ${{ matrix.preset }} \
            -DCMAKE_C_COMPILER=clang-${{ env.CLANG_VERSION }} \
            -DCMAKE_CXX_COMPILER=clang++-${{ env.CLANG_VERSION }} \
            $MORPH_FASTCACHE_AUTO_INSTALL_FLAG

      - name: Build
        run: cmake --build --preset ${{ matrix.preset }}

      - name: Test
        if: endsWith(matrix.preset, '-debug')
        run: ctest --preset ${{ matrix.preset }}

      # Cumulative hit/miss for this leg. Without it the cache is
      # unfalsifiable: a thrashing cache and a working one look identical
      # from the outside, and only the build-step duration hints at which
      # one you have. `|| true` so a stats failure never fails the job.
      #
      # Guarded the same way as the Install/Restore sccache steps above:
      # sccache is never installed on the self-hosted path (fastcache-cc is
      # used there instead), so `sccache --show-stats` would just fail
      # "command not found" there.
      - name: sccache stats
        if: "always() && !contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted')"
        run: sccache --show-stats || true

      # Cache statistics for this leg. The `sccache stats` step is skipped
      # whenever the probe put this job on the self-hosted fleet, because
      # sccache is not the launcher there -- fastcache-cc is. Nothing replaced
      # it, so those legs ran with no cache reporting at all: exactly the
      # "unfalsifiable" state the sccache step's own comment warns about, where
      # a thrashing cache and a working one look identical from the outside and
      # only the build duration hints at which one you have.
      #
      # The line that matters is
      #     unavailable : N  (x% of all compiles -- CACHE NOT REACHED)
      # which is how a daemon that is configured but never answering shows up.
      # Configure still prints "Enabling fastcache-cc at ..." in that case and
      # the build simply takes as long as a cold one, so no other signal in the
      # job would reveal it.
      #
      # Mirror of the sccache step's condition, so exactly one of the two runs.
      # `|| true` for the same reason it has one: a stats failure must never
      # fail the job.
      - name: fastcache-cc stats
        if: "always() && contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted')"
        run: |
          FC="$(command -v fastcache-cc || true)"
          if [ -z "$FC" ]; then
            FC="$(ls -t "$HOME"/.cache/fastcache-cc/*/*/fastcache-cc 2>/dev/null | head -1 || true)"
          fi
          if [ -z "$FC" ]; then
            echo "::warning::fastcache-cc not found on a self-hosted runner -- the build ran uncached."
            exit 0
          fi
          echo "launcher: $FC   FASTCACHE_ADDR=${FASTCACHE_ADDR:-<unset>}"
          # This job's own numbers, not the runner's lifetime totals. The
          # bare form is kept underneath because the whole-runner view is
          # what shows eviction pressure across jobs, which a single job's
          # slice cannot.
          "$FC" --show-stats --prefetch-group "$FASTCACHE_PREFETCH_GROUP" || true
          echo "--- whole runner, all jobs (context for the above) ---"
          "$FC" --show-stats || true

      # Save only on a push to master. Every run used to write a new
      # per-commit entry, and with 16 cache-writing legs at 1 GB each one
      # generation already exceeds GitHub's 10 GB per-repo budget -- so
      # legs evicted each other and entries rarely survived to be reused.
      # Restricting writes to master keeps the property that makes the cache
      # usable at all (only one branch ever writes, so no branch can delete
      # another's entry) while collapsing the generations that actually blow
      # the budget. Pull requests still restore, read-only, and get the full
      # benefit.
      - name: Save sccache
        if: github.event_name == 'push' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main') && !contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted')
        uses: actions/cache/save@v4
        with:
          path: /home/runner/.cache/sccache
          key: sccache-${{ matrix.preset }}-${{ github.sha }}

  # ── Linux: sanitizers + coverage (all clang) ─────────────────────────
  linux-sanitizers:
    name: Linux / ${{ matrix.preset }}
    needs: probe-self-hosted
    runs-on: ${{ fromJSON(needs.probe-self-hosted.outputs.runs_on) }}
    env:
      # See linux-compilers' identical env block for why FASTCACHE_ADDR is
      # conditional, and why FASTCACHE_AUTO_INSTALL has to be a -D flag
      # (MORPH_FASTCACHE_AUTO_INSTALL_FLAG) rather than an env var of that
      # name -- CompileCache.cmake declares it as a plain option(), which
      # CMake never reads from the environment.
      FASTCACHE_ADDR: ${{ contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted') && 'host.docker.internal:6674' || '' }}
      MORPH_FASTCACHE_AUTO_INSTALL_FLAG: ${{ contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted') && '-DFASTCACHE_AUTO_INSTALL=ON' || '' }}
    strategy:
      fail-fast: false
      matrix:
        preset: [clang-asan, clang-tsan, clang-ubsan]
    steps:
      - uses: actions/checkout@v4

      - name: Cache apt packages
        uses: actions/cache@v4
        with:
          path: /var/cache/apt/archives
          key: apt-sanitizers-${{ hashFiles('.github/workflows/ci.yml') }}
          restore-keys: apt-sanitizers-

      - name: Install Clang ${{ env.CLANG_VERSION }} from apt.llvm.org
        run: |
          sudo apt-get update -q
          sudo apt-get install -y ninja-build catch2 libsqlite3-dev
          # --fail, a file, and a non-empty check -- never `wget -qO- | sudo
          # bash`: see linux-compilers' identical install step for why the piped
          # form reports success having installed nothing.
          curl -sSL --fail -o /tmp/llvm.sh https://apt.llvm.org/llvm.sh
          test -s /tmp/llvm.sh
          sudo bash /tmp/llvm.sh ${{ env.CLANG_VERSION }}

      # Keyed by preset alone, matching linux-compilers' cache above: this
      # matrix's clang-asan/clang-tsan legs share the same preset name (and
      # much of the same object set) as ladder-sanitizers and kanban-tsan
      # respectively, which build the identical compiler+preset with extra
      # -DMORPH_BUILD_* flags on top. See linux-compilers' identical comment
      # for why sharing the key across jobs is safe.

      # Skipped on the self-hosted path: see linux-compilers' identical
      # Restore/Install sccache steps for why (installing sccache
      # unconditionally would permanently defeat fastcache-cc auto-install).
      - name: Restore sccache
        if: "!contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted')"
        uses: actions/cache/restore@v4
        with:
          path: /home/runner/.cache/sccache
          key: sccache-${{ matrix.preset }}-${{ github.sha }}
          restore-keys: sccache-${{ matrix.preset }}-

      - name: Install sccache
        if: "!contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted')"
        run: |
          # `--fail` and a file rather than a pipe into tar: see
          # linux-compilers' identical Install sccache step for why an
          # unchecked download reports itself as "not in gzip format".
          curl -sSL --fail -o /tmp/sccache.tar.gz \
            https://github.com/mozilla/sccache/releases/download/v0.9.1/sccache-v0.9.1-x86_64-unknown-linux-musl.tar.gz
          tar -xzf /tmp/sccache.tar.gz --strip-components=1 -C /usr/local/bin \
            sccache-v0.9.1-x86_64-unknown-linux-musl/sccache

      # morph::net and the SQLite offline queue are opt-in, but they are also
      # where the memory/threading/UB risk actually lives (raw sockets, an I/O
      # thread, a hand-rolled frame reader, a C API). Left off, the sanitizers
      # silently skip them. QML, the fuzzers, and the ladder stay out of
      # this matrix entirely — they are covered by linux-coverage and
      # linux-all-features, and "a GUI stack under TSan is mostly noise".
      #
      # No -DCMAKE_..._COMPILER_LAUNCHER=sccache: see linux-compilers' Configure
      # steps for why leaving it unset is what lets fastcache-cc be selected.
      - name: Configure
        run: |
          cmake --preset ${{ matrix.preset }} \
            -DMORPH_BUILD_NET=ON \
            -DMORPH_BUILD_OFFLINE_SQLITE=ON \
            -DCMAKE_C_COMPILER=clang-${{ env.CLANG_VERSION }} \
            -DCMAKE_CXX_COMPILER=clang++-${{ env.CLANG_VERSION }} \
            $MORPH_FASTCACHE_AUTO_INSTALL_FLAG

      - name: Build
        run: cmake --build --preset ${{ matrix.preset }}

      # A sanitizer job whose binaries are not instrumented runs the whole suite
      # and learns nothing, while reporting success. Asserting this over one
      # job's binaries, or for `__asan_` alone, is vacuous on the tsan and
      # ubsan legs -- the same "control that measures nothing" it exists to
      # prevent. This walks what ctest will actually run and keys the expected
      # symbol on the preset, so none of the three legs can pass on a blind
      # build.
      #
      # No `QT_QPA_PLATFORM: offscreen` here, unlike the identical step in
      # bank-sanitizers, kanban-tsan and ladder-sanitizers, and the absence is
      # deliberate rather than an omission. The sweep's first act is
      # `ctest --show-only=json-v1`, which *executes* every DISCOVERY_MODE
      # PRE_TEST binary to enumerate its cases; a Qt-linked one aborts headless
      # and takes the whole listing with it. This matrix's Configure above sets
      # neither MORPH_BUILD_QT nor MORPH_BUILD_LADDER, so it builds no Qt-linked
      # suite for that to happen to, and its own Test step does not declare the
      # variable either. Adding it for symmetry would be a line protecting
      # against nothing, which invites the next reader to look for what it
      # protects. Revisit the moment this matrix gains a Qt target.
      - name: Every ctest binary is instrumented
        run: |
          case "${{ matrix.preset }}" in
            clang-asan)  mode=asan ;;
            clang-tsan)  mode=tsan ;;
            clang-ubsan) mode=ubsan ;;
            *) echo "::error::no sanitizer mode for preset ${{ matrix.preset }}"; exit 1 ;;
          esac
          bash scripts/check_sanitizer_instrumentation.sh build/${{ matrix.preset }} "$mode"

      - name: Test
        env:
          # Known-false-positive suppressions, the same treatment
          # cmake/valgrind.supp already gets on the Valgrind job below. The
          # entries are libstdc++'s two refcounts for a shared exception --
          # exception_ptr's, and the COW string holding the message -- both
          # decremented inside an uninstrumented libstdc++.so.6, so TSan
          # gets no happens-before edge between the last thread to read a
          # shared exception's what() and the thread whose release frees it.
          # The file itself carries the measured evidence and
          # says why each of the three frames it names still resolves
          # against the runner's stripped libstdc++.
          #
          # Harmless on the clang-asan and clang-ubsan legs of this matrix:
          # neither runtime reads TSAN_OPTIONS.
          #
          # `second_deadlock_stack=1` is colon-separated *into this value*, not
          # a second `TSAN_OPTIONS:` key -- a second key silently replaces the
          # first and drops the suppressions file, leaving the job green and
          # unsuppressed. It makes TSan print, for a lock-order inversion,
          # the stacks where the *already-held* mutexes were taken. Measured on
          # a two-mutex inversion under clang 22.1.8: 36 lines -> 55, the extra
          # 19 being two `Mutex Mn previously acquired by the same thread here:`
          # stacks that name the acquiring function and line. Without it TSan
          # prints only `Hint: use TSAN_OPTIONS=second_deadlock_stack=1 to get
          # more informative warning message` -- advice nobody can take after
          # the fact, because the races this job catches are intermittent and
          # the run that fires is the only evidence that will ever exist. No
          # measurable runtime cost: 2M lock acquisitions under TSan take a
          # median 0.275s without and 0.273s with.
          TSAN_OPTIONS: suppressions=${{ github.workspace }}/cmake/tsan.supp:second_deadlock_stack=1
        run: |
          # morph::testkit::OomInjector (tests/oom_injector.cpp) overrides
          # the process-wide operator new/delete to force std::bad_alloc on
          # demand. ASan and TSan's own runtimes already interpose operator
          # new/delete themselves, so the file compiles its overrides *out*
          # under either sanitizer rather than linking a second definition
          # beside theirs.
          #
          # The link does *not* fail with "multiple definition of
          # `operator new(unsigned long)'", which is the obvious guess. It
          # succeeds, and the tests fail at *runtime* instead, because
          # OomInjector's constructor throws when its overrides are compiled
          # out --
          #
          #     OomInjector: unusable under ASan/TSan (operator new/delete
          #     overrides are compiled out)
          #
          # -- which is precisely what a ctest-level exclusion handles, and is
          # why the exclusion below works at all. Measured with the filter
          # bypassed: six failures on each of the two legs, the five
          # `OomInjector` cases plus the one whose name the second alternative
          # matches. Deleting the -E filter turns both legs red.
          #
          # Excluded by test name on exactly these two legs; every other CI leg
          # (plain clang/gcc, Windows, ubsan, coverage) runs these tests
          # normally -- the guard keys on __SANITIZE_ADDRESS__/
          # __SANITIZE_THREAD__, which no other leg defines.
          EXCLUDE_ARGS=()
          if [ "${{ matrix.preset }}" = "clang-asan" ] || [ "${{ matrix.preset }}" = "clang-tsan" ]; then
            EXCLUDE_ARGS+=(-E "OomInjector|morph#108")
          fi
          ctest --preset ${{ matrix.preset }} "${EXCLUDE_ARGS[@]}"

      # Cache statistics for this leg. The `sccache stats` step is skipped
      # whenever the probe put this job on the self-hosted fleet, because
      # sccache is not the launcher there -- fastcache-cc is. Nothing replaced
      # it, so those legs ran with no cache reporting at all: exactly the
      # "unfalsifiable" state the sccache step's own comment warns about, where
      # a thrashing cache and a working one look identical from the outside and
      # only the build duration hints at which one you have.
      #
      # The line that matters is
      #     unavailable : N  (x% of all compiles -- CACHE NOT REACHED)
      # which is how a daemon that is configured but never answering shows up.
      # Configure still prints "Enabling fastcache-cc at ..." in that case and
      # the build simply takes as long as a cold one, so no other signal in the
      # job would reveal it.
      #
      # Mirror of the sccache step's condition, so exactly one of the two runs.
      # `|| true` for the same reason it has one: a stats failure must never
      # fail the job.
      - name: fastcache-cc stats
        if: "always() && contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted')"
        run: |
          FC="$(command -v fastcache-cc || true)"
          if [ -z "$FC" ]; then
            FC="$(ls -t "$HOME"/.cache/fastcache-cc/*/*/fastcache-cc 2>/dev/null | head -1 || true)"
          fi
          if [ -z "$FC" ]; then
            echo "::warning::fastcache-cc not found on a self-hosted runner -- the build ran uncached."
            exit 0
          fi
          echo "launcher: $FC   FASTCACHE_ADDR=${FASTCACHE_ADDR:-<unset>}"
          # This job's own numbers, not the runner's lifetime totals. The
          # bare form is kept underneath because the whole-runner view is
          # what shows eviction pressure across jobs, which a single job's
          # slice cannot.
          "$FC" --show-stats --prefetch-group "$FASTCACHE_PREFETCH_GROUP" || true
          echo "--- whole runner, all jobs (context for the above) ---"
          "$FC" --show-stats || true

  # ── Linux: coverage (clang, ladder + Qt) ─────────────────────────────
  #
  # Split out of linux-sanitizers (which used to carry this as a 4th
  # clang-coverage matrix leg) so plain asan/tsan/ubsan can move onto the
  # self-hosted probe while this leg -- the one that builds the full
  # ladder stack (ODBC/SQLite/yaml-cpp/zip) and Qt, and uploads to
  # Codecov -- stays pinned to ubuntu-24.04.
  linux-coverage:
    name: Linux / clang-coverage
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4

      - name: Cache apt packages
        uses: actions/cache@v4
        with:
          path: /var/cache/apt/archives
          key: apt-coverage-${{ hashFiles('.github/workflows/ci.yml') }}
          restore-keys: apt-coverage-

      - name: Install Clang ${{ env.CLANG_VERSION }} from apt.llvm.org
        run: |
          sudo apt-get update -q
          sudo apt-get install -y ninja-build catch2 libsqlite3-dev
          # --fail, a file, and a non-empty check -- never `wget -qO- | sudo
          # bash`: see linux-compilers' identical install step for why the piped
          # form reports success having installed nothing.
          curl -sSL --fail -o /tmp/llvm.sh https://apt.llvm.org/llvm.sh
          test -s /tmp/llvm.sh
          sudo bash /tmp/llvm.sh ${{ env.CLANG_VERSION }}

      # examples/common's hand-written GUI/testkit code is real coverage of
      # morph's client stack (Bridge, backends, QtExecutor, completions --
      # see examples/TESTING.md's "round-7 T4 reframe"), so it belongs in
      # the coverage number the same way the models it will host later do
      # (examples/IMPLEMENTATION.md rule 5).
      - name: Install ODBC + SQLite driver
        run: |
          # unixodbc-dev + libsqliteodbc: the application ladder (built by
          # this job) fetches the Lightweight ORM, whose CMake runs
          # `pkg_check_modules(ODBC REQUIRED odbc)`, and whose ladder fixtures
          # open a real `DRIVER=SQLite3` connection at test time.
          # Named explicitly rather than relied on from the runner image.
          # libyaml-cpp-dev + libzip-dev: Lightweight's own CMakeLists.txt
          # does `find_package(yaml-cpp)`/`find_package(libzip)` as system
          # CONFIG packages, not through CPM (examples/bank/CMakeLists.txt's
          # comment on the identical fetch) — without these, configure fails
          # the moment MORPH_BUILD_LADDER=ON pulls Lightweight in.
          # Dropped from this step by mistake when it was renamed from
          # "Install Qt6 WebSockets" to "Install ODBC + SQLite driver" —
          # every other job that builds the ladder on Linux (Application
          # ladder, all optional features) already carries this pair.
          sudo apt-get install -y libgl1-mesa-dev unixodbc-dev libsqliteodbc libyaml-cpp-dev libzip-dev

      # Not the distro's Qt: examples/common/CMakeLists.txt requires 6.5+
      # unconditionally (not gated on MORPH_BUILD_FORMS_QML) and Ubuntu
      # 24.04 still ships 6.4.2 -- the identical gap the "all optional
      # features" and "Application ladder" jobs' own install-qt-action steps
      # already document. Named qt6-base-dev/qt6-websockets-dev/qt6-tools-dev
      # used to be installed above; replaced wholesale rather than kept
      # alongside aqtinstall's Qt, which would leave two Qt6 installs on the
      # same runner for find_package() to pick between.
      - name: Install Qt ${{ env.QT_VERSION }}
        uses: jurplel/install-qt-action@v4.3.1
        with:
          version: ${{ env.QT_VERSION }}
          modules: qtwebsockets
          cache: true

      - name: Restore sccache
        uses: actions/cache/restore@v4
        with:
          path: /home/runner/.cache/sccache
          key: sccache-clang-coverage-${{ github.sha }}
          restore-keys: sccache-clang-coverage-

      - name: Install sccache
        run: |
          # `--fail` and a file rather than a pipe into tar: see
          # linux-compilers' identical Install sccache step for why an
          # unchecked download reports itself as "not in gzip format".
          curl -sSL --fail -o /tmp/sccache.tar.gz \
            https://github.com/mozilla/sccache/releases/download/v0.9.1/sccache-v0.9.1-x86_64-unknown-linux-musl.tar.gz
          tar -xzf /tmp/sccache.tar.gz --strip-components=1 -C /usr/local/bin \
            sccache-v0.9.1-x86_64-unknown-linux-musl/sccache

      - name: Configure
        run: |
          cmake --preset clang-coverage \
            -DMORPH_BUILD_NET=ON \
            -DMORPH_BUILD_OFFLINE_SQLITE=ON \
            -DMORPH_BUILD_QT=ON \
            -DMORPH_BUILD_LADDER=ON \
            -DMORPH_LADDER_RUNGS=all \
            -DCMAKE_C_COMPILER=clang-${{ env.CLANG_VERSION }} \
            -DCMAKE_CXX_COMPILER=clang++-${{ env.CLANG_VERSION }} \
            -DCMAKE_C_COMPILER_LAUNCHER=sccache \
            -DCMAKE_CXX_COMPILER_LAUNCHER=sccache

      # QT_QPA_PLATFORM=offscreen here too, not just on Test below: Catch2's
      # catch_discover_tests() runs each Qt-linked test binary once at BUILD
      # time to enumerate its cases, which can abort on this headless runner
      # without it — see "Linux / all optional features"'s own Build step
      # for the identical failure this job's build hit once the ladder
      # actually started compiling (no QML here, a narrower Qt surface, but
      # ladder_common_tests still links Qt6::WebSockets).
      - name: Build
        env:
          QT_QPA_PLATFORM: offscreen
        run: cmake --build --preset clang-coverage

      - name: Test
        env:
          # Required for the ladder tests, which open real Qt widgets/sockets
          # on a runner with no display.
          QT_QPA_PLATFORM: offscreen
        run: |
          LLVM_PROFILE_FILE="build/clang-coverage/%p.profraw" ctest --preset clang-coverage

      # Deliberately left on the implicit `success()`, unlike the three test
      # steps that carry `!cancelled()` (ladder-tests' scenario corpus,
      # ladder-sanitizers' Qt transport suites, linux-all-features' fuzz-replay
      # verification). This is a decision, not an oversight, and it is written
      # down so it is not "fixed" later: this step and the two below it consume
      # the Test step's `.profraw` output rather than measuring a surface of
      # their own. Forcing them to run after a failed or truncated test pass
      # would produce a coverage *number* computed from partial profile data --
      # and a number nobody should trust is worse than no number. The rule the
      # three others follow is "a red leg reports everything it was able to
      # measure"; here, nothing was.
      - name: Generate coverage report
        run: bash scripts/coverage.sh

      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v5
        with:
          files: build/clang-coverage/coverage.lcov
          # Without this, codecov-action's own auto-discovery finds every
          # other *.lcov/coverage.* file under the build tree too (its own
          # log says so: "Found 5 coverage files to report") -- including
          # coverage.lcov.raw, the *pre-aggregation* file
          # aggregate_lcov_branches.py rewrites away from, plus unrelated
          # fetched-dependency fixtures
          # (_deps/nlohmann_json-src/.../coverage.test). Codecov then merges
          # all of them, silently re-introducing every record `coverage.lcov`
          # was built to remove. `files:` alone does not disable that scan --
          # this does.
          disable_search: true
          token: ${{ secrets.CODECOV_TOKEN }}

      # No `if:` guard, and none may be added that names `matrix`. This job has
      # no matrix, so `matrix.preset` evaluates to the empty string and any
      # condition testing it is false on every run -- the step is then skipped
      # forever, and a skipped step and a successful one are rendered the same
      # way, so nothing reports it.
      - name: Upload coverage HTML
        uses: actions/upload-artifact@v4
        with:
          name: coverage-report
          path: build/clang-coverage/html/
          # llvm-cov show emits one page per source file across include/morph,
          # examples/common and every rung -- a few thousand small files, which
          # upload-artifact pays per-file overhead on. Bounded rather than kept
          # forever, since the step runs on every coverage build.
          retention-days: 14

      # Cumulative hit/miss for this leg. Without it the cache is
      # unfalsifiable: a thrashing cache and a working one look identical
      # from the outside, and only the build-step duration hints at which
      # one you have. `|| true` so a stats failure never fails the job.
      - name: sccache stats
        if: always()
        run: sccache --show-stats || true

      # Save only on a push to master. Writing a new per-commit entry from
      # every run does not work here: with 16 cache-writing legs at 1 GB each,
      # one generation exceeds GitHub's 10 GB per-repo budget, so legs evict
      # each other and entries rarely survive to be reused. Restricting writes
      # to master keeps the property that makes the cache usable at all (only
      # one branch ever writes, so no branch can delete another's entry) while
      # collapsing the generations that blow the budget. Pull requests still
      # restore, read-only, and get the full benefit.
      - name: Save sccache
        if: github.event_name == 'push' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main')
        uses: actions/cache/save@v4
        with:
          path: /home/runner/.cache/sccache
          key: sccache-clang-coverage-${{ github.sha }}

  # ── Linux: kanban's concurrent-move stress test under ThreadSanitizer ──
  # test_kanban_stress.cpp's [tsan]-tagged TEST_CASE drives BoardModel through
  # a bare morph::bridge::Bridge/morph::backend::LocalBackend directly, on a
  # real morph::exec::ThreadPoolExecutor{4}, with zero Qt frames anywhere in
  # its call graph (see the test file's own header comment) -- so the "a GUI
  # stack under TSan is mostly noise" rationale that keeps the ladder out of
  # linux-sanitizers does not apply to this one test. This job builds only
  # what that test needs -- MORPH_BUILD_LADDER=ON, MORPH_LADDER_RUNGS=kanban,
  # no Qt GUI modules beyond the WebSockets backend the ladder testkit itself
  # requires -- to keep it a minimal, fast, TSan-clean addition rather than
  # pulling every rung's Qt Quick/QML code into the sanitizer matrix.
  #
  # The test must not reach a QtExecutor, and the constraint is load-bearing
  # rather than stylistic: driving the same scenario through
  # BackendRig{Mode::Local, ...} constructs a real morph::qt::QtExecutor for
  # client-facing callback delivery, and that produces 165 ThreadSanitizer
  # warnings bottoming out in genuine Qt-internal frames -- undetectable as
  # real bugs or false positives from outside a TSan-instrumented Qt build.
  # Never constructing one sidesteps the ambiguity rather than resolving it.
  kanban-tsan:
    name: Kanban / ThreadSanitizer
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4

      - name: Cache apt packages
        uses: actions/cache@v4
        with:
          path: /var/cache/apt/archives
          key: apt-kanban-tsan-${{ hashFiles('.github/workflows/ci.yml') }}
          restore-keys: apt-kanban-tsan-

      - name: Install Clang ${{ env.CLANG_VERSION }} from apt.llvm.org
        run: |
          sudo apt-get update -q
          # unixodbc-dev + libsqliteodbc: the ladder (built by this job)
          # fetches the Lightweight ORM, whose CMake runs
          # `pkg_check_modules(ODBC REQUIRED odbc)`, and whose DbFixture
          # opens a real `DRIVER=SQLite3` connection at test time (identical
          # rationale to linux-sanitizers' coverage-leg step and ladder-tests'
          # own install step). Named explicitly rather than relied on from the
          # runner image.
          # libyaml-cpp-dev + libzip-dev: Lightweight's own CMakeLists.txt does
          # `find_package(yaml-cpp)`/`find_package(libzip)` as system CONFIG
          # packages, not through CPM (examples/bank/CMakeLists.txt's comment
          # on the identical fetch) — without these, configure fails the
          # moment MORPH_BUILD_LADDER=ON pulls Lightweight in.
          # libgl1-mesa-dev: every other job that configures MORPH_BUILD_QT=ON
          # together with MORPH_BUILD_LADDER=ON installs this (linux-sanitizers'
          # coverage leg, ladder-tests, linux-all-features) for Qt's GL platform
          # integration; carried here for the same reason even though this leg's
          # test run itself stays off-GUI.
          sudo apt-get install -y ninja-build catch2 libsqlite3-dev \
            unixodbc-dev libsqliteodbc libyaml-cpp-dev libzip-dev libgl1-mesa-dev
          # --fail, a file, and a non-empty check -- never `wget -qO- | sudo
          # bash`: see linux-compilers' identical install step for why the piped
          # form reports success having installed nothing.
          curl -sSL --fail -o /tmp/llvm.sh https://apt.llvm.org/llvm.sh
          test -s /tmp/llvm.sh
          sudo bash /tmp/llvm.sh ${{ env.CLANG_VERSION }}

      # Not the distro's Qt: examples/common/CMakeLists.txt requires 6.5+
      # unconditionally and Ubuntu 24.04 still ships 6.4.2 — the same gap
      # every other job that builds the ladder on Linux already documents.
      - name: Install Qt ${{ env.QT_VERSION }}
        uses: jurplel/install-qt-action@v4.3.1
        with:
          version: ${{ env.QT_VERSION }}
          modules: qtwebsockets
          cache: true

      # Keyed by preset alone (clang-tsan), matching linux-sanitizers' cache:
      # this job's clang-tsan+Qt+kanban build shares the same compiler and
      # much of the same core-library object set as that job's clang-tsan
      # leg, which builds plain clang-tsan+net+offline_sqlite. See
      # linux-compilers' identical comment for why sharing the key is safe.
      - name: Restore sccache
        uses: actions/cache/restore@v4
        with:
          path: /home/runner/.cache/sccache
          key: sccache-clang-tsan-${{ github.sha }}
          restore-keys: sccache-clang-tsan-

      - name: Install sccache
        run: |
          # `--fail` and a file rather than a pipe into tar: see
          # linux-compilers' identical Install sccache step for why an
          # unchecked download reports itself as "not in gzip format".
          curl -sSL --fail -o /tmp/sccache.tar.gz \
            https://github.com/mozilla/sccache/releases/download/v0.9.1/sccache-v0.9.1-x86_64-unknown-linux-musl.tar.gz
          tar -xzf /tmp/sccache.tar.gz --strip-components=1 -C /usr/local/bin \
            sccache-v0.9.1-x86_64-unknown-linux-musl/sccache

      # MORPH_LADDER_RUNGS=kanban (a single rung, not "all"): examples/CMakeLists.txt's
      # rung-selection loop (`if(MORPH_LADDER_RUNGS STREQUAL "all" OR _rung IN_LIST
      # MORPH_LADDER_RUNGS)`) matches a single-value list correctly, and examples/common
      # (the testkit every rung's tests link) is always added regardless of which rungs
      # are selected — so this configures and builds only kanban's ladder targets, not
      # the whole ladder.
      - name: Configure (clang-tsan, kanban only)
        run: |
          cmake --preset clang-tsan \
            -DMORPH_BUILD_QT=ON \
            -DMORPH_BUILD_LADDER=ON \
            -DMORPH_LADDER_RUNGS=kanban \
            -DCMAKE_C_COMPILER=clang-${{ env.CLANG_VERSION }} \
            -DCMAKE_CXX_COMPILER=clang++-${{ env.CLANG_VERSION }} \
            -DCMAKE_C_COMPILER_LAUNCHER=sccache \
            -DCMAKE_CXX_COMPILER_LAUNCHER=sccache

      # QT_QPA_PLATFORM=offscreen here too, not just on Test below: Catch2's
      # catch_discover_tests() runs ladder_kanban_tests once at BUILD time to
      # enumerate its cases, which can abort on this headless runner (no X
      # server) without it — see linux-sanitizers' and ladder-tests' own Build
      # steps for the identical note.
      - name: Build
        env:
          QT_QPA_PLATFORM: offscreen
        run: cmake --build --preset clang-tsan

      # The same assertion linux-sanitizers and ladder-sanitizers make, for the
      # same reason: this job's whole claim is that kanban's stress
      # test ran under ThreadSanitizer, and an uninstrumented binary makes that
      # claim while proving nothing. Keyed on `__tsan_`, not `__asan_` — an
      # ASan-only assertion on a TSan leg is itself a control that measures
      # nothing.
      #
      # QT_QPA_PLATFORM=offscreen, matching the Build step above and the Test
      # step below, because this step sits between them and enumerates the same
      # binaries they do. The sweep begins with `ctest
      # --show-only=json-v1`, and listing a DISCOVERY_MODE PRE_TEST suite *runs*
      # its binary. Nothing this job builds is both Qt-linked and PRE_TEST
      # today -- ladder_kanban_tests is POST_BUILD (cmake/morph_add_rung.cmake),
      # so its enumeration already happened inside the Build step's environment
      # -- which is why this step is green without the variable and not why it
      # is safe. Changing one word to PRE_TEST on any Qt-linked rung suite would
      # make this step fail with `ctest listed no tests`, naming neither Qt nor
      # the display -- a diagnostic that points nowhere near its cause.
      - name: Every ctest binary is instrumented
        env:
          QT_QPA_PLATFORM: offscreen
        run: bash scripts/check_sanitizer_instrumentation.sh build/clang-tsan tsan

      # Every ladder ctest case only ever carries the "ladder"/"ladder-<rung>"
      # labels morph_add_rung() applies (cmake/morph_add_rung.cmake) — Catch2's
      # own tags ([kanban][stress][tsan]) are never translated into ctest
      # labels anywhere in this repo's CMake (no catch_discover_tests call
      # passes ADD_TAGS_AS_LABELS). A "-L tsan" filter would therefore match
      # zero tests and silently run nothing. This test's name is the only
      # thing distinguishing it, and "ThreadSanitizer" appears in exactly one
      # TEST_CASE name across the whole kanban tree (confirmed by grep), so
      # -R selects it precisely.
      - name: Test (kanban's TSan-tagged stress test only)
        env:
          QT_QPA_PLATFORM: offscreen
          # The same suppression file linux-sanitizers' Test step passes. Both
          # entries are libstdc++ refcounts for a shared exception, decremented
          # inside an uninstrumented libstdc++.so.6; the evidence is in
          # cmake/tsan.supp.
          # Without it this leg is a coin toss on a false positive that the
          # other TSan leg already knows is one — and the failure mode of a
          # known false positive is that the next real one is waved past.
          #
          # `second_deadlock_stack=1` for the reason the linux-sanitizers Test
          # step above gives at length, and appended to the same
          # value rather than added as a second `TSAN_OPTIONS:` key, which
          # would silently drop the suppressions file this leg was given in the
          # first place.
          TSAN_OPTIONS: suppressions=${{ github.workspace }}/cmake/tsan.supp:second_deadlock_stack=1
        run: ctest --preset clang-tsan -L ladder-kanban -R ThreadSanitizer --output-on-failure

      # Cumulative hit/miss for this leg. Without it the cache is
      # unfalsifiable: a thrashing cache and a working one look identical
      # from the outside, and only the build-step duration hints at which
      # one you have. `|| true` so a stats failure never fails the job.
      - name: sccache stats
        if: always()
        run: sccache --show-stats || true

      # Save only on a push to master. Writing a new per-commit entry from
      # every run does not work here: with 16 cache-writing legs at 1 GB each,
      # one generation exceeds GitHub's 10 GB per-repo budget, so legs evict
      # each other and entries rarely survive to be reused. Restricting writes
      # to master keeps the property that makes the cache usable at all (only
      # one branch ever writes, so no branch can delete another's entry) while
      # collapsing the generations that blow the budget. Pull requests still
      # restore, read-only, and get the full benefit.
      - name: Save sccache
        if: github.event_name == 'push' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main')
        uses: actions/cache/save@v4
        with:
          path: /home/runner/.cache/sccache
          key: sccache-clang-tsan-${{ github.sha }}

  # ── Linux: the bank example under UndefinedBehaviorSanitizer ──────────
  # No other sanitizer leg builds the bank example: linux-sanitizers,
  # kanban-tsan, ladder-sanitizers and valgrind set zero MORPH_BUILD_BANK_*
  # flags, against eight places elsewhere in this file that set
  # MORPH_BUILD_BANK_EXAMPLE=ON. Bank is not a rung (it is absent from
  # examples/rungs.txt and never calls morph_add_rung(), for the reasons that
  # file gives), so MORPH_BUILD_LADDER=ON does not reach it either. This job is
  # the only instrumented build bank gets.
  #
  # What that covers, stated exactly, because the obvious claim is too strong.
  # An out-of-range double -> std::int64_t conversion in
  # examples/bank/gui/controllers/Format.hpp -- on the path of every amount
  # typed into the bank GUI -- exits bank_gui_tests 1 here with
  #
  #     examples/bank/gui/controllers/Format.hpp:76:38: runtime error:
  #     9.2e+19 is outside the range of representable values of type 'long'
  #
  # but only because a test calls parseMinor with such a value. Measured: with
  # that test absent, the same defective header leaves this leg green. A
  # sanitizer leg reaches only what the suites drive, and this one's reach is
  # bounded by how much of bank they drive.
  #
  # Why a job of its own rather than a flag on linux-sanitizers' clang-ubsan
  # leg. Two measured reasons. (1) That leg builds no Qt, and its own comment
  # reserves the matrix against GUI stacks; bank's GUI is where this class of
  # UB lives, so covering it means adding Qt there. (2) Cold, cacheless, 12
  # cores, clang 22.1.8: that leg's shape (core + net + offline_sqlite, no Qt)
  # is 36s configure / 144s build over 144 ninja edges, and this job's shape is
  # 64s / 391s over 287. Folding one into the other roughly triples the slowest
  # leg of a three-leg matrix, whose duration is then the matrix's. Split out,
  # the three existing legs are untouched and this runs beside them. Same
  # argument as kanban-tsan above.
  #
  # ubsan rather than asan: UBSan is the sanitizer that diagnoses the
  # conversion class above, and an ASan run over a Qt GUI needs the
  # detect_leaks=0 and suppression story ladder-sanitizers already carries,
  # which this job would have to acquire before it could be believed. Bank
  # under ASan is worth having and is not covered here.
  #
  # The bill was measured: turning bank on and instrumenting every one of its
  # targets produces **zero** UBSan findings. bank_tests (145 assertions in 21
  # cases), bank_gui_tests (19 in 5) and bank_gui_qml_tests (32 in 2) all pass
  # clean, and so does the full 1696-test suite of this configure. Nothing is
  # suppressed here and there is no allowlist entry.
  bank-sanitizers:
    name: Bank example / UBSan
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4

      - name: Cache apt packages
        uses: actions/cache@v4
        with:
          path: /var/cache/apt/archives
          key: apt-bank-ubsan-${{ hashFiles('.github/workflows/ci.yml') }}
          restore-keys: apt-bank-ubsan-

      - name: Install Clang ${{ env.CLANG_VERSION }} from apt.llvm.org
        run: |
          sudo apt-get update -q
          # The same set kanban-tsan and ladder-sanitizers install, and for
          # the same reasons: unixodbc-dev + libsqliteodbc because
          # examples/bank/CMakeLists.txt fetches the Lightweight ORM, whose
          # CMake runs `pkg_check_modules(ODBC REQUIRED odbc)` and whose
          # fixtures open a real `DRIVER=SQLite3` connection at test time;
          # libyaml-cpp-dev + libzip-dev because Lightweight's own
          # CMakeLists.txt finds them as system CONFIG packages rather than
          # through CPM; libgl1-mesa-dev for Qt's GL platform integration,
          # which every job configuring MORPH_BUILD_QT=ON alongside a Qt GUI
          # target installs.
          sudo apt-get install -y ninja-build catch2 libsqlite3-dev \
            unixodbc-dev libsqliteodbc libyaml-cpp-dev libzip-dev libgl1-mesa-dev
          # --fail, a file, and a non-empty check -- never `wget -qO- | sudo
          # bash`: see linux-compilers' identical install step for why the piped
          # form reports success having installed nothing.
          curl -sSL --fail -o /tmp/llvm.sh https://apt.llvm.org/llvm.sh
          test -s /tmp/llvm.sh
          sudo bash /tmp/llvm.sh ${{ env.CLANG_VERSION }}

      # Not the distro's Qt: examples/common/CMakeLists.txt requires 6.5+
      # unconditionally and Ubuntu 24.04 still ships 6.4.2 — the same gap
      # every other job that builds Qt on Linux already documents.
      - name: Install Qt ${{ env.QT_VERSION }}
        uses: jurplel/install-qt-action@v4.3.1
        with:
          version: ${{ env.QT_VERSION }}
          modules: qtwebsockets
          cache: true

      # Keyed by preset alone (clang-ubsan), matching linux-sanitizers' cache:
      # this job's clang-ubsan+Qt+bank build shares the same compiler and much
      # of the same core-library object set as that job's clang-ubsan leg. See
      # linux-compilers' identical comment for why sharing the key is safe.
      - name: Restore sccache
        uses: actions/cache/restore@v4
        with:
          path: /home/runner/.cache/sccache
          key: sccache-clang-ubsan-${{ github.sha }}
          restore-keys: sccache-clang-ubsan-

      - name: Install sccache
        run: |
          # `--fail` and a file rather than a pipe into tar: see
          # linux-compilers' identical Install sccache step for why an
          # unchecked download reports itself as "not in gzip format".
          curl -sSL --fail -o /tmp/sccache.tar.gz \
            https://github.com/mozilla/sccache/releases/download/v0.9.1/sccache-v0.9.1-x86_64-unknown-linux-musl.tar.gz
          tar -xzf /tmp/sccache.tar.gz --strip-components=1 -C /usr/local/bin \
            sccache-v0.9.1-x86_64-unknown-linux-musl/sccache

      # MORPH_BUILD_BANK_GUI=ON, not MORPH_BUILD_BANK_EXAMPLE alone: the
      # controllers and Format.hpp -- the numeric-conversion surface this job
      # exists for -- live in bank_gui_lib, which only exists when the GUI
      # option adds gui/. Without it this job instruments bank_lib and the ORM
      # and misses the half of bank that does the arithmetic. No MORPH_BUILD_LADDER: bank is not a rung, so
      # it would add every rung's tree for nothing.
      - name: Configure (clang-ubsan, bank example + GUI)
        run: |
          cmake --preset clang-ubsan \
            -DMORPH_BUILD_QT=ON \
            -DMORPH_BUILD_BANK_EXAMPLE=ON \
            -DMORPH_BUILD_BANK_GUI=ON \
            -DCMAKE_C_COMPILER=clang-${{ env.CLANG_VERSION }} \
            -DCMAKE_CXX_COMPILER=clang++-${{ env.CLANG_VERSION }} \
            -DCMAKE_C_COMPILER_LAUNCHER=sccache \
            -DCMAKE_CXX_COMPILER_LAUNCHER=sccache

      # QT_QPA_PLATFORM=offscreen at build time as well as test time: Catch2's
      # catch_discover_tests() runs each POST_BUILD-discovered Qt-linked test
      # binary once during the build to enumerate its cases — see ladder-tests'
      # own Build step. In this configure that is morph_qt_tests
      # (tests/qt/CMakeLists.txt:91); it is *not* bank's three suites, which
      # are PRE_TEST and therefore enumerate at ctest time instead. The step
      # below is where that matters.
      - name: Build
        env:
          QT_QPA_PLATFORM: offscreen
        run: cmake --build --preset clang-ubsan

      # The same assertion linux-sanitizers, ladder-sanitizers and kanban-tsan
      # make. It is not a formality here: bank's targets need an
      # apply_sanitizers() call of their own, and this sweep is what says so
      # rather than letting the leg report a clean bank run over uninstrumented
      # binaries. Measured with bank configured on and the AF_SANITIZER blocks
      # absent:
      #
      #     ::error::check_sanitizer_instrumentation: 3 of 9 ctest binaries
      #     are not ubsan-instrumented
      #
      # naming bank_tests, bank_gui_tests and bank_gui_qml_tests. With the
      # blocks in place the same sweep reports 9 of 9.
      #
      # QT_QPA_PLATFORM=offscreen, and this is the step that cannot do without
      # it. The sweep's first act is `ctest --show-only=json-v1`, and ctest
      # is exactly where bank's PRE_TEST discovery runs: listing the tests
      # *executes* `bank_gui_qml_tests --list-tests`, whose main constructs a
      # QGuiApplication (examples/common/testkit/testkit_main.cpp) before
      # Catch2 ever sees the flag. With no display and no QT_QPA_PLATFORM that
      # aborts; Catch2's CatchAddTests.cmake raises a message(FATAL_ERROR) on a
      # nonzero discovery, and ctest then exits 8 having printed no JSON at all
      # — not bank's entries missing, the entire listing, every other suite
      # included. The sweep correctly refuses to pass having examined nothing,
      # so the symptom is the guard and the cause is the missing variable --
      # a diagnostic worth expecting. The Test step below declares the same value,
      # which is the point: this sweep's subject is the binaries that step will
      # run, so it has to enumerate them in that step's environment.
      #
      # Reproduced locally against this very configure (clang 22.1.8, Catch2
      # 3.16.0, Qt 6.11.2 — the runner's versions differ, the code path does
      # not), by emulating the runner's one distinguishing property, a headless
      # session:
      #
      #     $ env -u DISPLAY -u WAYLAND_DISPLAY \
      #           bash scripts/check_sanitizer_instrumentation.sh \
      #                build/clang-ubsan ubsan
      #     ::error::check_sanitizer_instrumentation: ctest listed no tests in
      #     build/clang-ubsan -- this check would pass having examined nothing
      #     `ctest --show-only=json-v1` exited 8 and wrote 0 bytes of stdout.
      #       | CMake Error at .../CatchAddTests.cmake:307 (message):
      #       |   Error listing tests from executable
      #       |   '.../examples/bank/bank_gui_qml_tests':
      #       |     Result: Subprocess aborted
      #
      #     $ env -u DISPLAY -u WAYLAND_DISPLAY QT_QPA_PLATFORM=offscreen \
      #           bash scripts/check_sanitizer_instrumentation.sh \
      #                build/clang-ubsan ubsan
      #     check_sanitizer_instrumentation: 9 ctest binaries all carry
      #     __ubsan_ symbols (0 allowlisted).
      #
      # Same tree, same build, one environment variable apart. That is also
      # why the two earlier attempts to reproduce this job's failure locally
      # could not: a workstation has a display, so the same command enumerates
      # all nine there whether or not the variable is set.
      - name: Every ctest binary is instrumented
        env:
          QT_QPA_PLATFORM: offscreen
        run: bash scripts/check_sanitizer_instrumentation.sh build/clang-ubsan ubsan

      # -L bank, not the whole suite: this configure also builds morph_tests
      # and morph_qt_tests, which linux-sanitizers' clang-ubsan leg already
      # runs under the identical instrumentation -- 1696 tests and 212s
      # measured locally, against 28 tests and 6s for bank's own three suites.
      # The label is applied by examples/bank/CMakeLists.txt's
      # catch_discover_tests calls; a filter that matched nothing would be this
      # repository's named failure mode, and CMakePresets.json's base-test sets
      # `noTestsAction: error` so it exits 8 with "No tests were found!!!"
      # instead (confirmed against a tree built without bank).
      - name: Test (bank's suites only)
        env:
          QT_QPA_PLATFORM: offscreen
          # halt_on_error, because apply_sanitizers()'s ubsan arm already
          # passes -fno-sanitize-recover=undefined -- this makes the runtime
          # agree with the compile line rather than leaving the two to differ,
          # the same pair ladder-sanitizers' Test step sets.
          UBSAN_OPTIONS: print_stacktrace=1:halt_on_error=1
        run: ctest --preset clang-ubsan -L bank --output-on-failure

      # Cumulative hit/miss for this leg. Without it the cache is
      # unfalsifiable: a thrashing cache and a working one look identical from
      # the outside, and only the build-step duration hints at which one you
      # have. `|| true` so a stats failure never fails the job.
      - name: sccache stats
        if: always()
        run: sccache --show-stats || true

      # Save only on a push to master, for the cache-budget reason every other
      # leg's identical step gives.
      - name: Save sccache
        if: github.event_name == 'push' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main')
        uses: actions/cache/save@v4
        with:
          path: /home/runner/.cache/sccache
          key: sccache-clang-ubsan-${{ github.sha }}

  # ── Linux: Qt WebSocket backend build + tests ─────────────────────────
  linux-qt:
    name: Linux / Qt6 WebSockets
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4

      - name: Cache apt packages
        uses: actions/cache@v4
        with:
          path: /var/cache/apt/archives
          key: apt-qt-${{ hashFiles('.github/workflows/ci.yml') }}
          restore-keys: apt-qt-

      - name: Install GCC 15, ninja, catch2, Qt6 WebSockets
        run: |
          sudo apt-get update -q
          sudo apt-get install -y software-properties-common
          sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
          sudo apt-get update -q
          sudo apt-get install -y gcc-15 g++-15 ninja-build catch2 \
            qt6-base-dev qt6-websockets-dev qt6-tools-dev libgl1-mesa-dev
          sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-15 15
          sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-15 15

      # Keyed by preset alone (gcc-debug), matching linux-compilers' cache:
      # this job's gcc-debug+Qt build shares the same core-library object set
      # as linux-compilers' plain gcc-debug leg, ladder-tests' gcc-debug+Qt+
      # ladder build, and valgrind's gcc-debug+net build. See linux-compilers'
      # identical comment for why sharing the key across jobs is safe.
      - name: Restore sccache
        uses: actions/cache/restore@v4
        with:
          path: /home/runner/.cache/sccache
          key: sccache-gcc-debug-${{ github.sha }}
          restore-keys: sccache-gcc-debug-

      - name: Install sccache
        run: |
          # `--fail` and a file rather than a pipe into tar: see
          # linux-compilers' identical Install sccache step for why an
          # unchecked download reports itself as "not in gzip format".
          curl -sSL --fail -o /tmp/sccache.tar.gz \
            https://github.com/mozilla/sccache/releases/download/v0.9.1/sccache-v0.9.1-x86_64-unknown-linux-musl.tar.gz
          tar -xzf /tmp/sccache.tar.gz --strip-components=1 -C /usr/local/bin \
            sccache-v0.9.1-x86_64-unknown-linux-musl/sccache

      - name: Configure (gcc-debug with MORPH_BUILD_QT=ON)
        run: |
          cmake --preset gcc-debug \
            -DMORPH_BUILD_QT=ON \
            -DCMAKE_C_COMPILER_LAUNCHER=sccache \
            -DCMAKE_CXX_COMPILER_LAUNCHER=sccache

      - name: Build
        run: cmake --build --preset gcc-debug

      # ── moc output that climbs out of the build tree ─────────────────
      # Runs here rather than alongside the repo's other lint gates because
      # what it inspects is generated: it needs an AUTOMOC target to have
      # actually been built. The checker's own self-test needs none of that and
      # runs in drift-guard.yml's automoc-include-lint job instead, so it still
      # reports when a build fails.
      - name: Check no generated moc include ascends
        run: bash scripts/check_automoc_includes.sh build/gcc-debug

      - name: Test (offscreen Qt platform)
        env:
          QT_QPA_PLATFORM: offscreen
        run: ctest --preset gcc-debug

      # Cumulative hit/miss for this leg. Without it the cache is
      # unfalsifiable: a thrashing cache and a working one look identical
      # from the outside, and only the build-step duration hints at which
      # one you have. `|| true` so a stats failure never fails the job.
      - name: sccache stats
        if: always()
        run: sccache --show-stats || true

      # Save only on a push to master. Writing a new per-commit entry from
      # every run does not work here: with 16 cache-writing legs at 1 GB each,
      # one generation exceeds GitHub's 10 GB per-repo budget, so legs evict
      # each other and entries rarely survive to be reused. Restricting writes
      # to master keeps the property that makes the cache usable at all (only
      # one branch ever writes, so no branch can delete another's entry) while
      # collapsing the generations that blow the budget. Pull requests still
      # restore, read-only, and get the full benefit.
      - name: Save sccache
        if: github.event_name == 'push' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main')
        uses: actions/cache/save@v4
        with:
          path: /home/runner/.cache/sccache
          key: sccache-gcc-debug-${{ github.sha }}

  # ── Linux: application ladder testkit (path-filtered) ─────────────────
  ladder-tests:
    name: Application ladder
    needs: probe-self-hosted
    runs-on: ${{ fromJSON(needs.probe-self-hosted.outputs.runs_on) }}
    env:
      # See linux-compilers' identical env block for why FASTCACHE_ADDR is
      # conditional, and why FASTCACHE_AUTO_INSTALL has to be a -D flag
      # (MORPH_FASTCACHE_AUTO_INSTALL_FLAG) rather than an env var of that
      # name -- CompileCache.cmake declares it as a plain option(), which
      # CMake never reads from the environment.
      FASTCACHE_ADDR: ${{ contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted') && 'host.docker.internal:6674' || '' }}
      MORPH_FASTCACHE_AUTO_INSTALL_FLAG: ${{ contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted') && '-DFASTCACHE_AUTO_INSTALL=ON' || '' }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # need history for the changed-paths diff below

      - name: Determine whether the ladder needs to run
        id: filter
        run: |
          # Not because `echo | grep` can lose a status today -- `echo` does
          # not fail -- but because this block decides whether a whole job
          # runs, and the next edit to it is the one that adds a pipeline
          # that can. Nothing enforces this rule across the file's other `run:`
          # blocks, so it is a convention rather than something CI holds you to.
          set -o pipefail
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            base="${{ github.event.pull_request.base.sha }}"
          else
            base="${{ github.event.before }}"
          fi
          if [ -z "$base" ] || ! git cat-file -e "$base" 2>/dev/null; then
            echo "run=true" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          changed=$(git diff --name-only "$base" HEAD)
          # The pattern is generated from examples/rungs.txt, never written
          # here. A hand-copied rung alternation drifts behind the file it
          # copies, and the drift is silent: a change confined to a rung the
          # pattern has not caught up with matches nothing and skips this job,
          # and a filter that matches nothing looks exactly like one that
          # correctly decided there was nothing to do. See
          # scripts/ladder_rungs.sh for what the non-rung half of the pattern
          # covers and why.
          pattern="$(bash scripts/ladder_rungs.sh ci-path-regex)"
          echo "ladder path filter: $pattern"
          if echo "$changed" | grep -qE "$pattern"; then
            echo "run=true" >> "$GITHUB_OUTPUT"
          else
            echo "run=false" >> "$GITHUB_OUTPUT"
          fi

      # ── Every scenario corpus must be one this job actually runs ──────
      # The step at the end of this job runs scripts/scenario/run_scenarios.py
      # over the corpus. A corpus can drop out of that run in two ways, and
      # neither announces itself:
      #
      #   * a scenarios/<name>/ directory with no RungSpec in run_scenarios.py.
      #     The driver's default set is the intersection of the two, so an
      #     unknown directory is simply not in it -- and passing --rung <name>
      #     for it is an argparse error, not a run.
      #   * a rung this job builds no server for. The driver exits 2 in that
      #     case (find_server), which is correct and deliberately not softened
      #     into a skip -- but it only says so after a full Qt + ladder build.
      #
      # Both are the same failure one level down: a gate that quietly
      # runs five corpora out of six reports green exactly as loudly as one
      # that ran them all. So they are checked here instead, on a bare
      # checkout, in seconds, before anything is installed or compiled.
      #
      # A corpus can also arrive for something that is not a ladder rung at
      # all. examples/bank is the live case: its server comes
      # from a local add_executable() rather than morph_add_rung(), and bank is
      # deliberately absent from examples/rungs.txt. So the check has a third
      # arm for a corpus whose server is declared that way, and this job
      # configures -DMORPH_BUILD_BANK_EXAMPLE=ON and builds ladder_bank_server
      # by name below -- rather than letting the corpus run five of six
      # directories in silence, or dropping bank into rungs.txt to buy silence.
      - name: Check every scenario corpus has a server this job builds
        if: steps.filter.outputs.run == 'true'
        run: |
          set -euo pipefail
          corpora="$(find scripts/scenario/scenarios -mindepth 1 -maxdepth 1 -type d -printf '%f\n' | sort)"
          if [ -z "$corpora" ]; then
            echo "::error::scripts/scenario/scenarios/ holds no corpus directories -- the scenario step at the end of this job would report success having run nothing"
            exit 1
          fi

          # The rungs run_scenarios.py knows how to start a server for. Read
          # out of the module rather than restated here: a second copy of this
          # list is a second thing that can fall behind.
          known="$(python3 - <<'PY'
          import importlib.util
          import sys

          spec = importlib.util.spec_from_file_location(
              "run_scenarios", "scripts/scenario/run_scenarios.py")
          module = importlib.util.module_from_spec(spec)
          # Registered before exec_module: @dataclasses.dataclass looks its
          # class's own module up in sys.modules while decorating, and raises
          # if it is not there yet.
          sys.modules[spec.name] = module
          spec.loader.exec_module(module)
          print("\n".join(sorted(module.RUNGS)))
          PY
          )"

          # The rungs this job configures: -DMORPH_LADDER_RUNGS=all below
          # reaches exactly the names in examples/rungs.txt.
          configured="$(bash scripts/ladder_rungs.sh list | sort)"

          # The third way a corpus can have a server this job builds: a plain
          # add_executable(ladder_<rung>_server) in examples/<rung>/CMakeLists.txt,
          # with no line in examples/rungs.txt at all. bank is that case --
          # it predates the ladder, carries no rung number,
          # and listing it in rungs.txt would enrol it in every consumer that
          # derives from that file rather than describe it, which rungs.txt's
          # own comment settles at length. So the `configured` arm below cannot
          # see bank and never will.
          #
          # What stands in for a rungs.txt line is the target's own declaration.
          # Keyed on that rather than on the name "bank": a hardcoded name would
          # keep passing after someone deleted the add_executable(), which is
          # precisely the state -- a corpus with no server -- this whole step
          # exists to refuse. Delete it and this grep stops matching, the
          # rungs.txt arm fires again, and the job says so on a bare checkout
          # instead of after a full Qt build. Written over ${1} so the next
          # corpus that arrives this way needs no edit here, only the configure
          # flag and the named build further down.
          #
          # This is an extra arm, not a relaxation: a corpus that is neither a
          # listed rung nor a local target still falls through to the error.
          declares_local_server() {
            grep -qE "^[[:space:]]*add_executable\([[:space:]]*ladder_${1}_server([[:space:]]|\)|$)" \
              "examples/${1}/CMakeLists.txt" 2>/dev/null
          }

          status=0
          for rung in $corpora; do
            if ! printf '%s\n' "$known" | grep -qxF "$rung"; then
              echo "::error::scripts/scenario/scenarios/${rung}/ has no RungSpec in scripts/scenario/run_scenarios.py, so nothing can start a server for it and the driver would leave it out of its default set"
              status=1
            elif printf '%s\n' "$configured" | grep -qxF "$rung"; then
              # A listed rung: its server is morph_add_rung()'s implicit target,
              # and that macro derives the sources from src/server/. No such
              # directory means no such target, however green rungs.txt looks.
              if [ ! -d "examples/${rung}/src/server" ]; then
                echo "::error::examples/${rung}/src/server/ does not exist, so cmake/morph_add_rung.cmake declares no ladder_${rung}_server to run scripts/scenario/scenarios/${rung}/ against"
                status=1
              else
                echo "ok: ${rung} -- corpus, RungSpec and ladder_${rung}_server all accounted for"
              fi
            elif declares_local_server "$rung"; then
              echo "ok: ${rung} -- corpus, RungSpec and a local ladder_${rung}_server in examples/${rung}/CMakeLists.txt all accounted for"
            else
              echo "::error::scripts/scenario/scenarios/${rung}/ is a corpus for '${rung}', which is neither listed in examples/rungs.txt nor served by an add_executable(ladder_${rung}_server) in examples/${rung}/CMakeLists.txt -- this job configures no ladder_${rung}_server for it. Either list it there, or declare that target and make this job configure and build it (see bank's -DMORPH_BUILD_BANK_EXAMPLE=ON below)."
              status=1
            fi
          done
          exit "$status"

      - name: Cache apt packages
        if: steps.filter.outputs.run == 'true'
        uses: actions/cache@v4
        with:
          path: /var/cache/apt/archives
          key: apt-qt-${{ hashFiles('.github/workflows/ci.yml') }}
          restore-keys: apt-qt-

      - name: Install GCC 15, ninja, catch2
        if: steps.filter.outputs.run == 'true'
        run: |
          sudo apt-get update -q
          sudo apt-get install -y software-properties-common
          sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
          sudo apt-get update -q
          # libsqlite3-dev: Lightweight's own CMakeLists.txt does
          # find_package(SQLite3) as a system CONFIG package. GitHub-hosted
          # ubuntu-24.04 ships it preinstalled; a bare self-hosted image does
          # not, so configure fails with "Could NOT find SQLite3" the moment
          # MORPH_BUILD_LADDER=ON pulls Lightweight in without it.
          # unixodbc-dev + libsqliteodbc: the application ladder fetches the
          # Lightweight ORM, whose CMake runs
          # `pkg_check_modules(ODBC REQUIRED odbc)`, and whose ladder fixtures
          # open a real `DRIVER=SQLite3` connection at test time.
          # Named explicitly rather than relied on from the runner image.
          # libyaml-cpp-dev + libzip-dev: Lightweight's own CMakeLists.txt
          # does `find_package(yaml-cpp)`/`find_package(libzip)` as system
          # CONFIG packages, not through CPM (examples/bank/CMakeLists.txt's
          # comment on the identical fetch) — without these, configure fails
          # the moment MORPH_BUILD_LADDER=ON pulls Lightweight in.
          # Qt itself is installed by the aqtinstall step below, not apt: see
          # that step's comment for why the distro package is unusable here.
          sudo apt-get install -y gcc-15 g++-15 ninja-build catch2 \
            libsqlite3-dev libyaml-cpp-dev libzip-dev libgl1-mesa-dev \
            unixodbc-dev libsqliteodbc
          sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-15 15
          sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-15 15

      # Not the distro's Qt: examples/common/CMakeLists.txt requires 6.5+
      # (QQmlApplicationEngine::loadFromModule, used by MORPH_BUILD_FORMS_QML
      # rungs) and Ubuntu 24.04 still ships 6.4.2 — the exact gap the "all
      # optional features" job's identical step already documents. This job
      # configures MORPH_BUILD_LADDER=ON without MORPH_BUILD_FORMS_QML, but
      # examples/common/CMakeLists.txt's Qt6 6.5 REQUIRED applies unconditionally
      # (it is not gated on MORPH_BUILD_FORMS_QML), so the floor still bites here.
      - name: Install Qt ${{ env.QT_VERSION }}
        if: steps.filter.outputs.run == 'true'
        uses: jurplel/install-qt-action@v4.3.1
        with:
          version: ${{ env.QT_VERSION }}
          modules: qtwebsockets
          cache: true

      # Keyed by preset alone (gcc-debug), matching linux-qt's cache above:
      # this job's gcc-debug+Qt+ladder build shares the same core-library
      # objects as linux-compilers' plain gcc-debug leg and linux-qt's
      # gcc-debug+Qt build.

      # Skipped on the self-hosted path: see linux-compilers' identical
      # Restore/Install sccache steps for why (installing sccache
      # unconditionally would permanently defeat fastcache-cc auto-install).
      - name: Restore sccache
        if: "steps.filter.outputs.run == 'true' && !contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted')"
        uses: actions/cache/restore@v4
        with:
          path: /home/runner/.cache/sccache
          key: sccache-gcc-debug-${{ github.sha }}
          restore-keys: sccache-gcc-debug-

      - name: Install sccache
        if: "steps.filter.outputs.run == 'true' && !contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted')"
        run: |
          # `--fail` and a file rather than a pipe into tar: see
          # linux-compilers' identical Install sccache step for why an
          # unchecked download reports itself as "not in gzip format".
          curl -sSL --fail -o /tmp/sccache.tar.gz \
            https://github.com/mozilla/sccache/releases/download/v0.9.1/sccache-v0.9.1-x86_64-unknown-linux-musl.tar.gz
          tar -xzf /tmp/sccache.tar.gz --strip-components=1 -C /usr/local/bin \
            sccache-v0.9.1-x86_64-unknown-linux-musl/sccache

      # No -DCMAKE_..._COMPILER_LAUNCHER=sccache: see linux-compilers'
      # Configure steps for why leaving it unset is what lets fastcache-cc
      # be selected.
      # -DMORPH_BUILD_BANK_EXAMPLE=ON is what puts ladder_bank_server in this
      # build tree. bank is not a rung, so -DMORPH_LADDER_RUNGS=all does not
      # reach it: the root CMakeLists.txt guards add_subdirectory(examples/bank)
      # on that option alone (OFF by default -- bank pulls the Lightweight ORM
      # in), and examples/bank/CMakeLists.txt then declares the server inside
      # its own if(MORPH_BUILD_QT), which this job already sets. Nothing new has
      # to be installed for it: the apt step above already names Lightweight's
      # libsqlite3-dev/libyaml-cpp-dev/libzip-dev/unixodbc-dev/libsqliteodbc
      # (MORPH_BUILD_LADDER=ON fetches the same pinned ORM through
      # examples/common) and libgl1-mesa-dev, and the server itself links only
      # Qt6::Core and Qt6::WebSockets -- the aqtinstall step already asks for
      # qtwebsockets.
      - name: Configure (gcc-debug, ladder + Qt + bank on)
        if: steps.filter.outputs.run == 'true'
        run: |
          cmake --preset gcc-debug \
            -DMORPH_BUILD_QT=ON \
            -DMORPH_BUILD_LADDER=ON \
            -DMORPH_LADDER_RUNGS=all \
            -DMORPH_BUILD_BANK_EXAMPLE=ON \
            $MORPH_FASTCACHE_AUTO_INSTALL_FLAG

      # QT_QPA_PLATFORM=offscreen here too, not just on Test below: Catch2's
      # catch_discover_tests() runs each Qt-linked test binary once at BUILD
      # time to enumerate its cases, which aborts on a headless runner (no X
      # server) without it — see "Linux / all optional features"'s own Build
      # step for the identical note. This job has not hit it in practice
      # (its ladder test binaries' discovery apparently succeeds without a
      # platform anyway), but the risk is structurally identical, so it is
      # set defensively rather than left to reappear the next time a rung
      # adds a Qt Quick-linked test binary here.
      - name: Build
        if: steps.filter.outputs.run == 'true'
        env:
          QT_QPA_PLATFORM: offscreen
        run: |
          cmake --build --preset gcc-debug
          # ladder_bank_server is already in the all-target above whenever the
          # configure got -DMORPH_BUILD_BANK_EXAMPLE=ON, so this second
          # invocation is a no-op then. It is here for when it is not: drop that
          # flag and the all-target build stays green while bank is simply not
          # in the tree, and the next thing to notice would be the scenario step
          # exiting 2 a Qt build later. Naming the target turns that into "no
          # rule to make target" here instead. The pre-flight near the top of
          # this job cannot cover this half -- it reads the source tree, not the
          # configure.
          cmake --build --preset gcc-debug --target ladder_bank_server

      # ── moc output that climbs out of the build tree ─────────────────
      # Same gate as linux-qt above, and for the same reason -- see its
      # comment. This job is the one that matters most: ladder_<rung>_gui_lib
      # is the AUTOMOC target every ladder_<rung>_tests binary links, so this
      # build tree is the one carrying the output that stops compiling when a
      # generated include ascends.
      - name: Check no generated moc include ascends
        if: steps.filter.outputs.run == 'true'
        run: bash scripts/check_automoc_includes.sh build/gcc-debug

      # ── Two ctest entries under one name ──────────────────────────────
      # A ctest name is global to the build tree, not scoped to the target it
      # was discovered from, and rung test binaries share TEST_CASE names
      # freely. Every by-name operation then addresses both entries at once:
      # `set_tests_properties(<name> PROPERTIES LABELS ...)` reaches both and
      # CTest *appends*, so one entry accumulates the other rung's label and
      # `ctest -L ladder-<rung>` runs another rung's binary alongside its own
      # (measured once as crm reporting on 180 cases while owning 168); a
      # failure line then names a test that exists twice. cmake/morph_add_rung.cmake's TEST_PREFIX makes
      # those names unique by construction -- this is what keeps them that way
      # the next time a rung is template-copied or a suite is registered by
      # hand.
      #
      # Here, and only here: this is the job that configures every rung at once
      # (-DMORPH_LADDER_RUNGS=all), which is the only configuration in which a
      # cross-rung collision can exist to be found. It runs before the Test step
      # below rather than after, so a build whose test selection is ambiguous
      # says so before the suite is spent on it. The gate's own self-test is in
      # drift-guard.yml, which needs no build.
      - name: Check no two ctest tests share a name
        if: steps.filter.outputs.run == 'true'
        run: bash scripts/check_ctest_name_collisions.sh build/gcc-debug

      - name: Test (offscreen Qt platform, ladder tests only, stress excluded)
        if: steps.filter.outputs.run == 'true'
        env:
          QT_QPA_PLATFORM: offscreen
        run: ctest --preset gcc-debug -L ladder -LE stress --output-on-failure

      # ── The scenario corpus, against the servers just built ────────────
      # This step is the only place in CI that runs
      # scripts/scenario/run_scenarios.py. Without it the corpus can be refused
      # wholesale by a real server with every workflow still green: measured
      # once as sixteen of sixteen ledger scenarios refused for five days and
      # through a merge, while drift-guard.yml's scenario-coverage job reported
      # "ledger actions 18/18 dispatched, workflows 16/16" throughout. That job
      # parses the corpus; only running it can see a refusal.
      #
      # Here rather than in drift-guard.yml, for the reason drift-guard.yml's
      # own comment gives for deferring it: running the corpus needs the
      # ladder_<rung>_server binaries, which that workflow deliberately has no
      # build to produce. This job already builds every one of them
      # unconditionally -- each rung's from cmake/morph_add_rung.cmake, and
      # bank's from examples/bank/CMakeLists.txt under the
      # -DMORPH_BUILD_BANK_EXAMPLE=ON the Configure step above passes -- so the
      # build this step needs is already paid for above.
      #
      # --rung is passed once per corpus directory found on disk rather than
      # left to the driver's default: the set that runs is then demonstrably
      # the set that exists, and the check near the top of this job has already
      # refused any corpus this job could not have run. --build-dir names the
      # build, so a stale binary in some other build tree cannot be picked up.
      #
      # A missing binary is not tolerated. run_scenarios.py exits 2 when a
      # server is absent and that is the right answer; softening it into a skip
      # would rebuild the blindness this step exists to end.
      # `!cancelled()` rather than the implicit `success()`: this step tests a
      # different surface from the ctest step above it (the scenario corpus
      # against real servers, versus the ladder unit tests), so a red ctest
      # skipping it leaves that surface unmeasured with nothing in the log
      # distinguishing "fine" from "never attempted" -- and the next push pays
      # a full 26-74 minute cycle to discover it. Not `always()`, which also
      # fires during teardown of a *cancelled* run and manufactures a leg that
      # stopped within seconds of its siblings looking like a defect rather
      # than a cancellation. The job's conclusion is the same either way: a
      # red step keeps the job red.
      - name: Run the scenario corpus against the built servers
        if: "!cancelled() && steps.filter.outputs.run == 'true'"
        env:
          QT_QPA_PLATFORM: offscreen
        run: |
          set -euo pipefail
          rungs=()
          for dir in scripts/scenario/scenarios/*/; do
            rungs+=(--rung "$(basename "$dir")")
          done
          echo "corpus rungs: ${rungs[*]}"
          python3 scripts/scenario/run_scenarios.py \
            --build-dir build/gcc-debug "${rungs[@]}"

      # Cumulative hit/miss for this leg. Without it the cache is
      # unfalsifiable: a thrashing cache and a working one look identical
      # from the outside, and only the build-step duration hints at which
      # one you have. `|| true` so a stats failure never fails the job.
      #
      # Guarded the same way as the Install/Restore sccache steps above:
      # sccache is never installed on the self-hosted path.
      - name: sccache stats
        if: "always() && steps.filter.outputs.run == 'true' && !contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted')"
        run: sccache --show-stats || true

      # Cache statistics for this leg. The `sccache stats` step is skipped
      # whenever the probe put this job on the self-hosted fleet, because
      # sccache is not the launcher there -- fastcache-cc is. Nothing replaced
      # it, so those legs ran with no cache reporting at all: exactly the
      # "unfalsifiable" state the sccache step's own comment warns about, where
      # a thrashing cache and a working one look identical from the outside and
      # only the build duration hints at which one you have.
      #
      # The line that matters is
      #     unavailable : N  (x% of all compiles -- CACHE NOT REACHED)
      # which is how a daemon that is configured but never answering shows up.
      # Configure still prints "Enabling fastcache-cc at ..." in that case and
      # the build simply takes as long as a cold one, so no other signal in the
      # job would reveal it.
      #
      # Mirror of the sccache step's condition, so exactly one of the two runs.
      # `|| true` for the same reason it has one: a stats failure must never
      # fail the job.
      - name: fastcache-cc stats
        if: "always() && steps.filter.outputs.run == 'true' && contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted')"
        run: |
          FC="$(command -v fastcache-cc || true)"
          if [ -z "$FC" ]; then
            FC="$(ls -t "$HOME"/.cache/fastcache-cc/*/*/fastcache-cc 2>/dev/null | head -1 || true)"
          fi
          if [ -z "$FC" ]; then
            echo "::warning::fastcache-cc not found on a self-hosted runner -- the build ran uncached."
            exit 0
          fi
          echo "launcher: $FC   FASTCACHE_ADDR=${FASTCACHE_ADDR:-<unset>}"
          # This job's own numbers, not the runner's lifetime totals. The
          # bare form is kept underneath because the whole-runner view is
          # what shows eviction pressure across jobs, which a single job's
          # slice cannot.
          "$FC" --show-stats --prefetch-group "$FASTCACHE_PREFETCH_GROUP" || true
          echo "--- whole runner, all jobs (context for the above) ---"
          "$FC" --show-stats || true

      # Save only on a push to master. Every run used to write a new
      # per-commit entry, and with 16 cache-writing legs at 1 GB each one
      # generation already exceeds GitHub's 10 GB per-repo budget -- so
      # legs evicted each other and entries rarely survived to be reused.
      # Restricting writes to master keeps the property that makes the cache
      # usable at all (only one branch ever writes, so no branch can delete
      # another's entry) while collapsing the generations that actually blow
      # the budget. Pull requests still restore, read-only, and get the full
      # benefit.
      - name: Save sccache
        if: "steps.filter.outputs.run == 'true' && github.event_name == 'push' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main') && !contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted')"
        uses: actions/cache/save@v4
        with:
          path: /home/runner/.cache/sccache
          key: sccache-gcc-debug-${{ github.sha }}

  # ── Linux: every rung's tests under AddressSanitizer + UBSan ──────────
  # Before this job, no rung test ran under any sanitizer: ladder-tests above
  # builds plain gcc-debug, and the linux-sanitizers matrix deliberately skips
  # the ladder (only its clang-coverage leg sets MORPH_BUILD_LADDER). So every
  # rung's models, presenters and QML adapters — the code the ladder exists to
  # exercise — were compiled and run with no memory or UB instrumentation
  # anywhere in CI.
  #
  # ASan and UBSan, not TSan. `apply_sanitizers(<target> asan)` compiles with
  # -fsanitize=address,undefined (cmake/compiler_options.cmake), so this one
  # preset delivers both and a separate ubsan leg for the ladder would re-run
  # a strict subset. TSan is deliberately absent: a rung's tests drive Qt on
  # every path, and against an uninstrumented system Qt that produces warnings
  # bottoming out in Qt-internal frames which cannot be classified as real
  # races or false positives from outside a TSan-instrumented Qt build —
  # measured at 165 warnings deep. The way through is to write the one test
  # that matters so it constructs no QtExecutor at all and run only it under
  # TSan, which is what kanban-tsan above does. Thread-
  # sanitising a rung means following that pattern per test, not adding a
  # blanket -DAF_SANITIZER=tsan leg here.
  #
  # -LE stress mirrors ladder-tests: the stress cases are long-running by
  # design and ASan's shadow-memory overhead compounds that.
  ladder-sanitizers:
    name: Application ladder / ASan+UBSan
    needs: probe-self-hosted
    runs-on: ${{ fromJSON(needs.probe-self-hosted.outputs.runs_on) }}
    env:
      # See linux-compilers' identical env block for why FASTCACHE_ADDR is
      # conditional, and why FASTCACHE_AUTO_INSTALL has to be a -D flag
      # (MORPH_FASTCACHE_AUTO_INSTALL_FLAG) rather than an env var of that
      # name -- CompileCache.cmake declares it as a plain option(), which
      # CMake never reads from the environment.
      FASTCACHE_ADDR: ${{ contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted') && 'host.docker.internal:6674' || '' }}
      MORPH_FASTCACHE_AUTO_INSTALL_FLAG: ${{ contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted') && '-DFASTCACHE_AUTO_INSTALL=ON' || '' }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # need history for the changed-paths diff below

      # Same filter as ladder-tests, and now literally the same generator
      # rather than a second hand-copy of the same list: the two jobs build the
      # identical tree and differ only in instrumentation, so a change that
      # warrants running one warrants running the other, and the two patterns
      # must not be able to diverge. This job is the only one in the repository
      # that sanitizer-instruments a rung, so a filter that drifts behind
      # examples/rungs.txt silently stops sanitising whatever it has not caught
      # up with.
      - name: Determine whether the ladder needs to run
        id: filter
        run: |
          # Not because `echo | grep` can lose a status today -- `echo` does
          # not fail -- but because this block decides whether a whole job
          # runs, and the next edit to it is the one that adds a pipeline
          # that can. Nothing enforces this rule across the file's other `run:`
          # blocks, so it is a convention rather than something CI holds you to.
          set -o pipefail
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            base="${{ github.event.pull_request.base.sha }}"
          else
            base="${{ github.event.before }}"
          fi
          if [ -z "$base" ] || ! git cat-file -e "$base" 2>/dev/null; then
            echo "run=true" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          changed=$(git diff --name-only "$base" HEAD)
          pattern="$(bash scripts/ladder_rungs.sh ci-path-regex)"
          echo "ladder path filter: $pattern"
          if echo "$changed" | grep -qE "$pattern"; then
            echo "run=true" >> "$GITHUB_OUTPUT"
          else
            echo "run=false" >> "$GITHUB_OUTPUT"
          fi

      - name: Cache apt packages
        if: steps.filter.outputs.run == 'true'
        uses: actions/cache@v4
        with:
          path: /var/cache/apt/archives
          key: apt-ladder-asan-${{ hashFiles('.github/workflows/ci.yml') }}
          restore-keys: apt-ladder-asan-

      - name: Install Clang ${{ env.CLANG_VERSION }}, ninja, catch2, ODBC
        if: steps.filter.outputs.run == 'true'
        run: |
          sudo apt-get update -q
          # unixodbc-dev + libsqliteodbc: the ladder fetches the Lightweight
          # ORM, whose CMake runs `pkg_check_modules(ODBC REQUIRED odbc)` and
          # whose fixtures open a real `DRIVER=SQLite3` connection at test
          # time. libyaml-cpp-dev/libzip-dev/libgl1-mesa-dev round out the
          # same set every other ladder-building Linux job installs.
          sudo apt-get install -y ninja-build catch2 libsqlite3-dev \
            unixodbc-dev libsqliteodbc libyaml-cpp-dev libzip-dev libgl1-mesa-dev
          # --fail, a file, and a non-empty check -- never `wget -qO- | sudo
          # bash`: see linux-compilers' identical install step for why the piped
          # form reports success having installed nothing.
          curl -sSL --fail -o /tmp/llvm.sh https://apt.llvm.org/llvm.sh
          test -s /tmp/llvm.sh
          sudo bash /tmp/llvm.sh ${{ env.CLANG_VERSION }}

      # Not the distro's Qt: examples/common/CMakeLists.txt requires 6.5+
      # unconditionally and Ubuntu 24.04 still ships 6.4.2 — the same gap
      # every other job that builds the ladder on Linux already documents.
      - name: Install Qt ${{ env.QT_VERSION }}
        if: steps.filter.outputs.run == 'true'
        uses: jurplel/install-qt-action@v4.3.1
        with:
          version: ${{ env.QT_VERSION }}
          modules: qtwebsockets
          cache: true

      # Keyed by preset alone (clang-asan), matching linux-sanitizers' cache:
      # this job's clang-asan+Qt+ladder build shares the same compiler and
      # much of the same core-library object set as that job's clang-asan leg.

      # Skipped on the self-hosted path: see linux-compilers' identical
      # Restore/Install sccache steps for why (installing sccache
      # unconditionally would permanently defeat fastcache-cc auto-install).
      - name: Restore sccache
        if: "steps.filter.outputs.run == 'true' && !contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted')"
        uses: actions/cache/restore@v4
        with:
          path: /home/runner/.cache/sccache
          key: sccache-clang-asan-${{ github.sha }}
          restore-keys: sccache-clang-asan-

      - name: Install sccache
        if: "steps.filter.outputs.run == 'true' && !contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted')"
        run: |
          # `--fail` and a file rather than a pipe into tar: see
          # linux-compilers' identical Install sccache step for why an
          # unchecked download reports itself as "not in gzip format".
          curl -sSL --fail -o /tmp/sccache.tar.gz \
            https://github.com/mozilla/sccache/releases/download/v0.9.1/sccache-v0.9.1-x86_64-unknown-linux-musl.tar.gz
          tar -xzf /tmp/sccache.tar.gz --strip-components=1 -C /usr/local/bin \
            sccache-v0.9.1-x86_64-unknown-linux-musl/sccache

      # No -DCMAKE_..._COMPILER_LAUNCHER=sccache: see linux-compilers'
      # Configure steps for why leaving it unset is what lets fastcache-cc
      # be selected.
      - name: Configure (clang-asan, ladder + Qt on)
        if: steps.filter.outputs.run == 'true'
        run: |
          cmake --preset clang-asan \
            -DMORPH_BUILD_QT=ON \
            -DMORPH_BUILD_LADDER=ON \
            -DMORPH_LADDER_RUNGS=all \
            -DCMAKE_C_COMPILER=clang-${{ env.CLANG_VERSION }} \
            -DCMAKE_CXX_COMPILER=clang++-${{ env.CLANG_VERSION }} \
            $MORPH_FASTCACHE_AUTO_INSTALL_FLAG

      # QT_QPA_PLATFORM=offscreen at build time as well as test time: Catch2's
      # catch_discover_tests() runs each Qt-linked test binary once during the
      # build to enumerate its cases — see ladder-tests' own Build step.
      - name: Build
        if: steps.filter.outputs.run == 'true'
        env:
          QT_QPA_PLATFORM: offscreen
        run: cmake --build --preset clang-asan

      # A sanitizer job whose binaries are not actually instrumented is worse
      # than no job: it runs the full suite, costs the full runtime and always
      # passes, so a missing apply_sanitizers() call in morph_add_rung.cmake
      # would read as "rungs are ASan-clean" rather than "rungs were never
      # checked". That is not hypothetical — before the AF_SANITIZER blocks
      # landed in cmake/morph_add_rung.cmake and examples/common/CMakeLists.txt,
      # -DAF_SANITIZER=asan instrumented morph_tests and nothing under
      # examples/.
      #
      # Not a hand-rolled `nm | grep __asan_` over
      # `examples/*/ladder_*_tests`, which is the same shape of blind
      # spot one level up: it asserts the instrumentation of the binaries
      # someone thought to name, and this job also builds tests/qt,
      # examples/qt_tls_client and examples/concepts, none of which that glob
      # reaches. The shared script walks what ctest will actually
      # run instead of a pattern, so a suite added tomorrow is covered by
      # having been added.
      #
      # QT_QPA_PLATFORM=offscreen, matching the Build step above and the Test
      # step below, for the reason the identical step elsewhere gives: this
      # sweep opens with `ctest
      # --show-only=json-v1`, and listing a DISCOVERY_MODE PRE_TEST suite *runs*
      # its binary -- so a Qt-linked PRE_TEST suite in this configure would
      # abort headless and take the entire listing down, every other suite
      # included. Today every Qt-linked suite this job builds is POST_BUILD
      # (cmake/morph_add_rung.cmake, examples/common/CMakeLists.txt,
      # tests/qt/CMakeLists.txt), so discovery already happened under the Build
      # step's copy of this variable. That is an accident of one keyword, not a
      # property of this step: flip any of those suites to PRE_TEST and the
      # variable becomes load-bearing here too.
      - name: Every ctest binary is instrumented
        if: steps.filter.outputs.run == 'true'
        env:
          QT_QPA_PLATFORM: offscreen
        run: bash scripts/check_sanitizer_instrumentation.sh build/clang-asan asan

      # detect_leaks=0: LeakSanitizer reports allocations the Qt platform
      # plugins and QML engine intentionally keep for process lifetime, which
      # are not leaks this repo can fix or meaningfully suppress per-frame.
      # The memory-error and UB checks — what this job is actually for — stay
      # fully on. Drop this once a Qt-aware suppression file proves workable.
      - name: Test (offscreen Qt platform, ladder tests only, stress excluded)
        if: steps.filter.outputs.run == 'true'
        env:
          QT_QPA_PLATFORM: offscreen
          ASAN_OPTIONS: detect_leaks=0
          UBSAN_OPTIONS: print_stacktrace=1:halt_on_error=1
        run: ctest --preset clang-asan -L ladder -LE stress --output-on-failure

      # The Qt transport suites, which no other sanitizer leg runs.
      # Instrumenting a suite nothing runs swaps one vacuous control for
      # another, so both halves belong here: this is the only leg that
      # builds Qt under a sanitizer, so if these run anywhere it is here.
      # linux-sanitizers deliberately keeps Qt out of its matrix (see its
      # Configure comment), and kanban-tsan runs exactly one named stress test.
      #
      # Measured before adding this step, on clang 22 with these same options:
      # all 67 cases across tests/qt, tests/net_qt_interop and
      # qt_tls_example_runs pass clean under -fsanitize=address,undefined. This
      # job's configure leaves MORPH_BUILD_NET off, so the filter below selects
      # the 57 that exist here -- tests/qt plus the TLS example.
      #
      # `--no-tests=error` because `-R` over test names is exactly the filter
      # that goes stale silently: a renamed TEST_CASE would otherwise leave
      # ctest reporting success having run nothing.
      # `!cancelled()`, for the reason the other test steps give, which bites hardest
      # here: this is the only leg in CI that runs the Qt transport suites
      # under any sanitizer, so if the ladder step above goes red and this one
      # is skipped, that surface is measured nowhere at all. Not `always()` --
      # see ladder-tests' own note. The job still fails on a red step.
      - name: Test (the Qt transport suites, which no sanitizer leg ran)
        if: "!cancelled() && steps.filter.outputs.run == 'true'"
        env:
          QT_QPA_PLATFORM: offscreen
          # detect_leaks=0 for the reason the ladder step above gives: Qt's
          # platform plugins and QML engine keep allocations for process
          # lifetime. The memory-error and UB checks stay fully on.
          ASAN_OPTIONS: detect_leaks=0
          UBSAN_OPTIONS: print_stacktrace=1:halt_on_error=1
        run: |
          ctest --preset clang-asan --no-tests=error --output-on-failure \
            -R 'morph::qt::|qt_tls_example_runs'

      # Cumulative hit/miss for this leg. Without it the cache is
      # unfalsifiable: a thrashing cache and a working one look identical
      # from the outside, and only the build-step duration hints at which
      # one you have. `|| true` so a stats failure never fails the job.
      #
      # Guarded the same way as the Install/Restore sccache steps above:
      # sccache is never installed on the self-hosted path.
      - name: sccache stats
        if: "always() && steps.filter.outputs.run == 'true' && !contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted')"
        run: sccache --show-stats || true

      # Cache statistics for this leg. The `sccache stats` step is skipped
      # whenever the probe put this job on the self-hosted fleet, because
      # sccache is not the launcher there -- fastcache-cc is. Nothing replaced
      # it, so those legs ran with no cache reporting at all: exactly the
      # "unfalsifiable" state the sccache step's own comment warns about, where
      # a thrashing cache and a working one look identical from the outside and
      # only the build duration hints at which one you have.
      #
      # The line that matters is
      #     unavailable : N  (x% of all compiles -- CACHE NOT REACHED)
      # which is how a daemon that is configured but never answering shows up.
      # Configure still prints "Enabling fastcache-cc at ..." in that case and
      # the build simply takes as long as a cold one, so no other signal in the
      # job would reveal it.
      #
      # Mirror of the sccache step's condition, so exactly one of the two runs.
      # `|| true` for the same reason it has one: a stats failure must never
      # fail the job.
      - name: fastcache-cc stats
        if: "always() && steps.filter.outputs.run == 'true' && contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted')"
        run: |
          FC="$(command -v fastcache-cc || true)"
          if [ -z "$FC" ]; then
            FC="$(ls -t "$HOME"/.cache/fastcache-cc/*/*/fastcache-cc 2>/dev/null | head -1 || true)"
          fi
          if [ -z "$FC" ]; then
            echo "::warning::fastcache-cc not found on a self-hosted runner -- the build ran uncached."
            exit 0
          fi
          echo "launcher: $FC   FASTCACHE_ADDR=${FASTCACHE_ADDR:-<unset>}"
          # This job's own numbers, not the runner's lifetime totals. The
          # bare form is kept underneath because the whole-runner view is
          # what shows eviction pressure across jobs, which a single job's
          # slice cannot.
          "$FC" --show-stats --prefetch-group "$FASTCACHE_PREFETCH_GROUP" || true
          echo "--- whole runner, all jobs (context for the above) ---"
          "$FC" --show-stats || true

      # Save only on a push to master. Every run used to write a new
      # per-commit entry, and with 16 cache-writing legs at 1 GB each one
      # generation already exceeds GitHub's 10 GB per-repo budget -- so
      # legs evicted each other and entries rarely survived to be reused.
      # Restricting writes to master keeps the property that makes the cache
      # usable at all (only one branch ever writes, so no branch can delete
      # another's entry) while collapsing the generations that actually blow
      # the budget. Pull requests still restore, read-only, and get the full
      # benefit.
      - name: Save sccache
        if: "steps.filter.outputs.run == 'true' && github.event_name == 'push' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main') && !contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted')"
        uses: actions/cache/save@v4
        with:
          path: /home/runner/.cache/sccache
          key: sccache-clang-asan-${{ github.sha }}

  # ── Linux: every optional feature enabled at once ─────────────────────
  # Every MORPH_BUILD_* option below is off by default, and until this job
  # existed no CI configuration turned any of them on — so several thousand
  # lines (morph::net, the Qt/QML forms renderer, the SQLite queue, the fuzz
  # harnesses, the vetted-HMAC adapters, the soak/bench targets) were never
  # compiled here, let alone tested. That is how a build that cannot configure
  # (MORPH_REQUIRE_VETTED_HMAC) and a replay test matching the wrong file
  # extension both reached master green. Enabling them together also proves
  # they compose, which building each alone would not.
  linux-all-features:
    name: Linux / all optional features (${{ matrix.compiler }})
    needs: probe-self-hosted
    runs-on: ${{ fromJSON(needs.probe-self-hosted.outputs.runs_on) }}
    env:
      # See linux-compilers' identical env block for why FASTCACHE_ADDR is
      # conditional, and why FASTCACHE_AUTO_INSTALL has to be a -D flag
      # (MORPH_FASTCACHE_AUTO_INSTALL_FLAG) rather than an env var of that
      # name -- CompileCache.cmake declares it as a plain option(), which
      # CMake never reads from the environment.
      FASTCACHE_ADDR: ${{ contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted') && 'host.docker.internal:6674' || '' }}
      MORPH_FASTCACHE_AUTO_INSTALL_FLAG: ${{ contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted') && '-DFASTCACHE_AUTO_INSTALL=ON' || '' }}
    strategy:
      fail-fast: false
      matrix:
        include:
          # Clang additionally builds the libFuzzer harnesses, which require it.
          - compiler: clang
            preset: clang-debug
            fuzzers: 'ON'
          - compiler: gcc
            preset: gcc-debug
            fuzzers: 'OFF'
    steps:
      - uses: actions/checkout@v4

      - name: Cache apt packages
        uses: actions/cache@v4
        with:
          path: /var/cache/apt/archives
          key: apt-all-features-${{ matrix.compiler }}-${{ hashFiles('.github/workflows/ci.yml') }}
          restore-keys: apt-all-features-${{ matrix.compiler }}-

      - name: Install toolchain and the non-Qt dependencies
        run: |
          sudo apt-get update -q
          sudo apt-get install -y software-properties-common
          sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
          sudo apt-get update -q
          # unixodbc-dev + libsqliteodbc: the application ladder (enabled in
          # the configure step below) fetches the Lightweight ORM, whose CMake
          # runs `pkg_check_modules(ODBC REQUIRED odbc)`, and whose ladder
          # fixtures open a real `DRIVER=SQLite3` connection at test time.
          # Named explicitly rather than relied on from the runner image.
          # libyaml-cpp-dev + libzip-dev: Lightweight's own CMakeLists.txt
          # (examples/bank/CMakeLists.txt's comment on the same fetch) does
          # `find_package(yaml-cpp)`/`find_package(libzip)` as system CONFIG
          # packages, not through CPM — without these, Lightweight's configure
          # fails with "could not find a package configuration file" the
          # moment MORPH_BUILD_LADDER=ON pulls it in here.
          sudo apt-get install -y ninja-build catch2 \
            libsqlite3-dev libsodium-dev libssl-dev \
            unixodbc-dev libsqliteodbc \
            libyaml-cpp-dev libzip-dev \
            libgl1-mesa-dev libxkbcommon-x11-0 libxcb-cursor0 libxcb-icccm4 \
            libxcb-keysyms1 libxcb-shape0 libxcb-xinerama0
          if [ "${{ matrix.compiler }}" = "gcc" ]; then
            sudo apt-get install -y gcc-15 g++-15
            sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-15 15
            sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-15 15
          else
            # --fail, a file, and a non-empty check -- never `wget -qO- | sudo
            # bash`: see linux-compilers' identical install step for why the piped
            # form reports success having installed nothing.
            curl -sSL --fail -o /tmp/llvm.sh https://apt.llvm.org/llvm.sh
            test -s /tmp/llvm.sh
            sudo bash /tmp/llvm.sh ${{ env.CLANG_VERSION }}
          fi

      # Not the distro's Qt: MORPH_BUILD_FORMS_QML needs 6.5+ (see the version
      # floor in CMakeLists.txt) and Ubuntu 24.04 still ships 6.4.2, whose
      # QQmlApplicationEngine has no loadFromModule.
      - name: Install Qt ${{ env.QT_VERSION }}
        uses: jurplel/install-qt-action@v4.3.1
        with:
          version: ${{ env.QT_VERSION }}
          modules: qtwebsockets
          cache: true

      # Keyed by preset alone, matching linux-compilers' cache: this matrix's
      # gcc-debug/clang-debug legs (with every optional feature layered on
      # top) share their core-library objects with linux-compilers' plain
      # gcc-debug/clang-debug legs and every other job building the same
      # preset (linux-qt, ladder-tests, valgrind for gcc-debug).

      # Skipped on the self-hosted path: see linux-compilers' identical
      # Restore/Install sccache steps for why (installing sccache
      # unconditionally would permanently defeat fastcache-cc auto-install).
      - name: Restore sccache
        if: "!contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted')"
        uses: actions/cache/restore@v4
        with:
          path: /home/runner/.cache/sccache
          key: sccache-${{ matrix.preset }}-${{ github.sha }}
          restore-keys: sccache-${{ matrix.preset }}-

      - name: Install sccache
        if: "!contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted')"
        run: |
          # `--fail` and a file rather than a pipe into tar: see
          # linux-compilers' identical Install sccache step for why an
          # unchecked download reports itself as "not in gzip format".
          curl -sSL --fail -o /tmp/sccache.tar.gz \
            https://github.com/mozilla/sccache/releases/download/v0.9.1/sccache-v0.9.1-x86_64-unknown-linux-musl.tar.gz
          tar -xzf /tmp/sccache.tar.gz --strip-components=1 -C /usr/local/bin \
            sccache-v0.9.1-x86_64-unknown-linux-musl/sccache

      # MORPH_REQUIRE_VETTED_HMAC is deliberately combined with
      # MORPH_BUILD_TESTS=ON (the preset default). docs/spec/security.md
      # documents that pairing as supported; this is what keeps it that way.
      - name: Configure (every optional feature ON)
        run: |
          EXTRA=""
          if [ "${{ matrix.compiler }}" = "clang" ]; then
            EXTRA="-DCMAKE_C_COMPILER=clang-${{ env.CLANG_VERSION }} -DCMAKE_CXX_COMPILER=clang++-${{ env.CLANG_VERSION }}"
          fi
          # shellcheck disable=SC2086
          # MORPH_BUILD_LADDER belongs in this job by its own charter ("every
          # MORPH_BUILD_* option … enabling them together also proves they
          # compose") and closes a real hole: until it was added here, *no* CI
          # leg configured MORPH_BUILD_LADDER=ON together with
          # MORPH_BUILD_FORMS_QML=ON. The ladder-tests job below cannot — its
          # distro Qt is 6.4.2, under the 6.5 floor MORPH_BUILD_FORMS_QML
          # requires — so each rung's QML module, desktop client and offscreen
          # engine-load smoke test were built by nothing at all. This job has
          # Qt ${{ env.QT_VERSION }} from aqtinstall, so here they are built,
          # and the smoke test runs, on every push.
          #
          # MORPH_BUILD_BANK_GUI (with MORPH_BUILD_BANK_EXAMPLE, which it needs
          # -- examples/bank/CMakeLists.txt only descends into gui/ from the
          # bank example's own subdirectory) was, until this line, the single
          # MORPH_BUILD_* option no job in .github/workflows/ enabled at all:
          # the `linux-everything` preset that sets it is named by no workflow.
          # What that costs is a target that stops compiling on master with
          # every gate green. This is the one leg that can host it:
          # it already installs Qt ${{ env.QT_VERSION }} from aqtinstall (the
          # GUI needs Qml/Quick/QuickControls2 at 6.5+, which the distro Qt the
          # other bank jobs use cannot give) and already installs the
          # ODBC/SQLite/yaml-cpp/libzip set the bank example's Lightweight
          # fetch requires. Nothing now checks that the next option is added
          # here too -- the option-coverage job that did was removed with the
          # meta-gates.
          # No -DCMAKE_..._COMPILER_LAUNCHER=sccache: see linux-compilers'
          # Configure steps for why leaving it unset is what lets
          # fastcache-cc be selected.
          cmake --preset ${{ matrix.preset }} \
            -DMORPH_BUILD_NET=ON \
            -DMORPH_BUILD_QT=ON \
            -DMORPH_BUILD_FORMS_QML=ON \
            -DMORPH_BUILD_LADDER=ON \
            -DMORPH_LADDER_RUNGS=all \
            -DMORPH_BUILD_OFFLINE_SQLITE=ON \
            -DMORPH_BUILD_LOAD_TESTS=ON \
            -DMORPH_BUILD_HMAC_EXAMPLES=ON \
            -DMORPH_BUILD_FUZZERS=${{ matrix.fuzzers }} \
            -DMORPH_BUILD_BANK_EXAMPLE=ON \
            -DMORPH_BUILD_BANK_GUI=ON \
            -DMORPH_REQUIRE_VETTED_HMAC=ON \
            $EXTRA \
            $MORPH_FASTCACHE_AUTO_INSTALL_FLAG

      # QT_QPA_PLATFORM=offscreen here too, not just on Test below: Catch2's
      # catch_discover_tests() runs each Qt-linked test binary once at BUILD
      # time to enumerate its cases (CatchAddTests.cmake), not only when
      # ctest later executes them — a ladder_<rung>_tests binary aborts at
      # that discovery step on this headless runner (no X server, xcb
      # platform plugin fails to load) without it, before any real test ever
      # runs. Only bites once MORPH_BUILD_LADDER=ON actually reaches a rung's
      # own Qt-linked test binary, which is why this job's build only started
      # failing here after the yaml-cpp/libzip configure gap (fixed earlier
      # this branch) stopped masking it.
      - name: Build
        env:
          QT_QPA_PLATFORM: offscreen
        run: cmake --build --preset ${{ matrix.preset }}

      # ── moc output that climbs out of the build tree ─────────────────
      # Same gate as linux-qt, and for the same reason -- see its comment.
      # This is the widest build it reaches: the clang leg is the only one that
      # compiles moc output under -Weverything, where -Wshadow-header is what
      # actually fires, and this job is the only one that builds
      # morph_forms_module's AUTOMOC output at all.
      - name: Check no generated moc include ascends
        run: bash scripts/check_automoc_includes.sh build/${{ matrix.preset }}

      # Includes the fuzz *replay* tests on the clang leg: each committed seed
      # and crash reproducer is replayed once and must not crash. This is a
      # deterministic regression check, not a fuzzing campaign.
      #
      # ── --parallel: the one leg in this repository that runs ctest in
      #    parallel, deliberately ─────────────────────────────────────────────
      #
      # Every other ctest invocation in .github/workflows/ is serial, which
      # makes a whole class of defect invisible to CI by construction: two
      # ctest cases sharing an on-disk database, a port, or a temp path cannot
      # collide when only one runs at a time. Measured instance: bank's suites
      # at 0/21 under `ctest -j 12` on a workstation and 21/21 serially, with
      # CI green throughout, on every leg, for as long as the defect existed.
      #
      # This leg and not another: it is the only one whose ctest covers the
      # bank suites *and* every ladder rung *and* Qt *and*
      # the core suites, so it is the only place where one flag exposes the
      # whole class rather than one corner of it. It also costs no new leg --
      # a second job would add its own configure and build to every future PR,
      # for the same coverage this already has.
      #
      # Measured, with the caveat stated rather than smoothed over. On a
      # 12-core workstation, clang-debug with MORPH_BUILD_NET, MORPH_BUILD_QT
      # and MORPH_BUILD_OFFLINE_SQLITE on -- 1898 tests, which is this tree's
      # core/forms/net/qt/offline set but *not* the ladder or bank:
      #
      #     ctest                   1898/1898 passed, 275.06 s
      #     ctest --parallel 12     1898/1898 passed,  98.25 s
      #     ctest --parallel 12     1898/1898 passed, 127.53 s
      #     ctest --parallel 12     1898/1898 passed,  78.80 s
      #     ctest --parallel 4      1898/1898 passed, 109.38 s   (hosted vCPU count)
      #
      # So for the part that could be measured locally this is a saving, not a
      # cost: the test step gets faster, and the leg's wall time with it. Bank,
      # measured separately once its suites took per-case databases, is 21/21
      # in 1.1 s parallel against 5.7 s serial.
      #
      # NOT measured, and this is the risk: the ladder rungs in parallel with
      # each other. They declare RESOURCE_LOCK (cmake/morph_add_rung.cmake),
      # which is what ctest --parallel consults to serialise the cases that
      # need it -- a mechanism that exists precisely for this and that no other
      # leg exercises. A `SQLite database is locked` in the ledger corpus is
      # the shape of first bill to expect here.
      #
      # If this leg goes red or flaky on contention rather than on a real
      # regression, the failing case is the finding -- file it, fix the
      # isolation, and keep the flag. Dropping `--parallel` again puts the
      # whole class back out of CI's sight, which is what this flag exists to
      # prevent. $(nproc) rather than a literal: hosted runners give 4, the
      # self-hosted fleet gives more, and the point is contention, not a number.
      - name: Test (offscreen Qt platform, ctest in parallel)
        env:
          QT_QPA_PLATFORM: offscreen
        run: ctest --preset ${{ matrix.preset }} --parallel "$(nproc)" --output-on-failure

      # A guard that never fires is indistinguishable from one that works, so
      # assert the fuzz replay actually ran the committed crash reproducers
      # rather than silently matching nothing (the `.txt`-vs-`.bin` glob bug).
      # `!cancelled()`: this checks something the ctest step
      # above cannot report on -- whether the replay matched the committed
      # reproducers at all, the `.txt`-vs-`.bin` glob bug -- so skipping it
      # when some unrelated test fails hides a guard going vacuous behind an
      # unrelated red. Not `always()`; see ladder-tests' note. Still red on
      # failure.
      - name: Verify the fuzz replay covered the committed reproducers
        if: "!cancelled() && matrix.fuzzers == 'ON'"
        run: |
          ctest --preset ${{ matrix.preset }} -R fuzz -V > fuzz-replay.log 2>&1
          status=0
          for finding in tests/fuzz/findings/*/*; do
            if ! grep -qF "$(basename "$finding")" fuzz-replay.log; then
              echo "::error::fuzz replay never referenced committed reproducer $finding"
              status=1
            fi
          done
          exit "$status"

      # Cumulative hit/miss for this leg. Without it the cache is
      # unfalsifiable: a thrashing cache and a working one look identical
      # from the outside, and only the build-step duration hints at which
      # one you have. `|| true` so a stats failure never fails the job.
      #
      # Guarded the same way as the Install/Restore sccache steps above:
      # sccache is never installed on the self-hosted path.
      - name: sccache stats
        if: "always() && !contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted')"
        run: sccache --show-stats || true

      # Cache statistics for this leg. The `sccache stats` step is skipped
      # whenever the probe put this job on the self-hosted fleet, because
      # sccache is not the launcher there -- fastcache-cc is. Nothing replaced
      # it, so those legs ran with no cache reporting at all: exactly the
      # "unfalsifiable" state the sccache step's own comment warns about, where
      # a thrashing cache and a working one look identical from the outside and
      # only the build duration hints at which one you have.
      #
      # The line that matters is
      #     unavailable : N  (x% of all compiles -- CACHE NOT REACHED)
      # which is how a daemon that is configured but never answering shows up.
      # Configure still prints "Enabling fastcache-cc at ..." in that case and
      # the build simply takes as long as a cold one, so no other signal in the
      # job would reveal it.
      #
      # Mirror of the sccache step's condition, so exactly one of the two runs.
      # `|| true` for the same reason it has one: a stats failure must never
      # fail the job.
      - name: fastcache-cc stats
        if: "always() && contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted')"
        run: |
          FC="$(command -v fastcache-cc || true)"
          if [ -z "$FC" ]; then
            FC="$(ls -t "$HOME"/.cache/fastcache-cc/*/*/fastcache-cc 2>/dev/null | head -1 || true)"
          fi
          if [ -z "$FC" ]; then
            echo "::warning::fastcache-cc not found on a self-hosted runner -- the build ran uncached."
            exit 0
          fi
          echo "launcher: $FC   FASTCACHE_ADDR=${FASTCACHE_ADDR:-<unset>}"
          # This job's own numbers, not the runner's lifetime totals. The
          # bare form is kept underneath because the whole-runner view is
          # what shows eviction pressure across jobs, which a single job's
          # slice cannot.
          "$FC" --show-stats --prefetch-group "$FASTCACHE_PREFETCH_GROUP" || true
          echo "--- whole runner, all jobs (context for the above) ---"
          "$FC" --show-stats || true

      # Save only on a push to master. Every run used to write a new
      # per-commit entry, and with 16 cache-writing legs at 1 GB each one
      # generation already exceeds GitHub's 10 GB per-repo budget -- so
      # legs evicted each other and entries rarely survived to be reused.
      # Restricting writes to master keeps the property that makes the cache
      # usable at all (only one branch ever writes, so no branch can delete
      # another's entry) while collapsing the generations that actually blow
      # the budget. Pull requests still restore, read-only, and get the full
      # benefit.
      - name: Save sccache
        if: github.event_name == 'push' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main') && !contains(needs.probe-self-hosted.outputs.runs_on, 'self-hosted')
        uses: actions/cache/save@v4
        with:
          path: /home/runner/.cache/sccache
          key: sccache-${{ matrix.preset }}-${{ github.sha }}

  # ── Valgrind (memcheck) ───────────────────────────────────────────────
  valgrind:
    name: Valgrind memcheck
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4

      - name: Cache apt packages
        uses: actions/cache@v4
        with:
          path: /var/cache/apt/archives
          key: apt-valgrind-${{ hashFiles('.github/workflows/ci.yml') }}
          restore-keys: apt-valgrind-

      - name: Install GCC 15, ninja, catch2, valgrind
        run: |
          sudo apt-get update -q
          sudo apt-get install -y software-properties-common
          sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
          sudo apt-get update -q
          sudo apt-get install -y gcc-15 g++-15 ninja-build catch2 valgrind
          sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-15 15
          sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-15 15

      # Keyed by preset alone (gcc-debug), matching linux-compilers' cache:
      # this job's gcc-debug+net+offline_sqlite build shares its
      # core-library objects with every other job building plain gcc-debug.
      - name: Restore sccache
        uses: actions/cache/restore@v4
        with:
          path: /home/runner/.cache/sccache
          key: sccache-gcc-debug-${{ github.sha }}
          restore-keys: sccache-gcc-debug-

      - name: Install sccache
        run: |
          # `--fail` and a file rather than a pipe into tar: see
          # linux-compilers' identical Install sccache step for why an
          # unchecked download reports itself as "not in gzip format".
          curl -sSL --fail -o /tmp/sccache.tar.gz \
            https://github.com/mozilla/sccache/releases/download/v0.9.1/sccache-v0.9.1-x86_64-unknown-linux-musl.tar.gz
          tar -xzf /tmp/sccache.tar.gz --strip-components=1 -C /usr/local/bin \
            sccache-v0.9.1-x86_64-unknown-linux-musl/sccache

      # morph::net and the SQLite queue are where the raw pointers, manual
      # buffers and C API calls live — precisely what memcheck is for — so they
      # are built here rather than left to the default (Qt/QML stays out: it
      # drags in a GUI stack whose own allocations dominate the report).
      - name: Configure
        run: |
          cmake --preset gcc-debug \
            -DMORPH_BUILD_NET=ON \
            -DMORPH_BUILD_OFFLINE_SQLITE=ON \
            -DCMAKE_C_COMPILER_LAUNCHER=sccache \
            -DCMAKE_CXX_COMPILER_LAUNCHER=sccache

      - name: Build
        run: cmake --build --preset gcc-debug

      - name: Run tests under Valgrind
        run: |
          status=0
          for suite in tests/morph_tests tests/net/morph_net_tests tests/offline_sqlite/morph_offline_sqlite_tests; do
            binary="build/gcc-debug/$suite"
            if [ ! -x "$binary" ]; then
              echo "::error::expected Valgrind suite $binary was not built"
              exit 1
            fi
            echo "── memcheck: $suite ──"
            # [oom-injector]/[issue108]: morph::testkit::OomInjector
            # overrides the process-wide operator new/delete
            # (tests/oom_injector.cpp) to force std::bad_alloc on demand --
            # Valgrind's own memcheck instrumentation intercepts allocations
            # at a layer this override does not reach, so the injector
            # silently never fires under Valgrind (confirmed: even its own
            # self-tests fail here). Skipped for this leg only; every other
            # CI leg (plain clang/gcc, Windows) runs these tests normally.
            EXTRA_ARGS=()
            if [ "$suite" = "tests/morph_tests" ]; then
              EXTRA_ARGS=("~[oom-injector]" "~[issue108]")
            fi
            valgrind \
              --tool=memcheck \
              --leak-check=full \
              --show-leak-kinds=definite,indirect \
              --errors-for-leak-kinds=definite,indirect \
              --error-exitcode=1 \
              --suppressions=cmake/valgrind.supp \
              "$binary" "${EXTRA_ARGS[@]}" || status=1
          done
          exit "$status"

      # Cumulative hit/miss for this leg. Without it the cache is
      # unfalsifiable: a thrashing cache and a working one look identical
      # from the outside, and only the build-step duration hints at which
      # one you have. `|| true` so a stats failure never fails the job.
      - name: sccache stats
        if: always()
        run: sccache --show-stats || true

      # Save only on a push to master. Writing a new per-commit entry from
      # every run does not work here: with 16 cache-writing legs at 1 GB each,
      # one generation exceeds GitHub's 10 GB per-repo budget, so legs evict
      # each other and entries rarely survive to be reused. Restricting writes
      # to master keeps the property that makes the cache usable at all (only
      # one branch ever writes, so no branch can delete another's entry) while
      # collapsing the generations that blow the budget. Pull requests still
      # restore, read-only, and get the full benefit.
      - name: Save sccache
        if: github.event_name == 'push' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main')
        uses: actions/cache/save@v4
        with:
          path: /home/runner/.cache/sccache
          key: sccache-gcc-debug-${{ github.sha }}

  # ── clang-format (whole tree) ─────────────────────────────────────────
  #
  # .clang-format is in the tree, and an unenforced one drifts fast: measured
  # once at 471 of 677 tracked .hpp/.cpp files not matching it. An unenforced
  # config is worse than none, because every editor with format-on-save obeys it
  # faithfully -- so touching one file rewrites parts the author never meant to
  # change, and the reviewer's job becomes separating intent from churn.
  #
  # Whole tree, not changed lines. A changed-lines check passes as long as
  # nobody touches the non-conforming lines, so it would have reported success
  # over a tree that was 70% non-conforming -- a control that measures almost
  # nothing. The tree was reformatted wholesale first (see
  # .git-blame-ignore-revs), which is what makes the wider check possible.
  #
  # Pinned to the same CLANG_VERSION as clang-tidy-diff: clang-format output is
  # not stable across major versions, so an unpinned check would disagree with
  # itself between runners.
  clang-format:
    name: clang-format
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4

      - name: Install clang-format ${{ env.CLANG_VERSION }}
        run: |
          # --fail, a file, and a non-empty check -- never `wget -qO- | sudo
          # bash`: see linux-compilers' identical install step for why the piped
          # form reports success having installed nothing.
          curl -sSL --fail -o /tmp/llvm.sh https://apt.llvm.org/llvm.sh
          test -s /tmp/llvm.sh
          sudo bash /tmp/llvm.sh ${{ env.CLANG_VERSION }}
          sudo apt-get install -y clang-format-${{ env.CLANG_VERSION }}

      - name: Check every tracked C++ file against .clang-format
        run: |
          # Without pipefail the count below is `wc`'s status, not `tr`'s: a
          # missing or unreadable cpp-files.z yields COUNT=0 rather than an
          # error. The `-lt 100` guard catches that particular
          # case; pipefail is what keeps the *next* pipeline here honest.
          set -o pipefail
          git ls-files -z '*.hpp' '*.cpp' > cpp-files.z
          COUNT=$(tr -cd '\0' < cpp-files.z | wc -c)
          # An empty or truncated file list would make this job pass while
          # checking nothing, which is the exact failure it exists to prevent.
          # Refuse rather than report a vacuous success.
          if [ "$COUNT" -lt 100 ]; then
            echo "::error::only $COUNT C++ files matched -- the check would be vacuous"
            exit 1
          fi
          echo "Checking $COUNT files"
          xargs -0 clang-format-${{ env.CLANG_VERSION }} --dry-run -Werror \
            < cpp-files.z 2> clang-format-report.txt || true
          if [ -s clang-format-report.txt ]; then
            cat clang-format-report.txt
            echo "::error::tree does not match .clang-format -- run: git ls-files -z '*.hpp' '*.cpp' | xargs -0 clang-format -i"
            exit 1
          fi

      - name: Upload clang-format report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: clang-format-report
          path: clang-format-report.txt
          if-no-files-found: ignore

  # ── clang-tidy-diff (changed lines only) ──────────────────────────────

  clang-tidy:
    name: clang-tidy-diff
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # need full history for git diff against base

      - name: Cache apt packages
        uses: actions/cache@v4
        with:
          path: /var/cache/apt/archives
          key: apt-clang-tidy-${{ hashFiles('.github/workflows/ci.yml') }}
          restore-keys: apt-clang-tidy-

      - name: Install Clang ${{ env.CLANG_VERSION }}, clang-tidy, and the non-Qt deps
        run: |
          sudo apt-get update -q
          # unixodbc-dev + libsqliteodbc, libyaml-cpp-dev + libzip-dev: the
          # Configure step below turns MORPH_BUILD_LADDER on, which pulls in the
          # Lightweight ORM -- whose CMake does `pkg_check_modules(ODBC REQUIRED
          # odbc)` and `find_package(yaml-cpp)`/`find_package(libzip)` as system
          # CONFIG packages, not through CPM. Without these four the configure
          # fails outright. Same set, for the same reason, as every other Linux
          # job that configures the ladder (see the "Install ODBC + SQLite
          # driver" step above). This job never builds or runs anything, so the
          # SQLite ODBC *driver* is not strictly exercised here; it is installed
          # alongside unixodbc-dev to keep the four-package set identical to the
          # jobs that do, rather than subtly divergent.
          sudo apt-get install -y ninja-build catch2 \
            libsqlite3-dev libsodium-dev libssl-dev \
            unixodbc-dev libsqliteodbc libyaml-cpp-dev libzip-dev \
            libgl1-mesa-dev libxkbcommon-x11-0 libxcb-cursor0 libxcb-icccm4 \
            libxcb-keysyms1 libxcb-shape0 libxcb-xinerama0
          # --fail, a file, and a non-empty check -- never `wget -qO- | sudo
          # bash`: see linux-compilers' identical install step for why the piped
          # form reports success having installed nothing.
          curl -sSL --fail -o /tmp/llvm.sh https://apt.llvm.org/llvm.sh
          test -s /tmp/llvm.sh
          sudo bash /tmp/llvm.sh ${{ env.CLANG_VERSION }}
          sudo apt-get install -y clang-tidy-${{ env.CLANG_VERSION }}

      # Here rather than in a lint job of its own because this is the only job
      # that already has a pinned clang-tidy on it, and both steps below need
      # one. Neither reads the compile database, so they run before the
      # Configure step and fail in seconds rather than after it.
      #
      # See scripts/test_check_tidy_suppression_scope.sh's own comment: a lint
      # gate nobody tests reports green whether or not it still detects
      # anything, and this one's behavioural half asserts a *negative* -- that
      # a check does not fire in a header -- which a broken probe satisfies by
      # accident.
      - name: Self-test the clang-tidy suppression-scope checker
        run: bash scripts/test_check_tidy_suppression_scope.sh clang-tidy-${{ env.CLANG_VERSION }}

      # The Catch2 on this runner's include path decides whether a
      # readability-function-cognitive-complexity finding on a TEST_CASE body
      # reaches this job, and `apt-get install -y catch2` above pins nothing.
      # This step reads the version out of the headers the step above just
      # installed and fails if it is not the one CATCH2_VERSION records, so a
      # move in the runner image is a red job rather than a quiet change of
      # what this gate measures. Its self-test runs first, for the
      # same reason the suppression-scope checker's does.
      - name: Self-test the catch2-pin checker
        run: bash scripts/test_check_catch2_pin.sh

      - name: Assert the Catch2 this job analyses against
        run: bash scripts/check_catch2_pin.sh . --strict

      # Catches a bug class this file's own layout invites: tests/.clang-tidy's
      # thirteen suppressions are argued as Catch2 and raw-syscall idiom, which
      # is true of test sources and says nothing about include/morph/** -- yet
      # clang-tidy resolves configuration from the translation unit's path, so
      # they are off for every header a tests/ TU reaches as well. Measured:
      # 333 findings inside include/morph/**, across 25 headers, reported from
      # those 134 TUs once that file is removed. The reach
      # cannot be narrowed, so it is written down in tests/.clang-tidy -- and
      # this step is what keeps the record from going stale.
      - name: Check tests/.clang-tidy records the reach it actually has
        run: bash scripts/check_tidy_suppression_scope.sh clang-tidy-${{ env.CLANG_VERSION }} .

      # See the linux-all-features job: the QML renderer needs Qt 6.5+.
      - name: Install Qt ${{ env.QT_VERSION }}
        uses: jurplel/install-qt-action@v4.3.1
        with:
          version: ${{ env.QT_VERSION }}
          modules: qtwebsockets
          cache: true

      # Every optional feature is ON here purely so its sources land in
      # compile_commands.json. clang-tidy only ever analyses *changed lines*, so
      # this costs a wider configure, not a wider lint. Configured narrowly
      # before, the whole opt-in surface — morph::net, the Qt transport, the QML
      # forms renderer, the SQLite queue, the fuzz harnesses — was invisible to
      # the one gate in this workflow that reads code rather than running it.
      #
      # MORPH_BUILD_LADDER + MORPH_BUILD_BANK_EXAMPLE are the two that make that
      # claim true rather than aspirational. Both default OFF and
      # gate `add_subdirectory(examples)` / `add_subdirectory(examples/bank)`,
      # so without them the database holds 261 entries of which
      # 16 are under examples/ — four directories, none of them a ladder rung.
      # examples/ is 69% of the repository's C/C++ files (524 of 793 were
      # outside the database, against 60 under include/morph), and clang-tidy
      # does not skip a file it has no compile command for: clang tooling
      # interpolates one from a neighbouring entry, morph's own -I survive, the
      # rung's do not, and the translation unit dies at include #2 with
      # `'ledger/models/ledger_model.hpp' file not found`. That is a
      # clang-diagnostic-error, not a lint finding, and it means no check ever
      # reached a line of a rung's own code. Measured, same flags, clang 22:
      # 261 -> 690 entries, examples/ 16 -> 276, spanning all thirteen example
      # directories. Configure goes 61s -> 107s locally for it.
      #
      # MORPH_LADDER_RUNGS is deliberately NOT passed: it already defaults to
      # "all" (CMakeLists.txt), and passing `-DMORPH_LADDER_RUNGS=all`
      # explicitly was measured to produce a byte-identical 690-entry database.
      # A flag that changes nothing is a flag that misleads the next reader
      # about what this step depends on.
      #
      # The prerequisites examples/common/CMakeLists.txt enforces with a
      # FATAL_ERROR are already met above: MORPH_BUILD_QT=ON is passed, and
      # MORPH_BUILD_TESTS defaults ON.
      # No full Build step: clang-tidy-diff.py reads compile_commands.json (a
      # configure-time artifact, CMAKE_EXPORT_COMPILE_COMMANDS=ON in the base
      # preset) and runs clang-tidy itself per translation unit -- it neither
      # needs the project actually compiled nor linked. pinned_facts.cmake's
      # generated header is likewise a configure_file() (configure-time), not
      # a build-time add_custom_command, so it's already on disk too.
      #
      # That paragraph answers "which generated headers exist without a
      # build?" for configure_file() output and *only* for configure_file()
      # output, while reading as though it had settled the question. It has
      # not: AUTOMOC's output is the other kind -- a build-time
      # add_custom_command -- and two sources #include it by name. See the
      # AUTOMOC step below, which is why this says "no full Build step" rather
      # than "no Build step".
      #
      # Compiler caching (sccache/fastcache-cc) is still not set up here. That
      # step compiles 67 objects; a real build of this configure would compile
      # the database's 737, so the caching steps would cost more setup than
      # they could save.
      #
      # MORPH_BUILD_BANK_GUI is the second flag "every optional feature is ON
      # here" is easy to be wrong about. It
      # defaults OFF (CMakeLists.txt), gates `add_subdirectory(gui)` in
      # examples/bank/CMakeLists.txt, and the bank GUI's *tests* are gated on
      # it too -- bank_gui_tests only exists `if(TARGET bank_gui_lib)`, which
      # is that option's target. Without it, eleven tracked sources have no
      # compile command in this job's database and are dropped, unanalysed,
      # by the filter below: nine under examples/bank/gui/ and two under
      # examples/bank/tests/gui/.
      #
      # Measured locally with clang 22.1.8, Qt 6, this job's own flag
      # set, cold build directory each time:
      #
      #   without BANK_GUI: 703 entries, 695 distinct in-workspace sources,
      #                     270 under examples/; 63 of 473 tracked C/C++
      #                     sources absent from the database; configure 63.7s
      #   with BANK_GUI:    737 entries, 727 distinct in-workspace sources,
      #                     281 under examples/; 52 absent; configure 64.4s
      #
      # The delta is exactly the eleven files, and the configure cost is under
      # a second -- an `add_subdirectory` of Qt Quick targets nothing here ever
      # builds. Both of the filter step's floors (600 in-workspace, 200 under
      # examples/) move further from their limit, not closer.
      #
      # This needs nothing new installed: linux-all-features already builds
      # this option on the same runner image with the same
      # `jurplel/install-qt-action@v4 modules: qtwebsockets` install and the
      # same apt set, so the GUI's Qml/Quick/QuickControls2 requirement is
      # already known to be met.
      #
      # What it does *not* do is clear the eleven files' existing findings.
      # Measured on the same configure, whole-file, with this step's own
      # `-extra-arg` pair: 97 findings inside the eleven sources themselves
      # (44 cppcoreguidelines-pro-bounds-avoid-unchecked-container-access, 23
      # performance-unnecessary-value-param, 9 misc-const-correctness, 8
      # readability-identifier-length, 13 others), across ten of them --
      # BankController.cpp is clean. clang-tidy-diff only reports on *changed*
      # lines, so none of that goes red until someone edits one of these files
      # on a line that carries a finding. Clearing them is separate work from
      # putting them in the database, and is deliberately not folded in here.
      - name: Configure (generates compile_commands.json over every optional feature)
        run: |
          cmake --preset clang-debug \
            -DMORPH_BUILD_NET=ON \
            -DMORPH_BUILD_QT=ON \
            -DMORPH_BUILD_FORMS_QML=ON \
            -DMORPH_BUILD_OFFLINE_SQLITE=ON \
            -DMORPH_BUILD_LOAD_TESTS=ON \
            -DMORPH_BUILD_HMAC_EXAMPLES=ON \
            -DMORPH_BUILD_FUZZERS=ON \
            -DMORPH_BUILD_LADDER=ON \
            -DMORPH_BUILD_BANK_EXAMPLE=ON \
            -DMORPH_BUILD_BANK_GUI=ON \
            -DCMAKE_C_COMPILER=clang-${{ env.CLANG_VERSION }} \
            -DCMAKE_CXX_COMPILER=clang++-${{ env.CLANG_VERSION }}

      # Two sources end with `#include "<own-basename>.moc"` -- the AUTOMOC
      # idiom for a Q_OBJECT declared inside a .cpp rather than in a header:
      # examples/common/testkit/test_qml_surface.cpp and
      # src/qt/forms/tests/tst_main.cpp. AUTOMOC writes that header at *build*
      # time into <target>_autogen/include/, so after a configure-only run it
      # does not exist and clang-tidy dies on the whole translation unit --
      # `error: 'tst_main.moc' file not found [clang-diagnostic-error]` -- with
      # WarningsAsErrors:"*" turning it into a failed job, before a single
      # changed line is analysed. Reproduced locally with this job's own
      # configure flags and clang-tidy 22.1.8: one line added to each of the
      # two files, and clang-tidy-diff.py exits 1 with exactly those two
      # diagnostics and nothing else.
      #
      # Suppressing the diagnostic instead is not available, not merely
      # unattractive. -Wno-missing-include-dirs below covers an include
      # *directory* that does not exist, not a #include that resolves to
      # nothing; and clang-tidy does not let a compiler error be filtered at
      # all. Measured locally with clang-tidy 22.1.8 on tst_main.cpp with the
      # moc absent: `-checks=-clang-diagnostic-error`,
      # `-checks=-clang-diagnostic-*` and `--warnings-as-errors=''` each still
      # exit 1 reporting the same line. The only remaining way to "filter" it
      # would be to grep clang-tidy-diff.py's output and override its exit
      # code -- a gate that cannot fail, built deliberately.
      #
      # So the headers get generated, for these two targets only. Not `cmake
      # --build` over everything, and not every *_autogen target either:
      # building all 91 of them was measured locally at 264 objects and 179s,
      # because a <target>_autogen target depends on that target's link
      # dependencies. Just these two, with USE_COMPILER_CACHE=OFF on a 12-core
      # Linux box: 100 ninja edges, 67 compilations, 7 links, 9 moc runs, 31s.
      # 39 of the 67 are the vendored Lightweight ORM, which
      # ladder_common_tests depends on transitively -- that, not moc, is what
      # this step costs. A four-core hosted runner pays more.
      #
      # The target list is written out rather than derived, so that it is
      # greppable and reviewable; the *check* underneath is derived from the
      # tree, so the list cannot go quietly stale. It rescans every tracked
      # C++ source for the self-include idiom and fails if a .moc that a
      # source names is still absent -- which is what a third source adopting
      # the idiom looks like. It also fails when it finds no self-include at
      # all: a step that generates nothing and reports green is this
      # repository's standing failure mode, and an empty scan is exactly how
      # this one would produce it.
      - name: Generate the AUTOMOC headers two sources include by name
        run: |
          cmake --build build/clang-debug --target \
            ladder_common_tests_autogen \
            morph_forms_qml_tests_autogen

          python3 - <<'PY'
          import json
          import pathlib
          import re
          import subprocess
          import sys

          root = pathlib.Path().resolve()
          database = json.loads(
              pathlib.Path("build/clang-debug/compile_commands.json").read_text())
          command_of = {
              pathlib.Path(entry["file"]).resolve(): entry["command"]
              for entry in database
          }

          tracked = subprocess.run(
              ["git", "ls-files", "-z", "*.cpp", "*.cc", "*.cxx"],
              capture_output=True, text=True, check=True).stdout.split("\0")
          self_include = re.compile(
              r'^[ \t]*#[ \t]*include[ \t]+"([^"]+\.moc)"', re.M)

          found = 0
          missing = 0
          for name in filter(None, tracked):
              source = pathlib.Path(name)
              for moc in self_include.findall(source.read_text(errors="replace")):
                  found += 1
                  command = command_of.get((root / source).resolve())
                  if command is None:
                      # Not in this configure's database: clang-tidy cannot
                      # analyse the file at all, which is a different problem
                      # and not one this step can fix.
                      print(f"::warning::{name} self-includes {moc} but has no "
                            f"compile command in this configure")
                      continue
                  directories = re.findall(r'-I(\S+_autogen/include)', command)
                  if not directories:
                      print(f"::error::{name} self-includes {moc} but its compile "
                            f"command names no *_autogen/include directory")
                      missing += 1
                      continue
                  if not any((pathlib.Path(d) / moc).is_file() for d in directories):
                      print(f"::error::{name}: {moc} was not generated -- add this "
                            f"source's <target>_autogen to the cmake --build above")
                      missing += 1
                      continue
                  print(f"ok: {name} -> {moc}")

          if found == 0:
              print("::error::no tracked source self-includes a .moc -- this "
                    "step's scan has stopped detecting the idiom it exists for")
              sys.exit(1)
          print(f"ok: {found} self-included .moc header(s), {missing} missing")
          sys.exit(1 if missing else 0)
          PY

      - name: Run clang-tidy-diff on changed lines
        run: |
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            BASE_SHA="${{ github.event.pull_request.base.sha }}"
          else
            BASE_SHA="${{ github.event.before }}"
          fi
          # The left-hand side of the pipeline below is *expected* to fail:
          # `find` exits non-zero when one of its two search roots is absent,
          # and `head -1` closing the pipe SIGPIPEs it. The `-z` test is what
          # reads the result. This is why the `set -o pipefail` further down is
          # placed after this line rather than at the top of the step, and why
          # the line carries a `pipefail-ok:` marker. The checker that read it was
              # removed with the meta-gates; the marker stays as the explanation.
          CLANG_TIDY_DIFF="$(find /usr/lib/llvm-${{ env.CLANG_VERSION }}/share/clang /usr/share/clang \
            -name 'clang-tidy-diff.py' 2>/dev/null | head -1)"  # pipefail-ok: find's roots may be absent; head SIGPIPEs it; the -z test below reads the result
          if [ -z "$CLANG_TIDY_DIFF" ]; then
            echo "::error::clang-tidy-diff.py not found"
            exit 1
          fi
          echo "Base SHA: $BASE_SHA"
          echo "Script: $CLANG_TIDY_DIFF"

          # `set -o pipefail` from here down, rather than for the whole step: a
          # `run:` with no `shell:` key runs under `bash -e {0}` -- `-e` but NOT
          # `-o pipefail` -- so a pipeline exits with its *last* command's
          # status. Ending in `tee`, which always succeeds, discarded
          # clang-tidy-diff.py's exit code and left this gate unable to fail on
          # anything it found. `tee` stays: the Upload step below
          # publishes the file it writes. Set here and not at the top, and not
          # via `shell: bash` (which is `bash --noprofile --norc -eo pipefail
          # {0}`), because the `find ... | head -1` above would then fail the
          # step whenever `find` exits non-zero -- one of its two search roots
          # being absent, or a SIGPIPE from `head` closing the pipe early.
          set -o pipefail

          # No -regex narrowing here, deliberately: every changed C/C++ file in
          # the diff is analysed. A `-regex` excluding
          # examples/{bank,common,<every rung>} is only defensible while the
          # Configure step leaves MORPH_BUILD_LADDER and MORPH_BUILD_BANK_EXAMPLE
          # at their OFF defaults, since those files then have no compile command
          # and can only produce `'ledger/core/errors.hpp' file not found`.
          # The Configure step passes both, which is what turns the ladder
          # configure from pure cost into coverage. Restoring any exclusion here
          # silently undoes 276 of the database's 690 entries.
          #
          # Deliberately NOT clang-tidy-diff.py's own -only-check-in-db either,
          # which filters on literal membership of compile_commands.json: no
          # header is ever a compilation unit, so it would silently drop all of
          # include/morph/** -- the same gate-measures-nothing failure one
          # directory over.
          #
          # -extra-arg is appended to the *compiler* command line, so an
          # -extra-arg=-warnings-as-errors=* here reaches clang as an unknown
          # argument and makes every translation unit fail with
          # `error: unknown argument` -- i.e. clang-tidy-diff.py exits 1 on
          # every non-empty diff, clean or not. There is nothing to add:
          # .clang-tidy already carries `WarningsAsErrors: "*"`.
          #
          # -Wno-missing-include-dirs: this job configures but never builds (see
          # the Configure step's comment), and Qt AUTOMOC's
          # <target>_autogen/include directories are created by the build. With
          # the ladder configured, 632 of the 690 stored commands name one (90
          # distinct directories, none of which exists after a configure-only
          # run), up from 203 of 261 -- and -Weverything + WarningsAsErrors:"*"
          # turns each into a clang-diagnostic error that says nothing about the
          # changed lines. Suppressing it is sufficient *for the directories*:
          # over the last ten commits' changed lines against the ladder database
          # this run reports 48 findings and zero clang-diagnostic-error from a
          # missing autogen directory, and no source under examples/, include/
          # or src/ includes a generated `moc_<name>.h`/`ui_<name>.h` from
          # another directory (the "Application ladder" job's own "Check no
          # generated moc include ascends" step is the standing guard on that).
          #
          # It is not sufficient for a generated header that a source includes
          # *by name*. This flag says nothing about `#include "tst_main.moc"`:
          # the directory it would be found in is one of the 90, but the error
          # raised is the file not being there, not the directory. That is what
          # the AUTOMOC step above generates, and why this job builds two
          # targets.
          # And it is not sufficient for a source this configure does not
          # build at all. That is one structural problem with three faces --
          # a generated header, tests/lint/ text fixtures, and an
          # unbuilt source: clang-tidy-diff.py analyses every
          # changed C/C++ line, a changed *comment* line is a changed line,
          # and clang tooling does not skip a file it has no compile command
          # for -- it interpolates a neighbouring entry's command. What comes
          # back is a clang-diagnostic-error about this job's configure, not a
          # lint finding about the diff, and WarningsAsErrors:"*" makes it a
          # failed job. Measured on a branch editing five such
          # sources in comments only: 21 clang-diagnostic-errors from the four
          # WASM mains (no Emscripten/Qt-WASM toolchain here) and from
          # tests/compile_checks/client_only_facade_no_model_header.cpp (built
          # by a configure-time try_run() with -DMORPH_CLIENT_ONLY, and
          # deliberately incomplete without it).
          #
          # Not editing the comments is no answer either: a comment that cites
          # a docs/spec section a branch renames has to change with it, or the
          # spec-citation gate goes red instead.
          #
          # So the diff is filtered first: a changed *source* with no entry in
          # compile_commands.json is dropped, and every drop is printed. A
          # changed *header* cannot be dropped on that test -- a header is
          # never a translation unit, so -only-check-in-db's literal
          # membership test would silently discard all of include/morph/**,
          # which is the same gate-measures-nothing failure (see above).
          # The filter refuses to run at all unless the database is still the
          # wide one the Configure step builds, because a filter consulting a
          # narrowed database would quietly stop analysing everything the
          # narrowing dropped.
          #
          # Keeping a changed header and handing it to clang-tidy with no
          # command at all is not the same as analysing it: clang
          # falls back to InterpolatingCompilationDatabase, borrows the
          # nearest entry's flags, and reports whatever the resulting broken
          # parse produces as findings *in the contributor's file*. Reproduced
          # on a new header in a directory with no .cpp:
          # 'Lightweight/SqlConnection.hpp' file not found, plus a
          # cppcoreguidelines-pro-type-member-init and a
          # readability-identifier-naming that are both false -- the
          # constructor does initialise those fields, and `_previous` is
          # spelled like every other private member there.
          #
          # So a changed header is *pinned*: the filter takes candidate
          # commands from the database nearest-first, actually runs each one
          # (`-fsyntax-only -x c++` on the header, with this job's own
          # -extra-args), and writes the first that parses into an augmented
          # database as a real entry for that header. clang-tidy then reads a
          # command somebody checked instead of interpolating one. A header no
          # candidate can parse is dropped with a warning that names the cause
          # -- which is the honest answer, because there is no command to
          # analyse it with -- and if that empties the diff the filter fails
          # rather than reporting a green gate over nothing.
          cat > /tmp/filter-unbuilt-sources.py <<'PY'
          import json
          import pathlib
          import re
          import shlex
          import subprocess
          import sys

          # Only *sources* are filtered out on membership. A header is never a
          # translation unit, so it is never in compile_commands.json -- it gets the
          # command check below instead.
          SOURCE_SUFFIXES = {".c", ".cc", ".cpp", ".cxx", ".c++", ".cl", ".m", ".mm"}
          HEADER_SUFFIXES = {".h", ".hh", ".hpp", ".hxx", ".h++", ".inc", ".ipp", ".tcc"}

          # Floors, not equalities. This filter is only trustworthy while the
          # database it consults is the wide one the Configure step builds: if
          # that configure regresses -- MORPH_BUILD_LADDER back to its OFF
          # default is the concrete way -- every examples/ source
          # would silently become "not built by this configure" and stop being
          # analysed, and this gate would go green having read 40% less code.
          MIN_ENTRIES = 600
          MIN_EXAMPLES_ENTRIES = 200

          # How many database entries a changed header is allowed to borrow flags from
          # before this script gives up on it. Candidates are tried nearest-first (by
          # shared path prefix), which is the same ordering clang's
          # InterpolatingCompilationDatabase uses -- the difference is that each one is
          # *checked* rather than assumed, and the first that parses the header is the
          # one written into the database. 8 is enough to cross a directory boundary
          # (the include/morph/** headers parse on candidate 1) without turning a
          # pathological header into a linear scan of 700 compilations.
          MAX_HEADER_CANDIDATES = 8

          root = pathlib.Path.cwd().resolve()
          database_path = pathlib.Path(sys.argv[1])
          database = json.loads(database_path.read_text())
          compiled = {pathlib.Path(entry["file"]).resolve() for entry in database}
          inside = {f for f in compiled if f.is_relative_to(root)}
          examples = {f for f in inside if f.is_relative_to(root / "examples")}

          if len(inside) < MIN_ENTRIES or len(examples) < MIN_EXAMPLES_ENTRIES:
              print(
                  f"::error::compile_commands.json names {len(inside)} "
                  f"in-workspace source(s) ({len(examples)} under examples/), "
                  f"below the floors {MIN_ENTRIES}/{MIN_EXAMPLES_ENTRIES}. This "
                  f"configure has stopped covering what the changed-source "
                  f"filter assumes it covers -- fix the configure, do not lower "
                  f"the floor."
              )
              sys.exit(1)


          def entry_command(entry):
              if "command" in entry:
                  return shlex.split(entry["command"])
              return list(entry["arguments"])


          def probe_argv(entry, header):
              """The entry's own compile command, aimed at `header` and told only to parse.

              Everything that makes the command produce *output* is dropped -- `-c`, the
              `-o`, the depfile switches and the source operand -- and nothing else is:
              the include paths and macro definitions are the whole point, and they are
              what the interpolated command gets wrong.
              """
              argv = entry_command(entry)
              out = [argv[0]]
              skip_next = False
              for arg in argv[1:]:
                  if skip_next:
                      skip_next = False
                      continue
                  if arg in ("-c",):
                      continue
                  if arg in ("-o", "-MT", "-MF", "-MQ", "-x"):
                      skip_next = True
                      continue
                  if arg in ("-MD", "-MMD", "-MP", "-M", "-MM"):
                      continue
                  # Every input operand goes, not just source-suffixed ones. A candidate
                  # can itself be a pinned header entry built by an earlier iteration,
                  # whose argv already ends in `-x c++ <that header>`; leaving it in
                  # hands clang two main files and it refuses with "expected exactly one
                  # compiler job". Caught by this branch's own clang-tidy-diff gate.
                  if pathlib.Path(arg).suffix.lower() in SOURCE_SUFFIXES | HEADER_SUFFIXES:
                      continue
                  out.append(arg)
              out += ["-fsyntax-only", "-x", "c++", str(header)]
              return out


          def shared_prefix_length(one, two):
              count = 0
              for a, b in zip(one.parts, two.parts):
                  if a != b:
                      break
                  count += 1
              return count


          donors = list(database)


          def command_for_header(header, extra_args):
              """Find a compile command that actually parses `header`, or None.

              Nearest-first by shared path prefix, and each candidate is *run* rather
              than trusted. Returns (entry, argv) for the first that parses.
              """
              # `donors`, not `database`: the pinned entries this loop appends must never
              # become candidates for the next header. They are derived commands, not
              # ones the build system produced, and borrowing from one compounds a guess
              # rather than checking it.
              candidates = sorted(
                  donors,
                  key=lambda e: -shared_prefix_length(header, pathlib.Path(e["file"])),
              )[:MAX_HEADER_CANDIDATES]
              for entry in candidates:
                  argv = probe_argv(entry, header) + list(extra_args)
                  try:
                      done = subprocess.run(
                          argv, cwd=entry["directory"], stdout=subprocess.DEVNULL,
                          stderr=subprocess.DEVNULL, timeout=300, check=False,
                      )
                  except (OSError, subprocess.TimeoutExpired):
                      continue
                  if done.returncode == 0:
                      return entry, argv
              return None, None


          sections = []
          current = None
          for line in pathlib.Path(sys.argv[2]).read_text(errors="replace").splitlines(keepends=True):
              if line.startswith("diff --git "):
                  current = []
                  sections.append(current)
              if current is None:
                  continue
              current.append(line)

          # Extra flags the clang-tidy-diff invocation passes through -extra-arg. The
          # probe has to see the same ones or it answers a question nobody asked.
          extra_args = sys.argv[5:]

          kept = []
          skipped = []
          unparseable = []
          pinned = []
          headers_seen = 0
          for section in sections:
              name = None
              for line in section:
                  match = re.match(r'^\+\+\+ (?:"?b/)?([^\t\n"]*)', line)
                  if match:
                      name = match.group(1)
                      break
              # A whole section is kept or dropped together, never just its
              # hunks: clang-tidy-diff.py attributes `@@` lines to the last
              # `+++` it saw, so dropping a `+++` while keeping its hunks would
              # charge them to the previous file.
              #
              # No destination path (a pure deletion) leaves nothing to
              # analyse, and clang-tidy-diff.py's extension filter drops it.
              if name is None or name == "/dev/null":
                  kept.append(section)
                  continue
              path = root / name
              suffix = path.suffix.lower()
              if suffix in SOURCE_SUFFIXES and path.resolve() not in compiled:
                  skipped.append(name)
                  continue
              if suffix in HEADER_SUFFIXES and path.is_file():
                  headers_seen += 1
                  entry, argv = command_for_header(path.resolve(), extra_args)
                  if entry is None:
                      unparseable.append(name)
                      continue
                  pinned.append((name, entry["file"]))
                  database.append({
                      "directory": entry["directory"],
                      "file": str(path.resolve()),
                      "arguments": argv,
                  })
              kept.append(section)

          if not sections:
              # A diff with no file sections at all means clang-tidy-diff.py
              # would be handed nothing, analyse nothing and exit 0 -- a green
              # gate over an empty input. The same shape one level up is a
              # local `git diff -U0 HEAD` on a committed branch; here it would
              # be a BASE_SHA that does not name this branch's fork point.
              # Neither a pull_request nor a push event
              # can legitimately produce an empty diff, so this is loud rather
              # than silent.
              print(
                  "::error::the diff handed to this filter has no file sections. "
                  "clang-tidy-diff.py would analyse zero files and exit 0, so this "
                  "gate would report success having read nothing. Check the base "
                  "revision the diff was computed against."
              )
              sys.exit(1)

          if sections and not kept:
              print(
                  f"::error::every one of the {len(sections)} changed file section(s) was "
                  f"dropped -- {len(skipped)} unbuilt source(s), {len(unparseable)} header(s) "
                  f"no compile command in this configure can parse. clang-tidy would then "
                  f"report success having analysed nothing, which is the failure this filter "
                  f"exists to prevent. Build these files from some target."
              )
              sys.exit(1)

          pathlib.Path(sys.argv[3]).write_text("".join(line for section in kept for line in section))

          # The augmented database: every original entry, plus one pinned entry per
          # changed header. clang-tidy is pointed at this one, so it never reaches
          # InterpolatingCompilationDatabase for a header and never analyses one with a
          # command nobody checked.
          out_db = pathlib.Path(sys.argv[4])
          out_db.mkdir(parents=True, exist_ok=True)
          (out_db / "compile_commands.json").write_text(json.dumps(database))

          for name in skipped:
              print(
                  f"::warning file={name}::not analysed by clang-tidy-diff: this "
                  f"configure builds no translation unit for it, so clang-tidy "
                  f"would interpolate a neighbouring entry's compile command and "
                  f"report only clang-diagnostic-errors about that."
              )
          for name in unparseable:
              print(
                  f"::warning file={name}::not analysed by clang-tidy-diff: none of the "
                  f"{MAX_HEADER_CANDIDATES} nearest compile commands in this configure can "
                  f"parse this header, so clang-tidy would report the failed parse as "
                  f"findings in your code. Build this header from some "
                  f"translation unit to have it analysed."
              )
          for name, donor in pinned:
              print(f"ok: {name} pinned to the compile command of {donor}")
          print(
              f"ok: compile database names {len(inside)} in-workspace source(s) "
              f"({len(examples)} under examples/); {len(kept)} of {len(sections)} "
              f"changed file section(s) analysed, {len(skipped)} source(s) "
              f"skipped as unbuilt here, {len(pinned)} header(s) pinned to a checked "
              f"compile command, {len(unparseable)} header(s) skipped as unparseable"
          )
          PY

          git diff -U0 "$BASE_SHA" > /tmp/changed.diff
          # The fourth argument is where the *augmented* database is written:
          # every entry the configure produced, plus one pinned entry per
          # changed header. Everything after it is the -extra-arg set below,
          # which the probe has to see or it answers a different question than
          # the one clang-tidy will ask.
          python3 /tmp/filter-unbuilt-sources.py \
            build/clang-debug/compile_commands.json /tmp/changed.diff /tmp/analysed.diff \
            /tmp/tidy-db -std=c++23 -Wno-missing-include-dirs

          # -path /tmp/tidy-db, not build/clang-debug: that is the augmented
          # database, and pointing clang-tidy at it is the whole fix for
          # the interpolated-command problem. The floors above are still
          # evaluated against
          # build/clang-debug's own database, so narrowing cannot hide behind
          # the augmentation.
          if ! python3 "$CLANG_TIDY_DIFF" \
              -path /tmp/tidy-db \
              -clang-tidy-binary clang-tidy-${{ env.CLANG_VERSION }} \
              -p1 \
              -j "$(nproc)" \
              -extra-arg=-std=c++23 \
              -extra-arg=-Wno-missing-include-dirs \
              -quiet \
              < /tmp/analysed.diff \
              2>&1 | tee clang-tidy-report.txt; then
            echo "::error::clang-tidy reported findings on changed lines -- see the log above and the clang-tidy-report artifact"
            exit 1
          fi

      - name: Upload clang-tidy report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: clang-tidy-report
          path: clang-tidy-report.txt

  # ── Deprecation-marker format lint ────────────────────────────────────

  install-export:
    name: find_package(morph CONFIG) consumability
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4

      # GCC 15 for the same reason the gcc-* presets use it: the default
      # logger needs a standard library with <print>, and ubuntu-24.04 ships
      # GCC 13.
      - name: Install GCC 15 and ninja
        run: |
          sudo apt-get update -q
          sudo apt-get install -y software-properties-common
          sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
          sudo apt-get update -q
          sudo apt-get install -y gcc-15 g++-15 ninja-build

      # See scripts/test_check_install_export.sh's own comment: a gate nobody
      # tests reports green whether or not it still detects anything, and this
      # one guards a defect whose whole character was reporting success.
      - name: Self-test the install/export checker
        env:
          CC: gcc-15
          CXX: g++-15
        run: bash scripts/test_check_install_export.sh

      # The check itself: install to a scratch prefix, then configure, build
      # and run a consumer project outside the tree against morph::morph and
      # morph::net via find_package(morph CONFIG REQUIRED).
      - name: Install morph and build a consumer against the prefix
        env:
          CC: gcc-15
          CXX: g++-15
        run: bash scripts/check_install_export.sh

  install-export-forms-qml:
    name: MorphForms QML module consumability
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4

      # GCC 15 for the same reason install-export uses it (<print>); the GL and
      # xcb libraries are what the offscreen QPA plugin still links against.
      - name: Install GCC 15, ninja and the Qt runtime libraries
        run: |
          sudo apt-get update -q
          sudo apt-get install -y software-properties-common
          sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
          sudo apt-get update -q
          sudo apt-get install -y gcc-15 g++-15 ninja-build \
            libgl1-mesa-dev libxkbcommon-x11-0 libxcb-cursor0 libxcb-icccm4 \
            libxcb-keysyms1 libxcb-shape0 libxcb-xinerama0

      # Not the distro's Qt: MORPH_BUILD_FORMS_QML needs 6.5+ and Ubuntu 24.04
      # ships 6.4.2 (see linux-all-features' identical step).
      - name: Install Qt ${{ env.QT_VERSION }}
        uses: jurplel/install-qt-action@v4.3.1
        with:
          version: ${{ env.QT_VERSION }}
          cache: true

      # Install MorphForms to a scratch prefix, then build and *run* an
      # application that renders a DynamicForm from it -- plus the vacuity
      # guard that the same application without the plugin cannot.
      - name: Install MorphForms and render a form from the prefix
        env:
          CC: gcc-15
          CXX: g++-15
        run: bash scripts/check_forms_qml_install.sh