Struct Formation 

pub struct Formation {
    pub label: String,
    pub budget: Budget,
    /* private fields */
}

A team of agents assembled by Organism to run in a Converge Engine.

Formations are hypotheses: “this team, with these seeds, will converge on a good answer.” Organism may run multiple formations concurrently and pick the winner.

Fields

label: String

Human-readable label for logging and learning.

budget: Budget

Execution budget for this formation’s run.

Implementations

impl Formation

pub fn new(label: impl Into<String>) -> Self

Create an empty formation with a human-readable label.

pub fn agent(self, suggestor: impl Suggestor + 'static) -> Self

Add a heterogeneous agent to the team.

pub fn agent_boxed(self, suggestor: Box<dyn Suggestor>) -> Self

Add a boxed agent to the team.

pub fn seed( self, key: ContextKey, id: impl Into<ProposalId>, content: impl Into<String>, provenance: impl Into<Provenance>, ) -> Self

Stage an initial input with explicit provenance.

pub fn with_budget(self, budget: Budget) -> Self

Set the execution budget.

pub async fn run(self) -> Result<FormationResult, FormationError>

Run this formation in a fresh Converge Engine.

This is the honest execution boundary: Organism assembles the team, Converge runs it. Agents propose, the engine promotes, and the returned result is governed by Converge.

pub async fn run_with_event_observer( self, observer: Arc<dyn ExperienceEventObserver>, ) -> Result<FormationResult, FormationError>

Run this formation with a run-scoped experience observer.

Organism should use this with FormationExperienceObserver when it needs tenant/correlation metadata on Converge experience envelopes.

impl Formation

Builder helpers for standard organism agent teams.

pub fn with_simulation_swarm(self) -> Self

Add the standard simulation swarm (all 5 dimensions) with default configs.

pub fn with_adversarial_team(self) -> Self

Add the standard adversarial team with default configs.

pub fn with_learning_priors(self) -> Self

Add the planning prior agent for learning feedback.

pub fn with_stress_test_pipeline(self) -> Self

Full Stage 2 pipeline: priors → adversarial → simulation.

pub fn with_consensus_evaluator( self, rule: ConsensusRule, total_voters: usize, ) -> Self

Add the platform consensus evaluator: tallies Vote facts under ContextKey::Votes against rule and emits ConsensusOutcome facts under ContextKey::ConsensusOutcomes.

Use this for any team that needs collective sign-off — research huddles, vendor-selection panels, multi-agent reviews. Vote facts are authored by domain pack agents; this evaluator stays domain-agnostic.

pub fn with_round_starter(self, max_rounds: u8) -> Self

Add the platform round starter: emits round:start:N signals to drive round-by-round deliberation. Round 1 fires immediately; later rounds fire when a round:continue:N marker has landed under the configured continue key. Stops at max_rounds.

pub fn with_round_synthesizer<P>( self, expected_note_count: usize, producer: P, ) -> Self

where P: SynthesisProducer + 'static,

Add the platform round synthesizer: once a started round has expected_note_count notes under ContextKey::Hypotheses, invokes the supplied [SynthesisProducer] and emits a synthesis fact under ContextKey::Strategies. Producer errors route to ContextKey::Diagnostic.

pub fn with_disagreement_mapper(self) -> Self

Add the platform disagreement mapper: aggregates Disagreement facts into per-topic crate::huddle::DisagreementMap payloads, emitted once per topic under ContextKey::Diagnostic.