Reference

Machine

Package Trax.StateMachine.Persistence·Namespace Trax.StateMachine.Persistence·Source Machine.cs, Fluent.cs, Invokes.cs, Timers.cs, MachineTrigger.cs

A machine is a subclass of Machine<TState, TTrigger> that declares itself in Configure. TState and TTrigger are the host's own enums. The builder compiles to the same total engine (SnapshotMachine<TState, TTrigger>) the conformance fixtures drive. Machine<TState, TTrigger> ships in Trax.StateMachine.Persistence; the builder interfaces ship in Trax.StateMachine.

Signature

namespace Trax.StateMachine.Persistence;
 
public abstract class Machine<TState, TTrigger> : IMachine
    where TState : struct, Enum
    where TTrigger : struct, Enum
{
    protected abstract void Configure(IMachineBuilder<TState, TTrigger> machine);
}

Members

IMachine is the machine-agnostic handle a host discovers and the registry keys on. Machine<TState, TTrigger> implements it.

Triggers, States and StartInputType have default implementations on IMachine that throw NotSupportedException; derive from Machine<TState, TTrigger> to get them.

IMachineBuilder

Build() throws InvalidOperationException for a custom rule or reduction whose name has no handler bound, so an unbound name fails when the machine is built rather than refusing its edge forever. It also throws for a machine that binds more than one effect with RunsOnce: a machine runs exactly one irreversible effect, and a second binding would otherwise be declared and never run. And it throws for a machine that enters its effect's target state by any transition other than the effect's own: that state means the effect ran, and a plain advance of the other edge would put a draft there without it. A self-loop on the target does not enter it and is allowed. It throws, too, for a machine that sends the effect's trigger on any other transition: the server supplies that trigger's input and the twin and generated clients treat it as effect-bound wherever it is sent, so it is sent on the effect's edge only. Handlers may be bound before or after the rules that name them. CustomGuard and CustomReducer are default interface methods that throw NotSupportedException on a custom IMachineBuilder implementation that does not override them.

IStateBuilder

IInvokeBuilder

Says where an invoked train's outcome, or a spawned child's end, goes. It is also the state's IStateBuilder, so the state's transitions follow it. Every target joins the machine's reserved states.

Build() throws InvalidOperationException, naming the state, when an invoking state lacks OnDone, OnFailed or OnCancelled, declares either of the last two twice, invokes or spawns a second thing, names the train by a class rather than its interface, or names a tuple as the output (its elements are fields, which no guard or reduction can read), or writes a spawned child's id into a field its declared context does not hold as a Guid?. It also throws when a state is declared with both Ends() and Fails(), or ends and also invokes or spawns, when an outcome goes to the target of the RunsOnce effect, or to the state the machine StartsAt (which would be reserved, so no draft could ever be created), or when an ordinary transition enters a state an outcome goes to (a self-loop is allowed). An invoked train does not count against the one RunsOnce effect.

ITransitionBuilder

IDifferentialBuilder

Authors a machine's differential fuzzing inputs, consumed only by the cross-language differential test: the harness enumerates the reachable space plus these inputs, records each outcome into a committed corpus, and every runtime replays it. Declared in C# so the machine is the single source; the IR carries them and the generated runtime machine strips them. The harness always fires a no-input case per trigger, so an explicit empty sample is a distinct case. Typed overloads serialize the record with camelCase names (nulls kept); raw JsonObject overloads give exact control.

Rules, start, reads and timers

These declarations describe how a machine is served to clients. Each event, the machine's start and its reads declare who may reach them, and the server checks every event and every start against its rule (see persistence ports). The draft service's Start validates the start input against its record and applies the reduction to the initial context, and a host refuses to start while the start of a machine a client can reach copies its input into a field an invoked train's outcome, the effect or an event gated by Requires or RequiresPolicy writes.

An event has one rule, whichever state it is sent from: Build refuses a machine whose edges of one event declare different rules (or one declares a rule and another none), and one where a gated event (one that names a role or a policy) enters the start state from another state, since anyone allowed to start an instance can put one there (unless the start state invokes a train, where the startup comparison below is the gate). AnyAuthenticated() and Anonymous() stand alone; combining either with another rule on one edge throws. Outcome and timer triggers are the server's own and offer no rule. At startup the host compares every event entering an invoking state, and the start into an invoking initial state, with the invoked train's [TraxAuthorize], and refuses one whose rule does not prove the train's: an event's role set must sit inside each of the train's role sets, and it must name each of the train's policies, since a policy cannot be proven to grant a role.

A state has at most one timer. Build refuses two timers on one state, a timer back into its own state, timers that form a cycle no event breaks, a timer into an effect's target or an invoked train's outcome target, a fixed duration that is not positive or is above MachineTimers.MaxDuration (366 days), bounds whose minimum is not positive or is above the maximum or whose maximum is above the cap, and a duration field the state's declared context does not have, does not type as TimeSpan?, or marks [TraxSensitive] (a deadline is exported and shown). A selector that is not a single field builds, but the IR export refuses the machine. A timer's target is not reserved, because a timer carries the context unchanged; the timed state itself is locked against the soft save, and the generic save refuses a machine with a timer. A host refuses to start a user-owned machine whose timer enters a state that invokes a train, since nobody is present to authorize the run.

Trigger input

