ci: pin mcpp 2026.8.25.1 (#9)

* ci: pin the build tool this package was released against

The pin was several releases behind, so what CI validated was not what
the ecosystem resolves. 2026.8.24.6 is the version this package's
current contents were released alongside — openkal 0.7.0 and the
implementations that follow it.

A version verified to build this package, not a measured minimum: the
pin exists for reproducibility rather than because an older mcpp is
known to fail.

* ci: pin 2026.8.25.1 — the release that fixes what 2026.8.24.6 broke

* ci: validate against the mcpp under review, before it is released

Several mcpp releases went out green and only then turned this ecosystem
red. The engine's own CI cannot see a defect that appears only in a real
dependency graph, and this repository could not see the engine until it had
been published — so the first place the two met was after the release.

`MCPP_SOURCE_REF` (a workflow_dispatch input, or a repository variable)
names a branch of mcpp-community/mcpp. When set, every job builds that
source with the released mcpp as bootstrap and puts the result first on
PATH; when empty the job tests the released pin exactly as before.

Also re-pins to 2026.8.25.2, which fixes what this repository last failed on.

* ci: bootstrap from the index when validating an unreleased mcpp

The pin may name the very release the run is validating, which does not
exist yet — that is what MCPP_SOURCE_REF is for. Bootstrap from whatever
the index has; the build under review replaces it a step later.

* ci: the clone's workspace pin does not decide which mcpp builds it

`.xlings.json` at mcpp's root pins the mcpp that compiles mcpp, and that
pin does not move when mcpp is released — a build inside the checkout obeys
it and installs a version the index may no longer carry. What this step
wants is the source compiled by the mcpp installed a moment earlier.

* ci: note why the fresh clone needs no mtime sort

The mcpp side of this cross-validation had to sort by mtime — its target/
is restored from a cache and `find … | head -1` returned a binary an
earlier push had left, with the right version string and the wrong code.
Here $src is a fresh clone, so the plain form is correct; `-printf` is a
GNU extension and one of the runners reaching this line is macOS.

* ci: find the built mcpp by either spelling, on every runner

The matrix reaches Windows and macOS. Measured on the Windows row:
`Finished release [optimized] in 173.44s` followed by "mcpp did not
build" — the build had succeeded and the search was looking for a name
that filesystem does not use.

Author: Sunrisepeak

.github/workflows/ci.yml

@@ -19,9 +19,14 @@ on:
     branches: [main]
   pull_request:
   workflow_dispatch:
-
+    inputs:
+      mcpp_ref:
+        description: "Branch of mcpp-community/mcpp to build and test against (empty = the released pin)"
+        required: false
+        default: ""
 env:
-  MCPP_VERSION: 2026.8.19.4
+  MCPP_SOURCE_REF: ${{ github.event.inputs.mcpp_ref || vars.MCPP_SOURCE_REF }}
+  MCPP_VERSION: 2026.8.25.2
   XLINGS_VERSION: v2026.8.17.2
   XLINGS_NON_INTERACTIVE: '1'
 
@@ -68,9 +73,67 @@ jobs:
       - name: Install mcpp
         run: |
           xlings update
-          xlings install "mcpp@$MCPP_VERSION" -y -g
+          # ⚠️ THE PIN MAY NAME THE RELEASE THIS RUN IS VALIDATING, which does
+          # not exist yet — that is the whole point of MCPP_SOURCE_REF. Bootstrap
+          # from whatever the index has; the step below replaces it with the
+          # build under review, and the pin is what an ordinary run tests.
+          if [ -n "${MCPP_SOURCE_REF:-}" ]; then
+            xlings install mcpp -y -g
+          else
+            xlings install "mcpp@$MCPP_VERSION" -y -g
+          fi
           mcpp --version
           mcpp self config --mirror GLOBAL
+          # ⭐⭐ CROSS-VALIDATION: BUILD THE mcpp UNDER REVIEW AND USE THAT ONE.
+          #
+          # Empty in the ordinary run, so this job keeps testing the RELEASED
+          # mcpp the pin above names. Set it — `workflow_dispatch` input, or the
+          # repository variable — and the same job runs against that source.
+          #
+          # ⚠️ THIS EXISTS BECAUSE THE ORDER USED TO BE WRONG. Several mcpp
+          # releases went out green and only then turned this ecosystem red: the
+          # engine's own CI cannot see a defect that appears only in a real
+          # dependency graph, and this repository could not see the engine until
+          # it had been published. Validating before the release closes that gap.
+          #
+          # The released mcpp installed just above is the bootstrap that compiles
+          # it; mcpp builds itself and there is no other compiler for it here.
+          if [ -n "${MCPP_SOURCE_REF:-}" ]; then
+            src="$RUNNER_TEMP/mcpp-src"
+            [ -d "$src" ] || git clone --quiet --depth 1 \
+              --branch "$MCPP_SOURCE_REF" \
+              https://github.com/mcpp-community/mcpp.git "$src"
+            # ⚠️ THE CLONE'S OWN WORKSPACE PIN MUST NOT DECIDE WHICH mcpp
+            # BUILDS IT. `.xlings.json` at mcpp's root pins the mcpp that
+            # compiles mcpp, and that pin does not move when mcpp is released —
+            # so a build inside the checkout obeys it and tries to install a
+            # version the index may no longer carry:
+            #
+            #     [error] xlings: version '2026.8.17.1' not found for 'mcpp'
+            #       available: 2026.8.25.1
+            #
+            # What is wanted here is the source compiled by the mcpp installed
+            # above, which is exactly what removing the file leaves.
+            rm -f "$src/.xlings.json"
+            ( cd "$src" && mcpp build --release )
+            # ⚠️ BOTH SPELLINGS, AND NO `-perm`. The matrix reaches Windows and
+            # macOS runners too: on Windows the artefact is `mcpp.exe`, and
+            # `-perm -u+x` is not a question that filesystem answers the way this
+            # expects. Measured: `Finished release [optimized] in 173.44s`
+            # followed by "mcpp did not build" — the build had succeeded and the
+            # search was looking for the wrong name.
+            #
+            # `$src` is a FRESH clone each run, so `target/` holds exactly what
+            # this step just built; `-printf` would be the safer form on a cached
+            # tree and is a GNU extension this must not use.
+            built=$(find "$src/target" -type f \
+                    \( -name mcpp -o -name mcpp.exe \) | head -1)
+            [ -n "$built" ] || { echo "::error::mcpp did not build from $MCPP_SOURCE_REF"; exit 1; }
+            echo "$(cd "$(dirname "$built")" && pwd)" >> "$GITHUB_PATH"
+            # ⚠️ Reported, because a PATH entry that does not win looks exactly
+            # like one that does until something built with the wrong engine.
+            echo "under review: $("$built" --version)  (from $MCPP_SOURCE_REF)"
+          fi
 
       - name: Select the toolchain
         run: |
@@ -138,8 +201,66 @@ jobs:
       - name: Install mcpp
         run: |
           xlings update
-          xlings install "mcpp@$MCPP_VERSION" -y -g
+          # ⚠️ THE PIN MAY NAME THE RELEASE THIS RUN IS VALIDATING, which does
+          # not exist yet — that is the whole point of MCPP_SOURCE_REF. Bootstrap
+          # from whatever the index has; the step below replaces it with the
+          # build under review, and the pin is what an ordinary run tests.
+          if [ -n "${MCPP_SOURCE_REF:-}" ]; then
+            xlings install mcpp -y -g
+          else
+            xlings install "mcpp@$MCPP_VERSION" -y -g
+          fi
           mcpp self config --mirror GLOBAL
+          # ⭐⭐ CROSS-VALIDATION: BUILD THE mcpp UNDER REVIEW AND USE THAT ONE.
+          #
+          # Empty in the ordinary run, so this job keeps testing the RELEASED
+          # mcpp the pin above names. Set it — `workflow_dispatch` input, or the
+          # repository variable — and the same job runs against that source.
+          #
+          # ⚠️ THIS EXISTS BECAUSE THE ORDER USED TO BE WRONG. Several mcpp
+          # releases went out green and only then turned this ecosystem red: the
+          # engine's own CI cannot see a defect that appears only in a real
+          # dependency graph, and this repository could not see the engine until
+          # it had been published. Validating before the release closes that gap.
+          #
+          # The released mcpp installed just above is the bootstrap that compiles
+          # it; mcpp builds itself and there is no other compiler for it here.
+          if [ -n "${MCPP_SOURCE_REF:-}" ]; then
+            src="$RUNNER_TEMP/mcpp-src"
+            [ -d "$src" ] || git clone --quiet --depth 1 \
+              --branch "$MCPP_SOURCE_REF" \
+              https://github.com/mcpp-community/mcpp.git "$src"
+            # ⚠️ THE CLONE'S OWN WORKSPACE PIN MUST NOT DECIDE WHICH mcpp
+            # BUILDS IT. `.xlings.json` at mcpp's root pins the mcpp that
+            # compiles mcpp, and that pin does not move when mcpp is released —
+            # so a build inside the checkout obeys it and tries to install a
+            # version the index may no longer carry:
+            #
+            #     [error] xlings: version '2026.8.17.1' not found for 'mcpp'
+            #       available: 2026.8.25.1
+            #
+            # What is wanted here is the source compiled by the mcpp installed
+            # above, which is exactly what removing the file leaves.
+            rm -f "$src/.xlings.json"
+            ( cd "$src" && mcpp build --release )
+            # ⚠️ BOTH SPELLINGS, AND NO `-perm`. The matrix reaches Windows and
+            # macOS runners too: on Windows the artefact is `mcpp.exe`, and
+            # `-perm -u+x` is not a question that filesystem answers the way this
+            # expects. Measured: `Finished release [optimized] in 173.44s`
+            # followed by "mcpp did not build" — the build had succeeded and the
+            # search was looking for the wrong name.
+            #
+            # `$src` is a FRESH clone each run, so `target/` holds exactly what
+            # this step just built; `-printf` would be the safer form on a cached
+            # tree and is a GNU extension this must not use.
+            built=$(find "$src/target" -type f \
+                    \( -name mcpp -o -name mcpp.exe \) | head -1)
+            [ -n "$built" ] || { echo "::error::mcpp did not build from $MCPP_SOURCE_REF"; exit 1; }
+            echo "$(cd "$(dirname "$built")" && pwd)" >> "$GITHUB_PATH"
+            # ⚠️ Reported, because a PATH entry that does not win looks exactly
+            # like one that does until something built with the wrong engine.
+            echo "under review: $("$built" --version)  (from $MCPP_SOURCE_REF)"
+          fi
 
       - name: Every interface, every kind of examination
         env: