statekit 0.2.0

An immutable state-machine for validating predefined transitions.
Documentation
# Statekit Migration Guide

This document describes breaking and behaviorally significant changes between Statekit releases and provides guidance for migrating existing code.

The newest migration information appears first.

## 0.1 → 0.2

Version 0.2 strengthens Statekit's domain invariants and moves validation closer to the point where state names and transitions are created.

### `MachineBuilder::allow` is deprecated

`MachineBuilder::allow` has been deprecated in favor of `MachineBuilder::try_allow`.

Version 0.1:
```rust
let machine = Machine::builder()
    .allow("queued", "running")
    .allow("running", "completed")
    .build()?;
```

Version 0.2:
```rust
let machine = Machine::builder()
    .try_allow("queued", "running")?
    .try_allow("running", "completed")?
    .build()?;
```

`try_allow` validates the transition immediately and returns `Result<MachineBuilder, StateError>`.

The deprecated `allow` method remains available for compatibility but panics when given an invalid transition. New code should use `try_allow`.

> **Important:** Although `allow` remains available for source compatibility, its error behavior has changed. In 0.1, invalid transitions were generally rejected by `build()`. In 0.2, invalid input passed to `allow` causes an immediate panic. Code that handles invalid or externally supplied state names should migrate to `try_allow`.

### Validation now occurs when transitions are added

In 0.1, invalid transition definitions could be stored temporarily in `MachineBuilder` and were rejected by `build()`.

In 0.2, `try_allow` validates state names and transition-level invariants before storing the transition.

As a result, errors such as invalid state names and self-transitions are returned by `try_allow` rather than being deferred until `build`.

`build()` is responsible for machine-level validation, including requiring at least one transition.

### State-name validation is stricter

Version 0.2 introduces stronger state-name invariants. This is a behavioral compatibility change: state names accepted by 0.1 may be rejected by 0.2.

A state name:

- must contain at least one non-whitespace character;
- must not begin with Unicode whitespace;
- must not end with Unicode whitespace;
- remains case-sensitive;
- may contain whitespace internally;
- supports UTF-8.

For example:

```
"running"          valid
"In Progress"      valid
" running"         invalid
"running "         invalid
"   "              invalid
```

Applications that previously used state names containing leading or trailing whitespace must correct those values before upgrading.

Statekit rejects invalid names rather than silently trimming or normalizing them.

### `StateError::AmbiguousStateName` is added

State names containing leading or trailing whitespace now produce:

```
StateError::AmbiguousStateName
```

Consumers that exhaustively match `StateError` variants may need to handle this additional variant.

### Self-transitions fail earlier

Self-transitions remain invalid:

```
running -> running
```

When using `try_allow`, the error is now returned when the transition is added rather than when the machine is built:

```rust
let result = Machine::builder()
    .try_allow("running", "running");

assert_eq!(
    result,
    Err(StateError::SelfTransition {
        state: "running".to_owned(),
    })
);
```

Cycles between distinct states remain valid:

```
queued  -> running
running -> queued
```

### `Machine::targets` is deprecated in favor of `Machine::targets_from`

`Machine::targets` remains available in 0.2 for compatibility, but is deprecated. Existing code continues to compile with a deprecation warning.

New code should use `targets_from`.

Version 0.1:

```rust
machine.targets("running");
```

Version 0.2:

```rust
machine.targets_from("running");
```

`targets_from` returns the states directly reachable from the specified source state.

### Source states can be enumerated

Version 0.2 adds a source-state iterator:

```rust
for source in machine.sources() {
    if let Some(targets) = machine.targets_from(source) {
        for target in targets {
            println!("{source} -> {target}");
        }
    }
}
```

`sources()` returns states that have at least one outgoing transition. States that appear only as transition targets are not included. The iteration order is unspecified.

This complements `targets_from` and allows callers to inspect the transition graph without exposing Statekit's internal storage representation.

### Unique states can be enumerated

Version 0.2 adds an iterator over all unique states in the machine:

```rust
for state in machine.states() {
    println!("{state}");
}
```

`states()` returns every unique state that appears as either the source or target of a transition. Each state is returned once, and iteration order is unspecified.

Because a valid machine contains at least one transition and self-transitions are prohibited, a machine contains at least two unique states.

### Internal architectural changes

The following changes are important to Statekit's architecture but do not themselves form part of the public storage contract.

#### State names are represented internally by `StateName`

Machine definitions now store validated domain values rather than raw strings.

Conceptually:

```rust
HashMap<StateName, HashSet<StateName>>
```

This ensures that invalid state names cannot exist inside a successfully constructed builder or machine.

The internal storage representation is not part of Statekit's public API and may change in future releases.

#### Validation responsibilities are separated

Version 0.2 establishes clearer invariant boundaries:

- `StateName` guarantees a valid state name.
- `MachineBuilder::try_allow` guarantees a valid transition relationship.
- `MachineBuilder::build` guarantees that a machine contains at least one transition.
- `Machine` represents an immutable, valid machine definition.

This separation is intended to keep invalid domain states from propagating through the library.

### Migration summary

Most 0.1 consumers should migrate builder calls from:

```rust
.allow(from, to)
```

to:

```rust
.try_allow(from, to)?
```

and transition-target queries from:

```rust
.targets(from)
```

to:

```rust
.targets_from(from)
```

Applications should also verify that persisted or externally supplied state names do not contain leading or trailing whitespace.

Consumers that exhaustively match `StateError` should add handling for `StateError::AmbiguousStateName`.