From 8800ffc0ae189e785d05383a3bff753100665e33 Mon Sep 17 00:00:00 2001
From: Yuma Endo <endo@skipbit.jp>
Date: Fri, 31 Jul 2026 09:59:00 +0900
Subject: [PATCH 1/8] ci: restructure the build matrix around the supported
 compiler range

The macOS GCC jobs have been failing since the macos-latest label moved to
macOS 26: the SDK defines xnu_static_assert_struct_size only for Clang, so
Homebrew GCC leaves the macro unexpanded and the build stops inside
mach/message.h. Raising the GCC version does not help, as the same failure is
reported for 15.

That failure exposed a wider mismatch between what the documentation promises
and what CI verifies. MSVC 2022+ was declared without a single Windows job,
macOS was verified without being declared, and the three places stating the
requirements disagreed with each other (README said Clang 17+, contributing.rst
said Clang 16+).

Rework the matrix so that it verifies the declared range and nothing else:

- Pin every required job to a specific runner image and take compilers from the
  image only. ubuntu-24.04 provides GCC 13 and Clang 17 (the lower bound),
  ubuntu-26.04 provides GCC 15 and Clang 22 (the newest we verify). This drops
  the ppa:ubuntu-toolchain-r/test and apt.llvm.org dependencies, including the
  jammy-pinned list that was being added to a noble runner.
- Replace macos-14/macos-15 with macos-15/macos-26. macOS 14 is scheduled for
  removal in November, and Apple Clang tracks the OS image, so varying the OS
  already varies the compiler.
- Drop the macOS Homebrew GCC jobs. That combination was never declared as
  supported, and the breakage originates in the SDK rather than in this project.
- Stop forcing -stdlib=libc++ on Linux Clang. Most Clang users on Linux build
  against the default standard library; libc++ moves to the nightly watch.
- Pin the static library and installation jobs to specific images instead of
  the floating labels.

Add a nightly watch for what the required gates deliberately exclude: the
newest GCC and Clang from external repositories, libc++, and the floating
runner labels. Breaking there is the signal we want ahead of users hitting it,
so those jobs never gate a pull request.

Restate the requirements as a verified range plus best effort, with the README
as the single source. An open-ended "GCC 13+" cannot be verified by a finite
matrix, and GCC 16 is deliberately left to the nightly watch. Remove MSVC and
Windows from the declared support so the promise matches what is exercised.
---
 .github/workflows/linux.yml            |  72 ++++++------
 .github/workflows/macos.yml            |  73 +++---------
 .github/workflows/nightly.yml          | 150 +++++++++++++++++++++++++
 README.md                              |   4 +-
 docs/sphinx/source/contributing.rst    |   3 +-
 docs/sphinx/source/getting-started.rst |  13 ++-
 6 files changed, 211 insertions(+), 104 deletions(-)
 create mode 100644 .github/workflows/nightly.yml

diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml
index 4d9725b..e514c99 100644
--- a/.github/workflows/linux.yml
+++ b/.github/workflows/linux.yml
@@ -6,86 +6,85 @@ on:
   pull_request:
     branches: [ main, develop ]
 
+# Compilers come from the runner images only. Pinning the OS pins the compiler
+# set, which keeps an upstream repository change from breaking a required gate.
+# ubuntu-24.04 covers the lower bound of the supported range, ubuntu-26.04 the
+# newest versions we verify.
+
 jobs:
   build-ubuntu-gcc:
     name: Ubuntu GCC Build
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.toolchain.os }}
     strategy:
+      fail-fast: false
       matrix:
         build_type: [Debug, Release]
-        gcc_version: [13, 14]
+        toolchain:
+          - { os: ubuntu-24.04, gcc: 13 }
+          - { os: ubuntu-26.04, gcc: 15 }
 
     steps:
     - uses: actions/checkout@v7
 
-    - name: Install dependencies and GCC ${{ matrix.gcc_version }}
+    - name: Report toolchain versions
       run: |
-        sudo apt-get update
-        sudo apt-get install -y cmake build-essential software-properties-common
-        sudo add-apt-repository ppa:ubuntu-toolchain-r/test -y
-        sudo apt-get update
-        sudo apt-get install -y gcc-${{ matrix.gcc_version }} g++-${{ matrix.gcc_version }}
+        gcc-${{ matrix.toolchain.gcc }} --version
+        cmake --version
 
     - name: Configure CMake
       run: |
         cmake -S . -B build \
           -DCMAKE_BUILD_TYPE=${{ matrix.build_type }} \
-          -DCMAKE_C_COMPILER=gcc-${{ matrix.gcc_version }} \
-          -DCMAKE_CXX_COMPILER=g++-${{ matrix.gcc_version }}
+          -DCMAKE_C_COMPILER=gcc-${{ matrix.toolchain.gcc }} \
+          -DCMAKE_CXX_COMPILER=g++-${{ matrix.toolchain.gcc }}
 
     - name: Build
-      run: cmake --build build --config ${{ matrix.build_type }} -j$(nproc)
+      run: cmake --build build --config ${{ matrix.build_type }} -j"$(nproc)"
 
     - name: Test
       run: ./build/test/dross_test --gtest_color=yes
 
   build-ubuntu-clang:
     name: Ubuntu Clang Build
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.toolchain.os }}
     strategy:
+      fail-fast: false
       matrix:
         build_type: [Debug, Release]
