feat: Enforce secure image ID verification (v0.3.0)

BREAKING CHANGE: Receipt.verify() now requires image_id parameter

Security improvements:
- verify() method now requires external image_id parameter
- Prevents deriving image ID from untrusted receipt data
- Follows security best practice: never trust data from unverified sources

Test improvements:
- Added comprehensive test suite with zero-tolerance policy
- Created run_all_tests.sh master test runner
- All tests and demos return proper exit codes
- Test runner aborts immediately on first failure

API refinements:
- Simplified API with consistent naming conventions
- Removed legacy code and unnecessary complexity
- Better error messages and validation

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: nyc432

CLAUDE.md

@@ -171,4 +171,101 @@ print(dir(pyr0))  # Should show 'serialization' if properly installed
 - **0.x.x** - Alpha/Beta releases
 - **1.x.x** - Stable releases (future)
 
-**Remember**: ALWAYS ask "What version number should this be?" before pushing to GitHub.
+**Remember**: ALWAYS ask "What version number should this be?" before pushing to GitHub.
+
+## Test and Demo Requirements
+
+**CRITICAL**: All tests and demos MUST follow strict error handling guidelines to ensure reliability and maintainability.
+
+### Mandatory Requirements for ALL Tests and Demos:
+
+1. **Exit Codes**: 
+   - MUST exit with code 0 on success, 1 on ANY failure
+   - MUST track failures throughout execution (e.g., `test_passed = False`)
+   - MUST NOT return success if any part failed
+
+2. **No Silent Failures**:
+   - NEVER treat missing dependencies as optional or acceptable
+   - NEVER use warning symbols (⚠️) for actual failures - use error symbols (✗)
+   - NEVER skip tests silently - missing prerequisites are failures
+   - NEVER return success when errors occurred but were caught
+
+3. **Exception Handling**:
+   - MUST fail the test if an unexpected exception occurs
+   - MUST NOT catch and ignore exceptions that indicate real problems
+   - MUST NOT continue execution after critical failures
+
+4. **Dependencies**:
+   - ALL dependencies (like PyR0, merkle_py) are REQUIRED, not optional
+   - If a dependency is missing, the test/demo MUST fail with a clear error
+   - NEVER print "install X to enable feature" - if X is needed, its absence is a failure
+
+5. **Validation**:
+   - MUST verify ALL expected outcomes, not just print them
+   - MUST fail if outputs don't match expectations (wrong size, format, values)
+   - MUST check return codes of called functions and demos
+
+### Integration with Master Test Runner:
+
+All new tests and demos MUST be added to `run_all_tests.sh`:
+
+```bash
+# Add your test/demo to the appropriate section:
+run_test "Your Test Name" "uv run path/to/your_test.py"
+```
+
+The master test runner (`./run_all_tests.sh`):
+- Runs tests and demos in sequence, aborting immediately on first failure
+- Shows colored output with clear failure messages
+- Exits with code 1 immediately upon ANY test failure
+- Exits with code 0 only if ALL tests pass (zero tolerance)
+- Does NOT skip tests for missing dependencies - all are required
+
+### Example of CORRECT Test Structure:
+
+```python
+#!/usr/bin/env python3
+import sys
+
+test_passed = True
+
+try:
+    # Test something
+    result = do_something()
+    if not result:
+        print("✗ Test failed: unexpected result")
+        test_passed = False
+except Exception as e:
+    print(f"✗ Test failed with error: {e}")
+    test_passed = False
+
+if test_passed:
+    print("✓ All tests passed")
+    sys.exit(0)
+else:
+    print("✗ Some tests failed")
+    sys.exit(1)
+```
+
+### Example of INCORRECT Patterns (NEVER DO THESE):
+
+```python
+# WRONG - Silent failure
+try:
+    import required_module
+except ImportError:
+    print("⚠️ Module not available, skipping test")  # NO!
+    return  # This hides a failure!
+
+# WRONG - Treating errors as acceptable
+if not dependency_exists:
+    print("Continuing without dependency...")  # NO!
+    # Should fail here instead
+
+# WRONG - Success despite errors
+except Exception as e:
+    print(f"Error: {e}")
+    # No test_passed = False here!  # NO!
+```
+
+**Remember**: The goal is ZERO TOLERANCE for failures. If something should work, it MUST work, or the test MUST fail visibly with exit code 1.

Cargo.toml

@@ -2,7 +2,7 @@
 
 [package]
 name = "pyr0"
-version = "0.2.0"
+version = "0.3.0"
 edition = "2021"
 
 [lib]

README.md

@@ -1,11 +1,11 @@
 # PyR0 - Python Interface for RISC Zero zkVM
 
