feat: add Element::NotSummed wrapper to opt-out of sum propagation

[QuantumExplorer]

Issue being fixed or feature implemented

Symmetric counterpart to Element::NonCounted (#654). Where NonCounted opts a child out of count propagation in count-bearing trees, NotSummed opts a sum-bearing subtree out of sum propagation in sum-bearing trees.

Use case: a SumTree of category subtotals, where one inner sum-tree should be informational only — it tracks its own sum but does not bubble up to the parent total.

What was done?

Added a new Element::NotSummed(Box<Element>) variant that:

• behaves identically to its inner element for storage, hashing, and the inner sum-tree's own internal sum aggregate,
• contributes 0 to the parent sum tree's running sum,
• still contributes the inner element's count to a parent count tree (only sum is suppressed),
• may only wrap one of the four sum-tree variants (SumTree, BigSumTree, CountSumTree, ProvableCountSumTree),
• may only be inserted into a sum-bearing parent (SumTree, BigSumTree, CountSumTree, ProvableCountSumTree).

Design choice: stricter inner-type whitelist than NonCounted

NonCounted can wrap any element (including items, references, all tree types). NotSummed restricts the inner to the four sum-tree variants because that is where the wrapper is semantically meaningful — a sum-bearing subtree that retains its own internal sum but contributes nothing to the parent. Wrapping items or non-sum trees would have no effect distinct from using the bare type.

The constructor Element::new_not_summed returns Result and rejects everything else with InvalidInput. Serialization and deserialization enforce the same whitelist, plus an O(1) two-byte pre-check that rejects all four wrapper-on-wrapper combinations ([15,15], [15,16], [16,15], [16,16]) before bincode can recurse — closing a stack-exhaustion vector.

Discriminant scheme

	bincode (Element)	ElementType flag bit	twins
NonCounted (existing)	15	0x80	128..=142 (15 twins)
NotSummed (new)	16	0x40	68, 69, 71, 74 (only 4 twins)

The disjoint flag bits keep is_non_counted() and is_not_summed() independently testable on ElementType. base() strips whichever flag is set. The two wrappers are mutually exclusive in practice — constructors and (de)serializers reject any nesting, including cross-nesting NotSummed(NonCounted(_)) and NonCounted(NotSummed(_)).

Cryptographic notes

The wrapper byte is part of the serialized value, so the value hash distinguishes NotSummed(X) from a bare X. The parent's TreeFeatureType for a not-summed child is the inner element's feature type with its sum component zeroed (via a new TreeFeatureType::zero_sum() helper, symmetric to zero_count()); no new TreeFeatureType variants are introduced.

Scope

Touched 27 files across grovedb-element, grovedb-query, grovedb-merk, and grovedb. Mirrors PR #654's wiring throughout the stack:

• enum + discriminant + constructor + helpers + serialization
• merk: TreeType::is_sum_bearing(), insert validation, feature-type dispatch, get/cost paths, reconstruct preserves wrapper
• grovedb: batch propagation tracks not_summed flag alongside non_counted in InsertTreeWithRootHash, parent-type guard, estimated cost overhead, debugger transparency
• existing tests in tests/{batch_unit,batch_coverage,batch_rejection}_tests.rs updated for the new field

How Has This Been Tested?

New tests:

• grovedb-element (10 tests): constructor whitelist (rejects items, sum items, plain trees, count trees, all wrapper nesting; accepts the four sum-tree variants); helper passthrough (is_*, sum_value_or_default → 0, count_value_or_default still propagates, count_sum_value_or_default → (count, 0), flag accessors); bincode round-trip; reject nested wrappers at deserialize and at serialize; long-chain pre-check stack-overflow guard.
• grovedb-element discriminant pinning: pins NOT_SUMMED_WRAPPER_DISCRIMINANT = 16 and the four 0x40 | base twin discriminants; rejects all illegal inner bytes including the wrapper bytes themselves and the synthetic twin range.
• grovedb-merk (5 tests): insert into NormalTree and CountTree is rejected; insert into SumTree succeeds and contributes 0; NotSummed(SumTree(_,100,_)) in a ProvableCountSumTree yields count=1 sum=0; reconstruct_with_root_key preserves the wrapper through propagation; constructor rejects non-sum-tree inner.
• grovedb (tests/not_summed_tests.rs, 5 tests): batch insert rejected into NormalTree and CountTree; direct insert in SumTree excludes subtree sum from parent aggregate; batch propagation preserves wrapper through InsertTreeWithRootHash (with both wrapper insert AND child insert in the same batch); check_subtree_exists works through the wrapper.

Full workspace test suite passes:

• cargo test -p grovedb-element — 74 passed (57 unit + 17 integration)
• cargo test -p grovedb-query — 235 passed
• cargo test -p grovedb-merk --features minimal,test_utils,full — 416 passed
• cargo test -p grovedb — 1495 passed

Breaking Changes

None for existing callers. The change adds a new Element variant and is additive at the API surface. The on-disk serialization format gains bincode discriminant 16 — older code reading data written with this variant would fail to deserialize, so producer/consumer pairs need to be upgraded together. This matches the existing "ONLY APPEND TO THIS LIST" comment on the Element enum.

The internal GroveOp::InsertTreeWithRootHash variant gains a not_summed: bool field; the variant is #[non_exhaustive] and only constructed inside this crate, but the four in-tree test sites that build it directly are updated.

Checklist:

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have added or updated relevant unit/integration/functional/e2e tests
• I have made corresponding changes to the documentation

🤖 Generated with Claude Code

[coderabbitai]

Warning

Rate limit exceeded

@QuantumExplorer has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 55 minutes and 46 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 372951dd-2277-41df-9f96-dbb420609c29

📥 Commits

Reviewing files that changed from the base of the PR and between 1206049 and b00b830.

📒 Files selected for processing (29)

• grovedb-element/Cargo.toml
• grovedb-element/src/element/constructor.rs
• grovedb-element/src/element/helpers.rs
• grovedb-element/src/element/mod.rs
• grovedb-element/src/element/serialize.rs
• grovedb-element/src/element/visualize.rs
• grovedb-element/src/element_type.rs
• grovedb-query/src/proofs/tree_feature_type.rs
• grovedb/src/batch/mod.rs
• grovedb/src/debugger.rs
• grovedb/src/estimated_costs/average_case_costs.rs
• grovedb/src/estimated_costs/worst_case_costs.rs
• grovedb/src/lib.rs
• grovedb/src/operations/get/query.rs
• grovedb/src/operations/insert/mod.rs
• grovedb/src/operations/proof/generate.rs
• grovedb/src/operations/proof/verify.rs
• grovedb/src/reference_path.rs
• grovedb/src/tests/batch_coverage_tests.rs
• grovedb/src/tests/batch_rejection_tests.rs
• grovedb/src/tests/batch_unit_tests.rs
• grovedb/src/tests/mod.rs
• grovedb/src/tests/not_summed_tests.rs
• merk/src/element/costs.rs
• merk/src/element/get.rs
• merk/src/element/insert.rs
• merk/src/element/reconstruct.rs
• merk/src/element/tree_type.rs
• merk/src/tree_type/mod.rs

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/not-summed-foundation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[QuantumExplorer]

@coderabbitai review

This is Claude. The PR is intentionally in draft while we wait for the first review pass — please review it now.

[coderabbitai]

@QuantumExplorer Sure, I'll start the review of PR #659 now!

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[codecov]

Codecov Report

❌ Patch coverage is 91.83938% with 63 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.74%. Comparing base (1206049) to head (b00b830).

Files with missing lines	Patch %	Lines
grovedb/src/batch/mod.rs	51.16%	21 Missing ⚠️
grovedb-element/src/element/mod.rs	93.41%	11 Missing ⚠️
grovedb-element/src/element/constructor.rs	83.33%	4 Missing ⚠️
grovedb-element/src/element/helpers.rs	97.03%	4 Missing ⚠️
grovedb/src/operations/get/query.rs	0.00%	4 Missing ⚠️
merk/src/element/insert.rs	95.00%	4 Missing ⚠️
merk/src/element/get.rs	70.00%	3 Missing ⚠️
grovedb/src/estimated_costs/worst_case_costs.rs	66.66%	2 Missing ⚠️
grovedb/src/operations/proof/generate.rs	0.00%	2 Missing ⚠️
grovedb/src/operations/proof/verify.rs	0.00%	2 Missing ⚠️
... and 6 more

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #659      +/-   ##
===========================================
+ Coverage    90.64%   90.74%   +0.10%     
===========================================
  Files          184      184              
  Lines        54826    55532     +706     
===========================================
+ Hits         49699    50395     +696     
- Misses        5127     5137      +10     

Components	Coverage Δ
grovedb-core	88.53% <46.03%> (-0.06%)	⬇️
merk	92.26% <95.18%> (+0.17%)	⬆️
storage	86.36% <ø> (ø)
commitment-tree	96.43% <ø> (ø)
mmr	96.76% <ø> (ø)
bulk-append-tree	89.14% <ø> (ø)
element	95.75% <95.91%> (+0.51%)	⬆️

🚀 New features to boost your workflow:

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

[QuantumExplorer]

Codex review findings:

1. [P1] Reject cross-wrapper construction (grovedb-element/src/element/constructor.rs:393-407)

new_non_counted only rejects NonCounted, so it can still construct NonCounted(NotSummed(...)) even though serialization rejects cross-wrapper nesting. That value can reach batch execution with is_non_counted() == true and underlying() == NotSummed, then hit the supposedly-unreachable wrapper arm instead of returning a typed error.

Suggested fix: make new_non_counted reject both wrapper variants, and make into_non_counted avoid wrapping NotSummed as well, either by making it fallible or by adding a separate checked helper for external callers. Add a batch regression for NonCounted(NotSummed(SumTree)) to confirm it returns an InvalidInput / InvalidBatchOperation instead of panicking.

2. [P2] Add serde-side wrapper validation (grovedb-element/src/element/mod.rs:45-47)

The bincode serialize/deserialize paths now reject nested wrappers and NotSummed with a non-sum-tree inner, but the serde feature still derives recursive Deserialize for Element. With serde enabled, a payload can construct invalid NotSummed(Item) / cross-wrapper values, and deeply nested wrapper payloads still recurse before any validation runs.

Suggested fix: replace the derived serde deserialize path with a manual visitor or serde helper wrappers that enforce the same invariants as Element::deserialize: wrapper inners must not be wrappers, and NotSummed may only wrap SumTree, BigSumTree, CountSumTree, or ProvableCountSumTree. Add serde-feature tests for nested wrapper rejection and NotSummed(non_sum_tree) rejection.

[QuantumExplorer]

Reviewed