Struct FormationCompiler 

pub struct FormationCompiler;

Implementations

impl FormationCompiler

pub fn new() -> Self

pub fn compile( &self, request: &FormationCompileRequest, catalogs: &FormationCompilerCatalogs, ) -> Result<CompiledFormationPlan, FormationCompileError>

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

Catalog-aware compile. Sources Suggestor candidates from a DiscoveryCatalog using structural filters (DiscoveryCatalog::find_by_role / DiscoveryCatalog::find_by_capability), then applies the same deterministic coverage-and-affinity ranking as Self::compile.

The returned CompiledFormationPlan carries a structured per-role decision trace under CompiledFormationPlan::decisions, so callers can see why each capability was satisfied or left uncovered.

advisory_order is an optional ranked list of descriptor IDs from an out-of-band advisor (e.g. an LLM-backed [CatalogLookup]). The compiler uses it strictly as a tie-breaker after deterministic scoring — it cannot promote a candidate above one with better coverage or domain affinity. LLM output is advisory, never authority.

pub fn compile_draft_from_catalog( &self, request: &FormationCompileRequest, formation_templates: &FormationCatalog, catalog: &DiscoveryCatalog, providers: &ProviderDescriptorCatalog, descriptor_ids: &[SuggestorDescriptorId], ) -> Result<CompiledFormationPlan, CatalogCompileFailure>

Exact-roster validator for a draft produced by an upstream deliberation Formation (see organism-dynamics).

Confirms every id in descriptor_ids is unique, resolves in catalog (returns FormationCompileError::DraftDescriptorMissing for the first missing one), and that the supplied roster covers the template’s required roles + capabilities (returns FormationCompileError::UncoveredRequirements otherwise). Does not greedy-reselect — the returned plan’s roster is exactly descriptor_ids in the supplied order.

This is intentionally distinct from Self::compile_from_catalog: the catalog-aware path picks the best roster from a pool; the draft validator honors an upstream Formation’s choice and only checks admissibility.

The returned CompiledFormationPlan carries a single RoleDecision per chosen descriptor under its decisions field, with empty considered (no candidate ranking happened) and chosen_role derived from the descriptor’s profile.

impl FormationCompiler

pub fn compile_k_candidates( &self, request: &FormationCompileRequest, formation_templates: &FormationCatalog, catalog: &DiscoveryCatalog, providers: &ProviderDescriptorCatalog, k: usize, ) -> Result<Vec<CompiledFormationPlan>, CatalogCompileFailure>

Source up to k distinct candidate rosters from the same DiscoveryCatalog by iterative swap-out diversity.

After each candidate is compiled, the function tests whether excluding each chosen descriptor would still leave the catalog capable of satisfying the template — by running a trial Self::compile_from_catalog against the catalog minus the descriptor and the current exclude set. A descriptor is added to the exclude set for the next iteration only when the trial compile succeeds, i.e. the remaining catalog can still produce some valid roster without that descriptor (possibly via a compositional alternative — multiple other descriptors covering the slot collectively). This is stricter and more correct than the previous heuristic “shares one capability with another descriptor of the same role”, which could mis-classify a broad specialist as swappable even when it was the only provider of a separate required capability.

Stops early when the filtered catalog can no longer cover the formation requirements — that’s the graceful end of the pool, not an error. Returns whatever candidates were produced.

Returns the underlying CatalogCompileFailure only when the very first iteration fails (i.e. the catalog can’t satisfy the template even unfiltered). All later failures are absorbed as “pool exhausted” and the loop stops.

Cost. Per produced candidate, this runs 1 + roster_size compiles: one to produce the candidate, and one per chosen descriptor to test swappability. compile_from_catalog is pure metadata work (no executable instantiation), so the constant is small.

k = 0 is well-defined and returns Ok(vec![]). k = 1 is equivalent to a single Self::compile_from_catalog call.

Trait Implementations

impl Debug for FormationCompiler

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for FormationCompiler

fn default() -> FormationCompiler

Returns the “default value” for a type.