Crate mlua_flow_ir 

flow.ir async runtime + mlua binding.

Layer 3 of the 4-layer flow.ir stack:

1. flow-ir-lua — Pure Lua DSL (separate repo, ecosystem-neutral)
2. flow-ir-core — Pure Rust schema + sync interpreter (no mlua, no async)
3. mlua-flow-ir — this crate: re-export of flow-ir-core + AsyncDispatcher + eval_async (including Fanout join-mode support) + Lua module() binding
4. mlua-swarm-engine — host concerns (Spawner / Worker / Loop / AuthzPolicy / cp_state persist)

All schema types (Node / Expr / JoinMode / EvalError / Dispatcher) are re-exported verbatim from flow-ir-core so callers can keep a single import path:

use mlua_flow_ir::{eval, eval_async, AsyncDispatcher, Dispatcher, EvalError, Expr, Node};

Sync/async divergence (Fanout join modes)

Sync (flow_ir_core::eval_with_storage_externs) and async (eval_async_with_storage_externs) share identical per-Node logic for Step / Seq / Branch / Loop / Try / Assign, and for JoinMode::All. Two Fanout modes are intentionally divergent: Race — sync evaluates only items[0]; async races every branch and the first branch to complete wins, so an early error can win over a later success. Any — sync short-circuits sequentially (later branches never dispatch once one succeeds); async launches every branch concurrently and cancels the losers at their next .await point, so in-flight side effects on losing branches may be truncated.

Feature flags

Default = lua54 + vendored (matches every existing consumer). The Lua module() binding and its mlua dependency live behind the implicit mlua feature (auto-enabled by any lua5x/luajit/luau feature). To pick another Lua version: default-features = false, features = ["luajit", "vendored"]. To link a system Lua instead of a vendored build, drop vendored. For an async-only build with no Lua binding at all (module() unavailable): default-features = false.

Structs

ExternMap

HashMap-backed Externs impl for host-side Rust closures.

MemoryCtx

Default CtxStorage impl — Arc<Mutex<Value>> wrapper。

NoExterns

Empty registry — every call_extern raises ExternError (parity with canonical “requires opts.externs” error). Used by the externs-less compat wrappers (eval / eval_expr / eval_with_storage).

Path

A parsed, validated context path — the canonical IR for the flow.ir $.a.b / RFC 9535-style bracket path syntax. The full syntax and rejection rules are documented on Path::read / Path::write and the FromStr implementation below.

PathParseError

Error returned by Path::from_str (and therefore surfaced through Path’s Deserialize impl, and through the read_path / write_path compat wrappers as EvalError::InvalidPath) on malformed path syntax.

Enums

EvalError

Evaluation error.

Expr

flow.ir Expr op.

JoinMode

Fanout join semantics (Promise / futures combinators).

Node

flow.ir Node kind.

Traits

AsyncDispatcher

Async dispatcher trait — async 版 Dispatcher。

CtxStorage

Ctx backend trait — eval(_with_storage) 系が ctx state を touch する 唯一の経路。 &self write (interior mutability) で 走行中の Flow と 外部 task が同じ ctx を共有 できる (= dispatch().await suspend 中に外部 task が ctx.write で State 注入 → resume 後 Step が read で観測、 という dynamic injection 経路を成立させる)。

Dispatcher

Dispatcher callback: resolves a Step.ref against the provided input, returns the step’s raw output value.

Externs

Extern registry: resolves a call_extern.ref against evaluated args and returns the value. Mirror of canonical opts.externs (flow-ir-lua interpreter.lua): each entry MUST be a pure function — no side effects, no flow control, value-shape manipulation only.

Functions

eval

Legacy Value-passing sync evaluator — backward compat wrapper around eval_with_storage + MemoryCtx. Value を所有権で受け取り、 内部で MemoryCtx::new(ctx) を使って storage 版に委譲、 終了後の snapshot を返す。

eval_async

Evaluate a Node against a context value asynchronously, using the given async dispatcher for Step resolution.

eval_async_externs

eval_async + externs registry for call_extern Expr resolution.

eval_async_with_storage

Storage-backed async evaluator — canonical entry.

eval_async_with_storage_externs

eval_async_with_storage + externs registry for call_extern Expr resolution. externs must be Sync so the recursive future stays Send (host executors spawn it across threads).

eval_expr

Evaluate an Expr against a context value, returning the resolved JSON value. Externs-less compat wrapper — call_extern raises ExternError.

eval_expr_with_externs

eval_expr + externs registry for call_extern Expr resolution.

eval_externs

eval + externs registry for call_extern Expr resolution.

eval_with_storage

Storage-backed sync evaluator — CtxStorage 経由で ctx を touch する正本。

eval_with_storage_externs

eval_with_storage + externs registry for call_extern Expr resolution.

is_truthy

JSON value の truthy 判定 (= flow.ir Branch cond / Loop cond で使う)。 Bool は値そのまま、 null/false 以外は truthy (Lua / JS と整合)。

module

Register the flow module table with Lua.

read_path

Parse path and read the value it resolves to inside ctx.

write_path

Write a value at the path location inside ctx, returning the updated ctx. out must be a Path Expr (its at field is an already-parsed Path, so no re-parsing happens here — this is a thin wrapper around Path::write, adapted to the Value-in/Value-out shape the rest of this crate’s legacy (non-CtxStorage) API uses).

Type Aliases

ExternFn

Boxed pure extern function stored in ExternMap.