Crate flux_lang 

flux-lang — the pure Flux-Lang language core.

Flux-Lang is an authored workflow language: applications place deterministic control flow around typed model stages and registered operations, and a deterministic runtime runs the AST. This crate is the language half, deliberately separated from the engine that executes it:

• ast — the Draft AST, typed HIR, physical plan, value model, the semantic ast::FlowEffects, and the run-event trace.
• render — the AST pretty-printer (human-auditable projections).
• [format] / parse — the canonical compact text syntax (the round-trippable .flux surface): parse(&format(&ast)) == ast for every DraftAst. Distinct from render (one-way).
• analyze — the validator, working against an abstract opspec::OpCatalog (no knowledge of any concrete tool registry).
• opspec — the typed operation spec/signature and the opspec::OpCatalog seam.
• prelude — the artifact-type ontology (claims, evidence, needs, context packs, …) ops declare their I/O against; a stdlib of Named schemas, not a Value change.
• program — the multi-agent Program layer (agents/channels/triggers/journeys) + the key-sniffing module loader; pure-data decls the L6 flux-app host runs.
• effects — lowering of semantic effects onto host flux_spec::Effect + policy actions.
• schema — the single source of truth: a derived JSON Schema and the node-kind catalog that drives generated skill/docs and language tooling.
• context_slice — automatic context slicing (KF4/L-56): derive the minimum model-visible context for a model-op call or diagnostic UI from HIR reads, field access paths, op schemas, and diagnostics, gated by visibility/secret/policy and a token budget.

It is an L0 leaf: it depends only on other pure contracts (flux-core, flux-spec, flux-policy) and has no IO, no provider, no runtime, and no dependency on concrete tools. The engine crate flux-flow builds on top of it (analyze → execute) and re-exports it.

Re-exports

pub use error::FlowError;

pub use error::Result;

Modules

analyze

The analyzer. M1 validates the single-call grammar: the operation must be registered. Later milestones add full name / type / effect / bounded-loop checking over the whole AST, lowering a DraftAst into a typed HirFlow.

ast

The pure language contracts: the Draft AST the LLM emits, the typed HIR the analyzer produces, the physical plan the optimizer produces, the value model, semantic effects, and the run-event trace. No IO and no flux-runtime/provider dependency — these types are shared by every phase and by the UI projections.

context_slice

context_slice — automatic context slicing for planner and model ops (KF4/L-56, docs/designs/flux-lang-agent-speed.md).

dsl

A Rust embedded DSL for authoring Flux-Lang flows — builder primitives that compile straight down to the crate::ast tree, so a Rust programmer can write a flow natively instead of emitting JSON or natural language.

effects

Lowering of semantic FlowEffects onto the host-resource Effect + policy Action that the existing authorization bridge understands. This keeps flux_spec::Effect host-resource-shaped while letting operations declare workflow meaning (sends mail, costs money, …).

error

The crate error type. Library code returns Result; the phases (parse/analyze/compile/ runtime) each map onto a variant so diagnostics stay attributable.

expr

The expr evaluator — a safe, side-effect-free formula mini-language for conditional logic, arithmetic, string functions, and list operations. Used by Node::Expr in the runtime and by transform operations (filter, map, etc.) for predicate evaluation. Public so flux-tools can reuse the exact semantics for op-side predicates (L-46).

format

format — the canonical compact text projection of a DraftAst, and the round-trip partner of crate::parse. Where crate::render is a one-way box-drawing display tree, this module emits a re-parseable surface: parse(&format(&ast)) == ast for every DraftAst whose header names are spellable (see “The flow-header exception” below — node bodies are covered totally).

highlight

highlight — CST-classified highlight spans (the shared syntax-highlighting substrate).

host

The execution host seam: the narrow interface the interpreter dispatches operations and approvals through. The engine implements OpHost over its real safety envelope (Executor::dispatch + the approver); the language stays free of any concrete runtime or tool dependency — it knows only this trait.

lexer

lexer — the lossless, layout-aware lexer, stage one of the CST front-end.

