ci.yml

name: ci

on:
  push:
    branches: [main]
  pull_request:
  workflow_dispatch:
    inputs:
      mcpp_source_ref:
        description: "A branch or tag of mcpp-community/mcpp to build and run in place of the release MCPP_VERSION names"
        required: false
        default: ""

env:
  # The mcpp release the consumers build with. Raising it is what admits a
  # member that relies on a newer engine; the README states each member's floor.
  # 2026.9.11.1 is what `dist-*` needs at the API level:
  # `mcpp::provides_pack_format`, `mcpp::pack_format`, `${mcpp.stage_dir}` and
  # `mcpp::package_version` all arrived in it. Raising this is what admits a
  # member relying on a newer engine; the README states each member's floor,
  # and the index descriptor's own `min_mcpp` is a different question -- it
  # bounds the DESCRIPTOR's syntax, and raising it would brick every older
  # client's whole index.
  #
  # 2026.9.11.2 IS WHAT `dist-apple` NEEDS TO BE REACHABLE AT ALL, and the red
  # lane was the dependency rather than a convention. Under 2026.9.11.1 the
  # macOS job failed with
  #
  #   error: cannot package the Mach-O program 'app-consumer' yet.
  #
  # because `mcpp pack` staged unconditionally before dispatching and let a
  # staging failure fail the command -- and its built-in closure walk uses
  # `LD_TRACE_LOADED_OBJECTS`, which dyld answers by RUNNING the program. So
  # every dispatched format was unreachable on macOS, including one that never
  # reads the staged tree. Staging is a service to the provider in 2026.9.11.2,
  # and `dist-apple` has been unreachable, not broken, since it was written.
  #
  # 2026.9.14.2 IS THE RELEASE THAT STAGES THE CLOSURES `dist-apk` AND
  # `dist-apple` READ (mcpp#634). It stages an Android application's native
  # libraries under `lib/` (`lib/<abi>/` for several targets) and a Mach-O
  # program's dylibs beside it, naming each in the stage manifest's `needs`
  # lines; it leaves an rpath that begins with `@executable_path` as written,
  # which `dist-apple`'s framework rpath needs; and it runs a distributable
  # through the runner named after its format, which is how `mcpp run --format
  # app` reaches `macapp-run`. An engine below it stages no `needs` lines, and
  # `dist-apk` refuses its tree naming this release.
  MCPP_VERSION: 2026.9.14.2
  # AN ENGINE BUILT FROM SOURCE, WHEN A DISPATCH NAMES ONE.
  #
  # Empty on every push and pull request, so the steps run the release above.
  # A dispatch that names a branch or tag of mcpp-community/mcpp through the
  # `mcpp_source_ref` input has `.github/scripts/mcpp-under-review.sh` build
  # that reference with the release above and point `$MCPP` at the result, in
  # each job that fetches mcpp, and the step after it checks that the steps run
  # what it built. This is how a change to the engine is measured against this
  # collection before either is released.
  MCPP_SOURCE_REF: ${{ inputs.mcpp_source_ref || '' }}
  # PINNED, AND WITHOUT IT THE CACHE BELOW CACHED NOTHING.
  #
  # A released mcpp is self-contained: with no `MCPP_HOME`, `mcpp self env`
  # reports the extracted tarball's own directory as its home, so every install
  # landed in `$GITHUB_WORKSPACE/mcpp-<ver>-linux-x86_64/` while the cache
  # saved and restored `~/.mcpp` -- a directory mcpp never touched. Every run
  # was therefore the cold case, which is what the 90-minute budget below was
  # sized for. mcpp's own ci-linux.yml pins it for this reason and says so.
  #
  # Set per JOB rather than here: the path differs by platform, and a
  # workflow-level `/home/runner/.mcpp` would silently be wrong on the other
  # two runners -- wrong in the direction that still appears to work, which is
  # the kind this repository has already paid for once.