-[![Version](https://img.shields.io/badge/version-0.2.0-orange)](https://github.com/garyrob/PyR0/releases)
+[![Version](https://img.shields.io/badge/version-0.3.0-orange)](https://github.com/garyrob/PyR0/releases)
 **⚠️ Experimental Alpha - Apple Silicon Only**
 
 Python bindings for [RISC Zero](https://www.risczero.com/) zkVM, enabling zero-knowledge proof generation and verification from Python.
 
-> **Note**: This is an experimental alpha release (v0.2.0) currently targeting Apple Silicon (M1/M2/M3) Macs only.
+> **Note**: This is an experimental alpha release (v0.3.0) currently targeting Apple Silicon (M1/M2/M3) Macs only.
 
 ## Overview
 
@@ -29,6 +29,65 @@ The typical workflow:
 3. Use PyR0 to load the ELF, provide input, and generate a proof
 4. Share the proof and journal (public outputs) for verification
 
+## Guest Program Development
+
+### Basic Guest Setup
+
+A minimal RISC Zero guest program requires proper configuration:
+
+**Cargo.toml:**
+```toml
+[package]
+name = "my-guest"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+# Basic setup - works for simple guests
+risc0-zkvm = { version = "1.2", default-features = false, features = ["std"] }
+```
+
+### Memory Management
+
+⚠️ **Critical for complex guests**: The default bump allocator never frees memory, causing "Out of memory!" errors even with moderate data.
+
+Enable the heap allocator for guests that:
+- Process variable-length data
+- Use collections (Vec, HashMap, etc.)
+- Perform string operations
+- Run iterative algorithms
+
+```toml
+[dependencies]
+risc0-zkvm = { version = "1.2", default-features = false, features = ["std", "heap-embedded-alloc"] }
+```
+
+*Note: The heap allocator adds ~5% cycle overhead but prevents memory exhaustion.*
+
+### Common Guest Patterns
+
+**Reading Input:**
+```rust
+// For raw bytes (most efficient, works with pyr0.prove(image, raw_bytes))
+use std::io::Read;
+let mut buffer = Vec::new();
+env::stdin().read_to_end(&mut buffer).unwrap();
+
+// For serialized data (when using PyR0 serialization helpers)
+let data: MyStruct = env::read();
+```
+
+**Writing to Journal:**
+```rust
+// Simple values
+env::commit(&my_u32);
+
+// Complex structures (using Borsh)
+use borsh::BorshSerialize;
+let output = MyOutput { /* ... */ };
+env::commit_slice(&borsh::to_vec(&output).unwrap());
+```
+
 ## Installation
 
 ### System Requirements

demo/ed25519_demo.py

@@ -142,7 +142,7 @@
 print(f"✓ Program ID verified: {receipt_program_id[:16]}...{receipt_program_id[-16:]}")
 
 # Verify the cryptographic proof
-receipt.verify()
+receipt.verify(image.id)  # Pass the trusted image ID
 print("✓ Proof verified")
 
 # Test with invalid signature
@@ -152,7 +152,7 @@
 input_data = serialization.ed25519_input(pk_bytes, sig_bytes, msg_bytes)
 
 # For the second test, we just execute, no need for proof
-segments, info = pyr0.execute_with_input(image, input_data)
+info = pyr0.dry_run(image, input_data)
 journal = info.journal
 
 print(f"Journal: {len(journal)} bytes")
@@ -167,13 +167,20 @@
 
 import struct
 result = struct.unpack('<I', journal[16:20])[0]
+test_passed = False
 if result == 0:
     print("✅ Signature INVALID - Test PASSED")
+    test_passed = True
 elif result == 1:
     print("❌ Signature reported as VALID - Test FAILED")
 else:
     print(f"❌ Unexpected result: {result}")
 
 print("\n=== Summary ===")
-print("If both tests passed, the zkVM correctly validates Ed25519 signatures!")
-print("These are real cryptographic proofs in production mode.")
+if test_passed:
+    print("✓ Both tests passed! The zkVM correctly validates Ed25519 signatures!")
+    print("These are real cryptographic proofs in production mode.")
+    sys.exit(0)
+else:
+    print("✗ Some tests failed")
+    sys.exit(1)

demo/merkle_demo.py

@@ -6,6 +6,7 @@
 Poseidon hash over BN254, compatible with Noir/Barretenberg ZK circuits.
 """
 
+import sys
 import merkle_py
 
 def test_basic_operations():
@@ -144,19 +145,26 @@ def main():
     print("\nThis test suite demonstrates a sparse Merkle tree implementation")
     print("compatible with zero-knowledge proof circuits (Noir/Barretenberg).")
 
-    tree = test_basic_operations()
-    test_poseidon_hash()
-    test_batch_operations()
-    
-    print("\n" + "╔" + "=" * 58 + "╗")
-    print("║" + " " * 20 + "ALL TESTS PASSED ✅" + " " * 19 + "║")
-    print("╚" + "=" * 58 + "╝")
-    
-    print("\nThis implementation provides:")
-    print("  • Sparse Merkle tree supporting 2^256 keys")
-    print("  • Poseidon hash function over BN254 field")
-    print("  • 16-level Merkle proofs for ZK circuits")
-    print("  • Python interface via PyO3 bindings")
+    try:
+        tree = test_basic_operations()
+        test_poseidon_hash()
+        test_batch_operations()
+        
+        print("\n" + "╔" + "=" * 58 + "╗")
+        print("║" + " " * 20 + "ALL TESTS PASSED ✅" + " " * 19 + "║")
+        print("╚" + "=" * 58 + "╝")
+        
+        print("\nThis implementation provides:")
+        print("  • Sparse Merkle tree supporting 2^256 keys")
+        print("  • Poseidon hash function over BN254 field")
+        print("  • 16-level Merkle proofs for ZK circuits")
+        print("  • Python interface via PyO3 bindings")
+        return 0
+    except Exception as e:
+        print(f"\n✗ Test failed: {e}")
+        import traceback
+        traceback.print_exc()
+        return 1
 
 if __name__ == "__main__":
-    main()
+    sys.exit(main())