Converge Core

A correctness-first, context-driven multi-agent runtime.

Converge is an Agent OS where:

• Context is the API
• Agents collaborate through data, not calls
• Execution proceeds until a fixed point
• Convergence is explicit and observable

Quick Start

use converge_core::{Engine, Context, ContextKey};
use converge_core::agents::{SeedAgent, ReactOnceAgent};

// Create engine and register agents
let mut engine = Engine::new();
engine.register(SeedAgent::new("seed-1", "initial data"));
engine.register(ReactOnceAgent::new("hyp-1", "derived insight"));

// Run until convergence
let result = engine.run(Context::new()).expect("should converge");

// Inspect results
assert!(result.converged);
assert!(result.context.has(ContextKey::Seeds));
assert!(result.context.has(ContextKey::Hypotheses));
println!("Converged in {} cycles", result.cycles);

Core Concepts

• Context: The shared, typed, evolving state of a job
• Agent: A capability that reads context and emits effects
• AgentEffect: Buffered output (facts) from an agent
• Engine: The convergence loop that coordinates agents

Guarantees

• Determinism: Same input → same output
• Termination: Budgets prevent infinite loops
• Isolation: Agents never call each other
• Auditability: All changes are traceable

Design Tenets

These are the nine non-negotiable axioms that converge-core exists to encode, enforce, and protect. Every type, trait, and pattern in this crate serves one or more of these tenets.

1. Explicit Authority

Axiom: No defaults that grant authority. Authority is always explicit, typed, and traceable.

Why: Implicit permissions lead to security drift and unauditable systems.

In code: AuthorityGrant and AuthorityScope require explicit construction. The pub(crate) constructors on AuthorityGrant prevent external code from forging authority. See also PromotionRecord which traces approvers.

2. Convergence Over Control Flow

Axiom: We converge on outcomes via governed proposals, not ad-hoc loops or hidden heuristics.

Why: Control flow hides decisions; convergence makes them observable.

In code: The Engine runs agents repeatedly until a fixed point is reached. StopReason exhaustively enumerates why execution halted. No hidden loops.

3. Append-Only Truth

Axiom: Facts are never mutated. Corrections are new facts.

Why: Mutable state hides history and prevents audit replay.

In code: TypesFact has private fields with no &mut methods. CorrectionEvent creates new correction facts rather than mutating existing ones. The Context accumulates facts without overwriting.

4. Agents Suggest, Engine Decides

Axiom: Agents emit proposals; promotion requires validation gates (and sometimes humans).

Why: Separates suggestion from decision, enabling governance and audit.

In code: PromotionGate is the ONLY path to create Facts. Agents produce Proposal in the Draft state which must go through ValidationReport before becoming Validated and finally TypesFact.

5. Safety by Construction

Axiom: Make invalid states unrepresentable. Prefer types over conventions.

Why: Runtime checks can be bypassed; type-level guarantees cannot.

In code: The type-state pattern on Proposal (Draft vs Validated) makes it impossible to promote an unvalidated proposal. Newtype IDs like FactId, ProposalId, and ObservationId prevent mixing.

6. Transparent Determinism

Axiom: The system tells the truth about replayability and determinism.

Why: Hidden non-determinism corrupts audit trails and reproducibility.

In code: TypesTraceLink distinguishes LocalTrace (replay-eligible) from RemoteRef (audit-only). Replayability explicitly marks whether operations can be replayed deterministically.

7. Human Authority First-Class

Axiom: Explicit pause/approve gates for consequential actions.

Why: AI systems must preserve human oversight for high-stakes decisions.

In code: Actor and ActorKind distinguish human from automated approvers. PromotionRecord records who approved each fact. The ValidationPolicy can require human approval.

8. No Hidden Work

Axiom: No silent background effects, retries, implicit state changes, or shadow decisioning.

Why: Hidden work makes systems unpredictable and unauditable.

In code: AgentEffect explicitly captures all agent output. The Engine budget system (CycleBudget, FactBudget, TokenBudget) makes resource consumption visible. StopReason explains exactly why execution ended.

9. Scale by Intent Replication

Axiom: Scale by replicating intent and invariants across domains.

Why: Scaling should preserve governance, not bypass it.

In code: RootIntent and Frame capture intent as data. Invariant enforces governance rules. These types can be serialized and replicated across distributed systems while preserving their constraints.

Purity Declaration

converge-core is the constitutional foundation for Converge. It must remain pure: no I/O, no runtime behavior, no implementation logic. Only types, traits, and promotion gates.

Allowed Dependencies

Forbidden Dependencies

The Purity Rule

If a module implies execution, I/O, network, model inference, or persistence, it does not belong in converge-core.

Capability crates (e.g., converge-runtime, converge-llm, converge-provider) implement the traits defined here using the forbidden dependencies.

See deny.toml at the crate root for CI enforcement of these rules.