-        clang_version: [17, 18]
+        toolchain:
+          - { os: ubuntu-24.04, clang: 17 }
+          - { os: ubuntu-26.04, clang: 22 }
 
     steps:
     - uses: actions/checkout@v7
 
-    - name: Install dependencies and Clang ${{ matrix.clang_version }}
+    - name: Report toolchain versions
       run: |
-        sudo apt-get update
-        sudo apt-get install -y cmake build-essential
-        wget -qO- https://apt.llvm.org/llvm-snapshot.gpg.key | sudo tee /etc/apt/trusted.gpg.d/apt.llvm.org.asc
-        echo "deb http://apt.llvm.org/jammy/ llvm-toolchain-jammy-${{ matrix.clang_version }} main" | sudo tee /etc/apt/sources.list.d/llvm.list
-        sudo apt-get update
-        sudo apt-get install -y clang-${{ matrix.clang_version }} libc++-${{ matrix.clang_version }}-dev libc++abi-${{ matrix.clang_version }}-dev
+        clang-${{ matrix.toolchain.clang }} --version
+        cmake --version
 
+    # No -stdlib override: the default standard library is what most Clang
+    # users on Linux build against.
     - name: Configure CMake
       run: |
         cmake -S . -B build \
           -DCMAKE_BUILD_TYPE=${{ matrix.build_type }} \
-          -DCMAKE_C_COMPILER=clang-${{ matrix.clang_version }} \
-          -DCMAKE_CXX_COMPILER=clang++-${{ matrix.clang_version }} \
-          -DCMAKE_CXX_FLAGS="-stdlib=libc++" \
-          -DCMAKE_EXE_LINKER_FLAGS="-stdlib=libc++"
+          -DCMAKE_C_COMPILER=clang-${{ matrix.toolchain.clang }} \
+          -DCMAKE_CXX_COMPILER=clang++-${{ matrix.toolchain.clang }}
 
     - name: Build
-      run: cmake --build build --config ${{ matrix.build_type }} -j$(nproc)
+      run: cmake --build build --config ${{ matrix.build_type }} -j"$(nproc)"
 
     - name: Test
       run: ./build/test/dross_test --gtest_color=yes
 
   build-static-library:
     name: Static Library Build
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
 
     steps:
     - uses: actions/checkout@v7
 
-    - name: Install dependencies
-      run: |
-        sudo apt-get update
-        sudo apt-get install -y cmake build-essential
-
     - name: Configure CMake (Static)
       run: |
         cmake -S . -B build \
@@ -93,27 +92,22 @@ jobs:
           -DBUILD_SHARED_LIBS=OFF
 
     - name: Build
-      run: cmake --build build -j$(nproc)
+      run: cmake --build build -j"$(nproc)"
 
     - name: Test
       run: ./build/test/dross_test --gtest_color=yes
 
   install-test:
     name: Installation Test
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
 
     steps:
     - uses: actions/checkout@v7
 
-    - name: Install dependencies
-      run: |
-        sudo apt-get update
-        sudo apt-get install -y cmake build-essential pkg-config
-
     - name: Build and Install
       run: |
         cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
-        cmake --build build -j$(nproc)
+        cmake --build build -j"$(nproc)"
         sudo cmake --install build
 
     - name: Test find_package
diff --git a/.github/workflows/macos.yml b/.github/workflows/macos.yml
index 23599b6..c202a01 100644
--- a/.github/workflows/macos.yml
+++ b/.github/workflows/macos.yml
@@ -6,22 +6,28 @@ on:
   pull_request:
     branches: [ main, develop ]
 
+# macOS users build with the Apple Clang that ships with the OS, so the OS
+# generation is the axis worth varying: pinning to the two current releases
+# covers two Apple Clang generations without a separate compiler axis.
+
 jobs:
   build-macos-clang:
     name: macOS Clang Build
     runs-on: ${{ matrix.os }}
     strategy:
+      fail-fast: false
       matrix:
-        os: [macos-14, macos-15]
+        os: [macos-15, macos-26]
         build_type: [Debug, Release]
 
     steps:
     - uses: actions/checkout@v7
 
-    - name: Install dependencies
+    - name: Report toolchain versions
       run: |
-        brew update
-        brew install cmake
+        clang --version
+        xcrun --show-sdk-version
+        cmake --version
 
     - name: Configure CMake
       run: |
@@ -29,62 +35,18 @@ jobs:
           -DCMAKE_BUILD_TYPE=${{ matrix.build_type }}
 
     - name: Build
