feat: keys-only projection for axis reads on the unified PathQuery

[QuantumExplorer]

Follow-up to #824.

Why

run_path_query served every ReadMode::Axis read through the resolving indexed-axis reads, so the unified path had no way to ask for the ranking pairs alone. A caller that only ranks (Dash Platform's ranked / having executors, any leaderboard view) paid up to k primary point reads per page — through its own transaction, after the pinned secondary page was collected, so outside the iterator's view whenever that transaction is None — for values it then discards. #824 gave the standalone API a keys-only shape; this gives the PathQuery vocabulary the same, so the planned unified-path rebuild of branched ranked queries (dashpay/platform#4401) doesn't re-inherit the blocker raised on dashpay/platform#4382.

What

• AxisQuery.projection: AxisProjection { Entries (default), Keys } — encoded as a trailing frozen tag byte (0 / 1; unknown rejected). validate rejects Keys on the traversals that list no entries (RankOfKey, AggregateOverValueRange) — enforced at classify, so read, prove and verify agree. AxisQuery::keys_only() / with_projection() builders; PathQuery::new_axis(path, axis_query) to build a read from an already-configured AxisQuery.
• run_path_query routes a Keys read through the _keys reads (never opens the primary) and returns PathQueryRun::AxisKeys(AxisKeys) / BranchedAxisKeys (absent branches None, exactly as for entries). AxisKeys { Count | Sum | Avg } holds the (ordering_value, original_key) pairs; AxisEntries::to_keys() is the projection.
• Prove / verify are unchanged: the projection is an unproved-read choice. A proof always carries the referenced primary values and verification yields entries; keys are a strict projection of them, so prover and verifier treat a Keys query exactly as Entries (pinned by test).
• Book: unified-path-query.md documents the field and the semantics.

Tests

axis_read_projection_tests: keys == entries projected on every axis, both directions, with and without an offset, for ranked-page and bounded traversals; branched keys == branched entries projected including an absent branch; keys == verified entries projected; keys reads cost strictly fewer seeks and loaded bytes; Keys rejected on rank-of-key and value-range aggregates. grovedb-query: projection round-trips, tag frozen, unknown tag rejected, validation matrix. Full grovedb lib suite green (2845 passed), lib clippy clean (incl. empty_line_after_doc_comments), verifier-only build unaffected.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@QuantumExplorer, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 28 minutes

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.

How can I continue?

Wait for the limit to reset, then comment @coderabbitai review or push new commits to the PR.

An organization admin can change what happens after included review limits in Billing.

How do review limits work?

CodeRabbit enforces per-developer PR review limits within each organization.

For paid Pro and Pro+ reviews, CodeRabbit uses a developer's included PR review attempts over the past 7 days to set the current hourly allowance. At typical activity levels, the full plan allowance applies. Higher sustained activity can lower the allowance until earlier attempts leave the 7-day window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 3f50ad89-091f-453b-ba0e-e0145834d6f7

📥 Commits

Reviewing files that changed from the base of the PR and between 1b18de6 and 7d36edc.

📒 Files selected for processing (10)

• docs/book/src/unified-path-query.md
• grovedb-query/src/axis_query.rs
• grovedb-query/src/lib.rs
• grovedb/src/lib.rs
• grovedb/src/operations/get/run_path_query.rs
• grovedb/src/operations/proof/indexed_axis/envelope.rs
• grovedb/src/query/mod.rs
• grovedb/src/query_result_type.rs
• grovedb/src/tests/axis_read_projection_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

❌ Patch coverage is 97.05882% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.41%. Comparing base (1b18de6) to head (7d36edc).

Files with missing lines	Patch %	Lines
grovedb/src/operations/get/run_path_query.rs	96.96%	4 Missing ⚠️
grovedb/src/query_result_type.rs	66.66%	3 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #827      +/-   ##
===========================================
+ Coverage    92.39%   92.41%   +0.01%     
===========================================
  Files          288      288              
  Lines        87906    88135     +229     
===========================================
+ Hits         81219    81447     +228     
- Misses        6687     6688       +1     

Components	Coverage Δ
grovedb-core	90.61% <95.33%> (+0.02%)	⬆️
merk	93.27% <ø> (ø)
storage	87.08% <ø> (ø)
commitment-tree	96.29% <ø> (ø)
mmr	96.49% <ø> (ø)
bulk-append-tree	92.27% <ø> (ø)
element	97.98% <ø> (ø)

🚀 New features to boost your workflow:

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