Crate mlua_swarm_schema

Expand description

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".parse().unwrap() },
    },
    agents: vec![AgentDef {
        name: "greeter".into(),
        kind: AgentKind::RustFn,
        spec: json!({"fn_id": "hello_world"}),
        profile: None,
        meta: None,
    }],
    operators: vec![],
    metas: vec![],
    hints: Default::default(),
    strategy: Default::default(),
    metadata: Default::default(),
    spawner_hints: Default::default(),
    default_agent_kind: AgentKind::Operator,
    default_operator_kind: None,
    default_init_ctx: None,
    default_agent_ctx: None,
    default_context_policy: None,
    projection_placement: None,
    audits: vec![],
    degradation_policy: None,
};

assert_eq!(bp.id.as_str(), "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![],
    metas: 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,
    default_init_ctx: None,
    default_agent_ctx: None,
    default_context_policy: None,
    projection_placement: None,
    audits: vec![],
    degradation_policy: 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).
AuditDef: GH #34 — one Blueprint-declared after-run audit hook. See Blueprint::audits for the persistence / invariant contract.
Blueprint: Unified package of flow.ir + Swarm extension layers. The entry-point type of Swarm.
BlueprintId: Identifier for a Blueprint series — the domain name (coding, design, testing, etc.). Default: BlueprintId::main.
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.
ContextPolicy: Receptacle for a Blueprint-driven filter over the materialized AgentContextView (GH #20/#21). Declared BP-side via Blueprint::default_context_policy (BP-global) or AgentMeta::context_policy (per-agent, outranks the BP-global tier) — resolved and applied by AgentContextMiddleware in the mlua-swarm core crate (this crate stays execution-free; see the crate doc). Default (include: None, exclude: vec![]) is pass-all — Self::allows returns true for every field name.
MetaDef: Named, multi-step-shared declarative context payload (GH #21 Phase 2).
OperatorDef: Design-time definition of an Operator role (first-class).
ProjectionPlacementSpec: GH #27 (follow-up to #23) — Blueprint-declared override of the mlua-swarm core crate’s placement resolver (mlua_swarm::core::projection_placement::ProjectionPlacement), which decides where a Step’s materialized OUTPUT file (submit-time sink, server read-back, and spawn-time ctx_projection pointer — the “3 path” convergence point) is written on disk. Both fields are independently optional and validated (dir_template) at Compiler::compile time — see that resolver’s from_spec doc for the full rejection rules.
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.
AuditMode: GH #34 — dispatch timing for an AuditDef’s audit agent. Neither variant ever changes the audited step’s outcome (see Blueprint::audits’s binding invariant).
BlueprintOrigin: Provenance record of a Blueprint.
DegradationPolicy: GH #32 — Blueprint-declared policy for worker-reported degradations. See Blueprint::degradation_policy for the (currently schema-only) enforcement contract.
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.