jobs:
  consumers:
    name: consumers (linux x86_64)
    runs-on: ubuntu-24.04
    env:
      MCPP_HOME: /home/runner/.mcpp
    # 90 rather than 60: the SYCL fixture pulls three payloads this job did not
    # need before -- dpcpp (578 MB installed), gcc (265 MB) and cuda-nvcc
    # (319 MB) -- and a cold cache downloads all of them before the first
    # compile. The cache key includes the fixtures' manifests, so a run that
    # changes one of them is always the cold case.
    #
    # 150, which leaves room for the source build a dispatch naming
    # `mcpp_source_ref` adds ahead of every step.
    timeout-minutes: 150
    steps:
      - uses: actions/checkout@v4

      - name: Cache the mcpp sandbox
        uses: actions/cache@v4
        with:
          path: ~/.mcpp
          key: mcpp-sandbox-${{ runner.os }}-${{ runner.arch }}-${{ env.MCPP_VERSION }}-${{ hashFiles('tests/*/mcpp.toml') }}
          restore-keys: |
            mcpp-sandbox-${{ runner.os }}-${{ runner.arch }}-${{ env.MCPP_VERSION }}-

      - name: Fetch the released mcpp
        run: |
          curl -L -fsS --retry 3 --retry-all-errors -o mcpp.tar.gz \
            "https://github.com/mcpp-community/mcpp/releases/download/v${MCPP_VERSION}/mcpp-${MCPP_VERSION}-linux-x86_64.tar.gz"
          tar -xzf mcpp.tar.gz
          MCPP="$PWD/mcpp-${MCPP_VERSION}-linux-x86_64/bin/mcpp"
          "$MCPP" --version
          # THE BUNDLED xlings, NAMED EXPLICITLY BECAUSE `MCPP_HOME` IS PINNED.
          #
          # A released tarball carries its own xlings at `registry/bin/xlings`
          # and finds it there when its home IS that tarball. Pinning the home
          # elsewhere moves the place mcpp looks, so the first command fails
          # with `xlings binary not found` -- measured. The override is needed
          # only for that first call: mcpp copies the binary into the pinned
          # home and answers from there afterwards.
          export MCPP_VENDORED_XLINGS="$PWD/mcpp-${MCPP_VERSION}-linux-x86_64/registry/bin/xlings"
          "$MCPP" self config --mirror GLOBAL
          echo "MCPP=$MCPP" >> "$GITHUB_ENV"
          echo "MCPP_VENDORED_XLINGS=$MCPP_VENDORED_XLINGS" >> "$GITHUB_ENV"

      # THE ENGINE THE STEPS BELOW RUN: the release fetched above, or mcpp built
      # from `MCPP_SOURCE_REF` (see the workflow's `env`). A cold build of mcpp
      # is the longest step of the job, which is what its timeout is sized for.
      - name: the mcpp under review, built from MCPP_SOURCE_REF when it is set
        timeout-minutes: 45
        run: bash .github/scripts/mcpp-under-review.sh

      # THE CRITERION FOR THE STEP ABOVE, IN A LATER STEP, because what that step
      # writes to `GITHUB_ENV` governs only the steps after it.
      - name: the steps below run the mcpp under review
        if: env.MCPP_SOURCE_REF != ''
        timeout-minutes: 5
        run: |
          set -eu
          [ "$MCPP" = "$MCPP_UNDER_REVIEW" ] || {
            echo "::error::the steps run $MCPP, and the mcpp built from $MCPP_SOURCE_REF is $MCPP_UNDER_REVIEW"; exit 1; }
          version=$("$MCPP" --version | head -1)
          [ "$version" = "$MCPP_UNDER_REVIEW_VERSION" ] || {
            echo "::error::$MCPP prints '$version', and the build printed '$MCPP_UNDER_REVIEW_VERSION'"; exit 1; }
          # A reading, not a criterion: the two engines' versions, which may be
          # equal when the reference has not moved the version yet, so the
          # criterion above is the path and not the version.
          echo "READING released: $("$MCPP_RELEASED" --version | head -1); under review: $version"
          echo "ok: the steps run $version, built from $MCPP_SOURCE_REF"

      # The rule's output is a header holding the SPIR-V module; the program
      # checks the magic number in its first word, so no Vulkan runtime is
      # needed and what is tested is the rule and the engine path feeding it.
      # ONE PACKAGE, ONE VERSION. `mcpp::plugins::version` was `0.1.1` while the
      # package was `0.2.6`, and nothing noticed because nothing read it. Every
      # rule now states it with `mcpp::fact`, and this compares the two
      # spellings so a stale constant is a red build rather than a wrong entry
      # in every consumer's log.
      - name: the collection states its own version
        run: |
          declared=$(sed -n 's/^version *= *"\(.*\)".*/\1/p' mcpp.toml | head -1)
          insource=$(sed -n 's/.*version *= *"\(.*\)";.*/\1/p' src/plugins.cppm | head -1)
          echo "mcpp.toml=$declared  src/plugins.cppm=$insource"
          if [ "$declared" != "$insource" ]; then
            echo "FAIL: mcpp.toml says '$declared' and src/plugins.cppm says '$insource'"
            exit 1
          fi
          echo "ok: one version, two files agreeing"

      # ONE DERIVATION, AND THE CHECK THAT KEEPS IT ONE.
      #
      # `common_base_dir` and `namespace_of` were written in `rules/spirv.cppm`
      # and written again in `rules/slang.cppm`, and `mcpp.tools.island` is the
      # third caller. They live in the lib root now, which is what makes the
      # island fixture's cross-platform run protect the SHADER lane too: the
      # separator defect fixed in 0.5.2 was in this function, and the shader
      # lane had it as well -- its Windows fixture keeps every payload in one
      # directory, so a namespace segment was never derived there.
      #
      # A copy reintroduced in a rule would silently take that protection away,
      # so the absence of a second definition is asserted rather than assumed.
      - name: the path-to-namespace derivation exists once
        run: |
          n=$(grep -c '^inline std::vector<std::string> namespace_of' rules/*.cppm tools/*.cppm | awk -F: '{s+=$2} END {print s+0}')
          m=$(grep -c '^inline std::string common_base_dir' rules/*.cppm tools/*.cppm | awk -F: '{s+=$2} END {print s+0}')
          [ "$n" = 0 ] && [ "$m" = 0 ] || {
            echo "FAIL: a rule or tool defines its own copy of the derivation"
            grep -n '^inline std::vector<std::string> namespace_of\|^inline std::string common_base_dir' rules/*.cppm tools/*.cppm
            exit 1; }
          grep -q '^inline std::vector<std::string> namespace_of' src/plugins.cppm
          grep -q '^inline std::string common_base_dir' src/plugins.cppm
          echo "ok: one definition, in the lib root, for both lanes"

      - name: rules-spirv through a consumer
        working-directory: tests/spirv-consumer
        run: |
          "$MCPP" build
          "$MCPP" run | tee run.log
          grep -q '^magic=07230203' run.log

      # THE MODULE SURFACE, AND THE COLLISION IT DISSOLVES.
      #
      # This fixture has `shaders/a/scale.comp` and `shaders/b/scale.comp` --
      # one stem, two directories -- which the step below this one asserts is
      # REFUSED when the two would produce one output. They no longer do: the
      # directory is part of the namespace, the generated file's path and the
      # array's name, so both are built and reached as `shaders::a::scale_comp`
      # and `shaders::b::scale_comp`.
      #
      # The program asserts the two arrays are DISTINCT OBJECTS, not only that
      # both carry the SPIR-V magic number. Without that assertion this fixture
      # passed while both accessors returned one array: the two generated data
      # headers were byte-identical, and GCC's `#pragma once` treats two files
      # with the same size and content as the same file, so the second include
      # silently did nothing.
      - name: rules-spirv through the module surface
        working-directory: tests/spirv-module-consumer
        run: |
          "$MCPP" build
          "$MCPP" run | tee run.log
          grep -q '^a/scale.comp: magic=07230203' run.log
          grep -q '^b/scale.comp: magic=07230203' run.log
          grep -q '^default/scale.comp: magic=07230203' run.log
          grep -q '^all ok' run.log
          # A DIRECTORY NAMED AFTER A C++ KEYWORD. `a` and `b` are ordinary
          # identifiers and cannot tell a name filter that knows the keywords
          # from one that does not; without the guard this is
          # `namespace default {` and the generated file does not parse.
          grep -q '^namespace default_ {' \
            target/.build-mcpp/out/spirv/shader_app.shaders.cppm \
            || { echo "FAIL: the keyword directory did not get its trailing underscore"
                 grep -n namespace target/.build-mcpp/out/spirv/shader_app.shaders.cppm
                 exit 1; }
          # The point of the surface: a consumer names no generated file.
          if grep -rn 'scale_comp\.h\|\.inc"' src/; then
            echo "FAIL: a consumer source names a generated file"
            exit 1
          fi
          echo "ok: the consumer names only the module"
          # And what it imports really is a generated module interface.
          #
          # `shader_app`, while this directory is `spirv-module-consumer`. The
          # module root is derived from `[package] name`, and the two are
          # deliberately different here: a derivation that fell back to the
          # manifest directory's leaf -- which is what this rule did before mcpp
          # 2026.9.7.1 gave build programs `mcpp::package_name()` -- would write
          # `spirv_module_consumer.shaders.cppm` and this test would find no file.
          iface=target/.build-mcpp/out/spirv/shader_app.shaders.cppm
          test -f "$iface" || {
            echo "FAIL: no module interface at $iface"
            find target/.build-mcpp/out/spirv -name '*.cppm' -print
            exit 1; }
          grep -q '^export module shader_app.shaders;' "$iface"
          # The interface must name no standard-library type: one that does
          # carries that header's templates in every consumer's BMI, measured at
          # 727 times the size of the std-free form.
          if grep -n 'std::\|#include <' "$iface"; then
            echo "FAIL: the generated module interface names a standard-library type"
            exit 1
          fi
          echo "ok: the generated interface is std-free"

      # THE SECOND COMPILER, THROUGH THE SAME FIXTURE. glslang and glslc share
      # almost no flags -- glslc's `-mfmt=c` is a bare initialiser list where
      # glslang's `-x --vn` is a complete declaration, and glslc's `-S` means
      # "emit assembly" where glslang's names a stage -- so the rule writes the
      # declaration itself on this route. The program is unchanged, which is the
      # assertion: one source, two compilers, one answer.
      - name: rules-spirv through glslc
        working-directory: tests/spirv-consumer
        run: |
          curl -L -fsS --retry 3 --retry-all-errors -o shaderc.tar.gz \
            "https://github.com/xlings-res/shaderc/releases/download/2026.3/shaderc-2026.3-linux-x86_64.tar.gz"
          tar -xzf shaderc.tar.gz
          rm -rf target
          MCPP_GLSLC="$PWD/shaderc-2026.3/bin/glslc" "$MCPP" build
          test -f target/.build-mcpp/out/spirv/scale_comp.inc
          MCPP_GLSLC="$PWD/shaderc-2026.3/bin/glslc" "$MCPP" run | tee run-glslc.log
          grep -q '^magic=07230203' run-glslc.log
          rm -rf shaderc.tar.gz shaderc-2026.3

      # TWO SHADERS THAT DIFFER ONLY BY DIRECTORY.
      #
      # They used to produce one output -- the name was the stem and the stage,
      # so `a/x.vert` and `b/x.vert` both gave `x_vert.h` declaring
      # `x_vert_spv` -- and the rule refused, because ninja's duplicate-output
      # error named the generated file and neither shader.
      #
      # THE COLLISION IS GONE, and this step asserts what replaced it. The
      # shader's directory is part of the generated file's path and of the
      # array's name, so the two are two things. That change was not made for
      # ergonomics: two byte-identical generated headers collapse under GCC's
      # `#pragma once`, which treats two files of the same size and content as
      # the same file, so the second include silently did nothing and both
      # accessors returned one array.
      #
      # The rule's refusal stays, and its condition is now two shaders with one
      # name in ONE directory. A single glob cannot construct that; an explicit
      # `options::base_dir` can.
      - name: two shaders with one stem are two payloads, not one
        working-directory: tests/spirv-consumer
        run: |
          set -e
          mkdir -p shaders/dup
          cp shaders/scale.comp shaders/dup/scale.comp
          # The fixture globs `shaders/*.comp`; widen it for this step only.
          cp mcpp.toml mcpp.toml.bak
          sed -i 's#shaders/\*.comp#shaders/**/*.comp#' mcpp.toml
          rm -rf target
          "$MCPP" build > dup.log 2>&1 || {
            echo "FAIL: two shaders differing only by directory were refused"
            tail -20 dup.log; mv mcpp.toml.bak mcpp.toml; rm -rf shaders/dup; exit 1; }
          # TWO declarations, and the directory is in the second one's name.
          # A build that collapsed them would also produce a working binary, so
          # the criterion is the generated names rather than the run.
          d=target/.build-mcpp/out/spirv
          find "$d" -name '*.h' | sort | sed 's/^/  /'
          grep -rq 'scale_comp_spv' "$d" || {
            echo "FAIL: the top-level shader lost its declaration"; exit 1; }
          grep -rq 'dup_scale_comp_spv' "$d" || {
            echo "FAIL: the shader in dup/ did not take its directory into its name"
            grep -rho '[a-z_]*scale_comp_spv' "$d" | sort -u
            exit 1; }
          echo "ok: two directories sharing a stem are two payloads"
          # …and the fixture still builds with one shader per stem, so this step
          # cannot leave a project that refuses everything.
          mv mcpp.toml.bak mcpp.toml
          rm -rf shaders/dup target
          "$MCPP" build > restored.log 2>&1 || {
            echo "FAIL: the fixture no longer builds after the duplicate was removed"
            tail -20 restored.log; exit 1; }
          rm -f dup.log restored.log
          echo "ok: and it builds again with one shader per stem"

      # THE OTHER GENERATED INTERFACE, AND THE ONE THAT IS NOT A PAYLOAD.
      #
      # `mcpp.tools.island` generates the boundary a device island is reached
      # across: the `extern "C"` header its compiler includes, and the module the
      # C++ side imports. The entry points are declared once, so the copy that
      # can drift is gone -- and at a C-linkage boundary that copy is the worst
      # one available, because nothing mangles and two disagreeing declarations
      # link cleanly.
      #
      # The island here is a `.c` rather than a `.cu`: the generator does not
      # know what compiler produced the object, and a fixture needing a vendor
      # toolkit could only run where that toolkit is published.
      #
      # THE FIXTURE'S SHAPE IS ITSELF A CRITERION. `src/kernels` is the layout
      # root and holds a subdirectory; `src/cpu` implements the same two entry
      # points in ONE FLAT FILE. A generator that derived a namespace from every
      # root would give `island_scale` two of them, and one that required the
      # trees to have equal shapes would refuse this layout outright.
      - name: island interfaces are generated, namespaced, and not written
        working-directory: tests/island-interface
        run: |
          "$MCPP" build
          "$MCPP" run | tee run.log
          grep -q '^out\[0\]=6 out\[1\]=12 out\[2\]=18 out\[3\]=24' run.log
          grep -q '^all ok' run.log
          # Neither artefact is written by hand.
          test ! -f include/island_interface.kernels.h
          d=target/.build-mcpp/out/island
          grep -q 'extern "C" {' "$d/island_interface.kernels.h"
          # THE MODULE NAME AND THE NAMESPACE ARE ONE IDENTIFIER PATH, which is
          # the rule docs/42 states for both lanes and the one this generator
          # did not follow before 0.5.0: it put every entry point at global
          # scope, so `import app.kernels` bought a file name and nothing else.
          grep -q '^export namespace island_interface::kernels {' \
            "$d/island_interface.kernels.cppm"
          # A directory below the layout root extends it. `image/scale.c` is
          # what puts this block in the file, and a generator that ignored
          # directories would still pass every other check here.
          grep -q '^export namespace island_interface::kernels::image {' \
            "$d/island_interface.kernels.cppm"
          grep -q '^using ::island_saxpy;' "$d/island_interface.kernels.cppm"
          grep -q '^using ::island_scale;'  "$d/island_interface.kernels.cppm"
          # TWO, not four. Both roots implement the same two entry points, and a
          # merge that appended instead would declare each one twice -- which
          # the module rejects as a redefinition and the header silently
          # accepts, so the count catches it in both surfaces.
          n=$(grep -c '^using ::' "$d/island_interface.kernels.cppm")
          [ "$n" = 2 ] || { echo "FAIL: the module re-exports $n names; the two roots declare 2"
                            cat "$d/island_interface.kernels.cppm"; exit 1; }
          # THE SHORT NAME, AND THE ONE IT IS A SPELLING OF. An island's symbol
          # is global to the whole program, so an entry point carries a prefix
          # the namespace then repeats. Both spellings are emitted and the
          # authored one stays canonical.
          grep -q '^inline constexpr auto saxpy = island_saxpy;' \
            "$d/island_interface.kernels.cppm"
          grep -q '^inline constexpr auto scale = island_scale;' \
            "$d/island_interface.kernels.cppm"
          # THE HEADER IS FLAT. It is read by a C compiler, which has no
          # namespace to read, and by no other means could the device half
          # compile against it.
          if grep -q 'namespace' "$d/island_interface.kernels.h"; then
            echo "FAIL: the generated header carries a namespace"
            grep -n namespace "$d/island_interface.kernels.h"; exit 1
          fi
          # The module re-exports NAMES: a second copy of a signature is the
          # thing this generator exists to remove, so its appearance here is a
          # regression even though it would compile.
          if grep -q 'int island_saxpy(' "$d/island_interface.kernels.cppm"; then
            echo "FAIL: the module restated a signature instead of re-exporting a name"
            exit 1
          fi
          # NEITHER SIDE INCLUDES ANYTHING. The C++ side imports, and the
          # island reads the generated header through the compiler's
          # forced-include flag -- so a project using this generator has no
          # header in its source tree and no line naming one.
          if grep -rn '#include' src/main.cpp src/app.cppm src/kernels/saxpy.c \
               src/kernels/image/scale.c src/cpu/ops.c; then
            echo "FAIL: a source names an include; the generator exists to remove it"
            exit 1
          fi
          # THE SEAM IS A MODULE OF THIS PROJECT IMPORTING THE GENERATED ONE.
          # `main.cpp` is not a module unit, so its import said nothing about
          # ordering two module interfaces where one is written during the
          # build. `src/app.cppm` is, and it is the shape every example under
          # examples/09-heterogeneous has.
          grep -q '^import island_interface.kernels;' src/app.cppm \
            || { echo "FAIL: the seam no longer imports the generated module"; exit 1; }
          # CODE, NOT TEXT. `src/main.cpp` explains in a comment that it names
          # no boundary symbol, and a plain grep matches that sentence -- the
          # criterion then reports the file for saying what it does. Comment
          # lines are stripped first, which is the difference between asking
          # "does this file mention the name" and "does this file use it".
          if sed 's://.*::' src/main.cpp | grep -q 'island_saxpy\|island_scale'; then
            echo "FAIL: the consumer names a boundary symbol; the seam exists to hide it"
            sed 's://.*::' src/main.cpp | grep -n 'island_saxpy\|island_scale'
            exit 1
          fi
          # THE MECHANISM, NOT THE WORD. `grep 'include'` matched this build
          # program's own comments and its `mcpp::include_dir` line, so it
          # would have passed with the forced include removed -- a criterion
          # that cannot fail is not one.
          grep -v '^[[:space:]]*//' build.mcpp | grep -q 'force_include_flags' \
            || { echo "FAIL: the build program no longer forces the header in"; exit 1; }
          # THE MARKER SELECTS, AND THE UNMARKED MUST NOT TRAVEL. The island has
          # a static helper and an unmarked external function; a scan that
          # exported whatever the file contained would still pass every check
          # above, because both generated files would merely be larger.
          for name in internal_device unexported_helper host_only_helper; do
            if grep -q "$name" "$d/island_interface.kernels.h" \
            || grep -q "$name" "$d/island_interface.kernels.cppm"; then
              echo "FAIL: $name is not marked and reached the generated boundary"
              exit 1
            fi
          done
          # The marker is defined by the header, so the island needs no other
          # arrangement to compile.
          grep -q '^#define MCPP_EXPORT_C$' "$d/island_interface.kernels.h"
          # A signature that wrapped across lines survived: the scan matches
          # parentheses rather than reading lines.
          grep -q 'int island_scale(float a, float\* out, unsigned n);' \
            "$d/island_interface.kernels.h"
          echo "ok: one declaration, two generated artefacts, and only what was marked"

      # ONE ENTITY, TWO SPELLINGS, AND NO SECOND SYMBOL.
      #
      # The short name is a `constexpr` function pointer, so it costs the
      # artifact nothing and `nm` shows the authored name alone. A generator
      # that emitted a forwarding FUNCTION instead would pass every check above
      # and put a second symbol in every artifact.
      - name: the short name is a spelling, not a second function
        working-directory: tests/island-interface
        run: |
          bin=$(find target -name island-interface -type f | head -1)
          test -n "$bin" || { echo "FAIL: no artifact"; exit 1; }
          n=$(nm "$bin" | grep -c ' island_saxpy$')
          [ "$n" = 1 ] || { echo "FAIL: $n definitions of island_saxpy"; exit 1; }
          if nm "$bin" | grep -qE ' (T|t|W) saxpy$'; then
            echo "FAIL: the short name became a symbol of its own"
            nm "$bin" | grep -E ' saxpy$'; exit 1
          fi
          echo "ok: one symbol for the pair"

      # THE SEAM'S OTHER HALF, AND THE NAME THAT DOES NOT MOVE WITH IT.
      #
      # A seam has two implementations of one `extern "C"` boundary -- a device
      # island and a host fallback -- and exactly one of them is in any link.
      # `build.mcpp` names both roots unconditionally, because both exist on
      # disk in either build and the manifest decides which is compiled.
      #
      # The criterion is stronger than "the CPU leg builds": the generated
      # module must be BYTE-IDENTICAL to the device leg's. The consumer's
      # qualified name is what would otherwise differ between two builds of one
      # project, and it is the failure a namespace derived from every root
      # produces.
      - name: the same boundary and the same names, from the half the build selected
        working-directory: tests/island-interface
        run: |
          d=target/.build-mcpp/out/island
          cp "$d/island_interface.kernels.cppm" /tmp/device-leg.cppm
          rm -rf target
          "$MCPP" build --no-accel > cpu.log 2>&1 || {
            echo "FAIL: the CPU leg does not build"; tail -25 cpu.log; exit 1; }
          "$MCPP" run --no-accel | tee cpurun.log
          grep -q '^out\[0\]=6 out\[1\]=12 out\[2\]=18 out\[3\]=24' cpurun.log
          grep -q '^all ok' cpurun.log
          diff /tmp/device-leg.cppm "$d/island_interface.kernels.cppm" || {
            echo "FAIL: the qualified names differ between the two legs"; exit 1; }
          echo "ok: the CPU leg reaches the same qualified names"

      # THE SHAPE COMES FROM ONE STATED ROOT.
      #
      # Moving the flat fallback under a directory of its own must rename
      # nothing. The rejected alternative -- take the DEEPEST directory among an
      # entry point's implementations -- passes every other check in this file
      # and fails this one: `src/cpu/deep/ops.c` would put both entry points in
      # `::deep`, so a refactor of a tree nobody consumes would rename what
      # every consumer writes.
      - name: reorganising a root that does not supply the shape renames nothing
        working-directory: tests/island-interface
        run: |
          d=target/.build-mcpp/out/island
          cp "$d/island_interface.kernels.cppm" /tmp/before-move.cppm
          mkdir -p src/cpu/deep && mv src/cpu/ops.c src/cpu/deep/ops.c
          rm -rf target
          "$MCPP" build --no-accel > moved.log 2>&1 || {
            echo "FAIL: the build broke when a fallback moved"; tail -20 moved.log
            mv src/cpu/deep/ops.c src/cpu/ops.c; rmdir src/cpu/deep; exit 1; }
          rc=0
          diff /tmp/before-move.cppm "$d/island_interface.kernels.cppm" || rc=1
          mv src/cpu/deep/ops.c src/cpu/ops.c; rmdir src/cpu/deep
          [ "$rc" = 0 ] || { echo "FAIL: a non-layout root changed a consumer's names"; exit 1; }
          rm -f moved.log
          echo "ok: the layout root alone decides where an entry point lives"

      # ADDING A FILE HAS TO RE-RUN THE GENERATOR.
      #
      # Declared inputs are hashed CONTENTS, so a new file changes none of them
      # and a program that registered only the files it read would never see the
      # new entry point -- the consumer's failure would be an unresolved name in
      # a module that silently did not grow. The glob's fingerprint is the
      # sorted set of matching paths, which is the question being asked.
      - name: a new island file reaches the boundary with nothing else touched
        working-directory: tests/island-interface
        run: |
          d=target/.build-mcpp/out/island
          rm -rf target && "$MCPP" build > base.log 2>&1
          before=$(grep -c '^using ::' "$d/island_interface.kernels.cppm")
          mkdir -p src/kernels/audio
          printf 'MCPP_EXPORT_C\nint island_fft(float* out, unsigned n) { (void)out; (void)n; return 0; }\n' \
            > src/kernels/audio/fft.c
          "$MCPP" build > added.log 2>&1 || {
            echo "FAIL: the build broke after a file was added"; tail -20 added.log
            rm -rf src/kernels/audio; exit 1; }
          rc=0
          grep -q '^export namespace island_interface::kernels::audio {' \
            "$d/island_interface.kernels.cppm" || rc=1
          after=$(grep -c '^using ::' "$d/island_interface.kernels.cppm")
          rm -rf src/kernels/audio base.log added.log
          [ "$rc" = 0 ] && [ "$after" = $((before + 1)) ] || {
            echo "FAIL: adding a file left the boundary at $before entry points"; exit 1; }
          echo "ok: the glob makes which files are here an input"

      # ONE NAME TWICE IN ONE ROOT IS A COLLISION, NOT A SEAM.
      #
      # C language linkage does not mangle, so two entry points with one name
      # are one symbol whatever namespace each appears in -- measured: two
      # modules re-exporting one name into two namespaces give `&a::f == &b::f`.
      # A namespace is a lookup alias over a flat symbol, and this refusal is
      # what keeps it from promising an isolation the linker does not provide.
      - name: two files in one root declaring one name are refused
        working-directory: tests/island-interface
        run: |
          printf 'MCPP_EXPORT_C\nint island_saxpy(float a, const float* x, const float* y, float* out, unsigned n) {\n  (void)a; (void)x; (void)y; (void)out; (void)n; return 1;\n}\n' \
            > src/kernels/dup.c
          rm -rf target
          set +e
          "$MCPP" build > dup.log 2>&1
          rc=$?
          set -e
          rm -f src/kernels/dup.c
          [ "$rc" != 0 ] || { echo "FAIL: the collision was accepted"; tail -20 dup.log; exit 1; }
          grep -q 'is declared twice in the root' dup.log || {
            echo "FAIL: refused, but not for this reason"; tail -20 dup.log; exit 1; }
          # Both file names, and the way out: a diagnostic that only says "no"
          # leaves the reader to guess that two roots are how a seam is spelled.
          grep -q 'src/kernels/dup.c' dup.log
          grep -q 'src/kernels/saxpy.c' dup.log
          grep -q 'in two roots' dup.log
          rm -f dup.log
          echo "ok: refused, naming both files and the arrangement that is not a collision"

      # A SHORT NAME IS A SECOND SPELLING OF ONE ENTRY POINT, NOT A SHARED ONE.
      #
      # Stripping a prefix can land on a name that is already taken. The
      # generated module would then declare one name twice, and the error would
      # name a generated file rather than the two entry points that produced it.
      - name: a short name that collides with an authored one is refused
        working-directory: tests/island-interface
        run: |
          printf 'MCPP_EXPORT_C\nint saxpy(float a, float* out, unsigned n) { (void)a; (void)out; (void)n; return 1; }\n' \
            > src/kernels/collide.c
          rm -rf target
          set +e
          "$MCPP" build > collide.log 2>&1
          rc=$?
          set -e
          rm -f src/kernels/collide.c
          [ "$rc" != 0 ] || { echo "FAIL: the short-name collision was accepted"
                              tail -20 collide.log; exit 1; }
          grep -q 'both reach' collide.log || {
            echo "FAIL: refused, but not for this reason"; tail -20 collide.log; exit 1; }
          rm -f collide.log
          echo "ok: refused, naming both entry points and the prefix"

      # OVERLAPPING ROOTS ARE REFUSED.
      #
      # A file reachable from two roots has two namespace paths, and which one
      # it got would depend on the order of the list. It would also be read
      # twice and merged with itself, so the entry would look like two
      # implementations agreeing -- a misconfiguration that produces a
      # plausible result rather than stopping.
      - name: overlapping roots are refused
        working-directory: tests/island-interface
        run: |
          cp build.mcpp /tmp/build.mcpp.overlap.bak
          sed -i 's|opt.roots       = { root + "/src/kernels", root + "/src/cpu" };|opt.roots       = { root + "/src/kernels", root + "/src/cpu", root + "/src" };|' \
            build.mcpp
          grep -q 'root + "/src" };' build.mcpp || {
            echo "FAIL: the fixture was not perturbed; this step would assert nothing"
            cp /tmp/build.mcpp.overlap.bak build.mcpp; exit 1; }
          rm -rf target
          set +e
          "$MCPP" build > overlap.log 2>&1
          rc=$?
          set -e
          cp /tmp/build.mcpp.overlap.bak build.mcpp
          [ "$rc" != 0 ] || { echo "FAIL: overlapping roots were accepted"
                              tail -20 overlap.log; exit 1; }
          grep -q 'overlap' overlap.log || {
            echo "FAIL: refused, but not for this reason"; tail -20 overlap.log; exit 1; }
          rm -f overlap.log
          echo "ok: refused, naming both roots"

      # A ROOT THAT YIELDS NOTHING IS AN ERROR, NOT AN EMPTY MODULE.
      #
      # A misspelled root or a marker that never arrived would otherwise produce
      # a module exporting nothing, and the failure would surface as an
      # unresolved name in a consumer three files away.
      - name: roots holding no marker are refused, naming the roots
        working-directory: tests/island-interface
        run: |
          cp build.mcpp /tmp/build.mcpp.bak
          sed -i 's|opt.produced_by = "the island-interface fixture";|&\n    opt.marker = "MCPP_NOT_THE_MARKER";|' build.mcpp
          grep -q 'MCPP_NOT_THE_MARKER' build.mcpp || {
            echo "FAIL: the fixture was not perturbed; this step would assert nothing"
            cp /tmp/build.mcpp.bak build.mcpp; exit 1; }
          rm -rf target
          set +e
          "$MCPP" build > empty.log 2>&1
          rc=$?
          set -e
          cp /tmp/build.mcpp.bak build.mcpp
          [ "$rc" != 0 ] || { echo "FAIL: an empty scan was accepted"; tail -20 empty.log; exit 1; }
          grep -q 'no entry point marked' empty.log || {
            echo "FAIL: refused, but not for this reason"; tail -20 empty.log; exit 1; }
          grep -q 'src/kernels' empty.log
          rm -f empty.log
          echo "ok: refused, naming the marker and the roots"

      # AND THE REVERSE LEG, WHICH IS THE POINT OF READING EVERY ROOT.
      #
      # C language linkage does not mangle and two implementations are never in
      # one link, so two declarations of one name that disagree produce a clean
      # build and an artifact that reads its arguments by whichever signature it
      # happened to be compiled with. `scan` is the only place both texts exist
      # at once, so it is the only place that can refuse.
      - name: two implementations that disagree are refused where both texts exist
        working-directory: tests/island-interface
        run: |
          cp src/cpu/ops.c /tmp/cpu_ops.bak
          sed -i 's/^int island_scale(float a, float\* out, unsigned n) {/int island_scale(float a, float* out, double n) {/' \
            src/cpu/ops.c
          grep -q 'double n' src/cpu/ops.c || {
            echo "FAIL: the fixture was not perturbed; this step would assert nothing"
            cp /tmp/cpu_ops.bak src/cpu/ops.c; exit 1; }
          rm -rf target
          set +e
          "$MCPP" build > neg.log 2>&1
          rc=$?
          set -e
          cp /tmp/cpu_ops.bak src/cpu/ops.c
          [ "$rc" != 0 ] || { echo "FAIL: the disagreement was accepted"; tail -20 neg.log; exit 1; }
          grep -q 'declare it differently' neg.log || {
            echo "FAIL: refused, but not for this reason"; tail -20 neg.log; exit 1; }
          # Both file names, because a diagnostic naming one leaves the reader
          # to find the other.
          grep -q 'src/kernels/image/scale.c' neg.log
          grep -q 'src/cpu/ops.c' neg.log
          echo "ok: refused, naming both definitions and both signatures"
          # And it builds again once they agree, so this step cannot leave a
          # fixture that refuses everything.
          rm -rf target
          "$MCPP" build > restored.log 2>&1 || {
            echo "FAIL: the fixture no longer builds after the perturbation was undone"
            tail -20 restored.log; exit 1; }
          rm -f neg.log restored.log cpu.log cpurun.log
          echo "ok: and it builds again once the two agree"

      # NO BUILD PROGRAM AT ALL, WHICH IS WHAT THE TWO KEYS BUY.
      #
      # `spirv-consumer` and `spirv-module-consumer` both write a `build.mcpp`,
      # so neither can tell whether mcpp would have written it. This fixture has
      # a dependency edge naming a feature and nothing else: no `host-module`,
      # no build program. The step asserts both absences, because a fixture that
      # gained one by accident would still pass every other check here.
      - name: rules-spirv with no build program
        working-directory: tests/spirv-zero-config
        run: |
          test ! -f build.mcpp || { echo "FAIL: the fixture has its own build program"; exit 1; }
          # STRIPPED OF COMMENTS, for the same reason the island step is: this
          # fixture EXPLAINS in its own header that `host-module = true` is not
          # written and not needed, so a plain grep reports the file for saying
          # what it does. The property is about the manifest's keys.
          if grep -v '^[[:space:]]*#' mcpp.toml | grep -q 'host-module'; then
            echo "FAIL: the fixture declares host-module"
            grep -v '^[[:space:]]*#' mcpp.toml | grep -n 'host-module'
            exit 1
          fi
          "$MCPP" build | tee build.log
          grep -q 'Rules mcpp.rules.spirv' build.log \
            || { echo "FAIL: the build did not report which rule it ran"; exit 1; }
          "$MCPP" run | tee run.log
          grep -q '^magic=07230203' run.log
          grep -q '^all ok' run.log
          # And the program mcpp wrote is where it says it is, and is the one a
          # project would take over.
          test -f target/.build-mcpp/build.mcpp
          grep -q '^import mcpp.rules.spirv;' target/.build-mcpp/build.mcpp
          echo "ok: one edge, no program, shaders compiled"

      # WHERE THE BYTES LIVE, TWICE, AGAINST ONE UNCHANGED CONSUMER.
      #
      # Both fixtures' `src/main.cpp` has the same shape as the header-stored
      # one: one import, one call, a `payload` struct. That is the claim -- the
      # storage is not something a consumer can see -- and it is why these are
      # separate fixtures rather than options on an existing one.
      #
      # `object` is what a project reaches for above roughly 1 MB of total
      # payload; below that the header route is faster, measured at 1.10s
      # against 2.17s for 100 shaders of 16 KB.
      - name: rules-spirv with object storage
        working-directory: tests/spirv-object-storage
        run: |
          "$MCPP" build
          "$MCPP" run | tee run.log
          grep -q '^magic=07230203' run.log
          grep -q '^all ok' run.log
          # The bytes are a section, so the compiler never saw a C array: the
          # payload is a bare `.spv` and an `.S` names it with `.incbin`.
          test -f target/.build-mcpp/out/spirv/scale_comp.spv
          test -f target/.build-mcpp/out/spirv/spirv_object_storage.shaders.payload.S
          grep -q '\.incbin' target/.build-mcpp/out/spirv/spirv_object_storage.shaders.payload.S
          if ls target/.build-mcpp/out/spirv/*.inc >/dev/null 2>&1; then
            echo "FAIL: object storage still produced a C initialiser list"
            exit 1
          fi
          # `pCode` wants four-byte alignment and a section directive alone does
          # not promise it.
          grep -q '\.balign 4' target/.build-mcpp/out/spirv/spirv_object_storage.shaders.payload.S
          echo "ok: the payload is a section, not generated source"

      - name: rules-spirv with sidecar storage
        working-directory: tests/spirv-sidecar
        run: |
          "$MCPP" build
          "$MCPP" run | tee run.log
          grep -q '^magic=07230203' run.log
          grep -q '^all ok' run.log
          test -f target/.build-mcpp/out/spirv/scale_comp.spv
          # THE REVERSE LEG, AND IT IS THE POINT OF THIS STORAGE. The accessor
          # opens a path relative to the working directory, so the program finds
          # its shaders from the package root and must not from anywhere else.
          # Without this half the fixture would pass against an implementation
          # that had quietly embedded the payload after all.
          bin=$(ls target/*/*/bin/spirv-sidecar)
          bin=$(cd "$(dirname "$bin")" && pwd)/$(basename "$bin")
          if (cd /tmp && "$bin" > away.log 2>&1); then
            echo "FAIL: the sidecar program succeeded from the wrong directory"
            cat /tmp/away.log
            exit 1
          fi
          grep -q 'sidecar payload was not found' /tmp/away.log \
            || { echo "FAIL: it failed for some other reason"; cat /tmp/away.log; exit 1; }
          echo "ok: found from the package root, reported missing from elsewhere"

      # AN EDITED SHADER REACHES THE ARTIFACT, UNDER EVERY STORAGE.
      #
      # The three storage steps above assert STRUCTURE: the `.S` names the
      # payload, the section is aligned, no C initialiser was written. All three
      # passed against 0.3.0, in which object storage served a STALE artifact --
      # the shader recompiled, the object did not, and the program reported the
      # previous payload's byte count with a green build. Structure cannot see
      # that. Only editing a shader and reading what comes out can.
      #
      # THE DENOMINATOR IS THE POINT. Header storage was already correct, so a
      # run where only `object` fails names the mechanism, and a run where all
      # three fail names the harness -- a distinction one fixture cannot make.
      #
      # The edit adds a statement guarded by a value the host never passes, so
      # the compiled module must grow while the program's output stays
      # comparable.
      - name: an edited shader reaches the artifact under every storage
        run: |
          set -u
          fail=0
          for fx in spirv-module-consumer:header spirv-object-storage:object spirv-sidecar:sidecar; do
            dir=${fx%%:*}; store=${fx##*:}
            cd "$GITHUB_WORKSPACE/tests/$dir"
            shader=$(find shaders -name '*.comp' | sort | head -1)
            cp "$shader" /tmp/shader.bak
            # `|| { ...; continue; }` and not a bare command: a `run:` block
            # runs under `bash -e`, so a bare failing build would end the STEP
            # here and the other two storages would never run -- losing the
            # denominator this check is built around.
            "$MCPP" build > /dev/null \
              || { echo "FAIL[$store]: build"; fail=1; cp /tmp/shader.bak "$shader"; continue; }
            before=$("$MCPP" run 2>&1 | sed -n 's/.*bytes=\([0-9]*\).*/\1/p' | awk '{s+=$1} END {print s+0}')
            sed -i 's|void main() {|void main() {\n    if (push.n == 0xdeadu) { v[0] = 1.0; v[1] = 2.0; v[2] = 3.0; }|' "$shader"
            "$MCPP" build > /dev/null \
              || { echo "FAIL[$store]: rebuild"; fail=1; cp /tmp/shader.bak "$shader"; continue; }
            after=$("$MCPP" run 2>&1 | sed -n 's/.*bytes=\([0-9]*\).*/\1/p' | awk '{s+=$1} END {print s+0}')
            cp /tmp/shader.bak "$shader"
            if [ -z "$before" ] || [ -z "$after" ]; then
              echo "FAIL[$store]: no byte count printed (before='$before' after='$after')"
              fail=1
            elif [ "$before" = "$after" ]; then
              echo "FAIL[$store]: the shader changed and the artifact did not (bytes=$before both times)"
              fail=1
            else
              echo "ok[$store]: $before -> $after"
            fi
          done
          [ "$fail" -eq 0 ] || exit 1

      # AN EDITED `#include` REACHES THE ARTIFACT.
      #
      # The step above edits the shader itself, which every rule declares as an
      # action input. This edits a file the shader INCLUDES, which no rule
      # declares: `a.input()` is fixed when build.mcpp runs, before the compiler
      # has read a line, so the only channel is the depfile the compiler writes
      # afterwards. `grep depfile rules/` returned nothing across all six rules
      # until 0.3.1, and editing an included `.glsl` rebuilt nothing.
      #
      # ON THE HEADER-STORAGE FIXTURE, AND THAT IS NOT ARBITRARY. Run against
      # `spirv-object-storage` this step tests two mechanisms at once: measured,
      # it fails when EITHER the depfile or the `.incbin` declaration is absent,
      # so a red run would not say which. Header storage compiles the payload in
      # as generated source, where the compile edge is dirty for the ordinary
      # reason, and what remains under test is the depfile alone.
      #
      # Both shader compilers were measured writing one that names the include:
      #   glslangValidator --depfile   ->  out.spv: scale.comp ./common.glsl
      #   glslc -MD -MF                ->  out2.spv: scale.comp common.glsl
      - name: an edited include reaches the artifact
        working-directory: tests/spirv-module-consumer
        run: |
          set -u
          shader=shaders/default/scale.comp
          inc=shaders/default/common.glsl
          cp "$shader" /tmp/scale.bak
          printf 'const float kBias = 0.0;\n' > "$inc"
          sed -i 's|#version 450|#version 450\n#extension GL_GOOGLE_include_directive : require\n#include "common.glsl"|' "$shader"
          sed -i 's|+ v\[push.n + i\];|+ v[push.n + i] + kBias;|' "$shader"
          "$MCPP" build > /dev/null
          before=$("$MCPP" run 2>&1 | sed -n 's/.*bytes=\([0-9]*\).*/\1/p' | awk '{s+=$1} END {print s+0}')
          # ONLY THE INCLUDED FILE CHANGES NOW. Nothing any rule declared as an
          # input is touched, so a rebuild happens only if the depfile said so.
          printf 'const float kBias = 1.0;\nconst float kPad0 = 2.0;\nconst float kPad1 = 3.0;\n' > "$inc"
          "$MCPP" build > /dev/null
          after=$("$MCPP" run 2>&1 | sed -n 's/.*bytes=\([0-9]*\).*/\1/p' | awk '{s+=$1} END {print s+0}')
          cp /tmp/scale.bak "$shader"
          rm -f "$inc"
          if [ -z "$before" ] || [ -z "$after" ]; then
            echo "FAIL: no byte count printed (before='$before' after='$after')"
            exit 1
          fi
          if [ "$before" = "$after" ]; then
            echo "FAIL: the included file changed and the artifact did not (bytes=$before both times)"
            exit 1
          fi
          echo "ok: an included file reaches the artifact ($before -> $after)"

      # OBJECT STORAGE WITHOUT THE TOOL IS REFUSED, AND THE REFUSAL SAYS WHAT
      # TO ADD.
      #
      # `tools = [...]` is default-off: nothing is built unless a consumer asks,
      # which is what keeps the DEFAULT storage free of a tool build. The cost
      # is that a project can ask for object storage and not for the tool, and
      # what it gets then is a message -- so the message is a contract. Asserted
      # on the three strings a reader needs: that the tool is what is missing,
      # the key that supplies it, and the storage that needs none.
      - name: object storage without the tool is refused, naming the fix
        run: |
          set -u
          W="$GITHUB_WORKSPACE/tests/spirv-object-storage"
          cp "$W/mcpp.toml" /tmp/objstore.toml
          # Remove only the tools request, leaving everything else in place.
          sed -i 's/, tools = \["mcpp-embed"\]//' "$W/mcpp.toml"
          cd "$W"
          rm -rf target
          if "$MCPP" build > refusal.log 2>&1; then
            cp /tmp/objstore.toml mcpp.toml
            echo "FAIL: object storage built with no way to generate its assembly"
            exit 1
          fi
          cp /tmp/objstore.toml mcpp.toml
          fail=0
          grep -q 'mcpp-embed' refusal.log || { echo "FAIL: the refusal does not name the tool"; fail=1; }
          grep -q 'tools = ' refusal.log   || { echo "FAIL: the refusal does not name the key that supplies it"; fail=1; }
          grep -q 'storage::header' refusal.log || { echo "FAIL: the refusal does not name the way out"; fail=1; }
          if [ "$fail" -ne 0 ]; then cat refusal.log; exit 1; fi
          rm -f refusal.log
          echo "ok: refused, naming the tool, the key and the alternative"

      # EVERY RULE PASSES A DEPFILE, AND THE DENOMINATOR IS THE RULE COUNT.
      #
      # The step above proves the channel works for the one lane CI can run.
      # The other four compile for accelerators no runner has, so what can be
      # asserted about them is that each one declares the field -- read from the
      # code rather than from a list written here, so a seventh rule is counted
      # the day it is added and not the day someone remembers this step.
      - name: every rule declares a depfile
        run: |
          set -u
          cd "$GITHUB_WORKSPACE"
          rules=$(ls rules/*.cppm | wc -l)
          withdep=$(grep -l 'depfile' rules/*.cppm | wc -l)
          echo "rules with a depfile: $withdep of $rules"
          if [ "$withdep" -ne "$rules" ]; then
            echo "FAIL: these rules pass no depfile:"
            for f in rules/*.cppm; do
              grep -q 'depfile' "$f" || echo "  $f"
            done
            exit 1
          fi

      # SLANG: A DIFFERENT LANGUAGE, THE SAME SURFACE.
      #
      # The point of this step is not that Slang compiles -- it is that a
      # consumer cannot tell which rule produced its shaders. The fixture's
      # `main.cpp` contains nothing Slang-specific and would compile unchanged
      # against `mcpp.rules.spirv` if the shader were GLSL.
      #
      # It needs an engine that knows the `.slang` extension: a constrained
      # glob's `accel` key does not make a file a device source, the engine's
      # own `kDeviceExtensions` table does, and before that table listed
      # `.slang` the file fell through to the ordinary source scan and was
      # refused with "mcpp has no role for the extension".
      - name: rules-slang through a consumer
        working-directory: tests/slang-consumer
        run: |
          "$MCPP" build
          "$MCPP" run | tee run.log
          # TWO SHADERS, AND THE ENTRY POINT'S NAME IS THE MEASUREMENT.
          #
          # `-fvk-use-entrypoint-name` reaches slangc through
          # `options::extra_args` and makes the module carry the function's
          # name instead of `main`; `-DOFFSET_ENTRY` reaches ONE shader through
          # `options::per_file` and switches its name again. The consumer reads
          # both names out of the SPIR-V bytes, and `scale.slang` would report
          # `wrongMain` if the per-file macro had leaked to it.
          grep -q '^scale.slang: magic=07230203 .* entry=computeMain ok' run.log
          grep -q '^offset.slang: magic=07230203 .* entry=offsetMainDefined ok' run.log
          grep -q '^all ok' run.log
          if grep -rn 'scale\.h\|\.inc"' src/; then
            echo "FAIL: a consumer source names a generated file"
            exit 1
          fi
          grep -q '^export module slang_consumer.shaders;' \
            target/.build-mcpp/out/slang/slang_consumer.shaders.cppm
          echo "ok: a Slang shader reached through the same surface as a GLSL one"

      # THE NEGATIVE LEG. A `per_file` key that names no shader must refuse the
      # build and list what it could have named; a rule that applied nothing
      # and built anyway would hand the project a module it believes carries
      # the option. Without this half the table could silently become a no-op
      # and every positive assertion above would still pass.
      - name: rules-slang refuses a per_file key that names no shader
        working-directory: tests/slang-consumer
        run: |
          cp build.mcpp /tmp/build.mcpp.bak
          sed -i 's|shaders/offset.slang|shaders/offest.slang|' build.mcpp
          if "$MCPP" build > refused.log 2>&1; then
            cp /tmp/build.mcpp.bak build.mcpp
            echo "FAIL: a mistyped per_file key built anyway"; cat refused.log; exit 1
          fi
          cp /tmp/build.mcpp.bak build.mcpp
          grep -q 'per_file. names .shaders/offest.slang., and no shader' refused.log
          grep -q '^    shaders/offset.slang' refused.log
          echo "ok: refused by name, and the shaders it could have named were listed"

      # THE THIRD STORAGE, FOR SLANG. `options::storage` is new in 0.7.0; before
      # it the rule embedded unconditionally. The consumer's source is the one
      # `slang-consumer` has minus the per-file assertions, and the reverse leg
      # is the point of the storage, as `spirv-sidecar` records.
      - name: rules-slang with sidecar storage
        working-directory: tests/slang-sidecar
        run: |
          "$MCPP" build
          "$MCPP" run | tee run.log
          grep -q '^magic=07230203' run.log
          grep -q '^all ok' run.log
          test -f target/.build-mcpp/out/slang/scale.spv
          if grep -q 'source-embed' target/*/*/build.ninja; then
            echo "FAIL: sidecar storage still asked slangc to embed"; exit 1
          fi
          bin=$(ls target/*/*/bin/slang-sidecar)
          bin=$(cd "$(dirname "$bin")" && pwd)/$(basename "$bin")
          if (cd /tmp && "$bin" > away.log 2>&1); then
            echo "FAIL: the sidecar program succeeded from the wrong directory"
            cat /tmp/away.log
            exit 1
          fi
          grep -q 'sidecar payload was not found' /tmp/away.log \
            || { echo "FAIL: it failed for some other reason"; cat /tmp/away.log; exit 1; }
          echo "ok: a Slang payload found from the package root, reported missing from elsewhere"

      # A tool, not a rule: the header is written while the build program runs,
      # so there is no action to schedule. The second build is the measurement
      # that matters -- editing the data file must reach the binary, which is
      # the fast-path comparison mcpp 2026.9.5.4 added and the reason this job
      # pins that version.
      - name: tools-embed through a consumer
        working-directory: tests/embed-consumer
        run: |
          "$MCPP" run | tee run.log
          grep -q '^size=33 sum=3189 text=mcpp.tools.embed fixture payload' run.log
          printf 'changed\n' > data/message.txt
          "$MCPP" run | tee run2.log
          grep -q '^size=8 ' run2.log
          git checkout -- data/message.txt

      # THE SAME SURFACE FROM A TOOL RATHER THAN A RULE.
      #
      # `file()` writes a header per input and the consumer includes each by
      # name; `group()` hands the same headers to the same generator the shader
      # rules use, so a set of data files and a set of shaders reach a consumer
      # through one shape.
      #
      # The size assertion is the one that matters. `<id>_size` counts ELEMENTS
      # and the surface reports BYTES, and `null_terminate` appends a byte that
      # `_size` does not count -- so neither `_size` nor `sizeof` is the answer
      # on its own. The fixture compares the payload against its exact text, and
      # a trailing NUL fails it.
      - name: tools-embed through the module surface
        working-directory: tests/embed-module-consumer
        run: |
          "$MCPP" build
          "$MCPP" run | tee run.log
          grep -q '^alpha.txt: bytes=46 ok' run.log
          grep -q '^beta.txt: bytes=15 ok' run.log
          grep -q '^all ok' run.log
          if grep -rn 'alpha_txt\.h\|beta_txt\.h' src/; then
            echo "FAIL: a consumer source names a generated file"
            exit 1
          fi
          echo "ok: two payloads, one import, sizes exact"

      # N INPUTS, ONE HEADER, ONE TABLE -- the shape `file()` and `files()`
      # cannot express, taken from a shader set whose consumer iterates rather
      # than naming each entry.
      #
      # The fixture's own build program runs three more `table()` calls than
      # the consumer needs, and the build only reaches "Finished" because all
      # of them behave: a duplicate key is refused naming BOTH inputs, the
      # same collision is resolved by `key_kind::relative_path`, and a
      # non-multiple-of-4 input under `element::word32` is refused naming the
      # file. Each was checked by fault injection while it was written -- the
      # refusal was disabled and the probe caught it -- so these are not
      # assertions that pass by never running.
      - name: tools-embed table() through a consumer
        working-directory: tests/embed-table-consumer
        run: |
          "$MCPP" build
          "$MCPP" run | tee run.log
          grep -q '^row 0: key=Standard.vert size=20' run.log
          grep -q '^row 1: key=Standard.frag size=22' run.log
          grep -q '^all ok' run.log
          # EVERY GENERATED HEADER, NOT WHICHEVER `find` LISTED FIRST. This
          # fixture writes three -- the real table plus probes that exercise
          # `key_kind::relative_path` and `element::word32` -- and `head -1`
          # picked one by directory order, so the check was asserting about a
          # file nothing chose.
          mapfile -t headers < <(find target/.build-mcpp/out -name '*.h' | sort)
          [ "${#headers[@]}" -gt 0 ] || { echo "FAIL: no generated header"; exit 1; }
          echo "checking ${#headers[@]} generated header(s)"
          for h in "${headers[@]}"; do
            # The bytes are a numeric array and never a raw string literal: a
            # raw literal cannot carry arbitrary binary, and its delimiter is
            # terminable by the input. The CMake code this shape replaces used
            # string concatenation and has exactly that defect.
            if grep -q 'R"' "$h"; then
              echo "FAIL: $h emitted a raw string literal"; exit 1
            fi
            # SELF-CONTAINED, ASSERTED AS A PROPERTY AND NOT AS A NAME. The
            # row type is declared beside the array, so the header compiles on
            # its own. The first version grepped for `struct embedded_file`,
            # which is the DEFAULT `row_type` -- and this fixture sets
            # `row_type = "shader_entry"` precisely because that option
            # exists. So the assertion failed with the code correct, which is
            # what a check tied to a spelling the fixture chooses will
            # eventually always do.
            #
            # What is wanted: the header declares a struct, and the table's
            # element type IS that struct. Both read out of the file.
            row=$(sed -n 's/^struct \([A-Za-z_][A-Za-z0-9_]*\) {.*/\1/p' "$h" | head -1)
            test -n "$row" \
              || { echo "FAIL: $h declares no row struct"; head -30 "$h"; exit 1; }
            grep -q "constexpr $row .*\[\] = {" "$h" \
              || { echo "FAIL: $h's element type is not the struct it declares ($row)"
                   head -40 "$h"; exit 1; }
            echo "  ok: $(basename $h) declares '$row' and its table is an array of it"
          done
          echo "ok: N inputs, one header, one table"

      # ── dist: what comes out of the LINK ────────────────────────────────
      #
      # Every step above asserts what reaches a COMPILE. These assert what
      # comes out of the link, which is a different pass of the engine: the
      # build program runs a SECOND time, after `mcpp pack` has staged the
      # closure, and submits an artifact action whose input is a directory that
      # did not exist during the build.
      - name: dist-appimage produces an AppImage, and it runs
        working-directory: tests/appimage-consumer
        run: |
          # A PLAIN BUILD HAS NO DISTRIBUTION EDGE. The member declares the
          # format unconditionally and submits only when asked, so this build
          # must produce no AppImage at all -- the half of the contract a
          # member author is most likely to get wrong, and the half that still
          # works for whoever wrote it.
          "$MCPP" build
          if find target -name '*.AppImage' | grep -q .; then
            echo "FAIL: a plain build produced a distributable"; exit 1
          fi
          # AND YET THE FORMAT IS KNOWN, which is what the unconditional
          # declaration buys: the engine can name what is available on a build
          # that asked for nothing.
          set +e
          so=$("$MCPP" pack --format bogus 2>/dev/null); rc=$?
          se=$("$MCPP" pack --format bogus 2>&1 >/dev/null)
          set -e
          [ "$rc" = 2 ] || { echo "FAIL: --format bogus exited $rc, expected 2"; exit 1; }
          [ -z "$so" ] || { echo "FAIL: the refusal wrote to stdout"; exit 1; }
          grep -q 'available in this build: tar, dir, appimage' <<<"$se" \
            || { echo "FAIL: the refusal does not name appimage"; echo "$se"; exit 1; }

          "$MCPP" pack --format appimage | tee pack.log
          img=$(find target -name '*.AppImage' | head -1)
          test -n "$img" || { cat pack.log; echo "FAIL: no AppImage"; exit 1; }
          # THE CRITERION IS THAT IT RUNS AND PRINTS, not that a file exists.
          # A packaging step that succeeds while carrying nothing is the
          # measured failure this whole category exists to prevent, and a valid
          # empty image satisfies every check that stops at the file.
          #
          # `--appimage-extract-and-run` because a runner has no FUSE: measured
          # with `fusermount` off the PATH, the plain invocation exits 127 with
          # "No suitable fusermount binary found on the $PATH".
          chmod +x "$img"
          APPIMAGE_EXTRACT_AND_RUN=1 "$img" | tee run.log
          grep -q '^appimage-consumer ok' run.log \
            || { echo "FAIL: the AppImage did not run the program"; exit 1; }
          # No network was reached to build it. appimagetool downloads its
          # type-2 runtime stub on every invocation unless `--runtime-file`
          # names a local copy, and `xim:appimagetool` carves one out of
          # itself for exactly this reason.
          if grep -qi 'downloading runtime' pack.log; then
            echo "FAIL: the build fetched a runtime stub over the network"; exit 1
          fi
          echo "ok: one AppImage, and it printed the program's output"

      # THE iOS ROW OF `dist-apple`, AT THE PLAN LEVEL (#622 B1). No runner
      # in this workflow has an Apple SDK, so `--target aarch64-ios-sim`
      # refuses before `build.mcpp` even runs -- see
      # `tests/ios-app-consumer/mcpp.toml`'s own header for the measured
      # refusal and the reasoning. What this step CAN check on this runner:
      # the compiled build program's actual behaviour under the exact
      # environment contract `--target aarch64-ios-sim --format app` and the
      # device row would set, run directly rather than through mcpp.
      - name: dist-apple's iOS row, checked at the plan level
        working-directory: tests/ios-app-consumer
        run: MCPP="$MCPP" ./check-ios-plan.sh

      # dist-apple's framework directory, signature, runner and disk image, as
      # planned for the macOS and iOS rows (mcpp#634, B1 to B3). The same
      # fixture is built, signed, run and imaged on the macOS runner.
      - name: dist-apple's framework, signature, runner and disk image, checked at the plan level
        timeout-minutes: 15
        working-directory: tests/app-framework-consumer
        run: MCPP="$MCPP" ./check-apple-plan.sh

      # dist-wix's `setup` format, as planned for a Windows target (mcpp#634,
      # B4): the bundle follows the MSI, both generated documents are
      # well-formed XML, and `setup.exe` is refused. The bundle itself is built
      # on the Windows runner.
      - name: dist-wix's MSI and Burn bundle, checked at the plan level
        timeout-minutes: 15
        working-directory: tests/msi-consumer
        run: MCPP="$MCPP" ./check-wix-plan.sh

      # dist-web (#622 B3), end to end, the real `mcpp pack --format web
      # --target wasm32-emscripten` -- see `tests/web-consumer/
      # check-web-plan.sh`'s own header for the host-toolchain defect this
      # needed fixed first (mcpp commit 23974c5e, #622 e2e 657) and the
      # MCPP_VERSION this step therefore needs at least. Since 0.9.0 the same
      # pin is also the floor for `${mcpp.self}` and `mcpp stage`'s argument
      # shape as an engine contract (design record
      # `2026-09-13-four-upstream-asks-from-a-ui-framework.md`, §4), which
      # `dist-web`'s two copy steps now use in place of `cp`. `mcpp toolchain
      # install` first, because this job's `~/.mcpp` cache does not carry
      # the emsdk payload the way the local sandbox this member was
      # developed against does.
      - name: Install the emsdk payload for dist-web
        run: '"$MCPP" toolchain install emsdk 6.0.9'

      - name: dist-web produces a static directory, and node runs it
        working-directory: tests/web-consumer
        run: MCPP="$MCPP" ./check-web-plan.sh

      # P3's own criterion: a second, no-op pack copies nothing, which `cp`
      # could never give and `${mcpp.self} stage --verify content` gives for
      # free. A sibling script, not an addition to the one above, so that
      # one keeps passing exactly as it did before this batch.
      - name: dist-web's second pack copies nothing
        working-directory: tests/web-consumer
        run: MCPP="$MCPP" ./check-web-idempotent.sh
      # `kind = "app"` on `*-linux-android` links a shared object (#622 A3),
      # so this fixture's own toolchain resolution provisions `xim:android-
      # ndk` for `--target x86_64-linux-android` exactly as mcpp's own CI
      # does; `dist-apk` provisions the four payloads on its own
      # `feature-xlings.dist-apk` table (`xim:android-build-tools`, `xim:
      # android-platform`, `xim:jdk-temurin`, `xim:android-debug-keystore`).
      # NOT YET GREEN under this job's pinned `MCPP_VERSION`: `kind = "app"`
      # and `mcpp::min_platform_version()` are #622 engine additions, and
      # this step needs the release that carries them (see this repository's
      # README, `dist-apk`'s own row) -- raising the pin is P5's own change,
      # together with the rest of this collection's release.
      #
      # THIS STEP ASSERTS PACKAGING ONLY, DELIBERATELY, NOT `mcpp run
      # --format apk`. This fixture's own `main.cpp` and `mcpp.toml` DO wire
      # up a real device row (`ANativeActivity_onCreate`, `runner =
      # ["adb-run"]`) and it was run end to end (2026-09-12) against both a
      # KVM-accelerated x86_64 emulator (`xim:android-emulator` +
      # `xim:android-system-image`) and a physical arm64-v8a phone over adb,
      # both exiting 0 with `1-2-3` in the logcat output -- but this GitHub-
      # hosted runner has neither an emulator image nor a device attached,
      # so a `run` step here would only ever report "no device/emulator
      # found" and never `1-2-3`. That measurement stays a local/self-hosted
      # concern until a runner class with a real device or a KVM-capable
      # emulator is wired into this workflow.
      - name: dist-apk produces a signed APK, level 0 and level 1
        working-directory: tests/apk-consumer
        run: |
          "$MCPP" build --target x86_64-linux-android
          "$MCPP" pack --format apk --target x86_64-linux-android | tee pack.log
          apk=$(find target -name 'apk-consumer.apk' | head -1)
          test -n "$apk" || { cat pack.log; echo "FAIL: no apk-consumer.apk"; exit 1; }

          BT=$(find "$MCPP_HOME/registry/data/xpkgs/xim-x-android-build-tools" -mindepth 1 -maxdepth 1 -type d | head -1)
          JDK=$(find "$MCPP_HOME/registry/data/xpkgs/xim-x-jdk-temurin" -mindepth 1 -maxdepth 1 -type d | head -1)
          AAPT2="$BT/aapt2"
          APKSIGNER="$BT/bin/apksigner"
          JAR="$JDK/bin/jar"

          "$APKSIGNER" verify --print-certs "$apk" 2>/dev/null | tee verify.log
          grep -q 'CN=Android Debug' verify.log \
            || { echo "FAIL: not signed with the debug key"; exit 1; }

          "$JAR" tf "$apk" | tee listing.log
          for f in "lib/x86_64/libapk-consumer.so" "assets/mcpp-run.json" \
                   "AndroidManifest.xml" "assets/generated/res.bin"; do
            grep -qxF "$f" listing.log \
              || { echo "FAIL: the apk does not list $f"; exit 1; }
          done

          "$AAPT2" dump badging "$apk" 2>/dev/null | tee badging.log
          grep -q "^package: name='" badging.log \
            || { echo "FAIL: aapt2 could not read the package name"; exit 1; }
          # aapt2 spells the attribute `minSdkVersion:'24'`; the file is shown
          # byte-for-byte on a miss so that a quoting difference is visible.
          tr -d '\r' < badging.log | grep -Eq "^(min)?[sS]dkVersion:'24'" \
            || { echo "FAIL: minSdkVersion is not 24 (this fixture's own min_api_level)"; cat -A badging.log | head -12; exit 1; }
          echo "ok: dist-apk level 0 -- a signed, aapt2-readable APK carrying the native library, the deployed asset and the run sidecar"

      # P1/P2's own criteria (design record §3.5 / §9.2), beside the step
      # above rather than folded into it: (a) level 0 with no template is
      # 0.8.0's manifest byte-for-byte; (b) a template's own permission and
      # receiver reach the linked apk; (c),(d) a template missing a required
      # token, or naming an unknown one, is refused at plan time, checked on
      # build.mcpp's own stdout/stderr since mcpp discards it on a plan-time
      # refusal's exit code of 0 (the script's own header says why); (e) two
      # Java roots, one under this project and one a sibling directory
      # reached by an absolute path, dex into one file carrying classes from
      # both; (g) a project's own res/ links as the BASE -- two resources
      # nothing else defines reach the apk (0.9.0 linked res/ as an aapt2
      # overlay, which refuses any resource the base does not already have).
      - name: dist-apk's manifest template, Java roots, res/ and version tokens, (a) to (h)
        working-directory: tests/apk-consumer
        run: MCPP="$MCPP" ./check-apk-features.sh

      # THE CLOSURE THE ENGINE STAGED (mcpp#634, B5). A dependency linked as a
      # shared object on the Android row reaches `lib/<abi>/` beside the app's
      # own because the engine stages the closure and names it in the stage
      # manifest (2026.9.14.2+), and the member reads that tree. Five criteria:
      # two packs in a row carry the dependency's library both times; two
      # triples give one signed APK listing both ABIs; `--format aab` gives an
      # App Bundle bundletool validates and jarsigner verifies, and a universal
      # APK built from it; a refusal prints its reason; and a stage manifest
      # without `needs` lines is refused naming the engine floor. The script's
      # header records what 0.9.3 did for each.
      - name: dist-apk reads the staged closure, packs two ABIs into one APK, and builds an App Bundle
        timeout-minutes: 30
        working-directory: tests/apk-consumer-shared
        run: MCPP="$MCPP" ./check-apk-closure.sh

      # Compiles the device unit on a machine with no GPU: the clang route
      # produces sm_89 code from the payload toolkit. Running it needs a
      # device, so the run is of the CPU variant, which the same seam serves.
      - name: rules-cuda through a consumer
        working-directory: tests/cuda-consumer
        run: |
          "$MCPP" build
          "$MCPP" build --no-accel
          "$MCPP" run --no-accel | tee run.log
          grep -q '^12 24 36 48' run.log

      # The same shape one API over: HIP on the NVIDIA platform is a header
      # layer over the CUDA runtime, so this compiles the same device code
      # through a different spelling and needs no ROCm. The device object is
      # asserted to exist, because a rule that submitted no action at all would
      # otherwise leave a build that "succeeded" and produced nothing.
      - name: rules-hip through a consumer
        working-directory: tests/hip-consumer
        run: |
          "$MCPP" build
          test -f target/.build-mcpp/out/saxpy.hip.o
          "$MCPP" build --no-accel
          "$MCPP" run --no-accel | tee run.log
          grep -q '^12 24 36 48' run.log

      # SYCL is compiled by a second compiler, so this step is the one that
      # would catch a payload the rule cannot drive. Two objects have to exist:
      # the unit's own, and the device-link wrapper that registers its image --
      # without the second the program links and finds no kernel at run time.
      - name: rules-sycl through a consumer
        working-directory: tests/sycl-consumer
        run: |
          "$MCPP" build
          test -f target/.build-mcpp/out/saxpy.sycl.o
          test -f target/.build-mcpp/out/sycl_device_link.o
          "$MCPP" build --no-accel
          "$MCPP" run --no-accel | tee run.log
          grep -q '^12 24 36 48' run.log

      # EVERY RULE COMPILED FOR THIS HOST, which is a different claim from any
      # step above. Each of those exercises one rule and needs that rule's
      # payload, so a rule is only ever compiled on the platforms its payload
      # exists for -- and a rule's host-dependent halves are exactly the code
      # those platforms do not compile. This fixture names no accelerator, so
      # every rule returns before looking for a payload and nothing is
      # downloaded; what it asserts is that all six modules compile here.
      - name: every rule module compiles for this host
        run: |
          set -e
          # THE FIXTURE'S OWN DENOMINATOR. It asserts "every rule compiles
          # here", and "every" is a list it carries -- so a seventh member
          # added to this package would be covered by a step whose name says it
          # already is. The list is therefore compared against the package's
          # own `[features]` before the build, and the two must be equal.
          # OFF THE SECTION HEADERS, which is where a feature's name is
          # since 0.3.0: a feature carries `device_extensions` and
          # `rule_module` as well as `sources`, and TOML 1.0 forbids a
          # multi-line inline table, so `[features.<name>]` replaced
          # `<name> = { ... }`. Reading keys out of the table BODY matched
          # `sources` once per feature and reported the fixture as
          # incomplete while the extractor was what broke.
          # MEMBERS, NOT EVERY FEATURE. A feature that another feature
          # IMPLIES is internal -- `surface` carries the build-program half of
          # the generated surface and every member implies it, and a consumer
          # never writes it. Subtracting the implied ones keeps this check
          # meaning "the fixture names every member a consumer can activate";
          # padding the fixture instead would make it mean less.
          #
          # The rule is read out of the manifest, not listed here, so a seventh
          # MEMBER is still caught: nothing implies it.
          # A TEMP FILE, NOT `<(...)`. This step also runs on windows-2022
          # through Git Bash, where process substitution is emulated and not
          # dependable -- and a check that behaves differently on one of the
          # three hosts is the exact class of difference this job exists to
          # catch, so it must not introduce one.
          grep -oE '^implies[[:space:]]*=.*' mcpp.toml \
            | grep -oE '"[a-z0-9-]+"' | tr -d '"' | sort -u > /tmp/implied.txt
          grep -oE '^\[features\.[a-z0-9-]+\]' mcpp.toml \
            | sed 's/^\[features\.//; s/\]$//' | sort > /tmp/allfeats.txt
          feats=$(comm -23 /tmp/allfeats.txt /tmp/implied.txt)
          used=$(sed -n '/features = \[/,/\], host-module/p' tests/all-rules-compile/mcpp.toml \
                 | grep -oE '"[a-z-]+"' | tr -d '"' | sort)
          [ -n "$feats" ] || {
            echo "FAIL: read no features out of mcpp.toml. The extractor above"
            echo "      expects [features.<name>] sections and found none, so the"
            echo "      manifest spelling changed -- the package has not stopped"
            echo "      having features."
            grep -n '^\[features' mcpp.toml | head
            exit 1; }
          [ "$feats" = "$used" ] || {
            echo "FAIL: the fixture does not name every published feature"
            echo "  package: $(echo $feats)"
            echo "  fixture: $(echo $used)"
            exit 1; }
          cd tests/all-rules-compile
          "$MCPP" build
          "$MCPP" run | tee run.log
          grep -q '^all-rules-compile ok' run.log

      # TWO RULES IN ONE BUILD PROGRAM, which every step above has exactly
      # one of. With one, a rule can take the whole of `device_sources()` and
      # be right by accident; with two, that list holds a `.cu` AND a `.comp`,
      # and a rule that takes all of it hands its compiler a file the compiler
      # does not accept. Measured on the unfixed rules: the CUDA rule compiled
      # `scale.comp` as CUDA and the shader rule then failed on the `.cu`.
      #
      # Both device products are asserted to exist, because a rule that
      # submitted no action would otherwise leave a build that "succeeded".
      # The `--no-accel` leg is asserted separately: it is what proves a rule
      # whose backend is absent does nothing rather than complaining.
      - name: two rules in one build program
        working-directory: tests/multi-rule-consumer
        run: |
          "$MCPP" build
          test -f target/.build-mcpp/out/saxpy.cu.o
          test -f target/.build-mcpp/out/spirv/scale_comp.h
          test ! -f target/.build-mcpp/out/scale.cu.o
          "$MCPP" run --no-accel | tee run.log
          grep -q '^magic=(no shader in this build)' run.log
          grep -q '^12 24 36 48' run.log

      # THE PAYLOADS CAME FROM THE RULE, NOT FROM THE FIXTURE.
      #
      # Every fixture above builds, and that alone does not distinguish "the
      # rule declared its toolkit" from "the fixture still declares it": a
      # re-added `[xlings.workspace]` block would keep all of them green while
      # the claim this package makes stopped being true.
      #
      # The object is mcpp's own report of WHERE the entries came from. It
      # names the pass -- the graph's, not the root's -- so it separates the
      # two cases directly rather than by reading the manifests back.
      - name: the rules declare their own payloads
        run: |
          set -e
          # THE PROVISIONING LINE ONLY PRINTS ON A STAMP MISS, and the earlier
          # steps of this job have already written those stamps. Without
          # clearing them, the criterion's "no" and "this ran after the
          # fixtures" are the same reading. Removing them costs nothing: the
          # packages are still installed, so the re-provision is one xlings
          # round trip.
          #
          # THE PATH IS ASKED FOR, NOT ASSUMED. A released mcpp is
          # self-contained and its home is the extracted tarball unless
          # MCPP_HOME says otherwise -- so `rm -rf ~/.mcpp/provisioned` removed
          # nothing and this step failed on a working build. Measured: a local
          # rehearsal passed because a DEV build is disqualified from
          # self-contained mode and does use ~/.mcpp, so the rehearsal and CI
          # were clearing different directories.
          # Through a FILE rather than a pipe: on macOS this same expression
          # killed mcpp with `internal: unhandled exception: failed to write
          # formatted output`, because `awk ... exit` closes the read end at
          # the first match. Written the same way on every platform so the two
          # jobs cannot drift.
          "$MCPP" self env > mcpp-env.txt
          HOME_DIR=$(awk -F'= *' '/^MCPP_HOME/{print $2; exit}' mcpp-env.txt)
          [ -n "$HOME_DIR" ] || { echo "FAIL: could not read MCPP_HOME"; cat mcpp-env.txt; exit 1; }
          echo "clearing provisioning stamps under $HOME_DIR"
          rm -rf "$HOME_DIR/provisioned"
          for d in tests/cuda-consumer tests/hip-consumer \
                   tests/sycl-consumer tests/spirv-consumer; do
            # No project-side declaration is the first half of the claim, and
            # it is a property of a file this repository owns.
            if grep -qE '^\[(target\..*\.)?xlings\.workspace\]' "$d/mcpp.toml"; then
              echo "FAIL: $d declares payloads itself, so this step proves nothing"
              exit 1
            fi
            ( cd "$d" && rm -rf target && "$MCPP" build > prov.log 2>&1 ) || {
              echo "build failed in $d"; tail -20 "$d/prov.log"; exit 1; }
            grep -q 'entries declared by dependencies' "$d/prov.log" || {
              echo "FAIL: $d installed no payload the rule declared"
              grep -i 'provisioning' "$d/prov.log" || echo "(no provisioning line at all)"
              exit 1
            }
            echo "ok: $d — $(grep -m1 'entries declared by dependencies' "$d/prov.log")"
            rm -f "$d/prov.log"
          done
          # And the one fixture that DOES override, so the override path is on
          # this graph too: it declares one entry, and one version is installed.
          d=tests/multi-rule-consumer
          grep -q 'xlings.workspace' "$d/mcpp.toml" || {
            echo "FAIL: $d no longer demonstrates the override"; exit 1; }
          ( cd "$d" && rm -rf target && "$MCPP" build > prov.log 2>&1 ) || {
            echo "build failed in $d"; tail -20 "$d/prov.log"; exit 1; }
          XPKGS="$HOME_DIR/registry/data/xpkgs"
          n=$(ls -1 "$XPKGS/xim-x-glslang" | wc -l | tr -d ' ')
          [ "$n" = "1" ] || {
            echo "FAIL: the override installed $n versions of glslang:"
            ls -1 "$XPKGS/xim-x-glslang"
            exit 1
          }
          echo "ok: $d — one glslang, $(ls -1 "$XPKGS/xim-x-glslang")"
          rm -f "$d/prov.log"

      # THE HOST-LEAK ASSERTION, and what it measures was corrected once.
      #
      # Its first form grepped a verbose build for `/usr`. That reported
      # nothing wrong on a developer machine AND on a runner, while the runner
      # was in fact compiling the HIP device pass against the host's
      # `/usr/include/c++/14` -- because an IMPLICIT include search never
      # appears on a command line. The compiler's own `#include <...> search
      # starts here` list is where it is visible.
      #
      # The criterion is the C++ standard library specifically, not `/usr`
      # absence: mcpp's own compiles leave `/usr/include` on the list as a last
      # resort for C headers, and a stricter rule here would be stricter than
      # the engine it is checking. What must never appear is a C++ library
      # nothing in this ecosystem chose.
      # AND THE C LIBRARY, WHICH THE ASSERTION BELOW CANNOT SEE.
      #
      # "no host C++ standard library" was true of the SYCL rule while its
      # device units compiled against the HOST's C library: dpcpp's clang had
      # no ecosystem glibc on its search list at all, so `/usr/include` was not
      # a last resort there, it was the only one. The reasoning below -- that
      # `/usr/include` last is what the engine itself does -- holds only when
      # the ecosystem's own C library is ahead of it.
      #
      # THE OBJECT IS THE COMPILER'S OWN SEARCH LIST. A build log carries the
      # ENGINE's compile lines too, and those name the ecosystem glibc, so
      # grepping the log passes for a rule whose device compile names nothing.
      # Measured: the HIP rule's device command carries neither `--sysroot` nor
      # `-isystem <glibc>` and is nonetheless correct, because the compiler it
      # drives is configured with the ecosystem glibc. Only the search list
      # separates that from the case that is wrong.
      - name: every device compile finds the ecosystem C library first
        run: |
          bash tools/check_device_c_library.sh \
            tests/cuda-consumer tests/hip-consumer tests/sycl-consumer

      - name: no device compile reads a host C++ standard library
        run: |
          fail=0
          for d in tests/cuda-consumer tests/hip-consumer tests/sycl-consumer; do
            ( cd "$d" && rm -rf target && "$MCPP" build -v > build.log 2>&1 ) || {
              echo "build failed in $d"; tail -20 "$d/build.log"; exit 1; }
            hits=$(grep -oE '/(usr|opt)/[^ ]*(c\+\+|include/c\+\+)[^ ]*' "$d/build.log" | sort -u | head -5)
            if [ -n "$hits" ]; then
              echo "host C++ standard library reached from $d:"; echo "$hits"; fail=1
            else
              echo "ok: $d reads no host C++ standard library"
            fi
          done
          [ "$fail" -eq 0 ]

  # ── THE SAME RULE ON THE OTHER TWO PLATFORMS ────────────────────────────────
  #
  # `rules-spirv` is the only member whose payload this ecosystem publishes for
  # all three, so it is the only one that can be checked on all three. What this
  # job proves is the claim the per-platform declaration makes: a project writes
  # the rule edge and nothing else, and the compiler that arrives is whichever
  # one that platform has -- glslang on Linux, glslc here.
  #
  # ONLY THE SPIR-V FIXTURE. The CUDA, HIP and SYCL payloads are Linux-only
  # upstream, so a matrix that ran every fixture everywhere would be red for a
  # reason that is not a defect.
  rules-cross-platform:
    name: rules (${{ matrix.name }})
    runs-on: ${{ matrix.runs-on }}
    # 150, which leaves room for the source build a dispatch naming
    # `mcpp_source_ref` adds ahead of every step.
    timeout-minutes: 150
    strategy:
      fail-fast: false
      matrix:
        include:
          # macos-15, matching mcpp's own macOS CI, and the reason is a
          # measured limitation of the older release rather than a preference.
          #
          # On macos-14 a build program fails to LINK, with
          #
          #   ld64.lld: error: undefined symbol:
          #       std::__1::__is_posix_terminal(__sFILE*)
          #
          # referenced from `std::__1::__print::__is_terminal`. That symbol
          # lives in the libc++ DYLIB and was added in a version macOS 14 does
          # not ship, and the build program's link resolves `-lc++` to the
          # system copy rather than to the LLVM payload's. It is reached
          # through `import std` itself, so no rule package can avoid it -- the
          # rules stopped using `std::println` for the same reason and it was
          # not enough.
          #
          # Recorded rather than worked around here: the engine-side half is
          # `host_link_tokens` returning before it adds the payload's runtime
          # directories on macOS. Once a release carries that, this moves back
          # to macos-14, which is the floor mcpp's README states.
          - name: macos arm64
            runs-on: macos-15
            asset: macosx-arm64.tar.gz
            dir-suffix: macosx-arm64
          - name: windows x86_64
            runs-on: windows-2022
            asset: windows-x86_64.zip
            dir-suffix: windows-x86_64
    defaults:
      run:
        shell: bash
    steps:
      - uses: actions/checkout@v4

      - name: Pin MCPP_HOME under this runner's home
        run: |
          set -e
          # The value has to be in the HOST's path syntax, not Git Bash's.
          # `$HOME` there is `/c/Users/runneradmin`, and mcpp hands this
          # variable to xlings, which is a native Windows program: it answered
          # `The filename, directory name, or volume label syntax is
          # incorrect.` and exited 1, from inside a provisioning step whose own
          # message named a package rather than a path.
          H="$HOME/.mcpp"
          command -v cygpath >/dev/null && H=$(cygpath -m "$H")
          echo "MCPP_HOME=$H" >> "$GITHUB_ENV"

      - name: Cache the mcpp sandbox
        uses: actions/cache@v4
        with:
          path: ~/.mcpp
          key: mcpp-sandbox-${{ runner.os }}-${{ runner.arch }}-${{ env.MCPP_VERSION }}-${{ hashFiles('tests/spirv-consumer/mcpp.toml') }}
          restore-keys: |
            mcpp-sandbox-${{ runner.os }}-${{ runner.arch }}-${{ env.MCPP_VERSION }}-

      - name: Fetch the released mcpp
        run: |
          set -e
          curl -L -fsS --retry 3 --retry-all-errors -o mcpp.pkg \
            "https://github.com/mcpp-community/mcpp/releases/download/v${MCPP_VERSION}/mcpp-${MCPP_VERSION}-${{ matrix.asset }}"
          case "${{ matrix.asset }}" in
            *.zip) unzip -q mcpp.pkg ;;
            *)     tar -xzf mcpp.pkg ;;
          esac
          dir="mcpp-${MCPP_VERSION}-${{ matrix.dir-suffix }}"
          MCPP="$PWD/$dir/bin/mcpp"
          "$MCPP" --version
          # The bundled xlings, named explicitly because MCPP_HOME is pinned
          # away from the tarball. See the Linux job for the measurement.
          #
          # The suffix is the host's: the Windows distribution ships
          # `registry/bin/xlings.exe`, and a variable pointing at a file that
          # does not exist produces `error: xlings binary not found` naming
          # three remedies, none of which is the one that applies.
          # Two host differences, and the second one is the interesting one.
          # The suffix: the Windows distribution ships `xlings.exe`. The PATH
          # SHAPE: this job runs under Git Bash, whose `$PWD` is a POSIX path
          # (`/d/a/...`), while `mcpp` is a native Windows program and reads
          # this variable as a Windows path. Both failures report the same
          # `error: xlings binary not found` and offer the same three remedies,
          # none of which is "the path you gave is in the other syntax".
          XL="$PWD/$dir/registry/bin/xlings"
          [ -f "$XL" ] || XL="$XL.exe"
          test -f "$XL" || { echo "no vendored xlings at $XL"; exit 1; }
          command -v cygpath >/dev/null && XL=$(cygpath -m "$XL")
          export MCPP_VENDORED_XLINGS="$XL"
          "$MCPP" self config --mirror GLOBAL
          echo "MCPP=$MCPP" >> "$GITHUB_ENV"
          echo "MCPP_VENDORED_XLINGS=$MCPP_VENDORED_XLINGS" >> "$GITHUB_ENV"

      # THE ENGINE THE STEPS BELOW RUN: the release fetched above, or mcpp built
      # from `MCPP_SOURCE_REF` (see the workflow's `env`). A cold build of mcpp
      # is the longest step of the job, which is what its timeout is sized for.
      - name: the mcpp under review, built from MCPP_SOURCE_REF when it is set
        timeout-minutes: 45
        run: bash .github/scripts/mcpp-under-review.sh

      # THE CRITERION FOR THE STEP ABOVE, IN A LATER STEP, because what that step
      # writes to `GITHUB_ENV` governs only the steps after it.
      - name: the steps below run the mcpp under review
        if: env.MCPP_SOURCE_REF != ''
        timeout-minutes: 5
        run: |
          set -eu
          [ "$MCPP" = "$MCPP_UNDER_REVIEW" ] || {
            echo "::error::the steps run $MCPP, and the mcpp built from $MCPP_SOURCE_REF is $MCPP_UNDER_REVIEW"; exit 1; }
          version=$("$MCPP" --version | head -1)
          [ "$version" = "$MCPP_UNDER_REVIEW_VERSION" ] || {
            echo "::error::$MCPP prints '$version', and the build printed '$MCPP_UNDER_REVIEW_VERSION'"; exit 1; }
          # A reading, not a criterion: the two engines' versions, which may be
          # equal when the reference has not moved the version yet, so the
          # criterion above is the path and not the version.
          echo "READING released: $("$MCPP_RELEASED" --version | head -1); under review: $version"
          echo "ok: the steps run $version, built from $MCPP_SOURCE_REF"

      # FIRST, BECAUSE IT IS THE CHEAPER QUESTION AND THE MORE INFORMATIVE
      # ANSWER. Every other step here drives one rule end to end and needs
      # that rule's payload; this one names no accelerator, downloads nothing,
      # and asks only whether all six modules COMPILE for this host -- which
      # is the half of a rule that a Linux-only CI never sees. Run after the
      # end-to-end step, its failure arrived as somebody else's build error:
      # `no member named 'popen' in the global namespace`, reported against a
      # consumer that had nothing to do with it.
      - name: every rule module compiles for this host
        run: |
          set -e
          # THE FIXTURE'S OWN DENOMINATOR. It asserts "every rule compiles
          # here", and "every" is a list it carries -- so a seventh member
          # added to this package would be covered by a step whose name says it
          # already is. The list is therefore compared against the package's
          # own `[features]` before the build, and the two must be equal.
          # OFF THE SECTION HEADERS, which is where a feature's name is
          # since 0.3.0: a feature carries `device_extensions` and
          # `rule_module` as well as `sources`, and TOML 1.0 forbids a
          # multi-line inline table, so `[features.<name>]` replaced
          # `<name> = { ... }`. Reading keys out of the table BODY matched
          # `sources` once per feature and reported the fixture as
          # incomplete while the extractor was what broke.
          # MEMBERS, NOT EVERY FEATURE. A feature that another feature
          # IMPLIES is internal -- `surface` carries the build-program half of
          # the generated surface and every member implies it, and a consumer
          # never writes it. Subtracting the implied ones keeps this check
          # meaning "the fixture names every member a consumer can activate";
          # padding the fixture instead would make it mean less. The rule is
          # read out of the manifest, so a seventh MEMBER is still caught.
          #
          # A temp file, not `<(...)`: this step also runs on windows-2022
          # through Git Bash, where process substitution is emulated and not
          # dependable -- and a check that behaves differently on one of the
          # three hosts is the class of difference this job exists to catch.
          grep -oE '^implies[[:space:]]*=.*' mcpp.toml \
            | grep -oE '"[a-z0-9-]+"' | tr -d '"' | sort -u > /tmp/implied.txt
          grep -oE '^\[features\.[a-z0-9-]+\]' mcpp.toml \
            | sed 's/^\[features\.//; s/\]$//' | sort > /tmp/allfeats.txt
          feats=$(comm -23 /tmp/allfeats.txt /tmp/implied.txt)
          used=$(sed -n '/features = \[/,/\], host-module/p' tests/all-rules-compile/mcpp.toml \
                 | grep -oE '"[a-z-]+"' | tr -d '"' | sort)
          [ -n "$feats" ] || {
            echo "FAIL: read no features out of mcpp.toml. The extractor above"
            echo "      expects [features.<name>] sections and found none, so the"
            echo "      manifest spelling changed -- the package has not stopped"
            echo "      having features."
            grep -n '^\[features' mcpp.toml | head
            exit 1; }
          [ "$feats" = "$used" ] || {
            echo "FAIL: the fixture does not name every published feature"
            echo "  package: $(echo $feats)"
            echo "  fixture: $(echo $used)"
            exit 1; }
          cd tests/all-rules-compile
          "$MCPP" build
          "$MCPP" run | tee run.log
          grep -q '^all-rules-compile ok' run.log

      - name: rules-spirv through a consumer
        working-directory: tests/spirv-consumer
        run: |
          set -e
          "$MCPP" build
          "$MCPP" run | tee run.log
          grep -q '^magic=07230203' run.log

      # The same provenance criterion the Linux job applies: the payload has to
      # come from the GRAPH, not from the fixture. Without it, a fixture that
      # quietly regained an `[xlings.workspace]` would keep this green while the
      # claim stopped being true.
      # THE ISLAND BOUNDARY, ON THE TWO HOSTS WHERE ITS DERIVATION HAD NEVER RUN.
      #
      # `mcpp.tools.island` compiles on all three hosts -- the fixture above
      # imports it -- but until 0.5.1 nothing EXERCISED it outside Linux, and
      # what it does is path arithmetic: a namespace is the path from a root to
      # a file, and a path separator is not the same character everywhere.
      # `force_include_flags` also answers `/FI<path>` as one token for MSVC
      # where every other driver takes `-include <path>` as two, and that branch
      # had no runner either.
      #
      # The fixture needs no accelerator payload: its islands are ordinary C,
      # and `accel` selects which of the two roots the manifest compiles.
      - name: the island boundary, generated and namespaced on this host
        working-directory: tests/island-interface
        run: |
          set -e
          "$MCPP" build
          "$MCPP" run | tee run.log
          grep -q '^out\[0\]=6 out\[1\]=12 out\[2\]=18 out\[3\]=24' run.log
          grep -q '^all ok' run.log
          d=target/.build-mcpp/out/island
          # The namespace is the path from the layout root to the file, so this
          # is the assertion a separator mistake fails.
          grep -q '^export namespace island_interface::kernels {' \
            "$d/island_interface.kernels.cppm"
          grep -q '^export namespace island_interface::kernels::image {' \
            "$d/island_interface.kernels.cppm"
          if grep -q 'namespace' "$d/island_interface.kernels.h"; then
            echo "FAIL: the generated header carries a namespace"; exit 1
          fi
          echo "ok: the boundary is generated and namespaced on this host"

      # ── dist, on the platform each member serves ────────────────────────
      #
      # A PLAN-LEVEL ASSERTION IS NOT A MEASUREMENT. `plan_for()` returning
      # `applies == false` on the wrong OS says the gate works; it says nothing
      # about whether the tool accepts what the member renders. These two steps
      # exist because that question is only answerable here, and because the
      # members were written on a Linux host where neither tool can run.
      #
      # THE FIRST THING EITHER ONE SETTLES IS A SPELLING. `dist-wix` writes
      # `$(Executable)` in its generated `.wxs`, taken from a working
      # implementation rather than from WiX's documentation, which spells a
      # `-d` define as `$(var.Executable)`. Only a real `wix build` can say
      # which one this schema accepts.
      - name: dist-wix produces an MSI that carries the program
        if: runner.os == 'Windows'
        working-directory: tests/msi-consumer
        shell: bash
        run: |
          set -e
          # THE TOOL COMES FROM THE PAYLOAD, NOT FROM THIS STEP. `dist-wix`
          # declares `xim:wix` under `[target.windows.feature-xlings.dist-wix]`,
          # so mcpp provisions it when the fixture activates the feature on a
          # Windows target, and the member locates it through `xpkg_dir`. An
          # earlier revision of this step installed WiX 6 with `dotnet tool`
          # and the member searched PATH; the criterion below on the argv is
          # what distinguishes the two, and a run that found a host `wix.exe`
          # would fail it. WiX 7 is not an option for the payload either: it
          # refuses to run until an OSMF licence is accepted out of band
          # (`error WIX7015`, measured on windows-2022), while 5.0.2 and 6.0.2
          # are under the Microsoft Reciprocal License and run as installed.

          # A plain build must have no distribution edge.
          "$MCPP" build
          if find target -name '*.msi' | grep -q .; then
            echo "FAIL: a plain build produced an installer"; exit 1
          fi
          "$MCPP" pack --format msi | tee pack.log
          msi=$(find target -name '*.msi' | head -1)
          test -n "$msi" || { cat pack.log; echo "FAIL: no MSI"; exit 1; }
          # THE TOOL CAME FROM THE PAYLOAD BY CONSTRUCTION, and the criterion
          # is the absence of any other: this step installs no WiX, the member
          # has no PATH tier, and the runner image ships WiX 3 (candle/light)
          # but no `wix.exe`. An MSI therefore exists only if the payload's
          # `wix.exe` produced it. The engine prints the argv with the tool's
          # basename, so the log line cannot carry the store path -- an earlier
          # revision asserted on that and failed on a correct run.
          if command -v wix.exe >/dev/null 2>&1 || command -v wix >/dev/null 2>&1; then
            echo "FAIL: a host wix is on PATH; this step cannot tell the payload's tool from it"
            command -v wix.exe wix; exit 1
          fi

          # THE CRITERION IS THE `File` TABLE, NOT THE FILE'S EXISTENCE. The
          # measured failure this member is shaped around is a VALID, EMPTY,
          # 52 KB installer with no diagnostic, produced when a harvested bind
          # path resolved to nothing. An assertion that stops at "an .msi
          # exists" passes on exactly that artifact.
          size=$(stat -c %s "$msi" 2>/dev/null || stat -f %z "$msi")
          echo "msi: $msi ($size bytes)"
          exe=$(find target -name 'msi-consumer.exe' | head -1)
          test -n "$exe" || { echo "FAIL: no linked program to compare against"; exit 1; }
          exesize=$(stat -c %s "$exe" 2>/dev/null || stat -f %z "$exe")

          # ASK THE INSTALLER WHAT IT CONTAINS. A SIZE RATIO IS A GUESS.
          #
          # This was `size > exesize / 2`, with the reasoning "a cabinet
          # compresses, so this is a floor and not an equality". The ratio was
          # invented, and the first real WiX 6 run refused a correct MSI: 32768
          # bytes for a 114688-byte program, which is what a stripped
          # hello-world looks like once a cab has had it -- mostly padding and
          # highly compressible. The same mistake was already made once in this
          # ecosystem, on the AppImage floor, where a 16 KB bound refused a
          # 14999-byte correct bundle.
          #
          # An administrative install writes the payload out uncompressed, so
          # the question "is the program in there" has an exact answer and this
          # asserts EQUALITY against the linked binary. It also proves the
          # package installs, which a size never did.
          admin="$PWD/msi-admin-image"
          rm -rf "$admin"; mkdir -p "$admin"
          msiexec //a "$(cygpath -w "$msi")" //qn TARGETDIR="$(cygpath -w "$admin")" \
            || { echo "FAIL: the MSI would not produce an administrative image"; exit 1; }
          inside=$(find "$admin" -name 'msi-consumer.exe' | head -1)
          test -n "$inside" || {
            echo "FAIL: the MSI installs no msi-consumer.exe -- it is the empty installer"
            find "$admin" -type f | head -20; exit 1; }
          insidesize=$(stat -c %s "$inside" 2>/dev/null || stat -f %z "$inside")
          [ "$insidesize" -eq "$exesize" ] || {
            echo "FAIL: the installed program is $insidesize bytes, the linked one $exesize"
            exit 1; }
          echo "ok: the MSI installs msi-consumer.exe, $insidesize bytes, byte-for-byte the linked program"

          # THE STAGED TREE IS INSTALLED, NOT ONLY THE PROGRAM (0.10.1). The
          # fixture deploys `share/greeting.txt` to `data/`; the engine stages
          # it at `bin/data/greeting.txt` and the member names it in the
          # `StagedFiles` group, so the administrative image carries it at the
          # same path beside the program, byte-for-byte.
          data="$(dirname "$inside")/data/greeting.txt"
          test -f "$data" || {
            echo "FAIL: the MSI does not install the deployed data/greeting.txt beside the program"
            find "$admin" -type f | head -20; exit 1; }
          cmp "$data" share/greeting.txt \
            || { echo "FAIL: the installed data/greeting.txt differs from share/greeting.txt"; exit 1; }
          echo "ok: the MSI installs the deployed data/greeting.txt beside the program"

      # `--format setup` (mcpp#634, B4): a Burn bundle with WiX's stock
      # bootstrapper application, chaining the MSI the step above measured, and
      # built through the extension `xim:wix` 5.0.2-1 carries.
      - name: dist-wix produces a Burn bundle that chains the MSI
        if: ${{ !cancelled() && runner.os == 'Windows' }}
        timeout-minutes: 20
        working-directory: tests/msi-consumer
        run: MCPP="$MCPP" ./check-setup.sh

      - name: dist-apple produces a bundle that launches
        if: runner.os == 'macOS'
        working-directory: tests/app-consumer
        shell: bash
        run: |
          set -e
          "$MCPP" build
          if find target -name '*.app' | grep -q .; then
            echo "FAIL: a plain build produced a bundle"; exit 1
          fi
          "$MCPP" pack --format app | tee pack.log
          app=$(find target -name '*.app' -type d | head -1)
          test -n "$app" || { cat pack.log; echo "FAIL: no .app bundle"; exit 1; }

          # The three files a bundle is, and the one that decides whether it
          # launches at all.
          test -f "$app/Contents/Info.plist" || { echo "FAIL: no Info.plist"; exit 1; }
          exe=$(/usr/libexec/PlistBuddy -c 'Print :CFBundleExecutable' "$app/Contents/Info.plist")
          test -n "$exe" || { echo "FAIL: Info.plist names no executable"; exit 1; }
          # `CFBundleExecutable` must be a BARE NAME, never a path: Apple's
          # loader resolves it against Contents/MacOS/ and a path there is not
          # a launchable bundle. This is the assumption the member documents.
          case "$exe" in */*) echo "FAIL: CFBundleExecutable is a path: $exe"; exit 1 ;; esac
          test -x "$app/Contents/MacOS/$exe" \
            || { echo "FAIL: $app/Contents/MacOS/$exe is missing or not executable"
                 ls -la "$app/Contents/MacOS"; exit 1; }
          # THE CRITERION IS THAT IT RUNS THROUGH THE BUNDLE, not that the
          # binary runs: a bundle whose Info.plist names the wrong executable
          # still contains a working program.
          "$app/Contents/MacOS/$exe" | tee run.log
          grep -q '^app-consumer ok' run.log \
            || { echo "FAIL: the bundled program did not run"; exit 1; }
          # `plutil -lint` is Apple's own parser: a plist this member wrote by
          # hand and got subtly wrong would otherwise fail at launch time on a
          # user's machine and nowhere here.
          plutil -lint "$app/Contents/Info.plist"
          # THE DEPLOYED FILE, AT THE RESOURCE DESTINATION AND NOT BESIDE THE
          # PROGRAM (mcpp#630, item 3a): the engine stages `bin/data/...` and
          # this member places it under `Contents/Resources/`.
          test -f "$app/Contents/Resources/data/greeting.txt" \
            || { echo "FAIL: the deployed file is not under Contents/Resources"; find "$app" -type f; exit 1; }
          if [ -e "$app/Contents/MacOS/bin" ]; then
            echo "FAIL: the staged tree was copied whole into Contents/MacOS"; find "$app" -type f; exit 1
          fi
          grep -q 'closure = not-walked' pack.log || echo "note: the stage manifest's closure line was not echoed by pack"
          echo "ok: one bundle, a valid plist, it launches, and the resource is where NSBundle looks"

      # THE CLOSURE AS A FRAMEWORK, ON THE BUNDLE (mcpp#634, B1 to B3). The
      # plan-level half runs on Linux. This step, the Metal step and the iOS
      # step measure independent things, so each runs when an earlier step of
      # the job failed and the job reports every reading it can take. This half reads the linked program's
      # load commands, verifies the bundle's ad-hoc signature, runs the program
      # with and without its framework, runs the bundle through `mcpp run
      # --format app` with no runner in the manifest, and attaches the image.
      - name: dist-apple carries the closure as a signed framework, runs through macapp-run, and writes a disk image
        if: ${{ !cancelled() && runner.os == 'macOS' }}
        timeout-minutes: 30
        working-directory: tests/app-framework-consumer
        run: MCPP="$MCPP" ./check-apple-bundle.sh

      # rules-metal (mcpp#634, B6): three Metal libraries from two shaders, and
      # the compiler's dependency file in the graph. On a runner without the
      # Metal toolchain the script asserts the rule's refusal and annotates the
      # run with a warning that the two criteria are unmeasured.
      - name: rules-metal compiles Metal libraries, or records that this runner has no Metal toolchain
        if: ${{ !cancelled() && runner.os == 'macOS' }}
        timeout-minutes: 20
        working-directory: tests/metal-consumer
        run: MCPP="$MCPP" ./check-metal.sh

      # THE iOS ROW, FOR REAL (#622 B1's other half). `tests/ios-app-consumer`
      # is the same fixture the Linux `consumers` job checks at the plan
      # level (see that fixture's own header); here it is built, packed and
      # run against the real target, because this runner -- unlike every
      # other host this workflow uses -- carries the Xcode SDKs and a
      # bootable simulator that make `--target aarch64-ios-sim` reachable at
      # all.
      #
      # GATED ON THE SAME PRECONDITION mcpp's OWN iOS LANE GATES ON
      # (mcpp's `ci-macos-ios.yml`, `ios-host-surface`): the iPhoneSimulator
      # SDK ships inside Xcode as a separate component, not the Command Line
      # Tools alone, so its absence is a fact about the runner image and not
      # a regression in this collection. Skipped rather than failed, and
      # skipped before anything is provisioned -- the same order `dist-apple`
      # itself refuses in, and the reason `docs/20-toolchains.md` (mcpp)
      # gives: "a machine without Xcode should not download a compiler before
      # being told the compiler is not what is missing."
      - name: dist-apple's iOS row produces a bundle the simulator launches
        if: ${{ !cancelled() && runner.os == 'macOS' }}
        working-directory: tests/ios-app-consumer
        shell: bash
        run: |
          set -uo pipefail
          if ! xcrun --sdk iphonesimulator --show-sdk-path >/dev/null 2>&1; then
            echo "SKIP: no iphonesimulator SDK on this runner"
            echo "      (xcrun --sdk iphonesimulator --show-sdk-path failed) -- see"
            echo "      mcpp's docs/20-toolchains.md, 'The Apple SDKs Are Located, Not Installed'"
            exit 0
          fi
          set -e

          rm -rf target
          "$MCPP" build --target aarch64-ios-sim
          if find target -name '*.app' | grep -q .; then
            echo "FAIL: a plain build produced a bundle"; exit 1
          fi
          "$MCPP" pack --target aarch64-ios-sim --format app | tee pack.log
          app=$(find target -name '*.app' -type d | head -1)
          test -n "$app" || { cat pack.log; echo "FAIL: no .app bundle"; exit 1; }

          # FLAT, NOT Contents/-SHAPED -- the one difference from the macOS
          # bundle above, and the whole reason iOS needed its own branch in
          # `dist/apple.cppm`.
          if [ -d "$app/Contents" ]; then
            echo "FAIL: the simulator bundle carries Contents/ -- not a flat iOS layout"
            exit 1
          fi
          plist="$app/Info.plist"
          test -f "$plist" || { echo "FAIL: no Info.plist at the bundle root"; exit 1; }
          plutil -lint "$plist"

          # `MinimumOSVersion` MUST CARRY THIS FIXTURE'S OWN `[build]
          # ios_deployment_target`, not a default the engine invented.
          minos=$(/usr/libexec/PlistBuddy -c 'Print :MinimumOSVersion' "$plist")
          [ "$minos" = "17.0" ] || {
            echo "FAIL: MinimumOSVersion is '$minos', expected 17.0 (this fixture's ios_deployment_target)"
            exit 1; }
          plat=$(/usr/libexec/PlistBuddy -c 'Print :CFBundleSupportedPlatforms:0' "$plist")
          [ "$plat" = "iPhoneSimulator" ] || {
            echo "FAIL: CFBundleSupportedPlatforms is '$plat', expected iPhoneSimulator"
            exit 1; }
          # THE DEPLOYED FILE, AT THE BUNDLE ROOT (the flat layout), and the
          # executable at the root by its bare name -- not under `bin/`.
          test -f "$app/data/greeting.txt" \
            || { echo "FAIL: the deployed file is not at the bundle root"; find "$app" -type f; exit 1; }
          test -x "$app/ios-app-consumer" \
            || { echo "FAIL: the executable is not at the bundle root"; find "$app" -type f; exit 1; }

          exe=$(/usr/libexec/PlistBuddy -c 'Print :CFBundleExecutable' "$plist")
          test -x "$app/$exe" \
            || { echo "FAIL: $app/$exe is missing or not executable"; ls -la "$app"; exit 1; }

          # THE SIMULATOR, THROUGH THE DECLARED RUNNER. `mcpp run --format
          # app` hands the packaged bundle to `runner = ["simctl-run"]`
          # (`xim:apple-simulator-tools` 0.3.0, declared on this target row),
          # which installs the bundle and, because its executable does not
          # load UIKit, runs the installed executable with `simctl spawn`. This
          # is the same path a consumer's own `mcpp run --target aarch64-ios-sim
          # --format app` takes, not a bare `simctl spawn` this step could call
          # directly.
          #
          # THE PROGRAM EXITS 7, AND 7 IS THE CRITERION. `simctl launch`, which
          # 0.2.0 used, returns 0 for an application that exits 7, so a fixture
          # that exited 0 could not tell a runner that returns the status from
          # one that loses it (mcpp#634's triage record, section 7.2).
          out=$("$MCPP" run --target aarch64-ios-sim --format app 2>&1) && rc=0 || rc=$?
          printf '%s\n' "$out" | tail -20
          [ "$rc" -eq 7 ] \
            || { echo "FAIL: mcpp run --target aarch64-ios-sim --format app exited $rc, and the program exits 7"; exit 1; }
          # A line may end in a carriage return when the output passes through
          # a pty, so the marker is asserted as a line after that is stripped.
          # The diagnostic uses `od -c`, which BSD and GNU both accept; BSD
          # `cat` refuses `-A`.
          tr -d '\r' <<<"$out" | grep -Eq '^[[:space:]]*1-2-3[[:space:]]*$' \
            || { echo "FAIL: the program's output line '1-2-3' is absent"; printf '%s\n' "$out" | tail -8 | od -c; exit 1; }
          echo "ok: a flat iOS Simulator bundle, MinimumOSVersion 17.0, and the simulator ran it and returned its status 7"

      - name: the rule declared its own compiler
        working-directory: tests/spirv-consumer
        run: |
          set -e
          if grep -qE '^\[(target\..*\.)?xlings\.workspace\]' mcpp.toml; then
            echo "FAIL: the fixture declares payloads itself"; exit 1
          fi
          # `mcpp self env > file`, not `mcpp self env | awk`. Measured on
          # macos-15: through a pipe whose reader exits at the first match,
          # mcpp died with `internal: unhandled exception: failed to write
          # formatted output` and exit 70. A file has no reader to disappear.
          "$MCPP" self env > env.txt
          HOME_DIR=$(awk -F'= *' '/^MCPP_HOME/{print $2; exit}' env.txt)
          test -n "$HOME_DIR" || { echo "FAIL: mcpp self env named no MCPP_HOME"; cat env.txt; exit 1; }
          rm -rf "$HOME_DIR/provisioned" target
          "$MCPP" build > prov.log 2>&1
          grep -q 'entries declared by dependencies' prov.log || {
            echo "FAIL: no payload came from the graph"
            grep -i provisioning prov.log || echo "(no provisioning line at all)"
            exit 1; }
          echo "ok: $(grep -m1 'entries declared by dependencies' prov.log)"