Task #10: Implement DeriveFieldGuarantee function (#25)

- Converts ORC column statistics into guarantee expressions
- Handles all-null case (num_values=0): returns is_null(field)
- Handles single-value case (min==max): returns field==value with null handling
- Handles range case (min<max): returns field in [min, max] with null handling
- Validates statistics: ignores deprecated or corrupted stats (min>max)
- Returns nullopt for incomplete or missing statistics (conservative fallback)

Verified:
- Checks is_statistics_deprecated flag before using stats
- Properly handles has_null flag for null value inclusion
- Validates min <= max to detect corrupted statistics
- Uses std::optional for safe failure handling

Author: cbb330

cpp/src/arrow/dataset/file_orc.cc

@@ -337,6 +337,100 @@ std::vector<PredicateField> ResolvePredicateFields(
   return resolved_fields;
 }
 
+/// \brief Derive guarantee expression from stripe column statistics
+///
+/// Converts ORC column statistics into an Arrow expression that represents
+/// the guarantee about values in this stripe. This guarantee can be used
+/// to simplify predicates and potentially eliminate the stripe entirely.
+///
+/// Returns std::nullopt if:
+/// - Statistics are deprecated (ORC writer indicated they're unreliable)
+/// - Statistics are missing or incomplete
+/// - Statistics are corrupted (min > max)
+///
+/// Special cases:
+/// - All null (num_values == 0): returns "is_null(field_ref)"
+/// - Single value (min == max): returns "field_ref == value OR is_null(field_ref)"
+///   (if has_null) or "field_ref == value" (if !has_null)
+/// - Range (min != max): returns "field_ref >= min AND field_ref <= max"
+///   plus "OR is_null(field_ref)" if has_null
+///
+/// \param field_ref The field reference for the expression
+/// \param field_type The Arrow data type of the field
+/// \param stats The ORC column statistics for this stripe
+/// \return Guarantee expression, or nullopt if statistics can't be used
+std::optional<compute::Expression> DeriveFieldGuarantee(
+    const FieldRef& field_ref,
+    const std::shared_ptr<DataType>& field_type,
+    const adapters::orc::ColumnStatistics& stats) {
+  auto field_expr = compute::field_ref(field_ref);
+
+  // Check if statistics are deprecated (writer indicates they're unreliable)
+  if (stats.is_statistics_deprecated) {
+    return std::nullopt;
+  }
+
+  // Determine if the stripe may contain null values
+  bool may_have_null = stats.has_null;
+
+  // Special case: All values are null (no non-null values)
+  if (stats.num_values == 0) {
+    // The entire stripe is either empty or all nulls
+    // Return "is_null(field_ref)" as the guarantee
+    return compute::is_null(std::move(field_expr));
+  }
+
+  // Check if min/max statistics are available
+  if (!stats.has_minimum || !stats.has_maximum) {
+    // Incomplete statistics - can't derive useful guarantees
+    return std::nullopt;
+  }
+
+  // Get min and max scalars
+  auto min = stats.minimum;
+  auto max = stats.maximum;
+
+  if (!min || !max) {
+    // Missing scalar values
+    return std::nullopt;
+  }
+
+  // Validate statistics: min should not be greater than max
+  // If this occurs, statistics are corrupted and should not be trusted
+  if (min->type()->id() == max->type()->id()) {
+    auto cmp_result = Scalar::Compare(*min, *max);
+    if (!cmp_result.ok() || *cmp_result == CompareOperator::GREATER) {
+      // Corrupted statistics (min > max) - don't use them
+      return std::nullopt;
+    }
+  }
+
+  // Case 1: Single value (min == max)
+  if (min->Equals(*max)) {
+    auto single_value = compute::equal(field_expr, compute::literal(min));
+
+    if (!may_have_null) {
+      // All non-null values equal this value, no nulls present
+      return single_value;
+    }
+    // Values are either this single value OR null
+    return compute::or_(std::move(single_value), compute::is_null(std::move(field_expr)));
+  }
+
+  // Case 2: Range of values (min < max)
+  auto lower_bound = compute::greater_equal(field_expr, compute::literal(min));
+  auto upper_bound = compute::less_equal(field_expr, compute::literal(max));
+  auto in_range = compute::and_(std::move(lower_bound), std::move(upper_bound));
+
+  if (!may_have_null) {
+    // All values are within [min, max], no nulls
+    return in_range;
+  }
+
+  // Values are within [min, max] OR null
+  return compute::or_(std::move(in_range), compute::is_null(std::move(field_expr)));
+}
+
 /// \brief A ScanTask backed by an ORC file.
 class OrcScanTask {
  public: