Struct Runtime 

pub struct Runtime;

The formation guru.

Organism’s runtime does exactly three things:

1. Quick admission gate (is the intent even valid?)
2. Run formations in Converge (each is a team of heterogeneous Suggestors)
3. Pick the winner

Everything else — adversarial review, simulation, planning, policy checks — happens INSIDE the formation as Suggestors in the convergence loop.

Implementations

impl Runtime

pub fn new() -> Self

pub fn admit_intent( &self, intent: &IntentPacket, actor: AdmissionActor, source: AdmissionSource, context: &mut ContextState, ) -> Result<AdmissionReceipt, IntentAdmissionError>

Run organism’s structural admission gate on an IntentPacket and stage it through Converge’s typed admission boundary.

This is the public Organism → Helms contract for getting work into the runtime. Callers compile their input (e.g. with axiom_truth::compile_intent for Truth-shaped sources) into an IntentPacket and pass it here.

Flow:

1. Organism’s structural admission gate runs (cheap, deterministic).
2. The intent is staged through converge_kernel::admission::admit_observation under ContextKey::Seeds. The kernel produces the AdmissionReceipt; promotion to a governed fact happens later through the engine’s normal gate.

Returns the AdmissionReceipt — proof the intent has been staged. The caller already holds the IntentPacket and can use it directly to drive resolution and planning.

Errors

Returns IntentAdmissionError if the intent fails the admission gate, or fails Converge admission validation.

pub fn select_formation<'cat>( &self, intent: &IntentPacket, catalog: &'cat FormationCatalog, capabilities: &[SuggestorCapability], ) -> Result<GuruSelection<'cat>, GuruError>

Pick a formation template for intent from catalog given the host’s available capabilities. The guru classifies the intent, queries the catalog by class-derived keywords, and post-filters by the host’s declared capability inventory. Returns the chosen primary plus up to two alternates and a SelectionTrace explaining the choice.

This is auto-mode’s front half — selection without execution. To run the chosen template, build a FormationCompileRequest keyed on selection.primary.id() and call [compile_and_run_formation].

Errors

Returns GuruError if no template in catalog satisfies the classified problem under capabilities.

pub fn compile_formation( &self, intent: &IntentPacket, request: &FormationCompileRequest, catalogs: &FormationCompilerCatalogs, ) -> Result<CompiledFormationPlan, PipelineError>

Admit an intent and compile the formation plan Organism would run.

This is the pure compiler boundary: descriptor catalogs produce an auditable formation plan without creating live suggestor instances.

pub fn compile_and_instantiate_formation( &self, intent: &IntentPacket, request: &FormationCompileRequest, catalogs: &FormationCompilerCatalogs, executables: &ExecutableSuggestorCatalog, seeds: impl IntoIterator<Item = Seed>, ) -> Result<(CompiledFormationPlan, Formation), PipelineError>

Admit, compile, and instantiate a runnable formation from registered executable suggestor factories.

This keeps the boundary honest: a plan can run only when every compiled suggestor_id has a concrete factory in executables.

pub async fn compile_and_run_formation( &self, intent: &IntentPacket, request: &FormationCompileRequest, catalogs: &FormationCompilerCatalogs, executables: &ExecutableSuggestorCatalog, seeds: impl IntoIterator<Item = Seed>, observer: Option<Arc<dyn ExperienceEventObserver>>, ) -> Result<FormationExecutionRecord, PipelineError>

Admit, compile, instantiate, and run one formation candidate.

This is the single-candidate execution path. Tournaments can build on top of this by running multiple compile requests and comparing returned FormationExecutionRecord values.

pub fn compile_formation_from_catalog( &self, intent: &IntentPacket, request: &FormationCompileRequest, formation_templates: &FormationCatalog, catalog: &DiscoveryCatalog, providers: &ProviderDescriptorCatalog, advisory_order: Option<&[String]>, ) -> Result<CompiledFormationPlan, PipelineError>

Admit an intent and compile a formation plan from a DiscoveryCatalog. Catalog-aware parallel to Self::compile_formation.

pub fn compile_and_instantiate_from_catalog( &self, intent: &IntentPacket, request: &FormationCompileRequest, formation_templates: &FormationCatalog, catalog: &DiscoveryCatalog, providers: &ProviderDescriptorCatalog, executables: &ExecutableSuggestorCatalog, seeds: impl IntoIterator<Item = Seed>, advisory_order: Option<&[String]>, ) -> Result<(CompiledFormationPlan, Formation), PipelineError>

Admit, compile from catalog, and instantiate a runnable formation. Catalog-aware parallel to Self::compile_and_instantiate_formation.

pub async fn compile_k_and_run_tournament<F>( &self, intent: &IntentPacket, request: &FormationCompileRequest, formation_templates: &FormationCatalog, catalog: &DiscoveryCatalog, providers: &ProviderDescriptorCatalog, executables: &ExecutableSuggestorCatalog, seeds_fn: F, k: usize, ) -> Result<CatalogTournamentOutcome, PipelineError>

where F: Fn(usize, &CompiledFormationPlan) -> Vec<Seed>,

Source k candidate rosters from the catalog, instantiate each, and run a FormationTournament to pick the winner.

Each candidate covers the same formation template requirements but draws a different roster from the catalog (via swap-out diversity — see FormationCompiler::compile_k_candidates). The returned CatalogTournamentOutcome carries both the tournament result (winner + scores + priors) and each candidate’s CompiledFormationPlan (with its decisions trace) so the audit trail shows selection rationale AND score outcome side-by-side.

seeds_fn is called once per candidate to produce its seed inventory — formations consume their seeds when run, so each candidate needs its own fresh Vec<Seed>.

pub async fn handle( &self, intent: IntentPacket, formations: Vec<Formation>, ) -> Result<OrganismResult, PipelineError>

Drive an intent through the pipeline.

The caller is responsible for assembling formations (teams of Suggestors). That’s the formation-guru logic — deciding which agents to include based on the intent’s characteristics, available capabilities, and learned priors.

Each formation may include any mix of:

• LLM reasoning agents
• Optimization solvers
• Policy gates
• Analytics/ML agents
• Adversarial skeptics
• Domain-specific pack agents

All participate through the same Suggestor trait. Same contract, same governance, same convergence loop.