feat: converge template identity, runtime contracts, and release state

.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.8.1'
+    default: '2026.8.9.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.8.1'
+    default: '2026.8.9.2'
 
 runs:
   using: composite

.github/workflows/aur-publish.yml

@@ -1,102 +1,119 @@
 name: aur-publish
 
-# Publish the `mcpp-bin` and `mcpp` AUR packages after a release.
-#
-# Triggers on COMPLETION of the `release` workflow (not on `release:
-# published`): release.yml creates the GitHub Release in its first job but
-# uploads the aarch64 / macOS / Windows assets in LATER jobs, so the aarch64
-# .sha256 that mcpp-bin needs only exists once the whole workflow finishes.
-#
-# Requires one repository secret:
-#   AUR_SSH_PRIVATE_KEY — private key whose public half is registered on the
-#                         AUR account that owns mcpp / mcpp-bin.
-# See scripts/aur/README.md → "Automated publishing" for the full setup.
+# Reconcile only mcpp-bin.  This workflow is downstream of `release`, so its
+# failure is visible without changing the already-terminal release conclusion.
 on:
   workflow_run:
     workflows: [release]
     types: [completed]
+  schedule:
+    - cron: '17 */6 * * *'
   workflow_dispatch:
     inputs:
-      version:
-        description: "Version to publish (default: [package].version in mcpp.toml)"
+      publish:
+        description: 'Publish the validated diff (false performs a dry-run only)'
+        type: boolean
+        required: true
+        default: false
+      tag:
+        description: 'Optional exact latest complete stable tag (no downgrade override)'
+        type: string
         required: false
 
 concurrency:
-  group: aur-publish
+  group: aur-mcpp-bin-reconcile
   cancel-in-progress: false
 
+permissions:
+  contents: read
+
 jobs:
-  publish:
-    runs-on: ubuntu-latest
-    # On the workflow_run trigger, only proceed if the release actually
-    # succeeded (skip failed/cancelled release runs).
+  reconcile:
+    name: reconcile mcpp-bin
     if: >-
-      github.event_name == 'workflow_dispatch' ||
+      github.event_name != 'workflow_run' ||
       github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 60
+    env:
+      GH_TOKEN: ${{ github.token }}
+      PYTHONDONTWRITEBYTECODE: '1'
+      REQUESTED_TAG: ${{ inputs.tag }}
     steps:
-      - name: Checkout released commit
+      - name: Checkout reconciler source
         uses: actions/checkout@v4
         with:
-          # workflow_run: the exact commit the release was built from.
-          # workflow_dispatch: default ref (HEAD of the branch).
           ref: ${{ github.event.workflow_run.head_sha || github.ref }}
 
-      - name: Refresh both PKGBUILDs to the release version
-        id: refresh
+      - name: Reconciler contract tests
+        run: python3 tests/scripts/test_aur_reconcile.py
+
+      # This phase has no SSH private key in its environment.  It downloads the
+      # immutable manifest and both Linux payload/sidecars, recomputes hashes,
+      # runs makepkg as non-root in Arch, inspects RPC + HTTPS git, and emits the
+      # exact diff before any publishing secret is loaded.
+      - name: Inspect and validate desired state
+        id: plan
         env:
-          # CI runs as root; force update.sh's template .SRCINFO path.
-          MCPP_AUR_NO_MAKEPKG: "1"
+          TRIGGER: ${{ github.event_name }}
+          MANUAL_PUBLISH: ${{ inputs.publish }}
         run: |
-          VER="${{ github.event.inputs.version }}"
-          if [ -z "$VER" ]; then
-            # mcpp.toml at the released commit carries the right version.
-            VER=$(grep -m1 -E '^\s*version\s*=' mcpp.toml | sed -E 's/.*"([^"]+)".*/\1/')
+          args=(
+            --trigger "$TRIGGER"
+            --report-json "$RUNNER_TEMP/aur-plan.json"
+            --summary "$GITHUB_STEP_SUMMARY"
+          )
+          [[ -z "$REQUESTED_TAG" ]] || args+=(--tag "$REQUESTED_TAG")
+          python3 scripts/aur/reconcile_mcpp_bin.py "${args[@]}"
+
+          if [[ "$TRIGGER" == workflow_run || "$TRIGGER" == schedule ]]; then
+            publish=true
+          else
+            publish=${MANUAL_PUBLISH:-false}
           fi
-          echo "version=$VER" >> "$GITHUB_OUTPUT"
-          ./scripts/aur/update.sh "$VER"
+          echo "needs_publish=$(jq -r '.needs_publish' "$RUNNER_TEMP/aur-plan.json")" >> "$GITHUB_OUTPUT"
+          echo "publish=$publish" >> "$GITHUB_OUTPUT"
 
-      - name: Configure AUR SSH
+      - name: Configure pinned AUR SSH identity
+        if: steps.plan.outputs.needs_publish == 'true' && steps.plan.outputs.publish == 'true'
+        env:
+          AUR_SSH_PRIVATE_KEY: ${{ secrets.AUR_SSH_PRIVATE_KEY }}
         run: |
-          install -dm700 ~/.ssh
-          printf '%s\n' "${{ secrets.AUR_SSH_PRIVATE_KEY }}" > ~/.ssh/aur
-          chmod 600 ~/.ssh/aur
-          ssh-keyscan -t rsa,ed25519 aur.archlinux.org >> ~/.ssh/known_hosts 2>/dev/null
-          cat > ~/.ssh/config <<'EOF'
-          Host aur.archlinux.org
-            User aur
-            IdentityFile ~/.ssh/aur
-            IdentitiesOnly yes
-          EOF
+          test -n "$AUR_SSH_PRIVATE_KEY" || { echo 'AUR_SSH_PRIVATE_KEY is empty'; exit 1; }
+          install -dm700 "$HOME/.ssh"
+          install -m600 /dev/null "$HOME/.ssh/aur"
+          printf '%s\n' "$AUR_SSH_PRIVATE_KEY" > "$HOME/.ssh/aur"
+          install -m600 scripts/aur/aur.archlinux.org.known_hosts "$HOME/.ssh/known_hosts"
+          ssh-keygen -lf "$HOME/.ssh/known_hosts" -E sha256 \
+            | grep -F 'SHA256:RFzBCUItH9LZS0cKB5UE6ceAYhBD5C8GeOBip8Z11+4'
+          install -m600 /dev/null "$HOME/.ssh/config"
+          printf '%s\n' \
+            'Host aur.archlinux.org' \
+            '  User aur' \
+            '  IdentityFile ~/.ssh/aur' \
+            '  IdentitiesOnly yes' \
+            '  StrictHostKeyChecking yes' \
+            '  UserKnownHostsFile ~/.ssh/known_hosts' \
+            > "$HOME/.ssh/config"
 
-      - name: Push to the AUR
+      - name: Fast-forward publish and verify convergence
+        if: steps.plan.outputs.needs_publish == 'true' && steps.plan.outputs.publish == 'true'
         env:
-          VER: ${{ steps.refresh.outputs.version }}
+          TRIGGER: ${{ github.event_name }}
         run: |
-          set -eu
-          git config --global user.name  "mcpp-ci"
-          git config --global user.email "x.d2learn.org@gmail.com"
-
-          publish() {  # $1 = package name (= dir under scripts/aur/)
-            pkg="$1"; src="scripts/aur/${pkg}"; work="/tmp/aur-${pkg}"
-            # Clone the existing AUR repo; if the package doesn't exist yet
-            # (first publish), start an empty repo — AUR creates it on push.
-            if git clone "ssh://aur@aur.archlinux.org/${pkg}.git" "$work" 2>/dev/null \
-               && [ -e "$work/.git" ]; then :; else
-              rm -rf "$work"; mkdir -p "$work"
-              git -C "$work" init -q
-              git -C "$work" remote add origin "ssh://aur@aur.archlinux.org/${pkg}.git"
-            fi
-            # AUR repos contain only PKGBUILD, .SRCINFO and local sources.
-            cp "$src/PKGBUILD" "$src/.SRCINFO" "$src/mcpp.sh" "$work/"
-            git -C "$work" add -A
-            if git -C "$work" diff --cached --quiet; then
-              echo ":: ${pkg}: no changes, skipping"
-              return 0
-            fi
-            git -C "$work" commit -q -m "${pkg} ${VER}"
-            git -C "$work" push origin HEAD:master
-            echo ":: ${pkg}: published ${VER}"
-          }
+          args=(
+            --publish
+            --trigger "$TRIGGER"
+            --report-json "$RUNNER_TEMP/aur-final.json"
+            --summary "$GITHUB_STEP_SUMMARY"
+          )
+          [[ -z "$REQUESTED_TAG" ]] || args+=(--tag "$REQUESTED_TAG")
+          python3 scripts/aur/reconcile_mcpp_bin.py "${args[@]}"
 
-          publish mcpp-bin
-          publish mcpp-m
+      - name: Preserve reconciliation reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: aur-mcpp-bin-reconciliation
+          path: ${{ runner.temp }}/aur-*.json
+          if-no-files-found: error

.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.8.1'
+      XLINGS_VERSION: '2026.8.9.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.8.1
+          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.8.9.2
           echo "$HOME/.xlings/subos/current/bin" >> "$GITHUB_PATH"
 
       - name: Install mcpp and config mirror
@@ -179,11 +179,12 @@ jobs:
       # Template packages exercise the sha256-pinned mcpp-index fetch
       # path (user report: `mcpp new ... --template imgui` failed with
       # fetch 'imgui@0.0.6' exit 1 on hosts without a sha256sum binary).
-      - name: "Template: mcpp new --template imgui (fetch path)"
+      - name: "Template: exact mcpplibs.imgui selector (fetch path)"
         run: |
           cd "$(mktemp -d)"
-          mcpp new abc1 --template imgui
+          mcpp new abc1 --template mcpplibs.imgui 2>&1 | tee template.log
           test -f abc1/mcpp.toml
+          grep -F 'namespace=mcpplibs name=imgui' template.log
 
       - name: "Default: build mcpp"
         run: |
@@ -292,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.8.1
+          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.8.9.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
@@ -363,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.8.1
+          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.8.9.2
           echo "$HOME/.xlings/subos/current/bin" >> "$GITHUB_PATH"
 
       - name: Install mcpp and config mirror
@@ -391,11 +392,12 @@ jobs:
       # path — this is what broke on hosts without a sha256sum binary
       # (stock macOS / bare Windows) before xlings 0.4.51 hashed
       # in-process.
-      - name: "Template: mcpp new --template imgui (fetch path)"
+      - name: "Template: exact mcpplibs.imgui selector (fetch path)"
         run: |
           cd "$(mktemp -d)"
-          mcpp new abc1 --template imgui
+          mcpp new abc1 --template mcpplibs.imgui 2>&1 | tee template.log
           test -f abc1/mcpp.toml
+          grep -F 'namespace=mcpplibs name=imgui' template.log
 
       - name: "LLVM: build mcpp"
         run: |
@@ -466,13 +468,15 @@ jobs:
       # path (user report: `mcpp new abc1 --template imgui` failed with
       # fetch 'imgui@0.0.6' exit 1 on bare Windows — no sha256sum binary
       # outside git-bash; fixed by xlings 0.4.51 in-process hashing).
-      - name: "Template: mcpp new --template imgui (fetch path)"
+      - name: "Template: exact mcpplibs.imgui selector (fetch path)"
         shell: pwsh
         run: |
           $tmp = New-TemporaryFile | ForEach-Object { Remove-Item $_; New-Item -ItemType Directory -Path $_ }
           Set-Location $tmp
-          mcpp new abc1 --template imgui
+          mcpp new abc1 --template mcpplibs.imgui 2>&1 | Tee-Object -Variable templateOutput
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
           if (!(Test-Path abc1/mcpp.toml)) { exit 1 }
+          if (-not (($templateOutput -join "`n") -match 'namespace=mcpplibs name=imgui')) { exit 1 }
 
       - name: "LLVM: build mcpp"
         shell: pwsh

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

@@ -133,7 +133,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.8.1
+          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.8.9.2
           export PATH="$HOME/.xlings/subos/current/bin:$PATH"
           xlings update
           xlings install mcpp -y -g

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

@@ -118,7 +118,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.8.1'
+          XLINGS_VERSION: '2026.8.9.2'
         run: |
           tarball="xlings-${XLINGS_VERSION}-linux-x86_64.tar.gz"
           curl -fsSL -o "/tmp/${tarball}" \
@@ -255,7 +255,7 @@ jobs:
       - name: Bootstrap mcpp via xlings
         env:
           XLINGS_NON_INTERACTIVE: '1'
-          XLINGS_VERSION: '2026.8.8.1'
+          XLINGS_VERSION: '2026.8.9.2'
         run: |
           tarball="xlings-${XLINGS_VERSION}-linux-x86_64.tar.gz"
           curl -fsSL -o "/tmp/${tarball}" \