feature: Add pseudo-GPU device compilation harness for pass verification

.github/workflows/ci-lambda-spec.yml

@@ -0,0 +1,79 @@
+name: Lambda specialization decisions
+
+# Pseudo-GPU verification of the lambda kernel-arg analysis: compile every
+# lambda GPU test through the real HIP device pipeline (clang -x hip
+# targeting amdgcn) with ProteusPass loaded, on a plain CPU container -- no
+# GPU or ROCm -- and fail on any drift of specialize/decline decisions
+# against tests/gpu/lambda-spec-groundtruth.json.
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/ci-lambda-spec.yml"
+      - "CMakeLists.txt"
+      - "include/**"
+      - "src/**"
+      - "tests/gpu/**"
+      - "tools/lambda-spec-ci/**"
+      - "tools/pseudo-gpu/**"
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/ci-lambda-spec.yml"
+      - "CMakeLists.txt"
+      - "include/**"
+      - "src/**"
+      - "tests/gpu/**"
+      - "tools/lambda-spec-ci/**"
+      - "tools/pseudo-gpu/**"
+
+jobs:
+  lambda-spec:
+    name: pseudo-GPU decision check (LLVM ${{ matrix.llvm }})
+    runs-on: ubuntu-latest
+    container: ubuntu:24.04
+    strategy:
+      matrix:
+        llvm: [19]
+    steps:
+      - name: Install toolchain
+        run: |
+          apt-get update
+          DEBIAN_FRONTEND=noninteractive apt-get install -y \
+            wget gnupg software-properties-common cmake ninja-build \
+            python3 git zlib1g-dev
+          wget -qO- https://apt.llvm.org/llvm-snapshot.gpg.key \
+            | tee /etc/apt/trusted.gpg.d/apt.llvm.org.asc
+          add-apt-repository -y \
+            "deb http://apt.llvm.org/noble/ llvm-toolchain-noble-${{ matrix.llvm }} main"
+          apt-get update
+          apt-get install -y clang-${{ matrix.llvm }} llvm-${{ matrix.llvm }}-dev \
+            libclang-${{ matrix.llvm }}-dev libzstd-dev libedit-dev libcurl4-openssl-dev
+
+      - uses: actions/checkout@v4
+
+      - name: Build ProteusPass (pseudo-GPU mode)
+        run: |
+          cmake -S . -B build -G Ninja \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DCMAKE_C_COMPILER=clang-${{ matrix.llvm }} \
+            -DCMAKE_CXX_COMPILER=clang++-${{ matrix.llvm }} \
+            -DLLVM_INSTALL_DIR=/usr/lib/llvm-${{ matrix.llvm }} \
+            -DPROTEUS_PSEUDO_GPU=ON
+          cmake --build build --target ProteusPass -j "$(nproc)"
+
+      - name: Sweep lambda suite and check decisions
+        run: |
+          bash tools/lambda-spec-ci/run_sweep.sh \
+            clang++-${{ matrix.llvm }} \
+            "$(pwd)/build/src/pass/libProteusPass.so" \
+            "$(pwd)/build/lambda-spec-logs"
+
+      - name: Upload traces on failure
+        if: failure()
+        uses: actions/upload-artifact@v7
+        with:
+          name: lambda-spec-logs-llvm${{ matrix.llvm }}
+          path: build/lambda-spec-logs
+          retention-days: 7

CMakeLists.txt

