README policy, release-index vocabulary sync, magnus boot-smoke gate

.github/workflows/_build-platform.yml

@@ -938,6 +938,12 @@ jobs:
           # copied out to the host-visible .build/smoke-{headers,tools}
           # (host legs read the stash in place; a mkdwarfs miss is not
           # fatal — the fixture falls back to tfs when one resolves).
+          # The stash copy names the leg's EXACT version: the image bakes
+          # an older generation's stash beside this leg's, and a stash_*
+          # merge lands both ruby-<abi> trees in smoke-headers — the
+          # alphabetical ruby-* glob then picks the wrong one (the 4.0.7
+          # container legs compiled against 3.3 headers). The rm -rf makes
+          # the populate idempotent against any earlier content.
           # The pin-verified tfs CLI cache (downloads/tfs/<sha>/tfs-*)
           # is copied out too — the spawn-edge acceptance gate below runs
           # on the HOST (or in a fresh alpine for musl) and presses its
@@ -977,8 +983,9 @@ jobs:
             PATH="/opt/cargo/bin:$PATH" /mnt/w/tools/build_runtime --ruby "${{ matrix.ruby.version }}" --output "/mnt/w/runtime-packages/$runtime" \
             --prefix /root/.build --src-mirror file:///mnt/w/.build/spec22-src-roll --src-release spec22-chain \
             ${{ matrix.env.os == 'linux-gnu' && '--patchelf' || '' }} && \
+            rm -rf /mnt/w/.build/smoke-headers && \
             mkdir -p /mnt/w/.build/smoke-headers /mnt/w/.build/smoke-tools /mnt/w/.build/downloads/tfs && \
-            cp -a /root/.build/deps/stash_*/include/. /mnt/w/.build/smoke-headers/ && \
+            cp -a /root/.build/deps/stash_${{ matrix.ruby.version }}/include/. /mnt/w/.build/smoke-headers/ && \
             cp -a /root/.build/downloads/tfs/. /mnt/w/.build/downloads/tfs/ && \
             { cp -a /root/.build/deps/bin/mkdwarfs /mnt/w/.build/smoke-tools/ 2>/dev/null || true; }'; then
             echo "::warning::build failed — dumping ext extconf probe logs"
@@ -1667,6 +1674,14 @@ jobs:
           TEBAKO_SMOKE_EXPECT_OPENSSL: ok
         run: |
           set -euo pipefail
+          # The magnus fixture gate (issue #192) compiles a magnus
+          # extension in-leg: rb-sys's bindgen loads libclang at build
+          # time. The ubuntu images carry clang toolchains but not
+          # reliably the libclang shared library; macOS legs resolve the
+          # selected Xcode's. cargo is the runner's rustup toolchain.
+          if [ "${{ matrix.env.os }}" = "linux-gnu" ] && ! ldconfig -p | grep -q libclang; then
+            sudo apt-get update -qq && sudo apt-get install -y -qq libclang-dev
+          fi
           bundle install --jobs 4 --retry 3
           bundle exec rspec --tag boot_smoke --format documentation
 
@@ -1695,11 +1710,30 @@ jobs:
           docker run --rm -v ${{ github.workspace }}:/mnt/w -w /mnt/w \
             -e TEBAKO_RUNTIME_ROOT \
             -e TEBAKO_SMOKE_EXPECT_OPENSSL \
+            -e RUST_VERSION="${{ needs.compute.outputs.rust-version }}" \
+            -e RUSTUP_HOME=/opt/rustup \
+            -e CARGO_HOME=/opt/cargo \
             alpine:3.21 sh -c '
               set -e
               # git: the Gemfile pins tebako-release from its git
               # tag (contract.yml release_tooling) — bundler shell-outs.
