libmongocrypt-helper 1.8.0.0.1001 → 1.11.0.0.1001

data/ext/libmongocrypt/libmongocrypt/src/mc-range-encoding.c

@@ -162,8 +162,131 @@ bool mc_getTypeInfo64(mc_getTypeInfo64_args_t args, mc_OSTType_Int64 *out, mongo
 }
 
 #define exp10Double(x) pow(10, x)
+#define SCALED_DOUBLE_BOUNDS 9007199254740992.0 // 2^53
+
+uint64_t subtract_int64_t(int64_t max, int64_t min) {
+    BSON_ASSERT(max > min);
+    // If the values have the same sign, then simple subtraction
+    // will work because we know max > min.
+    if ((max > 0 && min > 0) || (max < 0 && min < 0)) {
+        return (uint64_t)(max - min);
+    }
+
+    // If they are opposite signs, then we can just invert
+    // min to be positive and return the sum.
+    uint64_t u_return = (uint64_t)max;
+    u_return += (uint64_t)(~min + 1);
+    return u_return;
+}
+
+bool ceil_log2_double(uint64_t i, uint32_t *maxBitsOut, mongocrypt_status_t *status) {
+    if (i == 0) {
+        CLIENT_ERR("Invalid input to ceil_log2_double function. Input cannot be 0.");
+        return false;
+    }
+
+    uint32_t clz = (uint32_t)_mlibCountLeadingZeros_u64(i);
+    uint32_t bits;
+    if ((i & (i - 1)) == 0) {
+        bits = 64 - clz - 1;
+    } else {
+        bits = 64 - clz;
+    }
+    *maxBitsOut = bits;
+    return true;
+}
+
+bool mc_canUsePrecisionModeDouble(double min,
+                                  double max,
+                                  int32_t precision,
+                                  uint32_t *maxBitsOut,
+                                  mongocrypt_status_t *status) {
+    BSON_ASSERT_PARAM(maxBitsOut);
+    BSON_ASSERT(precision >= 0);
+
+    if (min >= max) {
+        CLIENT_ERR("Invalid bounds for double range precision, min must be less than max. min: %g, max: %g", min, max);
+        return false;
+    }
+
+    const double scaled_prc = exp10Double(precision);
+
+    const double scaled_max = max * scaled_prc;
+    const double scaled_min = min * scaled_prc;
+
+    if (scaled_max != trunc(scaled_max)) {
+        CLIENT_ERR("Invalid upper bound for double precision. Fractional digits must be less than the specified "
+                   "precision value. max: %g",
+                   max);
+        return false;
+    }
+
+    if (scaled_min != trunc(scaled_min)) {
+        CLIENT_ERR("Invalid lower bound for double precision. Fractional digits must be less than the specified "
+                   "precision value. min: %g",
+                   min);
+        return false;
+    }
+
+    if (fabs(scaled_max) >= SCALED_DOUBLE_BOUNDS) {
+        CLIENT_ERR(
+            "Invalid upper bound for double precision. Absolute scaled value of max must be less than %g. max: %g",
+            SCALED_DOUBLE_BOUNDS,
+            max);
+        return false;
+    }
+
+    if (fabs(scaled_min) >= SCALED_DOUBLE_BOUNDS) {
+        CLIENT_ERR(
+            "Invalid lower bound for double precision. Absolute scaled value of min must be less than %g. min: %g",
+            SCALED_DOUBLE_BOUNDS,
+            min);
+        return false;
+    }
+
+    const double t_1 = scaled_max - scaled_min;
+    const double t_4 = (double)UINT64_MAX - t_1;
+    const double t_5 = floor(log10(t_4)) - 1;
+
+    if ((double)precision > t_5) {
+        CLIENT_ERR("Invalid value for precision. precision: %" PRId32, precision);
+        return false;
+    }
+
+    const int64_t i_1 = (int64_t)(scaled_max);
+    const int64_t i_2 = (int64_t)(scaled_min);
+
+    const uint64_t range = subtract_int64_t(i_1, i_2);
+
+    if (((uint64_t)scaled_prc) > UINT64_MAX - range) {
+        CLIENT_ERR("Invalid value for min, max, and precision. The calculated domain size is too large. min: %g, max: "
+                   "%g, precision: %" PRId32,
+                   min,
+                   max,
+                   precision);
+        return false;
+    }
+
+    const uint64_t i_3 = range + (uint64_t)(scaled_prc);
 
-bool mc_getTypeInfoDouble(mc_getTypeInfoDouble_args_t args, mc_OSTType_Double *out, mongocrypt_status_t *status) {
+    if (!ceil_log2_double(i_3, maxBitsOut, status)) {
+        return false;
+    }
+
+    // Integers between -2^53 and 2^53 can be exactly represented. Outside this range, doubles lose precision by a
+    // multiple of 2^(n-52) where n = #bits. We disallow users from using precision mode when the bounds exceed 2^53 to
+    // prevent the users from being surprised by how floating point math works.
+    if (*maxBitsOut >= 53) {
+        return false;
+    }
+
+    return true;
+}
+
+bool mc_getTypeInfoDouble(mc_getTypeInfoDouble_args_t args,
+                          mc_OSTType_Double *out,
+                          mongocrypt_status_t *status,
+                          bool use_range_v2) {
     if (args.min.set != args.max.set || args.min.set != args.precision.set) {
         CLIENT_ERR("min, max, and precision must all be set or must all be unset");
         return false;
@@ -194,6 +317,19 @@ bool mc_getTypeInfoDouble(mc_getTypeInfoDouble_args_t args, mc_OSTType_Double *o
         }
     }
 
+    if (args.precision.set) {
+        if (args.precision.value < 0) {
+            CLIENT_ERR("Precision must be non-negative, but got %" PRId32, args.precision.value);
+            return false;
+        }
+
+        double scaled = exp10Double(args.precision.value);
+        if (!mc_isfinite(scaled)) {
+            CLIENT_ERR("Precision is too large and cannot be used to calculate the scaled range bounds");
+            return false;
+        }
+    }
+
     const bool is_neg = args.value < 0.0;
 
     // Map negative 0 to zero so sign bit is 0.
@@ -210,39 +346,33 @@ bool mc_getTypeInfoDouble(mc_getTypeInfoDouble_args_t args, mc_OSTType_Double *o
     bool use_precision_mode = false;
     uint32_t bits_range;
     if (args.precision.set) {
-        // Subnormal representations can support up to 5x10^-324 as a number
-        if (args.precision.value > 324) {
-            CLIENT_ERR("Precision must be between 0 and 324 inclusive, got: %" PRIu32, args.precision.value);
-            return false;
-        }
-
-        double range = args.max.value - args.min.value;
+        use_precision_mode =
+            mc_canUsePrecisionModeDouble(args.min.value, args.max.value, args.precision.value, &bits_range, status);
 
-        // We can overflow if max = max double and min = min double so make sure
-        // we have finite number after we do subtraction
-        // Ignore conversion warnings to fix error with glibc.
-        if (mc_isfinite(range)) {
-            // This creates a range which is wider then we permit by our min/max
-            // bounds check with the +1 but it is as the algorithm is written in
-            // WRITING-11907.
-            double rangeAndPrecision = (range + 1) * exp10Double(args.precision.value);
-
-            if (mc_isfinite(rangeAndPrecision)) {
-                double bits_range_double = log2(rangeAndPrecision);
-                bits_range = (uint32_t)ceil(bits_range_double);
-
-                if (bits_range < 64) {
-                    use_precision_mode = true;
-                }
+        if (!use_precision_mode && use_range_v2) {
+            if (!mongocrypt_status_ok(status)) {
+                return false;
             }
+
+            CLIENT_ERR("The domain of double values specified by the min, max, and precision cannot be represented in "
+                       "fewer than 53 bits. min: %g, max: %g, precision: %" PRId32,
+                       args.min.value,
+                       args.max.value,
+                       args.precision.value);
+            return false;
         }
+
+        // If we are not in range_v2, then we don't care about the error returned
+        // from canUsePrecisionMode so we can reset the status.
+        _mongocrypt_status_reset(status);
     }
 
     if (use_precision_mode) {
         // Take a number of xxxx.ppppp and truncate it xxxx.ppp if precision = 3.
         // We do not change the digits before the decimal place.
-        double v_prime = trunc(args.value * exp10Double(args.precision.value)) / exp10Double(args.precision.value);
-        int64_t v_prime2 = (int64_t)((v_prime - args.min.value) * exp10Double(args.precision.value));
+        int64_t v_prime = (int64_t)(trunc(args.value * exp10Double(args.precision.value)));
+        int64_t scaled_min = (int64_t)(args.min.value * exp10Double(args.precision.value));
+        int64_t v_prime2 = v_prime - scaled_min;
 
         BSON_ASSERT(v_prime2 < INT64_MAX && v_prime2 >= 0);
 
@@ -298,7 +428,7 @@ bool mc_getTypeInfoDouble(mc_getTypeInfoDouble_args_t args, mc_OSTType_Double *o
  * @param dec
  * @return mlib_int128
  */
-static mlib_int128 dec128_to_int128(mc_dec128 dec) {
+static mlib_int128 dec128_to_uint128(mc_dec128 dec) {
     // Only normal numbers
     BSON_ASSERT(mc_dec128_is_finite(dec));
     BSON_ASSERT(!mc_dec128_is_nan(dec));
@@ -313,6 +443,7 @@ static mlib_int128 dec128_to_int128(mc_dec128 dec) {
     // Decimal128:
     int32_t exp = ((int32_t)mc_dec128_get_biased_exp(dec)) - MC_DEC128_EXPONENT_BIAS;
     // We will scale up/down based on whether it is negative:
+    BSON_ASSERT(abs(exp) <= UINT8_MAX);
     mlib_int128 e1 = mlib_int128_pow10((uint8_t)abs(exp));
     if (exp < 0) {
         ret = mlib_int128_div(ret, e1);
@@ -323,15 +454,176 @@ static mlib_int128 dec128_to_int128(mc_dec128 dec) {
     return ret;
 }
 
+// (2^127 - 1) = the maximum signed 128-bit integer value, as a decimal128
+#define INT_128_MAX_AS_DECIMAL mc_dec128_from_string("170141183460469231731687303715884105727")
+// (2^128 - 1) = the max unsigned 128-bit integer value, as a decimal128
+#define UINT_128_MAX_AS_DECIMAL mc_dec128_from_string("340282366920938463463374607431768211455")
+
+static mlib_int128 dec128_to_int128(mc_dec128 dec) {
+    BSON_ASSERT(mc_dec128_less(dec, INT_128_MAX_AS_DECIMAL));
+
+    bool negative = false;
+
+    if (mc_dec128_is_negative(dec)) {
+        negative = true;
+        dec = mc_dec128_mul(MC_DEC128(-1), dec);
+    }
+
+    mlib_int128 ret_val = dec128_to_uint128(dec);
+
+    if (negative) {
+        ret_val = mlib_int128_mul(MLIB_INT128(-1), ret_val);
+    }
+
+    return ret_val;
+}
+
+bool ceil_log2_int128(mlib_int128 i, uint32_t *maxBitsOut, mongocrypt_status_t *status) {
+    if (mlib_int128_eq(i, MLIB_INT128(0))) {
+        CLIENT_ERR("Invalid input to ceil_log2_int128 function. Input cannot be 0.");
+        return false;
+    }
+
+    uint32_t clz = (uint32_t)_mlibCountLeadingZeros_u128(i);
+    uint32_t bits;
+
+    // if i & (i - 1) == 0
+    if (mlib_int128_eq((mlib_int128_bitand(i, (mlib_int128_sub(i, MLIB_INT128(1))))), MLIB_INT128(0))) {
+        bits = 128 - clz - 1;
+    } else {
+        bits = 128 - clz;
+    }
+    *maxBitsOut = bits;
+    return true;
+}
+
+bool mc_canUsePrecisionModeDecimal(mc_dec128 min,
+                                   mc_dec128 max,
+                                   int32_t precision,
+                                   uint32_t *maxBitsOut,
+                                   mongocrypt_status_t *status) {
+    BSON_ASSERT_PARAM(maxBitsOut);
+    BSON_ASSERT(precision >= 0);
+
+    if (!mc_dec128_is_finite(max)) {
+        CLIENT_ERR("Invalid upper bound for Decimal128 precision. Max is infinite.");
+        return false;
+    }
+
+    if (!mc_dec128_is_finite(min)) {
+        CLIENT_ERR("Invalid lower bound for Decimal128 precision. Min is infinite.");
+        return false;
+    }
+
+    if (mc_dec128_greater_equal(min, max)) {
+        CLIENT_ERR("Invalid upper and lower bounds for Decimal128 precision. Min must be strictly less than max. min: "
+                   "%s, max: %s",
+                   mc_dec128_to_string(min).str,
+                   mc_dec128_to_string(max).str);
+        return false;
+    }
+
+    mc_dec128 scaled_max = mc_dec128_scale(max, precision);
+    mc_dec128 scaled_min = mc_dec128_scale(min, precision);
+
+    mc_dec128 scaled_max_trunc = mc_dec128_round_integral_ex(scaled_max, MC_DEC128_ROUND_TOWARD_ZERO, NULL);
+    mc_dec128 scaled_min_trunc = mc_dec128_round_integral_ex(scaled_min, MC_DEC128_ROUND_TOWARD_ZERO, NULL);
+
+    if (mc_dec128_not_equal(scaled_max, scaled_max_trunc)) {
+        CLIENT_ERR("Invalid upper bound for Decimal128 precision. Fractional digits must be less than "
+                   "the specified precision value. max: %s, precision: %" PRId32,
+                   mc_dec128_to_string(max).str,
+                   precision);
+        return false;
+    }
+
+    if (mc_dec128_not_equal(scaled_min, scaled_min_trunc)) {
+        CLIENT_ERR("Invalid lower bound for Decimal128 precision. Fractional digits must be less than "
+                   "the specified precision value. min: %s, precision: %" PRId32,
+                   mc_dec128_to_string(min).str,
+                   precision);
+        return false;
+    }
+
+    if (mc_dec128_greater(mc_dec128_abs(scaled_max), INT_128_MAX_AS_DECIMAL)) {
+        CLIENT_ERR("Invalid upper bound for Decimal128 precision. Absolute scaled value must be less than "
+                   "or equal to %s. max: %s",
+                   mc_dec128_to_string(INT_128_MAX_AS_DECIMAL).str,
+                   mc_dec128_to_string(max).str);
+        return false;
+    }
+
+    if (mc_dec128_greater(mc_dec128_abs(scaled_min), INT_128_MAX_AS_DECIMAL)) {
+        CLIENT_ERR("Invalid lower bound for Decimal128 precision. Absolute scaled value must be less than "
+                   "or equal to %s. min: %s",
+                   mc_dec128_to_string(INT_128_MAX_AS_DECIMAL).str,
+                   mc_dec128_to_string(min).str);
+        return false;
+    }
+
+    mc_dec128 t_1 = mc_dec128_sub(scaled_max, scaled_min);
+    mc_dec128 t_4 = mc_dec128_sub(UINT_128_MAX_AS_DECIMAL, t_1);
+
+    // t_5 = floor(log10(t_4)) - 1;
+    mc_dec128 t_5 = mc_dec128_sub(mc_dec128_round_integral_ex(mc_dec128_log10(t_4), MC_DEC128_ROUND_TOWARD_ZERO, NULL),
+                                  MC_DEC128(1));
+
+    // We convert precision to a double so we can avoid warning C4146 on Windows.
+    mc_dec128 prc_dec = mc_dec128_from_double((double)precision);
+
+    if (mc_dec128_less(t_5, prc_dec)) {
+        CLIENT_ERR("Invalid value for precision. precision: %" PRId32, precision);
+        return false;
+    }
+
+    mlib_int128 i_1 = dec128_to_int128(scaled_max);
+    mlib_int128 i_2 = dec128_to_int128(scaled_min);
+
+    // Because we have guaranteed earlier that max is greater than min, we can
+    // subtract these values and guarantee that taking their unsigned
+    // representation will yield the actual range result.
+    mlib_int128 range128 = mlib_int128_sub(i_1, i_2);
+
+    if (precision > UINT8_MAX) {
+        CLIENT_ERR("Invalid value for precision. Must be less than 255. precision: %" PRId32, precision);
+        return false;
+    }
+
+    mlib_int128 i_3 = mlib_int128_add(range128, mlib_int128_pow10((uint8_t)precision));
+    if (!ceil_log2_int128(i_3, maxBitsOut, status)) {
+        return false;
+    }
+
+    if (*maxBitsOut >= 128) {
+        return false;
+    }
+
+    return true;
+}
+
 bool mc_getTypeInfoDecimal128(mc_getTypeInfoDecimal128_args_t args,
                               mc_OSTType_Decimal128 *out,
-                              mongocrypt_status_t *status) {
+                              mongocrypt_status_t *status,
+                              bool use_range_v2) {
     /// Basic param checks
     if (args.min.set != args.max.set || args.min.set != args.precision.set) {
         CLIENT_ERR("min, max, and precision must all be set or must all be unset");
         return false;
     }
 
+    if (args.precision.set) {
+        if (args.precision.value < 0) {
+            CLIENT_ERR("Precision must be non-negative, but got %" PRId32, args.precision.value);
+            return false;
+        }
+
+        mc_dec128 scaled = mc_dec128_scale(MC_DEC128(1), args.precision.value);
+        if (!mc_dec128_is_finite(scaled)) {
+            CLIENT_ERR("Precision is too large and cannot be used to calculate the scaled range bounds");
+            return false;
+        }
+    }
+
     // We only accept normal numbers
     if (mc_dec128_is_inf(args.value) || mc_dec128_is_nan(args.value)) {
         CLIENT_ERR("Infinity and Nan Decimal128 values are not supported.");
@@ -375,45 +667,27 @@ bool mc_getTypeInfoDecimal128(mc_getTypeInfoDecimal128_args_t args,
     // full range.
     bool use_precision_mode = false;
     // The number of bits required to hold the result (used for precision mode)
-    uint8_t bits_range = 0;
+    uint32_t bits_range = 0;
     if (args.precision.set) {
-        // Subnormal representations can support up to 5x10^-6182 as a number
-        if (args.precision.value > 6182) {
-            CLIENT_ERR("Precision must be between 0 and 6182 inclusive, got: %" PRIu32, args.precision.value);
-            return false;
-        }
+        use_precision_mode =
+            mc_canUsePrecisionModeDecimal(args.min.value, args.max.value, args.precision.value, &bits_range, status);
 
-        // max - min
-        mc_dec128 bounds_n1 = mc_dec128_sub(args.max.value, args.min.value);
-        // The size of [min, max]: (max - min) + 1
-        mc_dec128 bounds = mc_dec128_add(bounds_n1, MC_DEC128_ONE);
-
-        // We can overflow if max = max_dec128 and min = min_dec128 so make sure
-        // we have finite number after we do subtraction
-        if (mc_dec128_is_finite(bounds)) {
-            // This creates a range which is wider then we permit by our min/max
-            // bounds check with the +1 but it is as the algorithm is written in
-            // WRITING-11907.
-            mc_dec128 precision_scaled_bounds = mc_dec128_scale(bounds, args.precision.value);
-            /// The number of bits required to hold the result for the given
-            /// precision (as decimal)
-            mc_dec128 bits_range_dec = mc_dec128_log2(precision_scaled_bounds);
-
-            if (mc_dec128_is_finite(bits_range_dec) && mc_dec128_less(bits_range_dec, MC_DEC128(128))) {
-                // We need fewer than 128 bits to hold the result. But round up,
-                // just to be sure:
-                int64_t r =
-                    mc_dec128_to_int64(mc_dec128_round_integral_ex(bits_range_dec, MC_DEC128_ROUND_UPWARD, NULL));
-                BSON_ASSERT(r >= 0);
-                BSON_ASSERT(r <= UINT8_MAX);
-                // We've computed the proper 'bits_range'
-                bits_range = (uint8_t)r;
-
-                if (bits_range < 128) {
-                    use_precision_mode = true;
-                }
+        if (use_range_v2 && !use_precision_mode) {
+            if (!mongocrypt_status_ok(status)) {
+                return false;
             }
+
+            CLIENT_ERR("The domain of decimal values specified by the min, max, and precision cannot be represented in "
+                       "fewer than 128 bits. min: %s, max: %s, precision: %" PRIu32,
+                       mc_dec128_to_string(args.min.value).str,
+                       mc_dec128_to_string(args.max.value).str,
+                       args.precision.value);
+            return false;
         }
+
+        // If we are not in range_v2, then we don't care about the error returned
+        // from canUsePrecisionMode so we can reset the status.
+        _mongocrypt_status_reset(status);
     }
 
     // Constant zero
@@ -456,9 +730,9 @@ bool mc_getTypeInfoDecimal128(mc_getTypeInfoDecimal128_args_t args,
         v_prime2 = mc_dec128_round_integral_ex(v_prime2, MC_DEC128_ROUND_TOWARD_ZERO, NULL);
 
         BSON_ASSERT(mc_dec128_less(mc_dec128_log2(v_prime2), MC_DEC128(128)));
-
+        BSON_ASSERT(bits_range < 128);
         // Resulting OST maximum
-        mlib_int128 ost_max = mlib_int128_sub(mlib_int128_pow2(bits_range), i128_one);
+        mlib_int128 ost_max = mlib_int128_sub(mlib_int128_pow2((uint8_t)bits_range), i128_one);
 
         // Now we need to get the Decimal128 out as a 128-bit integer
         // But Decimal128 does not support conversion to Int128.
@@ -575,3 +849,23 @@ bool mc_getTypeInfoDecimal128(mc_getTypeInfoDecimal128_args_t args,
 }
 
 #endif // defined MONGOCRYPT_HAVE_DECIMAL128_SUPPORT
+
+const int64_t mc_FLERangeSparsityDefault = 2;
+const int32_t mc_FLERangeTrimFactorDefault = 6;
+
+int32_t trimFactorDefault(size_t maxlen, mc_optional_int32_t trimFactor, bool use_range_v2) {
+    if (trimFactor.set) {
+        return trimFactor.value;
+    }
+
+    if (!use_range_v2) {
+        // Preserve old default.
+        return 0;
+    }
+
+    if (bson_cmp_greater_su(mc_FLERangeTrimFactorDefault, maxlen - 1)) {
+        return (int32_t)(maxlen - 1);
+    } else {
+        return mc_FLERangeTrimFactorDefault;
+    }
+}

data/ext/libmongocrypt/libmongocrypt/src/mc-range-mincover-generator.template.h

@@ -17,18 +17,6 @@
 // mc-range-mincover-generator.template.h is meant to be included in another
 // source file.
 
-// TODO: replace `CONCAT` with `BSON_CONCAT` after libbson dependency is
-// upgraded to 1.20.0 or higher.
-#ifndef CONCAT
-#define CONCAT_1(a, b) a##b
-#define CONCAT(a, b) CONCAT_1(a, b)
-#endif
-// TODO: replace `CONCAT3` with `BSON_CONCAT3` after libbson dependency is
-// upgraded to 1.20.0 or higher.
-#ifndef CONCAT3
-#define CONCAT3(a, b, c) CONCAT(a, CONCAT(b, c))
-#endif
-
 #if !(defined(UINT_T) && defined(UINT_C) && defined(UINT_FMT_S) && defined(DECORATE_NAME))
 #ifdef __INTELLISENSE__
 #define UINT_T uint32_t
@@ -101,6 +89,7 @@ typedef struct {
     UINT_T _rangeMin;
     UINT_T _rangeMax;
     size_t _sparsity;
+    int32_t _trimFactor;
     // _maxlen is the maximum bit length of edges in the mincover.
     size_t _maxlen;
 } DECORATE_NAME(MinCoverGenerator);
@@ -110,7 +99,9 @@ static inline DECORATE_NAME(MinCoverGenerator)
                                            UINT_T rangeMax,
                                            UINT_T max,
                                            size_t sparsity,
-                                           mongocrypt_status_t *status) {
+                                           mc_optional_int32_t opt_trimFactor,
+                                           mongocrypt_status_t *status,
+                                           bool use_range_v2) {
     BSON_ASSERT_PARAM(status);
 
     if (UINT_COMPARE(rangeMin, rangeMax) > 0) {
@@ -131,11 +122,25 @@ static inline DECORATE_NAME(MinCoverGenerator)
         CLIENT_ERR("Sparsity must be > 0");
         return NULL;
     }
+    size_t maxlen = (size_t)BITS - DECORATE_NAME(mc_count_leading_zeros)(max);
+    int32_t trimFactor = trimFactorDefault(maxlen, opt_trimFactor, use_range_v2);
+    if (trimFactor != 0 && bson_cmp_greater_equal_su(trimFactor, maxlen)) {
+        CLIENT_ERR("Trim factor must be less than the number of bits (%ld) used to represent an element of the domain, "
+                   "but got %" PRId32,
+                   maxlen,
+                   trimFactor);
+        return NULL;
+    }
+    if (trimFactor < 0) {
+        CLIENT_ERR("Trim factor must be >= 0, but got (%" PRId32 ")", trimFactor);
+        return NULL;
+    }
     DECORATE_NAME(MinCoverGenerator) *mcg = bson_malloc0(sizeof(DECORATE_NAME(MinCoverGenerator)));
     mcg->_rangeMin = rangeMin;
     mcg->_rangeMax = rangeMax;
     mcg->_maxlen = (size_t)BITS - DECORATE_NAME(mc_count_leading_zeros)(max);
     mcg->_sparsity = sparsity;
+    mcg->_trimFactor = trimFactor;
     return mcg;
 }
 
@@ -164,7 +169,9 @@ static inline bool DECORATE_NAME(MinCoverGenerator_isLevelStored)(DECORATE_NAME(
                                                                   size_t maskedBits) {
     BSON_ASSERT_PARAM(mcg);
     size_t level = mcg->_maxlen - maskedBits;
-    return 0 == maskedBits || 0 == (level % mcg->_sparsity);
+    BSON_ASSERT(bson_in_range_size_t_signed(mcg->_trimFactor));
+    size_t trimFactor_sz = (size_t)mcg->_trimFactor;
+    return 0 == maskedBits || (level >= trimFactor_sz && 0 == (level % mcg->_sparsity));
 }
 
 char *
@@ -219,6 +226,11 @@ static inline mc_mincover_t *DECORATE_NAME(MinCoverGenerator_minCover)(DECORATE_
     return mc;
 }
 
+static inline int32_t DECORATE_NAME(MinCoverGenerator_usedTrimFactor)(DECORATE_NAME(MinCoverGenerator) * mcg) {
+    BSON_ASSERT_PARAM(mcg);
+    return mcg->_trimFactor;
+}
+
 // adjustBounds increments *lowerBound if includeLowerBound is false and
 // decrements *upperBound if includeUpperBound is false.
 // lowerBound, min, upperBound, and max are expected to come from the result

data/ext/libmongocrypt/libmongocrypt/src/mc-range-mincover-private.h

@@ -33,6 +33,9 @@ const char *mc_mincover_get(mc_mincover_t *mincover, size_t index);
 // mc_mincover_len returns the number of represented mincover.
 size_t mc_mincover_len(mc_mincover_t *mincover);
 
+// Return the trimFactor that was used to generate this mincover.
+int32_t mc_mincover_get_used_trimFactor(const mc_mincover_t *mincover);
+
 // mc_mincover_destroys frees `mincover`.
 void mc_mincover_destroy(mc_mincover_t *mincover);
 
@@ -44,12 +47,14 @@ typedef struct {
     mc_optional_int32_t min;
     mc_optional_int32_t max;
     size_t sparsity;
+    mc_optional_int32_t trimFactor;
 } mc_getMincoverInt32_args_t;
 
 // mc_getMincoverInt32 implements the Mincover Generation algorithm described in
 // SERVER-68600 for int32_t.
 mc_mincover_t *mc_getMincoverInt32(mc_getMincoverInt32_args_t args,
-                                   mongocrypt_status_t *status) MONGOCRYPT_WARN_UNUSED_RESULT;
+                                   mongocrypt_status_t *status,
+                                   bool use_range_v2) MONGOCRYPT_WARN_UNUSED_RESULT;
 
 typedef struct {
     int64_t lowerBound;
@@ -59,12 +64,14 @@ typedef struct {
     mc_optional_int64_t min;
     mc_optional_int64_t max;
     size_t sparsity;
+    mc_optional_int32_t trimFactor;
 } mc_getMincoverInt64_args_t;
 
 // mc_getMincoverInt64 implements the Mincover Generation algorithm described in
 // SERVER-68600 for int64_t.
 mc_mincover_t *mc_getMincoverInt64(mc_getMincoverInt64_args_t args,
-                                   mongocrypt_status_t *status) MONGOCRYPT_WARN_UNUSED_RESULT;
+                                   mongocrypt_status_t *status,
+                                   bool use_range_v2) MONGOCRYPT_WARN_UNUSED_RESULT;
 
 typedef struct {
     double lowerBound;
@@ -74,13 +81,15 @@ typedef struct {
     size_t sparsity;
     mc_optional_double_t min;
     mc_optional_double_t max;
-    mc_optional_uint32_t precision;
+    mc_optional_int32_t precision;
+    mc_optional_int32_t trimFactor;
 } mc_getMincoverDouble_args_t;
 
 // mc_getMincoverDouble implements the Mincover Generation algorithm described
 // in SERVER-68600 for double.
 mc_mincover_t *mc_getMincoverDouble(mc_getMincoverDouble_args_t args,
-                                    mongocrypt_status_t *status) MONGOCRYPT_WARN_UNUSED_RESULT;
+                                    mongocrypt_status_t *status,
+                                    bool use_range_v2) MONGOCRYPT_WARN_UNUSED_RESULT;
 
 #if MONGOCRYPT_HAVE_DECIMAL128_SUPPORT
 typedef struct {
@@ -90,13 +99,15 @@ typedef struct {
     bool includeUpperBound;
     size_t sparsity;
     mc_optional_dec128_t min, max;
-    mc_optional_uint32_t precision;
+    mc_optional_int32_t precision;
+    mc_optional_int32_t trimFactor;
 } mc_getMincoverDecimal128_args_t;
 
 // mc_getMincoverDecimal128 implements the Mincover Generation algorithm
 // described in SERVER-68600 for Decimal128 (as mc_dec128).
 mc_mincover_t *mc_getMincoverDecimal128(mc_getMincoverDecimal128_args_t args,
-                                        mongocrypt_status_t *status) MONGOCRYPT_WARN_UNUSED_RESULT;
+                                        mongocrypt_status_t *status,
+                                        bool use_range_v2) MONGOCRYPT_WARN_UNUSED_RESULT;
 #endif // MONGOCRYPT_HAVE_DECIMAL128_SUPPORT
 
 #endif /* MC_RANGE_MINCOVER_PRIVATE_H */