Crate fsmp 

fsmp — FSM Prompter: prompt-driven workflows backed by extended finite state machines.

A definition (model::Definition) is a static workflow, authored ahead of the run — by a person, or by an agent working with one — and kept in version control: states carrying prose guidance, guarded transitions with effects, read-only params, and mutable context. The agent driving a machine never authors or mutates its own definition. An instance (model::Instance) is one live run — a snapshot of the definition taken at creation, plus the current state, the context, and a transition log.

The pieces:

• model — the data types for definitions and instances.
• engine — guard evaluation, effect application, and {var} interpolation, implemented as methods on model::Instance.
• render — turns an instance into the step text an agent acts on (prose or JSON).
• lint — checks a definition for authoring problems (unreachable states, dead ends, unknown targets) without instantiating it.
• store — definition parsing/validation and the on-disk instance layout under $FSMP_HOME (default ~/.fsmp).
• guide — the embedded authoring/driving reference docs.

The primary interface is the fsmp CLI (this crate’s binary), whose primary user is an AI coding agent driving one transition at a time. This library exposes the same engine for embedding in another transport or harness. The API is pre-1.0 and may change.

Modules

engine

Transition evaluation: guard checks, effect application, and value resolution/interpolation against an instance’s params + context.

guide

Embedded authoring/driving docs, served by fsmp guide [topic].

lint

Definition linter. Unlike store::validate (which hard-fails at the first structural error so a broken guardrail can’t be instantiated), the linter collects all authoring problems in a parseable definition at once and adds reachability analysis that new does not do. It operates on an already-parsed Definition and never touches disk, so lint is a pure, unit-testable function; the CLI feeds it store::parse_definition output.

model

Data model for machine definitions and running instances.

render

The prose renderer. This is the product: what the agent reads after every call. It states where the machine is, re-injects the current step’s instruction, lists only the currently-valid moves, and — crucially — names the tempting-but-blocked moves and why they’re blocked.

store

On-disk layout. Definitions come from wherever the caller points (version control, a skill dir); instance state lives under ~/.fsmp/state/<id>/.