fix(artifacts): unify Merkle odd-node level advancement and explicit sibling indexing

[rishiiicreates]

addresses #45

unifies odd-node level advancement and sibling index calculation between merkle_root_from_leaf_hashes() and generate_merkle_proof():

• added _next_merkle_level() helper that handles odd-count node duplication without mutating the input level list in-place
• replaced the fragile index ^ 1 XOR in generate_merkle_proof() with explicit parity check and bounds guarding:

  sibling_index = index - 1 if index % 2 == 1 else index + 1
  if sibling_index >= len(level):
      sibling_index = index

• expanded tests/test_artifacts.py with unit tests covering:
  • _next_merkle_level() parity behavior on even and odd lists
  • exhaustive proof generation and round-trip verification across chunk counts 1 through 16
  • corruption rejection (tampered chunk bytes, flipped sibling position, mutated sibling hash)
  • out-of-bounds index and malformed proof handling

tested locally with pytest tests/test_artifacts.py (7/7 passed), python reproducibility.py falsifiability suite (all 5 scenarios passed), and chain.py train/audit smoke.

Summary by CodeRabbit

• Bug Fixes

  • Merkle proofs now handle files with an odd number of chunks correctly, including the final chunk at each tree level.
  • Generating Merkle levels no longer changes the input list.

• Tests

  • Expanded coverage for proof verification, invalid proof data, chunk-count edge cases, and empty files.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 1b4c8276-e9a8-4b7d-acbd-ff5ae1594471

📥 Commits

Reviewing files that changed from the base of the PR and between 14a21c4 and afec576.

📒 Files selected for processing (2)

• src/artifacts.py
• tests/test_artifacts.py

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

---

📝 Walkthrough

Walkthrough

Merkle root construction and proof generation now use a shared helper to advance tree levels. Tests cover odd-level pairing, input-list immutability, proof verification, malformed proofs, and invalid chunk indices.

Changes

Merkle tree construction and proofs

Layer / File(s)	Summary
Shared Merkle-level advancement src/artifacts.py, tests/test_artifacts.py	A shared helper pairs adjacent hashes and pairs an unpaired final hash with itself. Root construction uses the helper. Tests check pairing and input-list immutability.
Proof generation and validation src/artifacts.py, tests/test_artifacts.py	Proof generation selects a sibling without mutating the current level and uses the shared helper to advance levels. Tests cover proof verification, malformed proofs, and invalid chunk indices.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Suggested reviewers: ryoari

Merge Risk: ⚪ Minimal · up to afec5

The Merkle changes have no identified issue that needs resolution before merge.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 22.22% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: shared Merkle level advancement and explicit sibling indexing.
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.

• Fix all pre-merge checks with AI

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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

[gitcordapp]

Link your account with Gitcord

Thanks for opening this PR, @rishiiicreates!

To receive Discord notifications and contributor tracking for this organization:

1. Join Discord: https://discord.gg/hjUhu33uAn
2. In Discord, run /link rishiiicreates
3. Paste the verification code into your GitHub bio (or a public gist)
4. Click Verify in Discord (or run /verify-link rishiiicreates)

Once linked, Gitcord can notify you about reviews, merges, and more.

— Posted by Gitcord