Skip to content
Merged
Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
f5e39e3
feat(grovedb,query): allow AggregateCountOnRange as carrier subquery
QuantumExplorer May 14, 2026
73ccbc2
fix(grovedb,query): address review feedback on carrier ACOR
QuantumExplorer May 14, 2026
ae7962d
test(grovedb,query): boost carrier ACOR patch coverage
QuantumExplorer May 14, 2026
f31fcb2
refactor(grovedb): reject V0 envelopes for AggregateCountOnRange enti…
QuantumExplorer May 14, 2026
4219045
fix(grovedb): support right-to-left direction in carrier ACOR verifier
QuantumExplorer May 14, 2026
d8ddda5
docs(grovedb): tone down carrier ACOR direction comment
QuantumExplorer May 14, 2026
e1dddd5
refactor(grovedb,query): drop "ACOR" abbreviation for forward-compat
QuantumExplorer May 14, 2026
066c774
refactor(grovedb): split aggregate_count proof module into submodules
QuantumExplorer May 14, 2026
19739e5
fix(grovedb): canonical decoding for aggregate-count proofs
QuantumExplorer May 14, 2026
f1c365a
test(grovedb,query): pin nested-carrier rejection
QuantumExplorer May 14, 2026
7b083f5
test(grovedb): pin SQL-style A=1, B>4, COUNT(C>4) carrier query
QuantumExplorer May 14, 2026
0dbeff4
fix(grovedb): emit lower-layer for empty count tree under carrier ACOR
QuantumExplorer May 14, 2026
2bbf7d1
fix(grovedb): tighten query_aggregate_count to leaf-only validation
QuantumExplorer May 14, 2026
fc4e09e
fix(grovedb): surface InvalidProof instead of panicking on classifica…
QuantumExplorer May 14, 2026
d1cd151
feat(grovedb): add no-proof query_aggregate_count_per_key entry point
QuantumExplorer May 14, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
839 changes: 839 additions & 0 deletions grovedb-query/src/aggregate_count.rs

Large diffs are not rendered by default.

5 changes: 5 additions & 0 deletions grovedb-query/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,11 @@
/// Error types for query operations.
pub mod error;

/// `AggregateCountOnRange` (ACOR) construction and validation. The
/// shape, detection, and leaf/carrier rule sets live here; the proof
/// generation and verification live in the `grovedb` crate.
mod aggregate_count;

/// Aggregate sum query for sum-up-to style queries.
pub mod aggregate_sum_query;

Expand Down
372 changes: 0 additions & 372 deletions grovedb-query/src/query.rs
Original file line number Diff line number Diff line change
Expand Up @@ -303,149 +303,6 @@ impl Query {
}
}