-      run: cmake --build build --config ${{ matrix.build_type }} -j$(sysctl -n hw.ncpu)
-
-    - name: Test
-      run: ./build/test/dross_test --gtest_color=yes
-
-  build-macos-gcc:
-    name: macOS GCC Build
-    runs-on: macos-latest
-    strategy:
-      matrix:
-        build_type: [Debug, Release]
-        gcc_version: [13, 14]
-
-    steps:
-    - uses: actions/checkout@v7
-
-    - name: Install dependencies and GCC ${{ matrix.gcc_version }}
-      run: |
-        brew update
-        brew install cmake gcc@${{ matrix.gcc_version }}
-
-    - name: Configure CMake
-      run: |
-        # Find GCC path (different for Intel and Apple Silicon)
-        if [ -x "/usr/local/bin/gcc-${{ matrix.gcc_version }}" ]; then
-          GCC_PATH="/usr/local/bin"
-        elif [ -x "/opt/homebrew/bin/gcc-${{ matrix.gcc_version }}" ]; then
-          GCC_PATH="/opt/homebrew/bin"
-        else
-          echo "GCC ${{ matrix.gcc_version }} not found"
-          exit 1
-        fi
-
-        cmake -S . -B build \
-          -DCMAKE_BUILD_TYPE=${{ matrix.build_type }} \
-          -DCMAKE_C_COMPILER=$GCC_PATH/gcc-${{ matrix.gcc_version }} \
-          -DCMAKE_CXX_COMPILER=$GCC_PATH/g++-${{ matrix.gcc_version }}
-
-    - name: Build
-      run: cmake --build build --config ${{ matrix.build_type }} -j$(sysctl -n hw.ncpu)
+      run: cmake --build build --config ${{ matrix.build_type }} -j"$(sysctl -n hw.ncpu)"
 
     - name: Test
       run: ./build/test/dross_test --gtest_color=yes
 
   build-static-library:
     name: macOS Static Library Build
-    runs-on: macos-latest
+    runs-on: macos-15
 
     steps:
     - uses: actions/checkout@v7
 
-    - name: Install dependencies
-      run: |
-        brew update
-        brew install cmake
-
     - name: Configure CMake (Static)
       run: |
         cmake -S . -B build \
@@ -92,27 +54,22 @@ jobs:
           -DBUILD_SHARED_LIBS=OFF
 
     - name: Build
-      run: cmake --build build -j$(sysctl -n hw.ncpu)
+      run: cmake --build build -j"$(sysctl -n hw.ncpu)"
 
     - name: Test
       run: ./build/test/dross_test --gtest_color=yes
 
   install-test:
     name: macOS Installation Test
-    runs-on: macos-latest
+    runs-on: macos-15
 
     steps:
     - uses: actions/checkout@v7
 
-    - name: Install dependencies
-      run: |
-        brew update
-        brew install cmake pkg-config
-
     - name: Build and Install
       run: |
         cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
-        cmake --build build -j$(sysctl -n hw.ncpu)
+        cmake --build build -j"$(sysctl -n hw.ncpu)"
         sudo cmake --install build
 
     - name: Test find_package
diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml
new file mode 100644
index 0000000..c5f6e36
--- /dev/null
+++ b/.github/workflows/nightly.yml
@@ -0,0 +1,150 @@
+name: Nightly Toolchain Watch
+
+on:
+  schedule:
+    # 03:00 UTC daily
+    - cron: '0 3 * * *'
+  workflow_dispatch:
+
+# Early warning for environments outside the verified range: the newest
+# compilers and the floating runner labels. These jobs deliberately use the
+# wiring the required gates avoid — floating OS labels and compilers from
+# external repositories — because breaking here is the signal we want, ahead
+# of users hitting it. They never gate a pull request and must not be added to
+# required status checks.
+
+jobs:
+  newest-gcc:
+    name: Newest GCC
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        build_type: [Release]
+
+    steps:
+    - uses: actions/checkout@v7
+
+    - name: Install newest GCC
+      run: |
+        sudo add-apt-repository ppa:ubuntu-toolchain-r/test -y
+        sudo apt-get update
+        sudo apt-get install -y gcc-16 g++-16
+
+    - name: Report toolchain versions
+      run: |
+        gcc-16 --version
+        cmake --version
+
+    - name: Configure CMake
+      run: |
+        cmake -S . -B build \
+          -DCMAKE_BUILD_TYPE=${{ matrix.build_type }} \
+          -DCMAKE_C_COMPILER=gcc-16 \
+          -DCMAKE_CXX_COMPILER=g++-16
+
+    - name: Build
+      run: cmake --build build -j"$(nproc)"
+
+    - name: Test
+      run: ./build/test/dross_test --gtest_color=yes
+
+  newest-clang:
+    name: Newest Clang
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        build_type: [Release]
+
+    steps:
+    - uses: actions/checkout@v7
+
+    - name: Install newest Clang
+      run: |
+        wget https://apt.llvm.org/llvm.sh
+        chmod +x llvm.sh
+        sudo ./llvm.sh
+        version=$(find /usr/lib -maxdepth 1 -name 'llvm-[0-9]*' -printf '%f\n' \
+          | sed 's/llvm-//' | sort -n | tail -1)
+        echo "CLANG_VERSION=$version" >> "$GITHUB_ENV"
+
+    - name: Report toolchain versions
+      run: |
+        clang-"$CLANG_VERSION" --version
+        cmake --version
+
+    - name: Configure CMake
+      run: |
+        cmake -S . -B build \
+          -DCMAKE_BUILD_TYPE=${{ matrix.build_type }} \
+          -DCMAKE_C_COMPILER=clang-"$CLANG_VERSION" \
+          -DCMAKE_CXX_COMPILER=clang++-"$CLANG_VERSION"
+
+    - name: Build
+      run: cmake --build build -j"$(nproc)"
+
+    - name: Test
+      run: ./build/test/dross_test --gtest_color=yes
+
+  libcxx:
+    name: Clang with libc++
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        build_type: [Release]
+
+    steps:
+    - uses: actions/checkout@v7
+
+    - name: Install libc++
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y libc++-17-dev libc++abi-17-dev
+
+    - name: Report toolchain versions
+      run: |
+        clang-17 --version
+        cmake --version
+
+    - name: Configure CMake
+      run: |
+        cmake -S . -B build \
+          -DCMAKE_BUILD_TYPE=${{ matrix.build_type }} \
+          -DCMAKE_C_COMPILER=clang-17 \
+          -DCMAKE_CXX_COMPILER=clang++-17 \
+          -DCMAKE_CXX_FLAGS="-stdlib=libc++" \
+          -DCMAKE_EXE_LINKER_FLAGS="-stdlib=libc++"
+
+    - name: Build
+      run: cmake --build build -j"$(nproc)"
+
+    - name: Test
+      run: ./build/test/dross_test --gtest_color=yes
+
+  floating-runners:
+    name: Floating Runner
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+
+    steps:
+    - uses: actions/checkout@v7
+
+    - name: Report toolchain versions
+      run: |
+        cc --version
+        cmake --version
+
+    - name: Configure CMake
+      run: |
+        cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+
+    - name: Build
+      run: cmake --build build -j2
+
+    - name: Test
+      run: ./build/test/dross_test --gtest_color=yes
diff --git a/README.md b/README.md
index 33b88f5..2f3a328 100644
--- a/README.md
+++ b/README.md
@@ -23,7 +23,9 @@
 
 ### Requirements
 
