converge-core 1.0.0

# converge-core Purity Contract

## Overview

**converge-core is pure.** This means:

- **No I/O**: No file system access, no network calls, no database connections
- **No Runtime**: No async executors, no parallelism, no background tasks
- **No Implementation Logic**: Only types, traits, and promotion gates

### Why Purity Matters

1. **Portability**: Pure code compiles anywhere - WebAssembly, embedded, native
2. **Testability**: Pure functions are deterministic and easy to test
3. **Stability**: No external runtime dependencies that can break or change
4. **Composability**: Pure interfaces allow capability crates to provide their own implementations

### How This Works

This document is the **human-readable contract**. The machine-enforced policy lives in [`deny.toml`](./deny.toml), which is checked by `cargo deny` in CI. Together, they ensure converge-core stays pure.

---

## ALLOWED Dependencies

These dependencies are permitted in converge-core because they don't violate purity:

| Crate | Version | Purpose | Justification |
|-------|---------|---------|---------------|
| thiserror | 2 | Error type derivation | Zero-cost, compile-time only - generates `Error` trait implementations |
| serde | 1 | Serialization traits | Trait-only, no I/O - defines `Serialize`/`Deserialize` interfaces |
| serde_json | 1 | JSON serialization | Required for stable wire format, pure transformation |
| tracing | 0.1 | Logging facade | Facade only - no subscriber included, just trait definitions |
| strum | 0.26 | Enum derives | Compile-time only - generates `Display`, `FromStr`, iterators |

**Criteria for ALLOWED status:**
- Must be compile-time only OR pure transformation
- Must not require async runtime
- Must not perform I/O
- Must not imply parallelism or background execution

---

## FORBIDDEN Dependencies

These dependencies MUST NOT appear in converge-core. Each violates one or more purity constraints.

### Async Runtimes

| Crate | Reason | Alternative |
|-------|--------|-------------|
| tokio | Async runtime violates I/O-free purity | Define sync traits, implement async in converge-runtime |
| async-std | Async runtime violates I/O-free purity | Define sync traits, implement async in converge-runtime |
| async-trait | Async macro implies async runtime dependency | Define sync traits, implement async versions in runtime crates |

### HTTP/Network

| Crate | Reason | Alternative |
|-------|--------|-------------|
| reqwest | HTTP client violates I/O-free constraint | converge-runtime |
| hyper | HTTP library violates I/O-free constraint | converge-runtime |
| axum | HTTP server violates I/O-free constraint | converge-runtime |

### gRPC

| Crate | Reason | Alternative |
|-------|--------|-------------|
| tonic | gRPC runtime violates purity | converge-runtime |
| prost | protobuf codegen violates purity | converge-runtime |

### Parallelism

| Crate | Reason | Alternative |
|-------|--------|-------------|
| rayon | Parallelism is runtime concern, not core logic | converge-runtime |

### Randomness

| Crate | Reason | Alternative |
|-------|--------|-------------|
| rand | Randomness violates determinism constraint | Trait abstraction or dev-dependencies only |
| rand_core | Randomness violates determinism constraint | Trait abstraction |

### Hashing

| Crate | Reason | Alternative |
|-------|--------|-------------|
| sha2 | Hashing is implementation detail | Fingerprint trait abstraction |
| hex | Encoding for sha2, remove together | Remove with sha2 |

### ML/Data Processing

| Crate | Reason | Alternative |
|-------|--------|-------------|
| burn | ML runtime violates purity | converge-analytics |
| polars | Data processing runtime violates purity | converge-analytics |
| ndarray | Numerical computing implies runtime execution | converge-analytics |

---

## The Nine Design Tenets

Purity supports these non-negotiable design tenets:

1. **Explicit Authority** - No defaults that grant authority
2. **Convergence Over Control Flow** - Governed proposals, not ad-hoc loops
3. **Append-Only Truth** - Facts are never mutated
4. **Agents Suggest, Engine Decides** - Proposals require validation gates
5. **Safety by Construction** - Invalid states are unrepresentable
6. **Transparent Determinism** - The system tells the truth about replayability
7. **Human Authority First-Class** - Explicit pause/approve gates
8. **No Hidden Work** - No silent background effects
9. **Scale by Intent Replication** - Scale via intent and invariants

By keeping converge-core pure, we ensure these tenets can be enforced by the type system rather than convention.

---

## Enforcement

### Automated Checks

- **`cargo deny check`** runs in CI on every PR
- **Configuration**: [`deny.toml`](./deny.toml) defines the forbidden dependency list
- **Blocking**: PRs that add forbidden dependencies are blocked from merging
- **Scope**: Checks both direct and transitive dependencies

### Local Verification

```bash
# Install cargo-deny
cargo install --locked cargo-deny

# Run purity check
cargo deny check bans licenses sources
```

### CI Integration

The GitHub Actions workflow (`.github/workflows/ci.yml`) runs cargo-deny automatically:

```yaml
- name: Check dependency policy
  uses: EmbarkStudios/cargo-deny-action@v2
  with:
    command: check bans licenses sources
    manifest-path: converge-platform/converge-core/Cargo.toml
```

---

## Exception Process

### Can I Add a Forbidden Dependency?

**No.** Forbidden dependencies are forbidden for architectural reasons, not convenience.

If you need functionality from a forbidden dependency:

1. **Define a trait** in converge-core that describes the capability
2. **Implement the trait** in the appropriate capability crate
3. **Inject the implementation** at runtime

### What If I Really Need an Exception?

If you believe there is a legitimate case for an exception:

1. **Open an RFC** explaining:
   - What dependency you need
   - Why no alternative exists
   - What purity guarantees you can preserve
   - How this affects portability

2. **Review process**:
   - Core maintainer review required
   - Architecture impact assessment
   - Documentation of exception and constraints

3. **If approved**:
   - Add to `deny.toml` with `skip` or `allow` entry
   - Document in this file under a new "Exceptions" section
   - Include sunset date if temporary

### Current Exceptions

None. converge-core has no exceptions to the purity policy.

---

## Version History

| Version | Date | Changes |
|---------|------|---------|
| 1.0 | 2026-01-23 | Initial purity contract established |