Crate converge_core 

Converge Core

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

Converge is a Suggestor OS where:

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

Quick Start

use converge_core::{ContextState, ContextKey, Engine};
use converge_core::suggestors::{ReactOnceSuggestor, SeedSuggestor};

// Create engine and register suggestors
let mut engine = Engine::new();
engine.register_suggestor(SeedSuggestor::new("seed-1", "initial data"));
engine.register_suggestor(ReactOnceSuggestor::new("hyp-1", "derived insight"));

// Run until convergence (async)
let result = engine.run(ContextState::new()).await.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
• Suggestor: A capability that reads context and emits effects
• AgentEffect: Buffered proposal output from a suggestor
• Engine: The convergence loop that coordinates suggestors

Guarantees

• Determinism: Same input → same output
• Termination: Budgets prevent infinite loops
• Isolation: Suggestors 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 suggestors 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. Suggestors Suggest, Engine Decides

Axiom: Suggestors 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. Suggestors 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 suggestor 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 in the architectural sense: no I/O, no persistence, no hidden background work, and no runtime ownership. Core coordination logic such as the engine and promotion gates belongs here; adapters and transport/runtime wiring do not.

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 runtime ownership

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
manifold	Database/object-store adapters	Persistence
postgres	Database	Persistence
rand	Randomness	Non-determinism
rayon	Parallelism	Execution strategy

The Purity Rule

If a module implies executor ownership, 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 admission::AdmissionActor;

pub use admission::AdmissionActorKind;

pub use admission::AdmissionContent;

pub use admission::AdmissionError;

pub use admission::AdmissionReceipt;

pub use admission::AdmissionRequest;

pub use admission::AdmissionSource;

pub use formation::DeliberatedFormation;

pub use formation::Formation;

pub use formation::FormationDecision;

pub use formation::FormationKind;

pub use formation::FormationOutcome;

pub use formation::OpenClawFormation;

pub use formation::ScoredFormation;

pub use formation::ScoringWeights;

pub use formation::StaticFormation;

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::BoundaryKind;

pub use experience_store::BoundaryTarget;

pub use experience_store::BudgetResource;

pub use experience_store::ContractResultSnapshot;

pub use experience_store::CorrectionTarget;

pub use experience_store::EventQuery;

pub use experience_store::ExperienceEvent;

pub use experience_store::ExperienceEventEnvelope;

pub use experience_store::ExperienceEventKind;

pub use experience_store::ExperienceRecord;

pub use experience_store::ExperienceStore;

pub use experience_store::ExperienceStoreError;

pub use experience_store::ExperienceStoreResult;

pub use experience_store::HypothesisOutcome;

pub use experience_store::OverrideTarget;

pub use experience_store::PolicySnapshot;

pub use experience_store::TimeRange;

pub use experience_store::UserExperienceEvent;

pub use experience_store::UserExperienceEventEnvelope;

pub use integrity::IntegrityProof;

pub use integrity::LamportClock;

pub use integrity::MerkleRoot;

pub use integrity::TrackedContext;

pub use invariant::Invariant;

pub use invariant::InvariantClass;

pub use invariant::InvariantError;

pub use invariant::InvariantResult;

pub use invariant::Violation;

pub use prompt::AgentPrompt;

pub use prompt::AgentRole;

pub use prompt::Constraint;

pub use prompt::OutputContract;

pub use prompt::OutputFormat;

pub use prompt::OutputKind;

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::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 truth::CriterionEvaluator;

pub use truth::CriterionOutcome;

pub use truth::CriterionResult;

pub use truth::TruthCatalog;

pub use truth::TruthDefinition;

pub use truth::TruthKind;

pub use types::IntentId;

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::ContextStore;

pub use traits::Executor;

pub use traits::Fingerprint;

pub use traits::FingerprintError;

pub use traits::Randomness;

pub use kernel_boundary::AdapterTrace;

pub use kernel_boundary::ContentKind;

pub use kernel_boundary::ContextFact as KernelContextFact;

pub use kernel_boundary::ContractResult;

pub use kernel_boundary::DataClassification;

pub use kernel_boundary::DecisionStep;