A trigger's input is validated in the engine, so every path that fires a trigger checks it: the draft service, the generic advance, and a host's IMachineInstances.Advance, which is trusted for rules but never for input. The TypeScript twin validates against the same exported schema and gives the same verdict (ADR 0048).

• A declared record is checked as strictly as its CLR type. A missing non-nullable field, a field of another JSON type, a fraction in an integral field (2020.0 is an integer, 1.5 is not), a field the record does not declare (a PascalCase key is an unknown field, not an alias), and anything other than an object are refused. No input reads as {}. A nested record, and each element of a list of records, is checked the same way. Constraints such as [MinLength(1)] are checked against the input, never the context.
• Names follow System.Text.Json. A [JsonPropertyName] is the field's name, and a [JsonIgnore] member is not part of the input.
• A declarative trigger without WithInput takes no input: only none or {} is accepted. An effect-bound one takes the receipt its effect runner hands it. A trigger whose guard or reducer is a delegate reads the input in code nothing can describe, so its input is left to that code unless it declares WithInput.
• Some machines refuse to build. A record that contains itself has no finite schema, so WithInput<T>() throws naming it. One trigger has one input schema: Build() refuses a trigger whose edges declare different records, or a record on one edge and none on another. An invoked train's output type needs a schema too, since its output is checked against it before an OnDone guard reads it.
• Never an exception. A duplicate key, a number outside the range of a double (1e400), a string with a lone surrogate, or a deeply nested object is refused as INVALID_INPUT.

Exporting the IR

ExportIr() turns a built machine into its canonical IR, the same JSON the trax machine CLI writes to <machine>.ir.json; the CLI calls ExportIr(). It throws InvalidOperationException for a machine that made no declarative call, and for one that mixes the styles and still has a delegate guard (When(Func...)), delegate reducer (Reduce(Func...)) or Holds validator; the message names each edge (source state, trigger, target) and state.

string ir = new CheckoutMachine().ExportIr();

Behavior

Triggers and states

IMachine.Triggers lists a machine's triggers as MachineTrigger(Name, Kind, InputType) records, where Kind is a TriggerKind: Client, EffectBound, Outcome or Timer. Machine<TState, TTrigger> lists every member of its trigger enum (EffectBound when an edge on it binds the machine's effect, else Client, with the record its WithInput<T>() declares or null), then each invoking state's <State>.done, .failed and .cancelled as Outcome, the success outcome's input type being the train's output type, then each timed state's <State>.after as Timer, with no input. A typed API is built from this list, and offers no operation for an outcome or a timer, with two more: IMachine.States lists every member of the state enum as a MachineState(Name, ContextType), where ContextType is the record the state's Context<TContext>() declares (null for Context() or none), and IMachine.StartInputType is the record Start<TStartInput> declares, or null when the machine declares no start. The machines root types each exposed machine's state, context and operations from the three.

The engine (SnapshotMachine) fires a timer trigger through an entry point of its own, which only the server's reconciler calls, kept apart from Advance, which refuses one as TIMER_BOUND. It fires only the timer of the state the snapshot is in (any other is NO_TRANSITION) and carries the context to the timer's target. The IR exports timers in a timers block of their own (state, trigger, target, after or field with min and max as ISO-8601 durations, and the union of the rules of everything that enters the state), never in inputs or triggers; a machine without timers exports no block.

Delegate vs declarative

Holds, When(Func...) and Reduce(Func...) take delegates; Context<T>, When(Rule), Reduce(Reduction) and WithInput<T> take data and also record the DeclarativeModel the IR is exported from. Both compile to the same engine delegates. See Delegates and declarative rules.

Results

Every advance and rehydrate returns a typed result, never an exception: see Result codes.

Example

The turnstile from the State Machine sample:

From Trax.Samples/samples/StateMachine/Trax.Samples.StateMachine/Machines.cs

[TraxMachine]
public sealed class TurnstileMachine : Machine<TurnstileState, TurnstileTrigger>
{
    protected override void Configure(IMachineBuilder<TurnstileState, TurnstileTrigger> m)
    {
        m.Id("turnstile")
            .Version(1)
            .StartsAt(TurnstileState.Locked, () => new JsonObject())
            .Start<EmptyStart>(s => s.Reduce(Keep()).AnyAuthenticated())
            .Get(r => r.OwnerOnly())
            .Watch(r => r.OwnerOnly())
            .Discard(r => r.OwnerOnly());
 
        m.In(TurnstileState.Locked)
            .Context()
            .On(TurnstileTrigger.Coin)
            .AnyAuthenticated()
            .WithInput<CoinInput>()
            .When(Input((CoinInput i) => i.Coin).IsOneOf("quarter", "dollar"))
            .Because("Only a quarter or a dollar is accepted.")
            .Reduce(Set((UnlockedContext u) => u.PaidWith).FromInput((CoinInput i) => i.Coin))
            .To(TurnstileState.Unlocked);
 
        m.In(TurnstileState.Unlocked)
            .Context<UnlockedContext>()
            .On(TurnstileTrigger.Push)
            .AnyAuthenticated()
            .Reduce(Clear())
            .To(TurnstileState.Locked);
    }
}

See also

• Authoring a machine and Declarative authoring.
• Delegates and declarative rules.
• Rules vocabulary and the declarative data model.
• Invoking a train.
• AddStateMachines.