Struct AinlRuntime 

pub struct AinlRuntime { /* private fields */ }

Orchestrates ainl-memory, persona snapshot state, and graph extraction for one agent.

Evolution writes vs ArmaraOS / openfang-runtime

In production ArmaraOS, openfang-runtime’s GraphMemoryWriter::run_persona_evolution_pass is the active writer of the evolution persona row (crate::EVOLUTION_TRAIT_NAME) to each agent’s ainl_memory.db. This struct holds its own GraphExtractorTask and EvolutionEngine. Calling Self::persist_evolution_snapshot or Self::evolve_persona_from_graph_signals concurrently with that pass on the same SQLite store is undefined (competing last-writer wins on the same persona node).

Prefer [Self::with_evolution_writes_enabled(false)] when a host embeds AinlRuntime alongside openfang while openfang remains the sole evolution writer. Self::evolution_engine_mut can still mutate in-memory axis state; calling EvolutionEngine::write_persona_node yourself bypasses this guard and must be avoided in that configuration.

Implementations

impl AinlRuntime

pub async fn run_turn_async( &mut self, input: TurnInput, ) -> Result<TurnOutcome, AinlRuntimeError>

Async single-turn orchestration: graph SQLite I/O is offloaded with spawn_blocking.

The graph remains Arc<std::sync::Mutex<GraphMemory>> (see crate README.md); this method does not switch that inner lock to tokio::sync::Mutex.

Requires the async crate feature and a Tokio runtime (multi-thread recommended).

impl AinlRuntime

pub fn new(config: RuntimeConfig, store: SqliteGraphStore) -> Self

pub fn register_adapter(&mut self, adapter: impl PatchAdapter + 'static)

Register a crate::PatchAdapter keyed by [PatchAdapter::name] (e.g. procedural patch label).

pub fn register_default_patch_adapters(&mut self)

Install the reference GraphPatchAdapter as fallback for procedural patches without a label-specific adapter (see PatchDispatchContext).

pub fn registered_adapters(&self) -> Vec<&str>

Names of currently registered patch adapters.

pub fn with_hooks(self, hooks: impl TurnHooks + 'static) -> Self

pub fn with_hooks_async(self, hooks: Arc<dyn TurnHooksAsync>) -> Self

Install async turn hooks (TurnHooksAsync) for Self::run_turn_async.

pub fn with_evolution_writes_enabled(self, enabled: bool) -> Self

Set whether Self::persist_evolution_snapshot and Self::evolve_persona_from_graph_signals may write the evolution persona row. When false, those methods return Err. Chaining after Self::new is the supported way to disable writes for hosts that delegate evolution persistence elsewhere (see struct-level docs).

pub fn evolution_writes_enabled(&self) -> bool

Current evolution-write mode for this runtime instance.

Hosts embedding AinlRuntime alongside OpenFang should keep this false so only one writer owns the evolution persona row in SQLite.

pub fn sqlite_store(&self) -> SqliteStoreRef<'_>

Borrow the backing SQLite store (same connection as graph memory).

When built with the async feature, this locks the in-runtime graph mutex for the lifetime of the returned guard (see SqliteStoreRef). That mutex is std::sync::Mutex (shared via std::sync::Arc), not tokio::sync::Mutex, so this helper remains usable from Tokio worker threads for quick reads without forcing an async lock API.

pub fn evolution_engine(&self) -> &EvolutionEngine

Borrow the persona EvolutionEngine for this runtime’s agent.

This is the same EvolutionEngine instance held by GraphExtractorTask::evolution_engine. Scheduled GraphExtractorTask::run_pass continues to feed graph + pattern signals into it; hosts may also call EvolutionEngine::ingest_signals, EvolutionEngine::correction_tick, EvolutionEngine::extract_signals, or EvolutionEngine::evolve directly, then Self::persist_evolution_snapshot to write the PersonaSnapshot row (crate::EVOLUTION_TRAIT_NAME).

pub fn evolution_engine_mut(&mut self) -> &mut EvolutionEngine

Mutable access to the persona EvolutionEngine (see Self::evolution_engine).

Direct calls to EvolutionEngine::write_persona_node bypass Self::evolution_writes_enabled.

pub fn apply_evolution_signals(&mut self, signals: Vec<RawSignal>) -> usize

Ingest explicit RawSignals without reading the graph (wrapper for EvolutionEngine::ingest_signals).

pub fn evolution_correction_tick(&mut self, axis: PersonaAxis, correction: f32)

Apply a host correction nudge on one axis (EvolutionEngine::correction_tick).

pub fn persist_evolution_snapshot(&mut self) -> Result<PersonaSnapshot, String>

Snapshot current axis EMA state and persist the evolution persona bundle to the store.

Returns Err when Self::evolution_writes_enabled is false (see Self::with_evolution_writes_enabled).

pub fn evolve_persona_from_graph_signals( &mut self, ) -> Result<PersonaSnapshot, String>

Graph-backed evolution only: extract signals from the store, ingest, write (EvolutionEngine::evolve).

This does not run semantic recurrence_count bumps or the extractor’s extract_pass heuristics — use GraphExtractorTask::run_pass for the full scheduled pipeline.

Returns Err when Self::evolution_writes_enabled is false (see Self::with_evolution_writes_enabled).

pub fn load_artifact(&self) -> Result<AinlGraphArtifact, String>

Boot: export + validate the agent subgraph.

pub fn compile_memory_context(&self) -> Result<MemoryContext, String>

Same as Self::compile_memory_context_for with user_message: None (treated as empty for semantic ranking; see Self::compile_memory_context_for).

pub fn compile_memory_context_for( &self, user_message: Option<&str>, ) -> Result<MemoryContext, String>

Build MemoryContext from the live store plus current extractor axis state.

relevant_semantic is ranked from this user_message only (ainl-semantic-tagger topic tags

• recurrence); None is treated as empty (high-recurrence fallback), not the latest episode text.

pub fn route_emit_edges( &self, episode_id: Uuid, turn_output_payload: &Value, ) -> Result<(), String>

Route EMIT_TO edges from an episode to hook targets (host implements TurnHooks::on_emit).

pub fn run_turn( &mut self, input: TurnInput, ) -> Result<TurnOutcome, AinlRuntimeError>

Full single-turn orchestration (no LLM / no IR parse).

pub fn dispatch_patches( &mut self, patches: &[AinlMemoryNode], frame: &HashMap<String, Value>, ) -> Vec<PatchDispatchResult>