Enum CompileError 

pub enum CompileError {
    BoundAgent(BoundAgentResolveError),
    UnknownKind(AgentKind),
    InvalidSpec {
        name: String,
        msg: String,
    },
    UnresolvedRef(String),
    DuplicateAgent(String),
    UnresolvedOperatorRef {
        agent: String,
        op_ref: String,
        defined: Vec<String>,
    },
    RemovedSpawnerHint {
        key: String,
        reason: String,
    },
    UnresolvedMetaRef {
        where_: String,
        meta_ref: String,
        defined: Vec<String>,
    },
    StepNamingCollision(StepNamingError),
    InvalidProjectionPlacement(ProjectionPlacementError),
    UnresolvedAuditAgent {
        agent: String,
        defined: Vec<String>,
    },
    VerdictChannelMismatch {
        where_: String,
        agent: String,
        expected_channel: String,
        actual_shape: String,
    },
    VerdictValueNotInContract {
        where_: String,
        agent: String,
        value: String,
        values: Vec<String>,
    },
    VerdictValueUnhandled {
        agent: String,
        value: String,
        declared_values: Vec<String>,
        step_ref: String,
    },
}

Everything that can go wrong while Compiler::compile turns a Blueprint into a CompiledBlueprint.

Variants

BoundAgent(BoundAgentResolveError)

Runner / Agent / Context binding failed before any spawner was built.

UnknownKind(AgentKind)

An AgentDef.kind has no matching entry in the SpawnerRegistry and Blueprint.strategy.strict_kind is set.

InvalidSpec

The AgentDef.spec shape did not match what the factory for its kind requires (missing/mistyped field, etc.).

Fields

name: String

The offending agent’s name.

msg: String

Human-readable description of what was wrong with the spec.

UnresolvedRef(String)

The flow references an agent name that has no corresponding AgentDef (and no default spawner is configured).

DuplicateAgent(String)

Two AgentDefs in the same Blueprint share a name.

UnresolvedOperatorRef

A kind = Operator agent’s spec.operator_ref does not match any OperatorDef.name declared in Blueprint.operators.

Fields

agent: String

The agent whose operator_ref didn’t resolve.

op_ref: String

The operator_ref value that was looked up.

defined: Vec<String>

The OperatorDef.names that are declared, for the error message.

RemovedSpawnerHint

Blueprint.spawner_hints.layers names a layer that has been removed from the engine — currently only "operator_delegate".

Why this is an error and not a skipped key

service::linker::link skips hint keys the deployment’s LayerRegistry does not answer, on purpose: it keeps a Blueprint portable across deployments that install different layers. That leniency is exactly wrong for a key the engine used to answer and no longer does — the Blueprint would keep parsing, keep registering, and quietly run a different execution shape than the author wrote, with nothing anywhere saying a declared capability had been dropped. Being lenient about an unknown capability and being lenient about a withdrawn one are different bets, and only the first one pays.

Refusing at compile is also what makes the removal legible in the one place that can name the replacement. See the removed-spawner-hint lint and mse://guides/blueprint-authoring.

Fields

key: String

The removed hint key the Blueprint still declares.

reason: String

Why the layer went, in one clause — folded into the message so an author reading only the error text learns the cause, not just the verdict.

UnresolvedMetaRef

GH #21 Phase 2: an AgentMeta.meta_ref or a statically-visible $step_meta.ref (inside a Step.in Lit expr) does not match any MetaDef.name declared in Blueprint.metas.

Fields

where_: String

Human-readable description of where the reference was found (e.g. "AgentMeta.meta_ref of agent 'planner'" or "Step 'scout' $step_meta.ref").

meta_ref: String

The meta_ref value that was looked up.

defined: Vec<String>

The MetaDef.names that are declared, for the error message.

StepNamingCollision(StepNamingError)

GH #23: two Steps’ canonical/alias projection names collide and at least one side declared AgentMeta.projection_name — see crate::core::step_naming::StepNaming::from_blueprint’s doc for the full resolution rule (an undeclared/undeclared clash is a soft warning instead, logged but not rejected).

InvalidProjectionPlacement(ProjectionPlacementError)

GH #27 (follow-up to #23): Blueprint.projection_placement failed validation — see crate::core::projection_placement::ProjectionPlacement::from_spec’s doc for the rejection rules (dir_template empty / missing the {task_id} placeholder / absolute / containing a .. segment, or root not "work_dir"/"project_root").

