deprecate(compute): mark Mask and Compute.filter for removal

A materialized selection mask is a slower primitive than a fused single-pass
scan — it builds a positional bitmap the reduce must then re-scan (two-pass
filter->Mask->reduce measured ~1.5x a fused one-pass; Compute.filter's
bitmap build ~6x a vectorizable count). Mask and Compute.filter are now
@deprecated(forRemoval) in favour of fused kernels like Compute.filteredSum
(and a forthcoming fused multi-column filteredReduce). Nothing is removed:
the Calcite boundary fold still uses Mask until it migrates, guarded by
narrow @SuppressWarnings("removal") on the transitional internal call sites.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: dfa1

CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `Compute.filteredSum(filterColumn, predicate, aggColumn)` fuses a filter and a sum into a single scan — a row folds into the total only when the predicate selects it (a null filter row is excluded) and the aggregate value is non-null — with no intermediate selection bitmap. It matches a hand-written fused loop and is ~1.5× faster than the two-pass `filter` + `sum`. ([57d2225b](https://github.com/dfa1/vortex-java/commit/57d2225b))
+
+### Deprecated
+
+- The selection `Mask` and `Compute.filter(Array, Predicate, Arena)` are deprecated for removal: a materialized selection mask is a slower primitive than a fused single-pass scan (it builds a positional bitmap the reduce must re-scan). Prefer the fused `Compute.filteredSum` (and the forthcoming fused multi-column `filteredReduce`), which fold filter and aggregate in one pass with no intermediate bitmap. ([319cfd97](https://github.com/dfa1/vortex-java/commit/319cfd97))
+
 ## [0.11.0] — 2026-06-28
 
 SQL over Vortex grows a **compute layer**: a Calcite `WHERE`-filtered `SUM`/`COUNT`/`MIN`/`MAX` is now answered from the zone-map statistics — folding the chunks the predicate fully selects without decoding them and decoding only the one or two chunks its range cuts through (ADR 0013 §6 / ADR 0018 boundary tier). On a 100-chunk file a `SELECT SUM(x) WHERE id BETWEEN …` answers ~12× faster than a full scan when the range is wide. Plus the security hardening of the untrusted-input parse paths (ADR 0003) and a `vortex.zstd` binding bump.

calcite/src/main/java/io/github/dfa1/vortex/calcite/VortexTable.java

@@ -324,6 +324,7 @@ public Optional<FilteredFold> filteredFold(RowFilter filter, String aggColumn) {
     /// [VortexException] disables the sum (mirroring a zone that records no usable sum) rather than
     /// failing the whole fold — a `MIN`/`MAX` over the same column still folds. The aggregate
     /// column's null count among the selected rows is the selected count minus the non-null count.
+    @SuppressWarnings("removal") // transitional — uses the deprecated Mask until the fused multi-column filteredReduce lands
     private static void foldBoundaryZone(VortexReader reader, int zone, List<String> columns,
                                          RowFilter filter, String aggColumn, Fold fold) {
         try (Chunk chunk = reader.decodeChunk(zone, columns);
@@ -353,6 +354,7 @@ private static void foldBoundaryZone(VortexReader reader, int zone, List<String>
     /// column's decoded array, and an n-ary `AND` intersects the per-leaf masks (a row is selected
     /// only when every leaf accepts it). The kernels apply SQL three-valued logic, so a null row
     /// never satisfies a value predicate — matching the fold's null semantics.
+    @SuppressWarnings("removal") // transitional — uses the deprecated Mask until the fused multi-column filteredReduce lands
     private static Mask buildMask(Chunk chunk, RowFilter filter, Arena arena) {
         long n = chunk.rowCount();
         List<Mask> masks = new ArrayList<>();
@@ -378,6 +380,7 @@ private static Mask buildMask(Chunk chunk, RowFilter filter, Arena arena) {
     /// A [RowFilter.Column] already holds the exact compute [Predicate], so the kernel runs it
     /// directly against the bound column — no translation seam, since `>=`, `<=` and `<>` are now
     /// first-class predicate variants.
+    @SuppressWarnings("removal") // transitional — uses the deprecated Mask and Compute.filter until the fused multi-column filteredReduce lands
     private static void collectLeafMasks(Chunk chunk, RowFilter filter, Arena arena, List<Mask> out) {
         switch (filter) {
             case RowFilter.And(var parts) -> {

performance/src/main/java/io/github/dfa1/vortex/performance/ComputeKernelBenchmark.java

@@ -100,6 +100,7 @@
         "--sun-misc-unsafe-memory-access=allow",
         "-Xmx4g"
 })
+@SuppressWarnings("removal") // transitional — benchmarks the deprecated Mask / Compute.filter two-pass path against the fused single-pass kernel
 public class ComputeKernelBenchmark {
 
     /// Total rows scanned per op — ≈ 800 MB per column, far larger than L3, so memory-bound.

reader/src/main/java/io/github/dfa1/vortex/reader/compute/Compute.java

@@ -34,6 +34,14 @@ private Compute() {
     /// @param arena     the arena for the output bitmap; its [Arena#allocate(long)] zero-fills, which
     ///                  seeds the unselected bits to 0
     /// @return a mask of `array.length()` positions selected where `predicate` holds
+    /// @deprecated Materializing a selection [Mask] is a slower primitive than a fused single-pass
+    ///             scan: it builds a positional bitmap over the whole filter column, which a later
+    ///             reduce must re-scan. Prefer the fused [#filteredSum(Array, Predicate, Array)] (and
+    ///             the forthcoming fused multi-column `filteredReduce`), which fold filter and
+    ///             aggregate in one pass with no intermediate bitmap. Scheduled for removal once the
+    ///             Calcite boundary fold migrates off it.
+    @Deprecated(since = "0.12.0", forRemoval = true)
+    @SuppressWarnings("removal") // suppresses only this method's own use of the to-be-removed Mask return type — callers still see filter() as deprecated
     public static Mask filter(Array array, Predicate predicate, Arena arena) {
         Objects.requireNonNull(array, "array");
         Objects.requireNonNull(predicate, "predicate");
@@ -43,10 +51,14 @@ public static Mask filter(Array array, Predicate predicate, Arena arena) {
 
     /// Sums the selected non-null values of `array`.
     ///
+    /// Pairs with the (deprecated) [Mask]; transitional pending the fused reductions such as
+    /// [#filteredSum(Array, Predicate, Array)].
+    ///
     /// @param array the array to reduce
     /// @param mask  the selection mask, must have the same length as `array`
     /// @return the sum as a [Long] for integer columns or a [Double] for floating columns; the
     ///         additive identity (`0`) when no selected position is non-null
+    @SuppressWarnings("removal") // transitional — consumes the deprecated Mask until the fused multi-column filteredReduce lands
     public static Number sum(Array array, Mask mask) {
         return Reductions.SUM.apply(array, requireMask(array, mask));
     }
@@ -77,27 +89,39 @@ public static Number filteredSum(Array filterColumn, Predicate predicate, Array
 
     /// Counts the selected non-null values of `array`.
     ///
+    /// Pairs with the (deprecated) [Mask]; transitional pending the fused reductions such as
+    /// [#filteredSum(Array, Predicate, Array)].
+    ///
     /// @param array the array to reduce
     /// @param mask  the selection mask, must have the same length as `array`
     /// @return the count of selected non-null values, `0` when none
+    @SuppressWarnings("removal") // transitional — consumes the deprecated Mask until the fused multi-column filteredReduce lands
     public static long count(Array array, Mask mask) {
         return Reductions.COUNT.apply(array, requireMask(array, mask));
     }
 
     /// Finds the smallest selected non-null value of `array` under its dtype-aware order.
     ///
+    /// Pairs with the (deprecated) [Mask]; transitional pending the fused reductions such as
+    /// [#filteredSum(Array, Predicate, Array)].
+    ///
     /// @param array the array to reduce
     /// @param mask  the selection mask, must have the same length as `array`
     /// @return the minimum value, or `null` when no selected position is non-null
+    @SuppressWarnings("removal") // transitional — consumes the deprecated Mask until the fused multi-column filteredReduce lands
     public static Object min(Array array, Mask mask) {
         return Reductions.MIN.apply(array, requireMask(array, mask));
     }
 
     /// Finds the largest selected non-null value of `array` under its dtype-aware order.
     ///
+    /// Pairs with the (deprecated) [Mask]; transitional pending the fused reductions such as
+    /// [#filteredSum(Array, Predicate, Array)].
+    ///
     /// @param array the array to reduce
     /// @param mask  the selection mask, must have the same length as `array`
     /// @return the maximum value, or `null` when no selected position is non-null
+    @SuppressWarnings("removal") // transitional — consumes the deprecated Mask until the fused multi-column filteredReduce lands
     public static Object max(Array array, Mask mask) {
         return Reductions.MAX.apply(array, requireMask(array, mask));
     }
@@ -107,6 +131,7 @@ public static Object max(Array array, Mask mask) {
     /// @param array the array to reduce
     /// @param mask  the selection mask
     /// @return the validated mask
+    @SuppressWarnings("removal") // transitional — consumes the deprecated Mask until the fused multi-column filteredReduce lands
     private static Mask requireMask(Array array, Mask mask) {
         Objects.requireNonNull(array, "array");
         Objects.requireNonNull(mask, "mask");

reader/src/main/java/io/github/dfa1/vortex/reader/compute/FilterKernel.java

@@ -33,5 +33,6 @@ interface FilterKernel {
     /// @param arena     the arena for the output bitmap; its [Arena#allocate(long)] zero-fills, which
     ///                  seeds the unselected bits to 0
     /// @return a mask of `array.length()` positions, selected where `current` and `predicate` agree
+    @SuppressWarnings("removal") // transitional — uses the deprecated Mask until the fused multi-column filteredReduce lands
     Mask apply(Array array, Mask current, Predicate predicate, Arena arena);
 }

reader/src/main/java/io/github/dfa1/vortex/reader/compute/Mask.java

@@ -21,6 +21,14 @@
 ///   `compare` / `between` / `is_null` kernels.
 ///
 /// All variants are read-only views: a mask never copies or allocates a bitmap of its own.
+///
+/// @deprecated The materialized selection mask is a slower primitive than a fused single-pass scan:
+///             producing it forces a positional bitmap and then a second pass over the aggregate
+///             column. Prefer the fused `Compute.filteredSum` (and the forthcoming fused
+///             multi-column `filteredReduce`), which fuse filter and aggregate in one pass with no
+///             intermediate bitmap. Scheduled for removal once the Calcite boundary fold migrates
+///             off it.
+@Deprecated(since = "0.12.0", forRemoval = true)
 public sealed interface Mask permits Mask.AllTrue, Mask.AllFalse, Mask.RangeMask, Mask.BitmapMask {
 
     /// Returns the number of positions this mask covers.

reader/src/main/java/io/github/dfa1/vortex/reader/compute/PrimitiveFilter.java

@@ -49,6 +49,7 @@ private PrimitiveFilter() {
     /// @param predicate the predicate to evaluate
     /// @param arena     the arena for the result bitmap; its zero-fill seeds the unselected bits to 0
     /// @return the selection mask, or `null` if the input is not specializable
+    @SuppressWarnings("removal") // transitional — uses the deprecated Mask until the fused multi-column filteredReduce lands
     static Mask tryFilter(Array array, Mask current, Predicate predicate, Arena arena) {
         Array data;
         BoolArray validity;
@@ -427,6 +428,7 @@ private static MemorySegment nullLeaf(BoolArray validity, long n, Arena arena, b
     /// @param bits    the predicate-result bitmap, mutated in place
     /// @param current the incoming selection mask
     /// @param n       the row count
+    @SuppressWarnings("removal") // transitional — uses the deprecated Mask until the fused multi-column filteredReduce lands
     private static void applyCurrent(MemorySegment bits, Mask current, long n) {
         if (current instanceof Mask.AllTrue) {
             return;

reader/src/main/java/io/github/dfa1/vortex/reader/compute/ReduceKernel.java

@@ -21,5 +21,6 @@ interface ReduceKernel<R> {
     /// @param array   the input array, possibly a lazy variant; never materialized whole
     /// @param current the selection mask, must have the same length as `array`
     /// @return the reduction result
+    @SuppressWarnings("removal") // transitional — uses the deprecated Mask until the fused multi-column filteredReduce lands
     R apply(Array array, Mask current);
 }

reader/src/main/java/io/github/dfa1/vortex/reader/compute/Reductions.java

@@ -25,6 +25,8 @@
 /// columns fold into a [Long] (wrapping at 2^63, like SQL `SUM(BIGINT)`), floating columns into a
 /// [Double], nulls are skipped, and the Rust empty / all-null results are mirrored exactly — `SUM` is
 /// the additive identity (`0L` or `0.0`, never null), `COUNT` is `0`, and `MIN` / `MAX` are `null`.
+// transitional — every reduction consumes the deprecated Mask until the fused multi-column filteredReduce lands
+@SuppressWarnings("removal")
 final class Reductions {
 
     /// Sums the selected non-null values: a [Long] for integer columns, a [Double] for floats.

reader/src/main/java/io/github/dfa1/vortex/reader/compute/StreamingFilterKernel.java

@@ -22,6 +22,7 @@
 final class StreamingFilterKernel implements FilterKernel {
 
     @Override
+    @SuppressWarnings("removal") // transitional — uses the deprecated Mask until the fused multi-column filteredReduce lands
     public Mask apply(Array array, Mask current, Predicate predicate, Arena arena) {
         Objects.requireNonNull(array, "array");
         Objects.requireNonNull(current, "current");
@@ -54,6 +55,7 @@ public Mask apply(Array array, Mask current, Predicate predicate, Arena arena) {
     /// @param predicate the predicate to evaluate
     /// @param arena     the arena for the result bitmap
     /// @return the selection mask the generic per-element path produces
+    @SuppressWarnings("removal") // transitional — uses the deprecated Mask until the fused multi-column filteredReduce lands
     Mask applyGeneric(Array array, Mask current, Predicate predicate, Arena arena) {
         long n = array.length();
         if (n == 0 || current instanceof Mask.AllFalse) {
@@ -62,6 +64,7 @@ Mask applyGeneric(Array array, Mask current, Predicate predicate, Arena arena) {
         return applyGeneric(array, current, predicate, arena, n);
     }
 
+    @SuppressWarnings("removal") // transitional — uses the deprecated Mask until the fused multi-column filteredReduce lands
     private Mask applyGeneric(Array array, Mask current, Predicate predicate, Arena arena, long n) {
         long bytes = (n + 7) >>> 3;
         // Arena.allocate zero-fills (FFM spec), so the unselected bits are already 0 — the loop