fix(batch): enforce reference hop limits for existing refs

[QuantumExplorer]

Summary

• remove the hop-one batch reference shortcut that borrowed the target value hash without decoding it
• resolve hop-one on-disk targets through the existing element-aware path so terminal references hit ReferenceLimit
• add a regression for a one-hop batch reference pointing at an existing reference

Fixes #687.

Verification

• cargo test -p grovedb test_batch_ref_hop_one_to_existing --lib
• git diff --check

[coderabbitai]

Warning

Rate limit exceeded

@QuantumExplorer has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 53 minutes and 11 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: 76556056-085e-417f-8e2b-08a700364ea1

📥 Commits

Reviewing files that changed from the base of the PR and between a2129a9 and ef25e07.

📒 Files selected for processing (6)

• grovedb-version/src/version/grovedb_versions.rs
• grovedb-version/src/version/v1.rs
• grovedb-version/src/version/v2.rs
• grovedb-version/src/version/v3.rs
• grovedb/src/batch/mod.rs
• grovedb/src/tests/batch_unit_tests.rs

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-687-batch-reference-limit

---

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.43%. Comparing base (60f2968) to head (ef25e07).
⚠️ Report is 3 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop     #733   +/-   ##
========================================
  Coverage    91.42%   91.43%           
========================================
  Files          236      236           
  Lines        67053    67119   +66     
========================================
+ Hits         61305    61371   +66     
  Misses        5748     5748           

Components	Coverage Δ
grovedb-core	88.94% <100.00%> (+<0.01%)	⬆️
merk	92.26% <ø> (ø)
storage	86.36% <ø> (ø)
commitment-tree	96.43% <ø> (ø)
mmr	96.79% <ø> (+0.03%)	⬆️
bulk-append-tree	89.39% <ø> (+0.13%)	⬆️
element	97.38% <ø> (+0.01%)	⬆️

🚀 New features to boost your workflow:

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

[QuantumExplorer]

I think we don't want this one.

[QuantumExplorer]

Closing: the hop=1 fast path this changes is documented intentional behavior, not an oversight. The 18-line comment added in #667 (merged 2026-05-17, before issue #687 and this PR were filed) explicitly declares max_hop=1 pointing at another Reference to be ill-formed input that is out of scope for the fast path, caught by verify_grovedb, with the decode cost deliberately skipped. The path is also unreachable through Drive: hop=1 references (document index refs, contested doc refs) always target Item primary storage, and keep-history uses hop=2 through the latest-version reference, which takes the decode path before the final hop. As written the PR would additionally flip cost behavior inside the already-in-use GROVE_V3 rather than introducing a new version. If we ever want to revisit the documented contract, that should happen as a design discussion on #687, not via this patch.