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

[QuantumExplorer]

Context

PR 5 of the unified PathQuery effort (stacked on #799 ← #798 ← #797 ← #795). Sum-budget path queries — ReadMode::SumBudget: walk items in key order, stop when the running net sum reaches the budget — gain a proof form, completing proof coverage for every read-mode shape.

Design

The window is the proof. A new appended ProofBytes::SumBudgetWindow variant carries { exhausted, window_len, merk_proof }: an ordinary Merk proof over exactly the window of elements the budget walk scanned. No new cryptographic machinery — the parent binding falls out of the ordinary combine_hash(H(value), child_root) tree-descent check, and merk limit-proof semantics already attest "these are the first N elements in walk order".

The fold replay is the attestation. The verifier executes the window proof with the query's own items and direction — limited to the claimed window on a stop, unlimited on claimed exhaustion (so the proof itself must prove the range end) — then replays the read engine's exact fold arithmetic element by element: saturating net-budget subtraction (negative sum items give budget back), the per-match limit, and the grove-version global scan cap including its counted-but-unprocessed tripping element. A window that continues past a fired stop, stops short of one, or misstates exhaustion is rejected. A plain Merk descent at a sum-budget position is also rejected, so the shape can never be silently served as key selection.

Provable fold semantics, pinned. The provable shape skips non-sum elements and skips references — the two behaviors a single-subtree window proof can replay deterministically (a reference's target lives outside the window). run_path_query's trusted read switches to the same options, so read ≡ verified over any state; the legacy AggregateSumPathQuery surface keeps its configurable options untouched.

Engine-truth corrections made while pinning the replay against element/aggregate_sum_query:

• SumBudgetRead.max_items_checked → match_limit: the engine decrements this per matched result, not per scanned element — the PR feat: ReadMode vocabulary — PathQuery expresses axis and sum-budget reads #797 name and doc were wrong (wire layout unchanged; the stack is unmerged so no compat concern)
• sum_limit > i64::MAX now rejected at validation (the engine's budget arithmetic is signed and errors there anyway)
• AggregateSumQueryResult gains elements_scanned — the window size the prover needs, and a useful read-API datum in its own right

Gating: new proof.sum_budget_in_v1_envelope slot (0 in V1–V3, 1 in V4) read by both sides; V0-envelope refusal follows the ACOR template. verify_path_query returns VerifiedPathQuery::SumBudget { matches, total, stop } with the replay-attested SumBudgetStop (BudgetReached / MatchLimitReached / HardScanCapReached / Exhausted).

Tests

• Round trips for all stop conditions: budget (incl. negative values giving budget back), match limit, exhaustion, and skip-semantics windows containing foreign elements
• Read ≡ verified agreement across budget configurations
• Forgeries: understated window (claiming an earlier stop), exhaustion lies in both directions, plain-descent substitution at the sum-budget position
• V3-refuses / V4-serves gates on both prover and verifier
• Full suites green, clippy clean, verify-only build green

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: cc6ecb41-7800-4529-84c8-b08c39f22b9b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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

[QuantumExplorer]

Reviewed