docs(audit): record six verified-rejected findings; correct the #693 invariant

[QuantumExplorer]

Follows the pattern set by #769: when an audit finding is adversarially verified and rejected, the rationale gets checked in so the next audit doesn't re-file it.

Six issues were triaged against current develop and closed on GitHub with these same rationales: #691, #700, #702, #703, #682, #721.

New sections

Trust-boundary findings — #682 (lazy-loaded Merk metadata) and #700 (delete_checkpoint). Corrupt local storage and caller-chosen paths are inside GroveDB's trust boundary; integrity auditing is delegated to Merk::verify / verify_grovedb deliberately. The #682 entry also records the argument against fixing it: validating hash_for_link on every link load adds hash_node_calls to the hot read path, and cost changes are replay-critical. It further notes that the debug_assert_eq! at merk/src/tree/mod.rs:1606 is tautological and can never fire, since TreeNode::decode overwrites the decoded key with the lookup key.

Version-gating and build hygiene — #702 (GroveVersion::default: protocol_version is never read anywhere, and default() is behaviorally identical to GROVE_V1), #703 (three of seven refs are read-only APIs; the four typed append entry points already fail closed before any mutation, via their cost dispatchers), #721 (non-default feature, pinned version and pinned SHA-256, fail-closed).

#691 joins the existing proof/encoding section: a dense root-only proof does verify in isolation, but every in-repo verifier either binds it to a query or discards entries and forces the root to the parent-committed hash.

Correction worth reviewing

The overflow section claimed element counts are "hash-verified before any arithmetic runs". That invariant does not hold, and several entries leaned on it.

For the non-Merk lower layers the ordering is reversed: verify.rs:1953-2016 dispatches the MMR / bulk-append / dense verifiers using an Element decoded from the proof's own value_bytes, and only at verify.rs:2018 does combine_hash(value_hash(value_bytes), &lower_hash) bind it to the parent-committed hash. So a forged count genuinely does reach 2 * leaf_count - popcount.

#693 stays closed on impact — the release build wraps and the subsequent chain check rejects the result — but the stated reason was wrong. Worth flagging two consequences: a build with overflow-checks = true panics rather than wrapping, and Element::CommitmentTree routes through the same function, which is live on mainnet. Both the preamble bullet and the #693 row now state the real invariant, so a future refactor that turns a wrap into a hard error doesn't get waved through on a premise that was never true.

Docs only — no code changes.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

Next included review available in 22 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: db2c5d4f-d81c-42ca-a887-370f68f35737

📥 Commits

Reviewing files that changed from the base of the PR and between 6b34ea8 and 5e41368.

📒 Files selected for processing (1)

• docs/audit-non-issues.md

---

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

[QuantumExplorer]

Found three documentation-correctness issues. Most importantly, the corrected #693 rationale still identifies the wrong verifier invariant: the validated bulk-tree height bounds completed_chunks below the multiplication overflow threshold, so the asserted release wrap and overflow-check panic cannot occur. The transaction and optional-dependency statements also need narrower wording. Focused bulk-append, dense-tree, and version tests passed (367 tests), and git diff --check passed.

[QuantumExplorer]

[P2] Use the actual verifier bound for #693

verify_and_compute_root rejects height outside 1..=16 before this calculation. Therefore chunk_item_count = 2^height is at least 2, so for every u64 total_count, completed_chunks <= floor(u64::MAX / 2) = 2^63 - 1. Consequently 2 * completed_chunks - popcount(completed_chunks) cannot overflow. Neither release wrapping nor an overflow-checks = true panic is reachable on this verifier path. Please document this bound and remove the wrap/panic assertions; as written, the audit guide records behavior that cannot occur and the unchanged “Becomes real if” rule immediately matches the newly described unauthenticated input.

[QuantumExplorer]

[P2] Qualify the StorageBatch atomicity claim

The direct typed append operations commit their child data_batch into the transaction before updating the parent Merk; the source comments explicitly say a later parent-update failure leaves orphaned subtree data in the transaction and that a caller-supplied transaction must be rolled back. For example, mmr_tree_append can pass the MMR cost gate, stage and commit its child writes, and then fail a later parent insert_subtree version gate. The early lower-layer dispatcher supports the narrow argument, but “committed only on success” is not generally true. Please qualify this to locally owned transactions/the caller rollback contract, or remove the sentence and narrow the “Becomes real if” condition.

[QuantumExplorer]

[P3] Say optional dependencies are not activated, not unresolved

Cargo still resolves optional dependencies while producing the workspace lockfile even when their features are disabled. A feature-off focused test run here generated a Cargo.lock containing both reqwest and sha2; they are absent from the active feature-off build graph, so the accurate claim is that they are not activated, built, or executed. “Not even resolved” overstates the default-feature isolation.