@@ -23,6 +23,10 @@ option(ENABLE_DEVELOPER_COMPILER_FLAGS "Enable developer compiler flags: -Wall -
 option(PROTEUS_INSTALL_IMPL_HEADERS "Install implementation headers" OFF)
 option(PROTEUS_ENABLE_PYTHON "Build Python bindings" OFF)
 option(PROTEUS_PYTHON_WHEEL "Build wheel-oriented Python package layout" OFF)
+option(PROTEUS_PSEUDO_GPU
+  "Add per-test pseudo-GPU device-compile targets (<test>.HIP) that run the \
+real HIP device pipeline through ProteusPass and emit LLVM IR, without \
+ROCm or a GPU" OFF)
 
 set(PROTEUS_PYTHON_PACKAGE_DIR "proteus" CACHE STRING
   "Install-relative path for the Proteus Python package")
@@ -111,8 +115,24 @@ include(cmake/ProteusFunctions.cmake)
 include(GNUInstallDirs)
 include(CMakePackageConfigHelpers)
 
+if(PROTEUS_PSEUDO_GPU AND (PROTEUS_ENABLE_HIP OR PROTEUS_ENABLE_CUDA))
+  message(FATAL_ERROR "PROTEUS_PSEUDO_GPU is for builds without a GPU "
+                      "toolchain; disable PROTEUS_ENABLE_HIP/CUDA")
+endif()
+
 add_subdirectory(src)
 
+if(PROTEUS_PSEUDO_GPU)
+  # Build the pass HIP-flavored so isDeviceKernel recognizes amdgpu_kernel
+  # functions without requiring the HIP toolchain, and let it tolerate
+  # upstream clang re-running it on the device module (see emitModuleDevice);
+  # production builds keep the unique-name fatal. Scoped to the pass objects
+  # so the runtime library is unaffected.
+  target_compile_definitions(ProteusPassObjects PRIVATE PROTEUS_ENABLE_HIP=1
+                                                        PROTEUS_PSEUDO_GPU=1)
+  include(tools/pseudo-gpu/PseudoGPUTargets.cmake)
+endif()
+
 if(ENABLE_TESTS)
   enable_testing()
 endif()

docs/dev/lambda-spec-groundtruth.md

@@ -0,0 +1,66 @@
+# Lambda GPU suite: specialization ground truth
+
+`tests/gpu/lambda-spec-groundtruth.json` records, for every lambda GPU test,
+which kernels the analysis specializes and which functors it conservatively
+declines. It is the reviewable source of truth for analysis behavior: any
+change to the pass that shifts a decision must either be a bug fix (update
+the JSON in the same commit, explaining the flip) or is a regression (CI
+fails).
+
+## Running the check
+
+Logs come from the ProteusPass debug trace, which is identical for real ROCm
+builds and the pseudo-GPU pipeline:
+
+    # 1. produce one log per test (any build that runs the pass), e.g.:
+    PROTEUS_DEBUG_OUTPUT=1 ctest -R 'lambda_.*HIP' ...   # ROCm
+    #    or compile each test --offload-device-only with the pass plugin
+    #    (pseudo-GPU), then collect .proteus-logs/proteus-pass.*.log into
+    #    <logs-dir>/<test>.log
+
+    # 2. diff against ground truth:
+    python3 tools/lambda-spec-ci/lambda_spec_ci.py check \
+        --logs <logs-dir> --truth tests/gpu/lambda-spec-groundtruth.json
+
+    # re-capture (after an intended behavior change):
+    python3 tools/lambda-spec-ci/lambda_spec_ci.py capture \
+        --logs <logs-dir> --truth tests/gpu/lambda-spec-groundtruth.json \
+        --pipeline <rocm-x.y|pseudo-gpu-llvmNN> --note "<why>"
+
+## Provenance caveat
+
+The current JSON is the baseline of MAIN's analysis over main's lambda
+suite, captured from the pseudo-GPU pipeline (LLVM 19, -O1, gfx90a).
+Compile-time decisions have matched ROCm in spot checks, but this file
+should be re-captured from a ROCm run before being treated as hardware
+ground truth. Tests with no entry produce no analysis decisions in this
+pipeline: lambda_dominating_store (ill-formed, unregistered in CMake) and
+lambda_large_warning (needs __syncthreads in the pseudo-GPU stub).
+
+## Current decisions
+
+| Test | Specializes | Declines |
+| --- | --- | --- |
+| lambda | kernel | — |
+| lambda-two | kernel | — |
+| lambda_call_shapes | kernelSameReturns, kernelSelectSame | makeIndirectBody, makeReturnBody, makeSelectSameBody |
+| lambda_def | kernel | — |
+| lambda_factory | kernel | — |
+| lambda_factory_forwarded | kernel | — |
+| lambda_factory_multi | — | — |
+| lambda_factory_so_runner | — | — |
+| lambda_factory_tu1 | _GLOBAL__N_1 | — |
+| lambda_factory_tu2 | _GLOBAL__N_1 | — |
+| lambda_host_device | kernel | — |
+| lambda_index_first_wrapper | kernel | — |
+| lambda_insertvalue_offsets | kernelDoubleShift, kernelPadded, kernelShift | — |
+| lambda_memory_intrinsic_shapes | kernelNonoverlapMemset, kernelOffsetMemmove | makeDynamicBody |
+| lambda_mfem_style_launch | MockRajaInterface | — |
+| lambda_multiple | kernel | — |
+| lambda_pathological | kernel_case1, kernel_case2_a, kernel_case2_b, kernel_case4, kernel_case5 | — |
+| lambda_phi_analysis | kernel_phi, kernel_phi_arg1, kernel_phi_changed_rc | — |
+| lambda_pointer_field_load | kernelPointerFieldLoad | — |
+| lambda_provenance_shapes | kernelArrayMember, kernelMemcpySource, kernelNegativeGep, kernelOffsetMemcpy, kernelPartialMemcpy, kernelReturnedInteriorPointer | — |
+| lambda_spec_test | kernel | — |
+| lambda_store_order | kernelCaptureFromArg, kernelLatestStore, kernelStoreOrder | makeAmbiguousBody, makeMutatedBody |
+| lambda_thread_privatizer | kernel_thread_privatizer | — |

src/pass/ProteusPass.cpp

@@ -976,9 +976,21 @@ class ProteusPassImpl {
     Constant *JitModule = ConstantDataArray::get(
         M.getContext(),
         ArrayRef<uint8_t>((const uint8_t *)Bitcode.data(), Bitcode.size()));
-    if (M.getNamedGlobal(GVName))
+    if (M.getNamedGlobal(GVName)) {
+#ifdef PROTEUS_PSEUDO_GPU
+      // Upstream clang's HIP device pipeline registers pass-plugin pipeline
+      // callbacks twice (ROCm clang runs the pass once), so pseudo-GPU
+      // compiles re-run this pass on an already-processed module. The first
+      // embedding is authoritative; skip the duplicate so the device compile
+      // can emit its module.
+      DEBUG(Logger::logs("proteus-pass")
+            << "Skipping duplicate jit module global " << GVName << "\n");
+      return;
+#else
       reportFatalError("Expected unique name for jit module global variable " +
                        GVName);
+#endif
+    }
     auto *GV =
         new GlobalVariable(M, JitModule->getType(), /* isConstant */ true,
                            GlobalValue::ExternalLinkage, JitModule, GVName);

tests/gpu/lambda-spec-groundtruth.json

@@ -0,0 +1,170 @@
+{
+  "meta": {
+    "generated": "2026-10-15",
+    "commit": "9cffdd4a",
+    "pipeline": "pseudo-gpu-llvm19",
+    "note": "Baseline of MAIN's analysis over main's lambda suite (branch base 2a8f200a). Captured from the pseudo-GPU device pipeline; re-capture from a ROCm run before treating as hardware ground truth. lambda_dominating_store (ill-formed, unregistered) and lambda_large_warning (stub lacks __syncthreads) produce no decisions."
+  },
+  "tests": {
+    "lambda-two": {
+      "specialize": [
+        "kernel"
+      ],
+      "decline": []
+    },
+    "lambda": {
+      "specialize": [
+        "kernel"
+      ],
+      "decline": []
+    },
+    "lambda_call_shapes": {
+      "specialize": [
+        "kernelSameReturns",
+        "kernelSelectSame"
+      ],
+      "decline": [
+        "makeIndirectBody",
+        "makeReturnBody",
+        "makeSelectSameBody"
+      ]
+    },
+    "lambda_def": {
+      "specialize": [
+        "kernel"
+      ],
+      "decline": []
+    },
+    "lambda_factory": {
+      "specialize": [
+        "kernel"
+      ],
+      "decline": []
+    },
+    "lambda_factory_forwarded": {
+      "specialize": [
+        "kernel"
+      ],
+      "decline": []
+    },
+    "lambda_factory_multi": {
+      "specialize": [],
+      "decline": []
+    },
+    "lambda_factory_so_runner": {
+      "specialize": [],
+      "decline": []
+    },
+    "lambda_factory_tu1": {
+      "specialize": [
+        "_GLOBAL__N_1"
+      ],
+      "decline": []
+    },
+    "lambda_factory_tu2": {
+      "specialize": [
+        "_GLOBAL__N_1"
+      ],
+      "decline": []
+    },
+    "lambda_host_device": {
+      "specialize": [
+        "kernel"
+      ],
+      "decline": []
+    },
+    "lambda_index_first_wrapper": {
+      "specialize": [
+        "kernel"
+      ],
+      "decline": []
+    },
+    "lambda_insertvalue_offsets": {
+      "specialize": [
+        "kernelDoubleShift",
+        "kernelPadded",
+        "kernelShift"
+      ],
+      "decline": []
+    },
+    "lambda_memory_intrinsic_shapes": {
+      "specialize": [
+        "kernelNonoverlapMemset",
+        "kernelOffsetMemmove"
+      ],
+      "decline": [
+        "makeDynamicBody"
+      ]
+    },
+    "lambda_mfem_style_launch": {
+      "specialize": [
+        "MockRajaInterface"
+      ],
+      "decline": []
+    },
+    "lambda_multiple": {
+      "specialize": [
+        "kernel"
+      ],
+      "decline": []
+    },
+    "lambda_pathological": {
+      "specialize": [
+        "kernel_case1",
+        "kernel_case2_a",
+        "kernel_case2_b",
+        "kernel_case4",
+        "kernel_case5"
+      ],
+      "decline": []
+    },
+    "lambda_phi_analysis": {
+      "specialize": [
+        "kernel_phi",
+        "kernel_phi_arg1",
+        "kernel_phi_changed_rc"
+      ],
+      "decline": []
+    },
+    "lambda_pointer_field_load": {
+      "specialize": [
+        "kernelPointerFieldLoad"
+      ],
+      "decline": []
+    },
+    "lambda_provenance_shapes": {
+      "specialize": [
+        "kernelArrayMember",
+        "kernelMemcpySource",
+        "kernelNegativeGep",
+        "kernelOffsetMemcpy",
+        "kernelPartialMemcpy",
+        "kernelReturnedInteriorPointer"
+      ],
+      "decline": []
+    },
+    "lambda_spec_test": {
+      "specialize": [
+        "kernel"
+      ],
+      "decline": []
+    },
+    "lambda_store_order": {
+      "specialize": [
+        "kernelCaptureFromArg",
+        "kernelLatestStore",
+        "kernelStoreOrder"
+      ],
+      "decline": [
+        "makeAmbiguousBody",
+        "makeMutatedBody"
+      ]
+    },
+    "lambda_thread_privatizer": {
+      "specialize": [
+        "kernel_thread_privatizer"
+      ],
+      "decline": []
+    }
+  }
+}