Clarify BloomFilter mixed-mode scope.

Document that the buffer-conversion path is a defensive fix for a rare mixed CPU/GPU plan and explain how the regression test intentionally forces that scenario.

Made-with: Cursor

Author: firestarman

sql-plugin/src/main/spark330/scala/com/nvidia/spark/rapids/shims/BloomFilterShims.scala

@@ -102,6 +102,7 @@ object BloomFilterShims {
             aggBuffer.copy(dataType = a.dataType)(aggBuffer.exprId, aggBuffer.qualifier)
           }
 
+          // This is a defensive correctness fix for the rare mixed CPU/GPU bridge path.
           // BloomFilterAggregate crosses the CPU/GPU boundary as BinaryType in both directions,
           // but empty GPU partial buffers can be null while Spark CPU final expects a serialized
           // empty bloom filter. We still need a converter even though the runtime type

tests/src/test/spark330/scala/com/nvidia/spark/rapids/BloomFilterAggregateQuerySuiteBase.scala

@@ -150,6 +150,11 @@ trait BloomFilterAggregateQuerySuiteBase extends SparkQueryCompareTestSuite {
 
   // Keep the empty-partition mixed CPU/GPU regression coverage in the shared base so both the
   // 3.3x/3.5x suites and the 4.1.1 suite exercise the same bridge behavior.
+  // This is a defensive correctness path that is unlikely in normal workloads because a supported
+  // BloomFilterAggregate would normally keep both partial and final stages on GPU.
+  // The test forces the mixed plan on purpose: BloomFilterMightContain falls back to CPU,
+  // hashAgg.replaceMode keeps only one aggregate stage on GPU, AQE stays off so the plan shape is
+  // stable, and extra shuffle partitions guarantee empty build partitions.
   for (mode <- Seq("partial", "final")) {
     ALLOW_NON_GPU_testSparkResultsAreEqualWithCapture(
       s"might_contain GPU $mode build CPU probe with empty build partitions",