[runtime] Option C alias + library-mode unittests + CI fixes

Introduce `using measure_result = measure_handle;` in MLIR mode
(library mode keeps the legacy class) so existing source names get
the new deferred-measurement semantics without generating host
wrappers for device-only handle signatures. This is the Option C
direction confirmed in the 2026-04-30 runtime sync; rationale and
the rejected alternatives live in
`.cursor/measure-handle-rename-evaluation.md`.

Library-mode CMake routing for `unittests/` (`add_compile_definitions
(CUDAQ_LIBRARY_MODE)`) keeps host-side overloads in
`qpe_ftqc.cpp` and other measurement-using GTests that cannot be
intercepted by the bridge. Temporary workaround until library mode
itself is removed.

CI green-up across the bridge, marshalling, ODS verifiers, and the
expand-measurements / QIR conversion test suites for the new types.

Squashed from four `*`-prefixed WIP commits per PR NVIDIA#4409 history
cleanup; original SHAs: d84f6d8, 8fbe92d, 0e05f4c, ec5eac5.

Signed-off-by: Pradnya Khalate <pkhalate@nvidia.com>

Author: khalatepradnya

docs/sphinx/examples/cpp/sample_to_run_migration.cpp

@@ -31,7 +31,7 @@ __qpu__ void reset_pattern() {
 
 // [Begin Example1]
 struct simple_conditional {
-  auto operator()() __qpu__ {
+  bool operator()() __qpu__ {
     cudaq::qvector q(2);
     h(q[0]);
     auto r = mz(q[0]);

lib/Frontend/nvqpp/ASTBridge.cpp

@@ -73,18 +73,6 @@ static bool hasAnyQubitTypes(FunctionType funcTy) {
   return false;
 }
 
-// Returns true if any input or result type of `funcTy` transitively contains
-// `!cc.measure_handle`.
-static bool hasMeasureHandleInSignature(FunctionType funcTy) {
-  for (auto ty : funcTy.getInputs())
-    if (cudaq::cc::containsMeasureHandle(ty))
-      return true;
-  for (auto ty : funcTy.getResults())
-    if (cudaq::cc::containsMeasureHandle(ty))
-      return true;
-  return false;
-}
-
 // Remove the Itanium mangling "_ZTS" prefix. This is to match the name returned
 // by `typeid(TYPE).name()`.
 static std::string
@@ -654,14 +642,27 @@ void ASTBridgeAction::ASTBridgeConsumer::HandleTranslationUnit(
       if ((!hasAnyQubitTypes(func.getFunctionType())) &&
           (!cudaq::ASTBridgeAction::ASTBridgeConsumer::isCustomOpGenerator(
               fdPair.second))) {
+        auto hasMH = [](FunctionType ft) {
+          for (auto ty : ft.getInputs())
+            if (cudaq::cc::containsMeasureHandle(ty))
+              return true;
+          for (auto ty : ft.getResults())
+            if (cudaq::cc::containsMeasureHandle(ty))
+              return true;
+          return false;
+        };
+        if (hasMH(func.getFunctionType())) {
+          if (auto *md = dyn_cast<clang::CXXMethodDecl>(fdPair.second);
+              md && md->getOverloadedOperator() == clang::OO_Call) {
+            cudaq::details::reportClangError(
+                fdPair.second, mangler,
+                "measure_handle cannot cross the host-device boundary; "
+                "entry-point kernels must discriminate first");
+          }
+          continue;
+        }
         // Flag func as an entry point to a quantum kernel.
         func->setAttr(entryPointAttrName, unitAttr);
-        if (hasMeasureHandleInSignature(func.getFunctionType())) {
-          cudaq::details::reportClangError(
-              fdPair.second, mangler,
-              "measure_handle cannot cross the host-device boundary; "
-              "entry-point kernels must discriminate first");
-        }
         // Generate a declaration for the CPU C++ function.
         addFunctionDecl(fdPair.second, visitor, func.getFunctionType(),
                         entryName, func.empty());

lib/Frontend/nvqpp/ConvertDecl.cpp

@@ -161,7 +161,9 @@ bool QuakeBridgeVisitor::interceptRecordDecl(clang::RecordDecl *x) {
       return pushType(quake::StateType::get(ctx));
     if (name == "pauli_word")
       return pushType(cc::CharspanType::get(ctx));
-    if (name == "measure_handle")
+    // NB: Accommodating the spec request, to keep the change minimally
+    // invasive to the user make these two equivalent.
+    if (name == "measure_handle" || name == "measure_result")
       return pushType(cc::MeasureHandleType::get(ctx));
     if (name == "qkernel") {
       auto *cts = cast<clang::ClassTemplateSpecializationDecl>(x);

lib/Optimizer/Builder/Marshal.cpp

@@ -761,10 +761,10 @@ void cudaq::opt::marshal::populateCallbackBuffer(
 
 bool cudaq::opt::marshal::hasLegalType(FunctionType funTy) {
   for (auto ty : funTy.getInputs())
-    if (quake::isQuantumType(ty))
+    if (quake::isQuantumType(ty) || cc::containsMeasureHandle(ty))
       return false;
   for (auto ty : funTy.getResults())
-    if (quake::isQuantumType(ty))
+    if (quake::isQuantumType(ty) || cc::containsMeasureHandle(ty))
       return false;
   return true;
 }
@@ -790,6 +790,11 @@ std::pair<bool, func::FuncOp> cudaq::opt::marshal::lookupHostEntryPointFunc(
     // No host entry point needed.
     return {false, func::FuncOp{}};
   }
+  // Device-only kernels with signatures that cannot cross the host boundary
+  // have no host-side entry point to rewrite.
+  if (!funcOp->hasAttr(cudaq::entryPointAttrName) &&
+      !cudaq::opt::marshal::hasLegalType(funcOp.getFunctionType()))
+    return {false, func::FuncOp{}};
   if (auto *decl = module.lookupSymbol(mangledEntryPointName))
     if (auto func = dyn_cast<func::FuncOp>(decl)) {
       func.eraseBody();

lib/Optimizer/Dialect/CC/CCOps.cpp

@@ -460,25 +460,35 @@ LogicalResult cudaq::cc::CastOp::verify() {
 }
 
 namespace {
-// There are a number of series of casts that can be fused. For now, fuse
-// pointer cast chains.
+// Fold cast cascades whose endpoints are both pointer types. Two shapes:
+//   - ptr -> ptr -> ptr  (eliminate the intermediate pointer view)
+//   - ptr -> int -> ptr  (eliminate the integer round-trip)
+// `cc.cast` is a value-preserving type-only view, so collapsing either shape
+// to a single `ptr -> ptr` cast is always safe. The integer-round-trip case
+// also matters for the QIR profile pipelines: the discriminate / measurement
+// patterns build `Result* -> i64 -> ... -> ptr<i1>` chains, and the trailing
+// `Result* -> i64` lowers to `llvm.ptrtoint`, which the NVQIR profile
+// verifier rejects (only `bitcast`, `inttoptr`, etc. are allow-listed for
+// pointer-typed operands). After this fold + DCE the chain collapses to a
+// single `ptr -> ptr` cast that lowers to `llvm.bitcast`.
 struct FuseCastCascade : public OpRewritePattern<cudaq::cc::CastOp> {
   using OpRewritePattern::OpRewritePattern;
 
   LogicalResult matchAndRewrite(cudaq::cc::CastOp castOp,
                                 PatternRewriter &rewriter) const override {
-    if (auto castToCast = castOp.getValue().getDefiningOp<cudaq::cc::CastOp>())
-      if (isa<cudaq::cc::PointerType>(castOp.getType()) &&
-          isa<cudaq::cc::PointerType>(castToCast.getType())) {
-        // %4 = cc.cast %3 : (!cc.ptr<T>) -> !cc.ptr<U>
-        // %5 = cc.cast %4 : (!cc.ptr<U>) -> !cc.ptr<V>
-        // ────────────────────────────────────────────
-        // %5 = cc.cast %3 : (!cc.ptr<T>) -> !cc.ptr<V>
-        rewriter.replaceOpWithNewOp<cudaq::cc::CastOp>(castOp, castOp.getType(),
-                                                       castToCast.getValue());
-        return success();
-      }
-    return failure();
+    auto castToCast = castOp.getValue().getDefiningOp<cudaq::cc::CastOp>();
+    if (!castToCast)
+      return failure();
+    if (!isa<cudaq::cc::PointerType>(castOp.getType()))
+      return failure();
+    if (!isa<cudaq::cc::PointerType>(castToCast.getValue().getType()))
+      return failure();
+    auto middleTy = castToCast.getType();
+    if (!isa<cudaq::cc::PointerType, IntegerType>(middleTy))
+      return failure();
+    rewriter.replaceOpWithNewOp<cudaq::cc::CastOp>(castOp, castOp.getType(),
+                                                   castToCast.getValue());
+    return success();
   }
 };
 

runtime/cudaq/qis/execution_manager.h

@@ -15,6 +15,7 @@
 #include "cudaq/algorithms/policies.h"
 #include "cudaq/host_config.h"
 #include "cudaq/operators.h"
+#include "cudaq/qis/measure_handle.h"
 #include <deque>
 #include <string_view>
 #include <vector>
@@ -70,8 +71,9 @@ class measure_result {
   }
 };
 #else
-/// When compiling with MLIR, we default to a boolean.
-using measure_result = bool;
+// In MLIR mode, keep the existing `measure_result` API name as a compatibility
+// alias for `measure_handle`.
+using measure_result = measure_handle;
 #endif
 
 /// The ExecutionManager provides a base class describing a concrete sub-system

runtime/cudaq/qis/measure_handle.h

@@ -15,17 +15,17 @@
 #include <cstdint>
 #include <limits>
 
-namespace cudaq {
-
-namespace details {
+namespace cudaq::details {
 /// Tag type used to dispatch the index-taking `measure_handle` constructor,
 /// so `measure_handle{42}` cannot be compiled in user code. The tag surface is
 /// reserved for internal runtime use. Inside `__qpu__` regions the
 /// bridge never calls this constructor because `mz`/`mx`/`my` produce
 /// `!cc.measure_handle` SSA values directly.
 struct handle_index_t {};
 inline constexpr handle_index_t handle_index{};
-} // namespace details
+} // namespace cudaq::details
+
+namespace cudaq {
 
 /// @brief Handle for a measurement event with deferred discrimination.
 ///