Crate mlua_swarm_schema 

Blueprint schema — Swarm IF SoT (= the core type set that defines “how a Blueprint object is written”).

This crate provides schema types + serde derives only as a pure IF crate. Execution layers (SpawnerFactory / EngineDispatcher / Compiler) are not included here; consumers (the mlua-swarm crate) own them. External consumers, sibling worktrees, and future bundles can read/write Blueprints by depending on this single crate.

Versioning contract

Blueprint.schema_version is tied to this crate’s semver. It is fixed at 0.1.0 for now; during 0.x breaking changes are free, and 1.0 will freeze the schema.

IN-immutability (extension discipline)

This crate is the IN side of the swarm layering and stays plain serde data: no compile pass, no field the engine macro-expands, no DSL dialect. Flow conds are written literally against the Flow.ir Expr set (Eq($.<step>.verdict, Lit("blocked")) — domain verdicts are plain strings in step output). Authoring sugar (builders) lives OUT on the consumer side; runtime behavior extension lives in the engine’s SpawnerLayer middleware.

AgentKind handling (= internal SoT)

AgentKind is the SoT for the SpawnerAdapter offering axis. It is a closed enum managed inside Swarm, extended by variant addition through explicit maintenance. String lookup or a Custom escape hatch is deliberately avoided (= structurally eliminates the “silly runtime typos” class of failures).

Examples

Build a minimal Blueprint with a single AgentDef via struct literal:

use mlua_swarm_schema::{
    AgentDef, AgentKind, Blueprint, current_schema_version,
};
use mlua_flow_ir::{Expr, Node};
use serde_json::json;

let bp = Blueprint {
    schema_version: current_schema_version(),
    id: "hello".into(),
    flow: Node::Step {
        ref_: "greeter".into(),
        in_: Expr::Lit { value: json!({"name": "world"}) },
        out: Expr::Path { at: "$.greeting".into() },
    },
    agents: vec![AgentDef {
        name: "greeter".into(),
        kind: AgentKind::RustFn,
        spec: json!({"fn_id": "hello_world"}),
        profile: None,
        meta: None,
    }],
    operators: vec![],
    hints: Default::default(),
    strategy: Default::default(),
    metadata: Default::default(),
    spawner_hints: Default::default(),
    default_agent_kind: AgentKind::Operator,
    default_operator_kind: None,
};

assert_eq!(bp.id, "hello");
assert_eq!(bp.agents.len(), 1);
assert_eq!(bp.strategy.strict_refs, true);

Round-trip a Blueprint through JSON (= confirms serde derives and the deny_unknown_fields contract):

use mlua_swarm_schema::{AgentKind, Blueprint, BlueprintMetadata};
use mlua_flow_ir::{Expr, Node};
use serde_json::json;

let bp = Blueprint {
    schema_version: mlua_swarm_schema::current_schema_version(),
    id: "roundtrip".into(),
    flow: Node::Seq { children: vec![] },
    agents: vec![],
    operators: vec![],
    hints: Default::default(),
    strategy: Default::default(),
    metadata: BlueprintMetadata {
        description: Some("roundtrip smoke".into()),
        default_run_ttl_secs: Some(1800),
        ..Default::default()
    },
    spawner_hints: Default::default(),
    default_agent_kind: AgentKind::Operator,
    default_operator_kind: None,
};

let json = serde_json::to_string(&bp).unwrap();
let back: Blueprint = serde_json::from_str(&json).unwrap();
assert_eq!(bp, back);
assert_eq!(back.metadata.default_run_ttl_secs, Some(1800));

Structs

AgentDef

Maps an agent name to a Worker IMPL kind and its configuration. Referenced from flow.ir Step.ref by name.

AgentMeta

Agent / Operator level metadata (description / version / tags).

AgentProfile

Agent persona information. Orthogonal to the backend kind (Shell / InProc / Operator).

Blueprint

Unified package of flow.ir + Swarm extension layers. The entry-point type of Swarm.

BlueprintMetadata

Blueprint-level metadata (description / origin / tags / ttl / version label / alias).

CompilerHints

Per-agent overrides / hints. Interpreted by the Compiler / SpawnerFactory; not required.

CompilerStrategy

Compiler behavior rules. Controls strict / lenient handling and default fallback.

OperatorDef

Design-time definition of an Operator role (first-class).

SpawnerHints

Set of capability hint keys for the SpawnerLayer required by a Blueprint.

Enums

AgentKind

SoT of the Worker IMPL axis. A closed enum managed inside Swarm and extended by variant addition through explicit maintenance. String lookup / escape hatches are deliberately not adopted.

BlueprintOrigin

Provenance record of a Blueprint.

OperatorKind

Kind axis of an Operator role (= “in which mode does this Operator run”). Corresponds 1:1 with the engine’s runtime OperatorKind. Kept as a schema duplicate so that BPs can be authored while depending only on this crate.

Constants

CURRENT_SCHEMA_VERSION

Current Blueprint schema version. Tied to this crate’s semver.

Functions

current_schema_version

Blueprint construction helper: returns the semver of the current schema version. Callers can write schema_version: current_schema_version(),.

default_global_agent_kind

Global default AgentKind at the Schema impl Default layer. Bottom of the 4-layer cascade.