Crate mlua_swarm 

Swarm engine host for mlua — a long-running stateful runtime that compiles flow.ir Blueprints and dispatches their agent steps to workers.

Architecture

mlua-swarm is the host layer of a four-layer stack:

flow.ir programs (Lua / JSON Blueprints authored by users or AIs)
        │  parsed / compiled
flow-ir-core        IR node & expr types + pure evaluation
        │  bridged into Lua
mlua-flow-ir        Lua <-> IR bridge (mlua-based)
        │  hosted by
mlua-swarm (this)   engine, workers, operators, middleware, stores

A Blueprint declares a flow (step / seq / branch / loop / fanout / try / assign nodes) plus the agents it references. The Compiler resolves each agent to a SpawnerFactory (Lua in-process, Rust fn, subprocess, or WS operator), and the Engine drives the flow while recording task state as an Event stream.

Domain vs. Data separation

Control-flow values (verdicts, counters, small routing fields) travel in the shared Ctx; large worker responses are offloaded to an OutputStore and referenced from Ctx by OutputRef. This keeps flow evaluation cheap and bounded regardless of payload size.

Middleware

Worker dispatch passes through a SpawnerStack assembled from a LayerRegistry: a base layer set plus per-blueprint hints (CompilerHints) select layers such as audit, long-hold, main-AI bridging, senior escalation, and operator delegation.

Module map

