moonseed 0.2.0

Deterministic, checkpointable Lua 5.4 runtime in safe Rust
Documentation

Moonseed

crates.io docs.rs CI License MSRV

Moonseed is a Lua 5.4 runtime in safe Rust for deterministic execution, resource limits and checkpoint/restore. The current package version is 0.2.0. The public interface is the Rust embedding API. The MSRV is Rust 1.88. Raising the MSRV is announced in the CHANGELOG.

Quick start

Add moonseed = "0.2" under [dependencies].

use moonseed::{compile, Config, FromLuaMulti, Journal, Runtime, StepOutcome};
let mut config = Config::default();
config.fuel_limit = Some(10_000);
let mut rt = Runtime::builder().config(config).build()?;
rt.load_main(&compile(b"return 6 * 7")?)?;
assert_eq!(rt.run(1_000, &mut Journal::new()).map_err(moonseed::Error::from)?, StepOutcome::Completed);
let values = rt.result_values()?;
assert_eq!(i64::from_lua_multi(values, &mut rt)?, 42);
# Ok::<(), Box<dyn std::error::Error>>(())

This finite chunk needs no libraries. For arbitrary programs, inspect all outcomes and resume fuel pauses with the same journal. A quantum bounds one slice; Config::fuel_limit bounds total execution. Start with the copyable recipes for complete embedding tasks.

When to use Moonseed

Use it when scripts need deterministic behavior, fuel and logical memory limits, checkpoint/restore of active execution, or capability-gated IO. The crate forbids unsafe code and runs on native targets and wasm32-unknown-unknown without a C toolchain.

Choose another runtime when you need the Lua C API, C modules, PUC Lua binary chunks, or compute speed comparable to PUC Lua or LuaJIT. Moonseed is an interpreter; the retained benchmark uses 2.5795× PUC Lua 5.4.9's executed host instructions. That is not an elapsed-time ratio; no LuaJIT ratio is published. See the retained method.

Status and compatibility

Moonseed implements the Lua 5.4 source language and its Lua-visible runtime semantics, with most of the standard library. It does not implement the Lua C API, PUC Lua binary chunks or C modules. The io and os libraries only reach the outside world through capabilities the host provides.

The pinned, unmodified Lua 5.4.9 suite compiles 33/33 files: 14 passed, 19 failed, zero unknown. Each failure has a classified reason. This is not a full-suite pass. See the suite ledger and compatibility details.

The same retained corpus uses 1.27× omniLua (21 workloads), 0.70× Luna's interpreter (21) and 0.56× Piccolo (16) host instructions. Piccolo lacks five required library workloads, so coverage differs. Counts include startup, compilation, setup, execution and teardown on divisor-100 sources; they exclude the empty startup probe and do not estimate full-size elapsed time.

Documentation

Embedding reference, runtime comparison, Rust API and compatibility policy.

License

MIT or Apache-2.0, at your option.