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::{Context, 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(Context::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
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 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 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;

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

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

pub use types::ArtifactId;

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

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

pub use types::Frame;

pub use types::FrameConstraint;

pub use types::FrameId;

pub use types::GateId;

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

pub use types::ObservationKind;

pub use types::ObservationProvenance;

pub use types::PromotionError;

pub use types::PromotionRecord;

pub use types::Proposal;

pub use types::ProposalId;

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

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

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

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.

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.

Budget

Budget limits for execution.

Context

The shared context for a Converge job.

ConvergeResult

Result of a converged execution.

Engine

The Converge execution engine.

EngineHitlPolicy

Engine-level HITL policy for gating proposals.

Fact

A validated, authoritative assertion in the context.

HitlPause

State returned when convergence pauses at a HITL gate.

ProposedFact

An unvalidated suggestion from a non-authoritative source.

SuggestorId

Unique identifier for a registered suggestor.

TypesRunHooks

Per-run hooks for typed intent execution.

ValidationError

Error when a ProposedFact fails validation.

Enums

ContextKey

Typed keys for the shared context namespace.

ConvergeError

Top-level error type for Converge operations.

RunResult

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

Traits

ContextView

Re-export the Context trait from converge-pack. Suggestor and Invariant implementations use &dyn ContextView in their signatures. Read-only view of the shared context.

ExperienceEventObserver

Run-scoped observer for experience events emitted during convergence.

StreamingCallback

Callback trait for streaming fact emissions during convergence.

Suggestor

The core suggestor contract.