UnresolvedAuditAgent

GH #34: an audits[].agent name does not match any AgentDef.name declared in Blueprint.agents — mirrors the operator_ref validation above (same “design-time reference must resolve” discipline).

Fields

agent: String

The audits[].agent value that was looked up.

defined: Vec<String>

The AgentDef.names that are declared, for the error message.

VerdictChannelMismatch

GH #50: a Branch/Loop cond compares a contract-bearing agent’s output using the wrong OUTPUT channel — e.g. the agent declares channel: "part" (verdict staged as the named part "verdict", addressed $.<step>.parts.verdict) but the cond addresses the bare step output ($.<step>) instead, or vice versa. See the blueprint-authoring.md guide’s “Returning verdicts to drive BP flow” section for Pattern A (channel: "body") vs Pattern B (channel: "part").

Fields

where_: String

Human-readable description of where the offending cond was found (e.g. "Branch cond" / "Loop cond").

agent: String

The agent whose declared verdict.channel didn’t match.

expected_channel: String

The agent’s declared channel ("body" or "part").

actual_shape: String

The channel shape the cond’s Path actually addressed ("body" or "part").

VerdictValueNotInContract

GH #50: a Branch/Loop cond’s Lit operand (or, for In, one of the Lit haystack’s array elements) is not a member of a contract-bearing agent’s declared verdict.values closed token set.

Fields

where_: String

Human-readable description of where the offending cond was found (e.g. "Branch cond" / "Loop cond").

agent: String

The agent whose declared verdict.values didn’t contain value.

value: String

The offending Lit value, rendered as a string (the raw JSON representation when it is not itself a JSON string — a non-string Lit can never be a member of values: Vec<String> either way).

values: Vec<String>

The agent’s declared verdict.values closed token set, for the error message.

VerdictValueUnhandled

GH #50 follow-up (issue 33bc825b): a contract-bearing agent declares verdict.values = [...] but at least one member of that closed token set is never referenced by any downstream Branch/Loop cond Lit — the flow author declared a verdict value they never wrote a handler for. Emitted only when the Blueprint opts in via BlueprintMetadata::strict_verdict_handling= Some(true); under the default (None/Some(false)) unhandled values surface as tracing::warn! only and compilation succeeds (back-compat with Blueprints that intentionally leave some verdict values as silent-pass informational tokens).

Fields

agent: String

The agent whose declared verdict.values entry lacks a downstream handler.

value: String

The declared value that has no downstream cond reference.

declared_values: Vec<String>

The agent’s full declared verdict.values closed token set, for the error message.

step_ref: String

The Step.ref_ where this agent is invoked. When the same agent is invoked at multiple sites, the first one encountered during flow walk is reported (best-effort — the diagnostic still identifies the offending agent uniquely).

Trait Implementations

impl Debug for CompileError

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

Formats the value using the given formatter.

impl Display for CompileError

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

Formats the value using the given formatter.

impl Error for CompileError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<&CompileError> for Diagnostic

GH #79 Phase 2: project every CompileError variant into the unified [Diagnostic] shape (mlua-swarm-diag), preserving the variant’s typed fields into span / notes / help directly — no substring re-parse of the #[error(...)] strings.

Every diagnostic is stage: CompileLint / level: Error (a CompileError always aborts the compile). The kind keys match mlua_swarm_diag::LINT_DECLS entries one-to-one — asserted by this module’s every_compile_error_variant_maps_to_a_declared_lint test.

One specialization: an CompileError::InvalidSpec whose message carries WORKER_BINDING_REQUIRED_MSG_PREFIX maps to the dual-stage kind worker-binding-missing (the same lint bp_doctor reports as Warn post-register) instead of the generic invalid-agent-spec — one lint kind, one docs anchor, one downstream switch key across both stages.

fn from(err: &CompileError) -> Self

Converts to this type from the input type.

impl From<BoundAgentResolveError> for CompileError

fn from(source: BoundAgentResolveError) -> Self

Converts to this type from the input type.

impl From<CompileError> for TaskLaunchError

fn from(source: CompileError) -> Self

Converts to this type from the input type.

impl From<ProjectionPlacementError> for CompileError

fn from(source: ProjectionPlacementError) -> Self

Converts to this type from the input type.

impl From<StepNamingError> for CompileError

fn from(source: StepNamingError) -> Self

Converts to this type from the input type.