ci.yml

name: ci

on:
  push:
    branches: [main]
  pull_request:
  workflow_dispatch:

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.
  MCPP_VERSION: 2026.9.11.2
  # 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.
    timeout-minutes: 90
    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 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
          grep -q '^scale.slang: magic=07230203' 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"

      # 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"

      # 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 }}
    timeout-minutes: 60
    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"

      # 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
          # WiX ships through NuGet and is not redistributable through this
          # ecosystem, which is why the member LOCATES it rather than declaring
          # a payload. Installing it here is the CI runner supplying what a
          # developer's machine would.
          # WiX 6, PINNED, AND THE PIN IS THE WHOLE POINT.
          #
          # An unpinned `dotnet tool install wix` gets v7, which REFUSES TO RUN
          # AT ALL until a licence is accepted out of band. Measured on
          # windows-2022:
          #
          #   wix.exe : error WIX7015: You must accept the Open Source
          #   Maintenance Fee (OSMF) EULA to use WiX Toolset v7.
          #
          # That is a runtime gate, not a licence term about redistribution: 6's
          # own EULA states that binaries may be redistributed and that the
          # source remains freely distributable under the Microsoft Reciprocal
          # License. So 6 is the version this ecosystem can actually drive, and
          # it is also the version `xim:wix` should carry when that package
          # lands -- a package pinning 7 would install a tool that cannot run.
          #
          # THE DISPATCH WAS ALREADY CORRECT WHEN THIS FAILED, which is worth
          # recording because it is why the fix is a version pin and not a code
          # change. The same run reported
          #
          #   Distributing msi-consumer v0.3.0 (--format msi)
          #   wix.exe build -arch x64 -d Executable=bin/msi-consumer.exe -o ... MsiConsumer.wxs
          #
          # so the `.wxs` was rendered, the argv was assembled and the engine
          # handed the request to the member. Only the tool declined.
          dotnet tool install --global wix --version 6.0.2 >/dev/null 2>&1 \
            || dotnet tool update --global wix --version 6.0.2 >/dev/null 2>&1
          export PATH="$PATH:$HOME/.dotnet/tools"
          wix --version

          # 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 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"

      - 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"
          echo "ok: one bundle, a valid plist, and it launches"

      - 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)"