docs: document chunk restore height placeholder safety (#15)

[QuantumExplorer]

Summary

• Documents why intermediate height placeholder values during chunk restoration are safe (audit finding feat: multi path + multi key proof construction #15)
• Adds comprehensive doc comments to Restorer struct, write_chunk, finalize, rewrite_heights, and Child::as_link explaining the three-layer safety guarantee: exclusive ownership, no structural mutations during restore, and mandatory height verification/rewrite in finalize()
• This is a documentation-only change; no behavioral modifications

Analysis

During chunk restoration, Link::Reference entries at chunk boundaries are written with placeholder child_heights of (0, 0) because the actual subtree behind a Node::Hash has not yet been received. Finding #15 noted these heights are "trusted before verification."

Conclusion: Safe by design. The Restorer exclusively owns the Merk during restoration -- no external queries, inserts, or AVL rebalancing occur on the partially-restored tree. The finalize() method performs a full recursive height audit via verify_height() and, if any discrepancy is found, rewrite_heights() traverses the entire tree bottom-up to compute correct heights from the actual structure. A Merk with incorrect heights can never escape the Restorer.

Test plan

• cargo check -p grovedb-merk --features full passes
• cargo fmt -- --check passes
• All pre-commit hooks pass
• Documentation-only change -- no new tests needed

🤖 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 27 minutes and 22 seconds before requesting another review.

⌛ 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: c04a831c-25f3-4ab1-8864-184cb852036b

📥 Commits

Reviewing files that changed from the base of the PR and between 6285dde and b6ceb91.

📒 Files selected for processing (2)

• merk/src/merk/restore.rs
• merk/src/proofs/tree.rs

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/chunk-restore-height-safety

---

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 90.70%. Comparing base (6285dde) to head (b6ceb91).
⚠️ Report is 3 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop     #619   +/-   ##
========================================
  Coverage    90.70%   90.70%           
========================================
  Files          182      182           
  Lines        50734    50734           
========================================
  Hits         46016    46016           
  Misses        4718     4718           

Components	Coverage Δ
grovedb-core	88.80% <ø> (ø)
merk	92.05% <ø> (ø)
storage	86.37% <ø> (ø)
commitment-tree	96.41% <ø> (ø)
mmr	96.72% <ø> (ø)
bulk-append-tree	90.85% <ø> (ø)
element	97.55% <ø> (ø)

🚀 New features to boost your workflow:

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

[QuantumExplorer]

Approved