Struct Engine 

pub struct Engine { /* private fields */ }

The Converge execution engine.

Owns suggestor registration, dependency indexing, and the convergence loop.

Implementations

impl Engine

pub fn new() -> Self

Creates a new engine with default budget.

pub fn with_budget(budget: Budget) -> Self

Creates a new engine with custom budget.

pub fn set_budget(&mut self, budget: Budget)

Sets the execution budget.

pub fn set_streaming(&mut self, callback: Arc<dyn StreamingCallback>)

Sets a streaming callback for real-time fact emission.

When set, the callback will be invoked:

• At the start of each convergence cycle
• When each fact is added to the context
• At the end of each convergence cycle

Example

use std::sync::Arc;
use converge_core::{Engine, StreamingCallback, Fact};

struct MyCallback;
impl StreamingCallback for MyCallback {
    fn on_cycle_start(&self, cycle: u32) {
        println!("[cycle:{}] started", cycle);
    }
    fn on_fact(&self, cycle: u32, fact: &Fact) {
        println!("[cycle:{}] fact:{} | {:?}", cycle, fact.id(), fact.text());
    }
    fn on_cycle_end(&self, cycle: u32, facts_added: usize) {
        println!("[cycle:{}] ended with {} facts", cycle, facts_added);
    }
}

let mut engine = Engine::new();
engine.set_streaming(Arc::new(MyCallback));

pub fn set_event_observer(&mut self, observer: Arc<dyn ExperienceEventObserver>)

Sets the event observer for audit trail capture.

When set, the engine emits ExperienceEvents during convergence: FactPromoted, OutcomeRecorded, BudgetExceeded, and HITL gate decisions.

pub fn clear_streaming(&mut self)

Clears the streaming callback.

pub fn set_hitl_policy(&mut self, policy: EngineHitlPolicy)

Sets the HITL policy for gating proposals.

When set, proposals matching the policy will pause convergence instead of auto-promoting. Use run_with_hitl() to get a RunResult that can represent the paused state.

pub fn clear_hitl_policy(&mut self)

Clears the HITL policy.

pub async fn run_with_hitl(&mut self, context: ContextState) -> RunResult

Runs the convergence loop with HITL gate support.

Like run(), but returns RunResult which can represent either completion or a HITL pause. When paused, call resume() with the human’s decision to continue.

pub async fn resume( &mut self, pause: HitlPause, decision: GateDecision, ) -> RunResult

Resumes convergence after a HITL gate decision.

Takes the HitlPause state returned from run_with_hitl() and the human’s GateDecision, then continues the convergence loop.

On approval: the paused proposal is promoted and convergence continues. On rejection: the proposal is discarded and convergence continues without it (may still converge on remaining facts).

pub fn register_invariant( &mut self, invariant: impl Invariant + 'static, ) -> InvariantId

Registers an invariant (compiled Gherkin predicate).

Invariants are checked at different points depending on their class:

• Structural: after every merge
• Semantic: at end of each cycle
• Acceptance: when convergence is claimed

pub fn register_suggestor( &mut self, suggestor: impl Suggestor + 'static, ) -> SuggestorId

Registers a suggestor and returns its ID.

Suggestors are assigned monotonically increasing IDs. The dependency index is updated incrementally.

pub fn register_suggestor_in_pack( &mut self, pack_id: impl Into<PackId>, suggestor: impl Suggestor + 'static, ) -> SuggestorId

Registers a suggestor as part of a named pack.

Pack ownership is used by run_with_types_intent and set_active_packs to constrain which suggestors may participate in a run.

pub fn suggestor_count(&self) -> usize

Returns the number of registered suggestors.

pub fn set_active_packs<I, S>(&mut self, pack_ids: I)

where I: IntoIterator<Item = S>, S: Into<PackId>,

Restrict future runs to the provided pack IDs.

pub fn clear_active_packs(&mut self)

Remove any active pack restriction.

pub async fn run_with_types_intent( &mut self, context: ContextState, intent: &TypesRootIntent, ) -> Result<ConvergeResult, ConvergeError>

Run the engine with budgets and active packs derived from a typed intent.

pub async fn run_with_types_intent_and_hooks( &mut self, context: ContextState, intent: &TypesRootIntent, hooks: TypesRunHooks, ) -> Result<ConvergeResult, ConvergeError>

Run the engine with a typed intent plus run-scoped observers/evaluators.

pub async fn run( &mut self, context: ContextState, ) -> Result<ConvergeResult, ConvergeError>

Runs the convergence loop until fixed point or budget exhaustion.

Algorithm

initialize context
mark all keys as dirty (first cycle)

repeat:
  clear dirty flags
  find eligible suggestors (dirty deps + accepts)
  execute eligible suggestors (parallel read)
  merge effects (serial, deterministic order)
  track which keys changed
until no keys changed OR budget exhausted

Errors

Returns ConvergeError::BudgetExhausted if:

• max_cycles is exceeded
• max_facts is exceeded

Trait Implementations

impl Default for Engine

fn default() -> Self

Returns the “default value” for a type.