-- **C++23** compatible compiler (GCC 13+, Clang 17+, MSVC 2022+)
+- **C++23** compatible compiler
+  - Verified in CI: GCC 13–15, Clang 17–22, Apple Clang (macOS 15 and 26)
+  - Newer versions are best effort, exercised by the nightly toolchain watch
 - **CMake 3.20+**
 
 ### Installation
diff --git a/docs/sphinx/source/contributing.rst b/docs/sphinx/source/contributing.rst
index ff41c57..cef8488 100644
--- a/docs/sphinx/source/contributing.rst
+++ b/docs/sphinx/source/contributing.rst
@@ -33,7 +33,8 @@ Development Setup
 Build Requirements
 ~~~~~~~~~~~~~~~~~~
 
-- C++23 compatible compiler (GCC 13+, Clang 16+, MSVC 2022+)
+- C++23 compatible compiler (verified in CI: GCC 13-15, Clang 17-22,
+  Apple Clang on macOS 15 and 26; newer versions are best effort)
 - CMake 3.20 or later
 - Git
 
diff --git a/docs/sphinx/source/getting-started.rst b/docs/sphinx/source/getting-started.rst
index 3d965a9..f5e44ac 100644
--- a/docs/sphinx/source/getting-started.rst
+++ b/docs/sphinx/source/getting-started.rst
@@ -9,13 +9,16 @@ System Requirements
 To build and use dross, you need:
 
 - **C++ Compiler**: Supporting C++23 standard
-  
-  - GCC 13 or later
-  - Clang 16 or later (with libc++ for full C++23 support)
-  - MSVC 2022 or later
+
+  - GCC 13 through 15
+  - Clang 17 through 22
+  - Apple Clang shipped with macOS 15 or 26
+
+  Newer versions are best effort: they are exercised by the nightly toolchain
+  watch rather than by the required build matrix.
 
 - **Build System**: CMake 3.20 or later
-- **Operating System**: Linux, macOS, Windows, or any POSIX-compliant system
+- **Operating System**: Linux or macOS
 
 Installation
 ------------

From 7b07c0ba6389de3a40fa84b328de0cc58a27004a Mon Sep 17 00:00:00 2001
From: Yuma Endo <endo@skipbit.jp>
Date: Fri, 31 Jul 2026 10:05:36 +0900
Subject: [PATCH 2/8] ci: sharpen the declared range and make the nightly watch
 self-updating

Follow-up to the matrix rework, addressing three gaps found while reviewing it.

The requirements listed compilers and operating systems on separate axes, which
read as if macOS with GCC were supported. It is not: the required gates cover
Linux with GCC or Clang, and macOS with the Apple Clang from the OS image.
State the combinations per platform instead of listing them in parallel.

The nightly jobs pinned GCC 16 and derived the Clang version by scanning
/usr/lib for llvm-*, which also matches the versions the runner image ships
and would silently pick one of those. Query apt after adding each repository
instead, so both jobs install the newest version that repository offers and
keep tracking upstream without edits. An empty result now fails the step rather
than invoking a command with no version suffix.

Matrix entries are objects, so the generated job names embedded the whole
object. Name the jobs explicitly, and report cmake and pkg-config versions in
the installation jobs now that the package installation steps are gone.
---
 .github/workflows/linux.yml            |  9 ++++-
 .github/workflows/macos.yml            |  7 +++-
 .github/workflows/nightly.yml          | 51 ++++++++++++++------------
 README.md                              |  5 ++-
 docs/sphinx/source/contributing.rst    |  4 +-
 docs/sphinx/source/getting-started.rst |  5 +--
 6 files changed, 48 insertions(+), 33 deletions(-)

diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml
index e514c99..0e6b5aa 100644
--- a/.github/workflows/linux.yml
+++ b/.github/workflows/linux.yml
@@ -13,7 +13,7 @@ on:
 
 jobs:
   build-ubuntu-gcc:
-    name: Ubuntu GCC Build
+    name: Ubuntu GCC ${{ matrix.toolchain.gcc }} (${{ matrix.build_type }})
     runs-on: ${{ matrix.toolchain.os }}
     strategy:
       fail-fast: false