pub use kernel_boundary::ExecutionEnv;

pub use kernel_boundary::KernelContext;

pub use kernel_boundary::KernelIntent;

pub use kernel_boundary::KernelPolicy;

pub use kernel_boundary::KernelProposal;

pub use kernel_boundary::LocalReplayTrace;

pub use kernel_boundary::ProposalKind;

pub use kernel_boundary::ProposedContent;

pub use kernel_boundary::RecallTrace;

pub use kernel_boundary::RemoteReplayTrace;

pub use kernel_boundary::ReplayTrace;

pub use kernel_boundary::Replayability;

pub use kernel_boundary::RiskTier;

pub use kernel_boundary::RoutingPolicy;

pub use kernel_boundary::SamplerParams;

pub use governed_artifact::GovernedArtifactState;

pub use governed_artifact::InvalidStateTransition;

pub use governed_artifact::LifecycleEvent;

pub use governed_artifact::ReplayIntegrityViolation;

pub use governed_artifact::RollbackImpact;

pub use governed_artifact::RollbackRecord;

pub use governed_artifact::RollbackSeverity;

pub use governed_artifact::validate_transition;

pub use backend::BackendAdapterPolicy;

pub use backend::BackendBudgets;

pub use backend::BackendCapability;

pub use backend::BackendContractResult;

pub use backend::BackendError;

pub use backend::BackendPrompt;

pub use backend::BackendRecallPolicy;

pub use backend::BackendRequest;

pub use backend::BackendResponse;

pub use backend::BackendResult;

pub use backend::BackendUsage;

pub use backend::BackoffStrategy;

pub use backend::CircuitBreakerConfig;

pub use backend::CircuitState;

pub use backend::ContractReport;

pub use backend::ContractSpec;

pub use backend::Message;

pub use backend::MessageRole;

pub use backend::RetryPolicy;

pub use types::Actor;

pub use types::ActorKind;

pub use types::CaptureContext;

pub use types::ChosenSide;

pub use types::ConflictType;

pub use types::ConstraintKind;

pub use types::ConstraintSeverity as TypesConstraintSeverity;

pub use types::ContextBuilder;

pub use types::CorrectionError;

pub use types::CorrectionEvent;

pub use types::CorrectionReason;

pub use types::CorrectionScope;

pub use types::Criterion;

pub use types::Draft;

pub use types::EvidenceRef;

pub use types::Fact as TypesFact;

pub use types::FactContent;

pub use types::FactContentKind;

pub use types::Frame;

pub use types::FrameConstraint;

pub use types::FrameId;

pub use types::Hypothesis;

pub use types::IntentId as TypesIntentId;

pub use types::LocalTrace;

pub use types::Observation;

pub use types::ObservationError;

pub use types::ObservationKind;

pub use types::ObservationProvenance;

pub use types::PromotionError;

pub use types::PromotionRecord;

pub use types::Proposal;

pub use types::ProposedContent as TypesProposedContent;

pub use types::ProposedContentKind;

pub use types::ProviderIdentity;

pub use types::RemoteRef;

pub use types::RiskPosture;

pub use types::Tension;

pub use types::TensionId;

pub use types::TensionResolution;

pub use types::TensionSide;

pub use types::TraceLink as TypesTraceLink;

pub use types::TypeError;

pub use types::TypesBudgets;

pub use types::TypesContextKey;

pub use types::TypesContextSnapshot;

pub use types::TypesIntentConstraint;

pub use types::TypesIntentKind;

pub use types::TypesObjective;

pub use types::TypesRootIntent;

pub use types::TypesValidationError;

pub use types::Validated;

pub use types::ValidationSummary;

pub use gates::AllowAllFlowGateAuthorizer;

pub use gates::AuthorityGrant;

pub use gates::AuthorityGrantor;

pub use gates::AuthorityLevel;

pub use gates::AuthorityScope;

pub use gates::CheckResult;

pub use gates::CycleBudget;

pub use gates::ErrorCategory;

pub use gates::ExecutionBudget;

pub use gates::FactBudget;

pub use gates::FlowAction;

pub use gates::FlowGateAuthorizer;

