Crate ainl_runtime 

ainl-runtime v0.3.5-alpha — orchestration layer for the unified AINL graph (memory substrate + extraction).

This crate does not call LLMs, parse AINL IR, or implement tool adapters. It coordinates ainl_memory, persona axis state via ainl_persona::EvolutionEngine (shared with ainl_graph_extractor::GraphExtractorTask), and scheduled graph extraction — with TurnHooks for host integration (e.g. OpenFang).

Evolution: EvolutionEngine lives in ainl-persona. AinlRuntime::evolution_engine_mut and helpers (AinlRuntime::apply_evolution_signals, AinlRuntime::persist_evolution_snapshot, …) drive it without going through the extractor. GraphExtractorTask::run_pass remains one signal producer (graph extract + recurrence + pattern heuristics), not the only way to evolve persona axes. Scheduled passes attach ExtractionReport to TurnResult; populated extract_error / pattern_error / persona_error slots become separate TurnWarning entries tagged with TurnPhase::ExtractionPass, TurnPhase::PatternPersistence, and TurnPhase::PersonaEvolution.

For a minimal “record episodes + run extractor” path without the full engine, see RuntimeContext.

Semantic ranking / MemoryContext

compile_memory_context_for(None) no longer inherits previous episode text for semantic ranking; pass Some(user_message) if you want topic-aware MemoryContext::relevant_semantic. AinlRuntime::compile_memory_context still calls compile_memory_context_for(None) (empty message → high-recurrence fallback). AinlRuntime::run_turn always passes the current turn text.

Episodic tools_invoked (canonical storage)

Raw TurnInput::tools_invoked strings are normalized with ainl_semantic_tagger::tag_tool_names before the episode row is written: stored values are canonical tool tag values, deduplicated and sorted. Empty input uses ["turn"]. The emit payload’s tool list matches the persisted episode.

Episode id in turn results

The returned episode identifier is the graph node row id (AinlMemoryNode::id), not necessarily EpisodicNode::turn_id. Use it for EMIT_TO edges and store queries keyed by node id.

Async / Tokio: enable the optional async crate feature for AinlRuntime::run_turn_async. Graph memory is then Arc<std::sync::Mutex<GraphMemory>> (not tokio::sync::Mutex) so AinlRuntime::new and AinlRuntime::sqlite_store can take short locks on any thread; SQLite work for async turns is still offloaded with tokio::task::spawn_blocking. See the crate README.md for rationale; ArmaraOS hub docs/ainl-runtime.md, patch dispatch docs/ainl-runtime-graph-patch.md, and optional OpenFang embed docs/ainl-runtime-integration.md cover host integration and registry crates.io pins.

Structs

AdapterRegistry

AinlGraphArtifact

A loaded, validated AINL graph artifact (memory substrate view for one agent).

AinlRuntime

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

EvolutionEngine

ExtractionReport

Result of GraphExtractorTask::run_pass. Errors are carried per phase; the pass does not return Result so callers can record partial progress and continue.

GraphExtractorTask

GraphPatchAdapter

Reference adapter registered as Self::NAME. Used as a fallback when no label-specific PatchAdapter is registered for the procedural patch label.

MemoryContext

Compiled memory context for a turn (prompt-side assembly in the host).

NoOpAsyncHooks

Default async hook implementation (no side effects).

NoOpHooks

Default hook implementation (no side effects).

PatchDispatchContext

Per-patch inputs for crate::PatchAdapter::execute_patch (procedural patch nodes).

PatchDispatchResult

Result of attempting to dispatch one procedural patch node.

PersonaSnapshot

RawSignal

RuntimeConfig

Configuration for AinlRuntime and RuntimeContext.

RuntimeContext

Host context: optional memory plus optional stateful extractor (legacy / lightweight).

SqliteStoreRef

Borrowed view of the backing SQLite store (see crate::AinlRuntime::sqlite_store).

TurnInput

Input for a single agent turn (host fills; runtime does not call LLMs).

TurnResult

Payload from a finished turn (memory context, episode id, patch dispatch, etc.).

TurnWarning

One non-fatal failure recorded during a turn (the turn still returns a usable TurnResult).

Enums

AinlRuntimeError

Hard failure for crate::AinlRuntime::run_turn (store open, invalid graph, invalid compile input, etc.).

MemoryNodeType

PatchSkipReason

PersonaAxis

TurnOutcome

Full success vs partial success after non-fatal write failures.

TurnPhase

Non-fatal bookkeeping phase inside [AinlRuntime::run_turn] (SQLite / export / persona persistence).

TurnStatus

Soft outcome for step caps / disabled graph (not store write failures — those become TurnWarning).

Constants

EMIT_TO_EDGE

Edge label for emit routing (matches ainl_graph_edges.label).

EVOLUTION_TRAIT_NAME

Canonical ainl_memory::PersonaNode::trait_name for axis-evolution bundles. graph_extractor (Prompt 2) should import this from the crate root when selecting persona rows for domain / formality signals — do not duplicate the string.

INGEST_SCORE_EPSILON

Minimum absolute score delta on an axis for a signal to count as “applied” in EvolutionEngine::ingest_signals.

Traits

GraphPatchHostDispatch

Optional host hook: receives the same JSON summary as GraphPatchAdapter::execute_patch.

PatchAdapter

Label-keyed procedural patch executor. Register via crate::AinlRuntime::register_adapter.

TurnHooks

Hooks for observability and host wiring. Every method has a default empty body.

TurnHooksAsync

Async observability hooks for crate::AinlRuntime::run_turn_async (Tokio-friendly).

Functions

default_axis_map

infer_topic_tags

Deterministic keyword tagging for broad topics. One tag per topic slug; confidence is the max across that slug’s keyword hits (0.85 exact / phrase, 0.70 substring for single-token keys).

run_extraction_pass

Convenience wrapper for one-off extraction. Creates a fresh GraphExtractorTask with a new crate::PersonaSignalExtractorState on each call, so streak-based detectors (brevity, formality) cannot fire across invocations. For long-running agent loops, instantiate GraphExtractorTask directly and call GraphExtractorTask::run_pass to preserve streak state between passes.