feat: AggregateSumOnRange query + proof + verify for ProvableSumTree

Adds the marquee Phase 5 feature for ProvableSumTree: a query that asks
"what's the cryptographically-verifiable signed sum of children with keys
in range [a, b]?" against a ProvableSumTree, with proof size O(log n + |boundary|)
and a verify path that returns the root hash plus the aggregate i64 sum.

Mirrors AggregateCountOnRange line-for-line:
- QueryItem::AggregateSumOnRange(Box<QueryItem>) variant (wire tag 11)
- Query / SizedQuery / PathQuery::validate_aggregate_sum_on_range with the
  same nested-rejection, no-subquery, no-pagination, allowed-inner-range rules
- merk/src/proofs/query/aggregate_sum.rs (~760 lines) implementing
  create_aggregate_sum_on_range_proof + verify_aggregate_sum_on_range_proof
  with the same Disjoint/Contained/Boundary classification, HashWithSum
  self-verifying compression at fully-inside/outside subtrees, and
  KVDigestSum at boundaries
- grovedb/src/operations/proof/aggregate_sum.rs (~330 lines) for the
  GroveDB-level multi-layer envelope chain check
- prove_query / verify_query dispatch in generate.rs and verify.rs
- Tree-type rejection arms in BulkAppendTree, DenseTree, MMR for the new variant

Key correctness points handled differently from count:
- i128 accumulator throughout the verifier (sum can validly be 0 with
  non-zero children, so no "if sum == 0" short-circuit; final narrow to
  i64 with an explicit overflow error)
- No checked_sub equivalent for own_sum derivation — signed sums make
  arithmetic-only corruption detection meaningless; the hash chain binds
  the values regardless
- ProvableSumTree-only at the merk-level gate (Sum/BigSum use different
  hash dispatches and can't host this proof shape)

Tests: 35 new tests total (14 merk-level in aggregate_sum.rs, 21 GroveDB-
level in aggregate_sum_query_tests.rs) covering empty trees, single-key
ranges, full/sub/boundary ranges, negative sums, mixed-sign extremes
including i64::MAX + i64::MIN = -1, tampering rejection, wrong-tree
rejection, validation rejection of nested/Key/RangeFull/orthogonal-aggregate
inners, multi-layer paths, NotSummed-wrapped subtree exclusion, V0 envelope
round-trip. Workspace test count: 2898 → 2938, zero failures.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: QuantumExplorer

grovedb-bulk-append-tree/src/proof/mod.rs

@@ -142,6 +142,13 @@ fn query_to_ranges(query: &Query, total_count: u64) -> Result<Vec<(u64, u64)>, B
                         .into(),
                 ));
             }
+            QueryItem::AggregateSumOnRange(_) => {
+                return Err(BulkAppendError::InvalidInput(
+                    "AggregateSumOnRange is only supported on provable sum trees, \
+                     not on BulkAppendTree"
+                        .into(),
+                ));
+            }
         };
         ranges.push((start, end));
     }

grovedb-dense-fixed-sized-merkle-tree/src/proof/mod.rs

@@ -123,6 +123,13 @@ pub(crate) fn query_to_positions(query: &Query, count: u16) -> Result<Vec<u16>,
                         .into(),
                 ));
             }
+            QueryItem::AggregateSumOnRange(_) => {
+                return Err(DenseMerkleError::InvalidProof(
+                    "AggregateSumOnRange is only supported on provable sum trees, \
+                     not on dense fixed-size merkle trees"
+                        .into(),
+                ));
+            }
         }
     }
 

grovedb-query/src/query.rs

@@ -321,6 +321,22 @@ impl Query {
         }
     }
 
+    /// Creates an aggregate-sum-on-range query that sums the children matched
+    /// by `range`. Mirrors [`Self::new_aggregate_count_on_range`] for
+    /// `ProvableSumTree` instead of `ProvableCountTree`.
+    ///
+    /// `range` must be a true range variant; passing `Key`, `RangeFull`,
+    /// another `AggregateSumOnRange`, or an `AggregateCountOnRange` is
+    /// allowed at construction time but will be rejected by
+    /// [`Self::validate_aggregate_sum_on_range`].
+    pub fn new_aggregate_sum_on_range(range: QueryItem) -> Self {
+        Self {
+            items: vec![QueryItem::AggregateSumOnRange(Box::new(range))],
+            left_to_right: true,
+            ..Self::default()
+        }
+    }
+
     /// If this query contains an `AggregateCountOnRange` item *anywhere* in
     /// its `items` vec, returns a reference to the first such item (whether
     /// the surrounding query is well-formed or not). Returns `None` only
@@ -339,6 +355,15 @@ impl Query {
             .find(|item| item.is_aggregate_count_on_range())
     }
 
+    /// Mirror of [`Self::aggregate_count_on_range`] for `AggregateSumOnRange`.
+    /// Returns `Some(...)` for any query containing such an item, regardless
+    /// of well-formedness.
+    pub fn aggregate_sum_on_range(&self) -> Option<&QueryItem> {
+        self.items
+            .iter()
+            .find(|item| item.is_aggregate_sum_on_range())
+    }
+
     /// Returns `true` if any item in this query — including items inside
     /// nested subquery branches — is an `AggregateCountOnRange`.
     ///
@@ -372,6 +397,31 @@ impl Query {
         false
     }
 