@@ -45,7 +45,7 @@ jobs:
       run: ./build/test/dross_test --gtest_color=yes
 
   build-ubuntu-clang:
-    name: Ubuntu Clang Build
+    name: Ubuntu Clang ${{ matrix.toolchain.clang }} (${{ matrix.build_type }})
     runs-on: ${{ matrix.toolchain.os }}
     strategy:
       fail-fast: false
@@ -104,6 +104,11 @@ jobs:
     steps:
     - uses: actions/checkout@v7
 
+    - name: Report toolchain versions
+      run: |
+        cmake --version
+        pkg-config --version
+
     - name: Build and Install
       run: |
         cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
diff --git a/.github/workflows/macos.yml b/.github/workflows/macos.yml
index c202a01..1cb3fe8 100644
--- a/.github/workflows/macos.yml
+++ b/.github/workflows/macos.yml
@@ -12,7 +12,7 @@ on:
 
 jobs:
   build-macos-clang:
-    name: macOS Clang Build
+    name: macOS Clang (${{ matrix.os }}, ${{ matrix.build_type }})
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
@@ -66,6 +66,11 @@ jobs:
     steps:
     - uses: actions/checkout@v7
 
+    - name: Report toolchain versions
+      run: |
+        cmake --version
+        pkg-config --version
+
     - name: Build and Install
       run: |
         cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml
index c5f6e36..80a1acb 100644
--- a/.github/workflows/nightly.yml
+++ b/.github/workflows/nightly.yml
@@ -17,31 +17,36 @@ jobs:
   newest-gcc:
     name: Newest GCC
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        build_type: [Release]
 
     steps:
     - uses: actions/checkout@v7
 
+    # Resolve the newest g++ the toolchain PPA offers rather than pinning a
+    # major, so this keeps tracking upstream without edits.
     - name: Install newest GCC
       run: |
         sudo add-apt-repository ppa:ubuntu-toolchain-r/test -y
         sudo apt-get update
-        sudo apt-get install -y gcc-16 g++-16
+        version=$(apt-cache search --names-only '^g\+\+-[0-9]+$' \
+          | sed 's/^g++-//; s/ .*//' | sort -n | tail -1)
+        if [ -z "$version" ]; then
+          echo "No versioned g++ package found in the toolchain PPA" >&2
+          exit 1
+        fi
+        sudo apt-get install -y "gcc-$version" "g++-$version"
+        echo "GCC_VERSION=$version" >> "$GITHUB_ENV"
 
     - name: Report toolchain versions
       run: |
-        gcc-16 --version
+        gcc-"$GCC_VERSION" --version
         cmake --version
 
     - name: Configure CMake
       run: |
         cmake -S . -B build \
-          -DCMAKE_BUILD_TYPE=${{ matrix.build_type }} \
-          -DCMAKE_C_COMPILER=gcc-16 \
-          -DCMAKE_CXX_COMPILER=g++-16
+          -DCMAKE_BUILD_TYPE=Release \
+          -DCMAKE_C_COMPILER=gcc-"$GCC_VERSION" \
+          -DCMAKE_CXX_COMPILER=g++-"$GCC_VERSION"
 
     - name: Build
       run: cmake --build build -j"$(nproc)"
@@ -52,21 +57,25 @@ jobs:
   newest-clang:
     name: Newest Clang
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        build_type: [Release]
 
     steps:
     - uses: actions/checkout@v7
 
+    # llvm.sh adds the apt.llvm.org repository and installs the current stable
+    # release. Query apt afterwards so the version comes from that repository
+    # rather than from whatever the runner image happens to ship.
     - name: Install newest Clang
       run: |
         wget https://apt.llvm.org/llvm.sh
         chmod +x llvm.sh
         sudo ./llvm.sh
-        version=$(find /usr/lib -maxdepth 1 -name 'llvm-[0-9]*' -printf '%f\n' \
-          | sed 's/llvm-//' | sort -n | tail -1)
+        version=$(apt-cache search --names-only '^clang-[0-9]+$' \
+          | sed 's/^clang-//; s/ .*//' | sort -n | tail -1)
+        if [ -z "$version" ]; then
+          echo "No versioned clang package found in the apt.llvm.org repository" >&2
+          exit 1
+        fi
+        sudo apt-get install -y "clang-$version"
         echo "CLANG_VERSION=$version" >> "$GITHUB_ENV"
 
     - name: Report toolchain versions
@@ -77,7 +86,7 @@ jobs:
     - name: Configure CMake
       run: |
         cmake -S . -B build \
-          -DCMAKE_BUILD_TYPE=${{ matrix.build_type }} \
+          -DCMAKE_BUILD_TYPE=Release \
           -DCMAKE_C_COMPILER=clang-"$CLANG_VERSION" \
           -DCMAKE_CXX_COMPILER=clang++-"$CLANG_VERSION"
 
@@ -90,10 +99,6 @@ jobs:
   libcxx:
     name: Clang with libc++
     runs-on: ubuntu-24.04
-    strategy:
-      fail-fast: false
-      matrix:
-        build_type: [Release]
 
     steps:
     - uses: actions/checkout@v7
@@ -111,7 +116,7 @@ jobs:
     - name: Configure CMake
       run: |
         cmake -S . -B build \
