Skip to content

fix: answer a single-path axis read over an absent path with the empty result - #965

Merged
QuantumExplorer merged 1 commit into
developfrom
fix/axis-read-absent-path
Sep 14, 2026
Merged

QuantumExplorer merged 1 commit into
developfrom
fix/axis-read-absent-path

Conversation

@QuantumExplorer

@QuantumExplorer QuantumExplorer commented Sep 14, 2026 •

Copy link
Copy Markdown
Member

Issue being fixed or feature implemented

A single-path axis read (PathQuery::new_axis*) whose path does not exist fails on every surface: run_path_query with a storage error (InvalidParentLayerPath), prove_query with an explicit refusal ("a single-path axis read must produce exactly one axis descent ... the path does not name an indexed tree carrying that axis"). Key selection (test_proof_for_invalid_path) and the branched axis shape already answer an absent path with an authenticated empty result, so this was the one provable shape that could not.

Surfaced in Dash Platform (dashpay/platform#4753): a ranked windowed top-K (IN_TIME_RANGE newest on a range == step grid) descends into the current window's bucket, which only exists once the first document lands in it, and until then every request came back as an internal error instead of an empty leaderboard. The Platform side worked around it by switching single-branch pinned reads to the branched envelope with one key; with this change that workaround goes away and the single-path shape answers correctly on its own, including for OFFSET > 0 (which the branched envelope cannot attest).

What was done?

Absence was always provable here. The generic V1 walk emits the layers that authenticate it: the parent of the missing segment proves the key absent through its single-key Merk proof, an empty ancestor is bound to NULL_HASH (verify_empty_tree_binding), every present non-empty tree on the path must carry its lower layer, and a present axis position must be an indexed tree with an axis layer (the #799 guards). So a verified walk with zero axis layers can only mean the path does not exist, or that a non-tree element blocks it (surfaced as a row).

  • verify_path_query, AxisRead arm: zero axis layers now map to the traversal's empty answer through the new absent_axis_path_into_verified: no entries and skipped: Some(0) for a ranked page (the population is zero), no entries and None for a bounded walk, 0 for a value-range aggregate. A present non-tree row on the queried path is rejected. More than one layer stays an error.
  • prove_query (prove_query_non_serialized_v1): with zero descents the prover settles the same question against the proof's own snapshot (path_is_present): an absent path yields the proof; a present path that does not lead to an indexed tree, or that runs through a non-tree element, is still refused.
  • run_path_query, AxisRead arm: probes the path the way the branched arm already does and returns the same empty answer (absent_axis_run) for an absent path; a present non-tree element part-way down falls through to the primitive's kind error.
  • RankOfKey has no empty answer and fails over an absent path on every surface with PathKeyNotFound, exactly as it does for a key absent from a present tree.
  • AxisKeys::empty_for_axis added, mirroring AxisEntries::empty_for_axis.
  • Docs (unified-path-query.md) and CHANGELOG updated.

No proof format or GroveVersion change: the envelope is unchanged, no prover at any version ever emitted a proof this verifier newly accepts (the prover refused), and the verify-side change is a strict relaxation that the walk's existing guards keep sound.

How Has This Been Tested?

New tests in axis_descent_proof_tests.rs:

  • a_single_path_axis_read_over_an_absent_path_answers_empty_everywhere: absent last segment, absent intermediate segment and an empty-tree ancestor round-trip empty through the reader (entries and keys-only), the prover and the verifier against the live root hash, for ranked (skipped: Some(0) with a requested offset of 1), bounded and both aggregate folds; rank-of-key is refused on both sides with PathKeyNotFound.
  • an_absent_path_proof_covers_only_its_own_gap: the absence proof verifies another key inside its Merk gap as absent (which it truly is) and fails for a key past a hashed-out subtree and for the present tree next to it.
  • stripping_a_single_path_axis_layer_is_rejected_not_read_as_absence: stripping the axis layer of a present indexed tree, populated or empty, from an honest single-path proof is still rejected.
  • a_single_path_axis_read_over_a_present_non_indexed_target_fails_generation (replaces the test that pinned the old refusal for a missing path): a present plain tree and a path through an item are still refused by prover and reader.

Ran: cargo test -p grovedb --lib (3485 passed), cargo clippy -p grovedb --all-targets -- -D warnings, cargo check -p grovedb --no-default-features --features verify, cargo fmt.

Breaking Changes

None. Reads and proofs over an absent path that previously errored now return the empty answer; everything that verified before still verifies to the same result.

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

For repository code-owners and collaborators only

  • I have assigned this pull request to a milestone

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Changed

    • Single-path axis queries now return empty results when the requested path is missing or traverses an empty tree.
    • Ranked queries report no skipped entries, bounded traversals return no results, and value-range aggregates return zero.
    • RankOfKey continues to report a missing-path error.
    • Paths that exist but do not lead to an indexed tree continue to be rejected.
    • Proof generation and verification now consistently reflect these outcomes.
  • Documentation

    • Updated query and proof documentation to describe missing-path behavior.

…y result

A single-path axis read (`PathQuery::new_axis*`) whose path did not exist
failed on every surface: the trusted reader with a storage error, and the
prover with an explicit refusal ("a single-path axis read must produce
exactly one axis descent"), so the verifier never saw such a proof. Key
selection and the branched axis shape already answer an absent path with
an authenticated empty result; the single-path axis read was the one
provable shape that could not, which made a ranking over a window nothing
had been written to yet (a fresh time-range bucket, a prefix value nobody
has used) unanswerable rather than empty.

Absence was always provable here. The generic walk emits the layers that
authenticate it: the parent of the missing segment proves the key absent
through its single-key Merk proof, an empty ancestor is bound to
NULL_HASH, every present non-empty tree on the path must carry its lower
layer, and a present axis position must be an indexed tree with an axis
layer. So zero axis layers in a verified walk can only mean the path does
not exist, or (surfaced as a row) that a non-tree element blocks it.

Now:
- the verifier reads zero axis layers as the traversal's empty answer: no
  entries and `skipped: Some(0)` for a ranked page (the population is
  zero), no entries and `None` for a bounded walk, `0` for a value-range
  aggregate; a present non-tree row on the path is rejected;
- the prover settles the same question against its own snapshot before
  handing the proof out: an absent path yields the proof, a present path
  that does not lead to an indexed tree is still refused;
- the trusted reader probes the path the way the branched arm already
  does and returns the same empty answer for an absent path;
- `RankOfKey`, which has no empty answer, fails over an absent path on
  every surface exactly as it does for a key absent from a present tree.

`AxisKeys::empty_for_axis` is new, mirroring `AxisEntries::empty_for_axis`.

Tests: absent last segment, absent intermediate segment and an
empty-tree ancestor round-trip empty through the reader, the prover and
the verifier for ranked, bounded and both aggregate folds, with rank-of-key
refused; an absence proof covers exactly its Merk gap (a key inside the
gap verifies absent, a key past a hashed-out subtree does not, and the
present tree next to it does not); stripping a present indexed tree's axis
layer, populated or empty, is still rejected rather than read as absence;
a present non-indexed target and a path through an item are still refused
by prover and reader.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Sep 14, 2026 •

Copy link
Copy Markdown
Contributor

Review Change StackReview Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: cb19e436-480e-4b4e-bec9-508acc400845

📥 Commits

Reviewing files that changed from the base of the PR and between bc3a496 and 4d12666.

📒 Files selected for processing (7)
  • CHANGELOG.md
  • docs/book/src/unified-path-query.md
  • grovedb/src/operations/get/run_path_query.rs
  • grovedb/src/operations/proof/generate.rs
  • grovedb/src/operations/proof/verify_path_query.rs
  • grovedb/src/query_result_type.rs
  • grovedb/src/tests/axis_descent_proof_tests.rs

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.


📝 Walkthrough

Walkthrough

Single-path axis reads now return empty results for absent paths across trusted reads and proofs. Present non-indexed paths remain errors. RankOfKey remains an error for absent paths.

Changes

Absent Axis Path Handling

Layer / File(s) Summary
Trusted axis-read handling
grovedb/src/query_result_type.rs, grovedb/src/operations/get/run_path_query.rs
Path segments are checked before axis reads. Absent paths return empty ranked, bounded, or aggregate results. RankOfKey returns PathKeyNotFound.
Proof generation and verification
grovedb/src/operations/proof/generate.rs, grovedb/src/operations/proof/verify_path_query.rs
Zero-axis-descent proofs are accepted for authenticated absent paths and converted to empty results. Present non-indexed paths and invalid proof structures remain rejected.
Behavior validation and documentation
grovedb/src/tests/axis_descent_proof_tests.rs, docs/book/src/unified-path-query.md, CHANGELOG.md
Tests cover missing segments, empty-tree ancestors, proof boundaries, stripped axis layers, and present non-indexed paths. Documentation records the new behavior.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant run_path_query
  participant prove_query_non_serialized_v1
  participant verify_path_query
  Caller->>run_path_query: Execute single-path axis query
  run_path_query-->>Caller: Empty result or PathKeyNotFound
  Caller->>prove_query_non_serialized_v1: Generate proof for the same query
  prove_query_non_serialized_v1-->>Caller: Proof or path error
  Caller->>verify_path_query: Verify proof against the root hash
  verify_path_query-->>Caller: Empty verified result or InvalidProof
Loading

Merge Risk: ⚪ Minimal · up to 4d126

The absent-path behavior is consistently implemented and covered across reads and proofs, with invalid present-path cases remaining rejected. No merge-blocking risk is identified.

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and concisely describes the main change: single-path axis reads over absent paths now return an empty result.
Docstring Coverage ✅ Passed Docstring coverage is 88.24% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 17 functions across 5 files. (2 skipped: 2 …
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ 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 fix/axis-read-absent-path

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

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

@QuantumExplorer
QuantumExplorer force-pushed the fix/axis-read-absent-path branch from fd1e5ee to 4d12666 Compare September 14, 2026 22:16

@QuantumExplorer QuantumExplorer left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed

@QuantumExplorer
QuantumExplorer merged commit a579d52 into develop Sep 14, 2026
12 of 14 checks passed
@QuantumExplorer
QuantumExplorer deleted the fix/axis-read-absent-path branch September 14, 2026 22:34
QuantumExplorer added a commit to dashpay/platform that referenced this pull request Sep 14, 2026
… proves an empty page

A ranked (top-K) or having-range query pinned to a prefix value tree no
document has written yet failed on both the unproved read and the prover.
The reported case is a windowed leaderboard: `IN_TIME_RANGE newest` on a
`range == step` grid resolves to the current bucket's start, and that
bucket's value tree only comes into existence with the first document
written under it (contract registration creates only the level trees, and
TTL drops buckets again), so until the day's first like the single-path
axis read had no indexed tree to descend into. GroveDB refused to generate
the proof ("a single-path axis read must produce exactly one axis descent
... the path does not name an indexed tree carrying that axis") and every
such request surfaced to clients as an internal error. The same failure
hit any `==` pin on a never-written value (a hashtag nobody has used) on
both surfaces.

The refusal was GroveDB's: key selection and the branched axis shape
already answered an absent path with an authenticated empty result, and
the single-path axis read was the one provable shape that did not.
dashpay/grovedb#965 fixes it there, so this bumps the pin to that commit
(6816457d -> 4d12666f, which also carries the 6.0.1 crate versions): the
reader, the prover and the verifier now all answer an absent path with
the traversal's empty page, absence authenticated by the layers the walk
emits. Drive's query shapes are unchanged; only the executor docs and the
book describe the new semantics. Because the single-path shape keeps its
skip attestation, this also covers `OFFSET > 0` over an unwritten prefix.

Tests: ranked and having pinned-prefix tests for a never-written `==` pin
(read, prove, verify against the live root hash, including an offset page
that verifies empty at skip 0); a time-range e2e test for an unwritten
window that later fills; and an ABCI entry-point test verifying an empty
window through the SDK. The having test that pinned the old "error rather
than empty page" rule is flipped.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@codecov

codecov Bot commented Sep 14, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 74.39024% with 42 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.93%. Comparing base (afd0075) to head (4d12666).
⚠️ Report is 3 commits behind head on develop.

Files with missing lines Patch % Lines
grovedb/src/operations/proof/verify_path_query.rs 50.00% 31 Missing ⚠️
grovedb/src/operations/proof/generate.rs 88.46% 6 Missing ⚠️
grovedb/src/operations/get/run_path_query.rs 93.18% 3 Missing ⚠️
grovedb/src/query_result_type.rs 66.66% 2 Missing ⚠️

❌ Your patch status has failed because the patch coverage (74.39%) is below the target coverage (90.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files
@@             Coverage Diff             @@
##           develop     #965      +/-   ##
===========================================
- Coverage    92.96%   92.93%   -0.03%     
===========================================
  Files          331      331              
  Lines       104077   104225     +148     
===========================================
+ Hits         96752    96864     +112     
- Misses        7325     7361      +36     
Components Coverage Δ
grovedb-core 91.21% <74.39%> (-0.05%) ⬇️
merk 93.97% <ø> (ø)
storage 91.86% <ø> (ø)
commitment-tree 95.62% <ø> (ø)
mmr 95.11% <ø> (ø)
bulk-append-tree 92.78% <ø> (ø)
element 97.18% <ø> (ø)
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

QuantumExplorer added a commit to dashpay/platform that referenced this pull request Sep 14, 2026
… proves an empty page

A ranked (top-K) or having-range query pinned to a prefix value tree no
document has written yet failed on both the unproved read and the prover.
The reported case is a windowed leaderboard: `IN_TIME_RANGE newest` on a
`range == step` grid resolves to the current bucket's start, and that
bucket's value tree only comes into existence with the first document
written under it (contract registration creates only the level trees, and
TTL drops buckets again), so until the day's first like the single-path
axis read had no indexed tree to descend into. GroveDB refused to generate
the proof ("a single-path axis read must produce exactly one axis descent
... the path does not name an indexed tree carrying that axis") and every
such request surfaced to clients as an internal error. The same failure
hit any `==` pin on a never-written value (a hashtag nobody has used) on
both surfaces.

The refusal was GroveDB's: key selection and the branched axis shape
already answered an absent path with an authenticated empty result, and
the single-path axis read was the one provable shape that did not.
dashpay/grovedb#965 fixes it there, so this bumps the pin to its merge on
develop (6816457d -> a579d52f, which also carries the 6.0.1 crate
versions): the reader, the prover and the verifier now all answer an
absent path with the traversal's empty page, absence authenticated by the
layers the walk emits. Drive's query shapes are unchanged; only the
executor docs and the book describe the new semantics. Because the
single-path shape keeps its skip attestation, this also covers
`OFFSET > 0` over an unwritten prefix.

The GroveDB git pins now live once in `[workspace.dependencies]`, like the
rust-dashcore ones, and the six consuming crates take them with
`workspace = true` (keeping their own `optional` and `features`;
`default-features = false` for `grovedb` moves to the workspace
declaration, where Cargo actually honours it). The next bump is one line.

Tests: ranked and having pinned-prefix tests for a never-written `==` pin
(read, prove, verify against the live root hash, including an offset page
that verifies empty at skip 0); a time-range e2e test for an unwritten
window that later fills; and an ABCI entry-point test verifying an empty
window through the SDK. The having test that pinned the old "error rather
than empty page" rule is flipped.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant