Transition-boundary conventions for ordinary Rust state machines.
Statelet is being designed for teams that already write explicit Rust state
machines with enums, structs, methods, and match expressions. It does not run
the machine, own the dispatch loop, or ask the code to become a graph DSL. Its
job is narrower: make transition boundaries easier to name, observe, and review.
This repository is currently in the design and bootstrap phase. The first
validation slice is deliberately non-macro: prove that runtime conventions,
stable state names, and documented tracing fields help real mdtablefix code
before publishing a procedural macro.
- Ordinary Rust stays ordinary: branch logic, state mutation, errors, and side effects remain in project code.
- The framework boundary is explicit: use
statig,smlang,typed-fsm,rust-fsm, orstatelesswhen you want a machine definition or transition table. Use Statelet only if the machine already exists. - Observability is the product pressure: the first useful surface is a shared state-name and tracing-field convention, not a runtime engine.
- The macro must earn its place:
#[statelet::transition]is deferred until it beats#[tracing::instrument]plus local helpers on real code.
Clone the repository and run the generated project gates:
git clone https://github.com/leynos/statelet.git
cd statelet
make allThe current crate skeleton is intentionally small. The useful "hello world" is to validate the repository and read the design gates before adding API:
make all
sed -n '1,120p' docs/roadmap.mdFor the proposed user-facing workflow, start with the design and roadmap rather than a speculative code sample:
Current repository state:
- Rust 2024 crate skeleton with strict lint, formatting, and documentation gates.
- Terms of reference defining the market gap, non-goals, and validation test.
- Technical design sequencing a runtime conventions crate before any macro crate.
- Roadmap with explicit dependencies, kill gates, and validation signposts.
Planned core, pending validation:
StateNameconventions for cheap, stable state names.- Semver-relevant tracing field names for transition observability.
- A conventions-only
mdtablefixspike that can stop the project if the value is too weak. - A procedural macro only if real examples prove that the boilerplate is worth hiding behind an attribute.
- Users' Guide - generated project commands and local usage notes.
- Developers' Guide - contributor workflow and tooling.
- Documentation contents - the full documentation index.
- Terms of reference - problem space, users, and validation criteria.
- Technical design - crate boundaries, public API decisions, and validation gates.
- Roadmap - delivery phases, dependencies, and exit criteria.
ISC - see LICENSE for details.
Contributions are welcome. Please read AGENTS.md and the Developers' Guide before changing the repository, then keep changes small, gated, and committed with the relevant validation output.