-              apk add --no-cache ruby ruby-dev build-base ruby-bundler git >/dev/null
+              # curl/bash/ca-certificates + clang19-libclang: the magnus
+              # fixture gate (issue #192) compiles a magnus extension
+              # in-leg — rustup installs the ecosystem pin (flowed from
+              # compute exactly like the build legs) and rb-sys'"'"'s
+              # bindgen loads libclang at build time. RUSTUP_HOME/CARGO_HOME
+              # must RIDE the environment (the build legs do the same):
+              # prepare-rust-toolchain.sh'"'"'s exports die with its
+              # process, and without the pair the /opt/cargo/bin shim probes
+              # an empty $HOME/.rustup and names no default toolchain.
+              apk add --no-cache ruby ruby-dev build-base ruby-bundler git \
+                curl bash ca-certificates clang19-libclang >/dev/null
+              bash ci/prepare-rust-toolchain.sh
+              # bindgen dlopens libclang via clang-sys, whose probe list
+              # names the debian/llvm-config spellings — not alpine'"'"'s
+              # /usr/lib/llvm<N>/lib. Point it exactly (derived, never a
+              # second literal of the llvm version).
+              export LIBCLANG_PATH="$(dirname "$(find /usr/lib -name libclang.so | head -1)")"
               bundle install --jobs 4 --retry 3
               bundle exec rspec --tag boot_smoke --format documentation'
 
@@ -1718,6 +1752,34 @@ jobs:
           TEBAKO_SMOKE_EXPECT_OPENSSL: ok
         run: |
           set -euo pipefail
+          # The magnus fixture gate (issue #192) compiles a magnus
+          # extension in-leg against the leg's stashed headers + the build
+          # tree's import lib. The runner's rustup defaults to MSVC — the
+          # runtime is ucrt64 (mingw), so the fixture builds for the gnu
+          # target whose link model matches; rb-sys's bindgen loads
+          # libclang (the runner image's VS2022 Clang tools carry it, the
+          # ucrt64 clang package is the fallback).
+          # The image's rustup/cargo are windows-native under the profile's
+          # .cargo/bin — a dir the msys2 shell does NOT inherit on PATH
+          # (the first round's windows legs 127'd on exactly this).
+          # Resolve it by its canonical home and fail by name if the image
+          # moved it. Only the ucrt64 (x86_64) legs run the fixture's
+          # gnu-target build — windows/arm64 fails closed by design before
+          # any cargo call, so no target add there.
+          cargo_bin="$(cygpath -u "${CARGO_HOME:-$USERPROFILE/.cargo}/bin")"
+          [ -x "$cargo_bin/cargo.exe" ] || { echo "::error::no windows-native cargo at $cargo_bin — the runner image's rust toolchain moved"; exit 1; }
+          export PATH="$cargo_bin:$PATH"
+          if [ "$(uname -m)" = "x86_64" ]; then
+            rustup target add x86_64-pc-windows-gnu
+          fi
+          vs_libclang="/c/Program Files/Microsoft Visual Studio/2022/Enterprise/VC/Tools/Llvm/x64/bin"
+          if [ -e "$vs_libclang/libclang.dll" ]; then
+            # clang-sys runs in the windows-native cargo process — the env
+            # value must be a WINDOWS path, not this shell's /c/ spelling.
+            export LIBCLANG_PATH='C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Tools\Llvm\x64\bin'
+          else
+            pacman -S --needed --noconfirm mingw-w64-ucrt-x86_64-clang >/dev/null
+          fi
           gem install bundler --no-document
           bundle install --jobs 4 --retry 3
           bundle exec rspec --tag boot_smoke --format documentation

.github/workflows/bump-source-pin.yml

@@ -25,6 +25,13 @@ on:
       tag:
         description: "tamatebako/ruby source release tag (e.g. v0.2.9)"
         required: true
+      dry_run:
+        description: "Compute and report the bump (pin move + vocabulary delta) from the published release indexes; never writes, pushes, or opens a PR"
+        type: boolean
+        default: false
+      from_tag:
+        description: "Dry-run only: compute the bump FROM this tag instead of the checkout's current pin (historical-bump replays)"
+        required: false
 
 permissions:
   contents: write
@@ -40,7 +47,37 @@ jobs:
         with:
           token: ${{ secrets.TEBAKO_CI_PAT_TOKEN || secrets.GITHUB_TOKEN }}
 
