feat: provable sum-budget reads — SumBudgetWindow in the GroveDBProof V1 envelope

[QuantumExplorer]

Re-opens the work from #800, rebased onto develop after #799 merged.

Why a new PR: #800 was merged into #799's branch rather than into develop, and that merge was then reverted — so GitHub shows #800 as MERGED (unreopenable) while develop contains none of its content. This branch replays the same commit on top of the merged #799.

What it adds

Sum-budget path queries were the last shape with no proof form. They now prove through the standard V1 envelope — no new wire family — via ProofBytes::SumBudgetWindow:

• Prover runs the budget walk to find the window (the first N entries at which the stop condition fired), then emits a merk range proof with limit = N over the same items.
• Verifier replays the fold over the proved entries — same skip/count semantics as the trusted read — accumulates the running sum, and checks the stop condition was applied correctly. Returns VerifiedPathQuery::SumBudget { matches, total, stop }.

Gated on proof.sum_budget_in_v1_envelope (GROVE_V4+), mirroring the axis-descent gate on both sides.

Rebase adaptations

• SumBudgetRead.max_items_checked → match_limit: the engine decrements it per matched result, not per scanned element, so the old name described the wrong thing. Renamed with the field.
• Box<ReadMode> (develop's large_enum_variant fix) threaded through the new read_mode_at_path resolver and the window builder — as_deref() at both sites.
• read_mode_at_path is now the shared private resolver; axis_read_at_path and sum_budget_at_path are thin wrappers over it, so prover and verifier still cannot disagree about which layers carry read modes.
• verify_path_query_shape_tests::sum_budget_path_queries_have_no_proof_form_yet (added in feat: axis-ordered reads embedded in the GroveDBProof V1 envelope #799) asserted this shape had no proof form. That is exactly what this PR provides, so it became sum_budget_verifies_through_the_unified_entry — a positive round trip asserting the proved window equals the trusted read's results, with total = 12 and stop = BudgetReached.

Verification

• cargo test --workspace --all-features — green
• cargo clippy --workspace --all-features -- -D warnings — clean
• cargo build --no-default-features --features verify -p grovedb — clean
• New suite: grovedb/src/tests/sum_budget_proof_tests.rs (round trips per stop reason, read-vs-proof differentials across sum_limit/match_limit combinations, non-sum-element skip parity, forgery rejections, V4 gates)

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added verifiable sum-budget query proofs, including matched entries, totals, and the reason processing stopped.
  • Added support for budget limits, match limits, scan exhaustion, negative sums, and non-sum entries.
  • Aggregate sum results now report the number of elements scanned.

• Improvements

  • Renamed the sum-budget limit setting to clarify that it limits matched items.
  • Added validation for invalid limits and oversized budgets.

• Compatibility

  • Sum-budget proofs are supported starting with GroveDB V4; earlier versions reject them.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 1695e4ff-f6f6-4ef9-9a94-dbcdedfb7be4

📥 Commits

Reviewing files that changed from the base of the PR and between 2ce6fdf and e11cf87.

📒 Files selected for processing (19)

• grovedb-query/src/read_mode.rs
• grovedb-query/tests/query_encoding_golden.rs
• grovedb-version/src/version/grovedb_versions.rs
• grovedb-version/src/version/v1.rs
• grovedb-version/src/version/v2.rs
• grovedb-version/src/version/v3.rs
• grovedb-version/src/version/v4.rs
• grovedb/src/element/aggregate_sum_query/mod.rs
• grovedb/src/operations/get/run_path_query.rs
• grovedb/src/operations/proof/generate.rs
• grovedb/src/operations/proof/mod.rs
• grovedb/src/operations/proof/verify.rs
• grovedb/src/operations/proof/verify_path_query.rs
• grovedb/src/query/mod.rs
• grovedb/src/query/shape.rs
• grovedb/src/tests/mod.rs
• grovedb/src/tests/read_mode_gate_tests.rs
• grovedb/src/tests/sum_budget_proof_tests.rs
• grovedb/src/tests/verify_path_query_shape_tests.rs

---

📝 Walkthrough

Walkthrough

Sum-budget queries now limit matched items, generate terminal Merk window proofs, and verify replayed budget outcomes. Support is enabled from Grove V4. Tests cover round trips, stop conditions, tampering, trusted-read agreement, and version gates.

Changes

Sum-budget proof support

Layer / File(s)	Summary
Budget and query contracts grovedb-query/src/read_mode.rs, grovedb-query/tests/query_encoding_golden.rs, grovedb/src/query/..., grovedb/src/element/aggregate_sum_query/mod.rs, grovedb/src/operations/get/run_path_query.rs	SumBudgetRead now uses match_limit. Validation, encoding, display output, and fixtures use the renamed field. Aggregate results report elements_scanned. Trusted reads apply matching and scan options explicitly.
Protocol gate and window payload grovedb-version/src/version/*.rs, grovedb/src/operations/proof/mod.rs	A sum_budget_in_v1_envelope gate is disabled through Grove V3 and enabled in Grove V4. SumBudgetWindowProof provides canonical encoding and bounded decoding.
Window proof generation grovedb/src/operations/proof/generate.rs	Proof generation classifies sum-budget queries, checks the V1 envelope gate, walks the eligible range, records the stop condition, and emits a terminal SumBudgetWindow proof.
Window proof verification grovedb/src/operations/proof/verify.rs, grovedb/src/operations/proof/verify_path_query.rs	Verification decodes the window, replays matching and budget rules, validates the stop condition, rejects ordinary Merk descent, and returns VerifiedPathQuery::SumBudget.
End-to-end validation grovedb/src/tests/sum_budget_proof_tests.rs, grovedb/src/tests/verify_path_query_shape_tests.rs, grovedb/src/tests/read_mode_gate_tests.rs, grovedb/src/tests/mod.rs	Tests cover budget, match-limit, and exhaustion stops; trusted-read agreement; tampered metadata; invalid descent; and Grove V3 rejection.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant PathQuery
  participant ProofGenerator
  participant SumBudgetWindowProof
  participant ProofVerifier
  participant VerifiedPathQuery
  PathQuery->>ProofGenerator: submit sum-budget query
  ProofGenerator->>SumBudgetWindowProof: build and encode terminal window
  SumBudgetWindowProof-->>ProofVerifier: carry window metadata and Merk proof
  ProofVerifier->>ProofVerifier: replay budget and stop conditions
  ProofVerifier-->>VerifiedPathQuery: return matches, total, and stop

Loading

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/sum-budget-proofs-v2

---

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 76.37615% with 103 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.15%. Comparing base (2ce6fdf) to head (e11cf87).
⚠️ Report is 1 commits behind head on develop.

Files with missing lines	Patch %	Lines
grovedb/src/operations/proof/verify.rs	72.22%	45 Missing ⚠️
grovedb/src/operations/proof/generate.rs	82.78%	26 Missing ⚠️
grovedb/src/operations/proof/verify_path_query.rs	59.61%	21 Missing ⚠️
grovedb/src/operations/proof/mod.rs	71.42%	8 Missing ⚠️
grovedb-query/src/read_mode.rs	82.35%	3 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #807      +/-   ##
===========================================
- Coverage    92.23%   92.15%   -0.08%     
===========================================
  Files          267      267              
  Lines        80895    81285     +390     
===========================================
+ Hits         74612    74908     +296     
- Misses        6283     6377      +94     

Components	Coverage Δ
grovedb-core	90.33% <76.13%> (-0.16%)	⬇️
merk	93.13% <ø> (ø)
storage	87.00% <ø> (ø)
commitment-tree	96.05% <ø> (ø)
mmr	96.79% <ø> (ø)
bulk-append-tree	89.82% <ø> (ø)
element	97.92% <ø> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.