ci-linux-e2e.yml

name: ci-linux-e2e

# The e2e suite (tests/e2e/run_all.sh) on Linux, called by ci.yml beside
# ci-linux.yml after the Linux build. As many shards as ci.yml's plan gives
# (design 2026-11-12 §5.11; `mtest ci plan` over the measured history of main's
# stores, tests/e2e/mtest.toml [ci.plan]); the scripts are divided among them
# by that history (design 2026-11-08 W8; rule R4 of the 2026-10-02 CI record),
# each running the one binary build.yml produced (use-built-mcpp, rule R1).
# Each shard writes a per-test report that the e2e-coverage job of ci.yml reads
# (rule R5).
#
# Paired workflows: ci-linux.yml (unit + toolchain legs + integration),
# ci-macos.yml / ci-macos-e2e.yml, ci-windows.yml / ci-windows-e2e.yml.

on:
  workflow_call:
    inputs:
      set:
        description: the set of cases (`pr` or `full`; ci.yml's changes job)
        type: string
        default: full
      shards:
        description: the shards of this host (`mtest ci plan`), a JSON list
        type: string
        default: '[1,2,3]'
      count:
        description: how many shards the list holds
        type: string
        default: '3'
      work:
        description: whether the set gives this host any case
        type: boolean
        default: true

jobs:
  e2e:
    name: e2e ${{ matrix.shard }}/${{ inputs.count }} (linux x86_64, self-host)
    if: inputs.work
    runs-on: ubuntu-24.04
    timeout-minutes: 45
    strategy:
      fail-fast: false
      matrix:
        shard: ${{ fromJSON(inputs.shards) }}
    env:
      E2E_SHARD: ${{ matrix.shard }}/${{ inputs.count }}
      # By mtest (design 2026-11-08 W8; .github/actions/e2e-mtest): parts by
      # the measured history of main's stores, two tests at a time (measured on
      # one Linux shard: 220 s against 424 s one at a time, three no faster),
      # and on a pull request the tests its change affects.
      E2E_JOBS: '2'
      E2E_SET: ${{ inputs.set == 'pr' && 'pr' || '' }}
      E2E_REPORT: ${{ github.workspace }}/e2e-report-linux-${{ matrix.shard }}.tsv
      MCPP_HOME: /home/runner/.mcpp
      # NOTE: do NOT force MCPP_VERBOSE here. The e2e suite includes tests that
      # assert mcpp's DEFAULT (quiet) output — e.g. 48_build_error_output and
      # 53_namespaced_cache_label — which forced verbose would break. Verbose is
      # set only in the fresh-install workflows (cold bootstrap, no such asserts).
      # A specific test that needs verbose passes `--verbose` itself.
    steps:
      # `submodules: recursive` so tests/e2e/233_bench_matrix.sh can check that
      # each `hub`/`body` in bench/matrix.json exists in the tree it names.
      # Without the trees that check reads "submodule not initialised" and
      # reports nothing (#599). Under 10 MB of source; every shard carries it,
      # because which shard holds 233 follows from the timing table.
      - uses: actions/checkout@v4
        with:
          submodules: recursive

      - uses: ./.github/actions/bootstrap-mcpp

      - uses: ./.github/actions/use-built-mcpp
        with:
          host: linux-x86_64

      # Its own step and its own limit, so that downloads on a cold sandbox are
      # not taken from the suite's budget.
      - name: The toolchains the suite probes
        timeout-minutes: 15
        run: |
          set -euo pipefail
          # Pin the global default so test 28 (default-toolchain path) gets a
          # deterministic GNU answer instead of an auto-install pick. Installed
          # explicitly, not assumed: the restored sandbox is the build job's,
          # and a toolchain that only happens to be in it is a dependency on a
          # cache.
          "$MCPP" toolchain install gcc 16.1.0
          "$MCPP" toolchain default gcc@16.1.0
          # The toolchains whose capabilities the suite probes (run_all.sh):
          # musl, llvm (which also yields scan-deps and import-std-libcxx) and
          # the Linux-hosted MinGW cross compiler. Without them their tests
          # skip on every runner; measured 2026-10-01, seventeen such tests ran
          # nowhere. Warm runs re-install nothing.
          "$MCPP" toolchain install gcc 16.1.0-musl
          "$MCPP" toolchain install llvm 23.1.3
          "$MCPP" toolchain install mingw-cross 16.1.0
          XLINGS_HOME="$MCPP_HOME/registry" "$MCPP_VENDORED_XLINGS" install xim:nasm -y
          # The index payloads e2e 32, 33 and 40 link from this home into their
          # own (_inherit_toolchain.sh). Installed in a test home instead, they
          # are refused: the inherited subos projects assets that home's ledger
          # does not register. A warm sandbox used to hold them by accident.
          XLINGS_HOME="$MCPP_HOME/registry" "$MCPP_VENDORED_XLINGS" install \
              mcpplibs:cmdline@0.0.1 mcpplibs:cmdline@0.0.2 -y

      - uses: ./.github/actions/e2e-mtest
        with:
          host: linux

      - name: E2E suite
        # About twice the shard's budget of ten minutes (R4): reached only by a
        # hang. The per-test 600 s limit in run_all.sh names the test that hung.
        timeout-minutes: 22
        run: |
          set -euo pipefail
          # MCPP is this commit's binary and MCPP_BOOT the released bootstrap
          # (use-built-mcpp). e2e 252 needs the latter: the claim that an older
          # client can build against a package this commit produces is only
          # worth making against a real old binary.
          export MCPP MCPP_BOOT
          test -x "$MCPP_VENDORED_XLINGS"
          # GitHub-hosted runners are outside CN; keep CI toolchain downloads on
          # the global mirror while mcpp's default remains CN for fresh local
          # sandboxes. E2E tests with their own MCPP_HOME read this variable.
          export MCPP_E2E_TOOLCHAIN_MIRROR=GLOBAL
          "$MCPP" self config
          bash tests/e2e/run_all.sh

      # The shard's run as Markdown in the job's summary (mtest report).
      - name: The shard's report
        if: always()
        shell: bash
        run: |
          [ -n "${E2E_MTEST:-}" ] || exit 0
          (cd tests/e2e && "$E2E_MTEST" report --format md --group "$GITHUB_RUN_ID") >> "$GITHUB_STEP_SUMMARY" \
            || echo "::warning::no e2e run of this workflow run in the store"

      # The shard's store: main's are the history the next runs divide the suite by.
      - name: Upload the shard's store
        if: always()
        timeout-minutes: 5
        uses: actions/upload-artifact@v4
        with:
          name: e2e-store-linux-${{ matrix.shard }}
          path: tests/e2e/.mtest
          include-hidden-files: true
          if-no-files-found: ignore
          retention-days: 14

      # One file, no glob: the report the e2e-coverage job of ci.yml reads.
      - name: Upload the shard's report
        if: always()
        timeout-minutes: 5
        uses: actions/upload-artifact@v4
        with:
          name: e2e-report-linux-${{ matrix.shard }}
          path: e2e-report-linux-${{ matrix.shard }}.tsv
          if-no-files-found: warn
          retention-days: 7

  # An MCPP_HOME and a project on NFSv3 (docs/25 §6, #809): the filesystem
  # whose rename refuses RENAME_NOREPLACE with EINVAL, where `mcpp new` once
  # failed. mcpp measures what the filesystem does and publishes by it.
  nfs:
    name: e2e nfs (NFSv3 home and project)
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4

      - uses: ./.github/actions/bootstrap-mcpp

      - uses: ./.github/actions/use-built-mcpp
        with:
          host: linux-x86_64

      - name: An NFSv3 export of this machine, mounted
        run: |
          set -euo pipefail
          sudo apt-get update -q
          sudo apt-get install -y --no-install-recommends nfs-kernel-server nfs-common
          sudo mkdir -p /srv/nfs /mnt/nfs
          sudo chown "$(id -u):$(id -g)" /srv/nfs
          echo "/srv/nfs 127.0.0.1(rw,sync,no_subtree_check,no_root_squash)" | sudo tee /etc/exports
          sudo exportfs -ra
          sudo systemctl restart nfs-kernel-server
          sudo mount -t nfs -o vers=3,nolock 127.0.0.1:/srv/nfs /mnt/nfs
          test "$(stat -f -c %T /mnt/nfs)" = nfs

      - name: A toolchain, a new project, its build and run, all on NFSv3
        run: |
          set -euo pipefail
          export MCPP_HOME=/mnt/nfs/mcpp-home
          "$MCPP" toolchain install gcc 16.1.0
          cd /mnt/nfs
          "$MCPP" new hello
          cd hello
          "$MCPP" build
          "$MCPP" run > "$RUNNER_TEMP/run.log"
          grep -q 'Hello from hello' "$RUNNER_TEMP/run.log"

      - name: Doctor names the home's filesystem
        run: |
          set -euo pipefail
          export MCPP_HOME=/mnt/nfs/mcpp-home
          # doctor's exit status reports the machine's health, not this line.
          "$MCPP" self doctor > "$RUNNER_TEMP/doctor.log" 2>&1 || true
          grep -q '/mnt/nfs/mcpp-home on nfs' "$RUNNER_TEMP/doctor.log"

  # ──────────────────────────────────────────────────────────────────
  # Bare metal: the one chain the sharded suite above cannot be trusted
  # to exercise.
  #
  # tests/e2e/130_freestanding_riscv_build_and_run.sh declares
  # `# requires: qemu-riscv`, which is legitimately absent on the macOS and
  # Windows runners — so it must be a SOFT token, and a soft token means the
  # test skips in silence on a Linux runner that lost qemu too. That is the
  # exact shape this repository has been burned by twice (65_* never ran at
  # all; ten pack e2e skipped on two platforms), and no token can tell the two
  # cases apart.
  #
  # So the guard lives here, where it can be exact: install qemu, run the one
  # test, and assert its PASS line appeared. A skip fails this job.
  # ──────────────────────────────────────────────────────────────────
  baremetal:
    name: bare-metal e2e (riscv64-none-elf + cortex-m, qemu)
    runs-on: ubuntu-24.04
    timeout-minutes: 40
    env:
      MCPP_HOME: /home/runner/.mcpp
    steps:
      - uses: actions/checkout@v4
      - uses: ./.github/actions/bootstrap-mcpp

      - uses: ./.github/actions/use-built-mcpp
        with:
          host: linux-x86_64

      - name: Install the emulator (xim:qemu-riscv)
        run: |
          # BOTH homes. The shim on PATH dispatches against whichever home
          # owns it, and `mcpp run` runs the runner through that shim — so an
          # emulator installed only in the ambient xlings home answers
          # "xlings: 'qemu-system-riscv64' is not installed" when mcpp asks.
          # Measured: the job installed it once, the shim resolved, and the
          # run still failed.
          "$XLINGS_BIN" install xim:qemu-riscv -y
          XLINGS_HOME="${MCPP_HOME:-$HOME/.mcpp}/registry" \
            "$XLINGS_BIN" install xim:qemu-riscv -y
          # Assert it is reachable AND runnable BEFORE the tests. Without this
          # the capability probe simply would not add `qemu-riscv` and the
          # tests would skip — which is what this job exists to prevent.
          command -v qemu-system-riscv64
          qemu-system-riscv64 --version | head -1
          # The target sysroot, into the home MCPP uses. Test 131's BSP
          # declares it as an `[xlings] deps` entry and finds it through
          # `xpkg_dir`; installed into the ambient xlings home instead, the
          # test would SKIP and the seam would go unexercised.
          XLINGS_HOME="${MCPP_HOME:-$HOME/.mcpp}/registry" \
            "$XLINGS_BIN" install xim:picolibc-riscv -y
          test -d "${MCPP_HOME:-$HOME/.mcpp}/registry/data/xpkgs/xim-x-picolibc-riscv"
          # The M-profile emulator, in BOTH homes for the reason above.
          # `xim:qemu-arm` carries `qemu-system-arm` as well as
          # `qemu-system-aarch64`; test 332 addresses it by absolute path out of
          # the payload, so what matters is that the payload EXISTS in the home
          # mcpp uses rather than that a shim resolves.
          "$XLINGS_BIN" install xim:qemu-arm -y
          XLINGS_HOME="${MCPP_HOME:-$HOME/.mcpp}/registry" \
            "$XLINGS_BIN" install xim:qemu-arm -y
          # Reachable AND runnable before the tests, so that a missing emulator
          # fails this step rather than silently skipping test 332.
          ls "${MCPP_HOME:-$HOME/.mcpp}"/registry/data/xpkgs/xim-x-qemu-arm/*/bin/qemu-system-arm \
            | sort -V | tail -1 | xargs -I{} {} --version | head -1

      - name: Bare-metal e2e
        timeout-minutes: 25
        run: |
          export MCPP MCPP_VENDORED_XLINGS
          export MCPP_E2E_TOOLCHAIN_MIRROR=GLOBAL
          # llvm is the toolchain a freestanding target pins; install it
          # explicitly rather than relying on whatever the sandbox cache holds.
          "$MCPP" toolchain install llvm 23.1.3
          # Run the scripts DIRECTLY rather than through run_all.sh: they are
          # standalone (they take $MCPP and nothing else) and this job runs
          # seven of the suite. A script that does not apply exits 77
          # (tests/e2e/mtest.toml, skip_exit), so the status says which of the
          # three happened; a skip is a failure here for every script this
          # job exists to run, and is stated for the one whose base package
          # the job does not install (338, picolibc-arm).
          for t in tests/e2e/130_freestanding_riscv_build_and_run.sh \
                   tests/e2e/131_freestanding_bsp_supplies_everything.sh \
                   tests/e2e/132_freestanding_test_and_artifacts.sh \
                   tests/e2e/133_freestanding_std_subset.sh \
                   tests/e2e/332_cortex_m_builds_and_boots.sh \
                   tests/e2e/336_armv7a_builds_and_boots.sh \
                   tests/e2e/338_cortex_m_picolibc_sysroot.sh; do
            echo "=== $t ==="
            bash "$t" 2>&1 | tee "$(basename "$t").log"
            rc=${PIPESTATUS[0]}
            case "$rc:$t" in
              0:*) ;;
              77:*/338_*) echo "$t: skipped (exit 77)" ;;
              77:*) echo "$t skipped on the runner that must run it"; exit 1 ;;
              *) echo "$t failed (exit $rc)"; exit 1 ;;
            esac
          done
          # The assertion this job exists for: both tests RAN, by the line each
          # prints when it has.
          grep -q 'PASS: freestanding riscv64 build + run' \
            130_freestanding_riscv_build_and_run.sh.log || {
            echo "130 (engine chain) skipped on the runner that must run it"; exit 1; }
          grep -q 'PASS: BSP supplies the sysroot' \
            131_freestanding_bsp_supplies_everything.sh.log || {
            echo "131 (ecosystem chain) skipped on the runner that must run it"; exit 1; }
          grep -q 'PASS: bare-metal mcpp test names its failure' \
            132_freestanding_test_and_artifacts.sh.log || {
            echo "132 (test + artifacts) skipped on the runner that must run it"; exit 1; }
          grep -q 'PASS: the freestanding std subset' \
            133_freestanding_std_subset.sh.log || {
            echo "133 (std subset) skipped on the runner that must run it"; exit 1; }
          # 332 declares `# requires: qemu-arm`, which no sharded runner has
          # — so on the shards it exits 0 without running. This job is the only
          # place its PASS line can be demanded.
          grep -q 'PASS: cortex-m rows build, boot' \
            332_cortex_m_builds_and_boots.sh.log || {
            echo "332 (cortex-m) skipped on the runner that must run it"; exit 1; }
          # And a count, because four `grep -q` calls that each matched say
          # nothing about how many rows the script actually booted: a fixture
          # that stopped iterating would still print its PASS line.
          booted=$(grep -c 'booted on ' 332_cortex_m_builds_and_boots.sh.log || true)
          [ "$booted" = "4" ] || {
            echo "332 booted $booted rows, expected 4"; exit 1; }
          # 336 IS HERE FOR THE SAME REASON, AND ADDING IT TO THE LOOP ABOVE
          # WITHOUT ADDING IT HERE WOULD HAVE BEEN THE SAME DEFECT: it declares
          # `# requires: qemu-arm`, so on a shard it exits 0 having run nothing.
          grep -q 'PASS: armv7-a rows build, boot' \
            336_armv7a_builds_and_boots.sh.log || {
            echo "336 (armv7-a) skipped on the runner that must run it"; exit 1; }
          a32=$(grep -c 'booted on virt' 336_armv7a_builds_and_boots.sh.log || true)
          [ "$a32" = "2" ] || {
            echo "336 booted $a32 rows, expected 2"; exit 1; }
          # 338 SKIPS UNTIL `xim:picolibc-arm` IS PUBLISHED, and a skip here
          # is legitimate rather than a defect — the payload is a separate
          # release. So its PASS line is NOT demanded; what IS demanded is that
          # the script either passed or said why, which is what distinguishes a
          # skip from a silent zero-exit.
          grep -qE 'PASS: a Cortex-M project opts into picolibc|SKIP: picolibc-arm is not installed' \
            338_cortex_m_picolibc_sysroot.sh.log || {
            cat 338_cortex_m_picolibc_sysroot.sh.log
            echo "338 neither passed nor reported why it did not run"; exit 1; }

  # ──────────────────────────────────────────────────────────────────
  # Android: the rows no sharded runner can reach.
  #
  # `run_all.sh` adds the `android-ndk` capability only when the NDK payload
  # is already installed, and no other job installs it, so every
  # `# requires: android-ndk` test skipped on every CI runner while reporting
  # green. This job installs the payload, runs those tests directly and demands
  # each PASS line, then runs `mcpp test` on an API 34 emulator through
  # `adb-run` (the configuration measured on mcpp#635), which is the only
  # place a test program's loading on the device is observed.
  # ──────────────────────────────────────────────────────────────────
  android:
    name: android e2e (NDK rows + x86_64 emulator)
    runs-on: ubuntu-24.04
    timeout-minutes: 90
    env:
      MCPP_HOME: /home/runner/.mcpp
    steps:
      - uses: actions/checkout@v4
      - uses: ./.github/actions/bootstrap-mcpp

      - uses: ./.github/actions/use-built-mcpp
        with:
          host: linux-x86_64

      - name: Install the NDK (xim:android-ndk)
        timeout-minutes: 20
        run: |
          XLINGS_HOME="$MCPP_HOME/registry" "$XLINGS_BIN" install xim:android-ndk@30.0.16248370 -y
          # Present before the tests, so a missing payload fails this step
          # rather than an assertion deep inside a test.
          ls "$MCPP_HOME"/registry/data/xpkgs/xim-x-android-ndk/*/toolchains/llvm/prebuilt/*/bin/clang++

      - name: Android e2e (no device)
        timeout-minutes: 40
        run: |
          export MCPP MCPP_VENDORED_XLINGS
          export MCPP_E2E_TOOLCHAIN_MIRROR=GLOBAL
          "$MCPP" toolchain install gcc 16.1.0
          "$MCPP" toolchain default gcc@16.1.0
          # Run directly, not through run_all.sh, so a skip cannot pass as a
          # green: each script either prints its PASS line or this step fails.
          declare -A pass=(
            [652b_an_application_on_android_is_a_shared_library]='652b: kind = "app" on Android is a shared library OK'
            [664_a_universal_apk_is_two_legs_in_one_tree]='664: the universal APK is the library route applied to an app OK'
            [667_an_android_pack_stages_its_closure]='667: an Android pack stages its closure OK'
            [675_android_test_programs_carry_their_cxx_runtime]='PASS: 675_android_test_programs_carry_their_cxx_runtime'
            [680_a_dependency_floor_on_the_android_api_level]='PASS: 680_a_dependency_floor_on_the_android_api_level'
          )
          for t in "${!pass[@]}"; do
            echo "=== $t ==="
            bash "tests/e2e/$t.sh" 2>&1 | tee "$t.log"
            rc=${PIPESTATUS[0]}
            [ "$rc" = "0" ] || { echo "$t failed (exit $rc)"; exit 1; }
            grep -qF "${pass[$t]}" "$t.log" || { echo "$t did not print its PASS line"; exit 1; }
          done
          echo "MCPP=$MCPP" >> "$GITHUB_ENV"

      - name: Enable KVM
        run: |
          echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
          sudo udevadm control --reload-rules
          sudo udevadm trigger --name-match=kvm

      - name: Compile the device tests before the emulator starts
        timeout-minutes: 20
        run: bash .github/tools/android_emulator_test.sh prebuild "$RUNNER_TEMP/droidtest"

      - name: mcpp test on an API 34 emulator
        timeout-minutes: 30
        uses: reactivecircus/android-emulator-runner@v2
        with:
          api-level: 34
          arch: x86_64
          target: google_apis
          force-avd-creation: false
          emulator-options: -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none
          disable-animations: true
          script: bash .github/tools/android_emulator_test.sh run "$RUNNER_TEMP/droidtest"

  # ──────────────────────────────────────────────────────────────────
  # Hermetic (no host toolchain): the ONLY environment class that
  # faithfully reproduces issue #195. Standard runners ship gcc +
  # libc6-dev, so a sandbox toolchain that leaks to the host's CRT
  # still links "green" there; this container has no compiler and no
  # host Scrt1.o, so any leak fails loudly. Builds PR code with the
  # bootstrap mcpp, then runs the llvm flow end-to-end.
  # ──────────────────────────────────────────────────────────────────
  hermetic:
    name: hermetic e2e (no host toolchain, container)
    runs-on: ubuntu-24.04
    container: debian:stable-slim
    timeout-minutes: 60
    env:
      XLINGS_NON_INTERACTIVE: '1'
    steps:
      - name: Install base utilities (NO compiler)
        run: |
          apt-get update -qq
          apt-get install -y -qq curl ca-certificates git xz-utils unzip
          # The whole point of this job: no host toolchain, no host CRT.
          ! command -v gcc
          ! command -v cc
          test ! -e /usr/lib/x86_64-linux-gnu/Scrt1.o
          test ! -e /usr/lib/gcc

      - uses: actions/checkout@v4

      # Payload cache (downloads only — the container still has no host
      # toolchain, which is the property under test).
      - name: Restore mcpp sandbox payloads
        id: hermetic-cache
        uses: actions/cache/restore@v4
        with:
          path: ~/.mcpp
          key: mcpp-hermetic-${{ hashFiles('mcpp.toml', '.github/workflows/ci-linux-e2e.yml') }}
          restore-keys: |
            mcpp-hermetic-

      - name: Bootstrap xlings + released mcpp
        run: |
          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.26.1
          export PATH="$HOME/.xlings/subos/current/bin:$PATH"
          xlings update
          xlings install mcpp -y -g
          MCPP_BOOT="$HOME/.xlings/subos/current/bin/mcpp"
          "$MCPP_BOOT" --version
          "$MCPP_BOOT" self config --mirror GLOBAL
          # The restored ~/.mcpp holds the package index as it was when that
          # cache was saved; the commit builds against the index as published
          # (.github/tools/install_pinned_mcpp.sh says why a miss alone did not
          # refresh it before 2026.10.26.2).
          "$MCPP_BOOT" index update
          echo "MCPP_BOOT=$MCPP_BOOT" >> "$GITHUB_ENV"

      # This job builds its own mcpp on purpose: the build is part of what it
      # tests, a compiler-free container in which only sandbox payloads exist.
      - name: Build PR mcpp from source (sandbox gcc only)
        run: |
          MCPP=$(bash "$GITHUB_WORKSPACE/.github/tools/built_artifact.sh" "$MCPP_BOOT" mcpp)
          test -x "$MCPP"
          "$MCPP" --version
          echo "MCPP=$MCPP" >> "$GITHUB_ENV"

      - name: "issue #195 reproduction: manifest llvm toolchain, fresh"
        run: |
          cd "$(mktemp -d)"
          "$MCPP" new hello195
          cd hello195
          printf '\n[toolchain]\nlinux = "llvm@23.1.3"\n' >> mcpp.toml
          printf 'import std;\nint main() { std::println("hello {}", 195); return 0; }\n' > src/main.cpp
          "$MCPP" run

      - name: Hermetic llvm e2e subset
        run: |
          export PATH="$HOME/.xlings/subos/current/bin:$PATH"
          export MCPP
          bash tests/e2e/86_llvm_hermetic_link.sh
          bash tests/e2e/37_llvm_import_std.sh

      # The scripts whose C++ runtime is a package (`llvm.libcxx`) declare
      # `# requires: llvm`, which no shard has, and `run_all.sh` exits 0 when it
      # skips. They run here, where llvm is installed, and each is held to the
      # line it prints only when it ran to the end, and to the line of the step
      # that runs a program (#641).
      - name: "C++ runtime e2e that needs llvm (663, 690, 696, 700)"
        run: |
          set -o pipefail
          export PATH="$HOME/.xlings/subos/current/bin:$PATH"
          export MCPP
          run_and_assert() {   # $1 = script; the remaining arguments are lines it must print
            local script="$1"; shift
            local log="$RUNNER_TEMP/$(basename "$script").log"
            bash "$script" 2>&1 | tee "$log"
            for line in "$@"; do
              grep -qxF "$line" "$log" || { echo "::error::$script did not print: $line"; exit 1; }
            done
          }
          run_and_assert tests/e2e/663_a_graph_libcxx_over_the_payloads_c_library.sh \
            "ok: llvm.libcxx supplies the C++ layer over the payload's C library, and the program runs"
          run_and_assert tests/e2e/690_a_shared_library_over_a_graph_cxx_runtime.sh \
            'ok: linkage = "static" builds and runs' \
            'ok: cxx_runtime = { shared = "self-contained" } links a private copy and runs' \
            "PASS: 690 a shared library over a graph C++ runtime is refused or carries a stated private copy"
          run_and_assert tests/e2e/696_a_cxx_layer_provider_keeps_its_own_standard.sh \
            "PASS: a C++-layer provider compiles its implementation units at its own standard"
          # #646 F3a: the default llvm shape of a program over a C++ shared library
          # aborted with std::bad_cast before its programs took the library's contract.
          run_and_assert tests/e2e/700_a_program_over_a_cxx_shared_library_has_one_cxx_runtime.sh \
            "ok: a program over a C++ shared library runs on one C++ runtime" \
            "ok: a stated self-contained program over a coupled C++ shared library is refused" \
            "PASS: 700 a program over a C++ shared library has one C++ runtime"

      # The compile database (#699 report, design 2026-09-26 §3): the cases whose rows need llvm
      # (tests/e2e/cdb/toolchains.cpp, formerly e2e 783-786) require `llvm`, which no shard has, so
      # they run here. The bootstrap drives `mcpp test` so that the test build reuses the build of
      # the step above; the mcpp under test is that build's binary (MCPP_BIN_MCPP). Each case is
      # held to its `ok` line: a skip or a failure fails the step.
      - name: "Compile database e2e that needs llvm (e2e/cdb, suite toolchains)"
        run: |
          set -o pipefail
          export PATH="$HOME/.xlings/subos/current/bin:$PATH"
          log="$RUNNER_TEMP/cdb-toolchains.log"
          "$MCPP_BOOT" test e2e/cdb --case toolchains 2>&1 | tee "$log"
          for line in \
              "  ok   toolchains/783 cdb switches whole with the configuration" \
              "  ok   toolchains/784 cdb replays from its directory" \
              "  ok   toolchains/785 cdb interface flag module extensions" \
              "  ok   toolchains/786 std unit in the database and build id" \
              "4 passed, 0 failed, 0 skipped"; do
            grep -qxF "$line" "$log" || { echo "::error::e2e/cdb toolchains did not print: $line"; exit 1; }
          done

      # Last, so that the payloads the steps above installed are in it. This job
      # is the one writer of its cache, on main only (R3).
      - name: Save mcpp sandbox payloads
        if: ${{ github.event_name == 'push' && steps.hermetic-cache.outputs.cache-hit != 'true' }}
        uses: actions/cache/save@v4
        with:
          path: ~/.mcpp
          key: ${{ steps.hermetic-cache.outputs.cache-primary-key }}