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

Forbidden Dependencies

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.