Crate converge_core 

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

Crate	Purpose	Rationale
thiserror	Error derives	Pure derives, no runtime
tracing	Log macros	Compile-time only when used
serde	Serialization derives	Pure derives, no I/O
serde_json	JSON encoding	Value-only, no I/O
typed-builder	Builder derives	Pure derives
hex	Hex encoding	Pure transforms
Small pure libs	Hashing, encoding	No I/O, no async

Forbidden Dependencies

Crate	Category	Why Forbidden
tokio	Async runtime	Implies execution
reqwest	HTTP client	Network I/O
axum	HTTP server	Network I/O
tonic	gRPC	Network I/O
prost	Protobuf	gRPC dependency
burn	ML runtime	Heavy computation
llama-burn	LLM inference	Model execution
fastembed	Embeddings	Model execution
polars	DataFrames	Heavy computation
arrow	Columnar data	Analytics dependency
lancedb	Vector DB	Persistence
surrealdb	Database	Persistence
postgres	Database	Persistence
rand	Randomness	Non-determinism
rayon	Parallelism	Execution strategy

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.

Re-exports

pub use eval::Eval;

pub use eval::EvalId;

pub use eval::EvalOutcome;

pub use eval::EvalRegistry;

pub use eval::EvalResult;

pub use experience_store::ArtifactKind;

pub use experience_store::ArtifactQuery;

pub use experience_store::ContractResultSnapshot;

pub use experience_store::EventQuery;

pub use experience_store::ExperienceEvent;

pub use experience_store::ExperienceEventEnvelope;

pub use experience_store::ExperienceEventKind;

pub use experience_store::ExperienceStore;Deprecated

pub use experience_store::ExperienceStoreError;

pub use experience_store::ExperienceStoreResult;

pub use experience_store::PolicySnapshot;

pub use experience_store::TimeRange;

pub use invariant::Invariant;

pub use invariant::InvariantClass;

pub use invariant::InvariantError;

pub use invariant::InvariantResult;

pub use invariant::Violation;

pub use model_selection::AgentRequirements;

pub use model_selection::ComplianceLevel;

pub use model_selection::CostClass;

pub use model_selection::CostTier;

pub use model_selection::DataSovereignty;

pub use model_selection::Jurisdiction;

pub use model_selection::LatencyClass;

pub use model_selection::ModelSelectorTrait;

pub use model_selection::RequiredCapabilities;

pub use model_selection::SelectionCriteria;

pub use model_selection::TaskComplexity;

pub use prompt::AgentPrompt;

pub use prompt::AgentRole;

pub use prompt::Constraint;

pub use prompt::OutputContract;

pub use prompt::PromptContext;

pub use prompt::PromptFormat;

pub use root_intent::Budgets;

pub use root_intent::ConstraintSeverity;

pub use root_intent::IntentConstraint;

pub use root_intent::IntentId;

pub use root_intent::IntentKind;

pub use root_intent::IntentValidationError;

pub use root_intent::Objective;

pub use root_intent::RootIntent;

pub use root_intent::Scope;

pub use root_intent::ScopeConstraint;

pub use root_intent::SuccessCriteria;

pub use root_intent::SuccessCriterion;

pub use capability::CapabilityError;

pub use capability::CapabilityErrorKind;

pub use capability::CapabilityKind;

pub use capability::CapabilityMetadata;

pub use capability::EmbedInput;

pub use capability::EmbedRequest;

pub use capability::EmbedResponse;

pub use capability::Embedding;

pub use capability::GraphEdge;

pub use capability::GraphNode;

pub use capability::GraphQuery;

pub use capability::GraphRecall;

pub use capability::GraphResult;

pub use capability::Modality;

pub use capability::RankedItem;

pub use capability::RerankRequest;

pub use capability::RerankResponse;

pub use capability::Reranking;

pub use capability::VectorMatch;

pub use capability::VectorQuery;

pub use capability::VectorRecall;

pub use capability::VectorRecord;

pub use traits::Executor;

pub use traits::Fingerprint;

pub use traits::FingerprintError;

pub use traits::Randomness;

pub use kernel_boundary::KernelIntent;

pub use kernel_boundary::KernelContext;

pub use kernel_boundary::ContextFact;

pub use kernel_boundary::KernelPolicy;

pub use kernel_boundary::DecisionStep;

pub use kernel_boundary::TraceLink;

pub use kernel_boundary::LocalTraceLink;

pub use kernel_boundary::RemoteTraceLink;

pub use kernel_boundary::Replayability;

pub use kernel_boundary::AdapterTrace;

pub use kernel_boundary::SamplerParams;

pub use kernel_boundary::RecallTrace;

pub use kernel_boundary::ExecutionEnv;

pub use kernel_boundary::KernelProposal;

pub use kernel_boundary::ProposalKind;

pub use kernel_boundary::ProposedContent;

pub use kernel_boundary::ContentKind;

pub use kernel_boundary::ContractResult;

pub use kernel_boundary::RiskTier;

pub use kernel_boundary::DataClassification;

pub use kernel_boundary::RoutingPolicy;

pub use governed_artifact::GovernedArtifactState;

pub use governed_artifact::validate_transition;

pub use governed_artifact::InvalidStateTransition;

pub use governed_artifact::LifecycleEvent;

