#MoonLab

MoonLab is an original Apache-2.0 MoonBit library for deterministic distributed-system simulation and fault injection. It lets protocol authors express Nodes as typed, pure transitions while MoonLab controls scheduling, Virtual Time, Messages, Timers, Stable Storage, finite Choice Points, crashes, restarts, and Network Partitions.

The same Scenario, compatible engine identity, and Decision Stream produce the same selected actions. A failing run can therefore be saved as separate Replay JSON, explanatory Trace JSONL, and summary Report JSON artifacts, replayed exactly, and locally shrunk while retaining its Failure Signature.

#What is included

sim: typed System Models, Scenario compilation, deterministic scheduling, fault plans, properties, budgets, and one bounded run.
explore: deterministic seed campaigns, exact Replay, stable Failure Signatures, and bounded decision shrinking.
artifact: schema-versioned Replay, Trace, and Report serialization with compatibility checks.
runner: statically typed Scenario registration and reusable command behavior.
cmd/moonlab: Native CLI with artifact-file orchestration.
examples: executable Raft-style election, replicated register, two-phase commit, and deliberately faulty election models.

#Quick start

Install the current MoonBit toolchain, then run:

moon update
moon check --target all --deny-warn
moon test --target wasm-gc --deny-warn
moon run cmd/moonlab --target native -- list
moon run cmd/moonlab --target native -- run raft-election 7 .scratch/raft
moon run cmd/moonlab --target native -- replay raft-election .scratch/raft.moonlab.replay.json

The run with an output prefix writes:

.scratch/raft.moonlab.replay.json
.scratch/raft.moonlab.trace.jsonl
.scratch/raft.moonlab.report.json

#Model interface

A model supplies three typed functions:

let model : @sim.SystemModel[State, Message, Config, Observation, Choice] = {
  boot: fn(node, config, reason) { ... },
  step: fn(node, state, event) { ... },
  observe: fn(snapshot) { ... },
}

boot and step return a new State and declarative Effects. Effects can send a Message, set or cancel a Timer, issue an asynchronous Stable Storage request, or expose a finite model Choice Point. Correctness checks consume only the immutable domain Observation returned by observe.

Every ScenarioSpec also requires a stable caller-maintained input_identity; change it whenever generic typed configuration or external model inputs change so incompatible Replay Artifacts are rejected.

See API guide, examples, architecture, artifact contract, security model, and the domain language in CONTEXT.md.

#Determinism and targets

The portable core does not read host time, randomness, files, sockets, processes, or threads. It builds for Wasm, Wasm-GC, JavaScript, and Native. Only cmd/moonlab performs Native filesystem I/O.

CI checks formatting and warnings, exercises portable and Native tests on Linux and Windows, and includes a deterministic 100,000-action boundary test. Default Resource Budgets cap actions, Virtual Time, pending work, retained Trace events, and Shrinker attempts.

#Boundaries

MoonLab v0.1 is bounded schedule exploration, not exhaustive model checking. It does not prove unbounded liveness, isolate untrusted model code, start production processes, implement a real network stack, or claim that the bundled teaching models are production Raft or transaction systems.

#Project and license

MoonLab is an original implementation, not a port. Conceptual prior art is acknowledged in THIRD_PARTY_NOTICES.md. Source code is licensed under the Apache License 2.0.

Development is tracked in GitHub Issues. See CONTRIBUTING.md for verification commands and contribution rules.

Site source Report issue Packages Build queue Skills Statistics