converge-core 1.0.0

Converge Agent OS - correctness-first, context-driven multi-agent runtime
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

# Migration Guide: converge-core v2.0.0

This document describes breaking changes in converge-core v2.0.0 and how to migrate.

## Overview

converge-core v2.0.0 removes all runtime dependencies (rayon, rand, sha2, hex) to achieve
a pure, portable core. Functionality that required these dependencies is now provided
through capability traits that external crates implement.

## Breaking Changes

### 1. Parallel Execution Removed

**What changed:** `Engine::execute_agents` no longer uses Rayon for parallel execution.

**Why:** Rayon is a runtime dependency that violates converge-core's purity principles.
The core library should be portable across all environments including WASM.

**Migration:**

Before (v1.x):
- Agents executed in parallel automatically via Rayon

After (v2.0.0):
- Agents execute sequentially by default
- For parallel execution, use `converge-runtime` with an `Executor` implementation

```rust
// v2.0.0: Use converge-runtime for parallel execution
use converge_runtime::ParallelExecutor;

let executor = ParallelExecutor::new();
let engine = Engine::with_executor(executor);  // Future API
```

### 2. Cryptographic Hashing Changed

**What changed:** `ContentHash::compute` no longer uses SHA-256.

**Why:** sha2 is a runtime dependency. Cryptographic hashing should be configurable.

**Migration:**

Before (v1.x):
- `ContentHash::compute("data")` returned SHA-256 hash

After (v2.0.0):
- `ContentHash::compute("data")` returns a non-cryptographic hash (FNV-1a)
- For cryptographic hashing, use `converge-runtime` with a `Fingerprint` implementation

```rust
// v2.0.0: Use converge-runtime for SHA-256
use converge_runtime::{Sha256Fingerprint, Fingerprint};

let fingerprint = Sha256Fingerprint::new();
let hash = fingerprint.compute(data.as_bytes());
```

### 3. Random ID Generation Changed

**What changed:** `IntentId::generate()` no longer uses cryptographic randomness.

**Why:** rand is a runtime dependency that may not be available in all environments.

**Migration:**

Before (v1.x):
- `IntentId::generate()` used `rand::random()` for uniqueness

After (v2.0.0):
- `IntentId::generate()` uses timestamp + process ID + counter
- For cryptographic randomness, use `converge-runtime` with a `Randomness` implementation

```rust
// v2.0.0: Use converge-runtime for random IDs
use converge_runtime::{SystemRandomness, Randomness};

let rng = SystemRandomness::new();
let random_bytes = rng.random_u32();
let id = IntentId::new(format!("intent-{random_bytes:08x}"));
```

### 4. Hex Encoding API Changed

**What changed:** `ContentHash::from_hex` returns `ContentHashError` instead of `hex::FromHexError`.

**Migration:**

```rust
// Before (v1.x)
let hash = ContentHash::from_hex(s)?;  // Returns hex::FromHexError

// After (v2.0.0)
let hash = ContentHash::from_hex(s)?;  // Returns ContentHashError
```

## Capability Traits

converge-core v2.0.0 introduces capability boundary traits in `converge_core::traits`:

| Trait | Replaces | Purpose |
|-------|----------|---------|
| `Executor` | rayon | Parallel execution |
| `Fingerprint` | sha2/hex | Cryptographic hashing |
| `Randomness` | rand | Random number generation |

These traits are defined in converge-core but implemented in converge-runtime.

## Deprecation Warnings

Methods using the legacy stub implementations are marked `#[deprecated]`:

- `Engine::execute_agents` - Use Executor trait
- `ContentHash::compute` - Use Fingerprint trait
- `ContentHash::compute_fact` - Use Fingerprint trait
- `ContentHash::combine` - Use Fingerprint trait
- `IntentId::generate` - Use Randomness trait

To suppress warnings while migrating:

```rust
#[allow(deprecated)]
let id = IntentId::generate();
```

## Timeline

- **v2.0.0**: Deprecated methods available, stub implementations work
- **v3.0.0** (future): Deprecated methods removed, trait implementations required

## Getting Help

- See `PURITY.md` for the full list of allowed/forbidden dependencies
- See `BOUNDARY.md` (Phase 5) for trait ownership documentation
- File issues at https://github.com/kpernyer/converge-core/issues