pub use gates::FlowGateContext;

pub use gates::FlowGateDecision;

pub use gates::FlowGateError;

pub use gates::FlowGateInput;

pub use gates::FlowGateOutcome;

pub use gates::FlowGatePrincipal;

pub use gates::FlowGateResource;

pub use gates::FlowPhase;

pub use gates::PromotionGate;

pub use gates::ProposalLifecycle;

pub use gates::RejectAllFlowGateAuthorizer;

pub use gates::SimpleIntent;

pub use gates::StopReason;

pub use gates::TokenBudget;

pub use gates::ValidatedProposal;

pub use gates::ValidationContext;

pub use gates::ValidationError as GatesValidationError;

pub use gates::ValidationPolicy;

pub use gates::ValidationReport;

Modules

admission

Typed admission boundary for external observations.

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

formation

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

model_selection

Transitional re-exports for provider selection vocabulary.

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.

suggestors

Example suggestors for testing and demonstration.

traits

Capability Boundary Traits

truth

Truth catalog primitives.

types

Core type vocabulary for Converge.

validation

LLM and staged-proposal validation for Converge.

Structs

AgentEffect

The output of a suggestor’s execute() call.

AgentRequirements

Requirements for an agent’s LLM usage.

ApprovalId

Unique identifier for a human approval.

ApprovalPointId

Identifier for an approval point or workflow reference.

ArtifactId

Unique identifier for a derived artifact.

BackendId

Identifier for a backend, provider, or adapter.

Budget

Budget limits for execution.

ChainId

Identifier for a convergence chain or run.

ConstraintName

Consumer-owned name for a constraint.

ConstraintValue

Consumer-owned value for a constraint.

ContentHash

Content-addressable hash encoded as 32 raw bytes and serialized as hex.

ContextFact

Read-only projection of a validated assertion in the context.

ContextSnapshot

Durable, verified context snapshot for storage adapters.

ContextState

The shared context for a Converge job.

ConvergeResult

Result of a converged execution.

CorrelationId

Identifier for correlating related events or runs.

CriterionId

Identifier for a success criterion.

Engine

The Converge execution engine.

EngineHitlPolicy

Engine-level HITL policy for gating proposals.

EventId

Identifier for an experience event envelope.

FactId

Unique identifier for a promoted fact.

GateId

Unique identifier for a promotion gate.

HitlPause

State returned when convergence pauses at a HITL gate.

ObservationId

Unique identifier for a raw observation.

PackId

Identifier for a named pack.

PolicyId

Identifier for a policy definition.

ProposalId

Unique identifier for a proposal.

ProposedFact

An unvalidated suggestion from a non-authoritative source.

RequiredCapabilities

Required model capabilities.

SelectionCriteria

Selection criteria using orthogonal dimensions.

SuggestorId

Unique identifier for a registered suggestor.

TenantId

Identifier for a tenant scope.

Timestamp

ISO-8601 timestamp string.

TraceLinkId

Identifier for a stored replay trace link.

TruthId

Identifier for a truth definition.

TypesRunHooks

Per-run hooks for typed intent execution.

UnitInterval

Re-export canonical pack value types used by core public structs. A finite value in the inclusive [0.0, 1.0] range.

ValidationError

Error when a ProposedFact fails validation.

Enums

ComplianceLevel

Compliance level requirements.

ContextKey

Typed keys for the shared context namespace.

ConvergeError

Top-level error type for Converge operations.

CostClass

Cost classification — how expensive is this backend to use?

CostTier

Cost tier preference.

DataSovereignty

Data sovereignty requirements — where can data legally reside?

Jurisdiction

Data jurisdiction requirements.

LatencyClass

Latency class requirements.

RunResult

Result of running the engine — either converged or paused at HITL gate.

TaskComplexity

Task complexity hint.

Traits

Context

Re-export canonical pack value types used by core public structs. Read-only view of the shared context.

ExperienceEventObserver

Run-scoped observer for experience events emitted during convergence.

ModelSelectorTrait

Trait for model selection based on LLM requirements.

StreamingCallback

Callback trait for streaming fact emissions during convergence.

Suggestor

The core suggestor contract.