+      # The dry-run: compute the whole bump from the two published release
+      # indexes (pin move + vocabulary delta) and report it — nothing is
+      # written, pushed, or opened. This is the "adding a version to the
+      # source factory's release flows to the factory matrix with zero
+      # manual edits" demonstration, safe to run for any tag pair.
+      - name: Dry-run report (no writes, no push, no PR)
+        if: inputs.dry_run
+        env:
+          TAG: ${{ github.event.client_payload.tag || inputs.tag }}
+          FROM_TAG: ${{ inputs.from_tag }}
+        run: |
+          set -euo pipefail
+          file="build/lib/tebako_runtime_builder/source_fetcher.rb"
+          case "$TAG" in
+            v[0-9]*) ;;
+            *) echo "::error::unexpected tag '$TAG'"; exit 1 ;;
+          esac
+          current="${FROM_TAG:-$(grep -oE 'DEFAULT_RELEASE = "[^"]+"' "$file" | cut -d'"' -f2)}"
+          {
+            echo "### Pin bump dry-run: $current -> $TAG"
+            echo ""
+            echo "- pin: \`DEFAULT_RELEASE\` in \`$file\` would move \`$current\` -> \`$TAG\`"
+            echo "- vocabulary sync (published SHA256SUMS indexes of both releases):"
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+          ruby tools/sync_matrix_vocabulary.rb "$current" "$TAG" --dry-run | tee -a "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+          echo "(dry-run: the checkout is untouched, no branch is pushed, no PR is opened)" >> "$GITHUB_STEP_SUMMARY"
+
       - name: bump the pin
+        if: ${{ !inputs.dry_run }}
         id: bump
         env:
           TAG: ${{ github.event.client_payload.tag || inputs.tag }}
@@ -74,17 +111,19 @@ jobs:
       # (matrix.json ruby.catalog/full/tidy) in the SAME commit, or a
       # catalog/full/tidy coordinator dispatch silently misses the new
       # ruby (the 4.0.7 gap: #182 landed the source, the vocabulary still
-      # stopped at 4.0.6). The script runs in DELTA mode: only versions
-      # the bump newly offers are admitted -- backfills the factory
-      # deliberately skipped stay skipped.
+      # stopped at 4.0.6). The tool reads each tag's PUBLISHED index (the
+      # release's SHA256SUMS asset — releases are the interface, never the
+      # repository tree) and runs in DELTA mode: only versions the bump
+      # newly offers are admitted -- backfills the factory deliberately
+      # skipped stay skipped.
       - name: Setup Ruby
-        if: steps.bump.outputs.changed == 'true'
+        if: ${{ !inputs.dry_run && steps.bump.outputs.changed == 'true' }}
         uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
         with:
           ruby-version: 3.3
 
       - name: sync the dispatch vocabulary
-        if: steps.bump.outputs.changed == 'true'
+        if: ${{ !inputs.dry_run && steps.bump.outputs.changed == 'true' }}
         id: vocab
         env:
           GH_TOKEN: ${{ secrets.TEBAKO_CI_PAT_TOKEN || secrets.GITHUB_TOKEN }}
@@ -99,18 +138,12 @@ jobs:
             echo "summary=pin-only bump ($TAG not newer than $CURRENT), vocabulary untouched" >> "$GITHUB_OUTPUT"
             exit 0
           fi
-          gh api "repos/tamatebako/ruby/contents/versions.yml?ref=$CURRENT" \
-            -H "Accept: application/vnd.github.raw" > "$RUNNER_TEMP/versions-old.yml" \
-            || { echo "::error::cannot read versions.yml at $CURRENT -- a yanked source tag breaks the chain; fix the pin by hand"; exit 1; }
-          gh api "repos/tamatebako/ruby/contents/versions.yml?ref=$TAG" \
-            -H "Accept: application/vnd.github.raw" > "$RUNNER_TEMP/versions-new.yml" \
-            || { echo "::error::cannot read versions.yml at $TAG"; exit 1; }
-          ruby tools/sync_matrix_vocabulary.rb "$RUNNER_TEMP/versions-old.yml" "$RUNNER_TEMP/versions-new.yml" \
+          ruby tools/sync_matrix_vocabulary.rb "$CURRENT" "$TAG" \
             | tee "$RUNNER_TEMP/vocab.log"
           echo "summary=$(tail -1 "$RUNNER_TEMP/vocab.log")" >> "$GITHUB_OUTPUT"
 
       - name: push branch and open pull request
-        if: steps.bump.outputs.changed == 'true'
+        if: ${{ !inputs.dry_run && steps.bump.outputs.changed == 'true' }}
         env:
           GH_TOKEN: ${{ secrets.TEBAKO_CI_PAT_TOKEN || secrets.GITHUB_TOKEN }}
           TAG: ${{ github.event.client_payload.tag || inputs.tag }}