+    /// Mirror of [`Self::has_aggregate_count_on_range_anywhere`] for
+    /// `AggregateSumOnRange`. Used by the prover/verifier to validate at
+    /// entry — if any ASOR is present anywhere, the query must satisfy
+    /// [`Self::validate_aggregate_sum_on_range`].
+    pub fn has_aggregate_sum_on_range_anywhere(&self) -> bool {
+        if self.aggregate_sum_on_range().is_some() {
+            return true;
+        }
+        if let Some(sub) = self.default_subquery_branch.subquery.as_deref()
+            && sub.has_aggregate_sum_on_range_anywhere()
+        {
+            return true;
+        }
+        if let Some(branches) = &self.conditional_subquery_branches {
+            for branch in branches.values() {
+                if let Some(sub) = branch.subquery.as_deref()
+                    && sub.has_aggregate_sum_on_range_anywhere()
+                {
+                    return true;
+                }
+            }
+        }
+        false
+    }
+
     /// Validates the Query-level constraints that apply when an
     /// `AggregateCountOnRange` is present. On success, returns a reference
     /// to the inner `QueryItem` describing the range to count.
@@ -427,6 +477,12 @@ impl Query {
                     "AggregateCountOnRange may not wrap another AggregateCountOnRange",
                 ));
             }
+            QueryItem::AggregateSumOnRange(_) => {
+                return Err(Error::InvalidOperation(
+                    "AggregateCountOnRange may not wrap AggregateSumOnRange — the two are \
+                     orthogonal aggregate queries",
+                ));
+            }
             _ => {}
         }
         if self.default_subquery_branch.subquery.is_some()
@@ -446,6 +502,86 @@ impl Query {
         Ok(inner)
     }
 
+    /// Validates the Query-level constraints that apply when an
+    /// `AggregateSumOnRange` is present. Mirror of
+    /// [`Self::validate_aggregate_count_on_range`] for `ProvableSumTree`.
+    ///
+    /// Rules enforced:
+    ///
+    /// 1. The query must contain exactly one item.
+    /// 2. That item must be `AggregateSumOnRange(_)`.
+    /// 3. The inner item must not be `Key` (use `has_raw` / `get_raw` for
+    ///    existence tests).
+    /// 4. The inner item must not be `RangeFull` (read the parent
+    ///    `Element::ProvableSumTree` bytes directly for the unconditional
+    ///    total).
+    /// 5. The inner item must not itself be `AggregateSumOnRange`.
+    /// 6. The inner item must not be `AggregateCountOnRange` (the two
+    ///    aggregate variants are orthogonal).
+    /// 7. `default_subquery_branch.subquery` and
+    ///    `default_subquery_branch.subquery_path` must both be `None`.
+    /// 8. `conditional_subquery_branches` must be `None` or empty.
+    ///
+    /// `SizedQuery::limit` / `SizedQuery::offset` checks live at the
+    /// `PathQuery` / `SizedQuery` layer.
+    pub fn validate_aggregate_sum_on_range(&self) -> Result<&QueryItem, Error> {
+        if self.items.len() != 1 {
+            return Err(Error::InvalidOperation(
+                "AggregateSumOnRange must be the only item in the query",
+            ));
+        }
+        let inner = match &self.items[0] {
+            QueryItem::AggregateSumOnRange(inner) => inner.as_ref(),
+            _ => {
+                return Err(Error::InvalidOperation(
+                    "validate_aggregate_sum_on_range called on a query without an \
+                     AggregateSumOnRange item",
+                ));
+            }
+        };
+        match inner {
+            QueryItem::Key(_) => {
+                return Err(Error::InvalidOperation(
+                    "AggregateSumOnRange may not wrap Key — use has_raw / get_raw for \
+                     existence tests",
+                ));
+            }
+            QueryItem::RangeFull(_) => {
+                return Err(Error::InvalidOperation(
+                    "AggregateSumOnRange may not wrap RangeFull — read the parent \
+                     ProvableSumTree element for the unconditional total",
+                ));
+            }
+            QueryItem::AggregateSumOnRange(_) => {
+                return Err(Error::InvalidOperation(
+                    "AggregateSumOnRange may not wrap another AggregateSumOnRange",
+                ));
+            }
+            QueryItem::AggregateCountOnRange(_) => {
+                return Err(Error::InvalidOperation(
+                    "AggregateSumOnRange may not wrap AggregateCountOnRange — the two are \
+                     orthogonal aggregate queries",
+                ));
+            }
+            _ => {}
+        }
+        if self.default_subquery_branch.subquery.is_some()
+            || self.default_subquery_branch.subquery_path.is_some()
+        {
+            return Err(Error::InvalidOperation(
+                "AggregateSumOnRange queries may not carry a default subquery branch",
+            ));
+        }
+        if let Some(branches) = &self.conditional_subquery_branches
+            && !branches.is_empty()
+        {
+            return Err(Error::InvalidOperation(
+                "AggregateSumOnRange queries may not carry conditional subquery branches",
+            ));
+        }
+        Ok(inner)
+    }
+
     /// Returns `true` if the given key would trigger a subquery (either via
     /// the default subquery branch or a matching conditional branch).
     pub fn has_subquery_on_key(&self, key: &[u8], in_path: bool) -> bool {

grovedb-query/src/query_item/intersect.rs

@@ -613,6 +613,7 @@ impl QueryItem {
                 end: RangeSetItem::Inclusive(range.end().clone()),
             },
             QueryItem::AggregateCountOnRange(inner) => inner.to_range_set(),
+            QueryItem::AggregateSumOnRange(inner) => inner.to_range_set(),
         }
     }
 
@@ -662,6 +663,7 @@ impl QueryItem {
                 end: RangeSetSimpleItemBorrowed::Inclusive(range.end()),
             }),
             QueryItem::AggregateCountOnRange(inner) => inner.to_range_set_borrowed(),
+            QueryItem::AggregateSumOnRange(inner) => inner.to_range_set_borrowed(),
         }
     }