-          -DCMAKE_BUILD_TYPE=${{ matrix.build_type }} \
+          -DCMAKE_BUILD_TYPE=Release \
           -DCMAKE_C_COMPILER=clang-17 \
           -DCMAKE_CXX_COMPILER=clang++-17 \
           -DCMAKE_CXX_FLAGS="-stdlib=libc++" \
@@ -124,7 +129,7 @@ jobs:
       run: ./build/test/dross_test --gtest_color=yes
 
   floating-runners:
-    name: Floating Runner
+    name: Floating Runner (${{ matrix.os }})
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
@@ -144,7 +149,7 @@ jobs:
         cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
 
     - name: Build
-      run: cmake --build build -j2
+      run: cmake --build build --parallel
 
     - name: Test
       run: ./build/test/dross_test --gtest_color=yes
diff --git a/README.md b/README.md
index 2f3a328..6618ac4 100644
--- a/README.md
+++ b/README.md
@@ -23,8 +23,9 @@
 
 ### Requirements
 
-- **C++23** compatible compiler
-  - Verified in CI: GCC 13–15, Clang 17–22, Apple Clang (macOS 15 and 26)
+- **C++23** compatible compiler, verified in CI as:
+  - Linux: GCC 13–15 or Clang 17–22
+  - macOS: the Apple Clang shipped with macOS 15 or 26
   - Newer versions are best effort, exercised by the nightly toolchain watch
 - **CMake 3.20+**
 
diff --git a/docs/sphinx/source/contributing.rst b/docs/sphinx/source/contributing.rst
index cef8488..3cc54bf 100644
--- a/docs/sphinx/source/contributing.rst
+++ b/docs/sphinx/source/contributing.rst
@@ -33,8 +33,8 @@ Development Setup
 Build Requirements
 ~~~~~~~~~~~~~~~~~~
 
-- C++23 compatible compiler (verified in CI: GCC 13-15, Clang 17-22,
-  Apple Clang on macOS 15 and 26; newer versions are best effort)
+- C++23 compatible compiler: on Linux, GCC 13-15 or Clang 17-22; on macOS,
+  the Apple Clang shipped with macOS 15 or 26. Newer versions are best effort.
 - CMake 3.20 or later
 - Git
 
diff --git a/docs/sphinx/source/getting-started.rst b/docs/sphinx/source/getting-started.rst
index f5e44ac..d60f7cc 100644
--- a/docs/sphinx/source/getting-started.rst
+++ b/docs/sphinx/source/getting-started.rst
@@ -10,9 +10,8 @@ To build and use dross, you need:
 
 - **C++ Compiler**: Supporting C++23 standard
 
-  - GCC 13 through 15
-  - Clang 17 through 22
-  - Apple Clang shipped with macOS 15 or 26
+  - On Linux: GCC 13 through 15, or Clang 17 through 22
+  - On macOS: the Apple Clang shipped with macOS 15 or 26
 
   Newer versions are best effort: they are exercised by the nightly toolchain
   watch rather than by the required build matrix.

From 494424d642d4e2a043c9d371f6d96f5bf3c7b112 Mon Sep 17 00:00:00 2001
From: Yuma Endo <endo@skipbit.jp>
Date: Fri, 31 Jul 2026 10:09:13 +0900
Subject: [PATCH 3/8] ci: describe what the nightly version resolution actually
 guarantees

The comments claimed the resolved version comes from the repository just
added, but the query looks at every configured source. State what the step
does, and record that tracking the stable release rather than trunk is a
choice: the watch exists to catch what users will hit, not what is still in
development.
---
 .github/workflows/nightly.yml | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml
index 80a1acb..6f5c670 100644
--- a/.github/workflows/nightly.yml
+++ b/.github/workflows/nightly.yml
@@ -21,8 +21,9 @@ jobs:
     steps:
     - uses: actions/checkout@v7
 
-    # Resolve the newest g++ the toolchain PPA offers rather than pinning a
-    # major, so this keeps tracking upstream without edits.
+    # Resolve the newest versioned g++ available once the toolchain PPA is in
+    # place, rather than pinning a major, so this keeps tracking upstream
+    # without edits.
     - name: Install newest GCC
       run: |
         sudo add-apt-repository ppa:ubuntu-toolchain-r/test -y
@@ -61,9 +62,10 @@ jobs:
     steps:
     - uses: actions/checkout@v7
 
-    # llvm.sh adds the apt.llvm.org repository and installs the current stable
-    # release. Query apt afterwards so the version comes from that repository
-    # rather than from whatever the runner image happens to ship.
+    # llvm.sh adds the apt.llvm.org repository for the current stable release,
+    # then we take the newest versioned clang package available. Tracking the
+    # stable release rather than trunk (llvm.sh all) is deliberate: this watches
+    # what users will actually reach for, not what is still in development.
     - name: Install newest Clang
       run: |
         wget https://apt.llvm.org/llvm.sh

From caad6c47848bf2a8da308d09eab3ad038922be1a Mon Sep 17 00:00:00 2001
From: Yuma Endo <endo@skipbit.jp>
Date: Fri, 31 Jul 2026 10:27:44 +0900
Subject: [PATCH 4/8] ci: raise the Clang lower bound to 18

Clang 17 cannot compile the C++23 std::expected declarations in path.h
against libstdc++. It only ever worked because the previous configuration
forced libc++, so the lower bound was never verified against the standard
library most Clang users on Linux get by default.

Try 18, the next version the ubuntu-24.04 image ships, to find the oldest
Clang that builds with either standard library.
---
 .github/workflows/linux.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml
index 0e6b5aa..df3c80d 100644
--- a/.github/workflows/linux.yml
+++ b/.github/workflows/linux.yml
@@ -52,7 +52,7 @@ jobs:
       matrix:
         build_type: [Debug, Release]
         toolchain:
-          - { os: ubuntu-24.04, clang: 17 }
+          - { os: ubuntu-24.04, clang: 18 }
           - { os: ubuntu-26.04, clang: 22 }
 
     steps:

From 5764a221953125ae1a568f859db4bef6ebff781f Mon Sep 17 00:00:00 2001
From: Yuma Endo <endo@skipbit.jp>
Date: Fri, 31 Jul 2026 10:30:48 +0900
Subject: [PATCH 5/8] ci: give Clang the libstdc++ 14 headers on ubuntu-24.04

GCC 13 builds fine, so libstdc++ 13 does provide std::expected; Clang just
cannot consume that release's <expected> in C++23 mode. The 14 series fixed
the interoperability, and ubuntu-24.04 ships it, so install those headers for
the Clang jobs and let Clang pick them up.
---
 .github/workflows/linux.yml | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml
index df3c80d..7e33efd 100644
--- a/.github/workflows/linux.yml
+++ b/.github/workflows/linux.yml
@@ -52,12 +52,21 @@ jobs:
       matrix:
         build_type: [Debug, Release]
         toolchain:
-          - { os: ubuntu-24.04, clang: 18 }
-          - { os: ubuntu-26.04, clang: 22 }
+          - { os: ubuntu-24.04, clang: 18, stdlib_pkg: libstdc++-14-dev }
+          - { os: ubuntu-26.04, clang: 22, stdlib_pkg: '' }
 
     steps:
     - uses: actions/checkout@v7
 
+    # Clang picks the newest libstdc++ headers it can find. The 13 series that
+    # ubuntu-24.04 defaults to cannot be consumed by Clang for C++23, so pull in
+    # the 14 headers there.
+    - name: Install standard library headers
+      if: matrix.toolchain.stdlib_pkg != ''
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y ${{ matrix.toolchain.stdlib_pkg }}
+
     - name: Report toolchain versions
       run: |
         clang-${{ matrix.toolchain.clang }} --version

From 33167b5c32c9f17790213ac596c2951802c022a4 Mon Sep 17 00:00:00 2001
From: Yuma Endo <endo@skipbit.jp>
Date: Fri, 31 Jul 2026 10:33:59 +0900
Subject: [PATCH 6/8] ci: move the Clang lower bound onto ubuntu-26.04

Installing the libstdc++ 14 headers changed nothing: Clang 18 on
ubuntu-24.04 still cannot see std::expected. Whichever way the exact cause
falls, a consumer building on that image would hit the same wall and would
have to work around it, so there is no Clang lower bound worth declaring
there.

Try Clang 20, the oldest the ubuntu-26.04 image ships, to find the oldest
one that builds against the default standard library without help.
---
 .github/workflows/linux.yml | 13 ++-----------
 1 file changed, 2 insertions(+), 11 deletions(-)

diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml
index 7e33efd..ccb4e3e 100644
--- a/.github/workflows/linux.yml
+++ b/.github/workflows/linux.yml
@@ -52,21 +52,12 @@ jobs:
       matrix:
         build_type: [Debug, Release]
         toolchain:
-          - { os: ubuntu-24.04, clang: 18, stdlib_pkg: libstdc++-14-dev }
-          - { os: ubuntu-26.04, clang: 22, stdlib_pkg: '' }
+          - { os: ubuntu-26.04, clang: 20 }
+          - { os: ubuntu-26.04, clang: 22 }
 
     steps:
     - uses: actions/checkout@v7
 
-    # Clang picks the newest libstdc++ headers it can find. The 13 series that
-    # ubuntu-24.04 defaults to cannot be consumed by Clang for C++23, so pull in
-    # the 14 headers there.
-    - name: Install standard library headers
-      if: matrix.toolchain.stdlib_pkg != ''
-      run: |
-        sudo apt-get update
-        sudo apt-get install -y ${{ matrix.toolchain.stdlib_pkg }}
-
     - name: Report toolchain versions
       run: |
         clang-${{ matrix.toolchain.clang }} --version

From 6a0cd9c722efd7221f2b2f9e90ea5b7aeaf6eb48 Mon Sep 17 00:00:00 2001
From: Yuma Endo <endo@skipbit.jp>
Date: Fri, 31 Jul 2026 10:37:01 +0900
Subject: [PATCH 7/8] ci: settle the Clang lower bound at 20 and state it in
 the requirements
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Clang 20 builds against the default standard library on ubuntu-26.04, so
that is the oldest Clang worth declaring. Record the range in the three
places that state the requirements, and explain in the getting started guide
why the Clang bound sits higher than the GCC one — otherwise the asymmetry
looks arbitrary.

Move the libc++ watch onto the same image and compiler as the new lower
bound, so the nightly run covers the standard library the required gates do
not, rather than a version the project no longer claims to support.
---
 .github/workflows/nightly.yml          | 13 ++++++++-----
 README.md                              |  2 +-
 docs/sphinx/source/contributing.rst    |  2 +-
 docs/sphinx/source/getting-started.rst |  8 +++++++-
 4 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml
index 6f5c670..811f001 100644
--- a/.github/workflows/nightly.yml
+++ b/.github/workflows/nightly.yml
@@ -98,9 +98,12 @@ jobs:
     - name: Test
       run: ./build/test/dross_test --gtest_color=yes
 
+  # The required gates build Clang against the default standard library.
+  # This covers the other choice, so neither ends up being the only one that
+  # works.
   libcxx:
     name: Clang with libc++
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-26.04
 
     steps:
     - uses: actions/checkout@v7
@@ -108,19 +111,19 @@ jobs:
     - name: Install libc++
       run: |
         sudo apt-get update
-        sudo apt-get install -y libc++-17-dev libc++abi-17-dev
+        sudo apt-get install -y libc++-20-dev libc++abi-20-dev
 
     - name: Report toolchain versions
       run: |
-        clang-17 --version
+        clang-20 --version
         cmake --version
 
     - name: Configure CMake
       run: |
         cmake -S . -B build \
           -DCMAKE_BUILD_TYPE=Release \
-          -DCMAKE_C_COMPILER=clang-17 \
-          -DCMAKE_CXX_COMPILER=clang++-17 \
+          -DCMAKE_C_COMPILER=clang-20 \
+          -DCMAKE_CXX_COMPILER=clang++-20 \
           -DCMAKE_CXX_FLAGS="-stdlib=libc++" \
           -DCMAKE_EXE_LINKER_FLAGS="-stdlib=libc++"
 
diff --git a/README.md b/README.md
index 6618ac4..19713f2 100644
--- a/README.md
+++ b/README.md
@@ -24,7 +24,7 @@
 ### Requirements
 
 - **C++23** compatible compiler, verified in CI as:
-  - Linux: GCC 13–15 or Clang 17–22
+  - Linux: GCC 13–15 or Clang 20–22
   - macOS: the Apple Clang shipped with macOS 15 or 26
   - Newer versions are best effort, exercised by the nightly toolchain watch
 - **CMake 3.20+**
diff --git a/docs/sphinx/source/contributing.rst b/docs/sphinx/source/contributing.rst
index 3cc54bf..c4c0fa9 100644
--- a/docs/sphinx/source/contributing.rst
+++ b/docs/sphinx/source/contributing.rst
@@ -33,7 +33,7 @@ Development Setup
 Build Requirements
 ~~~~~~~~~~~~~~~~~~
 
-- C++23 compatible compiler: on Linux, GCC 13-15 or Clang 17-22; on macOS,
+- C++23 compatible compiler: on Linux, GCC 13-15 or Clang 20-22; on macOS,
   the Apple Clang shipped with macOS 15 or 26. Newer versions are best effort.
 - CMake 3.20 or later
 - Git
diff --git a/docs/sphinx/source/getting-started.rst b/docs/sphinx/source/getting-started.rst
index d60f7cc..731e801 100644
--- a/docs/sphinx/source/getting-started.rst
+++ b/docs/sphinx/source/getting-started.rst
@@ -10,12 +10,18 @@ To build and use dross, you need:
 
 - **C++ Compiler**: Supporting C++23 standard
 
-  - On Linux: GCC 13 through 15, or Clang 17 through 22
+  - On Linux: GCC 13 through 15, or Clang 20 through 22
   - On macOS: the Apple Clang shipped with macOS 15 or 26
 
   Newer versions are best effort: they are exercised by the nightly toolchain
   watch rather than by the required build matrix.
 
+  The Clang lower bound is higher than the GCC one because older Clang
+  releases cannot compile this library's C++23 ``std::expected`` usage against
+  the libstdc++ they are paired with on Ubuntu 24.04, whether or not newer
+  libstdc++ headers are installed alongside. Either standard library works
+  from Clang 20 onwards, so neither is imposed.
+
 - **Build System**: CMake 3.20 or later
 - **Operating System**: Linux or macOS
 

From 19fbb483c3b596db1f953787ffca1e3f65ceeeb4 Mon Sep 17 00:00:00 2001
From: Yuma Endo <endo@skipbit.jp>
Date: Fri, 31 Jul 2026 10:41:36 +0900
Subject: [PATCH 8/8] ci: correct the header comment about where each lower
 bound sits
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The comment still claimed ubuntu-24.04 covers the lower bound, which stopped
being true for Clang. Spell out the asymmetry instead — it is exactly the
place a reader would look to understand why the two compilers start on
different images.
---
 .github/workflows/linux.yml | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml
index ccb4e3e..ad4f5f6 100644
--- a/.github/workflows/linux.yml
+++ b/.github/workflows/linux.yml
@@ -8,8 +8,11 @@ on:
 
 # Compilers come from the runner images only. Pinning the OS pins the compiler
 # set, which keeps an upstream repository change from breaking a required gate.
-# ubuntu-24.04 covers the lower bound of the supported range, ubuntu-26.04 the
-# newest versions we verify.
+#
+# The lower bounds do not line up across compilers. GCC is verified from 13 on
+# ubuntu-24.04, but Clang starts at 20 on ubuntu-26.04: older Clang releases
+# cannot build this library's C++23 usage against the libstdc++ they are paired
+# with on ubuntu-24.04. Both are verified up to what ubuntu-26.04 provides.
 
 jobs:
   build-ubuntu-gcc: