microsoft · Elliot (theelliotm) · Aug 17, 2026 · Jul 31, 2026 · Jul 31, 2026 · Jul 31, 2026
@@ -43,6 +43,60 @@ build.bat --with-microvm   # Include NanVix micro-VM binaries
 
 Requires Xcode Command Line Tools and Rust. Produces an unsigned `mxc-exec-mac` binary (codesigning + notarization happen at release time). Schema `0.7.0-alpha` or later required for macOS/Seatbelt backend.
 
+### GitHub Actions
+
+`.github/workflows/Build.yml` is the PR/CI entry point. It fans out to the
+workflow-call-only `Build.Windows.Job.yml`, `Build.Linux.Job.yml`, and
+`Build.MacOS.Job.yml`, which build and upload the per-target artifacts in
+parallel, then to the lint / versioning / SDK jobs.
+
+**Validation (E2E) test infrastructure.** Fully documented in
+[`docs/ci-validation-infrastructure.md`](../docs/ci-validation-infrastructure.md)
+(matrix contents, job names, per-backend coverage and status, and the runbook
+for adding/removing an OS, backend, or plan). Backend E2E tests run from those
+same build artifacts — never from a fresh build — so artifact production and
+consumption stay in one workflow run:
+
+- `.github/workflows/Validation.Tests.Scheduled.yml` — scheduled entry point.
+  The `nightly` plan runs Mon–Sat; Sunday runs `nightly` *and* `weekly`.
+  `workflow_dispatch` takes a `plan` input to run one on demand.
+- `.github/workflows/Validation.Tests.Matrix.Job.yml` — workflow-call-only,
+  takes a `plan` input. Its `resolve` job expands the plan into per-family
+  matrices, then the `windows` / `linux` / `macos` jobs each download the
+  artifact, prepare the host, and run the backend suite.
+
+An entry point must build the artifacts (call the three `Build.*.Job.yml`
+workflows) before calling the matrix job.
+
+**The matrix is declarative:**
+
+- `scripts/ci/validation-test-matrix.json` is the catalog: `platforms` (each
+  with per-architecture target/artifact/1ES pool and the backends that platform
+  supports) and `triggers` (which OS/backend pairs each plan runs). The
+  `triggers` keys *are* the plan list — the resolver reads them at run time, so
+  adding a plan needs no script change.
+- `scripts/ci/resolve-validation-test-matrix.mjs` validates that catalog and
+  expands a plan (currently `pr`, `nightly`, `weekly`, `enabled`) into GitHub
+  Actions matrices. It rejects an invalid catalog before any specialized test
+  runner is allocated, so add a backend to a trigger only where the platform
+  declares it.
+- A non-macOS platform architecture with an empty `pool` is never scheduled,
+  which is how a catalog entry stays declared but dormant. macOS entries use a
+  GitHub-hosted `runner` instead of a 1ES `pool`.
+
+**Host preparation** happens in the matrix job before the tests, keyed by the
+matrix `backend` id: `scripts/ci/prepare-windows-host.ps1` and
+`scripts/ci/prepare-linux-host.sh`. A backend with no prerequisites is an
+explicit no-op, so the step runs unconditionally for every entry.
+
+**Test dispatch** goes through `tests/scripts/run_ci_backend_tests.ps1`
+(Windows) and `tests/scripts/run_ci_backend_tests.sh` (Linux/macOS), which map
+the matrix `backend` id to the repository's existing backend suite. Ids that
+share a suite get their own case (`process-t1` and `process-t3` both run
+`WinProcessContainer-Tests.ps1`, which derives the tier it expects from the
+host's own `--probe`). A backend with no wired suite fails loudly rather than
+reporting a false success.
+
 ### Individual components
 
 ```
@@ -98,6 +152,18 @@ tests\scripts\run_bwrap_all_tests.sh          # All Bubblewrap tests (Linux, req
 # E2E test crate — Rust executor integration tests (from src/)
 cargo test -p wxc_e2e_tests                 # Invokes MXC binaries directly
 cargo test -p wxc_e2e_tests -- --ignored    # Include stress tests (run_on_repeat)
+
+# WSLC has no cargo E2E suite — it is covered by tests\scripts\run_wslc_all_tests.ps1,
+# which the validation matrix runs via tests\scripts\run_ci_backend_tests.ps1.
+
+# CI validation entry points — run a backend suite against a downloaded artifact
+# the way the validation matrix does. Take the matrix backend id exactly as it
+# appears in scripts/ci/validation-test-matrix.json.
+tests\scripts\run_ci_backend_tests.ps1 -Backend process-t1 -BinaryDirectory <dir> -Architecture x64
+tests\scripts\run_ci_backend_tests.sh <bubblewrap|lxc|seatbelt> <binary-directory>
+
+# Resolve a plan locally to see exactly what CI would schedule
+node scripts/ci/resolve-validation-test-matrix.mjs --plan nightly
 ```
 
 ## Architecture
@@ -154,6 +220,7 @@ Core references:
 - `docs/authoring-a-new-feature.md` — step-by-step guide for adding experimental features (which files to touch, in what order)
 - `docs/examples.md` — annotated configuration examples (see also `tests/examples/` and `tests/configs/`)
 - `docs/diagnostics.md` — diagnostic logging knobs (env vars, log file format)
+- `docs/ci-validation-infrastructure.md` — validation (E2E) test matrix: workflows and job names, catalog format, per-backend coverage and status, and the runbook for adding/removing an OS, backend, or plan
 - `docs/host-prep.md` — `wxc-host-prep.exe` host setup binary (`prepare-system-drive` / `unprepare-system-drive` for the AppContainer ACEs on the system-drive root, plus `prepare-null-device` / `verify-null-device` / `dump-null-device` for the `\Device\Null` security descriptor that AppContainer-based backends require). Owns elevation via embedded `requireAdministrator` manifest — `wxc-exec.exe` no longer self-elevates.
 - `docs/sandbox-policy/0.7.0/policy.md` — sandbox policy 0.7.0 specification
 

@@ -13,9 +13,11 @@ jobs:
           - arch: x64
             runner: ubuntu-latest
             target: x86_64-unknown-linux-gnu
+            features: hyperlight
           - arch: arm64
             runner: ubuntu-24.04-arm
             target: aarch64-unknown-linux-gnu
+            features: ''
     runs-on: ${{ matrix.runner }}
     defaults:
       run:
@@ -54,12 +56,26 @@ jobs:
         run: sudo apt-get update && sudo apt-get install -y --no-install-recommends gcc-aarch64-linux-gnu
 
       - name: Build lxc
-        run: cargo build --locked --release --target ${{ matrix.target }}
-             --no-default-features --features hyperlight
+        shell: bash
+        run: |
+          set -euo pipefail
+          features=()
+          if [[ -n "${{ matrix.features }}" ]]; then
+            features=(--features "${{ matrix.features }}")
+          fi
+          cargo build --locked --release --target "${{ matrix.target }}" \
+            --no-default-features "${features[@]}"
 
       - name: Test lxc
-        run: cargo test --locked --release --target ${{ matrix.target }}
-             --no-default-features --features hyperlight
+        shell: bash
+        run: |
+          set -euo pipefail
+          features=()
+          if [[ -n "${{ matrix.features }}" ]]; then
+            features=(--features "${{ matrix.features }}")
+          fi
+          cargo test --locked --release --target "${{ matrix.target }}" \
+            --no-default-features "${features[@]}"
 
       # Bubblewrap is required to run the executor characterization tests in
       # wxc_e2e_tests (they skip via has_bwrap() when it is absent). lxc-exec
@@ -81,7 +97,7 @@ jobs:
         working-directory: src
         run: cargo test --locked --release --target ${{ matrix.target }}
              -p wxc_e2e_tests
-
+             
       # PLM (Permissive Learning Mode) is functionally Windows-only, but the
       # crate builds cross-platform: the lib's helper modules compile on every
       # target, and the binary has a no-op stub `fn main()` for non-Windows so

@@ -6,8 +6,7 @@ on:
 jobs:
   build:
     name: arm64
-    # macos-14 / macos-latest are Apple Silicon (arm64); older labels are Intel.
-    runs-on: macos-14
+    runs-on: macos-15
     defaults:
       run:
         working-directory: src
@@ -55,6 +54,18 @@ jobs:
         run: cargo test --locked --release --target aarch64-apple-darwin
              -p mxc_darwin -p seatbelt_common -p wxc_common -p wxc_e2e_tests
 
+      - name: Verify artifact payload
+        shell: bash
+        run: |
+          set -euo pipefail
+          bin_dir="target/aarch64-apple-darwin/release"
+          for file in mxc-exec-mac unix-test-proxy; do
+            if [[ ! -f "$bin_dir/$file" ]]; then
+              echo "Missing artifact file: $file" >&2
+              exit 1
+            fi
+          done
+
       - name: Upload binaries
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:

@@ -18,8 +18,8 @@ jobs:
           - arch: arm64
             runner: windows-11-arm
             target: aarch64-pc-windows-msvc
-            # nanvixd.exe is x64-only, so microvm tests can't run on arm64.
-            features: hyperlight isolation_session wslc
+            # Hyperlight and MicroVM runtimes are x64-only.
+            features: isolation_session wslc
     runs-on: ${{ matrix.runner }}
     defaults:
       run:
@@ -86,5 +86,7 @@ jobs:
             src/target/${{ matrix.target }}/release/wxc-test-proxy.exe
             src/target/${{ matrix.target }}/release/mxc-diagnostic-console.exe
             src/target/${{ matrix.target }}/release/wslcsdk.dll
-          if-no-files-found: warn
+            src/target/${{ matrix.target }}/release/wxc-ui-probe.exe
+            src/target/${{ matrix.target }}/release/wxc-test-driver.exe
+          if-no-files-found: error
           retention-days: 1
@@ -18,6 +18,7 @@ concurrency:
   cancel-in-progress: true
 
 permissions:
+  actions: read
   contents: read
 
 jobs:

@@ -24,7 +24,7 @@ jobs:
             clippy-args: --locked --all-targets --all-features --release
           - os_label: macos
             component: MAC
-            runner: macos-14
+            runner: macos-26
             target: aarch64-apple-darwin
             working-directory: src
             # Workspace has Windows-only crates, so --all-features won't build on macOS.

@@ -15,7 +15,7 @@ jobs:
           - os_label: linux
             runner: ubuntu-latest
           - os_label: macos
-            runner: macos-14
+            runner: macos-26
     runs-on: ${{ matrix.runner }}
     defaults:
       run:

@@ -0,0 +1,173 @@
+name: Create Validation Test Matrix
+
+on:
+  workflow_call:
+    inputs:
+      plan:
+        description: Test plan to resolve.
+        required: true
+        type: string
+
+permissions:
+  actions: read
+  contents: read
+
+jobs:
+  resolve:
+    name: resolve "${{ inputs.plan }}" test matrix
+    runs-on: ubuntu-latest
+    outputs:
+      windows: ${{ steps.matrix.outputs.windows }}
+      linux: ${{ steps.matrix.outputs.linux }}
+      macos: ${{ steps.matrix.outputs.macos }}
+      has_windows: ${{ steps.matrix.outputs.has_windows }}
+      has_linux: ${{ steps.matrix.outputs.has_linux }}
+      has_macos: ${{ steps.matrix.outputs.has_macos }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+
+      - name: Resolve test combinations
+        id: matrix
+        run: node scripts/ci/resolve-validation-test-matrix.mjs --plan "${{ inputs.plan }}"
+
+  windows:
+    name: ${{ matrix.os }}, ${{ matrix.architecture }}, ${{ matrix.backend }}
+    needs: resolve
+    if: needs.resolve.outputs.has_windows == 'true'
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.resolve.outputs.windows) }}
+    runs-on: [ self-hosted, "1ES.Pool=${{ matrix.pool }}", "JobId=mxc-e2e-${{ github.run_id }}-${{ github.run_number }}-${{ github.run_attempt }}" ]
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+
+      - name: Download ${{ matrix.target }} artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c
+        with:
+          name: ${{ matrix.artifact }}
+          path: artifacts/bin
+
+      - name: Prepare backend prerequisites
+        timeout-minutes: 15
+        shell: pwsh
+        run: |
+          & ./scripts/ci/prepare-windows-host.ps1 `
+            -Backend '${{ matrix.backend }}' `
+            -BinaryDirectory (Join-Path $env:GITHUB_WORKSPACE 'artifacts\bin') *>&1 |
+            Tee-Object -FilePath (Join-Path $env:RUNNER_TEMP 'mxc-ci.log') -Append
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+      - name: Run backend tests
+        # A backend that hangs (rather than failing) would otherwise burn the
+        # full job timeout. Fail fast enough to keep the log useful.
+        timeout-minutes: 45
+        shell: pwsh
+        run: |
+          & ./tests/scripts/run_ci_backend_tests.ps1 `
+            -Backend '${{ matrix.backend }}' `
+            -BinaryDirectory (Join-Path $env:GITHUB_WORKSPACE 'artifacts\bin') `
+            -Architecture '${{ matrix.architecture }}' *>&1 |
+            Tee-Object -FilePath (Join-Path $env:RUNNER_TEMP 'mxc-ci.log') -Append
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+      - name: Upload failure logs
+        if: failure() || cancelled()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
+        with:
+          name: logs-${{ inputs.plan }}-${{ matrix.os }}-${{ matrix.architecture }}-${{ matrix.backend }}-${{ github.run_attempt }}
+          path: |
+            ${{ runner.temp }}/mxc-ci.log
+            ${{ runner.temp }}/mxc-wpc-tests/logs
+            ${{ runner.temp }}/WinProcessContainer-Tests.results.*
+            ${{ runner.temp }}/mxc_concurrent_oneshot
+          if-no-files-found: ignore
+          retention-days: 7
+
+  linux:
+    name: ${{ matrix.os }}, ${{ matrix.architecture }}, ${{ matrix.backend }}
+    needs: resolve
+    if: needs.resolve.outputs.has_linux == 'true'
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.resolve.outputs.linux) }}
+    runs-on: [ self-hosted, "1ES.Pool=${{ matrix.pool }}", "JobId=mxc-e2e-${{ github.run_id }}-${{ github.run_number }}-${{ github.run_attempt }}" ]
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+
+      - name: Download ${{ matrix.target }} artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c
+        with:
+          name: ${{ matrix.artifact }}
+          path: artifacts/bin
+
+      - name: Prepare backend prerequisites
+        timeout-minutes: 15
+        shell: bash
+        run: |
+          set -euo pipefail
+          bash scripts/ci/prepare-linux-host.sh \
+            '${{ matrix.backend }}' "$GITHUB_WORKSPACE/artifacts/bin" 2>&1 |
+            tee -a "$RUNNER_TEMP/mxc-ci.log"
+
+      - name: Run backend tests
+        timeout-minutes: 45
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [[ '${{ matrix.backend }}' == 'lxc' ]]; then
+            sudo --preserve-env=RUNNER_TEMP bash tests/scripts/run_ci_backend_tests.sh \
+              '${{ matrix.backend }}' "$GITHUB_WORKSPACE/artifacts/bin" 2>&1 |
+              tee -a "$RUNNER_TEMP/mxc-ci.log"
+          else
+            bash tests/scripts/run_ci_backend_tests.sh \
+              '${{ matrix.backend }}' "$GITHUB_WORKSPACE/artifacts/bin" 2>&1 |
+              tee -a "$RUNNER_TEMP/mxc-ci.log"
+          fi
+
+      - name: Upload failure logs
+        if: failure() || cancelled()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
+        with:
+          name: logs-${{ inputs.plan }}-${{ matrix.os }}-${{ matrix.architecture }}-${{ matrix.backend }}-${{ github.run_attempt }}
+          path: ${{ runner.temp }}/mxc-ci.log
+          if-no-files-found: ignore
+          retention-days: 7
+
+  macos:
+    name: ${{ matrix.os }}, ${{ matrix.backend }}
+    needs: resolve
+    if: needs.resolve.outputs.has_macos == 'true'
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.resolve.outputs.macos) }}
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+
+      - name: Download ${{ matrix.target }} artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c
+        with:
+          name: ${{ matrix.artifact }}
+          path: artifacts/bin
+
+      - name: Run backend tests
+        timeout-minutes: 60
+        shell: bash
+        run: |
+          set -euo pipefail
+          chmod +x artifacts/bin/mxc-exec-mac artifacts/bin/unix-test-proxy
+          bash tests/scripts/run_ci_backend_tests.sh \
+            '${{ matrix.backend }}' "$GITHUB_WORKSPACE/artifacts/bin" 2>&1 |
+            tee "$RUNNER_TEMP/mxc-ci.log"
+
+      - name: Upload failure logs
+        if: failure() || cancelled()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
+        with:
+          name: logs-${{ inputs.plan }}-${{ matrix.os }}-${{ matrix.architecture }}-${{ matrix.backend }}-${{ github.run_attempt }}
+          path: ${{ runner.temp }}/mxc-ci.log
+          if-no-files-found: ignore
+          retention-days: 7