A hierarchical finite state machine (HSM) and workflow execution engine for MoonBit

statemachine

fsm

hsm

workflow

automata

moon add Lyl66655/moonbit-workflow-engine@0.1.4

Download zip

Author

Lyl66655

Version

0.1.4

License

Apache-2.0

Repository

github.com/Lyl66655/moonbit-statemachine

Last updated

5 hours ago

Downloads

README

#MoonBit StateMachine & Workflow Engine

An open-source MoonBit library for building hierarchical state machines, deterministic workflow pipelines, and event schedulers.

The project is organized around nine practical building blocks:

core/ for the base state transition engine
hsm/ for hierarchical state machines with event bubbling and LCA-based lifecycle handling
workflow/ for sequential pipelines with retry and failure handling
timer/ for deterministic timeout and interval simulation
export/ for Mermaid and PlantUML diagram export
diagnostics/ for configuration validation and actionable CI diagnostics
trace/ for bounded execution traces, checkpoints, filtering, and replay cursors
benchmarks/ for deterministic logical-workload evidence without wall-clock noise
examples/ for executable demos and reference usage

#What it does

Models complex stateful logic with explicit guards, actions, and lifecycle hooks
Supports parent-child state hierarchies and bubbling event dispatch
Adds a simple workflow runner for agent pipelines, task orchestration, and recoverable step execution
Provides deterministic timer behavior for testable timeout logic
Rejects invalid periodic intervals through a checked API and makes the legacy scheduler API fail-safe for malformed periods
Exports diagrams that can be embedded directly in docs and READMEs

#Repository Layout

Package	Path	Purpose
Core	core/	Transition engine, guards, and lifecycle hooks
HSM	hsm/	Hierarchical states, event bubbling, and LCA resolution
Workflow	workflow/	Sequential pipelines with retry policies
Timer	timer/	Deterministic scheduler and timeout simulation
Export	export/	Mermaid and PlantUML generator
Diagnostics	diagnostics/	FSM/HSM/Workflow configuration checks
Trace	trace/	Execution records and replay inspection
Benchmarks	benchmarks/	Reproducible workload and release evidence
Examples	examples/	Agent workflow and game state demos

#Quick Start

#Installation

To add this package to your project, run:

moon add Lyl66655/moonbit-workflow-engine@0.1.4

#Basic Usage

enum State { Locked; Unlocked } derive(Eq, Debug)
enum Event { Coin; Push } derive(Eq, Debug)
struct Context { mut coins : Int } derive(Eq, Debug)

let ctx = { coins: 0 }
let fsm = @core.Machine::new(State::Locked, ctx)

fsm.add_transition(
  State::Locked,
  Event::Coin,
  State::Unlocked,
  cond=fn(c, _e) { c.coins < 5 },
  action=fn(c, _e) { c.coins = c.coins + 1 },
)

fsm.add_transition(State::Unlocked, Event::Push, State::Locked)
let transitioned = fsm.send(Event::Coin)

#Running Examples

You can execute the provided demos directly from the command line:

moon run examples/ai_agent_workflow/main

Expected Output:

[Agent] Task initialized.
[Agent] Planning steps...
[Agent] Step 1 executed.
[Agent] Workflow completed successfully.

(Output may vary slightly based on the specific demo logic)

moon run examples/game_fsm/main

Expected Output:

[Game] Spawned boss at 100% health
[Game] Player attacking... boss health at 80%
[Game] Boss phase changed to Enraged

For more details, see:

#Quality Checks

To verify the repository locally, you can run the following standard MoonBit checks:

moon check
moon build
moon test

For stricter formatting, warnings, and public API checks:

moon fmt --check
moon info
moon check --deny-warn
moon test --deny-warn

To validate every supported compiler backend locally:

moon check --target all --deny-warn
moon build --target all
moon test --target all --deny-warn

The benchmark package reports logical operations, successes, failures, and Markdown release evidence without wall-clock assertions. Use @benchmarks.run_suite(100) and @benchmarks.summarize(results) in a MoonBit package to reproduce the release evidence.

For production configuration checks, use @diagnostics.validate_hsm to catch missing parents, parent cycles, inconsistent initial children, and initial-child cycles. For schedulers that accept user-provided intervals, prefer schedule_periodic_checked; it returns None and registers no timer when the interval is zero or negative. The legacy schedule_periodic method remains safe and treats such input as a one-shot event.

On the current local toolchain, the standard and all-backend checks pass. Repository CI runs the standard workflow on Ubuntu, Windows, and macOS with MoonBit 0.10.7+bc794d341.

#Competition Notes

This repository is prepared for the OSC 2026 MoonBit track:

Open-source license: Apache-2.0
Default branch: master
Remote mirrors: GitHub and GitLink
Development history: preserved in git commits

#Current Status

MoonBit source files: 37
MoonBit source lines: 3,261 (excluding generated .mbti files)
Test count and result: 47 passed, 0 failed in the local verification run

The repository includes production-oriented engines, diagnostics, deterministic benchmark scenarios, executable examples, and boundary tests. The OSC guide uses 4k–10k effective MoonBit lines as a project-scale reference; this checkout has crossed the requested 3,000-line milestone and should continue toward the larger project-scale range before final acceptance.

#License

Apache-2.0. See LICENSE.

Site source Report issue Packages Build queue Skills Statistics