feat(pack): ship a library as interface + prebuilt binaries (#433)

.github/actions/bootstrap-mcpp/action.yml

@@ -25,7 +25,7 @@ inputs:
     # `package.name`, so one of the two was simply unreachable — and which one
     # depended on the machine, which is why CI failed on `compat:lua` on
     # Windows and `mcpplibs.capi:lua` on Linux. Never pin below that.
-    default: '2026.8.11.2'
+    default: '2026.8.17.2'
   cache-target:
     description: also restore/save target/ (build artifacts + BMIs)
     required: false

.github/actions/setup-macos-llvm/action.yml

@@ -15,7 +15,7 @@ inputs:
     # Floor imposed by the index, not a routine bump — see
     # .github/actions/bootstrap-mcpp/action.yml for why 0.4.69 is required
     # (two packages named `lua` in one repo need openxlings/xlings#381).
-    default: '2026.8.11.2'
+    default: '2026.8.17.2'
 
 runs:
   using: composite

.github/workflows/bootstrap-macos.yml

@@ -17,7 +17,7 @@ jobs:
       # Dormant (workflow_dispatch only), but kept in step with the rest —
       # check_version_pins.sh holds it there. Floor: 0.4.69, below which the
       # index cannot resolve two packages that share a short name.
-      XLINGS_VERSION: '2026.8.11.2'
+      XLINGS_VERSION: '2026.8.17.2'
     steps:
       - uses: actions/checkout@v4
 

.github/workflows/ci-fresh-install.yml

@@ -152,7 +152,7 @@ jobs:
         env:
           XLINGS_NON_INTERACTIVE: '1'
         run: |
-          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.8.11.2
+          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.8.17.2
           echo "$HOME/.xlings/subos/current/bin" >> "$GITHUB_PATH"
 
       - name: Install mcpp and config mirror
@@ -293,7 +293,7 @@ jobs:
 
       - name: Install xlings + mcpp
         run: |
-          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.8.11.2
+          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.8.17.2
           # Deliberately NOT writing to $GITHUB_PATH here. On container
           # images that declare no PATH in their config (opensuse/
           # tumbleweed), appending a single dir to GITHUB_PATH makes the
@@ -364,7 +364,7 @@ jobs:
           #             (older ones carry minos=15 and refuse to start).
           #   v0.4.51+: in-process sha256 — this image has no sha256sum
           #             binary, so pinned fetches failed before it.
-          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.8.11.2
+          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.8.17.2
           echo "$HOME/.xlings/subos/current/bin" >> "$GITHUB_PATH"
 
       - name: Install mcpp and config mirror

.github/workflows/ci-linux-e2e.yml

@@ -63,6 +63,11 @@ jobs:
           # Point the e2e runner at the freshly-built binary, not the
           # bootstrap one. Tests cd into mktemp -d, so $MCPP must be
           # absolute or the relative path breaks under the temp cwd.
+          # The RELEASED mcpp this job bootstrapped from, kept for e2e 252: the
+          # claim that an older client can still build against a package the PR
+          # produces is only worth making if something checks it against a real
+          # old binary. Captured before $MCPP is repointed at the fresh build.
+          export MCPP_BOOT="$MCPP"
           MCPP=$(realpath "$(find target -type f -name mcpp -printf '%T@ %p\n' | sort -rn | head -1 | cut -d' ' -f2)")
           test -x "$MCPP"
           export MCPP
@@ -133,7 +138,7 @@ jobs:
 
       - name: Bootstrap xlings + released mcpp
         run: |
-          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.8.11.2
+          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.8.17.2
           export PATH="$HOME/.xlings/subos/current/bin:$PATH"
           xlings update
           xlings install mcpp -y -g

.github/workflows/ci-macos-e2e.yml

@@ -41,6 +41,11 @@ jobs:
         # Per-test 600s timeout lives in run_all.sh.
         timeout-minutes: 25
         run: |
+          # The RELEASED mcpp this job bootstrapped from, kept for e2e 252: the
+          # claim that an older client can still build against a package the PR
+          # produces is only worth making if something checks it against a real
+          # old binary. Captured before $MCPP is repointed at the fresh build.
+          export MCPP_BOOT="$MCPP"
           MCPP=$(find target -path "*/bin/mcpp" | head -1)
           MCPP=$(cd "$(dirname "$MCPP")" && pwd)/$(basename "$MCPP")
           test -x "$MCPP"

.github/workflows/ci-windows-e2e.yml

@@ -57,12 +57,44 @@ jobs:
           "$MCPP_SELF" --version
           echo "MCPP_SELF=$MCPP_SELF" >> "$GITHUB_ENV"
 
+      # MinGW-w64 GCC (xim:mingw-gcc). Installed here so the `mingw` capability
+      # is GRANTED rather than left to whatever the shared sandbox cache happens
+      # to carry: e2e 256 packs an MSVC leg and a MinGW leg into one package,
+      # which is the only place `lib/` keyed by triple is proven with two
+      # DIFFERENT artifact names (mathkit.lib beside libmathkit.a). Without this
+      # step that test skips, and a skipped test in a green suite reads exactly
+      # like a passing one.
+      #
+      # Not `|| true`: if the payload cannot be installed the capability quietly
+      # disappears and the coverage goes with it, which is the failure mode this
+      # step exists to prevent.
+      - name: "Toolchain: MinGW payload for the fat-package e2e"
+        shell: bash
+        run: |
+          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
+          "$MCPP_SELF" toolchain install mingw 16.1.0
+          # Verified through the SAME two locations run_all.sh probes — checking
+          # only one of them would let the step pass while the capability stays
+          # ungranted, which is the shape of a green run that tested nothing.
+          found=""
+          for c in "${MCPP_HOME:-$HOME/.mcpp}"/registry/data/xpkgs/xim-x-mingw-gcc/*/bin/g++.exe \
+                   "$HOME"/.xlings/data/xpkgs/xim-x-mingw-gcc/*/bin/g++.exe; do
+            [[ -x "$c" ]] && { found="$c"; break; }
+          done
+          test -n "$found" || { echo "FAIL: mingw installed but not where run_all.sh looks"; exit 1; }
+          echo "mingw payload: $found"
+
       - name: E2E suite
         shell: bash
         # Fail-fast on hung tests instead of burning the whole job budget.
         # Per-test 600s timeout lives in run_all.sh.
         timeout-minutes: 25
         run: |
+          # The RELEASED mcpp this job bootstrapped from, kept for e2e 252: the
+          # claim that an older client can still build against a package the PR
+          # produces is only worth making if something checks it against a real
+          # old binary. Captured before $MCPP is repointed at the fresh build.
+          export MCPP_BOOT="${MCPP:-$MCPP_BOOT}"
           export MCPP="$MCPP_SELF"
           export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
           export MCPP_E2E_TOOLCHAIN_MIRROR=GLOBAL

.github/workflows/cross-build-test.yml

@@ -34,6 +34,10 @@ name: cross-build-test
 # qemu-aarch64 is the CI proxy for "does this cross artefact actually execute".
 #
 # ── NOT here ───────────────────────────────────────────────────────────────
+#   * The e2e scripts this job names explicitly (102, 198, 240, 248) are the
+#     ones the ordinary Linux shards SKIP for want of `mingw-cross`. They are
+#     listed in the job rather than left to run_all's cap gating precisely so
+#     they cannot end up skipping everywhere at once.
 #   * Same-arch builds (host arch == target arch) are NOT cross. The native musl
 #     static build `--target x86_64-linux-musl` (x86_64 host) is exercised by
 #     ci-linux.yml's "Toolchain: musl-gcc" step, and release.yml for the static
@@ -118,7 +122,7 @@ jobs:
           # release assets were uploaded in a broken state (records present,
           # blobs missing → 404 on GET); re-uploaded clean. The stale-INDEX
           # half is handled by the marker-clear below.
-          XLINGS_VERSION: '2026.8.11.2'
+          XLINGS_VERSION: '2026.8.17.2'
         run: |
           tarball="xlings-${XLINGS_VERSION}-linux-x86_64.tar.gz"
           bash "$GITHUB_WORKSPACE/.github/tools/fetch_release.sh" \
@@ -256,7 +260,7 @@ jobs:
       - name: Bootstrap mcpp via xlings
         env:
           XLINGS_NON_INTERACTIVE: '1'
-          XLINGS_VERSION: '2026.8.11.2'
+          XLINGS_VERSION: '2026.8.17.2'
         run: |
           tarball="xlings-${XLINGS_VERSION}-linux-x86_64.tar.gz"
           bash "$GITHUB_WORKSPACE/.github/tools/fetch_release.sh" \
@@ -320,6 +324,23 @@ jobs:
           export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
           bash tests/e2e/240_pack_pe_zip_cross.sh
 
+      # A LIBRARY package whose legs cross an OS boundary, for the same reason
+      # as the three above: this is the only job with a MinGW cross toolchain.
+      #
+      # It is not redundant with 245 (which covers the fat-package mechanism
+      # with gnu + musl and therefore runs on every ordinary Linux shard). The
+      # leg added here changes BINARY FORMAT, and it is the case that proves
+      # `lib/` has to be keyed by triple rather than by OS: MinGW and MSVC are
+      # both "windows" and write `libfoo.a` and `foo.lib` respectively.
+      #
+      # Without this step the test would carry `# requires: mingw-cross` and
+      # skip in every job that exists — verified on a developer's machine and
+      # nowhere else, while the suite reported green.
+      - name: "e2e: pack a library across an OS boundary (PE leg)"
+        run: |
+          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
+          bash tests/e2e/248_pack_library_fat_pe_leg.sh
+
   # ── windows → linux ───────────────────────────────────────────────────────
   # The mirror of mingw-cross-wine. Two jobs because a Windows runner cannot
   # execute the ELF it produces; the artefact is handed to a Linux job and

.github/workflows/release.yml

@@ -96,7 +96,7 @@ jobs:
           # Pin xlings to a known-good version. The upstream install
           # script always grabs `latest` (no version override), so we
           # download + self-install manually to avoid broken releases.
-          XLINGS_VERSION: '2026.8.11.2'
+          XLINGS_VERSION: '2026.8.17.2'
         run: |
           if [ ! -x "$HOME/.xlings/subos/default/bin/xlings" ]; then
             tarball="xlings-${XLINGS_VERSION}-linux-x86_64.tar.gz"
@@ -289,7 +289,7 @@ jobs:
       - name: Bootstrap mcpp via xlings
         env:
           XLINGS_NON_INTERACTIVE: '1'
-          XLINGS_VERSION: '2026.8.11.2'
+          XLINGS_VERSION: '2026.8.17.2'
         run: |
           tarball="xlings-${XLINGS_VERSION}-linux-x86_64.tar.gz"
           bash "$GITHUB_WORKSPACE/.github/tools/fetch_release.sh" \
@@ -360,7 +360,7 @@ jobs:
           # below are pinned to the same version as XLINGS_VERSION; they are
           # NOT interpolated from it, so check_version_pins.sh scans for them
           # explicitly (they were absent from the old lock-step comment).
-          XLA="xlings-2026.8.11.2-linux-aarch64.tar.gz"
+          XLA="xlings-2026.8.17.2-linux-aarch64.tar.gz"
           # NOT fetch_release.sh: this asset is OPTIONAL and the `if` is the
           # point — an arch with no prebuilt xlings must fall through quietly,
           # while the helper retries a 404 five times before giving up. The one
@@ -369,9 +369,9 @@ jobs:
           # cover it.
           if curl -fsSL --retry 3 --retry-delay 2 --retry-all-errors \
                --connect-timeout 20 --max-time 600 -o "/tmp/$XLA" \
-               "https://github.com/openxlings/xlings/releases/download/v2026.8.11.2/$XLA"; then
+               "https://github.com/openxlings/xlings/releases/download/v2026.8.17.2/$XLA"; then
             tar -xzf "/tmp/$XLA" -C /tmp
-            XLBIN=$(find /tmp/xlings-2026.8.11.2-linux-aarch64 -path '*/bin/xlings' -type f | head -1)
+            XLBIN=$(find /tmp/xlings-2026.8.17.2-linux-aarch64 -path '*/bin/xlings' -type f | head -1)
             if [ -n "$XLBIN" ]; then
               mkdir -p "$STAGING/$WRAPPER/registry/bin"
               cp "$XLBIN" "$STAGING/$WRAPPER/registry/bin/xlings"
@@ -449,7 +449,7 @@ jobs:
       - name: Bootstrap mcpp via xlings
         env:
           XLINGS_NON_INTERACTIVE: '1'
-          XLINGS_VERSION: '2026.8.11.2'
+          XLINGS_VERSION: '2026.8.17.2'
         run: |
           if [ ! -x "$HOME/.xlings/subos/default/bin/xlings" ]; then
             WORK=$(mktemp -d)
@@ -632,7 +632,7 @@ jobs:
         shell: bash
         env:
           XLINGS_NON_INTERACTIVE: '1'
-          XLINGS_VERSION: '2026.8.11.2'
+          XLINGS_VERSION: '2026.8.17.2'
         run: |
           # Captured before the `cd` below, in POSIX form: this step never
           # returns to the workspace, and GITHUB_WORKSPACE is a backslash