Expose proof and historical access methods to VersionedKvStore Python API

[zhangfengcdt]

Summary

Comprehensive enhancement of the VersionedKvStore Python API to expose cryptographic proof functionality and historical access methods that were previously only available in Rust.

This PR addresses missing critical functionality in the Python VersionedKvStore class by exposing proof generation/verification and historical state access methods.

Changes Made

1. Proof Methods

Rust Implementation (src/git/versioned_store.rs)

• ✅ Add generate_proof(&self, key: &[u8]) -> Proof<N> method
• ✅ Add verify(&self, proof: Proof<N>, key: &[u8], expected_value: Option<&[u8]>) -> bool method
• ✅ Both methods delegate to underlying ProllyTree implementation
• ✅ Add comprehensive unit test test_versioned_store_proof_methods

Python Bindings (src/python.rs)

• ✅ Add generate_proof(key: bytes) -> bytes to PyVersionedKvStore
• ✅ Add verify_proof(proof_bytes: bytes, key: bytes, expected_value: Optional[bytes]) -> bool
• ✅ Handle proof serialization/deserialization with bincode
• ✅ Thread-safe implementation with proper GIL handling

2. Historical Access Method

Python Bindings (src/python.rs)

• ✅ Add get_keys_at_ref(reference: str) -> List[Tuple[bytes, bytes]] method
• ✅ Properly handles HashMap to Python list of tuples conversion
• ✅ Thread-safe implementation with error handling
• ✅ Supports all git references (commits, branches, tags, HEAD~n, etc.)

Testing

• ✅ Add comprehensive unit test test_get_keys_at_ref
• ✅ Verify access to historical states at different commits
• ✅ Test both commit hashes and symbolic references

3. Type Stubs (python/prollytree/prollytree.pyi)

• ✅ Add generate_proof and verify_proof method signatures
• ✅ Add get_keys_at_ref method signature with comprehensive documentation
• ✅ Add MergeConflict and ConflictResolution classes
• ✅ Add get_commits_for_key, get_commit_history, merge, and try_merge methods
• ✅ Include detailed docstrings with examples for all methods

4. Documentation

• ✅ Updated Python README.md with proof verification examples
• ✅ Added cryptographic verification to VersionedKvStore examples
• ✅ Clarified that proof functionality works across trees and versioned storage

API Usage Examples

Cryptographic Proofs

from prollytree import VersionedKvStore

store = VersionedKvStore.open("/path/to/repo")
store.insert(b"key1", b"value1")
store.commit("Add data")

# Generate cryptographic proof
proof = store.generate_proof(b"key1")

# Verify proof with expected value
is_valid = store.verify_proof(proof, b"key1", b"value1")  # Returns True

# Verify proof for existence only
exists = store.verify_proof(proof, b"key1", None)  # Returns True

Historical Access

# Get all key-value pairs at a specific commit
pairs = store.get_keys_at_ref("abc123def456")
for key, value in pairs:
    print(f"{key}: {value}")

# Get all keys from the main branch
main_pairs = store.get_keys_at_ref("main")

# Get all keys from current HEAD
current_pairs = store.get_keys_at_ref("HEAD")

# Get all keys from previous commit
previous_pairs = store.get_keys_at_ref("HEAD~1")

Benefits

• 🔐 Cryptographic Verification: Merkle proofs for data integrity across versioned storage
• 🔍 Historical Access: Retrieve complete store state at any point in history
• 🎯 API Consistency: VersionedKvStore now has the same proof capabilities as ProllyTree
• 📚 IDE Support: Complete type stubs for IntelliSense and static analysis
• 🐛 Time-Travel Debugging: Debug by examining exact state at past commits
• 📊 Auditing: Track how data evolved over time
• 🔄 Version Control Integration: Proof generation works seamlessly with git operations
• 🔄 Cross-Language Support: Available in both Rust and Python APIs
• ⚡ Thread Safety: Python implementation properly handles GIL and threading

Test Plan

• All existing tests continue to pass
• New unit test test_versioned_store_proof_methods verifies proof functionality
• New unit test test_get_keys_at_ref verifies historical access
• Code formatting and linting checks pass (cargo fmt, cargo clippy)
• Rust compilation succeeds with all features
• Type stubs provide proper IDE support

Checklist

• Code compiles without warnings
• Tests pass locally
• Documentation updated
• Type stubs added/updated
• Pre-commit hooks pass

🤖 Generated with Claude Code