web4-core 0.1.0__tar.gz

web4_core-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Rust build artifacts
+/target/
+/python/target/
+
+# Cargo lock is typically committed for libraries, but not for applications
+# For a library, we keep Cargo.lock
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.whl
+.eggs/

web4_core-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,87 @@
+# Web4-Core Architecture Decision: Rust + Python Bindings
+
+## Why Rust?
+
+### The Problem with Pure Python
+
+The original Web4 implementation was Python-first. While Python excels at prototyping and AI/ML integration, it creates fundamental problems for trust infrastructure:
+
+1. **No Memory Safety Guarantees**: Trust computations must be deterministic and tamper-resistant. Python's dynamic nature makes formal verification impractical.
+
+2. **Performance Ceiling**: Cryptographic operations (hashing, signing, verification) in Python are 10-100x slower than native code. At scale, this becomes prohibitive.
+
+3. **Deployment Complexity**: Python's dependency management (pip, virtualenv, conda) creates reproducibility issues. "Works on my machine" is unacceptable for trust infrastructure.
+
+4. **Hardware Binding Impossible**: TPM 2.0, Secure Enclave, and FIDO2 require FFI to native libraries. Python's ctypes/cffi add unnecessary indirection and attack surface.
+
+### Why Not Pure Rust?
+
+Pure Rust would sacrifice the ecosystem advantages that make Web4 practical:
+
+1. **AI Integration**: The AI agent ecosystem lives in Python (LangChain, transformers, Claude SDK). Forcing Rust adoption creates friction.
+
+2. **Rapid Iteration**: Research and prototyping benefit from Python's REPL and dynamic typing. We need both rigor and velocity.
+
+3. **Adoption Curve**: Most developers know Python. Rust has a steep learning curve. Bindings let teams choose their comfort level.
+
+## The Hybrid Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Python Applications                   │
+│         (AI Agents, CLI Tools, Web Services)            │
+├─────────────────────────────────────────────────────────┤
+│                    PyO3 Bindings                         │
+│              (Zero-copy where possible)                  │
+├─────────────────────────────────────────────────────────┤
+│                    Rust Core                             │
+│     LCT │ T3 Trust │ V3 Provenance │ Coherence │ Crypto │
+├─────────────────────────────────────────────────────────┤
+│                 Platform Abstraction                     │
+│         TPM 2.0 │ Secure Enclave │ FIDO2 │ Software     │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Benefits Realized
+
+1. **Single Source of Truth**: Core logic lives in Rust. Python bindings are generated, not maintained separately.
+
+2. **Type Safety Propagates**: Rust's type system catches errors at compile time. PyO3 generates typed stubs for Python IDE support.
+
+3. **Performance Where It Matters**: Hot paths (hashing, tensor computation, chain verification) run at native speed.
+
+4. **Hardware Binding Ready**: Rust's FFI story is mature. We can bind to tpm2-tss, Security.framework, and libfido2 directly.
+
+5. **Cross-Platform**: One Rust codebase compiles to Linux, macOS, Windows. Python wheels hide platform complexity.
+
+## Module Mapping
+
+| Rust Module | Python Binding | Purpose |
+|-------------|----------------|---------|
+| `lct.rs` | `web4.lct` | Linked Context Token identity |
+| `t3.rs` | `web4.t3` | Trust tensor computation |
+| `v3.rs` | `web4.v3` | Verifiable provenance |
+| `coherence.rs` | `web4.coherence` | Identity stability metrics |
+| `crypto.rs` | `web4.crypto` | Cryptographic primitives |
+
+## What Stays in Python
+
+- CLI tools and scripts
+- AI agent integration layers
+- Web service endpoints
+- Test harnesses and fixtures
+- Documentation generation
+
+## Migration Path
+
+1. **Phase 1** (Complete): Core modules ported to Rust, Python bindings via PyO3
+2. **Phase 2** (Current): Hardbound enterprise layer in Rust
+3. **Phase 3** (Next): Hardware binding implementation
+4. **Phase 4** (Future): WASM compilation for browser/edge deployment
+
+## Lessons Learned
+
+- Start with types, not functions. Getting the data structures right in Rust first made everything else easier.
+- PyO3's `#[pyclass]` and `#[pymethods]` are straightforward but require thinking about ownership.
+- Rust's borrow checker forced us to clarify mutable vs immutable operations that were ambiguous in Python.
+- Integration tests should run through Python bindings, not just Rust unit tests.