northroot-proof-engine 0.3.2

# Northroot Proof Engine

Core proof computation and validation library for the Northroot Proof system.

## Overview

The Northroot Proof Engine provides foundational cryptographic and validation primitives for the modular proof architecture:

- **PoSH (Proof of Shape)**: Method transformation contracts
- **PoX (Proof of Execution)**: Run evidence and commitments

## Features

- Deterministic JSON canonicalization
- SHA-256 hash computation
- ed25519 signature handling
- Input validation functions
- Data shape hashing
- OTEL ID validation (legacy compatibility)

## Usage

Add to your `Cargo.toml`:

```toml
[dependencies]
northroot-proof-engine = "0.3.0"
```

### Quick Start

```rust
use northroot_proof_engine::{compute_sha256, validate_trace_id};

// Compute SHA-256 hash
let hash = compute_sha256("Hello, world!");
println!("Hash: {}", hash);

// Validate trace ID
match validate_trace_id("tr_01H1234567890") {
    Ok(_) => println!("Valid trace ID"),
    Err(e) => println!("Invalid: {}", e),
}
```

### CLI Demo Tool

The engine includes a CLI tool for demonstrations and validation:

```bash
# Run end-to-end workflow demo
cargo run --bin northroot-cli -- demo workflow

# Benchmark hash operations
cargo run --bin northroot-cli -- bench hash

# Validate a proof JSON file
cargo run --bin northroot-cli -- validate tests/golden/pox_span_commitment.json
```

See [CLI Guide](docs/CLI_GUIDE.md) for more details.

### Example: Creating and Verifying a Span Commitment

```rust
use northroot_proof_engine::{
    compute_span_commitment_hash, sign_span_commitment, verify_span_commitment_signature,
    ArtifactRef, MethodRef, SpanCommitment, SpanStatus,
};
use ed25519_dalek::SigningKey;
use rand::rngs::OsRng;

// Create a span commitment
let commitment = SpanCommitment {
    schema_version: "proof.v2".to_string(),
    trace_id: "tr_01H1234567890".to_string(),
    span_id: "sp-0001".to_string(),
    method_ref: MethodRef { /* ... */ },
    data_shape_hash: "sha256:...".to_string(),
    span_shape_hash: "sha256:...".to_string(),
    inputs: vec![],
    outputs: vec![],
    start_time: "2025-11-06T12:00:00.000Z".to_string(),
    end_time: "2025-11-06T12:00:00.042Z".to_string(),
    status: SpanStatus::OK,
    meta: None,
};

// Sign the commitment
let mut csprng = OsRng;
let signing_key = SigningKey::generate(&mut csprng);
let signature = sign_span_commitment(&commitment, &signing_key, "did:key:zExecutor".to_string())?;

// Verify the signature
let verifying_key = signing_key.verifying_key();
let verified = verify_span_commitment_signature(
    &commitment,
    &signature,
    verifying_key.as_bytes(),
)?;
```

## Performance

The engine is optimized for deterministic, fast hash computation and canonicalization. Typical performance characteristics:

- **SHA-256**: ~100K+ ops/sec (1KB input)
- **Canonicalization**: ~50K+ ops/sec
- **Span Commitment Hash**: ~30K+ ops/sec

Run benchmarks with:
```bash
cargo bench
```

Or use the CLI for quick performance testing:
```bash
cargo run --bin northroot-cli -- bench hash
```

See [Benchmarks](docs/BENCHMARKS.md) for detailed performance data.

## CLI Reference

The `northroot-cli` tool provides several commands:

- `demo workflow` - Demonstrates end-to-end PoSH → PoX workflow
- `bench hash` - Benchmarks hash and canonicalization operations
- `validate <file>` - Validates proof JSON files

See [CLI Guide](docs/CLI_GUIDE.md) for complete documentation.

## Documentation

- [5W1H Executive Guide](docs/5W1H_EXEC_GUIDE.md) - Mathematical foundation and proof architecture
- [PoSH Mini Spec](docs/specs/PoSH_MINI_SPEC.md) - Proof of Shape specification
- [PoX Mini Spec](docs/specs/PoX_MINI_SPEC.md) - Proof of Execution specification
- [Recommended Types](docs/reccomended_types.md) - Type recommendations for v0.2
- [CLI Guide](docs/CLI_GUIDE.md) - Command-line tool usage
- [Benchmarks](docs/BENCHMARKS.md) - Performance characteristics and benchmarks

**Current:** v0.3.0

This version includes CLI tool, enhanced testing, and improved documentation. Breaking changes will require a major version bump.

## Development

### Setup

```bash
# Install git hooks (run once)
./scripts/setup-hooks.sh
```

### Pre-commit Checks

Automatically runs on commit:
- Code formatting check (`cargo fmt`)

### Pre-push Checks

Automatically runs before push:
- Clippy linting (`cargo clippy`)
- Full test suite (`cargo test`)
- Release build verification (`cargo build --release`)

### Releasing

1. Update `CHANGELOG.md` with changes
2. Run the release script:
   ```bash
   ./scripts/release.sh <version>
   # Example: ./scripts/release.sh 0.2.1
   ```
3. Push the commit and tag:
   ```bash
   git push origin main
   git push origin v<version>
   ```

GitHub Actions will automatically:
- Run full CI checks
- Publish to crates.io
- Create a GitHub release

**Note:** You'll need to set the `CRATES_IO_TOKEN` secret in GitHub repository settings.

## License

MIT License - see LICENSE file for details.