Opt-in overflow tracking for decimal fixed-point arithmetic

cpp/CMakeLists.txt

@@ -99,7 +99,6 @@ mark_as_advanced(CUDF_BUILD_STREAMS_TEST_UTIL)
 option(CUDF_CLANG_TIDY "Enable clang-tidy during compilation" OFF)
 option(CUDF_IWYU "Enable IWYU during compilation" OFF)
 option(CUDF_CLANG_TIDY_AUTOFIX "Enable clang-tidy autofixes" OFF)
-
 option(
   CUDF_KVIKIO_REMOTE_IO
   "Enable remote IO (e.g. AWS S3) support through KvikIO. If disabled, cudf-python will still be able to do remote IO through fsspec."
@@ -452,6 +451,7 @@ add_library(
   src/binaryop/compiled/Sub.cu
   src/binaryop/compiled/TrueDiv.cu
   src/binaryop/compiled/binary_ops.cu
+  src/binaryop/compiled/binary_ops_safe.cu
   src/binaryop/compiled/equality_ops.cu
   src/binaryop/compiled/util.cpp
   src/labeling/label_bins.cu

cpp/include/cudf/binaryop.hpp

@@ -10,7 +10,9 @@
 #include <cudf/utilities/export.hpp>
 #include <cudf/utilities/memory_resource.hpp>
 
+#include <cstdint>
 #include <memory>
+#include <utility>
 
 namespace CUDF_EXPORT cudf {
 
@@ -221,6 +223,46 @@ std::unique_ptr<column> binary_operation(
   rmm::cuda_stream_view stream      = cudf::get_default_stream(),
   rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
+/**
+ * @brief Decimal fixed-point binary operation with a per-row overflow column.
+ *
+ * Like `binary_operation` for two base-10 decimal operands, but additionally returns a
+ * `BOOL8` column of the same length as the result. Element `i` of that column is `true`
+ * iff row `i` is an **active** (non-null on both sides) row whose arithmetic or rescale
+ * to @p output_type overflowed. Rows that are null on either side, or rows whose
+ * arithmetic completed without overflow, hold `false`. The overflow column has no null
+ * mask.
+ *
+ * Supported operators: ADD, SUB, MUL, DIV, MOD, PMOD, PYMOD.
+ *
+ * @return A pair `{result, overflow}` where `result` is the arithmetic result column
+ *         (same semantics as `binary_operation`) and `overflow` is the per-row BOOL8
+ *         overflow column described above.
+ */
+std::pair<std::unique_ptr<column>, std::unique_ptr<column>> binary_operation_safe(
+  scalar const& lhs,
+  column_view const& rhs,
+  binary_operator op,
+  data_type output_type,
+  rmm::cuda_stream_view stream      = cudf::get_default_stream(),
+  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
+
+std::pair<std::unique_ptr<column>, std::unique_ptr<column>> binary_operation_safe(
+  column_view const& lhs,
+  scalar const& rhs,
+  binary_operator op,
+  data_type output_type,
+  rmm::cuda_stream_view stream      = cudf::get_default_stream(),
+  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
+
+std::pair<std::unique_ptr<column>, std::unique_ptr<column>> binary_operation_safe(
+  column_view const& lhs,
+  column_view const& rhs,
+  binary_operator op,
+  data_type output_type,
+  rmm::cuda_stream_view stream      = cudf::get_default_stream(),
+  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
+
 /**
  * @brief Performs a binary operation between two columns using a
  * user-defined PTX function.

cpp/include/cudf/fixed_point/detail/safe_arithmetic.hpp

@@ -0,0 +1,273 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <cudf/fixed_point/detail/floating_conversion.hpp>
+#include <cudf/fixed_point/fixed_point.hpp>
+#include <cudf/utilities/export.hpp>
+#include <cudf/utilities/traits.hpp>
+
+#include <cuda/std/type_traits>
+#include <cuda/std/utility>
+
+/**
+ * @file safe_arithmetic.hpp
+ * @brief Overflow-aware free functions for `numeric::fixed_point`.
+ *
+ * These free functions intentionally live outside of `fixed_point` itself
+ * (mirroring how `floating_conversion.hpp` lives outside `fixed_point` for the
+ * float<->decimal conversion path). They take regular, non-tracking
+ * `fixed_point` operands and return a `safe_result` that pairs the computed
+ * value with an `overflow` flag describing whether the operation -- including
+ * any internal rescale -- would have wrapped the underlying integer storage.
+ *
+ * The intent is that overflow-aware code paths (the `binary_operation_safe`
+ * kernel today; specialized reduce/groupby aggregations in the future) compose
+ * these primitives explicitly, instead of relying on a sticky bit baked into
+ * the value type.
+ */
+
+namespace CUDF_EXPORT numeric {
+namespace detail {
+
+/**
+ * @brief Result of an overflow-checked `fixed_point` operation.
+ *
+ * @tparam Rep Storage type of the wrapped `fixed_point` value
+ * @tparam Rad Radix of the wrapped `fixed_point` value
+ */
+template <typename Rep, Radix Rad>
+struct safe_result {
+  fixed_point<Rep, Rad> value;  ///< Computed `fixed_point` value
+  bool overflow;                ///< Whether the producing operation overflowed
+};
+
+/**
+ * @brief Whether `shift<Rep, Rad>(val, scale)` would incur signed-integer overflow
+ *
+ * Mirrors the overflow conditions of `multiplication_overflow` /
+ * `division_overflow` on the intermediate scale factor.
+ *
+ * @tparam Rep Representation type
+ * @tparam Rad Radix
+ * @tparam T   Type of the value being shifted (typically `Rep`)
+ * @param val The value being shifted
+ * @param scale The amount to shift the value by
+ * @return true if the shift would overflow `Rep`, false otherwise
+ */
+template <typename Rep, Radix Rad, typename T>
+CUDF_HOST_DEVICE inline constexpr bool shift_overflows(T const& val, scale_type const& scale)
+{
+  auto const v = static_cast<Rep>(val);
+  if (scale == 0) { return false; }
+  if (scale > 0) {
+    Rep const divisor = ipow<Rep, Rad>(static_cast<int32_t>(scale));
+    return division_overflow<Rep>(v, divisor);
+  }
+  Rep const multiplier = ipow<Rep, Rad>(static_cast<int32_t>(-scale));
+  return multiplication_overflow<Rep>(v, multiplier);
+}
+
+/**
+ * @brief Rescale a `fixed_point` value, reporting whether the underlying shift overflows
+ *
+ * Equivalent to `x.rescaled(new_scale)` but surfaces the shift overflow flag
+ * instead of dropping it.
+ *
+ * @tparam Rep Storage type
+ * @tparam Rad Radix
+ * @param x The value to rescale
+ * @param new_scale The target scale
+ * @return `{rescaled_value, overflow}`
+ */
+template <typename Rep, Radix Rad>
+CUDF_HOST_DEVICE inline safe_result<Rep, Rad> safe_rescaled(fixed_point<Rep, Rad> x,
+                                                            scale_type new_scale)
+{
+  if (new_scale == x.scale()) { return safe_result<Rep, Rad>{x, false}; }
+  auto const scale_delta = scale_type{new_scale - x.scale()};
+  bool const overflow    = shift_overflows<Rep, Rad>(x.value(), scale_delta);
+  Rep const value        = shift<Rep, Rad>(x.value(), scale_delta);
+  return safe_result<Rep, Rad>{fixed_point<Rep, Rad>{scaled_integer<Rep>{value, new_scale}},
+                               overflow};
+}
+
+/**
+ * @brief Overflow-checked addition of two `fixed_point` values
+ *
+ * Rescales both operands to the smaller of their two scales (matching
+ * `operator+`), then performs the add. The returned `overflow` flag is the
+ * disjunction of any rescale overflow and the integer add overflow.
+ */
+template <typename Rep, Radix Rad>
+CUDF_HOST_DEVICE inline safe_result<Rep, Rad> safe_add(fixed_point<Rep, Rad> lhs,
+                                                       fixed_point<Rep, Rad> rhs)
+{
+  auto const common_scale = cuda::std::min(lhs.scale(), rhs.scale());
+  auto const lhs_r        = safe_rescaled(lhs, common_scale);
+  auto const rhs_r        = safe_rescaled(rhs, common_scale);
+  Rep const lv            = lhs_r.value.value();
+  Rep const rv            = rhs_r.value.value();
+  bool const op_overflow  = addition_overflow<Rep>(lv, rv);
+  Rep const sum           = lv + rv;
+  return safe_result<Rep, Rad>{
+    fixed_point<Rep, Rad>{scaled_integer<Rep>{sum, common_scale}},
+    op_overflow || lhs_r.overflow || rhs_r.overflow};
+}
+
+/**
+ * @brief Overflow-checked subtraction of two `fixed_point` values
+ */
+template <typename Rep, Radix Rad>
+CUDF_HOST_DEVICE inline safe_result<Rep, Rad> safe_sub(fixed_point<Rep, Rad> lhs,
+                                                       fixed_point<Rep, Rad> rhs)
+{
+  auto const common_scale = cuda::std::min(lhs.scale(), rhs.scale());
+  auto const lhs_r        = safe_rescaled(lhs, common_scale);
+  auto const rhs_r        = safe_rescaled(rhs, common_scale);
+  Rep const lv            = lhs_r.value.value();
+  Rep const rv            = rhs_r.value.value();
+  bool const op_overflow  = subtraction_overflow<Rep>(lv, rv);
+  Rep const diff          = lv - rv;
+  return safe_result<Rep, Rad>{
+    fixed_point<Rep, Rad>{scaled_integer<Rep>{diff, common_scale}},
+    op_overflow || lhs_r.overflow || rhs_r.overflow};
+}
+
+/**
+ * @brief Overflow-checked multiplication of two `fixed_point` values
+ *
+ * No rescale is needed -- the result scale is `lhs.scale() + rhs.scale()`.
+ */
+template <typename Rep, Radix Rad>
+CUDF_HOST_DEVICE inline safe_result<Rep, Rad> safe_mul(fixed_point<Rep, Rad> lhs,
+                                                       fixed_point<Rep, Rad> rhs)
+{
+  Rep const lv           = lhs.value();
+  Rep const rv           = rhs.value();
+  bool const op_overflow = multiplication_overflow<Rep>(lv, rv);
+  Rep const prod         = lv * rv;
+  scale_type const out_scale{lhs.scale() + rhs.scale()};
+  return safe_result<Rep, Rad>{fixed_point<Rep, Rad>{scaled_integer<Rep>{prod, out_scale}},
+                               op_overflow};
+}
+
+/**
+ * @brief Overflow-checked division of two `fixed_point` values
+ *
+ * Only `INT_MIN / -1` is a signed-integer division overflow; that's exactly what
+ * `division_overflow` catches.
+ */
+template <typename Rep, Radix Rad>
+CUDF_HOST_DEVICE inline safe_result<Rep, Rad> safe_div(fixed_point<Rep, Rad> lhs,
+                                                       fixed_point<Rep, Rad> rhs)
+{
+  Rep const lv           = lhs.value();
+  Rep const rv           = rhs.value();
+  bool const op_overflow = division_overflow<Rep>(lv, rv);
+  Rep const quot         = lv / rv;
+  scale_type const out_scale{lhs.scale() - rhs.scale()};
+  return safe_result<Rep, Rad>{fixed_point<Rep, Rad>{scaled_integer<Rep>{quot, out_scale}},
+                               op_overflow};
+}
+
+/**
+ * @brief Overflow-checked modulo of two `fixed_point` values
+ *
+ * Integer `%` itself cannot overflow when both operands are representable, so
+ * the only overflow source is the rescale to the common scale.
+ */
+template <typename Rep, Radix Rad>
+CUDF_HOST_DEVICE inline safe_result<Rep, Rad> safe_mod(fixed_point<Rep, Rad> lhs,
+                                                       fixed_point<Rep, Rad> rhs)
+{
+  auto const common_scale = cuda::std::min(lhs.scale(), rhs.scale());
+  auto const lhs_r        = safe_rescaled(lhs, common_scale);
+  auto const rhs_r        = safe_rescaled(rhs, common_scale);
+  Rep const remainder     = lhs_r.value.value() % rhs_r.value.value();
+  return safe_result<Rep, Rad>{
+    fixed_point<Rep, Rad>{scaled_integer<Rep>{remainder, common_scale}},
+    lhs_r.overflow || rhs_r.overflow};
+}
+
+/**
+ * @brief Overflow-checked positive modulo, matching `ops::PMod` semantics for decimals.
+ *
+ * Implements `rem = x % y; (rem < 0) ? (rem + y) % y : rem`. The intermediate
+ * `rem + y` can overflow even though `%` itself cannot, so this surfaces the
+ * add overflow in addition to the rescale overflows reported by `safe_mod`.
+ */
+template <typename Rep, Radix Rad>
+CUDF_HOST_DEVICE inline safe_result<Rep, Rad> safe_pmod(fixed_point<Rep, Rad> lhs,
+                                                        fixed_point<Rep, Rad> rhs)
+{
+  auto const m = safe_mod(lhs, rhs);
+  if (!(m.value.value() < Rep{0})) { return m; }
+
+  auto const rhs_r       = safe_rescaled(rhs, m.value.scale());
+  Rep const mv           = m.value.value();
+  Rep const rv           = rhs_r.value.value();
+  bool const add_overflow = addition_overflow<Rep>(mv, rv);
+  Rep const corrected    = (mv + rv) % rv;
+  return safe_result<Rep, Rad>{
+    fixed_point<Rep, Rad>{scaled_integer<Rep>{corrected, m.value.scale()}},
+    m.overflow || rhs_r.overflow || add_overflow};
+}
+
+/**
+ * @brief Overflow-checked Python-style modulo: `((x % y) + y) % y`.
+ *
+ * The intermediate add can overflow; the final `%` cannot.
+ */
+template <typename Rep, Radix Rad>
+CUDF_HOST_DEVICE inline safe_result<Rep, Rad> safe_pymod(fixed_point<Rep, Rad> lhs,
+                                                         fixed_point<Rep, Rad> rhs)
+{
+  auto const m = safe_mod(lhs, rhs);
+
+  auto const rhs_r       = safe_rescaled(rhs, m.value.scale());
+  Rep const mv           = m.value.value();
+  Rep const rv           = rhs_r.value.value();
+  bool const add_overflow = addition_overflow<Rep>(mv, rv);
+  Rep const corrected    = (mv + rv) % rv;
+  return safe_result<Rep, Rad>{
+    fixed_point<Rep, Rad>{scaled_integer<Rep>{corrected, m.value.scale()}},
+    m.overflow || rhs_r.overflow || add_overflow};
+}
+
+/**
+ * @brief Overflow-checked floating-point -> `fixed_point` conversion
+ *
+ * Uses `convert_floating_to_integral<Rep, true>` (in
+ * `floating_conversion.hpp`) for base-10 decimals, which saturates and reports
+ * overflow. For base-2 radixes there is no checked path today, so `overflow`
+ * is always `false`.
+ *
+ * @tparam Fixed    Target `fixed_point` instantiation
+ * @tparam Floating Source floating-point type
+ * @param floating  The floating-point value to convert
+ * @param scale     The desired scale of the result
+ * @return `{fixed_point_value, overflow}`
+ */
+template <typename Fixed,
+          typename Floating,
+          CUDF_ENABLE_IF(cuda::std::is_floating_point_v<Floating> &&
+                         cudf::is_fixed_point<Fixed>())>
+CUDF_HOST_DEVICE inline safe_result<typename Fixed::rep, Fixed::rad>
+safe_convert_floating_to_fixed(Floating floating, scale_type scale)
+{
+  using Rep = typename Fixed::rep;
+  if constexpr (Fixed::rad == Radix::BASE_10) {
+    auto const [value, overflow] = convert_floating_to_integral<Rep, true>(floating, scale);
+    return safe_result<Rep, Fixed::rad>{Fixed{scaled_integer<Rep>{value, scale}}, overflow};
+  } else {
+    Rep const value = static_cast<Rep>(shift<Rep, Fixed::rad>(floating, scale));
+    return safe_result<Rep, Fixed::rad>{Fixed{scaled_integer<Rep>{value, scale}}, false};
+  }
+}
+
+}  // namespace detail
+}  // namespace CUDF_EXPORT numeric

cpp/include/cudf/fixed_point/fixed_point.hpp

@@ -663,10 +663,8 @@ CUDF_HOST_DEVICE inline fixed_point<Rep1, Rad1> operator+(fixed_point<Rep1, Rad1
   auto const sum   = lhs.rescaled(scale)._value + rhs.rescaled(scale)._value;
 
 #if defined(__CUDACC_DEBUG__)
-
   assert(!addition_overflow<Rep1>(lhs.rescaled(scale)._value, rhs.rescaled(scale)._value) &&
          "fixed_point overflow");
-
 #endif
 
   return fixed_point<Rep1, Rad1>{scaled_integer<Rep1>{sum, scale}};
@@ -681,10 +679,8 @@ CUDF_HOST_DEVICE inline fixed_point<Rep1, Rad1> operator-(fixed_point<Rep1, Rad1
   auto const diff  = lhs.rescaled(scale)._value - rhs.rescaled(scale)._value;
 
 #if defined(__CUDACC_DEBUG__)
-
   assert(!subtraction_overflow<Rep1>(lhs.rescaled(scale)._value, rhs.rescaled(scale)._value) &&
          "fixed_point overflow");
-
 #endif
 
   return fixed_point<Rep1, Rad1>{scaled_integer<Rep1>{diff, scale}};
@@ -696,9 +692,7 @@ CUDF_HOST_DEVICE inline fixed_point<Rep1, Rad1> operator*(fixed_point<Rep1, Rad1
                                                           fixed_point<Rep1, Rad1> const& rhs)
 {
 #if defined(__CUDACC_DEBUG__)
-
   assert(!multiplication_overflow<Rep1>(lhs._value, rhs._value) && "fixed_point overflow");
-
 #endif
 
   return fixed_point<Rep1, Rad1>{
@@ -711,9 +705,7 @@ CUDF_HOST_DEVICE inline fixed_point<Rep1, Rad1> operator/(fixed_point<Rep1, Rad1
                                                           fixed_point<Rep1, Rad1> const& rhs)
 {
 #if defined(__CUDACC_DEBUG__)
-
   assert(!division_overflow<Rep1>(lhs._value, rhs._value) && "fixed_point overflow");
-
 #endif
 
   return fixed_point<Rep1, Rad1>{

cpp/include/cudf/utilities/type_dispatcher.hpp

@@ -206,7 +206,8 @@ constexpr bool type_id_matches_device_storage_type(type_id id)
 {
   return (id == type_id::DECIMAL32 && std::is_same_v<T, int32_t>) ||
          (id == type_id::DECIMAL64 && std::is_same_v<T, int64_t>) ||
-         (id == type_id::DECIMAL128 && std::is_same_v<T, __int128_t>) || id == type_to_id<T>();
+         (id == type_id::DECIMAL128 && std::is_same_v<T, __int128_t>) ||
+         id == type_to_id<T>();
 }
 
 /**