/// Creates an aggregate-count-on-range query that counts the elements
/// matched by `range`. The resulting query has `AggregateCountOnRange(range)`
/// as its sole item, no subquery branches, and `left_to_right = true`
/// (counting is direction-agnostic).
///
/// `range` must be a true range variant (`Range`, `RangeInclusive`,
/// `RangeFrom`, `RangeTo`, `RangeToInclusive`, `RangeAfter`, `RangeAfterTo`,
/// or `RangeAfterToInclusive`). Passing `Key`, `RangeFull`, or another
/// `AggregateCountOnRange` is allowed at construction time but will be
/// rejected by [`validate_aggregate_count_on_range`].
pub fn new_aggregate_count_on_range(range: QueryItem) -> Self {
Self {
items: vec![QueryItem::AggregateCountOnRange(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
/// when no item is an `AggregateCountOnRange`.
///
/// This is intentionally a **detection-only** helper: malformed queries
/// like `items: [Key(...), AggregateCountOnRange(...)]` still report
/// `Some(...)` here so callers don't accidentally route them through
/// the regular-query path. Use
/// [`Self::validate_aggregate_count_on_range`] when you also need to
/// enforce the well-formedness rules (single item, allowed inner kind,
/// no subqueries, etc.).
pub fn aggregate_count_on_range(&self) -> Option<&QueryItem> {
self.items
.iter()
.find(|item| item.is_aggregate_count_on_range())
}

/// Returns `true` if any item in this query — including items inside
/// nested subquery branches — is an `AggregateCountOnRange`.
///
/// `AggregateCountOnRange` is a *terminal* item: the canonical
/// well-formed query contains exactly one `AggregateCountOnRange` at
/// the top level and nothing else. This recursive detector exists so
/// the prover can validate up front: if any ACOR is present anywhere,
/// the query as a whole must satisfy
/// [`Self::validate_aggregate_count_on_range`] — otherwise a malformed
/// shape (e.g. ACOR hidden inside `default_subquery_branch.subquery`)
/// could slip past a top-level-only check and be silently routed
/// through the regular-proof path.
pub fn has_aggregate_count_on_range_anywhere(&self) -> bool {
if self.aggregate_count_on_range().is_some() {
return true;
}
if let Some(sub) = self.default_subquery_branch.subquery.as_deref()
&& sub.has_aggregate_count_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_count_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.
///
/// Rules enforced (matching the constraints documented in the GroveDB
/// book chapter "Aggregate Count Queries"):
///
/// 1. The query must contain exactly one item.
/// 2. That item must be `AggregateCountOnRange(_)`.
/// 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::ProvableCountTree` / `Element::ProvableCountSumTree`
/// bytes directly for the unconditional total).
/// 5. The inner item must not itself be `AggregateCountOnRange`.
/// 6. `default_subquery_branch.subquery` and
/// `default_subquery_branch.subquery_path` must both be `None`.
/// 7. `conditional_subquery_branches` must be `None` or empty.
///
/// `SizedQuery::limit` / `SizedQuery::offset` checks live at the
/// `PathQuery` / `SizedQuery` layer (see
/// [`SizedQuery::validate_aggregate_count_on_range`]).
pub fn validate_aggregate_count_on_range(&self) -> Result<&QueryItem, Error> {
if self.items.len() != 1 {
return Err(Error::InvalidOperation(
"AggregateCountOnRange must be the only item in the query",
));
}
let inner = match &self.items[0] {
QueryItem::AggregateCountOnRange(inner) => inner.as_ref(),
_ => {
return Err(Error::InvalidOperation(
"validate_aggregate_count_on_range called on a query without an \
AggregateCountOnRange item",
));
}
};
match inner {
QueryItem::Key(_) => {
return Err(Error::InvalidOperation(
"AggregateCountOnRange may not wrap Key — use has_raw / get_raw for \
existence tests",
));
}
QueryItem::RangeFull(_) => {
return Err(Error::InvalidOperation(
"AggregateCountOnRange may not wrap RangeFull — read the parent \
ProvableCountTree element for the unconditional total",
));
}
QueryItem::AggregateCountOnRange(_) => {
return Err(Error::InvalidOperation(
"AggregateCountOnRange may not wrap another AggregateCountOnRange",
));
}
_ => {}
}
if self.default_subquery_branch.subquery.is_some()
|| self.default_subquery_branch.subquery_path.is_some()
{
return Err(Error::InvalidOperation(
"AggregateCountOnRange queries may not carry a default subquery branch",
));
}
if let Some(branches) = &self.conditional_subquery_branches
&& !branches.is_empty()
{
return Err(Error::InvalidOperation(
"AggregateCountOnRange 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 {
Expand Down Expand Up @@ -1050,233 +907,4 @@ mod tests {
"innermost query should have no further subquery"
);
}

// ---------- AggregateCountOnRange validation tests ----------
//
// These hit each numbered rule in `Query::validate_aggregate_count_on_range`
// independently. The happy path is also covered to ensure the success
// arm returns the inner range.

fn make_acor_query(inner: QueryItem) -> Query {
Query::new_aggregate_count_on_range(inner)
}

#[test]
fn validate_acor_happy_path_returns_inner() {
let q = make_acor_query(QueryItem::Range(b"a".to_vec()..b"z".to_vec()));
let inner = q
.validate_aggregate_count_on_range()
.expect("happy path should validate");
match inner {
QueryItem::Range(r) => {
assert_eq!(r.start, b"a".to_vec());
assert_eq!(r.end, b"z".to_vec());
}
_ => panic!("expected inner Range"),
}
}

#[test]
fn validate_acor_rejects_extra_items() {
let mut q = make_acor_query(QueryItem::Range(b"a".to_vec()..b"z".to_vec()));
q.items.push(QueryItem::Key(b"extra".to_vec()));
let err = q
.validate_aggregate_count_on_range()
.expect_err("two-item query must fail");
assert!(matches!(err, crate::error::Error::InvalidOperation(_)));
}

#[test]
fn validate_acor_rejects_non_acor_only_item() {
// A query with one item that isn't AggregateCountOnRange triggers the
// "validate called on a query without an AggregateCountOnRange item"
// branch.
let q = Query::new_single_query_item(QueryItem::Key(b"k".to_vec()));
let err = q
.validate_aggregate_count_on_range()
.expect_err("non-ACOR-only item must fail");
assert!(matches!(err, crate::error::Error::InvalidOperation(_)));
}

#[test]
fn validate_acor_rejects_inner_key() {
let q = make_acor_query(QueryItem::Key(b"k".to_vec()));
let err = q
.validate_aggregate_count_on_range()
.expect_err("inner Key must fail");
match err {
crate::error::Error::InvalidOperation(msg) => assert!(msg.contains("Key")),
_ => panic!("expected InvalidOperation"),
}
}

#[test]
fn validate_acor_rejects_inner_range_full() {
let q = make_acor_query(QueryItem::RangeFull(std::ops::RangeFull));
let err = q
.validate_aggregate_count_on_range()
.expect_err("inner RangeFull must fail");
match err {
crate::error::Error::InvalidOperation(msg) => assert!(msg.contains("RangeFull")),
_ => panic!("expected InvalidOperation"),
}
}

#[test]
fn validate_acor_rejects_nested_acor() {
// AggregateCountOnRange wrapping another AggregateCountOnRange.
let inner_acor = QueryItem::AggregateCountOnRange(Box::new(QueryItem::Range(
b"a".to_vec()..b"z".to_vec(),
)));
let q = make_acor_query(inner_acor);
let err = q
.validate_aggregate_count_on_range()
.expect_err("nested ACOR must fail");
match err {
crate::error::Error::InvalidOperation(msg) => {
assert!(msg.contains("AggregateCountOnRange"))
}
_ => panic!("expected InvalidOperation"),
}
}

#[test]
fn validate_acor_rejects_default_subquery_branch() {
let mut q = make_acor_query(QueryItem::Range(b"a".to_vec()..b"z".to_vec()));
q.default_subquery_branch = SubqueryBranch {
subquery_path: None,
subquery: Some(Box::new(Query::new())),
};
let err = q
.validate_aggregate_count_on_range()
.expect_err("default subquery branch must fail");
match err {
crate::error::Error::InvalidOperation(msg) => assert!(msg.contains("subquery")),
_ => panic!("expected InvalidOperation"),
}
}

#[test]
fn validate_acor_rejects_default_subquery_path() {
let mut q = make_acor_query(QueryItem::Range(b"a".to_vec()..b"z".to_vec()));
q.default_subquery_branch = SubqueryBranch {
subquery_path: Some(vec![b"x".to_vec()]),
subquery: None,
};
let err = q
.validate_aggregate_count_on_range()
.expect_err("subquery_path must fail");
match err {
crate::error::Error::InvalidOperation(msg) => assert!(msg.contains("subquery")),
_ => panic!("expected InvalidOperation"),
}
}

#[test]
fn validate_acor_rejects_conditional_subquery_branches() {
let mut q = make_acor_query(QueryItem::Range(b"a".to_vec()..b"z".to_vec()));
let mut branches = IndexMap::new();
branches.insert(
QueryItem::Key(b"k".to_vec()),
SubqueryBranch {
subquery_path: None,
subquery: Some(Box::new(Query::new())),
},
);
q.conditional_subquery_branches = Some(branches);
let err = q
.validate_aggregate_count_on_range()
.expect_err("conditional branches must fail");
match err {
crate::error::Error::InvalidOperation(msg) => {
assert!(msg.contains("conditional"));
}
_ => panic!("expected InvalidOperation"),
}
}

#[test]
fn validate_acor_accepts_empty_conditional_branches_map() {
// An empty `Some(IndexMap::new())` is treated as "no branches" by the
// validator (the rule enforces non-empty rejection only).
let mut q = make_acor_query(QueryItem::Range(b"a".to_vec()..b"z".to_vec()));
q.conditional_subquery_branches = Some(IndexMap::new());
let inner = q
.validate_aggregate_count_on_range()
.expect("empty conditional map must validate");
assert!(matches!(inner, QueryItem::Range(_)));
}

#[test]
fn aggregate_count_on_range_helper_detects_acor_anywhere_in_items() {
// Well-formed shape — single ACOR item.
let q = make_acor_query(QueryItem::Range(b"a".to_vec()..b"z".to_vec()));
assert!(q.aggregate_count_on_range().is_some());

// Two items including ACOR → still detected, so the routing layer
// can hand the malformed query to validate_aggregate_count_on_range
// for a precise error rather than silently treating it as a regular
// query.
let mut q2 = q.clone();
q2.items.push(QueryItem::Key(b"x".to_vec()));
assert!(
q2.aggregate_count_on_range().is_some(),
"ACOR + extra item must still be detected as ACOR-bearing"
);

// ACOR not at index 0 — also detected.
let mut q3 = Query::new_single_query_item(QueryItem::Key(b"x".to_vec()));
q3.items.push(QueryItem::AggregateCountOnRange(Box::new(
QueryItem::Range(b"a".to_vec()..b"z".to_vec()),
)));
assert!(q3.aggregate_count_on_range().is_some());

// No ACOR anywhere → None.
let q4 = Query::new_single_query_item(QueryItem::Key(b"x".to_vec()));
assert!(q4.aggregate_count_on_range().is_none());

// Empty items → None.
let q5 = Query::new();
assert!(q5.aggregate_count_on_range().is_none());
}

#[test]
fn has_aggregate_count_on_range_anywhere_walks_subqueries() {
// No ACOR anywhere → false.
let plain = Query::new_single_query_item(QueryItem::Range(b"a".to_vec()..b"z".to_vec()));
assert!(!plain.has_aggregate_count_on_range_anywhere());

// Top-level ACOR → true (covered by `aggregate_count_on_range` too).
let top = make_acor_query(QueryItem::Range(b"a".to_vec()..b"z".to_vec()));
assert!(top.has_aggregate_count_on_range_anywhere());

// ACOR hidden inside `default_subquery_branch.subquery` — the
// top-level-only `aggregate_count_on_range` would miss it, but the
// recursive helper finds it. This is the surface that the
// prove_query entry-point gate uses to refuse to run any
// ACOR-bearing query that isn't the canonical single-ACOR shape.
let inner_acor = make_acor_query(QueryItem::Range(b"a".to_vec()..b"z".to_vec()));
let mut hidden =
Query::new_single_query_item(QueryItem::Range(b"a".to_vec()..b"z".to_vec()));
hidden.set_subquery(inner_acor);
assert!(hidden.aggregate_count_on_range().is_none());
assert!(
hidden.has_aggregate_count_on_range_anywhere(),
"ACOR hidden in default subquery branch must be detected"
);

// ACOR hidden in a conditional subquery branch.
let inner_acor2 = make_acor_query(QueryItem::Range(b"a".to_vec()..b"z".to_vec()));
let mut conditional =
Query::new_single_query_item(QueryItem::Range(b"a".to_vec()..b"z".to_vec()));
conditional.add_conditional_subquery(
QueryItem::Key(b"k".to_vec()),
None,
Some(inner_acor2),
);
assert!(
conditional.has_aggregate_count_on_range_anywhere(),
"ACOR hidden in conditional subquery branch must be detected"
);
}
}
Loading
Loading