test: pin the envelope relationship between prove_query and the direct indexed-axis provers (#835)

[QuantumExplorer]

What

Builds out #835: a golden test suite (grovedb/src/tests/envelope_byte_equality_tests.rs) pinning the byte-level relationship between prove_query on single-path axis queries and the direct prove_indexed_* provers, so platform's switch to the unified surface is a proven relationship rather than an assumption.

The documented finding: outer envelopes are NOT byte-identical — by construction

The two surfaces deliberately emit different wire formats, so whole-proof byte-equality does not hold and never did. The divergence is enumerated in the test module doc:

	direct provers	prove_query
envelope type	IndexedAxisPaginatedProof / IndexedAxisRangeProof	GroveDBProof::V1
bincode config	standard() (little-endian)	standard().with_big_endian()
path attestation	layer_proofs (single-key Merk proof per segment) + ancestor_attestations	ordinary LayerProof nesting of the general proof walk
echoed parameters	axis, k / offset / limit, direction — echoed and verifier-authenticated	only axis_tag (plus the rank for RankOfKey); everything else is query-as-input

This lands in the issue's second acceptance branch ("where equality does not hold — a documented enumeration of the divergence and mutual-acceptance tests between the two verifier entry points"). Since the formats are disjoint, mutual acceptance resolves as mutual rejection, and the suite pins that too: each verifier entry point cleanly errors (no panic, no false accept) on the other family's bytes, so the families cannot be cross-fed accidentally.

Divergence 2 (found by CI): bounded-over-empty is unified-only

The first CI run surfaced a genuine capability divergence the suite had assumed away — exactly the outcome the issue says to document rather than fear: a bounded read over a completely empty secondary proves on the unified surface (empty proof bytes resolving to a NULL_HASH secondary root, so the parent binding attests the emptiness) but is refused outright by the standalone range prover (merk-level "Cannot create proof for empty tree" — it has no empty-tree shape). The paginated shape has no such gap: both surfaces prove empty secondaries. Both behaviors are now pinned by the empty-secondary test and enumerated in the module doc. This is the same asymmetry platform's drive-abci maps onto its retry-unproved InvalidArgument for the having surface.

The pinned equality: the semantic core is byte-identical

For the same state and arguments, across all three axes × both traversal shapes (top-k-paginated, bounded) × both directions × empty and populated secondaries × offset 0 / mid / past-the-end, the tests pin byte-for-byte equality of the security-relevant payload shared by the unified AxisDescentProof layer and the direct envelopes:

• secondary_proof — the encoded Merk proof over the per-axis secondary,
• target_chains — the resolved primary rows,
• primary_root_hash, other_axes_root_hashes, target_is_pcpsit, axis_tag,

plus the observable equivalence that makes the platform switch a pure refactor: both verifiers reconstruct the same GroveDB root hash and return identical entries (and identical attested skipped for the paginated shape), and both provers are pinned deterministic (proving twice yields identical bytes — the goldens are stable).

Also covered: the single-secondary PSIT target shape (target_is_pcpsit = false), an in-domain empty selection window, the empty-proof-bytes convention over empty secondaries, and the direct envelopes' parameter echoes (requested_k / requested_offset / requested_limit / descending / axis_tag).

Notes for reviewers

• The bounded cross-checks drive the direct prove/verify_indexed_{count,sum,avg}_query entry points through the same axis_lowering::axis_bounded_merk_query lowering both proof sides already share, so the compared queries cannot drift.
• Test-only change; no production code is touched. The book's "Relationship to the specialized surfaces" section (docs/book/src/unified-path-query.md) already states the entries/root-hash equivalence these tests now pin at the byte level.

Closes #835.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

Next included review available in 29 minutes.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4a53a410-b58a-44a5-acb3-9452f06df6ca

📥 Commits

Reviewing files that changed from the base of the PR and between 6b34ea8 and 8d29a25.

📒 Files selected for processing (2)

• grovedb/src/tests/envelope_byte_equality_tests.rs
• grovedb/src/tests/mod.rs

---

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.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.53%. Comparing base (0b85d7e) to head (8d29a25).
⚠️ Report is 2 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop     #837   +/-   ##
========================================
  Coverage    92.53%   92.53%           
========================================
  Files          292      292           
  Lines        90484    90501   +17     
========================================
+ Hits         83727    83745   +18     
+ Misses        6757     6756    -1     

Components	Coverage Δ
grovedb-core	90.68% <ø> (+<0.01%)	⬆️
merk	93.27% <ø> (+<0.01%)	⬆️
storage	91.95% <ø> (ø)
commitment-tree	96.38% <ø> (ø)
mmr	95.12% <ø> (ø)
bulk-append-tree	92.75% <ø> (ø)
element	97.98% <ø> (ø)

🚀 New features to boost your workflow:

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