lower_cst

lower_cst — strict lowering from the lossless rowan tree to the semantic DraftAst, plus the range side-map that gives the message-only analyzer diagnostics real TextRanges.

opspec

The pure operation contracts: the typed OpSpec (which lowers to a flux_spec::ToolSpec), the OpSignature the analyzer and model-stage catalog reason over, and the abstract OpCatalog the analyzer validates against.

optimize

The optimizer: lower a validated HirFlow into a PhysicalPlan — a schedule over the flow’s top-level body. The scheduler (L-53) builds a whole-node symbol dependency graph: every statement is summarized by walking its entire subtree — nested blocks, when conditions, object/list templates, call arguments — into (reads, writes, class). Whole-node read-only statements (every reachable op registered with only Read effects, no approval/durability construct) are placed into dependency levels between fences; each multi-node level becomes a Stage::Parallel. An order floor keeps the emitted stage sequence in exact program order, so the replayed trace is identical to sequential execution while independent reads still overlap.

parse

parse — read canonical Flux-Lang text back into a DraftAst. The round-trip partner of crate::format: parse(&format(&ast)) == ast for every DraftAst (the supported subset natively, everything else via the @json escape; the flow header is the one documented exception — see crate::format’s “flow-header exception”). The accepting grammar is the lossless CST in crate::parser; this module is the strict public wrapper around structured CST lowering.

parser

parser — the tolerant, event-free recursive-descent parser that turns the crate::lexer token stream into a lossless rowan green tree (stage two of the CST front-end, L-58).

prelude

The artifact-type prelude — the curated standard library of typed structures an agent task manipulates (claims, evidence, needs, context packs, patches, …). These are not new Value variants: every artifact is an ordinary crate::ast::Value::Struct whose Named crate::ast::TypeRef names one of these schemas. The prelude ships with the language so ops can declare their inputs and outputs in these terms; an op’s Named("Claim") input lowers to a #/$defs/Claim $ref (opspec::type_ref_to_schema) that resolves against prelude_schema.

program

The multi-agent Program layer: a .flux file may declare a whole app — capability ceilings, agents, channels, datasources, triggers, and journeys — not just a single flow. These are pure-data declarations (L0, strings + an opaque settings JSON map); the L3 engine and the L6 flux-app host give them their runtime meaning (model/datasource/channel wiring, the event bus, the scheduler). This keeps the multi-agent vision coherent without expanding the language core: orchestration is an op-pack (ask/send/emit/spawn), so this layer needs zero new node kinds.

render

Pretty-rendering of a DraftAst as a human-readable execution-path tree — the pretty output of --plan / --compile-only, and the live plan view the engine surfaces before executing.

runtime

The reference interpreter: execute a compiled Flux-Lang flow against an injected execution host. execute_call dispatches one op (store the result as an immutable value, optionally bind a symbol, trace it); execute_flow walks a whole graph — bind / call / return plus when (typed branch) and repeat (bounded loop) — resolving each $symbol argument to the value the store owns (await cross-turn suspend/resume is the next slice).

schema

Schema generation — the single source of truth for the Flux-Lang AST surface.

sink

The observation sink the interpreter streams to as it executes — the language-level mirror of the engine’s AgentSink. Op results are reported as OpOutcomes (not the host’s tool result), keeping the trait free of any runtime type. The engine bridges this to its real sink.

skill

The Flux-Lang language skill: a self-contained reference for authoring durable Flux-Lang programs. It is generated — the node-kind table comes from crate::schema::node_kind_catalog (the Node doc-comments), so it can never drift from the types. Unlike the engine’s skill it carries no registered-ops table: operations are provided by the host runtime, not the language.

store

The value/symbol/event store the interpreter reads and writes through. The engine backs it with a durable SQLite store (flux_flow::state::FlowStore); the language ships an in-memory MemStore so the interpreter can run standalone (CLI, tests) without a database.

syntax

syntax — the SyntaxKind alphabet for the lossless CST front-end and its rowan::Language binding.