Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
9 changes: 1 addition & 8 deletions grovedb-query/src/axis_query.rs
Original file line number Diff line number Diff line change
Expand Up @@ -249,14 +249,7 @@ pub enum AxisTraversal {
/// The same pair over sums `[40, -10, 25]` with band `[0, 100]`
/// selects `40` and `25`: `Population` answers `2`, `Total` answers
/// `65`.
///
/// **Currently unsupported: `Total` on the count axis.** The query
/// validates and serializes (the vocabulary is stable), but every
/// execution surface — trusted read, embedded prover/verifier,
/// standalone prover/verifier — refuses it with a typed
/// `NotSupported` naming issue #806 until the count secondary
/// becomes sum-bearing (#806 part 2, which removes this paragraph).
/// The other three (axis, fold) cells are served today.

///
/// **Cost** — `O(log n)` in every case, either fold. The walk
/// classifies each subtree as fully Contained, Disjoint, or Partial
Expand Down
44 changes: 26 additions & 18 deletions grovedb/src/batch/indexed_tree/mirror.rs
Original file line number Diff line number Diff line change
Expand Up @@ -23,17 +23,25 @@ use grovedb_storage::StorageContext;
use grovedb_version::version::GroveVersion;

use super::{read_entry_aggregates, AggregatePair, AggregateTransition};
use crate::{operations::indexed_tree::make_axis_secondary_key, Element, Error};
use crate::{
operations::indexed_tree::{count_value_as_sum, make_axis_secondary_key},
Element, Error,
};

/// The per-axis payload stored alongside the sort key. The key encodes the
/// ordering value; the payload carries what the secondary's own aggregate
/// must sum to, which is why the sum and avg axes cannot store a bare item.
fn axis_row_payload(axis: IndexAxis, sum: i64) -> Element {
match axis {
IndexAxis::Count => Element::new_item(Vec::new()),
/// must sum to, which is why NO axis can store a bare item: every
/// secondary is a dual-aggregate `ProvableCountProvableSumTree`, and the
/// count axis mirrors its `count_value` into the sum half so a band
/// TOTAL is one committed scalar (issue #806).
///
/// Fallible only through [`count_value_as_sum`]'s fail-closed guard.
fn axis_row_payload(axis: IndexAxis, count: u64, sum: i64) -> Result<Element, Error> {
Ok(match axis {
IndexAxis::Count => Element::new_sum_item(count_value_as_sum(count)?),
IndexAxis::Sum => Element::new_sum_item(sum),
IndexAxis::Avg => Element::new_item_with_sum_item(Vec::new(), sum),
}
})
}

/// Enforce the precise per-axis item-key bound: avg prepends a 16-byte sort
Expand Down Expand Up @@ -101,18 +109,18 @@ fn build_axis_mirror_batch(
let secondary_tree_type = crate::operations::indexed_tree::axis_secondary_tree_type(axis);
let mut secondary_batch: Vec<BatchEntry<Vec<u8>>> = Vec::with_capacity(transitions.len() * 2);
for (key, old_aggregates, new_aggregates) in transitions {
let old_entry = old_aggregates.map(|(c, s)| {
(
make_axis_secondary_key(axis, c, s, key),
axis_row_payload(axis, s),
)
});
let new_entry = new_aggregates.map(|(c, s)| {
(
make_axis_secondary_key(axis, c, s, key),
axis_row_payload(axis, s),
)
});
let entry_for = |aggregates: &AggregatePair| -> Result<_, Error> {
aggregates
.map(|(c, s)| {
Ok((
make_axis_secondary_key(axis, c, s, key),
axis_row_payload(axis, c, s)?,
))
})
.transpose()
};
let old_entry = cost_return_on_error_no_add!(cost, entry_for(old_aggregates));
let new_entry = cost_return_on_error_no_add!(cost, entry_for(new_aggregates));
if old_entry == new_entry {
continue;
}
Expand Down
2 changes: 1 addition & 1 deletion grovedb/src/estimated_costs/average_case_costs.rs
Original file line number Diff line number Diff line change
Expand Up @@ -550,7 +550,7 @@ impl GroveDb {
// their fixed worst-case varint width, so `i64::MAX` here is the
// upper bound, not an average.
let worst_case_row = match axis {
grovedb_element::indexed::IndexAxis::Count => Element::new_item(vec![]),
grovedb_element::indexed::IndexAxis::Count => Element::new_sum_item(i64::MAX),
grovedb_element::indexed::IndexAxis::Sum => Element::new_sum_item(i64::MAX),
grovedb_element::indexed::IndexAxis::Avg => {
Element::new_item_with_sum_item(vec![], i64::MAX)
Expand Down
4 changes: 3 additions & 1 deletion grovedb/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1692,7 +1692,9 @@ impl GroveDb {
// under the right key but carrying the wrong value is caught too
// — the key alone does not pin the stored aggregate.
let payload = match axis {
grovedb_element::indexed::IndexAxis::Count => Element::new_item(Vec::new()),
grovedb_element::indexed::IndexAxis::Count => Element::new_sum_item(
crate::operations::indexed_tree::count_value_as_sum(count)?,
),
grovedb_element::indexed::IndexAxis::Sum => Element::new_sum_item(sum),
grovedb_element::indexed::IndexAxis::Avg => {
Element::new_item_with_sum_item(Vec::new(), sum)
Expand Down
23 changes: 17 additions & 6 deletions grovedb/src/operations/get/run_path_query.rs
Original file line number Diff line number Diff line change
Expand Up @@ -458,12 +458,23 @@ impl GroveDb {
)))
.wrap_with_cost(cost)
}
(IndexAxis::Count, AggregateFold::Total) => Err(Error::NotSupported(
"a TOTAL over the count axis needs a sum-bearing count secondary; \
tracked in issue #806"
.to_string(),
))
.wrap_with_cost(cost),
(IndexAxis::Count, AggregateFold::Total) => {
let (lo_count, hi_count) = clamp_count_bounds(*lo, *hi);
let value = cost_return_on_error!(
&mut cost,
self.indexed_count_total_over_value_range(
path,
lo_count,
hi_count,
transaction,
grove_version
)
);
Ok(PathQueryRun::AxisAggregate(AxisAggregateValue::Total(
value,
)))
.wrap_with_cost(cost)
}
// classify rejects value-range aggregates on the Avg axis.
(IndexAxis::Avg, _) => Err(Error::CorruptedCodeExecution(
"value-range aggregate on the Avg axis survived classification",
Expand Down
160 changes: 137 additions & 23 deletions grovedb/src/operations/indexed_tree.rs
Original file line number Diff line number Diff line change
Expand Up @@ -53,22 +53,43 @@ use grovedb_version::version::GroveVersion;
use crate::{util::TxRef, Element, Error, GroveDb, Transaction, TransactionArg};

/// Per-axis Merk tree type to open the secondary with.
///
/// Every axis uses the dual-aggregate
/// [`TreeType::ProvableCountProvableSumTree`]: the count half is what
/// makes positional queries provable in `O(log n)` (the count-offset
/// proof primitive skips whole subtrees via counted node commitments),
/// and the sum half is what makes a TOTAL over a value band answerable
/// as one committed scalar ([`AggregateFold::Total`], issue #806).
#[inline]
pub(crate) fn axis_secondary_tree_type(axis: IndexAxis) -> TreeType {
match axis {
// Each count entry contributes count = 1.
IndexAxis::Count => TreeType::ProvableCountTree,
// Each sum entry contributes (count = 1, sum = its own SumValue).
// The count half is what makes positional queries against the sum
// ranking provable in O(log n): the count-offset proof primitive
// skips whole subtrees via counted node commitments, which needs
// every secondary node to carry a hash-bound count aggregate.
// Each count entry contributes (count = 1, sum = its
// count_value as an i64) — the sum half is the band-total.
IndexAxis::Count => TreeType::ProvableCountProvableSumTree,
// Each sum entry contributes (count = 1, sum = its own
// SumValue).
IndexAxis::Sum => TreeType::ProvableCountProvableSumTree,
// Each avg entry contributes (count = 1, sum = item's SumValue).
IndexAxis::Avg => TreeType::ProvableCountProvableSumTree,
}
}

/// The count-axis secondary stores each entry's `count_value` as its
/// sum item, and sum items are `i64`: a count above `i64::MAX` cannot
/// be mirrored faithfully, so it FAILS CLOSED rather than clamping —
/// a clamped total would silently lie through authenticated state.
/// Unreachable for any real tree (a count is bounded by the number of
/// elements), so the guard is a type-level seam, not a live limit.
#[inline]
pub(crate) fn count_value_as_sum(count: u64) -> Result<i64, Error> {
i64::try_from(count).map_err(|_| {
Error::CorruptedData(format!(
"count value {count} exceeds i64::MAX and cannot be mirrored into the \
count-axis secondary's sum aggregate"
))
})
}

/// Build the secondary key bytes for an entry at `item_key` under the
/// given axis, given the relevant aggregate values:
/// - count axis → `count_be(8) ‖ item_key`
Expand Down Expand Up @@ -1021,7 +1042,10 @@ impl GroveDb {
for (key, (count, sum)) in &entries {
let secondary_key = make_axis_secondary_key(axis, *count, *sum, key);
let payload = match axis {
IndexAxis::Count => Element::new_item(Vec::new()),
IndexAxis::Count => Element::new_sum_item(cost_return_on_error_no_add!(
cost,
count_value_as_sum(*count)
)),
IndexAxis::Sum => Element::new_sum_item(*sum),
IndexAxis::Avg => Element::new_item_with_sum_item(Vec::new(), *sum),
};
Expand Down Expand Up @@ -1901,6 +1925,68 @@ impl GroveDb {
Ok(population).wrap_with_cost(cost)
}

/// The TOTAL of the count values of every entry whose `count_value`
/// falls in the inclusive band `[lo_count, hi_count]` — the
/// [`AggregateFold::Total`](grovedb_query::AggregateFold)
/// counterpart of [`Self::indexed_count_aggregate_over_value_range`]
/// (which answers the band's POPULATION), enabled by the count
/// secondary mirroring each entry's `count_value` into its sum half
/// (issue #806).
///
/// `O(log n)`: the walk folds contained subtrees' stored sums and
/// descends only along the two band boundaries.
pub fn indexed_count_total_over_value_range<'b, B, P>(
&self,
path: P,
lo_count: u64,
hi_count: u64,
transaction: TransactionArg,
grove_version: &GroveVersion,
) -> CostResult<i64, Error>
where
B: AsRef<[u8]> + 'b,
P: Into<SubtreePath<'b, B>>,
{
// The version gate precedes the degenerate-range fast path:
// every input to this entry point is held to the same version
// contract, inverted bounds included.
grovedb_version::check_grovedb_v0_with_cost!(
"indexed_count_total_over_value_range",
grove_version.grovedb_versions.operations.indexed_axis.read
);
use grovedb_merk::proofs::query::QueryItem as MerkQueryItemForRange;

let mut cost = OperationCost::default();
if lo_count > hi_count {
return Ok(0i64).wrap_with_cost(cost);
}
let path: SubtreePath<B> = path.into();
let tx = TxRef::new(&self.db, transaction);
let tx_ref = tx.as_ref();

let secondary_merk = cost_return_on_error!(
&mut cost,
self.open_validated_axis_secondary(path, IndexAxis::Count, tx_ref, grove_version)
);

let lo_bytes = encode_count_sort_key(lo_count).to_vec();
let inner_range = if hi_count == u64::MAX {
MerkQueryItemForRange::RangeFrom(lo_bytes..)
} else {
let upper_bytes = encode_count_sort_key(hi_count + 1).to_vec();
MerkQueryItemForRange::Range(lo_bytes..upper_bytes)
};

let total = cost_return_on_error!(
&mut cost,
secondary_merk
.sum_aggregate_on_range(&inner_range, grove_version)
.map_err(|e| Error::CorruptedData(format!("indexed count total on range: {e}")))
);

Ok(total).wrap_with_cost(cost)
}

// ---- avg axis (PCPSIT-only) ----

/// Iterate the avg-axis secondary in avg-order and return the
Expand Down Expand Up @@ -2335,12 +2421,16 @@ pub(crate) fn mirror_indexed_axis_to_secondary<'db, S: StorageContext<'db>>(
// - Count → constant empty Item (contributes count = 1)
// - Sum → SumItem(sum)
// - Avg → ItemWithSumItem(empty, sum) (contributes (1, sum))
let axis_payload = |sum: i64| -> Element {
match axis {
IndexAxis::Count => Element::new_item(Vec::new()),
// The payload is a function of BOTH aggregates now: the count axis
// mirrors count_value into its sum half, so a closure over `sum`
// alone could not see a count-only change and the fast path below
// would silently skip a real payload update.
let axis_payload = |count: u64, sum: i64| -> Result<Element, Error> {
Ok(match axis {
IndexAxis::Count => Element::new_sum_item(count_value_as_sum(count)?),
IndexAxis::Sum => Element::new_sum_item(sum),
IndexAxis::Avg => Element::new_item_with_sum_item(Vec::new(), sum),
}
})
};

// Compute old and new sort keys. Either may be None (no entry).
Expand All @@ -2366,8 +2456,11 @@ pub(crate) fn mirror_indexed_axis_to_secondary<'db, S: StorageContext<'db>>(
// former key-only check and preserves the fast path for the common
// case.
if old_key == new_key && new_key.is_some() {
let payload_unchanged = match (old_sum, new_sum) {
(Some(os), Some(ns)) => axis_payload(os) == axis_payload(ns),
let payload_unchanged = match ((old_count, old_sum), (new_count, new_sum)) {
((Some(oc), Some(os)), (Some(nc), Some(ns))) => {
cost_return_on_error_no_add!(cost, axis_payload(oc, os))
== cost_return_on_error_no_add!(cost, axis_payload(nc, ns))
}
_ => false,
};
if payload_unchanged {
Expand All @@ -2392,16 +2485,16 @@ pub(crate) fn mirror_indexed_axis_to_secondary<'db, S: StorageContext<'db>>(
.map_err(Error::MerkError)
);
}
if let (Some(nk), Some(new_sum_val)) = (&new_key, new_sum) {
if let (Some(nk), Some(new_count_val), Some(new_sum_val)) = (&new_key, new_count, new_sum) {
// Derived by the same `axis_payload` closure the fast-path
// equality check above uses, so the two stay in lockstep:
// - Count → empty Item (secondary is a ProvableCountTree; every
// entry contributes count = 1)
// - Sum → SumItem(sum) (secondary is a
// ProvableCountProvableSumTree; contributes (1, sum))
// - Avg → ItemWithSumItem(empty, sum) (secondary is a
// ProvableCountProvableSumTree; contributes (1, sum))
let entry = axis_payload(new_sum_val);
// equality check above uses, so the two stay in lockstep.
// Every axis's secondary is a dual-aggregate
// ProvableCountProvableSumTree:
// - Count → SumItem(count_value) — contributes (1, count), so a
// band TOTAL is one committed scalar (issue #806)
// - Sum → SumItem(sum) — contributes (1, sum)
// - Avg → ItemWithSumItem(empty, sum) — contributes (1, sum)
let entry = cost_return_on_error_no_add!(cost, axis_payload(new_count_val, new_sum_val));
cost_return_on_error!(
&mut cost,
entry
Expand Down Expand Up @@ -2521,6 +2614,27 @@ fn corrupted_secondary_key_error(axis: IndexAxis, secondary_key: &[u8]) -> Error
))
}

#[cfg(test)]
mod count_value_as_sum_tests {
//! The count-axis secondary stores count_value as an i64 sum item;
//! the conversion FAILS CLOSED above i64::MAX rather than clamping,
//! because a clamped value would flow into hash-bound authenticated
//! state as a silently wrong total.

use super::count_value_as_sum;

#[test]
fn converts_in_domain_and_fails_closed_above_i64_max() {
assert_eq!(count_value_as_sum(0).unwrap(), 0);
assert_eq!(count_value_as_sum(8).unwrap(), 8);
assert_eq!(count_value_as_sum(i64::MAX as u64).unwrap(), i64::MAX);
let err = count_value_as_sum(i64::MAX as u64 + 1)
.expect_err("one past i64::MAX must fail closed");
assert!(err.to_string().contains("cannot be mirrored"), "{err}");
count_value_as_sum(u64::MAX).expect_err("u64::MAX must fail closed");
}
}

#[cfg(test)]
mod secondary_key_codec_tests {
//! The secondary keyspace is `sort_key ‖ item_key`, and every per-axis
Expand Down
11 changes: 5 additions & 6 deletions grovedb/src/operations/proof/indexed_axis/envelope.rs
Original file line number Diff line number Diff line change
Expand Up @@ -90,12 +90,11 @@ pub struct IndexedAxisRangeProof {
/// indexed-tree's per-axis secondary.
///
/// Every axis's secondary binds a count aggregate into its node hashes
/// (count axis: `ProvableCountTree`; sum and avg axes: dual-axis
/// `ProvableCountProvableSumTree`), so the secondary proof is always
/// produced by `Merk::prove_count_offset_on_range`: the skipped prefix
/// is attested by counted subtree commitments (`HashWithCount` /
/// `HashWithCountAndSum`), giving `O(log n + k)` proof size regardless
/// of `offset`.
/// (every axis is a dual-aggregate `ProvableCountProvableSumTree`), so
/// the secondary proof is always produced by
/// `Merk::prove_count_offset_on_range`: the skipped prefix is attested
/// by counted subtree commitments (`HashWithCountAndSum`), giving
/// `O(log n + k)` proof size regardless of `offset`.
#[derive(Encode, Decode, Debug)]
pub struct IndexedAxisPaginatedProof {
/// Echoed [`IndexAxis::tag`] of the queried axis. The verifier
Expand Down
Loading
Loading