• types / [errors] — Role × Verb capability gate, CapToken (HMAC-SHA256), ID newtypes, and the EngineError surface.
• core — engine config, task state machine, Ctx, and the Engine itself.
• blueprint — schema shim, compiler, loader ($agent_md file-ref expansion), and versioned stores (in-memory / git2-backed).
• worker / operator — spawner adapters, process spawning, output events, and WS operator sessions.
• middleware — the layer registry and the individual layers.
• lua / [agent_block] — Lua blueprint bridge, agents/*.md loader, and the agent-block SDK spawner integration.
• service / application / enhance — task-launch orchestration, application façades, and the self-enhancement (patch / verify / commit) flow.
• store — persistence traits and default backends for outputs, issues, and enhance settings/logs.

Re-exports

pub use application::Application;

pub use application::BlueprintRef;

pub use application::EnhanceApplication;

pub use application::EnhanceApplicationConfig;

pub use application::EnhanceApplicationError;

pub use application::EnhanceApplicationInput;

pub use application::TaskApplication;

pub use application::TaskApplicationError;

pub use application::TaskApplicationInput;

pub use application::TaskApplicationOutput;

pub use application::TickOutcome;

pub use application::VersionSelector;

pub use blueprint::compiler::CompileError;

pub use blueprint::compiler::CompiledAgentTable;

pub use blueprint::compiler::CompiledBlueprint;

pub use blueprint::compiler::Compiler;

pub use blueprint::compiler::HostBridge;

pub use blueprint::compiler::LuaInProcessSpawnerFactory;

pub use blueprint::compiler::LuaScriptSource;

pub use blueprint::compiler::OperatorSpawnerFactory;

pub use blueprint::compiler::RustFnInProcessSpawnerFactory;

pub use blueprint::compiler::SpawnerFactory;

pub use blueprint::compiler::SpawnerFactoryKind;

pub use blueprint::compiler::SpawnerRegistry;

pub use blueprint::compiler::SubprocessProcessSpawnerFactory;

pub use blueprint::loader::expand_file_refs;

pub use blueprint::loader::load_blueprint_from_path;

pub use blueprint::loader::LoadError;

pub use blueprint::EngineDispatcher;

pub use core::config::EngineCfg;

pub use core::config::LongHoldConfig;

pub use core::ctx::collapse_operator_kind;

pub use core::ctx::Ctx;

pub use core::ctx::CtxMeta;

pub use core::ctx::OperatorInfo;

pub use core::ctx::OperatorKind;

pub use core::ctx::SeniorBridge;

pub use core::ctx::SpawnHook;

pub use core::engine::Engine;

pub use core::errors::EngineError;

pub use core::state::CapTokenConsumeError;

pub use core::state::CapTokenRecord;

pub use core::state::DispatchOutcome;

pub use core::state::Event;

pub use core::state::EventStream;

pub use core::state::OperatorSession;

pub use core::state::ResumeKey;

pub use core::state::ResumePending;

pub use core::state::TaskSpec;

pub use core::state::TaskState;

pub use core::state::TaskStatus;

pub use lua::bridge::parse_lua_blueprint;

pub use lua::bridge::parse_lua_blueprint_with_ctx;

pub use middleware::lua_layer::LuaMiddleware;

pub use middleware::project_name_alias::ProjectNameAliasMiddleware;

pub use middleware::project_name_alias::PROJECT_NAME_ALIAS_KEY;

pub use middleware::resolver::AgentResolver;

pub use middleware::resolver::FnResolver;

pub use middleware::resolver::ResolverMiddleware;

pub use middleware::AuditMiddleware;

pub use middleware::LayerFactory;

pub use middleware::LayerRegistry;

pub use middleware::LongHoldMiddleware;

pub use middleware::MainAIMiddleware;

pub use middleware::OperatorDelegateMiddleware;

pub use middleware::SeniorEscalationMiddleware;

pub use middleware::SpawnerLayer;

pub use middleware::SpawnerStack;

pub use operator::Operator;

pub use operator::OperatorSpawner;

pub use service::TaskLaunchError;

pub use service::TaskLaunchInput;

pub use service::TaskLaunchOutput;

pub use service::TaskLaunchService;

pub use store::output::InMemoryOutputStore;

pub use store::output::OutputRecord;

pub use store::output::OutputRef;

pub use store::output::OutputStore;

pub use store::output::OutputStoreError;

pub use types::default_role_verb_table;

pub use types::CapToken;

pub use types::CapTokenDecodeError;

pub use types::Role;

pub use types::RoleVerbGate;

pub use types::SessionId;

pub use types::TaskId;

pub use types::Verb;

pub use types::WorkerId;

pub use types::WorkerPayload;

pub use worker::adapter::InProcSpawner;

pub use worker::adapter::SpawnError;

pub use worker::adapter::SpawnerAdapter;

pub use worker::adapter::WorkerError;

pub use worker::adapter::WorkerFn;

pub use worker::adapter::WorkerInvocation;

pub use worker::adapter::WorkerResult;

pub use worker::agent_block::AgentBlockInProcessSpawnerFactory;

pub use worker::output::ContentRef;

pub use worker::output::OutputEvent;

pub use worker::output::OutputSink;

pub use worker::process_spawner::ProcessSpawner;

pub use worker::process_spawner::StreamMode;

pub use worker::MiddlewareWorker;

pub use worker::Worker;

pub use worker::WorkerJoinHandler;

Modules

application

Application axis — the per-input (IN) use-case entry points that drive processing on top of the Engine.

blueprint

Blueprint runner — glue that executes a flow.ir AST (mlua_flow_ir::Node) through the engine. Each Step.ref is run as a single task via start_task + dispatch_attempt_with, and the resulting Pass Value is written back to Step.out.

core

Core runtime primitives: Engine + Ctx + State + Config.

enhance

Enhance domain — Rust wiring for the Blueprint self-enhancement flow.

lua

Lua bridge layer: agent.md loader + Lua-DSL bridge.

middleware

Middleware overlay — cross-cutting concerns (Audit / MainAI / Senior / LongHold).

operator

Operator abstraction.

service

Domain-service layer.

store

Persistence layer — the sibling of application / service in the Layered decomposition.

types

Fundamental types: Role / Verb / RoleVerbGate / CapToken / IDs.

worker

The Worker trait — the shared interface for the execution units each spawner keeps internally.

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).

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.

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.

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(),.