pub use governed_artifact::RollbackSeverity;

pub use governed_artifact::RollbackImpact;

pub use governed_artifact::RollbackRecord;

pub use governed_artifact::ReplayIntegrityViolation;

pub use backend::LlmBackend;Deprecated

pub use backend::BackendError;

pub use backend::BackendResult;

pub use backend::BackendCapability;

pub use backend::BackendRequest;

pub use backend::BackendPrompt;

pub use backend::Message;

pub use backend::MessageRole;

pub use backend::ContractSpec;

pub use backend::BackendBudgets;

pub use backend::BackendRecallPolicy;

pub use backend::BackendAdapterPolicy;

pub use backend::BackendResponse;

pub use backend::ContractReport;

pub use backend::BackendContractResult;

pub use backend::BackendUsage;

pub use backend::RetryPolicy;

pub use backend::BackoffStrategy;

pub use backend::CircuitBreakerConfig;

pub use backend::CircuitState;

pub use types::FactId;

pub use types::ObservationId;

pub use types::ProposalId;

pub use types::GateId;

pub use types::ApprovalId;

pub use types::ArtifactId;

pub use types::ContentHash;

pub use types::Timestamp;

pub use types::Observation;

pub use types::ObservationKind;

pub use types::CaptureContext;

pub use types::ProviderIdentity;

pub use types::Proposal;

pub use types::Draft;

pub use types::Validated;

pub use types::ProposedContent as TypesProposedContent;

pub use types::ProposedContentKind;

pub use types::ObservationProvenance;

pub use types::Fact as TypesFact;

pub use types::FactContent;

pub use types::FactContentKind;

pub use types::PromotionRecord;

pub use types::EvidenceRef;

pub use types::TraceLink as TypesTraceLink;

pub use types::LocalTrace;

pub use types::RemoteRef;

pub use types::Actor;

pub use types::ActorKind;

pub use types::ValidationSummary;

pub use types::FrameId;

pub use types::Frame;

pub use types::FrameConstraint;

pub use types::ConstraintKind;

pub use types::ConstraintSeverity as TypesConstraintSeverity;

pub use types::Criterion;

pub use types::IntentId as TypesIntentId;

pub use types::TensionId;

pub use types::Tension;

pub use types::TensionSide;

pub use types::ConflictType;

pub use types::TensionResolution;

pub use types::ChosenSide;

pub use types::Hypothesis;

pub use types::TypesIntentKind;

pub use types::TypesObjective;

pub use types::RiskPosture;

pub use types::TypesIntentConstraint;

pub use types::TypesBudgets;

pub use types::TypesRootIntent;

pub use types::TypesContextKey;

pub use types::ContextBuilder;

pub use types::TypesContextSnapshot;

pub use types::CorrectionEvent;

pub use types::CorrectionReason;

pub use types::CorrectionScope;

pub use types::TypeError;

pub use types::PromotionError;

pub use types::TypesValidationError;

pub use types::ObservationError;

pub use types::CorrectionError;

pub use gates::ProposalLifecycle;

pub use gates::PromotionGate;

pub use gates::ValidatedProposal;

pub use gates::SimpleIntent;

pub use gates::CheckResult;

pub use gates::ValidationContext;

pub use gates::ValidationError as GatesValidationError;

pub use gates::ValidationPolicy;

pub use gates::ValidationReport;

pub use gates::CycleBudget;

pub use gates::FactBudget;

pub use gates::TokenBudget;

pub use gates::ExecutionBudget;

pub use gates::StopReason;

pub use gates::ErrorCategory;

pub use gates::AuthorityGrant;

pub use gates::AuthorityGrantor;

pub use gates::AuthorityScope;

Modules

agents

Example agents for testing and demonstration.

backend

LLM Backend Interface — The unification boundary for local and remote LLMs.

capability

Capability abstractions for Converge providers.

eval

Eval system for Converge.

experience_store

Experience Store Types — Append-only ledger boundary

gates

Gate Pattern - Enforcing “agents suggest, engine decides”.

governed_artifact

Governed artifact lifecycle management.

integrity

Integrity primitives for Converge.

invariant

Invariant system for Converge.

kernel_boundary

Kernel Boundary Types

llm

LLM provider abstraction for Converge.

model_selection

Model selection based on agent requirements.

prompt

Converge Prompt DSL — Compact machine-to-machine contract format.

recall

Recall Types — Portable across all backends

root_intent

Root Intent — The constitution of a Converge job.

traits

Capability Boundary Traits

types

Core type vocabulary for Converge.

validation

LLM output validation for Converge.

Structs

AgentEffect

The output of an agent’s execution.

AgentId

Unique identifier for a registered agent.

Budget

Budget limits for execution.

Context

The shared context for a Converge job.

ConvergeResult

Result of a converged execution.

Engine

The Converge execution engine.

Fact

A typed assertion added to context.

ProposedFact

A suggested fact from a non-authoritative source (e.g., LLM).

ValidationError

Error when a ProposedFact fails validation.

Enums

ContextKey

A key identifying a category of facts in context.

ConvergeError

Top-level error type for Converge operations.

Traits

Agent

A semantic capability that observes context and emits effects.

StreamingCallback

Callback trait for streaming fact emissions during convergence.